@baldurpan/create-ai-workflow 0.5.1 → 0.6.0

package/README.md

@@ -40,7 +40,7 @@ starting point — nothing has to be looked up first.
 | `/feature-close` | retires a feature: a `history.md` row, a `git mv` into `archive/`, and a reviewed reference sweep |
 | `/orchestrate` | one ad-hoc, commit-sized change through the same gates — no entry, no ledger |
 | `/prototype` | a throwaway HTML/CSS mockup under `prototypes/`, to settle a layout question before a plan commits to it — no gates, no application code |
-| `/onboard` | fills in your own stubs, adopting what the repo already documented and running each verification command before writing it down |
+| `/onboard` | fills in your own stubs, adopting what the repo already documented, indexing where it documents itself, and running each verification command before writing it down |
 
 ## What makes it different
 
@@ -63,6 +63,13 @@ the agent does — and every command that lands code reads it before closing out
 commits*: a tool installed into a repository it knows nothing about does not get to write that
 repository's history unasked. Branches, pushes and pull requests are outside the workflow entirely.
 
+**Documentation is part of the change.** A plan starts by finding where the project explains itself —
+`context/stack.md` holds that index, `/onboard` fills it by sweeping the tree and asking what is published
+elsewhere — and every plan carries a §7 naming what the feature makes untrue there. Each row is assigned to
+a phase, and its path goes on that phase's `Files:` line, so the README lands with the rename rather than
+after it. Docs are the one output with no gate behind them: nothing fails when a page keeps describing a
+flag that no longer exists.
+
 **A finding outlives the session that found it.** A reviewer `FAIL` or a capped gate is written to
 `context/findings.md` *before* the loopback, so it survives the conversation ending. An open `P0`/`P1`
 blocks its phase from being marked `done` and blocks `/feature-close`.
@@ -109,6 +116,22 @@ npx @baldurpan/create-ai-workflow update --force     # back up edited files (.ba
 | missing | restores |
 | not in the manifest | nothing — it cannot reach it |
 
+**Run `/onboard` after an update.** That last row is the whole reason: a new version's tool-owned files can
+expect something of a project-owned one — a section of `context/stack.md` that every plan now reads, a
+`context/git.md` older than the file itself — and the updater is forbidden to write either. So it ends by
+naming each gap and stops:
+
+```
+Next
+  ! context/stack.md has no "Documentation" section — this version's stub has one
+  ! context/git.md is missing — a stub is project-owned, so update cannot write one
+  Run /onboard in your agent. It is re-runnable, and it is the only thing that
+  reaches these files — the commands above now read them.
+```
+
+It is a note, not a failure — the exit code is the conflict count's to set. A tool that failed an update
+over the shape of a file it may not touch would be calling someone else's business its own breakage.
+
 ## Standards
 
 `context/standards/` ships a vendored default, and `context/standards/README.md` holds a

package/dist/check/markdown.js

@@ -6,6 +6,13 @@
 export function stripComments(text) {
     return text.replace(/<!--[\s\S]*?-->/g, (match) => match.replace(/[^\n]/g, ' '));
 }
+/**
+ * Blank out fenced code blocks, preserving line count. A `##` inside a fence is an illustration — the
+ * stubs sketch a directory layout in one — not a heading of the document.
+ */
+export function stripFences(text) {
+    return text.replace(/^```[\s\S]*?^```/gm, (match) => match.replace(/[^\n]/g, ' '));
+}
 function splitCells(line) {
     return line
         .trim()

package/dist/cli.js

@@ -10,7 +10,8 @@ const USAGE = `${bold('create-ai-workflow')} — overlay a tiered planning workf
 ${bold('Usage')}
   npx @baldurpan/create-ai-workflow                      install into this repository
   npm  create @baldurpan/ai-workflow                     the same thing, shorter
-  npx @baldurpan/create-ai-workflow update               replace the tool-owned files with this version
+  npx @baldurpan/create-ai-workflow update               replace the tool-owned files with this version,
+                                                         and name what only ${cyan('/onboard')} can fill
   npx @baldurpan/create-ai-workflow standards add <url>  swap context/standards/ for a git repository
   npx @baldurpan/create-ai-workflow check                report structural breakage; never writes
 

package/dist/commands/update.js

@@ -2,9 +2,10 @@ import { copyFileSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'no
 import path from 'node:path';
 import { apply as applyBlock, BlockConflictError, inspect } from "../agents-block.js";
 import { AGENTS_BLOCK_KEY, DEFAULT_ADAPTERS, STANDARDS_PREFIX, agentsBlockBody, managedFiles, renderManaged, } from "../layout.js";
-import { bold, cyan, dim, green, info, red, UserError, warn, yellow } from "../log.js";
+import { bold, cyan, dim, green, info, red, UserError, yellow } from "../log.js";
 import { readManifest, writeManifest } from "../manifest.js";
 import { exists, hash, packageVersion } from "../paths.js";
+import { stubGaps } from "../stubs.js";
 const LABEL = {
     replace: green('update '),
     restore: green('restore'),
@@ -138,9 +139,11 @@ export function update(root, options) {
         info();
         info(`${yellow('!')} the bundled standards moved: ${dim(installedRef.slice(0, 8))} → ${dim(bundledRef.slice(0, 8))}`);
     }
+    const gaps = stubGaps(root);
     if (options.dryRun) {
         info();
         info(dim('--dry-run: nothing was written.'));
+        reportStubGaps(gaps);
         return conflicts.length > 0 && !options.force ? 1 : 0;
     }
     if (conflicts.length > 0 && !options.force) {
@@ -201,8 +204,30 @@ export function update(root, options) {
     writeManifest(root, manifest);
     info();
     info(`${green('done')} ${written} file${written === 1 ? '' : 's'} written. Review the diff — nothing was committed.`);
+    reportStubGaps(gaps);
     return 0;
 }
+/**
+ * What this version's stubs expect and the install does not have. Printed last, because it is the only
+ * part of an update that needs a person: everything above it has already happened, and nothing here can.
+ *
+ * This is a note, never an error — the exit code is the conflict count's to set. A tool that fails an
+ * update over the shape of a file it is forbidden to touch would be reporting someone else's business as
+ * its own breakage.
+ */
+function reportStubGaps(gaps) {
+    if (gaps.length === 0)
+        return;
+    info();
+    info(bold('Next'));
+    for (const gap of gaps) {
+        info(gap.section === undefined
+            ? `  ${yellow('!')} ${gap.dest} ${dim('is missing — a stub is project-owned, so update cannot write one')}`
+            : `  ${yellow('!')} ${gap.dest} ${dim(`has no "${gap.section}" section — this version's stub has one`)}`);
+    }
+    info(`  Run ${cyan('/onboard')} in your agent. ${dim('It is re-runnable, and it is the only thing that')}`);
+    info(`  ${dim('reaches these files — the commands above now read them.')}`);
+}
 function describeBad(state) {
     return state.kind === 'duplicate'
         ? `${state.count} ai-workflow blocks in AGENTS.md — delete the extra one`

package/dist/layout.js

@@ -93,15 +93,22 @@ export function managedFiles(adapters) {
     }
     return files;
 }
-/** Project-owned files. Written once, at install, and never reachable by `update`. */
+/**
+ * Project-owned files. Written once, at install, and never reachable by `update`.
+ *
+ * `onboard` marks the four whose content a person supplies, through `/onboard`. The other three are
+ * written by the workflow as it runs — a roadmap entry, a history row, a finding — so a question about
+ * their shape is `check`'s, and pointing at `/onboard` for one of them would name a command that does not
+ * touch it.
+ */
 export const STUBS = [
-    { source: 'stubs/stack.md', dest: 'context/stack.md' },
-    { source: 'stubs/verify.md', dest: 'context/verify.md' },
-    { source: 'stubs/executors.md', dest: 'context/executors.md' },
-    { source: 'stubs/git.md', dest: 'context/git.md' },
-    { source: 'stubs/roadmap.md', dest: 'context/roadmap.md' },
-    { source: 'stubs/history.md', dest: 'context/history.md' },
-    { source: 'stubs/findings.md', dest: 'context/findings.md' },
+    { source: 'stubs/stack.md', dest: 'context/stack.md', onboard: true },
+    { source: 'stubs/verify.md', dest: 'context/verify.md', onboard: true },
+    { source: 'stubs/executors.md', dest: 'context/executors.md', onboard: true },
+    { source: 'stubs/git.md', dest: 'context/git.md', onboard: true },
+    { source: 'stubs/roadmap.md', dest: 'context/roadmap.md', onboard: false },
+    { source: 'stubs/history.md', dest: 'context/history.md', onboard: false },
+    { source: 'stubs/findings.md', dest: 'context/findings.md', onboard: false },
 ];
 export const STUB_DIRS = ['context/drafts', 'context/plans', 'context/archive'];
 export function readTemplate(source) {

package/dist/stubs.js

@@ -0,0 +1,51 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { stripComments, stripFences } from "./check/markdown.js";
+import { readTemplate, STUBS } from "./layout.js";
+import { exists } from "./paths.js";
+/**
+ * The `##` headings of a markdown document, in order.
+ *
+ * Fenced blocks and HTML comments are blanked first: the stubs ship their examples commented out and
+ * `stack.md` carries a fenced layout sketch, and a heading inside either is an illustration rather than a
+ * section of the document.
+ */
+export function sections(text) {
+    return [...stripComments(stripFences(text)).matchAll(/^## +(.+?)\s*$/gm)].map((m) => m[1]);
+}
+/** Backticks, case and run-together whitespace are formatting, not identity. */
+function normalise(heading) {
+    return heading.replace(/`/g, '').replace(/\s+/g, ' ').trim().toLowerCase();
+}
+/**
+ * What this version's stubs expect that the install does not have — a stub file that is missing outright,
+ * or one whose sections this version has added to.
+ *
+ * `update` reports this and writes nothing. Stubs are project-owned and deliberately absent from the
+ * manifest, so nothing here can reach them; `/onboard` is the only thing that fills one, and until it runs
+ * a command can be pointed at a section of a file that does not have it.
+ *
+ * **Only the stubs `/onboard` fills are examined.** `roadmap.md`, `history.md` and `findings.md` are
+ * written by the workflow rather than by a person, so their shape is `check`'s question — and a report
+ * that named `/onboard` for a file that command never opens would be sending someone somewhere useless.
+ *
+ * A section the user deleted on purpose and one this version added look identical from here, and both are
+ * reported. Telling them apart would mean recording stub state in the manifest, which is the one place the
+ * design keeps free of project-owned files — and the fix is the same either way.
+ */
+export function stubGaps(root) {
+    const gaps = [];
+    for (const stub of STUBS.filter((s) => s.onboard)) {
+        const full = path.join(root, stub.dest);
+        if (!exists(full)) {
+            gaps.push({ dest: stub.dest });
+            continue;
+        }
+        const have = new Set(sections(readFileSync(full, 'utf8')).map(normalise));
+        for (const section of sections(readTemplate(stub.source))) {
+            if (!have.has(normalise(section)))
+                gaps.push({ dest: stub.dest, section });
+        }
+    }
+    return gaps;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baldurpan/create-ai-workflow",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Overlay a tiered planning workflow — roadmap, plans, phase ledgers, verification gates — onto an existing repository, for coding agents.",
   "keywords": [
     "ai",

package/templates/blocks/agents-block.md

@@ -17,7 +17,7 @@ the standing rules, and every command cites it rather than restating it.
 
 | Read | For |
 |---|---|
-| [`context/stack.md`](context/stack.md) | runtime, layout, conventions |
+| [`context/stack.md`](context/stack.md) | runtime, layout, conventions, and where this project documents itself |
 | [`context/standards/README.md`](context/standards/README.md) | engineering standards — load per its conditional table |
 | [`context/verify.md`](context/verify.md) | the real lint / typecheck / build / test commands — the only file that names one |
 | [`context/git.md`](context/git.md) | who commits, and at what granularity — read it before closing out any change |
@@ -31,5 +31,8 @@ the working tree and the user commits it.
 
 **An open `P0` or `P1` in [`context/findings.md`](context/findings.md) blocks its phase from being `done`.**
 
+**Documentation is part of the change.** Whatever a change makes untrue in this project's own docs is fixed
+by the phase that makes it untrue, not by a follow-up.
+
 **Require evidence, not assertion.** A claim about what a file contains needs the file read, not recalled —
 yours as much as a subagent's.

package/templates/claude/agents/planner.agent.md

@@ -33,9 +33,13 @@ The default shape below applies only when the brief names none.
    generic principles.
 2. **Read the project.** `context/stack.md` for what this repo is; `context/verify.md` for how it proves
    itself. Search the codebase and find the patterns that already exist.
-3. **Verify externals.** Check documentation for every library and API involved. Cite what you confirmed.
-4. **Consider.** Edge cases, error states, and implicit requirements the request did not mention.
-5. **Draft.** Say *what* needs to happen, not *how* to code it.
+3. **Find the documentation.** `context/stack.md`'s Documentation section says where this project explains
+   itself. If it is empty, sweep for it — READMEs, `docs/`, a docs site in the tree, an API reference, a
+   changelog, help text in the code. Report what the change would make untrue there, per surface. An empty
+   index is not evidence that there are none.
+4. **Verify externals.** Check documentation for every library and API involved. Cite what you confirmed.
+5. **Consider.** Edge cases, error states, and implicit requirements the request did not mention.
+6. **Draft.** Say *what* needs to happen, not *how* to code it.
 
 ## Default output shape
 

package/templates/context/README.md

@@ -32,7 +32,7 @@ generated "current state" file — hand-editing a ledger row changes every comma
 | [`plan-template.notes.md`](plan-template.notes.md) | what goes in each section of that skeleton | tool |
 | [`roles/coder.md`](roles/coder.md) | the coder system prompt — names no commands | tool |
 | [`standards/`](standards/README.md) | engineering standards, loaded per that README's conditional table | tool* |
-| [`stack.md`](stack.md) | this project's runtime, layout, conventions, and an index of your own files | project |
+| [`stack.md`](stack.md) | this project's runtime, layout, conventions, where it documents itself, and an index of your own files | project |
 | [`verify.md`](verify.md) | this project's real lint / typecheck / build / test commands | project |
 | [`executors.md`](executors.md) | how this project dispatches a coder and a reviewer | project |
 | [`git.md`](git.md) | who commits the work an agent produces, and at what granularity | project |
@@ -71,6 +71,11 @@ hash, `update` walks that manifest, and a project-owned file is not in it — so
 
 `update` prints both columns when it runs. A visible boundary beats a documented one.
 
+The boundary has a cost, and `update` prints that too: a new version's tool-owned files can expect
+something of a project-owned one — a section of [`stack.md`](stack.md), a `git.md` that predates the
+file — and nothing in the updater may write it. So it names each gap under **Next** and stops there.
+Closing them is `/onboard`, which is re-runnable for exactly this reason.
+
 **Anything else you add under `context/` is yours forever**, by the same property — `context/decisions.md`,
 `context/glossary.md`, `context/ops-notes.md` all survive by default, with no feature required to protect
 them. Index your own additions in [`stack.md`](stack.md), not here: this file is replaced on every update,
@@ -80,3 +85,7 @@ so a line you add to it is a line you lose.
 
 Planning artifacts live in `context/`, wherever else your docs live. Product specs, API references and
 anything else written for humans or library consumers stay where this project already keeps them.
+
+They are not out of scope for being elsewhere, though. [`stack.md`](stack.md)'s Documentation section
+indexes where "elsewhere" is, so a plan can name what a feature makes untrue there and a phase can carry
+the fix — the standing rule is in [`workflow.md`](workflow.md).

package/templates/context/plan-template.md

@@ -63,10 +63,22 @@ differently-shaped one nearby is a decoy that gets read by mistake.
 
 **Done when:** <a condition checkable against the repo>
 
-## 7. Verification
+## 7. Documentation
+
+<What this feature makes untrue in the project's own documentation. Start from the Documentation index in
+[`../stack.md`](../stack.md), and from the repository itself if that index is empty.>
+
+| Surface | What changes | Phase |
+|---|---|---|
+| <path, or the URL of a docs site> | <what it claims now that this makes wrong, or what it will not say yet> | <n> |
+
+<If nothing changes, name the surfaces you checked and why none of them describe this. An empty section
+reads as "not checked", and nothing downstream can tell those apart.>
+
+## 8. Verification
 
 <How to prove the feature works, beyond `context/verify.md` passing.>
 
-## 8. Open questions
+## 9. Open questions
 
 - <Anything the plan could not settle. An honest gap is worth more than an invented decision.>

package/templates/context/plan-template.notes.md

@@ -36,11 +36,19 @@ repo match the ledger" has no answer. A phase is a **commit-sized unit of work w
 not a category of activity — "grammar plus container support for the new token" is a phase; "testing" is
 not.
 
-**§7 Verification** — how to prove the feature works, beyond [`verify.md`](verify.md) passing. Commands to
+**§7 Documentation** — every place this project explains itself that the feature makes wrong, out of date
+or incomplete. The surfaces come from [`stack.md`](stack.md)'s Documentation index, and from a sweep of the
+repository when that index is empty — an index nobody filled in is not evidence that there are no docs.
+**Each row names the phase that carries it, and that phase's `Files:` line names the same path.** A
+documentation row with no phase is a follow-up nobody does. If the feature genuinely changes nothing, the
+section says which surfaces were checked and why: *"no surface describes this"* is an answer, and it is
+distinguishable from silence only when it is written down.
+
+**§8 Verification** — how to prove the feature works, beyond [`verify.md`](verify.md) passing. Commands to
 run by hand, files to eyeball, numbers to compare against §1's measurements. Anything that belongs to the
 project's standing verification stack goes in `verify.md` instead, not here.
 
-**§8 Open questions** — what the plan could not settle. Do not paper over them.
+**§9 Open questions** — what the plan could not settle. Do not paper over them.
 
 ## Standing rules
 
@@ -48,7 +56,8 @@ project's standing verification stack goes in `verify.md` instead, not here.
   [`roadmap.md`](roadmap.md), phase status in §6.1, retired outcomes in [`history.md`](history.md) — one
   place each. `check` fails a plan that grows one.
 - **`/feature-plan` produces a reviewable skeleton plus open questions**, not a finished plan of record.
-  §1, §3 and §6.1 are the sections research can usefully draft. §4 and §5 usually arrive as open questions.
+  §1, §3, §6.1 and §7 are the sections research can usefully draft — §7 in particular is a search, not a
+  judgement call. §4 and §5 usually arrive as open questions.
 - **Cite by §-number, not by line number.** Source comments cite plan sections; line numbers rot on the
   first edit, and a §-number survives the move into `archive/`.
 - **Never mark a phase `done` in a plan that has not been executed.** Every phase in a new plan is

package/templates/context/workflow.md

@@ -96,6 +96,20 @@ policy, resolves by committing on its own every phase. That is a call about some
 it is a written answer rather than an inference. Branching and pushing are outside it: nothing here creates
 a branch, pushes, or opens a pull request under either answer.
 
+### Documentation is part of the change
+
+> **Find where this project documents itself before planning — the Documentation index in
+> [`stack.md`](stack.md), and the repository itself when that index is missing or empty. Whatever a change
+> makes untrue there is fixed by the phase that makes it untrue, not by a follow-up.**
+
+Documentation is the one output with no gate behind it. Nothing fails when a README goes on describing a
+flag that was renamed, so the drift is invisible until someone follows the old instructions and it is not
+invisible to them. `/feature-plan` writes the affected surfaces into the plan's §7, each assigned to a
+phase, and that phase's **Files:** line carries the path like anything else it touches.
+
+*"Nothing here describes this feature"* is a legitimate answer, and it names the surfaces that were
+checked. Saying nothing is not that answer.
+
 ### Never transcribe a credential
 
 > **A DSN, token or key is described and pointed at the secret store, never copied into a tracked file.**

package/templates/skills/feature-implement/SKILL.md

@@ -38,7 +38,8 @@ detailed it looks.
 This is the step that used to be structural: `/feature-plan` stopped and you typed a second command. It is
 explicit here now, or it is lost.
 
-1. **Surface the plan's §8 Open questions and require an acknowledgement.** Do not proceed on silence.
+1. **Surface the plan's Open questions section and require an acknowledgement.** Do not proceed on
+   silence. Cite it by name — a plan written against an earlier template numbers its sections differently.
 2. **Re-check that the files the plan cites still exist.** A plan drafted a month ago against a
    since-changed tree is a state that can now exist and could not before. Name anything that has moved.
 3. **Check the one-active-feature rule** in [`context/workflow.md`](../../../context/workflow.md). If
@@ -84,6 +85,12 @@ under either answer in [`context/git.md`](../../../context/git.md). Never commit
 
 Read the phase's §6.2 sub-section: its scope, its **Files:**, and what `done` means for it.
 
+**The plan's Documentation rows assigned to this phase are part of this phase**, not a follow-up — their
+paths are on the same **Files:** line as the code. Per the standing rule in
+[`context/workflow.md`](../../../context/workflow.md), whatever this phase makes untrue is fixed by this
+phase. If the work turned out differently from the plan and made something *else* untrue — a README the
+plan never listed — fix that too and say so; the sweep happened before the code existed.
+
 Delegate to a coder per [`context/executors.md`](../../../context/executors.md) if one is configured;
 otherwise implement in-host. The coder's system prompt is
 [`context/roles/coder.md`](../../../context/roles/coder.md).
@@ -137,7 +144,8 @@ blocked by definition), then escalate to the user with the current state and the
 
 The row is part of the same change as the work — never a separate step afterwards:
 
-- **All of the phase's scope landed and both gates passed** → `done`.
+- **All of the phase's scope landed and both gates passed** → `done`. Its documentation rows are part of
+  that scope: a phase whose doc update has not landed has not landed.
 - **Some landed** → stays `in progress`, Note rewritten to name exactly what remains.
 - **A gate hit its cap, or something external blocks it** → `blocked`, with the blocker in the Note.
 

package/templates/skills/feature-plan/SKILL.md

@@ -98,6 +98,13 @@ planner's own default shape:
   acceptance-criteria — a per-phase artifact, not a plan — and you will throw it away.
 - Pointers to `context/stack.md`, `context/standards/README.md` (load per its conditional table) and
   `context/verify.md`. Cite the paths; do not paste the files in. Anything reading this repo can open them.
+- **Where this project documents itself, and what this feature makes untrue there.** Start from the
+  Documentation section of `context/stack.md`. **If that section is empty, missing, or names less than the
+  tree plainly holds, sweep for it** — the root `README`, a `README` in each package, `docs/`, a docs site
+  or landing page in the repository, an API reference or OpenAPI document, a changelog, help text and
+  format comments that live in the code. Ask the user about anything hosted elsewhere: a wiki, a docs site
+  built from another repo, a published reference. **An index nobody filled in is not evidence that there
+  are no docs**, and a plan that assumes it is ships the drift.
 - **Cite file paths and command output for every claim about the current codebase.** Anything unverified is
   an open question, not an assertion.
 - Phases are **commit-sized units with checkable outcomes**, each with a real `Depends on` value and a
@@ -111,7 +118,11 @@ Fill in the template's shape. Then:
 - Date it and point its header at the roadmap entry.
 - **No `**Status:**` header.** Feature status lives in `roadmap.md`, phase status in the ledger. A document
   that claims its own status is a copy that goes stale.
-- Fill in **§8 Open questions** honestly. An honest gap is worth more than an invented decision.
+- Fill in **§7 Documentation** from what the sweep found: one row per surface the feature changes, each
+  assigned to the phase that carries it, **and that phase's `Files:` line names the same path.** A
+  documentation row with no phase is a follow-up nobody does. If nothing changes, say which surfaces you
+  checked and why none of them describe this — that is an answer, and leaving the section blank is not.
+- Fill in **§9 Open questions** honestly. An honest gap is worth more than an invented decision.
 - Every phase is `not started`.
 
 ### 6. Update the roadmap entry
@@ -129,7 +140,8 @@ own; discarding it over a marker would undo the point of the split.
 
 ### 7. Report and stop
 
-State the document path, the phase count, and the open questions. Then say plainly that **what you produced
+State the document path, the phase count, the documentation surfaces §7 commits to updating, and the open
+questions. Then say plainly that **what you produced
 is a reviewable skeleton plus open questions, not a finished plan of record** — the value is the structure
 and the research. Name the next step: the user reviews and edits the plan, and `/feature-implement` runs it
 once they are satisfied.

package/templates/skills/onboard/SKILL.md

@@ -9,6 +9,11 @@ Fills the project-owned stubs the installer deliberately left empty, and folds w
 already documented into them. **Re-runnable** — run it again after the stack changes, and it re-proposes
 against what is there now.
 
+**Run it after an `update`, too.** The updater replaces tool-owned files only; the stubs are project-owned
+and it cannot reach them, so a section a new version's stub gained arrives only through this command. The
+update prints the gaps it found under **Next** — every one of them is this command's work. Until it runs,
+a command can be pointed at a section of a file that does not have it.
+
 **Asking is not guessing.** The installer could have detected a test command and written it in; that is
 exactly how a file ends up naming a command that has never run. This command asks, and where it can, it
 *checks*.
@@ -22,7 +27,7 @@ Read [`context/workflow.md`](../../../context/workflow.md) for the tier model.
 | [`context/verify.md`](../../../context/verify.md) | the real Lint / Typecheck / Build / Test commands — **only ones that exited 0** |
 | [`context/executors.md`](../../../context/executors.md) | how this project dispatches a coder and a reviewer |
 | [`context/git.md`](../../../context/git.md) | who commits the work, and at what granularity |
-| [`context/stack.md`](../../../context/stack.md) | runtime, layout, conventions |
+| [`context/stack.md`](../../../context/stack.md) | runtime, layout, conventions, and the index of where this project documents itself |
 | [`AGENTS.md`](../../../AGENTS.md) | pruned, on confirmation, of what moved into those four. The region between the `ai-workflow` markers is never touched |
 
 Show every proposed edit before writing it, and **do not commit.** The user reviews and commits.
@@ -45,6 +50,7 @@ Break what you read into claims — a paragraph, a table row, a bullet — and p
 | A claim about | Goes to |
 |---|---|
 | what the project is, its layout, its conventions | `context/stack.md` |
+| where the project's own documentation lives, or how it is published | `context/stack.md`, its Documentation section |
 | a lint, typecheck, build or test command | a **candidate** for `context/verify.md` — Step 6 still has to run it |
 | how a coder or a reviewer is dispatched | `context/executors.md` |
 | a rule about who commits, or when work is committed | `context/git.md` |
@@ -69,6 +75,11 @@ old file is a candidate like any other and still has to run.
 
 On a re-run, a claim its destination file already states is already adopted. Say so in a line and move on.
 
+**If an `update` named a missing section** — `context/stack.md` with no Documentation section, a stub that
+is not there at all — add the heading in the shipped stub's order, then fill it through the step below that
+owns it. Do not rewrite what is already there to match a newer stub: the section is the part that is new,
+not the prose someone wrote about their own project.
+
 ## Step 2 — Coder dispatch
 
 Ask whether implementation runs **in-host** or is **offloaded** to an external coder CLI.
@@ -183,6 +194,23 @@ Start from what Step 1 routed here, show it back as a draft, and ask only for th
   that earns its keep; the rest is discoverable. Inherited prose is usually strongest here and weakest at
   describing layout, which drifts.
 
+Then fill in the **Documentation** section, which is the one every later plan reads:
+
+1. **Sweep the repository.** The root `README`, a `README` in every package, `docs/`, a docs site or
+   landing page built from this repo, an API reference or OpenAPI document, a changelog, a `man` page or
+   `--help` text that lives in the code, a comment that is the only description of a file format.
+2. **Ask what is published elsewhere** — a wiki, a hosted docs site built from another repository, a
+   support centre, a public API reference. Nothing in the tree can reveal those, and they are the surfaces
+   that rot longest without anyone noticing.
+3. **Ask which of them are actually maintained.** A directory nobody has touched in two years is worth
+   recording as exactly that; a plan can then say so instead of proposing an update to a dead file.
+4. **Write "none" if there is none.** An empty section reads as "nobody checked", and `/feature-plan`
+   cannot tell those apart — it sweeps the tree itself when the section is empty, which finds files but
+   never finds the docs site nobody mentioned.
+
+Say what this is for: every plan's §7 starts from this list, and whatever a feature makes untrue there is
+fixed by the phase that makes it untrue.
+
 Point out that anything else added under `context/` should be indexed in `stack.md`, not in
 `context/README.md`, which is tool-owned and replaced on update.
 

package/templates/skills/orchestrate/SKILL.md

@@ -45,6 +45,11 @@ A refusal here is the workflow working.
 
 Read `context/stack.md` and load `context/standards/README.md` per its conditional table.
 
+**Check that file's Documentation section, and the tree if it is empty.** If this change makes something
+there wrong — a README, a docs page, a changelog, help text in the code — the fix is part of this change,
+per the standing rule in [`context/workflow.md`](../../../context/workflow.md). A one-shot change is where
+that gets skipped most, because there is no plan holding the row.
+
 Delegate to a coder per [`context/executors.md`](../../../context/executors.md) if one is configured;
 otherwise implement in-host. The coder's system prompt is
 [`context/roles/coder.md`](../../../context/roles/coder.md). The brief **cites paths, it does not paste

package/templates/stubs/stack.md

@@ -25,6 +25,19 @@ What this project is, and what an agent has to know before touching it. Run `/on
      things deliberately kept separate, where local secrets live, what must never be run against
      production. -->
 
+## Documentation
+
+<!-- Every place this project explains itself, one line each: the path or URL, who reads it, and what kind
+     of change has to reach it. READMEs at the root and in each package, docs/, a docs site or landing page,
+     an API reference or OpenAPI document, a changelog, a wiki, help text that lives in the code, comments
+     that are the only description of a format.
+
+     Say which ones are actually maintained — a directory nobody has updated in two years is worth writing
+     down as that, rather than leaving the next reader to discover it.
+
+     If this project documents itself nowhere, write "none". An empty section reads as "nobody checked",
+     and a plan cannot tell those two apart. -->
+
 ## Also in `context/`
 
 <!-- Index anything you add under context/ here — decisions.md, glossary.md, ops-notes.md. Not in