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

package/content/skills/promote.md

@@ -0,0 +1,39 @@
+---
+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
+
+## 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
+
+Most relevant here: #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/content/skills/protocol.md

@@ -0,0 +1,41 @@
+---
+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)
+
+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
+
+Most relevant here: #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/content/skills/reconcile.md

@@ -0,0 +1,45 @@
+---
+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`.
+
+## 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
+
+Most relevant here: #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).

package/content/skills/refactor.md

@@ -0,0 +1,79 @@
+---
+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)
+
+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
+
+For this skill (brownfield), **all** principles 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 always-on in any AFM project session. This skill covers only the active refactor procedure.

package/content/skills/reflect.md

@@ -0,0 +1,43 @@
+---
+name: reflect
+description: |
+  Finds where the local docs failed AS A HARNESS in the live session and the project's sessions since the last cycle. Examples are an ambiguous rule applied wrong, a doc that misled, and a user correction against the doc. The evidence is the session trajectory, never a static scan. It proposes edits that make the docs more assertive.
+  Activates: `afm reflect`, "this rule is ambiguous", "the doc sent me the wrong way", "why do I keep getting this wrong when the doc covers it?".
+---
+
+
+# AFM — Reflect (behavioral self-reflection on the docs)
+
+> **Carve-out (does not overlap existing ops):** `afm reconcile` works **code to docs, and is additive**. It learns a new fact and proposes adding it. `reflect` works **docs to docs, and refines**. An existing doc guided the agent wrong, so `reflect` proposes a clearer version. `afm diagnose` runs a **static** scan. `reflect` uses **behavioral** evidence from the session trajectory. Only the agent sees its own stumble. `afm evolve` is the **orchestrator**. It composes `reflect` and `afm diagnose` into one cycle with a single gate.
+
+## When not to activate
+
+This is a disambiguation criterion for a skill already active, not an activation criterion. That is why it lives in the body, not in the resident listing.
+
+Learning a new fact, gotcha, or decision belongs to passive mode (`afm reconcile`). Route it to `afm gotcha`, `afm rule`, or `afm adr`. A static mechanical scan belongs to `afm diagnose`. Merging N gotchas belongs to `afm generalize`. A failure with an external signal belongs to `afm remediate`. 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. **Did the live session or the project's sessions since the last cycle hit a doc-friction event** (or an articulated symptom)? Read the window with `afm sessions --since reflect --json` and `afm sessions signals --since reflect --json`. If the whole window has no signal, report "no doc friction observed" and stop. Reflection without behavioral evidence is forbidden (#5).
+
+## Procedure
+
+The steps are:
+
+**1. Collection.** Build the behavioral signature φ_b = `(symptom-lived, doc-causal-status, mechanism)`. Cite both the doc passage **and** the session event (`session:<id>@<ts>`). Weight: one signal in the live session suffices; a past-session signal needs 2 or more sessions, an explicit correction, or `regressed`, and `regressed` comes first. A repeated prompt is a finding: propose the artifact that stops the retyping.
+
+**2. Self-critique.** Consider a rival hypothesis: it was me, not the doc. Apply the guardrail: a violated rule is not a wrong rule. Apply an addressability filter.
+
+**3. Proposal.** Refine instructiveness: rewrite the ambiguous part, add an executable trigger, and remove ambiguity. Add suggestions for the human. This step follows the **shared proposal discipline** in `evolve.md` (`afm path ops/evolve.md`) and does not duplicate it.
+
+**4. Own gate.** Ask item by item, earned, with `afm ask reflect --scope <item-slug>`. `afm evolve` suppresses this gate.
+
+**5. Record.** Write to `docs/evolution/NNN-<date>.md`. Add an `afm promote` suggestion when the finding generalizes. Hand off to passive mode (`afm reconcile`).
+
+## Invariant principles
+
+Rule #1 applies: refine the doc's instructiveness, not the agent's memory. Rule #5 applies: no lived event, no finding. Rule #6 applies: self-verify, then report. The gate is a load-bearing residue. Bright lines #7 for plugin, deletion, and push apply.
+
+Rule #8 applies: a suggestion or question must be earned, recommendation-first. **No new principle here.** `reflect` is a composed materialization. The doctrine lives in the op file.

package/content/skills/remediate.md

@@ -0,0 +1,33 @@
+---
+name: remediate
+description: |
+  Reads the open failures of the state store (`afm failures promotable`) and proposes the durable artifact: a procedure when the fix is mechanical, a learning when it is conceptual. A failure enters by external signal, never by self-judgment.
+  Activates: `afm remediate`, "this failed again, fix it for real", "create a runbook for this", "record this lesson for the next agent sessions".
+---
+
+
+# AFM — Remediate (CRITIC loop)
+
+## When NOT to activate
+
+This is a disambiguation for a skill that already activated. It is not an activation trigger. That is why it lives in the body and not in the resident listing.
+
+Use `afm.md § 5.1` for an in-task retry at the moment of the error. Use `afm gotcha` for an SDK surprise with no failure of its own. Do not invent a failure. Only act on a recorded failure that `afm failures promotable` lists, or on an explicit user correction.
+
+## Pre-check
+
+1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop. Suggest `afm init` for a greenfield project or `afm refactor` for a brownfield project.
+2. **Is there an open failure?** Run `afm failures promotable`. With `no failure is promotable` and no explicit user correction, report "nothing to remediate" and stop. An empty diagnosis is a valid result.
+3. **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 op includes the promotion gate (#5): 1 user correction OR at least 2 mechanical occurrences promote a failure. A transient failure does not promote. It also includes classification through the rubric `rubrics/failure-classification.md` (`afm path rubrics/failure-classification.md`). For each delta, propose the artifact (procedure or learning) and cite the source `sig=` (hard rule 19). Ask the artifact question with `afm ask remediate --scope <sig>`, materialize the result, close the signature with `afm failures close --sig <sig> --as remediated`, and report it (#6).
+
+## Invariant principles
+
+Most relevant here: #3 (CRITIC corollary — recognition by tool, not self-judgment). See also #5 (do not promote a failure without recurrence or an oracle) and #6 (propose only, the human approves).
+
+## Continuous doctrine
+
+Passive mode (`afm reconcile`) is always on. It reads `afm failures promotable` at the end of the turn and can propose remediation with no explicit command. The `afm evolve` cycle uses the failure events as evidence for `afm reflect`, toward a final remediation. This skill is the active record of the loop.

package/content/skills/restructure.md

@@ -0,0 +1,46 @@
+---
+name: 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)
+
+> **Carve-out (does not overlap existing ops):** `afm 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. `afm reconcile` adds **missing** information. `restructure` relocates information that **exists but sits in the wrong place**. `afm reflect` targets **clarity**. `restructure` targets **location and freshness**. `afm evolve` is the **orchestrator** that composes this skill when `afm 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 passive mode (`afm 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
+
+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 passive mode (`afm 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. `afm evolve` suppresses this gate when it runs.
+5. **Record.** Write the result to `docs/evolution/NNN-<date>.md`. Suggest `afm promote` if the finding generalizes.
+
+## Invariant principles
+
+Most relevant here:
+
+- #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 passive mode (`afm 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.

package/content/skills/rule.md

@@ -0,0 +1,43 @@
+---
+name: 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
+
+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
+
+Most relevant here: #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/content/skills/specify.md

@@ -0,0 +1,28 @@
+---
+name: 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
+
+## 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 `afm 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
+
+Most relevant here: #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 (`afm reconcile`) is always on. This skill covers only the opening of the feature.

package/content/skills/tasks.md

@@ -0,0 +1,24 @@
+---
+name: tasks
+description: |
+  Generates the `tasks:` list of `tasks.md` in TDD order with `afm task add`. 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
+
+## When NOT to activate
+
+There is no `plan.md` yet: run `afm plan` first. An end-to-end delivery is `afm 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.
+
+## Principles
+
+Most relevant here: #5 (every task traces to a US or RF) and rule 1 (TDD: no green task without the red task it closes).
+
+## Continuous doctrine
+
+Passive mode (`afm reconcile`) is always on. This skill covers only the task list.

package/content/skills/update.md

@@ -0,0 +1,58 @@
+---
+name: 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)
+
+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`. On migrate, run the rewrite as one orchestrated batch through
+   {{host:workflow}}, with a light model per agent ({{host:light-model}}) for the rewrite and the loss
+   check. Escalate only a flagged file to a capable model. The session model keeps the excluded scope and
+   the final gate.
+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
+
+Most relevant here: #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/content/skills/verify.md

@@ -0,0 +1,29 @@
+---
+name: 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)
+
+## 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
+
+Most relevant here: #5 is load-bearing.

package/content/templates/adr.template.md

@@ -0,0 +1,51 @@
+---
+type: template
+description: 'Template rendered during materialization: ADR-NNNN — {{short title on the decision, not on the problem}}.'
+load: cold
+renders_to: 'docs/adr/*.md'
+frontmatter_for_output: |
+  type: adr
+  description: '<one sentence: the decision and why it matters>'
+  load: warm
+  status: proposed           # proposed | accepted | superseded | deprecated. Set from step 2's
+                              # `afm ask adr` answer; `afm adr --supersedes` sets superseded.
+  date: YYYY-MM-DD           # The day the decision was written down.
+  decided_by: '<who>'        # `[TBD]` when nobody said.
+  supersedes: ADR-NNNN       # ONLY when this decision replaces an earlier one. Omit otherwise.
+  superseded_by: ADR-NNNN    # ONLY when status is superseded by a later decision. Omit otherwise.
+  relates_to: [ADR-NNNN]     # ONLY when it depends on or refines other ADRs. Omit otherwise.
+  trigger_path: '{{glob}}'   # ONLY when this decision constrains one path or family of paths.
+                              # Most decisions bind none: omit the key rather than guess one.
+---
+
+# ADR-NNNN — {{short title on the decision, not on the problem}}
+
+## Context
+
+{{What was happening, what problem appeared, which constraints (time, scope, security, cost) limit the decision. 3-5 sentences. Cite the concrete symptom that forced the decision. Do not invent a retroactive motivation.}}
+
+## Decision
+
+{{What was decided, in one header sentence.}}
+
+{{Operational details. What changes in the code, in which file, with which contract. Use a concrete, absolute path and a snippet when useful.}}
+
+## Alternatives considered
+
+- **{{alternative A}}** — why it was NOT chosen (cost / risk / simplicity).
+- **{{alternative B}}** — why it was NOT chosen.
+
+<!-- guidance -->
+(List 1-3 alternatives. If you considered none, write "Direct decision — no alternatives evaluated because {{reason}}".)
+<!-- /guidance -->
+
+## Consequence
+
+{{What becomes easy now. What becomes hard now. Accepted technical debt. A gotcha other developers will hit (link to `gotchas.md` if it applies).}}
+
+## References
+
+- Commit: `{{sha}}`
+- Related US/RF: US-NNN / RF-NN
+- Canonical doc: `/docs/{{file}}.md` §X
+- External issue / PR: {{link}}