golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

chore: stop tracking .planning/ (already gitignored)

Browse Source 
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2026-01-19 23:43:55 -06:00
parent cffb3f24cd
commit d0db04f32f
10 changed files with 0 additions and 947 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
.planning/MILESTONES.md
View File

@@ -1,28 +0,0 @@
# Project Milestones: GSD
## v1.8.0 Quick Mode (Shipped: 2026-01-19)
**Delivered:** Fast-path command (`/gsd:quick`) for executing small tasks with full GSD guarantees but 50-70% fewer tokens.
**Phases completed:** 1-2 (3 plans total)
**Key accomplishments:**
- Created `/gsd:quick` command with interactive prompting and directory setup
- Implemented gsd-planner and gsd-executor spawning for quick mode
- Added STATE.md Quick Tasks Completed table integration
- Documented quick mode in help.md, README.md, and GSD-STYLE.md
- Established quick task directory structure (`.planning/quick/NNN-slug/`)
**Stats:**
- 34 files created/modified
- +1,129/-379 lines
- 2 phases, 3 plans, 2 quick tasks
- Same-day completion (2026-01-19)
**Git range:** `2b36394` → `7692ebd` (1.8.0)
**What's next:** Codebase Intelligence System
---

68
.planning/PROJECT.md
View File

@@ -1,68 +0,0 @@
# GSD Codebase Intelligence
## What This Is
A living codebase knowledge system for GSD that learns project structure and conventions as code is written, injecting accumulated understanding into every Claude session. Enables Claude to "just know" the codebase without manual documentation or stale snapshots.
## Core Value
Claude understands your codebase structure and conventions before it starts working — automatically.
## Current Milestone: v1.9.0 Codebase Intelligence System
**Goal:** Make GSD feel intelligent and automagical in how it navigates and understands both greenfield and brownfield projects.
**Target features:**
- Automatic codebase indexing via hooks (greenfield learns as you build)
- Deep analysis command for brownfield projects
- Session-start context injection with codebase awareness
- Convention detection and pattern learning
## Requirements
### Validated
- ✓ `/gsd:quick "description"` command executes end-to-end — v1.8.0
- ✓ Spawns gsd-planner (unchanged, just skips researcher/checker) — v1.8.0
- ✓ Spawns gsd-executor for each plan — v1.8.0
- ✓ Commits only files it edits/creates (not entire working dir) — v1.8.0
- ✓ Updates STATE.md with "Quick Tasks Completed" table — v1.8.0
- ✓ Updates STATE.md "Last activity" line — v1.8.0
- ✓ Errors if no ROADMAP.md exists — v1.8.0
- ✓ help.md updated with quick command — v1.8.0
- ✓ README.md updated with quick mode section — v1.8.0
- ✓ GSD-STYLE.md updated with quick mode patterns — v1.8.0
### Active
*Defined in REQUIREMENTS.md*
### Out of Scope
- `/gsd:resume-work` decimal phase handling — deferred from v1.8.0
- Semantic embeddings / vector search — future milestone
- Cross-project convention sharing — future milestone
- Framework auto-detection — future milestone
## Context
GSD's document ecosystem (PROJECT.md, ROADMAP.md, STATE.md, PLAN.md) tracks planning intent and execution outcomes. The Codebase Intelligence System adds a parallel code layer that tracks what actually exists in the codebase — files, exports, naming patterns, directory structure.
## Constraints
- **Zero API calls** for core functionality (local computation only)
- **Hook-based** integration using Claude Code's native infrastructure
- **Advisory only** — never block Claude's workflow
- **Lightweight** — minimal storage, fast operations
## Key Decisions
| Decision | Rationale | Outcome |
|----------|-----------|---------|
| No planner changes | Quick mode is orchestrator-level, not agent-level | ✓ Good |
| No decimal phases | Quick tasks don't need ROADMAP integration | ✓ Good — simpler |
| Quick Tasks table in STATE.md | Better tracking than just Last activity | ✓ Good |
| Error if no ROADMAP | Maintains state integrity, no standalone mode | ✓ Good |
---
*Last updated: 2026-01-19 — starting v1.9.0 milestone*

65
.planning/STATE.md
View File

@@ -1,65 +0,0 @@
# Project State
## Project Reference
See: .planning/PROJECT.md (updated 2026-01-19)
**Core value:** Claude understands your codebase structure and conventions before it starts working — automatically
**Current focus:** v1.9.0 Codebase Intelligence System
## Current Position
Phase: 2 of 3 (Context Injection)
Plan: 1 of 2 complete
Status: In progress
Last activity: 2026-01-20 — Completed 02-01-PLAN.md (Convention Detection Engine)
Progress: [████░░░░░░] 43%
## Performance Metrics
**Velocity:**
- Total plans completed: 3
- Average duration: 3.0 min
- Total execution time: 9 min
**By Phase:**
| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| 1. Foundation & Learning | 2/2 | 7 min | 3.5 min |
| 2. Context Injection | 1/2 | 2 min | 2.0 min |
| 3. Brownfield & Integration | 0/3 | - | - |
*Updated after each plan completion*
## Accumulated Context
### Decisions
| Decision | Phase | Rationale |
|----------|-------|-----------|
| index.json keyed by absolute path | 01-01 | O(1) lookup for file entries |
| JSON schema with version field | 01-01 | Enables future schema migrations |
| updated=null for initialization | 01-01 | Distinguishes init from update |
| Use heredoc for stdin testing | 01-02 | Pipe chaining has timing issues with async stdin |
| Extract 'default' as export name | 01-02 | Both 'default' and identifier recorded for default exports |
| Read file from disk for Edit tool | 01-02 | Edit only provides old_string/new_string, not full content |
| Regenerate conventions every index update | 02-01 | Detection is fast, avoids staleness issues |
| Skip 'default' in case detection | 02-01 | Keyword, not naming convention indicator |
| Single lowercase words as camelCase | 02-01 | Follows camelCase rules (e.g., 'main', 'app') |
| Use lookup tables for purposes | 02-01 | More maintainable than regex patterns |
### Pending Todos
- `/gsd:resume-work` decimal phase handling (deferred from v1.8.0)
### Blockers/Concerns
- `.planning/` is gitignored in GSD repo - intel files created but not committed (expected for project-local data)
## Session Continuity
Last session: 2026-01-20
Stopped at: Completed 02-01-PLAN.md, ready for 02-02-PLAN.md
Resume file: None

5
.planning/config.json
View File

@@ -1,5 +0,0 @@
{
"mode": "yolo",
"depth": "quick",
"parallelization": true
}

104
.planning/milestones/v1.8.0-REQUIREMENTS.md
View File

@@ -1,104 +0,0 @@
# Requirements Archive: v1.8.0 Quick Mode
**Archived:** 2026-01-19
**Status:** ✅ SHIPPED
This is the archived requirements specification for v1.8.0.
For current requirements, see `.planning/REQUIREMENTS.md` (created for next milestone).
---
# Requirements: GSD Quick Mode
**Defined:** 2025-01-19
**Core Value:** Same guarantees, 50-70% fewer tokens for simple tasks
## v1 Requirements
### Command
- [x] **CMD-01**: `/gsd:quick "description"` parses description from arguments
- [x] **CMD-02**: Command errors if .planning/ROADMAP.md doesn't exist
- [x] **CMD-03**: Command calculates next decimal phase from current phase in STATE.md
- [x] **CMD-04**: Command creates phase directory `.planning/phases/{decimal}-{slug}/`
- [x] **CMD-05**: Command inserts decimal phase entry in ROADMAP.md
### Execution
- [x] **EXEC-01**: Command spawns gsd-planner (no researcher, no checker)
- [x] **EXEC-02**: Command spawns gsd-executor for each plan created
- [x] **EXEC-03**: Multiple plans execute in parallel waves (same as execute-phase)
- [x] **EXEC-04**: Executor commits only files it edits/creates
### State
- [x] **STATE-01**: STATE.md "Last activity" updated after completion
- [x] **STATE-02**: STATE.md "Quick Tasks Completed" table created/updated
- [x] **STATE-03**: ROADMAP.md decimal phase marked complete with date
### Resume
- [ ] **RESUME-01**: `/gsd:resume-work` parses decimal phase numbers (3.1, 3.2) — DEFERRED
- [ ] **RESUME-02**: `/gsd:resume-work` finds decimal phase directories — DEFERRED
### Docs
- [x] **DOCS-01**: help.md lists `/gsd:quick` command
- [x] **DOCS-02**: README.md includes quick mode section
- [x] **DOCS-03**: GSD-STYLE.md documents quick mode patterns
## v2 Requirements
(None identified)
## Out of Scope
| Feature | Reason |
|---------|--------|
| `--plan-only` flag | MVP always executes |
| `--after N` flag | Always uses current phase |
| `--standalone` flag | Requires active project for state integrity |
| Node.js helper scripts | Claude handles decimal parsing inline |
| Git status warnings | Commits only its own files |
| Planner modifications | Orchestrator skips agents, planner unchanged |
| gsd-verifier | Verification skipped by design |
| Requirements mapping | Quick tasks are ad-hoc |
| `/gsd:squash-quick` | Future enhancement |
## Traceability
| Requirement | Phase | Status |
|-------------|-------|--------|
| CMD-01 | Phase 1 | Complete |
| CMD-02 | Phase 1 | Complete |
| CMD-03 | Phase 1 | Complete |
| CMD-04 | Phase 1 | Complete |
| CMD-05 | Phase 1 | Complete |
| EXEC-01 | Phase 1 | Complete |
| EXEC-02 | Phase 1 | Complete |
| EXEC-03 | Phase 1 | Complete |
| EXEC-04 | Phase 1 | Complete |
| STATE-01 | Phase 1 | Complete |
| STATE-02 | Phase 1 | Complete |
| STATE-03 | Phase 1 | Complete |
| RESUME-01 | — | Deferred |
| RESUME-02 | — | Deferred |
| DOCS-01 | Phase 2 | Complete |
| DOCS-02 | Phase 2 | Complete |
| DOCS-03 | Phase 2 | Complete |
**Coverage:**
- v1 requirements: 17 total
- Shipped: 15
- Deferred: 2 (RESUME-01, RESUME-02)
---
## Milestone Summary
**Shipped:** 15 of 17 v1 requirements
**Adjusted:** CMD-03, CMD-04, CMD-05, STATE-03 — Design changed from decimal phases in ROADMAP.md to separate `.planning/quick/` directory structure
**Dropped:** None
---
*Archived: 2026-01-19 as part of v1.8.0 milestone completion*

69
.planning/milestones/v1.8.0-ROADMAP.md
View File

@@ -1,69 +0,0 @@
# Milestone v1.8.0: Quick Mode
**Status:** ✅ SHIPPED 2026-01-19
**Phases:** 1-2
**Total Plans:** 3
## Overview
Quick mode adds a fast-path command (`/gsd:quick`) that executes small tasks with full GSD guarantees (atomic commits, STATE.md tracking) but skips optional verification agents. Quick tasks live in `.planning/quick/` separate from planned phases.
## Phases
### Phase 1: Core Command
**Goal**: User can run `/gsd:quick` and have it execute with full state tracking
**Depends on**: Nothing (first phase)
**Plans**: 2 plans
Plans:
- [x] 01-01: Quick command file with pre-flight validation and directory setup
- [x] 01-02: Quick orchestration (planner spawn, executor spawn, state update)
**Details:**
- Created `/gsd:quick` command file with proper frontmatter
- Implemented ROADMAP.md validation with clear error messaging
- Added interactive description prompt using AskUserQuestion
- Implemented slug generation and sequential numbering for quick task directories
- Implemented gsd-planner spawn with quick mode context
- Implemented gsd-executor spawn with no-ROADMAP constraint
- Added STATE.md Quick Tasks Completed table creation/update logic
- Added final commit pattern and GSD-style completion output
### Phase 2: Documentation
**Goal**: Quick mode is documented in all relevant locations
**Depends on**: Phase 1
**Plans**: 1 plan
Plans:
- [x] 02-01: Document /gsd:quick in help.md, README.md, and GSD-STYLE.md
**Details:**
- help.md Quick Mode section with command usage, purpose, and output files
- README.md Quick Mode section in How It Works plus Utilities table entry
- GSD-STYLE.md Quick Mode Patterns section with when-to-use, structure, tracking, orchestration, and commit conventions
---
## Milestone Summary
**Key Decisions:**
- No planner changes — Quick mode is orchestrator-level, not agent-level
- No decimal phases — Quick tasks don't need ROADMAP integration
- No flags for MVP — Simplest possible interface
- Quick Tasks table in STATE.md — Better tracking than just Last activity
- Orchestration inline in command — No separate workflow needed
**Issues Resolved:**
- Token efficiency for simple tasks (50-70% reduction)
**Issues Deferred:**
- `/gsd:resume-work` decimal phase handling (deferred to future)
- `/gsd:squash-quick` for consolidating fragmented quick tasks
**Technical Debt Incurred:**
- None significant
---
*For current project status, see .planning/ROADMAP.md*

106
.planning/milestones/v1.9.0-REQUIREMENTS.md
View File

@@ -1,106 +0,0 @@
# Requirements: v1.9.0 Codebase Intelligence System
## v1 Requirements
### Indexing (INDEX)
- [x] **INDEX-01**: PostToolUse hook indexes files after Write/Edit operations
- [x] **INDEX-02**: Index tracks file paths, exports, and imports
- [x] **INDEX-03**: Index stored in `.planning/intel/index.json`
- [x] **INDEX-04**: Hook fails silently on any error (never blocks Claude)
- [x] **INDEX-05**: Index updates incrementally (add/modify, not full rebuild)
### Context Injection (CTX)
- [ ] **CTX-01**: SessionStart hook injects codebase summary into Claude's context
- [ ] **CTX-02**: Summary includes detected conventions (naming, directory patterns)
- [ ] **CTX-03**: Summary includes directory structure overview
- [ ] **CTX-04**: Summary includes key exports by category (classes, functions, consts)
- [ ] **CTX-05**: Summary wrapped in `<codebase-intelligence>` tags
### Convention Detection (CONV)
- [ ] **CONV-01**: Detect naming patterns (PascalCase, camelCase, kebab-case, snake_case)
- [ ] **CONV-02**: Detect suffix patterns (*.service.ts, *.controller.ts, *.test.ts)
- [ ] **CONV-03**: Detect directory purpose patterns (src/services/, src/components/)
- [ ] **CONV-04**: Confidence threshold: 5+ files required before pattern is detected
- [ ] **CONV-05**: Confidence threshold: 70%+ match rate required
- [x] **CONV-06**: Conventions stored in `.planning/intel/conventions.json`
### Brownfield Analysis (BROWN)
- [ ] **BROWN-01**: `/gsd:analyze-codebase` command scans existing codebase
- [ ] **BROWN-02**: Command works without `/gsd:new-project` (standalone)
- [ ] **BROWN-03**: Creates `.planning/intel/` directory structure
- [ ] **BROWN-04**: Populates index.json with full codebase analysis
- [ ] **BROWN-05**: Generates conventions.json from detected patterns
- [ ] **BROWN-06**: Hooks continue incremental learning after initial analysis
### GSD Integration (INT)
- [ ] **INT-01**: `install.js` registers intel hooks in settings.json
- [ ] **INT-02**: `/gsd:new-project` creates `.planning/intel/` structure
- [ ] **INT-03**: Subagent prompts (planner, executor) include codebase context
- [ ] **INT-04**: Summary regenerated when conventions change
### Documentation (DOC)
- [ ] **DOC-01**: README.md updated with codebase intelligence section
- [ ] **DOC-02**: help.md updated with `/gsd:analyze-codebase` command
- [ ] **DOC-03**: GSD-STYLE.md updated with intel patterns
## v2 Requirements (Deferred)
- PreToolUse convention advisory hook (warn before Write if pattern mismatch)
- `/gsd:intel-correct` command for manual convention corrections
- Exception tracking (intentional deviations from conventions)
- Confidence adjustment based on exceptions
- `/gsd:resume-work` decimal phase handling (from v1.8.0)
## Out of Scope
| Exclusion | Reason |
|-----------|--------|
| Semantic embeddings / vector search | Requires API calls, violates zero-API constraint |
| Cross-project convention sharing | Future milestone scope |
| Framework auto-detection | Future milestone scope |
| IDE-like navigation features | Not GSD's domain |
| Native dependencies (tree-sitter) | Breaks installation simplicity |
| Blocking hooks (reject writes) | Advisory-only principle |
## Traceability
| Requirement | Phase | Status |
|-------------|-------|--------|
| INDEX-01 | Phase 1 | Complete |
| INDEX-02 | Phase 1 | Complete |
| INDEX-03 | Phase 1 | Complete |
| INDEX-04 | Phase 1 | Complete |
| INDEX-05 | Phase 1 | Complete |
| CTX-01 | Phase 2 | Pending |
| CTX-02 | Phase 2 | Pending |
| CTX-03 | Phase 2 | Pending |
| CTX-04 | Phase 2 | Pending |
| CTX-05 | Phase 2 | Pending |
| CONV-01 | Phase 2 | Pending |
| CONV-02 | Phase 2 | Pending |
| CONV-03 | Phase 2 | Pending |
| CONV-04 | Phase 2 | Pending |
| CONV-05 | Phase 2 | Pending |
| CONV-06 | Phase 1 | Complete |
| BROWN-01 | Phase 3 | Pending |
| BROWN-02 | Phase 3 | Pending |
| BROWN-03 | Phase 3 | Pending |
| BROWN-04 | Phase 3 | Pending |
| BROWN-05 | Phase 3 | Pending |
| BROWN-06 | Phase 3 | Pending |
| INT-01 | Phase 3 | Pending |
| INT-02 | Phase 3 | Pending |
| INT-03 | Phase 3 | Pending |
| INT-04 | Phase 2 | Pending |
| DOC-01 | Phase 3 | Pending |
| DOC-02 | Phase 3 | Pending |
| DOC-03 | Phase 3 | Pending |
---
*Created: 2026-01-19*

71
.planning/milestones/v1.9.0-ROADMAP.md
View File

@@ -1,71 +0,0 @@
# Roadmap: v1.9.0 Codebase Intelligence System
## Overview
This milestone delivers a living knowledge system that learns codebase structure and conventions as Claude writes code, then injects that understanding into every session. The build order is: learning mechanism (PostToolUse hook) -> injection mechanism (SessionStart hook) -> brownfield analysis command -> GSD workflow integration.
## Phases
- [x] **Phase 1: Foundation & Learning** - Index store, PostToolUse hook, file parsing ✓
- [ ] **Phase 2: Context Injection** - SessionStart hook, convention detection, summary generation
- [ ] **Phase 3: Brownfield & Integration** - analyze-codebase command, GSD integration, documentation
## Phase Details
### Phase 1: Foundation & Learning
**Goal**: Claude learns from every file it writes, building an index of the codebase structure
**Depends on**: Nothing (first phase)
**Requirements**: INDEX-01, INDEX-02, INDEX-03, INDEX-04, INDEX-05, CONV-06
**Success Criteria** (what must be TRUE):
1. When Claude writes or edits a file, the file's exports and imports are captured in `.planning/intel/index.json`
2. Index updates incrementally (only the changed file is reprocessed)
3. Hook failures never block Claude — any error results in silent failure with `{ proceed: true }`
4. Index file exists at `.planning/intel/index.json` with valid JSON structure
**Plans:** 2 plans
Plans:
- [x] 01-01-PLAN.md — Index store and data model ✓
- [x] 01-02-PLAN.md — PostToolUse indexing hook ✓
### Phase 2: Context Injection
**Goal**: Claude receives codebase understanding automatically at session start
**Depends on**: Phase 1
**Requirements**: CTX-01, CTX-02, CTX-03, CTX-04, CTX-05, CONV-01, CONV-02, CONV-03, CONV-04, CONV-05
**Success Criteria** (what must be TRUE):
1. When a Claude session starts, codebase summary is injected wrapped in `<codebase-intelligence>` tags
2. Summary includes detected naming conventions (camelCase, PascalCase, etc.) with confidence thresholds met (5+ files, 70%+ match)
3. Summary includes directory structure overview and key exports by category
4. Conventions are stored in `.planning/intel/conventions.json`
5. Summary regenerates when conventions change
**Plans:** 2 plans
Plans:
- [ ] 02-01-PLAN.md — Convention detection engine
- [ ] 02-02-PLAN.md — SessionStart injection hook and summary generation
### Phase 3: Brownfield & Integration
**Goal**: Codebase intelligence works on existing codebases and integrates with GSD workflows
**Depends on**: Phase 2
**Requirements**: BROWN-01, BROWN-02, BROWN-03, BROWN-04, BROWN-05, BROWN-06, INT-01, INT-02, INT-03, INT-04, DOC-01, DOC-02, DOC-03
**Success Criteria** (what must be TRUE):
1. `/gsd:analyze-codebase` command scans existing codebase and populates `.planning/intel/`
2. Command works without `/gsd:new-project` — standalone operation on any codebase
3. After initial analysis, hooks continue incremental learning
4. `install.js` registers intel hooks in settings.json
5. `/gsd:new-project` creates `.planning/intel/` directory structure
6. Subagent prompts include codebase context
7. README, help.md, and GSD-STYLE.md document the codebase intelligence feature
**Plans**: TBD
Plans:
- [ ] 03-01: analyze-codebase command
- [ ] 03-02: GSD integration (installer, new-project, subagents)
- [ ] 03-03: Documentation updates
## Progress
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Foundation & Learning | 2/2 | ✓ Complete | 2026-01-20 |
| 2. Context Injection | 0/2 | Planned | - |
| 3. Brownfield & Integration | 0/3 | Not started | - |

69
.planning/phases/01-core-command/01-CONTEXT.md
View File

@@ -1,69 +0,0 @@
# Phase 1: Core Command - Context
**Gathered:** 2025-01-19
**Status:** Ready for planning
<domain>
## Phase Boundary
Complete `/gsd:quick` command that executes small tasks with GSD guarantees (atomic commits, STATE.md tracking) while skipping optional agents (research, plan-checker, verifier). Quick tasks live in `.planning/quick/` separate from planned phases.
</domain>
<decisions>
## Implementation Decisions
### Invocation & Arguments
- Interactive prompt for task description (no inline args)
- No flags — keep it minimal
- Fail with clear error if no ROADMAP.md exists
- Can run mid-phase — quick tasks always allowed regardless of current phase status
### Task Scope & Execution
- No scope limits — user decides what's "quick"
- Skip research agent, plan-checker agent, and verifier agent
- On failure: no resume tracking — user re-runs `/gsd:quick` from scratch
- Creates PLAN.md before execution (lightweight, single task)
### Output & Feedback
- Standard GSD output during execution (same task status updates)
- Creates SUMMARY.md matching regular phase format
- No commit if no changes (current GSD behavior)
### Directory Structure
- Quick tasks go to `.planning/quick/NNN-slug/` (NOT `.planning/phases/`)
- 3-digit padded ascending numbers: `001-fix-button-spacing/`, `002-update-readme/`
- Each directory contains: PLAN.md, SUMMARY.md
### State Integration
- Do NOT update ROADMAP.md — quick tasks are ad-hoc, not planned work
- Update STATE.md with "Quick Tasks Completed" table
- Table includes: number, description, date, commit hash, link to /quick/ dir
### Claude's Discretion
- Exact PLAN.md format for quick tasks (simplified vs full)
- Slug generation from task description
- Error message wording
</decisions>
<specifics>
## Specific Ideas
- Keep roadmap clean — it's the plan, not the execution log
- Quick tasks are interruptions, not planned phases — structure should reflect that
- Date is in git commit, no need in directory name
</specifics>
<deferred>
## Deferred Ideas
None — discussion stayed within phase scope
</deferred>
---
*Phase: 01-core-command*
*Context gathered: 2025-01-19*

362
.planning/phases/01-core-command/01-RESEARCH.md
View File

@@ -1,362 +0,0 @@
# Phase 1: Core Command - Research
**Researched:** 2025-01-19
**Domain:** GSD command architecture, slash command patterns, subagent orchestration
**Confidence:** HIGH
## Summary
This phase implements `/gsd:quick` as a lightweight command that executes small tasks while maintaining GSD guarantees (atomic commits, STATE.md tracking) but skipping optional agents (research, plan-checker, verifier). The CONTEXT.md decisions establish a clear separation from planned phases: quick tasks live in `.planning/quick/` with their own numbering scheme (001, 002, etc.) and do NOT touch ROADMAP.md.
The implementation reuses existing GSD infrastructure (gsd-planner in quick mode, gsd-executor unchanged, commit patterns from execute-plan). The main work is:
1. The orchestrator command itself
2. Interactive description prompting
3. Quick directory management (`.planning/quick/NNN-slug/`)
4. STATE.md integration (new "Quick Tasks Completed" table)
**Primary recommendation:** Build as a thin orchestrator command that spawns 2 agents (planner + executor) and handles the `.planning/quick/` directory structure directly.
## Standard Stack
The implementation uses existing GSD components with no new libraries.
### Core
| Component | Version | Purpose | Why Standard |
|-----------|---------|---------|--------------|
| gsd-planner | existing | Creates PLAN.md | Already has quick mode support documented in design docs |
| gsd-executor | existing | Executes tasks, creates SUMMARY.md | Unchanged from full mode |
| Task tool | Claude Code native | Spawns subagents | Standard GSD orchestration pattern |
### Supporting
| Component | Version | Purpose | When to Use |
|-----------|---------|---------|-------------|
| AskUserQuestion | Claude Code native | Interactive description prompt | Initial task description gathering |
| Edit tool | Claude Code native | STATE.md updates | Inserting rows in Quick Tasks table |
| Bash tool | Claude Code native | Directory creation, git commits | File system and git operations |
### Not Needed
| Instead of | Skip | Reason |
|------------|------|--------|
| gsd-phase-researcher | Skip entirely | Quick tasks don't need domain research |
| gsd-plan-checker | Skip entirely | Quick tasks trade verification for speed |
| gsd-verifier | Skip entirely | No phase verification for quick tasks |
| ROADMAP.md updates | Skip entirely | Quick tasks are ad-hoc, not planned work |
| Decimal phase logic | Skip entirely | Quick tasks use separate `.planning/quick/` directory |
## Architecture Patterns
### Recommended Directory Structure
```
.planning/
├── quick/ # Quick task storage (separate from phases)
│ ├── 001-fix-button-spacing/
│ │ ├── PLAN.md
│ │ └── SUMMARY.md
│ ├── 002-update-readme/
│ │ ├── PLAN.md
│ │ └── SUMMARY.md
│ └── ...
├── phases/ # Regular planned phases (unchanged)
├── STATE.md # Updated with Quick Tasks table
├── ROADMAP.md # NOT modified by quick tasks
└── ...
```
### Pattern 1: Thin Orchestrator with Interactive Prompt
**What:** Command prompts for description inline, then delegates all heavy work to subagents
**When to use:** When user invokes `/gsd:quick`
The command flow:
1. Validate `.planning/ROADMAP.md` exists (error if not - need active project)
2. Prompt user inline: "What do you want to do?"
3. Calculate next quick task number (scan `.planning/quick/` directories)
4. Create directory `.planning/quick/NNN-slug/`
5. Spawn gsd-planner (quick mode)
6. Spawn gsd-executor(s) for each plan created
7. Update STATE.md "Quick Tasks Completed" table
8. Commit artifacts
### Pattern 2: Sequential Numbering with Collision Detection
**What:** 3-digit zero-padded sequential numbers (001, 002, 003...)
**When to use:** Determining next quick task directory name
```bash
# Find existing quick task directories
existing=$(ls -1d .planning/quick/[0-9][0-9][0-9]-* 2>/dev/null | sort -r | head -1)
if [ -z "$existing" ]; then
next_num="001"
else
# Extract number from path like .planning/quick/042-some-task
current_num=$(basename "$existing" | grep -oE '^[0-9]+')
next_num=$(printf "%03d" $((10#$current_num + 1)))
fi
```
### Pattern 3: STATE.md Quick Tasks Table
**What:** Dedicated section tracking completed quick tasks
**When to use:** After each quick task completion
```markdown
### Quick Tasks Completed
| # | Description | Date | Commit | Directory |
|---|-------------|------|--------|-----------|
| 001 | Fix button spacing | 2025-01-19 | abc123f | [001-fix-button-spacing](./quick/001-fix-button-spacing/) |
| 002 | Update readme | 2025-01-19 | def456g | [002-update-readme](./quick/002-update-readme/) |
```
**Algorithm for STATE.md update:**
1. Find `## Accumulated Context` section
2. Find or create `### Quick Tasks Completed` subsection
3. Find or create the table with headers
4. Append new row with task details
5. If section doesn't exist, create it after existing subsections
### Pattern 4: Subagent Spawning (Planner then Executor)
**What:** Sequential spawning of planner then executor(s)
**When to use:** After directory created
```markdown
# Planner spawn
Task(
prompt="
<planning_context>
**Mode:** quick
**Phase Directory:** .planning/quick/{NNN}-{slug}/
**Description:** {description}
**Project State:**
@.planning/STATE.md
</planning_context>
<output>
Write PLAN.md to: .planning/quick/{NNN}-{slug}/PLAN.md
Return: ## PLANNING COMPLETE
</output>
",
subagent_type="gsd-planner",
description="Quick plan: {description}"
)
```
### Anti-Patterns to Avoid
- **Updating ROADMAP.md:** Quick tasks are interruptions, not planned work. Keep ROADMAP clean for phases only.
- **Using decimal phases:** The CONTEXT.md explicitly chose `.planning/quick/` to separate quick tasks from planned phases.
- **Inline args:** The CONTEXT.md chose interactive prompt instead of `/gsd:quick "description"` style.
- **Adding flags:** No flags (--plan-only, --after N). Keep it minimal per CONTEXT.md.
## Don't Hand-Roll
Problems that look simple but have existing solutions:
| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Plan creation | Custom quick-plan logic | gsd-planner (quick mode) | Already documented in QUICK-MODE-DESIGN.md |
| Task execution | Custom execution | gsd-executor | Unchanged, handles checkpoints/commits |
| Commit format | Custom commit messages | git-integration.md patterns | Consistent with full GSD |
| Wave execution | Custom parallel logic | execute-phase.md patterns | Proven wave-based parallelization |
| Slug generation | Custom slugify | Bash tr/sed pattern | Used throughout GSD commands |
**Key insight:** Quick mode is the same system with a shorter path. Reuse existing agents and patterns.
## Common Pitfalls
### Pitfall 1: Trying to Track Quick Tasks in ROADMAP.md
**What goes wrong:** Pollutes the roadmap with ad-hoc work, loses the clean "planned phases" narrative
**Why it happens:** Natural assumption that all work should be in the roadmap
**How to avoid:** STATE.md "Quick Tasks Completed" table is the tracking mechanism
**Warning signs:** Impulse to add decimal phases or "QUICK" markers to ROADMAP.md
### Pitfall 2: Not Checking for .planning/ROADMAP.md
**What goes wrong:** Command runs without a project context, creates orphan artifacts
**Why it happens:** Forgetting pre-flight validation
**How to avoid:** First step must be `ls .planning/ROADMAP.md` check
**Warning signs:** Quick task directories appearing in non-project codebases
### Pitfall 3: Complex Argument Parsing
**What goes wrong:** Adds complexity that CONTEXT.md explicitly rejected
**Why it happens:** QUICK-MODE-DESIGN.md has `--plan-only` and `--after N` flags
**How to avoid:** CONTEXT.md overrides: "No flags - keep it minimal"
**Warning signs:** Building arg parser for flags that won't be used
### Pitfall 4: Forgetting the Failure Case (No Resume)
**What goes wrong:** Users expect to resume failed quick tasks
**Why it happens:** Full GSD has resume capability
**How to avoid:** CONTEXT.md: "On failure: no resume tracking - user re-runs from scratch"
**Warning signs:** Building checkpoint/resume infrastructure for quick mode
### Pitfall 5: Not Creating .planning/quick/ Directory
**What goes wrong:** First quick task fails because parent directory doesn't exist
**Why it happens:** Assuming directory exists
**How to avoid:** `mkdir -p .planning/quick/` before creating task directory
**Warning signs:** "No such file or directory" errors on first quick task
## Code Examples
Verified patterns from existing GSD codebase:
### Pre-flight Validation
```bash
# Source: commands/gsd/quick.md (to be created)
# Check .planning exists with ROADMAP.md
if [ ! -f .planning/ROADMAP.md ]; then
echo "Quick mode requires an active project with ROADMAP.md."
echo "Run /gsd:new-project first."
exit 1
fi
```
### Next Quick Task Number Calculation
```bash
# Source: new pattern for quick task numbering
# Find highest existing number and increment
last=$(ls -1d .planning/quick/[0-9][0-9][0-9]-* 2>/dev/null | sort -r | head -1 | xargs -I{} basename {} | grep -oE '^[0-9]+')
if [ -z "$last" ]; then
next_num="001"
else
next_num=$(printf "%03d" $((10#$last + 1)))
fi
```
### Slug Generation
```bash
# Source: commands/gsd/new-project.md, commands/gsd/quick.md patterns
slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//' | cut -c1-40)
```
### Directory Creation
```bash
# Ensure .planning/quick/ exists then create task directory
mkdir -p ".planning/quick/${next_num}-${slug}"
```
### Planner Spawn (Quick Mode)
```markdown
# Source: QUICK-MODE-DESIGN.md, adapted for .planning/quick/ structure
Task(
prompt="
<planning_context>
**Mode:** quick
**Directory:** .planning/quick/{NNN}-{slug}/
**Description:** {description}
**Project State:**
@.planning/STATE.md
</planning_context>
<output>
Write PLAN.md to: .planning/quick/{NNN}-{slug}/PLAN.md
Return: ## PLANNING COMPLETE
</output>
",
subagent_type="gsd-planner",
description="Quick plan: {description}"
)
```
### Executor Spawn
```markdown
# Source: commands/gsd/execute-phase.md, adapted for quick tasks
Task(
prompt="
Execute quick task {NNN}.
Plan: @.planning/quick/{NNN}-{slug}/PLAN.md
Project state: @.planning/STATE.md
",
subagent_type="gsd-executor",
description="Execute: {description}"
)
```
### STATE.md Table Update (Conceptual)
```markdown
# Use Edit tool to append row to Quick Tasks Completed table
# Anchor: "### Quick Tasks Completed" section
# If section doesn't exist, create after "### Blockers/Concerns"
| {NNN} | {description} | {date} | {commit_hash} | [{NNN}-{slug}](./quick/{NNN}-{slug}/) |
```
### Commit Pattern
```bash
# Source: get-shit-done/references/git-integration.md
# Stage specific files only (never git add .)
git add .planning/quick/${next_num}-${slug}/
git add .planning/STATE.md
git commit -m "$(cat <<'EOF'
docs(quick-{NNN}): {description}
Quick task completed.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"
```
## State of the Art
| Old Approach (QUICK-MODE-DESIGN.md) | Current Approach (CONTEXT.md) | Why Changed | Impact |
|-------------------------------------|------------------------------|-------------|--------|
| `/gsd:quick "description"` inline args | Interactive prompt | Simpler UX, no quoting issues | Command parsing simplified |
| Decimal phases (3.1, 3.2) | `.planning/quick/NNN-slug/` | Cleaner separation from planned work | Directory logic completely different |
| Update ROADMAP.md | Do NOT update ROADMAP.md | Roadmap is plan, not execution log | Skip ROADMAP editing entirely |
| `--plan-only`, `--after N` flags | No flags | Keep it minimal | No argument parsing needed |
| STATE.md brief mention | Full "Quick Tasks Completed" table | Proper tracking mechanism | Need table creation/update logic |
**Key context:** CONTEXT.md from `/gsd:discuss-phase` represents user decisions that override the earlier QUICK-MODE-DESIGN.md. The research must follow CONTEXT.md.
## Open Questions
Things that couldn't be fully resolved:
1. **Table Creation Timing**
- What we know: STATE.md needs "Quick Tasks Completed" table
- What's unclear: Should table be created on first quick task, or pre-created in STATE.md template?
- Recommendation: Create on first quick task (check if exists, create if not)
2. **Multi-Plan Wave Execution**
- What we know: Quick tasks can produce multiple plans (per QUICK-MODE-DESIGN.md)
- What's unclear: CONTEXT.md mentions "execute each plan" but doesn't specify wave logic
- Recommendation: Reuse execute-phase wave pattern for consistency
3. **PLAN.md Naming in Quick Directory**
- What we know: Directory is `NNN-slug/`, contains PLAN.md and SUMMARY.md
- What's unclear: Should PLAN.md be named `PLAN.md` or `{NNN}-PLAN.md`?
- Recommendation: Simple `PLAN.md` since it's inside a numbered directory already
## Sources
### Primary (HIGH confidence)
- `.planning/phases/01-core-command/01-CONTEXT.md` - User decisions that override original requirements
- `commands/gsd/execute-phase.md` - Wave execution patterns
- `get-shit-done/workflows/execute-plan.md` - Executor workflow details
- `get-shit-done/workflows/execute-phase.md` - Subagent spawning patterns
- `get-shit-done/references/git-integration.md` - Commit format and patterns
- `get-shit-done/templates/state.md` - STATE.md structure
### Secondary (MEDIUM confidence)
- `docs/QUICK-MODE-DESIGN.md` - Original design (partially superseded by CONTEXT.md)
- `docs/QUICK-MODE-MVP.md` - MVP approach (partially superseded by CONTEXT.md)
### Changes from Design Docs
The CONTEXT.md decisions override several aspects of QUICK-MODE-DESIGN.md:
- No inline args (interactive prompt instead)
- No decimal phases (`.planning/quick/` instead)
- No ROADMAP.md updates
- No flags
- "Quick Tasks Completed" table for tracking
## Metadata
**Confidence breakdown:**
- Standard stack: HIGH - Using existing GSD agents unchanged
- Architecture: HIGH - Patterns well-documented in existing commands
- Pitfalls: HIGH - CONTEXT.md explicitly addresses common misunderstandings
**Research date:** 2025-01-19
**Valid until:** Stable - patterns from existing GSD codebase