Aether

Aether is Ego Hygiene’s canonical first-party library of reusable AI specifications, skills, and agent source with deterministic validation and build tooling.

1) Lifecycle and status

• Repository status: active, with canonical source in library/organization/.
• Publishing/install surfaces (gh skill, release tags) are preview-dependent and may change CLI behavior.
• Artifact lifecycle policy: draft -> stable -> deprecated -> retired (see ARCHITECTURE.md).
• Catalog records may also include experimental state where explicitly defined by catalog contracts.
• Only stable artifacts are releasable per catalog policy.

2) What Aether owns (and does not own)

Aether owns:

• First-party canonical specs, skills, and agents.
• Catalog/provenance schemas and deterministic validators.
• Distribution/projection build scripts.

Aether does not own:

• Org-wide deployment automation, CI baseline, templates, environment provisioning, shell command runtime tooling, lint implementation, release orchestration, or conformance enforcement in consumer repos.

See PURPOSE.md#4-what-aether-is-not.

3) Architecture: canonical vs generated

Canonical source:

• library/organization/specs/
• library/organization/skills/
• library/organization/agents/

Generated artifacts:

• catalog/first-party/catalog.v1.json
• dist/skills/
• dist/github/

.staging/ is non-canonical migration/provenance holding space and cannot be emptied without ADR-005 deletion-gate requirements (DECISIONS.md#adr-005).

4) First-party catalog summary

Current canonical inventory snapshot (recompute with the commands shown):

• 23 specifications (find library/organization/specs -name "*.spec.md")
• 29 skills (find library/organization/skills -name "SKILL.md")
• 9 canonical agent profiles (find library/organization/agents -name "AGENT.md")

Machine-readable catalog and provenance:

• catalog/first-party/catalog.v1.json
• catalog/external/approved-skills.v1.json

5) Prerequisites

• Python 3.12+
• Git
• GitHub CLI (gh) 2.96+ for skill publish/install flows

Install dev dependencies:

pip install -r requirements-dev.lock

6) Quickstart

From repository root:

./aether distribution build --output-directory "dist"
./aether validate --format "text"
./aether catalog generate --check
./aether test

7) Validation and tests

Primary validator:

./aether distribution build --output-directory "dist"
./aether validate --format "text"
./aether validate --format "json"

Targeted validation scopes:

./aether validate --skills --format "text"
./aether validate --specifications --format "text"
./aether validate --catalog --format "text"
./aether validate --distribution --format "text"
./aether validate --provenance --format "text"
./aether validate --staging --format "text"
./aether validate --links --format "text"
./aether validate --evals --format "text"

Catalog check:

python3 catalog/validate_catalog.py

Test suite:

./aether test

8) Build and inspect distributions

Build deterministic first-party skill distributions:

./aether distribution build --output-directory "dist"
./aether distribution build --output-directory "dist" --check

Underlying generators remain available when a narrower check is needed:

python3 library/organization/skills/build-distributions.py
python3 library/organization/skills/build-distributions.py --check
python3 library/organization/agents/build-projections.py
python3 library/organization/agents/build-projections.py --check

Inspect generated output:

find dist/skills -maxdepth 2 -type f | sort
find dist/github -maxdepth 4 -type f | sort

Validate publishability (no release write):

gh skill publish "dist" --dry-run

9) Install locally with GitHub CLI

Install from local build output:

gh skill install "./dist" "create-purpose-document" --from-local

Install from repository default ref:

gh skill install "egohygiene/aether" "create-purpose-document"

10) Install a pinned release with GitHub CLI

Pin by release tag (or commit SHA):

gh skill install "egohygiene/aether" \
  "create-purpose-document" \
  --pin "v1.0.0"

11) Update and remove installed skills

Update skills:

gh skill update --dry-run
gh skill update --all
gh skill update --unpin

Inspect installed paths (for manual removal when needed):

gh skill list --json skillName,path,scope,pinned

At present, GitHub CLI exposes update but no dedicated remove subcommand; remove by deleting the listed installed skill directory at the reported path.

12) Release and version model

• Repository release tags pin installable snapshots.
• Artifact versions are per-record metadata in the first-party catalog.
• Breaking changes require major version increments in artifact metadata and release documentation.
• Only stable artifacts are eligible for release manifests.
• Release publication is explicit through .github/workflows/release-first-party-skills.yml; PR validation stays read-only in .github/workflows/pr-validation.yml.

See CHANGELOG.md and docs/release-and-pinning-guide.md.

13) External-skill provenance policy

External skill records must be reconstructable from staged provenance evidence and validated against schema:

• catalog/external/approved-skills.v1.json
• catalog/schemas/aether.external-source-record.v1.schema.json
• .staging/manifests/skills-lock.json

Policy and review workflow: docs/external-source-review-guide.md.

14) Security, privacy, and executable-resource warning

• Treat all generated or imported agent/skill artifacts as executable instruction surfaces.
• Review tools, links, scripts, and external references before promotion or installation.
• Never commit credentials/secrets in frontmatter, templates, eval fixtures, or hooks.

See SECURITY.md and docs/agent-and-hook-safety-guide.md.

15) Contribution workflow

1. Edit canonical source only (library/organization/, catalog/ schemas/contracts).
2. Run deterministic validation/build checks.
3. Regenerate derived artifacts when required.
4. Submit focused PRs with clear scope and evidence.

Detailed process: CONTRIBUTING.md.

16) Ecosystem boundaries

Aether interfaces with neighboring repos/systems but does not replace them:

• egohygiene/.github: org agent deployment surfaces
• Empathy: repository baselines
• Holon: repository templates
• Realm: dev environment provisioning
• Mantle: shell command runtime
• Egolint: lint implementation
• Relay: GitHub Actions/workflow automation
• PACE: conformance enforcement
• Consumer repositories: local policy/overrides and runtime adoption

Consumer-local instructions override Aether defaults in consumer context.

17) License and support

• License: LICENSE
• Support: SUPPORT.md