@sabaiway/agent-workflow-kit 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -4,6 +4,52 @@ 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.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
+project, so **no migration is needed** (`upgrade` reconciles and re-stamps to `1.3.0` with nothing
+to apply). Drawn from [*Lessons from building Claude Code: how we use Skills*](https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills).
+
+- **Consolidated Gotchas section in `SKILL.md`** — the blog calls the Gotchas section "the highest-signal content in any skill". The non-obvious traps that were scattered through the procedure (harness-added `Co-Authored-By` vs prose, hidden mode never touching `package.json`, `CLAUDE.md` as a symlink not a copy, source-vs-target dir, no-Node → skip enforcement, never overwrite an existing entry point/hook) are now also a single scannable list.
+- **Setup contracts moved to `references/contracts.md`** — progressive disclosure: `SKILL.md` keeps a lean *Setup contracts* pointer (with one-line defaults), and the full Visibility / Communication / Attribution rules load only when needed. Trims the always-loaded `SKILL.md` by ~40 lines without losing any rule.
+- **Setup questions use structured prompts where supported** — the three bootstrap questions (visibility, language, attribution) and the equivalent `upgrade` migration questions now call for a structured multiple-choice prompt (`AskUserQuestion` in Claude Code) where the agent supports it, falling back to prose elsewhere — keeping cross-agent portability (Codex / Cursor / Devin) intact.
+
 ## 1.2.0 — Agent attribution is opt-in
 
 **Attribution question at setup**
@@ -23,7 +69,7 @@ every `migrations/<version>-<slug>.md` newer than it, in semver order.
 **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.2.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
 ```
@@ -210,10 +217,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
 ├── launchers/       ← Codex / Devin Desktop / Cursor entries
 └── migrations/      ← per-version upgrade steps
 ```
@@ -221,5 +231,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.2.0'
+  version: '1.4.0'
 ---
 
 # agent-workflow-kit
@@ -12,12 +12,66 @@ 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.
 
 ---
 
+## 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.
+
+---
+
 ## Two 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.
@@ -29,6 +83,8 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 
 > Bundled sources below (templates, scripts) live in **this skill's own directory** — `${CLAUDE_SKILL_DIR}/` in Claude Code, or the folder containing this `SKILL.md` in Codex / other agents. Use that as the copy/read source; the working directory is the **target project**, not the skill.
 
+> The three setup questions (steps 2–4) are decisions only the user can make and are hard to reverse after a commit. Ask each as a **structured multiple-choice prompt where your agent supports it** (`AskUserQuestion` in Claude Code — one option per choice, recommended one first), otherwise in prose — and **wait for the answer before writing anything**.
+
 1. **Recon (read-only).** Before writing anything:
    - `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` → stack, package manager, scripts.
    - `ls -la` root → `README`, existing `AGENTS.md`/`CLAUDE.md`, CI configs, linter/formatter configs.
@@ -36,15 +92,20 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
    - `src/` (or equivalent) 2–3 levels deep → modules, routes/pages, components, services, types.
    - Tests (framework, location, E2E?) and linter rules.
    - Record: stack, package manager, daily commands (`dev`/`test`/`lint`/`type-check`), routes/pages, architecture layers.
-2. **Choose visibility — ASK the user explicitly and wait for the answer, before writing anything.** This decides what gets tracked and is hard to reverse after a commit, so never assume the default silently: `visible` (committed — canonical, recommended) or `hidden` (in-tree, hidden via `~/.gitignore_global`). See *Visibility contract*.
-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*. 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*.
+2. **Choose visibility — ASK the user explicitly and wait for the answer, before writing anything.** This decides what gets tracked and is hard to reverse after a commit, so never assume the default silently: `visible` (committed — canonical, recommended) or `hidden` (in-tree, hidden via `~/.gitignore_global`). See [Visibility contract](references/contracts.md#visibility-contract).
+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`).
 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).
+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 **ask before committing** — never auto-commit.
 
 Fill strategy:
@@ -59,53 +120,33 @@ 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). 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**.
-
----
-
-## Visibility contract
-
-The user chooses at bootstrap whether the AI artifacts are visible in the repo or hidden — an **explicit up-front question** (step 2), never an assumed default. The two modes then diverge:
-
-- **visible** — artifacts are committed. Wire the project's `package.json` scripts (`docs:check` / `docs:index` / `docs:index:check` / `docs:archive` / `docs:archive:check` / `docs:archive:issues` / `docs:archive:issues:check` / `prepare: node scripts/install-git-hooks.mjs`) and add a minimal `.gitignore` (`docs/plans/`, `.claude/settings.local.json`). This is the canonical model.
-- **hidden** (in-tree) — same files on disk, but the repo "looks normal": append the artifact paths (`AGENTS.md`, `CLAUDE.md`, `docs/ai/`, `docs/plans/`, `scripts/*.mjs` you added, `docs/ai/.workflow-version`) to the global excludes file git **already uses** (`git config --get core.excludesFile`); if none is set, point it at `~/.gitignore_global` (`git config --global core.excludesFile ~/.gitignore_global`) and append there. **Verify `git status` shows the artifacts as ignored** afterwards. **Do not edit `package.json`** — that is a tracked change and would leak; the pre-commit hook (always untracked in `.git/hooks/`) calls the scripts via `node scripts/<x>.mjs` directly.
-
-Not in this version: a fully-external hidden mode (artifacts relocated outside the repo tree). Deferred to a later release + migration.
+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 **deployment-lineage head** (`1.3.0`, not the package version). Report changes; **ask before committing**.
 
 ---
 
-## Communication contract
-
-The user chooses at bootstrap (step 3) which language the agent **talks to them** in. The choice is recorded in the *Communication language* block of the project's `AGENTS.md`, so every agent that reads the entry point honours it — and stops drifting between languages mid-session.
-
-Scope — **dialogue only**:
+## Gotchas
 
-- **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*.
+The non-obvious traps — scan these before bootstrapping or upgrading. Each is also enforced inline in the procedure above; this is the consolidated high-signal list.
 
-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).
+- **Source vs target directory.** Templates and scripts are read from the skill's own dir (`${CLAUDE_SKILL_DIR}/` in Claude Code, the `SKILL.md` folder elsewhere). The **working directory is the target project** — never write kernel files back into the skill.
+- **The `Co-Authored-By` trailer is added by the harness, not by prose.** When attribution is `off`, a doc directive alone won't stop it — for Claude Code you **must** also set `"includeCoAuthoredBy": false` in the project's `.claude/settings.json` (create it if absent). Other tools: disable their equivalent co-author/footer setting.
+- **Hidden mode must never touch `package.json`.** Editing it is a *tracked* change and leaks the whole system. Hidden mode wires nothing into `package.json`; the pre-commit hook (untracked in `.git/hooks/`) calls `node scripts/<x>.mjs` directly. After hiding, **verify `git status` shows the artifacts as ignored**.
+- **`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 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.
 
 ---
 
-## Attribution contract
-
-The user chooses at bootstrap (step 4) whether the agent may **attribute work to itself or to AI**. The choice is recorded in the *Attribution* block of the project's `AGENTS.md`, so every agent that reads the entry point honours it. **Default is `off`** — people are routinely surprised to find an AI listed as a repo contributor (a `Co-Authored-By` trailer is enough to do it), so opt-in, never opt-out.
-
-When attribution is **`off`**, no mention of the agent, AI, or the model appears **anywhere**:
-
-- **No `Co-Authored-By` trailers** and **no "Generated with …" footers** on commits or PRs.
-- **No AI/agent/model references** in code, comments, commit messages, PR titles/bodies, branch names, or `docs/` prose. The work reads as the human author's.
-- **Two enforcement layers** — the *Attribution* block binds everything an agent writes **by hand**; the automatic `Co-Authored-By` trailer is added by the **harness**, not the prose, so for **Claude Code** the kit also sets `"includeCoAuthoredBy": false` in the project's `.claude/settings.json`. Other tools: disable their equivalent co-author/footer setting if present.
-
-When **`on`**, the agent may add its standard trailer / footer per the user's tooling defaults. This block is about *attribution*, not authorship of the actual changes — quality, tests, and the "ask before commit" rule are unchanged either way.
+## Setup contracts
 
-On `upgrade`, a pre-1.2.0 deployment with no block gets one (the agent asks, defaulting to `off`).
+The three setup choices — **visibility** (step 2), **conversational language** (step 3), and **agent attribution** (step 4) — each have a full contract in [`references/contracts.md`](references/contracts.md). Load it when you need the complete rule (e.g. while filling the matching `AGENTS.md` block, or when an `upgrade` migration touches one). Defaults, in brief: visibility = `visible` (committed); language = whatever the user is already writing in; attribution = `off`. Ask each as a structured multiple-choice prompt where supported (`AskUserQuestion` in Claude Code), otherwise in prose.
 
 ---
 
@@ -149,9 +190,12 @@ Deploy these into `AGENTS.md`; remove rows that don't apply to the stack.
 
 ## References
 
+- [`references/contracts.md`](references/contracts.md) — the three setup contracts (visibility, conversational language, agent attribution) in full; the *Setup contracts* section above points here.
 - [`references/planning.md`](references/planning.md) — plan vocabulary (Plan→Phase→Step→Substep), lifecycle, `queue.md` series-index, mandatory Cleanup, session-continuity heuristic.
 - [`references/templates/`](references/templates/) — stack-agnostic `AGENTS.md`, `agent_rules.md`, 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` + `methodology-slot.md` (the bounded slot injection), 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.4.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.2.0",
+  "version": "1.4.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"