almogbaku/aos/evolve

capability-evolve

Not in context yet? Load the capability-lifecycle skill first — the map, the contract, the overlay doctrine, and the Experience rules. This is the overlay's write side — the single front door for every "change this capability" ask; the classify step routes what isn't yours. Default fate of every change: the user's MOD, silently. MOD states current desired state, so every write is an edit in place, never an appended record (the capability-lifecycle skill's reference/overlay.md).

1. Identify the capability and artifacts (aos-cap show <id>); restate the

desired change in one line.

1. Read the current MOD.md first, then classify (if the change adds or moves a

skill's files, capability-lifecycle's reference/naming.md binds the names and where references may point — a reference to another skill or agent is written as a slot, \{{skill: <id>}}, never as a computed name):

• an ONBOARDING question covers it → update that typed answer in the frontmatter;
• a prose statement already covers the subject → rewrite that statement (never add a

second one that contradicts it — "office hours: none" replaces "office hours Thursday 17:00–18:00", it does not follow it);

• the change restores the shipped default → delete the entry; MOD only states

differences;

• nothing covers the subject yet → add one imperative statement;
• actually an upstream bug or explicitly for everyone → the {{skill: contribute}}

skill owns it: it changes the shipped source (building mode, approval-gated). Say so and hand over — nothing lands in MOD.

1. Write the MOD.md change first (the capability-lifecycle skill's

reference/overlay.md, Capture and fold — the MOD statement lands before anything depends on it), then apply to the pinned render in personal/capabilities/<id>/ (and any native artifacts per the cheat-sheet — the capability-lifecycle skill's reference/harness-<harness-runtime>.md, load it now; native edit verbs where they exist), through the STAGE→GATE→EXECUTE phases.

1. aos-cap rehash <id> — refresh the recorded hashes in place so verify

stays clean; the persist hook commits personal/ (dated message). From now on {{skill: upgrade}} re-applies this change on every upgrade. (New artifacts, jobs, or keys → a full aos-cap record with the complete set from aos-cap show.)

1. Confirm: "recorded in your MOD.md — survives every upgrade."
2. Promotion check — signal-gated, never reflexive (the judgment, tests,

threshold ladder, and etiquette live in the capability-lifecycle skill's reference/overlay.md, Promote and retire). An offer fires only on: objectively-broken workaround · forced mechanism override (the change fought the template beyond its {{mod}} slots) · the user asked. At most one one-liner offer, at the conversation's end, once per statement ever; a "no" is recorded and never re-asked. Yes → hand to {{skill: contribute}} with the statement. Never open a PR or file an issue yourself — every upstream write needs the user's explicit yes (contract).

Capture mode (drift found by verify or by noticing a hand-edit): same steps, but step 3's second half is skipped — the render already carries the change, so there is nothing to apply. Step 3's MOD.md write still happens, and it is the whole point of capture mode: the edit exists on disk and nowhere in the overlay, so the next upgrade would silently drop it. Skip the write and step 5's "recorded in your MOD.md — survives every upgrade" is a lie (the capability-lifecycle skill's reference/overlay.md, "Capture and fold").