@tenkara/afm-linux-arm64 0.0.0-stage → 4.0.0-alpha.6

package/plugin/claude-code/skills/diagnose/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: diagnose
+description: |
+  Scans the health of the local docs on 7 axes. The axes are dead reference, stale marker, instance-to-plugin drift, broken ADR chain, dead rule trigger, inflation or orphan, and cross-doc contradiction. It reads only `<consumer>/docs/` and returns evidence as `command + file:line`. It proposes no edit.
+  Activates: `/afm:diagnose`, "diagnose the methodology", "what is broken in the docs?", "run the AFM health check".
+---
+
+
+# AFM — Diagnose (mechanical weakness-mining, read-only)
+
+This is a mechanism skill of AFM. The canonical procedure is the op file that `afm path ops/diagnose.md` prints.
+
+> **Carve-out (does not overlap existing ops):** `analyze` audits **one feature**. `diagnose` audits the **whole instance** of `/docs/`. `reflect` uses **behavioral** evidence, where the agent stumbled. `diagnose` is **static**, based on filesystem and git. `evolve` is the **orchestrator**. It combines `diagnose` (mechanical evidence) with `reflect` (behavioral evidence) into one proposal and one gate. `diagnose` is **read-only**. It never proposes an edit or opens a gate.
+
+## When NOT to activate
+
+This section disambiguates for a skill that already activated. It does not define activation, so it stays in the body, not in the resident listing.
+
+Validation of ONE feature is `/afm:analyze`. Behavioral friction, where a doc misguided the agent at apply time, is `/afm:reflect`. Proposing or applying a fix is `/afm:evolve` (the full cycle, which includes diagnose).
+
+## Pre-check
+
+1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop. Suggest `/afm:init` (greenfield) or `/afm:refactor` (brownfield) first.
+2. **Does `afm preflight` exit 0?** A non-zero exit says why (docs not bootstrapped, content unresolved, pin mismatch). Report it to the user. Do not fall back silently.
+
+## Procedure
+
+Read the op (`afm path ops/diagnose.md`) end to end. Follow it literally.
+
+The procedure has two phases. **Phase 0 — Scan** is gap-driven. Run `afm doctor --json`: it checks A1-A6, staleness and dead gotchas mechanically, and every finding carries a command plus `file:line`. You add A7 yourself. All 7 axes are checked, every time.
+
+Axis A7, cross-doc contradiction, uses a paired read. That read applies an anti-false-positive layer test. An axis that cannot be covered becomes "not-covered: <reason>".
+
+**Phase 1 — Diagnosis** has the ANALYZER role. **It must not propose an edit.** The signature is φ = `(symptom, causal-status-of-behavior, mechanism)`.
+
+Phase 1 requires rival mechanisms, for example "agent non-compliant" versus "target legitimately removed". It applies an addressability filter and a self-sufficient severity matrix.
+
+**Output** is an evidence bundle ordered by severity. Run à la carte, the skill prints the report to chat. It does not write to disk. It opens no gate. Under `evolve`, it feeds the proposal instead.
+
+This scan has no cooldown. It is read-only and cheap. The cycle's cooldown belongs to the orchestrator.
+
+## Invariant principles
+
+Single canonical source: `PRINCIPLES.md` (`afm path PRINCIPLES.md`). Universals §1-8 apply. Especially relevant: #2 (discover-first — diagnose with evidence before any proposal). Also #3 (mechanize-or-demote — the checks must pass the test they audit). Also #5 (no finding without evidence external to the text).
+
+**No new principle here.** `diagnose` is a composed materialization. The doctrine lives in the op file.
+
+## Version
+
+Content version: `afm version` prints it.

package/plugin/claude-code/skills/evolve/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: evolve
+description: |
+  Runs the full self-evolution cycle over `<consumer>/docs/`. It combines diagnose and reflect, adds generalize, restructure, update and remediate on demand, and delivers one package through one gate (`afm ask evolve`). It conducts the mechanisms and never touches the plugin.
+  Activates: `/afm:evolve`, "audit the methodology", "the docs are a mess", "the rules no longer trigger", "clean up the docs", "reorganize the docs".
+---
+
+
+# AFM — Evolve (orchestrator for the self-evolution cycle)
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
+
+This is an orchestrator skill of AFM. The canonical procedure is the op file that `afm path ops/evolve.md` prints.
+
+> **Conductor, not executor** (same pattern as `deliver`). `evolve` owns 3 things that no mechanism owns alone: (1) the evidence-collection driver for the whole instance (combines `diagnose` + `reflect`), (2) the split into buckets plus the single gate, (3) the apply driver, post-conditions, and the log/lineage record. It reads and follows everything else from the mechanisms, through a suppression contract.
+>
+> **Carve-outs (it does not override existing ops):** `diagnose`/`reflect`/`generalize`/`restructure` are the **mechanisms** (each runs à la carte). `analyze` audits **one feature** (read-only). `reconcile` proposes **one single edit** at the end of a turn. `promote` **records** a finding meant for the plugin (it does not edit the plugin). `evolve` is the **cycle** that chains the mechanisms with one gate and one log — the level no other op covers.
+
+## When NOT to activate
+
+This section helps someone who already activated the skill decide if it fits. It is not an activation trigger, so it stays in the body, not in the resident listing.
+
+Use a single mechanism instead when the need is narrow. A report is `/afm:diagnose`. Refining a doc that misled you is `/afm:reflect`. Merging gotchas is `/afm:generalize`.
+
+A structure or staleness check is `/afm:restructure`. A version bump is `/afm:update`. `reconcile` proposes a one-off additive signal (new gotcha, rule, or ADR) directly.
+
+A feature-level check is `/afm:analyze` or `/afm:deliver`. Recording a finding for the plugin is `/afm:promote`.
+
+## Pre-check
+
+1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop. Suggest `/afm:init` (greenfield) or `/afm:refactor` (brownfield) first.
+2. **Does `afm preflight` exit 0?** A non-zero exit says why (docs not bootstrapped, content unresolved, pin mismatch). Report it to the user. Do not fall back silently.
+3. **Does `afm evolve gate-check` allow a cycle?** Pass `--symptom "<what the user said>"` when there is one. Exit 0 runs; exit 1 is the cooldown refusing (no new signal inside the window), so say so and stop; 3 and 4 mean not a project or undecided.
+
+## Procedure
+
+Read the op (`afm path ops/evolve.md`) end to end and follow it exactly. The op has 5 phases.
+
+**Phase 1 — Evidence collection.** Combine two sources through the suppression contract. `diagnose` is the mechanical scan of the 7 axes (`afm doctor --json` plus the A7 reading), read-only. `reflect` is behavioral evidence of docs that misled the agent. Run `generalize`/`restructure` on demand, when their own trigger signal fires. An empty diagnosis counts as a valid result.
+
+**Phase 2 — Proposal.** This phase plays the IMPROVER role. Apply the op's **shared proposal discipline**: retrieval before create, then a dry run before the gate. Split the proposals into 3 buckets.
+
+A non-restorable change always goes through the gate. It never invents its own target. Decide here whether to downgrade, archive, or merge an artifact. Cap bucket (b) at 8 items per cycle (`afm evolve gate-check --critical <n> --high <n> --medium <n> --low <n>` computes what to ask and what to stage). Recurring failures come from `afm failures promotable`.
+
+**Phase 3 — Single gate.** Ask item by item with `afm ask evolve --scope <item-slug>`, at most 4 questions per call. This gate is never skippable — there is no "go" shortcut.
+
+**Phase 4 — Apply and post-conditions.** Re-run `afm doctor --json`, `afm index --check` and `afm detect --for <file>` over the touched docs, and confirm the content root is clean (`git status`, or a timestamp check with no git).
+
+**Phase 5 — Log.** Record the cycle in `docs/evolution/NNN-<date>.md`. Suggest `promote` when a finding generalizes beyond this instance.
+
+Consult the rubric `rubrics/when-to-evolve-methodology.md` (`afm path rubrics/when-to-evolve-methodology.md`) to decide between a full cycle, a single mechanism, or a one-off fix.
+
+## Invariant principles
+
+The single canonical source is `PRINCIPLES.md` (`afm path PRINCIPLES.md`). Universals §1-8 apply. #2 (discover-first) applies: diagnose with evidence before you propose. #3 (mechanize-or-downgrade) applies too: evolve's own signals must pass the same test evolve applies to others.
+
+#8 (earned questions, recommendation-first) also applies to this skill.
+
+#6 (autonomy-first with self-check) follows the pattern *produce → self-check → report*. The gate is the load-bearing residue. Bright lines for #7 plugin, deletion, and push still apply.
+
+**No new principle here** — evolve is a composed materialization. The doctrine lives in the op and the rubric.
+
+## Continuous doctrine
+
+The `reconcile` skill owns passive mode, and it is always on. Reconcile may **suggest** `/afm:evolve` when it detects a Class B signal. That signal is a lived contradiction between docs, or perceived inflation at apply time. Only the user can invoke the full cycle.
+
+## Version
+
+Content version: `afm version` prints it.

package/plugin/claude-code/skills/export-template/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: export-template
+description: |
+  Converts a bootstrapped project into an architectural template. It deletes the product files, keeps ach, afm, gotchas and adr, and writes the `docs/.template` marker. It touches `docs/` only.
+  Activates: `/afm:export-template`, "export as template", "turn this project into a starter".
+---
+
+# AFM — Export-template
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
+
+Atomic skill of `afm`. The canonical procedure is the op `afm path ops/export-template`. The CLI owns the plan,
+the diff and the marker. This skill keeps the judgment.
+
+## When NOT to activate
+
+This is a criterion for a skill already active, not an activation trigger. If the project is already a
+template (`docs/.template` exists), the op is idempotent but asks first.
+
+## Pre-check
+
+`afm template export --dry-run` does it: a project with no `docs/.afm-version` is not bootstrapped yet, so
+stop and suggest `/afm:init` (greenfield) or `/afm:refactor` (brownfield) first.
+
+## Procedure (judgment only)
+
+1. Collect the template name and version as free text. A blank answer stays `[TBD]`; never derive the name
+   from the folder.
+2. Ask what to keep: `afm ask export-template`. Put every coherence warning of the dry run to the operator.
+3. Induce the reusable task template from the latest all-green feature BEFORE `docs/features/` goes.
+4. Show the full diff with `afm template export --dry-run ...`, then ask `afm ask export-template-apply`.
+   Deleting files is a bright line: it is never applied without that confirmation.
+5. Apply with the same flags and `--yes`, and suggest the commit message the command prints.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply.
+
+Especially #5 (do not invent metadata when the operator leaves it blank: use `[TBD]` in the JSON). Also #6
+(autonomy-first, but deleting files is a bright line): confirm the diff before you delete.
+
+Passive mode (`/afm:reconcile`) is always on. This skill focuses only on the active conversion to a template.

package/plugin/claude-code/skills/generalize/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: generalize
+description: |
+  Merges two or more similar gotchas into one abstract rule, from episodic to semantic. Merged entries become tombstones and nothing is deleted.
+  Activates: `/afm:generalize`, "these gotchas are all the same thing", "merge these rules", "I have 3 gotchas that say the same thing".
+---
+
+
+# AFM — Generalize (semantic consolidation of gotchas)
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
+
+Mechanism skill of AFM. The canonical procedure is the op file that `afm path ops/generalize.md` prints.
+
+> **Carve-out (does not overlap existing ops):** `promote` **registers** a finding meant for the plugin. It does not write to the plugin. `generalize` merges **inside the instance** (N gotchas become 1 rule in the same `/docs/`). `reconcile` **adds** a new gotcha. `generalize` **merges** gotchas that already exist. `reflect` refines **one** doc. `generalize` consolidates **many**. `evolve` is the **orchestrator** and it composes this skill when `diagnose` flags inflation from redundant gotchas.
+
+## When NOT to activate
+
+This is a disambiguation criterion for someone who already activated the skill, not an activation trigger. That is why it lives in the body, not in the resident listing.
+
+Sending ONE learning to the plugin is `/afm:promote`. ADDING a new gotcha or rule is `reconcile` -> `/afm:gotcha`/`/afm:rule` (`generalize` only merges what already exists). Refining the clarity of ONE doc is `/afm:reflect`. With fewer than 2 similar candidates, there is no generalization to do.
+
+## Pre-check
+
+1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop and suggest `/afm:init` (greenfield) or `/afm:refactor` (brownfield) first.
+2. **Does `afm preflight` exit 0?** A non-zero exit says why (docs not bootstrapped, content unresolved, pin mismatch). Report it to the user. Do not fall back silently.
+3. **Is there a batch of >=2** similar gotchas/reflections? If not, report "nothing to generalize (no batch)" and stop. Generalizing from 1 case is forbidden (#5).
+
+## Procedure
+
+Read the op (`afm path ops/generalize.md`) end to end. Follow it literally.
+
+**1. Identify the batch:** cluster by shared abstract cause, >=2 cases. Ask "would one more general instruction have prevented all N?" A larger batch yields a more abstract rule.
+
+**2. MetaReflect:** draft the generalized, non-case-specific rule. The original cases become examples. Follow the **shared proposal discipline** from `evolve.md` (`afm path ops/evolve.md`) instead of duplicating it. Reduce, do not create a parallel path.
+
+**3. ShowsImprovement + backtracking:** check if the rule covers all N cases. A hard rule needs an executable 0/1 trigger. Otherwise it becomes a § 1.3 principle. If it cannot cover all cases without turning vague, back out and keep the cases separate.
+
+-> **4. Own gate** (item (b), unavoidable and earned, through `afm ask generalize`; suppressed under `evolve`. On approval: write the rule via `rule.md` (`afm rule new <slug>`) and **archive the merged entries as tombstones**. Never delete) -> **5. Record** the result in `docs/evolution/NNN-<date>.md`. Suggest `promote` if the finding matters beyond this instance.
+
+## Invariant principles
+
+Single canonical source: `PRINCIPLES.md` (`afm path PRINCIPLES.md`). Universals §1-8 apply here, especially #1 (episodic `gotchas.md` -> semantic `afm.md`). Also #3: a merged rule becomes hard only with an executable 0/1 trigger, the ShowsImprovement step of MetaReflection. Also #5: do not invent an abstraction without a real batch.
+
+Also #6/#8: self-verify before an earned gate. Deletion is a bright line. Use tombstones instead. **No new principle here** — `generalize` is a composed materialization. The doctrine lives in the op file.
+
+## Version
+
+Content version: `afm version` prints it.

package/plugin/claude-code/skills/gotcha/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: gotcha
+description: |
+  Writes a counterintuitive surprise to `<consumer>/docs/gotchas/`. The entry gate is mandatory: the issue must have bitten twice, or it must be documented behavior of an external SDK or runtime.
+  Activates: `/afm:gotcha`, "register a gotcha", "this has confused me before", "note this surprise for the next person".
+---
+
+# AFM — Gotcha
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
+
+Atomic skill of `afm`. The canonical procedure is the op `afm path ops/gotcha`. The CLI owns the entry
+gate, the number, the frontmatter the trigger index reads and the index. This skill keeps only the judgment.
+
+## When NOT to activate
+
+This is a disambiguation for a skill that already activated. An architectural decision belongs to
+`/afm:adr`. A rule with an executable trigger belongs to `/afm:rule`. A recurring failure with an external
+signal belongs to `/afm:remediate`.
+
+## Pre-check
+
+`afm preflight`. Exit 3 means there is no instance: stop and suggest `/afm:init` or `/afm:refactor` first.
+
+## Procedure (judgment only)
+
+1. Validate the entry rule BEFORE you collect content: `afm ask gotcha`. `neither` stops: reject a gotcha
+   without a 2x incidence or an external doc.
+2. Collect the area, trigger, behavior, solution and references as free text. Decide how it fires: an
+   `event` when no file shape can fire it, a `file-shape` only with a narrow glob. A guessed trigger is worse
+   than one that never fires.
+3. Run `afm gotcha new <slug> --basis <bitten-twice|documented-sdk> ...` and report the path (#6). A later
+   re-bite is `afm gotcha bite <id>`.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. Two matter most here: #5 (do not
+invent a gotcha without a real case; the 2x entry check is a strong gate) and #6 (autonomy-first: save the
+result and report it).
+
+Passive mode (`/afm:reconcile`) is always on and can propose `/afm:gotcha` when it detects the signal "the
+same runtime surprise blocked work twice." This skill covers only active registration.

package/plugin/claude-code/skills/init/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: init
+description: |
+  Bootstraps AFM in a greenfield project. The CLI materializes `<consumer>/docs/` mechanically; the skill runs the interview for what only the operator knows, asking closed questions through `afm ask`. It detects the `docs/.template` marker and branches to the from-template path. It activates ONLY on explicit invocation and never from project state.
+  Activates: `/afm:init`, "build the AFM doc", "bootstrap AFM".
+---
+
+# AFM — Init (greenfield bootstrap)
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
+
+This skill of `afm` handles **greenfield bootstrap** and the from-template branch. It has a single
+responsibility. It does not route ops (each op is its own skill).
+
+The interview script is `afm path interview/bootstrap`. This skill is a router. It **never invents a
+procedure. It always reads the source first.** The layout of the shipped content is `afm path README`.
+
+---
+
+## When NOT to activate
+
+This is a disambiguation criterion for a skill that already activated. It is not an activation trigger.
+
+If the project already has `docs/.afm-version`, use the atomic skills instead. To move to a new version, use
+`/afm:update`. A brownfield codebase with no docs needs `/afm:refactor` instead.
+
+## Pre-check (before any action)
+
+1. **`afm preflight`.** Exit 3 means there is no `docs/.afm-version`: continue. Any other exit means the
+   project is already bootstrapped. **Do not run bootstrap again.** The atomic skills stay available
+   (`/afm:gotcha`, `/afm:adr`, `/afm:rule`, `/afm:promote`, `/afm:specify`, `/afm:plan`, `/afm:tasks`, `/afm:clarify`,
+   `/afm:analyze`, `/afm:export-template`), and passive mode (`/afm:reconcile`) stays always-on.
+2. **Does `docs/.template` exist?** Yes means the project comes from a template: ask `afm ask init-template`
+   whether to run the from-template branch, a subset focused on the product (default `Product only`). `Full
+   interview` goes to pre-check 3.
+3. **Does the project have significant pre-existing code?** A populated source root and a manifest with real
+   dependencies, or a git log with more than 20 commits. If so this is NOT the right path: stop and suggest
+   `/afm:refactor`: *"This project already has code. Greenfield bootstrap would make you pretend it is new.
+   `/afm:refactor` infers the docs from the existing code. Want to run it?"* `afm refactor --mechanical
+   --dry-run` states the verdict with its reasons.
+4. **Is the shipped content resolved?** `afm preflight` exit 4 means it is not. Tell the operator. Do not
+   guess the content and do not fail silently.
+
+---
+
+## Procedure (greenfield bootstrap)
+
+For projects without `docs/.afm-version`:
+
+1. Read `afm path interview/bootstrap` end to end.
+2. Ask the closed decisions the mechanical pass needs: `afm ask init`. Then run `afm init --mechanical`
+   (preview with `--dry-run`, or `--answers <file>` for a headless run). It creates `docs/` and `docs/adr/`,
+   fills the skeletons with the measured rule constants and `[TBD]` where the code answers nothing, copies
+   every rubric and pattern, writes `AGENTS.md` plus the harness stubs, and writes `docs/.afm-version` last.
+3. **Run the 7-step interview literally.** One question per turn. Free text only for open descriptions. For
+   everything with closed options, ask through `afm ask <op>` with the recommendation first (invariant
+   principle #8). Validate each answer with `afm ask confirm`. Fill each step into the matching
+   `docs/<file>.md`, replacing `{{placeholders}}` with the operator's answers and leaving unknown answers as
+   `[TBD]` (invariant principle #4).
+4. Apply opt-in modules. For each stack the operator confirms, read `afm path modules/<stack>/ach.patch` and
+   `afm path modules/<stack>/rules.patch` and merge them into `docs/ach.md` and `docs/afm.md`. A
+   `gotchas.seed` is a **commented reference** only: the project's `docs/gotchas/` starts empty.
+5. Generate the indexes (`afm index --materialize`) and print a summary: list every `[TBD]` and ask which ones
+   to fill in now.
+
+**Branch from-template** (if pre-check 2 found `docs/.template`): run a subset of the steps. The subset is
+0 + 3 + 6 short + 7 adapted. Skip steps 1, 2, 4 and 5, because the template already has them. The full
+procedure is in `afm path interview/bootstrap` § Alternate branch. `.afm-version` gets an inheritance line.
+
+---
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES`. For this skill (greenfield), the 8 universals apply (§1-8).
+#9 (retroactive ADR, load-bearing) does NOT apply to init. Bootstrap forbids a retroactive ADR.
+
+## Continuous doctrine
+
+Passive mode (`/afm:reconcile`) is the responsibility of the `reconcile` skill. It stays always-on in any AFM
+project session. This skill covers only the active bootstrap procedure.
+
+## Version
+
+`afm version` prints the version in use. History: `afm path CHANGELOG`.

package/plugin/claude-code/skills/plan/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: plan
+description: |
+  Fills `plan.md` for the active feature. It reads the stack from `ach.md` and infers the affected components from the code. It records each decision with its rejected alternatives. It soft-blocks on an open `[NEEDS CLARIFICATION:]` in the spec.
+  Activates: `/afm:plan [<feature>]`, "plan feature", "draft plan for feature X".
+---
+
+# AFM — Plan
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
+
+An atomic skill. The procedure lives in the op: read it with `afm path ops/plan.md`, end to end, and follow it literally.
+
+## When NOT to activate
+
+There is no `spec.md` yet: run `/afm:specify` first. An end-to-end delivery is `deliver`, which composes this op.
+
+## Pre-check
+
+Run `afm preflight` (exit 3: stop and suggest `/afm:init` or `/afm:refactor`). Run `afm feature status <NNN> --json`: a non-empty `blockers` means open `[NEEDS CLARIFICATION:]` markers in the spec, and the op asks the `open-markers` question (`afm ask plan`) before it goes on.
+
+## Procedure
+
+Read the stack from `docs/ach.md` and never reopen it. Infer the components, decisions, contracts and complexity from the code scan, and ask only for what the scan cannot resolve. Create the plan with `afm new feature-plan --feature NNN-slug` and fill it, including the first real `for_paths`. List the hard rules of `docs/afm.md` § 3 that apply, each binary. Suggest an ADR (`afm adr new <slug>`) for a load-bearing decision. Autonomy-first: write and report.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply. In particular #2 (discover-first: scan before you ask), #5 (do not invent contracts or a stack) and #8 (a question carries a recommendation).
+
+## Continuous doctrine
+
+Passive mode is the always-on `reconcile` skill. This skill covers only the planning.
+
+## Version
+
+`afm version`. History: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/policy/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: policy
+description: |
+  Reports what the organisation policy bundle imposes in this project. It answers which rules apply, which gotchas apply, whether the bundle can block, and what the reader may not edit here. It reads only and writes to neither bundle.
+  Activates: `/afm:policy`, "what does the organisation impose here", "which rules come from outside this repository", "why can I not edit this rule".
+---
+
+# AFM — Policy (report the organisation layer)
+
+Atomic skill of `afm`. The canonical procedure is the op `afm path ops/policy`.
+
+## When not to activate
+
+Never to CHANGE the policy. This skill reads. The organisation bundle belongs to whoever owns it, and no
+operation in this plugin writes to it.
+
+## Pre-check
+
+`afm preflight`. Exit 3 means there is no instance: stop. No organisation policy configured is a valid state
+that `afm policy report` says plainly, and a bundle with no `policy.md` is not a policy bundle: report it
+and stop.
+
+## Procedure (judgment only)
+
+Run `afm policy report` and read it by family. Say plainly that a policy bundle injects context and blocks
+nothing, and name what the reader may not edit here and who owns it. Never report a policy rule as
+enforced.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply.

package/plugin/claude-code/skills/promote/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: promote
+description: |
+  Records an instance learning that applies to every AFM project. It stores the finding in the project's machine state, classifies the target, and formats it as an issue body. It needs reproducible mechanical evidence. It never edits the plugin.
+  Activates: `/afm:promote`, "this applies to any project", "this rule should be in the template", "this gotcha should be in the template".
+---
+
+# AFM — Promote
+
+Atomic skill of `afm`. The canonical procedure is the op `afm path ops/promote`.
+
+## When NOT to activate
+
+This disambiguation applies once this skill has already activated. Project-specific learning stays in
+`<consumer>/docs/`. Use `/afm:generalize` to consolidate gotchas INSIDE the instance. Use `/afm:update` to
+bring the plugin INTO the instance (the opposite direction).
+
+## Pre-check
+
+`afm preflight`. Exit 3 means there is no instance: stop and suggest `/afm:init` or `/afm:refactor` first.
+
+## Procedure (judgment only)
+
+1. Read `afm path interview/promotion` and apply the gate for reproducible mechanical evidence: the command
+   that proves the defect or the learning, with its output before and expected after. No command means an
+   observation in the report, not a finding.
+2. Walk the classification (project entity, one stack, a convention, a pattern, or universal) to set the
+   `target`. A learning that names a project entity stays in `docs/`.
+3. Record it: `afm findings record --target <target> --title "<title>" --evidence "<command> → <output>"
+   --note "<why it applies to any instance>"`. Report and stop.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. That includes #5: never record a
+project-specific learning, and never one without a real case; the list grows on demand.
+
+It also includes #6/#7: the plugin boundary is **absolute**. This op records a finding and never applies a
+change.
+
+Passive mode (`/afm:reconcile`) is always on and can propose `/afm:promote` when it detects a signal that a
+learning generalizes to any project.

package/plugin/claude-code/skills/protocol/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: protocol
+description: |
+  Declares or reports the autonomy protocol of the project. The protocol parametrizes the PLAN threshold, the retry cap and the learning cadence. Three presets exist: p1 autonomous, p2 assisted, p3 planned-autonomous. It writes `protocol:` to `docs/_focus.md`, and with no argument it only reports.
+  Activates: `/afm:protocol [<name>]`, "what protocol am I using", "switch to assisted", "decide on your own for this delivery", "stop asking me so much".
+---
+
+# AFM — Protocol (declared autonomy posture)
+
+Skill of `afm`. The canonical procedure is the op `afm path ops/protocol`. Field and preset definitions are
+in `afm path core/protocol`.
+
+> **A protocol is data, not a new execution path.** It parametrizes operations that already exist. A project
+> with no `protocol:` declared uses the defaults, which reproduce pre-v4 behavior.
+
+## When NOT to activate
+
+This is a disambiguation for a skill that already activated. Running a delivery is `/afm:deliver` (it
+**reads** the current protocol, it does not set it). Changing a hard rule is `/afm:rule`. Adjusting the work
+focus without touching posture is a direct edit to `docs/_focus.md`. A mid-delivery "go ahead" is an
+**ephemeral gate override**, not a protocol change, and it does not activate this skill.
+
+## Pre-check
+
+1. `afm preflight`. Exit 3 means there is no instance: stop and suggest `/afm:init` or `/afm:refactor`.
+2. **`p1` becomes current only through explicit invocation in this session.** Never infer it from natural
+   language and never inherit it from `git pull`. Granting the loosest posture is a human act, not a
+   repository act: a person runs `afm protocol p1 --i-mean-it`.
+
+## Procedure (judgment only)
+
+Run `afm protocol` to report, or `afm protocol <p1|p2|p3>` to switch. Then explain the **behavior delta** the
+command printed, because switching protocols without knowing what changes means switching contracts blind.
+Outside the three presets, the file must already exist: never invent one.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES`. See especially #4 and #5.
+
+#4: `[TBD]` beats invention. An instance with no declared posture does not receive an assumed one.
+
+#5: Do not invent a preset without a real case.

package/plugin/claude-code/skills/reconcile/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: reconcile
+description: |
+  Always-on passive mode. It watches the signals in `interview/triggers.md` and proposes one edit to `docs/` at the end of the turn. It never applies the edit on its own and needs no command. It stays active in any project with `docs/.afm-version`, next to any other skill and to normal code work.
+---
+
+# AFM — Reconcile (passive mode, always-on)
+
+The always-on skill. It loads the continuous doctrine and the passive-mode procedure, and it is the only skill that activates by default in any AFM project session. Every other skill needs explicit invocation or specific natural language.
+
+## When NOT to activate
+
+A project without `docs/.afm-version`: stay silent until bootstrap. Do not interfere with a bootstrap session (`/afm:init`) or a refactor session (`/afm:refactor`); they create `.afm-version`, and reconcile starts after that.
+
+## Pre-check
+
+`afm preflight` exits 0 when the project is bootstrapped: reconcile is active, so load the signal table and the procedure and watch the whole session. Exit 3 means it is not: stay silent and propose nothing.
+
+## Doctrine
+
+One criterion decides where something belongs (universal principle #1, source in `afm path PRINCIPLES.md`):
+
+> *"If another developer, or another agent without my memory, needs to know this to avoid breaking something, it is a doc, not memory."*
+
+`docs/` holds rules, decisions, gotchas, architecture, persona, flows and cross-module contracts. The agent's memory holds only the user's style and durable preferences ("small PRs, not big bundles") and personal context (role, years of experience, current focus).
+
+`docs/` is a living source, **not a frozen bootstrap artifact**: it evolves through the whole session by passive reconcile. The signal table is `afm path interview/triggers.md`. The procedure is the op: read it with `afm path ops/reconcile.md`.
+
+## Procedure (always-on)
+
+In any session of a project with `docs/.afm-version`:
+
+1. Load `afm path interview/triggers.md`: the signals, the affected docs and the ready-made phrasing.
+2. Load the op `afm path ops/reconcile.md`: the literal passive-mode procedure.
+3. Monitor the work in progress (code, debugging, refactor, feature, doc edit). When a signal fires (a new structural decision, a runtime surprise twice, a correction with a reusable rule, a new component), **propose an edit** to the right `docs/` file at the end of the turn.
+4. **Never auto-apply** (principle #6: autonomy-first applies inside an invoked op or an approved feature; a passive signal is not approved scope).
+5. When a proposal becomes a concrete action, suggest the matching op: `/afm:adr`, `/afm:gotcha`, `/afm:rule`, `/afm:promote`, `/afm:specify`, and more.
+
+## Critical anti-patterns
+
+Never apply an edit without proposing it first, never save a project rule in memory, never invent a gotcha without a 2x trigger, never promote to the template before the operator confirms, and never interrupt code work with a long proposal: use one short line at the end of the turn. The full list is in the op.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply, in particular #1 (the one criterion for memory against doc), #5 (no gotcha or rule without a case) and #6 (reconcile PROPOSES at the end of the turn).
+
+## Version
+
+`afm version`. History: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/refactor/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: refactor
+description: |
+  Adopts AFM retroactively in a brownfield codebase. The CLI reads the code, the git log and the existing rules and materializes `<consumer>/docs/` with `[TBD]` in the gaps; the skill then asks the gap questions through `afm ask`. New rules are forward-only in `afm.md § 3.1`. It activates ONLY on explicit invocation and never from project state.
+  Activates: `/afm:refactor`, "adopt AFM here", "build the doc retroactively", "infer docs from the code".
+---
+
+# AFM — Refactor (brownfield retroactive)
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
+
+This skill of `afm` handles **retroactive AFM adoption in a brownfield codebase**. Single responsibility. It
+does not route ops (each op is its own skill).
+
+The roadmap is `afm path interview/refactor`. This skill is a router. It **never invents procedure and always
+reads the source first**. The layout of the shipped content is `afm path README`.
+
+---
+
+## When NOT to activate
+
+This is a disambiguation check for a skill already active. It is not an activation trigger.
+
+The project already has `docs/.afm-version`: use `/afm:update` to raise the version, refactor refuses. A
+project with `docs/.template` needs `/afm:init` (from-template branch).
+
+## Pre-check (before any action)
+
+1. **`afm preflight`.** Exit 3 means there is no `docs/.afm-version`: continue. Any other exit means the
+   project is already bootstrapped: **refactor does not run.** The atomic skills stay available (`/afm:gotcha`,
+   `/afm:adr`, `/afm:rule`, `/afm:promote`, `/afm:specify`, `/afm:plan`, `/afm:tasks`, `/afm:clarify`, `/afm:analyze`,
+   `/afm:export-template`), and passive mode (`/afm:reconcile`) is already always-on. **If the
+   goal was to raise the instance to a newer version** (`.afm-version` drift), use `/afm:update`: refactor
+   creates an instance, update updates an existing one.
+2. **Does `docs/.template` exist?** Yes means the project comes from a template, and refactor is not the right
+   path. Suggest `/afm:init` (it detects the marker and branches to the from-template flow).
+3. **Is this real brownfield?** `afm refactor --mechanical --dry-run` checks it and states the reasons: a
+   manifest with real dependencies, a populated source root, a git history of more than 20 commits. Any
+   false means this is not brownfield: suggest `/afm:init` (*"This project does not yet seem to have a relevant
+   codebase. `/afm:init` does the greenfield bootstrap. Want to run that?"*).
+4. **Is the shipped content resolved?** `afm preflight` exit 4 means it is not. Report it. Do not guess the
+   content and do not fall back silently.
+
+---
+
+## Procedure (brownfield refactor)
+
+For brownfield projects without `docs/.afm-version`:
+
+1. Read `afm path interview/refactor` end to end.
+2. Ask the closed decisions the mechanical pass needs (`afm ask init`), announce the plan in one line and
+   proceed directly: **no gate** (invoking `/afm:refactor` already approves this, per invariant principle #6).
+3. **Run the 4 parts literally:**
+   - **Part A**: `afm refactor --mechanical` runs the autonomous code archaeology (stack scan, folder tree,
+     entity scan, CI and hooks scan, hard-rule audit, retroactive ADR candidates) and prints the report. No
+     turns with the operator. Read the README and the history yourself for the prose-only facts.
+   - **Part B**: the same command materialized the skeleton of `docs/{prd,ach,afm,ust,gotchas}`; fill the
+     drafts from the report with `[TBD]` in the gaps and report a summary plus paths. Review happens through
+     `git diff`. No review gate applies.
+   - **Part C**: run a short interview, one question per turn, closed ones through `afm ask <op>`
+     recommendation-first (invariant principle #8). Cover the pain point, the persona and the README summary
+     validation, retroactive ADRs (with a load-bearing guardrail, invariant principle #9), confirmed gotchas,
+     DoD + pre-push and code-style seeds.
+   - **Part D**: write `afm.md § 3.1` with forward-only rules based on the audit. Check `docs/.afm-version` and
+     `AGENTS.md`.
+4. Apply the opt-in modules detected in A.1. For each stack, merge `afm path modules/<stack>/ach.patch` and
+   `afm path modules/<stack>/rules.patch` into the draft. A `gotchas.seed` becomes a commented block in the
+   gotchas doc. Only the entries the operator confirms in C.9.5 become active.
+5. Print a closing summary plus a suggested commit (see the roadmap § Closing).
+
+---
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES`. For this skill (brownfield), **all** apply: the 8 universals
+§1-8 plus the addition §9 (a retroactive ADR is load-bearing-only). #9 separates refactor from init. Init
+forbids retroactive ADRs.
+
+## Continuous doctrine
+
+Passive mode (`/afm:reconcile`) is the responsibility of the `reconcile` skill. It is always-on in any AFM
+project session. This skill covers only the active refactor procedure.
+
+## Version
+
+`afm version` prints the version in use. History: `afm path CHANGELOG`.