From 067d411c9bcbdfd6e691a26e6e7596ed2ee988d9 Mon Sep 17 00:00:00 2001 From: Luka Fagundes Date: Wed, 1 Apr 2026 07:47:31 -0700 Subject: [PATCH] feat: add /gsd:docs-update command for verified documentation generation (#1532) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(01-02): complete gsd-doc-writer agent skeleton plan - SUMMARY.md for plan 01-02 - STATE.md advanced to plan 2/2, progress 50% - ROADMAP.md updated with phase 1 plan progress - REQUIREMENTS.md marked DOCG-01 and DOCG-08 complete * feat(01-01): create lib/docs.cjs with cmdDocsInit and detection helpers - Add cmdDocsInit following cmdInitMapCodebase pattern - Add hasGsdMarker(), scanExistingDocs(), detectProjectType() - Add detectDocTooling(), detectMonorepoWorkspaces() private helpers - GSD_MARKER constant for generated-by tracking - Only Node.js built-ins and local lib requires used * feat(01-01): wire docs-init into gsd-tools.cjs and register gsd-doc-writer model profile - Add const docs = require('./lib/docs.cjs') to gsd-tools.cjs - Add case 'docs-init' routing to docs.cmdDocsInit - Add docs-init to help text and JSDoc header - Register gsd-doc-writer in MODEL_PROFILES (quality:opus, balanced:sonnet, budget:haiku) - Fix docs.cjs: inline withProjectRoot logic via checkAgentsInstalled (private in init.cjs) * docs(01-01): complete docs-init command plan - SUMMARY.md documenting cmdDocsInit, detection helpers, wiring - STATE.md advanced, progress updated to 100% - ROADMAP.md phase 1 marked Complete - REQUIREMENTS.md INFRA-01, INFRA-02, CONS-03 marked complete * feat(01-02): create gsd-doc-writer agent skeleton - YAML frontmatter with name, description, tools, color: purple - role block with doc_assignment receiving convention - create_mode and update_mode sections - 9 stub template sections (readme, architecture, getting_started, development, testing, api, configuration, deployment, contributing) - Each template has Required Sections list and Phase 3 TODO - critical_rules prohibiting GSD methodology and CHANGELOG - success_criteria checklist - No GSD methodology leaks in template sections * feat(02-01): add docs-update workflow Steps 1-6 — init, classify, route, resolve, detect - init_context step calling docs-init with @file: handling and agent-skills loading - validate_agents step warns on missing gsd-doc-writer without halting - classify_project step maps project_type signals to 5 primary labels plus conditional docs - build_doc_queue step with always-on 6 docs and conditional API/CONTRIBUTING/DEPLOYMENT routing - resolve_modes step with doc-type to canonical path mapping and create/update detection - detect_runtime_capabilities step with Task tool detection and sequential fallback routing * docs(02-01): complete docs-update workflow plan — 13-step orchestration for parallel doc generation - 02-01-SUMMARY.md: plan results, decisions, file inventory - STATE.md: advanced to last plan, progress 100%, decisions recorded - ROADMAP.md: Phase 2 marked Complete (1/1 plans with summary) - REQUIREMENTS.md: marked INFRA-04, DOCG-03, DOCG-04, CONS-01, CONS-02, CONS-04 complete * docs(03-02): complete command entry point and workflow extension plan - 03-02-SUMMARY.md: plan results, decisions, file inventory - STATE.md: advanced to plan 2, progress 100%, decisions recorded - ROADMAP.md: Phase 3 marked Complete (2/2 plans with summaries) - REQUIREMENTS.md: marked INFRA-03, EXIST-01, EXIST-02, EXIST-04 complete * feat(03-01): fill all 9 doc templates, add supplement mode and per-package README template - Replace all 9 template stubs with full content guidance (Required Sections, Content Discovery, Format Notes) - Add shared doc_tooling_guidance block for Docusaurus, VitePress, MkDocs, Storybook routing - Add supplement_mode block: append-only strategy with heading comparison and safety rules - Add template_readme_per_package for monorepo per-package README generation - Update role block to list supplement as third mode; add rule 7 to critical_rules - Add supplement mode check to success_criteria - Remove all Phase 3 TODO stubs and placeholder comments * feat(03-02): add docs-update command entry point with --force and --verify-only flags - YAML frontmatter with name, argument-hint, allowed-tools - objective block documents flag semantics with literal-token enforcement pattern - execution_context references docs-update.md workflow - context block passes $ARGUMENTS and documents flag derivation rules - --force takes precedence over --verify-only when both present * feat(03-02): extend docs-update workflow with preservation_check, monorepo dispatch, and verify-only - preservation_check step between resolve_modes and detect_runtime_capabilities - preservation_check skips on --force, --verify-only, or no hand-written docs - per-file AskUserQuestion choice: preserve/supplement/regenerate with fallback default to preserve - dispatch_monorepo_packages step after collect_wave_2 for per-package READMEs - verify_only_report early-exit step with VERIFY marker count and Phase 4 deferral message - preservation_mode field added to all doc_assignment blocks in dispatch_wave_1, dispatch_wave_2 - sequential_generation extended with monorepo per-package section - commit_docs updated to include per-package README files pattern - report extended with per-package README rows and preservation decisions - success_criteria updated with preservation, --force, --verify-only, and monorepo checks * feat(04-01): create gsd-doc-verifier agent with claim extraction and filesystem verification - YAML frontmatter with name, description, tools, and color fields - claim_extraction section with 5 categories: file paths, commands, API endpoints, functions, dependencies - skip_rules section for VERIFY markers, placeholders, example prefixes, and diff blocks - verification_process with 6 steps using filesystem tools only (no self-consistency checks) - output_format with exact JSON shape per D-01 - critical_rules enforcing filesystem-only verification and read-only operation * feat(04-01): add fix_mode to gsd-doc-writer with surgical correction instructions - Add fix_mode section after supplement_mode in modes block - Document fix mode as valid option in role block mode list - Add failures field to doc_assignment fields (fix mode only) - fix_mode enforces surgical precision: only correct listed failing lines - VERIFY marker fallback when correct value cannot be determined * test(04-03): add docs-init integration test suite - 13 tests across 4 describe blocks covering JSON output shape, project type detection, existing doc scanning, GSD marker detection, and doc tooling - Tests use node:test + node:assert/strict with beforeEach/afterEach lifecycle - All 13 tests pass with `node --test tests/docs-update.test.cjs` * feat(04-02): add verify_docs, fix_loop, scan_for_secrets steps to docs-update workflow - verify_docs step spawns gsd-doc-verifier per generated doc and collects structured JSON results - fix_loop step bounded at 2 iterations with regression detection (D-05/D-06) - scan_for_secrets step uses exact map-codebase grep pattern before commit (D-07/D-08) - verify_only_report updated to invoke real gsd-doc-verifier instead of VERIFY marker count stub - success_criteria updated with 4 new verification gate checklist items * docs(04-02): complete verification gate workflow steps plan - SUMMARY.md: verify_docs, fix_loop, scan_for_secrets, and updated verify_only_report - STATE.md: advanced to ready_for_verification, 100% progress, decisions logged - ROADMAP.md: phase 4 marked Complete (3/3 plans with SUMMARYs) - REQUIREMENTS.md: VERF-01, VERF-02, VERF-03 all marked complete * refactor(profiles): Adds 'gsd-doc-verifier' to the 'MODEL_PROFILES' * feat(agents): Add critical rules for file creation and update install test * docs(05): create phase plan for docs output refinement Co-Authored-By: Claude Opus 4.6 (1M context) * feat(05-01): make scanExistingDocs recursive into docs/ subdirectories - Replace flat docs/ scan with recursive walkDir helper (MAX_DEPTH=4) - Add SKIP_DIRS filtering at every level of recursive walk - Add fallback to documentation/ or doc/ when docs/ does not exist - Update JSDoc to reflect recursive scanning behavior Co-Authored-By: Claude Opus 4.6 (1M context) * feat(05-01): update gsd-doc-writer default path guidance to docs/ - Change "No tooling detected" guidance to default to docs/ directory - Add README.md and CONTRIBUTING.md as root-level exceptions - Add instruction to create docs/ directory if it does not exist Co-Authored-By: Claude Opus 4.6 (1M context) * feat(05-02): invert path table to default docs to docs/ directory - Invert resolve_modes path table: docs/ is primary for all types except readme and contributing - Add mkdir -p docs/ instruction before agent dispatch - Update all downstream path references: collect_wave_1, collect_wave_2, commit_docs, report, verify tables - Update sequential_generation wave_1_outputs and resolved path references - Update success criteria and verify_only_report examples to use docs/ paths * feat(05-02): add CONTRIBUTING confirmation gate and existing doc review queue - Add CONTRIBUTING.md user confirmation prompt in build_doc_queue (skipped with --force or when file exists) - Add review_queue for non-canonical existing docs (verification only, not rewriting) - Add review_queue verification in verify_docs step with fix_loop exclusion - Add existing doc accuracy review section to report step with manual correction guidance * docs(05-02): complete path table inversion and doc queue improvements plan - Add 05-02-SUMMARY.md with execution results - Update STATE.md with position, decisions, and metrics - Update ROADMAP.md with phase 05 plan progress * fix(05): replace plain text y/n prompts with AskUserQuestion in docs-update workflow Three prompts were using plain text (y/n) instead of GSD's standard AskUserQuestion pattern: CONTRIBUTING.md confirmation, doc queue proceed gate, and secrets scan confirmation. Co-Authored-By: Claude Opus 4.6 (1M context) * feat(05): structure-aware paths, non-canonical doc fixes, and gap detection - resolve_modes now inspects existing doc directory structure and places new docs in matching subdirectories (e.g., docs/architecture/ if that pattern exists), instead of dumping everything flat into docs/ - Non-canonical docs with inaccuracies are now sent to gsd-doc-writer in fix mode for surgical corrections, not just reported - Added documentation gap detection step that scans the codebase for undocumented areas and prompts user to create missing docs - Added type: custom support to gsd-doc-writer with template_custom section for gap-detected documentation Co-Authored-By: Claude Opus 4.6 (1M context) * fix(05): smarter structure-aware path resolution for grouped doc directories When a project uses grouped subdirectories (docs/architecture/, docs/api/, docs/guides/), ALL canonical docs must be placed in appropriate groups — none left flat in docs/. Added resolution chain per doc type with fallback creation. Filenames now match existing naming style (lowercase-kebab vs UPPERCASE). Queue presentation shows actual resolved paths, not defaults. Co-Authored-By: Claude Opus 4.6 (1M context) * fix(05): restore mode resolution table as primary queue presentation The table showing resolved paths, modes, and sources for each doc must be displayed before the proceed/abort confirmation. It was replaced by a simple list — now restored as the canonical queue view. Co-Authored-By: Claude Opus 4.6 (1M context) * fix(05): use table format for existing docs review queue presentation Co-Authored-By: Claude Opus 4.6 (1M context) * feat(05): add work manifest for structured handoffs between workflow steps Root cause from smoke test: orchestrator forgot to verify 45 non-canonical docs because the review_queue had no structural scaffolding — it existed only in orchestrator memory. Fix: 1. Write docs-work-manifest.json to .planning/tmp/ after resolve_modes with all canonical_queue, review_queue, and gap_queue items 2. Every subsequent step (dispatch, collect, verify, fix_loop, report) MUST read the manifest first — single source of truth 3. Restructured verify_docs into explicit Phase 1 (canonical) and Phase 2 (non-canonical) with separate dispatch for each 4. Both queues now eligible for fix_loop corrections 5. Added manifest read instructions to all dispatch/collect steps Follows the same pattern as execute-phase's phase-plan-index for tracking work items across multi-step orchestration. Co-Authored-By: Claude Opus 4.6 (1M context) * docs(05): update workflow purpose to reflect full command scope Co-Authored-By: Claude Opus 4.6 (1M context) * refactor(05): remove redundant steps from docs-update workflow - Remove validate_agents step (if command is available, agents are installed) - Remove agents_installed/missing_agents extraction from init_context - Remove available_agent_types block (agent types specified in each Task call) - Remove detect_runtime_capabilities step (runtime knows its own tools) - Replace hardcoded flat paths in collect_wave_1/2 with manifest resolved_paths Co-Authored-By: Claude Opus 4.6 (1M context) * fix(05): restore available_agent_types section required by test suite Test enforces that workflows spawning named agents must declare them in an block. Added back with both gsd-doc-writer and gsd-doc-verifier listed. Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- agents/gsd-doc-verifier.md | 201 ++++ agents/gsd-doc-writer.md | 602 +++++++++++ commands/gsd/docs-update.md | 48 + get-shit-done/bin/gsd-tools.cjs | 13 +- get-shit-done/bin/lib/docs.cjs | 267 +++++ get-shit-done/bin/lib/model-profiles.cjs | 2 + get-shit-done/workflows/docs-update.md | 1153 ++++++++++++++++++++++ tests/copilot-install.test.cjs | 2 + tests/docs-update.test.cjs | 272 +++++ 9 files changed, 2559 insertions(+), 1 deletion(-) create mode 100644 agents/gsd-doc-verifier.md create mode 100644 agents/gsd-doc-writer.md create mode 100644 commands/gsd/docs-update.md create mode 100644 get-shit-done/bin/lib/docs.cjs create mode 100644 get-shit-done/workflows/docs-update.md create mode 100644 tests/docs-update.test.cjs diff --git a/agents/gsd-doc-verifier.md b/agents/gsd-doc-verifier.md new file mode 100644 index 000000000..2f3551635 --- /dev/null +++ b/agents/gsd-doc-verifier.md @@ -0,0 +1,201 @@ +--- +name: gsd-doc-verifier +description: Verifies factual claims in generated docs against the live codebase. Returns structured JSON per doc. +tools: Read, Write, Bash, Grep, Glob +color: orange +# hooks: +# PostToolUse: +# - matcher: "Write" +# hooks: +# - type: command +# command: "npx eslint --fix $FILE 2>/dev/null || true" +--- + + +You are a GSD doc verifier. You check factual claims in project documentation against the live codebase. + +You are spawned by the `/gsd:docs-update` workflow. Each spawn receives a `` XML block containing: +- `doc_path`: path to the doc file to verify (relative to project_root) +- `project_root`: absolute path to project root + +Your job: Extract checkable claims from the doc, verify each against the codebase using filesystem tools only, then write a structured JSON result file. Returns a one-line confirmation to the orchestrator only — do not return doc content or claim details inline. + +**CRITICAL: Mandatory Initial Read** +If the prompt contains a `` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context. + + + +Before verifying, discover project context: + +**Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions. + +**Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists: +1. List available skills (subdirectories) +2. Read `SKILL.md` for each skill (lightweight index ~130 lines) +3. Load specific `rules/*.md` files as needed during verification +4. Do NOT load full `AGENTS.md` files (100KB+ context cost) + +This ensures project-specific patterns, conventions, and best practices are applied during verification. + + + +Extract checkable claims from the Markdown doc using these five categories. Process each category in order. + +**1. File path claims** +Backtick-wrapped tokens containing `/` or `.` followed by a known extension. + +Extensions to detect: `.ts`, `.js`, `.cjs`, `.mjs`, `.md`, `.json`, `.yaml`, `.yml`, `.toml`, `.txt`, `.sh`, `.py`, `.go`, `.rs`, `.java`, `.rb`, `.css`, `.html`, `.tsx`, `.jsx` + +Detection: scan inline code spans (text between single backticks) for tokens matching `[a-zA-Z0-9_./-]+\.(ts|js|cjs|mjs|md|json|yaml|yml|toml|txt|sh|py|go|rs|java|rb|css|html|tsx|jsx)`. + +Verification: resolve the path against `project_root` and check if the file exists using the Read or Glob tool. Mark as PASS if exists, FAIL with `{ line, claim, expected: "file exists", actual: "file not found at {resolved_path}" }` if not. + +**2. Command claims** +Inline backtick tokens starting with `npm`, `node`, `yarn`, `pnpm`, `npx`, or `git`; also all lines within fenced code blocks tagged `bash`, `sh`, or `shell`. + +Verification rules: +- `npm run