agent-docs-bootstrap 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versions follo
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-27
+
+### Changed
+- Third-party skills are bundled inside `docs-bootstrap` as guides in `vendor/<name>/`, read by path, instead of being installed as separate skills. Each `SKILL.md` is renamed to `<name>.md`, content unchanged: Codex and OpenCode find a nested `SKILL.md` and register it as a skill, and OpenCode silently keeps one of two skills with the same name. A user's own `grilling` or `domain-modeling` no longer clashes with the kit's copy. The install now has two skills, `docs-bootstrap` and `docs-check`.
+- The installer removes paths an earlier version installed into the same targets and this version no longer ships, so an update from 0.2.0 drops the old third-party skill folders.
+- README, package description and keywords: a set of agent skills for any agent that runs them; the installer sets up Claude Code, Codex and OpenCode. New "Other agents" section. `docs-check` falls back to `--snapshot-only` for any other harness.
+- `docs-scout` for OpenCode no longer needs the `diataxis-audit` skill permission; the brief gives it the guide's path.
+
+### Fixed
+- `--uninstall` and updates removed every path listed in `.agent-docs-bootstrap`, which is committed, so a line added by a bad merge (`src`, `../x`) deleted project or outside folders. Only lines shaped like a path the kit installs, `<layout folder>/<kit name>`, are now trusted; others are ignored with a warning and dropped from the marker. `reader-run.mjs` applies the same rule, so a stray `docs` line no longer hides every document from the snapshot.
+- `docs-check` snapshot: a nested `CLAUDE.md` came from the parent commit instead of the working tree. `README` stays from the parent commit on purpose, now stated in the skill.
+- README no longer says the Codex reader has no access to the repository: its read-only sandbox blocks writes, not reading other folders.
+- `docs-check`: global instructions wording no longer claims `claude -p --restricted` loads `~/.claude/CLAUDE.md`.
+- `reader-run.mjs`: `--timeout-min` is documented; on Windows the timeout stops the CLI, not only its shell; snapshot folders of two repositories with the same name no longer collide.
+- `install.mjs` accepts `--flag=value` as well as `--flag value`.
+
+### Removed
+- `grill-with-docs`: the kit did not use it, and it only calls the `grilling` and `domain-modeling` skills, which are no longer installed as skills.
+
 ## [0.2.0] - 2026-10-27
 
 ### Added

package/README.md

@@ -4,7 +4,9 @@
 [![check](https://github.com/TraneDev/agent-docs-bootstrap/actions/workflows/check.yml/badge.svg)](https://github.com/TraneDev/agent-docs-bootstrap/actions/workflows/check.yml)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-**agent-docs-bootstrap** is a set of skills and subagents for **Claude Code**, **Codex** and **OpenCode**. It interviews your team and writes the glossary, decision records, architecture, how-tos and `AGENTS.md` that coding agents and new developers need. If you want to see how well they work, an **optional** check has a fresh agent plan a task from the docs alone: one you bring, or real past tasks from your git history compared with the commits that solved them.
+**agent-docs-bootstrap** is a set of agent skills and instructions, not tied to one tool. It interviews your team and writes the glossary, decision records, architecture, how-tos and `AGENTS.md` that coding agents and new developers need. If you want to see how well they work, an **optional** check has a fresh agent plan a task from the docs alone: one you bring, or real past tasks from your git history compared with the commits that solved them.
+
+The installer sets up **Claude Code**, **Codex** and **OpenCode**. Any other agent that runs skills can use the two skill folders as they are: see [Other agents](#other-agents).
 
 [Quick start](#quick-start) · [How it works](#how-it-works) · [Optional: test the docs](#optional-test-the-docs-with-docs-check) · [Install options](#install-options) · [Harness differences](#harness-differences)
 
@@ -15,7 +17,7 @@ You need Node.js 18+ and a git repository.
 1. From your project root, install the skills and subagents:
 
    ```bash
-   npx agent-docs-bootstrap@0.2.0 --target claude
+   npx agent-docs-bootstrap@0.3.0 --target claude
    ```
 
    Replace `claude` with `codex`, `opencode`, a list such as `claude,codex`, or `all`.
@@ -79,7 +81,7 @@ flowchart LR
 
 1. The agent picks three real past tasks from git history, preferring commits made after the docs were written, and drops any whose solution is already in the code or the docs.
 2. For each task, the code is extracted **as it was before the task**, outside your repository, and your current documents from the working tree go on top.
-3. A fresh reader plans the task. It runs as a **separate process** of your harness (`claude -p`, `codex exec`, `opencode run`), read-only, with no history, no MCP tools and no access to your repository: a subagent of the same session could find the solution in your current code.
+3. A fresh reader plans the task. It runs as a **separate process** of your harness (`claude -p`, `codex exec`, `opencode run`), read-only, with no history and no MCP tools, in a snapshot outside your repository: a subagent of the same session could find the solution in your current code. Claude Code and OpenCode keep the reader's file access inside the snapshot; Codex's read-only sandbox blocks writes but not reading elsewhere, so there only the reader's instructions keep it in the snapshot (see [Harness differences](#harness-differences)).
 4. Its plan is compared with what the real commit changed. Missed files, missed verification commands, wrong terms, rejected approaches and guesses are **gaps**.
 5. The gaps become one list of fixes, grouped by document. You strike out what came from a poor commit rather than the docs, and the rest is applied.
 
@@ -101,19 +103,19 @@ All options run the same installer from your project root. Pin the version: the
 **From npm** (recommended):
 
 ```bash
-npx agent-docs-bootstrap@0.2.0 --target claude
+npx agent-docs-bootstrap@0.3.0 --target claude
 ```
 
 **From a GitHub release tag**, when the npm registry is blocked or unavailable:
 
 ```bash
-npx github:TraneDev/agent-docs-bootstrap#v0.2.0 --target claude
+npx github:TraneDev/agent-docs-bootstrap#v0.3.0 --target claude
 ```
 
 **From a clone**, to read or change the kit first:
 
 ```bash
-git clone --branch v0.2.0 https://github.com/TraneDev/agent-docs-bootstrap.git ~/agent-docs-bootstrap
+git clone --branch v0.3.0 https://github.com/TraneDev/agent-docs-bootstrap.git ~/agent-docs-bootstrap
 node ~/agent-docs-bootstrap/install.mjs --target claude
 ```
 
@@ -127,11 +129,22 @@ Files are copied into the project, not linked, so they get committed with it.
 | `codex` | `.agents/skills/` | `.codex/agents/*.toml` |
 | `opencode` | `.agents/skills/` | `.opencode/agents/*.md`, plus `/docs-bootstrap` and `/docs-check` commands |
 
-`.agent-docs-bootstrap` lists every installed path. The installer replaces or removes only those paths and never touches files it did not create.
+Two skills are installed, `docs-bootstrap` and `docs-check`. The guides by other authors that `docs-bootstrap` relies on travel inside it, in `docs-bootstrap/vendor/`, and are not registered as skills, so a skill of yours with the same name, such as `grilling`, never clashes with them.
+
+`.agent-docs-bootstrap` lists every installed path. The installer replaces or removes only those paths and never touches files it did not create: a path that already exists and is not listed there is skipped with a warning, and a line in the marker that is not shaped like a path the kit installs (for example `src` or `../x`, added by a bad merge) is ignored with a warning.
+
+### Other agents
+
+The skills are plain `SKILL.md` folders with Markdown references and templates. For an agent the installer does not know, copy `skills/docs-bootstrap` and `skills/docs-check` from a clone (see above) into the folder where that agent looks for skills, and start it with "document this project". An agent without skill support can be pointed at `docs-bootstrap/SKILL.md` directly.
+
+What changes without the installer's targets:
+
+- **No subagents.** `docs-bootstrap` does the scout's briefs itself and keeps only summaries in the conversation.
+- **`docs-check`** builds the snapshot with `reader-run.mjs --snapshot-only`; you start a fresh session of your agent in that folder and paste the task. Starting the reader automatically works only with `claude`, `codex` and `opencode`.
 
 ### Update or remove
 
-- **Update:** run the installer again with the new version and commit the result.
+- **Update:** run the installer again with the new version and commit the result. Paths the previous version installed and this one no longer ships are removed.
 - **Remove:** run it with `--uninstall`. Everything listed in `.agent-docs-bootstrap` is deleted, along with the marker itself.
 
 <details>
@@ -155,19 +168,20 @@ The protocol is the same everywhere; how strictly each harness can enforce the l
 
 | Guarantee | Claude Code | Codex | OpenCode |
 |---|---|---|---|
-| Reader cannot see the solution or history | Snapshot outside the repo, no history; `--restricted` keeps file tools inside it | Snapshot outside the repo, no history | Snapshot outside the repo, no history; `external_directory: deny` |
+| Reader cannot see the solution or history | Snapshot outside the repo, no history; `--restricted` keeps file tools inside it | Snapshot outside the repo, no history; reading other folders is not blocked, only the prompt forbids it | Snapshot outside the repo, no history; `external_directory: deny` |
 | Reader cannot edit or run commands | `--restricted --tools Read,Grep,Glob` | `-s read-only` sandbox | Permissions (`"*": deny`) |
 | Scout writes only to the scratch folder | Instructions (edit tool removed) | Instructions only | Path permissions |
 | External docs are never modified | Instructions | Instructions | Instructions |
+| Scout reads the bundled guides | File tools | File tools | Read permission; a `--global` install is outside the project, so `external_directory` asks once |
 
 Where a guarantee is "instructions only", tighten it with your harness's own permission settings if you need to. For example, deny the write tools of your wiki's MCP server.
 
 ## Repository layout
 
 ```text
-skills/docs-bootstrap/   orchestrator: SKILL.md, references/ (formats, scout briefs), templates/
+skills/docs-bootstrap/   orchestrator: SKILL.md, references/ (formats, scout briefs), templates/,
+                         vendor/ (guides by other authors, each with its LICENSE)
 skills/docs-check/       optional reader test: SKILL.md, templates/, scripts/reader-run.mjs (snapshot and reader process)
-skills/third-party/      skills by other authors, unmodified, each with its LICENSE
 agents/                  docs-scout, docs-reader: one prompt + per-harness frontmatter blocks
 package.json             npm package metadata and the version
 install.mjs              installer (the package's `bin`)
@@ -178,12 +192,12 @@ To work on the kit itself, start with [AGENTS.md](AGENTS.md) and run `node scrip
 
 ## Credits
 
-The workflow builds on skills by other authors, bundled unmodified under their licenses. Pinned commits and update steps are in [THIRD_PARTY.md](THIRD_PARTY.md).
+The workflow builds on skills by other authors, bundled inside `docs-bootstrap` under their licenses, unmodified except that each `SKILL.md` is renamed so it does not register as a separate skill. Pinned commits and update steps are in [THIRD_PARTY.md](THIRD_PARTY.md).
 
-- Matt Pocock, [mattpocock/skills](https://github.com/mattpocock/skills): `domain-modeling`, `grilling`, `grill-with-docs` and `writing-for-agents` (MIT).
+- Matt Pocock, [mattpocock/skills](https://github.com/mattpocock/skills): `domain-modeling`, `grilling` and `writing-for-agents` (MIT).
 - Georges Martin, [jrjsmrtn/diataxis-skills](https://github.com/jrjsmrtn/diataxis-skills): `diataxis-audit` (MIT).
 - Anthropic, [anthropics/skills](https://github.com/anthropics/skills): `doc-coauthoring` (Apache 2.0).
 
 ## License
 
-[MIT](LICENSE) for the kit's own files. Third-party skills keep their own licenses.
+[MIT](LICENSE) for the kit's own files. Bundled third-party guides keep their own licenses.

package/THIRD_PARTY.md

@@ -1,12 +1,13 @@
-# Third-party skills
+# Third-party guides
 
-Copies of skills by other authors, pinned to a commit and **not modified**. Each folder under `skills/third-party/` carries the license of its source, so a skill copied on its own keeps it.
+Copies of skills by other authors, pinned to a commit and **not modified**, bundled inside `docs-bootstrap` as guides it reads by path. Each folder under `skills/docs-bootstrap/vendor/` carries the license of its source.
+
+The only change is a rename: each `SKILL.md` becomes `<name>.md`. Codex and OpenCode look for `SKILL.md` recursively inside skill folders, and Claude Code does not document how deep it looks, so a bundled `SKILL.md` would register as a separate skill and clash with a user's own skill of the same name. Other files keep their names, so links between them still resolve.
 
 | Skill | Source | Commit | Author | License |
 |---|---|---|---|---|
 | `domain-modeling` | [mattpocock/skills](https://github.com/mattpocock/skills), `skills/engineering/domain-modeling` | `3cca18b` | Matt Pocock | MIT |
 | `grilling` | [mattpocock/skills](https://github.com/mattpocock/skills), `skills/productivity/grilling` | `3cca18b` | Matt Pocock | MIT |
-| `grill-with-docs` | [mattpocock/skills](https://github.com/mattpocock/skills), `skills/engineering/grill-with-docs` | `3cca18b` | Matt Pocock | MIT |
 | `writing-for-agents` | [mattpocock/skills](https://github.com/mattpocock/skills), `skills/productivity/writing-for-agents` | `3cca18b` | Matt Pocock | MIT |
 | `diataxis-audit` | [jrjsmrtn/diataxis-skills](https://github.com/jrjsmrtn/diataxis-skills), `skills/diataxis-audit` | `4f36079` | Georges Martin | MIT |
 | `doc-coauthoring` | [anthropics/skills](https://github.com/anthropics/skills), `skills/doc-coauthoring` | `34040c9` | Anthropic | Apache 2.0 |
@@ -17,17 +18,18 @@ Full commit hashes: `3cca18b368ae95cdbdebbff572ccafa662551015`, `4f36079fd36e498
 
 ## Updating
 
-Fresh clone of the source at the new commit → diff against the copy → review for harmful or harness-specific instructions → replace the folder (keep its `LICENSE`) → update the table. `node scripts/check.mjs` verifies every folder has a `LICENSE` and a row here.
+Fresh clone of the source at the new commit → diff against the copy (compare the source's `SKILL.md` with `<name>.md`) → review for harmful or harness-specific instructions → replace the folder, rename `SKILL.md` to `<name>.md`, keep its `LICENSE` → update the table. `node scripts/check.mjs` verifies every folder has `<name>.md`, a `LICENSE`, a row here and no `SKILL.md`.
 
 ## Known quirks
 
-- `grill-with-docs` sets `disable-model-invocation: true`: Claude Code and Codex (via `agents/openai.yaml`) only run it when the user asks; OpenCode ignores the field. The kit's own workflow does not depend on it.
 - `doc-coauthoring`: its "Reader Testing" step suggests opening a new chat on claude.ai. In this kit that step is skipped (the optional `docs-check` skill covers it); only the Context Gathering and Refinement stages are used.
 - `diataxis-audit` links to `diataxis-create`, `diataxis-convert` and `diataxis-plan`, which are not bundled; those links do not resolve, which is expected.
-- `agents/openai.yaml` inside Matt Pocock's skills is Codex UI metadata; other harnesses ignore it.
+- `writing-for-agents/SKILL-MECHANICS.md` links back to `SKILL.md`, which is `writing-for-agents.md` here; that file is about writing skills and is not used for `AGENTS.md`.
+- `agents/openai.yaml` inside Matt Pocock's skills is Codex UI metadata for a skill; as bundled guides they are inert.
 
 ## Considered and not bundled
 
 - `setup-matt-pocock-skills` — writes its own config and creates issues via `gh`/`glab`; its role (wiring docs into the other skills) is played by `AGENTS.md` here.
 - `improve-codebase-architecture`, `codebase-design` — not about documentation; they work well on top of a finished `CONTEXT.md` and ADRs.
 - `diataxis-create`, `diataxis-convert`, `diataxis-plan` — not needed by the workflow.
+- `grill-with-docs` — bundled up to 0.2.0; it only calls the `grilling` and `domain-modeling` skills, which are no longer installed as skills.

package/agents/docs-scout.md

@@ -45,7 +45,6 @@ opencode: |
       "*": deny
       "docs-bootstrap": allow
       "docs-check": allow
-      "diataxis-audit": allow
 ---
 
 You are a scout. Your job is to collect facts about the project and return them to the lead agent. You write to the repository only in the scratch folder `docs/agents/scratch/`, when the brief asks for a file.

package/install.mjs

@@ -10,7 +10,9 @@
 //   claude    skills → .claude/skills/   agents → .claude/agents/*.md
 //   codex     skills → .agents/skills/   agents → .codex/agents/*.toml
 //   opencode  skills → .agents/skills/   agents → .opencode/agents/*.md   commands → .opencode/commands/*.md
-// Installed paths are listed in .agent-docs-bootstrap; only those are ever replaced or removed.
+// Installed paths are listed in .agent-docs-bootstrap; only those are ever replaced or removed, and only if a line
+// has the shape of a path the kit writes (<layout folder>/<kit name>). On an update, listed paths this version no
+// longer ships are removed.
 // No network access, no changes to harness settings, no admin rights.
 
 import fs from 'node:fs';
@@ -36,7 +38,25 @@ const exists = (p) => { try { fs.lstatSync(p); return true; } catch { return fal
 if (!GLOBAL && (BASE === KIT || BASE.startsWith(KIT + path.sep)))
   die(`This is the kit's own directory (${BASE}). Run it from the project root: cd <project> && node ${path.join(KIT, 'install.mjs')} --target …`);
 
-const oldList = read(MARKER).split('\n').filter(l => l && !l.startsWith('version='));
+const codexHome = process.env.CODEX_HOME ? path.relative(BASE, process.env.CODEX_HOME) : '.codex';
+const ocConfig = process.env.OPENCODE_CONFIG_DIR ? path.relative(BASE, process.env.OPENCODE_CONFIG_DIR) : path.join('.config', 'opencode');
+const LAYOUT = {
+  claude:   { skills: '.claude/skills', agents: '.claude/agents' },
+  codex:    { skills: '.agents/skills', agents: GLOBAL ? path.join(codexHome, 'agents') : '.codex/agents' },
+  opencode: { skills: '.agents/skills', agents: GLOBAL ? path.join(ocConfig, 'agents') : '.opencode/agents',
+              commands: GLOBAL ? path.join(ocConfig, 'commands') : '.opencode/commands' },
+};
+
+// Every name any version of the kit installed. Add to it, never remove: an old install's marker may list them.
+const SHIPPED = new Set(['docs-bootstrap', 'docs-check', 'docs-scout', 'docs-reader',
+  'grilling', 'domain-modeling', 'writing-for-agents', 'doc-coauthoring', 'diataxis-audit', 'grill-with-docs']);
+const layoutDirs = new Set(Object.values(LAYOUT).flatMap(L => Object.values(L)).map(d => path.normalize(d)));
+// The marker is committed, so a bad merge or PR can add any line to it. Only a line shaped like a path the kit
+// writes, <layout folder>/<shipped name>[.md|.toml], is trusted; nothing else is ever replaced or removed.
+const isOwnedPath = (r) => layoutDirs.has(path.normalize(path.dirname(r))) && SHIPPED.has(path.basename(r).replace(/\.(md|toml)$/, ''));
+const markerLines = read(MARKER).split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('version='));
+for (const l of markerLines) if (!isOwnedPath(l)) warn(`ignored '${l}' in .agent-docs-bootstrap: not a path this kit installs`);
+const oldList = markerLines.filter(isOwnedPath);
 if (a.uninstall) { uninstall(); process.exit(0); }
 
 if (!a.target) usage(1, 'Missing --target.');
@@ -49,15 +69,6 @@ if (!GLOBAL) {
     die(`No .git here (${BASE}) — is this the project root? Run from the root or add --yes.`);
 }
 
-const codexHome = process.env.CODEX_HOME ? path.relative(BASE, process.env.CODEX_HOME) : '.codex';
-const ocConfig = process.env.OPENCODE_CONFIG_DIR ? path.relative(BASE, process.env.OPENCODE_CONFIG_DIR) : path.join('.config', 'opencode');
-const LAYOUT = {
-  claude:   { skills: '.claude/skills', agents: '.claude/agents' },
-  codex:    { skills: '.agents/skills', agents: GLOBAL ? path.join(codexHome, 'agents') : '.codex/agents' },
-  opencode: { skills: '.agents/skills', agents: GLOBAL ? path.join(ocConfig, 'agents') : '.opencode/agents',
-              commands: GLOBAL ? path.join(ocConfig, 'commands') : '.opencode/commands' },
-};
-
 const installed = new Set();
 const ours = (r) => oldList.includes(r);
 function writeOwned(r, fn) {
@@ -94,6 +105,11 @@ for (const t of targets) {
   }
 }
 
+// Paths an earlier version installed into these targets' folders and this version no longer ships.
+const ownDirs = new Set(targets.flatMap(t => Object.values(LAYOUT[t])));
+for (const r of oldList)
+  if (!installed.has(r) && ownDirs.has(path.dirname(r)) && exists(abs(r))) { fs.rmSync(abs(r), { recursive: true, force: true }); log(`removed  ${r} (no longer shipped)`); }
+
 // Keep entries of earlier installs (e.g. another target) that are still on disk.
 const keep = oldList.filter(r => !installed.has(r) && exists(abs(r)));
 fs.writeFileSync(MARKER, [`version=${VERSION}`, ...keep, ...installed].join('\n') + '\n');
@@ -139,14 +155,14 @@ function parseAgent(file) {
 // ---------- helpers
 function skillDirs() {
   const out = [];
-  for (const base of [path.join(KIT, 'skills'), path.join(KIT, 'skills', 'third-party')])
-    for (const e of fs.readdirSync(base, { withFileTypes: true })) {
-      const d = path.join(base, e.name);
-      if (!e.isDirectory() || !fs.existsSync(path.join(d, 'SKILL.md'))) continue;
-      const fm = (read(path.join(d, 'SKILL.md')).match(/^name:\s*["']?([^"'\n]+)["']?\s*$/m) || ['', ''])[1].trim();
-      if (!NAME_RE.test(e.name) || fm !== e.name) { warn(`skipped skill ${e.name}: frontmatter name '${fm}' must match the folder`); continue; }
-      out.push(d);
-    }
+  const base = path.join(KIT, 'skills');
+  for (const e of fs.readdirSync(base, { withFileTypes: true })) {
+    const d = path.join(base, e.name);
+    if (!e.isDirectory() || !fs.existsSync(path.join(d, 'SKILL.md'))) continue;
+    const fm = (read(path.join(d, 'SKILL.md')).match(/^name:\s*["']?([^"'\n]+)["']?\s*$/m) || ['', ''])[1].trim();
+    if (!NAME_RE.test(e.name) || fm !== e.name) { warn(`skipped skill ${e.name}: frontmatter name '${fm}' must match the folder`); continue; }
+    out.push(d);
+  }
   return out;
 }
 function uninstall() {
@@ -160,6 +176,8 @@ function uninstall() {
 function parseArgs(argv) {
   const o = {}; const withVal = new Set(['target', 'project', 'scout-model', 'reader-model']);
   for (let i = 0; i < argv.length; i++) {
+    const eq = argv[i].match(/^--([a-z-]+)=(.*)$/);
+    if (eq && withVal.has(eq[1])) { o[eq[1]] = eq[2]; continue; }
     const k = argv[i].replace(/^--/, '');
     if (argv[i] === '-h' || k === 'help') o.help = true;
     else if (withVal.has(k)) { if (i + 1 >= argv.length) die(`--${k} needs a value`); o[k] = argv[++i]; }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-docs-bootstrap",
-  "version": "0.2.0",
-  "description": "Skills and subagents that build reference documentation for a codebase and test it with a fresh agent. For Claude Code, Codex and OpenCode.",
+  "version": "0.3.0",
+  "description": "Agent skills that build reference documentation for a codebase (glossary, ADRs, architecture, how-tos, AGENTS.md) through interviews with the team, with an optional check by a fresh agent. Works with any agent that runs skills; the installer sets up Claude Code, Codex and OpenCode.",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/TraneDev/agent-docs-bootstrap.git" },
   "homepage": "https://github.com/TraneDev/agent-docs-bootstrap#readme",
@@ -9,5 +9,5 @@
   "bin": { "agent-docs-bootstrap": "install.mjs" },
   "files": ["install.mjs", "agents/", "skills/", "THIRD_PARTY.md", "CHANGELOG.md"],
   "engines": { "node": ">=18" },
-  "keywords": ["claude-code", "codex", "opencode", "agents-md", "documentation", "skills"]
+  "keywords": ["claude-code", "codex", "opencode", "agents-md", "documentation", "skills", "agent-skills", "ai-agents", "coding-agents"]
 }

package/skills/docs-bootstrap/SKILL.md

@@ -27,7 +27,7 @@ They hold at every stage.
 - **Keep your own context for the conversation.** Do not read external docs or scan the whole repository yourself: delegate to `docs-scout` and read its results from `docs/agents/scratch/` in parts.
 - **Secrets never reach the documents.** Passwords, tokens, keys and credentials, test environments included, are not written down: only where to get them (a vault, an environment variable, who to ask). If the human dictates a secret, record its source instead of the value and say why.
 - **Do not judge documentation quality yourself.** The human confirms what is written. If they want a measured check, the optional `docs-check` skill compares a fresh agent's plan with real commits.
-- **Formats are not duplicated.** Glossary and ADRs follow the `domain-modeling` skill (its `CONTEXT-FORMAT.md`, `ADR-FORMAT.md`). Diagrams — [references/c4-format.md](references/c4-format.md). `AGENTS.md` — [references/agents-md-format.md](references/agents-md-format.md). Reader test — the optional `docs-check` skill.
+- **Formats are not duplicated.** Glossary and ADRs follow `domain-modeling`: [CONTEXT-FORMAT.md](vendor/domain-modeling/CONTEXT-FORMAT.md), [ADR-FORMAT.md](vendor/domain-modeling/ADR-FORMAT.md). Diagrams — [references/c4-format.md](references/c4-format.md). `AGENTS.md` — [references/agents-md-format.md](references/agents-md-format.md). Reader test — the optional `docs-check` skill.
 - **Language.** Documents are written in the language recorded in the state file; identifiers and code terms stay as they are, and a glossary term carries its code name: "**Order request** (`Request`)". Templates in this skill are in English: translate headings and text when the documents language differs, keep file names.
 
 ## Subagents
@@ -38,6 +38,10 @@ Independent calls run in parallel, such as the stage 1.5 batches. Start them tog
 
 If the harness cannot start the `docs-scout` subagent, do the brief yourself but write the result to the scratch file and keep only a summary in the conversation.
 
+## Bundled guides
+
+`vendor/` holds guides by other authors (`grilling`, `domain-modeling`, `writing-for-agents`, `doc-coauthoring`, `diataxis-audit`), unmodified except that each `SKILL.md` is renamed to `<name>.md`. They are not separate skills: read the file at the stage that names it and follow it, even if a skill with the same name is installed in the session — this kit is tested with these copies. When a brief names a file under `vendor/`, give the scout its full path: the scout does not know where this skill is installed. This skill's folder is `.claude/skills/docs-bootstrap` or `.agents/skills/docs-bootstrap` in the project, or the same under the home directory for a global install; if unsure, search for `vendor/diataxis-audit/diataxis-audit.md`.
+
 ## Stage 0. Session start
 
 1. Read `docs/agents/bootstrap-state.md`. No file → ask the questions below, create `docs/agents/` and copy the templates from [templates/](templates/) into it: `bootstrap-state.md`, `sources.md`. Create `docs/agents/scratch/` and add the line `docs/agents/scratch/` to the project's `.gitignore`. Record the mode, the documents language and the kit version (first line of `.agent-docs-bootstrap` in the project root, if present) in the state file.
@@ -77,8 +81,8 @@ Skipped when `sources.md` lists no external sources, or the agent has no tools t
 **Scout.** Brief "Stage 2": draft terms from code with evidence and synonyms; name conflicts; ADR candidates from traces of decisions with reasons marked `ASSUMPTION`; comparison with facts from external docs (matches / differs / not in code).
 
 **You.**
-1. Load the `grilling` and `domain-modeling` skills.
-2. First decide single- or multi-context — the rule is in `CONTEXT-FORMAT.md`.
+1. Read [vendor/grilling/grilling.md](vendor/grilling/grilling.md) and [vendor/domain-modeling/domain-modeling.md](vendor/domain-modeling/domain-modeling.md) and follow them.
+2. First decide single- or multi-context — the rule is in [CONTEXT-FORMAT.md](vendor/domain-modeling/CONTEXT-FORMAT.md).
 3. Interview along the tree: term conflicts → definitions → each ADR candidate (reason, rejected alternatives, still valid?) → open questions accumulated at stages 1–1.5.
 4. Write as you go: `CONTEXT.md` (or `CONTEXT-MAP.md` + one `CONTEXT.md` per context), `docs/adr/NNNN-slug.md`. No ADR without a confirmed reason.
 
@@ -104,14 +108,14 @@ A how-to is a step-by-step procedure for a recurring task: "add a migration", "a
 
 **You.** Show the list; the human picks the 3–7 most frequent. For each:
 - an up-to-date external page exists → transfer it to `docs/how-to/<slug>.md`, checking every step against the code;
-- an outdated one exists → load `doc-coauthoring` and rewrite it with the human (stages Context Gathering and Refinement; its Reader Testing step is skipped; the optional `docs-check` skill covers it);
+- an outdated one exists → read [vendor/doc-coauthoring/doc-coauthoring.md](vendor/doc-coauthoring/doc-coauthoring.md) and rewrite it with the human (stages Context Gathering and Refinement; its Reader Testing step is skipped; the optional `docs-check` skill covers it);
 - none → do not write it from memory. List it as deferred: real team tasks will supply the material. If `docs/agents/reader-tests.md` exists, do not write how-tos from its tasks: a document written from a test task holds its answer, and the check on that task stops meaning anything.
 
 **Done when:** every step of every how-to points to an existing file or a command verified at stage 1; the deferred how-tos are listed in the state file.
 
 ## Stage 5. AGENTS.md
 
-**You.** Load `writing-for-agents`. Format — `agents-md-format.md`. Order:
+**You.** Read [vendor/writing-for-agents/writing-for-agents.md](vendor/writing-for-agents/writing-for-agents.md) and follow it. Format — `agents-md-format.md`. Order:
 1. Root `AGENTS.md`: up to 150 lines, only what is needed on every turn. Commands from stage 1, directory map from stage 3, pointers to `CONTEXT.md`, `docs/adr/`, `docs/how-to/`, `docs/architecture.md`.
 2. Nested `AGENTS.md` in large areas (an app in a monorepo, a big module): only rules specific to that area.
 3. Behaviour rules only from the human ("don't run e2e locally", "don't touch generated code").
@@ -131,7 +135,7 @@ There is no code, or very little, so there is nothing to reverse-engineer: all t
 
 ### N1. Interview the idea
 
-Load `grilling` and `domain-modeling`. Tree: what the system does and for whom → the main entities and their names → boundaries (single- or multi-context per `CONTEXT-FORMAT.md`) → decisions already made before the start (stack, state, storage, integrations) with reasons and rejected alternatives. Rounds as in stage 2.
+Read `grilling` and `domain-modeling` from `vendor/` as in stage 2. Tree: what the system does and for whom → the main entities and their names → boundaries (single- or multi-context per `CONTEXT-FORMAT.md`) → decisions already made before the start (stack, state, storage, integrations) with reasons and rejected alternatives. Rounds as in stage 2.
 
 **Write:** `CONTEXT.md` (or `CONTEXT-MAP.md`), `docs/adr/0001-…` onwards — only with a reason from a human. Also `docs/agents/sources.md` if the project already has external pages (spec, design).
 
@@ -145,7 +149,7 @@ From the design, not the code: C4 Context and Container per `c4-format.md`. A co
 
 ### N3. Starter AGENTS.md
 
-Load `writing-for-agents`. Use [templates/AGENTS.starter.md](templates/AGENTS.starter.md): commands already in the manifest (the scout verifies them by running, brief "Stage 1", sections 1–2), the planned directory map, rules from the human, pointers to `CONTEXT.md`, `docs/adr/`, `docs/architecture.md`. The how-to section stays empty with the note "will appear after the first features". Handle `CLAUDE.md` as in stage 5, step 4.
+Read `writing-for-agents` from `vendor/` as in stage 5. Use [templates/AGENTS.starter.md](templates/AGENTS.starter.md): commands already in the manifest (the scout verifies them by running, brief "Stage 1", sections 1–2), the planned directory map, rules from the human, pointers to `CONTEXT.md`, `docs/adr/`, `docs/architecture.md`. The how-to section stays empty with the note "will appear after the first features". Handle `CLAUDE.md` as in stage 5, step 4.
 
 **Done when:** the file is within 80 lines; every command is verified; every rule is confirmed.
 

package/skills/docs-bootstrap/references/scout-briefs.md

@@ -27,7 +27,7 @@ Use the tools the session has for the source listed in `docs/agents/sources.md`
 
 **Batches 1..K — classification.** For each page in the range:
 1. Get the structure, if the source can return it without the body: section headings, presence of code, tables, step lists.
-2. Determine the Diátaxis type from title and structure (criteria — the `diataxis-audit` skill). Numbered steps → how-to; parameter and API tables → reference; "why" and history → explanation; learning from zero → tutorial; a mix → mixed.
+2. Determine the Diátaxis type from title and structure (criteria — `vendor/diataxis-audit/diataxis-audit.md` in the `docs-bootstrap` skill folder; the lead gives its full path). Numbered steps → how-to; parameter and API tables → reference; "why" and history → explanation; learning from zero → tutorial; a mix → mixed.
 3. Only if the type is unclear, read the start of the body: at most 2000 characters. Read no further.
 4. Note whether the page refers to files or commands (code blocks, paths) — without checking; checks happen at stages 2 and 4.
 
@@ -43,7 +43,7 @@ Return these sections:
 
 1. **Terms** — for each: term, name in code, a one-sentence draft definition without implementation details, evidence files (up to 3), synonyms seen in code, UI strings, API. Leave out framework concepts.
 2. **Name conflicts** — one entity under different names (frontend/backend, DTO/UI, code/UI strings) and one name for different entities.
-3. **ADR candidates** — what was decided (fact), evidence, a hypothesis for the reason marked `ASSUMPTION`. Run each through the three criteria in `ADR-FORMAT.md` of the `domain-modeling` skill; for rejected ones name the failed criterion.
+3. **ADR candidates** — what was decided (fact), evidence, a hypothesis for the reason marked `ASSUMPTION`. Run each through the three criteria in `vendor/domain-modeling/ADR-FORMAT.md` of the `docs-bootstrap` skill folder (the lead gives its full path); for rejected ones name the failed criterion.
 4. **Check against external docs** — for each term and decision mentioned in the 1.5 audit: matches the code / differs (how) / not found in code. Read pages selectively: find the relevant section first, then read only that part, in chunks of at most 4000 characters. No more than 5 pages per run; if more are needed, return the list and the lead will start another run.
 
 ## Stage 3. Architecture

package/skills/docs-bootstrap/references/signals.md

@@ -15,7 +15,7 @@ The scout does not know in advance where things live in a given stack. It determ
 
 - Framework concepts (component, service, store, guard, DTO as a pattern) are not domain terms.
 - A code folder is not a container unless it deploys on its own.
-- A dependency is not an ADR until it passes the three criteria in `ADR-FORMAT.md`.
+- A dependency is not an ADR until it passes the three criteria in [ADR-FORMAT.md](../vendor/domain-modeling/ADR-FORMAT.md).
 
 ## Name conflict detector
 

package/skills/docs-check/SKILL.md

@@ -53,16 +53,16 @@ The reader must not see the solution, the history, your session's instructions o
 
 What the script does:
 
-- the snapshot is the parent's code without the documents and the kit's installed files, with the current documents from the working tree on top, committed or not (git-ignored and deleted ones are skipped, `docs/agents/` never goes in). Do not keep unfinished hand edits in the documents during a run: the reader gets them as they are;
+- the snapshot is the parent's code without the documents and the kit's installed files, with the current documents from the working tree on top, committed or not (git-ignored and deleted ones are skipped, `docs/agents/` never goes in). Do not keep unfinished hand edits in the documents during a run: the reader gets them as they are. `README` and other files stay as they were in the parent commit, like the code: today's `README` may already describe the solution;
 - the snapshot gets an empty `git init`, which stops the harness from loading `AGENTS.md` or `CLAUDE.md` from parent directories. No installed dependencies: the reader builds a plan, it does not execute it;
 - the reader: Claude Code `claude -p --restricted` with only `Read`, `Grep`, `Glob` and no MCP servers; Codex `codex exec -s read-only` with every MCP server, plugin and app turned off; OpenCode `opencode run --pure` with the `docs-reader` agent, whose permissions deny everything but reading, MCP tools included. The prompt is the installed `docs-reader`, the task goes through stdin;
 - it writes `rt-<N>-plan.md` and `rt-<N>-log.md` to the run directory and prints a three-line summary.
 
 Non-zero exit or "plan EMPTY" → show the human the summary and `rt-<N>-log.md`; do not guess. A plan that cites files outside the snapshot, the history, a tracker or external docs is invalid: note why in `reader-tests.md` and rerun.
 
-The user's global instructions (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.config/opencode/AGENTS.md`) cannot be switched off this way. If they are about this project, ask the human to move them aside for the test.
+The user's global instructions may still reach the reader: Codex loads `~/.codex/AGENTS.md`, OpenCode `~/.config/opencode/AGENTS.md`; whether `claude -p --restricted` loads `~/.claude/CLAUDE.md` is not documented. If they are about this project, ask the human to move them aside for the test.
 
-No `node`, or the harness CLI is not in PATH → do not play the reader yourself: you have seen the docs and the history. Run the script with `--snapshot-only` (it prints the snapshot path) and ask the human to start a new agent session with its working directory set to that path, paste the `docs-reader` prompt and the task, and save the answer to `rt-<N>-plan.md`.
+Your harness is not `claude`, `codex` or `opencode`, its CLI is not in PATH, or there is no `node` → do not play the reader yourself: you have seen the docs and the history. Run the script with `--snapshot-only` (it prints the snapshot path) and ask the human to start a new agent session with its working directory set to that path, paste the `docs-reader` prompt and the task, and save the answer to `rt-<N>-plan.md`.
 
 ## Step 4. Gaps
 

package/skills/docs-check/scripts/reader-run.mjs

@@ -2,20 +2,23 @@
 // docs-check steps 2–3: a history-free snapshot outside the repository and a fresh reader started as a
 // separate process of your harness. Works the same from bash, PowerShell and cmd; needs git and Node 18+.
 //
-//   node <skills>/docs-check/scripts/reader-run.mjs <run dir> <N> --harness claude|codex|opencode [--reader <path>]
+//   node <skills>/docs-check/scripts/reader-run.mjs <run dir> <N> --harness claude|codex|opencode [--reader <path>] [--timeout-min <m>]
 //   node <skills>/docs-check/scripts/reader-run.mjs <run dir> <N> --snapshot-only
 //
 // <run dir> holds tasks.json: { "tasks": [ { "n": 1, "parent": "<hash>", "task": "<wording>" } ] }.
 // Writes rt-<N>-plan.md (the reader's answer) and rt-<N>-log.md there; prints a short summary.
+// --timeout-min stops the reader after that many minutes (default 12).
 
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { execFileSync, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
 
 const a = parseArgs(process.argv.slice(2));
 if (a.help || a._.length < 2) {
-  console.log(fs.readFileSync(new URL(import.meta.url), 'utf8').split('\n').slice(1, 10).map(l => l.replace(/^\/\/ ?/, '')).join('\n'));
+  const src = fs.readFileSync(new URL(import.meta.url), 'utf8').split('\n').slice(1);
+  console.log(src.slice(0, src.findIndex(l => !l.startsWith('//'))).map(l => l.replace(/^\/\/ ?/, '')).join('\n'));
   process.exit(a.help ? 0 : 1);
 }
 
@@ -26,15 +29,21 @@ const spec = JSON.parse(read(path.join(RUN, 'tasks.json'), 'no tasks.json in the
 const task = (spec.tasks || []).find(t => Number(t.n) === N) || die(`tasks.json has no task n=${N}`);
 if (!task.parent || !task.task) die(`task ${N} has no parent or task`);
 
-const SNAPS = path.join(os.tmpdir(), `agent-docs-check-${path.basename(ROOT)}`);
+// The path hash keeps two repositories with the same folder name apart.
+const SNAPS = path.join(os.tmpdir(), `agent-docs-check-${path.basename(ROOT)}-${createHash('sha1').update(ROOT).digest('hex').slice(0, 8)}`);
 const SNAP = path.join(SNAPS, `rt-${N}`);
 const TIMEOUT_MS = Number(a['timeout-min'] || 12) * 60 * 1000;
 const win = process.platform === 'win32';
 
-// Documents the kit builds; kit-installed paths and its run files never reach the reader.
-const kitPaths = read(path.join(ROOT, '.agent-docs-bootstrap'), '', true).split('\n').filter(l => l && !l.startsWith('version='));
+// Documents the kit builds; kit-installed paths and its run files never reach the reader. The marker is committed
+// and could hold any line, so only lines shaped like an installed path count (a line `docs` would hide every document).
+const KIT_DIRS = ['.claude/skills', '.claude/agents', '.agents/skills', '.codex/agents', '.opencode/agents', '.opencode/commands'];
+const kitPaths = read(path.join(ROOT, '.agent-docs-bootstrap'), '', true).split('\n').map(l => l.trim())
+  .filter(l => KIT_DIRS.includes(path.posix.dirname(l)) && /^[a-z0-9-]+(\.md|\.toml)?$/.test(path.posix.basename(l)));
 const isKit = (p) => p === '.agent-docs-bootstrap' || p.startsWith('docs/agents/') || kitPaths.some(k => p === k || p.startsWith(k + '/'));
-const isDoc = (p) => /(^|\/)(AGENTS\.md|CONTEXT[^/]*\.md)$/.test(p) || p === 'CLAUDE.md' || p.startsWith('docs/');
+// README and other files stay as they were in the parent commit, like the code: they are the project as it was,
+// not the documents under test, and today's README may already describe the solution.
+const isDoc = (p) => /(^|\/)(AGENTS\.md|CLAUDE\.md|CONTEXT[^/]*\.md)$/.test(p) || p.startsWith('docs/');
 
 // ---------- snapshot: the parent's code without documents, today's documents from the working tree on top
 fs.rmSync(SNAP, { recursive: true, force: true });
@@ -97,7 +106,9 @@ child.stdin.end(input);
 let out = '', err = '';
 child.stdout.on('data', d => { out += d; });
 child.stderr.on('data', d => { err += d; });
-const timer = setTimeout(() => { err += `\nstopped after ${TIMEOUT_MS / 60000} min`; child.kill(); }, TIMEOUT_MS);
+// With shell: true on Windows, child.kill() stops only cmd.exe; taskkill /T takes the CLI with it.
+const stop = () => win ? spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' }) : child.kill();
+const timer = setTimeout(() => { err += `\nstopped after ${TIMEOUT_MS / 60000} min`; stop(); }, TIMEOUT_MS);
 child.on('error', e => die(`${cmd} did not start: ${e.message}`));
 child.on('close', code => {
   clearTimeout(timer);

package/skills/third-party/grill-with-docs/SKILL.md

@@ -1,7 +0,0 @@
----
-name: grill-with-docs
-description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
-disable-model-invocation: true
----
-
-Call the Skill tool twice, for "grilling" and "domain-modeling".

package/skills/third-party/grill-with-docs/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Grill with Docs"
-  short_description: "Grill a design and write its docs"
-policy:
-  allow_implicit_invocation: false

package/skills/third-party/writing-for-agents/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Matt Pocock
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.