diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 000000000..741459226 --- /dev/null +++ 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 | - | diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 000000000..8b653e020 --- /dev/null +++ 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 diff --git a/.planning/phases/09-integrate-verify-work/09-01-PLAN.md b/.planning/phases/09-integrate-verify-work/09-01-PLAN.md new file mode 100644 index 000000000..8730dd1e9 --- /dev/null +++ b/.planning/phases/09-integrate-verify-work/09-01-PLAN.md @@ -0,0 +1,134 @@ +--- +phase: 09-integrate-verify-work +plan: 01 +type: execute +--- + + +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. + + + +@~/.claude/get-shit-done/workflows/execute-phase.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.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 + + + + + + Task 1: Create verify-work workflow + get-shit-done/workflows/verify-work.md + +Create workflow following GSD patterns from discuss-phase.md: +- Use `` tag for overview +- Use `` with `` 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 `` 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 + + File exists at get-shit-done/workflows/verify-work.md with proper XML structure + Workflow file created with GSD-compliant structure, all logic preserved + + + + Task 2: Create UAT issues template + get-shit-done/templates/uat-issues.md + +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) + + File exists at get-shit-done/templates/uat-issues.md with proper template structure + Template created with phase-scoped issues format + + + + Task 3: Refactor verify-work command + commands/gsd/verify-work.md + +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: +``` + +1. Validate arguments (phase/plan number) +2. Follow verify-work.md workflow +3. Offer next steps (plan-fix if issues found) + +``` + + Command file matches GSD patterns, references workflow and template + Command refactored to delegate to workflow, follows GSD conventions + + + + + +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 + + + +- 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 + + + +After completion, create `.planning/phases/09-integrate-verify-work/09-01-SUMMARY.md` + diff --git a/.planning/phases/09-integrate-verify-work/09-01-SUMMARY.md b/.planning/phases/09-integrate-verify-work/09-01-SUMMARY.md new file mode 100644 index 000000000..cac83a806 --- /dev/null +++ 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*