nntrivi2001
26b0fe53c7
The `default` 8-node pipeline walked past its own intake: the node declared `agenthub stage intake`, a stage report with no work attached, so "intake" was a label the run passed through without ever asking a question. It now declares `/superpowers:brainstorming` (and detects it — that rule moves off `plan`), and both driving skills make the brainstorm mandatory, asked with AskUserQuestion and waited on rather than answered on the user's behalf. Three stops replace three silent slides: - After the plan is written and adversarially challenged, it goes to the USER for approval. Implementation does not start without it, and work that turns out to need a different approach comes back for a fresh one. - Review picks its reviewers from `git diff --name-only`: Claude Code's own `code-review` always, a domain reviewer only for a layer the diff actually touched, and — new — only once the change is big enough to have seams. Three agents re-reading twenty lines buys one opinion at three times the tokens, on every fix-loop lap. Review is also a loop now: it ends on a clean pass over the current diff, not on one pass having happened. - The gate asks the user to accept before anything is claimed done (and in the lane pipeline, before the PR is published — publishing is outward-facing). A NO-GO re-enters by SIZE: a defect goes back to implement, a wrong approach back to plan. Nothing carries a NO-GO forward with a note about it. Also here, from a real stall seen on a lane: `ship-feature` had no waiting rule at all, and a session at the gate invented one with `ScheduleWakeup` — a /loop-only primitive that paces nothing here and is refused outright when `auto` mode cannot reach its safety classifier. The rule the lane skill already had now exists in both. Cost, measured in what each agent is actually for: the suite run leaves its agent (nothing is judged, so nothing is delegated — an agent there buys a second model's tokens to read output the session can read for free), and `backend-reviewer` drops from opus to sonnet like its frontend twin; both read a scoped diff against a fixed checklist, and the senior gate above them is still opus. Skill bugs found in the same sweep: doc-map told agents not to recreate the removed translations and then, three lines later, to mirror every README change into them; the docs mapping still carried `+VN+CN` and the punctuation left by their removal; Procedure jumped 2 → 6; Verify required `scripts/doc-coverage.sh`, which does not exist in this repo.
6.0 KiB
6.0 KiB
name, description
| name | description |
|---|---|
| update-project-docs | MANDATORY for every coding agent (Claude Code, Codex, or any other) — keep this repository's documentation in sync after any change to behavior, configuration, interfaces, events, schema, or features. Use automatically (without being asked) at the end of ANY change-set that adds or alters an env var, event type, hook behavior, session/agent state transition, API route or response shape, DB schema, WebSocket message, MCP tool, CLI command, or user-facing feature — and whenever the user asks to "update the docs / README / architecture". Knows the full doc surface (README, ARCHITECTURE, server/client READMEs, docs/*) and which docs each kind of change touches. |
Update Project Docs
This repository keeps a large doc set and docs drift silently, because one change often belongs in several files at once. This skill encodes which docs exist, which change-types touch which docs, and how to propagate consistently. This build ships English only — the translated READMEs, the wiki and the root landing page were removed; do not recreate them.
Authoritative inventory with exact section anchors lives in references/doc-map.md — read it when deciding where a specific change lands. The repo rule .claude/rules/docs-markdown.md ("update all affected docs together") is binding.
When to update (including without being asked)
Update docs in the same change-set (PR/commit) as the code, before claiming done — do not wait for the user to ask — whenever the change is observable from outside the module:
- New/changed env var → every env-var table +
.env.example. - New event type (e.g. an
events.event_typevalue) → every event-type list/table. - New/changed hook behavior or session/agent state transition → hook docs + every state-machine diagram.
- New/changed API route or response shape → API docs + route tables + OpenAPI.
- DB schema change (table/column/index) → database docs + ERD.
- New WebSocket message type → client/server WS docs.
- New MCP tool → MCP docs.
- New CLI command / script / renamed file referenced in docs → command lists + onboarding guides.
- New user-facing feature / page / background service → feature tables + architecture.
Do NOT auto-update for: pure internal refactors with no observable/interface/config change, test-only changes, comment/typo fixes, or work the user explicitly scoped as "no docs". When unsure whether a change is observable, check the mapping below; if it touches any row, update.
Change → docs mapping
| Change type | Docs to update |
|---|---|
| Env var | README.md (env table), ARCHITECTURE.md (inline), server/README.md, .env.example |
| Event type | README.md (hook-event table), ARCHITECTURE.md (Event types line), docs/PLUGINS.md, docs/DATABASE.md (if it enumerates types), plus the en/vi strings under client/src/i18n/locales/ if the type is rendered |
| Hook behavior / state transition | docs/HOOKS.md, the state-machine mermaid diagrams in README.md, server/README.md and docs/DATABASE.md, ARCHITECTURE.md (hooks.js row) |
| API route / response | docs/API.md, server/README.md (routes), ARCHITECTURE.md (routes row), server/openapi.js + server/openapi-extra/*.js (code), then regenerate openapi.yaml with npm run openapi:yaml |
| DB schema | docs/DATABASE.md, ARCHITECTURE.md (ERD/schema) |
| WebSocket message | client/README.md (Event Types), server/README.md |
| Feature / page / background service | README.md (feature table + data-flow list), ARCHITECTURE.md (module table), server/README.md or client/README.md |
| CLI command / script | README.md commands, CLAUDE.md / AGENTS.md, INSTALL.md / SETUP.md |
| New language | docs/I18N.md, client/src/i18n/locales/<xx>/*, client/src/i18n/index.ts (add to supportedLngs AND the resources map) |
Procedure
- Classify the change against the table above. A change can hit multiple rows (a new feature with a new env var hits both).
- Write the canonical version first — usually
README.mdand/orARCHITECTURE.md. Get the wording right there; it anchors everything else. - Area READMEs / docs/: update
server/README.md,client/README.md, and the relevantdocs/*.mdper the mapping. - Diagrams: when a state transition changes, edit every mermaid
stateDiagram-v2block that models it (they are duplicated across README, server/README and docs/DATABASE). Keep transition labels consistent.
Verify (do not skip)
- Coverage: grep the new term (env var / event type / identifier) across the docs the mapping flags —
grep -rn "<new-term>" README.md ARCHITECTURE.md server/README.md client/README.md docs/— and confirm each flagged doc actually shows a hit. Advisory, not mechanical: not every term belongs in every file, but a flagged doc with zero hits is a miss to fix. - Tables: markdown tables stay pipe-balanced (header column count == every row).
- Mermaid: each edited block still parses (valid
source --> target: label). - i18n: every new English string has a
vientry inclient/src/i18n/locales/vi/. - Format/tests: run
npm run format(orprettier --checkon touched files); for any code touched, run the verification fromCLAUDE.md(npm run test:server/test:client). - State exactly which docs were updated and which were intentionally skipped (with reason), mirroring the repo's verification policy.
Tips
- The fastest way to find where something already lives:
grep -n "<existing-neighbor-term>" <doc>(e.g. grep an adjacent env var to find the env table).references/doc-map.mdlists the stable anchors per file. - Parallelize independent doc edits across subagents when the change is large, but write the canonical
README.md/ARCHITECTURE.mdedit yourself first so every other file has a faithful source. - One language/area per subagent keeps edits reviewable and tables un-corrupted.