feat: Claude Code Monitor — lanes, pipelines and a merged workspace
Internal SmartGift build of a Claude Code monitoring dashboard. Lanes: a durable unit of parallel agent work, one per working directory, tracked across session restarts. Managed lanes are git worktrees the dashboard provisions and can reset or remove behind a three-check destroy guard and a counted preflight; adopted lanes are directories you already own and are never destroyable. Pipelines: a lane moves through pipeline stages. A stage the agent declares with evidence renders green; a stage inferred from the tool-event stream renders dashed amber and never counts as done. Detection is forward-only within a 30-minute window, and never writes the declared stage. Workspace: one page at /run with a lane grid, the selected lane's pipeline, and a full Claude console behind a disclosure.
This commit is contained in:
@@ -0,0 +1,63 @@
|
||||
---
|
||||
name: update-project-docs
|
||||
description: 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`](references/doc-map.md) — read it when deciding where a specific change lands. The repo rule [`.claude/rules/docs-markdown.md`](../../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_type` value) → 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`+VN+CN (hook-event table), `ARCHITECTURE.md` (Event types line), `docs/PLUGINS.md`, + i18n, `docs/DATABASE.md` (if it enumerates types) |
|
||||
| **Hook behavior / state transition** | `docs/HOOKS.md`, state-machine **mermaid** diagrams in `README.md`+VN+CN + `server/README.md` + `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` (code) |
|
||||
| **DB schema** | `docs/DATABASE.md`, `ARCHITECTURE.md` (ERD/schema) |
|
||||
| **WebSocket message** | `client/README.md` (Event Types), `server/README.md`, |
|
||||
| **MCP tool** | `mcp/README.md`, `docs/MCP.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
|
||||
|
||||
1. **Classify** the change against the table above. A change can hit multiple rows (a new feature with a new env var hits both).
|
||||
2. **Write the canonical English version first** — usually `README.md` and/or `ARCHITECTURE.md`. Get the wording right there; it anchors everything else.
|
||||
6. **Area READMEs / docs/**: update `server/README.md`, `client/README.md`, and the relevant `docs/*.md` per the mapping.
|
||||
7. **Diagrams**: when a state transition changes, edit every mermaid `stateDiagram-v2` block that models it (they are duplicated across README, server/README and docs/DATABASE). Keep transition labels consistent.
|
||||
|
||||
## Verify (do not skip)
|
||||
|
||||
- **Coverage**: run `scripts/doc-coverage.sh <new-term> [...]` (e.g. the new env var / event type / identifier) and confirm every doc the mapping flags shows a HIT. The matrix is advisory — not every term belongs in every file — but a flagged doc reading `0` 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 `vi` entry in `client/src/i18n/locales/vi/`.
|
||||
- **Format/tests**: run `npm run format` (or `prettier --check` on touched files); for any code touched, run the verification from `CLAUDE.md` (`npm run test:server` / `test:client` / `mcp:typecheck`).
|
||||
- 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.md` lists the stable anchors per file.
|
||||
- Parallelize translations + HTML across subagents when the change is large, but write the canonical English edit yourself first so the translations have a faithful source.
|
||||
- One language/area per subagent keeps edits reviewable and tables un-corrupted.
|
||||
@@ -0,0 +1,65 @@
|
||||
# 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.
|
||||
Standalone full translations of `README.md`. **Every** README change must be mirrored here at the corresponding section. Conventions:
|
||||
- Keep in English/code: identifiers, env-var names, event-type names, `awaiting_input_since`, `pendingInterrupt`, "watchdog", `fs.watch`, model IDs, mermaid transition labels.
|
||||
- Translate prose. "Waiting" → **Đang chờ** (vi) / **等待中** (zh) / **대기 중** (ko). "watchdog" often kept; in zh sometimes 看门狗.
|
||||
|
||||
### `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/MCP.md` + `mcp/README.md`
|
||||
MCP server + tool reference. Update for new/changed MCP tools.
|
||||
|
||||
### `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`, `DEPLOYMENT.md`, `docs/DEPLOYMENT.md` — install/run/deploy 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.
|
||||
- `desktop/README.md`, `vscode-extension/README.md`, `statusline/README.md` — surface-specific; update only when that surface changes.
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,58 @@
|
||||
#!/usr/bin/env bash
|
||||
# doc-coverage.sh — verify that one or more terms (a new env var, event type,
|
||||
# route, identifier, feature name, …) are documented across this repo's
|
||||
# canonical doc surface. Prints a HIT/miss matrix so a docs update can be
|
||||
# checked for "full coverage" before finishing.
|
||||
#
|
||||
# Usage:
|
||||
# .claude/skills/update-project-docs/scripts/doc-coverage.sh DASHBOARD_SESSION_SYNC_MS
|
||||
# .claude/skills/update-project-docs/scripts/doc-coverage.sh Interrupted pendingInterrupt
|
||||
#
|
||||
# Run from the repo root. Exit code is non-zero if any term is missing from a
|
||||
# doc that the change-type mapping (see references/doc-map.md) says it belongs
|
||||
# in — but treat the matrix as advisory: not every term belongs in every file.
|
||||
# @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
|
||||
set -u
|
||||
|
||||
# The canonical doc set kept in sync. Translations + HTML + per-area READMEs.
|
||||
DOCS=(
|
||||
"README.md"
|
||||
"ARCHITECTURE.md"
|
||||
"server/README.md"
|
||||
"client/README.md"
|
||||
"docs/HOOKS.md"
|
||||
"docs/DATABASE.md"
|
||||
"docs/API.md"
|
||||
"docs/PLUGINS.md"
|
||||
"docs/MCP.md"
|
||||
"mcp/README.md"
|
||||
"docs/I18N.md"
|
||||
".env.example"
|
||||
)
|
||||
|
||||
if [ "$#" -eq 0 ]; then
|
||||
echo "usage: $0 <term> [term2 ...]" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
missing_any=0
|
||||
for term in "$@"; do
|
||||
echo "── coverage for: $term ──────────────────────────────"
|
||||
for doc in "${DOCS[@]}"; do
|
||||
if [ ! -f "$doc" ]; then
|
||||
printf " %-26s (absent)\n" "$doc"
|
||||
continue
|
||||
fi
|
||||
n=$(grep -Fc -- "$term" "$doc" 2>/dev/null || true)
|
||||
n=${n:-0}
|
||||
if [ "$n" -gt 0 ]; then
|
||||
printf " ✅ %-26s %s\n" "$doc" "$n"
|
||||
else
|
||||
printf " · %-26s 0\n" "$doc"
|
||||
fi
|
||||
done
|
||||
echo
|
||||
done
|
||||
|
||||
exit $missing_any
|
||||
Reference in New Issue
Block a user