Files

T

nntrivi2001 26b0fe53c7 feat(skills,pipelines): ask the user at the two points being wrong is cheap, and stop paying for reviews the diff does not need

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.

2026-09-18 10:21:03 +07:00

4.7 KiB

Raw Blame History

Documentation Map

Authoritative inventory of this repository's documentation surface: every doc that must be kept in sync, what each contains, and the stable anchors to grep for when placing an edit. Section line numbers drift — grep the anchor strings, don't trust line numbers.

Tier 1 — primary, always consider

`README.md` (English, canonical)

The source of truth most other docs mirror. Key sections:

Feature table — rows like **Kanban Board**, **Transcript Cache**, **Pre-Existing Session Detection**, **Continuous Project Sync**. Grep a neighboring row label.
Data-flow numbered list — bullets describing hook ingestion, the watchdog, periodic sweep, continuous sync. Grep Error detection watchdog / periodic server sweep.
Agent State Machine + Session State Machine — two mermaid stateDiagram-v2 blocks. Grep stateDiagram-v2.
Hook Events table — | Hook Type | Trigger | Dashboard Action |. Lists SessionStart…SessionEnd, plus synthetic Compaction, APIError, TurnDuration, ToolError, Interrupted. Grep ## Hook Events.
Configuration / Environment Variables table — | Environment Variable | Default | Description |. Grep DASHBOARD_PORT or DASHBOARD_HOST.

Translations

This build ships English only. README-VN.md, README-CN.md and README-KO.md were removed, as were the zh and ko UI locales — do not recreate them, and do not mirror a README change into a translation file. (The UI itself still ships en and vi locales under client/src/i18n/locales/ — those are strings, not docs, and are covered by the frontend section below.)

`ARCHITECTURE.md`

Module responsibility table — one row per source file (scripts/import-history.js, lib/transcript-cache.js, routes/hooks.js, server/index.js, …). Update the row whose file you changed. Grep the file path.
Data-flow + sequence diagrams, state machines, Continuous background sync prose block (grep Continuous background sync).
Event types line — grep | Event types |.
ERD / schema mermaid + event_type "PreToolUse|PostToolUse|Stop|etc".

`server/README.md`

Backend reference: routes table, Error Detection Watchdog / User-Interrupt (Esc) Recovery / Continuous Project Sync sections, Agent/Session lifecycle mermaid diagrams, Environment Variables bash block under ## Deployment. Update for any backend behavior, route, state, env var, or background service.

`client/README.md`

Frontend reference: component list, Event Types table (WebSocket broadcast message types like session_created, agent_updated), session/agent status TypeScript unions. Update for new WS message types or client-facing behavior. NOT needed for server-only changes the UI already renders generically.

`docs/HOOKS.md`

Per-hook deep reference (### 1. SessionStart … ### 8. SessionEnd), the awaiting_input_since overlay rules, the "User interrupts (Esc) — no hook fires" section, transcript-derived sync. Update for any hook semantics or state behavior.

`docs/DATABASE.md`

Schema reference: sessions / agents / events tables, column docs, status CHECK constraints, lifecycle mermaid diagrams. Update for schema or state-machine changes.

`docs/API.md`

REST API reference (endpoints, params, example responses). Update for route/response changes. Pair with server/openapi*.js (code, not docs).

`docs/PLUGINS.md`

Plugin/marketplace docs incl. an Event Types enumeration line — keep it in sync with the canonical event-type list.

`docs/I18N.md`

i18n architecture: Supported languages list, supportedLngs, the 15 namespaces. Update when adding a language or namespace. Client UI strings live in client/src/i18n/locales/{en,zh,vi}/*.json (code).

Tier 3 — situational

.env.example — every env var belongs here with a sane default + comment.
INSTALL.md, SETUP.md — install/run commands.
CLAUDE.md, AGENTS.md — agent working guides; update when commands, file locations, or workflows change.
docs/README.md — docs index; add a link when a new docs/*.md is created.

Consistency invariants

The event-type set must match across: README hook table, ARCHITECTURE Event types line, docs/PLUGINS.md. When adding one, grep the existing set (e.g. TurnDuration) across all and add everywhere it appears.
Env-var set must match across: README tables, server/README.md, .env.example, and any inline ARCHITECTURE mention.
State-machine diagrams are duplicated across README, server/README.md and docs/DATABASE.md. A transition change touches all of them.
Run scripts/doc-coverage.sh <term> to confirm a new identifier/var/event reached every doc that should mention it.

4.7 KiB Raw Blame History

Documentation Map

Tier 1 — primary, always consider

README.md (English, canonical)

Translations

ARCHITECTURE.md

server/README.md

client/README.md

docs/HOOKS.md

docs/DATABASE.md

docs/API.md

docs/PLUGINS.md

docs/I18N.md