@undeemed/get-shit-done-codex 1.6.12 → 1.20.2

package/get-shit-done/templates/phase-prompt.md

@@ -75,33 +75,23 @@ Output: [What artifacts will be created]
   <done>[Acceptance criteria]</done>
 </task>
 
+<!-- For checkpoint task examples and patterns, see @~/.claude/get-shit-done/references/checkpoints.md -->
+<!-- Key rule: Claude starts dev server BEFORE human-verify checkpoints. User only visits URLs. -->
+
 <task type="checkpoint:decision" gate="blocking">
   <decision>[What needs deciding]</decision>
   <context>[Why this decision matters]</context>
   <options>
-    <option id="option-a">
-      <name>[Option name]</name>
-      <pros>[Benefits and advantages]</pros>
-      <cons>[Tradeoffs and limitations]</cons>
-    </option>
-    <option id="option-b">
-      <name>[Option name]</name>
-      <pros>[Benefits and advantages]</pros>
-      <cons>[Tradeoffs and limitations]</cons>
-    </option>
+    <option id="option-a"><name>[Name]</name><pros>[Benefits]</pros><cons>[Tradeoffs]</cons></option>
+    <option id="option-b"><name>[Name]</name><pros>[Benefits]</pros><cons>[Tradeoffs]</cons></option>
   </options>
-  <resume-signal>[How to indicate choice - "Select: option-a or option-b"]</resume-signal>
+  <resume-signal>Select: option-a or option-b</resume-signal>
 </task>
 
 <task type="checkpoint:human-verify" gate="blocking">
-  <what-built>[What Claude just built that needs verification]</what-built>
-  <how-to-verify>
-    1. Run: [command to start dev server/app]
-    2. Visit: [URL to check]
-    3. Test: [Specific interactions]
-    4. Confirm: [Expected behaviors]
-  </how-to-verify>
-  <resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal>
+  <what-built>[What Claude built] - server running at [URL]</what-built>
+  <how-to-verify>Visit [URL] and verify: [visual checks only, NO CLI commands]</how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
 </task>
 
 </tasks>
@@ -403,15 +393,16 @@ Output: Working dashboard component.
   <done>Dashboard renders without errors</done>
 </task>
 
+<!-- Checkpoint pattern: Claude starts server, user visits URL. See checkpoints.md for full patterns. -->
+<task type="auto">
+  <name>Start dev server</name>
+  <action>Run `npm run dev` in background, wait for ready</action>
+  <verify>curl localhost:3000 returns 200</verify>
+</task>
+
 <task type="checkpoint:human-verify" gate="blocking">
-  <what-built>Responsive dashboard with user and product sections</what-built>
-  <how-to-verify>
-    1. Run: npm run dev
-    2. Visit: http://localhost:3000/dashboard
-    3. Desktop: Verify two-column grid
-    4. Mobile: Verify stacked layout
-    5. Check: No layout shift, no scroll issues
-  </how-to-verify>
+  <what-built>Dashboard - server at http://localhost:3000</what-built>
+  <how-to-verify>Visit localhost:3000/dashboard. Check: desktop grid, mobile stack, no scroll issues.</how-to-verify>
   <resume-signal>Type "approved" or describe issues</resume-signal>
 </task>
 </tasks>

package/get-shit-done/templates/planner-subagent-prompt.md

@@ -22,14 +22,14 @@ Template for spawning gsd-planner agent. The agent contains all planning experti
 @.planning/REQUIREMENTS.md
 
 **Phase Context (if exists):**
-@.planning/phases/{phase_dir}/{phase}-CONTEXT.md
+@.planning/phases/{phase_dir}/{phase_num}-CONTEXT.md
 
 **Research (if exists):**
-@.planning/phases/{phase_dir}/{phase}-RESEARCH.md
+@.planning/phases/{phase_dir}/{phase_num}-RESEARCH.md
 
 **Gap Closure (if --gaps mode):**
-@.planning/phases/{phase_dir}/{phase}-VERIFICATION.md
-@.planning/phases/{phase_dir}/{phase}-UAT.md
+@.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md
+@.planning/phases/{phase_dir}/{phase_num}-UAT.md
 
 </planning_context>
 

package/get-shit-done/templates/research-project/ARCHITECTURE.md

@@ -177,7 +177,7 @@ src/
 <guidelines>
 
 **System Overview:**
-- Use ASCII diagrams for clarity
+- Use ASCII box-drawing diagrams for clarity (├── └── │ ─ for structure visualization only)
 - Show major components and their relationships
 - Don't over-detail — this is conceptual, not implementation
 

package/get-shit-done/templates/research.md

@@ -1,6 +1,6 @@
 # Research Template
 
-Template for `.planning/phases/XX-name/{phase}-RESEARCH.md` - comprehensive ecosystem research before planning.
+Template for `.planning/phases/XX-name/{phase_num}-RESEARCH.md` - comprehensive ecosystem research before planning.
 
 **Purpose:** Document what Claude needs to know to implement a phase well - not just "which library" but "how do experts build this."
 
@@ -15,6 +15,29 @@ Template for `.planning/phases/XX-name/{phase}-RESEARCH.md` - comprehensive ecos
 **Domain:** [primary technology/problem domain]
 **Confidence:** [HIGH/MEDIUM/LOW]
 
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+**CRITICAL:** If CONTEXT.md exists from /gsd:discuss-phase, copy locked decisions here verbatim. These MUST be honored by the planner.
+
+### Locked Decisions
+[Copy from CONTEXT.md `## Decisions` section - these are NON-NEGOTIABLE]
+- [Decision 1]
+- [Decision 2]
+
+### Claude's Discretion
+[Copy from CONTEXT.md - areas where researcher/planner can choose]
+- [Area 1]
+- [Area 2]
+
+### Deferred Ideas (OUT OF SCOPE)
+[Copy from CONTEXT.md - do NOT research or plan these]
+- [Deferred 1]
+- [Deferred 2]
+
+**If no CONTEXT.md exists:** Write "No user constraints - all decisions at Claude's discretion"
+</user_constraints>
+
 <research_summary>
 ## Summary
 
@@ -524,6 +547,6 @@ function useVehicleControls(rigidBodyRef) {
 - Code examples can be referenced in task actions
 
 **After creation:**
-- File lives in phase directory: `.planning/phases/XX-name/{phase}-RESEARCH.md`
+- File lives in phase directory: `.planning/phases/XX-name/{phase_num}-RESEARCH.md`
 - Referenced during planning workflow
 - plan-phase loads it automatically when present

package/get-shit-done/templates/state.md

@@ -174,33 +174,3 @@ It's a DIGEST, not an archive. If accumulated context grows too large:
 The goal is "read once, know where we are" — if it's too long, that fails.
 
 </size_constraint>
-
-<guidelines>
-
-**When created:**
-- During project initialization (after ROADMAP.md)
-- Reference PROJECT.md (extract core value and current focus)
-- Initialize empty sections
-
-**When read:**
-- Every workflow starts by reading STATE.md
-- Then read PROJECT.md for full context
-- Provides instant context restoration
-
-**When updated:**
-- After each plan execution (update position, note decisions, update issues/blockers)
-- After phase transitions (update progress bar, clear resolved blockers, refresh project reference)
-
-**Size management:**
-- Keep under 100 lines total
-- Recent decisions only in STATE.md (full log in PROJECT.md)
-- Keep only active blockers
-
-**Sections:**
-- Project Reference: Pointer to PROJECT.md with core value
-- Current Position: Where we are now (phase, plan, status)
-- Performance Metrics: Velocity tracking
-- Accumulated Context: Recent decisions, pending todos, blockers
-- Session Continuity: Resume information
-
-</guidelines>

package/get-shit-done/templates/summary-complex.md

@@ -0,0 +1,59 @@
+---
+phase: XX-name
+plan: YY
+subsystem: [primary category]
+tags: [searchable tech]
+requires:
+  - phase: [prior phase]
+    provides: [what that phase built]
+provides:
+  - [bullet list of what was built/delivered]
+affects: [list of phase names or keywords]
+tech-stack:
+  added: [libraries/tools]
+  patterns: [architectural/code patterns]
+key-files:
+  created: [important files created]
+  modified: [important files modified]
+key-decisions:
+  - "Decision 1"
+patterns-established:
+  - "Pattern 1: description"
+duration: Xmin
+completed: YYYY-MM-DD
+---
+
+# Phase [X]: [Name] Summary (Complex)
+
+**[Substantive one-liner describing outcome]**
+
+## Performance
+- **Duration:** [time]
+- **Tasks:** [count completed]
+- **Files modified:** [count]
+
+## Accomplishments
+- [Key outcome 1]
+- [Key outcome 2]
+
+## Task Commits
+1. **Task 1: [task name]** - `hash`
+2. **Task 2: [task name]** - `hash`
+3. **Task 3: [task name]** - `hash`
+
+## Files Created/Modified
+- `path/to/file.ts` - What it does
+- `path/to/another.ts` - What it does
+
+## Decisions Made
+[Key decisions with brief rationale]
+
+## Deviations from Plan (Auto-fixed)
+[Detailed auto-fix records per GSD deviation rules]
+
+## Issues Encountered
+[Problems during planned work and resolutions]
+
+## Next Phase Readiness
+[What's ready for next phase]
+[Blockers or concerns]

package/get-shit-done/templates/summary-minimal.md

@@ -0,0 +1,41 @@
+---
+phase: XX-name
+plan: YY
+subsystem: [primary category]
+tags: [searchable tech]
+provides:
+  - [bullet list of what was built/delivered]
+affects: [list of phase names or keywords]
+tech-stack:
+  added: [libraries/tools]
+  patterns: [architectural/code patterns]
+key-files:
+  created: [important files created]
+  modified: [important files modified]
+key-decisions: []
+duration: Xmin
+completed: YYYY-MM-DD
+---
+
+# Phase [X]: [Name] Summary (Minimal)
+
+**[Substantive one-liner describing outcome]**
+
+## Performance
+- **Duration:** [time]
+- **Tasks:** [count]
+- **Files modified:** [count]
+
+## Accomplishments
+- [Most important outcome]
+- [Second key accomplishment]
+
+## Task Commits
+1. **Task 1: [task name]** - `hash`
+2. **Task 2: [task name]** - `hash`
+
+## Files Created/Modified
+- `path/to/file.ts` - What it does
+
+## Next Phase Readiness
+[Ready for next phase]

package/get-shit-done/templates/summary-standard.md

@@ -0,0 +1,48 @@
+---
+phase: XX-name
+plan: YY
+subsystem: [primary category]
+tags: [searchable tech]
+provides:
+  - [bullet list of what was built/delivered]
+affects: [list of phase names or keywords]
+tech-stack:
+  added: [libraries/tools]
+  patterns: [architectural/code patterns]
+key-files:
+  created: [important files created]
+  modified: [important files modified]
+key-decisions:
+  - "Decision 1"
+duration: Xmin
+completed: YYYY-MM-DD
+---
+
+# Phase [X]: [Name] Summary
+
+**[Substantive one-liner describing outcome]**
+
+## Performance
+- **Duration:** [time]
+- **Tasks:** [count completed]
+- **Files modified:** [count]
+
+## Accomplishments
+- [Key outcome 1]
+- [Key outcome 2]
+
+## Task Commits
+1. **Task 1: [task name]** - `hash`
+2. **Task 2: [task name]** - `hash`
+3. **Task 3: [task name]** - `hash`
+
+## Files Created/Modified
+- `path/to/file.ts` - What it does
+- `path/to/another.ts` - What it does
+
+## Decisions & Deviations
+[Key decisions or "None - followed plan as specified"]
+[Minor deviations if any, or "None"]
+
+## Next Phase Readiness
+[What's ready for next phase]

package/get-shit-done/templates/summary.md

@@ -233,37 +233,14 @@ The one-liner should tell someone what actually shipped.
 </example>
 
 <guidelines>
-**When to create:**
-- After completing each phase plan
-- Required output from execute-plan workflow
-- Documents what actually happened vs what was planned
-
-**Frontmatter completion:**
-- MANDATORY: Complete all frontmatter fields during summary creation
-- See <frontmatter_guidance> for field purposes
-- Frontmatter enables automatic context assembly for future planning
-
-**One-liner requirements:**
-- Must be substantive (describe what shipped, not "phase complete")
-- Should tell someone what was accomplished
-- Examples: "JWT auth with refresh rotation using jose library" not "Authentication implemented"
-
-**Performance tracking:**
-- Include duration, start/end timestamps
-- Used for velocity metrics in STATE.md
-
-**Deviations section:**
-- Documents unplanned work handled via deviation rules
-- Separate from "Issues Encountered" (which is planned work problems)
-- Auto-fixed issues: What was wrong, how fixed, verification
+**Frontmatter:** MANDATORY - complete all fields. Enables automatic context assembly for future planning.
+
+**One-liner:** Must be substantive. "JWT auth with refresh rotation using jose library" not "Authentication implemented".
 
 **Decisions section:**
-- Key decisions made during execution
-- Include rationale (why this choice)
+- Key decisions made during execution with rationale
 - Extracted to STATE.md accumulated context
 - Use "None - followed plan as specified" if no deviations
 
-**After creation:**
-- STATE.md updated with position, decisions, issues
-- Next plan can reference decisions made
+**After creation:** STATE.md updated with position, decisions, issues.
 </guidelines>

package/get-shit-done/templates/user-setup.md

@@ -304,20 +304,8 @@ curl -X POST http://localhost:3000/api/test-email \
 
 ## Guidelines
 
-**Include in USER-SETUP.md:**
-- Environment variable names and where to find values
-- Account creation URLs (if new service)
-- Dashboard configuration steps
-- Verification commands to confirm setup works
-- Local development alternatives (e.g., `stripe listen`)
-
-**Do NOT include:**
-- Actual secret values (never)
-- Steps Claude can automate (package installs, code changes, file creation)
-- Generic instructions ("set up your environment")
+**Never include:** Actual secret values. Steps Claude can automate (package installs, code changes).
 
 **Naming:** `{phase}-USER-SETUP.md` matches the phase number pattern.
-
 **Status tracking:** User marks checkboxes and updates status line when complete.
-
 **Searchability:** `grep -r "USER-SETUP" .planning/` finds all phases with user requirements.

package/get-shit-done/templates/verification-report.md

@@ -1,6 +1,6 @@
 # Verification Report Template
 
-Template for `.planning/phases/XX-name/{phase}-VERIFICATION.md` — phase goal verification results.
+Template for `.planning/phases/XX-name/{phase_num}-VERIFICATION.md` — phase goal verification results.
 
 ---
 

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

@@ -0,0 +1,111 @@
+<purpose>
+Add a new integer phase to the end of the current milestone in the roadmap. Automatically calculates next phase number, creates phase directory, and updates roadmap structure.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- All arguments become the phase description
+- Example: `/gsd:add-phase Add authentication` → description = "Add authentication"
+- Example: `/gsd:add-phase Fix critical performance issues` → description = "Fix critical performance issues"
+
+If no arguments provided:
+
+```
+ERROR: Phase description required
+Usage: /gsd:add-phase <description>
+Example: /gsd:add-phase Add authentication system
+```
+
+Exit.
+</step>
+
+<step name="init_context">
+Load phase operation context:
+
+```bash
+INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init phase-op "0")
+```
+
+Check `roadmap_exists` from init JSON. If false:
+```
+ERROR: No roadmap found (.planning/ROADMAP.md)
+Run /gsd:new-project to initialize.
+```
+Exit.
+</step>
+
+<step name="add_phase">
+**Delegate the phase addition to gsd-tools:**
+
+```bash
+RESULT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs phase add "${description}")
+```
+
+The CLI handles:
+- Finding the highest existing integer phase number
+- Calculating next phase number (max + 1)
+- Generating slug from description
+- Creating the phase directory (`.planning/phases/{NN}-{slug}/`)
+- Inserting the phase entry into ROADMAP.md with Goal, Depends on, and Plans sections
+
+Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
+</step>
+
+<step name="update_project_state">
+Update STATE.md to reflect the new phase:
+
+1. Read `.planning/STATE.md`
+2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
+   ```
+   - Phase {N} added: {description}
+   ```
+
+If "Roadmap Evolution" section doesn't exist, create it.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {N} added to current milestone:
+- Description: {description}
+- Directory: .planning/phases/{phase-num}-{slug}/
+- Status: Not planned yet
+
+Roadmap updated: .planning/ROADMAP.md
+
+---
+
+## ▶ Next Up
+
+**Phase {N}: {description}**
+
+`/gsd:plan-phase {N}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:add-phase <description>` — add another phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] `gsd-tools phase add` executed successfully
+- [ ] Phase directory created
+- [ ] Roadmap updated with new phase entry
+- [ ] STATE.md updated with roadmap evolution note
+- [ ] User informed of next steps
+</success_criteria>

package/get-shit-done/workflows/add-todo.md

@@ -0,0 +1,157 @@
+<purpose>
+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.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="init_context">
+Load todo context:
+
+```bash
+INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init todos)
+```
+
+Extract from init JSON: `commit_docs`, `date`, `timestamp`, `todo_count`, `todos`, `pending_dir`, `todos_dir_exists`.
+
+Ensure directories exist:
+```bash
+mkdir -p .planning/todos/pending .planning/todos/done
+```
+
+Note existing areas from the todos array 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
+# Search for key words from title in existing todos
+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">
+Use values from init context: `timestamp` and `date` are already available.
+
+Generate slug for the title:
+```bash
+slug=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs generate-slug "$title" --raw)
+```
+
+Write to `.planning/todos/pending/${date}-${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. Use `todo_count` from init context (or re-run `init todos` if count changed)
+2. Update "### Pending Todos" under "## Accumulated Context"
+</step>
+
+<step name="git_commit">
+Commit the todo and any updated state:
+
+```bash
+node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs: capture todo - [title]" --files .planning/todos/pending/[filename] .planning/STATE.md
+```
+
+Tool respects `commit_docs` config and gitignore automatically.
+
+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>
+
+<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>