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

package/plugin/agy/skills/afm-restructure/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: afm-restructure
+description: |
+  Checks the context architecture of the local docs. It looks at staleness against the code, findability across layers, and the hot versus on-demand partition. It relocates content that already exists and writes no new content.
+  Activates: `afm-restructure`, "the doc is stale versus the code", "this should load only on demand", "the guidance exists but I cannot find it in the doc".
+---
+
+
+# AFM — Restructure (context architecture health)
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and your shell tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with the host's question tool when it has one, and otherwise in chat as a numbered list: the `prompt`, then the `options` with their descriptions, the recommended one first and marked. Wait for the answer. 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 a mechanism skill of AFM. The canonical procedure is the op file that `afm path ops/restructure.md` prints.
+
+> **Carve-out (does not overlap existing ops):** `diagnose` A1 finds a **dead reference** (the path does not exist). `restructure` staleness finds a path that **exists but changed** while the doc did not. `reconcile` adds **missing** information. `restructure` relocates information that **exists but sits in the wrong place**. `reflect` targets **clarity**. `restructure` targets **location and freshness**. `evolve` is the **orchestrator** that composes this skill when `diagnose` flags staleness or bloat.
+>
+> **Maturity (honest YAGNI):** the actionable core today is **staleness** (from git) plus **findability**. **Temperature tiering** (always-hot vs on-demand) is an **opt-in** ADR proposal, only for a doc that has actually outgrown its size. Small docs do not need it.
+
+## When NOT to activate
+
+This is a disambiguation guide for a skill that has already activated. It does not gate activation, so it stays in the body, not in the resident listing.
+
+A path that does not exist belongs to `afm-diagnose` (A1). Staleness means the path exists but changed. Information never documented belongs to `reconcile` → `afm-gotcha` or `afm-rule`. An ambiguous doc belongs to `afm-reflect`. Merging gotchas belongs to `afm-generalize`. The full cycle belongs to `afm-evolve`.
+
+## 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. **Is git available?** The staleness scan needs the git history. Without git, `afm doctor` marks this axis "not covered: no git". Never omit it.
+
+## Procedure
+
+Read the op (`afm path ops/restructure.md`) end to end. Follow it literally. Use these five steps.
+
+1. **Staleness scan.** `afm doctor --json` runs it (findings with axis `staleness` and `dead-gotcha`); read them. The git trigger fires in two cases. First case: a path cited in the doc has a later last commit than the doc. Second case: the doc has been stale for more than N commits. A hit is a candidate, not a verdict. The scan never rewrites the doc on its own.
+2. **Findability.** Relocate or cross-reference information that exists but sits buried or in the wrong doc. Cite both locations. Route information that is genuinely missing to `reconcile`.
+3. **Temperature partition.** Propose a hot/on-demand loading strategy as an opt-in ADR. Do this only when a doc has outgrown its size. Preserve 100% of the content.
+4. **Its own gate.** This gate is load-bearing and earned, one `afm ask restructure --scope <item-slug>` per finding. It follows the **shared-proposal discipline** in `evolve.md` (`afm path ops/evolve.md`), instead of a duplicate copy of that discipline. `evolve` suppresses this gate when it runs.
+5. **Record.** Write the result to `docs/evolution/NNN-<date>.md`. Suggest `promote` if the finding generalizes.
+
+## Invariant principles
+
+The single canonical source is `PRINCIPLES.md` (`afm path PRINCIPLES.md`). Universal principles §1-8 apply here. Four principles matter most for this skill.
+
+- #2: get git evidence before you propose a change.
+- #3: staleness needs an executable git trigger.
+- #4/#5: missing product content becomes `[TBD]` or goes to `reconcile`. Never invent it.
+- #6/#8: self-check the work, then pass an earned gate.
+
+**No new principle here.** `restructure` is a composed materialization. The doctrine lives in the op file.
+
+## Version
+
+Content version: `afm version` prints it.

package/plugin/agy/skills/afm-rule/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: afm-rule
+description: |
+  Adds a hard rule to `<consumer>/docs/afm.md § 3`. A mechanical trigger is mandatory and must return 0 or 1, such as `grep`, `wc -l`, `git diff` or `tsc`. A code review or a PR template is not a trigger. Without a trigger the entry becomes a principle in § 1.3.
+  Activates: `afm-rule`, "new hard rule", "this should be a rule".
+---
+
+# AFM — Rule
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and your shell tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with the host's question tool when it has one, and otherwise in chat as a numbered list: the `prompt`, then the `options` with their descriptions, the recommended one first and marked. Wait for the answer. 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/rule`. The CLI owns the number, the
+rule file, the index line and the runner skeleton, and refuses a rule with no honest trigger form. This
+skill keeps only the judgment.
+
+## When NOT to activate
+
+This is a disambiguation for a skill that already activated. Use `afm-adr` for a one-off architectural
+decision. Use `afm-gotcha` for a counterintuitive surprise. Use `afm-generalize` to merge rules or gotchas
+that already exist.
+
+## Pre-check
+
+`afm preflight`. Exit 3 means there is no instance: stop and suggest `afm-init` or `afm-refactor` first.
+
+## Procedure (judgment only)
+
+1. Confirm the mechanical trigger as free text, and push back hard: no trigger means a principle in § 1.3.
+   Run the anti-Goodhart test: can a diff pass the trigger while it breaks the rule's intent? If yes, rewrite
+   or downgrade it.
+2. Measure the repo for any constant and propose the value with the measurement. An unanswered constant is
+   `[TBD]`. Check for an existing versioned script and cite it.
+3. Choose the surface: `afm ask rule`. Run `afm rule new <slug> --trigger '<command>' --surface <surface>` and
+   report the paths (#6). For `pre-commit` or `ci`, follow "Install the gate" in the op: `afm gate --baseline`
+   before the gate goes on.
+4. In a refactored project only, ask where the rule enters: `afm ask rule-scope` (universal § 3 or
+   forward-only § 3.1). The scope decision reflects intent, so it stays fixed once made.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. Note especially #3 (a hard rule needs
+a mechanical trigger, or it is a principle instead) and #6 (autonomy-first: materialize the change and
+report it).
+
+Passive mode (`afm-reconcile`) is always on and can propose `afm-rule` when it detects the signal "the user
+corrected an approach with a reusable rule".

package/plugin/agy/skills/afm-specify/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: afm-specify
+description: |
+  Opens a feature folder at `docs/features/NNN-slug/spec.md`, linked to a user story. A mechanical heuristic decides first, because a feature folder for a trivial change is overhead.
+  Activates: `afm-specify <slug>`, "open a feature", "start a new feature", "create a feature folder".
+---
+
+# AFM — Specify
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and your shell tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with the host's question tool when it has one, and otherwise in chat as a numbered list: the `prompt`, then the `options` with their descriptions, the recommended one first and marked. Wait for the answer. 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/specify.md`, end to end, and follow it literally.
+
+## When NOT to activate
+
+A trivial change (no feature folder needed) goes straight to the `afm.md § 2` loop. A full end-to-end delivery is `deliver`, which composes this op.
+
+## Pre-check
+
+Run `afm preflight`. Exit 3 means no `docs/.afm-version`: stop and suggest `afm-init` or `afm-refactor`. Exit 4 or 5: report the line it printed.
+
+## Procedure
+
+The number comes from `afm next-id feature`, never by hand. What is left to you is judgment: compute the trigger heuristic from the scan (ask the `heuristic` question only when borderline), find the linked US in `docs/ust.md` before asking (`afm ask specify`), create the spec with `afm new feature-spec <slug>` (the generator writes the frontmatter the template names) and fill its body, update the `Spec:` line of the US, and report the open `[NEEDS CLARIFICATION:]` items. Autonomy-first: write and report, review through `git diff`.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply. In particular #2 (discover-first: compute the heuristic and the US from the scan), #5 (never invent a success criterion) and #6 (autonomy-first).
+
+## Continuous doctrine
+
+Passive mode is the always-on `reconcile` skill. This skill covers only the opening of the feature.
+
+## Version
+
+`afm version`. History: `afm path CHANGELOG.md`.

package/plugin/agy/skills/afm-tasks/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: afm-tasks
+description: |
+  Generates `tasks.md` in TDD order, and marks the parallel tasks with `[P]`. Every task references a user story or a requirement. It hard-blocks on an open `[NEEDS CLARIFICATION:]` in the plan.
+  Activates: `afm-tasks [<feature>]`, "generate the tasks", "break the feature into tasks".
+---
+
+# AFM — Tasks
+
+An atomic skill. The procedure lives in the op: read it with `afm path ops/tasks.md`, end to end, and follow it literally.
+
+## When NOT to activate
+
+There is no `plan.md` yet: run `afm-plan` 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` is an open `[NEEDS CLARIFICATION:]` in the plan. That is a hard refusal with no override, not a question.
+
+## Procedure
+
+Break the plan into four phases (Setup, Foundation RED/GREEN, Boundary, Reconciliation) from the generator (`afm new feature-tasks --feature NNN-slug`). Mark `[P]` only where a task does not depend on the one before it; a GREEN never is. Give every task a `US-NNN` or `RF-NN`. Then run `afm feature lint <NNN>` and fix what it reports until it exits 0. The last task closes the `status:` keys. Autonomy-first: write and report.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply. In particular #5 (every task traces to a US or RF) and rule 1 (TDD: no GREEN without the RED before it).
+
+## Continuous doctrine
+
+Passive mode is the always-on `reconcile` skill. This skill covers only the task list.
+
+## Version
+
+`afm version`. History: `afm path CHANGELOG.md`.

package/plugin/agy/skills/afm-update/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: afm-update
+description: |
+  Syncs `<consumer>/docs/` with the current plugin version. It materializes the consumer-facing deltas between the pinned version and the shipped version, then moves the pin. It reads the plugin and never edits it.
+  Activates: `afm-update`, "bump the methodology version", "sync docs with the new plugin", "my `.afm-version` is behind".
+---
+
+# AFM — Update (sync instance-plugin)
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and your shell tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with the host's question tool when it has one, and otherwise in chat as a numbered list: the `prompt`, then the `options` with their descriptions, the recommended one first and marked. Wait for the answer. 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 the sync skill of `afm`. The canonical procedure is the op `afm path ops/update`. The CLI runs the
+codemod registry, proves each op and moves the pin. This skill keeps the judgment.
+
+> **Carve-out (does not overlap existing ops):** `afm-init` and `afm-refactor` **create** the instance
+> (bootstrap). `update` brings an **existing** instance forward, the path that `afm-refactor` refuses.
+> `afm-diagnose` only **detects** drift on axis A3 (read-only). `update` **resolves** it. `afm-promote`
+> **records** a finding meant for the plugin. `update` reads the plugin and materializes it into the
+> instance, and neither touches the shipped content: an absolute boundary (#7). `afm-evolve` is the
+> **cycle** that composes `update` on axis A3.
+
+## When NOT to activate
+
+This is a disambiguation for a skill that already activated. Use `afm-init` or `afm-refactor` if no instance
+is bootstrapped yet. Skip `update` if the pinned version already equals the shipped version (no drift). Use
+`afm-promote` to carry a learning from the instance TO the plugin (the opposite direction). Use
+`afm-diagnose` to only CHECK for drift. Use `afm-evolve` for the full cycle.
+
+## Pre-check
+
+`afm update --dry-run` does it: exit 3 means no instance (suggest `afm-init` or `afm-refactor`), exit 4 means
+the shipped content does not resolve (report it, do not fall back silently), and "already up to date" ends
+the run. A pin **ahead** of the binary is an anomaly: report it, never roll it back.
+
+## Procedure (judgment only)
+
+1. Read the dry run as one package and show it as evidence. Ask `afm ask update`. Under `afm-evolve` this gate
+   is suppressed.
+2. Run `afm update`. It moves the pin only at the end, and keeps it where it was when a codemod fails.
+3. Exit 6 means agent tasks are pending: do each one inside its scope (`afm lint --fix <path>` fixes the
+   frontmatter findings), then run `afm-update` again. `afm update --accept <path>` closes a sync on a file
+   you merged by hand. An opt-in delta is reported and never applied. Exit 5 (a major crossing) is
+   `afm migrate`.
+4. **Language migration** (when the instance is not English): read `prd.md` § 11.1 FIRST and derive the
+   excluded scope from it, and only then read a file. `[TBD]` there stops the step and asks
+   `afm ask update-strings`. It never picks a language. The artifacts question is
+   `afm ask update-artifacts`.
+5. Post-conditions: `afm index --check` returns 0 and the plugin boundary stays clean. Report in chat what
+   migrated and what stayed pending. Under `afm-evolve`, feed it to `docs/evolution/`.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. Follow #2 (discover-first): the proof of
+need is the grep that shows what is missing. Follow #4/#5: materialize only what the plugin already provides
+ready-made, and never invent missing product content. Follow #6 (autonomy-first with a gate). Bright line
+#7 applies: only **read** the plugin, and write only to the instance.
+
+**No new principle here.** `update` is composed materialization. The doctrine lives in the op file.

package/plugin/agy/skills/afm-verify/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: afm-verify
+description: |
+  Stamps a human verification on one doc under `docs/`. It writes the OKF `verified` field and is the only writer of that field. Use it when a person states they reviewed a document.
+  Activates: `afm-verify <path>`, "I reviewed this rule", "mark this gotcha as verified", "sign off on this ADR".
+---
+
+# AFM — Verify (stamp a human review)
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and your shell tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with the host's question tool when it has one, and otherwise in chat as a numbered list: the `prompt`, then the `options` with their descriptions, the recommended one first and marked. Wait for the answer. 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/verify`.
+
+## When not to activate
+
+Never on ordinary work, and never on your own output. This skill records that a PERSON read a document. An
+agent stamping its own writing produces a lie the trust tier cannot detect.
+
+## Pre-check
+
+1. `afm preflight`. Exit 3 means there is no instance: stop.
+2. **Did a person state they reviewed the file?** If not, stop and ask: `afm ask verify`. Inference is not
+   review.
+3. The file must carry a frontmatter block, or there is no contract to stamp.
+
+## Procedure (judgment only)
+
+Run `afm verify <path under docs/>` (add `--as <id>` when no git user name is set). The command refuses an
+agent actor. Report the tier that resulted and what it means.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. #5 is load-bearing here.

package/plugin/claude-code/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+	"$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+	"name": "afm",
+	"description": "The AFM plugin for Claude Code, installed by `afm install claude-code`.",
+	"owner": {
+		"name": "Mapree"
+	},
+	"plugins": [
+		{
+			"name": "afm",
+			"description": "Agent Flow Methodology: autonomous discovery, a strict TDD delivery loop, and documentation that evolves from measured evidence. The CLI owns state, ids, gates and lint; the skills carry the judgment.",
+			"source": "./"
+		}
+	]
+}

package/plugin/claude-code/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+	"name": "afm",
+	"description": "Agent Flow Methodology: autonomous discovery, a strict TDD delivery loop, and documentation that evolves from measured evidence. The CLI owns state, ids, gates and lint; the skills carry the judgment.",
+	"version": "4.0.0-alpha.6",
+	"author": {
+		"name": "Mapree"
+	},
+	"license": "UNLICENSED"
+}

package/plugin/claude-code/.mcp.json

@@ -0,0 +1,7 @@
+{
+	"mcpServers": {
+		"afm": {
+			"command": "afm-mcp"
+		}
+	}
+}

package/plugin/claude-code/agents/afm-executor.md

@@ -0,0 +1,18 @@
+---
+name: afm-executor
+description: Writer of one bounded change. Makes the edit its brief names, test first, inside the files the brief grants, and reports what changed; dispatched with a brief.
+tools: mcp__plugin_afm_afm, Read, Grep, Glob, Edit, Write, Bash
+---
+You are an executor. The message that dispatched you is your brief: follow it.
+
+You make the change the brief names, and only that change.
+
+- Touch only the files the brief grants. Another file you need is a question for the caller, not an edit.
+- Test first: a failing test (or a type that does not compile yet), then the smallest change that
+  makes it pass, then the refactor. Run the tests and the type check before you report.
+- Reuse what exists before you add a helper. Add no option, hook or abstraction the brief did not ask for.
+- Never print, write or commit a secret.
+- Never push, and never commit unless the brief says to.
+
+Reply with the files you changed, the checks you ran with their exact result, and anything you left
+undone or doubt.

package/plugin/claude-code/agents/afm-explorer.md

@@ -0,0 +1,20 @@
+---
+name: afm-explorer
+description: Read-only investigator. Answers one question from the code, the docs or the web, cites what it read, and changes nothing; dispatched with a brief.
+tools: mcp__plugin_afm_afm__approve, mcp__plugin_afm_afm__config, mcp__plugin_afm_afm__detect, mcp__plugin_afm_afm__doctor, mcp__plugin_afm_afm__failures_promotable, mcp__plugin_afm_afm__feature_lint, mcp__plugin_afm_afm__feature_status, mcp__plugin_afm_afm__gate, mcp__plugin_afm_afm__index, mcp__plugin_afm_afm__lang, mcp__plugin_afm_afm__next_id, mcp__plugin_afm_afm__path, mcp__plugin_afm_afm__policy, mcp__plugin_afm_afm__preflight, mcp__plugin_afm_afm__version, Read, Grep, Glob, WebFetch, WebSearch
+maxTurns: 60
+---
+You are an explorer. The message that dispatched you is your brief: follow it.
+
+You only read. You never edit a file, run a command that changes state, or commit.
+
+- Read only what the question needs: the sections you are about to use, not whole trees.
+- Cite every claim: a path with the line, or a source URL with the literal quote. A claim with no
+  citation is a guess, and you label it a guess.
+- Never invent a path, a line number, a URL or a quote. If you did not read it, you do not cite it.
+- Say what you could not find. Absence is a result.
+
+You have at most 60 steps. Write the answer whole, not a step at a time. If you run out, reply with
+what you have and what is still missing.
+
+Reply with the answer first, then the evidence, then the gaps.

package/plugin/claude-code/agents/afm-reviewer.md

@@ -0,0 +1,21 @@
+---
+name: afm-reviewer
+description: Blind auditor. Checks one piece of work it did not write against its sources and rules, and returns a verdict with evidence; dispatched with a brief.
+tools: mcp__plugin_afm_afm__approve, mcp__plugin_afm_afm__config, mcp__plugin_afm_afm__detect, mcp__plugin_afm_afm__doctor, mcp__plugin_afm_afm__failures_promotable, mcp__plugin_afm_afm__feature_lint, mcp__plugin_afm_afm__feature_status, mcp__plugin_afm_afm__gate, mcp__plugin_afm_afm__index, mcp__plugin_afm_afm__lang, mcp__plugin_afm_afm__next_id, mcp__plugin_afm_afm__path, mcp__plugin_afm_afm__policy, mcp__plugin_afm_afm__preflight, mcp__plugin_afm_afm__version, Read, Grep, Glob, WebFetch, WebSearch
+---
+You are a reviewer. The message that dispatched you is your brief: follow it.
+
+You audit work you did not write. You read it and the sources or rules it answers to. You never
+write a fix.
+
+- Judge against the rules and sources the brief names, not against taste.
+- Verify, do not trust: open each cited path, line or quote and confirm it says what the work claims.
+- Run the checks the brief lists that the `afm` tools offer (the gate, the doctor, the index), alone and one
+  at a time, and report their exact output. You have no shell: a check that needs one is a check you did
+  not run, and you say so.
+- Report a finding only with its evidence: the path and line, the rule it breaks, and the concrete
+  input or state that fails. A suspicion with no evidence is not a finding.
+- Say what you did not check.
+
+End with one verdict line: PASS when no finding stands, FAIL otherwise, followed by the findings
+most severe first.

package/plugin/claude-code/hooks/hooks.json

@@ -0,0 +1,85 @@
+{
+	"description": "AFM: injects the rules, gotchas and doctrine of /docs into the session, gates a commit and a doc edit before they run, and records the work. Silent outside an AFM project; a bug in a hook never stops the session.",
+	"hooks": {
+		"SessionStart": [
+			{
+				"matcher": "startup|clear|compact",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "afm hook SessionStart",
+						"timeout": 10
+					}
+				]
+			}
+		],
+		"PreToolUse": [
+			{
+				"matcher": "Write|Edit|MultiEdit",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "afm hook PreToolUse",
+						"timeout": 5
+					}
+				]
+			},
+			{
+				"matcher": "Bash",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "afm hook PreToolUse",
+						"timeout": 20
+					}
+				]
+			}
+		],
+		"PostToolUse": [
+			{
+				"matcher": "Write|Edit|MultiEdit|Bash|Skill",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "afm hook PostToolUse",
+						"timeout": 5
+					}
+				]
+			}
+		],
+		"PostToolUseFailure": [
+			{
+				"matcher": "Bash",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "afm hook PostToolUseFailure",
+						"timeout": 5
+					}
+				]
+			}
+		],
+		"SubagentStart": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "afm hook SubagentStart",
+						"timeout": 5
+					}
+				]
+			}
+		],
+		"Stop": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "afm hook Stop",
+						"timeout": 10
+					}
+				]
+			}
+		]
+	}
+}

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

@@ -0,0 +1,44 @@
+---
+name: adr
+description: |
+  Writes an Architecture Decision Record to `<consumer>/docs/adr/NNNN-slug.md`. It records context, decision, alternatives and consequence. In a refactored project, write a retroactive ADR only when it is load-bearing.
+  Activates: `/afm:adr`, "create ADR", "architectural decision", "record this architecture choice".
+---
+
+# AFM — ADR
+
+> **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/adr`. The CLI owns the number, the
+template, the frontmatter, the supersede link and the index. This skill keeps only the judgment.
+
+## When NOT to activate
+
+This is a disambiguation for a skill that already activated. It does not control activation itself. A
+counterintuitive surprise belongs in `/afm:gotcha`. A rule with an executable trigger belongs in `/afm:rule`.
+
+## Pre-check
+
+`afm preflight`. Exit 3 means there is no instance: stop and suggest `/afm:init` (greenfield) or
+`/afm:refactor` (brownfield) first. Exit 4 means the shipped content does not resolve: report it, do not
+fall back silently.
+
+## Procedure (judgment only)
+
+1. Ask the status: `afm ask adr`. Collect the title, context, decision, alternatives, consequence and refs
+   as free text, because these fields carry intent.
+2. Run `afm adr new <slug> --title "<title>" --description "<one sentence>"`, with `--supersedes N` when
+   the decision replaces ADR N.
+3. Fill the sections of the printed file with what the operator said, and leave the rest `[TBD]`. Report the
+   path (#6).
+
+The "Additional step in a refactored project" in the op applies ONLY when `/afm:refactor` adopted the
+project (signal: `afm.md` § 3.1 forward-only exists). A greenfield project forbids a retroactive ADR.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. Additional #9 (a retroactive ADR is
+load-bearing-only) applies ONLY in a refactored project.
+
+Passive mode (`/afm:reconcile`) is always on and can propose `/afm:adr` when it detects a "novel structural
+decision" signal. This skill covers only the active creation.

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

@@ -0,0 +1,36 @@
+---
+name: analyze
+description: |
+  Cross-checks one feature against the instance. It compares `docs/features/NNN-*/{spec,plan,tasks}.md` with prd, ust, ach, afm § 3 and PRINCIPLES. It reports findings by severity in chat and writes no file.
+  Activates: `/afm:analyze [<feature>]`, "audit feature", "check coverage", "validate consistency before implementation".
+---
+
+# AFM — Analyze
+
+> **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/analyze.md`, end to end, and follow it exactly.
+
+## When NOT to activate
+
+Use `/afm:clarify` to resolve markers interactively. Use `/afm:deliver` for end-to-end delivery: it runs analyze underneath, in gating mode. Use `/afm:diagnose` for the health of the whole doc set.
+
+## Pre-check
+
+Run `afm preflight` (exit 3: no `docs/.afm-version`, stop and suggest `/afm:init` or `/afm:refactor`).
+
+## Procedure
+
+Start from the mechanical findings: `afm feature lint <NNN> --json` covers the passes A, C, D, E and the structure of `tasks.md`. Add the judgment on top (constitution violations, duplication, the semantic side of inconsistency and ambiguity), build the coverage table, assign severities by the matrix, and report in chat with metrics. Close with the `remediation` question (`afm ask analyze`). Gating mode sorts findings into buckets instead of reporting.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply, especially #2 (detection is an autonomous scan, not a question), #5 (no finding without evidence) and #6 (analyze is read-only: it reports in chat, writes no file, and remediates only on request).
+
+## Continuous doctrine
+
+Passive mode is the always-on `reconcile` skill. This skill covers only active auditing.
+
+## Version
+
+`afm version`. History: `afm path CHANGELOG.md`.

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

@@ -0,0 +1,36 @@
+---
+name: clarify
+description: |
+  Scans one feature for ambiguity. It asks the irreducible questions, recommendation first, and writes the answers to `spec.md § 7 Clarifications`.
+  Activates: `/afm:clarify [<feature>]`, "resolve markers", "clear up ambiguity in feature X", "clarify the spec".
+---
+
+# AFM — Clarify
+
+> **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/clarify.md`, end to end, and follow it literally.
+
+## When NOT to activate
+
+Use `/afm:analyze` for a read-only, multi-artifact validation that does not resolve markers. Use `/afm:deliver` for end-to-end delivery: it calls clarify underneath when needed.
+
+## Pre-check
+
+Run `afm preflight` (exit 3: no `docs/.afm-version`, stop and suggest `/afm:init` or `/afm:refactor`). `afm feature status <NNN> --json` lists the open markers of a feature in `blockers`.
+
+## Procedure
+
+Judgment only: a 9-category scan of the spec, a prioritized queue (at most 5 questions), auto-resolution from the code and docs before any question, then one recommendation-first question per turn. The questions come from the spec, so they are dynamic; the one fixed decision (`underspecified`) is in `afm ask clarify`. Integrate each answer into `spec.md` at once, remove the marker, and finish with the coverage summary.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply. #2 is discover-first: resolve each question yourself through the scan or the docs, then ask. #4 says `[TBD]` beats invention, and a recommendation is a rejectable hypothesis, not a guess. #6 is autonomy-first: write the integration into spec § 7 and report. #8 is recommendation-first questions.
+
+## Continuous doctrine
+
+Passive mode is the always-on `reconcile` skill. This skill covers only the active resolution of ambiguity.
+
+## Version
+
+`afm version`. History: `afm path CHANGELOG.md`.

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

@@ -0,0 +1,44 @@
+---
+name: deliver
+description: |
+  Delivers one feature from discovery to reconciliation. It takes one recorded approval (`afm approve`), writes spec, plan and tasks, then runs each task as RED, GREEN, REFACTOR, COMMIT. It resumes from the correct phase when those files exist. Orchestrator: it composes specify, plan, tasks, clarify, analyze and reconcile. External research is not an AFM op; it routes to nasca.
+  Activates: `/afm:deliver [<feature>]`, "build feature X", "implement X end to end", "the tasks already exist, run them", "continue the delivery of feature N".
+---
+
+# AFM — Deliver (orchestrated autonomous delivery)
+
+> **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.
+
+The **orchestrator** of the delivery loop. One request takes "build feature X" from discovery to a delivered feature. The procedure lives in the op: read it with `afm path ops/deliver.md`, end to end, and follow it literally. It does not duplicate the sub-steps: it reads and follows `specify`, `plan`, `tasks`, `clarify`, `analyze` and `reconcile` through a suppression contract.
+
+## When NOT to activate
+
+An isolated step ("just open the spec", "just generate the tasks") is the matching atomic skill. A trivial change goes straight to the `afm.md § 2` loop.
+
+## Pre-check
+
+Run `afm preflight`. Exit 0 continues. Exit 3 means no `docs/.afm-version`: stop and suggest `/afm:init` (greenfield) or `/afm:refactor` (brownfield). Exit 4 or 5: report the line it printed. Do not fall back silently.
+
+## Procedure
+
+The CLI holds the state; the skill keeps only the judgment. Drive the loop with `afm feature status <NNN> --json`, which returns the phase to resume at, the next task and the blockers.
+
+- **Discovery:** scan scoped to the feature, external unknowns through the nasca research flow (`nasca-research`, or `nasca-campaign` for a deep study; ask the operator if nasca is missing), unknowns sorted into resolved-by-scan, researchable and irreducible. One batched, recommendation-first round, capped by the protocol (`/afm:protocol`).
+- **Draft:** spec, plan and tasks, verified with `afm feature lint <NNN>` plus the judgment passes of `analyze`.
+- **Gate:** the earned questions plus the `outcome` question (`afm ask deliver`), then `afm approve <NNN>`. An explicit "go" skips the questions, never the record.
+- **Execute:** each task is one `core/afm.md` § 2 cycle, checked with `afm gate --staged`, then `afm task done <NNN> <Txxx>`. Halt on a non-`[P]` failure after the capped retry.
+- **Reconcile:** § 8.5 plus a passive sweep.
+
+If artifacts already exist, resume from the correct phase, including "tasks already exist, run from the first `[ ]`".
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply. The backbone is **#2** (discover-first: resolve unknowns by scan and research, ask only the irreducible part, never guess product or criteria) and **#6** (autonomy-first: approval at checkpoint granularity, the consolidated plan IS the proposal).
+
+## Continuous doctrine
+
+Passive mode is the always-on `reconcile` skill. It runs in parallel with `deliver` and takes the closing turn of Phase 4.
+
+## Version
+
+`afm version`. History: `afm path CHANGELOG.md`.