get-shit-done-cc 1.3.33 → 1.4.0

package/README.md

@@ -177,6 +177,13 @@ Produces:
 
 Each phase breaks into 2-3 atomic tasks. Each task runs in a fresh subagent context — 200k tokens purely for implementation, zero degradation.
 
+**For multi-plan phases:**
+```
+/gsd:execute-phase 1   # Run all plans in parallel, "walk away" execution
+```
+
+Use `/gsd:execute-plan` for interactive single-plan execution with checkpoints. Use `/gsd:execute-phase` when you have multiple plans and want parallel "walk away" automation.
+
 ### 4. Ship and iterate
 
 ```
@@ -243,6 +250,7 @@ GSD handles it for you:
 | `PLAN.md` | Atomic task with XML structure, verification steps |
 | `SUMMARY.md` | What happened, what changed, committed to history |
 | `ISSUES.md` | Deferred enhancements tracked across sessions |
+| `todos/` | Captured ideas and tasks for later work |
 
 Size limits based on where Claude's quality degrades. Stay under, get consistent excellence.
 
@@ -315,7 +323,9 @@ You're never locked in. The system adapts.
 | `/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:execute-plan` | Run single plan via subagent |
+| `/gsd:execute-phase <N>` | Execute all plans in phase N with parallel agents |
+| `/gsd:status [--wait]` | Check background agent status from parallel execution |
 | `/gsd:progress` | Where am I? What's next? |
 | `/gsd:verify-work [N]` | User acceptance test of phase or plan ¹ |
 | `/gsd:plan-fix [plan]` | Plan fixes for UAT issues from verify-work |
@@ -332,6 +342,8 @@ You're never locked in. The system adapts.
 | `/gsd:resume-work` | Restore from last session |
 | `/gsd:resume-task [id]` | Resume interrupted subagent execution |
 | `/gsd:consider-issues` | Review deferred issues, close resolved, identify urgent |
+| `/gsd:add-todo [desc]` | Capture idea or task from conversation for later |
+| `/gsd:check-todos [area]` | List pending todos, select one to work on |
 | `/gsd:help` | Show all commands and usage guide |
 
 <sup>¹ Contributed by reddit user OracleGreyBeard</sup>
@@ -353,6 +365,14 @@ You're never locked in. The system adapts.
 npx get-shit-done-cc@latest
 ```
 
+**Using Docker or containerized environments?**
+
+If file reads fail with tilde paths (`~/.claude/...`), set `CLAUDE_CONFIG_DIR` before installing:
+```bash
+CLAUDE_CONFIG_DIR=/home/youruser/.claude npx get-shit-done-cc --global
+```
+This ensures absolute paths are used instead of `~` which may not expand correctly in containers.
+
 ---
 
 ## Star History

package/commands/gsd/add-todo.md

@@ -0,0 +1,182 @@
+---
+name: gsd:add-todo
+description: Capture idea or task as todo from current conversation context
+argument-hint: [optional description]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+---
+
+<objective>
+Capture an idea, task, or issue that surfaces during a GSD session as a structured todo for later work.
+
+Enables "thought → capture → continue" flow without losing context or derailing current work.
+</objective>
+
+<context>
+@.planning/STATE.md
+</context>
+
+<process>
+
+<step name="ensure_directory">
+```bash
+mkdir -p .planning/todos/pending .planning/todos/done
+```
+</step>
+
+<step name="check_existing_areas">
+```bash
+ls .planning/todos/pending/*.md 2>/dev/null | xargs -I {} grep "^area:" {} 2>/dev/null | cut -d' ' -f2 | sort -u
+```
+
+Note existing areas for consistency in infer_area step.
+</step>
+
+<step name="extract_content">
+**With arguments:** Use as the title/focus.
+- `/gsd:add-todo Add auth token refresh` → title = "Add auth token refresh"
+
+**Without arguments:** Analyze recent conversation to extract:
+- The specific problem, idea, or task discussed
+- Relevant file paths mentioned
+- Technical details (error messages, line numbers, constraints)
+
+Formulate:
+- `title`: 3-10 word descriptive title (action verb preferred)
+- `problem`: What's wrong or why this is needed
+- `solution`: Approach hints or "TBD" if just an idea
+- `files`: Relevant paths with line numbers from conversation
+</step>
+
+<step name="infer_area">
+Infer area from file paths:
+
+| Path pattern | Area |
+|--------------|------|
+| `src/api/*`, `api/*` | `api` |
+| `src/components/*`, `src/ui/*` | `ui` |
+| `src/auth/*`, `auth/*` | `auth` |
+| `src/db/*`, `database/*` | `database` |
+| `tests/*`, `__tests__/*` | `testing` |
+| `docs/*` | `docs` |
+| `.planning/*` | `planning` |
+| `scripts/*`, `bin/*` | `tooling` |
+| No files or unclear | `general` |
+
+Use existing area from step 2 if similar match exists.
+</step>
+
+<step name="check_duplicates">
+```bash
+grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null
+```
+
+If potential duplicate found:
+1. Read the existing todo
+2. Compare scope
+
+If overlapping, use AskUserQuestion:
+- header: "Duplicate?"
+- question: "Similar todo exists: [title]. What would you like to do?"
+- options:
+  - "Skip" — keep existing todo
+  - "Replace" — update existing with new context
+  - "Add anyway" — create as separate todo
+</step>
+
+<step name="create_file">
+```bash
+timestamp=$(date "+%Y-%m-%dT%H:%M")
+date_prefix=$(date "+%Y-%m-%d")
+```
+
+Generate slug from title (lowercase, hyphens, no special chars).
+
+Write to `.planning/todos/pending/${date_prefix}-${slug}.md`:
+
+```markdown
+---
+created: [timestamp]
+title: [title]
+area: [area]
+files:
+  - [file:lines]
+---
+
+## Problem
+
+[problem description - enough context for future Claude to understand weeks later]
+
+## Solution
+
+[approach hints or "TBD"]
+```
+</step>
+
+<step name="update_state">
+If `.planning/STATE.md` exists:
+
+1. Count todos: `ls .planning/todos/pending/*.md 2>/dev/null | wc -l`
+2. Update "### Pending Todos" under "## Accumulated Context"
+</step>
+
+<step name="git_commit">
+Commit the todo and any updated state:
+
+```bash
+git add .planning/todos/pending/[filename]
+[ -f .planning/STATE.md ] && git add .planning/STATE.md
+git commit -m "$(cat <<'EOF'
+docs: capture todo - [title]
+
+Area: [area]
+EOF
+)"
+```
+
+Confirm: "Committed: docs: capture todo - [title]"
+</step>
+
+<step name="confirm">
+```
+Todo saved: .planning/todos/pending/[filename]
+
+  [title]
+  Area: [area]
+  Files: [count] referenced
+
+---
+
+Would you like to:
+
+1. Continue with current work
+2. Add another todo
+3. View all todos (/gsd:check-todos)
+```
+</step>
+
+</process>
+
+<output>
+- `.planning/todos/pending/[date]-[slug].md`
+- Updated `.planning/STATE.md` (if exists)
+</output>
+
+<anti_patterns>
+- Don't create todos for work in current plan (that's deviation rule territory)
+- Don't create elaborate solution sections — captures ideas, not plans
+- Don't block on missing information — "TBD" is fine
+</anti_patterns>
+
+<success_criteria>
+- [ ] Directory structure exists
+- [ ] Todo file created with valid frontmatter
+- [ ] Problem section has enough context for future Claude
+- [ ] No duplicates (checked and resolved)
+- [ ] Area consistent with existing todos
+- [ ] STATE.md updated if exists
+- [ ] Todo and state committed to git
+</success_criteria>

package/commands/gsd/check-todos.md

@@ -0,0 +1,217 @@
+---
+name: gsd:check-todos
+description: List pending todos and select one to work on
+argument-hint: [area filter]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
+
+Enables reviewing captured ideas and deciding what to work on next.
+</objective>
+
+<context>
+@.planning/STATE.md
+@.planning/ROADMAP.md
+</context>
+
+<process>
+
+<step name="check_exist">
+```bash
+TODO_COUNT=$(ls .planning/todos/pending/*.md 2>/dev/null | wc -l | tr -d ' ')
+echo "Pending todos: $TODO_COUNT"
+```
+
+If count is 0:
+```
+No pending todos.
+
+Todos are captured during work sessions with /gsd:add-todo.
+
+---
+
+Would you like to:
+
+1. Continue with current phase (/gsd:progress)
+2. Add a todo now (/gsd:add-todo)
+```
+
+Exit.
+</step>
+
+<step name="parse_filter">
+Check for area filter in arguments:
+- `/gsd:check-todos` → show all
+- `/gsd:check-todos api` → filter to area:api only
+</step>
+
+<step name="list_todos">
+```bash
+for file in .planning/todos/pending/*.md; do
+  created=$(grep "^created:" "$file" | cut -d' ' -f2)
+  title=$(grep "^title:" "$file" | cut -d':' -f2- | xargs)
+  area=$(grep "^area:" "$file" | cut -d' ' -f2)
+  echo "$created|$title|$area|$file"
+done | sort
+```
+
+Apply area filter if specified. Display as numbered list:
+
+```
+Pending Todos:
+
+1. Add auth token refresh (api, 2d ago)
+2. Fix modal z-index issue (ui, 1d ago)
+3. Refactor database connection pool (database, 5h ago)
+
+---
+
+Reply with a number to view details, or:
+- `/gsd:check-todos [area]` to filter by area
+- `q` to exit
+```
+
+Format age as relative time.
+</step>
+
+<step name="handle_selection">
+Wait for user to reply with a number.
+
+If valid: load selected todo, proceed.
+If invalid: "Invalid selection. Reply with a number (1-[N]) or `q` to exit."
+</step>
+
+<step name="load_context">
+Read the todo file completely. Display:
+
+```
+## [title]
+
+**Area:** [area]
+**Created:** [date] ([relative time] ago)
+**Files:** [list or "None"]
+
+### Problem
+[problem section content]
+
+### Solution
+[solution section content]
+```
+
+If `files` field has entries, read and briefly summarize each.
+</step>
+
+<step name="check_roadmap">
+```bash
+ls .planning/ROADMAP.md 2>/dev/null && echo "Roadmap exists"
+```
+
+If roadmap exists:
+1. Check if todo's area matches an upcoming phase
+2. Check if todo's files overlap with a phase's scope
+3. Note any match for action options
+</step>
+
+<step name="offer_actions">
+**If todo maps to a roadmap phase:**
+
+Use AskUserQuestion:
+- header: "Action"
+- question: "This todo relates to Phase [N]: [name]. What would you like to do?"
+- options:
+  - "Work on it now" — move to done, start working
+  - "Add to phase plan" — include when planning Phase [N]
+  - "Brainstorm approach" — think through before deciding
+  - "Put it back" — return to list
+
+**If no roadmap match:**
+
+Use AskUserQuestion:
+- header: "Action"
+- question: "What would you like to do with this todo?"
+- options:
+  - "Work on it now" — move to done, start working
+  - "Create a phase" — /gsd:add-phase with this scope
+  - "Brainstorm approach" — think through before deciding
+  - "Put it back" — return to list
+</step>
+
+<step name="execute_action">
+**Work on it now:**
+```bash
+mv ".planning/todos/pending/[filename]" ".planning/todos/done/"
+```
+Update STATE.md todo count. Present problem/solution context. Begin work or ask how to proceed.
+
+**Add to phase plan:**
+Note todo reference in phase planning notes. Keep in pending. Return to list or exit.
+
+**Create a phase:**
+Display: `/gsd:add-phase [description from todo]`
+Keep in pending. User runs command in fresh context.
+
+**Brainstorm approach:**
+Keep in pending. Start discussion about problem and approaches.
+
+**Put it back:**
+Return to list_todos step.
+</step>
+
+<step name="update_state">
+After any action that changes todo count:
+
+```bash
+ls .planning/todos/pending/*.md 2>/dev/null | wc -l
+```
+
+Update STATE.md "### Pending Todos" section if exists.
+</step>
+
+<step name="git_commit">
+If todo was moved to done/, commit the change:
+
+```bash
+git add .planning/todos/done/[filename]
+git rm --cached .planning/todos/pending/[filename] 2>/dev/null || true
+[ -f .planning/STATE.md ] && git add .planning/STATE.md
+git commit -m "$(cat <<'EOF'
+docs: start work on todo - [title]
+
+Moved to done/, beginning implementation.
+EOF
+)"
+```
+
+Confirm: "Committed: docs: start work on todo - [title]"
+</step>
+
+</process>
+
+<output>
+- Moved todo to `.planning/todos/done/` (if "Work on it now")
+- Updated `.planning/STATE.md` (if todo count changed)
+</output>
+
+<anti_patterns>
+- Don't delete todos — move to done/ when work begins
+- Don't start work without moving to done/ first
+- Don't create plans from this command — route to /gsd:plan-phase or /gsd:add-phase
+</anti_patterns>
+
+<success_criteria>
+- [ ] All pending todos listed with title, area, age
+- [ ] Area filter applied if specified
+- [ ] Selected todo's full context loaded
+- [ ] Roadmap context checked for phase match
+- [ ] Appropriate actions offered
+- [ ] Selected action executed
+- [ ] STATE.md updated if todo count changed
+- [ ] Changes committed to git (if todo moved to done/)
+</success_criteria>

package/commands/gsd/execute-phase.md

@@ -0,0 +1,120 @@
+---
+name: gsd:execute-phase
+description: Execute all plans in a phase with intelligent parallelization
+argument-hint: "<phase-number>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - TaskOutput
+  - AskUserQuestion
+  - SlashCommand
+---
+
+<objective>
+Execute all unexecuted plans in a phase with parallel agent spawning.
+
+Analyzes plan dependencies to identify independent plans that can run concurrently.
+Spawns background agents for parallel execution, each agent commits its own tasks atomically.
+
+**Critical constraint:** One subagent per plan, always. This is for context isolation, not parallelization. Even strictly sequential plans spawn separate subagents so each starts with fresh 200k context at 0%.
+
+Use this command when:
+- Phase has 2+ unexecuted plans
+- Want "walk away, come back to completed work" execution
+- Plans have clear dependency boundaries
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/execute-plan.md
+@~/.claude/get-shit-done/workflows/execute-phase.md
+@~/.claude/get-shit-done/templates/summary.md
+@~/.claude/get-shit-done/references/checkpoints.md
+@~/.claude/get-shit-done/references/tdd.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+@.planning/STATE.md
+@.planning/config.json
+</context>
+
+<process>
+1. Validate phase exists in roadmap
+2. Find all PLAN.md files without matching SUMMARY.md
+3. If 0 or 1 plans: suggest /gsd:execute-plan instead
+4. If 2+ plans: follow execute-phase.md workflow
+5. Monitor parallel agents until completion
+6. Present results and next steps
+</process>
+
+<execution_strategies>
+**Strategy A: Fully Autonomous** (no checkpoints)
+
+- Spawn subagent to execute entire plan
+- Subagent creates SUMMARY.md and commits
+- Main context: orchestration only (~5% usage)
+
+**Strategy B: Segmented** (has verify-only checkpoints)
+
+- Execute in segments between checkpoints
+- Subagent for autonomous segments
+- Main context for checkpoints
+- Aggregate results → SUMMARY → commit
+
+**Strategy C: Decision-Dependent** (has decision checkpoints)
+
+- Execute in main context
+- Decision outcomes affect subsequent tasks
+- Quality maintained through small scope (2-3 tasks per plan)
+</execution_strategies>
+
+<deviation_rules>
+During execution, handle discoveries automatically:
+
+1. **Auto-fix bugs** - Fix immediately, document in Summary
+2. **Auto-add critical** - Security/correctness gaps, add and document
+3. **Auto-fix blockers** - Can't proceed without fix, do it and document
+4. **Ask about architectural** - Major structural changes, stop and ask user
+5. **Log enhancements** - Nice-to-haves, log to ISSUES.md, continue
+
+Only rule 4 requires user intervention.
+</deviation_rules>
+
+<commit_rules>
+**Per-Task Commits:**
+
+After each task completes:
+1. Stage only files modified by that task
+2. Commit with format: `{type}({phase}-{plan}): {task-name}`
+3. Types: feat, fix, test, refactor, perf, chore
+4. Record commit hash for SUMMARY.md
+
+**Plan Metadata Commit:**
+
+After all tasks complete:
+1. Stage planning artifacts only: PLAN.md, SUMMARY.md, STATE.md, ROADMAP.md
+2. Commit with format: `docs({phase}-{plan}): complete [plan-name] plan`
+3. NO code files (already committed per-task)
+
+**NEVER use:**
+- `git add .`
+- `git add -A`
+- `git add src/` or any broad directory
+
+**Always stage files individually.**
+</commit_rules>
+
+<success_criteria>
+- [ ] All independent plans executed in parallel
+- [ ] Dependent plans executed after dependencies complete
+- [ ] Each task committed individually (feat/fix/test/refactor)
+- [ ] All SUMMARY.md files created
+- [ ] Metadata committed by orchestrator
+- [ ] Phase progress updated
+</success_criteria>

package/commands/gsd/execute-plan.md

@@ -28,7 +28,7 @@ Uses intelligent segmentation:
   </objective>
 
 <execution_context>
-@~/.claude/get-shit-done/workflows/execute-phase.md
+@~/.claude/get-shit-done/workflows/execute-plan.md
 @~/.claude/get-shit-done/templates/summary.md
 @~/.claude/get-shit-done/references/checkpoints.md
 @~/.claude/get-shit-done/references/tdd.md
@@ -49,7 +49,7 @@ Plan path: $ARGUMENTS
 2. Verify plan at $ARGUMENTS exists
 3. Check if SUMMARY.md already exists (plan already executed?)
 4. Load workflow config for mode (interactive/yolo)
-5. Follow execute-phase.md workflow:
+5. Follow execute-plan.md workflow:
    - Parse plan and determine execution strategy (A/B/C)
    - Execute tasks (via subagent or main context as appropriate)
    - Handle checkpoints and deviations

package/commands/gsd/help.md

@@ -107,15 +107,38 @@ Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
 ### Execution
 
 **`/gsd:execute-plan <path>`**
-Execute a PLAN.md file directly.
+Execute a single PLAN.md file.
 
 - Runs plan tasks sequentially
 - Creates SUMMARY.md after completion
 - Updates STATE.md with accumulated context
-- Fast execution without loading full skill context
+- Use for interactive execution with checkpoints
 
 Usage: `/gsd:execute-plan .planning/phases/01-foundation/01-01-PLAN.md`
 
+**`/gsd:execute-phase <phase-number>`**
+Execute all unexecuted plans in a phase with parallel background agents.
+
+- Analyzes plan dependencies and spawns independent plans concurrently
+- Use when phase has 2+ plans and you want "walk away" execution
+- Respects max_concurrent_agents from config.json
+
+Usage: `/gsd:execute-phase 5`
+
+Options (via `.planning/config.json` parallelization section):
+- `max_concurrent_agents`: Limit parallel agents (default: 3)
+- `skip_checkpoints`: Skip human checkpoints in background (default: true)
+- `min_plans_for_parallel`: Minimum plans to trigger parallelization (default: 2)
+
+**`/gsd:status [--wait]`**
+Check status of background agents from parallel execution.
+
+- Shows running/completed agents from agent-history.json
+- Uses TaskOutput to poll agent status
+- With `--wait`: blocks until all agents complete
+
+Usage: `/gsd:status` or `/gsd:status --wait`
+
 ### Roadmap Management
 
 **`/gsd:add-phase <description>`**
@@ -225,6 +248,32 @@ Review deferred issues with codebase context.
 
 Usage: `/gsd:consider-issues`
 
+### Todo Management
+
+**`/gsd:add-todo [description]`**
+Capture idea or task as todo from current conversation.
+
+- Extracts context from conversation (or uses provided description)
+- Creates structured todo file in `.planning/todos/pending/`
+- Infers area from file paths for grouping
+- Checks for duplicates before creating
+- Updates STATE.md todo count
+
+Usage: `/gsd:add-todo` (infers from conversation)
+Usage: `/gsd:add-todo Add auth token refresh`
+
+**`/gsd:check-todos [area]`**
+List pending todos and select one to work on.
+
+- Lists all pending todos with title, area, age
+- Optional area filter (e.g., `/gsd:check-todos api`)
+- Loads full context for selected todo
+- Routes to appropriate action (work now, add to phase, brainstorm)
+- Moves todo to done/ when work begins
+
+Usage: `/gsd:check-todos`
+Usage: `/gsd:check-todos api`
+
 ### Utility Commands
 
 **`/gsd:help`**
@@ -239,6 +288,9 @@ Show this command reference.
 ├── STATE.md              # Project memory & context
 ├── ISSUES.md             # Deferred enhancements (created when needed)
 ├── config.json           # Workflow mode & gates
+├── todos/                # Captured ideas and tasks
+│   ├── pending/          # Todos waiting to be worked on
+│   └── done/             # Completed todos
 ├── codebase/             # Codebase map (brownfield projects)
 │   ├── STACK.md          # Languages, frameworks, dependencies
 │   ├── ARCHITECTURE.md   # Patterns, layers, data flow
@@ -306,6 +358,15 @@ Change anytime by editing `.planning/config.json`
 /gsd:new-project  # Start next milestone
 ```
 
+**Capturing ideas during work:**
+
+```
+/gsd:add-todo                    # Capture from conversation context
+/gsd:add-todo Fix modal z-index  # Capture with explicit description
+/gsd:check-todos                 # Review and work on todos
+/gsd:check-todos api             # Filter by area
+```
+
 ## Getting Help
 
 - Read `.planning/PROJECT.md` for project vision