@sabaiway/agent-workflow-kit 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -4,6 +4,56 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 1.14.0 — Activity procedures: recipe-aware, configurable playbooks
+
+A new read-only **`/agent-workflow-kit procedures <activity>`** advisor turns a bare command like
+"write a plan" into a codified, recipe-aware procedure. It reads the named activity's ordered steps
+**live** from the installed engine (`references/procedures.md`) and prints them verbatim, then resolves
+the **effective recipe per slot** from a new per-project, hand-edited config and the read-only backend
+detector. Two v1 activities: **`plan-authoring`** (slot: `review`) and **`plan-execution`** (slots:
+`execute`, `review`). It composes with the AD-018 recipes; **`recipes` stays read-only** (the config is
+hand-edited, never written by the kit).
+
+### Added
+- **`tools/procedures.mjs`** — the read-only CLI: live engine read + per-activity section extraction,
+  config IO + validation, and the resolved recipe per slot (default = Reviewed when a backend is ready,
+  Council on request, slot-aware incl. Delegated). A repeatable `--override <slot>=<recipe>` adjusts one
+  slot per run. Exit codes: `0` success (an unsatisfiable override degrades **loudly** but still `0`),
+  `2` usage (unknown activity / bad `--override`), `1` config or engine error (loud `path: reason`).
+- **`docs/ai/orchestration.json`** — the per-project, strict-JSON config (`{ activity: { slot: recipe } }`;
+  all slots optional; an optional `"_README"` is allowed + ignored). Hand-edited; kit-validated.
+- **`resolveActivityRecipe` / `ACTIVITIES` / `SLOT_RECIPES`** in `tools/recipes.mjs` — the pure resolver
+  (graceful default vs loud override degradation), drift-guarded against the engine canon's `Slots:`
+  lines. `planRecipe` / `recommendRecipe` are unchanged.
+- A **`workflow:methodology`** pointer clause routing to `/agent-workflow-kit procedures <activity>`
+  (the feature's only auto-discovery route — both engine + kit are `disable-model-invocation`).
+
+The deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change; no migration file). See
+**AD-019**.
+
+## 1.13.0 — Orchestration recipes: a named way to compose the bridges
+
+The kit now knows **how to put the optional execution-backends to work**, not just whether they're set
+up. A new read-only **`/agent-workflow-kit recipes`** advisor presents four named recipes — **Solo**
+(no backend), **Reviewed** (one backend reviews), **Council** (both review, you synthesize), and
+**Delegated** (a backend executes a bounded sub-task) — plans the right one for your environment, and
+**degrades gracefully with a stated reason** when a backend isn't ready (Council → Reviewed → Solo;
+Delegated → Solo). It offers the choice (a multiple-choice prompt where your agent supports it) and
+prints exactly what running it entails, including advisory quota/health notes. It is **read-only**:
+the orchestrator runs the chosen recipe through the bridge skills and always makes the single commit —
+the kit never executes a recipe and never runs a subscription CLI.
+
+Every deployed `AGENTS.md` now also carries a one-line **orchestration-recipes pointer** (right under
+the methodology pointer), reconciled live from the engine on bootstrap + upgrade. And the read-only
+backend-status line that bootstrap/upgrade already print gains an **actionable tail** — e.g.
+*"recipes: Reviewed available (via codex) — see /agent-workflow-kit recipes"* — so you're nudged
+toward the recipe that fits, never left guessing.
+
+Both entry-point templates were trimmed for headroom so both pointers fit inside the 100-line cap; if
+an entry point is already at the limit, the orchestration pointer is **skipped and reported** (never
+silently) while the methodology pointer still lands. The deployment-lineage head stays **`1.3.0`** (no
+`docs/ai` structural change; no migration file). See **AD-018**.
+
 ## 1.12.0 — See the whole family, and uninstall it cleanly
 
 Two new in-agent modes, built on a single **unified family registry**. `/agent-workflow-kit status`

package/README.md

@@ -221,6 +221,8 @@ command is printed).
 | `/agent-workflow-kit backends` | any time | **read-only** check of the optional execution-backends (the `codex` / `agy` bridges): what's set up vs missing and the next step. Never writes, never commits, never runs a subscription CLI (credentials = marker-file presence, not a live login). |
 | `/agent-workflow-kit setup [backend]` | opt-in, any time | **link-only** auto-setup of a bridge: places the bundled bridge skill (only into an absent / empty / managed dir — never overwrites an unmanaged one) + links its wrappers onto `PATH` via managed symlinks (idempotent; refuses to clobber a non-symlink; try `--dry-run` to preview). The binary install + the one-time subscription login stay **manual**: it prints the exact **login** command and points the binary install at each bridge's `setup/README.md`. POSIX wrappers — on Windows use WSL. Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit status` | any time | **read-only** view of the whole family: which members (kit / memory / engine / the two bridges) are installed and at what version, and — with a project — what's deployed (`docs/ai`, the version stamps, and whether the AI files are git-ignored for hidden mode). Never writes, never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit recipes` | any time | **read-only** orchestration advisor: presents four named recipes for composing the bridges into plan → execute → review — **Solo / Reviewed / Council / Delegated** — plans + recommends one for your environment (degrading with a stated reason when a backend isn't ready), and offers the choice. The orchestrator runs it via the bridge skills and **always commits**; the kit never executes a recipe, never runs a subscription CLI, never commits. |
+| `/agent-workflow-kit procedures <activity>` | any time | **read-only** activity-procedures advisor: prints a named activity's ordered steps (`plan-authoring` / `plan-execution`) read **live** from the engine, plus the **resolved recipe per slot** from your hand-edited `docs/ai/orchestration.json` + backend readiness (default Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated). `--override <slot>=<recipe>` adjusts one slot per run. Composes with `recipes`; never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` / settings — for those it prints the exact `rm` commands to run by hand. Always `--dry-run` first; preflight-then-mutate; never commits. |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.
@@ -260,8 +262,10 @@ agent-workflow-kit  —  the composition root (installed via npx … init)
 
 - **Delegates** substrate deployment to **`@sabaiway/agent-workflow-memory`** when a healthy
   standalone copy is present, else uses its **bundled fallback** — same `docs/ai/` either way.
-- **Injects** the bounded workflow methodology into the deployed `AGENTS.md`. Its *future* home is
-  **`agent-workflow-engine`** — today an `available: false` stub, never one of the shipped backends.
+- **Injects** two bounded pointers into the deployed `AGENTS.md` — the workflow **methodology** and the
+  **orchestration recipes** (Solo / Reviewed / Council / Delegated) — read **live** from the installed
+  **`agent-workflow-engine`** (the canonical narrative; a published member, never one of the shipped
+  backends). `/agent-workflow-kit recipes` surfaces + plans a recipe for your environment, read-only.
 - **Detects & (opt-in) sets up** the optional `codex` / `agy` **bridges** — agent skills (not npm, not
   installed by `init`). They plug into the workflow's **execute** and **review** phases — for *what
   each adds and why*, see the
@@ -304,9 +308,11 @@ agent-workflow-kit/
 ├── tools/           ← family tooling:
 │   ├── manifest/    ← capability-manifest schema + validator
 │   ├── delegation.mjs        ← detect substrate · delegate-or-fall-back
-│   ├── inject-methodology.mjs ← write the methodology slot
+│   ├── inject-methodology.mjs ← write the methodology + recipe slots
 │   ├── engine-source.mjs     ← live engine fragment read (fail-loud)
 │   ├── detect-backends.mjs    ← read-only backend detector
+│   ├── recipes.mjs           ← read-only recipe planner (recipes)
+│   ├── procedures.mjs        ← activity-procedures advisor (procedures)
 │   ├── setup-backends.mjs     ← link-only backend setup
 │   ├── fs-safe.mjs            ← symlink-safe copy/link/remove/unlink
 │   ├── family-registry.mjs    ← unified family registry (status)

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '1.12.0'
+  version: '1.14.0'
 ---
 
 # agent-workflow-kit
@@ -52,34 +52,40 @@ made: a partial/broken memory install discovered mid-flow must not disable the w
 **Hand-off contract (explicit; tested independent of agent interpretation).**
 - **Delegated** (memory valid): the kit passes the **target project dir** + the **three setup
   answers** (visibility / language / attribution) to `agent-workflow-memory`, which writes
-  `docs/ai/` + `AGENTS.md` (with the empty slot) + **`.memory-version`**. The kit then
-  **reconciles the bounded methodology slot** (below) and writes the kit-fallback
-  **`.workflow-version`**. → **both stamps** present. In **hidden** mode the kit is the **single
+  `docs/ai/` + `AGENTS.md` (carrying the **two empty pointer pairs** — `workflow:methodology` and
+  `workflow:orchestration`) + **`.memory-version`**. The kit then **reconciles both bounded pointers**
+  (below) and writes the kit-fallback **`.workflow-version`**. → **both stamps** present. In **hidden** mode the kit is the **single
   hide authority**: after the hand-off it runs `tools/hide-footprint.mjs` (step 9), which **absorbs
   memory's project-local footprint lines** into the one canonical `.git/info/exclude` block and adds
   the external footprint — so there is **no machine-global write** at any step (a stale memory's
   residual global block is cleaned via the upgrade reconcile, below).
 - **Fallback** (memory absent/invalid): the kit runs the bootstrap procedure below from its own
-  bundled assets — whose entry-point template now ships the **empty methodology slot** the kit
-  reconciles + fills — and writes **`.workflow-version`** only. Softly suggest installing
-  `agent-workflow-memory` — never a prerequisite.
-
-**Methodology slot reconciliation (the kit is the ONLY writer of memory's slot).** After
-`AGENTS.md` exists, reconcile its `workflow:methodology` slot:
-`node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile <project>/AGENTS.md`. Reconcile is
-**one atomic operation**: **ensure the slot exists** (insert an empty marker pair right after the
-Session-Protocols anchor when a legacy entry point lacks one) → **inject the bounded fragment ONLY
-IF the slot is empty** (a filled / user-customized slot is preserved verbatim) → **cap-check**
-(keeps `AGENTS.md` ≤100 lines). The fragment is a short summary + pointer read **live from the
-installed `agent-workflow-engine`** (`references/methodology-slot.md`, the family's one source of
-truth) — **not** a bundled mirror, and **not** the full `references/planning.md`. The live read is
-**lazy + fail-loud**: the engine is consulted **only when the slot actually needs filling**, so a
-deployment whose slot is already filled reconciles to a zero-diff no-op even on a host without the
-engine; but when a fill **is** needed and the engine is **absent/invalid**, reconcile **STOPs** —
-report it in plain language with the one-line install command `npx @sabaiway/agent-workflow-engine@latest init`
-(`npx @sabaiway/agent-workflow-kit@latest init` installs the engine for you; translate, never leak tool internals). Contract:
-exactly one ordered `start → end` pair; a malformed slot (single, reversed, nested, duplicate) or a
-missing / duplicate anchor → **STOP with an error**, never edit (the file is left byte-for-byte unchanged).
+  bundled assets — whose entry-point template now ships **two empty pointer pairs** (`workflow:methodology`
+  + `workflow:orchestration`) the kit reconciles + fills — and writes **`.workflow-version`** only.
+  Softly suggest installing `agent-workflow-memory` — never a prerequisite.
+
+**Bounded pointer reconciliation (the kit is the ONLY writer of these slots).** After `AGENTS.md`
+exists, run ONE command — `node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile
+<project>/AGENTS.md` — which reconciles **two** bounded pointers in a single atomic write: the
+**workflow-methodology** pointer (the plan → execute → review summary) **and**, right below it, the
+**orchestration-recipes** pointer (the Solo / Reviewed / Council / Delegated vocabulary, routing to
+`/agent-workflow-kit recipes`). Each is **one atomic operation per slot**: **ensure the slot exists**
+(insert an empty marker pair at its anchor when a legacy entry point lacks one) → **inject the bounded
+fragment ONLY IF the slot is empty** (a filled / user-customized slot is preserved verbatim) →
+**cap-check** (the second pointer's check runs on the file *after* the first, so it guards the
+**combined** ≤100-line budget). Both fragments are short summary + pointer, read **live from the
+installed `agent-workflow-engine`** (`references/methodology-slot.md` + `references/orchestration-slot.md`,
+the family's one source of truth) — **not** a bundled mirror, and **not** the full references. The
+live read is **lazy + fail-loud**: the engine is consulted **only when a slot actually needs filling**,
+so a deployment whose pointers are already filled reconciles to a zero-diff no-op even on a host
+without the engine; but when a fill **is** needed and the engine is **absent/invalid**, reconcile
+**STOPs** — report it in plain language with the one-line install command
+`npx @sabaiway/agent-workflow-engine@latest init` (`npx @sabaiway/agent-workflow-kit@latest init`
+installs the engine for you; translate, never leak tool internals). Contract per slot: exactly one
+ordered `start → end` pair; a malformed slot (single, reversed, nested, duplicate) or a missing /
+duplicate anchor → **STOP with an error**, never edit (the file is left byte-for-byte unchanged). The
+**orchestration pointer is soft-skipped** (reported, never silent) when — and only when — adding it
+would exceed the 100-line cap: the methodology pointer still lands and the upgrade continues.
 
 **One composition-level commit gate.** The delegated memory mode performs **no** commit and
 raises **no** "ask to commit". There is exactly **one** gate, owned by the kit, **after**
@@ -97,6 +103,8 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 - **`/agent-workflow-kit backends`** — read-only environment check: which optional **execution-backends** (the `codex` / `agy` bridges) are set up vs missing. Never writes, never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit setup [backend]`** — the **link-only**, opt-in companion to `backends`: place the bundled bridge skill + link its wrappers onto `PATH`. **In-agent only** — `init` (npx) never places bridges. The binary install + the interactive subscription login stay **manual** (it prints the exact commands); idempotent; refuses to clobber a non-symlink; never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit status`** — read-only view of the **whole family**: which members (kit / memory / engine / the two bridges) are installed, at what version, and — in a project — what is deployed (`docs/ai`, the version stamps, the hidden-mode fence). Never writes, never commits, never runs a subscription CLI.
+- **`/agent-workflow-kit recipes`** — read-only **orchestration advisor**: present the four recipes (Solo / Reviewed / Council / Delegated) over the bridges' role vocabulary, plan + recommend one for the current environment, and offer the choice. **The orchestrator executes the chosen recipe via the bridge skills and always commits** — the kit only surfaces/selects/plans it; it never executes a recipe, never runs a subscription CLI, never commits.
+- **`/agent-workflow-kit procedures <activity>`** — read-only **activity-procedures advisor**: print the ordered steps of a named activity (`plan-authoring` / `plan-execution`) read **live** from the installed engine (`references/procedures.md`), and the **resolved effective recipe per slot** from the per-project `docs/ai/orchestration.json` (hand-edited, strict JSON) + backend readiness (default = Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated; graceful default vs loud override degradation). A per-run `--override <slot>=<recipe>` overrides one slot. Composes with `recipes` (which stays read-only); never writes, never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit uninstall`** — the **guarded teardown** companion to `init`/`setup`. Removes what they placed — installed skill dirs + the bridge wrappers — and, in a project, reverses the hidden-mode fence + the marker pre-commit hook. **Never deletes user-authored content** (`docs/ai`, `AGENTS.md`, `.claude/settings.json`): it prints the exact commands for you to run by hand. `--dry-run` first, always; preflight-then-mutate; never commits.
 
 ### Version status & the two axes — surface this on every invocation
@@ -105,7 +113,7 @@ Before acting, read `docs/ai/.workflow-version` (the project's stamp), state a o
 
 - **absent** → bootstrap (a fresh deployment).
 - **stamp < `1.3.0`** (the deployment-lineage head) → `upgrade`.
-- **stamp == `1.3.0`** → already current; only the stamp-independent reconciles may run (the methodology slot **and** the hidden-mode footprint, *Mode: upgrade* step 3).
+- **stamp == `1.3.0`** → already current; only the stamp-independent reconciles may run (the methodology slot, the hidden-mode footprint, **and** the `docs/ai/orchestration.json` config ensure, *Mode: upgrade* step 3).
 - **stamp > head / unparseable** → STOP — never-downgrade gate (see *Mode: upgrade* step 2).
 
 **Two independent version axes — never conflate them:**
@@ -120,12 +128,20 @@ Before acting, read `docs/ai/.workflow-version` (the project's stamp), state a o
 Bootstrap (step 11) and **every** successful `upgrade` exit (steps 4 + 8) print the **same**
 read-only, one-line summary of the optional execution-backends. Run the **backend detector** —
 `node ${CLAUDE_SKILL_DIR}/tools/detect-backends.mjs` — and compose one line from its per-backend
-readiness. Canonical format:
-`backends: codex ✓ ready · antigravity ✗ needs-credentials — run /agent-workflow-kit backends`
-
+readiness, then **append an actionable recipe recommendation** from the recipe planner
+(`node ${CLAUDE_SKILL_DIR}/tools/recipes.mjs --json` → `recommendation.clause`, P2-rich). Canonical format:
+`backends: codex ✓ ready · antigravity ✗ needs-credentials — run /agent-workflow-kit backends · recipes: Reviewed available (via codex) — see /agent-workflow-kit recipes`
+
+- The **`recipes:` clause is appended after** the `— run /agent-workflow-kit backends` pointer (never
+  replacing it) and routes to the read-only `recipes` mode (`see /agent-workflow-kit recipes`). It is
+  **never blank**: both backends ready → *"Council available, Reviewed the everyday default"*; one
+  ready → *"Reviewed available (via …)"*; **none installed → *"Solo — run /agent-workflow-kit setup to
+  add a backend"***; a backend present-but-not-ready → Solo with that backend's specific remedy.
+  (Matches `recommendRecipe`.)
 - **Invariants:** **read-only · never blocks the commit gate · never runs a subscription CLI · the
-  pointer is the in-agent `backends` mode, never a network fetch · `init`/npx is unaffected (it never
-  places bridges, AD-011 §5).**
+  pointer is the in-agent `backends` mode, never a network fetch · the appended `recipes:` clause
+  routes to the in-agent `recipes` mode the same way · `init`/npx is unaffected (it never places
+  bridges, AD-011 §5).**
 - **Detector unavailable → skip with a stated reason, never silently.** The detector is a Node script
   the **agent host** runs (not the target project), so the only skip condition is "**the agent host
   can't run it**" — `node` is not on the agent's PATH, or the detector itself errors — **not** "the
@@ -151,7 +167,7 @@ readiness. Canonical format:
 3. **Choose conversational language — ASK the user explicitly and wait for the answer.** Which language should the agent *talk to them* in — questions, explanations, summaries, status updates? Offer the language they're already writing in as the default. Carry the answer into the `{{COMM_LANGUAGE}}` slot of the *Communication language* block when `AGENTS.md` is created (step 5). See [Communication contract](references/contracts.md#communication-contract). This sets the **dialogue** language only — never the files.
 4. **Choose agent attribution — ASK the user explicitly and wait for the answer.** May the agent attribute work to itself / to AI — `Co-Authored-By` trailers, "Generated with …" footers, "AI"/agent/model mentions in code, comments, commit messages, PR titles/bodies, or docs? **Default to `off`** (no agent/AI mention anywhere) unless they opt in — people are routinely surprised to find an AI listed as a repo contributor. Carry the answer into the `{{AGENT_ATTRIBUTION}}` slot of the *Attribution* block when `AGENTS.md` is created (step 5). **If `off` and the project uses Claude Code**, also set `"includeCoAuthoredBy": false` in the project's `.claude/settings.json` (create it if absent) — the trailer is added by the harness, so a doc directive alone won't stop it. See [Attribution contract](references/contracts.md#attribution-contract).
 5. **Entry-point doc.** If `AGENTS.md` / `CLAUDE.md` already exist (step-1 recon), do **not** overwrite — show the user and ask whether to merge or replace. Otherwise create `AGENTS.md` (the cross-agent standard — Codex / Cursor / Devin Desktop / Copilot read it natively) from `${CLAUDE_SKILL_DIR}/references/templates/AGENTS.md`, and symlink `CLAUDE.md -> AGENTS.md` (`ln -s AGENTS.md CLAUDE.md`) for Claude Code — single source, no duplication. For nested context, add a subdir `AGENTS.md` (+ a `CLAUDE.md` symlink beside it for Claude Code).
-6. **Deploy `docs/ai/`.** Create the 11 files + `pages/` from `${CLAUDE_SKILL_DIR}/references/templates/`. Keep each file's frontmatter (`type / lastUpdated / scope / staleAfter / owner / maxLines`).
+6. **Deploy `docs/ai/`.** Create every `docs/ai/` file + `pages/` from `${CLAUDE_SKILL_DIR}/references/templates/` (the template loop deploys each non-`AGENTS.md` template — the `.md` docs **and** the seeded, user-editable **`docs/ai/orchestration.json`** config, strict JSON, the per-project recipe defaults the `procedures` advisor reads). Keep each `.md` file's frontmatter (`type / lastUpdated / scope / staleAfter / owner / maxLines`); `orchestration.json` carries no frontmatter (the docs cap-validator globs `*.md` only, so it is inherently skipped).
 7. **Fill templates** per the table below.
 8. **Install enforcement (Node projects).** Copy `${CLAUDE_SKILL_DIR}/references/scripts/*.mjs` (+ `*.test.mjs`) into the project's `scripts/`. They self-configure (project name from `package.json`, hierarchical/on-demand sections auto-discovered). **If the project has no Node runtime** (step-1 recon), skip this step and the hook in step 9 — follow the cap/archive/index policy manually, or port the scripts to the project's language.
 9. **Wire / hide** per visibility (see [Visibility contract](references/contracts.md#visibility-contract)). Install the pre-commit hook (Node projects): `node scripts/install-git-hooks.mjs`. If the installer reports a pre-existing non-marker hook, stop and ask the user to merge it manually rather than overwriting.
@@ -185,21 +201,23 @@ Fill strategy:
 
 1. Read `docs/ai/.workflow-version` (the project's stamped lineage). If missing, treat as a pre-versioned deployment and offer to re-bootstrap conservatively.
 2. **Never-downgrade gate — FIRST, before any write.** Compare the stamp to the **deployment-lineage head** (`1.3.0` — NOT this kit's package version). If the stamp is **greater than the head** or unparseable → **STOP and report**; do not touch a newer / unknown deployment at all (not even the methodology slot).
-3. **Reconcile the methodology slot — stamp-independent, BEFORE the equal-head short-circuit.** Reached only when the stamp **≤ head**. Run `node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile <project>/AGENTS.md`. This ensures the `workflow:methodology` slot exists and is filled on **every** upgrade, idempotently (zero-diff when already present + filled) — so even a legacy / current **`1.3.0`** deployment gains the slot **without a lineage-head bump** (the head stays `1.3.0`; **no `agent-workflow-memory` change**). It inserts an empty slot at the Session-Protocols anchor if absent, preserves a customized slot verbatim, and STOPs (never edits) on a malformed slot, a missing / duplicate anchor, or **when a fill is needed but the installed `agent-workflow-engine` is absent/invalid** (the fragment is read live from it — see the three distinct non-zero outcomes below).
+3. **Reconcile the bounded pointers — stamp-independent, BEFORE the equal-head short-circuit.** Reached only when the stamp **≤ head**. Run `node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile <project>/AGENTS.md`. ONE call reconciles **two** pointers — the **workflow-methodology** pointer and, right below it, the **orchestration-recipes** pointer (Solo / Reviewed / Council / Delegated, routing to `/agent-workflow-kit recipes`) — and is filled on **every** upgrade, idempotently (zero-diff when both are already present + filled), so even a legacy / current **`1.3.0`** deployment gains them **without a lineage-head bump or a migration** (the deployment-lineage head stays `1.3.0`; the `agent-workflow-memory` **package** template did get a docs-only headroom trim for the second pointer, but no deployed-`docs/ai` structure changed). Per slot it inserts an empty pair at its anchor if absent, preserves a customized pair verbatim, and STOPs (never edits) on a malformed pair, a missing / duplicate anchor, or **when a fill is needed but the installed `agent-workflow-engine` is absent/invalid** (both fragments are read live from it — see the distinct outcomes below).
 
-   **`reconcile` has THREE distinct non-zero exits — classify by the stderr text, handle each differently:**
+   **Classify the exit — there are THREE non-zero exits + one soft in-band skip; handle each differently:**
 
-   (a) **Cap-refusal — a soft, reported skip (CONTINUE the upgrade).** If — and ONLY if — `reconcile` exits non-zero because filling the slot would exceed the deployed `AGENTS.md` 100-line cap (the entry point is already at / over budget), leave the file byte-for-byte unchanged (the tool already did) and **continue** the upgrade without the slot. This is **not** a silent skip (Hard Constraint — no silent failures): report it explicitly in the successful-exit report (**step 4** on an equal-head deployment, else **step 8**), in plain language, e.g. *"The workflow-methodology pointer wasn't added — `AGENTS.md` is N lines, over its 100-line limit. The methodology is already documented in `docs/ai/agent_rules.md`; to add the pointer, trim the entry point (move detail into `docs/ai/`) and re-run upgrade."* N is the file's **current** line count — never the tool's number (that is the would-be post-injection size). Because the entry point is already over cap, ensure the rest of the upgrade does not push it further: any mandatory `AGENTS.md` edit must keep it ≤100 lines or pause for an explicit trim — never bust the cap to land a migration.
+   (a) **Soft, reported skip of the orchestration pointer (CONTINUE the upgrade).** The orchestration pointer is the less-critical second pointer; when it can't be added right now `reconcile` exits **zero**, keeps the methodology pointer, and **reports the skip on stdout** (the `… skipped …` line) — never silent (Hard Constraint). Two reasons: **(i)** the methodology pointer fits but adding the orchestration pointer would push the file past the `AGENTS.md` 100-line cap; or **(ii)** the installed `agent-workflow-engine` is **present but too old** to ship the recipes fragment (`<1.2.0`) — it can still supply the methodology pointer, so only the recipes pointer is withheld. Report it in the successful-exit report (**step 4** equal-head, else **step 8**) in plain language, e.g. *"The orchestration-recipes pointer wasn't added — the entry point is at its 100-line limit / your methodology engine is older than the recipes feature. The recipes are still available any time via `/agent-workflow-kit recipes`; to add the pointer, trim the entry point and/or refresh the engine with `npx @sabaiway/agent-workflow-engine@latest init`, then re-run upgrade."* (The separate case where the **methodology** pointer ITSELF can't fit the cap is a non-zero exit that changes nothing — continue without either pointer, same plain-language framing.)
 
-   (b) **Malformed slot / missing-or-duplicate anchor — a hard STOP (do NOT continue).** A different non-zero exit (above); never soft-skip it.
+   (b) **Malformed pair / missing-or-duplicate anchor (either pointer) — a hard STOP (do NOT continue).** A non-zero exit whose message names a marker/anchor problem; never soft-skip it.
 
-   (c) **`methodology engine not found/invalid …` — a hard STOP (do NOT continue).** A fill was needed but the installed `agent-workflow-engine` (the live source of the fragment) is **absent/invalid**. Report it in plain language with the one-line install command `npx @sabaiway/agent-workflow-engine@latest init` (or note that `npx @sabaiway/agent-workflow-kit@latest init` installs the engine for you), then re-run upgrade once it is present. **Never** treat (c) as the cap soft-skip (a) — its message is distinct, and mis-handling it as a soft-skip would silently drop the slot (a no-silent-failures violation). (b) and (c) STOP the upgrade; only (a) continues.
+   (c) **`methodology engine not found/invalid …` — a hard STOP (do NOT continue).** A fill was needed but the installed `agent-workflow-engine` is **fully absent/invalid** — it can supply **neither** fragment (distinct from (a)(ii), where the engine is valid but merely too old for the recipes one). Report it in plain language with the one-line install command `npx @sabaiway/agent-workflow-engine@latest init` (or note that `npx @sabaiway/agent-workflow-kit@latest init` installs the engine for you), then re-run upgrade once it is present. **Never** treat (c) as a soft-skip (a) — mis-handling it would silently drop the methodology pointer (a no-silent-failures violation). (b) and (c) STOP the upgrade; only (a) continues.
 
-   **No-Node project:** the fragment lives only in the **installed `agent-workflow-engine`** (`references/methodology-slot.md`, under `~/.claude/skills/agent-workflow-engine` or `$AGENT_WORKFLOW_ENGINE_DIR`) — there is no bundled copy. A No-Node host also cannot run the `npx` engine install. Open `AGENTS.md` and classify the slot by hand: a **filled / customized** slot → leave it verbatim (no-op, no engine needed); a **malformed** slot (not exactly one ordered `start → end` pair) → STOP, do not edit. A slot that needs filling — **absent markers OR a present-but-empty pair** — needs the engine's fragment, so: if the engine is **not installed**, the pointer **cannot be added** — report that plainly (mirroring the Node STOP: the methodology is already in `docs/ai/agent_rules.md`; install the engine to add the pointer). If the engine **is** present, **count the lines first** — if adding/filling the pair with that fragment would take the file over 100 lines, **skip it and report the skip** (as above — trim to add the pointer). Otherwise: when markers are absent, paste the pair right after the *Read it before any code change.* line; then fill the empty pair from the engine's `references/methodology-slot.md` (never inline a copy — that would re-create the retired mirror).
+   **No-Node project:** the fragments live only in the **installed `agent-workflow-engine`** (`references/methodology-slot.md` + `references/orchestration-slot.md`, under `~/.claude/skills/agent-workflow-engine` or `$AGENT_WORKFLOW_ENGINE_DIR`) — there is no bundled copy, and a No-Node host cannot run the `npx` engine install. Open `AGENTS.md` and classify **each** pointer by hand: a **filled / customized** pair → leave it verbatim (no engine needed); a **malformed** pair (not exactly one ordered `start → end`) → STOP, do not edit. A pair that needs filling — **absent markers OR a present-but-empty pair** — needs the engine's fragment, so: if the engine is **not installed**, that pointer **cannot be added** — report it plainly (the methodology is already in `docs/ai/agent_rules.md`; the recipes are available via `/agent-workflow-kit recipes`; install the engine to add the pointers). If the engine **is** present, **count the lines first** — if adding/filling would take the file over 100 lines, **skip that pointer and report the skip** (methodology first, then orchestration; the orchestration pair sits right under the methodology end marker). Fill each empty pair from its engine fragment (`methodology-slot.md` / `orchestration-slot.md`) — never inline a copy (that would re-create the retired mirror).
 
    **Hidden-mode footprint reconcile — stamp-independent, same gate, BEFORE the equal-head short-circuit (D9 / AD-014).** A deployment does not record whether it chose `hidden`, so first **infer visibility**: `node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --reconcile --dry-run` (writes **zero bytes**). It reports one of — **visible** (the entry point is tracked) → nothing to do; **ambiguous** (untracked but not ignored — could be a fresh uncommitted repo, or a hide that broke) → **ASK** the user which it is, never guess; **hidden** → re-run without `--dry-run` to migrate any older **machine-global** hide to the **project-local** `.git/info/exclude` (one managed block; folds in the legacy `.claude/skills/` line), idempotently (a clean re-run is zero-diff). Handle its surfaced paths exactly as bootstrap step 9 (already-committed → show `git rm --cached`, ask before `--include`; generic-name present file → ask; **leftover machine-wide ignore block → ASK before `--remove-global`**, default keep + report). No Node on the agent host / Windows → as step 9. This runs on **every** hidden upgrade, like the methodology slot — no lineage-head bump, no migration file.
+
+   **Orchestration config ensure — stamp-independent, same gate, BEFORE the equal-head short-circuit.** Ensure `docs/ai/orchestration.json` exists: **create it if missing**, **preserve it byte-for-byte if it already exists** (a user may have edited it — never clobber it). In the **delegated** path memory does this from its own template (memory upgrade step 2); in the **fallback** path the kit seeds it from `${CLAUDE_SKILL_DIR}/references/templates/orchestration.json`. Like the pointer slots + the footprint reconcile, this lets an equal-head (`1.3.0`) deployment gain the config seed **without a lineage-head bump or a migration file** (it is a `.json`, inherently outside the docs cap-validator). Report it in the step 4 / step 8 success report (config *seeded* vs *already present*).
 4. **Equal-head exit — a real successful-exit report, not a bare stop.** If the stamp **equals** the head, the lineage is up to date — but step 3 (the methodology-slot **and** hidden-mode footprint reconciles) ran first and may have changed things, so this is a proper exit report, not a no-op:
-   - **Report step 3's outcome in plain language** — the workflow-methodology pointer was *added*, was *already present* (nothing changed), or was *skipped because the entry point is over its line limit* (the cap-refusal soft-skip from step 3, with its reason); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (Gotcha: never leak kit internals).
+   - **Report step 3's outcome in plain language** — for **each** pointer (workflow-methodology and orchestration-recipes) whether it was *added*, was *already present* (nothing changed), or was *skipped because the entry point is over its line limit* (the cap-refusal soft-skip from step 3, with its reason); whether the `docs/ai/orchestration.json` config was *seeded* or was *already present* (a user edit is preserved); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (Gotcha: never leak kit internals).
    - **Print the one-line backend-status line** — the shared contract above (run `node ${CLAUDE_SKILL_DIR}/tools/detect-backends.mjs`; same format, invariants, and detector-unavailable skip-with-reason).
    - **Then ask before committing — never auto-commit.** If step 3 added the slot (or anything else changed), report it and ask. If step 3 was a pure zero-diff no-op and nothing else changed, say **"already up to date"** and still print the read-only backend line.
 5. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
@@ -248,6 +266,42 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/family-registry.mjs [--dir <project>]` and p
 
 State plainly that the two version axes stay decoupled (an installed *skill* version is not a project's deployment-lineage stamp — see *Version status & the two axes*). The installed version reflects whatever is on disk under `~/.claude/skills/…`; a stale install shows its real (older) version, honestly.
 
+### Mode: recipes
+
+Read-only **orchestration advisor**. Answers *"how should I compose the optional execution-backends into plan → execute → review here, and which recipe fits?"* It **never writes, never commits, never runs a subscription CLI, and never executes a recipe** — the orchestrator (you) runs the chosen recipe through the bridge skills and makes the single commit; a backend is advisory or delegated, never autonomous.
+
+The four recipes (defined over each bridge's `provides` roles — `codex`: execute + review; `agy`: review + probe), canonical narrative in the **installed engine** (`references/orchestration.md`):
+
+- **Solo** — you plan, execute, and self-review; no backend (always available; the floor).
+- **Reviewed** — you execute; **one** backend reviews the result (advisory). Prefers `codex` when both are ready (`agy` carries a standing health caveat).
+- **Council** — **both** backends review independently; you synthesize the two opinions.
+- **Delegated** — you hand a **bounded** execution sub-task to a backend (`codex exec`), then review the returned diff and commit.
+
+1. Run **`node ${CLAUDE_SKILL_DIR}/tools/recipes.mjs`** (the read-only planner; `--json` for the structured form). It runs the backend detector, lists the four recipes, and prints — for the current environment — a **per-recipe dispatch plan that degrades with a stated reason** when a backend isn't `ready` (Council → Reviewed → Solo; Delegated → Solo), plus advisory **quota/health notes** (prefer the cheapest model; Council spends two backends' quota; `agy` may stall on substantive prompts — Issue-001, prefer `codex`).
+2. **Offer the choice** via **`AskUserQuestion` where your agent supports it** (`AskUserQuestion` in Claude Code) — one option per recipe, the `recommendRecipe` choice listed **first** — otherwise in prose. Then print `planRecipe(chosen, detection)` (the per-stage dispatch + degradation reasons + quota/health notes) so the user sees exactly what running it entails.
+3. **Availability = `readiness === ready`, full stop.** Every other readiness supplies the human reason (needs-skill → "not installed — `/agent-workflow-kit setup`"; needs-cli → "install the CLI"; needs-credentials → "log in"; degraded → "wrapper not on PATH — `/agent-workflow-kit setup`"). This is set-up state only — **never** a claim that a backend's service is responsive (the detector cannot observe a runtime stall; `agy`'s Issue-001 is a *standing advisory*, not a readiness signal).
+
+**Invariants:** read-only · never runs a subscription CLI · never commits · the orchestrator executes the recipe via the bridge skills, not the kit.
+
+### Mode: procedures
+
+Read-only **activity-procedures advisor**. Answers *"what are the steps of this named activity, and which recipe applies at each slot here?"* It composes the orchestration recipes (Mode: recipes) into **named activities** with **typed recipe slots**. It **never writes, never commits, never runs a subscription CLI** — the deterministic resolution lives in the kit; the orchestrator runs the resolved recipe via the bridge skills and **owns any commit when the activity has a commit boundary** (a backend never commits). Not every activity commits: `plan-authoring` ends at approval and produces no commit (plans are ephemeral, never committed); `plan-execution` commits per Step.
+
+The two v1 activities (canon in the **installed engine**, `references/procedures.md`):
+
+- **`plan-authoring`** (slot: `review`) — research → draft → self-review → **review {recipe}** → fold/loop → present for approval; enforce the mandatory Cleanup.
+- **`plan-execution`** (slots: `execute`, `review`) — per Step: resolve the recipe → if Delegated, dispatch execution first → implement → self-review → **review {recipe}** → gates → commit boundary.
+
+Run **`node ${CLAUDE_SKILL_DIR}/tools/procedures.mjs <activity> [--override <slot>=<recipe>]… [--json]`**. It reads the activity's steps live from the engine and prints them **verbatim**, then the **resolved effective recipe per slot** from the per-project config + the read-only backend detector:
+
+1. **Config = `docs/ai/orchestration.json`** — strict JSON, **hand-edited** (the kit reads + validates it; `recipes` stays read-only — there is no writer). Shape: `{ "<activity>": { "<slot>": "<recipe>" } }`; all slots optional (an absent slot → its computed default, stated); an optional `"_README"` string is allowed + ignored. `review` accepts `solo|reviewed|council`; `execute` accepts `solo|delegated`. Seeded by `init` (a user-editable template) — see *Mode: bootstrap*.
+2. **Default resolution (config silent):** `review` → Reviewed if any review-capable backend is `ready`, else Solo (never Council by default); `execute` → Solo (Delegated is opt-in). **Degradation:** a config/computed default degrades **gracefully with a stated reason** (Council → Reviewed → Solo; Delegated → Solo); a per-run **`--override <slot>=<recipe>`** that can't be satisfied degrades **loudly** (a flagged warning, so you tell the user) — but is **still exit 0** (a valid request that gracefully degraded).
+3. **Exit codes:** `0` success; `2` usage (unknown `<activity>` / bad `--override` — a bare `--override <recipe>`, an unknown slot, an invalid recipe-for-slot, or a duplicate slot); `1` config error (malformed / schema-invalid / unreadable `orchestration.json`) **or** engine error (the installed engine is absent / invalid / **too old** to ship `references/procedures.md` — upgrade it with `npx @sabaiway/agent-workflow-engine@latest init`). A `1`/`2` failure is loud (`path: reason`), never a silent fallback.
+
+**Cap-soft-skip degradation (the feature's only AUTO route).** The activity procedures are auto-discoverable only through the one-line **`workflow:methodology`** pointer (this kit + the engine carry `disable-model-invocation:true`, so NL like "write a plan" does **not** auto-load this skill). On a deployment whose methodology pointer was cap-soft-skipped — or whose pre-existing customized pointer lacks the procedures clause — the procedures are still reachable by **explicitly** invoking `/agent-workflow-kit procedures`; surface that plainly rather than treating it as a gap.
+
+**Invariants:** read-only · never writes · never commits · never runs a subscription CLI · the deterministic resolution is the kit's, the recipe execution is the orchestrator's.
+
 ### Mode: uninstall
 
 The **guarded teardown** — the inverse of `init` (the kit + engine skills) + `setup` (the bridges) + a hidden deploy. **In-agent, opt-in**, and built around one hard rule: **it never deletes user-authored content.** Run **`--dry-run` first, always**, show the user the classified plan in plain language, get explicit consent, then re-run with `--yes`. It **never commits**.
@@ -307,6 +361,7 @@ The three setup choices — **visibility** (step 2), **conversational language**
 10. **Honest `known_issues.md`.** Every bug with a workaround gets Impact + Plan so it isn't re-discovered later.
 11. **One conversational language.** Talk to the user in the language chosen at bootstrap; keep code, paths, commands, and abbreviations in their source language. See *Communication contract*.
 12. **Attribution is opt-in.** Honour the *Attribution* block: by default no agent/AI/model mention anywhere (commits, PRs, code, comments, docs), and no `Co-Authored-By` trailer. See *Attribution contract*.
+13. **Orchestrate via a named recipe.** Compose execution through a named recipe (Solo / Reviewed / Council / Delegated) and **always commit yourself** — backends are advisory or delegated, never autonomous. Encoded via the reconciled `workflow:orchestration` pointer (it routes to `/agent-workflow-kit recipes` + the engine canon), not by bloating the entry point.
 
 ---
 
@@ -335,10 +390,10 @@ Deploy these into `AGENTS.md`; remove rows that don't apply to the stack.
 
 - [`references/contracts.md`](references/contracts.md) — the three setup contracts (visibility, conversational language, agent attribution) in full; the *Setup contracts* section above points here.
 - **Plan vocabulary** (Plan→Phase→Step→Substep), lifecycle, `queue.md` series-index, mandatory Cleanup, session-continuity heuristic — the single home is the **installed `agent-workflow-engine`** canon (`~/.claude/skills/agent-workflow-engine/references/planning.md`, or `$AGENT_WORKFLOW_ENGINE_DIR`); there is no bundled mirror. `npx @sabaiway/agent-workflow-kit@latest init` installs the engine.
-- [`references/templates/`](references/templates/) — stack-agnostic `AGENTS.md`, `agent_rules.md`, and all `docs/ai/` files to deploy.
+- [`references/templates/`](references/templates/) — stack-agnostic `AGENTS.md`, `agent_rules.md`, the seeded user-editable `orchestration.json` config (byte-identical to the memory copy — `test/template-parity.test.mjs`), and all `docs/ai/` files to deploy.
 - [`references/scripts/`](references/scripts/) — the Node enforcement scripts (caps + staleness + index-freshness gate, 3-tier archive, hook installer) and their unit tests.
 - [`migrations/`](migrations/) — per-version upgrade steps; see `migrations/README.md`.
 - [`launchers/`](launchers/) — run the bootstrapper from non-Claude agents (`SKILL.md` is a native Codex skill; a Devin Desktop workflow launcher + install script). See `launchers/README.md`.
-- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `engine-source.mjs` (the bounded slot reconciliation — ensure-slot / inject-if-empty / cap; the fragment is read **live** from the installed `agent-workflow-engine` via `engine-source.mjs` — the family's one source of truth, no bundled mirror; fail-loud when the engine is needed but absent), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`, plus the axis-aware `guideFor`), `setup-backends.mjs` (the **link-only** backend setup behind `/agent-workflow-kit setup` — place the bundled bridge + link wrappers), `fs-safe.mjs` (the shared symlink-traversal-safe copy/link/**remove/unlink** primitives that `setup-backends`, the npx installer, and the uninstaller use), `known-footprint.mjs` + `hide-footprint.mjs` (the **hidden-mode** registry + the single hide-writer behind step 9 / the upgrade reconcile — one managed block in the **project-local** `.git/info/exclude` covering the full AI/agent footprint; pinned by `known-footprint.test.mjs` drift-guard + `hide-footprint.test.mjs` / `.integration.test.mjs`), `family-registry.mjs` (the **unified family registry** behind `/agent-workflow-kit status` — aggregates every member's `capability.json`; pinned by a `family-registry.test.mjs` drift-guard), `uninstall.mjs` (the **guarded teardown** behind `/agent-workflow-kit uninstall` — classify each surface, preflight-then-mutate, never delete user-authored content), and `release-scan.mjs` (the attribution-off release gate). The bundled bridge skill mirrors live under [`bridges/`](bridges/) (byte-identical to the repo-root bridges, pinned by `test/bridges-mirror.test.mjs`). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
+- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `engine-source.mjs` (the bounded **two-slot** reconciliation — ensure-slot / inject-if-empty / cap for the `workflow:methodology` **and** `workflow:orchestration` pointers; both fragments read **live** from the installed `agent-workflow-engine` via `engine-source.mjs` (`deps.rel` selects which) — the family's one source of truth, no bundled mirror; fail-loud when the engine is needed but absent, orchestration soft-skipped when it would bust the cap), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`, plus the axis-aware `guideFor`; exports the readiness consts the planner reuses), `recipes.mjs` (the read-only **recipe planner** behind `/agent-workflow-kit recipes` — `RECIPES` / `planRecipe` / `recommendRecipe` over the bridges' role vocabulary, drift-guarded against `provides`/`cost`/`quota` + an engine↔kit recipe-name parity guard; pure, never runs a subscription CLI; also exports the pure `ACTIVITIES` / `resolveActivityRecipe` activity-procedures resolver), `procedures.mjs` (the read-only **activity-procedures advisor** behind `/agent-workflow-kit procedures` — reads `references/procedures.md` live from the engine via `engine-source.mjs`, reads + validates the hand-edited `docs/ai/orchestration.json`, and prints the steps + the resolved effective recipe per slot; drift-guarded activity/slot table vs the canon; read-only, never runs a subscription CLI), `setup-backends.mjs` (the **link-only** backend setup behind `/agent-workflow-kit setup` — place the bundled bridge + link wrappers), `fs-safe.mjs` (the shared symlink-traversal-safe copy/link/**remove/unlink** primitives that `setup-backends`, the npx installer, and the uninstaller use), `known-footprint.mjs` + `hide-footprint.mjs` (the **hidden-mode** registry + the single hide-writer behind step 9 / the upgrade reconcile — one managed block in the **project-local** `.git/info/exclude` covering the full AI/agent footprint; pinned by `known-footprint.test.mjs` drift-guard + `hide-footprint.test.mjs` / `.integration.test.mjs`), `family-registry.mjs` (the **unified family registry** behind `/agent-workflow-kit status` — aggregates every member's `capability.json`; pinned by a `family-registry.test.mjs` drift-guard), `uninstall.mjs` (the **guarded teardown** behind `/agent-workflow-kit uninstall` — classify each surface, preflight-then-mutate, never delete user-authored content), and `release-scan.mjs` (the attribution-off release gate). The bundled bridge skill mirrors live under [`bridges/`](bridges/) (byte-identical to the repo-root bridges, pinned by `test/bridges-mirror.test.mjs`). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
 - [`capability.json`](capability.json) — the kit's own `agent-workflow` family manifest (`kind: composition-root`).
 - [`CHANGELOG.md`](CHANGELOG.md) — version history of this kernel.

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/scripts/check-docs-size.mjs

@@ -139,7 +139,10 @@ export const parseStaleAfter = (value) => {
   return Number(m[1]);
 };
 
-const walkMarkdownFiles = async (dir) => {
+// Discover the docs to validate: ONLY `*.md` files (recursively). Non-`.md` files — e.g. a hand-edited
+// `docs/ai/orchestration.json` config — are inherently skipped, so they are never subject to the
+// frontmatter / maxLines caps. Exported so that skip is pinned by a regression test.
+export const walkMarkdownFiles = async (dir) => {
   const entries = await readdir(dir, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {

package/references/scripts/check-docs-size.test.mjs

@@ -10,6 +10,7 @@ import {
   inspectFile,
   buildIndex,
   checkIndexFreshness,
+  walkMarkdownFiles,
 } from './check-docs-size.mjs';
 
 describe('parseFrontmatter', () => {
@@ -126,6 +127,29 @@ describe('inspectFile', () => {
   });
 });
 
+// The cap-validator discovers ONLY `*.md` files, so a non-`.md` doc — e.g. a hand-edited
+// `docs/ai/orchestration.json` config — is inherently skipped: never validated for frontmatter / caps.
+// This belt-and-suspenders regression pins that skip so adding a config `.json` under docs/ai can never
+// start failing the docs gate.
+describe('walkMarkdownFiles — only *.md is discovered (a config .json is skipped)', () => {
+  let dir;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'walk-md-test-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('returns the .md file and NOT a sibling orchestration.json', async () => {
+    await writeFile(join(dir, 'doc.md'), '---\ntype: reference\nmaxLines: 100\n---\n\nbody.\n');
+    await writeFile(join(dir, 'orchestration.json'), '{ "plan-authoring": { "review": "reviewed" } }\n');
+    const found = await walkMarkdownFiles(dir);
+    expect(found.some((f) => f.endsWith('doc.md'))).toBe(true);
+    expect(found.some((f) => f.endsWith('.json'))).toBe(false);
+    expect(found.some((f) => f.endsWith('orchestration.json'))).toBe(false);
+  });
+});
+
 // Synthetic row matching the shape produced by `inspectFile` + `formatRow`.
 const makeRow = (path, overrides = {}) => ({
   path,

package/references/templates/AGENTS.md

@@ -55,19 +55,18 @@ Start-of-session, during-work, and task-completion procedures live in [`docs/ai/
 
 <!-- workflow:methodology:start -->
 <!-- workflow:methodology:end -->
+<!-- workflow:orchestration:start -->
+<!-- workflow:orchestration:end -->
 
 ---
 
 ## 🚫 Hard Constraints
 
-> Adapt to this stack — remove rows that don't apply. Style rules should be linter-enforced, not prose.
-
 | Rule | Enforcement |
 |------|-------------|
 | No `export default` (named exports only) | Linter |
 | No `any` / no unsafe casts | Linter / type-checker |
 | Functional style (no mutation in app code) | Linter |
-| No single-letter variables | Code review |
 | Interactive elements semantic (button/link, not div+onClick) | Linter / a11y |
 | No hardcoded colors — design tokens only | Code review |
 | No business logic in components → hooks/services | Architecture review |

package/references/templates/orchestration.json

@@ -0,0 +1,5 @@
+{
+  "_README": "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Hand-edit this file — it is never written for you. Each activity is configured independently (e.g. plan-authoring, plan-execution), and so is each slot within it. A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an 'execute' slot accepts solo | delegated (you implement / a backend runs a bounded sub-task). The default below is 'solo' everywhere — no execution backend required. Raise a slot to reviewed or council for a second opinion, or to delegated to hand off execution; those need an execution backend set up first. Remove a slot's line to fall back to the computed default (reviewed when a review backend is ready, otherwise solo). Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your environment, and pass a per-run override to change one slot just once. Strict JSON — no comments.",
+  "plan-authoring": { "review": "solo" },
+  "plan-execution": { "execute": "solo", "review": "solo" }
+}

package/tools/detect-backends.mjs

@@ -38,12 +38,13 @@ const STUB = 'stub';
 const FOREIGN = 'foreign';
 const OK = 'ok';
 
-// readiness values.
-const READY = 'ready';
-const NEEDS_SKILL = 'needs-skill';
-const NEEDS_CLI = 'needs-cli';
-const NEEDS_CREDENTIALS = 'needs-credentials';
-const DEGRADED = 'degraded';
+// readiness values. Exported so the recipe planner (tools/recipes.mjs) maps backend availability off
+// the SAME consts the detector emits — no magic readiness literals duplicated across the two modules.
+export const READY = 'ready';
+export const NEEDS_SKILL = 'needs-skill';
+export const NEEDS_CLI = 'needs-cli';
+export const NEEDS_CREDENTIALS = 'needs-credentials';
+export const DEGRADED = 'degraded';
 
 const EXPECTED_KIND = 'execution-backend';
 

package/tools/engine-source.mjs

@@ -22,6 +22,15 @@ import { validateManifest, VALID } from './manifest/validate.mjs';
 export const ENGINE_ENV = 'AGENT_WORKFLOW_ENGINE_DIR';
 export const EXPECTED_ENGINE_NAME = 'agent-workflow-engine';
 export const ENGINE_FRAGMENT_REL = 'references/methodology-slot.md';
+// The orchestration-recipes slot fragment — a SECOND bounded fragment the kit injects (Plan 4). An
+// engine older than 1.2.0 does not ship it; detectEngine({ rel }) lets a caller verify the specific
+// fragment so `status` can caveat a too-old engine instead of failing the methodology read.
+export const ORCHESTRATION_FRAGMENT_REL = 'references/orchestration-slot.md';
+// The activity-procedures canon — a NEW live-read engine fragment (engine >= 1.3.0). The procedures
+// CLI reads it via readEngineFragment({ rel }); detectEngine({ rel }) lets `status` caveat — and the
+// CLI fail loudly on — an engine too old to ship it. readEngineFragment accepts an arbitrary `rel`
+// (no whitelist), so no further plumbing is needed beyond this constant.
+export const PROCEDURES_FRAGMENT_REL = 'references/procedures.md';
 const ENGINE_DEFAULT_REL = '.claude/skills/agent-workflow-engine';
 
 const defaultStatType = (path) => {
@@ -47,9 +56,10 @@ export const resolveEngineDir = ({ env = {}, home = '' } = {}) => {
 // (never a candidate-shipped one), and clones detectMemory's reason ladder so each failure has a
 // distinct, actionable reason. ok only on: a dir that exists + VALID manifest + kind
 // methodology-engine + the right name + available + the live fragment file present.
-export const detectEngine = (engineDir, { source } = {}, deps = {}) => {
+export const detectEngine = (engineDir, { source, rel } = {}, deps = {}) => {
   const validate = deps.validate ?? validateManifest;
   const statType = deps.statType ?? defaultStatType;
+  const fragmentRel = rel ?? ENGINE_FRAGMENT_REL;
 
   // The dir itself must exist first — this is what lets an env-pointed-but-absent dir read as the
   // distinct `env-set-but-missing` (validateManifest would only say "capability.json not found").
@@ -72,7 +82,7 @@ export const detectEngine = (engineDir, { source } = {}, deps = {}) => {
       return { result: 'invalid', errors: [`validator threw: ${err?.message ?? err}`] };
     }
   })();
-  const fragmentPresent = statType(join(engineDir, ENGINE_FRAGMENT_REL)) === 'file';
+  const fragmentPresent = statType(join(engineDir, fragmentRel)) === 'file';
   const ok =
     report.result === VALID &&
     report.kind === 'methodology-engine' &&
@@ -89,7 +99,7 @@ export const detectEngine = (engineDir, { source } = {}, deps = {}) => {
           ? `engine manifest name "${report.name}" is not "${EXPECTED_ENGINE_NAME}"`
           : report.available === false
             ? 'engine manifest is a declared stub (available:false)'
-            : `engine fragment missing (${ENGINE_FRAGMENT_REL})`;
+            : `engine fragment missing (${fragmentRel})`;
   return { ok, reason, dir: engineDir };
 };
 
@@ -99,14 +109,14 @@ export const detectEngine = (engineDir, { source } = {}, deps = {}) => {
 // not found/invalid" prefix is a stable contract: the agent classifies the reconcile STOP by it
 // (distinct from the cap-skip message), so do not reword it without updating SKILL.md.
 export const readEngineFragment = (engineDir, deps = {}) => {
-  const detection = detectEngine(engineDir, { source: deps.source }, deps);
+  const detection = detectEngine(engineDir, { source: deps.source, rel: deps.rel }, deps);
   const installHint = `npx @sabaiway/agent-workflow-engine@latest init  (or set ${ENGINE_ENV})`;
   if (!detection.ok) {
     throw new Error(`methodology engine not found/invalid at ${engineDir} (${detection.reason}) — install it: ${installHint}`);
   }
   const read = deps.readFileSync ?? readFileSync;
   try {
-    return read(join(engineDir, ENGINE_FRAGMENT_REL), 'utf8');
+    return read(join(engineDir, deps.rel ?? ENGINE_FRAGMENT_REL), 'utf8');
   } catch (err) {
     throw new Error(
       `methodology engine not found/invalid at ${engineDir} (fragment unreadable: ${err.message}) — install it: ${installHint}`,