get-shit-done-cc 1.2.13 → 1.3.1

package/README.md

@@ -52,14 +52,13 @@ That's what this is. No enterprise roleplay bullshit. Just an incredibly effecti
 
 The system asks questions. Keeps asking until it has everything — your goals, constraints, tech preferences, edge cases. You go back and forth until the idea is fully captured. Creates **PROJECT.md**.
 
-### 2. Research (optional) and create roadmap
+### 2. Create roadmap
 
 ```
-/gsd:research-project   # For niche domains (3D, audio, shaders)
 /gsd:create-roadmap     # Create phases and state tracking
 ```
 
-For complex domains, research spawns subagents to discover ecosystem patterns before planning. Then roadmap creation produces:
+Roadmap creation produces:
 
 - **ROADMAP.md** - Phases from start to finish
 - **STATE.md** - Living memory that persists across sessions
@@ -156,8 +155,8 @@ You're never locked in. The system adapts.
 | Command                           | What it does                                                  |
 | --------------------------------- | ------------------------------------------------------------- |
 | `/gsd:new-project`                | Extract your idea through questions, create PROJECT.md        |
-| `/gsd:research-project`           | Research domain ecosystem before roadmap (optional)           |
 | `/gsd:create-roadmap`             | Create roadmap and state tracking                             |
+| `/gsd:map-codebase`               | Map existing codebase for brownfield projects                 |
 | `/gsd:plan-phase [N]`             | Generate task plans for phase                                 |
 | `/gsd:execute-plan`               | Run plan via subagent                                         |
 | `/gsd:progress`                   | Where am I? What's next?                                      |

package/commands/gsd/create-roadmap.md

@@ -9,11 +9,9 @@ allowed-tools:
 ---
 
 <objective>
-Create project roadmap, optionally incorporating research findings from /gsd:research-project.
+Create project roadmap with phase breakdown.
 
-Roadmaps define the phase breakdown - what work happens in what order. This command can be used:
-1. After /gsd:new-project (without research)
-2. After /gsd:research-project (with domain research incorporated)
+Roadmaps define what work happens in what order. Run after /gsd:new-project.
 </objective>
 
 <execution_context>
@@ -57,46 +55,12 @@ If "Cancel": Exit
 If "Replace": Continue with workflow
 </step>
 
-<step name="check_research">
-Check for project research:
-
-```bash
-ls .planning/research/*.md 2>/dev/null
-```
-
-**If research found:**
-Load and summarize each research file:
-- ecosystem.md → Key libraries/frameworks recommended
-- architecture.md → Architectural patterns to follow
-- pitfalls.md → Top 2-3 critical pitfalls to avoid
-- standards.md → Standards and conventions to follow
-
-Present summary:
-```
-Found project research:
-
-Ecosystem: [key libraries/frameworks]
-Architecture: [key patterns]
-Pitfalls: [top 2-3 to avoid]
-Standards: [key conventions]
-
-This will inform phase structure.
-```
-
-**If no research found:**
-```
-No project research found.
-Creating roadmap based on PROJECT.md alone.
-(Optional: Run /gsd:research-project first for niche/complex domains)
-```
-</step>
-
 <step name="create_roadmap">
 Follow the create-roadmap.md workflow starting from detect_domain step.
 
 The workflow handles:
 - Domain expertise detection
-- Phase identification (informed by research if present)
+- Phase identification
 - Research flags for each phase
 - Confirmation gates (respecting config mode)
 - ROADMAP.md creation
@@ -145,7 +109,6 @@ Roadmap created:
 
 <success_criteria>
 - [ ] PROJECT.md validated
-- [ ] Research incorporated if present
 - [ ] ROADMAP.md created with phases
 - [ ] STATE.md initialized
 - [ ] Phase directories created

package/commands/gsd/help.md

@@ -21,10 +21,9 @@ Output ONLY the reference content below. Do NOT add:
 ## Quick Start
 
 1. `/gsd:new-project` - Initialize project with brief
-2. `/gsd:research-project` - (Optional) Research domain ecosystem
-3. `/gsd:create-roadmap` - Create roadmap and phases
-4. `/gsd:plan-phase <number>` - Create detailed plan for first phase
-5. `/gsd:execute-plan <path>` - Execute the plan
+2. `/gsd:create-roadmap` - Create roadmap and phases
+3. `/gsd:plan-phase <number>` - Create detailed plan for first phase
+4. `/gsd:execute-plan <path>` - Execute the plan
 
 ## Core Workflow
 
@@ -44,26 +43,25 @@ Initialize new project with brief and configuration.
 
 Usage: `/gsd:new-project`
 
-**`/gsd:research-project`**
-Research domain ecosystem before creating roadmap.
-
-- Spawns batched subagents to research domain patterns
-- Creates `.planning/research/` with ecosystem findings
-- Optional step for niche/complex domains
-- Run after new-project, before create-roadmap
-
-Usage: `/gsd:research-project`
-
 **`/gsd:create-roadmap`**
 Create roadmap and state tracking for initialized project.
 
 - Creates `.planning/ROADMAP.md` (phase breakdown)
 - Creates `.planning/STATE.md` (project memory)
 - Creates `.planning/phases/` directories
-- Incorporates research findings if present
 
 Usage: `/gsd:create-roadmap`
 
+**`/gsd:map-codebase`**
+Map an existing codebase for brownfield projects.
+
+- Analyzes codebase with parallel Explore agents
+- Creates `.planning/codebase/` with 7 focused documents
+- Covers stack, architecture, structure, conventions, testing, integrations, concerns
+- Use before `/gsd:new-project` on existing codebases
+
+Usage: `/gsd:map-codebase`
+
 ### Phase Planning
 
 **`/gsd:discuss-phase <number>`**
@@ -229,6 +227,14 @@ Show this command reference.
 ├── STATE.md              # Project memory & context
 ├── ISSUES.md             # Deferred enhancements (created when needed)
 ├── config.json           # Workflow mode & gates
+├── codebase/             # Codebase map (brownfield projects)
+│   ├── 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
 └── phases/
     ├── 01-foundation/
     │   ├── 01-01-PLAN.md
@@ -267,16 +273,6 @@ Change anytime by editing `.planning/config.json`
 /gsd:execute-plan .planning/phases/01-foundation/01-01-PLAN.md
 ```
 
-**Building something in a niche domain (3D, games, audio, shaders):**
-
-```
-/gsd:new-project
-/gsd:research-project  # Research domain ecosystem before roadmap
-/gsd:create-roadmap    # Roadmap incorporates research findings
-/gsd:plan-phase 1
-/gsd:execute-plan .planning/phases/01-foundation/01-01-PLAN.md
-```
-
 **Resuming work after a break:**
 
 ```

package/commands/gsd/map-codebase.md

@@ -0,0 +1,85 @@
+---
+description: Analyze codebase with parallel Explore agents to produce .planning/codebase/ documents
+argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+<objective>
+Analyze existing codebase using parallel Explore agents to produce structured codebase documents.
+
+This command spawns multiple Explore agents to analyze different aspects of the codebase in parallel, each with fresh context. Each agent produces focused documentation under 100 lines.
+
+Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/map-codebase.md
+@~/.claude/get-shit-done/templates/codebase/stack.md
+@~/.claude/get-shit-done/templates/codebase/architecture.md
+@~/.claude/get-shit-done/templates/codebase/structure.md
+@~/.claude/get-shit-done/templates/codebase/conventions.md
+@~/.claude/get-shit-done/templates/codebase/testing.md
+@~/.claude/get-shit-done/templates/codebase/integrations.md
+@~/.claude/get-shit-done/templates/codebase/concerns.md
+</execution_context>
+
+<context>
+Focus area: $ARGUMENTS (optional - if provided, tells agents to focus on specific subsystem)
+
+**Load project state if exists:**
+Check for .planning/STATE.md - loads context if project already initialized
+
+**This command can run:**
+- Before /gsd:new-project (brownfield codebases) - creates codebase map first
+- After /gsd:new-project (greenfield codebases) - updates codebase map as code evolves
+- Anytime to refresh codebase understanding
+</context>
+
+<when_to_use>
+**Use map-codebase for:**
+- Brownfield projects before initialization (understand existing code first)
+- Refreshing codebase map after significant changes
+- Onboarding to an unfamiliar codebase
+- Before major refactoring (understand current state)
+- When STATE.md references outdated codebase info
+
+**Skip map-codebase for:**
+- Greenfield projects with no code yet (nothing to map)
+- Trivial codebases (<5 files)
+</when_to_use>
+
+<process>
+1. Check if .planning/codebase/ already exists (offer to refresh or skip)
+2. Create .planning/codebase/ directory structure
+3. Spawn 4 parallel Explore agents to analyze codebase:
+   - Agent 1: Stack + Integrations (technology focus)
+   - Agent 2: Architecture + Structure (organization focus)
+   - Agent 3: Conventions + Testing (quality focus)
+   - Agent 4: Concerns (issues focus)
+4. Wait for all agents to complete, collect findings
+5. Write 7 codebase documents using templates:
+   - STACK.md - Languages, frameworks, key dependencies
+   - ARCHITECTURE.md - System design, patterns, data flow
+   - STRUCTURE.md - Directory layout, module organization
+   - CONVENTIONS.md - Code style, naming, patterns
+   - TESTING.md - Test structure, coverage, practices
+   - INTEGRATIONS.md - APIs, databases, external services
+   - CONCERNS.md - Technical debt, risks, issues
+6. Verify each document is under 100 lines (summarize if needed)
+7. Offer next steps (typically: /gsd:new-project or /gsd:plan-phase)
+</process>
+
+<success_criteria>
+- [ ] .planning/codebase/ directory created
+- [ ] All 7 codebase documents written
+- [ ] Each document under 100 lines
+- [ ] Documents follow template structure
+- [ ] Parallel agents completed without errors
+- [ ] User knows next steps
+</success_criteria>

package/commands/gsd/new-project.md

@@ -44,7 +44,40 @@ Creates `.planning/` with PROJECT.md and config.json.
    fi
    ```
 
-   **You MUST run both bash commands above using the Bash tool before proceeding.**
+3. **Detect existing code (brownfield detection):**
+   ```bash
+   # Check for existing code files
+   CODE_FILES=$(find . -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.swift" -o -name "*.java" 2>/dev/null | grep -v node_modules | grep -v .git | head -20)
+   HAS_PACKAGE=$([ -f package.json ] || [ -f requirements.txt ] || [ -f Cargo.toml ] || [ -f go.mod ] || [ -f Package.swift ] && echo "yes")
+   HAS_CODEBASE_MAP=$([ -d .planning/codebase ] && echo "yes")
+   ```
+
+   **You MUST run all bash commands above using the Bash tool before proceeding.**
+</step>
+
+<step name="brownfield_offer">
+**If existing code detected and .planning/codebase/ doesn't exist:**
+
+Check the results from setup step:
+- If `CODE_FILES` is non-empty OR `HAS_PACKAGE` is "yes"
+- AND `HAS_CODEBASE_MAP` is NOT "yes"
+
+Use AskUserQuestion:
+- header: "Existing Code"
+- question: "I detected existing code in this directory. Would you like to map the codebase first?"
+- options:
+  - "Map codebase first" - Run /gsd:map-codebase to understand existing architecture (Recommended)
+  - "Skip mapping" - Proceed with project initialization
+
+**If "Map codebase first":**
+```
+Run `/gsd:map-codebase` first, then return to `/gsd:new-project`
+```
+Exit command.
+
+**If "Skip mapping":** Continue to question step.
+
+**If no existing code detected OR codebase already mapped:** Continue to question step.
 </step>
 
 <step name="question">
@@ -140,19 +173,14 @@ Project initialized:
 
 - Project: .planning/PROJECT.md
 - Config: .planning/config.json (mode: [chosen mode])
+[If .planning/codebase/ exists:] - Codebase: .planning/codebase/ (7 documents)
 
 ---
 
 ## ▶ Next Up
 
-**[Project Name]** — research domain or create roadmap
-
-**Research first (recommended for niche/complex domains):**
-```
-/gsd:research-project
-```
+**[Project Name]** — create roadmap
 
-**Create roadmap directly:**
 ```
 /gsd:create-roadmap
 ```

package/commands/gsd/plan-phase.md

@@ -39,6 +39,9 @@ Phase number: $ARGUMENTS (optional - auto-detects next unplanned phase if not pr
 
 **Load phase context if exists (created by /gsd:discuss-phase):**
 Check for and read `.planning/phases/XX-name/{phase}-CONTEXT.md` - contains research findings, clarifications, and decisions from phase discussion.
+
+**Load codebase context if exists:**
+Check for `.planning/codebase/` and load relevant documents based on phase type.
 </context>
 
 <process>

package/get-shit-done/templates/codebase/architecture.md

@@ -0,0 +1,249 @@
+# Architecture Template
+
+Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code organization.
+
+**Purpose:** Document how the code is organized at a conceptual level. Complements STRUCTURE.md (which shows physical file locations).
+
+---
+
+## File Template
+
+```markdown
+# Architecture
+
+**Analysis Date:** [YYYY-MM-DD]
+
+## Pattern Overview
+
+**Overall:** [Pattern name: e.g., "Monolithic CLI", "Serverless API", "Full-stack MVC"]
+
+**Key Characteristics:**
+- [Characteristic 1: e.g., "Single executable"]
+- [Characteristic 2: e.g., "Stateless request handling"]
+- [Characteristic 3: e.g., "Event-driven"]
+
+## Layers
+
+[Describe the conceptual layers and their responsibilities]
+
+**[Layer Name]:**
+- Purpose: [What this layer does]
+- Contains: [Types of code: e.g., "route handlers", "business logic"]
+- Depends on: [What it uses: e.g., "data layer only"]
+- Used by: [What uses it: e.g., "API routes"]
+
+**[Layer Name]:**
+- Purpose: [What this layer does]
+- Contains: [Types of code]
+- Depends on: [What it uses]
+- Used by: [What uses it]
+
+## Data Flow
+
+[Describe the typical request/execution lifecycle]
+
+**[Flow Name] (e.g., "HTTP Request", "CLI Command", "Event Processing"):**
+
+1. [Entry point: e.g., "User runs command"]
+2. [Processing step: e.g., "Router matches path"]
+3. [Processing step: e.g., "Controller validates input"]
+4. [Processing step: e.g., "Service executes logic"]
+5. [Output: e.g., "Response returned"]
+
+**State Management:**
+- [How state is handled: e.g., "Stateless - no persistent state", "Database per request", "In-memory cache"]
+
+## Key Abstractions
+
+[Core concepts/patterns used throughout the codebase]
+
+**[Abstraction Name]:**
+- Purpose: [What it represents]
+- Examples: [e.g., "UserService, ProjectService"]
+- Pattern: [e.g., "Singleton", "Factory", "Repository"]
+
+**[Abstraction Name]:**
+- Purpose: [What it represents]
+- Examples: [Concrete examples]
+- Pattern: [Pattern used]
+
+## Entry Points
+
+[Where execution begins]
+
+**[Entry Point]:**
+- Location: [Brief: e.g., "src/index.ts", "API Gateway triggers"]
+- Triggers: [What invokes it: e.g., "CLI invocation", "HTTP request"]
+- Responsibilities: [What it does: e.g., "Parse args, route to command"]
+
+## Error Handling
+
+**Strategy:** [How errors are handled: e.g., "Exception bubbling to top-level handler", "Per-route error middleware"]
+
+**Patterns:**
+- [Pattern: e.g., "try/catch at controller level"]
+- [Pattern: e.g., "Error codes returned to user"]
+
+## Cross-Cutting Concerns
+
+[Aspects that affect multiple layers]
+
+**Logging:**
+- [Approach: e.g., "Winston logger, injected per-request"]
+
+**Validation:**
+- [Approach: e.g., "Zod schemas at API boundary"]
+
+**Authentication:**
+- [Approach: e.g., "JWT middleware on protected routes"]
+
+---
+
+*Architecture analysis: [date]*
+*Update when major patterns change*
+```
+
+<good_examples>
+```markdown
+# Architecture
+
+**Analysis Date:** 2025-01-20
+
+## Pattern Overview
+
+**Overall:** CLI Application with Plugin System
+
+**Key Characteristics:**
+- Single executable with subcommands
+- Plugin-based extensibility
+- File-based state (no database)
+- Synchronous execution model
+
+## Layers
+
+**Command Layer:**
+- Purpose: Parse user input and route to appropriate handler
+- Contains: Command definitions, argument parsing, help text
+- Depends on: Service layer for business logic
+- Used by: CLI entry point (src/index.ts)
+
+**Service Layer:**
+- Purpose: Core business logic
+- Contains: FileService, TemplateService, InstallService
+- Depends on: File system utilities, external tools
+- Used by: Command handlers
+
+**Utility Layer:**
+- Purpose: Shared helpers and abstractions
+- Contains: File I/O wrappers, path resolution, string formatting
+- Depends on: Node.js built-ins only
+- Used by: Service layer
+
+## Data Flow
+
+**CLI Command Execution:**
+
+1. User runs: `gsd new-project`
+2. Commander parses args and flags
+3. Command handler invoked (commands/new-project.ts)
+4. Handler calls service methods (e.g., ProjectService.create())
+5. Service reads templates, processes files, writes output
+6. Results logged to console
+7. Process exits with status code
+
+**State Management:**
+- File-based: All state lives in `.planning/` directory
+- No persistent in-memory state
+- Each command execution is independent
+
+## Key Abstractions
+
+**Service:**
+- Purpose: Encapsulate business logic for a domain
+- Examples: FileService, TemplateService, ProjectService
+- Pattern: Singleton-like (imported as modules, not instantiated)
+
+**Command:**
+- Purpose: CLI command definition
+- Examples: new-project, plan-phase, execute-plan
+- Pattern: Commander.js command registration
+
+**Template:**
+- Purpose: Reusable document structures
+- Examples: PROJECT.md, PLAN.md templates
+- Pattern: Markdown files with substitution variables
+
+## Entry Points
+
+**CLI Entry:**
+- Location: src/index.ts
+- Triggers: User runs `gsd <command>`
+- Responsibilities: Register commands, parse args, display help
+
+**Commands:**
+- Location: src/commands/*.ts
+- Triggers: Matched command from CLI
+- Responsibilities: Validate input, call services, format output
+
+## Error Handling
+
+**Strategy:** Throw exceptions, catch at command level, log and exit
+
+**Patterns:**
+- Services throw Error with descriptive messages
+- Command handlers catch, log error to stderr, exit(1)
+- Validation errors shown before execution (fail fast)
+
+## Cross-Cutting Concerns
+
+**Logging:**
+- Console.log for normal output
+- Console.error for errors
+- Chalk for colored output
+
+**Validation:**
+- Zod schemas for config file parsing
+- Manual validation in command handlers
+- Fail fast on invalid input
+
+**File Operations:**
+- FileService abstraction over fs-extra
+- All paths validated before operations
+- Atomic writes (temp file + rename)
+
+---
+
+*Architecture analysis: 2025-01-20*
+*Update when major patterns change*
+```
+</good_examples>
+
+<guidelines>
+**What belongs in ARCHITECTURE.md:**
+- Overall architectural pattern (monolith, microservices, layered, etc.)
+- Conceptual layers and their relationships
+- Data flow / request lifecycle
+- Key abstractions and patterns
+- Entry points
+- Error handling strategy
+- Cross-cutting concerns (logging, auth, validation)
+
+**What does NOT belong here:**
+- Specific file paths (that's STRUCTURE.md)
+- Technology choices (that's STACK.md)
+- Line-by-line code walkthrough (defer to code reading)
+- Implementation details of specific features
+
+**When filling this template:**
+- Read main entry points (index, server, main)
+- Identify layers by reading imports/dependencies
+- Trace a typical request/command execution
+- Note recurring patterns (services, controllers, repositories)
+- Keep descriptions conceptual, not mechanical
+
+**Useful for phase planning when:**
+- Adding new features (where does it fit in the layers?)
+- Refactoring (understanding current patterns)
+- Identifying where to add code (which layer handles X?)
+- Understanding dependencies between components
+</guidelines>