almogbaku/aos/capability-lifecycle

capability-lifecycle — the map

Capabilities are self-describing prompts; you are the installer. Judgment is yours; bookkeeping is aos-cap's (aos-cap --help — the lockfile is its file, never edit the YAML). Everything lives in the household <aos_home> — the aos home: --home/AOS_HOME, else ~/aos (not your home directory): upstream/ the pristine kit clone, personal/ the user's private repo (their MOD files, the pinned renders harnesses symlink to, their private capabilities), .aos/ machine state (the lockfile; harness.yml, the household's harness — aos-cap harness show). The diff gate is never optional. MOD.md states the user's personalization — what they changed from the shipped defaults, current state, edited in place: you re-apply it, you never overwrite it — and you never write anything to upstream (PR, issue, +1, push, fork, remote branch) without the user's explicit approval. The full rules: reference/contract.md. The overlay doctrine (interviews, transform, capture, promote/retire, persist): reference/overlay.md. Naming, installed skill names, and the uniqueness gate: reference/naming.md — read it before authoring or installing anything that ships a skill. Names are computed, never authored: write \{{skill: <id>}} and \{{agent: <id>}} in prose and aos-cap render substitutes the installed name. A backslash-escaped slot stays literal, which is how this sentence survives its own render.

Manifest quick facts: CAPABILITY.md frontmatter is strict-typed (aos-cap manifest <dir> parses and validates it — its errors name the field and rule); the fields are id · version · tags · summary · depends · cron · skills · skill_prefix · kb · uses (a cron entry: id · expr · agent · prompt_ref · exec · degraded), x-* reserved for extensions; the prose below the frontmatter is the installer's briefing, never runtime context. A skill's id is capability-local — the name it installs under is aos-cap skills <dir>'s answer, and it is single-owner across the whole harness; an agent's works the same way, from the same prefix, via aos-cap agents <dir> (reference/naming.md).

Experience

Every lifecycle interaction is warm + expert: concept before mechanics, explain-then-act. Before doing anything visible, say what is about to happen and what it buys the user — then proceed; the diff gate is the safety net, not repeated consent prompts. Batch questions; if you can infer it, don't ask. Set expectations before slow steps ("installing the tool takes a minute"). Show the gate as a payoff: each artifact → what it does for you. Close with a specific, celebratory summary — what was installed, where, which cron jobs, any degraded modes — never a vague "done." User-facing lines are warm prose; your internal steps stay silent.