get-shit-done-cc 1.2.13 → 1.3.0

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

@@ -0,0 +1,397 @@
+<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 (under 100 lines per document) 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)
+
+**Why 100-line limit:**
+Codebase maps are reference material loaded frequently. Concise summaries are more useful than exhaustive inventories. If codebase is large, summarize patterns rather than listing every file.
+</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.
+
+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
+
+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.
+
+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
+
+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.
+
+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
+
+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.
+
+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
+
+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)
+
+**Line count check:**
+
+Before writing, estimate total lines for each document. If any will exceed 100 lines:
+- Summarize patterns instead of listing all instances
+- Prioritize most important/frequent patterns
+- Reference "see code for full details" for exhaustive lists
+
+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 `~/.claude/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. **Verify line count** - if filled template exceeds 100 lines, summarize:
+   - Keep most critical findings
+   - Summarize patterns instead of exhaustive lists
+   - Add "(see code for full details)" where appropriate
+5. **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
+- Each document under 100 lines
+- No empty documents
+- Templates populated with findings
+
+If any checks fail, report issues to user.
+
+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
+
+[If any files >100 lines, add warning: "⚠ Some files exceed 100 lines - consider summarizing further"]
+
+---
+
+## ▶ 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
+- Each document under 100 lines (or warning shown)
+- Documents follow template structure with actual findings
+- Clear completion summary with line counts
+- User offered clear next steps in GSD style
+</success_criteria>

package/get-shit-done/workflows/plan-phase.md

@@ -96,6 +96,44 @@ Options:
 This ensures planning has full project context.
 </step>
 
+<step name="load_codebase_context">
+Check if codebase map exists:
+
+```bash
+ls .planning/codebase/*.md 2>/dev/null
+```
+
+**If .planning/codebase/ exists:**
+
+Determine which codebase documents are relevant based on phase goal:
+
+| Phase Keywords | Load These Documents |
+|----------------|---------------------|
+| UI, frontend, components, layout | CONVENTIONS.md, STRUCTURE.md |
+| API, backend, endpoints, routes | ARCHITECTURE.md, CONVENTIONS.md |
+| database, schema, models, migration | ARCHITECTURE.md, STACK.md |
+| testing, tests, coverage | TESTING.md, CONVENTIONS.md |
+| integration, external, API, service | INTEGRATIONS.md, STACK.md |
+| refactor, cleanup, debt | CONCERNS.md, ARCHITECTURE.md |
+| setup, config, infrastructure | STACK.md, STRUCTURE.md |
+| (default - load minimal set) | STACK.md, ARCHITECTURE.md |
+
+Read the relevant documents and summarize key constraints for this phase:
+- From STACK.md: Technologies that must be used
+- From ARCHITECTURE.md: Patterns that must be followed
+- From CONVENTIONS.md: Code style requirements
+- From CONCERNS.md: Issues to avoid or address
+
+**Add to planning context:**
+Track codebase constraints for inclusion in PLAN.md context section:
+- Which documents loaded
+- Key constraints extracted
+- Patterns to follow
+
+**If .planning/codebase/ doesn't exist:**
+Skip this step - no codebase map available.
+</step>
+
 <step name="identify_phase">
 Check roadmap for phases:
 ```bash
@@ -651,6 +689,16 @@ Output: [What artifacts will be created by this plan]
 @.planning/ROADMAP.md
 @.planning/STATE.md
 
+[If codebase map exists (from /gsd:map-codebase):]
+@.planning/codebase/STACK.md
+@.planning/codebase/ARCHITECTURE.md
+[Add other relevant docs based on phase type - see load_codebase_context step]
+
+**Codebase constraints:**
+- [Extracted constraints from codebase documents]
+- [Technologies that must be used]
+- [Patterns that must be followed]
+
 [If comprehensive ecosystem research exists (from /gsd:research-phase):]
 @.planning/phases/XX-name/{phase}-RESEARCH.md
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-shit-done-cc",
-  "version": "1.2.13",
+  "version": "1.3.0",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "get-shit-done-cc": "bin/install.js"

package/commands/gsd/research-project.md

@@ -1,195 +0,0 @@
----
-description: Research domain ecosystem before creating roadmap
-allowed-tools:
-  - Task
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-
-<objective>
-Research implementation context for Claude Code before roadmap creation.
-
-This is NOT research for human decision-making. This is context injection so Claude Code can implement correctly with current APIs, patterns, and best practices.
-
-Spawns 2-3 subagents in parallel to research PROJECT.md-specific needs:
-
-- **Stack** - What libraries/tools to use for THIS project's features
-- **Implementation** - Current API patterns, code examples, correct syntax
-- **Risks** - What Claude might get wrong, deprecated patterns to avoid
-
-Each subagent writes directly to `.planning/research/` preserving main context.
-</objective>
-
-<execution_context>
-@~/.claude/get-shit-done/workflows/research-project.md
-@~/.claude/get-shit-done/templates/project-research.md
-@~/.claude/get-shit-done/references/research-subagent-prompts.md
-</execution_context>
-
-<context>
-@.planning/PROJECT.md
-</context>
-
-<process>
-
-<step name="validate">
-Check prerequisites:
-
-```bash
-# Verify .planning/ exists
-[ -d .planning ] || { echo "No .planning/ directory. Run /gsd:new-project first."; exit 1; }
-
-# Verify PROJECT.md exists
-[ -f .planning/PROJECT.md ] || { echo "No PROJECT.md. Run /gsd:new-project first."; exit 1; }
-
-# Check for existing research
-[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"
-```
-
-If RESEARCH_EXISTS:
-
-```
-Research already exists at .planning/research/
-
-What would you like to do?
-1. View existing research
-2. Re-run research (overwrites existing)
-3. Skip to create-roadmap
-```
-
-Wait for user decision.
-</step>
-
-<step name="parse_project">
-Read PROJECT.md and extract research targets:
-
-**From Scope (Building):**
-- List each feature/capability that needs implementation
-- These become specific research queries
-
-**From Constraints:**
-- Tech stack requirements (language, framework, platform)
-- Performance requirements
-- Compatibility requirements
-
-**From Open Questions:**
-- Questions that research should answer
-- These are explicit research targets
-
-**From Decisions Made:**
-- Choices to validate ("any gotchas with X?")
-
-Create a research manifest:
-```
-Features to implement:
-- [feature 1]
-- [feature 2]
-- [feature 3]
-
-Stack constraints:
-- [constraint 1]
-- [constraint 2]
-
-Open questions to answer:
-- [question 1]
-- [question 2]
-
-Decisions to validate:
-- [decision 1]
-```
-
-If PROJECT.md is too vague for specific research targets, use AskUserQuestion:
-- header: "Research scope"
-- question: "What specific implementation questions should we research?"
-- options based on detected domain
-</step>
-
-<step name="research">
-Follow research-project.md workflow with PROJECT.md-driven research:
-
-1. Create `.planning/research/` directory
-2. Spawn subagents in parallel (all at once if ≤3):
-   - **stack.md** - Libraries/tools for each feature in Scope
-   - **implementation.md** - Current API patterns and code examples
-   - **risks.md** - What Claude might get wrong, deprecated patterns
-3. Wait for completion
-4. Verify all outputs exist and are high-quality
-</step>
-
-<step name="verify_quality">
-After subagents complete, verify quality:
-
-```bash
-# Check files exist
-for f in stack implementation risks; do
-  [ -s ".planning/research/${f}.md" ] && echo "✓ ${f}.md" || echo "✗ ${f}.md MISSING"
-done
-```
-
-**Quality check (read each file):**
-- Contains ONLY high-confidence information?
-- Includes actual code examples with current syntax?
-- Addresses specific features from PROJECT.md?
-- No low-confidence padding or "might be useful" items?
-
-If a file contains low-quality content, note it for summary.
-</step>
-
-<step name="summarize">
-After verification:
-
-```
-Research complete:
-- .planning/research/stack.md - [libraries/tools identified]
-- .planning/research/implementation.md - [patterns documented]
-- .planning/research/risks.md - [pitfalls to avoid]
-
-Key implementation context:
-- [Primary stack choice with rationale]
-- [Most important API pattern to use]
-- [Critical mistake Claude should avoid]
-
-Open questions remaining:
-- [Any questions research couldn't answer]
-
----
-
-## ▶ Next Up
-
-**Create Roadmap** — define phases based on research findings
-
-```
-/gsd:create-roadmap
-```
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- Review research files before continuing
-
----
-```
-</step>
-
-</process>
-
-<output>
-- `.planning/research/stack.md` - Libraries and tools for each feature
-- `.planning/research/implementation.md` - Current API patterns and code examples
-- `.planning/research/risks.md` - Deprecated patterns and common mistakes
-</output>
-
-<success_criteria>
-- [ ] PROJECT.md parsed for specific research targets
-- [ ] Research addresses actual features from Scope
-- [ ] Open Questions from PROJECT.md answered (or noted as unanswerable)
-- [ ] All outputs are HIGH-CONFIDENCE only (no padding)
-- [ ] Code examples use current API syntax
-- [ ] User knows next steps (create-roadmap)
-</success_criteria>