@sabaiway/agent-workflow-kit 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,75 @@ 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.5.0 — Backend detection (detect + guide)
+
+The kit's onboarding can now **see the optional execution-backends** — the thin bridges to
+subscription CLIs (`codex-cli-bridge` → `codex`, `antigravity-cli-bridge` → `agy`) — instead of
+being blind to everything but the memory substrate. **Additive and read-only**: no `capability.json`
+schema change, no validator change, no auto-install. Since nothing in the deployed `docs/ai/`
+structure changes, **no migration is needed** and the deployment-lineage head stays `1.3.0`
+(`upgrade` reconciles and re-stamps with nothing to apply).
+
+- **`tools/detect-backends.mjs` — the read-only detector.** Pure, dependency-injectable,
+  dependency-free (Node ≥ 18), and already shipped (it lives under `tools/`, which is in the
+  package `files` + the installer `PAYLOAD`). It reports two **decoupled** axes so a healthy
+  manifest is never confused with a usable backend: `manifestState` (health of the bridge *skill*:
+  `not-installed | unsupported-schema | invalid-manifest | foreign | stub | ok`) and the readiness
+  signals `cli` / `credentials` / `wrappers`, probed **independently** for every registry entry even
+  when the skill is absent — so "the `codex` CLI is installed and signed in, but the bridge skill
+  isn't" reads as `needs-skill`, with the setup pointer. Every fs probe is wrapped → an explicit
+  `unknown` + reason, never a throw and never a nameless failure.
+- **Detection is read-only — it never runs a subscription CLI.** "credentials present/missing" is
+  the existence of the credential-marker **file**, never a live `codex login status` / `agy` check
+  (which would spawn a paid, slow, networked CLI). The report deliberately never says
+  "authenticated" (a unit test asserts the word's absence).
+- **Kit-owned registry (`KNOWN_BACKENDS`), not a schema change.** A missing bridge has no manifest
+  on disk and no `setup/README.md` in the kit tarball, so the per-backend facts (`bin`, credential
+  marker, stable setup URL) must live in the detector. A **drift-guard** test keeps the registry in
+  lockstep with the in-repo manifests (set equality with every `kind:execution-backend` dir, unique
+  names, `detect.installed` match, `setup/README.md` exists).
+- **Two surfaces.** A new **`/agent-workflow-kit backends`** mode presents the table and, for any
+  backend that is not `ready`, points to its setup (local `setup/README.md` when installed, else the
+  setup URL). Bootstrap **step 11** also prints a one-line backends summary — read-only, and it
+  **never blocks the commit gate**. Honest about Windows: detection works, but the bridges' POSIX
+  `.sh` wrappers are not promised to run there.
+
+## 1.4.0 — Delegation-aware composition root (agent-workflow family, Plan 1)
+
+The kit becomes the **composition root** of the new `agent-workflow` family. **Additive** — the
+kit keeps its entire bundled substrate as a fallback, so the existing one-command install is
+unchanged and **no migration is needed** (`upgrade` reconciles and re-stamps; the deployment
+lineage head stays `1.3.0`). Published from the new `agent-workflow` monorepo.
+
+- **Memory extracted to `@sabaiway/agent-workflow-memory`** — the memory substrate (`docs/ai/`,
+  the entry point, caps / archive / index, the three setup contracts) now also ships as its own
+  package. The kit **delegates** substrate deployment to it when a **kit-owned detector** finds it
+  valid, and otherwise uses its own bundled copy. Detection runs the kit's **own shipped**
+  `tools/manifest/validate.mjs` (never a validator shipped by the candidate) and requires
+  `kind: memory-substrate` **valid** plus all required assets present; unsupported / invalid /
+  unavailable / wrong-family / wrong-name → bundled fallback. The fallback decision is made
+  **before** any project write.
+- **Family manifest contract** — every member ships a `capability.json` (`schema 1`, JSON,
+  dependency-free). The kit **owns and ships** the schema + validator at `tools/manifest/`
+  (in the tarball + installer `PAYLOAD`, so an installed kit can run the detector; root CI invokes
+  the same file). The kit's own manifest is `kind: composition-root`.
+- **Methodology slot injection** — memory ships an **empty** delimited `workflow:methodology` slot
+  in `AGENTS.md`; the kit is its **only** writer, injecting a **bounded** summary + pointer
+  (`tools/inject-methodology.mjs` + `tools/methodology-slot.md`) that keeps `AGENTS.md` under its
+  ≤100-line cap. Marker contract: exactly one ordered pair → replace between; absent → no-op;
+  malformed → no-op with an error.
+- **Two-stamp delegation hand-off** — delegated mode: memory writes `.memory-version`, the kit
+  injects + writes the fallback `.workflow-version` (→ both stamps); fallback mode: `.workflow-version`
+  only. Exactly **one** composition-level commit gate, owned by the kit, after injection. The
+  decision + hand-off matrix is codified and unit-tested in `tools/delegation.mjs`
+  (`detectMemory` + `handoffPlan`), so it does not depend on agent interpretation.
+- **Release gate — attribution-off** — `tools/release-scan.mjs` fails on AI/reviewer attribution
+  (co-author trailers, "Generated with <AI>" footers) anywhere in the release tree, so no agent
+  attribution can ship by accident.
+- **Hardened installer** — `copyRecursive` never writes *through* a destination symlink
+  (root / intermediate / leaf). `capability.json` + `tools/` added to `files` and the installer
+  `PAYLOAD`. `repository`/`homepage`/`bugs` repointed to the `agent-workflow` monorepo.
+
 ## 1.3.0 — Skill authoring aligned with Anthropic's Skills guidance
 
 Internal refinements to how the kernel itself is written — no change to what gets deployed into a
@@ -33,7 +102,7 @@ to apply). Drawn from [*Lessons from building Claude Code: how we use Skills*](h
 **Conversational language (dialogue only)**
 
 - **Bootstrap now asks the conversational language** — a new step 3 in `/agent-workflow-kit`, alongside the visibility question. The agent records the answer in a new *Communication language* block in the project's `AGENTS.md`, so every agent that reads the entry point talks to the user in that language and stops drifting between languages mid-session.
-- **Dialogue-only scope, by design** — the choice governs what the agent writes *for the user to read* (questions, explanations, summaries, status). Code, identifiers, file paths, shell commands, log output, and abbreviations stay in their source language; the deployed `docs/ai/` files and `AGENTS.md` stay English (the kernel stays English-only for cross-agent / cross-team portability). See the *Communication contract* in `SKILL.md`.
+- **Dialogue-only scope, by design** — the choice governs what the agent writes *for the user to read* (questions, explanations, summaries, status). Code, identifiers, file paths, shell commands, log output, and abbreviations stay in their source language; the deployed `docs/ai/` files and `AGENTS.md` are not translated either (the conversational choice governs the chat, not the artifacts). See the *Communication contract* in `SKILL.md`.
 - **Existing deployments are covered** — `/agent-workflow-kit upgrade` backfills the block on a pre-1.1.0 project, asking the user their language. See `migrations/1.1.0-communication-language.md` (idempotent, additive).
 
 **Clearer install / upgrade guidance**

package/README.md

@@ -12,7 +12,7 @@ instead of re-reading your whole repo.*
 [![license](https://img.shields.io/npm/l/@sabaiway/agent-workflow-kit)](./LICENSE)
 [![node](https://img.shields.io/node/v/@sabaiway/agent-workflow-kit)](https://nodejs.org)
 
-`v1.3.0`  ·  `Node ≥ 18`  ·  `kernel-only · English`
+`v1.4.0`  ·  `Node ≥ 18`  ·  `kernel-only`
 
 **Works with any tool that reads `AGENTS.md`** — Claude Code · Codex · Cursor · Devin Desktop (formerly Windsurf) · GitHub Copilot · Gemini CLI · Cline · Aider · and 20+ more.
 
@@ -121,6 +121,12 @@ Then invoke it **inside a project** — first time vs. already-deployed use diff
 
 <sub>`/agent-workflow-kit` bootstraps a fresh deployment (and asks your **visibility**, **conversational language**, and whether the agent may **attribute work to itself / AI** — default off); `/agent-workflow-kit upgrade` migrates an existing one to the kit's current version. The `npx … init` above is a third, separate thing — it updates the **kit itself**, not any project.</sub>
 
+> **New in 1.4.0 — optional memory substrate.** The memory layer is now also published
+> standalone as [`@sabaiway/agent-workflow-memory`](https://www.npmjs.com/package/@sabaiway/agent-workflow-memory).
+> If it is installed, the kit **delegates** substrate deployment to it and injects the workflow
+> methodology; if not, the kit uses its **own bundled copy** — the one command above keeps
+> working with no new dependency. Same `docs/ai/` either way.
+
 **Upgrade the kit itself** later — same command with `@latest`:
 
 ```bash
@@ -132,11 +138,12 @@ npx @sabaiway/agent-workflow-kit@latest init
 <details>
 <summary><b>Manual install</b> — no <code>npx</code></summary>
 
-The kit is a single self-contained folder. Clone it into a skill scope yourself, then run the launcher:
+The kit is a single self-contained folder inside the `agent-workflow` monorepo. Clone the repo
+and copy the kit into a skill scope yourself, then run the launcher:
 
 ```bash
-git clone https://github.com/sabaiway/agent-workflow-kit \
-  ~/.claude/skills/agent-workflow-kit
+git clone https://github.com/sabaiway/agent-workflow
+cp -r agent-workflow/agent-workflow-kit ~/.claude/skills/agent-workflow-kit
 cd ~/.claude/skills/agent-workflow-kit
 bash launchers/install-launchers.sh
 ```
@@ -174,6 +181,7 @@ command is printed).
 |---------|------|--------------|
 | `/agent-workflow-kit` | new / empty project | recon → **asks visible-or-hidden** + **conversational language** + **agent attribution** (default off) → deploys `AGENTS.md` + `docs/ai/` filled with real recon data → installs enforcement → **asks before committing** |
 | `/agent-workflow-kit upgrade` | existing deployment | reads `docs/ai/.workflow-version`, shows the changelog diff, applies migrations, re-stamps |
+| `/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). |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.
 
@@ -210,11 +218,13 @@ agent-workflow-kit/
 ├── README.md        ← you are here
 ├── SKILL.md         ← agent-facing algorithm
 ├── CHANGELOG.md     ← version history
+├── capability.json  ← agent-workflow family manifest (composition-root)
 ├── references/
     ├── templates/   ← AGENTS.md + every docs/ai file
     ├── scripts/     ← caps / archive / index + tests
     ├── contracts.md ← visibility / language / attribution rules
     └── planning.md  ← plan lifecycle + continuity
+├── tools/           ← family tooling: manifest schema + validator, methodology-slot injection, backend detector (detect-backends)
 ├── launchers/       ← Codex / Devin Desktop / Cursor entries
 └── migrations/      ← per-version upgrade steps
 ```
@@ -222,5 +232,5 @@ agent-workflow-kit/
 ---
 
 <div align="center">
-<sub>Kernel-only · stack-agnostic · English · distilled from a multi-year-verified reference implementation.</sub>
+<sub>Kernel-only · stack-agnostic · distilled from a multi-year-verified reference implementation.</sub>
 </div>

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.3.0'
+  version: '1.5.0'
 ---
 
 # agent-workflow-kit
@@ -12,18 +12,73 @@ Deploys a **portable AI-agent memory-and-workflow system** into a project, and u
 
 The kernel is **stack-agnostic workflow** — `docs/ai/` structure, entry-point doc, session protocols, plan lifecycle, frontmatter caps, 3-tier archive, index-freshness gate. Enforcement ships as **Node `.mjs` scripts** (the reference implementation; non-Node stacks follow the same policy manually).
 
-The kernel **artifacts** (this skill, the templates, the deployed `docs/ai/` files) are **English-only** — for cross-agent and cross-team portability. That is separate from the **conversational language**: the language the agent *talks to the user* in (questions, explanations, summaries, status). That is chosen once at bootstrap (step 3), recorded in the project's `AGENTS.md`, and applied to dialogue only — it never translates file contents, code, identifiers, paths, commands, or abbreviations.
+The kernel **artifacts** (this skill, the templates, the deployed `docs/ai/` files) stay in their **source language** — for cross-agent and cross-team portability. That is separate from the **conversational language**: the language the agent *talks to the user* in (questions, explanations, summaries, status). That is chosen once at bootstrap (step 3), recorded in the project's `AGENTS.md`, and applied to dialogue only — it never translates file contents, code, identifiers, paths, commands, or abbreviations.
 
 This kernel is distilled from a canonical, battle-tested reference implementation. The skill is the single source of truth — projects deploy from it and upgrade against it.
 
 ---
 
-## Two modes
+## Memory substrate: delegate or fall back (composition root)
+
+This kit is the **composition root** of the `agent-workflow` family. The memory substrate
+(`docs/ai/`, the entry-point doc, caps / archive / index, the setup contracts) is owned by
+**`agent-workflow-memory`**. The kit **prefers to delegate** substrate deployment to that skill
+when it is present and healthy, and otherwise uses its **own bundled copy** (`references/`,
+`migrations/`) — so the existing one-command install keeps working with **no new dependency**.
+
+**Detection (kit-owned, decided BEFORE any project write).** Run the kit's **own shipped**
+validator — `node ${CLAUDE_SKILL_DIR}/tools/manifest/validate.mjs <memory-skill-dir>` — never a
+validator shipped by the candidate (which could itself be broken). Delegate only when **all**
+hold:
+- result is **valid** and `kind` is `memory-substrate`;
+- **every required asset is present** in the candidate, at its real path:
+  `references/templates/`, `references/contracts.md`, `references/scripts/`,
+  `scripts/stamp-takeover.mjs`, `migrations/`, `capability.json`. A partial install (manifest +
+  `SKILL.md` only) is treated as **invalid**.
+
+On **unsupported** (unknown schema), **invalid**, **unavailable**, **wrong-family**, or
+**wrong-name**, **use the bundled copy** — never block. The fallback decision is final once
+made: a partial/broken memory install discovered mid-flow must not disable the working fallback.
+
+> The **executable form** of this whole decision lives in
+> [`tools/delegation.mjs`](tools/delegation.mjs): `detectMemory(<memory-dir>)` runs the validator +
+> the required-asset check and returns `delegate` / fallback with a reason; `handoffPlan(delegate)`
+> returns who writes what, which stamps end up present, and that the commit gate is kit-only. Both
+> are unit-tested, so the contract below is pinned by code, not agent interpretation.
+
+**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` + **`.memory-version`**. The kit then **injects the bounded
+  methodology slot** (below) and writes the kit-fallback **`.workflow-version`**. → **both
+  stamps** present.
+- **Fallback** (memory absent/invalid): the kit runs the bootstrap procedure below from its own
+  bundled assets and writes **`.workflow-version`** only. Softly suggest installing
+  `agent-workflow-memory` — never a prerequisite.
+
+**Methodology injection (the kit is the ONLY writer of memory's slot).** After `AGENTS.md`
+exists, inject the bounded methodology fragment into its `workflow:methodology` slot:
+`node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs <project>/AGENTS.md`. It injects a short
+summary + pointer (Phase-1 source: the kit's bundled `tools/methodology-slot.md`) — **not** the
+full `references/planning.md` — and keeps `AGENTS.md` under its ≤100-line cap. Marker contract:
+exactly one ordered `start → end` pair → replace only the bytes between them; markers absent →
+no-op; any malformed state (single, reversed, nested, duplicate) → no-op **with an error**,
+never edit.
+
+**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**
+injection: report results and **ask before committing** — never auto-commit. No kit asset is
+ever deleted.
+
+---
+
+## Modes
 
 Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to guard against bootstrapping over a live system, but the user makes the final call.
 
 - **`/agent-workflow-kit`** (default) — bootstrap a new or empty project. If `docs/ai/` already exists, stop and ask whether they meant `upgrade`.
 - **`/agent-workflow-kit upgrade`** — upgrade an existing deployment to the skill's current `version`.
+- **`/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.
 
 ### Mode: bootstrap
 
@@ -46,8 +101,13 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 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 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.
-10. **Stamp version.** Write the skill's `version` into `docs/ai/.workflow-version` (one semver line).
-11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then **ask before committing** — never auto-commit.
+10. **Stamp the deployment lineage.** Write the **deployment-lineage head** into
+    `docs/ai/.workflow-version` (one semver line). The lineage head is **`1.3.0`** — the shared
+    `agent-workflow` deployment lineage, **NOT** this kit's package version (`1.4.0`). The two are
+    independent axes: a packaging-only release bumps the package but leaves the lineage head until a
+    migration actually changes the deployed `docs/ai` structure. A stamp greater than the head →
+    STOP (never downgrade).
+11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then run the **backend detector** (`node ${CLAUDE_SKILL_DIR}/tools/detect-backends.mjs`) and print a one-line summary of the optional execution-backends (e.g. `backends: codex ✓ ready · antigravity ✗ needs-credentials — run /agent-workflow-kit backends`). This is **read-only and never blocks the commit gate**. Then **ask before committing** — never auto-commit.
 
 Fill strategy:
 
@@ -61,12 +121,22 @@ Fill strategy:
 
 ### Mode: upgrade
 
-1. Read `docs/ai/.workflow-version` (the project's stamped version). If missing, treat as a pre-versioned deployment and offer to re-bootstrap conservatively.
-2. Compare to this skill's `metadata.version` (frontmatter). If equal → report "up to date" and stop.
+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. Compare to the **deployment-lineage head** (`1.3.0` — NOT this kit's package version). If equal → report "up to date" and stop. If the stamp is **greater than the head** or unparseable → **STOP and report** (never downgrade).
 3. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
 4. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
 5. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`.
-6. Re-stamp `docs/ai/.workflow-version` to the skill's `version`. Report changes; **ask before committing**.
+6. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version). Report changes; **ask before committing**.
+
+### Mode: backends
+
+Read-only. Answers *"which optional execution-backends are set up vs missing, and what's the next step?"* — for the family's subscription-CLI bridges (`codex-cli-bridge` → `codex`, `antigravity-cli-bridge` → `agy`). It **never writes, never commits, and never runs a subscription CLI**.
+
+1. Run `node ${CLAUDE_SKILL_DIR}/tools/detect-backends.mjs` and present its table verbatim. Each row reports two **decoupled** axes: `manifestState` (health of the bridge *skill* — `not-installed | unsupported-schema | invalid-manifest | foreign | stub | ok`) and the readiness signals `cli` / `credentials` / `wrappers`, probed independently — so a CLI that is installed and signed in but whose bridge *skill* is absent reads `needs-skill`, not "missing".
+2. For any backend that is not `ready`, point to its setup: the local `setup/README.md` when the bridge is installed, otherwise the backend's setup URL (both are in the report).
+3. State plainly to the user that this is **detection only**:
+   - **"credentials present"** means the credential-marker **file** exists — it is **not** a live login check. The detector never runs `codex login status` / `agy` (that would spawn a paid, slow, networked subscription CLI).
+   - The bridges' wrappers are **POSIX `.sh`** scripts. On Windows the detector still works, but the bridges themselves are **not promised to run** — say so rather than implying they will.
 
 ---
 
@@ -80,7 +150,7 @@ The non-obvious traps — scan these before bootstrapping or upgrading. Each is
 - **`CLAUDE.md` is a symlink, not a copy.** `ln -s AGENTS.md CLAUDE.md` — single source, no duplication. A copy drifts; a symlink can't.
 - **Never overwrite an existing entry point or hook.** If `AGENTS.md` / `CLAUDE.md` already exist, or the installer reports a pre-existing non-marker git hook, **stop and ask** the user to merge vs replace — don't clobber.
 - **No Node runtime → skip enforcement.** If the project has no Node (recon step 1), skip bootstrap steps 8–9 (scripts + hook) and follow the cap/archive/index policy manually, or port the scripts to the project's language.
-- **Conversational language never translates artifacts.** It governs *dialogue only*. Code, identifiers, paths, commands, log output, abbreviations, and every deployed `docs/ai/` / `AGENTS.md` file stay English. See [Communication contract](references/contracts.md#communication-contract).
+- **Conversational language never translates artifacts.** It governs *dialogue only*. Code, identifiers, paths, commands, log output, abbreviations, and every deployed `docs/ai/` / `AGENTS.md` file stay in their source language. See [Communication contract](references/contracts.md#communication-contract).
 - **Never auto-commit.** Report quality-gate results and wait for explicit approval — in both modes.
 
 ---
@@ -137,4 +207,6 @@ Deploy these into `AGENTS.md`; remove rows that don't apply to the stack.
 - [`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` + `methodology-slot.md` (the bounded slot injection), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`), and `release-scan.mjs` (the attribution-off release gate). 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/bin/install.mjs

@@ -19,8 +19,8 @@
 // Dependency-free, Node >= 18.
 
 import { readFile, mkdir, readdir, copyFile, lstat, readlink, symlink } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, lstatSync } from 'node:fs';
+import { dirname, join, resolve, relative, sep, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
@@ -29,7 +29,18 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
 
 // The deployable skill = everything except the npm wrapper (package.json, bin/).
-const PAYLOAD = ['SKILL.md', 'README.md', 'CHANGELOG.md', 'references', 'launchers', 'migrations'];
+// capability.json (the family manifest) + tools/ (the family schema + validator the kit runs
+// as the memory detector) must land in the installed skill dir too.
+const PAYLOAD = [
+  'SKILL.md',
+  'README.md',
+  'CHANGELOG.md',
+  'capability.json',
+  'references',
+  'launchers',
+  'migrations',
+  'tools',
+];
 
 const tildify = (path) => path.replace(homedir(), '~');
 
@@ -42,7 +53,39 @@ const readVersion = async () => {
   }
 };
 
-const copyRecursive = async (src, dest) => {
+// lstat without following symlinks; null when absent. existsSync FOLLOWS symlinks (so a
+// *dangling* symlink reads as absent) — lstat is what lets the guard catch a dangling dest symlink.
+const lstatNoFollow = (path) => {
+  try {
+    return lstatSync(path);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err; // EACCES/EIO etc. must NOT fail open (be read as "not a symlink")
+  }
+};
+
+// Symlink-traversal guard: refuse to write *through* any symlink at or above `dest` within
+// `root` (root / intermediate dir / leaf, including a dangling one), or to a dest outside `root`.
+const assertContainedRealPath = (root, dest) => {
+  const rel = relative(root, dest);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`[agent-workflow-kit] refusing to write outside the target dir: ${dest}`);
+  }
+  if (lstatNoFollow(root)?.isSymbolicLink()) {
+    throw new Error(`[agent-workflow-kit] refusing to install into a symlinked target dir: ${root}`);
+  }
+  const walk = (acc, part) => {
+    const cur = join(acc, part);
+    if (lstatNoFollow(cur)?.isSymbolicLink()) {
+      throw new Error(`[agent-workflow-kit] refusing to write through a symlink at ${cur} (would escape ${root}).`);
+    }
+    return cur;
+  };
+  rel.split(sep).filter(Boolean).reduce(walk, root);
+};
+
+const copyRecursive = async (src, dest, root) => {
+  assertContainedRealPath(root, dest); // never write through a dest symlink (root/intermediate/leaf)
   const stat = await lstat(src);
   if (stat.isSymbolicLink()) {
     if (existsSync(dest)) return; // additive: never delete/replace an existing entry
@@ -51,7 +94,7 @@ const copyRecursive = async (src, dest) => {
   } else if (stat.isDirectory()) {
     await mkdir(dest, { recursive: true });
     const entries = await readdir(src);
-    await Promise.all(entries.map((entry) => copyRecursive(join(src, entry), join(dest, entry))));
+    await Promise.all(entries.map((entry) => copyRecursive(join(src, entry), join(dest, entry), root)));
   } else {
     await mkdir(dirname(dest), { recursive: true });
     await copyFile(src, dest);
@@ -105,17 +148,25 @@ const main = async () => {
   if (args.help) return printHelp(version);
   if (args.version) return console.log(version);
 
-  if (!existsSync(resolve(PKG_ROOT, 'SKILL.md'))) {
-    console.error('[agent-workflow-kit] package payload missing (no SKILL.md) — corrupt install?');
+  // Critical payload must be present, or the install would silently ship a kit that can't run
+  // its own detector (tools/) or family contract (capability.json). Fail loudly, don't filter away.
+  const REQUIRED = ['SKILL.md', 'capability.json', 'references', 'tools', 'migrations'];
+  const missing = REQUIRED.filter((entry) => !existsSync(resolve(PKG_ROOT, entry)));
+  if (missing.length > 0) {
+    console.error(`[agent-workflow-kit] package payload incomplete — missing: ${missing.join(', ')} (corrupt install?)`);
     process.exit(1);
   }
 
   const target = resolveTarget(args.dir);
   const wasPresent = existsSync(resolve(target, 'SKILL.md'));
+  if (lstatNoFollow(target)?.isSymbolicLink()) {
+    console.error(`[agent-workflow-kit] target dir is a symlink — refusing to write through it: ${tildify(target)}`);
+    process.exit(1);
+  }
   await mkdir(target, { recursive: true });
   await Promise.all(
     PAYLOAD.filter((entry) => existsSync(resolve(PKG_ROOT, entry))).map((entry) =>
-      copyRecursive(resolve(PKG_ROOT, entry), resolve(target, entry)),
+      copyRecursive(resolve(PKG_ROOT, entry), resolve(target, entry), target),
     ),
   );
   console.log(`[agent-workflow-kit] ${wasPresent ? 'updated the kit to' : 'installed'} v${version} -> ${tildify(target)}`);

package/bin/install.test.mjs

@@ -0,0 +1,66 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtemp, rm, mkdir, symlink, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const INSTALLER = join(dirname(fileURLToPath(import.meta.url)), 'install.mjs');
+// --no-launchers so the test never wires Codex/Devin on the host.
+const runInstaller = (target) =>
+  spawnSync(process.execPath, [INSTALLER, '--dir', target, '--no-launchers'], { encoding: 'utf8' });
+
+describe('kit installer — payload + symlink-traversal hardening', () => {
+  let dir;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'aw-kit-install-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('installs the critical payload (capability.json + tools/ + references/) and not the npm wrapper', () => {
+    const target = join(dir, 'agent-workflow-kit');
+    const res = runInstaller(target);
+    assert.equal(res.status, 0, res.stderr);
+    for (const f of ['SKILL.md', 'capability.json', 'tools/manifest/validate.mjs', 'tools/delegation.mjs', 'references']) {
+      assert.ok(existsSync(join(target, f)), `missing installed entry: ${f}`);
+    }
+    assert.equal(existsSync(join(target, 'bin/install.mjs')), false);
+  });
+
+  it('refuses to write through a symlinked INTERMEDIATE dest component (no leak)', async () => {
+    const target = join(dir, 'target');
+    const evil = join(dir, 'evil');
+    await mkdir(target, { recursive: true });
+    await mkdir(evil, { recursive: true });
+    await symlink(evil, join(target, 'references'));
+    const res = runInstaller(target);
+    assert.notEqual(res.status, 0);
+    assert.match(res.stderr, /symlink/i);
+    assert.deepEqual(await readdir(evil), []);
+  });
+
+  it('refuses a DANGLING destination symlink', async () => {
+    const target = join(dir, 'target');
+    await mkdir(target, { recursive: true });
+    await symlink(join(dir, 'nowhere'), join(target, 'references'));
+    const res = runInstaller(target);
+    assert.notEqual(res.status, 0);
+    assert.match(res.stderr, /symlink/i);
+    assert.equal(existsSync(join(dir, 'nowhere')), false);
+  });
+
+  it('refuses a symlinked TARGET root (no leak)', async () => {
+    const real = join(dir, 'real');
+    const root = join(dir, 'root');
+    await mkdir(real, { recursive: true });
+    await symlink(real, root);
+    const res = runInstaller(root);
+    assert.notEqual(res.status, 0);
+    assert.match(res.stderr, /symlink/i);
+    assert.deepEqual(await readdir(real), []);
+  });
+});

package/capability.json

@@ -0,0 +1,21 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "agent-workflow-kit",
+  "kind": "composition-root",
+  "version": "1.5.0",
+  "provides": [],
+  "roles": {},
+  "detect": {
+    "installed": {
+      "env": "AGENT_WORKFLOW_KIT_DIR",
+      "default": "~/.claude/skills/agent-workflow-kit",
+      "file": "SKILL.md"
+    },
+    "deployed": { "file": "docs/ai/.workflow-version" }
+  },
+  "install": { "npm": "@sabaiway/agent-workflow-kit" },
+  "cost": "none",
+  "quota": null,
+  "provenance": { "author": "sabaiway", "source": "github:sabaiway/agent-workflow" }
+}

package/migrations/1.1.0-communication-language.md

@@ -10,8 +10,8 @@ language* block in the project's `AGENTS.md` so every agent that reads the entry
 honours it instead of drifting between languages. Pre-1.1.0 deployments have no such block.
 
 Scope is **dialogue only** — code, identifiers, paths, commands, log output, and
-abbreviations stay in their source language, and the `docs/ai/` files + `AGENTS.md` stay
-English (the kernel is English-only). This migration changes *one* doc block, nothing else.
+abbreviations stay in their source language, and the `docs/ai/` files + `AGENTS.md` are not
+translated either. This migration changes *one* doc block, nothing else.
 
 ## Steps
 
@@ -29,8 +29,8 @@ English (the kernel is English-only). This migration changes *one* doc block, no
    ## 🗣️ Communication language
 
    > **Talk to the user in <their language>** — every question, explanation, summary, and status update.
-   > Keep code, identifiers, file paths, shell commands, log output, and abbreviations in their **source language** (usually English) — translating them breaks copy-paste, search, and tooling.
-   > This sets the **dialogue** language only. The files in `docs/ai/` and this entry point stay in English (kernel is English-only, for cross-agent / cross-team portability).
+   > Keep code, identifiers, file paths, shell commands, log output, and abbreviations in their **source language** — translating them breaks copy-paste, search, and tooling.
+   > This sets the **dialogue** language only — it does not translate the files in `docs/ai/` or this entry point, which stay in their source language (for cross-agent / cross-team portability).
    ```
 
 5. Keep `AGENTS.md` within its ≤100-line budget (the block is ~6 lines; it fits). Do **not**
@@ -43,7 +43,7 @@ English (the kernel is English-only). This migration changes *one* doc block, no
 - The docs cap-validator is still green (`node scripts/check-docs-size.mjs` for Node projects)
   — the entry point did not bust its line budget.
 - From now on the agent's replies are in the chosen language; paths/commands/identifiers
-  remain English.
+  remain in their source language.
 
 ## Rollback
 

package/migrations/README.md

@@ -10,7 +10,8 @@ releases add files/templates, which `upgrade` reconciles without a migration.
 1. Read the project's stamped version from `docs/ai/.workflow-version`.
 2. Select every migration whose `<version>` is **strictly newer** than the stamp.
 3. Apply them in **ascending semver order**.
-4. Re-stamp `docs/ai/.workflow-version` to the skill's current `version`.
+4. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0` today — the
+   shared lineage, **not** this skill's package version `1.4.0`). A stamp greater than the head → STOP.
 
 ## Authoring rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.3.0",
+  "version": "1.5.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",
@@ -25,13 +25,14 @@
     "memory",
     "developer-tools"
   ],
-  "homepage": "https://github.com/sabaiway/agent-workflow-kit#readme",
+  "homepage": "https://github.com/sabaiway/agent-workflow#readme",
   "bugs": {
-    "url": "https://github.com/sabaiway/agent-workflow-kit/issues"
+    "url": "https://github.com/sabaiway/agent-workflow/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/sabaiway/agent-workflow-kit.git"
+    "url": "git+https://github.com/sabaiway/agent-workflow.git",
+    "directory": "agent-workflow-kit"
   },
   "license": "MIT",
   "author": "sabaiway",
@@ -44,9 +45,11 @@
     "SKILL.md",
     "README.md",
     "CHANGELOG.md",
+    "capability.json",
     "references/",
     "launchers/",
-    "migrations/"
+    "migrations/",
+    "tools/"
   ],
   "engines": {
     "node": ">=18"

package/references/contracts.md

@@ -33,8 +33,8 @@ reads the entry point honours it — and stops drifting between languages mid-se
 Scope — **dialogue only**:
 
 - **In the chosen language** — everything the agent produces *for the user to read*: questions, explanations, plan summaries, status updates, commit-message prose if asked, review notes.
-- **Always in their source language (usually English)** — code, identifiers, file paths, shell commands, log/console output, error strings, config keys, and abbreviations/acronyms. Translating these breaks copy-paste, search, and tooling.
-- **Files stay English** — the deployed `docs/ai/` files, `AGENTS.md`, and this kernel are English-only regardless of the chosen language (cross-agent / cross-team portability). The conversational language is about the *chat*, not the *artifacts*.
+- **Always in their source language** — code, identifiers, file paths, shell commands, log/console output, error strings, config keys, and abbreviations/acronyms. Translating these breaks copy-paste, search, and tooling.
+- **Files aren't translated** — the deployed `docs/ai/` files, `AGENTS.md`, and this kernel stay in their source language regardless of the chosen language (cross-agent / cross-team portability). The conversational language is about the *chat*, not the *artifacts*.
 
 Default to the language the user is already writing in; confirm rather than assume. On `upgrade`, a
 pre-1.1.0 deployment with no block gets one (the agent asks).

package/references/scripts/archive-changelog.mjs

@@ -130,9 +130,6 @@ export const parseChangelogText = (text) => {
 
 const TRAILING_FOOTER_PATTERNS = [
   /^\*\*Last Updated:/i,
-  // Legacy in-tree footer line from the deleted changelog-archive.md — match left in place
-  // so a re-migration cannot leak the old marker into a freshly-rotated entry.
-  /^> Записи старше/i,
 ];
 
 export const stripTrailingSeparator = (block) => {
@@ -149,7 +146,7 @@ export const stripTrailingSeparator = (block) => {
 export const stripBlockquoteHistoryNotice = (preamble) => {
   const filtered = preamble
     .split('\n')
-    .filter((line) => !/changelog-archive\.md/i.test(line) && !/Записи старше/i.test(line));
+    .filter((line) => !/changelog-archive\.md/i.test(line));
 
   // Strip any previously-inserted "## History" section so re-running the rotator is idempotent.
   // A History section starts at `## History` and ends at the next `---` separator or end-of-file.

package/references/templates/AGENTS.md

@@ -9,8 +9,8 @@
 ## 🗣️ Communication language
 
 > **Talk to the user in {{COMM_LANGUAGE}}** — every question, explanation, summary, and status update.
-> Keep code, identifiers, file paths, shell commands, log output, and abbreviations in their **source language** (usually English) — translating them breaks copy-paste, search, and tooling.
-> This sets the **dialogue** language only. The files in `docs/ai/` and this entry point stay in English (kernel is English-only, for cross-agent / cross-team portability).
+> Keep code, identifiers, file paths, shell commands, log output, and abbreviations in their **source language** — translating them breaks copy-paste, search, and tooling.
+> This sets the **dialogue** language only — it does not translate the files in `docs/ai/` or this entry point, which stay in their source language (for cross-agent / cross-team portability).
 
 ---