gsd-opencode 1.3.31

package/get-shit-done/workflows/list-phase-assumptions.md

@@ -0,0 +1,178 @@
+<purpose>
+Surface Claude's assumptions about a phase before planning, enabling users to correct misconceptions early.
+
+Key difference from discuss-phase: This is ANALYSIS of what Claude thinks, not INTAKE of what user knows. No file output - purely conversational to prompt discussion.
+</purpose>
+
+<process>
+
+<step name="validate_phase" priority="first">
+Phase number: $ARGUMENTS (required)
+
+**If argument missing:**
+
+```
+Error: Phase number required.
+
+Usage: /gsd:list-phase-assumptions [phase-number]
+Example: /gsd:list-phase-assumptions 3
+```
+
+Exit workflow.
+
+**If argument provided:**
+Validate phase exists in roadmap:
+
+```bash
+cat .planning/ROADMAP.md | grep -i "Phase ${PHASE}"
+```
+
+**If phase not found:**
+
+```
+Error: Phase ${PHASE} not found in roadmap.
+
+Available phases:
+[list phases from roadmap]
+```
+
+Exit workflow.
+
+**If phase found:**
+Parse phase details from roadmap:
+
+- Phase number
+- Phase name
+- Phase description/goal
+- Any scope details mentioned
+
+Continue to analyze_phase.
+</step>
+
+<step name="analyze_phase">
+Based on roadmap description and project context, identify assumptions across five areas:
+
+**1. Technical Approach:**
+What libraries, frameworks, patterns, or tools would Claude use?
+- "I'd use X library because..."
+- "I'd follow Y pattern because..."
+- "I'd structure this as Z because..."
+
+**2. Implementation Order:**
+What would Claude build first, second, third?
+- "I'd start with X because it's foundational"
+- "Then Y because it depends on X"
+- "Finally Z because..."
+
+**3. Scope Boundaries:**
+What's included vs excluded in Claude's interpretation?
+- "This phase includes: A, B, C"
+- "This phase does NOT include: D, E, F"
+- "Boundary ambiguities: G could go either way"
+
+**4. Risk Areas:**
+Where does Claude expect complexity or challenges?
+- "The tricky part is X because..."
+- "Potential issues: Y, Z"
+- "I'd watch out for..."
+
+**5. Dependencies:**
+What does Claude assume exists or needs to be in place?
+- "This assumes X from previous phases"
+- "External dependencies: Y, Z"
+- "This will be consumed by..."
+
+Be honest about uncertainty. Mark assumptions with confidence levels:
+- "Fairly confident: ..." (clear from roadmap)
+- "Assuming: ..." (reasonable inference)
+- "Unclear: ..." (could go multiple ways)
+</step>
+
+<step name="present_assumptions">
+Present assumptions in a clear, scannable format:
+
+```
+## My Assumptions for Phase ${PHASE}: ${PHASE_NAME}
+
+### Technical Approach
+[List assumptions about how to implement]
+
+### Implementation Order
+[List assumptions about sequencing]
+
+### Scope Boundaries
+**In scope:** [what's included]
+**Out of scope:** [what's excluded]
+**Ambiguous:** [what could go either way]
+
+### Risk Areas
+[List anticipated challenges]
+
+### Dependencies
+**From prior phases:** [what's needed]
+**External:** [third-party needs]
+**Feeds into:** [what future phases need from this]
+
+---
+
+**What do you think?**
+
+Are these assumptions accurate? Let me know:
+- What I got right
+- What I got wrong
+- What I'm missing
+```
+
+Wait for user response.
+</step>
+
+<step name="gather_feedback">
+**If user provides corrections:**
+
+Acknowledge the corrections:
+
+```
+Got it. Key corrections:
+- [correction 1]
+- [correction 2]
+
+This changes my understanding significantly. [Summarize new understanding]
+```
+
+**If user confirms assumptions:**
+
+```
+Great, assumptions validated.
+```
+
+Continue to offer_next.
+</step>
+
+<step name="offer_next">
+Present next steps:
+
+```
+What's next?
+1. Discuss context (/gsd:discuss-phase ${PHASE}) - Let me ask you questions to build comprehensive context
+2. Plan this phase (/gsd:plan-phase ${PHASE}) - Create detailed execution plans
+3. Re-examine assumptions - I'll analyze again with your corrections
+4. Done for now
+```
+
+Wait for user selection.
+
+If "Discuss context": Note that CONTEXT.md will incorporate any corrections discussed here
+If "Plan this phase": Proceed knowing assumptions are understood
+If "Re-examine": Return to analyze_phase with updated understanding
+</step>
+
+</process>
+
+<success_criteria>
+- Phase number validated against roadmap
+- Assumptions surfaced across five areas: technical approach, implementation order, scope, risks, dependencies
+- Confidence levels marked where appropriate
+- "What do you think?" prompt presented
+- User feedback acknowledged
+- Clear next steps offered
+</success_criteria>

package/get-shit-done/workflows/map-codebase.md

@@ -0,0 +1,434 @@
+<purpose>
+Orchestrate parallel Explore agents to analyze codebase and produce structured documents in .planning/codebase/
+
+Each agent has fresh context and focuses on specific aspects. Output is concise and actionable for planning.
+</purpose>
+
+<philosophy>
+**Why parallel agents:**
+- Fresh context per domain (no token contamination)
+- Thorough analysis without context exhaustion
+- Each agent optimized for its domain (tech vs organization vs quality vs issues)
+- Faster execution (agents run simultaneously)
+
+**Document quality over length:**
+Include enough detail to be useful as reference. Prioritize practical examples (especially code patterns) over arbitrary brevity. A 200-line TESTING.md with real patterns is more valuable than a 74-line summary.
+
+**Always include file paths:**
+Documents are reference material for Claude when planning/executing. Vague descriptions like "UserService handles users" are not actionable. Always include actual file paths formatted with backticks: `src/services/user.ts`. This allows Claude to navigate directly to relevant code without re-searching. Do NOT include line numbers (they go stale), just file paths.
+</philosophy>
+
+<process>
+
+<step name="check_existing" priority="first">
+Check if .planning/codebase/ already exists:
+
+```bash
+ls -la .planning/codebase/ 2>/dev/null
+```
+
+**If exists:**
+
+```
+.planning/codebase/ already exists with these documents:
+[List files found]
+
+What's next?
+1. Refresh - Delete existing and remap codebase
+2. Update - Keep existing, only update specific documents
+3. Skip - Use existing codebase map as-is
+```
+
+Wait for user response.
+
+If "Refresh": Delete .planning/codebase/, continue to create_structure
+If "Update": Ask which documents to update, continue to spawn_agents (filtered)
+If "Skip": Exit workflow
+
+**If doesn't exist:**
+Continue to create_structure.
+</step>
+
+<step name="create_structure">
+Create .planning/codebase/ directory:
+
+```bash
+mkdir -p .planning/codebase
+```
+
+**Expected output files:**
+- STACK.md (from stack.md template)
+- ARCHITECTURE.md (from architecture.md template)
+- STRUCTURE.md (from structure.md template)
+- CONVENTIONS.md (from conventions.md template)
+- TESTING.md (from testing.md template)
+- INTEGRATIONS.md (from integrations.md template)
+- CONCERNS.md (from concerns.md template)
+
+Continue to spawn_agents.
+</step>
+
+<step name="spawn_agents">
+Spawn 4 parallel Explore agents to analyze codebase.
+
+Use Task tool with `subagent_type="Explore"` and `run_in_background=true` for parallel execution.
+
+**Agent 1: Stack + Integrations (Technology Focus)**
+
+Task tool parameters:
+```
+subagent_type: "Explore"
+run_in_background: true
+task_description: "Analyze codebase technology stack and external integrations"
+```
+
+Prompt:
+```
+Analyze this codebase for technology stack and external integrations.
+
+IMPORTANT: Always include actual file paths in your findings. Use backtick formatting like `src/config/database.ts`. This makes the output actionable for planning.
+
+Focus areas:
+1. Languages (check file extensions, package manifests)
+2. Runtime environment (Node.js, Python, etc. - check .nvmrc, .python-version, engines field)
+3. Package manager and lockfiles
+4. Frameworks (web, testing, build tools)
+5. Key dependencies (critical packages for functionality)
+6. External services (APIs, databases, auth providers)
+7. Third-party integrations (payment, analytics, etc.)
+8. Configuration approach (.env, config files)
+
+Search for:
+- package.json / requirements.txt / Cargo.toml / go.mod
+- .env files, .env.example
+- Config files (vite.config, webpack.config, tsconfig.json)
+- API client code, database connection code
+- Import statements for major libraries
+
+Output findings for populating these sections:
+- STACK.md: Languages, Runtime, Frameworks, Dependencies, Configuration
+- INTEGRATIONS.md: External APIs, Services, Third-party tools
+
+For each finding, include the file path where you found it. Example:
+- "TypeScript 5.3 - `package.json`"
+- "Supabase client - `src/lib/supabase.ts`"
+- "Stripe integration - `src/services/stripe.ts`, `src/webhooks/stripe.ts`"
+
+If something is not found, note "Not detected" for that category.
+```
+
+**Agent 2: Architecture + Structure (Organization Focus)**
+
+Task tool parameters:
+```
+subagent_type: "Explore"
+run_in_background: true
+task_description: "Analyze codebase architecture patterns and directory structure"
+```
+
+Prompt:
+```
+Analyze this codebase architecture and directory structure.
+
+IMPORTANT: Always include actual file paths in your findings. Use backtick formatting like `src/index.ts`. This makes the output actionable for planning.
+
+Focus areas:
+1. Overall architectural pattern (monolith, microservices, layered, etc.)
+2. Conceptual layers (API, service, data, utility)
+3. Data flow and request lifecycle
+4. Key abstractions and patterns (services, controllers, repositories)
+5. Entry points (main files, server files, CLI entry)
+6. Directory organization and purposes
+7. Module boundaries
+8. Naming conventions for directories and files
+
+Search for:
+- Entry points: index.ts, main.ts, server.ts, app.ts, cli.ts
+- Directory structure patterns (src/, lib/, components/, services/)
+- Import patterns (what imports what)
+- Recurring code patterns (base classes, interfaces, common abstractions)
+
+Output findings for populating these sections:
+- ARCHITECTURE.md: Pattern, Layers, Data Flow, Abstractions, Entry Points
+- STRUCTURE.md: Directory layout, Organization, Key locations
+
+For each finding, include the file path. Examples:
+- "CLI entry point: `bin/install.js`"
+- "Service layer: `src/services/*.ts` (UserService, ProjectService)"
+- "API routes: `src/routes/api/*.ts`"
+
+If something is not clear, provide best-guess interpretation based on code structure.
+```
+
+**Agent 3: Conventions + Testing (Quality Focus)**
+
+Task tool parameters:
+```
+subagent_type: "Explore"
+run_in_background: true
+task_description: "Analyze coding conventions and test patterns"
+```
+
+Prompt:
+```
+Analyze this codebase for coding conventions and testing practices.
+
+IMPORTANT: Always include actual file paths in your findings. Use backtick formatting like `vitest.config.ts`. This makes the output actionable for planning.
+
+Focus areas:
+1. Code style (indentation, quotes, semicolons, formatting)
+2. File naming conventions (kebab-case, PascalCase, etc.)
+3. Function/variable naming patterns
+4. Comment and documentation style
+5. Test framework and structure
+6. Test organization (unit, integration, e2e)
+7. Test coverage approach
+8. Linting and formatting tools
+
+Search for:
+- Config files: .eslintrc, .prettierrc, tsconfig.json
+- Test files: *.test.*, *.spec.*, __tests__/
+- Test setup: vitest.config, jest.config
+- Code patterns across multiple files
+- README or CONTRIBUTING docs
+
+Output findings for populating these sections:
+- CONVENTIONS.md: Code Style, Naming, Patterns, Documentation
+- TESTING.md: Framework, Structure, Coverage, Tools
+
+For each finding, include file paths. Examples:
+- "Prettier config: `.prettierrc`"
+- "Test pattern: `src/**/*.test.ts` (co-located with source)"
+- "Example of naming convention: `src/services/user-service.ts`"
+
+Look at actual code files to infer conventions if config files are missing.
+```
+
+**Agent 4: Concerns (Issues Focus)**
+
+Task tool parameters:
+```
+subagent_type: "Explore"
+run_in_background: true
+task_description: "Identify technical debt and areas of concern"
+```
+
+Prompt:
+```
+Analyze this codebase for technical debt, known issues, and areas of concern.
+
+CRITICAL: Always include actual file paths in your findings. Use backtick formatting like `src/auth/login.ts`. Concerns without file paths are not actionable. For each issue found, specify exactly where it is.
+
+Focus areas:
+1. TODO and FIXME comments
+2. Complex or hard-to-understand code
+3. Missing error handling (try/catch, error checks)
+4. Security patterns (hardcoded secrets, unsafe operations)
+5. Outdated dependencies (check versions against current)
+6. Missing tests for critical code
+7. Duplicate code patterns
+8. Performance concerns (N+1 queries, inefficient loops)
+9. Documentation gaps (complex code without comments)
+
+Search for:
+- TODO, FIXME, HACK, XXX comments
+- Large functions or files (>200 lines)
+- Repeated code patterns
+- Missing .env.example when .env is used
+- Dependencies with known vulnerabilities (check versions)
+- Error-prone patterns (no validation, no error handling)
+
+Output findings for populating:
+- CONCERNS.md: Technical Debt, Issues, Security, Performance, Documentation
+
+For EVERY concern, include file paths. Examples:
+- "Direct DB queries in components: `src/pages/Dashboard.tsx`, `src/pages/Profile.tsx`"
+- "Missing error handling: `src/api/webhook.ts` (Stripe webhook has no try/catch)"
+- "TODO: 'fix race condition' in `src/services/subscription.ts`"
+
+Be constructive - focus on actionable concerns, not nitpicks.
+If codebase is clean, note that rather than inventing problems.
+```
+
+Continue to collect_results.
+</step>
+
+<step name="collect_results">
+Wait for all 4 agents to complete.
+
+Use TaskOutput tool to collect results from each agent. Since agents were run with `run_in_background=true`, retrieve their output.
+
+**Collection pattern:**
+
+For each agent, use TaskOutput tool to get the full exploration findings.
+
+**Aggregate findings by document:**
+
+From Agent 1 output, extract:
+- STACK.md sections: Languages, Runtime, Frameworks, Dependencies, Configuration, Platform
+- INTEGRATIONS.md sections: External APIs, Services, Authentication, Webhooks
+
+From Agent 2 output, extract:
+- ARCHITECTURE.md sections: Pattern Overview, Layers, Data Flow, Key Abstractions, Entry Points
+- STRUCTURE.md sections: Directory Layout, Key Locations, Organization
+
+From Agent 3 output, extract:
+- CONVENTIONS.md sections: Code Style, Naming Conventions, Common Patterns, Documentation Style
+- TESTING.md sections: Framework, Structure, Coverage, Tools
+
+From Agent 4 output, extract:
+- CONCERNS.md sections: Technical Debt, Known Issues, Security, Performance, Missing
+
+**Handling missing findings:**
+
+If an agent didn't find information for a section, use placeholder:
+- "Not detected" (for infrastructure/tools that may not exist)
+- "Not applicable" (for patterns that don't apply to this codebase)
+- "No significant concerns" (for CONCERNS.md if codebase is clean)
+
+Continue to write_documents.
+</step>
+
+<step name="write_documents">
+Write all 7 codebase documents using templates and agent findings.
+
+**Template filling process:**
+
+For each document:
+
+1. **Read template file** from `~/.config/opencode/get-shit-done/templates/codebase/{name}.md`
+2. **Extract the "File Template" section** - this is the markdown code block containing the actual document structure
+3. **Fill template placeholders** with agent findings:
+   - Replace `[YYYY-MM-DD]` with current date
+   - Replace `[Placeholder text]` with specific findings from agents
+   - If agent found nothing for a section, use appropriate placeholder:
+     - "Not detected" for optional infrastructure
+     - "Not applicable" for patterns that don't fit this codebase
+     - "No significant concerns" for clean codebase areas
+4. **Write to .planning/codebase/{NAME}.md** (uppercase filename)
+
+**Example filling pattern:**
+
+Template placeholder:
+```
+**Primary:**
+- [Language] [Version] - [Where used: e.g., "all application code"]
+```
+
+Agent finding:
+```
+Found: TypeScript 5.3 used in all .ts files throughout src/
+```
+
+Filled result:
+```
+**Primary:**
+- TypeScript 5.3 - All application code
+```
+
+**Document writing order:**
+
+1. **STACK.md** (from stack.md template + Agent 1 findings)
+2. **INTEGRATIONS.md** (from integrations.md template + Agent 1 findings)
+3. **ARCHITECTURE.md** (from architecture.md template + Agent 2 findings)
+4. **STRUCTURE.md** (from structure.md template + Agent 2 findings)
+5. **CONVENTIONS.md** (from conventions.md template + Agent 3 findings)
+6. **TESTING.md** (from testing.md template + Agent 3 findings)
+7. **CONCERNS.md** (from concerns.md template + Agent 4 findings)
+
+After all documents written, continue to verify_output.
+</step>
+
+<step name="verify_output">
+Verify all documents created successfully:
+
+```bash
+ls -la .planning/codebase/
+wc -l .planning/codebase/*.md
+```
+
+**Verification checklist:**
+- All 7 documents exist
+- No empty documents
+- Templates populated with findings
+
+If any checks fail, report issues to user.
+
+Continue to commit_codebase_map.
+</step>
+
+<step name="commit_codebase_map">
+Commit the codebase map:
+
+```bash
+git add .planning/codebase/*.md
+git commit -m "$(cat <<'EOF'
+docs: map existing codebase
+
+- STACK.md - Technologies and dependencies
+- ARCHITECTURE.md - System design and patterns
+- STRUCTURE.md - Directory layout
+- CONVENTIONS.md - Code style and patterns
+- TESTING.md - Test structure
+- INTEGRATIONS.md - External services
+- CONCERNS.md - Technical debt and issues
+EOF
+)"
+```
+
+Continue to offer_next.
+</step>
+
+<step name="offer_next">
+Present completion summary and next steps.
+
+**Output format:**
+
+```
+Codebase mapping complete.
+
+Created .planning/codebase/:
+- STACK.md ([N] lines) - Technologies and dependencies
+- ARCHITECTURE.md ([N] lines) - System design and patterns
+- STRUCTURE.md ([N] lines) - Directory layout and organization
+- CONVENTIONS.md ([N] lines) - Code style and patterns
+- TESTING.md ([N] lines) - Test structure and practices
+- INTEGRATIONS.md ([N] lines) - External services and APIs
+- CONCERNS.md ([N] lines) - Technical debt and issues
+
+
+---
+
+## ▶ Next Up
+
+**Initialize project** — use codebase context for planning
+
+`/gsd:new-project`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Re-run mapping: `/gsd:map-codebase`
+- Review specific file: `cat .planning/codebase/STACK.md`
+- Edit any document before proceeding
+
+---
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- .planning/codebase/ directory created
+- 4 parallel Explore agents spawned with run_in_background=true
+- Agent prompts are specific and actionable
+- TaskOutput used to collect all agent results
+- All 7 codebase documents written using template filling
+- Documents follow template structure with actual findings
+- Clear completion summary with line counts
+- User offered clear next steps in GSD style
+</success_criteria>