diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6e4b3e2..df854c3 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -8,7 +8,7 @@ { "name": "do-it", "description": "Workflow discipline plugin: skills auto-trigger via hooks; no slash commands required.", - "version": "0.10.0", + "version": "0.11.0", "source": "./", "author": { "name": "tdwhere123" diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index b144884..9de267c 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "do-it", "description": "Workflow discipline plugin for Claude Code: tier routing, premise grilling, verification gates. Skills auto-trigger via hooks—no slash commands required.", - "version": "0.10.0", + "version": "0.11.0", "author": { "name": "tdwhere123" }, diff --git a/CHANGELOG.md b/CHANGELOG.md index 5594c7e..247f256 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,47 @@ - No unreleased changes. +## 0.11.0 + +### Fixed + +- macOS CI: the `anti-patterns-lint` hook is now BSD-portable. The no-consumer + check uses git grep's own `-w` word match instead of a GNU `\b` regex, and + file paths are canonicalized with `pwd -P` before repo-relative stripping so + the `/var`→`/private/var` symlink no longer breaks self-exclusion. The macOS + hook-test job was failing on these for three releases. + +### Changed + +- Handbook slimmed from 12 templates to 7 project-truth files. The five process + docs that duplicated skills were removed: the task-card layout now lives in + `do-it-planning`, the review protocol in `do-it-review-loop`, the dispatch + contract in `do-it-subagent-orchestration`, the execution pipeline in + `do-it-router`, and the handbook maintenance rules in the `do-it-handbook` + skill. +- Three low-utilization skills consolidated (23 → 20): `do-it-grill-log` folded + into `do-it-grill` (Grill Log Artifact), `do-it-domain-language` into + `do-it-context` (Domain Glossary Mode), and the optional `do-it-visual-planning` + into `do-it-planning` (Visual Aids); the visual companion (local browser + server + render templates) moves under `do-it-planning` and its templates were + visually redesigned. Existing installs remove the deprecated skills on upgrade. +- `do-it-router` gains a § Restraint principle: advisory over blocking, reuse + over add, no unbounded libraries, check git intent before deleting, and + capabilities that auto-fire instead of requiring a `/command`. +- `do-it-context` gives `CLAUDE.md` a formal role in the source-of-truth + hierarchy, draws the `CLAUDE.md` / `CONTEXT.md` / handbook boundary, and can + scaffold a lean `CLAUDE.md` on demand (additive, never auto-write). + +### Added + +- Advisory nudges (one-shot, never block): after grill on durable-plan work with + no plan card, a reminder to land the plan card before implementation drifts + ahead; on established projects (`.do-it/CONTEXT.md` or handbook present) or + port/restore prompts, a reminder to read existing structure / grep current + code first. +- `comments-lint` now flags `phase N`, `wave N`, and `BL-NNN` stage markers as + `task-ref` comments. + ## 0.10.0 ### Added diff --git a/README.md b/README.md index 32d971e..2d10d9d 100644 --- a/README.md +++ b/README.md @@ -112,8 +112,7 @@ CODEX_HOME=/tmp/do-it-plugin-test codex plugin marketplace add /path/to/do-it ``` The Codex plugin bundle lives at `plugins/do-it/` and is generated from -`manifest.json`. It includes 23 skills and 23 agents, including optional -`do-it-visual-planning`. +`manifest.json`. It includes 20 skills and 23 agents. For v1, pair plugin installation with `do-it setup` when you need enforced automatic hooks. Local `codex features list` currently reports @@ -137,9 +136,8 @@ do-it doctor --target=claude ``` The Claude target installs to `~/.claude/` by default; override with -`CLAUDE_PLUGIN_ROOT_OVERRIDE`. Optional skills such as -`do-it-visual-planning` are excluded by default; opt in with -`--with-optional`. +`CLAUDE_PLUGIN_ROOT_OVERRIDE`. The `--with-optional` flag installs any manifest +skills marked optional (none are marked optional in 0.11.0). ## What It Installs @@ -322,8 +320,7 @@ emitting valid JSON without `jq`. Stale session directories are pruned after 7 days. `do-it-router` gains an `Integrity` section — a failure is a clue to trace, not a symptom to hide — referenced by `do-it-debugging`, `do-it-fix-loop`, `do-it-verification-gate`, and the subagent dispatch -contract. `do-it-visual-planning` ships `plan-card` / `review-report` scenario -templates, and the CI test job now also runs on macOS. If a machine has a +contract. The CI test job now also runs on macOS. If a machine has a cached `0.8.0` plugin, reinstall or refresh so the host loads the new hook and skill files. diff --git a/README.zh-CN.md b/README.zh-CN.md index 2842b5a..d8e345a 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -102,7 +102,7 @@ CODEX_HOME=/tmp/do-it-plugin-test codex plugin marketplace add /path/to/do-it ``` Codex plugin bundle 位于 `plugins/do-it/`，由 `manifest.json` 生成。 -它包含 23 个 skill 和 23 个 agent，包括可选的 `do-it-visual-planning`。 +它包含 20 个 skill 和 23 个 agent。 v1 阶段，如果你需要强制自动 hooks，请把 plugin 安装和 `do-it setup` 配套使用。 当前本机 `codex features list` 显示 `codex_hooks=true`、`plugins=true`、 @@ -125,7 +125,7 @@ do-it doctor --target=claude ``` Claude target 默认装到 `~/.claude/`；用 `CLAUDE_PLUGIN_ROOT_OVERRIDE` 改根目录。 -可选 skill（如 `do-it-visual-planning`）默认不装，加 `--with-optional` 才装。 +`--with-optional` 会安装 manifest 中标记为 optional 的 skill（0.11.0 没有 optional skill）。 ## 它会安装什么 @@ -287,8 +287,7 @@ reasoning-effort 字段，Claude 生成的 agent 默认继承当前宿主模型 `do_it_emit_context` 在没有 `jq` 时仍能输出合法 JSON。陈旧 session 目录会在 7 天后清理。`do-it-router` 新增 `Integrity` 段 —— 失败是要追根因的线索, 不是要掩盖的症状 —— 被 `do-it-debugging`、`do-it-fix-loop`、 -`do-it-verification-gate` 和子智能体派发合约引用。`do-it-visual-planning` -新增 `plan-card` / `review-report` 场景模板,CI 测试任务现在也跑 macOS。 +`do-it-verification-gate` 和子智能体派发合约引用。CI 测试任务现在也跑 macOS。 若某台机器缓存了 `0.8.0` 插件,请重装或刷新,让宿主加载新的 hook 和 skill。 ## 升级到 0.8.0 diff --git a/commands/do-it-handbook.md b/commands/do-it-handbook.md index 8fead3c..ec1f043 100644 --- a/commands/do-it-handbook.md +++ b/commands/do-it-handbook.md @@ -1,5 +1,5 @@ --- -description: 在当前项目里铺一份 .do-it/handbook/ 骨架（invariants / architecture / code-map / glossary / backlog / runtime-status / maintenance / task-card-template + 三个 workflow 文件），仅补齐缺失文件，不覆盖已有内容。 +description: 在当前项目里铺一份 .do-it/handbook/ 骨架（invariants / architecture / code-map / glossary / backlog / runtime-status），仅补齐缺失文件，不覆盖已有内容。 --- # /do-it-handbook diff --git a/docs/maintenance.md b/docs/maintenance.md index f704f57..0bef671 100644 --- a/docs/maintenance.md +++ b/docs/maintenance.md @@ -110,8 +110,8 @@ When a skill changes, decide which kind of update it is: - do-it rewrite - do-it compatibility adapter that preserves a workflow idea while changing the installed name and wording -- optional auxiliary support, such as visual planning, that is installed but not - part of the default tier flow +- optional auxiliary support that is installed but not part of the default tier + flow (no skills are marked optional in 0.11.0) For either kind: @@ -259,8 +259,7 @@ surface generated from the same maintained manifest: `do-it` at `./plugins/do-it`. - `plugins/do-it/.codex-plugin/plugin.json` — plugin metadata with version parity to `package.json`. -- `plugins/do-it/skills/` — generated from every `manifest.skills[]` entry, - including optional `do-it-visual-planning`. +- `plugins/do-it/skills/` — generated from every `manifest.skills[]` entry. - `plugins/do-it/agents/` — generated from every `manifest.agents[]` entry. - `scripts/build-codex-plugin.mjs` — the only supported way to refresh the generated plugin bundle. diff --git a/docs/routing-matrix.md b/docs/routing-matrix.md index ca1bcdb..960a58c 100644 --- a/docs/routing-matrix.md +++ b/docs/routing-matrix.md @@ -130,16 +130,16 @@ rebuilds it from each `skills/do-it//SKILL.md` frontmatter and - `do-it-context`: maintains the project's canonical `.do-it/CONTEXT.md` — one-line definitions for terms, invariants, and relationships that downstream skills (grill, planning, review) read before debating semantics. -- `do-it-grill-log`: writes the per-task `.do-it/grill/.md` artifact - (`kind`, falsifier, status, evidence). Read by `do-it-planning` and + Its § Domain Glossary Mode stabilizes domain terms and catches contradictions + between user language, docs, and code. +- `do-it-grill` § Grill Log Artifact: writes the per-task `.do-it/grill/.md` + artifact (`kind`, falsifier, status, evidence). Read by `do-it-planning` and `do-it-verification-gate` so unresolved facts or execution-blocking decisions block closeout. - `do-it-architecture-scan`: checks ownership, dependency direction, coupling, migration path, rollout risk, and failure isolation. - `do-it-interface-drill`: checks API, type, schema, CLI, docs, protocol, and adapter contracts at the producer/consumer boundary. -- `do-it-domain-language`: stabilizes domain terms and catches contradictions - between user language, docs, and code. - `do-it-tdd`, `do-it-debugging`, `do-it-review-loop`, `do-it-fix-loop`, and `do-it-verification-gate`: focused quality loops used when behavior, root cause, review findings, or completion claims require @@ -148,8 +148,6 @@ rebuilds it from each `skills/do-it//SKILL.md` frontmatter and slices, ownership boundaries, and return schemas. - `do-it-worktree-isolation` and `do-it-branch-closeout`: optional support for isolated work and final integration. -- `do-it-visual-planning`: optional local visual companion for planning - artifacts; it is not part of the default delivery route. The do-it roles absorb the useful discipline from the previous workflow family: mandatory truth checks, failure-mode forecasting, explicit planning, isolated @@ -183,16 +181,16 @@ class: task` for a delegated slice, or `tier: Heavy, class: wave` for the parent coordinator. Do not use `wave` or `phase` as substitutes for `Standard` or `Heavy`. -`do-it-domain-language`, `do-it-worktree-isolation`, `do-it-skill-authoring`, -and `do-it-visual-planning` are routed by need rather than by tier: +`do-it-worktree-isolation` and `do-it-skill-authoring` are routed by need rather +than by tier: -- use `do-it-domain-language` when overloaded terms, product concepts, or - business rules affect the plan or review; - use `do-it-worktree-isolation` when current workspace state, parallel lanes, or rollback risk requires isolation; -- use `do-it-skill-authoring` when creating or updating skills; -- use `do-it-visual-planning` only when a local visual planning companion would - improve a planning discussion. +- use `do-it-skill-authoring` when creating or updating skills. + +Vocabulary work (overloaded terms, product concepts, business rules) routes to +`do-it-context` § Domain Glossary Mode; visual comparison routes to +`do-it-planning` § Visual Aids. ## Planning Rules @@ -276,7 +274,7 @@ Use for `Heavy` work: 2. Use `do-it-grill` to challenge the decision tree, failure-mode forecast, and path map before implementation. 3. Use `do-it-slicing` to define lanes and shared-file ownership. 4. Run `do-it-interface-drill`, `do-it-architecture-scan`, and - `do-it-domain-language` only where their evidence will change the plan. + `do-it-context` § Domain Glossary Mode only where their evidence will change the plan. 5. Delegate Standard slices unless a child is explicitly assigned Heavy work. 6. Run expanded review, fix-loop, re-review, and branch closeout. diff --git a/docs/upstream-map.md b/docs/upstream-map.md index 9a2ef24..69558a0 100644 --- a/docs/upstream-map.md +++ b/docs/upstream-map.md @@ -18,7 +18,7 @@ runtime-specific assumptions do not leak into new Codex installs. | `do-it-brainstorm` | requirement-shape discovery before grill | Absorbs multi-perspective divergence into a product + architecture core flow: product boundary, core goal, option tradeoffs, architecture foundation, extension modules, and explicit grill handoff. | | `do-it-architecture-scan` | architecture risk and opportunity scan | Absorbs codebase-improvement heuristics while keeping opportunities non-blocking unless correctness or delivery risk is real. | | `do-it-interface-drill` | interface and boundary design | Absorbs interface-design drills for APIs, schemas, CLIs, events, UI contracts, and agent handoffs. | -| `do-it-domain-language` | canonical term and model alignment | Absorbs ubiquitous-language and domain-model discipline for overloaded terms, glossary updates, and contradictions between code/docs/user language. | +| `do-it-context` § Domain Glossary Mode | canonical term and model alignment | Absorbs ubiquitous-language and domain-model discipline for overloaded terms, glossary updates, and contradictions between code/docs/user language. (Folded in from the former `do-it-domain-language` skill.) | | `do-it-tdd` | behavior-first RED/GREEN loop | Absorbs behavior-via-public-interface testing and one-test-at-a-time tracer-bullet TDD. | | `do-it-debugging` | root-cause investigation | Absorbs systematic debugging and issue triage: reproduce, trace, find root cause, then plan durable RED/GREEN fixes. | | `do-it-subagent-orchestration` | delegated slice protocol | Absorbs parallel-agent dispatch and subagent-driven development, but defaults child agents to Standard slices instead of inheriting Heavy parent flows. | @@ -27,7 +27,7 @@ runtime-specific assumptions do not leak into new Codex installs. | `do-it-verification-gate` | evidence-before-claims closeout | Absorbs legacy verification discipline and makes success claims depend on fresh commands or explicit evidence. | | `do-it-worktree-isolation` | workspace isolation | Absorbs git-worktree setup and current-worktree safety into a do-it support skill. | | `do-it-branch-closeout` | branch/PR/merge finish | Absorbs development-branch finish checks, commit/PR evidence, and cleanup choices. | -| `do-it-visual-planning` | optional planning companion | Absorbs the older visual brainstorming helper as an optional `.do-it/visual` support path, not a core workflow gate. Marked `optional: true` in `manifest.json` from 0.4.0; install with `--with-optional`. | +| `do-it-planning` § Visual Aids | optional planning companion | Absorbs the older visual brainstorming helper as an optional `.do-it/visual` support path, not a core workflow gate. (Folded in from the former `do-it-visual-planning` skill; the browser companion was retired.) | | `do-it-skill-authoring` | skill creation and maintenance | Absorbs progressive-disclosure skill writing and repo-managed skill validation. | ## External Idea Map @@ -45,8 +45,8 @@ The do-it skills are rewrites, not vendored copies. Useful ideas from | `improve-codebase-architecture` | `do-it-architecture-scan` | Friction-led exploration, shallow-module detection, deep-module candidates, coupling and testability impact. | | `tdd` | `do-it-tdd` | Public-interface behavior tests and one RED/GREEN vertical slice at a time. | | `triage-issue` | `do-it-debugging` | Manifestation, code path, root cause, minimal fix, and TDD fix plan. | -| `qa` | `do-it-review-loop`, `do-it-domain-language` | User-facing durable issues, concise reproduction, and project domain language. | -| `ubiquitous-language`, `domain-model` | `do-it-domain-language` | Canonical glossary, ambiguity flags, code/docs contradiction checks, and lightweight ADR triggers. | +| `qa` | `do-it-review-loop`, `do-it-context` | User-facing durable issues, concise reproduction, and project domain language. | +| `ubiquitous-language`, `domain-model` | `do-it-context` § Domain Glossary Mode | Canonical glossary, ambiguity flags, code/docs contradiction checks, and lightweight ADR triggers. | | `write-a-skill` | `do-it-skill-authoring` | Concise SKILL.md, progressive disclosure, optional resources, and validation. | Excluded or adapter-only ideas remain outside the core install flow unless a diff --git a/hooks/anti-patterns-lint.sh b/hooks/anti-patterns-lint.sh index 24699da..8eaf7e9 100755 --- a/hooks/anti-patterns-lint.sh +++ b/hooks/anti-patterns-lint.sh @@ -82,6 +82,14 @@ if ! command -v git >/dev/null 2>&1; then fi FILE_DIR="$(dirname "$FILE_PATH")" +# Canonicalize the directory so it matches git's symlink-resolved +# --show-toplevel output. On macOS the temp/working tree can sit under +# /var -> /private/var (or /tmp -> /private/tmp); without this the REPO_ROOT +# prefix strip below would fail, leaving REL_FILE absolute and REL_DIR collapsed +# to ".", which breaks both the diff pathspec and the self-exclusion. pwd -P is +# POSIX-portable; readlink -f is not (BSD lacks it). +FILE_DIR="$(cd "$FILE_DIR" 2>/dev/null && pwd -P || printf '%s' "$FILE_DIR")" +FILE_PATH="$FILE_DIR/$(basename "$FILE_PATH")" REPO_ROOT="$(git -C "$FILE_DIR" rev-parse --show-toplevel 2>/dev/null)" if [[ -z "$REPO_ROOT" ]]; then do_it_debug anti-patterns-lint "decision=skip reason=not-a-git-repo" @@ -187,9 +195,11 @@ case "$FILE_PATH" in NO_CONSUMER_NAMES="" while IFS= read -r name; do [[ -z "$name" ]] && continue - # Search for any reference to `name` in other JS/TS files. Use a basic - # word-boundary regex; this catches `Name(`, `Name.`, ` Name `, etc. - REFS="$(_doit_timeout 5s git -C "$REPO_ROOT" grep -lE "\\b${name}\\b" \ + # Search for any reference to `name` in other JS/TS files. Use git + # grep's own `-w` word match with `-F` fixed string — portable to BSD + # (macOS), unlike a GNU `\b` regex which BSD regcomp does not support. + # This still catches `Name(`, `Name.`, ` Name `, etc. at word boundaries. + REFS="$(_doit_timeout 5s git -C "$REPO_ROOT" grep -lwF -e "$name" \ -- '*.ts' '*.tsx' '*.js' '*.jsx' '*.mjs' '*.cjs' 2>/dev/null || true)" # Drop the current file from the result. REL_FILE="${FILE_PATH#"${REPO_ROOT}/"}" @@ -305,6 +315,9 @@ fi PROJECT_ROOT="$(do_it_project_root "$CWD")" PROJECT_ROOT="${PROJECT_ROOT%/}" +# FILE_PATH was symlink-resolved with pwd -P above; resolve PROJECT_ROOT the same +# way so the display strip still works when CWD is a symlinked path (macOS). +PROJECT_ROOT="$(cd "$PROJECT_ROOT" 2>/dev/null && pwd -P || printf '%s' "$PROJECT_ROOT")" case "$FILE_PATH" in "$PROJECT_ROOT"/*) DISPLAY_PATH="${FILE_PATH#"$PROJECT_ROOT"/}" ;; *) DISPLAY_PATH="$FILE_PATH" ;; diff --git a/hooks/comments-lint.sh b/hooks/comments-lint.sh index 0d23c62..5d53a7a 100755 --- a/hooks/comments-lint.sh +++ b/hooks/comments-lint.sh @@ -253,9 +253,10 @@ if [[ "${FIX_HITS:-0}" -gt 0 ]]; then _record_family "fix-narrative" fi -# 3. Task references +# 3. Task references — external trackers plus do-it stage markers (phase / +# wave / backlog IDs) that rot a release or two after they are written. TASKREF_HITS=$(printf '%s\n' "$FILTERED" \ - | grep -ciE 'issue #|pr #|ticket #|jira-' \ + | grep -ciE 'issue #|pr #|ticket #|jira-|\bBL-[0-9]|\bphase[ -][0-9]|\bwave[ -][0-9]' \ || true) if [[ "${TASKREF_HITS:-0}" -gt 0 ]]; then HITS=$((HITS + TASKREF_HITS)) diff --git a/hooks/grill-prompt.sh b/hooks/grill-prompt.sh index 314c9a1..b819b2e 100755 --- a/hooks/grill-prompt.sh +++ b/hooks/grill-prompt.sh @@ -21,6 +21,16 @@ source "${SCRIPT_DIR}/lib/keywords.sh" # shellcheck source=lib/debug.sh source "${SCRIPT_DIR}/lib/debug.sh" +# Advisory nudges (plan-card reliability, existing-codebase discipline) are +# computed once on a work turn and attached to whichever exit path this hook +# takes, so they fire even when the grill reminder itself does not. Advisory +# only — never blocks. +_doit_advisory="" +_emit_advisory_exit() { + [[ -n "$_doit_advisory" ]] && do_it_emit_context UserPromptSubmit "$_doit_advisory" + exit 0 +} + # Read stdin first so the subagent check can use the JSON-supplied # transcript_path (the host delivers it on stdin, not as an env var). RAW_INPUT="$(do_it_read_stdin)" @@ -79,6 +89,40 @@ if [[ "$EXPLICIT_GRILL" -eq 0 ]] && { [[ "$LAST_PROMPT_KIND" == "question" ]] || exit 0 fi +# ---- One-shot advisory nudges (work turns only; never block) ---- +ADVISORY_TIER="$(do_it_session_state_get "$SESSION_ID" tier)" + +# Plan-card nudge: grill ran in a prior turn and durable planning is required, +# but no plan card exists yet — nudge to land it before implementation drifts ahead. +_grilled_prev="$(do_it_session_state_get "$SESSION_ID" grilled)" +if [[ "$(do_it_session_state_get "$SESSION_ID" plan_nudged)" != "1" \ + && "$(do_it_session_state_get "$SESSION_ID" durable_plan_seen)" == "1" \ + && -n "$_grilled_prev" && "$_grilled_prev" != "0" && "$_grilled_prev" != "skip-question" ]] \ + && ! ls "${CWD}/.do-it/plans/"*.md >/dev/null 2>&1; then + do_it_session_state_set "$SESSION_ID" plan_nudged 1 + _doit_advisory="${_doit_advisory} +do-it planning: grill has converged and this is durable-plan work, but no .do-it/plans/.md exists yet. Load do-it-planning to land the plan card (acceptance criteria, failure-mode forecast, path map) before implementing. Advisory — skip only if an inline modification map fully covers the work. +" +fi + +# Existing-codebase / port-restore "understand before you change" nudge. +if [[ "$(do_it_session_state_get "$SESSION_ID" brownfield_nudged)" != "1" ]]; then + _port="$(do_it_session_state_get "$SESSION_ID" port_intent)" + _brown="$(do_it_session_state_get "$SESSION_ID" dim_brownfield)" + _touch="$(do_it_session_state_get "$SESSION_ID" dim_touches_code)" + if [[ "$_port" == "1" ]]; then + do_it_session_state_set "$SESSION_ID" brownfield_nudged 1 + _doit_advisory="${_doit_advisory} +do-it (existing code): this looks like port / restore / reintroduce work. Before writing a 'port' plan, grep/Glob the current packages/apps/migrations for the target name — it may already exist; if so, extend it instead of rebuilding. Advisory. +" + elif [[ "$_brown" == "1" && "$_touch" == "1" ]] && { [[ "$ADVISORY_TIER" == "Standard" || "$ADVISORY_TIER" == "Heavy" ]]; }; then + do_it_session_state_set "$SESSION_ID" brownfield_nudged 1 + _doit_advisory="${_doit_advisory} +do-it (existing code): this is an established codebase. Before editing, read the file/area you are changing and reuse its existing patterns, names, and invariants (.do-it/CONTEXT.md and handbook if present) rather than assuming greenfield. Advisory. +" + fi +fi + # Same-session de-dup: if we already grilled and the user did not re-request, # stay quiet. if [[ "$RE_GRILL" -eq 0 ]]; then @@ -89,7 +133,7 @@ if [[ "$RE_GRILL" -eq 0 ]]; then fi if [[ -n "$GRILLED" && "$GRILLED" != "0" && "$GRILLED" != "skip-question" ]]; then do_it_debug grill-prompt "decision=already-grilled state=$GRILLED" - exit 0 + _emit_advisory_exit fi fi @@ -108,7 +152,7 @@ if [[ -z "$TRIGGER" && "$EXPLICIT_GRILL" -eq 1 ]]; then fi if [[ -z "$TRIGGER" && "$TIER" == "Light" ]]; then do_it_debug grill-prompt "decision=no-trigger tier=$TIER reason=light" - exit 0 + _emit_advisory_exit fi if [[ -z "$TRIGGER" && "$TIER" == "Standard" ]] && do_it_prompt_has_any "$PROMPT" DO_IT_UNCERTAINTY_WORDS; then TRIGGER="uncertainty" @@ -129,13 +173,13 @@ if [[ -n "$TRIGGER" && "$TIER" == "Standard" && "$EXPLICIT_GRILL" -eq 0 ]]; then TOUCHES_CODE="$(do_it_session_state_get "$SESSION_ID" dim_touches_code)" if [[ "$TOUCHES_CODE" != "1" ]]; then do_it_debug grill-prompt "decision=no-trigger tier=Standard reason=dim-touches-code-zero original-trigger=${TRIGGER}" - exit 0 + _emit_advisory_exit fi fi if [[ -z "$TRIGGER" ]]; then do_it_debug grill-prompt "decision=no-trigger tier=$TIER" - exit 0 + _emit_advisory_exit fi # Heavy-tier turns get a fuller fact-first reminder; everyone else gets the @@ -182,5 +226,5 @@ case "${DO_IT_DEBUG:-0}" in ;; esac -do_it_emit_context UserPromptSubmit "$MSG" +do_it_emit_context UserPromptSubmit "${MSG}${_doit_advisory}" exit 0 diff --git a/hooks/router.sh b/hooks/router.sh index bf0bb42..f1d9049 100755 --- a/hooks/router.sh +++ b/hooks/router.sh @@ -119,6 +119,31 @@ if [[ "$TIER" == "Heavy" ]] || do_it_prompt_requires_durable_plan "$PROMPT"; the durable_plan_required=1 fi do_it_session_state_set "$SESSION_ID" durable_plan_required "$durable_plan_required" +# Sticky: once durable planning is required in a session, remember it so the +# post-grill plan-card nudge can fire on a later turn even after the per-turn +# durable_plan_required is recomputed to 0 by a follow-up prompt. +if [[ "$durable_plan_required" == "1" ]]; then + do_it_session_state_set "$SESSION_ID" durable_plan_seen 1 +fi + +# Existing-codebase + port/restore signals for the advisory nudges that +# grill-prompt.sh emits (router stays state-only). brownfield = the project has +# accumulated do-it context (CONTEXT.md or a handbook), so the agent should read +# that existing structure before editing rather than assume greenfield. Kept +# precise on purpose: the advisory points at those exact files, and a bare git +# repo is not "established" in the sense that matters. port_intent = the prompt +# asks to port / restore / reintroduce something that often already exists. +brownfield=0 +if [[ -f "${CWD}/.do-it/CONTEXT.md" || -d "${CWD}/.do-it/handbook" ]]; then + brownfield=1 +fi +do_it_session_state_set "$SESSION_ID" dim_brownfield "$brownfield" +port_intent=0 +case "$(do_it_lc "$PROMPT")" in + *"移植"*|*"迁移回"*|*"重新引入"*|*"恢复历史"*|*"恢复旧"*|*"恢复以前"*|*"reintroduce"*|*"re-introduce"*|*"port from"*|*"port over"*|*"port the"*|*"restore legacy"*|*"restore the old"*|*"bring back the"*) + port_intent=1 ;; +esac +do_it_session_state_set "$SESSION_ID" port_intent "$port_intent" # Dimensions are orthogonal to tier. Tier stays as the single derived label # existing skills key off; downstream skills may read these additive booleans diff --git a/index.json b/index.json index 79d5eb6..4483459 100644 --- a/index.json +++ b/index.json @@ -1,22 +1,19 @@ { - "version": "0.10.0", + "version": "0.11.0", "generated_at": "2026-05-24T15:12:54.935Z", "package": "@tdwhere/do-it", "repository": "https://github.com/tdwhere123/do-it", "domain": "agentic-workflow", - "total_skills": 23, + "total_skills": 20, "total_agents": 23, "coverage": { "skill_groups": { "index": 1, "mainline": 7, - "maintenance": 4, - "on-demand": 10, - "optional": 1 + "maintenance": 3, + "on-demand": 9 }, - "optional_skills": [ - "do-it-visual-planning" - ] + "optional_skills": [] }, "entries": [ { @@ -72,23 +69,13 @@ { "kind": "skill", "name": "do-it-context", - "description": "Use when repo terms or invariants are drifting and `.do-it/CONTEXT.md` should become the downstream source of truth for names, relationships, and facts.", + "description": "Use when repo terms or invariants are drifting, or when user/docs/code naming disagrees and a canonical glossary is needed — `.do-it/CONTEXT.md` is the downstream source of truth for names, relationships, and facts.", "origin": "do-it", "optional": false, "group": "maintenance", "source": "skills/do-it/do-it-context", "target": "skills/do-it-context" }, - { - "kind": "skill", - "name": "do-it-grill-log", - "description": "Use when grill facts or decisions need durable status logging as kind fact or decision before work continues.", - "origin": "do-it", - "optional": false, - "group": "maintenance", - "source": "skills/do-it/do-it-grill-log", - "target": "skills/do-it-grill-log" - }, { "kind": "skill", "name": "do-it-brainstorm", @@ -119,16 +106,6 @@ "source": "skills/do-it/do-it-interface-drill", "target": "skills/do-it-interface-drill" }, - { - "kind": "skill", - "name": "do-it-domain-language", - "description": "Use when user language, docs, and code naming disagree and a canonical domain glossary or handoff vocabulary is needed.", - "origin": "do-it", - "optional": false, - "group": "on-demand", - "source": "skills/do-it/do-it-domain-language", - "target": "skills/do-it-domain-language" - }, { "kind": "skill", "name": "do-it-tdd", @@ -209,16 +186,6 @@ "source": "skills/do-it/do-it-branch-closeout", "target": "skills/do-it-branch-closeout" }, - { - "kind": "skill", - "name": "do-it-visual-planning", - "description": "Use when a plan or design decision would benefit from a small diagram, sketch, mockup, or side-by-side visual artifact alongside text.", - "origin": "do-it", - "optional": true, - "group": "optional", - "source": "skills/do-it/do-it-visual-planning", - "target": "skills/do-it-visual-planning" - }, { "kind": "skill", "name": "do-it-skill-authoring", @@ -232,7 +199,7 @@ { "kind": "skill", "name": "do-it-handbook", - "description": "Use when a project needs a durable `.do-it/handbook/` skeleton for architecture, glossary, code map, backlog, runtime, maintenance, and workflow docs.", + "description": "Use when a project needs a durable `.do-it/handbook/` skeleton for architecture, invariants, glossary, code map, backlog, and runtime status.", "origin": "do-it", "optional": false, "group": "maintenance", diff --git a/install/manage.mjs b/install/manage.mjs index a4fc4ad..5bfd4ff 100755 --- a/install/manage.mjs +++ b/install/manage.mjs @@ -30,7 +30,7 @@ function usage(stream = console.error) { stream(""); stream("Options:"); stream(" --target= Pick install target (default: codex). Available: codex, claude."); - stream(" --with-optional Include skills marked optional (e.g. visual-planning)."); + stream(" --with-optional Include any skills marked optional in the manifest."); stream(" --session= With doctor: pretty-print session state (hook invocations, tier history) for the given session id."); stream(" --no-migrate With install: refuse to silently migrate from an older install-state version (exit code 2)."); stream(""); diff --git a/manifest.json b/manifest.json index ecf4f53..0b0d4b1 100644 --- a/manifest.json +++ b/manifest.json @@ -1,5 +1,5 @@ { - "version": "0.10.0", + "version": "0.11.0", "migrations": [ { "from": "0.4.x", @@ -24,6 +24,10 @@ { "from": "0.9.x", "actions": [] + }, + { + "from": "0.10.x", + "actions": [] } ], "targets": { @@ -359,6 +363,30 @@ "15619616cf9b0d82f74f81e472ad1669b5cc23f56b8b6adb31d9e33ddb16d79e" ], "reason": "removed after 0.4.x; use do-it-router plus focused planning, TDD/debugging, review-loop, fix-loop, and verification-gate as needed" + }, + { + "name": "do-it-grill-log", + "target": "skills/do-it-grill-log", + "legacyHashes": [ + "3d78d21c9cf63494773970273e750a7893d8dafc78992ce8a02bb01a417dd276" + ], + "reason": "folded into do-it-grill as the Grill Log Artifact section" + }, + { + "name": "do-it-domain-language", + "target": "skills/do-it-domain-language", + "legacyHashes": [ + "794f2d0cce1e77276a3840d12d673e9cc2859f7a3bc57df5dba435ac0717965b" + ], + "reason": "folded into do-it-context as Domain Glossary Mode" + }, + { + "name": "do-it-visual-planning", + "target": "skills/do-it-visual-planning", + "legacyHashes": [ + "d9a5232ded1eb64340d1698cce5e55b6e6c0a93046ce0f77458df0f8faa0936a" + ], + "reason": "auxiliary skill folded into do-it-planning as the Visual Aids section; visual companion relocated under do-it-planning" } ], "skills": [ @@ -398,12 +426,6 @@ "target": "skills/do-it-context", "origin": "do-it" }, - { - "name": "do-it-grill-log", - "source": "skills/do-it/do-it-grill-log", - "target": "skills/do-it-grill-log", - "origin": "do-it" - }, { "name": "do-it-brainstorm", "source": "skills/do-it/do-it-brainstorm", @@ -422,12 +444,6 @@ "target": "skills/do-it-interface-drill", "origin": "do-it" }, - { - "name": "do-it-domain-language", - "source": "skills/do-it/do-it-domain-language", - "target": "skills/do-it-domain-language", - "origin": "do-it" - }, { "name": "do-it-tdd", "source": "skills/do-it/do-it-tdd", @@ -476,13 +492,6 @@ "target": "skills/do-it-branch-closeout", "origin": "do-it" }, - { - "name": "do-it-visual-planning", - "source": "skills/do-it/do-it-visual-planning", - "target": "skills/do-it-visual-planning", - "origin": "do-it", - "optional": true - }, { "name": "do-it-skill-authoring", "source": "skills/do-it/do-it-skill-authoring", diff --git a/package.json b/package.json index 5e34777..a68fa8a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@tdwhere/do-it", - "version": "0.10.0", + "version": "0.11.0", "description": "Installable AI coding workflow for Codex and Claude Code with risk-based routing, scoped sub-agents, and evidence-backed completion.", "type": "module", "license": "MIT", diff --git a/plugins/do-it/.codex-plugin/plugin.json b/plugins/do-it/.codex-plugin/plugin.json index a098c03..4b77907 100644 --- a/plugins/do-it/.codex-plugin/plugin.json +++ b/plugins/do-it/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "do-it", - "version": "0.10.0", + "version": "0.11.0", "description": "Installable AI coding workflow for Codex and Claude Code with risk-based routing, scoped sub-agents, and evidence-backed completion.", "author": { "name": "tdwhere123" diff --git a/plugins/do-it/skills/_index.md b/plugins/do-it/skills/_index.md index ef098a6..f4af020 100644 --- a/plugins/do-it/skills/_index.md +++ b/plugins/do-it/skills/_index.md @@ -26,7 +26,6 @@ router 推荐按需加载：用 Skill 工具 + skill 名加载详情；不要一 - **do-it-interface-drill** — API, schema, CLI, or protocol changes must be checked across producer and cons… - **do-it-debugging** — a bug's root cause is unclear or prior fixes failed and you need a hypothesis,… - **do-it-slicing** — a large plan needs independent vertical slices with explicit ownership, verifi… -- **do-it-domain-language** — user language, docs, and code naming disagree and a canonical domain glossary… - **do-it-comments-discipline** — code comments are authored or reviewed and must be checked as anchors, invaria… - **do-it-worktree-isolation** — risky, long, or parallel work needs an isolated git worktree to protect the ma… - **do-it-branch-closeout** — closing a branch, PR, merge, or cleanup and you must name scope, verification… @@ -34,11 +33,6 @@ router 推荐按需加载：用 Skill 工具 + skill 名加载详情；不要一 ## Handbook & 维护 -- **do-it-handbook** — a project needs a durable `.do-it/handbook/` skeleton for architecture, glossa… -- **do-it-context** — repo terms or invariants are drifting and `.do-it/CONTEXT.md` should become th… -- **do-it-grill-log** — grill facts or decisions need durable status logging as kind fact or decision… +- **do-it-handbook** — a project needs a durable `.do-it/handbook/` skeleton for architecture, invari… +- **do-it-context** — repo terms or invariants are drifting, or when user/docs/code naming disagrees… - **do-it-skill-authoring** — creating or updating do-it skills and you need clear triggers, return shape, w… - -## 其他 (manifest 已声明但未分组) - -- **do-it-visual-planning** — a plan or design decision would benefit from a small diagram, sketch, mockup,… diff --git a/plugins/do-it/skills/do-it-brainstorm/SKILL.md b/plugins/do-it/skills/do-it-brainstorm/SKILL.md index 5694f3b..cc4664f 100644 --- a/plugins/do-it/skills/do-it-brainstorm/SKILL.md +++ b/plugins/do-it/skills/do-it-brainstorm/SKILL.md @@ -148,7 +148,7 @@ When durable handoff is useful, write: .do-it/brainstorm/.md ``` -`` follows the same rule as `do-it-grill-log`: slug from the user title or a short hash, with an optional session prefix. `/.do-it/brainstorm/.gitkeep` should exist when the project tracks do-it artifacts. +`` follows the same slug rule as the grill log (see `do-it-grill` § Grill Log Artifact): slug from the user title or a short hash, with an optional session prefix. `/.do-it/brainstorm/.gitkeep` should exist when the project tracks do-it artifacts. In the same turn, write the slug to the task pointer so router and other skills can pick it up: @@ -288,7 +288,6 @@ After discussion or artifact creation: - `do-it-router` — sets tier and decides whether brainstorm is useful. - `do-it-subagent-orchestration` — dispatch contract for selected lenses. -- `do-it-grill` — converges the must-discuss stack. -- `do-it-grill-log` — records resolved facts and decisions. +- `do-it-grill` — converges the must-discuss stack and records resolved facts and decisions in its grill log. - `do-it-review-loop` — reviews delivered diff, skill quality, install readiness, and release risk after implementation. - `do-it-context` — sediments terms anchored during brainstorm or grill. diff --git a/plugins/do-it/skills/do-it-context/SKILL.md b/plugins/do-it/skills/do-it-context/SKILL.md index d1f6f06..c8034c0 100644 --- a/plugins/do-it/skills/do-it-context/SKILL.md +++ b/plugins/do-it/skills/do-it-context/SKILL.md @@ -1,13 +1,13 @@ --- name: do-it-context -description: "Use when repo terms or invariants are drifting and `.do-it/CONTEXT.md` should become the downstream source of truth for names, relationships, and facts." +description: "Use when repo terms or invariants are drifting, or when user/docs/code naming disagrees and a canonical glossary is needed — `.do-it/CONTEXT.md` is the downstream source of truth for names, relationships, and facts." --- # Do-It Context ## Purpose -`.do-it/CONTEXT.md` is the single canonical place where this project's terminology, invariants, and relationship-shapes live for AI workflows. Other skills (especially `do-it-grill`, `do-it-planning`, `do-it-review-loop`, `do-it-domain-language`) read it before debating definitions. +`.do-it/CONTEXT.md` is the single canonical place where this project's terminology, invariants, and relationship-shapes live for AI workflows. Other skills (especially `do-it-grill`, `do-it-planning`, `do-it-review-loop`) read it before debating definitions. This skill also owns the deeper domain-language pass (canonical glossary + contradiction checks) — see § Domain Glossary Mode. It is **not** a wiki, README replacement, or onboarding doc. It is a terse, declarative artifact intended to fit in the AI's working memory budget. Keep it under ~200 lines. @@ -31,11 +31,15 @@ When context sources disagree, use this order: 1. Current code, tests, schemas, manifests, generated source-of-truth scripts, and live command output. -2. `.do-it/CONTEXT.md` for terse repo terms, invariants, and relationships that +2. `CLAUDE.md` (or the host's equivalent root agent-instruction file) for + durable, human-authored conventions and behavioral rules the team chose — + authoritative for *how to work here*, though current code still wins on + *what the code is*. +3. `.do-it/CONTEXT.md` for terse repo terms, invariants, and relationships that code does not express accessibly. -3. Current plan, grill log, task card, or issue for the active work. -4. README, docs, ADRs, and maintenance guides. -5. Memory, old reports, previous worker summaries, and external sources. +4. Current plan, grill log, task card, or issue for the active work. +5. README, docs, ADRs, and maintenance guides. +6. Memory, old reports, previous worker summaries, and external sources. Lower layers can point to what to inspect, but they do not override current repo truth. @@ -87,6 +91,85 @@ Roughly quarterly, or when the file crosses ~200 lines: 2. Find lines that no longer match the code; rewrite or delete. 3. Find lines that have moved into the type system / schema and can now be deleted. +## CLAUDE.md (durable conventions) + +`CLAUDE.md` (or the host's equivalent root instruction file) holds the durable, +human-owned conventions for how agents work in this project — coding standards, +review bar, do/don't rules, restraint principles. do-it reads it before grill +and planning. It differs from the other do-it homes: + +- **CLAUDE.md** — durable *behavioral* conventions and team rules (human-owned, + rarely changes). +- **`.do-it/CONTEXT.md`** — per-session *factual* sediment (terms, invariants, + relationships) that `do-it-grill` writes. +- **`.do-it/handbook/`** — structural project docs (architecture, code map, + glossary, backlog). + +CLAUDE.md is the top of the convention ladder: a rule that has held across +sessions and is about *how to work* (not a project fact) graduates here from +`.do-it/CONTEXT.md`. + +When the user asks to set up or tidy CLAUDE.md, scaffold a lean skeleton on +demand — never auto-write, and never overwrite an existing CLAUDE.md (additive, +like the handbook bootstrap). A useful skeleton: + +```markdown +# — agent conventions + +## Restraint +- Prefer advisory nudges over write-blocking gates. +- Reuse or thin an existing module before adding a new one; do not build things + that grow unbounded. +- Read existing structure and git intent before deleting or rewriting. + +## Conventions +- + +## Review bar +- +``` + +Keep it short — CLAUDE.md is read every turn, so it competes for context budget. +Detail belongs in `.do-it/handbook/` or `docs/`. + +## Domain Glossary Mode (Standard+) + +The sediment workflow above is the Light path — one line per clarified term. For +non-trivial naming or modeling work (a new public API, schema, data model, phase +plan, or widespread terminology drift), do the deeper pass: build an explicit +canonical language map before names harden into code, docs, schemas, UI labels, +or handoffs. + +Sequence: + +1. Collect terms from the user request, docs, code, tests, schemas, logs, and UI copy. +2. Group synonyms, aliases, abbreviations, and deprecated terms. +3. Identify contradictions between code, docs, user language, and runtime behavior. +4. Define canonical terms from domain meaning, not implementation convenience. +5. Name domain entities, actions, states, invariants, and forbidden states. +6. Recommend what must change now and what can wait; feed interface/architecture + implications into the relevant do-it skill. + +Glossary shape: + +| Term | Definition | Source evidence | Aliases | Status | +| --- | --- | --- | --- | --- | +| canonical-term | ... | file/docs/user | old-term | canonical | + +Status values: `canonical` (use in new code/docs), `alias` (acceptable for +compatibility), `deprecated` (avoid in new work, migrate when touched), +`conflict` (sources disagree and need a decision). + +Contradiction checks — look for: a user term and a code term that mean different +things; docs describing a concept code models differently; a UI label hiding a +backend state distinction; schema names encoding transport detail instead of +domain meaning; tests using legacy terms; agents or task cards using different +names for the same ownership boundary. + +Stable canonical terms graduate into `glossary.md` via the three-session +promotion rule (see `do-it-handbook`). Do not rename code broadly when a glossary +is enough for the current task. + ## Stop Conditions Do not update CONTEXT.md when: @@ -130,4 +213,3 @@ Before relying on or updating CONTEXT.md: - `do-it-grill` — primary writer of new entries. - `do-it-planning` — reads CONTEXT.md before drafting plan cards. - `do-it-review-loop` — checks CONTEXT.md for contract terms before reviewing. -- `do-it-domain-language` — for the deeper "is this a coherent domain language" question. diff --git a/plugins/do-it/skills/do-it-domain-language/SKILL.md b/plugins/do-it/skills/do-it-domain-language/SKILL.md deleted file mode 100644 index 71b8160..0000000 --- a/plugins/do-it/skills/do-it-domain-language/SKILL.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -name: do-it-domain-language -description: "Use when user language, docs, and code naming disagree and a canonical domain glossary or handoff vocabulary is needed." ---- - -# Do-It Domain Language - -## Purpose - -Use this to make domain terms explicit before names become code, docs, schemas, UI labels, or agent handoffs. The output is a small canonical language map with contradictions and proposed resolutions. - -## Tier Rules - -### Light - -Use for a local naming decision. Inspect nearby code and docs, pick the least surprising term, and note aliases if needed. - -### Standard - -Default for subagents and non-trivial naming or model work. Build a glossary from user language, docs, code, tests, schemas, and UI text. - -### Heavy - -Parent-only unless explicitly assigned. Use for phase plans, data models, public APIs, workflow policy, migrations, or widespread terminology drift. - -## Sequence - -1. Collect terms from the user request, docs, code, tests, schemas, logs, and UI copy. -2. Group synonyms, aliases, abbreviations, and deprecated terms. -3. Identify contradictions between code, docs, user language, and runtime behavior. -4. Define canonical terms using domain meaning, not implementation convenience. -5. Name domain entities, actions, states, invariants, and forbidden states. -6. Recommend where terminology must change now and what can wait. -7. Feed interface or architecture implications into the relevant do-it skill. - -## Glossary Shape - -| Term | Definition | Source evidence | Aliases | Status | -| --- | --- | --- | --- | --- | -| canonical-term | ... | file/docs/user | old-term | canonical | - -Status values: - -- `canonical`: use in new code/docs. -- `alias`: acceptable when preserving compatibility. -- `deprecated`: avoid in new work, migrate when touched. -- `conflict`: current sources disagree and need a decision. - -## Contradiction Checks - -Look for: - -- user term means one thing, code term means another; -- docs describe a concept that code models differently; -- UI label hides a backend state distinction; -- schema names encode transport detail instead of domain meaning; -- tests use legacy terms that make new behavior ambiguous; -- agents or task cards use different names for the same ownership boundary. - -## Output Shape - -- Scope scanned. -- Canonical glossary. -- Contradictions and proposed resolution. -- Domain entities, actions, states, and invariants. -- Required naming changes for current work. -- Deferred terminology cleanup, if any. -- Interface or architecture follow-ups. - -## Common Mistakes - -- Renaming code broadly when a glossary is enough for the current task. -- Picking names from implementation detail instead of domain meaning. -- Treating aliases as harmless when they create conflicting behavior. -- Ignoring docs or UI copy while changing API names. -- Letting a subagent redefine canonical language outside its assigned slice. diff --git a/plugins/do-it/skills/do-it-grill-log/SKILL.md b/plugins/do-it/skills/do-it-grill-log/SKILL.md deleted file mode 100644 index a5ffe0d..0000000 --- a/plugins/do-it/skills/do-it-grill-log/SKILL.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -name: do-it-grill-log -description: "Use when grill facts or decisions need durable status logging as kind fact or decision before work continues." ---- - -# Do-It Grill Log - -## Purpose - -`.do-it/grill/.md` is the per-task artifact that records every fact or decision grilling has actually pressure-tested, the cheap falsifier you used when one exists, and the resolution. It outlives any single chat turn and feeds `do-it-planning` and `do-it-verification-gate`. - -Without it, grilling is just a vibe — once context compacts, every signal is gone. - -## When To Use - -- Inside `do-it-grill` after a fact has been tested or a user decision has been made — write the result here. -- Inside `do-it-planning` to confirm no unresolved item blocks the plan. -- Inside `do-it-verification-gate` (and the gate hook) — fail closeout only when an unresolved decision still changes execution or a factual premise is still unverified. - -## File Path - -``` -.do-it/grill/.md -``` - -`` should be: - -- the slug from the user's task title (lowercased, dash-separated, ≤32 chars), if one is obvious; -- otherwise the first 8 characters of the SHA-1 of the user's first prompt this turn; -- prefixed with the short session id when collisions are likely (e.g. `s1a2-fix-login`). - -`/.do-it/grill/.gitkeep` should exist so the directory tracks in version control. - -## File Format - -```markdown ---- -task: -session_id: -created: -status: open ---- - -## Items tested - -- [ ] **** - - kind: - - falsifier: - - status: - - evidence: - -## Anchored terms - -- ****: ← from CLAUDE.md / .do-it/CONTEXT.md / clarified this turn - -## Failure modes considered - -- correctness: ... -- contract: ... -- migration: ... -- performance: ... -- security: ... -- UX: ... -``` - -Use `confirmed` / `refuted` only for facts. Use `chosen` / `deferred` / `needs_user_decision` only for user preferences or product decisions. A `needs_user_decision` item blocks only when it changes the next execution step. When every blocking item is resolved, change frontmatter `status: open` → `status: resolved`. - -## Style rules - -- One bullet per item. No nested bullets in the bullet body — each item is independent. -- Falsifier must be cheap and deterministic. "Read the spec" is not a falsifier; "grep -F 'createOrder' src/" is. -- Evidence is the literal artifact: a path, a line number, a snippet of output. Never paraphrase. -- "Anchored terms" entries get sedimented to `.do-it/CONTEXT.md` (see `do-it-context`) — this section is just a working pad. -- Failure modes section captures predicted modes by category; it is permission-to-stop-thinking, not a binding promise. -- Do not mark a user preference as `confirmed`; if the user chose it, use `chosen`. -- Do not block closeout on a `deferred` preference unless the current implementation still depends on it. - -## Append-only discipline - -- New items are appended; existing items are mutated in place (`needs_user_decision` → `chosen`/`deferred`, or fact status filled in). Never delete an item — refute or defer it instead. -- The frontmatter `status` flips to `resolved` once no execution-blocking item remains. Do not flip it back to `open` retroactively without a new entry explaining why. - -## Worked example - -```markdown ---- -task: dedupe grill across same session -session_id: s1a2 -created: 2026-05-02 -status: resolved ---- - -## Items tested - -- [x] **Same-session re-grill is wasted unless prompt diverges materially.** - - kind: fact - - falsifier: count tokens injected for back-to-back implement requests in one transcript. - - status: confirmed - - evidence: hooks/grill-prompt.sh:38 — emits ~300 tokens; second call adds zero signal. -- [x] **Question turns must not consume the real same-session grill marker.** - - kind: fact - - falsifier: simulate question prompt followed by work prompt and inspect session state. - - status: confirmed - - evidence: hooks/router.sh sets `last_prompt_kind`, while hooks/grill-prompt.sh treats `grilled=1` as the real de-dup marker. - -## Anchored terms - -- **grilled**: a session-state flag in `${session_dir}/state.json`; value `1` means a real grill reminder fired this session. Question turns use `last_prompt_kind=question`. - -## Failure modes considered - -- correctness: forgetting to flip `grilled=1` would cause repeated injection — covered. -- contract: external scripts reading `state.json` would see new key — acceptable, additive. -``` - -## Common Rationalizations - -- *"I'll record it later."* — Later means after compaction, which means never. -- *"It's obvious why I confirmed this."* — Obvious to you now, not to verification next turn. -- *"This is too small to log."* — Then this premise wasn't load-bearing; you should not have grilled it. -- *"I changed my mind, let me delete that line."* — Mutate decision in place; `refuted` with evidence is more honest. - -## Red Flags - -- Every fact is `confirmed`. (Are you grilling, or rubber-stamping?) -- All facts are `refuted` and the plan still proceeds unchanged. (Why grill?) -- `status: resolved` with execution-blocking `needs_user_decision` items remaining. (Do not flip status until each blocking item resolves.) -- File grows past ~150 lines for a single task. (Probably needs splitting into sub-tasks, or the task is too broad.) - -## Stop Conditions - -Stop and return to `do-it-grill` or the user when: - -- a decision item is `needs_user_decision` and changes the next action; -- a fact has no cheap falsifier but the implementation depends on it; -- the log would need multiple unrelated task slugs to stay coherent; -- the evidence is only paraphrase, memory, or old transcript context. - -## Verification - -Before using the log as closeout evidence: - -- every execution-blocking fact is `confirmed` or `refuted`; -- every execution-blocking decision is `chosen`, `deferred`, or escalated; -- every evidence field points to a file, command, grep result, or explicit user choice; -- frontmatter `status: resolved` appears only when no blocking item remains. - -## Related Skills - -- `do-it-grill` — primary writer. -- `do-it-context` — destination for sediment of "anchored terms". -- `do-it-planning` — must read this file before producing the plan card; references the slug in plan frontmatter. -- `do-it-verification-gate` — must check that no execution-blocking unresolved item remains before allowing closeout. diff --git a/plugins/do-it/skills/do-it-grill/SKILL.md b/plugins/do-it/skills/do-it-grill/SKILL.md index c047c48..11ca100 100644 --- a/plugins/do-it/skills/do-it-grill/SKILL.md +++ b/plugins/do-it/skills/do-it-grill/SKILL.md @@ -21,7 +21,7 @@ A common failure is to dump a 5-question template at the user and call it grilli 2. **Anchor terms before debating intent.** If the user uses a term that has a definition in `CLAUDE.md`, `.do-it/CONTEXT.md`, or visible in code with a different shape — surface the conflict before going further. 3. **Verify, don't ask, when verification is cheap.** If the question can be answered with `rg`, `cat`, or a quick local command, do that and report what you found. 4. **Ask only for decisions.** Ask the user one focused question only when local truth cannot decide a preference, priority, or scope tradeoff that changes execution. Before asking, explain the decision in plain language, list the viable options with benefits/costs/risks, and recommend a default. -5. **Sediment what you learned.** When a term gets clarified or a constraint surfaces, append it to `.do-it/CONTEXT.md` (one line, declarative). Use `do-it-grill-log` for the per-task `.do-it/grill/.md` artifact (`kind: fact|decision`, falsifier, status, evidence). +5. **Sediment what you learned.** When a term gets clarified or a constraint surfaces, append it to `.do-it/CONTEXT.md` (one line, declarative). Record the per-task `.do-it/grill/.md` artifact (`kind: fact|decision`, falsifier, status, evidence) per § Grill Log Artifact below. ## When To Use @@ -71,7 +71,7 @@ Run this loop until every execution-blocking item is resolved: facts become `con 1. **Pick the most load-bearing premise.** What single belief, if wrong, would change the most downstream decisions? 2. **Try to falsify cheaply.** Read the file, grep for the symbol, run the unit test, glance at the schema. If you find evidence, jump to step 4. 3. **Ask one focused question** only when the remaining unknown is a user decision. Start with the minimum context the user needs, then show 2-3 real options with tradeoffs and a recommended default so the user has something concrete to accept or correct. -4. **Record the outcome** in `.do-it/grill/.md` (see `do-it-grill-log`). Use `kind: fact` with `confirmed/refuted` for evidence, or `kind: decision` with `chosen/deferred/needs_user_decision` for user preferences. +4. **Record the outcome** in `.do-it/grill/.md` (see § Grill Log Artifact). Use `kind: fact` with `confirmed/refuted` for evidence, or `kind: decision` with `chosen/deferred/needs_user_decision` for user preferences. 5. **Repeat** with the next-most-load-bearing premise, until the remaining unknowns no longer change the route. ## Assumptions Mode @@ -103,7 +103,7 @@ Convergence flow: 1. **Read the artifact.** Parse `Requirement Shape`, `Product Boundary`, `Core Goal`, `Options`, `Architecture Foundation`, and `Grill Handoff`. Each `Must Resolve In Grill` entry is a candidate premise the brainstorm lenses thought a human, grill, or local verification had to settle. 2. **Rank by route-impact.** Sort candidates by "if this is wrong, how many downstream choices change?" — same rule as the Iterative Loop. Cross-lens tensions usually outrank single-lens one-offs. -3. **Resolve each candidate** via the existing loop (verify cheaply, ask one question if a user decision is needed, log the result in `.do-it/grill/.md` per `do-it-grill-log`). +3. **Resolve each candidate** via the existing loop (verify cheaply, ask one question if a user decision is needed, log the result in `.do-it/grill/.md` per § Grill Log Artifact). 4. **Reference the brainstorm slug** in the grill log frontmatter: add `brainstorm: ` so `do-it-planning` and `do-it-verification-gate` can trace the lineage. 5. **Flip brainstorm status.** Once every execution-blocking `Must Resolve In Grill` item has a resolution (`chosen` / `deferred` / `needs_user_decision` for decisions; `confirmed` / `refuted` for facts), edit the brainstorm artifact's frontmatter from `status: open` to `status: converged`. Do not delete the artifact; future sessions read it. @@ -238,10 +238,53 @@ For a heavy grill: - Treating architecture taste as delivery truth. - Using a fuzzy term repeatedly without ever defining it back to the user or to `.do-it/CONTEXT.md`. +## Grill Log Artifact + +Grill records every pressure-tested fact or decision in `.do-it/grill/.md` +so the signal outlives the chat turn and feeds `do-it-planning` and +`do-it-verification-gate`. Without it, grilling is just a vibe — once context +compacts, every signal is gone. + +`` is the user's task title (lowercased, dash-separated, ≤32 chars) +when one is obvious, else the first 8 chars of the SHA-1 of the first prompt; +prefix with the short session id when collisions are likely. Keep +`.do-it/grill/.gitkeep` so the directory tracks in git. + +Format: + +```markdown +--- +task: +session_id: +created: +status: open # flips to `resolved` when no execution-blocking item remains +brainstorm: # only when converging a brainstorm artifact +--- + +## Items tested + +- [ ] **** + - kind: + - falsifier: + - status: + - evidence: + +## Anchored terms + +- ****: ← from CLAUDE.md / .do-it/CONTEXT.md / clarified this turn +``` + +Rules: use `confirmed`/`refuted` only for facts, `chosen`/`deferred`/`needs_user_decision` +only for decisions. A `needs_user_decision` item blocks only when it changes the +next execution step. Append new items and mutate existing ones in place — never +delete an item; refute or defer it with evidence. Anchored-terms entries get +sedimented to `.do-it/CONTEXT.md` (see `do-it-context`); this section is a +working pad. Flip `status: resolved` once no execution-blocking item remains, and +do not flip it back without a new entry explaining why. + ## Related Skills -- `do-it-context` — set up and maintain `.do-it/CONTEXT.md` with project terms and invariants. -- `do-it-grill-log` — write per-task `.do-it/grill/.md` artifacts (`kind`, falsifier, status, evidence). +- `do-it-context` — set up and maintain `.do-it/CONTEXT.md` with project terms and invariants (sediment destination for anchored terms). - `do-it-brainstorm` — divergent persona pass that runs before grill; produces the open decisions grill converges on. -- `do-it-planning` — consume the grill outcome into a plan card under `.do-it/plans/.md`. +- `do-it-planning` — consume the grill outcome into a plan card under `.do-it/plans/.md`; reads the grill slug. - `do-it-review-loop` — apply pressure to the delivered diff after grilling has set the bar. diff --git a/plugins/do-it/skills/do-it-handbook/SKILL.md b/plugins/do-it/skills/do-it-handbook/SKILL.md index b6970cb..87af4b6 100644 --- a/plugins/do-it/skills/do-it-handbook/SKILL.md +++ b/plugins/do-it/skills/do-it-handbook/SKILL.md @@ -1,13 +1,13 @@ --- name: do-it-handbook -description: "Use when a project needs a durable `.do-it/handbook/` skeleton for architecture, glossary, code map, backlog, runtime, maintenance, and workflow docs." +description: "Use when a project needs a durable `.do-it/handbook/` skeleton for architecture, invariants, glossary, code map, backlog, and runtime status." --- # Do-It Handbook ## Purpose -Use this to scaffold a long-lived handbook for a project that uses `do-it`. The handbook is the agent-readable source of truth for terms, invariants, ownership, and review discipline that does not change every turn. It complements the per-task artifacts (`.do-it/grill/`, `.do-it/plans/`, `.do-it/brainstorm/`) and the always-active sediment (`.do-it/CONTEXT.md`). +Use this to scaffold a long-lived handbook for a project that uses `do-it`. The handbook is the agent-readable source of truth for terms, invariants, ownership, and architecture that does not change every turn. It complements the per-task artifacts (`.do-it/grill/`, `.do-it/plans/`, `.do-it/brainstorm/`) and the always-active sediment (`.do-it/CONTEXT.md`). The shape is borrowed from a project that has shipped against it for a year (Do-SOUL Alaya). Files are intentionally small (< 30 KB each) so the agent can read whatever it needs without bloating context. @@ -33,14 +33,16 @@ Skip when: glossary.md # vocabulary (long-stable terms) backlog.md # cross-cutting unresolved issues with close conditions runtime-status.md # implementation status and known wiring gaps - maintenance.md # documentation update rules - task-card-template.md # template for non-trivial work briefs - workflow/ - agent-workflow.md # per-card / per-wave / phase pipelines - review-protocol.md # review mode, severity, evidence expectations - subagent-dispatch.md # how delegated workers are constrained ``` +The handbook holds only **project-specific truth** — the facts a generic skill +cannot carry. Process docs (task-card layout, review protocol, subagent +dispatch, execution pipeline, maintenance rules) are NOT scaffolded here: the +owning skills are their single source of truth (`do-it-planning`, +`do-it-review-loop`, `do-it-subagent-orchestration`, `do-it-router`, and the +`## Maintenance` section below). This keeps the handbook small and removes the +duplicate-doc drift that comes from copying skill prose into every project. + ## Bootstrap Behavior When invoked: @@ -50,7 +52,7 @@ When invoked: - If it does **and** some files are missing, copy only the missing files (additive, never overwrite). - If it does not exist, create the full tree. 2. Templates are copied verbatim from `templates/` under this skill. Each template is a skeleton with placeholder text the project owner replaces; do not hand-edit the project's handbook from inside the bootstrap step. -3. Add a `.gitkeep` to `.do-it/brainstorm/`, `.do-it/grill/`, `.do-it/plans/`, and `.do-it/handbook/workflow/` if any of those directories are missing, so the project tracks them in version control. +3. Add a `.gitkeep` to `.do-it/brainstorm/`, `.do-it/grill/`, and `.do-it/plans/` if any of those directories are missing, so the project tracks them in version control. 4. Print one line per file written, then a one-paragraph "next steps" pointer telling the user to start by filling in `invariants.md` and `glossary.md`. Do **not**: @@ -66,11 +68,14 @@ Do **not**: | `do-it-context` | `.do-it/CONTEXT.md` (active sediment) | `glossary.md` (long-stable terms) | | `do-it-architecture-scan` | inline review output | `architecture.md`, `invariants.md` | | `do-it-grill` | `.do-it/grill/.md` | `invariants.md`, `glossary.md` | -| `do-it-planning` | `.do-it/plans/.md` | `task-card-template.md` | -| `do-it-review-loop` | `.do-it/review/.md` | `workflow/review-protocol.md`, `invariants.md` | -| `do-it-subagent-orchestration` | the dispatch contract | `workflow/subagent-dispatch.md` | +| `do-it-review-loop` | `.do-it/review/.md` | `invariants.md` | | code-mapper agent | summary returned to parent | writes `code-map.md` "Current implementation locations" section | +`do-it-planning` owns the task-card layout itself, `do-it-review-loop` owns the +review protocol, and `do-it-subagent-orchestration` owns the dispatch contract — +none of them read a handbook copy. The handbook only feeds them project-specific +truth (`invariants.md`, `glossary.md`, `architecture.md`). + The handbook is read-mostly. The only file that gets written by an agent on a regular basis is `code-map.md`, and only by `code-mapper` per the contract in its agent definition. ## Term Promotion Rule (`.do-it/CONTEXT.md` ↔ `glossary.md`) @@ -84,12 +89,39 @@ To prevent drift between the active sediment and the stable glossary: This rule is enforced by the agent during `do-it-context` writes, not by tooling. Stating it once here keeps both files honest. +## Maintenance + +When and how to update each handbook file. The per-session sediment +(`.do-it/CONTEXT.md`) and per-task artifacts (`.do-it/grill/`, `.do-it/plans/`, +`.do-it/review/`) live outside the handbook; the project root `README.md` / +`CLAUDE.md` are entry points that delegate detail here. + +Update triggers: + +- **Implementation moved** → update `code-map.md` "Current implementation + locations" (normally the `code-mapper` agent) and `runtime-status.md` if + wiring, readiness, or known gaps changed. +- **Cross-cutting issue opened/closed** → `backlog.md` with a close condition; + per-task acceptance belongs in the plan card, not here. +- **Contract changed** → schema snippets in `architecture.md`, enum values in + `glossary.md`, and the affected plan cards; then search the codebase for + callers. +- **Invariant changed** → open a task card citing the invariant number; after + landing, sweep for contradictions and file backlog issues for any you cannot + fix in the same change. +- **Term stabilized** → promote `.do-it/CONTEXT.md` → `glossary.md` per the + three-session rule above. + +Keep any single handbook file under ~30 KB (it is read on routine agent work; +context budget is the constraint, not disk). After doc edits, sweep for changed +symbols and readiness labels, e.g. `rg -n "" docs .do-it/handbook`. + ## Output The bootstrap command should produce a short, deterministic report: ``` -[do-it-handbook] writing 12 file(s) to .do-it/handbook/ +[do-it-handbook] writing 7 file(s) to .do-it/handbook/ + .do-it/handbook/README.md + .do-it/handbook/invariants.md + .do-it/handbook/architecture.md @@ -97,11 +129,6 @@ The bootstrap command should produce a short, deterministic report: + .do-it/handbook/glossary.md + .do-it/handbook/backlog.md + .do-it/handbook/runtime-status.md - + .do-it/handbook/maintenance.md - + .do-it/handbook/task-card-template.md - + .do-it/handbook/workflow/agent-workflow.md - + .do-it/handbook/workflow/review-protocol.md - + .do-it/handbook/workflow/subagent-dispatch.md next: fill in invariants.md and glossary.md before running grill on any non-trivial task. ``` @@ -110,7 +137,7 @@ Idempotent re-runs print only the files actually written; an empty list means th ## Common Mistakes -- Treating the bootstrap as a one-time action and never refreshing the templates against do-it upstream. When `do-it` ships a new template (e.g. a new workflow file), the bootstrap should be re-runnable to add it. +- Treating the bootstrap as a one-time action and never refreshing the templates against do-it upstream. When `do-it` ships a new template (e.g. a new truth file), the bootstrap should be re-runnable to add it. - Copying the templates and then immediately auto-filling them from the codebase. The placeholders are intentional — they prompt the human owner to make the call. - Letting `code-map.md` drift. The `code-mapper` agent owns its update; if your project is using do-it without code-mapper running periodically, the handbook copy will rot. - Promoting every term from `.do-it/CONTEXT.md` to `glossary.md` as soon as it appears. The three-session rule exists because most session terms do not survive review. @@ -119,6 +146,5 @@ Idempotent re-runs print only the files actually written; an empty list means th - `do-it-context` — owns active sediment; promotes terms to `glossary.md`. - `do-it-architecture-scan` — reads `architecture.md` and `invariants.md`. -- `do-it-planning` — reads `task-card-template.md` shape. -- `do-it-review-loop` — reads `workflow/review-protocol.md`. -- `do-it-subagent-orchestration` — `workflow/subagent-dispatch.md` is the narrative form of its dispatch contract. +- `do-it-grill` — reads `invariants.md` and `glossary.md` for term anchoring. +- `do-it-planning` / `do-it-review-loop` / `do-it-subagent-orchestration` — own their task-card layout / review protocol / dispatch contract directly; the handbook no longer carries a copy. diff --git a/plugins/do-it/skills/do-it-handbook/templates/README.md b/plugins/do-it/skills/do-it-handbook/templates/README.md index 234fcbd..796dc64 100644 --- a/plugins/do-it/skills/do-it-handbook/templates/README.md +++ b/plugins/do-it/skills/do-it-handbook/templates/README.md @@ -1,7 +1,7 @@ # Project Handbook The handbook is the agent-readable, low-token navigation hub for this -project. It captures the rules, terms, ownership, and review discipline +project. It captures the rules, terms, ownership, and architecture that hold across sessions. Per-task artifacts live elsewhere (`.do-it/grill/`, `.do-it/plans/`, `.do-it/brainstorm/`, `.do-it/CONTEXT.md`). @@ -10,16 +10,12 @@ that hold across sessions. Per-task artifacts live elsewhere - `invariants.md` — rules that always win. - `architecture.md` — stable system shape. -- `workflow/agent-workflow.md` — execution flow for non-trivial work. -- `workflow/review-protocol.md` — review mode and evidence rules. - `code-map.md` — current implementation locations (maintained by the `code-mapper` agent). - `runtime-status.md` — current implementation status and known gaps. - `backlog.md` — cross-cutting unresolved issues with explicit close conditions. - `glossary.md` — long-stable vocabulary. -- `task-card-template.md` — template for non-trivial work briefs. -- `maintenance.md` — when and how to update each handbook file. ## Source-Of-Truth Map @@ -31,15 +27,16 @@ that hold across sessions. Per-task artifacts live elsewhere | Implementation status / wiring gaps | `runtime-status.md` | | Cross-cutting issues | `backlog.md` | | Vocabulary | `glossary.md` | -| Per-task brief template | `task-card-template.md` | -| Execution flow | `workflow/agent-workflow.md` | -| Review discipline | `workflow/review-protocol.md` | -| Subagent dispatch | `workflow/subagent-dispatch.md` | -| Doc maintenance rules | `maintenance.md` | + +Process docs are owned by skills, not this handbook: task-card layout → +`do-it-planning`, review protocol → `do-it-review-loop`, subagent dispatch → +`do-it-subagent-orchestration`, execution pipeline → `do-it-router`. The +handbook update rules live in the `do-it-handbook` SKILL `## Maintenance` +section. ## How To Update -See `maintenance.md` for which file to update when, and which targeted -sweeps to run after edits. Do not let `code-map.md` and -`runtime-status.md` drift from the codebase — they are read every -session and bad data here costs more than missing data. +See the `do-it-handbook` SKILL `## Maintenance` section for which file to +update when, and which targeted sweeps to run after edits. Do not let +`code-map.md` and `runtime-status.md` drift from the codebase — they are read +every session and bad data here costs more than missing data. diff --git a/plugins/do-it/skills/do-it-handbook/templates/code-map.md b/plugins/do-it/skills/do-it-handbook/templates/code-map.md index 13a5ecb..3633562 100644 --- a/plugins/do-it/skills/do-it-handbook/templates/code-map.md +++ b/plugins/do-it/skills/do-it-handbook/templates/code-map.md @@ -43,7 +43,7 @@ sections may be hand-maintained. - Tests: __ — run with ``. - Type definitions: __ — convention ``. - Configuration: __ — __. -- Docs: __ — `maintenance.md` governs updates. +- Docs: __ — the `do-it-handbook` SKILL `## Maintenance` section governs updates. ## Conventions diff --git a/plugins/do-it/skills/do-it-handbook/templates/glossary.md b/plugins/do-it/skills/do-it-handbook/templates/glossary.md index 4786240..6300480 100644 --- a/plugins/do-it/skills/do-it-handbook/templates/glossary.md +++ b/plugins/do-it/skills/do-it-handbook/templates/glossary.md @@ -36,11 +36,10 @@ Avoid: ## Process Vocabulary **Light / Standard / Heavy** — Tier classification used by -`do-it-router` to size the workflow for a task. See -`workflow/agent-workflow.md`. +`do-it-router` to size the workflow for a task. See `do-it-router`. **Blocking / Important / Opportunity** — Severity used in review -findings. See `workflow/review-protocol.md`. +findings. See `do-it-review-loop`. **Grill / Brainstorm** — Convergent (`do-it-grill`) and divergent (`do-it-brainstorm`) reasoning passes that run before planning. diff --git a/plugins/do-it/skills/do-it-handbook/templates/invariants.md b/plugins/do-it/skills/do-it-handbook/templates/invariants.md index 50faf4b..a450e7a 100644 --- a/plugins/do-it/skills/do-it-handbook/templates/invariants.md +++ b/plugins/do-it/skills/do-it-handbook/templates/invariants.md @@ -30,8 +30,8 @@ A change to this file is a project-shape decision, not a routine edit. ## Review -9. A worker `DONE` claim is not an acceptance signal; the review - protocol in `workflow/review-protocol.md` decides acceptance. +9. A worker `DONE` claim is not an acceptance signal; `do-it-review-loop` + decides acceptance. 10. Closeout requires fresh verification evidence on the integrated branch; evidence from an isolated worktree alone is not enough. diff --git a/plugins/do-it/skills/do-it-handbook/templates/maintenance.md b/plugins/do-it/skills/do-it-handbook/templates/maintenance.md deleted file mode 100644 index 216b9b1..0000000 --- a/plugins/do-it/skills/do-it-handbook/templates/maintenance.md +++ /dev/null @@ -1,76 +0,0 @@ -# Documentation Maintenance - -When and how to update each handbook file. - -## Directory Roles - -- `.do-it/handbook/` — maintained handbook (this directory). -- `.do-it/CONTEXT.md` — per-session active sediment; owned by - `do-it-context`. -- `.do-it/grill/.md` — per-task grill log. -- `.do-it/plans/.md` — per-task plan card. -- `.do-it/brainstorm/.md` — per-task multi-persona brainstorm. -- `.do-it/review/.md` — per-task review-loop findings (when - used). -- Project root `README.md`, `CLAUDE.md` (or equivalent) — entry - points; delegate detail to the handbook. - -## Update Rules - -When implementation changes: - -- Update `code-map.md` "Current implementation locations" if files, - packages, routes, repos, migrations, or service ownership changed. - This is normally written by the `code-mapper` agent. -- Update `runtime-status.md` if wiring, readiness, or known gaps - changed. -- Update `backlog.md` only for unresolved cross-cutting issues with a - close condition. Per-task acceptance criteria belong in the task - card. - -When dependencies or readiness gates change: - -- Update `Prerequisite`, `Blocks`, `Depends` in the affected task - cards. -- Update `runtime-status.md` status labels. - -When contracts change: - -- Update schema snippets (architecture or interface docs). -- Update enum values in `glossary.md` if any. -- Update acceptance criteria and test expectations in the affected - task cards. -- Update downstream consumer assumptions and search the codebase for - callers. - -When a term stabilizes: - -- Promote it from `.do-it/CONTEXT.md` to `glossary.md` after the - three-session rule (see `do-it-handbook` SKILL). - -When an invariant changes: - -- Open a task card. Cite the invariant number. -- After landing, sweep the codebase for contradictions. File backlog - issues for any you cannot fix in the same change. - -## Large File Rule - -Do not create new handbook files larger than ~30 KB if they are read -on routine agent work. Split lookup-heavy content into smaller pages. -The agent's context budget is the constraint, not disk. - -## Drift Sweep - -After doc edits, run targeted sweeps for changed symbols, events, -dependencies, and readiness labels. Project-specific examples: - -```bash -rg -n "" docs .do-it/handbook -rg -n "schema-ready|implementation-ready|live-event-ready" \ - docs .do-it/handbook -find .do-it/handbook docs -type f -name '*.md' -size +30k -print -``` - -If a sweep surfaces a contradiction, fix it in the same change or -open a backlog issue with a close condition. diff --git a/plugins/do-it/skills/do-it-handbook/templates/task-card-template.md b/plugins/do-it/skills/do-it-handbook/templates/task-card-template.md deleted file mode 100644 index a1f8c13..0000000 --- a/plugins/do-it/skills/do-it-handbook/templates/task-card-template.md +++ /dev/null @@ -1,130 +0,0 @@ -# Task Card Template - -A lightweight template for non-trivial work that benefits from a -written brief — typically multi-file changes, multi-day efforts, -sub-agent dispatches, or anything that needs review-loop discipline. - -For one-shot fixes, just describe scope in the PR body and skip this. - -## File Layout - -- File path: `.do-it/plans/.md` for in-flight task cards; - graduated cards may move into a project-specific directory once - their wave settles. -- File MUST be UTF-8 without BOM, < 30 KB. Localized fixtures inside - the card are fine. - -## Section Order - -``` -# Implementation Brief: — - -> Frontmatter (block-quoted bullet list, fields below) - -## 1. Background & Goal -## 2. Allowed Scope -## 3. Deferred -## 4. Acceptance Criteria -## 5. Verification -## 6. Shared File Hazards & Dependencies -``` - -## Frontmatter Fields - -```markdown -> - **Card ID**: <short kebab-case id> -> - **Source/Background**: <link or one-liner> -> - **Target**: `<destination paths inside the repo>` -> - **Size**: <S | M | L | XL> (S ≤ 5 files, M ≤ 20, L ≤ 100, XL > 100) -> - **Tier**: <Light | Standard | Heavy> (matches do-it-router) -> - **Prerequisite**: <comma-separated card IDs, or `none`> -> - **Blocks**: <comma-separated card IDs, or `none`> -> - **Owner**: <`unassigned` until claimed> -> - **Grill**: <slug from .do-it/grill/, or `none`> -> - **Brainstorm**: <slug from .do-it/brainstorm/, or `none`> -``` - -## §1 Background & Goal - -Two short paragraphs: - -1. **Background**: why this work matters; what subsystem it touches; - what depends on it. -2. **Goal**: a single sentence stating the one outcome this card - delivers. One card = one goal. - -## §2 Allowed Scope - -The exhaustive enumeration of files the card touches. Use -sub-sections per file or per file group. For each file include: - -- **Target**: repo-relative path -- **Change**: brief description of what changes and why - -## §3 Deferred - -Anything intentionally NOT in this card. Each deferral MUST cite a -backlog issue: - -```markdown -- <thing> — deferred to backlog #BL-NNN with close condition - "<one-liner>". -``` - -If nothing is deferred, write `Nothing deferred.` exactly. - -## §4 Acceptance Criteria - -A markdown table. Each row has a stable AC ID (AC1, AC2, ...) and an -Evidence column that names a verifiable artifact. - -```markdown -| AC | Criteria | Evidence | -|---|---|---| -| AC1 | … | … | -| AC2 | TypeScript compiles | `pnpm exec tsc --noEmit` is clean | -| AC3 | Unit tests pass | `pnpm exec vitest run` is green | -``` - -## §5 Verification - -Concrete shell commands a reviewer can run to verify §4. Order them -build → test → lint → integration. - -For Heavy, release/install, multi-agent, or explicit durable-plan work, include -an Evidence Ledger table. Ordinary Light work and one-shot Standard fixes can -skip it. - -```markdown -| Claim ID | Readiness target | Truth plane | Ref/path | Evidence | Result | Date | Owner | Residual risk | -|---|---|---|---|---|---|---|---|---| -| C1 | fixture-ready | source-repo | `src/...` | `npm test` | NOT_VERIFIED | YYYY-MM-DD | parent | command not run yet | -``` - -Allowed `Result` values: `VERIFIED`, `FAILED`, `NOT_VERIFIED`, `BLOCKED`, and -`DEFERRED_BY_USER`. - -Allowed truth planes: `source-repo`, `task-worktree`, `integration-worktree`, -`temp-install`, `live-codex`, `live-claude`, `package-artifact`, -`host-behavior`, and `external-blocked`. - -Old projects do not need historical backfill. Record a `NOT_VERIFIED` baseline -only when old state affects the current task. - -## §6 Shared File Hazards & Dependencies - -A short list of shared files this card writes that may collide with -other cards in the same wave. If none, write `No shared-file -hazards.` exactly. - -Plus a short dependency restatement (mirrors frontmatter): - -```markdown -**Prerequisite**: <card IDs>. -**Blocks**: <card IDs>. -``` - -## Path Style - -All paths are repository-relative -(e.g. `packages/core/src/foo.ts`), never absolute. diff --git a/plugins/do-it/skills/do-it-handbook/templates/workflow/agent-workflow.md b/plugins/do-it/skills/do-it-handbook/templates/workflow/agent-workflow.md deleted file mode 100644 index 53fd09f..0000000 --- a/plugins/do-it/skills/do-it-handbook/templates/workflow/agent-workflow.md +++ /dev/null @@ -1,82 +0,0 @@ -# Agent Workflow - -Execution flow for non-trivial work. Light-tier mechanical edits skip -most of this; Standard and Heavy tiers follow it. - -## Per-Card Pipeline - -1. Read the relevant task card (under `.do-it/plans/`) or PR brief. - If the work area only has a README and no card, read the README - and split a task card or get explicit user scope before - implementing code. -2. Read `invariants.md`. -3. Read the affected handbook pages (`architecture.md`, - `code-map.md`, the relevant glossary entries). -4. Freeze scope from the card's §2-§5. -5. For multi-package or live-path work, map the producer / consumer - path before dispatching a worker. -6. Write or update tests first when practical - (see `do-it-tdd`). -7. Implement the smallest change that satisfies the card. -8. Verify using the card's §5 commands. -9. Run `do-it-review-loop` against the diff before marking - the card done. -10. Run a targeted doc/code consistency sweep for changed contracts. - -## Per-Wave Pipeline - -A "wave" is a set of cards that share a goal and may need to land -together. - -1. Confirm every card has a clear `Prerequisite`, `Blocks`, and - readiness target. -2. Execute independent cards in parallel only when their **write - sets do not overlap**. Cards that touch shared barrel files - (e.g. package index files) MUST serialize through a barrel-update - card. -3. Stop dependent workers when the prerequisite card is still under - review or when shared-contract work is not yet green. -4. Review each card against `invariants.md` and its acceptance - criteria. -5. Re-review every fix loop before merge; worker `DONE` is not an - acceptance signal. -6. Update `runtime-status.md` after each completed card. - -## Phase / Worktree Pipeline - -When the work spans multiple waves or touches risky shared files: - -1. Create an isolated worktree (`do-it-worktree-isolation`). -2. Verify the intended base branch and record its current status. -3. Dispatch card or wave workers from the phase controller only - after the controller freezes scope, dependencies, shared-file - ownership, and merge order. -4. Keep phase work out of the main checkout until build, tests, and - review/fix-loop closure on the phase branch are complete. -5. Merge back to main only after the final reviewer pass reports - zero unresolved Blocking or Important findings on the integrated - branch. -6. After merging, rerun gate verification on `main`. Evidence from - the worktree alone is not enough for closeout. - -## Anti-Tail Discipline - -- **One card, one goal.** If you discover the card needs two goals, - split it before continuing. -- **No silent scope expansion.** A new file outside §2 means open a - backlog issue or update §2 explicitly. -- **No mocking the database in integration tests** unless the card - says so. Mock/prod divergence is a recurring incident class. -- **No commit during a fix loop without re-running review** — partial - fixes ship under the cover of "addressed". - -## Light-Tier Shortcut - -For Light-tier work (mechanical refactors, one-symbol renames, -dependency bumps): - -1. Skip the per-card pipeline; describe scope inline in the PR. -2. Verify with the smallest test command that touches the changed - surface. -3. No handbook updates required unless `code-map.md` would otherwise - become wrong. diff --git a/plugins/do-it/skills/do-it-handbook/templates/workflow/review-protocol.md b/plugins/do-it/skills/do-it-handbook/templates/workflow/review-protocol.md deleted file mode 100644 index ef2c5db..0000000 --- a/plugins/do-it/skills/do-it-handbook/templates/workflow/review-protocol.md +++ /dev/null @@ -1,80 +0,0 @@ -# Review Protocol - -Review mode, severity, and evidence expectations. -`do-it-review-loop` is the agent-side counterpart of this document. - -## Review Modes - -- **Self-review** — the implementer re-reads the diff against the - task card §4 acceptance criteria before requesting review. -- **PR-style review** — `reviewer` agent (or a peer) checks the diff - against acceptance criteria, invariants, and contract surface. -- **Multi-perspective review** — additional read-only review agents - (`architect-reviewer`, `red-team-reviewer`, `domain-language-reviewer`, - etc.) run when their lens is needed. - -The default for a Standard-tier task is self-review. Add PR-style review when -the task has a named non-local risk, an interface/module boundary, or an -explicit review/subagent request. Heavy tier adds multi-perspective review. - -## Severity - -- **Blocking** — must resolve before merge. Correctness, contract, - invariants, or unsafe state. -- **Important** — should resolve now. Avoidable rework, review - failure, unclear ownership, or significant maintenance debt. -- **Opportunity** — useful improvement; not a blocker. - -A finding carries exactly one severity. Re-classifying a Blocking -finding as Important is a discussion, not a unilateral move. - -## Evidence Requirements - -Every finding must cite evidence. Acceptable forms: - -- `path:line` reference. -- A grep / rg snippet showing the contradicted assumption. -- A failing test command and its output. -- A schema or contract diff. - -Unacceptable evidence: - -- "It feels wrong." -- "I think this could be a problem." -- "In my experience, ...". - -If a reviewer cannot cite evidence, the finding is downgraded to a -question for the implementer, not a Blocking item. - -## Fix Loop - -1. Address each Blocking and Important finding atomically. -2. After fixes, **re-run review on the same scope**. Spot-fixes - without a re-review let partial fixes ship. -3. Repeat until Blocking and Important are empty. -4. Opportunity findings may merge with the change or get filed as - backlog issues; do not block on them. - -## Closeout - -A card is done when: - -- All §4 acceptance criteria pass with the §5 verification commands. -- All Blocking and Important review findings are resolved. -- Fresh verification evidence is recorded on the integrated branch - (not just the worktree). -- `runtime-status.md` and `code-map.md` are updated if implementation - shape changed. -- The closeout states which brainstorm, grill, subagent, review, and - verification steps were used or skipped, with the reason when the route made - them relevant. - -## Anti-Patterns - -- "DONE" claims without verification output. `do-it-verification-gate` - catches this; do not weaken the gate. -- Reviewers asking the implementer to fix Blocking findings while - approving the PR. Approval after Blocking findings is a process - failure. -- Reviewers re-litigating architecture invariants in PR comments. - Invariant changes go through a task card, not a review thread. diff --git a/plugins/do-it/skills/do-it-handbook/templates/workflow/subagent-dispatch.md b/plugins/do-it/skills/do-it-handbook/templates/workflow/subagent-dispatch.md deleted file mode 100644 index 7b171b3..0000000 --- a/plugins/do-it/skills/do-it-handbook/templates/workflow/subagent-dispatch.md +++ /dev/null @@ -1,116 +0,0 @@ -# Subagent Dispatch - -Narrative form of the `do-it-subagent-orchestration` contract. Read -this before delegating to a subagent for the first time on a project; -read the contract for the exact required fields. - -## When To Delegate - -Delegate when the parent has bounded the slice well enough that -another agent can do the work in isolation, and the parent's context -budget is better spent on integration and verification than on the -slice itself. - -Do **not** delegate when: - -- the parent has not yet verified enough current truth to bound the - slice; -- the work touches the parent's shared files (final integration, branch - closeout, manifest edits); -- two parallel workers would write the same file or hidden shared - state; -- the parent is uncertain about acceptance criteria. - -A delegated worker is evidence to inspect, not a rubber stamp. - -## Required Prompt Fields - -Every subagent prompt must specify: - -- **tier**: Light, Standard, or explicit Heavy. -- **scope**: exact task and non-goals. -- **write ownership**: allowed directories/files, or `read-only`. -- **forbidden paths**: files, directories, generated outputs, or - user-owned edits to avoid. -- **current truth**: facts the parent verified and the child may rely - on. -- **failure-mode forecast**: expected failure classes the child must - cover or refute. -- **path map**: producer → contract/event/schema → transport/client → - state/query → surface/operator action → verification, or - `not applicable`. -- **readiness target**: the readiness label expected after the slice. -- **truth plane**: `source-repo`, `task-worktree`, `integration-worktree`, - `temp-install`, `live-codex`, `live-claude`, `package-artifact`, - `host-behavior`, or `external-blocked`. -- **lane status**: starts as `assigned`; the parent updates it through - `running`, `done_with_evidence`, `integrated`, or `blocking`. -- **must-verify facts**: facts the child must check itself before - acting or reporting. -- **stop condition**: when to return `NEEDS_CONTEXT`, `BLOCKED`, or - `STILL_OPEN`. -- **integrity stance**: failure is a clue to trace, not to hide; do not - swallow errors, weaken checks, skip tests, or claim unverified work is done. -- **output_budget**: token cap selected from `do-it-subagent-orchestration`. -- **return schema**: the exact shape the parent needs. - -Include this guardrail unless Heavy is explicitly assigned: - -> You are a Standard-tier subagent. Do not expand into parent-level -> Heavy flow, broad planning, branch closeout, manifest/docs edits, or -> unrelated cleanup. - -## Standard Return Schemas - -Implementation/debugging workers return: - -- `status`: `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or - `BLOCKED`; -- lane status recommendation: `done_with_evidence` or `blocking`; -- tier used; -- files changed; -- commands run with results; -- facts verified; -- failure modes covered or still open; -- proof path evidence or why it was not applicable; -- assumptions; -- residual risk; -- requested parent action. - -Review/drill workers return: - -- `status`: `CLEAR`, `FINDINGS`, `STILL_OPEN`, `NEEDS_CONTEXT`, or - `BLOCKED`; -- scope reviewed; -- findings ordered by `Blocking`, `Important`, `Opportunity`; -- evidence per finding; -- cause class when known; -- commands or inspections run; -- facts verified; -- assumptions; -- residual risk; -- `NOT_CHECKED`: explicit scope or checks not performed. - -## Parent Duties - -- Inspect diffs and reports before accepting them. -- Resolve duplicate or conflicting findings. -- Re-run verification on the integrated branch — not the worker's - isolated working copy. -- Ensure subagents did not touch forbidden paths. -- Maintain lane state as `assigned`, `running`, `done_with_evidence`, - `integrated`, or `blocking`. -- Treat worker `DONE` as input to inspect; parent acceptance is `integrated`. -- Close or re-dispatch workers only after the stop condition is - satisfied. - -## Common Mistakes - -- Delegating before scope is bounded; the worker spends its budget - re-discovering the parent's question. -- Parallelizing workers that share a write target; one of them - silently overwrites the other. -- Treating a worker's `DONE` as acceptance. `DONE` is a status, not a - signoff. -- Letting a worker make manifest, docs, or release decisions outside - its slice. diff --git a/plugins/do-it/skills/do-it-planning/SKILL.md b/plugins/do-it/skills/do-it-planning/SKILL.md index eb9b367..ca04004 100644 --- a/plugins/do-it/skills/do-it-planning/SKILL.md +++ b/plugins/do-it/skills/do-it-planning/SKILL.md @@ -37,7 +37,7 @@ Parent-only unless explicitly assigned: - use for wave, phase, release, multi-agent, durable workflow, or cross-boundary planning; - lock scope, write ownership, non-goals, and integration ownership; -- run grill, interface, architecture, domain-language, or slicing drills as needed; +- run grill, interface, architecture, vocabulary (do-it-context), or slicing drills as needed; - stop for approval if the user asked to confirm the plan. ## Planning Sequence @@ -112,9 +112,28 @@ mkdir -p .do-it/runtime && printf '%s' "<slug>" > .do-it/runtime/pointer See `do-it-router` § Task Pointer for the full protocol. Inline plans that never produce a `<slug>.md` file do not need to write the pointer. -## Handbook Alignment +## Task Card Layout -When `.do-it/handbook/` exists, a durable `.do-it/plans/<slug>.md` card follows the section order in `.do-it/handbook/task-card-template.md` — frontmatter, then Background & Goal, Allowed Scope, Deferred, Acceptance Criteria, Verification, Shared File Hazards & Dependencies. The template owns the canonical layout; the lenses and required artifacts in this skill fill those sections. When the handbook is absent and the work spans many files or sessions, suggest `do-it-handbook` to scaffold it rather than inventing a one-off structure. +A durable `.do-it/plans/<slug>.md` card uses this canonical layout; the lenses +and required artifacts in this skill fill the sections. + +Frontmatter (block-quoted bullets): **Card ID**, **Source/Background**, +**Target** (repo-relative paths), **Size** (S ≤ 5 files, M ≤ 20, L ≤ 100, +XL > 100), **Tier** (Light/Standard/Heavy), **Prerequisite**, **Blocks**, +**Owner**, **Grill** (slug or `none`), **Brainstorm** (slug or `none`). + +Sections, in order: + +1. **Background & Goal** — why it matters, plus a one-sentence goal (one card = one goal). +2. **Allowed Scope** — exhaustive list of files the card touches, with the change per file. +3. **Deferred** — anything intentionally out of scope, each citing a backlog issue; write `Nothing deferred.` if none. +4. **Acceptance Criteria** — table of stable AC IDs (AC1, AC2, …) each with a verifiable Evidence column. +5. **Verification** — concrete shell commands ordered build → test → lint → integration; put the Evidence Ledger here for Heavy, release/install, multi-agent, or durable-plan work. +6. **Shared File Hazards & Dependencies** — shared files that may collide with other cards in the wave; write `No shared-file hazards.` if none. + +All paths are repository-relative. When the work spans many files or sessions +and no `.do-it/handbook/` exists yet, suggest `do-it-handbook` to scaffold the +project-truth files rather than inventing a one-off structure. ## Required Planning Artifacts @@ -203,6 +222,27 @@ Include: Keep file paths and code snippets out of durable PRD prose unless the user asks for a code-facing plan; they go stale faster than domain decisions. +## Visual Aids (optional) + +When seeing an option is materially clearer than reading it — UI layout +alternatives, architecture/data-flow diagrams, before/after states, side-by-side +interface shapes, or visual task sequencing for multi-agent work — produce the +smallest useful artifact under `.do-it/visual/<topic>/` (descriptive filenames +like `option-a-flow.md`, `api-boundary.svg`), compare 2-3 options with explicit +tradeoffs, and name a recommendation. Feed that decision back into this plan card +(or `do-it-interface-drill` / `do-it-architecture-scan` when it shapes a contract +or boundary). + +Treat visuals as auxiliary evidence, not durable plan output: the decision still +lands in the plan card. Skip them for text-only decisions, one-line questions, or +where a table is clearer. A visual aid never promotes a task's tier by itself. + +For browser-based side-by-side comparison, this skill ships an optional local +visual companion under `scripts/` (a small static server plus `plan-card` / +`review-report` render templates). Load `references/visual-companion.md` only +when you actually need the browser render; for everything else, file-based +sketches in `.do-it/visual/` are enough. + ## Output Shape - Tier and task class. diff --git a/plugins/do-it/skills/do-it-visual-planning/references/visual-companion.md b/plugins/do-it/skills/do-it-planning/references/visual-companion.md similarity index 100% rename from plugins/do-it/skills/do-it-visual-planning/references/visual-companion.md rename to plugins/do-it/skills/do-it-planning/references/visual-companion.md diff --git a/plugins/do-it/skills/do-it-planning/scripts/frame-template.html b/plugins/do-it/skills/do-it-planning/scripts/frame-template.html new file mode 100644 index 0000000..f0634c0 --- /dev/null +++ b/plugins/do-it/skills/do-it-planning/scripts/frame-template.html @@ -0,0 +1,855 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>do-it Visual Planning + + + + + + +
+

+ + + do-it + Visual Planning + +

+
Connected
+
+ +
+
+ +
+
+ +
+ Click an option above, then return to the terminal +
+ + + diff --git a/plugins/do-it/skills/do-it-visual-planning/scripts/helper.js b/plugins/do-it/skills/do-it-planning/scripts/helper.js similarity index 100% rename from plugins/do-it/skills/do-it-visual-planning/scripts/helper.js rename to plugins/do-it/skills/do-it-planning/scripts/helper.js diff --git a/plugins/do-it/skills/do-it-visual-planning/scripts/server.cjs b/plugins/do-it/skills/do-it-planning/scripts/server.cjs similarity index 100% rename from plugins/do-it/skills/do-it-visual-planning/scripts/server.cjs rename to plugins/do-it/skills/do-it-planning/scripts/server.cjs diff --git a/plugins/do-it/skills/do-it-visual-planning/scripts/start-server.sh b/plugins/do-it/skills/do-it-planning/scripts/start-server.sh similarity index 100% rename from plugins/do-it/skills/do-it-visual-planning/scripts/start-server.sh rename to plugins/do-it/skills/do-it-planning/scripts/start-server.sh diff --git a/plugins/do-it/skills/do-it-visual-planning/scripts/stop-server.sh b/plugins/do-it/skills/do-it-planning/scripts/stop-server.sh similarity index 100% rename from plugins/do-it/skills/do-it-visual-planning/scripts/stop-server.sh rename to plugins/do-it/skills/do-it-planning/scripts/stop-server.sh diff --git a/skills/do-it/do-it-visual-planning/templates/plan-card.html b/plugins/do-it/skills/do-it-planning/templates/plan-card.html similarity index 92% rename from skills/do-it/do-it-visual-planning/templates/plan-card.html rename to plugins/do-it/skills/do-it-planning/templates/plan-card.html index facf904..3d3ef2d 100644 --- a/skills/do-it/do-it-visual-planning/templates/plan-card.html +++ b/plugins/do-it/skills/do-it-planning/templates/plan-card.html @@ -1,5 +1,5 @@
diff --git a/plugins/do-it/skills/do-it-visual-planning/templates/review-report.html b/plugins/do-it/skills/do-it-planning/templates/review-report.html similarity index 98% rename from plugins/do-it/skills/do-it-visual-planning/templates/review-report.html rename to plugins/do-it/skills/do-it-planning/templates/review-report.html index 367fb1c..e7c6eb6 100644 --- a/plugins/do-it/skills/do-it-visual-planning/templates/review-report.html +++ b/plugins/do-it/skills/do-it-planning/templates/review-report.html @@ -1,5 +1,5 @@ placeholder in #do-it-content. - * All class names below form the contract consumed by helper.js and - * server.cjs (.option/.card/.selected/#indicator-text/...) — keep them. - */ - - * { box-sizing: border-box; margin: 0; padding: 0; } - html, body { height: 100%; overflow: hidden; } - - /* ===== THEME VARIABLES — light (warm paper) ===== */ - :root { - --bg-primary: #f3f1ec; - --bg-secondary: #ffffff; - --bg-tertiary: #ece9e1; - --bg-code: #f6f4ee; - --border: #ddd8cb; - --border-strong: #c8c2b1; - --grid: rgba(46, 40, 22, 0.04); - --text-primary: #201e18; - --text-secondary: #6c6557; - --text-tertiary: #9b9484; - --accent: #2f5fe0; - --accent-hover: #1f48bf; - --accent-soft: rgba(47, 95, 224, 0.10); - --success: #2f9e44; - --warning: #bd820c; - --error: #d4443c; - --selected-bg: rgba(47, 95, 224, 0.08); - --selected-border: #2f5fe0; - --shadow-sm: 0 1px 2px rgba(28, 24, 14, 0.06); - --shadow-md: 0 1px 2px rgba(28, 24, 14, 0.05), 0 10px 26px -14px rgba(28, 24, 14, 0.28); - --font-display: 'Fraunces', 'Iowan Old Style', Georgia, 'Times New Roman', serif; - --font-body: 'IBM Plex Sans', ui-sans-serif, system-ui, -apple-system, sans-serif; - --font-mono: 'IBM Plex Mono', ui-monospace, SFMono-Regular, Menlo, monospace; - } - - @media (prefers-color-scheme: dark) { - :root { - --bg-primary: #15161c; - --bg-secondary: #1d1f28; - --bg-tertiary: #282b38; - --bg-code: #11121a; - --border: #313440; - --border-strong: #444855; - --grid: rgba(255, 255, 255, 0.022); - --text-primary: #e9e9ee; - --text-secondary: #a1a1af; - --text-tertiary: #6b6c7b; - --accent: #7c9bff; - --accent-hover: #98b0ff; - --accent-soft: rgba(124, 155, 255, 0.14); - --success: #4cc46a; - --warning: #e0a93a; - --error: #f0635a; - --selected-bg: rgba(124, 155, 255, 0.12); - --selected-border: #7c9bff; - --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.35); - --shadow-md: 0 1px 2px rgba(0, 0, 0, 0.4), 0 14px 32px -16px rgba(0, 0, 0, 0.7); - } - } - - body { - font-family: var(--font-body); - background: var(--bg-primary); - color: var(--text-primary); - display: flex; - flex-direction: column; - line-height: 1.6; - font-weight: 400; - -webkit-font-smoothing: antialiased; - text-rendering: optimizeLegibility; - } - - ::selection { background: var(--accent-soft); } - - /* ===== FRAME: HEADER ===== */ - .header { - position: relative; - flex-shrink: 0; - height: 3.1rem; - padding: 0 1.4rem; - display: flex; - align-items: center; - justify-content: space-between; - background: var(--bg-secondary); - border-bottom: 1px solid var(--border); - } - .header::after { - content: ''; - position: absolute; - left: 0; right: 0; bottom: -1px; - height: 2px; - background: linear-gradient(90deg, var(--accent), transparent 38%); - opacity: 0.85; - } - .header h1 { font-size: 1rem; font-weight: 400; } - .header h1 a { - display: flex; - align-items: center; - gap: 0.6rem; - color: inherit; - text-decoration: none; - } - .brand-mark { - width: 1.4rem; height: 1.4rem; - border-radius: 6px; - background: linear-gradient(140deg, var(--accent), var(--accent-hover)); - box-shadow: var(--shadow-sm), inset 0 1px 0 rgba(255, 255, 255, 0.22); - position: relative; - flex-shrink: 0; - } - .brand-mark::before { - content: ''; - position: absolute; - inset: 0; - margin: auto; - width: 0.42rem; height: 0.42rem; - border-radius: 2px; - background: var(--bg-secondary); - } - .brand-name { - font-family: var(--font-mono); - font-weight: 600; - font-size: 0.92rem; - letter-spacing: 0.01em; - color: var(--text-primary); - } - .brand-sub { - font-family: var(--font-mono); - font-size: 0.68rem; - text-transform: uppercase; - letter-spacing: 0.16em; - color: var(--text-tertiary); - padding-left: 0.6rem; - border-left: 1px solid var(--border); - } - .header .status { - font-family: var(--font-mono); - font-size: 0.66rem; - text-transform: uppercase; - letter-spacing: 0.13em; - color: var(--text-secondary); - display: flex; - align-items: center; - gap: 0.45rem; - } - .header .status::before { - content: ''; - width: 6px; height: 6px; - border-radius: 50%; - background: var(--success); - box-shadow: 0 0 0 0 var(--success); - animation: pulse 2.6s ease-out infinite; - } - @keyframes pulse { - 0% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--success) 55%, transparent); } - 70%, 100% { box-shadow: 0 0 0 7px transparent; } - } - - /* ===== FRAME: MAIN ===== */ - .main { - flex: 1; - overflow-y: auto; - background-color: var(--bg-primary); - background-image: - linear-gradient(var(--grid) 1px, transparent 1px), - linear-gradient(90deg, var(--grid) 1px, transparent 1px); - background-size: 30px 30px; - background-position: center top; - } - .main::-webkit-scrollbar { width: 11px; } - .main::-webkit-scrollbar-thumb { - background: var(--border-strong); - border: 3px solid var(--bg-primary); - border-radius: 999px; - } - .main::-webkit-scrollbar-track { background: transparent; } - - #do-it-content { - max-width: 50rem; - margin: 0 auto; - padding: 2.75rem 2.25rem 4.5rem; - min-height: 100%; - } - - /* ===== FRAME: INDICATOR BAR ===== */ - .indicator-bar { - flex-shrink: 0; - background: var(--bg-secondary); - border-top: 1px solid var(--border); - padding: 0.6rem 1.4rem; - text-align: center; - } - .indicator-bar span { - font-family: var(--font-mono); - font-size: 0.7rem; - letter-spacing: 0.04em; - color: var(--text-tertiary); - } - .indicator-bar .selected-text { - color: var(--accent); - font-weight: 600; - } - - /* ===== TYPOGRAPHY ===== */ - h2 { - font-family: var(--font-display); - font-optical-sizing: auto; - font-size: 2.05rem; - font-weight: 600; - line-height: 1.12; - letter-spacing: -0.014em; - margin-bottom: 0.55rem; - } - h3 { - font-family: var(--font-body); - font-size: 1.05rem; - font-weight: 600; - letter-spacing: -0.005em; - margin-bottom: 0.25rem; - } - h4 { font-family: var(--font-body); } - p { color: var(--text-primary); } - a { color: var(--accent); } - - .subtitle { - color: var(--text-secondary); - font-size: 1.02rem; - line-height: 1.55; - margin-bottom: 1.5rem; - } - - /* Section eyebrow label — monospace with an accent tick. */ - .label { - display: flex; - align-items: center; - gap: 0.55rem; - font-family: var(--font-mono); - font-size: 0.68rem; - font-weight: 600; - text-transform: uppercase; - letter-spacing: 0.15em; - color: var(--text-secondary); - margin-bottom: 0.7rem; - } - .label::before { - content: ''; - width: 1.1rem; height: 2px; - background: var(--accent); - border-radius: 2px; - flex-shrink: 0; - } - - /* Sections: staggered rise-in on load. */ - .section { margin-bottom: 2rem; } - .section > p { color: var(--text-secondary); } - .section ul { margin-left: 1.15rem; } - .section li { margin-bottom: 0.35rem; color: var(--text-secondary); } - #do-it-content > .section { - animation: rise 0.5s cubic-bezier(0.22, 0.7, 0.2, 1) both; - } - #do-it-content > .section:nth-child(1) { animation-delay: 0.02s; } - #do-it-content > .section:nth-child(2) { animation-delay: 0.08s; } - #do-it-content > .section:nth-child(3) { animation-delay: 0.14s; } - #do-it-content > .section:nth-child(4) { animation-delay: 0.20s; } - #do-it-content > .section:nth-child(5) { animation-delay: 0.26s; } - #do-it-content > .section:nth-child(6) { animation-delay: 0.32s; } - #do-it-content > .section:nth-child(n+7) { animation-delay: 0.38s; } - @keyframes rise { - from { opacity: 0; transform: translateY(10px); } - to { opacity: 1; transform: translateY(0); } - } - - code, .mono { font-family: var(--font-mono); font-size: 0.86em; } - .section :not(pre) > code { - background: var(--bg-code); - border: 1px solid var(--border); - border-radius: 4px; - padding: 0.05rem 0.32rem; - color: var(--text-primary); - } - - /* ===== META ROW — monospace key/value chips ===== */ - .meta-row { - display: flex; - flex-wrap: wrap; - gap: 0.5rem; - margin-bottom: 1.6rem; - } - .meta-row span { - font-family: var(--font-mono); - font-size: 0.72rem; - color: var(--text-secondary); - background: var(--bg-secondary); - border: 1px solid var(--border); - border-radius: 999px; - padding: 0.26rem 0.72rem; - box-shadow: var(--shadow-sm); - } - .meta-row b { color: var(--text-primary); font-weight: 600; } - - /* ===== OPTIONS (A/B/C choices) ===== */ - .options { display: flex; flex-direction: column; gap: 0.7rem; } - .option { - background: var(--bg-secondary); - border: 1px solid var(--border); - border-radius: 13px; - padding: 1rem 1.2rem; - cursor: pointer; - transition: border-color 0.16s ease, transform 0.16s ease, box-shadow 0.16s ease; - display: flex; - align-items: flex-start; - gap: 1rem; - box-shadow: var(--shadow-sm); - } - .option:hover { border-color: var(--accent); transform: translateY(-1px); box-shadow: var(--shadow-md); } - .option.selected { background: var(--selected-bg); border-color: var(--selected-border); box-shadow: var(--shadow-md); } - .option .letter { - font-family: var(--font-mono); - background: var(--bg-tertiary); - color: var(--text-secondary); - width: 1.8rem; height: 1.8rem; - border-radius: 7px; - display: flex; align-items: center; justify-content: center; - font-weight: 600; font-size: 0.82rem; flex-shrink: 0; - transition: background 0.16s ease, color 0.16s ease; - } - .option.selected .letter { background: var(--accent); color: #fff; } - .option .content { flex: 1; } - .option .content h3 { font-size: 0.95rem; margin-bottom: 0.15rem; } - .option .content p { color: var(--text-secondary); font-size: 0.86rem; margin: 0; } - - /* ===== CARDS (designs / mockups) ===== */ - .cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(270px, 1fr)); gap: 1rem; } - .card { - background: var(--bg-secondary); - border: 1px solid var(--border); - border-radius: 13px; - overflow: hidden; - cursor: pointer; - box-shadow: var(--shadow-sm); - transition: border-color 0.16s ease, transform 0.16s ease, box-shadow 0.16s ease; - } - .card:hover { border-color: var(--accent); transform: translateY(-3px); box-shadow: var(--shadow-md); } - .card.selected { border-color: var(--selected-border); box-shadow: var(--shadow-md); } - .card-image { background: var(--bg-tertiary); aspect-ratio: 16/10; display: flex; align-items: center; justify-content: center; } - .card-body { padding: 1rem 1.1rem; } - .card-body h3 { margin-bottom: 0.25rem; } - .card-body p { color: var(--text-secondary); font-size: 0.86rem; } - - /* ===== MOCKUP CONTAINER ===== */ - .mockup { - background: var(--bg-secondary); - border: 1px solid var(--border); - border-radius: 13px; - overflow: hidden; - margin-bottom: 1.5rem; - box-shadow: var(--shadow-sm); - } - .mockup-header { - background: var(--bg-tertiary); - padding: 0.5rem 1rem; - font-family: var(--font-mono); - font-size: 0.72rem; - letter-spacing: 0.04em; - color: var(--text-secondary); - border-bottom: 1px solid var(--border); - } - .mockup-body { padding: 1.5rem; } - - /* ===== SPLIT VIEW ===== */ - .split { display: grid; grid-template-columns: 1fr 1fr; gap: 1.4rem; } - @media (max-width: 700px) { .split { grid-template-columns: 1fr; } } - - /* ===== PROS / CONS ===== */ - .pros-cons { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: 1rem 0; } - .pros, .cons { - background: var(--bg-secondary); - border: 1px solid var(--border); - border-radius: 11px; - padding: 1rem 1.1rem; - } - .pros h4, .cons h4 { - font-family: var(--font-mono); - font-size: 0.7rem; - text-transform: uppercase; - letter-spacing: 0.1em; - margin-bottom: 0.55rem; - } - .pros h4 { color: var(--success); } - .cons h4 { color: var(--error); } - .pros ul, .cons ul { margin-left: 1.15rem; font-size: 0.86rem; color: var(--text-secondary); } - .pros li, .cons li { margin-bottom: 0.28rem; } - - /* ===== PLACEHOLDER ===== */ - .placeholder { - background: var(--bg-tertiary); - border: 1.5px dashed var(--border-strong); - border-radius: 10px; - padding: 2rem; - text-align: center; - font-family: var(--font-mono); - font-size: 0.8rem; - color: var(--text-tertiary); - } - - /* ===== INLINE MOCKUP ELEMENTS ===== */ - .mock-nav { background: var(--accent); color: #fff; padding: 0.75rem 1rem; display: flex; gap: 1.5rem; font-size: 0.9rem; } - .mock-sidebar { background: var(--bg-tertiary); padding: 1rem; min-width: 180px; } - .mock-content { padding: 1.5rem; flex: 1; } - .mock-button { background: var(--accent); color: #fff; border: none; padding: 0.5rem 1rem; border-radius: 7px; font-size: 0.85rem; font-family: var(--font-body); cursor: pointer; } - .mock-input { background: var(--bg-primary); border: 1px solid var(--border); border-radius: 7px; padding: 0.5rem; width: 100%; font-family: var(--font-body); } - - /* ===== SCENARIO TEMPLATES (plan card / review report) ===== */ - table.do-it-table { - width: 100%; - border-collapse: separate; - border-spacing: 0; - font-size: 0.85rem; - margin: 0.5rem 0; - background: var(--bg-secondary); - border: 1px solid var(--border); - border-radius: 11px; - overflow: hidden; - box-shadow: var(--shadow-sm); - } - table.do-it-table th, table.do-it-table td { - padding: 0.55rem 0.8rem; - text-align: left; - vertical-align: top; - border-bottom: 1px solid var(--border); - } - table.do-it-table tr:last-child td { border-bottom: none; } - table.do-it-table th { - background: var(--bg-tertiary); - font-family: var(--font-mono); - font-size: 0.66rem; - font-weight: 600; - text-transform: uppercase; - letter-spacing: 0.1em; - color: var(--text-secondary); - } - table.do-it-table td:first-child { - font-family: var(--font-mono); - font-size: 0.78rem; - font-weight: 600; - color: var(--accent); - white-space: nowrap; - } - table.do-it-table td { color: var(--text-secondary); } - - .finding { - position: relative; - background: var(--bg-secondary); - border: 1px solid var(--border); - border-left: 3px solid var(--border-strong); - border-radius: 9px; - padding: 0.75rem 1rem; - margin-bottom: 0.7rem; - box-shadow: var(--shadow-sm); - } - .finding .sev { - font-family: var(--font-mono); - font-size: 0.64rem; - font-weight: 600; - text-transform: uppercase; - letter-spacing: 0.13em; - margin-bottom: 0.3rem; - } - .finding p { font-size: 0.9rem; color: var(--text-primary); } - .finding.blocking { border-left-color: var(--error); } - .finding.blocking .sev { color: var(--error); } - .finding.important { border-left-color: var(--warning); } - .finding.important .sev { color: var(--warning); } - .finding.opportunity { border-left-color: var(--success); } - .finding.opportunity .sev { color: var(--success); } - .finding .evidence { - font-family: var(--font-mono); - font-size: 0.74rem; - line-height: 1.55; - color: var(--text-secondary); - background: var(--bg-code); - border: 1px solid var(--border); - border-radius: 6px; - padding: 0.45rem 0.6rem; - margin-top: 0.45rem; - white-space: pre-wrap; - } - - @media (prefers-reduced-motion: reduce) { - *, *::before { animation: none !important; transition: none !important; } - } - - - -
-

- - - do-it - Visual Planning - -

-
Connected
-
- -
-
- -
-
- -
- Click an option above, then return to the terminal -
- - - diff --git a/scripts/build-index-json.mjs b/scripts/build-index-json.mjs index 74159aa..b446f08 100644 --- a/scripts/build-index-json.mjs +++ b/scripts/build-index-json.mjs @@ -26,16 +26,13 @@ const SKILL_GROUPS = new Map([ ["do-it-interface-drill", "on-demand"], ["do-it-debugging", "on-demand"], ["do-it-slicing", "on-demand"], - ["do-it-domain-language", "on-demand"], ["do-it-comments-discipline", "on-demand"], ["do-it-worktree-isolation", "on-demand"], ["do-it-branch-closeout", "on-demand"], ["do-it-subagent-orchestration", "on-demand"], ["do-it-handbook", "maintenance"], ["do-it-context", "maintenance"], - ["do-it-grill-log", "maintenance"], - ["do-it-skill-authoring", "maintenance"], - ["do-it-visual-planning", "optional"] + ["do-it-skill-authoring", "maintenance"] ]); function repoPath(relativePath) { diff --git a/scripts/build-skills-index.mjs b/scripts/build-skills-index.mjs index 09ebde8..a506130 100644 --- a/scripts/build-skills-index.mjs +++ b/scripts/build-skills-index.mjs @@ -32,7 +32,6 @@ const ON_DEMAND = [ "do-it-interface-drill", "do-it-debugging", "do-it-slicing", - "do-it-domain-language", "do-it-comments-discipline", "do-it-worktree-isolation", "do-it-branch-closeout", @@ -42,7 +41,6 @@ const ON_DEMAND = [ const HANDBOOK = [ "do-it-handbook", "do-it-context", - "do-it-grill-log", "do-it-skill-authoring" ]; diff --git a/scripts/test-hooks.sh b/scripts/test-hooks.sh index b15a0c2..d73c32a 100644 --- a/scripts/test-hooks.sh +++ b/scripts/test-hooks.sh @@ -265,4 +265,68 @@ run_router "$withcode_session" "release 我想确认 src/release.ts" withcode_grill="$(run_grill "$withcode_session" "release 我想确认 src/release.ts")" assert_contains "$withcode_grill" "trigger: uncertainty" "Standard + uncertainty + dim_touches_code=1 should still grill" +# ---- advisory nudges (plan-card reliability + existing-codebase) ---- + +# Plan-card nudge: after grill on durable-plan work with no plan card, a later +# grilled turn emits a one-shot plan-card nudge. +nudge_project="$TMP_ROOT/plan-nudge-project" +mkdir -p "$nudge_project" +plan_nudge_session="plan-card-nudge" +run_router "$plan_nudge_session" "Prepare the release schema migration" "$nudge_project" +run_grill "$plan_nudge_session" "Prepare the release schema migration" "$nudge_project" >/dev/null +[[ "$(state_value "$plan_nudge_session" durable_plan_seen)" == "1" ]] \ + || fail "Heavy turn should set durable_plan_seen" +run_router "$plan_nudge_session" "ok implement it" "$nudge_project" +plan_nudge_out="$(run_grill "$plan_nudge_session" "ok implement it" "$nudge_project")" +assert_contains "$plan_nudge_out" "no .do-it/plans/.md exists yet" \ + "post-grill durable work with no plan card should nudge planning" + +# one-shot: a third turn does not repeat the plan nudge +run_router "$plan_nudge_session" "continue implementing" "$nudge_project" +plan_nudge_repeat="$(run_grill "$plan_nudge_session" "continue implementing" "$nudge_project")" +[[ "$plan_nudge_repeat" != *"no .do-it/plans/.md exists yet"* ]] \ + || fail "plan-card nudge should be one-shot per session" + +# with a plan card present, no plan nudge +nudge_has_plan="$TMP_ROOT/plan-present-project" +mkdir -p "$nudge_has_plan/.do-it/plans" +printf '# plan\n' > "$nudge_has_plan/.do-it/plans/task.md" +has_plan_session="plan-present" +run_router "$has_plan_session" "Prepare the release schema migration" "$nudge_has_plan" +run_grill "$has_plan_session" "Prepare the release schema migration" "$nudge_has_plan" >/dev/null +run_router "$has_plan_session" "ok implement it" "$nudge_has_plan" +has_plan_out="$(run_grill "$has_plan_session" "ok implement it" "$nudge_has_plan")" +[[ "$has_plan_out" != *"no .do-it/plans/.md exists yet"* ]] \ + || fail "existing plan card should suppress the planning nudge" + +# Port/restore intent emits a one-shot "grep current code first" nudge. +port_session="port-intent-nudge" +run_router "$port_session" "port the BudgetService from v0.1" "$REPO_ROOT" +[[ "$(state_value "$port_session" port_intent)" == "1" ]] \ + || fail "port prompt should set port_intent" +port_out="$(run_grill "$port_session" "port the BudgetService from v0.1" "$REPO_ROOT")" +assert_contains "$port_out" "port / restore / reintroduce work" \ + "port intent should nudge to grep current code first" + +# Established project (has .do-it/CONTEXT.md) + Standard code edit emits the +# read-existing nudge; a greenfield repo does not. +brown_project="$TMP_ROOT/brownfield-project" +mkdir -p "$brown_project/.do-it" +printf '# context\n' > "$brown_project/.do-it/CONTEXT.md" +brown_session="brownfield-nudge" +run_router "$brown_session" "Implement the cleanup in src/util.ts" "$brown_project" +[[ "$(state_value "$brown_session" dim_brownfield)" == "1" ]] \ + || fail "project with .do-it/CONTEXT.md should set dim_brownfield" +brown_out="$(run_grill "$brown_session" "Implement the cleanup in src/util.ts" "$brown_project")" +assert_contains "$brown_out" "established codebase" \ + "brownfield Standard code edit should nudge read-existing" + +greenfield_project="$TMP_ROOT/greenfield-project" +mkdir -p "$greenfield_project" +greenfield_session="greenfield-no-nudge" +run_router "$greenfield_session" "Implement the cleanup in src/util.ts" "$greenfield_project" +green_out="$(run_grill "$greenfield_session" "Implement the cleanup in src/util.ts" "$greenfield_project")" +[[ "$green_out" != *"established codebase"* ]] \ + || fail "greenfield repo should not emit the read-existing nudge" + echo "[test-hooks] ok" diff --git a/skills/do-it/do-it-brainstorm/SKILL.md b/skills/do-it/do-it-brainstorm/SKILL.md index 5694f3b..cc4664f 100644 --- a/skills/do-it/do-it-brainstorm/SKILL.md +++ b/skills/do-it/do-it-brainstorm/SKILL.md @@ -148,7 +148,7 @@ When durable handoff is useful, write: .do-it/brainstorm/.md ``` -`` follows the same rule as `do-it-grill-log`: slug from the user title or a short hash, with an optional session prefix. `/.do-it/brainstorm/.gitkeep` should exist when the project tracks do-it artifacts. +`` follows the same slug rule as the grill log (see `do-it-grill` § Grill Log Artifact): slug from the user title or a short hash, with an optional session prefix. `/.do-it/brainstorm/.gitkeep` should exist when the project tracks do-it artifacts. In the same turn, write the slug to the task pointer so router and other skills can pick it up: @@ -288,7 +288,6 @@ After discussion or artifact creation: - `do-it-router` — sets tier and decides whether brainstorm is useful. - `do-it-subagent-orchestration` — dispatch contract for selected lenses. -- `do-it-grill` — converges the must-discuss stack. -- `do-it-grill-log` — records resolved facts and decisions. +- `do-it-grill` — converges the must-discuss stack and records resolved facts and decisions in its grill log. - `do-it-review-loop` — reviews delivered diff, skill quality, install readiness, and release risk after implementation. - `do-it-context` — sediments terms anchored during brainstorm or grill. diff --git a/skills/do-it/do-it-context/SKILL.md b/skills/do-it/do-it-context/SKILL.md index d1f6f06..c8034c0 100644 --- a/skills/do-it/do-it-context/SKILL.md +++ b/skills/do-it/do-it-context/SKILL.md @@ -1,13 +1,13 @@ --- name: do-it-context -description: "Use when repo terms or invariants are drifting and `.do-it/CONTEXT.md` should become the downstream source of truth for names, relationships, and facts." +description: "Use when repo terms or invariants are drifting, or when user/docs/code naming disagrees and a canonical glossary is needed — `.do-it/CONTEXT.md` is the downstream source of truth for names, relationships, and facts." --- # Do-It Context ## Purpose -`.do-it/CONTEXT.md` is the single canonical place where this project's terminology, invariants, and relationship-shapes live for AI workflows. Other skills (especially `do-it-grill`, `do-it-planning`, `do-it-review-loop`, `do-it-domain-language`) read it before debating definitions. +`.do-it/CONTEXT.md` is the single canonical place where this project's terminology, invariants, and relationship-shapes live for AI workflows. Other skills (especially `do-it-grill`, `do-it-planning`, `do-it-review-loop`) read it before debating definitions. This skill also owns the deeper domain-language pass (canonical glossary + contradiction checks) — see § Domain Glossary Mode. It is **not** a wiki, README replacement, or onboarding doc. It is a terse, declarative artifact intended to fit in the AI's working memory budget. Keep it under ~200 lines. @@ -31,11 +31,15 @@ When context sources disagree, use this order: 1. Current code, tests, schemas, manifests, generated source-of-truth scripts, and live command output. -2. `.do-it/CONTEXT.md` for terse repo terms, invariants, and relationships that +2. `CLAUDE.md` (or the host's equivalent root agent-instruction file) for + durable, human-authored conventions and behavioral rules the team chose — + authoritative for *how to work here*, though current code still wins on + *what the code is*. +3. `.do-it/CONTEXT.md` for terse repo terms, invariants, and relationships that code does not express accessibly. -3. Current plan, grill log, task card, or issue for the active work. -4. README, docs, ADRs, and maintenance guides. -5. Memory, old reports, previous worker summaries, and external sources. +4. Current plan, grill log, task card, or issue for the active work. +5. README, docs, ADRs, and maintenance guides. +6. Memory, old reports, previous worker summaries, and external sources. Lower layers can point to what to inspect, but they do not override current repo truth. @@ -87,6 +91,85 @@ Roughly quarterly, or when the file crosses ~200 lines: 2. Find lines that no longer match the code; rewrite or delete. 3. Find lines that have moved into the type system / schema and can now be deleted. +## CLAUDE.md (durable conventions) + +`CLAUDE.md` (or the host's equivalent root instruction file) holds the durable, +human-owned conventions for how agents work in this project — coding standards, +review bar, do/don't rules, restraint principles. do-it reads it before grill +and planning. It differs from the other do-it homes: + +- **CLAUDE.md** — durable *behavioral* conventions and team rules (human-owned, + rarely changes). +- **`.do-it/CONTEXT.md`** — per-session *factual* sediment (terms, invariants, + relationships) that `do-it-grill` writes. +- **`.do-it/handbook/`** — structural project docs (architecture, code map, + glossary, backlog). + +CLAUDE.md is the top of the convention ladder: a rule that has held across +sessions and is about *how to work* (not a project fact) graduates here from +`.do-it/CONTEXT.md`. + +When the user asks to set up or tidy CLAUDE.md, scaffold a lean skeleton on +demand — never auto-write, and never overwrite an existing CLAUDE.md (additive, +like the handbook bootstrap). A useful skeleton: + +```markdown +# — agent conventions + +## Restraint +- Prefer advisory nudges over write-blocking gates. +- Reuse or thin an existing module before adding a new one; do not build things + that grow unbounded. +- Read existing structure and git intent before deleting or rewriting. + +## Conventions +- + +## Review bar +- +``` + +Keep it short — CLAUDE.md is read every turn, so it competes for context budget. +Detail belongs in `.do-it/handbook/` or `docs/`. + +## Domain Glossary Mode (Standard+) + +The sediment workflow above is the Light path — one line per clarified term. For +non-trivial naming or modeling work (a new public API, schema, data model, phase +plan, or widespread terminology drift), do the deeper pass: build an explicit +canonical language map before names harden into code, docs, schemas, UI labels, +or handoffs. + +Sequence: + +1. Collect terms from the user request, docs, code, tests, schemas, logs, and UI copy. +2. Group synonyms, aliases, abbreviations, and deprecated terms. +3. Identify contradictions between code, docs, user language, and runtime behavior. +4. Define canonical terms from domain meaning, not implementation convenience. +5. Name domain entities, actions, states, invariants, and forbidden states. +6. Recommend what must change now and what can wait; feed interface/architecture + implications into the relevant do-it skill. + +Glossary shape: + +| Term | Definition | Source evidence | Aliases | Status | +| --- | --- | --- | --- | --- | +| canonical-term | ... | file/docs/user | old-term | canonical | + +Status values: `canonical` (use in new code/docs), `alias` (acceptable for +compatibility), `deprecated` (avoid in new work, migrate when touched), +`conflict` (sources disagree and need a decision). + +Contradiction checks — look for: a user term and a code term that mean different +things; docs describing a concept code models differently; a UI label hiding a +backend state distinction; schema names encoding transport detail instead of +domain meaning; tests using legacy terms; agents or task cards using different +names for the same ownership boundary. + +Stable canonical terms graduate into `glossary.md` via the three-session +promotion rule (see `do-it-handbook`). Do not rename code broadly when a glossary +is enough for the current task. + ## Stop Conditions Do not update CONTEXT.md when: @@ -130,4 +213,3 @@ Before relying on or updating CONTEXT.md: - `do-it-grill` — primary writer of new entries. - `do-it-planning` — reads CONTEXT.md before drafting plan cards. - `do-it-review-loop` — checks CONTEXT.md for contract terms before reviewing. -- `do-it-domain-language` — for the deeper "is this a coherent domain language" question. diff --git a/skills/do-it/do-it-domain-language/SKILL.md b/skills/do-it/do-it-domain-language/SKILL.md deleted file mode 100644 index 71b8160..0000000 --- a/skills/do-it/do-it-domain-language/SKILL.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -name: do-it-domain-language -description: "Use when user language, docs, and code naming disagree and a canonical domain glossary or handoff vocabulary is needed." ---- - -# Do-It Domain Language - -## Purpose - -Use this to make domain terms explicit before names become code, docs, schemas, UI labels, or agent handoffs. The output is a small canonical language map with contradictions and proposed resolutions. - -## Tier Rules - -### Light - -Use for a local naming decision. Inspect nearby code and docs, pick the least surprising term, and note aliases if needed. - -### Standard - -Default for subagents and non-trivial naming or model work. Build a glossary from user language, docs, code, tests, schemas, and UI text. - -### Heavy - -Parent-only unless explicitly assigned. Use for phase plans, data models, public APIs, workflow policy, migrations, or widespread terminology drift. - -## Sequence - -1. Collect terms from the user request, docs, code, tests, schemas, logs, and UI copy. -2. Group synonyms, aliases, abbreviations, and deprecated terms. -3. Identify contradictions between code, docs, user language, and runtime behavior. -4. Define canonical terms using domain meaning, not implementation convenience. -5. Name domain entities, actions, states, invariants, and forbidden states. -6. Recommend where terminology must change now and what can wait. -7. Feed interface or architecture implications into the relevant do-it skill. - -## Glossary Shape - -| Term | Definition | Source evidence | Aliases | Status | -| --- | --- | --- | --- | --- | -| canonical-term | ... | file/docs/user | old-term | canonical | - -Status values: - -- `canonical`: use in new code/docs. -- `alias`: acceptable when preserving compatibility. -- `deprecated`: avoid in new work, migrate when touched. -- `conflict`: current sources disagree and need a decision. - -## Contradiction Checks - -Look for: - -- user term means one thing, code term means another; -- docs describe a concept that code models differently; -- UI label hides a backend state distinction; -- schema names encode transport detail instead of domain meaning; -- tests use legacy terms that make new behavior ambiguous; -- agents or task cards use different names for the same ownership boundary. - -## Output Shape - -- Scope scanned. -- Canonical glossary. -- Contradictions and proposed resolution. -- Domain entities, actions, states, and invariants. -- Required naming changes for current work. -- Deferred terminology cleanup, if any. -- Interface or architecture follow-ups. - -## Common Mistakes - -- Renaming code broadly when a glossary is enough for the current task. -- Picking names from implementation detail instead of domain meaning. -- Treating aliases as harmless when they create conflicting behavior. -- Ignoring docs or UI copy while changing API names. -- Letting a subagent redefine canonical language outside its assigned slice. diff --git a/skills/do-it/do-it-grill-log/SKILL.md b/skills/do-it/do-it-grill-log/SKILL.md deleted file mode 100644 index a5ffe0d..0000000 --- a/skills/do-it/do-it-grill-log/SKILL.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -name: do-it-grill-log -description: "Use when grill facts or decisions need durable status logging as kind fact or decision before work continues." ---- - -# Do-It Grill Log - -## Purpose - -`.do-it/grill/.md` is the per-task artifact that records every fact or decision grilling has actually pressure-tested, the cheap falsifier you used when one exists, and the resolution. It outlives any single chat turn and feeds `do-it-planning` and `do-it-verification-gate`. - -Without it, grilling is just a vibe — once context compacts, every signal is gone. - -## When To Use - -- Inside `do-it-grill` after a fact has been tested or a user decision has been made — write the result here. -- Inside `do-it-planning` to confirm no unresolved item blocks the plan. -- Inside `do-it-verification-gate` (and the gate hook) — fail closeout only when an unresolved decision still changes execution or a factual premise is still unverified. - -## File Path - -``` -.do-it/grill/.md -``` - -`` should be: - -- the slug from the user's task title (lowercased, dash-separated, ≤32 chars), if one is obvious; -- otherwise the first 8 characters of the SHA-1 of the user's first prompt this turn; -- prefixed with the short session id when collisions are likely (e.g. `s1a2-fix-login`). - -`/.do-it/grill/.gitkeep` should exist so the directory tracks in version control. - -## File Format - -```markdown ---- -task: -session_id: -created: -status: open ---- - -## Items tested - -- [ ] **** - - kind: - - falsifier: - - status: - - evidence: - -## Anchored terms - -- ****: ← from CLAUDE.md / .do-it/CONTEXT.md / clarified this turn - -## Failure modes considered - -- correctness: ... -- contract: ... -- migration: ... -- performance: ... -- security: ... -- UX: ... -``` - -Use `confirmed` / `refuted` only for facts. Use `chosen` / `deferred` / `needs_user_decision` only for user preferences or product decisions. A `needs_user_decision` item blocks only when it changes the next execution step. When every blocking item is resolved, change frontmatter `status: open` → `status: resolved`. - -## Style rules - -- One bullet per item. No nested bullets in the bullet body — each item is independent. -- Falsifier must be cheap and deterministic. "Read the spec" is not a falsifier; "grep -F 'createOrder' src/" is. -- Evidence is the literal artifact: a path, a line number, a snippet of output. Never paraphrase. -- "Anchored terms" entries get sedimented to `.do-it/CONTEXT.md` (see `do-it-context`) — this section is just a working pad. -- Failure modes section captures predicted modes by category; it is permission-to-stop-thinking, not a binding promise. -- Do not mark a user preference as `confirmed`; if the user chose it, use `chosen`. -- Do not block closeout on a `deferred` preference unless the current implementation still depends on it. - -## Append-only discipline - -- New items are appended; existing items are mutated in place (`needs_user_decision` → `chosen`/`deferred`, or fact status filled in). Never delete an item — refute or defer it instead. -- The frontmatter `status` flips to `resolved` once no execution-blocking item remains. Do not flip it back to `open` retroactively without a new entry explaining why. - -## Worked example - -```markdown ---- -task: dedupe grill across same session -session_id: s1a2 -created: 2026-05-02 -status: resolved ---- - -## Items tested - -- [x] **Same-session re-grill is wasted unless prompt diverges materially.** - - kind: fact - - falsifier: count tokens injected for back-to-back implement requests in one transcript. - - status: confirmed - - evidence: hooks/grill-prompt.sh:38 — emits ~300 tokens; second call adds zero signal. -- [x] **Question turns must not consume the real same-session grill marker.** - - kind: fact - - falsifier: simulate question prompt followed by work prompt and inspect session state. - - status: confirmed - - evidence: hooks/router.sh sets `last_prompt_kind`, while hooks/grill-prompt.sh treats `grilled=1` as the real de-dup marker. - -## Anchored terms - -- **grilled**: a session-state flag in `${session_dir}/state.json`; value `1` means a real grill reminder fired this session. Question turns use `last_prompt_kind=question`. - -## Failure modes considered - -- correctness: forgetting to flip `grilled=1` would cause repeated injection — covered. -- contract: external scripts reading `state.json` would see new key — acceptable, additive. -``` - -## Common Rationalizations - -- *"I'll record it later."* — Later means after compaction, which means never. -- *"It's obvious why I confirmed this."* — Obvious to you now, not to verification next turn. -- *"This is too small to log."* — Then this premise wasn't load-bearing; you should not have grilled it. -- *"I changed my mind, let me delete that line."* — Mutate decision in place; `refuted` with evidence is more honest. - -## Red Flags - -- Every fact is `confirmed`. (Are you grilling, or rubber-stamping?) -- All facts are `refuted` and the plan still proceeds unchanged. (Why grill?) -- `status: resolved` with execution-blocking `needs_user_decision` items remaining. (Do not flip status until each blocking item resolves.) -- File grows past ~150 lines for a single task. (Probably needs splitting into sub-tasks, or the task is too broad.) - -## Stop Conditions - -Stop and return to `do-it-grill` or the user when: - -- a decision item is `needs_user_decision` and changes the next action; -- a fact has no cheap falsifier but the implementation depends on it; -- the log would need multiple unrelated task slugs to stay coherent; -- the evidence is only paraphrase, memory, or old transcript context. - -## Verification - -Before using the log as closeout evidence: - -- every execution-blocking fact is `confirmed` or `refuted`; -- every execution-blocking decision is `chosen`, `deferred`, or escalated; -- every evidence field points to a file, command, grep result, or explicit user choice; -- frontmatter `status: resolved` appears only when no blocking item remains. - -## Related Skills - -- `do-it-grill` — primary writer. -- `do-it-context` — destination for sediment of "anchored terms". -- `do-it-planning` — must read this file before producing the plan card; references the slug in plan frontmatter. -- `do-it-verification-gate` — must check that no execution-blocking unresolved item remains before allowing closeout. diff --git a/skills/do-it/do-it-grill/SKILL.md b/skills/do-it/do-it-grill/SKILL.md index c047c48..11ca100 100644 --- a/skills/do-it/do-it-grill/SKILL.md +++ b/skills/do-it/do-it-grill/SKILL.md @@ -21,7 +21,7 @@ A common failure is to dump a 5-question template at the user and call it grilli 2. **Anchor terms before debating intent.** If the user uses a term that has a definition in `CLAUDE.md`, `.do-it/CONTEXT.md`, or visible in code with a different shape — surface the conflict before going further. 3. **Verify, don't ask, when verification is cheap.** If the question can be answered with `rg`, `cat`, or a quick local command, do that and report what you found. 4. **Ask only for decisions.** Ask the user one focused question only when local truth cannot decide a preference, priority, or scope tradeoff that changes execution. Before asking, explain the decision in plain language, list the viable options with benefits/costs/risks, and recommend a default. -5. **Sediment what you learned.** When a term gets clarified or a constraint surfaces, append it to `.do-it/CONTEXT.md` (one line, declarative). Use `do-it-grill-log` for the per-task `.do-it/grill/.md` artifact (`kind: fact|decision`, falsifier, status, evidence). +5. **Sediment what you learned.** When a term gets clarified or a constraint surfaces, append it to `.do-it/CONTEXT.md` (one line, declarative). Record the per-task `.do-it/grill/.md` artifact (`kind: fact|decision`, falsifier, status, evidence) per § Grill Log Artifact below. ## When To Use @@ -71,7 +71,7 @@ Run this loop until every execution-blocking item is resolved: facts become `con 1. **Pick the most load-bearing premise.** What single belief, if wrong, would change the most downstream decisions? 2. **Try to falsify cheaply.** Read the file, grep for the symbol, run the unit test, glance at the schema. If you find evidence, jump to step 4. 3. **Ask one focused question** only when the remaining unknown is a user decision. Start with the minimum context the user needs, then show 2-3 real options with tradeoffs and a recommended default so the user has something concrete to accept or correct. -4. **Record the outcome** in `.do-it/grill/.md` (see `do-it-grill-log`). Use `kind: fact` with `confirmed/refuted` for evidence, or `kind: decision` with `chosen/deferred/needs_user_decision` for user preferences. +4. **Record the outcome** in `.do-it/grill/.md` (see § Grill Log Artifact). Use `kind: fact` with `confirmed/refuted` for evidence, or `kind: decision` with `chosen/deferred/needs_user_decision` for user preferences. 5. **Repeat** with the next-most-load-bearing premise, until the remaining unknowns no longer change the route. ## Assumptions Mode @@ -103,7 +103,7 @@ Convergence flow: 1. **Read the artifact.** Parse `Requirement Shape`, `Product Boundary`, `Core Goal`, `Options`, `Architecture Foundation`, and `Grill Handoff`. Each `Must Resolve In Grill` entry is a candidate premise the brainstorm lenses thought a human, grill, or local verification had to settle. 2. **Rank by route-impact.** Sort candidates by "if this is wrong, how many downstream choices change?" — same rule as the Iterative Loop. Cross-lens tensions usually outrank single-lens one-offs. -3. **Resolve each candidate** via the existing loop (verify cheaply, ask one question if a user decision is needed, log the result in `.do-it/grill/.md` per `do-it-grill-log`). +3. **Resolve each candidate** via the existing loop (verify cheaply, ask one question if a user decision is needed, log the result in `.do-it/grill/.md` per § Grill Log Artifact). 4. **Reference the brainstorm slug** in the grill log frontmatter: add `brainstorm: ` so `do-it-planning` and `do-it-verification-gate` can trace the lineage. 5. **Flip brainstorm status.** Once every execution-blocking `Must Resolve In Grill` item has a resolution (`chosen` / `deferred` / `needs_user_decision` for decisions; `confirmed` / `refuted` for facts), edit the brainstorm artifact's frontmatter from `status: open` to `status: converged`. Do not delete the artifact; future sessions read it. @@ -238,10 +238,53 @@ For a heavy grill: - Treating architecture taste as delivery truth. - Using a fuzzy term repeatedly without ever defining it back to the user or to `.do-it/CONTEXT.md`. +## Grill Log Artifact + +Grill records every pressure-tested fact or decision in `.do-it/grill/.md` +so the signal outlives the chat turn and feeds `do-it-planning` and +`do-it-verification-gate`. Without it, grilling is just a vibe — once context +compacts, every signal is gone. + +`` is the user's task title (lowercased, dash-separated, ≤32 chars) +when one is obvious, else the first 8 chars of the SHA-1 of the first prompt; +prefix with the short session id when collisions are likely. Keep +`.do-it/grill/.gitkeep` so the directory tracks in git. + +Format: + +```markdown +--- +task: +session_id: +created: +status: open # flips to `resolved` when no execution-blocking item remains +brainstorm: # only when converging a brainstorm artifact +--- + +## Items tested + +- [ ] **** + - kind: + - falsifier: + - status: + - evidence: + +## Anchored terms + +- ****: ← from CLAUDE.md / .do-it/CONTEXT.md / clarified this turn +``` + +Rules: use `confirmed`/`refuted` only for facts, `chosen`/`deferred`/`needs_user_decision` +only for decisions. A `needs_user_decision` item blocks only when it changes the +next execution step. Append new items and mutate existing ones in place — never +delete an item; refute or defer it with evidence. Anchored-terms entries get +sedimented to `.do-it/CONTEXT.md` (see `do-it-context`); this section is a +working pad. Flip `status: resolved` once no execution-blocking item remains, and +do not flip it back without a new entry explaining why. + ## Related Skills -- `do-it-context` — set up and maintain `.do-it/CONTEXT.md` with project terms and invariants. -- `do-it-grill-log` — write per-task `.do-it/grill/.md` artifacts (`kind`, falsifier, status, evidence). +- `do-it-context` — set up and maintain `.do-it/CONTEXT.md` with project terms and invariants (sediment destination for anchored terms). - `do-it-brainstorm` — divergent persona pass that runs before grill; produces the open decisions grill converges on. -- `do-it-planning` — consume the grill outcome into a plan card under `.do-it/plans/.md`. +- `do-it-planning` — consume the grill outcome into a plan card under `.do-it/plans/.md`; reads the grill slug. - `do-it-review-loop` — apply pressure to the delivered diff after grilling has set the bar. diff --git a/skills/do-it/do-it-handbook/SKILL.md b/skills/do-it/do-it-handbook/SKILL.md index b6970cb..87af4b6 100644 --- a/skills/do-it/do-it-handbook/SKILL.md +++ b/skills/do-it/do-it-handbook/SKILL.md @@ -1,13 +1,13 @@ --- name: do-it-handbook -description: "Use when a project needs a durable `.do-it/handbook/` skeleton for architecture, glossary, code map, backlog, runtime, maintenance, and workflow docs." +description: "Use when a project needs a durable `.do-it/handbook/` skeleton for architecture, invariants, glossary, code map, backlog, and runtime status." --- # Do-It Handbook ## Purpose -Use this to scaffold a long-lived handbook for a project that uses `do-it`. The handbook is the agent-readable source of truth for terms, invariants, ownership, and review discipline that does not change every turn. It complements the per-task artifacts (`.do-it/grill/`, `.do-it/plans/`, `.do-it/brainstorm/`) and the always-active sediment (`.do-it/CONTEXT.md`). +Use this to scaffold a long-lived handbook for a project that uses `do-it`. The handbook is the agent-readable source of truth for terms, invariants, ownership, and architecture that does not change every turn. It complements the per-task artifacts (`.do-it/grill/`, `.do-it/plans/`, `.do-it/brainstorm/`) and the always-active sediment (`.do-it/CONTEXT.md`). The shape is borrowed from a project that has shipped against it for a year (Do-SOUL Alaya). Files are intentionally small (< 30 KB each) so the agent can read whatever it needs without bloating context. @@ -33,14 +33,16 @@ Skip when: glossary.md # vocabulary (long-stable terms) backlog.md # cross-cutting unresolved issues with close conditions runtime-status.md # implementation status and known wiring gaps - maintenance.md # documentation update rules - task-card-template.md # template for non-trivial work briefs - workflow/ - agent-workflow.md # per-card / per-wave / phase pipelines - review-protocol.md # review mode, severity, evidence expectations - subagent-dispatch.md # how delegated workers are constrained ``` +The handbook holds only **project-specific truth** — the facts a generic skill +cannot carry. Process docs (task-card layout, review protocol, subagent +dispatch, execution pipeline, maintenance rules) are NOT scaffolded here: the +owning skills are their single source of truth (`do-it-planning`, +`do-it-review-loop`, `do-it-subagent-orchestration`, `do-it-router`, and the +`## Maintenance` section below). This keeps the handbook small and removes the +duplicate-doc drift that comes from copying skill prose into every project. + ## Bootstrap Behavior When invoked: @@ -50,7 +52,7 @@ When invoked: - If it does **and** some files are missing, copy only the missing files (additive, never overwrite). - If it does not exist, create the full tree. 2. Templates are copied verbatim from `templates/` under this skill. Each template is a skeleton with placeholder text the project owner replaces; do not hand-edit the project's handbook from inside the bootstrap step. -3. Add a `.gitkeep` to `.do-it/brainstorm/`, `.do-it/grill/`, `.do-it/plans/`, and `.do-it/handbook/workflow/` if any of those directories are missing, so the project tracks them in version control. +3. Add a `.gitkeep` to `.do-it/brainstorm/`, `.do-it/grill/`, and `.do-it/plans/` if any of those directories are missing, so the project tracks them in version control. 4. Print one line per file written, then a one-paragraph "next steps" pointer telling the user to start by filling in `invariants.md` and `glossary.md`. Do **not**: @@ -66,11 +68,14 @@ Do **not**: | `do-it-context` | `.do-it/CONTEXT.md` (active sediment) | `glossary.md` (long-stable terms) | | `do-it-architecture-scan` | inline review output | `architecture.md`, `invariants.md` | | `do-it-grill` | `.do-it/grill/.md` | `invariants.md`, `glossary.md` | -| `do-it-planning` | `.do-it/plans/.md` | `task-card-template.md` | -| `do-it-review-loop` | `.do-it/review/.md` | `workflow/review-protocol.md`, `invariants.md` | -| `do-it-subagent-orchestration` | the dispatch contract | `workflow/subagent-dispatch.md` | +| `do-it-review-loop` | `.do-it/review/.md` | `invariants.md` | | code-mapper agent | summary returned to parent | writes `code-map.md` "Current implementation locations" section | +`do-it-planning` owns the task-card layout itself, `do-it-review-loop` owns the +review protocol, and `do-it-subagent-orchestration` owns the dispatch contract — +none of them read a handbook copy. The handbook only feeds them project-specific +truth (`invariants.md`, `glossary.md`, `architecture.md`). + The handbook is read-mostly. The only file that gets written by an agent on a regular basis is `code-map.md`, and only by `code-mapper` per the contract in its agent definition. ## Term Promotion Rule (`.do-it/CONTEXT.md` ↔ `glossary.md`) @@ -84,12 +89,39 @@ To prevent drift between the active sediment and the stable glossary: This rule is enforced by the agent during `do-it-context` writes, not by tooling. Stating it once here keeps both files honest. +## Maintenance + +When and how to update each handbook file. The per-session sediment +(`.do-it/CONTEXT.md`) and per-task artifacts (`.do-it/grill/`, `.do-it/plans/`, +`.do-it/review/`) live outside the handbook; the project root `README.md` / +`CLAUDE.md` are entry points that delegate detail here. + +Update triggers: + +- **Implementation moved** → update `code-map.md` "Current implementation + locations" (normally the `code-mapper` agent) and `runtime-status.md` if + wiring, readiness, or known gaps changed. +- **Cross-cutting issue opened/closed** → `backlog.md` with a close condition; + per-task acceptance belongs in the plan card, not here. +- **Contract changed** → schema snippets in `architecture.md`, enum values in + `glossary.md`, and the affected plan cards; then search the codebase for + callers. +- **Invariant changed** → open a task card citing the invariant number; after + landing, sweep for contradictions and file backlog issues for any you cannot + fix in the same change. +- **Term stabilized** → promote `.do-it/CONTEXT.md` → `glossary.md` per the + three-session rule above. + +Keep any single handbook file under ~30 KB (it is read on routine agent work; +context budget is the constraint, not disk). After doc edits, sweep for changed +symbols and readiness labels, e.g. `rg -n "" docs .do-it/handbook`. + ## Output The bootstrap command should produce a short, deterministic report: ``` -[do-it-handbook] writing 12 file(s) to .do-it/handbook/ +[do-it-handbook] writing 7 file(s) to .do-it/handbook/ + .do-it/handbook/README.md + .do-it/handbook/invariants.md + .do-it/handbook/architecture.md @@ -97,11 +129,6 @@ The bootstrap command should produce a short, deterministic report: + .do-it/handbook/glossary.md + .do-it/handbook/backlog.md + .do-it/handbook/runtime-status.md - + .do-it/handbook/maintenance.md - + .do-it/handbook/task-card-template.md - + .do-it/handbook/workflow/agent-workflow.md - + .do-it/handbook/workflow/review-protocol.md - + .do-it/handbook/workflow/subagent-dispatch.md next: fill in invariants.md and glossary.md before running grill on any non-trivial task. ``` @@ -110,7 +137,7 @@ Idempotent re-runs print only the files actually written; an empty list means th ## Common Mistakes -- Treating the bootstrap as a one-time action and never refreshing the templates against do-it upstream. When `do-it` ships a new template (e.g. a new workflow file), the bootstrap should be re-runnable to add it. +- Treating the bootstrap as a one-time action and never refreshing the templates against do-it upstream. When `do-it` ships a new template (e.g. a new truth file), the bootstrap should be re-runnable to add it. - Copying the templates and then immediately auto-filling them from the codebase. The placeholders are intentional — they prompt the human owner to make the call. - Letting `code-map.md` drift. The `code-mapper` agent owns its update; if your project is using do-it without code-mapper running periodically, the handbook copy will rot. - Promoting every term from `.do-it/CONTEXT.md` to `glossary.md` as soon as it appears. The three-session rule exists because most session terms do not survive review. @@ -119,6 +146,5 @@ Idempotent re-runs print only the files actually written; an empty list means th - `do-it-context` — owns active sediment; promotes terms to `glossary.md`. - `do-it-architecture-scan` — reads `architecture.md` and `invariants.md`. -- `do-it-planning` — reads `task-card-template.md` shape. -- `do-it-review-loop` — reads `workflow/review-protocol.md`. -- `do-it-subagent-orchestration` — `workflow/subagent-dispatch.md` is the narrative form of its dispatch contract. +- `do-it-grill` — reads `invariants.md` and `glossary.md` for term anchoring. +- `do-it-planning` / `do-it-review-loop` / `do-it-subagent-orchestration` — own their task-card layout / review protocol / dispatch contract directly; the handbook no longer carries a copy. diff --git a/skills/do-it/do-it-handbook/templates/README.md b/skills/do-it/do-it-handbook/templates/README.md index 234fcbd..796dc64 100644 --- a/skills/do-it/do-it-handbook/templates/README.md +++ b/skills/do-it/do-it-handbook/templates/README.md @@ -1,7 +1,7 @@ # Project Handbook The handbook is the agent-readable, low-token navigation hub for this -project. It captures the rules, terms, ownership, and review discipline +project. It captures the rules, terms, ownership, and architecture that hold across sessions. Per-task artifacts live elsewhere (`.do-it/grill/`, `.do-it/plans/`, `.do-it/brainstorm/`, `.do-it/CONTEXT.md`). @@ -10,16 +10,12 @@ that hold across sessions. Per-task artifacts live elsewhere - `invariants.md` — rules that always win. - `architecture.md` — stable system shape. -- `workflow/agent-workflow.md` — execution flow for non-trivial work. -- `workflow/review-protocol.md` — review mode and evidence rules. - `code-map.md` — current implementation locations (maintained by the `code-mapper` agent). - `runtime-status.md` — current implementation status and known gaps. - `backlog.md` — cross-cutting unresolved issues with explicit close conditions. - `glossary.md` — long-stable vocabulary. -- `task-card-template.md` — template for non-trivial work briefs. -- `maintenance.md` — when and how to update each handbook file. ## Source-Of-Truth Map @@ -31,15 +27,16 @@ that hold across sessions. Per-task artifacts live elsewhere | Implementation status / wiring gaps | `runtime-status.md` | | Cross-cutting issues | `backlog.md` | | Vocabulary | `glossary.md` | -| Per-task brief template | `task-card-template.md` | -| Execution flow | `workflow/agent-workflow.md` | -| Review discipline | `workflow/review-protocol.md` | -| Subagent dispatch | `workflow/subagent-dispatch.md` | -| Doc maintenance rules | `maintenance.md` | + +Process docs are owned by skills, not this handbook: task-card layout → +`do-it-planning`, review protocol → `do-it-review-loop`, subagent dispatch → +`do-it-subagent-orchestration`, execution pipeline → `do-it-router`. The +handbook update rules live in the `do-it-handbook` SKILL `## Maintenance` +section. ## How To Update -See `maintenance.md` for which file to update when, and which targeted -sweeps to run after edits. Do not let `code-map.md` and -`runtime-status.md` drift from the codebase — they are read every -session and bad data here costs more than missing data. +See the `do-it-handbook` SKILL `## Maintenance` section for which file to +update when, and which targeted sweeps to run after edits. Do not let +`code-map.md` and `runtime-status.md` drift from the codebase — they are read +every session and bad data here costs more than missing data. diff --git a/skills/do-it/do-it-handbook/templates/code-map.md b/skills/do-it/do-it-handbook/templates/code-map.md index 13a5ecb..3633562 100644 --- a/skills/do-it/do-it-handbook/templates/code-map.md +++ b/skills/do-it/do-it-handbook/templates/code-map.md @@ -43,7 +43,7 @@ sections may be hand-maintained. - Tests: __ — run with ``. - Type definitions: __ — convention ``. - Configuration: __ — __. -- Docs: __ — `maintenance.md` governs updates. +- Docs: __ — the `do-it-handbook` SKILL `## Maintenance` section governs updates. ## Conventions diff --git a/skills/do-it/do-it-handbook/templates/glossary.md b/skills/do-it/do-it-handbook/templates/glossary.md index 4786240..6300480 100644 --- a/skills/do-it/do-it-handbook/templates/glossary.md +++ b/skills/do-it/do-it-handbook/templates/glossary.md @@ -36,11 +36,10 @@ Avoid: ## Process Vocabulary **Light / Standard / Heavy** — Tier classification used by -`do-it-router` to size the workflow for a task. See -`workflow/agent-workflow.md`. +`do-it-router` to size the workflow for a task. See `do-it-router`. **Blocking / Important / Opportunity** — Severity used in review -findings. See `workflow/review-protocol.md`. +findings. See `do-it-review-loop`. **Grill / Brainstorm** — Convergent (`do-it-grill`) and divergent (`do-it-brainstorm`) reasoning passes that run before planning. diff --git a/skills/do-it/do-it-handbook/templates/invariants.md b/skills/do-it/do-it-handbook/templates/invariants.md index 50faf4b..a450e7a 100644 --- a/skills/do-it/do-it-handbook/templates/invariants.md +++ b/skills/do-it/do-it-handbook/templates/invariants.md @@ -30,8 +30,8 @@ A change to this file is a project-shape decision, not a routine edit. ## Review -9. A worker `DONE` claim is not an acceptance signal; the review - protocol in `workflow/review-protocol.md` decides acceptance. +9. A worker `DONE` claim is not an acceptance signal; `do-it-review-loop` + decides acceptance. 10. Closeout requires fresh verification evidence on the integrated branch; evidence from an isolated worktree alone is not enough. diff --git a/skills/do-it/do-it-handbook/templates/maintenance.md b/skills/do-it/do-it-handbook/templates/maintenance.md deleted file mode 100644 index 216b9b1..0000000 --- a/skills/do-it/do-it-handbook/templates/maintenance.md +++ /dev/null @@ -1,76 +0,0 @@ -# Documentation Maintenance - -When and how to update each handbook file. - -## Directory Roles - -- `.do-it/handbook/` — maintained handbook (this directory). -- `.do-it/CONTEXT.md` — per-session active sediment; owned by - `do-it-context`. -- `.do-it/grill/.md` — per-task grill log. -- `.do-it/plans/.md` — per-task plan card. -- `.do-it/brainstorm/.md` — per-task multi-persona brainstorm. -- `.do-it/review/.md` — per-task review-loop findings (when - used). -- Project root `README.md`, `CLAUDE.md` (or equivalent) — entry - points; delegate detail to the handbook. - -## Update Rules - -When implementation changes: - -- Update `code-map.md` "Current implementation locations" if files, - packages, routes, repos, migrations, or service ownership changed. - This is normally written by the `code-mapper` agent. -- Update `runtime-status.md` if wiring, readiness, or known gaps - changed. -- Update `backlog.md` only for unresolved cross-cutting issues with a - close condition. Per-task acceptance criteria belong in the task - card. - -When dependencies or readiness gates change: - -- Update `Prerequisite`, `Blocks`, `Depends` in the affected task - cards. -- Update `runtime-status.md` status labels. - -When contracts change: - -- Update schema snippets (architecture or interface docs). -- Update enum values in `glossary.md` if any. -- Update acceptance criteria and test expectations in the affected - task cards. -- Update downstream consumer assumptions and search the codebase for - callers. - -When a term stabilizes: - -- Promote it from `.do-it/CONTEXT.md` to `glossary.md` after the - three-session rule (see `do-it-handbook` SKILL). - -When an invariant changes: - -- Open a task card. Cite the invariant number. -- After landing, sweep the codebase for contradictions. File backlog - issues for any you cannot fix in the same change. - -## Large File Rule - -Do not create new handbook files larger than ~30 KB if they are read -on routine agent work. Split lookup-heavy content into smaller pages. -The agent's context budget is the constraint, not disk. - -## Drift Sweep - -After doc edits, run targeted sweeps for changed symbols, events, -dependencies, and readiness labels. Project-specific examples: - -```bash -rg -n "" docs .do-it/handbook -rg -n "schema-ready|implementation-ready|live-event-ready" \ - docs .do-it/handbook -find .do-it/handbook docs -type f -name '*.md' -size +30k -print -``` - -If a sweep surfaces a contradiction, fix it in the same change or -open a backlog issue with a close condition. diff --git a/skills/do-it/do-it-handbook/templates/task-card-template.md b/skills/do-it/do-it-handbook/templates/task-card-template.md deleted file mode 100644 index a1f8c13..0000000 --- a/skills/do-it/do-it-handbook/templates/task-card-template.md +++ /dev/null @@ -1,130 +0,0 @@ -# Task Card Template - -A lightweight template for non-trivial work that benefits from a -written brief — typically multi-file changes, multi-day efforts, -sub-agent dispatches, or anything that needs review-loop discipline. - -For one-shot fixes, just describe scope in the PR body and skip this. - -## File Layout - -- File path: `.do-it/plans/.md` for in-flight task cards; - graduated cards may move into a project-specific directory once - their wave settles. -- File MUST be UTF-8 without BOM, < 30 KB. Localized fixtures inside - the card are fine. - -## Section Order - -``` -# Implementation Brief: — - -> Frontmatter (block-quoted bullet list, fields below) - -## 1. Background & Goal -## 2. Allowed Scope -## 3. Deferred -## 4. Acceptance Criteria -## 5. Verification -## 6. Shared File Hazards & Dependencies -``` - -## Frontmatter Fields - -```markdown -> - **Card ID**: <short kebab-case id> -> - **Source/Background**: <link or one-liner> -> - **Target**: `<destination paths inside the repo>` -> - **Size**: <S | M | L | XL> (S ≤ 5 files, M ≤ 20, L ≤ 100, XL > 100) -> - **Tier**: <Light | Standard | Heavy> (matches do-it-router) -> - **Prerequisite**: <comma-separated card IDs, or `none`> -> - **Blocks**: <comma-separated card IDs, or `none`> -> - **Owner**: <`unassigned` until claimed> -> - **Grill**: <slug from .do-it/grill/, or `none`> -> - **Brainstorm**: <slug from .do-it/brainstorm/, or `none`> -``` - -## §1 Background & Goal - -Two short paragraphs: - -1. **Background**: why this work matters; what subsystem it touches; - what depends on it. -2. **Goal**: a single sentence stating the one outcome this card - delivers. One card = one goal. - -## §2 Allowed Scope - -The exhaustive enumeration of files the card touches. Use -sub-sections per file or per file group. For each file include: - -- **Target**: repo-relative path -- **Change**: brief description of what changes and why - -## §3 Deferred - -Anything intentionally NOT in this card. Each deferral MUST cite a -backlog issue: - -```markdown -- <thing> — deferred to backlog #BL-NNN with close condition - "<one-liner>". -``` - -If nothing is deferred, write `Nothing deferred.` exactly. - -## §4 Acceptance Criteria - -A markdown table. Each row has a stable AC ID (AC1, AC2, ...) and an -Evidence column that names a verifiable artifact. - -```markdown -| AC | Criteria | Evidence | -|---|---|---| -| AC1 | … | … | -| AC2 | TypeScript compiles | `pnpm exec tsc --noEmit` is clean | -| AC3 | Unit tests pass | `pnpm exec vitest run` is green | -``` - -## §5 Verification - -Concrete shell commands a reviewer can run to verify §4. Order them -build → test → lint → integration. - -For Heavy, release/install, multi-agent, or explicit durable-plan work, include -an Evidence Ledger table. Ordinary Light work and one-shot Standard fixes can -skip it. - -```markdown -| Claim ID | Readiness target | Truth plane | Ref/path | Evidence | Result | Date | Owner | Residual risk | -|---|---|---|---|---|---|---|---|---| -| C1 | fixture-ready | source-repo | `src/...` | `npm test` | NOT_VERIFIED | YYYY-MM-DD | parent | command not run yet | -``` - -Allowed `Result` values: `VERIFIED`, `FAILED`, `NOT_VERIFIED`, `BLOCKED`, and -`DEFERRED_BY_USER`. - -Allowed truth planes: `source-repo`, `task-worktree`, `integration-worktree`, -`temp-install`, `live-codex`, `live-claude`, `package-artifact`, -`host-behavior`, and `external-blocked`. - -Old projects do not need historical backfill. Record a `NOT_VERIFIED` baseline -only when old state affects the current task. - -## §6 Shared File Hazards & Dependencies - -A short list of shared files this card writes that may collide with -other cards in the same wave. If none, write `No shared-file -hazards.` exactly. - -Plus a short dependency restatement (mirrors frontmatter): - -```markdown -**Prerequisite**: <card IDs>. -**Blocks**: <card IDs>. -``` - -## Path Style - -All paths are repository-relative -(e.g. `packages/core/src/foo.ts`), never absolute. diff --git a/skills/do-it/do-it-handbook/templates/workflow/agent-workflow.md b/skills/do-it/do-it-handbook/templates/workflow/agent-workflow.md deleted file mode 100644 index 53fd09f..0000000 --- a/skills/do-it/do-it-handbook/templates/workflow/agent-workflow.md +++ /dev/null @@ -1,82 +0,0 @@ -# Agent Workflow - -Execution flow for non-trivial work. Light-tier mechanical edits skip -most of this; Standard and Heavy tiers follow it. - -## Per-Card Pipeline - -1. Read the relevant task card (under `.do-it/plans/`) or PR brief. - If the work area only has a README and no card, read the README - and split a task card or get explicit user scope before - implementing code. -2. Read `invariants.md`. -3. Read the affected handbook pages (`architecture.md`, - `code-map.md`, the relevant glossary entries). -4. Freeze scope from the card's §2-§5. -5. For multi-package or live-path work, map the producer / consumer - path before dispatching a worker. -6. Write or update tests first when practical - (see `do-it-tdd`). -7. Implement the smallest change that satisfies the card. -8. Verify using the card's §5 commands. -9. Run `do-it-review-loop` against the diff before marking - the card done. -10. Run a targeted doc/code consistency sweep for changed contracts. - -## Per-Wave Pipeline - -A "wave" is a set of cards that share a goal and may need to land -together. - -1. Confirm every card has a clear `Prerequisite`, `Blocks`, and - readiness target. -2. Execute independent cards in parallel only when their **write - sets do not overlap**. Cards that touch shared barrel files - (e.g. package index files) MUST serialize through a barrel-update - card. -3. Stop dependent workers when the prerequisite card is still under - review or when shared-contract work is not yet green. -4. Review each card against `invariants.md` and its acceptance - criteria. -5. Re-review every fix loop before merge; worker `DONE` is not an - acceptance signal. -6. Update `runtime-status.md` after each completed card. - -## Phase / Worktree Pipeline - -When the work spans multiple waves or touches risky shared files: - -1. Create an isolated worktree (`do-it-worktree-isolation`). -2. Verify the intended base branch and record its current status. -3. Dispatch card or wave workers from the phase controller only - after the controller freezes scope, dependencies, shared-file - ownership, and merge order. -4. Keep phase work out of the main checkout until build, tests, and - review/fix-loop closure on the phase branch are complete. -5. Merge back to main only after the final reviewer pass reports - zero unresolved Blocking or Important findings on the integrated - branch. -6. After merging, rerun gate verification on `main`. Evidence from - the worktree alone is not enough for closeout. - -## Anti-Tail Discipline - -- **One card, one goal.** If you discover the card needs two goals, - split it before continuing. -- **No silent scope expansion.** A new file outside §2 means open a - backlog issue or update §2 explicitly. -- **No mocking the database in integration tests** unless the card - says so. Mock/prod divergence is a recurring incident class. -- **No commit during a fix loop without re-running review** — partial - fixes ship under the cover of "addressed". - -## Light-Tier Shortcut - -For Light-tier work (mechanical refactors, one-symbol renames, -dependency bumps): - -1. Skip the per-card pipeline; describe scope inline in the PR. -2. Verify with the smallest test command that touches the changed - surface. -3. No handbook updates required unless `code-map.md` would otherwise - become wrong. diff --git a/skills/do-it/do-it-handbook/templates/workflow/review-protocol.md b/skills/do-it/do-it-handbook/templates/workflow/review-protocol.md deleted file mode 100644 index ef2c5db..0000000 --- a/skills/do-it/do-it-handbook/templates/workflow/review-protocol.md +++ /dev/null @@ -1,80 +0,0 @@ -# Review Protocol - -Review mode, severity, and evidence expectations. -`do-it-review-loop` is the agent-side counterpart of this document. - -## Review Modes - -- **Self-review** — the implementer re-reads the diff against the - task card §4 acceptance criteria before requesting review. -- **PR-style review** — `reviewer` agent (or a peer) checks the diff - against acceptance criteria, invariants, and contract surface. -- **Multi-perspective review** — additional read-only review agents - (`architect-reviewer`, `red-team-reviewer`, `domain-language-reviewer`, - etc.) run when their lens is needed. - -The default for a Standard-tier task is self-review. Add PR-style review when -the task has a named non-local risk, an interface/module boundary, or an -explicit review/subagent request. Heavy tier adds multi-perspective review. - -## Severity - -- **Blocking** — must resolve before merge. Correctness, contract, - invariants, or unsafe state. -- **Important** — should resolve now. Avoidable rework, review - failure, unclear ownership, or significant maintenance debt. -- **Opportunity** — useful improvement; not a blocker. - -A finding carries exactly one severity. Re-classifying a Blocking -finding as Important is a discussion, not a unilateral move. - -## Evidence Requirements - -Every finding must cite evidence. Acceptable forms: - -- `path:line` reference. -- A grep / rg snippet showing the contradicted assumption. -- A failing test command and its output. -- A schema or contract diff. - -Unacceptable evidence: - -- "It feels wrong." -- "I think this could be a problem." -- "In my experience, ...". - -If a reviewer cannot cite evidence, the finding is downgraded to a -question for the implementer, not a Blocking item. - -## Fix Loop - -1. Address each Blocking and Important finding atomically. -2. After fixes, **re-run review on the same scope**. Spot-fixes - without a re-review let partial fixes ship. -3. Repeat until Blocking and Important are empty. -4. Opportunity findings may merge with the change or get filed as - backlog issues; do not block on them. - -## Closeout - -A card is done when: - -- All §4 acceptance criteria pass with the §5 verification commands. -- All Blocking and Important review findings are resolved. -- Fresh verification evidence is recorded on the integrated branch - (not just the worktree). -- `runtime-status.md` and `code-map.md` are updated if implementation - shape changed. -- The closeout states which brainstorm, grill, subagent, review, and - verification steps were used or skipped, with the reason when the route made - them relevant. - -## Anti-Patterns - -- "DONE" claims without verification output. `do-it-verification-gate` - catches this; do not weaken the gate. -- Reviewers asking the implementer to fix Blocking findings while - approving the PR. Approval after Blocking findings is a process - failure. -- Reviewers re-litigating architecture invariants in PR comments. - Invariant changes go through a task card, not a review thread. diff --git a/skills/do-it/do-it-handbook/templates/workflow/subagent-dispatch.md b/skills/do-it/do-it-handbook/templates/workflow/subagent-dispatch.md deleted file mode 100644 index 7b171b3..0000000 --- a/skills/do-it/do-it-handbook/templates/workflow/subagent-dispatch.md +++ /dev/null @@ -1,116 +0,0 @@ -# Subagent Dispatch - -Narrative form of the `do-it-subagent-orchestration` contract. Read -this before delegating to a subagent for the first time on a project; -read the contract for the exact required fields. - -## When To Delegate - -Delegate when the parent has bounded the slice well enough that -another agent can do the work in isolation, and the parent's context -budget is better spent on integration and verification than on the -slice itself. - -Do **not** delegate when: - -- the parent has not yet verified enough current truth to bound the - slice; -- the work touches the parent's shared files (final integration, branch - closeout, manifest edits); -- two parallel workers would write the same file or hidden shared - state; -- the parent is uncertain about acceptance criteria. - -A delegated worker is evidence to inspect, not a rubber stamp. - -## Required Prompt Fields - -Every subagent prompt must specify: - -- **tier**: Light, Standard, or explicit Heavy. -- **scope**: exact task and non-goals. -- **write ownership**: allowed directories/files, or `read-only`. -- **forbidden paths**: files, directories, generated outputs, or - user-owned edits to avoid. -- **current truth**: facts the parent verified and the child may rely - on. -- **failure-mode forecast**: expected failure classes the child must - cover or refute. -- **path map**: producer → contract/event/schema → transport/client → - state/query → surface/operator action → verification, or - `not applicable`. -- **readiness target**: the readiness label expected after the slice. -- **truth plane**: `source-repo`, `task-worktree`, `integration-worktree`, - `temp-install`, `live-codex`, `live-claude`, `package-artifact`, - `host-behavior`, or `external-blocked`. -- **lane status**: starts as `assigned`; the parent updates it through - `running`, `done_with_evidence`, `integrated`, or `blocking`. -- **must-verify facts**: facts the child must check itself before - acting or reporting. -- **stop condition**: when to return `NEEDS_CONTEXT`, `BLOCKED`, or - `STILL_OPEN`. -- **integrity stance**: failure is a clue to trace, not to hide; do not - swallow errors, weaken checks, skip tests, or claim unverified work is done. -- **output_budget**: token cap selected from `do-it-subagent-orchestration`. -- **return schema**: the exact shape the parent needs. - -Include this guardrail unless Heavy is explicitly assigned: - -> You are a Standard-tier subagent. Do not expand into parent-level -> Heavy flow, broad planning, branch closeout, manifest/docs edits, or -> unrelated cleanup. - -## Standard Return Schemas - -Implementation/debugging workers return: - -- `status`: `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or - `BLOCKED`; -- lane status recommendation: `done_with_evidence` or `blocking`; -- tier used; -- files changed; -- commands run with results; -- facts verified; -- failure modes covered or still open; -- proof path evidence or why it was not applicable; -- assumptions; -- residual risk; -- requested parent action. - -Review/drill workers return: - -- `status`: `CLEAR`, `FINDINGS`, `STILL_OPEN`, `NEEDS_CONTEXT`, or - `BLOCKED`; -- scope reviewed; -- findings ordered by `Blocking`, `Important`, `Opportunity`; -- evidence per finding; -- cause class when known; -- commands or inspections run; -- facts verified; -- assumptions; -- residual risk; -- `NOT_CHECKED`: explicit scope or checks not performed. - -## Parent Duties - -- Inspect diffs and reports before accepting them. -- Resolve duplicate or conflicting findings. -- Re-run verification on the integrated branch — not the worker's - isolated working copy. -- Ensure subagents did not touch forbidden paths. -- Maintain lane state as `assigned`, `running`, `done_with_evidence`, - `integrated`, or `blocking`. -- Treat worker `DONE` as input to inspect; parent acceptance is `integrated`. -- Close or re-dispatch workers only after the stop condition is - satisfied. - -## Common Mistakes - -- Delegating before scope is bounded; the worker spends its budget - re-discovering the parent's question. -- Parallelizing workers that share a write target; one of them - silently overwrites the other. -- Treating a worker's `DONE` as acceptance. `DONE` is a status, not a - signoff. -- Letting a worker make manifest, docs, or release decisions outside - its slice. diff --git a/skills/do-it/do-it-planning/SKILL.md b/skills/do-it/do-it-planning/SKILL.md index eb9b367..ca04004 100644 --- a/skills/do-it/do-it-planning/SKILL.md +++ b/skills/do-it/do-it-planning/SKILL.md @@ -37,7 +37,7 @@ Parent-only unless explicitly assigned: - use for wave, phase, release, multi-agent, durable workflow, or cross-boundary planning; - lock scope, write ownership, non-goals, and integration ownership; -- run grill, interface, architecture, domain-language, or slicing drills as needed; +- run grill, interface, architecture, vocabulary (do-it-context), or slicing drills as needed; - stop for approval if the user asked to confirm the plan. ## Planning Sequence @@ -112,9 +112,28 @@ mkdir -p .do-it/runtime && printf '%s' "<slug>" > .do-it/runtime/pointer See `do-it-router` § Task Pointer for the full protocol. Inline plans that never produce a `<slug>.md` file do not need to write the pointer. -## Handbook Alignment +## Task Card Layout -When `.do-it/handbook/` exists, a durable `.do-it/plans/<slug>.md` card follows the section order in `.do-it/handbook/task-card-template.md` — frontmatter, then Background & Goal, Allowed Scope, Deferred, Acceptance Criteria, Verification, Shared File Hazards & Dependencies. The template owns the canonical layout; the lenses and required artifacts in this skill fill those sections. When the handbook is absent and the work spans many files or sessions, suggest `do-it-handbook` to scaffold it rather than inventing a one-off structure. +A durable `.do-it/plans/<slug>.md` card uses this canonical layout; the lenses +and required artifacts in this skill fill the sections. + +Frontmatter (block-quoted bullets): **Card ID**, **Source/Background**, +**Target** (repo-relative paths), **Size** (S ≤ 5 files, M ≤ 20, L ≤ 100, +XL > 100), **Tier** (Light/Standard/Heavy), **Prerequisite**, **Blocks**, +**Owner**, **Grill** (slug or `none`), **Brainstorm** (slug or `none`). + +Sections, in order: + +1. **Background & Goal** — why it matters, plus a one-sentence goal (one card = one goal). +2. **Allowed Scope** — exhaustive list of files the card touches, with the change per file. +3. **Deferred** — anything intentionally out of scope, each citing a backlog issue; write `Nothing deferred.` if none. +4. **Acceptance Criteria** — table of stable AC IDs (AC1, AC2, …) each with a verifiable Evidence column. +5. **Verification** — concrete shell commands ordered build → test → lint → integration; put the Evidence Ledger here for Heavy, release/install, multi-agent, or durable-plan work. +6. **Shared File Hazards & Dependencies** — shared files that may collide with other cards in the wave; write `No shared-file hazards.` if none. + +All paths are repository-relative. When the work spans many files or sessions +and no `.do-it/handbook/` exists yet, suggest `do-it-handbook` to scaffold the +project-truth files rather than inventing a one-off structure. ## Required Planning Artifacts @@ -203,6 +222,27 @@ Include: Keep file paths and code snippets out of durable PRD prose unless the user asks for a code-facing plan; they go stale faster than domain decisions. +## Visual Aids (optional) + +When seeing an option is materially clearer than reading it — UI layout +alternatives, architecture/data-flow diagrams, before/after states, side-by-side +interface shapes, or visual task sequencing for multi-agent work — produce the +smallest useful artifact under `.do-it/visual/<topic>/` (descriptive filenames +like `option-a-flow.md`, `api-boundary.svg`), compare 2-3 options with explicit +tradeoffs, and name a recommendation. Feed that decision back into this plan card +(or `do-it-interface-drill` / `do-it-architecture-scan` when it shapes a contract +or boundary). + +Treat visuals as auxiliary evidence, not durable plan output: the decision still +lands in the plan card. Skip them for text-only decisions, one-line questions, or +where a table is clearer. A visual aid never promotes a task's tier by itself. + +For browser-based side-by-side comparison, this skill ships an optional local +visual companion under `scripts/` (a small static server plus `plan-card` / +`review-report` render templates). Load `references/visual-companion.md` only +when you actually need the browser render; for everything else, file-based +sketches in `.do-it/visual/` are enough. + ## Output Shape - Tier and task class. diff --git a/skills/do-it/do-it-visual-planning/references/visual-companion.md b/skills/do-it/do-it-planning/references/visual-companion.md similarity index 100% rename from skills/do-it/do-it-visual-planning/references/visual-companion.md rename to skills/do-it/do-it-planning/references/visual-companion.md diff --git a/skills/do-it/do-it-planning/scripts/frame-template.html b/skills/do-it/do-it-planning/scripts/frame-template.html new file mode 100644 index 0000000..f0634c0 --- /dev/null +++ b/skills/do-it/do-it-planning/scripts/frame-template.html @@ -0,0 +1,855 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>do-it Visual Planning + + + + + + +
+

+ + + do-it + Visual Planning + +

+
Connected
+
+ +
+
+ +
+
+ +
+ Click an option above, then return to the terminal +
+ + + diff --git a/skills/do-it/do-it-visual-planning/scripts/helper.js b/skills/do-it/do-it-planning/scripts/helper.js similarity index 100% rename from skills/do-it/do-it-visual-planning/scripts/helper.js rename to skills/do-it/do-it-planning/scripts/helper.js diff --git a/skills/do-it/do-it-visual-planning/scripts/server.cjs b/skills/do-it/do-it-planning/scripts/server.cjs similarity index 100% rename from skills/do-it/do-it-visual-planning/scripts/server.cjs rename to skills/do-it/do-it-planning/scripts/server.cjs diff --git a/skills/do-it/do-it-visual-planning/scripts/start-server.sh b/skills/do-it/do-it-planning/scripts/start-server.sh similarity index 100% rename from skills/do-it/do-it-visual-planning/scripts/start-server.sh rename to skills/do-it/do-it-planning/scripts/start-server.sh diff --git a/skills/do-it/do-it-visual-planning/scripts/stop-server.sh b/skills/do-it/do-it-planning/scripts/stop-server.sh similarity index 100% rename from skills/do-it/do-it-visual-planning/scripts/stop-server.sh rename to skills/do-it/do-it-planning/scripts/stop-server.sh diff --git a/plugins/do-it/skills/do-it-visual-planning/templates/plan-card.html b/skills/do-it/do-it-planning/templates/plan-card.html similarity index 92% rename from plugins/do-it/skills/do-it-visual-planning/templates/plan-card.html rename to skills/do-it/do-it-planning/templates/plan-card.html index facf904..3d3ef2d 100644 --- a/plugins/do-it/skills/do-it-visual-planning/templates/plan-card.html +++ b/skills/do-it/do-it-planning/templates/plan-card.html @@ -1,5 +1,5 @@
diff --git a/skills/do-it/do-it-visual-planning/templates/review-report.html b/skills/do-it/do-it-planning/templates/review-report.html similarity index 98% rename from skills/do-it/do-it-visual-planning/templates/review-report.html rename to skills/do-it/do-it-planning/templates/review-report.html index 367fb1c..e7c6eb6 100644 --- a/skills/do-it/do-it-visual-planning/templates/review-report.html +++ b/skills/do-it/do-it-planning/templates/review-report.html @@ -1,5 +1,5 @@ placeholder in #do-it-content. - * All class names below form the contract consumed by helper.js and - * server.cjs (.option/.card/.selected/#indicator-text/...) — keep them. - */ - - * { box-sizing: border-box; margin: 0; padding: 0; } - html, body { height: 100%; overflow: hidden; } - - /* ===== THEME VARIABLES — light (warm paper) ===== */ - :root { - --bg-primary: #f3f1ec; - --bg-secondary: #ffffff; - --bg-tertiary: #ece9e1; - --bg-code: #f6f4ee; - --border: #ddd8cb; - --border-strong: #c8c2b1; - --grid: rgba(46, 40, 22, 0.04); - --text-primary: #201e18; - --text-secondary: #6c6557; - --text-tertiary: #9b9484; - --accent: #2f5fe0; - --accent-hover: #1f48bf; - --accent-soft: rgba(47, 95, 224, 0.10); - --success: #2f9e44; - --warning: #bd820c; - --error: #d4443c; - --selected-bg: rgba(47, 95, 224, 0.08); - --selected-border: #2f5fe0; - --shadow-sm: 0 1px 2px rgba(28, 24, 14, 0.06); - --shadow-md: 0 1px 2px rgba(28, 24, 14, 0.05), 0 10px 26px -14px rgba(28, 24, 14, 0.28); - --font-display: 'Fraunces', 'Iowan Old Style', Georgia, 'Times New Roman', serif; - --font-body: 'IBM Plex Sans', ui-sans-serif, system-ui, -apple-system, sans-serif; - --font-mono: 'IBM Plex Mono', ui-monospace, SFMono-Regular, Menlo, monospace; - } - - @media (prefers-color-scheme: dark) { - :root { - --bg-primary: #15161c; - --bg-secondary: #1d1f28; - --bg-tertiary: #282b38; - --bg-code: #11121a; - --border: #313440; - --border-strong: #444855; - --grid: rgba(255, 255, 255, 0.022); - --text-primary: #e9e9ee; - --text-secondary: #a1a1af; - --text-tertiary: #6b6c7b; - --accent: #7c9bff; - --accent-hover: #98b0ff; - --accent-soft: rgba(124, 155, 255, 0.14); - --success: #4cc46a; - --warning: #e0a93a; - --error: #f0635a; - --selected-bg: rgba(124, 155, 255, 0.12); - --selected-border: #7c9bff; - --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.35); - --shadow-md: 0 1px 2px rgba(0, 0, 0, 0.4), 0 14px 32px -16px rgba(0, 0, 0, 0.7); - } - } - - body { - font-family: var(--font-body); - background: var(--bg-primary); - color: var(--text-primary); - display: flex; - flex-direction: column; - line-height: 1.6; - font-weight: 400; - -webkit-font-smoothing: antialiased; - text-rendering: optimizeLegibility; - } - - ::selection { background: var(--accent-soft); } - - /* ===== FRAME: HEADER ===== */ - .header { - position: relative; - flex-shrink: 0; - height: 3.1rem; - padding: 0 1.4rem; - display: flex; - align-items: center; - justify-content: space-between; - background: var(--bg-secondary); - border-bottom: 1px solid var(--border); - } - .header::after { - content: ''; - position: absolute; - left: 0; right: 0; bottom: -1px; - height: 2px; - background: linear-gradient(90deg, var(--accent), transparent 38%); - opacity: 0.85; - } - .header h1 { font-size: 1rem; font-weight: 400; } - .header h1 a { - display: flex; - align-items: center; - gap: 0.6rem; - color: inherit; - text-decoration: none; - } - .brand-mark { - width: 1.4rem; height: 1.4rem; - border-radius: 6px; - background: linear-gradient(140deg, var(--accent), var(--accent-hover)); - box-shadow: var(--shadow-sm), inset 0 1px 0 rgba(255, 255, 255, 0.22); - position: relative; - flex-shrink: 0; - } - .brand-mark::before { - content: ''; - position: absolute; - inset: 0; - margin: auto; - width: 0.42rem; height: 0.42rem; - border-radius: 2px; - background: var(--bg-secondary); - } - .brand-name { - font-family: var(--font-mono); - font-weight: 600; - font-size: 0.92rem; - letter-spacing: 0.01em; - color: var(--text-primary); - } - .brand-sub { - font-family: var(--font-mono); - font-size: 0.68rem; - text-transform: uppercase; - letter-spacing: 0.16em; - color: var(--text-tertiary); - padding-left: 0.6rem; - border-left: 1px solid var(--border); - } - .header .status { - font-family: var(--font-mono); - font-size: 0.66rem; - text-transform: uppercase; - letter-spacing: 0.13em; - color: var(--text-secondary); - display: flex; - align-items: center; - gap: 0.45rem; - } - .header .status::before { - content: ''; - width: 6px; height: 6px; - border-radius: 50%; - background: var(--success); - box-shadow: 0 0 0 0 var(--success); - animation: pulse 2.6s ease-out infinite; - } - @keyframes pulse { - 0% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--success) 55%, transparent); } - 70%, 100% { box-shadow: 0 0 0 7px transparent; } - } - - /* ===== FRAME: MAIN ===== */ - .main { - flex: 1; - overflow-y: auto; - background-color: var(--bg-primary); - background-image: - linear-gradient(var(--grid) 1px, transparent 1px), - linear-gradient(90deg, var(--grid) 1px, transparent 1px); - background-size: 30px 30px; - background-position: center top; - } - .main::-webkit-scrollbar { width: 11px; } - .main::-webkit-scrollbar-thumb { - background: var(--border-strong); - border: 3px solid var(--bg-primary); - border-radius: 999px; - } - .main::-webkit-scrollbar-track { background: transparent; } - - #do-it-content { - max-width: 50rem; - margin: 0 auto; - padding: 2.75rem 2.25rem 4.5rem; - min-height: 100%; - } - - /* ===== FRAME: INDICATOR BAR ===== */ - .indicator-bar { - flex-shrink: 0; - background: var(--bg-secondary); - border-top: 1px solid var(--border); - padding: 0.6rem 1.4rem; - text-align: center; - } - .indicator-bar span { - font-family: var(--font-mono); - font-size: 0.7rem; - letter-spacing: 0.04em; - color: var(--text-tertiary); - } - .indicator-bar .selected-text { - color: var(--accent); - font-weight: 600; - } - - /* ===== TYPOGRAPHY ===== */ - h2 { - font-family: var(--font-display); - font-optical-sizing: auto; - font-size: 2.05rem; - font-weight: 600; - line-height: 1.12; - letter-spacing: -0.014em; - margin-bottom: 0.55rem; - } - h3 { - font-family: var(--font-body); - font-size: 1.05rem; - font-weight: 600; - letter-spacing: -0.005em; - margin-bottom: 0.25rem; - } - h4 { font-family: var(--font-body); } - p { color: var(--text-primary); } - a { color: var(--accent); } - - .subtitle { - color: var(--text-secondary); - font-size: 1.02rem; - line-height: 1.55; - margin-bottom: 1.5rem; - } - - /* Section eyebrow label — monospace with an accent tick. */ - .label { - display: flex; - align-items: center; - gap: 0.55rem; - font-family: var(--font-mono); - font-size: 0.68rem; - font-weight: 600; - text-transform: uppercase; - letter-spacing: 0.15em; - color: var(--text-secondary); - margin-bottom: 0.7rem; - } - .label::before { - content: ''; - width: 1.1rem; height: 2px; - background: var(--accent); - border-radius: 2px; - flex-shrink: 0; - } - - /* Sections: staggered rise-in on load. */ - .section { margin-bottom: 2rem; } - .section > p { color: var(--text-secondary); } - .section ul { margin-left: 1.15rem; } - .section li { margin-bottom: 0.35rem; color: var(--text-secondary); } - #do-it-content > .section { - animation: rise 0.5s cubic-bezier(0.22, 0.7, 0.2, 1) both; - } - #do-it-content > .section:nth-child(1) { animation-delay: 0.02s; } - #do-it-content > .section:nth-child(2) { animation-delay: 0.08s; } - #do-it-content > .section:nth-child(3) { animation-delay: 0.14s; } - #do-it-content > .section:nth-child(4) { animation-delay: 0.20s; } - #do-it-content > .section:nth-child(5) { animation-delay: 0.26s; } - #do-it-content > .section:nth-child(6) { animation-delay: 0.32s; } - #do-it-content > .section:nth-child(n+7) { animation-delay: 0.38s; } - @keyframes rise { - from { opacity: 0; transform: translateY(10px); } - to { opacity: 1; transform: translateY(0); } - } - - code, .mono { font-family: var(--font-mono); font-size: 0.86em; } - .section :not(pre) > code { - background: var(--bg-code); - border: 1px solid var(--border); - border-radius: 4px; - padding: 0.05rem 0.32rem; - color: var(--text-primary); - } - - /* ===== META ROW — monospace key/value chips ===== */ - .meta-row { - display: flex; - flex-wrap: wrap; - gap: 0.5rem; - margin-bottom: 1.6rem; - } - .meta-row span { - font-family: var(--font-mono); - font-size: 0.72rem; - color: var(--text-secondary); - background: var(--bg-secondary); - border: 1px solid var(--border); - border-radius: 999px; - padding: 0.26rem 0.72rem; - box-shadow: var(--shadow-sm); - } - .meta-row b { color: var(--text-primary); font-weight: 600; } - - /* ===== OPTIONS (A/B/C choices) ===== */ - .options { display: flex; flex-direction: column; gap: 0.7rem; } - .option { - background: var(--bg-secondary); - border: 1px solid var(--border); - border-radius: 13px; - padding: 1rem 1.2rem; - cursor: pointer; - transition: border-color 0.16s ease, transform 0.16s ease, box-shadow 0.16s ease; - display: flex; - align-items: flex-start; - gap: 1rem; - box-shadow: var(--shadow-sm); - } - .option:hover { border-color: var(--accent); transform: translateY(-1px); box-shadow: var(--shadow-md); } - .option.selected { background: var(--selected-bg); border-color: var(--selected-border); box-shadow: var(--shadow-md); } - .option .letter { - font-family: var(--font-mono); - background: var(--bg-tertiary); - color: var(--text-secondary); - width: 1.8rem; height: 1.8rem; - border-radius: 7px; - display: flex; align-items: center; justify-content: center; - font-weight: 600; font-size: 0.82rem; flex-shrink: 0; - transition: background 0.16s ease, color 0.16s ease; - } - .option.selected .letter { background: var(--accent); color: #fff; } - .option .content { flex: 1; } - .option .content h3 { font-size: 0.95rem; margin-bottom: 0.15rem; } - .option .content p { color: var(--text-secondary); font-size: 0.86rem; margin: 0; } - - /* ===== CARDS (designs / mockups) ===== */ - .cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(270px, 1fr)); gap: 1rem; } - .card { - background: var(--bg-secondary); - border: 1px solid var(--border); - border-radius: 13px; - overflow: hidden; - cursor: pointer; - box-shadow: var(--shadow-sm); - transition: border-color 0.16s ease, transform 0.16s ease, box-shadow 0.16s ease; - } - .card:hover { border-color: var(--accent); transform: translateY(-3px); box-shadow: var(--shadow-md); } - .card.selected { border-color: var(--selected-border); box-shadow: var(--shadow-md); } - .card-image { background: var(--bg-tertiary); aspect-ratio: 16/10; display: flex; align-items: center; justify-content: center; } - .card-body { padding: 1rem 1.1rem; } - .card-body h3 { margin-bottom: 0.25rem; } - .card-body p { color: var(--text-secondary); font-size: 0.86rem; } - - /* ===== MOCKUP CONTAINER ===== */ - .mockup { - background: var(--bg-secondary); - border: 1px solid var(--border); - border-radius: 13px; - overflow: hidden; - margin-bottom: 1.5rem; - box-shadow: var(--shadow-sm); - } - .mockup-header { - background: var(--bg-tertiary); - padding: 0.5rem 1rem; - font-family: var(--font-mono); - font-size: 0.72rem; - letter-spacing: 0.04em; - color: var(--text-secondary); - border-bottom: 1px solid var(--border); - } - .mockup-body { padding: 1.5rem; } - - /* ===== SPLIT VIEW ===== */ - .split { display: grid; grid-template-columns: 1fr 1fr; gap: 1.4rem; } - @media (max-width: 700px) { .split { grid-template-columns: 1fr; } } - - /* ===== PROS / CONS ===== */ - .pros-cons { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: 1rem 0; } - .pros, .cons { - background: var(--bg-secondary); - border: 1px solid var(--border); - border-radius: 11px; - padding: 1rem 1.1rem; - } - .pros h4, .cons h4 { - font-family: var(--font-mono); - font-size: 0.7rem; - text-transform: uppercase; - letter-spacing: 0.1em; - margin-bottom: 0.55rem; - } - .pros h4 { color: var(--success); } - .cons h4 { color: var(--error); } - .pros ul, .cons ul { margin-left: 1.15rem; font-size: 0.86rem; color: var(--text-secondary); } - .pros li, .cons li { margin-bottom: 0.28rem; } - - /* ===== PLACEHOLDER ===== */ - .placeholder { - background: var(--bg-tertiary); - border: 1.5px dashed var(--border-strong); - border-radius: 10px; - padding: 2rem; - text-align: center; - font-family: var(--font-mono); - font-size: 0.8rem; - color: var(--text-tertiary); - } - - /* ===== INLINE MOCKUP ELEMENTS ===== */ - .mock-nav { background: var(--accent); color: #fff; padding: 0.75rem 1rem; display: flex; gap: 1.5rem; font-size: 0.9rem; } - .mock-sidebar { background: var(--bg-tertiary); padding: 1rem; min-width: 180px; } - .mock-content { padding: 1.5rem; flex: 1; } - .mock-button { background: var(--accent); color: #fff; border: none; padding: 0.5rem 1rem; border-radius: 7px; font-size: 0.85rem; font-family: var(--font-body); cursor: pointer; } - .mock-input { background: var(--bg-primary); border: 1px solid var(--border); border-radius: 7px; padding: 0.5rem; width: 100%; font-family: var(--font-body); } - - /* ===== SCENARIO TEMPLATES (plan card / review report) ===== */ - table.do-it-table { - width: 100%; - border-collapse: separate; - border-spacing: 0; - font-size: 0.85rem; - margin: 0.5rem 0; - background: var(--bg-secondary); - border: 1px solid var(--border); - border-radius: 11px; - overflow: hidden; - box-shadow: var(--shadow-sm); - } - table.do-it-table th, table.do-it-table td { - padding: 0.55rem 0.8rem; - text-align: left; - vertical-align: top; - border-bottom: 1px solid var(--border); - } - table.do-it-table tr:last-child td { border-bottom: none; } - table.do-it-table th { - background: var(--bg-tertiary); - font-family: var(--font-mono); - font-size: 0.66rem; - font-weight: 600; - text-transform: uppercase; - letter-spacing: 0.1em; - color: var(--text-secondary); - } - table.do-it-table td:first-child { - font-family: var(--font-mono); - font-size: 0.78rem; - font-weight: 600; - color: var(--accent); - white-space: nowrap; - } - table.do-it-table td { color: var(--text-secondary); } - - .finding { - position: relative; - background: var(--bg-secondary); - border: 1px solid var(--border); - border-left: 3px solid var(--border-strong); - border-radius: 9px; - padding: 0.75rem 1rem; - margin-bottom: 0.7rem; - box-shadow: var(--shadow-sm); - } - .finding .sev { - font-family: var(--font-mono); - font-size: 0.64rem; - font-weight: 600; - text-transform: uppercase; - letter-spacing: 0.13em; - margin-bottom: 0.3rem; - } - .finding p { font-size: 0.9rem; color: var(--text-primary); } - .finding.blocking { border-left-color: var(--error); } - .finding.blocking .sev { color: var(--error); } - .finding.important { border-left-color: var(--warning); } - .finding.important .sev { color: var(--warning); } - .finding.opportunity { border-left-color: var(--success); } - .finding.opportunity .sev { color: var(--success); } - .finding .evidence { - font-family: var(--font-mono); - font-size: 0.74rem; - line-height: 1.55; - color: var(--text-secondary); - background: var(--bg-code); - border: 1px solid var(--border); - border-radius: 6px; - padding: 0.45rem 0.6rem; - margin-top: 0.45rem; - white-space: pre-wrap; - } - - @media (prefers-reduced-motion: reduce) { - *, *::before { animation: none !important; transition: none !important; } - } - - - -
-

- - - do-it - Visual Planning - -

-
Connected
-
- -
-
- -
-
- -
- Click an option above, then return to the terminal -
- - - diff --git a/tests/hooks/anti-patterns-lint.test.sh b/tests/hooks/anti-patterns-lint.test.sh index a604d6f..a011078 100644 --- a/tests/hooks/anti-patterns-lint.test.sh +++ b/tests/hooks/anti-patterns-lint.test.sh @@ -162,6 +162,29 @@ OUT=$(_run_hook "$FILE") _assert_not_contains "no-consumer silent for referenced symbol" "$OUT" "- no-consumer:" rm -rf "$DIR" +# ------------------------------------------------------------------------- +echo "Case 4b: no-consumer with only a substring neighbour — word match required" +DIR=$(_setup_repo) +FILE="$DIR/util.ts" +cat > "$FILE" <<'EOF' +// initial +EOF +# Another file references WidgetFactory (Widget is a substring); a whole-word +# match must NOT count it as a consumer of the exported `Widget`. +cat > "$DIR/consumer.ts" <<'EOF' +import { WidgetFactory } from './factory'; +console.log(WidgetFactory()); +EOF +( cd "$DIR" && git add . && git commit -q -m base ) >/dev/null 2>&1 +cat > "$FILE" <<'EOF' +// initial +export function Widget() { return 1; } +EOF +OUT=$(_run_hook "$FILE") +_assert_contains "no-consumer flags symbol with only a substring neighbour" "$OUT" "- no-consumer:" +_assert_contains "names the orphan symbol Widget" "$OUT" "Widget" +rm -rf "$DIR" + # ------------------------------------------------------------------------- echo "Case 5: copy-paste hit — ≥5-line block duplicated in same directory" DIR=$(_setup_repo) diff --git a/tests/hooks/comments-lint.test.sh b/tests/hooks/comments-lint.test.sh index d060c24..b0afbbb 100755 --- a/tests/hooks/comments-lint.test.sh +++ b/tests/hooks/comments-lint.test.sh @@ -210,6 +210,23 @@ OUT=$(_run_hook "$FILE") _assert_not_contains "owner-tagged TODO ok" "$OUT" "orphan-todo" rm -rf "$DIR" +# ------------------------------------------------------------------------- +echo "Case 10: stage markers (phase / wave / backlog id) → flagged as task-ref" +DIR=$(_setup_repo) +FILE="$DIR/stage.ts" +printf 'function s() { return 1; }\n' > "$FILE" +( cd "$DIR" && git add stage.ts && git commit -q -m base ) >/dev/null 2>&1 +cat > "$FILE" <<'EOF' +function s() { + // Phase 3 advisory wiring; tracked at BL-038, lands in wave 2 + return 1; +} +EOF +OUT=$(_run_hook "$FILE") +_assert_contains "flags stage markers" "$OUT" "system-reminder" +_assert_contains "names task-ref family for stage markers" "$OUT" "task-ref" +rm -rf "$DIR" + # ------------------------------------------------------------------------- echo echo "Summary: $PASS passed, $FAIL failed"