docs(09-01): complete GSD-compliant verify-work foundation plan

Tasks completed: 3/3 - Create verify-work workflow - Create UAT issues template - Refactor verify-work command SUMMARY: .planning/phases/09-integrate-verify-work/09-01-SUMMARY.md
2026-01-08 09:00:24 -06:00
parent e5624d3b77
commit 17943465d5
4 changed files with 491 additions and 0 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -0,0 +1,159 @@
+# Roadmap: GSD Brownfield Support
+
+## Overview
+
+Add comprehensive brownfield support to GSD. Users adopting GSD for existing codebases will have a systematic way to capture architectural knowledge before planning begins. A new `/gsd:map-codebase` workflow will produce structured `.planning/codebase/` documents that stay current as plans execute.
+
+## Domain Expertise
+
+None - this is internal GSD development following existing command/workflow/template patterns.
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+- [ ] **Phase 1: Templates & Structure** - Create codebase map templates and folder structure
+- [ ] **Phase 2: Map Codebase Command** - Build /gsd:map-codebase with parallel Explore agents
+- [ ] **Phase 3: Integration** - Wire brownfield support into existing GSD workflows
+
+## Phase Details
+
+### Phase 1: Templates & Structure
+**Goal**: Create templates for all codebase map document types and define the folder structure
+**Depends on**: Nothing (first phase)
+**Research**: Unlikely (established GSD template patterns)
+**Plans**: TBD
+
+Documents to template:
+- stack.md (languages, frameworks, dependencies)
+- architecture.md (patterns, layers, data flow)
+- structure.md (directory layout, key files)
+- conventions.md (coding standards, naming)
+- testing.md (test setup, patterns)
+- integrations.md (external services, APIs)
+- concerns.md (tech debt, known issues)
+
+### Phase 2: Map Codebase Command
+**Goal**: Build the /gsd:map-codebase slash command with parallel Explore agent workflow
+**Depends on**: Phase 1
+**Research**: Unlikely (using existing Explore agent patterns, GSD workflow conventions)
+**Plans**: TBD
+
+Components:
+- Slash command: `commands/gsd/map-codebase.md`
+- Workflow: `get-shit-done/workflows/map-codebase.md`
+- Parallel Explore agent orchestration
+- Output to `.planning/codebase/`
+
+### Phase 3: Integration
+**Goal**: Wire brownfield support into existing GSD workflows
+**Depends on**: Phase 2
+**Research**: Unlikely (modifying existing GSD commands, established patterns)
+**Plans**: TBD
+
+Integration points:
+- `/gsd:new-project` - detect existing code, offer to map first
+- `/gsd:plan-phase` - load relevant codebase context automatically
+- Post-execution - update codebase map after plan execution
+
+### Phase 4: Plan-Phase Optimizations
+**Goal**: Reduce context usage in /gsd:plan-phase by ~37% through file consolidation and verbosity reduction
+**Depends on**: Phase 3
+**Research**: Unlikely (internal optimization of existing files)
+**Plans**: TBD
+
+Optimization targets:
+- Merge `cli-automation.md` into `checkpoints.md` (-15KB)
+- Compress `plan-format.md` to reference card (-7KB)
+- Trim `scope-estimation.md` verbosity (-6KB)
+- Streamline `plan-phase.md` workflow (-9KB)
+
+### Phase 5: TDD Instructions
+**Goal**: Add TDD guidance to GSD so Claude uses test-driven development when appropriate and beneficial
+**Depends on**: Phase 4
+**Research**: Unlikely (established TDD patterns, GSD integration points clear)
+**Plans**: 2 plans
+
+Plans:
+- [ ] 05-01: TDD Foundation - Create tdd.md reference, add TDD annotation to plan-format.md
+- [ ] 05-02: TDD Integration - Update plan-phase.md detection, execute-phase.md execution flow
+
+### Phase 6: Frontmatter System Upgrade
+
+**Goal:** Add YAML frontmatter to SUMMARY.md enabling automatic context assembly via dependency graph
+**Depends on:** Phase 5
+**Plans:** 2 plans
+
+Plans:
+- [ ] 06-01: Frontmatter Schema - Add comprehensive YAML frontmatter to summary.md template with dependency metadata
+- [ ] 06-02: Intelligent Selection - Implement frontmatter-based context assembly in plan-phase.md
+
+**Details:**
+Transform planning from "Claude guesses which summaries to read" to "System automatically assembles optimal context" by:
+- Adding frontmatter with subsystem, requires/provides/affects, tech-stack, key-files, key-decisions
+- Scanning all summary frontmatter (fast - first ~25 lines each)
+- Building dependency graph to auto-select relevant prior phases
+- Extracting context from frontmatter before reading full summaries
+- Making context assembly deterministic and optimal
+
+### Phase 7: Backfill Existing Summaries With Frontmatter
+
+**Goal:** Backfill YAML frontmatter with dependency graph metadata to Phase 1-6 historical summaries
+**Depends on:** Phase 6
+**Plans:** 1 plan
+
+Plans:
+- [x] 07-01: Backfill frontmatter to all Phase 1-5 summaries (10 files)
+
+**Details:**
+Enable intelligent context assembly for all historical phases by adding consistent frontmatter with subsystem categorization, dependency graph (requires/provides/affects), tech tracking, key decisions, and patterns established.
+
+### Phase 8: Improve Roadmap System
+
+**Goal:** [To be planned]
+**Depends on:** Phase 7
+**Research:** Unlikely (internal GSD workflow improvements)
+**Plans:** TBD
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 8 to break down)
+
+**Details:**
+[To be added during planning]
+
+### Phase 9: Integrate Verify-Work
+
+**Goal:** Properly integrate /gsd:verify-work into GSD with workflow delegation, templates, and /gsd:plan-fix command
+**Depends on:** Phase 8
+**Research:** Unlikely (refactoring contributed command to match GSD patterns)
+**Plans:** TBD
+
+Components:
+- Refactor `commands/gsd/verify-work.md` to GSD style (workflow delegation)
+- Create `workflows/verify-work.md` for UAT logic
+- Create `templates/uat-issues.md` for phase-scoped issues format
+- Create `commands/gsd/plan-fix.md` for planning fixes from UAT issues
+- Update `commands/gsd/progress.md` to offer plan-fix when issues exist
+- Update README.md with new commands
+
+**Details:**
+Community contribution from OracleGreyBeard. Original command works but doesn't follow GSD patterns (no workflow delegation, inline templates, verbose steps). Refactor to match conventions, then add /gsd:plan-fix to complete the verify → fix loop.
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Templates & Structure | 3/3 | Complete | 2025-12-17 |
+| 2. Map Codebase Command | 2/2 | Complete | 2025-12-17 |
+| 3. Integration | 1/1 | Complete | 2025-12-17 |
+| 4. Plan-Phase Optimizations | 2/2 | Complete | 2025-12-29 |
+| 5. TDD Instructions | 2/2 | Complete | 2025-12-31 |
+| 6. Frontmatter System Upgrade | 2/2 | Complete | 2026-01-05 |
+| 7. Backfill Existing Summaries | 1/1 | Complete | 2026-01-05 |
+| 8. Improve Roadmap System | 1/1 | Complete | 2026-01-05 |
+| 9. Integrate Verify-Work | 1/? | In Progress | - |
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -0,0 +1,99 @@
+# Project State
+
+## Project Summary
+
+**Building:** Brownfield support for GSD - `/gsd:map-codebase` workflow that analyzes existing codebases using parallel Explore agents, producing structured `.planning/codebase/` documents.
+
+**Core requirements:**
+- `/gsd:map-codebase` produces useful codebase documents from any codebase
+- Documents are focused (<100 lines each) and easy to update incrementally
+- `/gsd:new-project` detects existing code and offers mapping
+- `/gsd:plan-phase` loads relevant codebase context automatically
+- Codebase map updates after plan execution
+
+**Constraints:**
+- Explore agents required for initial mapping
+- Each codebase map file must stay under ~100 lines
+- Only load relevant codebase sections into phase planning
+- Follow existing GSD command/workflow/template patterns
+
+## Current Position
+
+Phase: 9 of 9 (Integrate Verify-Work)
+Plan: 1 of ? in current phase
+Status: In progress
+Last activity: 2026-01-08 - Completed 09-01-PLAN.md
+
+Progress: ████████████░ 93% (15 of 16+ plans)
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: 15
+- Average duration: 2.7 min
+- Total execution time: 40 min
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| 1 | 3 | 9 min | 3 min |
+| 2 | 2 | 5 min | 2.5 min |
+| 3 | 1 | 2 min | 2 min |
+| 4 | 2 | 7 min | 3.5 min |
+| 5 | 2 | 5 min | 2.5 min |
+| 6 | 2 | 4 min | 2 min |
+| 7 | 1 | 4 min | 4 min |
+| 8 | 1 | 1 min | 1 min |
+| 9 | 1 | 3 min | 3 min |
+
+**Recent Trend:**
+- Last 5 plans: 06-01 (2m), 06-02 (2m), 07-01 (4m), 08-01 (1m), 09-01 (3m)
+- Trend: Stable (2-4 min avg)
+
+*Updated after each plan completion*
+
+## Accumulated Context
+
+### Decisions Made
+
+| Phase | Decision | Rationale |
+|-------|----------|-----------|
+| 0 | Folder with focused files | Easier to update incrementally than monolithic file |
+| 0 | Update after plan execution | Fits existing STATE.md update pattern |
+| 0 | Parallel Explore agents | Thoroughness for initial mapping |
+| 0 | Selective context loading | Avoid loading irrelevant sections |
+| 6 | Frontmatter with dependency graph | Enable automatic context assembly via transitive closure |
+| 6 | Intelligent summary selection | Scan frontmatter, build graph, auto-select relevant phases |
+| 8 | Active milestone details in ROADMAP.md | Single source of truth during development, archive only on completion |
+| 9 | Phase-scoped UAT issues | Keep UAT findings tied to specific plan, not global ISSUES.md |
+
+### Deferred Issues
+
+None yet.
+
+### Blockers/Concerns Carried Forward
+
+None yet.
+
+### Roadmap Evolution
+
+- Phase 4 added: Plan-phase optimizations (~37% context reduction target)
+- Phase 5 added: TDD instructions for appropriate test-driven development
+- Phase 6 added: Frontmatter and related system upgrade
+- Phase 7 added: Backfill existing summaries with frontmatter
+- Phase 8 added: Improve roadmap system
+- Phase 9 added: Integrate verify-work (community contribution from OracleGreyBeard)
+
+## Project Alignment
+
+Last checked: Project start
+Status: ✓ Aligned
+Assessment: No work done yet - baseline alignment.
+Drift notes: None
+
+## Session Continuity
+
+Last session: 2026-01-08
+Stopped at: Completed 09-01-PLAN.md
+Resume file: None
--- a/.planning/phases/09-integrate-verify-work/09-01-PLAN.md
+++ b/.planning/phases/09-integrate-verify-work/09-01-PLAN.md
@@ -0,0 +1,134 @@
+---
+phase: 09-integrate-verify-work
+plan: 01
+type: execute
+---
+
+<objective>
+Create GSD-compliant foundation for verify-work: workflow, template, and refactored command.
+
+Purpose: Align community-contributed verify-work command with GSD patterns (workflow delegation, templates, terse steps).
+Output: Refactored verify-work.md command, new verify-work.md workflow, new uat-issues.md template.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/execute-phase.md
+@~/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+
+**Current verify-work.md (to refactor):**
+@commands/gsd/verify-work.md
+
+**Pattern references (existing GSD commands to match):**
+@commands/gsd/discuss-phase.md
+@commands/gsd/consider-issues.md
+
+**Pattern references (existing GSD workflows to match):**
+@get-shit-done/workflows/discuss-phase.md
+
+**Pattern references (existing GSD templates to match):**
+@get-shit-done/templates/context.md
+@get-shit-done/templates/issues.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create verify-work workflow</name>
+  <files>get-shit-done/workflows/verify-work.md</files>
+  <action>
+Create workflow following GSD patterns from discuss-phase.md:
+- Use `<purpose>` tag for overview
+- Use `<process>` with `<step name="X">` tags (terse names: identify, extract, generate, guide, collect, log, summarize, offer)
+- Reference template for issues format: `@~/.claude/get-shit-done/templates/uat-issues.md`
+- Log issues to phase-scoped file: `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md` (NOT global ISSUES.md)
+- Use AskUserQuestion for all user interaction (matching discuss-phase.md pattern)
+- Include `<success_criteria>` at end
+
+Key logic to preserve from current verify-work.md:
+- Find SUMMARY.md based on args or most recent
+- Extract user-observable deliverables
+- Generate test checklist
+- Guide through pass/fail/partial/skip for each test
+- Collect issues with severity
+- Present summary with verdict
+- Offer next actions based on results
+  </action>
+  <verify>File exists at get-shit-done/workflows/verify-work.md with proper XML structure</verify>
+  <done>Workflow file created with GSD-compliant structure, all logic preserved</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Create UAT issues template</name>
+  <files>get-shit-done/templates/uat-issues.md</files>
+  <action>
+Create template for phase-scoped UAT issues following patterns from context.md and issues.md:
+- Template header explaining purpose and location
+- File template section with markdown structure
+- Location: `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md`
+- Fields: UAT-NNN prefix, discovered date, phase/plan tested, severity, description, expected, actual
+- Include good_examples section
+- Include guidelines section
+
+Key difference from global issues.md:
+- Scoped to specific plan that was tested
+- Used as input for /gsd:plan-fix command
+- No "Closed Enhancements" section (issues are fixed via FIX.md plan, then file is historical record)
+  </action>
+  <verify>File exists at get-shit-done/templates/uat-issues.md with proper template structure</verify>
+  <done>Template created with phase-scoped issues format</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Refactor verify-work command</name>
+  <files>commands/gsd/verify-work.md</files>
+  <action>
+Refactor to match GSD command patterns from discuss-phase.md:
+- Add `name: gsd:verify-work` to frontmatter (already present)
+- Update execution_context to reference workflow: `@~/.claude/get-shit-done/workflows/verify-work.md`
+- Add template reference: `@~/.claude/get-shit-done/templates/uat-issues.md`
+- Simplify process section to delegate to workflow (like discuss-phase.md does)
+- Remove inline step details (moved to workflow)
+- Keep anti_patterns and success_criteria sections
+- Update success_criteria to reference phase-scoped ISSUES.md
+
+Structure should match discuss-phase.md:
+```
+<process>
+1. Validate arguments (phase/plan number)
+2. Follow verify-work.md workflow
+3. Offer next steps (plan-fix if issues found)
+</process>
+```
+  </action>
+  <verify>Command file matches GSD patterns, references workflow and template</verify>
+  <done>Command refactored to delegate to workflow, follows GSD conventions</done>
+</task>
+
+</tasks>
+
+<verification>
+Before declaring plan complete:
+- [ ] `get-shit-done/workflows/verify-work.md` exists with proper XML structure
+- [ ] `get-shit-done/templates/uat-issues.md` exists with template format
+- [ ] `commands/gsd/verify-work.md` delegates to workflow
+- [ ] No inline logic remains in command (all in workflow)
+- [ ] Issues logged to phase-scoped file, not global ISSUES.md
+</verification>
+
+<success_criteria>
+- All 3 files created/updated
+- Workflow follows GSD patterns (terse steps, XML structure)
+- Template follows GSD patterns (examples, guidelines)
+- Command delegates to workflow (no inline logic)
+- Phase-scoped issues file location used
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/09-integrate-verify-work/09-01-SUMMARY.md`
+</output>
--- a/.planning/phases/09-integrate-verify-work/09-01-SUMMARY.md
+++ b/.planning/phases/09-integrate-verify-work/09-01-SUMMARY.md
@@ -0,0 +1,99 @@
+---
+phase: 09-integrate-verify-work
+plan: 01
+subsystem: commands
+tags: [verify-work, uat, testing, workflow, template]
+
+# Dependency graph
+requires:
+  - phase: 08-improve-roadmap
+    provides: GSD command/workflow patterns
+provides:
+  - verify-work workflow with GSD structure
+  - UAT issues template for phase-scoped issues
+  - Refactored verify-work command with workflow delegation
+affects: [plan-fix, progress]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [workflow-delegation, phase-scoped-issues, AskUserQuestion-pattern]
+
+key-files:
+  created:
+    - get-shit-done/workflows/verify-work.md
+    - get-shit-done/templates/uat-issues.md
+  modified:
+    - commands/gsd/verify-work.md
+
+key-decisions:
+  - "Phase-scoped issues (not global ISSUES.md) for UAT findings"
+  - "UAT- prefix distinguishes from ISS- enhancement issues"
+  - "Workflow delegates via AskUserQuestion for all user interaction"
+
+patterns-established:
+  - "Phase-scoped issue files: {phase}-{plan}-ISSUES.md alongside SUMMARY.md"
+  - "UAT workflow: extract → generate → guide → collect → log → summarize → offer"
+
+issues-created: []
+
+# Metrics
+duration: 3min
+completed: 2026-01-08
+---
+
+# Phase 9 Plan 1: GSD-Compliant Verify-Work Foundation Summary
+
+**Workflow, template, and refactored command for UAT testing with phase-scoped issue logging**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-01-08T14:55:24Z
+- **Completed:** 2026-01-08T14:58:12Z
+- **Tasks:** 3
+- **Files modified:** 3
+
+## Accomplishments
+
+- Created verify-work workflow with GSD-compliant XML structure (terse step names, AskUserQuestion pattern)
+- Created UAT issues template for phase-scoped issue tracking
+- Refactored verify-work command to delegate to workflow (no inline logic)
+
+## Task Commits
+
+1. **Task 1: Create verify-work workflow** - `a9a9eff` (feat)
+2. **Task 2: Create UAT issues template** - `654b066` (feat)
+3. **Task 3: Refactor verify-work command** - `e5624d3` (refactor)
+
+**Plan metadata:** (pending)
+
+## Files Created/Modified
+
+- `get-shit-done/workflows/verify-work.md` - UAT workflow with 8 terse steps
+- `get-shit-done/templates/uat-issues.md` - Phase-scoped issue format with severity guide
+- `commands/gsd/verify-work.md` - Refactored to delegate to workflow
+
+## Decisions Made
+
+- Phase-scoped issues (`{phase}-{plan}-ISSUES.md`) rather than global `ISSUES.md` — keeps UAT findings tied to specific work
+- UAT- prefix for numbering — distinguishes from ISS- enhancement issues
+- Per-file numbering (UAT-001, UAT-002) — no global sequence needed
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None
+
+## Next Phase Readiness
+
+- verify-work workflow ready for use
+- Next: Create `/gsd:plan-fix` command to complete verify → fix loop
+- README.md update needed to document new commands
+
+---
+*Phase: 09-integrate-verify-work*
+*Completed: 2026-01-08*