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

package/plugin/opencode/agents/afm-executor.md

@@ -0,0 +1,39 @@
+---
+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.
+mode: subagent
+permissions:
+  - action: "*"
+    resource: "*"
+    effect: deny
+  - action: "read"
+    resource: "*"
+    effect: allow
+  - action: "glob"
+    resource: "*"
+    effect: allow
+  - action: "grep"
+    resource: "*"
+    effect: allow
+  - action: "edit"
+    resource: "*"
+    effect: allow
+  - action: "shell"
+    resource: "*"
+    effect: allow
+  - action: "afm_*"
+    resource: "*"
+    effect: allow
+---
+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/opencode/agents/afm-explorer.md

@@ -0,0 +1,92 @@
+---
+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.
+mode: subagent
+steps: 60
+permissions:
+  - action: "*"
+    resource: "*"
+    effect: deny
+  - action: "read"
+    resource: "*"
+    effect: allow
+  - action: "glob"
+    resource: "*"
+    effect: allow
+  - action: "grep"
+    resource: "*"
+    effect: allow
+  - action: "webfetch"
+    resource: "*"
+    effect: allow
+  - action: "websearch"
+    resource: "*"
+    effect: allow
+  - action: "afm_approve"
+    resource: "*"
+    effect: allow
+  - action: "afm_config"
+    resource: "*"
+    effect: allow
+  - action: "afm_detect"
+    resource: "*"
+    effect: allow
+  - action: "afm_doctor"
+    resource: "*"
+    effect: allow
+  - action: "afm_failures_promotable"
+    resource: "*"
+    effect: allow
+  - action: "afm_feature_lint"
+    resource: "*"
+    effect: allow
+  - action: "afm_feature_status"
+    resource: "*"
+    effect: allow
+  - action: "afm_gate"
+    resource: "*"
+    effect: allow
+  - action: "afm_index"
+    resource: "*"
+    effect: allow
+  - action: "afm_lang"
+    resource: "*"
+    effect: allow
+  - action: "afm_next_id"
+    resource: "*"
+    effect: allow
+  - action: "afm_path"
+    resource: "*"
+    effect: allow
+  - action: "afm_policy"
+    resource: "*"
+    effect: allow
+  - action: "afm_preflight"
+    resource: "*"
+    effect: allow
+  - action: "afm_read"
+    resource: "*"
+    effect: allow
+  - action: "afm_sessions"
+    resource: "*"
+    effect: allow
+  - action: "afm_sessions_signals"
+    resource: "*"
+    effect: allow
+  - action: "afm_version"
+    resource: "*"
+    effect: allow
+---
+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/opencode/agents/afm-reviewer.md

@@ -0,0 +1,93 @@
+---
+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.
+mode: subagent
+permissions:
+  - action: "*"
+    resource: "*"
+    effect: deny
+  - action: "read"
+    resource: "*"
+    effect: allow
+  - action: "glob"
+    resource: "*"
+    effect: allow
+  - action: "grep"
+    resource: "*"
+    effect: allow
+  - action: "webfetch"
+    resource: "*"
+    effect: allow
+  - action: "websearch"
+    resource: "*"
+    effect: allow
+  - action: "afm_approve"
+    resource: "*"
+    effect: allow
+  - action: "afm_config"
+    resource: "*"
+    effect: allow
+  - action: "afm_detect"
+    resource: "*"
+    effect: allow
+  - action: "afm_doctor"
+    resource: "*"
+    effect: allow
+  - action: "afm_failures_promotable"
+    resource: "*"
+    effect: allow
+  - action: "afm_feature_lint"
+    resource: "*"
+    effect: allow
+  - action: "afm_feature_status"
+    resource: "*"
+    effect: allow
+  - action: "afm_gate"
+    resource: "*"
+    effect: allow
+  - action: "afm_index"
+    resource: "*"
+    effect: allow
+  - action: "afm_lang"
+    resource: "*"
+    effect: allow
+  - action: "afm_next_id"
+    resource: "*"
+    effect: allow
+  - action: "afm_path"
+    resource: "*"
+    effect: allow
+  - action: "afm_policy"
+    resource: "*"
+    effect: allow
+  - action: "afm_preflight"
+    resource: "*"
+    effect: allow
+  - action: "afm_read"
+    resource: "*"
+    effect: allow
+  - action: "afm_sessions"
+    resource: "*"
+    effect: allow
+  - action: "afm_sessions_signals"
+    resource: "*"
+    effect: allow
+  - action: "afm_version"
+    resource: "*"
+    effect: allow
+---
+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/opencode/skills/afm-adr/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: afm-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 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.
+
+> **Procedure.** Run `afm read ops/adr.md` and follow it; read an on-demand section when its condition holds.
+
+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
+
+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.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/opencode/skills/afm-analyze/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: afm-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 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.
+
+> **Procedure.** Run `afm read ops/analyze.md` and follow it; read an on-demand section when its condition holds.
+
+## 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`); a remediation that adds a task runs `afm task add`, never a hand edit of the `tasks:` list, and a task is closed only with `afm task done`. Gating mode sorts findings into buckets instead of reporting.
+
+## Invariant principles
+
+Most relevant here: #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 (`afm-reconcile`) is always on. This skill covers only active auditing.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/opencode/skills/afm-clarify/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: afm-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 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.
+
+> **Procedure.** Run `afm read ops/clarify.md` and follow it; read an on-demand section when its condition holds.
+
+## 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
+
+Most relevant here: #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 (`afm-reconcile`) is always on. This skill covers only the active resolution of ambiguity.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/opencode/skills/afm-deliver/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: afm-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)
+
+> **Procedure.** Run `afm read ops/deliver.md` and follow it; read an on-demand section when its condition holds.
+
+The **orchestrator** of the delivery loop. One request takes "build feature X" from discovery to a delivered feature. It does not duplicate the sub-steps: it reads and follows `afm-specify`, `afm-plan`, `afm-tasks`, `afm-clarify`, `afm-analyze` and `afm-reconcile` through a suppression contract. External unknowns go through `nasca-research`, or `nasca-campaign` for a deep study; ask the operator if nasca is missing.
+
+## 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.
+
+## Most relevant here
+
+**#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 (`afm-reconcile`) is always on. It runs in parallel with `afm-deliver` and takes the closing turn of Phase 4 (`core/afm.md` § 8.5 plus a passive sweep).
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/opencode/skills/afm-diagnose/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: afm-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)
+
+> **Procedure.** Run `afm read ops/diagnose.md` and follow it; read an on-demand section when its condition holds.
+
+> **Carve-out (does not overlap existing ops):** `afm-analyze` audits **one feature**. `diagnose` audits the **whole instance** of `/docs/`. `afm-reflect` uses **behavioral** evidence, where the agent stumbled. `diagnose` is **static**, based on filesystem and git. `afm-evolve` is the **orchestrator**. It combines `diagnose` (mechanical evidence) with `afm-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
+
+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 `afm-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
+
+Most relevant here: #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.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/opencode/skills/afm-evolve/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: afm-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 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.
+
+> **Procedure.** Run `afm read ops/evolve.md` and follow it; read an on-demand section when its condition holds.
+
+This is an orchestrator skill of AFM. The canonical procedure is the op file that `afm path ops/evolve.md` prints.
+
+> **Carve-outs (it does not override existing ops):** `afm-diagnose`, `afm-reflect`, `afm-generalize` and `afm-restructure` are the **mechanisms** (each runs à la carte). `afm-analyze` audits **one feature** (read-only). Passive mode (`afm-reconcile`) proposes **one single edit** at the end of a turn. `afm-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`. Passive mode (`afm-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: evidence collection (diagnose plus reflect), proposal in 3 buckets, a single gate (`afm ask evolve`), apply with post-conditions, and the log in `docs/evolution/`.
+
+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.
+
+## Most relevant principles
+
+#2 (discover-first): diagnose with evidence before you propose. #3 (mechanize-or-downgrade): evolve's own signals must pass the same test evolve applies to others. #6 (autonomy-first with self-check): the gate is the load-bearing residue, and the bright lines for #7 plugin, deletion, and push still apply. #8 (earned questions, recommendation-first).
+
+## Continuous doctrine
+
+Passive mode (`afm-reconcile`) is always on. It 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.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/opencode/skills/afm-export-template/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: afm-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 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.
+
+> **Procedure.** Run `afm read ops/export-template.md` and follow it; read an on-demand section when its condition holds.
+
+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
+
+Most relevant here: #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.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/opencode/skills/afm-generalize/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: afm-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 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.
+
+> **Procedure.** Run `afm read ops/generalize.md` and follow it; read an on-demand section when its condition holds.
+
+> **Carve-out (does not overlap existing ops):** `afm-promote` **registers** a finding meant for the plugin. It does not write to the plugin. `afm-generalize` merges **inside the instance** (N gotchas become 1 rule in the same `/docs/`). `afm-reconcile` **adds** a new gotcha. `afm-generalize` **merges** gotchas that already exist. `afm-reflect` refines **one** doc. `afm-generalize` consolidates **many**. `afm-evolve` is the **orchestrator** and it composes this skill when `afm-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 `afm-reconcile` -> `afm-gotcha`/`afm-rule` (`afm-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).
+
+## Gate
+
+The merge is load-bearing and goes through its own earned gate, `afm ask generalize` (suppressed under `afm-evolve`). Merged entries become tombstones; never delete.
+
+## Most relevant here
+
+#1 (episodic `gotchas.md` -> semantic `afm.md`), #3 (a merged rule becomes hard only with an executable 0/1 trigger), #5 (no abstraction without a real batch), #6/#8 (self-verify before an earned gate; deletion is a bright line, so archive as tombstones). No new principle here: the doctrine lives in the op.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/opencode/skills/afm-gotcha/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: afm-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 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.
+
+> **Procedure.** Run `afm read ops/gotcha.md` and follow it; read an on-demand section when its condition holds.
+
+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
+
+Most relevant 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.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.