eliott/get-shit-done
1
0
Fork 0
mirror of https://github.com/glittercowboy/get-shit-done synced 2026-04-25 17:25:23 +02:00
Code Issues Packages Projects Releases Wiki Activity

Initial commit: Get Shit Done - meta-prompting system for Claude Code

Browse Source 
- NPX install: npx get-shit-done-cc
- Slash commands for project management
- Context engineering templates and workflows

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2025-12-14 08:16:28 -06:00
commit 1fe3fa427e
50 changed files with 11469 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored Normal file
View File

@@ -0,0 +1,2 @@
.planning
.DS_Store

21
LICENSE Normal file
View File

@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2025 Lex Christopherson
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

180
README.md Normal file
View File

@@ -0,0 +1,180 @@
# Get Shit Done
**A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.**
Vibecoding has a bad reputation. You describe what you want, AI generates code, and you get inconsistent garbage that falls apart at scale.
GSD fixes that. It's the context engineering layer that makes Claude Code reliable. Describe your idea, let the system extract everything it needs to know, and then let Claude Code get to work.
THIS is how you vibecode and actually get shit done.
_Warning: Not for people who enjoy inconsistent and sloppy results._
---
## Why I Built This
I'm a solo developer. I don't write code — Claude Code does.
Other spec-driven development tools exist; BMAD, Speckit... But they all seem to make things way more complicated than they need to be (sprint ceremonies, story points, stakeholder syncs, retrospectives, Jira workflows) or lack real big picture understanding of what you're building. I'm not a 50-person software company. I don't want to play enterprise theater. I'm just a creative person trying to build great things that work.
So I built GSD. The complexity is in the system, not in your workflow. Behind the scenes: context engineering, XML prompt formatting, subagent orchestration, state management. What you see: a few commands that just work.
I wanted to spend my time having ideas and seeing them through to implementation — not babysitting Claude. Now I can say "go," put it in YOLO mode, and go to the beach. The system gives Claude everything it needs to do the work _and_ verify it. I trust the workflow. It just does a good job.
That's what this is. No enterprise roleplay bullshit. Just an incredibly effective system for building cool stuff consistently using Claude Code.
— TÂCHES
---
## How It Works
### 1. Start with an idea
```
/gsd:new-project
```
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.
### 2. Initialize the project
Your idea becomes:
- **PROJECT.md** - Project vision (~50 lines)
- **ROADMAP.md** - Phases from start to finish
- **STATE.md** - Living memory that persists across sessions
### 3. Plan and execute phases
```
/gsd:plan-phase 1 # System creates atomic task plans
/gsd:execute-plan # Subagent implements autonomously
```
Each phase breaks into 2-3 atomic tasks. Each task runs in a fresh subagent context — 200k tokens purely for implementation, zero degradation.
### 4. Ship and iterate
```
/gsd:complete-milestone # Archive v1, prep for v2
/gsd:add-phase # Append new work
/gsd:insert-phase 2 # Slip urgent work between phases
```
Ship your MVP in a day. Add features. Insert hotfixes. The system stays modular — you're never stuck.
---
## Why It Works
### Context Engineering
Claude Code is incredibly powerful _if_ you give it the context it needs. Most people don't.
GSD handles it for you:
| File | What it does |
| ------------ | ------------------------------------------------------ |
| `PROJECT.md` | Project vision, always loaded |
| `ROADMAP.md` | Where you're going, what's done |
| `STATE.md` | Decisions, blockers, position — memory across sessions |
| `PLAN.md` | Atomic task with XML structure, verification steps |
| `SUMMARY.md` | What happened, what changed, committed to history |
Size limits based on where Claude's quality degrades. Stay under, get consistent excellence.
### XML Prompt Formatting
Every plan is structured XML optimized for Claude:
```xml
<task type="auto">
<name>Create login endpoint</name>
<files>src/app/api/auth/login/route.ts</files>
<action>
Use jose for JWT (not jsonwebtoken - CommonJS issues).
Validate credentials against users table.
Return httpOnly cookie on success.
</action>
<verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
<done>Valid credentials return cookie, invalid return 401</done>
</task>
```
Precise instructions. No guessing. Verification built in.
### Subagent Execution
Plans run in fresh contexts:
- 0% overhead to start
- Maximum quality, zero degradation
- Walk away, come back to completed work
### Clean Git History
Every task: atomic commit, clear message, summary documenting outcomes. Maintainable history you can trace.
### Modular by Design
- Add phases to current milestone
- Insert urgent work between phases
- Complete milestones and start fresh
- Adjust plans without rebuilding everything
You're never locked in. The system adapts.
---
## Commands
| Command | What it does |
| --------------------------------- | ------------------------------------------------------------- |
| `/gsd:new-project` | Extract your idea through questions, create project structure |
| `/gsd:plan-phase [N]` | Generate task plans for phase |
| `/gsd:execute-plan` | Run plan via subagent |
| `/gsd:progress` | Where am I? What's next? |
| `/gsd:complete-milestone` | Ship it, prep next version |
| `/gsd:discuss-milestone` | Gather context for next milestone |
| `/gsd:new-milestone [name]` | Create new milestone with phases |
| `/gsd:add-phase` | Append phase to roadmap |
| `/gsd:insert-phase [N]` | Insert urgent work |
| `/gsd:discuss-phase [N]` | Gather context before planning |
| `/gsd:list-phase-assumptions [N]` | See what Claude thinks before you correct it |
| `/gsd:pause-work` | Create handoff file when stopping mid-phase |
| `/gsd:resume-work` | Restore from last session |
| `/gsd:help` | Show all commands and usage guide |
---
## Who This Is For
People who want to vibecode and have it actually work.
Anyone who wants to clearly describe what they want, trust the system to build it, and go live their life.
Not for people who enjoy inconsistent and sloppy results.
---
## Installation
```bash
npx get-shit-done-cc
```
That's it. Works on Mac, Windows, and Linux.
Verify: `/gsd:help`
---
## License
MIT License. See [LICENSE](LICENSE) for details.
---
**Claude Code is powerful. GSD gives it the context and the systematic consistency to prove it.**

53
bin/install.js Executable file
View File

@@ -0,0 +1,53 @@
#!/usr/bin/env node
const fs = require('fs');
const path = require('path');
const os = require('os');
// Colors
const cyan = '\x1b[36m';
const green = '\x1b[32m';
const dim = '\x1b[2m';
const reset = '\x1b[0m';
// Get version from package.json
const pkg = require('../package.json');
const banner = `
${cyan} ██████╗ ███████╗██████╗
██╔════╝ ██╔════╝██╔══██╗
██║ ███╗███████╗██║ ██║
██║ ██║╚════██║██║ ██║
╚██████╔╝███████║██████╔╝
╚═════╝ ╚══════╝╚═════╝${reset}
Get Shit Done ${dim}v${pkg.version}${reset}
A meta-prompting, context engineering and spec-driven
development system for Claude Code by TÂCHES.
`;
console.log(banner);
// Paths
const src = path.join(__dirname, '..');
const claudeDir = path.join(os.homedir(), '.claude');
const commandsDir = path.join(claudeDir, 'commands');
// Create directories
fs.mkdirSync(commandsDir, { recursive: true });
// Copy commands/gsd
const gsdSrc = path.join(src, 'commands', 'gsd');
const gsdDest = path.join(commandsDir, 'gsd');
fs.cpSync(gsdSrc, gsdDest, { recursive: true });
console.log(` ${green}✓${reset} Installed commands/gsd`);
// Copy get-shit-done
const skillSrc = path.join(src, 'get-shit-done');
const skillDest = path.join(claudeDir, 'get-shit-done');
fs.cpSync(skillSrc, skillDest, { recursive: true });
console.log(` ${green}✓${reset} Installed get-shit-done`);
console.log(`
${green}Done!${reset} Run ${cyan}/gsd:help${reset} to get started.
`);

201
commands/gsd/add-phase.md Normal file
View File

@@ -0,0 +1,201 @@
---
description: Add phase to end of current milestone in roadmap
argument-hint: <description>
allowed-tools:
- Read
- Write
- Bash
---
<objective>
Add a new integer phase to the end of the current milestone in the roadmap.
This command appends sequential phases to the current milestone's phase list, automatically calculating the next phase number based on existing phases.
Purpose: Add planned work discovered during execution that belongs at the end of current milestone.
</objective>
<execution_context>
@.planning/ROADMAP.md
@.planning/STATE.md
</execution_context>
<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="load_roadmap">
Load the roadmap file:
```bash
if [ -f .planning/ROADMAP.md ]; then
ROADMAP=".planning/ROADMAP.md"
else
echo "ERROR: No roadmap found (.planning/ROADMAP.md)"
exit 1
fi
```
Read roadmap content for parsing.
</step>
<step name="find_current_milestone">
Parse the roadmap to find the current milestone section:
1. Locate the "## Current Milestone:" heading
2. Extract milestone name and version
3. Identify all phases under this milestone (before next "---" separator or next milestone heading)
4. Parse existing phase numbers (including decimals if present)
Example structure:
```
## Current Milestone: v1.0 Foundation
### Phase 4: Focused Command System
### Phase 5: Path Routing & Validation
### Phase 6: Documentation & Distribution
```
</step>
<step name="calculate_next_phase">
Find the highest integer phase number in the current milestone:
1. Extract all phase numbers from phase headings (### Phase N:)
2. Filter to integer phases only (ignore decimals like 4.1, 4.2)
3. Find the maximum integer value
4. Add 1 to get the next phase number
Example: If phases are 4, 5, 5.1, 6 → next is 7
Format as two-digit: `printf "%02d" $next_phase`
</step>
<step name="generate_slug">
Convert the phase description to a kebab-case slug:
```bash
# Example transformation:
# "Add authentication" → "add-authentication"
# "Fix critical performance issues" → "fix-critical-performance-issues"
slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
```
Phase directory name: `{two-digit-phase}-{slug}`
Example: `07-add-authentication`
</step>
<step name="create_phase_directory">
Create the phase directory structure:
```bash
phase_dir=".planning/phases/${phase_num}-${slug}"
mkdir -p "$phase_dir"
```
Confirm: "Created directory: $phase_dir"
</step>
<step name="update_roadmap">
Add the new phase entry to the roadmap:
1. Find the insertion point (after last phase in current milestone, before "---" separator)
2. Insert new phase heading:
```
### Phase {N}: {Description}
**Goal:** [To be planned]
**Depends on:** Phase {N-1}
**Plans:** 0 plans
Plans:
- [ ] TBD (run /gsd:plan-phase {N} to break down)
**Details:**
[To be added during planning]
```
3. Write updated roadmap back to file
Preserve all other content exactly (formatting, spacing, other phases).
</step>
<step name="update_project_state">
Update STATE.md to reflect the new phase:
1. Read `.planning/STATE.md`
2. Under "## Current Position" → "**Next Phase:**" add reference to new phase
3. 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: {roadmap-path}
Project state updated: .planning/STATE.md
What's next?
1. Plan this phase: /gsd:plan-phase {N}
2. Add another phase: /gsd:add-phase <description>
3. Review roadmap: cat .planning/ROADMAP.md
```
**If user selects option 1:**
Invoke SlashCommand("/gsd:plan-phase {N}")
**If user selects option 2:**
Invoke SlashCommand("/gsd:add-phase <description>")
Note: Commands are shown in options above so user can see what will run.
</step>
</process>
<anti_patterns>
- Don't modify phases outside current milestone
- Don't renumber existing phases
- Don't use decimal numbering (that's /gsd:insert-phase)
- Don't create plans yet (that's /gsd:plan-phase)
- Don't commit changes (user decides when to commit)
</anti_patterns>
<success_criteria>
Phase addition is complete when:
- [ ] Phase directory created: `.planning/phases/{NN}-{slug}/`
- [ ] Roadmap updated with new phase entry
- [ ] STATE.md updated with roadmap evolution note
- [ ] New phase appears at end of current milestone
- [ ] Next phase number calculated correctly (ignoring decimals)
- [ ] User informed of next steps
</success_criteria>

105
commands/gsd/complete-milestone.md Normal file
View File

@@ -0,0 +1,105 @@
---
type: prompt
description: Archive completed milestone and prepare for next version
argument-hint: <version>
allowed-tools:
- Read
- Write
- Bash
---
<objective>
Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md.
Purpose: Create historical record of shipped version, collapse completed work in roadmap, and prepare for next milestone.
Output: Milestone archived, roadmap reorganized, git tagged.
</objective>
<execution_context>
**Load these files NOW (before proceeding):**
- @~/.claude/get-shit-done/workflows/complete-milestone.md (main workflow)
- @~/.claude/get-shit-done/templates/milestone-archive.md (archive template)
</execution_context>
<context>
**Project files:**
- `.planning/ROADMAP.md`
- `.planning/STATE.md`
- `.planning/PROJECT.md`
**User input:**
- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
</context>
<process>
**Follow complete-milestone.md workflow:**
1. **Verify readiness:**
- Check all phases in milestone have completed plans (SUMMARY.md exists)
- Present milestone scope and stats
- Wait for confirmation
2. **Gather stats:**
- Count phases, plans, tasks
- Calculate git range, file changes, LOC
- Extract timeline from git log
- Present summary, confirm
3. **Extract accomplishments:**
- Read all phase SUMMARY.md files in milestone range
- Extract 4-6 key accomplishments
- Present for approval
4. **Archive milestone:**
- Create `.planning/milestones/v{{version}}-ROADMAP.md`
- Extract full phase details from ROADMAP.md
- Fill milestone-archive.md template
- Update ROADMAP.md to one-line summary with link
- Offer to create next milestone
5. **Update PROJECT.md:**
- Add "Current State" section with shipped version
- Add "Next Milestone Goals" section
- Archive previous content in `<details>` (if v1.1+)
6. **Commit and tag:**
- Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive file
- Commit: `chore: archive v{{version}} milestone`
- Tag: `git tag -a v{{version}} -m "[milestone summary]"`
- Ask about pushing tag
7. **Offer next steps:**
- Plan next milestone
- Archive planning
- Done for now
</process>
<success_criteria>
- Milestone archived to `.planning/milestones/v{{version}}-ROADMAP.md`
- ROADMAP.md collapsed to one-line entry
- PROJECT.md updated with current state
- Git tag v{{version}} created
- Commit successful
- User knows next steps
</success_criteria>
<critical_rules>
- **Load workflow first:** Read complete-milestone.md before executing
- **Verify completion:** All phases must have SUMMARY.md files
- **User confirmation:** Wait for approval at verification gates
- **Archive before collapsing:** Always create archive file before updating ROADMAP.md
- **One-line summary:** Collapsed milestone in ROADMAP.md should be single line with link
- **Context efficiency:** Archive keeps ROADMAP.md constant size
</critical_rules>

45
commands/gsd/discuss-milestone.md Normal file
View File

@@ -0,0 +1,45 @@
---
description: Gather context for next milestone through adaptive questioning
---
<objective>
Use adaptive questioning to gather comprehensive milestone context before creating a new milestone.
Purpose: After completing a milestone, discuss the scope and focus of the next milestone before diving into phase creation. Builds understanding of goals, constraints, priorities, and lessons learned.
Output: Context gathered, then routes to /gsd:new-milestone
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/discuss-milestone.md
</execution_context>
<context>
**Load project state first:**
@.planning/STATE.md
**Load roadmap:**
@.planning/ROADMAP.md
**Load milestones (if exists):**
@.planning/MILESTONES.md
</context>
<process>
1. Verify previous milestone complete (or acknowledge active milestone)
2. Present context from previous milestone (accomplishments, phase count)
3. Follow discuss-milestone.md workflow:
- Ask about milestone theme/focus
- Ask about scope (estimated phases)
- Ask about constraints and priorities
- Ask about lessons from previous milestone
- Present decision gate (ready / ask more / let me add context)
4. Hand off to /gsd:new-milestone with gathered context
</process>
<success_criteria>
- Project state loaded and presented
- Previous milestone context summarized
- Milestone scope gathered through adaptive questioning
- Context handed off to /gsd:new-milestone
</success_criteria>

47
commands/gsd/discuss-phase.md Normal file
View File

@@ -0,0 +1,47 @@
---
description: Gather phase context through adaptive questioning before planning
argument-hint: "[phase]"
---
<objective>
Use adaptive questioning to gather comprehensive phase context before planning.
Purpose: Build deep understanding of objectives, constraints, risks, success indicators, and codebase state through structured intake flow. Creates CONTEXT.md file that informs high-quality planning.
Output: {phase}-CONTEXT.md in phase directory with complete context documentation
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/discuss-phase.md
@~/.claude/get-shit-done/templates/context.md
</execution_context>
<context>
Phase number: $ARGUMENTS (required)
**Load project state first:**
@.planning/STATE.md
**Load roadmap:**
@.planning/ROADMAP.md
</context>
<process>
1. Validate phase number argument (error if missing or invalid)
2. Check if phase exists in roadmap
3. Check if CONTEXT.md already exists (offer to update if yes)
4. Follow discuss-phase.md workflow:
- Present initial context from roadmap
- Analyze gaps in: objectives, constraints, risks, success indicators, codebase context
- Ask 2-4 questions about genuine gaps (skip what roadmap provides)
- Present decision gate (ready / ask more / let me add context)
- Create CONTEXT.md using template
5. Offer next steps (typically: plan the phase)
</process>
<success_criteria>
- Phase validated against roadmap
- Context gathered through adaptive questioning
- CONTEXT.md created in phase directory
- User knows next steps (plan phase, review context, or done)
</success_criteria>

108
commands/gsd/execute-plan.md Normal file
View File

@@ -0,0 +1,108 @@
---
description: Execute a PLAN.md file
argument-hint: "[path-to-PLAN.md]"
allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
- Task
- AskUserQuestion
---
<objective>
Execute a PLAN.md file, create SUMMARY.md, update project state, commit.
Uses intelligent segmentation:
- Plans without checkpoints → spawn subagent for full autonomous execution
- Plans with verify checkpoints → segment execution, pause at checkpoints
- Plans with decision checkpoints → execute in main context
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/execute-phase.md
@~/.claude/get-shit-done/templates/summary.md
@~/.claude/get-shit-done/references/checkpoints.md
</execution_context>
<context>
Plan path: $ARGUMENTS
**Load project state first:**
@.planning/STATE.md
**Load workflow config:**
@.planning/config.json
</context>
<process>
1. Check .planning/ directory exists (error if not - user should run /gsd:new-project)
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:
- Parse plan and determine execution strategy (A/B/C)
- Execute tasks (via subagent or main context as appropriate)
- Handle checkpoints and deviations
- Create SUMMARY.md
- Update STATE.md
- Commit changes
</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>
**Critical: Stage only files this plan actually modified.**
NEVER use:
- `git add .`
- `git add -A`
- `git add src/` or any broad directory
Stage each file individually from the modified-files list.
</commit_rules>
<success_criteria>
- [ ] All tasks executed
- [ ] SUMMARY.md created with substantive content
- [ ] STATE.md updated (position, decisions, issues, session)
- [ ] ROADMAP updated (plan count, phase status)
- [ ] Changes committed with feat({phase}-{plan}): [summary]
- [ ] User informed of next steps
</success_criteria>

252
commands/gsd/help.md Normal file
View File

@@ -0,0 +1,252 @@
---
description: Show available GSD commands and usage guide
---
<objective>
Display the complete GSD command reference.
Output ONLY the reference content below. Do NOT add:
- Project-specific analysis
- Git status or file context
- Next-step suggestions
- Any commentary beyond the reference
</objective>
<reference>
# GSD Command Reference
**GSD** (Get Shit Done) creates hierarchical project plans optimized for solo agentic development with Claude Code.
## Quick Start
1. `/gsd:new-project` - Initialize project with brief and roadmap
2. `/gsd:plan-phase <number>` - Create detailed plan for first phase
3. `/gsd:execute-plan <path>` - Execute the plan
## Core Workflow
```
Initialization → Planning → Execution → Milestone Completion
```
### Project Initialization
**`/gsd:new-project`**
Initialize new project with brief, roadmap, and state tracking.
- Creates `.planning/PROJECT.md` (vision and requirements)
- Creates `.planning/ROADMAP.md` (phase breakdown)
- Creates `.planning/STATE.md` (project memory)
- Creates `.planning/config.json` (workflow mode)
- Asks for workflow mode (interactive/yolo) upfront
- Commits all initialization files to git
Usage: `/gsd:new-project`
### Phase Planning
**`/gsd:discuss-phase <number>`**
Gather phase context through adaptive questioning before planning.
- Builds understanding of objectives, constraints, risks
- Creates CONTEXT.md in phase directory
- Use before planning unfamiliar or complex phases
Usage: `/gsd:discuss-phase 2`
**`/gsd:list-phase-assumptions <number>`**
Surface Claude's assumptions about a phase before planning.
- Shows what Claude thinks about technical approach, scope, risks
- Enables early course correction before planning begins
- No files created - conversational output only
Usage: `/gsd:list-phase-assumptions 3`
**`/gsd:plan-phase <number>`**
Create detailed execution plan for a specific phase.
- Generates `.planning/phases/XX-phase-name/XX-YY-PLAN.md`
- Breaks phase into concrete, actionable tasks
- Includes verification criteria and success measures
- Multiple plans per phase supported (XX-01, XX-02, etc.)
Usage: `/gsd:plan-phase 1`
Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
### Execution
**`/gsd:execute-plan <path>`**
Execute a PLAN.md file directly.
- Runs plan tasks sequentially
- Creates SUMMARY.md after completion
- Updates STATE.md with accumulated context
- Fast execution without loading full skill context
Usage: `/gsd:execute-plan .planning/phases/01-foundation/01-01-PLAN.md`
### Roadmap Management
**`/gsd:add-phase <description>`**
Add new phase to end of current milestone.
- Appends to ROADMAP.md
- Uses next sequential number
- Updates phase directory structure
Usage: `/gsd:add-phase "Add admin dashboard"`
**`/gsd:insert-phase <after> <description>`**
Insert urgent work as decimal phase between existing phases.
- Creates intermediate phase (e.g., 7.1 between 7 and 8)
- Useful for discovered work that must happen mid-milestone
- Maintains phase ordering
Usage: `/gsd:insert-phase 7 "Fix critical auth bug"`
Result: Creates Phase 7.1
### Milestone Management
**`/gsd:discuss-milestone`**
Gather context for next milestone through adaptive questioning.
- Reviews previous milestone accomplishments
- Asks about scope, constraints, priorities for next milestone
- Routes to /gsd:new-milestone when ready
Usage: `/gsd:discuss-milestone`
**`/gsd:new-milestone <name>`**
Create a new milestone with phases for an existing project.
- Adds milestone section to ROADMAP.md
- Creates phase directories
- Updates STATE.md for new milestone
Usage: `/gsd:new-milestone "v2.0 Features"`
**`/gsd:complete-milestone <version>`**
Archive completed milestone and prepare for next version.
- Creates MILESTONES.md entry with stats
- Archives full details to milestones/ directory
- Creates git tag for the release
- Prepares workspace for next version
Usage: `/gsd:complete-milestone 1.0.0`
### Progress Tracking
**`/gsd:progress`**
Check project status and intelligently route to next action.
- Shows visual progress bar and completion percentage
- Summarizes recent work from SUMMARY files
- Displays current position and what's next
- Lists key decisions and open issues
- Offers to execute next plan or create it if missing
- Detects 100% milestone completion
Usage: `/gsd:progress`
### Session Management
**`/gsd:resume-work`**
Resume work from previous session with full context restoration.
- Reads STATE.md for project context
- Shows current position and recent progress
- Offers next actions based on project state
Usage: `/gsd:resume-work`
**`/gsd:pause-work`**
Create context handoff when pausing work mid-phase.
- Creates .continue-here file with current state
- Updates STATE.md session continuity section
- Captures in-progress work context
Usage: `/gsd:pause-work`
### Utility Commands
**`/gsd:help`**
Show this command reference.
## Files & Structure
```
.planning/
├── PROJECT.md # Project vision
├── ROADMAP.md # Current phase breakdown
├── STATE.md # Project memory & context
├── config.json # Workflow mode & gates
└── phases/
├── 01-foundation/
│ ├── 01-01-PLAN.md
│ └── 01-01-SUMMARY.md
└── 02-core-features/
├── 02-01-PLAN.md
└── 02-01-SUMMARY.md
```
## Workflow Modes
Set during `/gsd:new-project`:
**Interactive Mode**
- Confirms each major decision
- Pauses at checkpoints for approval
- More guidance throughout
**YOLO Mode**
- Auto-approves most decisions
- Executes plans without confirmation
- Only stops for critical checkpoints
Change anytime by editing `.planning/config.json`
## Common Workflows
**Starting a new project:**
```
/gsd:new-project
/gsd:plan-phase 1
/gsd:execute-plan .planning/phases/01-foundation/01-01-PLAN.md
```
**Resuming work after a break:**
```
/gsd:progress # See where you left off and continue
```
**Adding urgent mid-milestone work:**
```
/gsd:insert-phase 5 "Critical security fix"
/gsd:plan-phase 5.1
/gsd:execute-plan .planning/phases/05.1-critical-security-fix/05.1-01-PLAN.md
```
**Completing a milestone:**
```
/gsd:complete-milestone 1.0.0
/gsd:new-project # Start next milestone
```
## Getting Help
- Read `.planning/PROJECT.md` for project vision
- Read `.planning/STATE.md` for current context
- Check `.planning/ROADMAP.md` for phase status
- Run `/gsd:progress` to check where you're up to
</reference>

218
commands/gsd/insert-phase.md Normal file
View File

@@ -0,0 +1,218 @@
---
description: Insert urgent work as decimal phase (e.g., 72.1) between existing phases
argument-hint: <after> <description>
allowed-tools:
- Read
- Write
- Bash
---
<objective>
Insert a decimal phase for urgent work discovered mid-milestone that must be completed between existing integer phases.
Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions.
Purpose: Handle urgent work discovered during execution without renumbering entire roadmap.
</objective>
<execution_context>
@.planning/ROADMAP.md
@.planning/STATE.md
</execution_context>
<process>
<step name="parse_arguments">
Parse the command arguments:
- First argument: integer phase number to insert after
- Remaining arguments: phase description
Example: `/gsd:insert-phase 72 Fix critical auth bug`
→ after = 72
→ description = "Fix critical auth bug"
Validation:
```bash
if [ $# -lt 2 ]; then
echo "ERROR: Both phase number and description required"
echo "Usage: /gsd:insert-phase <after> <description>"
echo "Example: /gsd:insert-phase 72 Fix critical auth bug"
exit 1
fi
```
Parse first argument as integer:
```bash
after_phase=$1
shift
description="$*"
# Validate after_phase is an integer
if ! [[ "$after_phase" =~ ^[0-9]+$ ]]; then
echo "ERROR: Phase number must be an integer"
exit 1
fi
```
</step>
<step name="load_roadmap">
Load the roadmap file:
```bash
if [ -f .planning/ROADMAP.md ]; then
ROADMAP=".planning/ROADMAP.md"
else
echo "ERROR: No roadmap found (.planning/ROADMAP.md)"
exit 1
fi
```
Read roadmap content for parsing.
</step>
<step name="verify_target_phase">
Verify that the target phase exists in the roadmap:
1. Search for "### Phase {after_phase}:" heading
2. If not found:
```
ERROR: Phase {after_phase} not found in roadmap
Available phases: [list phase numbers]
```
Exit.
3. Verify phase is in current milestone (not completed/archived)
</step>
<step name="find_existing_decimals">
Find existing decimal phases after the target phase:
1. Search for all "### Phase {after_phase}.N:" headings
2. Extract decimal suffixes (e.g., for Phase 72: find 72.1, 72.2, 72.3)
3. Find the highest decimal suffix
4. Calculate next decimal: max + 1
Examples:
- Phase 72 with no decimals → next is 72.1
- Phase 72 with 72.1 → next is 72.2
- Phase 72 with 72.1, 72.2 → next is 72.3
Store as: `decimal_phase="${after_phase}.${next_decimal}"`
</step>
<step name="generate_slug">
Convert the phase description to a kebab-case slug:
```bash
slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
```
Phase directory name: `{decimal-phase}-{slug}`
Example: `72.1-fix-critical-auth-bug`
</step>
<step name="create_phase_directory">
Create the phase directory structure:
```bash
phase_dir=".planning/phases/${decimal_phase}-${slug}"
mkdir -p "$phase_dir"
```
Confirm: "Created directory: $phase_dir"
</step>
<step name="update_roadmap">
Insert the new phase entry into the roadmap:
1. Find insertion point: immediately after Phase {after_phase}'s content (before next phase heading or "---")
2. Insert new phase heading with (INSERTED) marker:
```
### Phase {decimal_phase}: {Description} (INSERTED)
**Goal:** [Urgent work - to be planned]
**Depends on:** Phase {after_phase}
**Plans:** 0 plans
Plans:
- [ ] TBD (run /gsd:plan-phase {decimal_phase} to break down)
**Details:**
[To be added during planning]
```
3. Write updated roadmap back to file
The "(INSERTED)" marker helps identify decimal phases as urgent insertions.
Preserve all other content exactly (formatting, spacing, other phases).
</step>
<step name="update_project_state">
Update STATE.md to reflect the inserted phase:
1. Read `.planning/STATE.md`
2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
```
- Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)
```
If "Roadmap Evolution" section doesn't exist, create it.
Add note about insertion reason if appropriate.
</step>
<step name="completion">
Present completion summary:
```
Phase {decimal_phase} inserted after Phase {after_phase}:
- Description: {description}
- Directory: .planning/phases/{decimal-phase}-{slug}/
- Status: Not planned yet
- Marker: (INSERTED) - indicates urgent work
Roadmap updated: {roadmap-path}
Project state updated: .planning/STATE.md
What's next?
1. Plan this phase: /gsd:plan-phase {decimal_phase}
2. Review insertion impact: Check if Phase {next_integer} dependencies still make sense
3. Review roadmap: cat .planning/ROADMAP.md
```
**If user selects option 1:**
Invoke SlashCommand("/gsd:plan-phase {decimal_phase}")
Note: Command is shown in option 1 above so user can see what will run.
</step>
</process>
<anti_patterns>
- Don't use this for planned work at end of milestone (use /gsd:add-phase)
- Don't insert before Phase 1 (decimal 0.1 makes no sense)
- Don't renumber existing phases
- Don't modify the target phase content
- Don't create plans yet (that's /gsd:plan-phase)
- Don't commit changes (user decides when to commit)
</anti_patterns>
<success_criteria>
Phase insertion is complete when:
- [ ] Phase directory created: `.planning/phases/{N.M}-{slug}/`
- [ ] Roadmap updated with new phase entry (includes "(INSERTED)" marker)
- [ ] Phase inserted in correct position (after target phase, before next integer phase)
- [ ] STATE.md updated with roadmap evolution note
- [ ] Decimal number calculated correctly (based on existing decimals)
- [ ] User informed of next steps and dependency implications
</success_criteria>

49
commands/gsd/list-phase-assumptions.md Normal file
View File

@@ -0,0 +1,49 @@
---
description: Surface Claude's assumptions about a phase approach before planning
argument-hint: "[phase]"
allowed-tools:
- Read
- Bash
- Grep
- Glob
---
<objective>
Analyze a phase and present Claude's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
Purpose: Help users see what Claude thinks BEFORE planning begins - enabling course correction early when assumptions are wrong.
Output: Conversational output only (no file creation) - ends with "What do you think?" prompt
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/list-phase-assumptions.md
</execution_context>
<context>
Phase number: $ARGUMENTS (required)
**Load project state first:**
@.planning/STATE.md
**Load roadmap:**
@.planning/ROADMAP.md
</context>
<process>
1. Validate phase number argument (error if missing or invalid)
2. Check if phase exists in roadmap
3. Follow list-phase-assumptions.md workflow:
- Analyze roadmap description
- Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
- Present assumptions clearly
- Prompt "What do you think?"
4. Gather feedback and offer next steps
</process>
<success_criteria>
- Phase validated against roadmap
- Assumptions surfaced across five areas
- User prompted for feedback
- User knows next steps (discuss context, plan phase, or correct assumptions)
</success_criteria>

58
commands/gsd/new-milestone.md Normal file
View File

@@ -0,0 +1,58 @@
---
description: Create a new milestone with phases for an existing project
argument-hint: "[milestone name, e.g., 'v2.0 Features']"
---
<objective>
Create a new milestone for an existing project with defined phases.
Purpose: After completing a milestone (or when ready to define next chunk of work), creates the milestone structure in ROADMAP.md with phases, updates STATE.md, and creates phase directories.
Output: New milestone in ROADMAP.md, updated STATE.md, phase directories created
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/create-milestone.md
@~/.claude/get-shit-done/templates/roadmap.md
</execution_context>
<context>
Milestone name: $ARGUMENTS (optional - will prompt if not provided)
**Load project state first:**
@.planning/STATE.md
**Load roadmap:**
@.planning/ROADMAP.md
**Load milestones (if exists):**
@.planning/MILESTONES.md
</context>
<process>
1. Load project context (STATE.md, ROADMAP.md, MILESTONES.md)
2. Calculate next milestone version and starting phase number
3. If milestone name provided in arguments, use it; otherwise prompt
4. Gather phases (3-6 recommended):
- If called from /gsd:discuss-milestone, use provided context
- Otherwise, prompt for phase breakdown
5. Detect research needs for each phase
6. Confirm phases (respect config.json gate settings)
7. Follow create-milestone.md workflow:
- Update ROADMAP.md with new milestone section
- Create phase directories
- Update STATE.md for new milestone
- Git commit milestone creation
8. Offer next steps (discuss first phase, plan first phase, review)
</process>
<success_criteria>
- Next phase number calculated correctly (continues from previous milestone)
- 3-6 phases defined with clear names
- Research flags assigned for each phase
- ROADMAP.md updated with new milestone section
- Phase directories created
- STATE.md reset for new milestone
- Git commit made
- User knows next steps
</success_criteria>

177
commands/gsd/new-project.md Normal file
View File

@@ -0,0 +1,177 @@
---
description: Initialize a new project with deep context gathering, PROJECT.md, roadmap, and state tracking
allowed-tools:
- Read
- Bash
- Write
- AskUserQuestion
---
<!--
DESIGN NOTE: Command + Workflow Pattern
This command handles the questioning phase directly (user interaction intensive),
then delegates roadmap/state creation to the create-roadmap workflow.
Architecture:
- Command: new-project.md - questioning, PROJECT.md, config.json
- Workflow: create-roadmap.md - domain detection, research flags, ROADMAP.md, STATE.md
-->
<objective>
Initialize a new project through comprehensive context gathering.
This is the most leveraged moment in any project. Deep questioning here means better plans, better execution, better outcomes.
Creates `.planning/` with PROJECT.md, ROADMAP.md, STATE.md, and config.json.
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/create-roadmap.md
@~/.claude/get-shit-done/references/principles.md
@~/.claude/get-shit-done/references/questioning.md
@~/.claude/get-shit-done/templates/project.md
@~/.claude/get-shit-done/templates/config.json
</execution_context>
<context>
!`[ -d .planning ] && echo "PLANNING_EXISTS" || echo "NO_PLANNING"`
!`[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"`
</context>
<process>
<step name="setup" silent="true">
Silent setup - execute before any user output:
```bash
# Abort if project exists
[ -d .planning ] && echo "Project already initialized. Use /gsd:progress" && exit 1
# Initialize git
[ -d .git ] || git init
```
</step>
<step name="question">
Start: "What do you want to build?"
Then use AskUserQuestion to cover the 9 domains (project type, problem, audience, success, constraints, scope, current state, decisions, open questions).
Skip domains already clear from user input. Probe for specifics on vague answers.
**Decision gate (MUST have all 3 options):**
```
Header: "Ready?"
Options:
1. "Create PROJECT.md" - Finalize
2. "Ask more questions" - Dig into uncovered domains
3. "Let me add context" - User shares more
```
If "Ask more questions" → ask about 2-3 uncovered domains → return to gate.
Loop until "Create PROJECT.md" selected.
</step>
<step name="project">
Synthesize all context into `.planning/PROJECT.md` using the template from `templates/project.md`.
Do not compress. Capture everything gathered.
</step>
<step name="mode">
Ask workflow mode preference:
Use AskUserQuestion:
- header: "Mode"
- question: "How do you want to work?"
- options:
- "Interactive" - Confirm at each step
- "YOLO" - Auto-approve, just execute
Create `.planning/config.json` with chosen mode using `templates/config.json` structure.
</step>
<step name="roadmap_and_state">
**Follow the create-roadmap workflow** from `@~/.claude/get-shit-done/workflows/create-roadmap.md`.
This handles:
1. Domain expertise detection (scan for applicable skills)
2. Phase identification (3-6 phases based on PROJECT.md)
3. Research needs detection (flag phases needing investigation)
4. Phase confirmation (respects yolo/interactive mode)
5. ROADMAP.md creation with research flags
6. STATE.md initialization
7. Phase directory creation
The workflow will create:
- `.planning/ROADMAP.md`
- `.planning/STATE.md`
- `.planning/phases/XX-name/` directories
</step>
<step name="commit">
```bash
git add .planning/
git commit -m "$(cat <<'EOF'
docs: initialize [project-name] ([N] phases)
[One-liner from PROJECT.md]
Phases:
1. [phase-name]: [goal]
2. [phase-name]: [goal]
3. [phase-name]: [goal]
EOF
)"
```
</step>
<step name="done">
```
Project initialized:
- Project: .planning/PROJECT.md
- Roadmap: .planning/ROADMAP.md ([N] phases)
- State: .planning/STATE.md
- Config: .planning/config.json (mode: [chosen mode])
What's next?
1. Plan Phase 1 (/gsd:plan-phase 01)
2. Review project setup
3. Done for now
```
If user selects "Plan Phase 1" → invoke `/gsd:plan-phase 01`
</step>
</process>
<output>
- `.planning/PROJECT.md`
- `.planning/ROADMAP.md`
- `.planning/STATE.md`
- `.planning/config.json`
- `.planning/phases/XX-name/` directories
</output>
<success_criteria>
- [ ] Deep questioning completed (not rushed)
- [ ] PROJECT.md captures full context
- [ ] config.json has workflow mode
- [ ] ROADMAP.md has 3-6 phases with research flags
- [ ] STATE.md initialized with project summary
- [ ] Phase directories created
- [ ] All committed to git
</success_criteria>
```

123
commands/gsd/pause-work.md Normal file
View File

@@ -0,0 +1,123 @@
---
description: Create context handoff when pausing work mid-phase
allowed-tools:
- Read
- Write
- Bash
---
<objective>
Create `.continue-here.md` handoff file to preserve complete work state across sessions.
Enables seamless resumption in fresh session with full context restoration.
</objective>
<context>
@.planning/STATE.md
Current phase: !`ls -lt .planning/phases/*/*.md 2>/dev/null | head -1`
</context>
<process>
<step name="detect">
Find current phase directory from most recently modified files.
</step>
<step name="gather">
**Collect complete state for handoff:**
1. **Current position**: Which phase, which plan, which task
2. **Work completed**: What got done this session
3. **Work remaining**: What's left in current plan/phase
4. **Decisions made**: Key decisions and rationale
5. **Blockers/issues**: Anything stuck
6. **Mental context**: The approach, next steps, "vibe"
7. **Files modified**: What's changed but not committed
Ask user for clarifications if needed.
</step>
<step name="write">
**Write handoff to `.planning/phases/XX-name/.continue-here.md`:**
```markdown
---
phase: XX-name
task: 3
total_tasks: 7
status: in_progress
last_updated: [timestamp]
---
<current_state>
[Where exactly are we? Immediate context]
</current_state>
<completed_work>
- Task 1: [name] - Done
- Task 2: [name] - Done
- Task 3: [name] - In progress, [what's done]
</completed_work>
<remaining_work>
- Task 3: [what's left]
- Task 4: Not started
- Task 5: Not started
</remaining_work>
<decisions_made>
- Decided to use [X] because [reason]
- Chose [approach] over [alternative] because [reason]
</decisions_made>
<blockers>
- [Blocker 1]: [status/workaround]
</blockers>
<context>
[Mental state, what were you thinking, the plan]
</context>
<next_action>
Start with: [specific first action when resuming]
</next_action>
```
Be specific enough for a fresh Claude to understand immediately.
</step>
<step name="commit">
```bash
git add .planning/phases/*/.continue-here.md
git commit -m "wip: [phase-name] paused at task [X]/[Y]"
```
</step>
<step name="confirm">
```
✓ Handoff created: .planning/phases/[XX-name]/.continue-here.md
Current state:
- Phase: [XX-name]
- Task: [X] of [Y]
- Status: [in_progress/blocked]
- Committed as WIP
To resume: /gsd:resume-work
```
</step>
</process>
<success_criteria>
- [ ] .continue-here.md created in correct phase directory
- [ ] All sections filled with specific content
- [ ] Committed as WIP
- [ ] User knows location and how to resume
</success_criteria>
```

60
commands/gsd/plan-phase.md Normal file
View File

@@ -0,0 +1,60 @@
---
description: Create detailed execution plan for a phase (PLAN.md)
argument-hint: "[phase]"
allowed-tools:
- Read
- Bash
- Write
- Glob
- Grep
- AskUserQuestion
- WebFetch
- mcp__context7__*
---
<objective>
Create executable phase prompt with discovery, context injection, and task breakdown.
Purpose: Break down roadmap phases into concrete, executable PLAN.md files that Claude can execute.
Output: One or more PLAN.md files in the phase directory (.planning/phases/XX-name/{phase}-{plan}-PLAN.md)
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/plan-phase.md
@~/.claude/get-shit-done/templates/phase-prompt.md
@~/.claude/get-shit-done/references/plan-format.md
@~/.claude/get-shit-done/references/scope-estimation.md
@~/.claude/get-shit-done/references/checkpoints.md
@~/.claude/get-shit-done/references/cli-automation.md
</execution_context>
<context>
Phase number: $ARGUMENTS (optional - auto-detects next unplanned phase if not provided)
**Load project state first:**
@.planning/STATE.md
**Load roadmap:**
@.planning/ROADMAP.md
</context>
<process>
1. Check .planning/ directory exists (error if not - user should run /gsd:new-project)
2. If phase number provided via $ARGUMENTS, validate it exists in roadmap
3. If no phase number, detect next unplanned phase from roadmap
4. Follow plan-phase.md workflow:
- Load project state and accumulated decisions
- Perform mandatory discovery (Level 0-3 as appropriate)
- Read project history (prior decisions, issues, concerns)
- Break phase into tasks
- Estimate scope and split into multiple plans if needed
- Create PLAN.md file(s) with executable structure
</process>
<success_criteria>
- One or more PLAN.md files created in .planning/phases/XX-name/
- Each plan has: objective, execution_context, context, tasks, verification, success_criteria, output
- Tasks are specific enough for Claude to execute
- User knows next steps (execute plan or review/adjust)
</success_criteria>

182
commands/gsd/progress.md Normal file
View File

@@ -0,0 +1,182 @@
---
description: Check project progress, show context, and route to next action (execute or plan)
allowed-tools:
- Read
- Bash
- Grep
- Glob
- SlashCommand
---
<objective>
Check project progress, summarize recent work and what's ahead, then intelligently route to the next action - either executing an existing plan or creating the next one.
Provides situational awareness before continuing work.
</objective>
<context>
Planning structure: !`ls -la .planning/ 2>/dev/null || echo "NO_PLANNING_STRUCTURE"`
Phases: !`ls .planning/phases/ 2>/dev/null || echo "NO_PHASES"`
State exists: !`[ -f .planning/STATE.md ] && echo "EXISTS" || echo "MISSING"`
Roadmap exists: !`[ -f .planning/ROADMAP.md ] && echo "EXISTS" || echo "MISSING"`
Recent summaries: !`find .planning/phases -name "*-SUMMARY.md" -type f 2>/dev/null | sort | tail -3`
All plans: !`find .planning/phases -name "*-PLAN.md" -type f 2>/dev/null | sort`
All summaries: !`find .planning/phases -name "*-SUMMARY.md" -type f 2>/dev/null | sort`
</context>
<process>
<step name="verify">
**Verify planning structure exists:**
If no `.planning/` directory:
```
No planning structure found.
Run /gsd:new-project to start a new project.
```
Exit.
If missing STATE.md or ROADMAP.md: inform what's missing, suggest running `/gsd:new-project`.
</step>
<step name="load">
**Load full project context:**
- Read `.planning/STATE.md` for living memory (position, decisions, issues)
- Read `.planning/ROADMAP.md` for phase structure and objectives
- Read `.planning/PROJECT.md` for project vision (brief summary only)
</step>
<step name="recent">
**Gather recent work context:**
- Find the 2-3 most recent SUMMARY.md files
- Extract from each: what was accomplished, key decisions, any issues logged
- This shows "what we've been working on"
</step>
<step name="position">
**Parse current position:**
- From STATE.md: current phase, plan number, status
- Calculate: total plans, completed plans, remaining plans
- Note any blockers, concerns, or deferred issues
- Check for CONTEXT.md: For phases without PLAN.md files, check if `{phase}-CONTEXT.md` exists in phase directory
</step>
<step name="report">
**Present rich status report:**
```
# [Project Name]
**Progress:** [████████░░] 8/10 plans complete
## Recent Work
- [Phase X, Plan Y]: [what was accomplished - 1 line]
- [Phase X, Plan Z]: [what was accomplished - 1 line]
## Current Position
Phase [N] of [total]: [phase-name]
Plan [M] of [phase-total]: [status]
CONTEXT: [✓ if CONTEXT.md exists | - if not]
## Key Decisions Made
- [decision 1 from STATE.md]
- [decision 2]
## Open Issues
- [any deferred issues or blockers]
## What's Next
[Next phase/plan objective from ROADMAP]
```
</step>
<step name="route">
**Determine next action:**
Find the next plan number that needs work.
Check if `{phase}-{plan}-PLAN.md` exists for that number.
**If PLAN.md exists (unexecuted):**
- Read its `<objective>` section
- Show: "Ready to execute: [path] - [objective summary]"
- Ask: "Execute? (y/n)"
- **CRITICAL: If user responds "y", "yes", or affirmatively, immediately invoke:**
```
SlashCommand("/gsd:execute-plan [full-path-to-PLAN.md]")
```
Do NOT describe what you would do. INVOKE THE TOOL.
**If PLAN.md does NOT exist:**
- Check if `{phase}-CONTEXT.md` exists in phase directory
- Show: "Next plan not yet created: [expected path]"
- Show phase objective from ROADMAP
**If CONTEXT.md exists:**
- Display: "✓ Context gathered, ready to plan"
- Ask: "Create this plan? (y/n)"
- **CRITICAL: If user responds "y", "yes", or affirmatively, immediately invoke:**
```
SlashCommand("/gsd:plan-phase [phase-number]")
```
Do NOT describe what you would do. INVOKE THE TOOL.
**If CONTEXT.md does NOT exist:**
- Display options:
```
Options for Phase [N]:
1. See assumptions (/gsd:list-phase-assumptions [phase]) - What Claude thinks about this phase
2. Discuss context (/gsd:discuss-phase [phase]) - Gather your context through questions
3. Plan directly (/gsd:plan-phase [phase]) - Skip to planning
```
- Ask: "Which approach? (assumptions/discuss/plan)"
- **If user responds "assumptions":**
```
SlashCommand("/gsd:list-phase-assumptions [phase-number]")
```
- **If user responds "discuss":**
```
SlashCommand("/gsd:discuss-phase [phase-number]")
```
- **If user responds "plan":**
```
SlashCommand("/gsd:plan-phase [phase-number]")
```
**If all plans complete for current phase:**
- Check if more phases exist in ROADMAP
- If yes: Offer to plan next phase with `/gsd:plan-phase [next-phase]`
- If no (milestone 100% complete): Offer to complete milestone
</step>
<step name="edge_cases">
**Handle edge cases:**
- Phase complete but next phase not planned → offer `/gsd:plan-phase [next]`
- All work complete → offer milestone completion
- Blockers present → highlight before offering to continue
- Handoff file exists → mention it, offer `/gsd:resume-work`
</step>
</process>
<success_criteria>
- [ ] Rich context provided (recent work, decisions, issues)
- [ ] Current position clear with visual progress
- [ ] What's next clearly explained
- [ ] Smart routing: /gsd:execute-plan if plan exists, /gsd:plan-phase if not
- [ ] User confirms before any action
- [ ] Seamless handoff to appropriate gsd command
</success_criteria>

50
commands/gsd/resume-work.md Normal file
View File

@@ -0,0 +1,50 @@
---
description: Resume work from previous session with full context restoration
allowed-tools:
- Read
- Bash
- Write
- AskUserQuestion
- SlashCommand
---
<!--
DESIGN NOTE: Command + Workflow Pattern
This command is a thin wrapper that routes to the resume-project workflow.
All resumption logic lives in the workflow for maintainability.
Architecture:
- Command: resume-work.md - entry point only
- Workflow: resume-project.md - all resumption logic
-->
<objective>
Restore complete project context and resume work seamlessly from previous session.
Routes to the resume-project workflow which handles:
- STATE.md loading (or reconstruction if missing)
- Checkpoint detection (.continue-here files)
- Incomplete work detection (PLAN without SUMMARY)
- Status presentation
- Context-aware next action routing
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/resume-project.md
</execution_context>
<process>
**Follow the resume-project workflow** from `@~/.claude/get-shit-done/workflows/resume-project.md`.
The workflow handles all resumption logic including:
1. Project existence verification
2. STATE.md loading or reconstruction
3. Checkpoint and incomplete work detection
4. Visual status presentation
5. Context-aware option offering (checks CONTEXT.md before suggesting plan vs discuss)
6. Routing to appropriate next command
7. Session continuity updates
</process>

594
get-shit-done/references/checkpoints.md Normal file
View File

@@ -0,0 +1,594 @@
<overview>
Plans execute autonomously. Checkpoints formalize the interaction points where human verification or decisions are needed.
**Core principle:** Claude automates everything with CLI/API. Checkpoints are for verification and decisions, not manual work.
</overview>
<checkpoint_types>
<type name="human-verify">
## checkpoint:human-verify (Most Common)
**When:** Claude completed automated work, human confirms it works correctly.
**Use for:**
- Visual UI checks (layout, styling, responsiveness)
- Interactive flows (click through wizard, test user flows)
- Functional verification (feature works as expected)
- Audio/video playback quality
- Animation smoothness
- Accessibility testing
**Structure:**
```xml
<task type="checkpoint:human-verify" gate="blocking">
<what-built>[What Claude automated and deployed/built]</what-built>
<how-to-verify>
[Exact steps to test - URLs, commands, expected behavior]
</how-to-verify>
<resume-signal>[How to continue - "approved", "yes", or describe issues]</resume-signal>
</task>
```
**Key elements:**
- `<what-built>`: What Claude automated (deployed, built, configured)
- `<how-to-verify>`: Exact steps to confirm it works (numbered, specific)
- `<resume-signal>`: Clear indication of how to continue
**Example: Vercel Deployment**
```xml
<task type="auto">
<name>Deploy to Vercel</name>
<files>.vercel/, vercel.json</files>
<action>Run `vercel --yes` to create project and deploy. Capture deployment URL from output.</action>
<verify>vercel ls shows deployment, curl {url} returns 200</verify>
<done>App deployed, URL captured</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Deployed to Vercel at https://myapp-abc123.vercel.app</what-built>
<how-to-verify>
Visit https://myapp-abc123.vercel.app and confirm:
- Homepage loads without errors
- Login form is visible
- No console errors in browser DevTools
</how-to-verify>
<resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal>
</task>
```
**Example: UI Component**
```xml
<task type="auto">
<name>Build responsive dashboard layout</name>
<files>src/components/Dashboard.tsx, src/app/dashboard/page.tsx</files>
<action>Create dashboard with sidebar, header, and content area. Use Tailwind responsive classes for mobile.</action>
<verify>npm run build succeeds, no TypeScript errors</verify>
<done>Dashboard component builds without errors</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Responsive dashboard layout at /dashboard</what-built>
<how-to-verify>
1. Run: npm run dev
2. Visit: http://localhost:3000/dashboard
3. Desktop (>1024px): Verify sidebar left, content right, header top
4. Tablet (768px): Verify sidebar collapses to hamburger
5. Mobile (375px): Verify single column, bottom nav
6. Check: No layout shift, no horizontal scroll
</how-to-verify>
<resume-signal>Type "approved" or describe layout issues</resume-signal>
</task>
```
**Example: Xcode Build**
```xml
<task type="auto">
<name>Build macOS app with Xcode</name>
<files>App.xcodeproj, Sources/</files>
<action>Run `xcodebuild -project App.xcodeproj -scheme App build`. Check for compilation errors in output.</action>
<verify>Build output contains "BUILD SUCCEEDED", no errors</verify>
<done>App builds successfully</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Built macOS app at DerivedData/Build/Products/Debug/App.app</what-built>
<how-to-verify>
Open App.app and test:
- App launches without crashes
- Menu bar icon appears
- Preferences window opens correctly
- No visual glitches or layout issues
</how-to-verify>
<resume-signal>Type "approved" or describe issues</resume-signal>
</task>
```
</type>
<type name="decision">
## checkpoint:decision
**When:** Human must make choice that affects implementation direction.
**Use for:**
- Technology selection (which auth provider, which database)
- Architecture decisions (monorepo vs separate repos)
- Design choices (color scheme, layout approach)
- Feature prioritization (which variant to build)
- Data model decisions (schema structure)
**Structure:**
```xml
<task type="checkpoint:decision" gate="blocking">
<decision>[What's being decided]</decision>
<context>[Why this decision matters]</context>
<options>
<option id="option-a">
<name>[Option name]</name>
<pros>[Benefits]</pros>
<cons>[Tradeoffs]</cons>
</option>
<option id="option-b">
<name>[Option name]</name>
<pros>[Benefits]</pros>
<cons>[Tradeoffs]</cons>
</option>
</options>
<resume-signal>[How to indicate choice]</resume-signal>
</task>
```
**Key elements:**
- `<decision>`: What's being decided
- `<context>`: Why this matters
- `<options>`: Each option with balanced pros/cons (not prescriptive)
- `<resume-signal>`: How to indicate choice
**Example: Auth Provider Selection**
```xml
<task type="checkpoint:decision" gate="blocking">
<decision>Select authentication provider</decision>
<context>
Need user authentication for the app. Three solid options with different tradeoffs.
</context>
<options>
<option id="supabase">
<name>Supabase Auth</name>
<pros>Built-in with Supabase DB we're using, generous free tier, row-level security integration</pros>
<cons>Less customizable UI, tied to Supabase ecosystem</cons>
</option>
<option id="clerk">
<name>Clerk</name>
<pros>Beautiful pre-built UI, best developer experience, excellent docs</pros>
<cons>Paid after 10k MAU, vendor lock-in</cons>
</option>
<option id="nextauth">
<name>NextAuth.js</name>
<pros>Free, self-hosted, maximum control, widely adopted</pros>
<cons>More setup work, you manage security updates, UI is DIY</cons>
</option>
</options>
<resume-signal>Select: supabase, clerk, or nextauth</resume-signal>
</task>
```
</type>
<type name="human-action">
## checkpoint:human-action (Rare)
**When:** Action has NO CLI/API and requires human-only interaction, OR Claude hit an authentication gate during automation.
**Use ONLY for:**
- **Authentication gates** - Claude tried to use CLI/API but needs credentials to continue (this is NOT a failure)
- Email verification links (account creation requires clicking email)
- SMS 2FA codes (phone verification)
- Manual account approvals (platform requires human review before API access)
- Credit card 3D Secure flows (web-based payment authorization)
- OAuth app approvals (some platforms require web-based approval)
**Do NOT use for pre-planned manual work:**
- Manually deploying to Vercel (use `vercel` CLI - auth gate if needed)
- Manually creating Stripe webhooks (use Stripe API - auth gate if needed)
- Manually creating databases (use provider CLI - auth gate if needed)
- Running builds/tests manually (use Bash tool)
- Creating files manually (use Write tool)
**Structure:**
```xml
<task type="checkpoint:human-action" gate="blocking">
<action>[What human must do - Claude already did everything automatable]</action>
<instructions>
[What Claude already automated]
[The ONE thing requiring human action]
</instructions>
<verification>[What Claude can check afterward]</verification>
<resume-signal>[How to continue]</resume-signal>
</task>
```
**Key principle:** Claude automates EVERYTHING possible first, only asks human for the truly unavoidable manual step.
**Example: Email Verification**
```xml
<task type="auto">
<name>Create SendGrid account via API</name>
<action>Use SendGrid API to create subuser account with provided email. Request verification email.</action>
<verify>API returns 201, account created</verify>
<done>Account created, verification email sent</done>
</task>
<task type="checkpoint:human-action" gate="blocking">
<action>Complete email verification for SendGrid account</action>
<instructions>
I created the account and requested verification email.
Check your inbox for SendGrid verification link and click it.
</instructions>
<verification>SendGrid API key works: curl test succeeds</verification>
<resume-signal>Type "done" when email verified</resume-signal>
</task>
```
**Example: Credit Card 3D Secure**
```xml
<task type="auto">
<name>Create Stripe payment intent</name>
<action>Use Stripe API to create payment intent for $99. Generate checkout URL.</action>
<verify>Stripe API returns payment intent ID and URL</verify>
<done>Payment intent created</done>
</task>
<task type="checkpoint:human-action" gate="blocking">
<action>Complete 3D Secure authentication</action>
<instructions>
I created the payment intent: https://checkout.stripe.com/pay/cs_test_abc123
Visit that URL and complete the 3D Secure verification flow with your test card.
</instructions>
<verification>Stripe webhook receives payment_intent.succeeded event</verification>
<resume-signal>Type "done" when payment completes</resume-signal>
</task>
```
**Example: Authentication Gate (Dynamic Checkpoint)**
```xml
<task type="auto">
<name>Deploy to Vercel</name>
<files>.vercel/, vercel.json</files>
<action>Run `vercel --yes` to deploy</action>
<verify>vercel ls shows deployment, curl returns 200</verify>
</task>
<!-- If vercel returns "Error: Not authenticated", Claude creates checkpoint on the fly -->
<task type="checkpoint:human-action" gate="blocking">
<action>Authenticate Vercel CLI so I can continue deployment</action>
<instructions>
I tried to deploy but got authentication error.
Run: vercel login
This will open your browser - complete the authentication flow.
</instructions>
<verification>vercel whoami returns your account email</verification>
<resume-signal>Type "done" when authenticated</resume-signal>
</task>
<!-- After authentication, Claude retries the deployment -->
<task type="auto">
<name>Retry Vercel deployment</name>
<action>Run `vercel --yes` (now authenticated)</action>
<verify>vercel ls shows deployment, curl returns 200</verify>
</task>
```
**Key distinction:** Authentication gates are created dynamically when Claude encounters auth errors during automation. They're NOT pre-planned - Claude tries to automate first, only asks for credentials when blocked.
</type>
</checkpoint_types>
<execution_protocol>
When Claude encounters `type="checkpoint:*"`:
1. **Stop immediately** - do not proceed to next task
2. **Display checkpoint clearly:**
```
════════════════════════════════════════
CHECKPOINT: [Type]
════════════════════════════════════════
Task [X] of [Y]: [Name]
[Display checkpoint-specific content]
[Resume signal instruction]
════════════════════════════════════════
```
3. **Wait for user response** - do not hallucinate completion
4. **Verify if possible** - check files, run tests, whatever is specified
5. **Resume execution** - continue to next task only after confirmation
**For checkpoint:human-verify:**
```
════════════════════════════════════════
CHECKPOINT: Verification Required
════════════════════════════════════════
Task 5 of 8: Responsive dashboard layout
I built: Responsive dashboard at /dashboard
How to verify:
1. Run: npm run dev
2. Visit: http://localhost:3000/dashboard
3. Test: Resize browser window to mobile/tablet/desktop
4. Confirm: No layout shift, proper responsive behavior
Type "approved" to continue, or describe issues.
════════════════════════════════════════
```
**For checkpoint:decision:**
```
════════════════════════════════════════
CHECKPOINT: Decision Required
════════════════════════════════════════
Task 2 of 6: Select authentication provider
Decision: Which auth provider should we use?
Context: Need user authentication. Three options with different tradeoffs.
Options:
1. supabase - Built-in with our DB, free tier
2. clerk - Best DX, paid after 10k users
3. nextauth - Self-hosted, maximum control
Select: supabase, clerk, or nextauth
════════════════════════════════════════
```
</execution_protocol>
<writing_guidelines>
**DO:**
- Automate everything with CLI/API before checkpoint
- Be specific: "Visit https://myapp.vercel.app" not "check deployment"
- Number verification steps: easier to follow
- State expected outcomes: "You should see X"
- Provide context: why this checkpoint exists
- Make verification executable: clear, testable steps
**DON'T:**
- Ask human to do work Claude can automate (deploy, create resources, run builds)
- Assume knowledge: "Configure the usual settings" ❌
- Skip steps: "Set up database" ❌ (too vague)
- Mix multiple verifications in one checkpoint (split them)
- Make verification impossible (Claude can't check visual appearance without user confirmation)
</writing_guidelines>
<usage_guidelines>
**Use checkpoint:human-verify for:**
- Visual verification (UI, layouts, animations)
- Interactive testing (click flows, user journeys)
- Quality checks (audio/video playback, animation smoothness)
- Confirming deployed apps are accessible
**Use checkpoint:decision for:**
- Technology selection (auth providers, databases, frameworks)
- Architecture choices (monorepo, deployment strategy)
- Design decisions (color schemes, layout approaches)
- Feature prioritization
**Use checkpoint:human-action for:**
- Email verification links (no API)
- SMS 2FA codes (no API)
- Manual approvals with no automation
- 3D Secure payment flows
**Don't use checkpoints for:**
- Things Claude can verify programmatically (tests pass, build succeeds)
- File operations (Claude can read files to verify)
- Code correctness (use tests and static analysis)
- Anything automatable via CLI/API
</usage_guidelines>
<placement_guidelines>
Place checkpoints:
- **After automation completes** - not before Claude does the work
- **After UI buildout** - before declaring phase complete
- **Before dependent work** - decisions before implementation
- **At integration points** - after configuring external services
Bad placement:
- Before Claude automates (asking human to do automatable work) ❌
- Too frequent (every other task is a checkpoint) ❌
- Too late (checkpoint is last task, but earlier tasks needed its result) ❌
</placement_guidelines>
<examples>
### Example 1: Deployment Flow (Correct)
```xml
<!-- Claude automates everything -->
<task type="auto">
<name>Deploy to Vercel</name>
<files>.vercel/, vercel.json, package.json</files>
<action>
1. Run `vercel --yes` to create project and deploy
2. Capture deployment URL from output
3. Set environment variables with `vercel env add`
4. Trigger production deployment with `vercel --prod`
</action>
<verify>
- vercel ls shows deployment
- curl {url} returns 200
- Environment variables set correctly
</verify>
<done>App deployed to production, URL captured</done>
</task>
<!-- Human verifies visual/functional correctness -->
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Deployed to https://myapp.vercel.app</what-built>
<how-to-verify>
Visit https://myapp.vercel.app and confirm:
- Homepage loads correctly
- All images/assets load
- Navigation works
- No console errors
</how-to-verify>
<resume-signal>Type "approved" or describe issues</resume-signal>
</task>
```
### Example 2: Database Setup (Correct)
```xml
<!-- Claude automates everything -->
<task type="auto">
<name>Create Upstash Redis database</name>
<files>.env</files>
<action>
1. Run `upstash redis create myapp-cache --region us-east-1`
2. Capture connection URL from output
3. Write to .env: UPSTASH_REDIS_URL={url}
4. Verify connection with test command
</action>
<verify>
- upstash redis list shows database
- .env contains UPSTASH_REDIS_URL
- Test connection succeeds
</verify>
<done>Redis database created and configured</done>
</task>
<!-- NO CHECKPOINT NEEDED - Claude automated everything and verified programmatically -->
```
### Example 3: Stripe Webhooks (Correct)
```xml
<!-- Claude automates everything -->
<task type="auto">
<name>Configure Stripe webhooks</name>
<files>.env, src/app/api/webhooks/route.ts</files>
<action>
1. Use Stripe API to create webhook endpoint pointing to /api/webhooks
2. Subscribe to events: payment_intent.succeeded, customer.subscription.updated
3. Save webhook signing secret to .env
4. Implement webhook handler in route.ts
</action>
<verify>
- Stripe API returns webhook endpoint ID
- .env contains STRIPE_WEBHOOK_SECRET
- curl webhook endpoint returns 200
</verify>
<done>Stripe webhooks configured and handler implemented</done>
</task>
<!-- Human verifies in Stripe dashboard -->
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Stripe webhook configured via API</what-built>
<how-to-verify>
Visit Stripe Dashboard > Developers > Webhooks
Confirm: Endpoint shows https://myapp.com/api/webhooks with correct events
</how-to-verify>
<resume-signal>Type "yes" if correct</resume-signal>
</task>
```
</examples>
<anti_patterns>
### ❌ BAD: Asking human to automate
```xml
<task type="checkpoint:human-action" gate="blocking">
<action>Deploy to Vercel</action>
<instructions>
1. Visit vercel.com/new
2. Import Git repository
3. Click Deploy
4. Copy deployment URL
</instructions>
<verification>Deployment exists</verification>
<resume-signal>Paste URL</resume-signal>
</task>
```
**Why bad:** Vercel has a CLI. Claude should run `vercel --yes`.
### ✅ GOOD: Claude automates, human verifies
```xml
<task type="auto">
<name>Deploy to Vercel</name>
<action>Run `vercel --yes`. Capture URL.</action>
<verify>vercel ls shows deployment, curl returns 200</verify>
</task>
<task type="checkpoint:human-verify">
<what-built>Deployed to {url}</what-built>
<how-to-verify>Visit {url}, check homepage loads</how-to-verify>
<resume-signal>Type "approved"</resume-signal>
</task>
```
### ❌ BAD: Too many checkpoints
```xml
<task type="auto">Create schema</task>
<task type="checkpoint:human-verify">Check schema</task>
<task type="auto">Create API route</task>
<task type="checkpoint:human-verify">Check API</task>
<task type="auto">Create UI form</task>
<task type="checkpoint:human-verify">Check form</task>
```
**Why bad:** Verification fatigue. Combine into one checkpoint at end.
### ✅ GOOD: Single verification checkpoint
```xml
<task type="auto">Create schema</task>
<task type="auto">Create API route</task>
<task type="auto">Create UI form</task>
<task type="checkpoint:human-verify">
<what-built>Complete auth flow (schema + API + UI)</what-built>
<how-to-verify>Test full flow: register, login, access protected page</how-to-verify>
<resume-signal>Type "approved"</resume-signal>
</task>
```
### ❌ BAD: Asking for automatable file operations
```xml
<task type="checkpoint:human-action">
<action>Create .env file</action>
<instructions>
1. Create .env in project root
2. Add: DATABASE_URL=...
3. Add: STRIPE_KEY=...
</instructions>
</task>
```
**Why bad:** Claude has Write tool. This should be `type="auto"`.
</anti_patterns>
<summary>
Checkpoints formalize human-in-the-loop points. Use them when Claude cannot complete a task autonomously OR when human verification is required for correctness.
**The golden rule:** If Claude CAN automate it, Claude MUST automate it.
**Checkpoint priority:**
1. **checkpoint:human-verify** (90% of checkpoints) - Claude automated everything, human confirms visual/functional correctness
2. **checkpoint:decision** (9% of checkpoints) - Human makes architectural/technology choices
3. **checkpoint:human-action** (1% of checkpoints) - Truly unavoidable manual steps with no API/CLI
</summary>

527
get-shit-done/references/cli-automation.md Normal file
View File

@@ -0,0 +1,527 @@
<overview>
**Core principle:** If it has a CLI or API, Claude does it. Never ask the human to perform manual steps that Claude can automate.
This reference documents what Claude CAN and SHOULD automate during plan execution.
</overview>
<deployment_platforms>
<platform name="vercel">
**CLI:** `vercel`
**What Claude automates:**
- Create and deploy projects: `vercel --yes`
- Set environment variables: `vercel env add KEY production`
- Link to git repo: `vercel link`
- Trigger deployments: `vercel --prod`
- Get deployment URLs: `vercel ls`
- Manage domains: `vercel domains add example.com`
**Never ask human to:**
- Visit vercel.com/new to create project
- Click through dashboard to add env vars
- Manually link repository
**Checkpoint pattern:**
```xml
<task type="auto">
<name>Deploy to Vercel</name>
<action>Run `vercel --yes` to deploy. Capture deployment URL.</action>
<verify>vercel ls shows deployment, curl {url} returns 200</verify>
</task>
<task type="checkpoint:human-verify">
<what-built>Deployed to {url}</what-built>
<how-to-verify>Visit {url} - check homepage loads</how-to-verify>
<resume-signal>Type "yes" if correct</resume-signal>
</task>
```
</platform>
<platform name="railway">
**CLI:** `railway`
**What Claude automates:**
- Initialize project: `railway init`
- Link to repo: `railway link`
- Deploy: `railway up`
- Set variables: `railway variables set KEY=value`
- Get deployment URL: `railway domain`
</platform>
<platform name="fly">
**CLI:** `fly`
**What Claude automates:**
- Launch app: `fly launch --no-deploy`
- Deploy: `fly deploy`
- Set secrets: `fly secrets set KEY=value`
- Scale: `fly scale count 2`
</platform>
</deployment_platforms>
<payment_billing>
<service name="stripe">
**CLI:** `stripe`
**What Claude automates:**
- Create webhook endpoints: `stripe listen --forward-to localhost:3000/api/webhooks`
- Trigger test events: `stripe trigger payment_intent.succeeded`
- Create products/prices: Stripe API via curl/fetch
- Manage customers: Stripe API via curl/fetch
- Check webhook logs: `stripe webhooks list`
**Never ask human to:**
- Visit dashboard.stripe.com to create webhook
- Click through UI to create products
- Manually copy webhook signing secret
**Checkpoint pattern:**
```xml
<task type="auto">
<name>Configure Stripe webhooks</name>
<action>Use Stripe API to create webhook endpoint at /api/webhooks. Save signing secret to .env.</action>
<verify>stripe webhooks list shows endpoint, .env contains STRIPE_WEBHOOK_SECRET</verify>
</task>
<task type="checkpoint:human-verify">
<what-built>Stripe webhook configured</what-built>
<how-to-verify>Check Stripe dashboard > Developers > Webhooks shows endpoint with correct URL</how-to-verify>
<resume-signal>Type "yes" if correct</resume-signal>
</task>
```
</service>
</payment_billing>
<databases_backend>
<service name="supabase">
**CLI:** `supabase`
**What Claude automates:**
- Initialize project: `supabase init`
- Link to remote: `supabase link --project-ref {ref}`
- Create migrations: `supabase migration new {name}`
- Push migrations: `supabase db push`
- Generate types: `supabase gen types typescript`
- Deploy functions: `supabase functions deploy {name}`
**Never ask human to:**
- Visit supabase.com to create project manually
- Click through dashboard to run migrations
- Copy/paste connection strings
**Note:** Project creation may require web dashboard initially (no CLI for initial project creation), but all subsequent work (migrations, functions, etc.) is CLI-automated.
</service>
<service name="upstash">
**CLI:** `upstash`
**What Claude automates:**
- Create Redis database: `upstash redis create {name} --region {region}`
- Get connection details: `upstash redis get {id}`
- Create Kafka cluster: `upstash kafka create {name} --region {region}`
**Never ask human to:**
- Visit console.upstash.com
- Click through UI to create database
- Copy/paste connection URLs manually
**Checkpoint pattern:**
```xml
<task type="auto">
<name>Create Upstash Redis database</name>
<action>Run `upstash redis create myapp-cache --region us-east-1`. Save URL to .env.</action>
<verify>.env contains UPSTASH_REDIS_URL, upstash redis list shows database</verify>
</task>
```
</service>
<service name="planetscale">
**CLI:** `pscale`
**What Claude automates:**
- Create database: `pscale database create {name} --region {region}`
- Create branch: `pscale branch create {db} {branch}`
- Deploy request: `pscale deploy-request create {db} {branch}`
- Connection string: `pscale connect {db} {branch}`
</service>
</databases_backend>
<version_control>
<service name="github">
**CLI:** `gh`
**What Claude automates:**
- Create repo: `gh repo create {name} --public/--private`
- Create issues: `gh issue create --title "{title}" --body "{body}"`
- Create PR: `gh pr create --title "{title}" --body "{body}"`
- Manage secrets: `gh secret set {KEY}`
- Trigger workflows: `gh workflow run {name}`
- Check status: `gh run list`
**Never ask human to:**
- Visit github.com to create repo
- Click through UI to add secrets
- Manually create issues/PRs
</service>
</version_control>
<build_tools>
<tools name="node">
**What Claude automates:**
- Install dependencies: `npm install`, `pnpm install`, `bun install`
- Run builds: `npm run build`
- Run tests: `npm test`, `npm run test:e2e`
- Type checking: `tsc --noEmit`
**Never ask human to:** Run these commands manually
</tools>
<tools name="xcode">
**CLI:** `xcodebuild`
**What Claude automates:**
- Build project: `xcodebuild -project App.xcodeproj -scheme App build`
- Run tests: `xcodebuild test -project App.xcodeproj -scheme App`
- Archive: `xcodebuild archive -project App.xcodeproj -scheme App`
- Check compilation: Parse xcodebuild output for errors
**Never ask human to:**
- Open Xcode and click Product > Build
- Click Product > Test manually
- Check for errors by looking at Xcode UI
**Checkpoint pattern:**
```xml
<task type="auto">
<name>Build macOS app</name>
<action>Run `xcodebuild -project App.xcodeproj -scheme App build`. Check output for errors.</action>
<verify>Build succeeds with "BUILD SUCCEEDED" in output</verify>
</task>
<task type="checkpoint:human-verify">
<what-built>Built macOS app at DerivedData/Build/Products/Debug/App.app</what-built>
<how-to-verify>Open App.app and check: login flow works, no visual glitches</how-to-verify>
<resume-signal>Type "approved" or describe issues</resume-signal>
</task>
```
</tools>
</build_tools>
<environment_config>
<config name="env-files">
**Tool:** Write tool
**What Claude automates:**
- Create .env files: Use Write tool
- Append variables: Use Edit tool
- Read current values: Use Read tool
**Never ask human to:**
- Manually create .env file
- Copy/paste values into .env
- Edit .env in text editor
**Pattern:**
```xml
<task type="auto">
<name>Configure environment variables</name>
<action>Write .env file with: DATABASE_URL, STRIPE_KEY, JWT_SECRET (generated).</action>
<verify>Read .env confirms all variables present</verify>
</task>
```
</config>
</environment_config>
<email_communication>
<service name="resend">
**API:** Resend API via HTTP
**What Claude automates:**
- Create API keys via dashboard API (if available) or instructions for one-time setup
- Send emails: Resend API
- Configure domains: Resend API
</service>
<service name="sendgrid">
**API:** SendGrid API via HTTP
**What Claude automates:**
- Create API keys via API
- Send emails: SendGrid API
- Configure webhooks: SendGrid API
**Note:** Initial account setup may require email verification (checkpoint:human-action), but all subsequent work is API-automated.
</service>
</email_communication>
<authentication_gates>
**Critical distinction:** When Claude tries to use a CLI/API and gets an authentication error, this is NOT a failure - it's a gate that requires human input to unblock automation.
**Pattern: Claude encounters auth error → creates checkpoint → you authenticate → Claude continues**
<example name="vercel-auth">
```xml
<task type="auto">
<name>Deploy to Vercel</name>
<files>.vercel/, vercel.json</files>
<action>Run `vercel --yes` to deploy</action>
<verify>vercel ls shows deployment</verify>
</task>
<!-- If vercel returns "Error: Not authenticated" -->
<task type="checkpoint:human-action" gate="blocking">
<action>Authenticate Vercel CLI so I can continue deployment</action>
<instructions>
I tried to deploy but got authentication error.
Run: vercel login
This will open your browser - complete the authentication flow.
</instructions>
<verification>vercel whoami returns your account email</verification>
<resume-signal>Type "done" when authenticated</resume-signal>
</task>
<!-- After authentication, Claude retries automatically -->
<task type="auto">
<name>Retry Vercel deployment</name>
<action>Run `vercel --yes` (now authenticated)</action>
<verify>vercel ls shows deployment, curl returns 200</verify>
</task>
```
</example>
<example name="stripe-auth">
```xml
<task type="auto">
<name>Create Stripe webhook endpoint</name>
<action>Use Stripe API to create webhook at /api/webhooks</action>
</task>
<!-- If API returns 401 Unauthorized -->
<task type="checkpoint:human-action" gate="blocking">
<action>Provide Stripe API key so I can continue webhook configuration</action>
<instructions>
I need your Stripe API key to create webhooks.
1. Visit dashboard.stripe.com/apikeys
2. Copy your "Secret key" (starts with sk_test_ or sk_live_)
3. Paste it here or run: export STRIPE_SECRET_KEY=sk_...
</instructions>
<verification>Stripe API key works: curl test succeeds</verification>
<resume-signal>Type "done" or paste the key</resume-signal>
</task>
<!-- After key provided, Claude writes to .env and continues -->
<task type="auto">
<name>Save Stripe key and create webhook</name>
<action>
1. Write STRIPE_SECRET_KEY to .env
2. Create webhook endpoint via Stripe API
3. Save webhook secret to .env
</action>
<verify>.env contains both keys, webhook endpoint exists</verify>
</task>
```
</example>
<example name="github-auth">
```xml
<task type="auto">
<name>Create GitHub repository</name>
<action>Run `gh repo create myapp --public`</action>
</task>
<!-- If gh returns "Not logged in" -->
<task type="checkpoint:human-action" gate="blocking">
<action>Authenticate GitHub CLI so I can create repository</action>
<instructions>
I need GitHub authentication to create the repo.
Run: gh auth login
Follow the prompts to authenticate (browser or token).
</instructions>
<verification>gh auth status shows "Logged in"</verification>
<resume-signal>Type "done" when authenticated</resume-signal>
</task>
<task type="auto">
<name>Create repository (authenticated)</name>
<action>Run `gh repo create myapp --public`</action>
<verify>gh repo view shows repository exists</verify>
</task>
```
</example>
<example name="upstash-auth">
```xml
<task type="auto">
<name>Create Upstash Redis database</name>
<action>Run `upstash redis create myapp-cache --region us-east-1`</action>
</task>
<!-- If upstash returns auth error -->
<task type="checkpoint:human-action" gate="blocking">
<action>Configure Upstash CLI credentials so I can create database</action>
<instructions>
I need Upstash authentication to create Redis database.
1. Visit console.upstash.com/account/api
2. Copy your API key
3. Run: upstash auth login
4. Paste your API key when prompted
</instructions>
<verification>upstash auth status shows authenticated</verification>
<resume-signal>Type "done" when authenticated</resume-signal>
</task>
<task type="auto">
<name>Create Redis database (authenticated)</name>
<action>
1. Run `upstash redis create myapp-cache --region us-east-1`
2. Capture connection URL
3. Write to .env: UPSTASH_REDIS_URL={url}
</action>
<verify>upstash redis list shows database, .env contains URL</verify>
</task>
```
</example>
<gate_protocol>
**When Claude encounters authentication error during execution:**
1. **Recognize it's not a failure** - Missing auth is expected, not a bug
2. **Stop current task** - Don't retry repeatedly
3. **Create checkpoint:human-action on the fly** - Dynamic checkpoint, not pre-planned
4. **Provide exact authentication steps** - CLI commands, where to get keys
5. **Verify authentication** - Test that auth works before continuing
6. **Retry the original task** - Resume automation where it left off
7. **Continue normally** - One auth gate doesn't break the flow
**Key difference from pre-planned checkpoints:**
- Pre-planned: "I need you to do X" (wrong - Claude should automate)
- Auth gate: "I tried to automate X but need credentials to continue" (correct - unblocks automation)
**This preserves agentic flow:**
- Claude tries automation first
- Only asks for help when blocked by credentials
- Continues automating after unblocked
- You never manually deploy/create resources - just provide keys
</gate_protocol>
</authentication_gates>
<required_cases>
**Truly rare cases where no CLI/API exists:**
1. **Email verification links** - Account signup requires clicking verification email
2. **SMS verification codes** - 2FA requiring phone
3. **Manual account approvals** - Platform requires human review before API access
4. **Domain DNS records at registrar** - Some registrars have no API
5. **Credit card input** - Payment methods requiring 3D Secure web flow
6. **OAuth app approval** - Some platforms require web-based app approval flow
**For these rare cases:**
```xml
<task type="checkpoint:human-action" gate="blocking">
<action>Complete email verification for SendGrid account</action>
<instructions>
I created the account and requested verification email.
Check your inbox for verification link and click it.
</instructions>
<verification>SendGrid API key works: curl test succeeds</verification>
<resume-signal>Type "done" when verified</resume-signal>
</task>
```
**Key difference:** Claude does EVERYTHING possible first (account creation, API requests), only asks human for the one thing with no automation path.
</required_cases>
<quick_reference>
| Action | CLI/API? | Claude does it? |
|--------|----------|-----------------|
| Deploy to Vercel | ✅ `vercel` | YES |
| Create Stripe webhook | ✅ Stripe API | YES |
| Run xcodebuild | ✅ `xcodebuild` | YES |
| Write .env file | ✅ Write tool | YES |
| Create Upstash DB | ✅ `upstash` CLI | YES |
| Install npm packages | ✅ `npm` | YES |
| Create GitHub repo | ✅ `gh` | YES |
| Run tests | ✅ `npm test` | YES |
| Create Supabase project | ⚠️ Web dashboard | NO (then CLI for everything else) |
| Click email verification link | ❌ No API | NO |
| Enter credit card with 3DS | ❌ No API | NO |
**Default answer: YES.** Unless explicitly in the "NO" category, Claude automates it.
</quick_reference>
<decision_tree>
```
┌─────────────────────────────────────┐
│ Task requires external resource? │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Does it have CLI/API/tool access? │
└──────────────┬──────────────────────┘
│
┌─────┴─────┐
│ │
▼ ▼
YES NO
│ │
│ ▼
│ ┌──────────────────────────────┐
│ │ checkpoint:human-action │
│ │ (email links, 2FA, etc.) │
│ └──────────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ task type="auto" │
│ Claude automates via CLI/API │
└────────────┬───────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ checkpoint:human-verify │
│ Human confirms visual/functional │
└────────────────────────────────────────┘
```
</decision_tree>
<summary>
**The rule:** If Claude CAN do it, Claude MUST do it.
Checkpoints are for:
- **Verification** - Confirming Claude's automated work looks/behaves correctly
- **Decisions** - Choosing between valid approaches
- **True blockers** - Rare actions with literally no API/CLI (email links, 2FA)
Checkpoints are NOT for:
- Deploying (use CLI)
- Creating resources (use CLI/API)
- Running builds (use Bash)
- Writing files (use Write tool)
- Anything with automation available
**This keeps the agentic coding workflow intact - Claude does the work, you verify results.**
</summary>

126
get-shit-done/references/git-integration.md Normal file
View File

@@ -0,0 +1,126 @@
<overview>
Git integration for GSD framework.
</overview>
<core_principle>
**Commit outcomes, not process.**
The git log should read like a changelog of what shipped, not a diary of planning activity.
</core_principle>
<commit_points>
| Event | Commit? | Why |
| ----------------------- | ------- | ------------------------------------- |
| BRIEF + ROADMAP created | YES | Project initialization |
| PLAN.md created | NO | Intermediate - commit with completion |
| RESEARCH.md created | NO | Intermediate |
| FINDINGS.md created | NO | Intermediate |
| **Phase completed** | YES | Actual code shipped |
| Handoff created | YES | WIP state preserved |
</commit_points>
<git_check>
```bash
[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
```
If NO_GIT: Run `git init` silently. GSD projects always get their own repo.
</git_check>
<commit_formats>
<format name="initialization">
## Project Initialization (brief + roadmap together)
```
docs: initialize [project-name] ([N] phases)
[One-liner from PROJECT.md]
Phases:
1. [phase-name]: [goal]
2. [phase-name]: [goal]
3. [phase-name]: [goal]
```
What to commit:
```bash
git add .planning/
git commit
```
</format>
<format name="phase-completion">
## Phase Completion
```
feat([domain]): [one-liner from SUMMARY.md]
- [Key accomplishment 1]
- [Key accomplishment 2]
- [Key accomplishment 3]
[If issues encountered:]
Note: [issue and resolution]
```
Use `fix([domain])` for bug fix phases.
What to commit:
```bash
git add .planning/phases/XX-name/ # PLAN.md + SUMMARY.md
git add src/ # Actual code created
git commit
```
</format>
<format name="handoff">
## Handoff (WIP)
```
wip: [phase-name] paused at task [X]/[Y]
Current: [task name]
[If blocked:] Blocked: [reason]
```
What to commit:
```bash
git add .planning/
git commit
```
</format>
</commit_formats>
<example_log>
```
a]7f2d1 feat(checkout): Stripe payments with webhook verification
b]3e9c4 feat(products): catalog with search, filters, and pagination
c]8a1b2 feat(auth): JWT with refresh rotation using jose
d]5c3d7 feat(foundation): Next.js 15 + Prisma + Tailwind scaffold
e]2f4a8 docs: initialize ecommerce-app (5 phases)
```
</example_log>
<anti_patterns>
- PLAN.md creation (wait for phase completion)
- RESEARCH.md (intermediate)
- FINDINGS.md (intermediate)
- Minor planning tweaks
- "Fixed typo in roadmap"
These create noise. Commit outcomes, not process.
</anti_patterns>

397
get-shit-done/references/plan-format.md Normal file
View File

@@ -0,0 +1,397 @@
<overview>
Claude-executable plans have a specific format that enables Claude to implement without interpretation. This reference defines what makes a plan executable vs. vague.
**Key insight:** PLAN.md IS the executable prompt. It contains everything Claude needs to execute the phase, including objective, context references, tasks, verification, success criteria, and output specification.
</overview>
<core_principle>
A plan is Claude-executable when Claude can read the PLAN.md and immediately start implementing without asking clarifying questions.
If Claude has to guess, interpret, or make assumptions - the task is too vague.
</core_principle>
<prompt_structure>
Every PLAN.md follows this XML structure:
```markdown
---
phase: XX-name
type: execute
domain: [optional]
---
<objective>
[What and why]
Purpose: [...]
Output: [...]
</objective>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@relevant/source/files.ts
</context>
<tasks>
<task type="auto">
<name>Task N: [Name]</name>
<files>[paths]</files>
<action>[what to do, what to avoid and WHY]</action>
<verify>[command/check]</verify>
<done>[criteria]</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<what-built>[what Claude automated]</what-built>
<how-to-verify>[numbered verification steps]</how-to-verify>
<resume-signal>[how to continue - "approved" or describe issues]</resume-signal>
</task>
<task type="checkpoint:decision" gate="blocking">
<decision>[what needs deciding]</decision>
<context>[why this matters]</context>
<options>
<option id="option-a"><name>[Name]</name><pros>[pros]</pros><cons>[cons]</cons></option>
<option id="option-b"><name>[Name]</name><pros>[pros]</pros><cons>[cons]</cons></option>
</options>
<resume-signal>[how to indicate choice]</resume-signal>
</task>
</tasks>
<verification>
[Overall phase checks]
</verification>
<success_criteria>
[Measurable completion]
</success_criteria>
<output>
[SUMMARY.md specification]
</output>
```
</prompt_structure>
<task_anatomy>
Every task has four required fields:
<field name="files">
**What it is**: Exact file paths that will be created or modified.
**Good**: `src/app/api/auth/login/route.ts`, `prisma/schema.prisma`
**Bad**: "the auth files", "relevant components"
Be specific. If you don't know the file path, figure it out first.
</field>
<field name="action">
**What it is**: Specific implementation instructions, including what to avoid and WHY.
**Good**: "Create POST endpoint that accepts {email, password}, validates using bcrypt against User table, returns JWT in httpOnly cookie with 15-min expiry. Use jose library (not jsonwebtoken - CommonJS issues with Next.js Edge runtime)."
**Bad**: "Add authentication", "Make login work"
Include: technology choices, data structures, behavior details, pitfalls to avoid.
</field>
<field name="verify">
**What it is**: How to prove the task is complete.
**Good**:
- `npm test` passes
- `curl -X POST /api/auth/login` returns 200 with Set-Cookie header
- Build completes without errors
**Bad**: "It works", "Looks good", "User can log in"
Must be executable - a command, a test, an observable behavior.
</field>
<field name="done">
**What it is**: Acceptance criteria - the measurable state of completion.
**Good**: "Valid credentials return 200 + JWT cookie, invalid credentials return 401"
**Bad**: "Authentication is complete"
Should be testable without subjective judgment.
</field>
</task_anatomy>
<task_types>
Tasks have a `type` attribute that determines how they execute:
<type name="auto">
**Default task type** - Claude executes autonomously.
**Structure:**
```xml
<task type="auto">
<name>Task 3: Create login endpoint with JWT</name>
<files>src/app/api/auth/login/route.ts</files>
<action>POST endpoint accepting {email, password}. Query User by email, compare password with bcrypt. On match, create JWT with jose library, set as httpOnly cookie (15-min expiry). Return 200. On mismatch, return 401.</action>
<verify>curl -X POST localhost:3000/api/auth/login returns 200 with Set-Cookie header</verify>
<done>Valid credentials → 200 + cookie. Invalid → 401.</done>
</task>
```
Use for: Everything Claude can do independently (code, tests, builds, file operations).
</type>
<type name="checkpoint:human-action">
**RARELY USED** - Only for actions with NO CLI/API. Claude automates everything possible first.
**Structure:**
```xml
<task type="checkpoint:human-action" gate="blocking">
<action>[Unavoidable manual step - email link, 2FA code]</action>
<instructions>
[What Claude already automated]
[The ONE thing requiring human action]
</instructions>
<verification>[What Claude can check afterward]</verification>
<resume-signal>[How to continue]</resume-signal>
</task>
```
Use ONLY for: Email verification links, SMS 2FA codes, manual approvals with no API, 3D Secure payment flows.
Do NOT use for: Anything with a CLI (Vercel, Stripe, Upstash, Railway, GitHub), builds, tests, file creation, deployments.
**Execution:** Claude automates everything with CLI/API, stops only for truly unavoidable manual steps.
</type>
<type name="checkpoint:human-verify">
**Human must verify Claude's work** - Visual checks, UX testing.
**Structure:**
```xml
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Responsive dashboard layout</what-built>
<how-to-verify>
1. Run: npm run dev
2. Visit: http://localhost:3000/dashboard
3. Desktop (>1024px): Verify sidebar left, content right
4. Tablet (768px): Verify sidebar collapses to hamburger
5. Mobile (375px): Verify single column, bottom nav
6. Check: No layout shift, no horizontal scroll
</how-to-verify>
<resume-signal>Type "approved" or describe issues</resume-signal>
</task>
```
Use for: UI/UX verification, visual design checks, animation smoothness, accessibility testing.
**Execution:** Claude builds the feature, stops, provides testing instructions, waits for approval/feedback.
</type>
<type name="checkpoint:decision">
**Human must make implementation choice** - Direction-setting decisions.
**Structure:**
```xml
<task type="checkpoint:decision" gate="blocking">
<decision>Select authentication provider</decision>
<context>We need user authentication. Three approaches with different tradeoffs:</context>
<options>
<option id="supabase">
<name>Supabase Auth</name>
<pros>Built-in with Supabase, generous free tier</pros>
<cons>Less customizable UI, tied to ecosystem</cons>
</option>
<option id="clerk">
<name>Clerk</name>
<pros>Beautiful pre-built UI, best DX</pros>
<cons>Paid after 10k MAU</cons>
</option>
<option id="nextauth">
<name>NextAuth.js</name>
<pros>Free, self-hosted, maximum control</pros>
<cons>More setup, you manage security</cons>
</option>
</options>
<resume-signal>Select: supabase, clerk, or nextauth</resume-signal>
</task>
```
Use for: Technology selection, architecture decisions, design choices, feature prioritization.
**Execution:** Claude presents options with balanced pros/cons, waits for decision, proceeds with chosen direction.
</type>
**When to use checkpoints:**
- Visual/UX verification (after Claude builds) → `checkpoint:human-verify`
- Implementation direction choice → `checkpoint:decision`
- Truly unavoidable manual actions (email links, 2FA) → `checkpoint:human-action` (rare)
**When NOT to use checkpoints:**
- Anything with CLI/API (Claude automates it) → `type="auto"`
- Deployments (Vercel, Railway, Fly) → `type="auto"` with CLI
- Creating resources (Upstash, Stripe, GitHub) → `type="auto"` with CLI/API
- File operations, tests, builds → `type="auto"`
**Golden rule:** If Claude CAN automate it, Claude MUST automate it.
See `./checkpoints.md` for comprehensive checkpoint guidance.
</task_types>
<context_references>
Use @file references to load context for the prompt:
```markdown
<context>
@.planning/PROJECT.md # Project vision
@.planning/ROADMAP.md # Phase structure
@.planning/phases/02-auth/FINDINGS.md # Research results
@src/lib/db.ts # Existing database setup
@src/types/user.ts # Existing type definitions
</context>
```
Reference files that Claude needs to understand before implementing.
</context_references>
<verification_section>
Overall phase verification (beyond individual task verification):
```markdown
<verification>
Before declaring phase complete:
- [ ] `npm run build` succeeds without errors
- [ ] `npm test` passes all tests
- [ ] No TypeScript errors
- [ ] Feature works end-to-end manually
</verification>
```
</verification_section>
<success_criteria_section>
Measurable criteria for phase completion:
```markdown
<success_criteria>
- All tasks completed
- All verification checks pass
- No errors or warnings introduced
- JWT auth flow works end-to-end
- Protected routes redirect unauthenticated users
</success_criteria>
```
</success_criteria_section>
<output_section>
Specify the SUMMARY.md structure:
```markdown
<output>
After completion, create `.planning/phases/XX-name/SUMMARY.md`:
# Phase X: Name Summary
**[Substantive one-liner]**
## Accomplishments
## Files Created/Modified
## Decisions Made
## Issues Encountered
## Next Phase Readiness
</output>
```
</output_section>
<specificity_levels>
<too_vague>
```xml
<task type="auto">
<name>Task 1: Add authentication</name>
<files>???</files>
<action>Implement auth</action>
<verify>???</verify>
<done>Users can authenticate</done>
</task>
```
Claude: "How? What type? What library? Where?"
</too_vague>
<just_right>
```xml
<task type="auto">
<name>Task 1: Create login endpoint with JWT</name>
<files>src/app/api/auth/login/route.ts</files>
<action>POST endpoint accepting {email, password}. Query User by email, compare password with bcrypt. On match, create JWT with jose library, set as httpOnly cookie (15-min expiry). Return 200. On mismatch, return 401. Use jose instead of jsonwebtoken (CommonJS issues with Edge).</action>
<verify>curl -X POST localhost:3000/api/auth/login -H "Content-Type: application/json" -d '{"email":"test@test.com","password":"test123"}' returns 200 with Set-Cookie header containing JWT</verify>
<done>Valid credentials → 200 + cookie. Invalid → 401. Missing fields → 400.</done>
</task>
```
Claude can implement this immediately.
</just_right>
<too_detailed>
Writing the actual code in the plan. Trust Claude to implement from clear instructions.
</too_detailed>
</specificity_levels>
<anti_patterns>
<vague_actions>
- "Set up the infrastructure"
- "Handle edge cases"
- "Make it production-ready"
- "Add proper error handling"
These require Claude to decide WHAT to do. Specify it.
</vague_actions>
<unverifiable_completion>
- "It works correctly"
- "User experience is good"
- "Code is clean"
- "Tests pass" (which tests? do they exist?)
These require subjective judgment. Make it objective.
</unverifiable_completion>
<missing_context>
- "Use the standard approach"
- "Follow best practices"
- "Like the other endpoints"
Claude doesn't know your standards. Be explicit.
</missing_context>
</anti_patterns>
<sizing_tasks>
Good task size: 15-60 minutes of Claude work.
**Too small**: "Add import statement for bcrypt" (combine with related task)
**Just right**: "Create login endpoint with JWT validation" (focused, specific)
**Too big**: "Implement full authentication system" (split into multiple plans)
If a task takes multiple sessions, break it down.
If a task is trivial, combine with related tasks.
**Note on scope:** If a phase has >3 tasks or spans multiple subsystems, split into multiple plans using the naming convention `{phase}-{plan}-PLAN.md`. See `./scope-estimation.md` for guidance.
</sizing_tasks>

97
get-shit-done/references/principles.md Normal file
View File

@@ -0,0 +1,97 @@
<principles>
Core principles for the Gets Shit Done planning system.
<solo_developer_claude>
You are planning for ONE person (the user) and ONE implementer (Claude).
- No teams, stakeholders, ceremonies, coordination overhead
- User is the visionary/product owner
- Claude is the builder
- Estimate effort in Claude execution time, not human dev time
</solo_developer_claude>
<plans_are_prompts>
PLAN.md is not a document that gets transformed into a prompt.
PLAN.md IS the prompt. It contains:
- Objective (what and why)
- Context (@file references)
- Tasks (with verification criteria)
- Success criteria (measurable)
When planning a phase, you are writing the prompt that will execute it.
</plans_are_prompts>
<initialization_leverage>
The most leveraged moment is project initialization.
- Deep questioning here = better everything downstream
- Garbage in = garbage out
- Spend the tokens on context gathering
- Don't rush to "the work"
</initialization_leverage>
<scope_control>
Plans must complete within reasonable context usage.
**Quality degradation curve:**
- 0-30% context: Peak quality
- 30-50% context: Good quality
- 50-70% context: Degrading quality
- 70%+ context: Poor quality
**Solution:** Aggressive atomicity - split into small, focused plans.
- 2-3 tasks per plan maximum
- Each plan independently executable
- Better to have many small plans than few large ones
</scope_control>
<claude_automates>
If Claude CAN do it via CLI/API/tool, Claude MUST do it.
Checkpoints are for:
- **Verification** - Human confirms Claude's work (visual, UX)
- **Decision** - Human makes implementation choice
Not for:
- Deploying (use CLI)
- Creating resources (use CLI/API)
- Running builds/tests (use Bash)
- Writing files (use Write tool)
</claude_automates>
<deviation_rules>
Plans are guides, not straitjackets. During execution:
1. **Auto-fix bugs** - Fix immediately, document
2. **Auto-add critical** - Security/correctness gaps, add immediately
3. **Auto-fix blockers** - Can't proceed, fix immediately
4. **Ask about architectural** - Major changes, stop and ask
5. **Log enhancements** - Nice-to-haves, log to Issues, continue
</deviation_rules>
<ship_fast>
No enterprise process. No approval gates.
Plan → Execute → Ship → Learn → Repeat
Milestones mark shipped versions (v1.0 → v1.1 → v2.0).
</ship_fast>
<anti_enterprise>
NEVER include:
- Team structures, RACI matrices
- Stakeholder management
- Sprint ceremonies
- Multi-week estimates
- Change management processes
- Documentation for documentation's sake
If it sounds like corporate PM theater, delete it.
</anti_enterprise>
</principles>

138
get-shit-done/references/questioning.md Normal file
View File

@@ -0,0 +1,138 @@
<questioning_guide>
The initialization questioning phase is the most leveraged moment in any project. Context gathered here flows through every downstream decision. Don't rush it.
<domains>
Ask about gaps - skip what's already clear from user input.
<project_type>
What kind of thing is this?
- Product/app (software for users)
- Automation/tool (system to automate a process)
- Research/analysis (investigation or learning)
- Creative work (content, art, media)
</project_type>
<problem_motivation>
Why does this need to exist?
- What pain point?
- What gap in current solutions?
- What opportunity?
- What's the current state without this?
</problem_motivation>
<audience>
Who is this for?
- Just the user (personal tool)
- Their team (internal use)
- Specific user segment (targeted audience)
- General public (broad availability)
</audience>
<success_criteria>
What does "done" look like?
- Must be measurable/verifiable
- Not vague ("make it good")
- Specific outcomes, not activities
</success_criteria>
<constraints>
What limits exist?
- Tech stack (must use X, can't use Y)
- Timeline (deadline, urgency)
- Resources (budget, team size)
- Dependencies (needs X to exist first)
- Compatibility (must work with Y)
</constraints>
<scope_boundaries>
What are you NOT building?
- Explicit exclusions prevent creep
- "Not in v1" is valid
- Helps focus on what matters
</scope_boundaries>
<current_state>
What exists already?
- Greenfield (nothing exists)
- Brownfield (existing code/system)
- Prior attempts (what was tried, what failed)
- Related work (adjacent systems)
</current_state>
<technical_decisions>
Any already made?
- Framework choices
- Architecture patterns
- Key libraries
- Deployment target
</technical_decisions>
<open_questions>
What's still unclear?
- Known unknowns
- Decisions deferred
- Areas needing research
</open_questions>
</domains>
<mechanics>
<ask_user_question_tool>
Every follow-up question uses structured options:
- 2-4 choices per question
- Always include "Other" or "Let me explain"
- Options should be mutually exclusive when possible
</ask_user_question_tool>
<assess_after_round>
After receiving answers, evaluate completeness:
**Critical gaps exist:**
- State the gap clearly
- Ask about it immediately
- Don't offer to finalize yet
**Sufficient context:**
- Acknowledge what's gathered
- Note optional areas could explore
- Offer choice: finalize or dig deeper
**Comprehensive:**
- Acknowledge depth
- Offer to finalize
- Only edge cases remain
</assess_after_round>
<decision_gate_pattern>
**CRITICAL: Always present ALL THREE options. Never skip "Ask more questions".**
Use AskUserQuestion with exactly these options:
```
Header: "Ready?"
Question: "Ready to create PROJECT.md, or explore more?"
Options (ALL THREE REQUIRED):
1. "Create PROJECT.md" - Finalize and continue
2. "Ask more questions" - I'll dig into areas we haven't covered
3. "Let me add context" - You have more to share
```
If user selects "Ask more questions":
- Identify domains not yet covered from the 9 domains list
- Ask about 2-3 of them
- Return to decision gate
Loop until "Create PROJECT.md" selected.
</decision_gate_pattern>
</mechanics>
<anti_patterns>
- **Rushing** - Don't minimize questions to get to "the work"
- **Assuming** - Don't fill gaps with assumptions, ask
- **Leading** - Don't push toward a preferred answer
- **Repeating** - Don't ask about what user already provided
- **Shallow** - Don't accept vague answers, probe for specifics
</anti_patterns>
</questioning_guide>

215
get-shit-done/references/research-pitfalls.md Normal file
View File

@@ -0,0 +1,215 @@
<research_pitfalls>
<purpose>
This document catalogs research mistakes discovered in production use, providing specific patterns to avoid and verification strategies to prevent recurrence.
</purpose>
<known_pitfalls>
<pitfall_config_scope>
**What**: Assuming global configuration means no project-scoping exists
**Example**: Concluding "MCP servers are configured GLOBALLY only" while missing project-scoped `.mcp.json`
**Why it happens**: Not explicitly checking all known configuration patterns
**Prevention**:
```xml
<verification_checklist>
**CRITICAL**: Verify ALL configuration scopes:
□ User/global scope - System-wide configuration
□ Project scope - Project-level configuration files
□ Local scope - Project-specific user overrides
□ Workspace scope - IDE/tool workspace settings
□ Environment scope - Environment variables
</verification_checklist>
```
</pitfall_config_scope>
<pitfall_search_vagueness>
**What**: Asking researchers to "search for documentation" without specifying where
**Example**: "Research MCP documentation" → finds outdated community blog instead of official docs
**Why it happens**: Vague research instructions don't specify exact sources
**Prevention**:
```xml
<sources>
Official sources (use WebFetch):
- https://exact-url-to-official-docs
- https://exact-url-to-api-reference
Search queries (use WebSearch):
- "specific search query {current_year}"
- "another specific query {current_year}"
</sources>
```
</pitfall_search_vagueness>
<pitfall_deprecated_features>
**What**: Finding archived/old documentation and concluding feature doesn't exist
**Example**: Finding 2022 docs saying "feature not supported" when current version added it
**Why it happens**: Not checking multiple sources or recent updates
**Prevention**:
```xml
<verification_checklist>
□ Check current official documentation
□ Review changelog/release notes for recent updates
□ Verify version numbers and publication dates
□ Cross-reference multiple authoritative sources
</verification_checklist>
```
</pitfall_deprecated_features>
<pitfall_tool_variations>
**What**: Conflating capabilities across different tools/environments
**Example**: "Claude Desktop supports X" ≠ "Claude Code supports X"
**Why it happens**: Not explicitly checking each environment separately
**Prevention**:
```xml
<verification_checklist>
□ Claude Desktop capabilities
□ Claude Code capabilities
□ VS Code extension capabilities
□ API/SDK capabilities
Document which environment supports which features
</verification_checklist>
```
</pitfall_tool_variations>
<pitfall_negative_claims>
**What**: Making definitive "X is not possible" statements without official source verification
**Example**: "Folder-scoped MCP configuration is not supported" (missing `.mcp.json`)
**Why it happens**: Drawing conclusions from absence of evidence rather than evidence of absence
**Prevention**:
```xml
<critical_claims_audit>
For any "X is not possible" or "Y is the only way" statement:
- [ ] Is this verified by official documentation stating it explicitly?
- [ ] Have I checked for recent updates that might change this?
- [ ] Have I verified all possible approaches/mechanisms?
- [ ] Am I confusing "I didn't find it" with "it doesn't exist"?
</critical_claims_audit>
```
</pitfall_negative_claims>
<pitfall_missing_enumeration>
**What**: Investigating open-ended scope without enumerating known possibilities first
**Example**: "Research configuration options" instead of listing specific options to verify
**Why it happens**: Not creating explicit checklist of items to investigate
**Prevention**:
```xml
<verification_checklist>
Enumerate ALL known options FIRST:
□ Option 1: [specific item]
□ Option 2: [specific item]
□ Option 3: [specific item]
□ Check for additional unlisted options
For each option above, document:
- Existence (confirmed/not found/unclear)
- Official source URL
- Current status (active/deprecated/beta)
</verification_checklist>
```
</pitfall_missing_enumeration>
<pitfall_single_source>
**What**: Relying on a single source for critical claims
**Example**: Using only Stack Overflow answer from 2021 for current best practices
**Why it happens**: Not cross-referencing multiple authoritative sources
**Prevention**:
```xml
<source_verification>
For critical claims, require multiple sources:
- [ ] Official documentation (primary)
- [ ] Release notes/changelog (for currency)
- [ ] Additional authoritative source (for verification)
- [ ] Contradiction check (ensure sources agree)
</source_verification>
```
</pitfall_single_source>
<pitfall_assumed_completeness>
**What**: Assuming search results are complete and authoritative
**Example**: First Google result is outdated but assumed current
**Why it happens**: Not verifying publication dates and source authority
**Prevention**:
```xml
<source_verification>
For each source consulted:
- [ ] Publication/update date verified (prefer recent/current)
- [ ] Source authority confirmed (official docs, not blogs)
- [ ] Version relevance checked (matches current version)
- [ ] Multiple search queries tried (not just one)
</source_verification>
```
</pitfall_assumed_completeness>
</known_pitfalls>
<red_flags>
<red_flag_zero_not_found>
**Warning**: Every investigation succeeds perfectly
**Problem**: Real research encounters dead ends, ambiguity, and unknowns
**Action**: Expect honest reporting of limitations, contradictions, and gaps
</red_flag_zero_not_found>
<red_flag_no_confidence>
**Warning**: All findings presented as equally certain
**Problem**: Can't distinguish verified facts from educated guesses
**Action**: Require confidence levels (High/Medium/Low) for key findings
</red_flag_no_confidence>
<red_flag_missing_urls>
**Warning**: "According to documentation..." without specific URL
**Problem**: Can't verify claims or check for updates
**Action**: Require actual URLs for all official documentation claims
</red_flag_missing_urls>
<red_flag_no_evidence>
**Warning**: "X cannot do Y" or "Z is the only way" without citation
**Problem**: Strong claims require strong evidence
**Action**: Flag for verification against official sources
</red_flag_no_evidence>
<red_flag_incomplete_enum>
**Warning**: Verification checklist lists 4 items, output covers 2
**Problem**: Systematic gaps in coverage
**Action**: Ensure all enumerated items addressed or marked "not found"
</red_flag_incomplete_enum>
</red_flags>
<continuous_improvement>
When research gaps occur:
1. **Document the gap**
- What was missed or incorrect?
- What was the actual correct information?
- What was the impact?
2. **Root cause analysis**
- Why wasn't it caught?
- Which verification step would have prevented it?
- What pattern does this reveal?
3. **Update this document**
- Add new pitfall entry
- Update relevant checklists
- Share lesson learned
</continuous_improvement>
<quick_reference>
Before submitting research, verify:
- [ ] All enumerated items investigated (not just some)
- [ ] Negative claims verified with official docs
- [ ] Multiple sources cross-referenced for critical claims
- [ ] URLs provided for all official documentation
- [ ] Publication dates checked (prefer recent/current)
- [ ] Tool/environment-specific variations documented
- [ ] Confidence levels assigned honestly
- [ ] Assumptions distinguished from verified facts
- [ ] "What might I have missed?" review completed
**Living Document**: Update after each significant research gap
**Lessons From**: MCP configuration research gap (missed `.mcp.json`)
</quick_reference>
</research_pitfalls>

451
get-shit-done/references/scope-estimation.md Normal file
View File

@@ -0,0 +1,451 @@
<scope_estimation>
Plans must maintain consistent quality from first task to last. This requires understanding the **quality degradation curve** and splitting aggressively to stay in the peak quality zone.
<quality_degradation_curve>
**Critical insight:** Claude doesn't degrade at arbitrary percentages - it degrades when it *perceives* context pressure and enters "completion mode."
```
Context Usage │ Quality Level │ Claude's Mental State
─────────────────────────────────────────────────────────
0-30% │ ████████ PEAK │ "I can be thorough and comprehensive"
│ │ No anxiety, full detail, best work
30-50% │ ██████ GOOD │ "Still have room, maintaining quality"
│ │ Engaged, confident, solid work
50-70% │ ███ DEGRADING │ "Getting tight, need to be efficient"
│ │ Efficiency mode, compression begins
70%+ │ █ POOR │ "Running out, must finish quickly"
│ │ Self-lobotomization, rushed, minimal
```
**The 40-50% inflection point:**
This is where quality breaks. Claude sees context mounting and thinks "I'd better conserve now or I won't finish." Result: The classic mid-execution statement "I'll complete the remaining tasks more concisely" = quality crash.
**The fundamental rule:** Stop BEFORE quality degrades, not at context limit.
</quality_degradation_curve>
<context_target>
**Plans should complete within ~50% of context usage.**
Why 50% not 80%?
- Huge safety buffer
- No context anxiety possible
- Quality maintained from start to finish
- Room for unexpected complexity
- Space for iteration and fixes
**If you target 80%, you're planning for failure.** By the time you hit 80%, you've already spent 40% in degradation mode.
</context_target>
<task_rule>
**Each plan should contain 2-3 tasks maximum. Context usage matters more than task count.**
**The real measure: Stay under 50% context usage.**
Task count is a proxy for context. Adjust based on task complexity:
**Simple tasks (CRUD, config, basic features):**
- 3 tasks is fine
- Each burns ~10-15% context
- Total: ~30-45% → Safe
**Complex tasks (auth, payments, architecture, integrations):**
- Stick to 2 tasks
- Each burns ~20-30% context
- Total: ~40-50% → At limit
**Very complex tasks (migrations, major refactors, novel patterns):**
- Consider 1-2 tasks only
- Each can burn 30-40% context
- Splitting to 1 task/plan is valid for high complexity
**Context estimation by task type:**
**Task 1 (0-15% context for simple, 0-30% for complex):**
- Fresh context
- Peak quality
- Comprehensive implementation
- Full testing
**Task 2 (15-35% context for simple, 30-50% for complex):**
- Still good quality
- Context pressure manageable
- Natural stopping point for complex work
**Task 3 (35-50% context for simple only):**
- Only include for simple tasks
- Skip for complex work
- Better to split complex work at 2 tasks
**Task 4+ (50%+ context):**
- NEVER do this
- Quality guaranteed to degrade
- Should have split earlier
**When in doubt: Default to 2 tasks.** Better to have an extra plan than degraded quality.
**The principle:** Each plan completes within 50% context. Task count is flexible based on complexity.
</task_rule>
<split_signals>
<always_split>
**1. More than 3 tasks**
- Even if tasks seem small
- Each additional task increases degradation risk
- Split into logical groups of 2-3
**2. Multiple subsystems**
```
❌ Bad (1 plan):
- Database schema (3 files)
- API routes (5 files)
- UI components (8 files)
Total: 16 files, 1 plan → guaranteed degradation
✅ Good (3 plans):
- 01-01-PLAN.md: Database schema (3 files, 2 tasks)
- 01-02-PLAN.md: API routes (5 files, 3 tasks)
- 01-03-PLAN.md: UI components (8 files, 3 tasks)
Total: 16 files, 3 plans → consistent quality
```
**3. Any task with >5 file modifications**
- Large tasks burn context fast
- Split by file groups or logical units
- Better: 3 plans of 2 files each vs 1 plan of 6 files
**4. Checkpoint + implementation work**
- Checkpoints require user interaction (context preserved)
- Implementation after checkpoint should be separate plan
✅ Good split:
- 02-01-PLAN.md: Setup (checkpoint: decision on auth provider)
- 02-02-PLAN.md: Implement chosen auth solution
**5. Research + implementation**
- Research produces FINDINGS.md (separate plan)
- Implementation consumes FINDINGS.md (separate plan)
- Clear boundary, clean handoff
</always_split>
<consider_splitting>
**1. Estimated >5 files modified total**
- Context from reading existing code
- Context from diffs
- Context from responses
- Adds up faster than expected
**2. Complex domains (auth, payments, data modeling)**
- These require careful thinking
- Burns more context per task than simple CRUD
- Split more aggressively
**3. Any uncertainty about approach**
- "Figure out X" phase separate from "implement X" phase
- Don't mix exploration and implementation
**4. Natural semantic boundaries**
- Setup → Core → Features
- Backend → Frontend
- Configuration → Implementation → Testing
</consider_splitting>
</split_signals>
<splitting_strategies>
<by_subsystem>
**Phase:** "Authentication System"
**Split:**
```
- 03-01-PLAN.md: Database models (User, Session tables + relations)
- 03-02-PLAN.md: Auth API (register, login, logout endpoints)
- 03-03-PLAN.md: Protected routes (middleware, JWT validation)
- 03-04-PLAN.md: UI components (login form, registration form)
```
Each plan: 2-3 tasks, single subsystem, clean commits.
</by_subsystem>
<by_dependency>
**Phase:** "Payment Integration"
**Split:**
```
- 04-01-PLAN.md: Stripe setup (webhook endpoints via API, env vars, test mode)
- 04-02-PLAN.md: Subscription logic (plans, checkout, customer portal)
- 04-03-PLAN.md: Frontend integration (pricing page, payment flow)
```
Later plans depend on earlier completion. Sequential execution, fresh context each time.
</by_dependency>
<by_complexity>
**Phase:** "Dashboard Buildout"
**Split:**
```
- 05-01-PLAN.md: Layout shell (simple: sidebar, header, routing)
- 05-02-PLAN.md: Data fetching (moderate: TanStack Query setup, API integration)
- 05-03-PLAN.md: Data visualization (complex: charts, tables, real-time updates)
```
Complex work gets its own plan with full context budget.
</by_complexity>
<by_verification_points>
**Phase:** "Deployment Pipeline"
**Split:**
```
- 06-01-PLAN.md: Vercel setup (deploy via CLI, configure domains)
→ Ends with checkpoint:human-verify "check xyz.vercel.app loads"
- 06-02-PLAN.md: Environment config (secrets via CLI, env vars)
→ Autonomous (no checkpoints) → subagent execution
- 06-03-PLAN.md: CI/CD (GitHub Actions, preview deploys)
→ Ends with checkpoint:human-verify "check PR preview works"
```
Verification checkpoints create natural boundaries. Autonomous plans between checkpoints execute via subagent with fresh context.
</by_verification_points>
</splitting_strategies>
<autonomous_vs_interactive>
**Critical optimization:** Plans without checkpoints don't need main context.
<autonomous_plans>
- Contains only `type="auto"` tasks
- No user interaction needed
- **Execute via subagent with fresh 200k context**
- Impossible to degrade (always starts at 0%)
- Creates SUMMARY, commits, reports back
- Can run in parallel (multiple subagents)
</autonomous_plans>
<interactive_plans>
- Contains `checkpoint:human-verify` or `checkpoint:decision` tasks
- Requires user interaction
- Must execute in main context
- Still target 50% context (2-3 tasks)
**Planning guidance:** If splitting a phase, try to:
- Group autonomous work together (→ subagent)
- Separate interactive work (→ main context)
- Maximize autonomous plans (more fresh contexts)
Example:
```
Phase: Feature X
- 07-01-PLAN.md: Backend (autonomous) → subagent
- 07-02-PLAN.md: Frontend (autonomous) → subagent
- 07-03-PLAN.md: Integration test (has checkpoint:human-verify) → main context
```
Two fresh contexts, one interactive verification. Perfect.
</interactive_plans>
</autonomous_vs_interactive>
<anti_patterns>
<antipattern_comprehensive>
```
Plan: "Complete Authentication System"
Tasks:
1. Database models
2. Migration files
3. Auth API endpoints
4. JWT utilities
5. Protected route middleware
6. Password hashing
7. Login form component
8. Registration form component
Result: 8 tasks, 80%+ context, degradation at task 4-5
```
**Why this fails:**
- Task 1-3: Good quality
- Task 4-5: "I'll do these concisely" = degradation begins
- Task 6-8: Rushed, minimal, poor quality
</antipattern_comprehensive>
<pattern_atomic>
```
Split into 4 plans:
Plan 1: "Auth Database Models" (2 tasks)
- Database schema (User, Session)
- Migration files
Plan 2: "Auth API Core" (3 tasks)
- Register endpoint
- Login endpoint
- JWT utilities
Plan 3: "Auth API Protection" (2 tasks)
- Protected route middleware
- Logout endpoint
Plan 4: "Auth UI Components" (2 tasks)
- Login form
- Registration form
```
**Why this succeeds:**
- Each plan: 2-3 tasks, 30-40% context
- All tasks: Peak quality throughout
- Git history: 4 focused commits
- Easy to verify each piece
- Rollback is surgical
</pattern_atomic>
<antipattern_efficiency_trap>
```
Thinking: "These tasks are small, let's do 6 to be efficient"
Result: Task 1-2 are good, task 3-4 begin degrading, task 5-6 are rushed
```
**Why this fails:** You're optimizing for fewer plans, not quality. The "efficiency" is false - poor quality requires more rework.
</antipattern_efficiency_trap>
<pattern_quality_first>
```
Thinking: "These tasks are small, but let's do 2-3 to guarantee quality"
Result: All tasks peak quality, clean commits, no rework needed
```
**Why this succeeds:** You optimize for quality, which is true efficiency. No rework = faster overall.
</pattern_quality_first>
</anti_patterns>
<estimating_context>
**Rough heuristics for plan size:**
<file_counts>
- 0-3 files modified: Small task (~10-15% context)
- 4-6 files modified: Medium task (~20-30% context)
- 7+ files modified: Large task (~40%+ context) - split this
</file_counts>
<complexity>
- Simple CRUD: ~15% per task
- Business logic: ~25% per task
- Complex algorithms: ~40% per task
- Domain modeling: ~35% per task
</complexity>
<two_task_plan>
- 2 simple tasks: ~30% total ✅ Plenty of room
- 2 medium tasks: ~50% total ✅ At target
- 2 complex tasks: ~80% total ❌ Too tight, split
</two_task_plan>
<three_task_plan>
- 3 simple tasks: ~45% total ✅ Good
- 3 medium tasks: ~75% total ⚠️ Pushing it
- 3 complex tasks: 120% total ❌ Impossible, split
**Conservative principle:** When in doubt, split. Better to have an extra plan than degraded quality.
</three_task_plan>
</estimating_context>
<atomic_commits>
**What we're optimizing for:** Beautiful git history where each commit is:
- Focused (2-3 related changes)
- Complete (fully implemented, tested)
- Documented (clear commit message)
- Reviewable (small enough to understand)
- Revertable (surgical rollback possible)
**Bad git history (large plans):**
```
feat(auth): Complete authentication system
- Added 16 files
- Modified 8 files
- 1200 lines changed
- Contains: models, API, UI, middleware, utilities
```
Impossible to review, hard to understand, can't revert without losing everything.
**Good git history (atomic plans):**
```
feat(auth-01): Add User and Session database models
- Added schema files
- Added migration
- 45 lines changed
feat(auth-02): Implement register and login API endpoints
- Added /api/auth/register
- Added /api/auth/login
- Added JWT utilities
- 120 lines changed
feat(auth-03): Add protected route middleware
- Added middleware/auth.ts
- Added tests
- 60 lines changed
feat(auth-04): Build login and registration forms
- Added LoginForm component
- Added RegisterForm component
- 90 lines changed
```
Each commit tells a story. Each is reviewable. Each is revertable. This is craftsmanship.
</atomic_commits>
<quality_assurance>
**The guarantee:** When you follow the 2-3 task rule with 50% context target:
1. **Consistency:** First task has same quality as last task
2. **Thoroughness:** No "I'll complete X concisely" degradation
3. **Documentation:** Full context budget for comments/tests
4. **Error handling:** Space for proper validation and edge cases
5. **Testing:** Room for comprehensive test coverage
**The cost:** More plans to manage.
**The benefit:** Consistent excellence. No rework. Clean history. Maintainable code.
**The trade-off is worth it.**
</quality_assurance>
<summary>
**2-3 tasks, 50% context target:**
- All tasks: Peak quality
- Git: Atomic, surgical commits
- Quality: Consistent excellence
- Autonomous plans: Subagent execution (fresh context)
**The principle:** Aggressive atomicity. More plans, smaller scope, consistent quality.
**The rule:** If in doubt, split. Quality over consolidation. Always.
</summary>
</scope_estimation>

17
get-shit-done/templates/config.json Normal file
View File

@@ -0,0 +1,17 @@
{
"mode": "interactive",
"gates": {
"confirm_project": true,
"confirm_phases": true,
"confirm_roadmap": true,
"confirm_breakdown": true,
"confirm_plan": true,
"execute_next_plan": true,
"issues_review": true,
"confirm_transition": true
},
"safety": {
"always_confirm_destructive": true,
"always_confirm_external_services": true
}
}

385
get-shit-done/templates/context.md Normal file
View File

@@ -0,0 +1,385 @@
# Phase Context Template
Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - phase context documentation gathered before planning.
**Purpose:** Capture comprehensive context through adaptive questioning to inform high-quality planning.
---
## File Template
```markdown
# Phase [X]: [Name] - Context
**Gathered:** [date]
**Status:** [For planning / Planning complete]
<phase_objectives>
## What This Phase Accomplishes
[Clear, specific description of what this phase delivers]
**Primary goal:**
[Main objective - what ships at the end]
**Secondary goals:**
[Supporting objectives or nice-to-haves]
**Out of scope:**
[What this phase explicitly does NOT include - prevents scope creep]
</phase_objectives>
<constraints>
## Constraints
**Technical:**
[Library choices, platform requirements, compatibility needs, existing architecture patterns to follow]
**Timeline:**
[Deadlines, urgency, sequencing dependencies]
**Resources:**
[Budget limits, API rate limits, storage constraints, computational limits]
**Dependencies:**
[What must exist before this phase can start, external factors, waiting on other teams/services]
**Other:**
[Any other constraints affecting approach]
[If no constraints: "None - flexible approach"]
</constraints>
<risks>
## Risks and Mitigation
**Risk 1: [Risk description]**
- **Likelihood:** [High / Medium / Low]
- **Impact:** [High / Medium / Low]
- **Mitigation:** [How to prevent or handle this]
**Risk 2: [Risk description]**
- **Likelihood:** [High / Medium / Low]
- **Impact:** [High / Medium / Low]
- **Mitigation:** [How to prevent or handle this]
[Continue for identified risks]
[If no major risks: "No major risks identified - straightforward implementation expected"]
</risks>
<success_indicators>
## Success Indicators
**How we'll know this phase is complete:**
**Functional:**
- [ ] [Specific feature works correctly]
- [ ] [Tests pass for X functionality]
- [ ] [Integration with Y system verified]
**Quality:**
- [ ] [Performance meets X threshold]
- [ ] [No TypeScript errors]
- [ ] [Test coverage >= X%]
**Deployment:**
- [ ] [Changes deployed to staging/production]
- [ ] [Verification in live environment]
**Documentation:**
- [ ] [API documented]
- [ ] [README updated]
- [ ] [Migration guide if needed]
**User-facing:**
- [ ] [Visual verification complete]
- [ ] [User testing passed]
- [ ] [Acceptance criteria met]
</success_indicators>
<codebase_context>
## Codebase State and Patterns
**Current state:**
[Fresh project / Established codebase / Legacy system / Mid-refactor]
**Relevant files/systems:**
- `path/to/relevant.ts` - [What this does and why it matters for this phase]
- `path/to/another.ts` - [What this does and why it matters for this phase]
**Patterns to follow:**
[Existing conventions, architectural patterns, naming conventions, testing patterns]
**External dependencies:**
- [Library/service 1] - [How it's used, version constraints]
- [Library/service 2] - [How it's used, version constraints]
**Known issues to address:**
[From ISSUES.md or prior phases - issues this phase should fix]
**Prior decisions affecting this phase:**
[From STATE.md - decisions from previous phases that constrain approach]
</codebase_context>
<decisions_needed>
## Decisions That Will Affect Implementation
**Decision 1: [What needs deciding]**
- **Context:** [Why this matters]
- **Options:** [Brief list of approaches]
- **When to decide:** [During planning / During task X / Before starting]
**Decision 2: [What needs deciding]**
- **Context:** [Why this matters]
- **Options:** [Brief list of approaches]
- **When to decide:** [During planning / During task X / Before starting]
[If no decisions needed: "No open decisions - approach is clear from roadmap and context"]
</decisions_needed>
<notes>
## Additional Context
[Any other relevant information gathered during context discussion]
[Questions asked during intake:]
- Q: [Question asked]
- A: [Answer received]
[Clarifications:]
- [Important points clarified during discussion]
[References:]
- [Links to relevant docs, prior art, examples]
[If no additional notes: "No additional notes"]
</notes>
---
*Phase: XX-name*
*Context gathered: [date]*
*Ready for planning: [yes/no]*
```
<good_examples>
```markdown
# Phase 3: Authentication - Context
**Gathered:** 2025-01-20
**Status:** For planning
<phase_objectives>
## What This Phase Accomplishes
Implement JWT-based authentication with secure session management.
**Primary goal:**
Users can register, login, logout with JWT tokens stored in httpOnly cookies. Protected routes verify authentication.
**Secondary goals:**
- Password reset flow via email
- Remember me functionality
- Session expiry and refresh
**Out of scope:**
- OAuth providers (Google, GitHub) - deferred to Phase 4
- 2FA - deferred to Phase 5
- Role-based access control - deferred to Phase 6
</phase_objectives>
<constraints>
## Constraints
**Technical:**
- Must use jose library (NOT jsonwebtoken - ESM compatibility requirement from Phase 1)
- Must work in Edge runtime (Next.js middleware requirement)
- Passwords must use bcrypt with minimum 10 salt rounds
- Database already has User model from Phase 2 (extend, don't recreate)
**Timeline:**
- Target completion: End of week 3
- Blocking Phase 4 (user profiles) and Phase 5 (product catalog)
**Resources:**
- Email sending limited to 100/day on current SendGrid plan (affects password reset testing)
**Dependencies:**
- Phase 2 complete (database models)
- Phase 1 complete (Next.js setup)
- SendGrid API key obtained (checkpoint for email features)
**Other:**
None
</constraints>
<risks>
## Risks and Mitigation
**Risk 1: JWT token size causing cookie overflow**
- **Likelihood:** Low
- **Impact:** High (authentication breaks)
- **Mitigation:** Keep JWT payload minimal (user ID only), store other data in database session table. Test with realistic tokens early.
**Risk 2: Session timing causing UX issues**
- **Likelihood:** Medium
- **Impact:** Medium (user frustration)
- **Mitigation:** Implement refresh token rotation, clear error messages on expiry, test user flows thoroughly.
**Risk 3: Password reset token security**
- **Likelihood:** Low
- **Impact:** High (account takeover)
- **Mitigation:** Use crypto.randomBytes(32) for tokens, short expiry (1 hour), single-use tokens, rate limiting on reset endpoint.
</risks>
<success_indicators>
## Success Indicators
**How we'll know this phase is complete:**
**Functional:**
- [ ] User can register with email/password
- [ ] User can login and receive JWT cookie
- [ ] Protected routes redirect unauthenticated users
- [ ] User can logout (cookie cleared)
- [ ] Password reset flow works end-to-end
**Quality:**
- [ ] No passwords stored in plaintext
- [ ] JWT tokens validated correctly
- [ ] Tests pass for all auth endpoints
- [ ] No TypeScript errors
- [ ] Test coverage >= 80% for auth code
**Deployment:**
- [ ] Auth endpoints deployed to staging
- [ ] Verified in staging environment
- [ ] Production environment variables configured
**Documentation:**
- [ ] API endpoints documented
- [ ] Authentication flow diagram added to README
- [ ] Environment variables documented
**User-facing:**
- [ ] Login/logout flows tested manually
- [ ] Error messages clear and helpful
- [ ] Password reset tested with real email
</success_indicators>
<codebase_context>
## Codebase State and Patterns
**Current state:**
Established codebase - Phase 2 complete with database models, Phase 1 has Next.js structure.
**Relevant files/systems:**
- `prisma/schema.prisma` - User model exists, need to add Session model
- `src/app/api/*` - API route conventions established in Phase 2
- `src/middleware.ts` - Next.js middleware file (create for protected routes)
- `src/lib/db.ts` - Database connection helper from Phase 2
**Patterns to follow:**
- API routes return JSON with `{ success: boolean, data?: any, error?: string }`
- Use Zod for request validation (established in Phase 2)
- Database queries in try/catch with error logging
- Tests colocated: `route.test.ts` next to `route.ts`
**External dependencies:**
- jose@5.2.0 - JWT library (decision from Phase 1)
- bcrypt@5.1.1 - Password hashing
- @sendgrid/mail - Email sending (need to add)
- zod@3.22.4 - Validation (already installed)
**Known issues to address:**
- ISS-002 from Phase 2: Add rate limiting to API endpoints (include auth endpoints)
**Prior decisions affecting this phase:**
- Phase 1: Use jose for JWT (ESM-native, Edge-compatible)
- Phase 2: API response format established (all endpoints must follow)
- Phase 2: Zod validation pattern established (use for auth requests)
</codebase_context>
<decisions_needed>
## Decisions That Will Affect Implementation
**Decision 1: Token expiry timing**
- **Context:** Balance security (short expiry) vs UX (avoid frequent re-login)
- **Options:** 15min access + 7day refresh / 1hr access + 30day refresh / 4hr access + 90day refresh
- **When to decide:** During planning (affects implementation)
**Decision 2: Remember me implementation**
- **Context:** How to handle "remember me" checkbox on login
- **Options:** Longer refresh token / Separate persistent token / Browser local storage flag
- **When to decide:** During task breakdown (affects token strategy)
</decisions_needed>
<notes>
## Additional Context
[Questions asked during intake:]
- Q: Are there constraints I should know about?
- A: Technical limitations - must use jose library, work in Edge runtime
- Q: What could go wrong in this phase?
- A: Security concerns - authentication vulnerabilities are critical
- Q: Which files or systems should I examine for context?
- A: Check prisma/schema.prisma for User model, src/app/api/* for API patterns
[Clarifications:]
- User stressed security is paramount - better to be overly cautious
- Password reset is "nice to have" but not blocking for Phase 4
- OAuth can wait - just email/password for now
[References:]
- OWASP Auth Cheatsheet: https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html
- jose docs: https://github.com/panva/jose
</notes>
---
*Phase: 03-authentication*
*Context gathered: 2025-01-20*
*Ready for planning: yes*
```
</good_examples>
<guidelines>
**When to create:**
- Before planning a phase (via /gsd:discuss-phase command)
- When roadmap description is too brief for quality planning
- When phase involves complex decisions or risks
**Structure:**
- Use XML tags for section markers (matches GSD templates)
- Five core sections: objectives, constraints, risks, success_indicators, codebase_context
- Two supporting sections: decisions_needed, notes
- All sections required (use "None" if truly not applicable)
**Content quality:**
- Objectives: Specific and measurable (not "add auth" but "JWT auth with registration, login, logout, password reset")
- Constraints: Technical/timeline/resource specifics (not "be fast" but "must work in Edge runtime")
- Risks: Include likelihood, impact, mitigation (not just "might break")
- Success indicators: Checklist format, specific criteria
- Codebase context: Reference actual files and patterns
- Decisions needed: Note when decision should be made (planning vs execution)
**Out of scope:**
- Document what phase does NOT include (prevents scope creep)
- Reference deferred items from roadmap
- Note what's pushed to future phases
**Integration with planning:**
- CONTEXT.md loaded as @context reference in PLAN.md
- Decisions inform task breakdown
- Risks inform verification criteria
- Success indicators become plan success criteria
- Prior decisions become task action notes
**After creation:**
- File lives in phase directory: `.planning/phases/XX-name/{phase}-CONTEXT.md`
- Referenced during planning workflow
- Can be updated if context changes before planning
</guidelines>

78
get-shit-done/templates/continue-here.md Normal file
View File

@@ -0,0 +1,78 @@
# Continue-Here Template
Copy and fill this structure for `.planning/phases/XX-name/.continue-here.md`:
```yaml
---
phase: XX-name
task: 3
total_tasks: 7
status: in_progress
last_updated: 2025-01-15T14:30:00Z
---
```
```markdown
<current_state>
[Where exactly are we? What's the immediate context?]
</current_state>
<completed_work>
[What got done this session - be specific]
- Task 1: [name] - Done
- Task 2: [name] - Done
- Task 3: [name] - In progress, [what's done on it]
</completed_work>
<remaining_work>
[What's left in this phase]
- Task 3: [name] - [what's left to do]
- Task 4: [name] - Not started
- Task 5: [name] - Not started
</remaining_work>
<decisions_made>
[Key decisions and why - so next session doesn't re-debate]
- Decided to use [X] because [reason]
- Chose [approach] over [alternative] because [reason]
</decisions_made>
<blockers>
[Anything stuck or waiting on external factors]
- [Blocker 1]: [status/workaround]
</blockers>
<context>
[Mental state, "vibe", anything that helps resume smoothly]
[What were you thinking about? What was the plan?
This is the "pick up exactly where you left off" context.]
</context>
<next_action>
[The very first thing to do when resuming]
Start with: [specific action]
</next_action>
```
<yaml_fields>
Required YAML frontmatter:
- `phase`: Directory name (e.g., `02-authentication`)
- `task`: Current task number
- `total_tasks`: How many tasks in phase
- `status`: `in_progress`, `blocked`, `almost_done`
- `last_updated`: ISO timestamp
</yaml_fields>
<guidelines>
- Be specific enough that a fresh Claude instance understands immediately
- Include WHY decisions were made, not just what
- The `<next_action>` should be actionable without reading anything else
- This file gets DELETED after resume - it's not permanent storage
</guidelines>

32
get-shit-done/templates/issues.md Normal file
View File

@@ -0,0 +1,32 @@
# Project Issues Log
Enhancements discovered during execution. Not critical - address in future phases.
## Open Enhancements
### ISS-001: [Brief description]
- **Discovered:** Phase [X] Task [Z] (YYYY-MM-DD)
- **Type:** [Performance / Refactoring / UX / Testing / Documentation / Accessibility]
- **Description:** [What could be improved and why it would help]
- **Impact:** Low (works correctly, this would enhance)
- **Effort:** [Quick / Medium / Substantial]
- **Suggested phase:** [Phase number or "Future"]
## Closed Enhancements
[Moved here when addressed]
---
## Template Notes
**When to create:** First time Rule 5 (log enhancements) triggers during execution.
**Location:** `.planning/ISSUES.md`
**ISS numbering:** Auto-increment from highest existing number.
**Entry format:** Copy the ISS-001 block, update number and fields.
**Closing issues:** Move entire block to "Closed Enhancements" section, add resolution note.

123
get-shit-done/templates/milestone-archive.md Normal file
View File

@@ -0,0 +1,123 @@
# Milestone Archive Template
This template is used by the complete-milestone workflow to create archive files in `.planning/milestones/`.
---
## File Template
# Milestone v{{VERSION}}: {{MILESTONE_NAME}}
**Status:** ✅ SHIPPED {{DATE}}
**Phases:** {{PHASE_START}}-{{PHASE_END}}
**Total Plans:** {{TOTAL_PLANS}}
## Overview
{{MILESTONE_DESCRIPTION}}
## Phases
{{PHASES_SECTION}}
[For each phase in this milestone, include:]
### Phase {{PHASE_NUM}}: {{PHASE_NAME}}
**Goal**: {{PHASE_GOAL}}
**Depends on**: {{DEPENDS_ON}}
**Plans**: {{PLAN_COUNT}} plans
Plans:
- [x] {{PHASE}}-01: {{PLAN_DESCRIPTION}}
- [x] {{PHASE}}-02: {{PLAN_DESCRIPTION}}
[... all plans ...]
**Details:**
{{PHASE_DETAILS_FROM_ROADMAP}}
**For decimal phases, include (INSERTED) marker:**
### Phase 2.1: Critical Security Patch (INSERTED)
**Goal**: Fix authentication bypass vulnerability
**Depends on**: Phase 2
**Plans**: 1 plan
Plans:
- [x] 2.1-01: Patch auth vulnerability
**Details:**
{{PHASE_DETAILS_FROM_ROADMAP}}
---
## Milestone Summary
**Decimal Phases:**
- Phase 2.1: Critical Security Patch (inserted after Phase 2 for urgent fix)
- Phase 5.1: Performance Hotfix (inserted after Phase 5 for production issue)
**Key Decisions:**
{{DECISIONS_FROM_PROJECT_STATE}}
[Example:]
- Decision: Use ROADMAP.md split (Rationale: Constant context cost)
- Decision: Decimal phase numbering (Rationale: Clear insertion semantics)
**Issues Resolved:**
{{ISSUES_RESOLVED_DURING_MILESTONE}}
[Example:]
- Fixed context overflow at 100+ phases
- Resolved phase insertion confusion
**Issues Deferred:**
{{ISSUES_DEFERRED_TO_LATER}}
[Example:]
- PROJECT-STATE.md tiering (deferred until decisions > 300)
**Technical Debt Incurred:**
{{SHORTCUTS_NEEDING_FUTURE_WORK}}
[Example:]
- Some workflows still have hardcoded paths (fix in Phase 5)
---
_For current project status, see .planning/ROADMAP.md_
---
## Usage Guidelines
<guidelines>
**When to create milestone archives:**
- After completing all phases in a milestone (v1.0, v1.1, v2.0, etc.)
- Triggered by complete-milestone workflow
- Before planning next milestone work
**How to fill template:**
- Replace {{PLACEHOLDERS}} with actual values
- Extract phase details from ROADMAP.md
- Document decimal phases with (INSERTED) marker
- Include key decisions from PROJECT-STATE.md or SUMMARY files
- List issues resolved vs deferred
- Capture technical debt for future reference
**Archive location:**
- Save to `.planning/milestones/v{VERSION}-{NAME}.md`
- Example: `.planning/milestones/v1.0-mvp.md`
**After archiving:**
- Update ROADMAP.md to collapse completed milestone in `<details>` tag
- Update PROJECT.md to brownfield format with Current State section
- Continue phase numbering in next milestone (never restart at 01)
</guidelines>

115
get-shit-done/templates/milestone.md Normal file
View File

@@ -0,0 +1,115 @@
# Milestone Entry Template
Add this entry to `.planning/MILESTONES.md` when completing a milestone:
```markdown
## v[X.Y] [Name] (Shipped: YYYY-MM-DD)
**Delivered:** [One sentence describing what shipped]
**Phases completed:** [X-Y] ([Z] plans total)
**Key accomplishments:**
- [Major achievement 1]
- [Major achievement 2]
- [Major achievement 3]
- [Major achievement 4]
**Stats:**
- [X] files created/modified
- [Y] lines of code (primary language)
- [Z] phases, [N] plans, [M] tasks
- [D] days from start to ship (or milestone to milestone)
**Git range:** `feat(XX-XX)` → `feat(YY-YY)`
**What's next:** [Brief description of next milestone goals, or "Project complete"]
---
```
<structure>
If MILESTONES.md doesn't exist, create it with header:
```markdown
# Project Milestones: [Project Name]
[Entries in reverse chronological order - newest first]
```
</structure>
<guidelines>
**When to create milestones:**
- Initial v1.0 MVP shipped
- Major version releases (v2.0, v3.0)
- Significant feature milestones (v1.1, v1.2)
- Before archiving planning (capture what was shipped)
**Don't create milestones for:**
- Individual phase completions (normal workflow)
- Work in progress (wait until shipped)
- Minor bug fixes that don't constitute a release
**Stats to include:**
- Count modified files: `git diff --stat feat(XX-XX)..feat(YY-YY) | tail -1`
- Count LOC: `find . -name "*.swift" -o -name "*.ts" | xargs wc -l` (or relevant extension)
- Phase/plan/task counts from ROADMAP
- Timeline from first phase commit to last phase commit
**Git range format:**
- First commit of milestone → last commit of milestone
- Example: `feat(01-01)` → `feat(04-01)` for phases 1-4
</guidelines>
<example>
```markdown
# Project Milestones: WeatherBar
## v1.1 Security & Polish (Shipped: 2025-12-10)
**Delivered:** Security hardening with Keychain integration and comprehensive error handling
**Phases completed:** 5-6 (3 plans total)
**Key accomplishments:**
- Migrated API key storage from plaintext to macOS Keychain
- Implemented comprehensive error handling for network failures
- Added Sentry crash reporting integration
- Fixed memory leak in auto-refresh timer
**Stats:**
- 23 files modified
- 650 lines of Swift added
- 2 phases, 3 plans, 12 tasks
- 8 days from v1.0 to v1.1
**Git range:** `feat(05-01)` → `feat(06-02)`
**What's next:** v2.0 SwiftUI redesign with widget support
---
## v1.0 MVP (Shipped: 2025-11-25)
**Delivered:** Menu bar weather app with current conditions and 3-day forecast
**Phases completed:** 1-4 (7 plans total)
**Key accomplishments:**
- Menu bar app with popover UI (AppKit)
- OpenWeather API integration with auto-refresh
- Current weather display with conditions icon
- 3-day forecast list with high/low temperatures
- Code signed and notarized for distribution
**Stats:**
- 47 files created
- 2,450 lines of Swift
- 4 phases, 7 plans, 28 tasks
- 12 days from start to ship
**Git range:** `feat(01-01)` → `feat(04-01)`
**What's next:** Security audit and hardening for v1.1
```
</example>

290
get-shit-done/templates/phase-prompt.md Normal file
View File

@@ -0,0 +1,290 @@
# Phase Prompt Template
Template for `.planning/phases/XX-name/{phase}-{plan}-PLAN.md` - executable phase plans.
**Naming:** Use `{phase}-{plan}-PLAN.md` format (e.g., `01-02-PLAN.md` for Phase 1, Plan 2)
---
## File Template
```markdown
---
phase: XX-name
type: execute
domain: [optional - if domain skill loaded]
---
<objective>
[What this phase accomplishes - from roadmap phase goal]
Purpose: [Why this matters for the project]
Output: [What artifacts will be created]
</objective>
<execution_context>
~/.claude/get-shit-done/workflows/execute-phase.md
./summary.md
[If plan contains checkpoint tasks (type="checkpoint:*"), add:]
~/.claude/get-shit-done/references/checkpoints.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
[If research exists:]
@.planning/phases/XX-name/FINDINGS.md
[Relevant source files:]
@src/path/to/relevant.ts
</context>
<tasks>
<task type="auto">
<name>Task 1: [Action-oriented name]</name>
<files>path/to/file.ext, another/file.ext</files>
<action>[Specific implementation - what to do, how to do it, what to avoid and WHY]</action>
<verify>[Command or check to prove it worked]</verify>
<done>[Measurable acceptance criteria]</done>
</task>
<task type="auto">
<name>Task 2: [Action-oriented name]</name>
<files>path/to/file.ext</files>
<action>[Specific implementation]</action>
<verify>[Command or check]</verify>
<done>[Acceptance criteria]</done>
</task>
<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>
</options>
<resume-signal>[How to indicate choice - "Select: option-a or option-b"]</resume-signal>
</task>
<task type="auto">
<name>Task 3: [Action-oriented name]</name>
<files>path/to/file.ext</files>
<action>[Specific implementation]</action>
<verify>[Command or check]</verify>
<done>[Acceptance criteria]</done>
</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>
</task>
[Continue for all tasks - mix of auto and checkpoints as needed...]
</tasks>
<verification>
Before declaring phase complete:
- [ ] [Specific test command]
- [ ] [Build/type check passes]
- [ ] [Behavior verification]
</verification>
<success_criteria>
- All tasks completed
- All verification checks pass
- No errors or warnings introduced
- [Phase-specific criteria]
</success_criteria>
<output>
After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`:
# Phase [X] Plan [Y]: [Name] Summary
**[Substantive one-liner - what shipped, not "phase complete"]**
## Accomplishments
- [Key outcome 1]
- [Key outcome 2]
## Files Created/Modified
- `path/to/file.ts` - Description
- `path/to/another.ts` - Description
## Decisions Made
[Key decisions and rationale, or "None"]
## Issues Encountered
[Problems and resolutions, or "None"]
## Next Step
[If more plans in this phase: "Ready for {phase}-{next-plan}-PLAN.md"]
[If phase complete: "Phase complete, ready for next phase"]
</output>
```
<key_elements>
From create-meta-prompts patterns:
- XML structure for Claude parsing
- @context references for file loading
- Task types: auto, checkpoint:human-action, checkpoint:human-verify, checkpoint:decision
- Action includes "what to avoid and WHY" (from intelligence-rules)
- Verification is specific and executable
- Success criteria is measurable
- Output specification includes SUMMARY.md structure
</key_elements>
<scope_guidance>
**Plan sizing:**
- Aim for 2-3 tasks per plan
- If planning >3 tasks, split into multiple plans (01-01, 01-02, etc.)
- Target ~50% context usage maximum
- Complex phases: Create 01-01, 01-02, 01-03 plans instead of one large plan
**When to split:**
- Different subsystems (auth vs API vs UI)
- Clear dependency boundaries (setup → implement → test)
- Risk of context overflow (>50% estimated usage)
</scope_guidance>
<good_examples>
```markdown
---
phase: 01-foundation
type: execute
domain: next-js
---
<objective>
Set up Next.js project with authentication foundation.
Purpose: Establish the core structure and auth patterns all features depend on.
Output: Working Next.js app with JWT auth, protected routes, and user model.
</objective>
<execution_context>
~/.claude/get-shit-done/workflows/execute-phase.md
./summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@src/lib/db.ts
</context>
<tasks>
<task type="auto">
<name>Task 1: Add User model to database schema</name>
<files>prisma/schema.prisma</files>
<action>Add User model with fields: id (cuid), email (unique), passwordHash, createdAt, updatedAt. Add Session relation. Use @db.VarChar(255) for email to prevent index issues.</action>
<verify>npx prisma validate passes, npx prisma generate succeeds</verify>
<done>Schema valid, types generated, no errors</done>
</task>
<task type="auto">
<name>Task 2: Create login API endpoint</name>
<files>src/app/api/auth/login/route.ts</files>
<action>POST endpoint that accepts {email, password}, validates against User table using bcrypt, returns JWT in httpOnly cookie with 15-min expiry. Use jose library for JWT (not jsonwebtoken - it has CommonJS issues with Next.js).</action>
<verify>curl -X POST /api/auth/login -d '{"email":"test@test.com","password":"test"}' -H "Content-Type: application/json" returns 200 with Set-Cookie header</verify>
<done>Valid credentials return 200 + cookie, invalid return 401, missing fields return 400</done>
</task>
</tasks>
<verification>
Before declaring phase complete:
- [ ] `npm run build` succeeds without errors
- [ ] `npx prisma validate` passes
- [ ] Login endpoint responds correctly to valid/invalid credentials
- [ ] Protected route redirects unauthenticated users
</verification>
<success_criteria>
- All tasks completed
- All verification checks pass
- No TypeScript errors
- JWT auth flow works end-to-end
</success_criteria>
<output>
After completion, create `.planning/phases/01-foundation/01-01-SUMMARY.md`
</output>
```
</good_examples>
<bad_examples>
```markdown
# Phase 1: Foundation
## Tasks
### Task 1: Set up authentication
**Action**: Add auth to the app
**Done when**: Users can log in
```
This is useless. No XML structure, no @context, no verification, no specificity.
</bad_examples>
<guidelines>
**When to use:**
- Creating execution plans for each phase
- One plan per 2-3 tasks, multiple plans per phase if needed
- Always use XML structure for Claude parsing
**Task types:**
- `type="auto"`: Execute without stopping
- `type="checkpoint:human-action"`: User must do something (manual step)
- `type="checkpoint:human-verify"`: User must verify output (testing, visual check)
- `type="checkpoint:decision"`: User must choose between options
**Gate values:**
- `gate="blocking"`: Must resolve before continuing
- `gate="optional"`: Can skip or defer
**Context references:**
- Use @path/to/file.md to load files
- Always include @.planning/PROJECT.md and @.planning/ROADMAP.md
- Include relevant source files for context
- Include workflow/template references
**After completion:**
- Create SUMMARY.md in same directory
- Follow summary.md template structure
- Document deviations, decisions, issues
</guidelines>

207
get-shit-done/templates/project.md Normal file
View File

@@ -0,0 +1,207 @@
# PROJECT.md Template
Template for `.planning/PROJECT.md` - the full project context captured during initialization.
## Greenfield Project (v1.0)
```markdown
# [Project Name]
## Vision
[What this is and why it matters. 2-4 paragraphs capturing the full picture.
Use the user's language and framing. Include motivation, not just description.
This should feel like the user explaining their project to a smart collaborator.]
## Problem
[What problem exists, who has it, why it matters, what the current state is.
Be specific - vague problems lead to vague solutions.
Include the pain, the gap, or the opportunity that makes this worth building.]
## Success Criteria
How we know this worked:
- [ ] [Measurable outcome 1 - specific, verifiable]
- [ ] [Measurable outcome 2 - specific, verifiable]
- [ ] [Measurable outcome 3 - specific, verifiable]
- [ ] [Add as many as genuinely needed]
## Scope
### Building
- [Feature/capability 1]
- [Feature/capability 2]
- [Feature/capability 3]
### Not Building
- [Explicit exclusion 1 - prevents scope creep]
- [Explicit exclusion 2 - clarifies boundaries]
- [Explicit exclusion 3 - manages expectations]
## Context
[Background information that informs implementation:
- Current state (greenfield)
- Relevant prior work or experience
- Technical environment or ecosystem context
- Explored alternatives and why they were rejected]
## Constraints
- **[Constraint type]**: [What] - [Why]
- **[Constraint type]**: [What] - [Why]
- **[Constraint type]**: [What] - [Why]
Common types: Tech stack, Timeline, Resources, Dependencies, Compatibility, Performance, Security
## Decisions Made
Key decisions from project exploration:
| Decision | Choice | Rationale |
|----------|--------|-----------|
| [Area/Topic] | [What we decided] | [Why this choice] |
| [Area/Topic] | [What we decided] | [Why this choice] |
## Open Questions
Things to figure out during execution:
- [ ] [Question 1 - known unknown to resolve]
- [ ] [Question 2 - decision to make later]
- [ ] [Question 3 - area needing research]
---
*Initialized: [date]*
```
## Brownfield Project (v1.1+)
After shipping v1.0, update PROJECT.md to include current state:
```markdown
# [Project Name]
## Current State (Updated: YYYY-MM-DD)
**Shipped:** v[X.Y] [Name] (YYYY-MM-DD)
**Status:** [Production / Beta / Internal / Live with users]
**Users:** [If known: "~500 downloads, 50 DAU" or "Internal use only" or "N/A"]
**Feedback:** [Key themes from user feedback, or "Initial release, gathering feedback"]
**Codebase:**
- [X,XXX] lines of [primary language]
- [Key tech stack: framework, platform, deployment target]
- [Notable dependencies or architecture]
**Known Issues:**
- [Issue 1 from v1.x that needs addressing]
- [Issue 2]
- [Or "None" if clean slate]
## v[Next] Goals
**Vision:** [What's the goal for this next iteration?]
**Motivation:**
- [Why this work matters now]
- [User feedback driving it]
- [Technical debt or improvements needed]
**Scope (v[X.Y]):**
- [Feature/improvement 1]
- [Feature/improvement 2]
- [Feature/improvement 3]
**Success Criteria:**
- [ ] [Measurable outcome 1]
- [ ] [Measurable outcome 2]
- [ ] [Measurable outcome 3]
**Not Building (this version):**
- [Not doing X in this version]
- [Not doing Y in this version]
## Constraints
- **[Constraint type]**: [What] - [Why]
- **[Constraint type]**: [What] - [Why]
## Open Questions
- [ ] [Question for this version]
- [ ] [Question for this version]
---
<details>
<summary>Original Vision (v1.0 - Archived)</summary>
## Vision
[Original vision content]
## Problem
[Original problem statement]
## Success Criteria
- [x] [Outcome 1] - Achieved
- [x] [Outcome 2] - Achieved
- [x] [Outcome 3] - Achieved
## Scope
### Built
- [What was built]
### Not Built
- [What was excluded]
## Context
[Original context]
## Constraints
[Original constraints]
## Decisions Made
[Original decisions table]
</details>
```
<guidelines>
**Greenfield:**
- Don't compress - capture everything from questioning
- Use user's words - preserve their language and framing
- Be specific - vague inputs create vague outputs
- Include rationale - "what" without "why" loses context
- Mark unknowns - open questions are valuable, not failures
**Brownfield:**
- Current State shows real-world context (shipped, users, feedback)
- v[Next] Goals focuses on the upcoming work
- Original Vision collapsed in `<details>` for reference
- Checkboxes marked [x] for achieved goals
- This makes all plans brownfield-aware automatically
</guidelines>
<state_summary>
When creating STATE.md, extract a summary from PROJECT.md:
**Building:** [One-liner from Vision]
**Core requirements:**
- [Top 3 from Success Criteria]
**Constraints:**
- [Key constraints]
This goes in STATE.md's immutable "Project Summary" section.
</state_summary>

133
get-shit-done/templates/research-prompt.md Normal file
View File

@@ -0,0 +1,133 @@
# Research Prompt Template
For phases requiring research before planning:
```markdown
---
phase: XX-name
type: research
topic: [research-topic]
---
<session_initialization>
Before beginning research, verify today's date:
!`date +%Y-%m-%d`
Use this date when searching for "current" or "latest" information.
Example: If today is 2025-11-22, search for "2025" not "2024".
</session_initialization>
<research_objective>
Research [topic] to inform [phase name] implementation.
Purpose: [What decision/implementation this enables]
Scope: [Boundaries]
Output: FINDINGS.md with structured recommendations
</research_objective>
<research_scope>
<include>
- [Question to answer]
- [Area to investigate]
- [Specific comparison if needed]
</include>
<exclude>
- [Out of scope for this research]
- [Defer to implementation phase]
</exclude>
</research_scope>
<research_protocol>
**Source Priority:**
1. **Context7 MCP** - For library/framework documentation (current, authoritative)
2. **Official Docs** - For platform-specific or non-indexed libraries
3. **WebSearch** - For comparisons, trends, community patterns (verify all findings)
**Quality Checklist:**
Before completing research, verify:
- [ ] All claims have authoritative sources (Context7 or official docs)
- [ ] Negative claims ("X is not possible") verified with official documentation
- [ ] API syntax/configuration from Context7 or official docs (never WebSearch alone)
- [ ] WebSearch findings cross-checked with authoritative sources
- [ ] Recent updates/changelogs checked for breaking changes
- [ ] Alternative approaches considered (not just first solution found)
**Confidence Levels:**
- HIGH: Context7 or official docs confirm
- MEDIUM: WebSearch + Context7/official docs confirm
- LOW: WebSearch only or training knowledge only (mark for validation)
</research_protocol>
<output_structure>
Create `.planning/phases/XX-name/FINDINGS.md`:
```markdown
# [Topic] Research Findings
## Summary
[2-3 paragraph executive summary - what was researched, what was found, what's recommended]
## Primary Recommendation
[What to do and why - be specific and actionable]
## Alternatives Considered
[What else was evaluated and why not chosen]
## Key Findings
### [Category 1]
- [Finding with source URL and relevance to our case]
### [Category 2]
- [Finding with source URL and relevance]
## Code Examples
[Relevant implementation patterns, if applicable]
## Metadata
<metadata>
<confidence level="high|medium|low">
[Why this confidence level - based on source quality and verification]
</confidence>
<sources>
- [Primary authoritative sources used]
</sources>
<open_questions>
[What couldn't be determined or needs validation during implementation]
</open_questions>
<validation_checkpoints>
[If confidence is LOW or MEDIUM, list specific things to verify during implementation]
</validation_checkpoints>
</metadata>
```
</output_structure>
<success_criteria>
- All scope questions answered with authoritative sources
- Quality checklist items completed
- Clear primary recommendation
- Low-confidence findings marked with validation checkpoints
- Ready to inform PLAN.md creation
</success_criteria>
<guidelines>
**When to use research prompts:**
- Technology choice unclear
- Best practices needed for unfamiliar domain
- API/library investigation required
- Architecture decision pending
- Multiple valid approaches exist
**When NOT to use:**
- Established patterns (CRUD, auth with known library)
- Implementation details (defer to execution)
- Questions answerable from existing project context
</guidelines>

196
get-shit-done/templates/roadmap.md Normal file
View File

@@ -0,0 +1,196 @@
# Roadmap Template
Template for `.planning/ROADMAP.md`.
## Initial Roadmap (v1.0 Greenfield)
```markdown
# Roadmap: [Project Name]
## Overview
[One paragraph describing the journey from start to finish]
## Domain Expertise
[Paths to domain skills that inform planning. These SKILL.md files serve as indexes - during phase planning, read them to find relevant references for each phase type.]
- ~/.claude/skills/expertise/[domain]/SKILL.md
[Add additional domains if project spans multiple (e.g., ISF shaders + macOS app)]
Or: None
## Phases
**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
Decimal phases appear between their surrounding integers in numeric order.
- [ ] **Phase 1: [Name]** - [One-line description]
- [ ] **Phase 2: [Name]** - [One-line description]
- [ ] **Phase 3: [Name]** - [One-line description]
- [ ] **Phase 4: [Name]** - [One-line description]
## Phase Details
### Phase 1: [Name]
**Goal**: [What this phase delivers]
**Depends on**: Nothing (first phase)
**Research**: Unlikely (established patterns)
**Plans**: [Number of plans, e.g., "3 plans" or "TBD"]
Plans:
- [ ] 01-01: [Brief description of first plan]
- [ ] 01-02: [Brief description of second plan]
- [ ] 01-03: [Brief description of third plan]
### Phase 2: [Name]
**Goal**: [What this phase delivers]
**Depends on**: Phase 1
**Research**: Likely (new integration)
**Research topics**: [What needs investigating]
**Plans**: [Number of plans]
Plans:
- [ ] 02-01: [Brief description]
- [ ] 02-02: [Brief description]
### Phase 2.1: Critical Fix (INSERTED)
**Goal**: [Urgent work inserted between phases]
**Depends on**: Phase 2
**Plans**: 1 plan
Plans:
- [ ] 2.1-01: [Description]
### Phase 3: [Name]
**Goal**: [What this phase delivers]
**Depends on**: Phase 2
**Research**: Likely (external API)
**Research topics**: [What needs investigating]
**Plans**: [Number of plans]
Plans:
- [ ] 03-01: [Brief description]
- [ ] 03-02: [Brief description]
### Phase 4: [Name]
**Goal**: [What this phase delivers]
**Depends on**: Phase 3
**Research**: Unlikely (internal patterns)
**Plans**: [Number of plans]
Plans:
- [ ] 04-01: [Brief description]
## Progress
**Execution Order:**
Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. [Name] | 0/3 | Not started | - |
| 2. [Name] | 0/2 | Not started | - |
| 3. [Name] | 0/2 | Not started | - |
| 4. [Name] | 0/1 | Not started | - |
```
<guidelines>
**Initial planning (v1.0):**
- 3-6 phases total (more = scope creep)
- Each phase delivers something coherent
- Phases can have 1+ plans (split if >3 tasks or multiple subsystems)
- Plans use naming: {phase}-{plan}-PLAN.md (e.g., 01-02-PLAN.md)
- No time estimates (this isn't enterprise PM)
- Progress table updated by execute workflow
- Plan count can be "TBD" initially, refined during planning
**Research flags:**
- `Research: Likely` - External APIs, new libraries, architectural decisions
- `Research: Unlikely` - Internal patterns, CRUD operations, established conventions
- Include `Research topics:` when Likely
- Flags are hints, not mandates - validate at planning time
**After milestones ship:**
- Collapse completed milestones in `<details>` tags
- Add new milestone sections for upcoming work
- Keep continuous phase numbering (never restart at 01)
</guidelines>
<status_values>
- `Not started` - Haven't begun
- `In progress` - Currently working
- `Complete` - Done (add completion date)
- `Deferred` - Pushed to later (with reason)
</status_values>
## Milestone-Grouped Roadmap (After v1.0 Ships)
After completing first milestone, reorganize with milestone groupings:
```markdown
# Roadmap: [Project Name]
## Milestones
- ✅ **v1.0 MVP** - Phases 1-4 (shipped YYYY-MM-DD)
- 🚧 **v1.1 [Name]** - Phases 5-6 (in progress)
- 📋 **v2.0 [Name]** - Phases 7-10 (planned)
## Phases
<details>
<summary>✅ v1.0 MVP (Phases 1-4) - SHIPPED YYYY-MM-DD</summary>
### Phase 1: [Name]
**Goal**: [What this phase delivers]
**Plans**: 3 plans
Plans:
- [x] 01-01: [Brief description]
- [x] 01-02: [Brief description]
- [x] 01-03: [Brief description]
[... remaining v1.0 phases ...]
</details>
### 🚧 v1.1 [Name] (In Progress)
**Milestone Goal:** [What v1.1 delivers]
#### Phase 5: [Name]
**Goal**: [What this phase delivers]
**Depends on**: Phase 4
**Plans**: 2 plans
Plans:
- [ ] 05-01: [Brief description]
- [ ] 05-02: [Brief description]
[... remaining v1.1 phases ...]
### 📋 v2.0 [Name] (Planned)
**Milestone Goal:** [What v2.0 delivers]
[... v2.0 phases ...]
## Progress
| Phase | Milestone | Plans Complete | Status | Completed |
|-------|-----------|----------------|--------|-----------|
| 1. Foundation | v1.0 | 3/3 | Complete | YYYY-MM-DD |
| 2. Features | v1.0 | 2/2 | Complete | YYYY-MM-DD |
| 5. Security | v1.1 | 0/2 | Not started | - |
```
**Notes:**
- Milestone emoji: ✅ shipped, 🚧 in progress, 📋 planned
- Completed milestones collapsed in `<details>` for readability
- Current/future milestones expanded
- Continuous phase numbering (01-99)
- Progress table includes milestone column

226
get-shit-done/templates/state.md Normal file
View File

@@ -0,0 +1,226 @@
# State Template
Template for `.planning/STATE.md` - the project's living memory.
---
## File Template
```markdown
# Project State
## Project Summary
[IMMUTABLE - Copy verbatim from PROJECT.md on creation. Never edit this section.]
**Building:** [One-liner from project vision]
**Core requirements:**
- [Requirement 1]
- [Requirement 2]
- [Requirement 3]
**Constraints:**
- [Key constraint 1]
- [Key constraint 2]
## Current Position
Phase: [X] of [Y] ([Phase name])
Plan: [A] of [B] in current phase
Status: [Ready to plan / Planning / Ready to execute / In progress / Phase complete]
Last activity: [YYYY-MM-DD] - [What happened]
Progress: [░░░░░░░░░░] 0%
## Performance Metrics
**Velocity:**
- Total plans completed: [N]
- Average duration: [X] min
- Total execution time: [X.X] hours
**By Phase:**
| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| - | - | - | - |
**Recent Trend:**
- Last 5 plans: [durations]
- Trend: [Improving / Stable / Degrading]
*Updated after each plan completion*
## Accumulated Context
### Decisions Made
| Phase | Decision | Rationale |
|-------|----------|-----------|
| - | - | - |
### Deferred Issues
[From ISSUES.md - list open items with phase of origin]
None yet.
### Blockers/Concerns Carried Forward
[From prior "Next Phase Readiness" sections - issues that affect future work]
None yet.
## Project Alignment
Last checked: [Date or "Project start"]
Status: [✓ Aligned / ⚠️ Drift detected / ✗ Misaligned]
Assessment: [One line summary]
Drift notes: [Details if drift detected, otherwise "None"]
## Session Continuity
Last session: [YYYY-MM-DD HH:MM]
Stopped at: [Description of last completed action]
Resume file: [Path to .continue-here*.md if exists, otherwise "None"]
```
<purpose>
STATE.md is the project's "short-term memory" that spans all phases and sessions.
**Problem it solves:** Information is captured in summaries, issues, and decisions - but not systematically consumed. Each phase plans in isolation. Sessions start without knowing accumulated context.
**Solution:** A single, small file that's:
- Always read first (every workflow)
- Always updated after work (every execution)
- Contains digest of all accumulated wisdom
- Enables instant context restoration
</purpose>
<lifecycle>
**Creation:** After ROADMAP.md is created (during init)
- Copy Project Summary from PROJECT.md (immutable after this)
- Initialize empty accumulated context sections
- Set position to "Phase 1 ready to plan"
**Reading:** First step of EVERY workflow
- progress: Present status to user
- plan: Inform planning decisions
- execute: Know current position
- transition: Know what's complete
**Writing:** After every significant action
- execute: After SUMMARY.md created
- Update position (phase, plan, status)
- Extract decisions → add to table
- Extract new issues → update deferred list
- Extract concerns → add to blockers
- transition: After phase marked complete
- Update progress bar
- Clear resolved blockers
- alignment-check: After verification
- Update alignment status
</lifecycle>
<sections>
### Project Summary (Immutable)
Copied from PROJECT.md on project initialization. Never edited afterward.
Provides constant reference to "what are we building" without re-reading full project doc.
### Current Position
Where we are right now:
- Phase X of Y - which phase
- Plan A of B - which plan within phase
- Status - current state
- Last activity - what happened most recently
- Progress bar - visual indicator of overall completion
Progress calculation: (completed plans) / (total plans across all phases) × 100%
### Performance Metrics
Track velocity to understand execution patterns:
- Total plans completed
- Average duration per plan
- Per-phase breakdown
- Recent trend (improving/stable/degrading)
Updated after each plan completion.
### Accumulated Context
**Decisions Made:** Table of significant decisions with rationale.
- Extracted from SUMMARY.md "Decisions Made" sections
- Include phase number for traceability
- These constrain future phases (e.g., "use jose not jsonwebtoken")
**Deferred Issues:** Open items from ISSUES.md
- Brief description with ISS-XXX number
- Phase where discovered
- Effort estimate if known
- Helps phase planning identify what to address
**Blockers/Concerns:** From "Next Phase Readiness" sections
- Issues that affect future work
- Prefix with originating phase
- Cleared when addressed
### Project Alignment
Tracks whether work matches original requirements:
- ✓ Aligned: On track
- ⚠️ Drift: Scope creeping or diverging
- ✗ Misaligned: Work doesn't serve project goals
Updated after each phase completion.
### Session Continuity
Enables instant resumption:
- When was last session
- What was last completed
- Is there a .continue-here file to resume from
</sections>
<size_constraint>
Keep STATE.md under 150 lines.
It's a DIGEST, not an archive. If accumulated context grows too large:
- Summarize older phase decisions: "Phases 1-2: [key decisions]"
- Reference ISSUES.md instead of listing all: "12 open issues - see ISSUES.md"
- Keep only active blockers, archive resolved ones
The goal is "read once, know everything" - if it's too long, that fails.
</size_constraint>
<guidelines>
**When created:**
- During project initialization (after ROADMAP.md)
- Copy Project Summary from PROJECT.md (never edit this section after creation)
- Initialize empty sections
**When read:**
- EVERY workflow starts by reading STATE.md
- Provides instant context restoration
- Shows current position and accumulated wisdom
**When updated:**
- After each plan execution (update position, extract decisions/issues/blockers)
- After phase transitions (update progress bar, clear resolved blockers)
- After alignment checks (update alignment status)
**Size management:**
- Keep under 150 lines total
- Summarize older decisions if table grows large
- Reference ISSUES.md instead of listing all issues
- Keep only active blockers, archive resolved ones
**Sections:**
- Project Summary: Immutable project overview
- Current Position: Where we are now (phase, plan, status)
- Performance Metrics: Velocity tracking
- Accumulated Context: Decisions, deferred issues, blockers
- Project Alignment: Are we on track with original vision?
- Session Continuity: Resume information
</guidelines>

200
get-shit-done/templates/summary.md Normal file
View File

@@ -0,0 +1,200 @@
# Summary Template
Template for `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md` - phase completion documentation.
---
## File Template
```markdown
# Phase [X]: [Name] Summary
**[Substantive one-liner describing outcome - NOT "phase complete" or "implementation finished"]**
## Performance
- **Duration:** [time] (e.g., 23 min, 1h 15m)
- **Started:** [ISO timestamp]
- **Completed:** [ISO timestamp]
- **Tasks:** [count completed]
- **Files modified:** [count]
## Accomplishments
- [Most important outcome]
- [Second key accomplishment]
- [Third if applicable]
## Files Created/Modified
- `path/to/file.ts` - What it does
- `path/to/another.ts` - What it does
## Decisions Made
[Key decisions with brief rationale, or "None - followed plan as specified"]
## Deviations from Plan
[If no deviations: "None - plan executed exactly as written"]
[If deviations occurred:]
### Auto-fixed Issues
**1. [Rule X - Category] Brief description**
- **Found during:** Task [N] ([task name])
- **Issue:** [What was wrong]
- **Fix:** [What was done]
- **Files modified:** [file paths]
- **Verification:** [How it was verified]
- **Commit:** [hash]
[... repeat for each auto-fix ...]
### Deferred Enhancements
Logged to .planning/ISSUES.md for future consideration:
- ISS-XXX: [Brief description] (discovered in Task [N])
- ISS-XXX: [Brief description] (discovered in Task [N])
---
**Total deviations:** [N] auto-fixed ([breakdown by rule]), [N] deferred
**Impact on plan:** [Brief assessment - e.g., "All auto-fixes necessary for correctness/security. No scope creep."]
## Issues Encountered
[Problems and how they were resolved, or "None"]
[Note: "Deviations from Plan" documents unplanned work that was handled automatically via deviation rules. "Issues Encountered" documents problems during planned work that required problem-solving.]
## Next Phase Readiness
[What's ready for next phase]
[Any blockers or concerns]
---
*Phase: XX-name*
*Completed: [date]*
```
<one_liner_rules>
The one-liner MUST be substantive:
**Good:**
- "JWT auth with refresh rotation using jose library"
- "Prisma schema with User, Session, and Product models"
- "Dashboard with real-time metrics via Server-Sent Events"
**Bad:**
- "Phase complete"
- "Authentication implemented"
- "Foundation finished"
- "All tasks done"
The one-liner should tell someone what actually shipped.
</one_liner_rules>
<example>
```markdown
# Phase 1: Foundation Summary
**JWT auth with refresh rotation using jose library, Prisma User model, and protected API middleware**
## Performance
- **Duration:** 28 min
- **Started:** 2025-01-15T14:22:10Z
- **Completed:** 2025-01-15T14:50:33Z
- **Tasks:** 5
- **Files modified:** 8
## Accomplishments
- User model with email/password auth
- Login/logout endpoints with httpOnly JWT cookies
- Protected route middleware checking token validity
- Refresh token rotation on each request
## Files Created/Modified
- `prisma/schema.prisma` - User and Session models
- `src/app/api/auth/login/route.ts` - Login endpoint
- `src/app/api/auth/logout/route.ts` - Logout endpoint
- `src/middleware.ts` - Protected route checks
- `src/lib/auth.ts` - JWT helpers using jose
## Decisions Made
- Used jose instead of jsonwebtoken (ESM-native, Edge-compatible)
- 15-min access tokens with 7-day refresh tokens
- Storing refresh tokens in database for revocation capability
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 2 - Missing Critical] Added password hashing with bcrypt**
- **Found during:** Task 2 (Login endpoint implementation)
- **Issue:** Plan didn't specify password hashing - storing plaintext would be critical security flaw
- **Fix:** Added bcrypt hashing on registration, comparison on login with salt rounds 10
- **Files modified:** src/app/api/auth/login/route.ts, src/lib/auth.ts
- **Verification:** Password hash test passes, plaintext never stored
- **Commit:** abc123f
**2. [Rule 3 - Blocking] Installed missing jose dependency**
- **Found during:** Task 4 (JWT token generation)
- **Issue:** jose package not in package.json, import failing
- **Fix:** Ran `npm install jose`
- **Files modified:** package.json, package-lock.json
- **Verification:** Import succeeds, build passes
- **Commit:** def456g
### Deferred Enhancements
Logged to .planning/ISSUES.md for future consideration:
- ISS-001: Add rate limiting to login endpoint (discovered in Task 2)
- ISS-002: Improve token refresh UX with auto-retry on 401 (discovered in Task 5)
---
**Total deviations:** 2 auto-fixed (1 missing critical, 1 blocking), 2 deferred
**Impact on plan:** Both auto-fixes essential for security and functionality. No scope creep.
## Issues Encountered
- jsonwebtoken CommonJS import failed in Edge runtime - switched to jose (planned library change, worked as expected)
## Next Phase Readiness
- Auth foundation complete, ready for feature development
- User registration endpoint needed before public launch
---
*Phase: 01-foundation*
*Completed: 2025-01-15*
```
</example>
<guidelines>
**When to create:**
- After completing each phase plan
- Required output from execute-phase workflow
- Documents what actually happened vs what was planned
**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
- Deferred enhancements: Logged to ISSUES.md with ISS-XXX numbers
**Decisions section:**
- Key decisions made during execution
- Include rationale (why this choice)
- 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
</guidelines>

490
get-shit-done/workflows/complete-milestone.md Normal file
View File

@@ -0,0 +1,490 @@
<purpose>
Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical record in MILESTONES.md, updates PROJECT.md with current state, reorganizes ROADMAP.md with milestone groupings, and tags the release in git.
This is the ritual that separates "development" from "shipped."
</purpose>
<required_reading>
**Read these files NOW:**
1. templates/milestone.md
2. templates/milestone-archive.md
3. `.planning/ROADMAP.md`
4. `.planning/PROJECT.md`
</required_reading>
<archival_behavior>
When a milestone completes, this workflow:
1. Extracts full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
2. Updates ROADMAP.md to replace milestone details with one-line summary
3. Links to archive file for historical reference
4. Offers to create next milestone inline
**Context Efficiency:**
- Completed milestones: One line each (~50 tokens)
- Full details: In archive files (loaded only when needed)
- Result: ROADMAP.md stays constant size (~1-2k lines) forever
**Archive Format:**
Uses `templates/milestone-archive.md` template with:
- Milestone header (status, phases, date)
- Full phase details from roadmap
- Milestone summary (decisions, issues, technical debt)
</archival_behavior>
<process>
<step name="verify_readiness">
Check if milestone is truly complete:
```bash
cat .planning/ROADMAP.md
ls .planning/phases/*/SUMMARY.md 2>/dev/null | wc -l
```
**Questions to ask:**
- Which phases belong to this milestone?
- Are all those phases complete (all plans have summaries)?
- Has the work been tested/validated?
- Is this ready to ship/tag?
Present:
```
Milestone: [Name from user, e.g., "v1.0 MVP"]
Appears to include:
- Phase 1: Foundation (2/2 plans complete)
- Phase 2: Authentication (2/2 plans complete)
- Phase 3: Core Features (3/3 plans complete)
- Phase 4: Polish (1/1 plan complete)
Total: 4 phases, 8 plans, all complete
```
**Check workflow config for gate behavior:**
```bash
cat .planning/config.json 2>/dev/null
```
Parse the config:
- If `mode: "yolo"` → auto-approve
- If `mode: "interactive"` → prompt user
- If `mode: "custom"` → check `gates.confirm_milestone_scope` (if exists)
**If auto-approved:**
```
⚡ Auto-approved: Milestone scope verification
[Show breakdown summary without prompting]
Proceeding to stats gathering...
```
**If prompting (interactive mode):**
```
Ready to mark this milestone as shipped?
(yes / wait / adjust scope)
```
Wait for confirmation.
If "adjust scope": Ask which phases should be included.
If "wait": Stop, user will return when ready.
</step>
<step name="gather_stats">
Calculate milestone statistics:
```bash
# Count phases and plans in milestone
# (user specified or detected from roadmap)
# Find git range
git log --oneline --grep="feat(" | head -20
# Count files modified in range
git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
# Count LOC (adapt to language)
find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null
# Calculate timeline
git log --format="%ai" FIRST_COMMIT | tail -1 # Start date
git log --format="%ai" LAST_COMMIT | head -1 # End date
```
Present summary:
```
Milestone Stats:
- Phases: [X-Y]
- Plans: [Z] total
- Tasks: [N] total (estimated from phase summaries)
- Files modified: [M]
- Lines of code: [LOC] [language]
- Timeline: [Days] days ([Start] → [End])
- Git range: feat(XX-XX) → feat(YY-YY)
```
</step>
<step name="extract_accomplishments">
Read all phase SUMMARY.md files in milestone range:
```bash
cat .planning/phases/01-*/01-*-SUMMARY.md
cat .planning/phases/02-*/02-*-SUMMARY.md
# ... for each phase in milestone
```
From summaries, extract 4-6 key accomplishments.
Present:
```
Key accomplishments for this milestone:
1. [Achievement from phase 1]
2. [Achievement from phase 2]
3. [Achievement from phase 3]
4. [Achievement from phase 4]
5. [Achievement from phase 5]
```
</step>
<step name="create_milestone_entry">
Create or update `.planning/MILESTONES.md`.
If file doesn't exist:
```markdown
# Project Milestones: [Project Name from PROJECT.md]
[New entry]
```
If exists, prepend new entry (reverse chronological order).
Use template from `templates/milestone.md`:
```markdown
## v[Version] [Name] (Shipped: YYYY-MM-DD)
**Delivered:** [One sentence from user]
**Phases completed:** [X-Y] ([Z] plans total)
**Key accomplishments:**
- [List from previous step]
**Stats:**
- [Files] files created/modified
- [LOC] lines of [language]
- [Phases] phases, [Plans] plans, [Tasks] tasks
- [Days] days from [start milestone or start project] to ship
**Git range:** `feat(XX-XX)` → `feat(YY-YY)`
**What's next:** [Ask user: what's the next goal?]
---
```
</step>
<step name="update_project">
Update `.planning/PROJECT.md` to reflect current state.
Add/update "Current State" section at top (after YAML if present):
```markdown
# Project: [Name]
## Current State (Updated: YYYY-MM-DD)
**Shipped:** v[X.Y] [Name] (YYYY-MM-DD)
**Status:** [Production / Beta / Internal]
**Users:** [If known, e.g., "~500 downloads, 50 DAU" or "Internal use only"]
**Feedback:** [Key themes from users, or "Initial release, gathering feedback"]
**Codebase:** [LOC] [language], [key tech stack], [platform/deployment target]
## [Next Milestone] Goals
**Vision:** [What's the goal for next version?]
**Motivation:**
- [Why this next work matters]
- [User feedback driving it]
- [Technical debt or improvements needed]
**Scope (v[X.Y]):**
- [Feature/improvement 1]
- [Feature/improvement 2]
- [Feature/improvement 3]
---
<details>
<summary>Original Vision (v1.0 - Archived for reference)</summary>
[Move original project content here]
</details>
```
**If this is v1.0 (first milestone):**
Just add "Current State" section, no need to archive original vision yet.
**If this is v1.1+:**
Collapse previous version's content into `<details>` section.
Show diff of changes:
</step>
<step name="reorganize_roadmap">
Update `.planning/ROADMAP.md` to group completed milestone phases.
Add milestone headers and collapse completed work:
```markdown
# Roadmap: [Project Name]
## Milestones
- ✅ **v1.0 MVP** - Phases 1-4 (shipped YYYY-MM-DD)
- 🚧 **v1.1 Security** - Phases 5-6 (in progress)
- 📋 **v2.0 Redesign** - Phases 7-10 (planned)
## Phases
<details>
<summary>✅ v1.0 MVP (Phases 1-4) - SHIPPED YYYY-MM-DD</summary>
- [x] Phase 1: Foundation (2/2 plans) - completed YYYY-MM-DD
- [x] Phase 2: Authentication (2/2 plans) - completed YYYY-MM-DD
- [x] Phase 3: Core Features (3/3 plans) - completed YYYY-MM-DD
- [x] Phase 4: Polish (1/1 plan) - completed YYYY-MM-DD
</details>
### 🚧 v[Next] [Name] (In Progress / Planned)
- [ ] Phase 5: [Name] ([N] plans)
- [ ] Phase 6: [Name] ([N] plans)
## Progress
| Phase | Milestone | Plans Complete | Status | Completed |
| ----------------- | --------- | -------------- | ----------- | ---------- |
| 1. Foundation | v1.0 | 2/2 | Complete | YYYY-MM-DD |
| 2. Authentication | v1.0 | 2/2 | Complete | YYYY-MM-DD |
| 3. Core Features | v1.0 | 3/3 | Complete | YYYY-MM-DD |
| 4. Polish | v1.0 | 1/1 | Complete | YYYY-MM-DD |
| 5. Security Audit | v1.1 | 0/1 | Not started | - |
| 6. Hardening | v1.1 | 0/2 | Not started | - |
```
</step>
<step name="archive_milestone">
Extract completed milestone details and create archive file.
**Process:**
1. Create archive file path: `.planning/milestones/v[X.Y]-ROADMAP.md`
2. Read `~/.claude/get-shit-done/templates/milestone-archive.md` template
3. Extract data from current ROADMAP.md:
- All phases belonging to this milestone (by phase number range)
- Full phase details (goals, plans, dependencies, status)
- Phase plan lists with completion checkmarks
4. Extract data from STATE.md:
- All decisions made during this milestone (filter by Phase column)
- Issues that were resolved
- Issues that were deferred
5. Fill template {{PLACEHOLDERS}}:
- {{VERSION}} - Milestone version (e.g., "1.0")
- {{MILESTONE_NAME}} - From ROADMAP.md milestone header
- {{DATE}} - Today's date
- {{PHASE_START}} - First phase number in milestone
- {{PHASE_END}} - Last phase number in milestone
- {{TOTAL_PLANS}} - Count of all plans in milestone
- {{MILESTONE_DESCRIPTION}} - From ROADMAP.md overview
- {{PHASES_SECTION}} - Full phase details extracted
- {{DECISIONS_FROM_PROJECT_STATE}} - Filtered decisions
- {{ISSUES_RESOLVED_DURING_MILESTONE}} - From summaries
- {{ISSUES_DEFERRED_TO_LATER}} - From ISSUES.md
6. Write filled template to `.planning/milestones/v[X.Y]-ROADMAP.md`
7. Update ROADMAP.md:
- Create/update "## Completed Milestones" section if not exists
- Add one-line entry: `- ✅ [v[X.Y] [Name]](milestones/v[X.Y]-ROADMAP.md) (Phases [N]-[M]) - SHIPPED [DATE]`
- Remove full milestone details from "Current Milestone" section
- Move next planned milestone to "Current Milestone" position
8. Verify files:
- Check archive file exists: `ls .planning/milestones/v[X.Y]-ROADMAP.md`
- Validate ROADMAP.md still parseable
9. Confirm archive complete:
```
✅ v[X.Y] archived to milestones/v[X.Y]-ROADMAP.md
```
Continue to git_tag step. Milestone creation happens in offer_next step.
</step>
<step name="git_tag">
Create git tag for milestone:
```bash
git tag -a v[X.Y] -m "$(cat <<'EOF'
v[X.Y] [Name]
Delivered: [One sentence]
Key accomplishments:
- [Item 1]
- [Item 2]
- [Item 3]
See .planning/MILESTONES.md for full details.
EOF
)"
```
Confirm: "Tagged: v[X.Y]"
Ask: "Push tag to remote? (y/n)"
If yes:
```bash
git push origin v[X.Y]
```
</step>
<step name="git_commit_milestone">
Commit milestone completion including archive file.
```bash
# Stage all milestone-related files
git add .planning/MILESTONES.md
git add .planning/PROJECT.md
git add .planning/ROADMAP.md
git add .planning/milestones/v[X.Y]-ROADMAP.md
# Commit with descriptive message
git commit -m "$(cat <<'EOF'
chore: archive v[X.Y] milestone
- Added MILESTONES.md entry
- Updated PROJECT.md current state
- Reorganized ROADMAP.md with milestone grouping
- Created milestone archive: milestones/v[X.Y]-ROADMAP.md
- Tagged v[X.Y]
EOF
)"
```
Confirm: "Committed: chore: archive v[X.Y] milestone"
Then proceed to git tag step.
</step>
<step name="offer_next">
```
✅ Milestone v[X.Y] [Name] complete
Shipped:
- [N] phases ([M] plans, [P] tasks)
- [One sentence of what shipped]
Summary: .planning/MILESTONES.md
Tag: v[X.Y]
Next steps:
1. Discuss next milestone scope (/gsd:discuss-milestone)
2. Create next milestone directly (/gsd:new-milestone)
3. Done for now
```
Wait for user decision.
If "1": Invoke SlashCommand("/gsd:discuss-milestone")
If "2": Invoke SlashCommand("/gsd:new-milestone")
Note: Commands are shown in options above so user can see what will run.
</step>
</process>
<milestone_naming>
**Version conventions:**
- **v1.0** - Initial MVP
- **v1.1, v1.2, v1.3** - Minor updates, new features, fixes
- **v2.0, v3.0** - Major rewrites, breaking changes, significant new direction
**Name conventions:**
- v1.0 MVP
- v1.1 Security
- v1.2 Performance
- v2.0 Redesign
- v2.0 iOS Launch
Keep names short (1-2 words describing the focus).
</milestone_naming>
<what_qualifies>
**Create milestones for:**
- Initial release (v1.0)
- Public releases
- Major feature sets shipped
- Before archiving planning
**Don't create milestones for:**
- Every phase completion (too granular)
- Work in progress (wait until shipped)
- Internal dev iterations (unless truly shipped internally)
If uncertain, ask: "Is this deployed/usable/shipped in some form?"
If yes → milestone. If no → keep working.
</what_qualifies>
<success_criteria>
Milestone completion is successful when:
- [ ] MILESTONES.md entry created with stats and accomplishments
- [ ] PROJECT.md updated with current state
- [ ] ROADMAP.md reorganized with milestone grouping
- [ ] Git tag created (v[X.Y])
- [ ] Milestone commit made
- [ ] User knows next steps
</success_criteria>
```

379
get-shit-done/workflows/create-milestone.md Normal file
View File

@@ -0,0 +1,379 @@
<purpose>
Create a new milestone for an existing project. Defines phases, updates roadmap, and resets state tracking for the new milestone.
This is used after completing a milestone when ready to define the next chunk of work.
</purpose>
<required_reading>
**Read these files NOW:**
1. ~/.claude/get-shit-done/templates/roadmap.md (milestone-grouped format)
2. `.planning/ROADMAP.md`
3. `.planning/STATE.md`
4. `.planning/MILESTONES.md` (if exists)
</required_reading>
<process>
<step name="load_context">
Load project context:
```bash
cat .planning/ROADMAP.md
cat .planning/STATE.md
cat .planning/MILESTONES.md 2>/dev/null || echo "No milestones file yet"
```
Extract:
- Previous milestone version (e.g., v1.0)
- Last phase number used
- Deferred issues from STATE.md
- Project brief summary from STATE.md
**Calculate next milestone version:**
- If previous was v1.0 → suggest v1.1 (minor) or v2.0 (major)
- If previous was v1.3 → suggest v1.4 or v2.0
- Parse from ROADMAP.md "Completed Milestones" section
</step>
<step name="get_milestone_info">
**If called from /gsd:discuss-milestone (context provided):**
Use the theme, scope, and constraints from discussion.
Suggest milestone name based on theme.
**If called directly (no prior context):**
Ask for milestone details:
header: "Milestone Name"
question: "What should we call this milestone?"
options:
- "v[X.Y] Features" - Adding new functionality
- "v[X.Y] Improvements" - Enhancing existing features
- "v[X.Y] Fixes" - Bug fixes and stability
- "v[X.Y] Refactor" - Code quality and architecture
- "v[X.Y+1].0 [Major]" - Major version bump
- "Other" - Custom name
Get milestone name in format: "v[X.Y] [Name]"
</step>
<step name="identify_phases">
**Calculate starting phase number:**
```bash
# Find highest phase number from roadmap
grep -E "^### Phase [0-9]+" .planning/ROADMAP.md | tail -1
# Extract number, add 1
```
Next phase starts at: [last_phase + 1]
**Gather phases (3-6 recommended):**
If context from discuss-milestone provided, use that scope.
Otherwise, ask:
```
What phases should this milestone include?
Starting at Phase [N]:
- Phase [N]: [name] - [one-line goal]
- Phase [N+1]: [name] - [one-line goal]
...
Describe the phases, or say "help me break this down" for guidance.
```
For each phase, capture:
- Phase number (continuing sequence)
- Phase name (kebab-case for directory)
- One-line goal
- Research flag (Likely/Unlikely based on triggers)
</step>
<step name="detect_research_needs">
**For each phase, determine if research is likely needed.**
Apply research triggers from create-roadmap.md:
<research_triggers>
**Likely (flag the phase):**
| Trigger Pattern | Why Research Needed |
| ----------------------------------------------------- | --------------------------------------- |
| "integrate [service]", "connect to [API]" | External API - need current docs |
| "authentication", "auth", "login", "JWT" | Architectural decision + library choice |
| "payment", "billing", "Stripe", "subscription" | External API + compliance patterns |
| "email", "SMS", "notifications", "SendGrid", "Twilio" | External service integration |
| "database", "Postgres", "MongoDB", "Supabase" | If new to project - setup patterns |
| "real-time", "websocket", "sync", "live updates" | Architectural decision |
| "deploy", "Vercel", "Railway", "hosting" | If first deployment - config patterns |
| "choose between", "select", "evaluate", "which" | Explicit decision needed |
| "AI", "OpenAI", "Claude", "LLM", "embeddings" | Fast-moving APIs - need current docs |
| Any technology not already in codebase | New integration |
**Unlikely (no flag needed):**
| Pattern | Why No Research |
| ------------------------------------------- | ----------------------- |
| "add button", "create form", "update UI" | Internal patterns |
| "CRUD operations", "list/detail views" | Standard patterns |
| "refactor", "reorganize", "clean up" | Internal work |
| "following existing patterns" | Conventions established |
| Technology already in package.json/codebase | Patterns exist |
</research_triggers>
Present research assessment:
```
Research needs detected:
Phase [N]: [Name]
Research: Unlikely (internal patterns)
Phase [N+1]: [Name]
Research: Likely (new API integration)
Topics: [What to investigate]
Does this look right? (yes / adjust)
```
</step>
<step name="confirm_phases">
**Check workflow config for gate behavior:**
```bash
cat .planning/config.json 2>/dev/null
```
Parse the config:
- If `mode: "yolo"` → auto-approve
- If `mode: "interactive"` or missing → prompt user
- If `mode: "custom"` → check `gates.confirm_phases`
**If auto-approved:**
```
⚡ Auto-approved: Milestone phases ([N] phases)
1. Phase [X]: [Name] - [goal]
2. Phase [X+1]: [Name] - [goal]
...
Proceeding to create milestone structure...
```
**If prompting:**
Present the phase breakdown:
```
Milestone: v[X.Y] [Name]
Phases:
1. Phase [X]: [Name] - [goal]
2. Phase [X+1]: [Name] - [goal]
3. Phase [X+2]: [Name] - [goal]
Does this feel right? (yes / adjust)
```
If "adjust": Ask what to change, revise, present again.
</step>
<step name="update_roadmap">
Update `.planning/ROADMAP.md` with new milestone:
**Add to Milestones section (if exists):**
```markdown
## Milestones
- ✅ **v1.0 [Previous]** - Phases 1-9 (shipped YYYY-MM-DD)
- 🚧 **v[X.Y] [Name]** - Phases [N]-[M] (in progress)
```
**Add to Phases section:**
```markdown
### 🚧 v[X.Y] [Name] (In Progress)
**Milestone Goal:** [One sentence describing what this milestone delivers]
#### Phase [N]: [Name]
**Goal**: [What this phase delivers]
**Depends on**: Phase [N-1] (or "Previous milestone complete")
**Research**: [Likely/Unlikely] ([reason])
**Research topics**: [If Likely, what to investigate]
**Plans**: TBD
Plans:
- [ ] [N]-01: TBD (run /gsd:plan-phase [N] to break down)
#### Phase [N+1]: [Name]
**Goal**: [What this phase delivers]
**Depends on**: Phase [N]
**Research**: [Likely/Unlikely] ([reason])
**Plans**: TBD
Plans:
- [ ] [N+1]-01: TBD
[... continue for all phases ...]
```
**Update Progress table:**
Add new phases with milestone column:
```markdown
| Phase | Milestone | Plans | Status | Completed |
| ------------- | --------- | ----- | ----------- | --------- |
| [N]. [Name] | v[X.Y] | 0/? | Not started | - |
| [N+1]. [Name] | v[X.Y] | 0/? | Not started | - |
```
</step>
<step name="create_phase_directories">
Create directories for new phases:
```bash
mkdir -p .planning/phases/[NN]-[slug]
mkdir -p .planning/phases/[NN+1]-[slug]
# ... for each phase
```
Use two-digit padding: `10-name`, `11-name`, etc.
</step>
<step name="update_state">
Update `.planning/STATE.md` for new milestone:
**Update Current Position:**
```markdown
## Current Position
Phase: [N] of [M] ([First phase name])
Plan: Not started
Status: Ready to plan
Last activity: [today's date] - Milestone v[X.Y] created
Progress: ░░░░░░░░░░ 0%
```
**Update Accumulated Context:**
Keep decisions from previous milestone (they're historical record).
Clear "Blockers/Concerns Carried Forward" section.
**Add to Roadmap Evolution:**
```markdown
### Roadmap Evolution
- Milestone v[X.Y] created: [theme/focus], [N] phases (Phase [start]-[end])
```
**Update Session Continuity:**
```markdown
## Session Continuity
Last session: [today's date and time]
Stopped at: Milestone v[X.Y] initialization
Resume file: None
```
</step>
<step name="git_commit">
Commit milestone creation:
```bash
git add .planning/ROADMAP.md .planning/STATE.md
git add .planning/phases/
git commit -m "$(cat <<'EOF'
docs: create milestone v[X.Y] [Name] ([N] phases)
Phases:
- [N]. [name]: [goal]
- [N+1]. [name]: [goal]
- [N+2]. [name]: [goal]
EOF
)"
```
Confirm: "Committed: docs: create milestone v[X.Y] [Name]"
</step>
<step name="offer_next">
```
Milestone v[X.Y] [Name] created:
- Phases: [N]-[M] ([count] phases)
- Directories created
- ROADMAP.md updated
- STATE.md reset for new milestone
What's next?
1. Discuss Phase [N] context (/gsd:discuss-phase [N])
2. Plan Phase [N] directly (/gsd:plan-phase [N])
3. Review roadmap
4. Done for now
```
**If user selects option 1:**
Invoke SlashCommand("/gsd:discuss-phase [N]")
**If user selects option 2:**
Invoke SlashCommand("/gsd:plan-phase [N]")
</step>
</process>
<phase_naming>
Use `XX-kebab-case-name` format with continuous numbering:
- `10-user-profiles`
- `11-notifications`
- `12-analytics`
Numbers continue from previous milestone. Names describe content.
</phase_naming>
<anti_patterns>
- Don't restart phase numbering at 01 (continue sequence)
- Don't add time estimates
- Don't create Gantt charts
- Don't plan more than 6 phases per milestone (scope creep)
- Don't modify completed milestone sections
Milestones are coherent chunks of work, not project management artifacts.
</anti_patterns>
<success_criteria>
Milestone creation is complete when:
- [ ] Next phase number calculated correctly (continues from previous)
- [ ] 3-6 phases defined with clear names
- [ ] Research flags assigned for each phase
- [ ] ROADMAP.md updated with new milestone section
- [ ] Phase directories created
- [ ] STATE.md reset for new milestone
- [ ] Git commit made
- [ ] User knows next steps
</success_criteria>
```

443
get-shit-done/workflows/create-roadmap.md Normal file
View File

@@ -0,0 +1,443 @@
<purpose>
Define the phases of implementation. Each phase is a coherent chunk of work
that delivers value. The roadmap provides structure, not detailed tasks.
</purpose>
<required_reading>
**Read these files NOW:**
1. ~/.claude/get-shit-done/templates/roadmap.md
2. ~/.claude/get-shit-done/templates/state.md
3. Read `.planning/PROJECT.md` if it exists
</required_reading>
<process>
<step name="check_brief">
```bash
cat .planning/PROJECT.md 2>/dev/null || echo "No brief found"
```
**If no brief exists:**
Ask: "No brief found. Want to create one first, or proceed with roadmap?"
If proceeding without brief, gather quick context:
- What are we building?
- What's the rough scope?
</step>
<step name="detect_domain">
Scan for available domain expertise:
```bash
ls ~/.claude/skills/expertise/ 2>/dev/null
```
**Inference:** Based on the brief/user request, infer applicable domains:
| Keywords | Domain |
| ---------------------------------------- | ------------------------ |
| "macOS", "Mac app", "menu bar", "AppKit" | expertise/macos-apps |
| "iPhone", "iOS", "iPad", "mobile app" | expertise/iphone-apps |
| "Unity", "game", "C#", "3D game" | expertise/unity-games |
| "MIDI", "sequencer", "music app" | expertise/midi |
| "ISF", "shader", "GLSL", "visual effect" | expertise/isf-shaders |
| "UI", "design", "frontend", "Tailwind" | expertise/ui-design |
| "Agent SDK", "Claude SDK", "agentic" | expertise/with-agent-sdk |
**If domain inferred:**
```
Detected: [domain] project → expertise/[name]
Include this domain expertise? (Y / see options / none)
```
**If multiple domains apply** (e.g., ISF shaders for a macOS app):
```
Detected multiple domains:
- expertise/isf-shaders (shader development)
- expertise/macos-apps (native app)
Include both? (Y / select one / none)
```
**If no domain obvious:**
```
Available domain expertise:
1. macos-apps
2. iphone-apps
[... others found ...]
N. None - proceed without domain expertise
Select (comma-separate for multiple):
```
**Store selected paths** for inclusion in ROADMAP.md.
</step>
<step name="identify_phases">
Based on the brief/context, identify 3-6 phases.
**Phase Numbering System:**
Use integer phases (1, 2, 3) for planned milestone work.
Use decimal phases (2.1, 2.2) for urgent insertions:
- Decimal phases inserted between integers (2.1 between 2 and 3)
- Mark with "(INSERTED)" in phase title
- Created when urgent work discovered after planning
- Examples: bugfixes, hotfixes, critical patches
**When to use decimals:**
- Urgent work that can't wait for next milestone
- Critical bugs blocking progress
- Security patches needing immediate attention
- NOT for scope creep or "nice to haves" (those go in ISSUES.md)
**Phase execution order:**
Numeric sort: 1 → 1.1 → 1.2 → 2 → 2.1 → 3
Good phases are:
- **Coherent**: Each delivers something complete
- **Sequential**: Later phases build on earlier
- **Sized right**: 1-3 days of work each (for solo + Claude)
Common phase patterns:
- Foundation → Core Feature → Enhancement → Polish
- Setup → MVP → Iteration → Launch
- Infrastructure → Backend → Frontend → Integration
</step>
<step name="detect_research_needs">
**For each phase, determine if research is likely needed.**
Scan the brief and phase descriptions for research triggers:
<research_triggers>
**Likely (flag the phase):**
| Trigger Pattern | Why Research Needed |
| ----------------------------------------------------- | --------------------------------------- |
| "integrate [service]", "connect to [API]" | External API - need current docs |
| "authentication", "auth", "login", "JWT" | Architectural decision + library choice |
| "payment", "billing", "Stripe", "subscription" | External API + compliance patterns |
| "email", "SMS", "notifications", "SendGrid", "Twilio" | External service integration |
| "database", "Postgres", "MongoDB", "Supabase" | If new to project - setup patterns |
| "real-time", "websocket", "sync", "live updates" | Architectural decision |
| "deploy", "Vercel", "Railway", "hosting" | If first deployment - config patterns |
| "choose between", "select", "evaluate", "which" | Explicit decision needed |
| "AI", "OpenAI", "Claude", "LLM", "embeddings" | Fast-moving APIs - need current docs |
| Any technology not already in codebase | New integration |
| Explicit questions in brief | Unknowns flagged by user |
**Unlikely (no flag needed):**
| Pattern | Why No Research |
| ------------------------------------------- | ----------------------- |
| "add button", "create form", "update UI" | Internal patterns |
| "CRUD operations", "list/detail views" | Standard patterns |
| "refactor", "reorganize", "clean up" | Internal work |
| "following existing patterns" | Conventions established |
| Technology already in package.json/codebase | Patterns exist |
</research_triggers>
**For each phase, assign:**
- `Research: Likely ([reason])` + `Research topics: [what to investigate]`
- `Research: Unlikely ([reason])`
**Important:** These are hints, not mandates. The mandatory_discovery step during phase planning will validate.
Present research assessment:
```
Research needs detected:
Phase 1: Foundation
Research: Unlikely (project setup, established patterns)
Phase 2: Authentication
Research: Likely (new system, technology choice)
Topics: JWT library for [stack], session strategy, auth provider options
Phase 3: Stripe Integration
Research: Likely (external API)
Topics: Current Stripe API, webhook patterns, checkout flow
Phase 4: Dashboard
Research: Unlikely (internal UI using patterns from earlier phases)
Does this look right? (yes / adjust)
```
</step>
<step name="confirm_phases">
**Check workflow config for gate behavior:**
```bash
cat .planning/config.json 2>/dev/null
```
**Note:** Config may not exist yet (this is project initialization). If missing, default to interactive mode.
Parse the config (if exists):
- If `mode: "yolo"` → auto-approve
- If `mode: "interactive"` or missing → prompt user
- If `mode: "custom"` → check `gates.confirm_phases`
**If auto-approved:**
```
⚡ Auto-approved: Phase breakdown ([N] phases)
1. [Phase name] - [goal]
2. [Phase name] - [goal]
3. [Phase name] - [goal]
Proceeding to research detection...
```
Proceed directly to detect_research_needs.
**If prompting:**
Present the phase breakdown inline:
"Here's how I'd break this down:
1. [Phase name] - [goal]
2. [Phase name] - [goal]
3. [Phase name] - [goal]
...
Does this feel right? (yes / adjust)"
If "adjust": Ask what to change, revise, present again.
</step>
<step name="decision_gate">
After phases confirmed (or auto-approved):
**Check workflow config for gate behavior:**
Read config from previous step (already parsed, or default to interactive if missing).
- If `mode: "yolo"` → auto-approve
- If `mode: "interactive"` or missing → prompt user
- If `mode: "custom"` → check `gates.confirm_roadmap`
**If auto-approved:**
```
⚡ Auto-approved: Create roadmap with [N] phases
Proceeding to create .planning/ROADMAP.md...
```
Proceed directly to create_structure.
**If prompting:**
Use AskUserQuestion:
- header: "Ready"
- question: "Ready to create the roadmap, or would you like me to ask more questions?"
- options:
- "Create roadmap" - I have enough context
- "Ask more questions" - There are details to clarify
- "Let me add context" - I want to provide more information
Loop until "Create roadmap" selected.
</step>
<step name="create_structure">
```bash
mkdir -p .planning/phases
```
</step>
<step name="write_roadmap">
Use template from `~/.claude/get-shit-done/templates/roadmap.md`.
Initial roadmaps use integer phases (1, 2, 3...).
Decimal phases added later via /gsd:insert-phase command (if it exists).
Write to `.planning/ROADMAP.md` with:
- Domain Expertise section (paths from detect_domain step, or "None" if skipped)
- Phase list with names and one-line descriptions
- Dependencies (what must complete before what)
- **Research flags** (from detect_research_needs step):
- `Research: Likely ([reason])` with `Research topics:` for flagged phases
- `Research: Unlikely ([reason])` for unflagged phases
- Status tracking (all start as "not started")
Create phase directories:
```bash
mkdir -p .planning/phases/01-{phase-name}
mkdir -p .planning/phases/02-{phase-name}
# etc.
```
</step>
<step name="initialize_project_state">
Create STATE.md - the project's living memory.
Use template from `~/.claude/get-shit-done/templates/state.md`.
Write to `.planning/STATE.md`:
```markdown
# Project State
## Brief Summary
**Building:** [Copy one-liner from PROJECT.md]
**Core requirements:**
[Copy 3-5 key requirements from PROJECT.md]
**Constraints:**
[Copy key constraints from PROJECT.md]
## Current Position
Phase: 1 of [N] ([First phase name])
Plan: Not started
Status: Ready to plan
Last activity: [today's date] - Project initialized
Progress: ░░░░░░░░░░ 0%
## Accumulated Context
### Decisions Made
| Phase | Decision | Rationale |
| ----- | -------- | --------- |
### Deferred Issues
None yet.
### Blockers/Concerns Carried Forward
None yet.
## Brief Alignment
Last checked: Project start
Status: ✓ Aligned
Assessment: No work done yet - baseline alignment.
Drift notes: None
## Session Continuity
Last session: [today's date and time]
Stopped at: Project initialization complete
Resume file: None
```
**Key points:**
- Brief Summary section is IMMUTABLE after creation - never edit it
- Copy verbatim from PROJECT.md to ensure fidelity
- This file will be read first in every future operation
- This file will be updated after every execution
</step>
<step name="git_commit_initialization">
Commit project initialization (brief + roadmap + state together):
```bash
git add .planning/PROJECT.md .planning/ROADMAP.md .planning/STATE.md
git add .planning/phases/
# config.json if exists
git add .planning/config.json 2>/dev/null
git commit -m "$(cat <<'EOF'
docs: initialize [project-name] ([N] phases)
[One-liner from PROJECT.md]
Phases:
1. [phase-name]: [goal]
2. [phase-name]: [goal]
3. [phase-name]: [goal]
EOF
)"
```
Confirm: "Committed: docs: initialize [project] ([N] phases)"
</step>
<step name="offer_next">
```
Project initialized:
- Brief: .planning/PROJECT.md
- Roadmap: .planning/ROADMAP.md
- State: .planning/STATE.md
- Committed as: docs: initialize [project] ([N] phases)
What's next?
1. Discuss Phase 1 context (/gsd:discuss-phase 1)
2. Plan Phase 1 in detail (/gsd:plan-phase 1)
3. Review/adjust phases
4. Done for now
```
**If user selects "Discuss Phase 1 context":**
Exit and invoke SlashCommand("/gsd:discuss-phase 1")
**If user selects "Plan Phase 1 in detail":**
Exit and invoke SlashCommand("/gsd:plan-phase 1")
</step>
</process>
<phase_naming>
Use `XX-kebab-case-name` format:
- `01-foundation`
- `02-authentication`
- `03-core-features`
- `04-polish`
Numbers ensure ordering. Names describe content.
</phase_naming>
<anti_patterns>
- Don't add time estimates
- Don't create Gantt charts
- Don't add resource allocation
- Don't include risk matrices
- Don't plan more than 6 phases (scope creep)
Phases are buckets of work, not project management artifacts.
</anti_patterns>
<success_criteria>
Roadmap is complete when:
- [ ] `.planning/ROADMAP.md` exists
- [ ] `.planning/STATE.md` exists (project memory initialized)
- [ ] 3-6 phases defined with clear names
- [ ] **Research flags assigned** (Likely/Unlikely for each phase)
- [ ] **Research topics listed** for Likely phases
- [ ] Phase directories created
- [ ] Dependencies noted if any
- [ ] Status tracking in place
</success_criteria>
```

144
get-shit-done/workflows/discuss-milestone.md Normal file
View File

@@ -0,0 +1,144 @@
<purpose>
Gather milestone context through adaptive questioning before creating a new milestone, using intake & decision gate pattern to build comprehensive understanding of goals, scope, lessons learned, and success criteria.
</purpose>
<process>
<step name="check_state" priority="first">
Load project state:
```bash
cat .planning/STATE.md
cat .planning/ROADMAP.md
```
**If no active milestone (expected state after completing previous):**
Continue to milestone_context.
**If active milestone exists:**
```
Current milestone in progress: v[X.Y] [Name]
Phases [N]-[M], [P]% complete
Did you want to:
1. Complete current milestone first (/gsd:complete-milestone)
2. Add phases to current milestone (/gsd:add-phase)
3. Continue anyway - discuss next milestone scope
```
Wait for user response. If "Continue anyway", proceed to milestone_context.
</step>
<step name="milestone_context">
Present context from previous milestone:
```
Last completed: v[X.Y] [Name] (shipped [DATE])
Key accomplishments:
- [From MILESTONES.md or STATE.md]
Total phases delivered: [N]
Next phase number: [N+1]
```
Continue to intake_gate.
</step>
<step name="intake_gate">
The primary question is: **What do you want to build/add/fix?**
Everything else (scope, priority, constraints) is secondary and derived from features.
Check for inputs:
- Deferred issues from STATE.md (potential features)
- Known gaps or pain points from usage
- User's ideas for what's next
Start: "What do you want to add, improve, or fix in this milestone?"
Then use AskUserQuestion to explore features. After each response, dig deeper with follow-up questions about specifics.
**Feature exploration questions (use as needed):**
If they named specific features:
- header: "Feature Details"
- question: "Tell me more about [feature] - what should it do?"
- options: [Contextual options based on feature type + "Let me describe it"]
If they described a general direction:
- header: "Breaking It Down"
- question: "That could involve [A], [B], [C] - which matter most?"
- options: [Specific sub-features + "All of them" + "Something else"]
If they're not sure:
- header: "Starting Points"
- question: "What's been frustrating or missing?"
- options: [Deferred issues from STATE.md + pain point categories + "Let me think about it"]
After gathering features, synthesize:
```
Based on what you described:
**Features:**
- [Feature 1]: [brief description]
- [Feature 2]: [brief description]
- [Feature 3]: [brief description]
**Estimated scope:** [N] phases
**Theme suggestion:** v[X.Y] [Name]
```
**Decision gate (MUST have all 3 options):**
```
Header: "Ready?"
Options:
1. "Create milestone" - Proceed to /gsd:new-milestone
2. "Ask more questions" - Explore features or constraints further
3. "Let me add context" - I have more to share
```
If "Ask more questions" → generate 2-3 contextual follow-ups → return to gate.
If "Let me add context" → receive input, update synthesis → return to gate.
Loop until "Create milestone" selected.
</step>
<step name="handoff">
Present summary and hand off to create-milestone:
```
Milestone scope defined:
**Features:**
- [Feature 1]: [description]
- [Feature 2]: [description]
- [Feature 3]: [description]
**Suggested milestone:** v[X.Y] [Theme Name]
**Estimated phases:** [N]
Ready to create the milestone structure.
```
**Invoke:** SlashCommand("/gsd:new-milestone")
Pass context forward by summarizing:
- Features to build (the substance)
- Suggested milestone name
- How features map to phases
</step>
</process>
<success_criteria>
- Project state loaded (STATE.md, ROADMAP.md)
- Previous milestone context presented
- **Features identified** - What to build/add/fix (the substance)
- Features explored with clarifying questions
- Scope synthesized from features (not asked abstractly)
- Context handed off to /gsd:new-milestone with feature list
</success_criteria>

254
get-shit-done/workflows/discuss-phase.md Normal file
View File

@@ -0,0 +1,254 @@
<purpose>
Gather phase context through adaptive questioning before planning, using intake & decision gate pattern to build comprehensive understanding of objectives, constraints, risks, success indicators, and codebase context.
</purpose>
<process>
<step name="validate_phase" priority="first">
Phase number: $ARGUMENTS (required)
Validate phase exists in roadmap:
```bash
if [ -f .planning/ROADMAP.md ]; then
cat .planning/ROADMAP.md | grep "Phase ${PHASE}:"
else
cat .planning/ROADMAP.md | grep "Phase ${PHASE}:"
fi
```
**If phase not found:**
```
Error: Phase ${PHASE} not found in roadmap.
Use /gsd:plan-phase to see available phases.
```
Exit workflow.
**If phase found:**
Parse phase details from roadmap:
- Phase number
- Phase name
- Phase description
- Status (should be "Not started" or "In progress")
Continue to check_existing.
</step>
<step name="check_existing">
Check if CONTEXT.md already exists for this phase:
```bash
ls .planning/phases/${PHASE}-*/CONTEXT.md 2>/dev/null
# Also check for ${PHASE}-CONTEXT.md in phase directory
ls .planning/phases/${PHASE}-*/${PHASE}-CONTEXT.md 2>/dev/null
```
**If exists:**
```
Phase ${PHASE} already has context: [path to CONTEXT.md]
What's next?
1. Update context - Review and revise existing context
2. View existing - Show me the current context
3. Skip - Use existing context as-is
```
Wait for user response.
If "Update context": Load existing CONTEXT.md into intake flow (pre-populate known context)
If "View existing": Read and display CONTEXT.md, then offer update/skip
If "Skip": Exit workflow
**If doesn't exist:**
Continue to intake_gate.
</step>
<step name="intake_gate">
<no_context_handler>
Present initial context from roadmap:
```
Phase ${PHASE}: ${PHASE_NAME}
Roadmap description: ${PHASE_DESCRIPTION}
I'll gather additional context through questions to ensure comprehensive planning.
```
Continue to context_analysis.
</no_context_handler>
<context_analysis>
Analyze roadmap phase description and extract what's already provided:
**Objectives (what):** What this phase accomplishes
**Constraints (how):** Technical/timeline limitations mentioned
**Risks (concerns):** Potential issues mentioned
**Success indicators (done when):** Completion criteria mentioned
**Codebase context (dependencies):** Related systems mentioned
Identify gaps where additional clarity would improve planning quality.
</context_analysis>
<initial_questions>
Ask 2-4 questions based on actual gaps. Use AskUserQuestion with structured options.
**If objectives are vague:**
header: "Phase Objectives"
question: "What should Phase ${PHASE} accomplish?"
options:
- "Create new functionality" - Build something that doesn't exist yet
- "Modify existing system" - Change or enhance what's already there
- "Fix or refactor" - Address bugs or improve code quality
- "Integrate external service" - Connect to API, library, or third-party
- "Infrastructure or setup" - Database, deployment, configuration
- "Other" - Something different
**If constraints are unclear:**
header: "Constraints"
question: "Are there constraints I should know about?"
options:
- "Technical limitations" - Library choices, platform requirements, compatibility
- "Timeline pressure" - Specific deadline or urgency
- "Dependencies" - Waiting on other phases or external factors
- "Performance requirements" - Speed, scale, resource constraints
- "No constraints" - Flexible approach
- "Other" - Something else
**If risks are not mentioned:**
header: "Risks"
question: "What could go wrong in this phase?"
options:
- "Breaking changes" - Could affect existing functionality
- "Integration complexity" - Coordinating multiple systems
- "Unknown unknowns" - New territory, unclear best practices
- "Performance impact" - Could slow things down
- "Security concerns" - Authentication, data protection, vulnerabilities
- "No major risks" - Straightforward implementation
- "Other" - Something else
**If success indicators are unclear:**
header: "Success Indicators"
question: "How will we know this phase is complete?"
options:
- "Feature works" - Functional verification (tests pass, behavior correct)
- "Deployed and live" - Actually running in production
- "User-verified" - Visual/manual confirmation required
- "Metrics hit target" - Performance, coverage, or quality thresholds
- "Documentation complete" - Properly documented for future work
- "Other" - Something else
Skip questions where roadmap already provides clear answers.
</initial_questions>
<gather_codebase_context>
After initial questions, ask about codebase state:
header: "Codebase Context"
question: "What should I know about the current codebase state?"
options:
- "Fresh project" - Just starting, minimal existing code
- "Established patterns" - Follow existing conventions and architecture
- "Needs refactoring" - Current code has issues to address
- "External dependencies" - Relies on specific libraries or services
- "Legacy constraints" - Working with older code or technologies
- "Not sure" - Help me figure this out
- "Other" - Something else
If "Established patterns" or "External dependencies" selected, ask follow-up:
"Which files or systems should I examine for context?"
If "Not sure" selected, offer to scan codebase:
"I can scan the codebase to identify patterns and dependencies. Proceed?"
</gather_codebase_context>
<decision_gate>
**Decision gate (MUST have all 3 options):**
```
Header: "Context Gathering"
Options:
1. "Create CONTEXT.md" - I have enough context, proceed
2. "Ask more questions" - There are details I want to clarify
3. "Let me add context" - I want to provide additional information
```
If "Ask more questions" → generate 2-3 contextual follow-ups based on accumulated context → return to gate.
If "Let me add context" → receive input → return to gate.
Loop until "Create CONTEXT.md" selected.
</decision_gate>
</step>
<step name="write_context">
Create CONTEXT.md using accumulated context from intake flow.
Use template from ~/.claude/get-shit-done/templates/context.md
**File location:** `.planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md`
**If phase directory doesn't exist yet:**
Create it: `.planning/phases/${PHASE}-${SLUG}/`
Use roadmap phase name for slug (lowercase, hyphens).
Populate template sections:
- `<phase_objectives>`: From "what" analysis and questions
- `<constraints>`: From "how" analysis and questions
- `<risks>`: From "concerns" analysis and questions
- `<success_indicators>`: From "done when" analysis and questions
- `<codebase_context>`: From codebase questions and optional scanning
- `<decisions_needed>`: From questions that revealed choices to make
- `<notes>`: Any additional context gathered
Write file.
</step>
<step name="confirm_creation">
Present CONTEXT.md to user:
```
Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
## Phase Objectives
[summary of objectives]
## Key Constraints
[summary of constraints]
## Risks to Watch
[summary of risks]
## Success Indicators
[summary of success criteria]
What's next?
1. Plan this phase (/gsd:plan-phase ${PHASE}) - CONTEXT.md will be loaded automatically
2. Review/edit CONTEXT.md - Make adjustments before planning
3. Done for now
```
</step>
</process>
<success_criteria>
- Phase number validated against roadmap
- Context gathered through adaptive questioning
- All five core areas addressed: objectives, constraints, risks, success indicators, codebase context
- CONTEXT.md created in phase directory using template
- User knows next steps (typically: plan the phase)
</success_criteria>

1261
get-shit-done/workflows/execute-phase.md Normal file
View File

File diff suppressed because it is too large Load Diff

178
get-shit-done/workflows/list-phase-assumptions.md Normal file
View File

@@ -0,0 +1,178 @@
<purpose>
Surface Claude's assumptions about a phase before planning, enabling users to correct misconceptions early.
Key difference from discuss-phase: This is ANALYSIS of what Claude thinks, not INTAKE of what user knows. No file output - purely conversational to prompt discussion.
</purpose>
<process>
<step name="validate_phase" priority="first">
Phase number: $ARGUMENTS (required)
**If argument missing:**
```
Error: Phase number required.
Usage: /gsd:list-phase-assumptions [phase-number]
Example: /gsd:list-phase-assumptions 3
```
Exit workflow.
**If argument provided:**
Validate phase exists in roadmap:
```bash
cat .planning/ROADMAP.md | grep -i "Phase ${PHASE}"
```
**If phase not found:**
```
Error: Phase ${PHASE} not found in roadmap.
Available phases:
[list phases from roadmap]
```
Exit workflow.
**If phase found:**
Parse phase details from roadmap:
- Phase number
- Phase name
- Phase description/goal
- Any scope details mentioned
Continue to analyze_phase.
</step>
<step name="analyze_phase">
Based on roadmap description and project context, identify assumptions across five areas:
**1. Technical Approach:**
What libraries, frameworks, patterns, or tools would Claude use?
- "I'd use X library because..."
- "I'd follow Y pattern because..."
- "I'd structure this as Z because..."
**2. Implementation Order:**
What would Claude build first, second, third?
- "I'd start with X because it's foundational"
- "Then Y because it depends on X"
- "Finally Z because..."
**3. Scope Boundaries:**
What's included vs excluded in Claude's interpretation?
- "This phase includes: A, B, C"
- "This phase does NOT include: D, E, F"
- "Boundary ambiguities: G could go either way"
**4. Risk Areas:**
Where does Claude expect complexity or challenges?
- "The tricky part is X because..."
- "Potential issues: Y, Z"
- "I'd watch out for..."
**5. Dependencies:**
What does Claude assume exists or needs to be in place?
- "This assumes X from previous phases"
- "External dependencies: Y, Z"
- "This will be consumed by..."
Be honest about uncertainty. Mark assumptions with confidence levels:
- "Fairly confident: ..." (clear from roadmap)
- "Assuming: ..." (reasonable inference)
- "Unclear: ..." (could go multiple ways)
</step>
<step name="present_assumptions">
Present assumptions in a clear, scannable format:
```
## My Assumptions for Phase ${PHASE}: ${PHASE_NAME}
### Technical Approach
[List assumptions about how to implement]
### Implementation Order
[List assumptions about sequencing]
### Scope Boundaries
**In scope:** [what's included]
**Out of scope:** [what's excluded]
**Ambiguous:** [what could go either way]
### Risk Areas
[List anticipated challenges]
### Dependencies
**From prior phases:** [what's needed]
**External:** [third-party needs]
**Feeds into:** [what future phases need from this]
---
**What do you think?**
Are these assumptions accurate? Let me know:
- What I got right
- What I got wrong
- What I'm missing
```
Wait for user response.
</step>
<step name="gather_feedback">
**If user provides corrections:**
Acknowledge the corrections:
```
Got it. Key corrections:
- [correction 1]
- [correction 2]
This changes my understanding significantly. [Summarize new understanding]
```
**If user confirms assumptions:**
```
Great, assumptions validated.
```
Continue to offer_next.
</step>
<step name="offer_next">
Present next steps:
```
What's next?
1. Discuss context (/gsd:discuss-phase ${PHASE}) - Let me ask you questions to build comprehensive context
2. Plan this phase (/gsd:plan-phase ${PHASE}) - Create detailed execution plans
3. Re-examine assumptions - I'll analyze again with your corrections
4. Done for now
```
Wait for user selection.
If "Discuss context": Note that CONTEXT.md will incorporate any corrections discussed here
If "Plan this phase": Proceed knowing assumptions are understood
If "Re-examine": Return to analyze_phase with updated understanding
</step>
</process>
<success_criteria>
- Phase number validated against roadmap
- Assumptions surfaced across five areas: technical approach, implementation order, scope, risks, dependencies
- Confidence levels marked where appropriate
- "What do you think?" prompt presented
- User feedback acknowledged
- Clear next steps offered
</success_criteria>

783
get-shit-done/workflows/plan-phase.md Normal file
View File

@@ -0,0 +1,783 @@
<decimal_phase_numbering>
Decimal phases enable urgent work insertion without renumbering:
- Integer phases (1, 2, 3) = planned milestone work
- Decimal phases (2.1, 2.2) = urgent insertions between integers
**Rules:**
- Decimals must be between consecutive integers (2.1 between 2 and 3)
- Filesystem sorting works automatically (2 < 2.1 < 2.2 < 3)
- Execution order follows numeric sort
- Directory format: `02.1-description/` (note the dot)
- Plan format: `02.1-01-PLAN.md`
**Example:**
```
Roadmap before insertion:
- Phase 72: Analytics (complete)
- Phase 73: Dashboard (planned)
User: "Need Sentry bugfix before Phase 73"
System creates Phase 72.1:
- Phase 72: Analytics (complete)
- Phase 72.1: Sentry Bugfix (INSERTED)
- Phase 73: Dashboard (planned)
Execution order: 72 → 72.1 → 73
```
**Validation:**
When creating decimal phase X.Y:
1. Integer phase X must exist and be complete
2. Integer phase X+1 must exist in roadmap
3. Decimal X.Y must not already exist
4. Y must be >= 1
</decimal_phase_numbering>
<required_reading>
**Read these files NOW:**
1. ~/.claude/get-shit-done/templates/phase-prompt.md
2. ~/.claude/get-shit-done/references/plan-format.md
3. ~/.claude/get-shit-done/references/scope-estimation.md
4. ~/.claude/get-shit-done/references/checkpoints.md
5. Read `.planning/ROADMAP.md`
6. Read `.planning/PROJECT.md`
**Load domain expertise from ROADMAP:** 7. Parse ROADMAP.md's `## Domain Expertise` section for paths 8. Read each domain SKILL.md (these serve as indexes) 9. Determine phase type from ROADMAP (UI, database, API, shaders, etc.) 10. Check each SKILL.md's `<references_index>` section 11. Load ONLY references relevant to THIS phase type
**Example:** Planning a UI phase for an ISF shader macOS app:
- ROADMAP says: `expertise/isf-shaders`, `expertise/macos-apps`
- Read both SKILL.md files
- isf-shaders `<references_index>` says: "For UI phases: references/parameter-ui.md"
- macos-apps `<references_index>` says: "For UI phases: references/swiftui-layout.md"
- Load those two references, not everything
</required_reading>
<purpose>
Create an executable phase prompt (PLAN.md). This is where we get specific:
objective, context, tasks, verification, success criteria, and output specification.
**Key insight:** PLAN.md IS the prompt that Claude executes. Not a document that
gets transformed into a prompt.
</purpose>
<process>
<step name="load_project_state" priority="first">
Before any planning, read project state:
```bash
cat .planning/STATE.md 2>/dev/null
```
**If file exists:** Parse and internalize:
- Current position (which phase we're planning)
- Accumulated decisions (constraints on this phase)
- Deferred issues (candidates for inclusion in this phase)
- Blockers/concerns (things this phase may need to address)
- Brief alignment status (are we on track?)
**If file missing but .planning/ exists:**
```
STATE.md missing but planning artifacts exist.
Options:
1. Reconstruct from existing artifacts
2. Continue without project state (may lose accumulated context)
```
This ensures planning has full project context.
</step>
<step name="identify_phase">
Check roadmap for phases:
```bash
cat .planning/ROADMAP.md
ls .planning/phases/
```
If multiple phases available, ask which one to plan.
If obvious (first incomplete phase), proceed.
**Phase number parsing:**
When user provides phase number, parse using regex: `^(\d+)(?:\.(\d+))?$`
- Group 1: Integer part (required) - e.g., "2" from "2" or "2.1"
- Group 2: Decimal part (optional) - e.g., "1" from "2.1"
**If decimal phase (e.g., 72.1):**
Validate insertion:
1. Check integer phase X (72) exists in roadmap: `grep "Phase 72:" ROADMAP.md`
2. Check integer phase X (72) is complete: Look for "Complete" status
3. Check integer phase X+1 (73) exists in roadmap: `grep "Phase 73:" ROADMAP.md`
4. Check decimal X.Y (72.1) doesn't already exist: `ls .planning/phases/ | grep "^72\.1-"`
5. Decimal part Y must be >= 1
If validation fails, explain issue and suggest correction.
**Directory naming:**
```bash
# Integer phase: 01-foundation
# Decimal phase: 01.1-hotfix
if decimal:
DIR_NAME="${PHASE_INT}.${PHASE_DEC}-${SLUG}"
else:
DIR_NAME="${PHASE_INT}-${SLUG}"
fi
```
**Roadmap marking:**
When creating decimal phases, mark them as "(INSERTED)" in roadmap entries.
Read any existing PLAN.md or FINDINGS.md in the phase directory.
</step>
<step name="mandatory_discovery">
**Discovery is MANDATORY unless you can prove current context exists.**
Claude's training data is 6-18 months stale. Treat pre-existing knowledge as hypothesis, not fact.
<discovery_decision_tree>
````
Starting discovery for Phase [X]...
↓
CHECK ROADMAP FLAG FIRST
─────────────────────────────────────
```bash
# Check if roadmap flagged this phase for research
grep -A2 "Phase [X]:" .planning/ROADMAP.md | grep "Research:"
```
→ If `Research: Likely` → Minimum depth is Level 1 (don't skip to Level 0)
→ If `Research: Unlikely` → Level 0 check still runs (might escalate)
→ Flag is a hint, not a mandate - actual depth determined below
↓
LEVEL 0: Pattern Check (30 seconds)
─────────────────────────────────────
**Skip this check if roadmap flagged Research: Likely**
Is this pure internal work using ONLY existing codebase patterns?
Check with:
```bash
# Look for existing patterns in codebase
grep -r "libraryName" src/ 2>/dev/null | head -5
ls src/components/ 2>/dev/null # existing UI patterns
cat package.json 2>/dev/null | grep -A5 '"dependencies"'
```
→ If ALL work follows established codebase patterns: SKIP discovery, proceed to planning
→ If ANY external dependency, new library, or API integration: Continue to Level 1+
↓
Does fresh FINDINGS.md exist?
─────────────────────────────────────
```bash
ls .planning/phases/XX-name/FINDINGS.md 2>/dev/null
```
If exists, check freshness:
- General libraries/frameworks: Valid for 30 days
- Fast-moving APIs (Stripe, OpenAI, etc.): Valid for 7 days
- Check file date vs today
→ If fresh FINDINGS.md exists covering this phase's topics: SKIP discovery, use existing
→ If missing or stale: Continue to determine depth
↓
Determine Discovery Depth
─────────────────────────────────────
Assess the phase requirements:
**LEVEL 1 - Quick Verification (2-5 min):**
Use when:
- Single known library, just confirming syntax/version
- Low-risk decision (easily changed later)
- "Is X still the right choice?"
Action:
1. Context7: mcp**context7**resolve-library-id → mcp**context7**get-library-docs
2. Verify current version/API matches expectations
3. No FINDINGS.md needed - proceed with confirmed knowledge
**LEVEL 2 - Standard Research (15-30 min):**
Use when:
- Choosing between 2-3 options
- New external integration (API, service)
- Medium-risk decision
Action:
1. Route to workflows/research-phase.md with depth=standard
2. Produces FINDINGS.md with recommendation
3. Return here after FINDINGS.md created
**LEVEL 3 - Deep Dive (1+ hour):**
Use when:
- Architectural decision with long-term impact
- Novel problem without clear patterns
- High-risk, hard to change later
- Multiple interacting systems
Action:
1. Route to workflows/research-phase.md with depth=deep
2. Full research with cross-verification
3. FINDINGS.md with detailed rationale and validation checkpoints
4. Return here after FINDINGS.md created
```
</discovery_decision_tree>
<depth_indicators>
**Signals requiring LEVEL 2+:**
- Phase involves new library not in package.json
- Phase involves external API integration
- Phase description includes "choose", "select", "evaluate"
- Roadmap marked this phase with `Research: Yes`
- Technology mentioned that Claude hasn't used in THIS codebase
**Signals requiring LEVEL 3:**
- Words like "architecture", "design", "system"
- Integration between multiple external services
- Data modeling decisions
- Authentication/authorization design
- Real-time, sync, or distributed systems
</depth_indicators>
<skip_conditions>
**Discovery can be skipped (Level 0) ONLY when ALL true:**
□ Pattern already exists in codebase (grep confirms)
□ No new external dependencies
□ Fresh FINDINGS.md exists (if external deps involved)
□ Pure internal refactoring or feature extension
□ Using established project conventions only
**Examples that skip discovery:**
- "Add delete button" → existing button patterns in codebase
- "Add field to model" → Prisma/schema patterns established
- "Create CRUD endpoint" → existing API patterns to follow
**Examples that REQUIRE discovery:**
- "Add authentication" → Level 2-3 (new system, choices to make)
- "Integrate Stripe" → Level 2 (external API)
- "Add email service" → Level 2 (compare options)
- "Design data sync" → Level 3 (architectural)
</skip_conditions>
Present discovery decision:
```
Phase [X]: [Name]
Discovery assessment:
- Roadmap flag: [Likely / Unlikely] ([reason from roadmap])
- Roadmap topics: [topics if flagged, or N/A]
- New external dependencies: [yes/no - list them]
- Existing FINDINGS.md: [yes (date) / no]
- Codebase patterns exist: [yes/no]
Discovery depth: [Level 0 (skip) / Level 1 (verify) / Level 2 (standard) / Level 3 (deep)]
Reason: [one line explanation]
[If Level 1: Proceeding with quick verification...]
[If Level 2-3: Routing to research workflow...]
[If Level 0: Skipping discovery, proceeding to planning...]
````
**Note:** If roadmap flagged `Research: Likely`, Level 0 (skip) is not available.
The roadmap flag lowers the bar for triggering research but doesn't guarantee depth.
</step>
<step name="read_project_history">
Before planning, absorb accumulated project wisdom. This is the **context injection** that ensures each phase benefits from all prior phases.
**1. From STATE.md (already loaded):**
- Decisions table → These CONSTRAIN this phase's approach
- Deferred issues → Candidates for inclusion in this phase
- Blockers/concerns → Things this phase may need to address
**2. Read previous phase summaries:**
```bash
# List all summaries from prior phases
ls .planning/phases/*/*-SUMMARY.md 2>/dev/null | sort
```
Don't load ALL summaries into context—scan them looking for:
- Decisions that constrain this phase's approach
- Issues flagged for "later" where "later" is now
- Warnings in "Next Phase Readiness" that apply
- Patterns established that should be maintained
**3. Read ISSUES.md:**
```bash
cat .planning/ISSUES.md 2>/dev/null
```
For each open issue, assess:
- Is this relevant to the phase being planned?
- Has it been waiting long enough to address?
- Would addressing it now be natural (same files/subsystem)?
- Is it blocking something this phase needs?
**4. Synthesize into planning context:**
Before proceeding to task breakdown, answer:
**Q1: What decisions from previous phases constrain this phase?**
→ These become explicit notes in task `<action>` sections
Example: "Use jose (NOT jsonwebtoken - see Phase 1 decision)"
**Q2: Are there deferred issues that should become tasks?**
→ These get added to the task list, marked "Addressing ISS-XXX"
Example: "Task 3: Add rate limiting (ISS-001 from Phase 2)"
**Q3: Are there concerns from "Next Phase Readiness" that apply?**
→ These inform verification criteria or become explicit tasks
Example: "Load test auth endpoints (Phase 2 concern)"
**Q4: Given all context, does the roadmap's description still make sense?**
→ If not, flag: "Phase as described may need adjustment because [X]"
**5. Document what will inform the plan:**
Track for inclusion in PLAN.md `<context>` section:
- Which prior summaries are relevant (will be @referenced)
- Which decisions apply (brief notes)
- Which issues are being addressed (ISS-XXX numbers)
- Which concerns are being verified
</step>
<step name="gather_phase_context">
For this specific phase, understand:
- What's the phase goal? (from roadmap)
- What exists already? (scan codebase if mid-project)
- What dependencies are met? (previous phases complete?)
- Any research findings? (FINDINGS.md)
- Any phase context? ({phase}-CONTEXT.md)
```bash
# If mid-project, understand current state
ls -la src/ 2>/dev/null
cat package.json 2>/dev/null | head -20
# Check for phase-specific context (created by /gsd:discuss-phase)
cat .planning/phases/XX-name/${PHASE}-CONTEXT.md 2>/dev/null
```
**If {phase}-CONTEXT.md exists:**
This file contains the user's input gathered through pre-planning questions. It captures their intent, preferences, constraints, and decisions BEFORE you plan.
**You MUST use this context to inform your planning:**
- `<phase_objectives>` → defines what to build (don't guess scope)
- `<constraints>` → technical/timeline limits to respect
- `<risks>` → inform verification criteria and task ordering
- `<success_indicators>` → become plan success criteria
- `<codebase_context>` → patterns to follow, files to reference
- `<decisions_needed>` → resolve during task breakdown or flag as checkpoints
- `<notes>` → user clarifications that override assumptions
**If {phase}-CONTEXT.md does NOT exist:**
Suggest running `/gsd:discuss-phase {phase}` first to gather context, OR proceed with roadmap description only (less informed planning).
</step>
<step name="break_into_tasks">
Decompose the phase into tasks.
Each task must have:
- **Type**: auto, checkpoint:human-verify, checkpoint:decision (human-action rarely needed)
- **Task name**: Clear, action-oriented
- **Files**: Which files created/modified (for auto tasks)
- **Action**: Specific implementation (including what to avoid and WHY)
- **Verify**: How to prove it worked
- **Done**: Acceptance criteria
**Identify checkpoints:**
- Claude automated work needing visual/functional verification? → checkpoint:human-verify
- Implementation choices to make? → checkpoint:decision
- Truly unavoidable manual action (email link, 2FA)? → checkpoint:human-action (rare)
**Critical:** If external resource has CLI/API (Vercel, Stripe, Upstash, GitHub, etc.), use type="auto" to automate it. Only checkpoint for verification AFTER automation.
See ~/.claude/get-shit-done/references/checkpoints.md for checkpoint structure and automation guidance.
</step>
<step name="estimate_scope">
After breaking into tasks, assess scope against the **quality degradation curve**.
**ALWAYS split if:**
- > 3 tasks total
- Multiple subsystems (DB + API + UI = separate plans)
- > 5 files modified in any single task
- Complex domains (auth, payments, data modeling)
**Aggressive atomicity principle:** Better to have 10 small, high-quality plans than 3 large, degraded plans.
**If scope is appropriate (2-3 tasks, single subsystem, <5 files per task):**
Proceed to confirm_breakdown for a single plan.
**If scope is large (>3 tasks):**
Split into multiple plans by:
- Subsystem (01-01: Database, 01-02: API, 01-03: UI, 01-04: Frontend)
- Dependency (01-01: Setup, 01-02: Core, 01-03: Features, 01-04: Testing)
- Complexity (01-01: Layout, 01-02: Data fetch, 01-03: Visualization)
- Autonomous vs Interactive (group auto tasks for subagent execution)
**Each plan must be:**
- 2-3 tasks maximum
- ~50% context target (not 80%)
- Independently committable
**Autonomous plan optimization:**
- Plans with NO checkpoints → will execute via subagent (fresh context)
- Plans with checkpoints → execute in main context (user interaction required)
- Try to group autonomous work together for maximum fresh contexts
See ~/.claude/get-shit-done/references/scope-estimation.md for complete splitting guidance and quality degradation analysis.
</step>
<step name="confirm_breakdown">
**Check workflow config for gate behavior:**
```bash
cat .planning/config.json 2>/dev/null
```
Parse the config:
- If `mode: "yolo"` → auto-approve
- If `mode: "interactive"` → prompt user
- If `mode: "custom"` → check `gates.confirm_breakdown`
**If auto-approved:**
```
⚡ Auto-approved: Phase [X] breakdown ([N] tasks, [M] plan(s))
[Show breakdown summary without prompting]
Proceeding to plan creation...
```
**If prompting (interactive mode or custom with gate enabled):**
Present the breakdown inline:
**If single plan (2-3 tasks):**
```
Here's the proposed breakdown for Phase [X]:
### Tasks (single plan: {phase}-01-PLAN.md)
1. [Task name] - [brief description] [type: auto/checkpoint]
2. [Task name] - [brief description] [type: auto/checkpoint]
[3. [Task name] - [brief description] [type: auto/checkpoint]] (optional 3rd task if small)
Autonomous: [yes/no] (no checkpoints = subagent execution with fresh context)
Does this breakdown look right? (yes / adjust / start over)
```
**If multiple plans (>3 tasks or multiple subsystems):**
```
Here's the proposed breakdown for Phase [X]:
This phase requires 3 plans to maintain quality:
### Plan 1: {phase}-01-PLAN.md - [Subsystem/Component Name]
1. [Task name] - [brief description] [type]
2. [Task name] - [brief description] [type]
3. [Task name] - [brief description] [type]
### Plan 2: {phase}-02-PLAN.md - [Subsystem/Component Name]
1. [Task name] - [brief description] [type]
2. [Task name] - [brief description] [type]
### Plan 3: {phase}-03-PLAN.md - [Subsystem/Component Name]
1. [Task name] - [brief description] [type]
2. [Task name] - [brief description] [type]
Each plan is independently executable and scoped to ~50% context.
Does this breakdown look right? (yes / adjust / start over)
```
Wait for confirmation before proceeding.
If "adjust": Ask what to change, revise, present again.
If "start over": Return to gather_phase_context step.
</step>
<step name="approach_ambiguity">
If multiple valid approaches exist for any task:
Use AskUserQuestion:
- header: "Approach"
- question: "For [task], there are multiple valid approaches:"
- options:
- "[Approach A]" - [tradeoff description]
- "[Approach B]" - [tradeoff description]
- "Decide for me" - Use your best judgment
Only ask if genuinely ambiguous. Don't ask obvious choices.
</step>
<step name="decision_gate">
After breakdown confirmed (or auto-approved):
**Check workflow config for gate behavior:**
Read config from previous step (already parsed).
- If `mode: "yolo"` → auto-approve
- If `mode: "interactive"` → prompt user
- If `mode: "custom"` → check `gates.confirm_plan`
**If auto-approved:**
```
⚡ Auto-approved: Create phase prompt for Phase [X]
```
Proceed directly to write_phase_prompt.
**If prompting:**
Use AskUserQuestion:
- header: "Ready"
- question: "Ready to create the phase prompt, or would you like me to ask more questions?"
- options:
- "Create phase prompt" - I have enough context
- "Ask more questions" - There are details to clarify
- "Let me add context" - I want to provide more information
Loop until "Create phase prompt" selected.
</step>
<step name="write_phase_prompt">
Use template from `~/.claude/get-shit-done/templates/phase-prompt.md`.
**If single plan:**
Write to `.planning/phases/XX-name/{phase}-01-PLAN.md`
**If multiple plans:**
Write multiple files:
- `.planning/phases/XX-name/{phase}-01-PLAN.md`
- `.planning/phases/XX-name/{phase}-02-PLAN.md`
- `.planning/phases/XX-name/{phase}-03-PLAN.md`
Each file follows the template structure:
```markdown
---
phase: XX-name
plan: { plan-number }
type: execute
domain: [if domain expertise loaded]
---
<objective>
[Plan-specific goal - what this plan accomplishes]
Purpose: [Why this plan matters for the phase]
Output: [What artifacts will be created by this plan]
</objective>
<execution_context>
./execute-phase.md
~/.claude/get-shit-done/templates/summary.md
[If plan has ANY checkpoint tasks (type="checkpoint:*"), add:]
~/.claude/get-shit-done/references/checkpoints.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
[If research done:]
@.planning/phases/XX-name/FINDINGS.md
[If phase context exists (from /gsd:discuss-phase):]
@.planning/phases/XX-name/{phase}-CONTEXT.md
[If continuing from previous plan in same phase:]
@.planning/phases/XX-name/{phase}-{prev}-SUMMARY.md
[Prior phase summaries relevant to this work (from read_project_history):]
@.planning/phases/01-foundation/01-02-SUMMARY.md # If contains relevant decisions
@.planning/phases/02-auth/02-01-SUMMARY.md # If contains relevant patterns
[Document what prior context informed this plan:]
**Prior decisions affecting this phase:**
- [Decision from Phase X that constrains approach]
- [Decision from Phase Y that establishes pattern]
**Deferred issues being addressed:**
- ISS-XXX: [description] (from Phase Z)
**Concerns being verified:**
- [Concern from Phase W's "Next Phase Readiness"]
[Relevant source files:]
@src/path/to/relevant.ts
</context>
<tasks>
[Tasks in XML format with type attribute]
[Mix of type="auto" and type="checkpoint:*" as needed]
</tasks>
<verification>
[Overall plan verification checks]
</verification>
<success_criteria>
[Measurable completion criteria for this plan]
</success_criteria>
<output>
After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
[Include summary structure from template]
</output>
```
**For multi-plan phases:**
- Each plan has focused scope (3-6 tasks)
- Plans reference previous plan summaries in context
- Last plan's success criteria includes "Phase X complete"
</step>
<step name="offer_next">
**If single plan:**
```
Phase plan created: .planning/phases/XX-name/{phase}-01-PLAN.md
[X] tasks defined.
What's next?
1. Execute plan (/gsd:execute-plan .planning/phases/XX-name/{phase}-01-PLAN.md)
2. Review/adjust tasks
3. Done for now
```
**If user selects "Execute plan":**
Exit skill and invoke SlashCommand("/gsd:execute-plan .planning/phases/XX-name/{phase}-01-PLAN.md")
Note: Command is shown in the options above so user can see what will run.
**If multiple plans:**
```
Phase plans created:
- {phase}-01-PLAN.md ([X] tasks) - [Subsystem name]
- {phase}-02-PLAN.md ([X] tasks) - [Subsystem name]
- {phase}-03-PLAN.md ([X] tasks) - [Subsystem name]
Total: [X] tasks across [Y] focused plans.
What's next?
1. Execute first plan (/gsd:execute-plan .planning/phases/XX-name/{phase}-01-PLAN.md)
2. Review/adjust tasks
3. Done for now
```
**If user selects "Execute first plan":**
Exit skill and invoke SlashCommand("/gsd:execute-plan .planning/phases/XX-name/{phase}-01-PLAN.md")
Note: Command is shown in the options above so user can see what will run.
</step>
</process>
<task_quality>
Good tasks:
- "Add User model to Prisma schema with email, passwordHash, createdAt"
- "Create POST /api/auth/login endpoint with bcrypt validation"
- "Add protected route middleware checking JWT in cookies"
Bad tasks:
- "Set up authentication" (too vague)
- "Make it secure" (not actionable)
- "Handle edge cases" (which ones?)
If you can't specify Files + Action + Verify + Done, the task is too vague.
</task_quality>
<anti_patterns>
- Don't add story points
- Don't estimate hours
- Don't assign to team members
- Don't add acceptance criteria committees
- Don't create sub-sub-sub tasks
Tasks are instructions for Claude, not Jira tickets.
</anti_patterns>
<success_criteria>
Phase planning is complete when:
- [ ] STATE.md read and project history absorbed
- [ ] **Mandatory discovery completed** (Level 0-3 as appropriate)
- [ ] If Level 2-3: FINDINGS.md exists with current context
- [ ] If Level 1: Quick verification performed via Context7
- [ ] Prior decisions, issues, and concerns synthesized
- [ ] One or more PLAN files exist with XML structure ({phase}-{plan}-PLAN.md)
- [ ] Each plan has: Objective, context, tasks, verification, success criteria, output
- [ ] @context references included (including STATE.md, FINDINGS.md if exists, relevant prior summaries)
- [ ] Prior decisions documented in context section
- [ ] Deferred issues being addressed are noted
- [ ] Each plan has 2-3 tasks (scoped to ~50% context)
- [ ] Each task has: Type, Files (if auto), Action, Verify, Done
- [ ] Checkpoints identified and properly structured
- [ ] Tasks are specific enough for Claude to execute
- [ ] If multiple plans: logical split by subsystem/dependency/complexity
- [ ] User knows next steps
</success_criteria>
```

293
get-shit-done/workflows/research-phase.md Normal file
View File

@@ -0,0 +1,293 @@
<purpose>
Execute discovery/research at the appropriate depth level.
Produces FINDINGS.md (for Level 2-3) that informs PLAN.md creation.
Called from plan-phase.md's mandatory_discovery step with a depth parameter.
</purpose>
<depth_levels>
**This workflow supports three depth levels:**
| Level | Name | Time | Output | When |
| ----- | ------------ | --------- | ------------------------------------------ | ----------------------------------------- |
| 1 | Quick Verify | 2-5 min | No file, proceed with verified knowledge | Single library, confirming current syntax |
| 2 | Standard | 15-30 min | FINDINGS.md | Choosing between options, new integration |
| 3 | Deep Dive | 1+ hour | Detailed FINDINGS.md with validation gates | Architectural decisions, novel problems |
**Depth is determined by plan-phase.md before routing here.**
</depth_levels>
<source_hierarchy>
**MANDATORY: Context7 BEFORE WebSearch**
Claude's training data is 6-18 months stale. Always verify.
1. **Context7 MCP FIRST** - Current docs, no hallucination
2. **Official docs** - When Context7 lacks coverage
3. **WebSearch LAST** - For comparisons and trends only
See ~/.claude/get-shit-done/templates/research-prompt.md `<source_hierarchy>` for full protocol.
</source_hierarchy>
<process>
<step name="determine_depth">
Check the depth parameter passed from plan-phase.md:
- `depth=verify` → Level 1 (Quick Verification)
- `depth=standard` → Level 2 (Standard Research)
- `depth=deep` → Level 3 (Deep Dive)
Route to appropriate level workflow below.
</step>
<step name="level_1_quick_verify">
**Level 1: Quick Verification (2-5 minutes)**
For: Single known library, confirming syntax/version still correct.
**Process:**
1. Resolve library in Context7:
```
mcp__context7__resolve-library-id with libraryName: "[library]"
```
2. Fetch relevant docs:
```
mcp__context7__get-library-docs with:
- context7CompatibleLibraryID: [from step 1]
- topic: [specific concern]
```
3. Verify:
- Current version matches expectations
- API syntax unchanged
- No breaking changes in recent versions
4. **If verified:** Return to plan-phase.md with confirmation. No FINDINGS.md needed.
5. **If concerns found:** Escalate to Level 2.
**Output:** Verbal confirmation to proceed, or escalation to Level 2.
</step>
<step name="level_2_standard">
**Level 2: Standard Research (15-30 minutes)**
For: Choosing between options, new external integration.
**Process:**
1. **Identify what to research:**
- What options exist?
- What are the key comparison criteria?
- What's our specific use case?
2. **Context7 for each option:**
```
For each library/framework:
- mcp__context7__resolve-library-id
- mcp__context7__get-library-docs (mode: "code" for API, "info" for concepts)
```
3. **Official docs** for anything Context7 lacks.
4. **WebSearch** for comparisons:
- "[option A] vs [option B] {current_year}"
- "[option] known issues"
- "[option] with [our stack]"
5. **Cross-verify:** Any WebSearch finding → confirm with Context7/official docs.
6. **Quality check:** Before finalizing findings, consult ~/.claude/get-shit-done/references/research-pitfalls.md to avoid common research gaps.
7. **Create FINDINGS.md** using ~/.claude/get-shit-done/templates/research-prompt.md structure:
- Summary with recommendation
- Key findings per option
- Code examples from Context7
- Confidence level (should be MEDIUM-HIGH for Level 2)
8. Return to plan-phase.md.
**Output:** `.planning/phases/XX-name/FINDINGS.md`
</step>
<step name="level_3_deep_dive">
**Level 3: Deep Dive (1+ hour)**
For: Architectural decisions, novel problems, high-risk choices.
**Process:**
1. **Scope the research** using ~/.claude/get-shit-done/templates/research-prompt.md:
- Create RESEARCH.md with clear scope
- Define include/exclude boundaries
- List specific questions to answer
2. **Exhaustive Context7 research:**
- All relevant libraries
- Related patterns and concepts
- Multiple topics per library if needed
3. **Official documentation deep read:**
- Architecture guides
- Best practices sections
- Migration/upgrade guides
- Known limitations
4. **WebSearch for ecosystem context:**
- How others solved similar problems
- Production experiences
- Gotchas and anti-patterns
- Recent changes/announcements
5. **Cross-verify ALL findings:**
- Every WebSearch claim → verify with authoritative source
- Mark what's verified vs assumed
- Flag contradictions
6. **Quality check:** Before finalizing findings, consult ~/.claude/get-shit-done/references/research-pitfalls.md to ensure comprehensive coverage and avoid common research gaps.
7. **Create comprehensive FINDINGS.md:**
- Full structure from ~/.claude/get-shit-done/templates/research-prompt.md
- Quality report with source attribution
- Confidence by finding
- If LOW confidence on any critical finding → add validation checkpoints
8. **Confidence gate:** If overall confidence is LOW, present options before proceeding.
9. Return to plan-phase.md.
**Output:** `.planning/phases/XX-name/FINDINGS.md` (comprehensive)
</step>
<step name="identify_unknowns">
**For Level 2-3:** Define what we need to learn.
Ask: What do we need to learn before we can plan this phase?
- Technology choices?
- Best practices?
- API patterns?
- Architecture approach?
</step>
<step name="create_research_prompt">
Use ~/.claude/get-shit-done/templates/research-prompt.md.
Write to `.planning/phases/XX-name/RESEARCH.md`
Include:
- Clear research objective
- Scoped include/exclude lists
- Source preferences (official docs, Context7, current year)
- Output structure for FINDINGS.md
</step>
<step name="execute_research">
Run the research prompt:
- Use web search for current info
- Use Context7 MCP for library docs
- Prefer current year sources
- Structure findings per template
</step>
<step name="create_findings">
Write `.planning/phases/XX-name/FINDINGS.md`:
- Summary with recommendation
- Key findings with sources
- Code examples if applicable
- Metadata (confidence, dependencies, open questions, assumptions)
</step>
<step name="confidence_gate">
After creating FINDINGS.md, check confidence level.
If confidence is LOW:
Use AskUserQuestion:
- header: "Low Confidence"
- question: "Research confidence is LOW: [reason]. How would you like to proceed?"
- options:
- "Dig deeper" - Do more research before planning
- "Proceed anyway" - Accept uncertainty, plan with caveats
- "Pause" - I need to think about this
If confidence is MEDIUM:
Inline: "Research complete (medium confidence). [brief reason]. Proceed to planning?"
If confidence is HIGH:
Proceed directly, just note: "Research complete (high confidence)."
</step>
<step name="open_questions_gate">
If FINDINGS.md has open_questions:
Present them inline:
"Open questions from research:
- [Question 1]
- [Question 2]
These may affect implementation. Acknowledge and proceed? (yes / address first)"
If "address first": Gather user input on questions, update findings.
</step>
<step name="offer_next">
```
Research complete: .planning/phases/XX-name/FINDINGS.md
Recommendation: [one-liner]
Confidence: [level]
What's next?
1. Discuss phase context (/gsd:discuss-phase [current-phase])
2. Create phase plan (/gsd:plan-phase [current-phase])
3. Refine research (dig deeper)
4. Review findings
```
NOTE: FINDINGS.md is NOT committed separately. It will be committed with phase completion.
</step>
</process>
<success_criteria>
**Level 1 (Quick Verify):**
- Context7 consulted for library/topic
- Current state verified or concerns escalated
- Verbal confirmation to proceed (no files)
**Level 2 (Standard):**
- Context7 consulted for all options
- WebSearch findings cross-verified
- FINDINGS.md created with recommendation
- Confidence level MEDIUM or higher
- Ready to inform PLAN.md creation
**Level 3 (Deep Dive):**
- RESEARCH.md exists with clear scope
- Context7 exhaustively consulted
- All WebSearch findings verified against authoritative sources
- FINDINGS.md created with comprehensive analysis
- Quality report with source attribution
- If LOW confidence findings → validation checkpoints defined
- Confidence gate passed
- Ready to inform PLAN.md creation
</success_criteria>
```

248
get-shit-done/workflows/resume-project.md Normal file
View File

@@ -0,0 +1,248 @@
<trigger>
Use this workflow when:
- Starting a new session on an existing project
- User says "continue", "what's next", "where were we", "resume"
- Any planning operation when .planning/ already exists
- User returns after time away from project
</trigger>
<purpose>
Instantly restore full project context and present clear status.
Enables seamless session continuity for fully autonomous workflows.
"Where were we?" should have an immediate, complete answer.
</purpose>
<process>
<step name="detect_existing_project">
Check if this is an existing project:
```bash
ls .planning/STATE.md 2>/dev/null && echo "Project exists"
ls .planning/ROADMAP.md 2>/dev/null && echo "Roadmap exists"
ls .planning/PROJECT.md 2>/dev/null && echo "Project file exists"
```
**If STATE.md exists:** Proceed to load_state
**If only ROADMAP.md/PROJECT.md exist:** Offer to reconstruct STATE.md
**If .planning/ doesn't exist:** This is a new project - route to /gsd:new-project
</step>
<step name="load_state">
Read and parse STATE.md:
```bash
cat .planning/STATE.md
```
Extract:
- **Brief Summary**: What we're building (immutable reminder)
- **Current Position**: Phase X of Y, Plan A of B, Status
- **Progress**: Visual progress bar
- **Decisions Made**: Key decisions that constrain future work
- **Deferred Issues**: Open items awaiting attention
- **Blockers/Concerns**: Issues carried forward
- **Brief Alignment**: Are we on track?
- **Session Continuity**: Where we left off, any resume files
</step>
<step name="check_incomplete_work">
Look for incomplete work that needs attention:
```bash
# Check for continue-here files (mid-plan resumption)
ls .planning/phases/*/.continue-here*.md 2>/dev/null
# Check for plans without summaries (incomplete execution)
for plan in .planning/phases/*/*-PLAN.md; do
summary="${plan/PLAN/SUMMARY}"
[ ! -f "$summary" ] && echo "Incomplete: $plan"
done 2>/dev/null
```
**If .continue-here file exists:**
- This is a mid-plan resumption point
- Read the file for specific resumption context
- Flag: "Found mid-plan checkpoint"
**If PLAN without SUMMARY exists:**
- Execution was started but not completed
- Flag: "Found incomplete plan execution"
</step>
<step name="present_status">
Present complete project status to user:
```
╔══════════════════════════════════════════════════════════════╗
║ PROJECT STATUS ║
╠══════════════════════════════════════════════════════════════╣
║ Building: [one-liner from Brief Summary] ║
║ ║
║ Phase: [X] of [Y] - [Phase name] ║
║ Plan: [A] of [B] - [Status] ║
║ Progress: [██████░░░░] XX% ║
║ ║
║ Last activity: [date] - [what happened] ║
╚══════════════════════════════════════════════════════════════╝
[If incomplete work found:]
⚠️ Incomplete work detected:
- [.continue-here file or incomplete plan]
[If deferred issues exist:]
📋 [N] deferred issues awaiting attention
[If blockers exist:]
⚠️ Carried concerns:
- [blocker 1]
- [blocker 2]
[If alignment is not ✓:]
⚠️ Brief alignment: [status] - [assessment]
```
</step>
<step name="determine_next_action">
Based on project state, determine the most logical next action:
**If .continue-here file exists:**
→ Primary: Resume from checkpoint
→ Option: Start fresh on current plan
**If incomplete plan (PLAN without SUMMARY):**
→ Primary: Complete the incomplete plan
→ Option: Abandon and move on
**If phase in progress, all plans complete:**
→ Primary: Transition to next phase
→ Option: Review completed work
**If phase ready to plan:**
→ Check if CONTEXT.md exists for this phase:
- If CONTEXT.md missing:
→ Primary: Discuss phase context (gather objectives, constraints, success indicators)
→ Secondary: Plan directly (skip context gathering)
- If CONTEXT.md exists:
→ Primary: Plan the phase
→ Option: Review roadmap
**If phase ready to execute:**
→ Primary: Execute next plan
→ Option: Review the plan first
</step>
<step name="offer_options">
Present contextual options based on project state:
```
What would you like to do?
[Primary action based on state - e.g.:]
1. Resume from checkpoint (/gsd:execute-plan .planning/phases/XX-name/.continue-here-02-01.md)
OR
1. Execute next plan (/gsd:execute-plan .planning/phases/XX-name/02-02-PLAN.md)
OR
1. Discuss Phase 3 context (/gsd:discuss-phase 3) [if CONTEXT.md missing]
OR
1. Plan Phase 3 (/gsd:plan-phase 3) [if CONTEXT.md exists or discuss option declined]
[Secondary options:]
2. Review current phase status
3. Check deferred issues ([N] open)
4. Review brief alignment
5. Something else
```
**Note:** When offering phase planning, check for CONTEXT.md existence first:
```bash
ls .planning/phases/XX-name/CONTEXT.md 2>/dev/null
```
If missing, suggest discuss-phase before plan. If exists, offer plan directly.
Wait for user selection.
</step>
<step name="route_to_workflow">
Based on user selection, route to appropriate workflow:
- **Execute plan** → EXIT and invoke SlashCommand("/gsd:execute-plan [path]")
- **Plan phase** → EXIT and invoke SlashCommand("/gsd:plan-phase [phase-number]")
- **Transition** → ./transition.md
- **Review issues** → Read ISSUES.md, present summary
- **Review alignment** → Read PROJECT.md, compare to current state
- **Something else** → Ask what they need
Note: Commands are shown in the presented options so user can see what will run.
</step>
<step name="update_session">
Before proceeding to routed workflow, update session continuity:
Update STATE.md:
```markdown
## Session Continuity
Last session: [now]
Stopped at: Session resumed, proceeding to [action]
Resume file: [updated if applicable]
```
This ensures if session ends unexpectedly, next resume knows the state.
</step>
</process>
<reconstruction>
If STATE.md is missing but other artifacts exist:
"STATE.md missing. Reconstructing from artifacts..."
1. Read PROJECT.md → Extract Brief Summary
2. Read ROADMAP.md → Determine phases, find current position
3. Scan \*-SUMMARY.md files → Extract decisions, issues, concerns
4. Read ISSUES.md → Count deferred issues
5. Check for .continue-here files → Session continuity
Reconstruct and write STATE.md, then proceed normally.
This handles cases where:
- Project predates STATE.md introduction
- File was accidentally deleted
- Cloning repo without full .planning/ state
</reconstruction>
<quick_resume>
For users who want minimal friction:
If user says just "continue" or "go":
- Load state silently
- Determine primary action
- Execute immediately without presenting options
"Continuing from [state]... [action]"
This enables fully autonomous "just keep going" workflow.
</quick_resume>
<success_criteria>
Resume is complete when:
- [ ] STATE.md loaded (or reconstructed)
- [ ] Incomplete work detected and flagged
- [ ] Clear status presented to user
- [ ] Contextual next actions offered
- [ ] User knows exactly where project stands
- [ ] Session continuity updated
</success_criteria>

488
get-shit-done/workflows/transition.md Normal file
View File

@@ -0,0 +1,488 @@
<required_reading>
**Read these files NOW:**
1. `.planning/STATE.md`
2. `.planning/ROADMAP.md`
3. Current phase's plan files (`*-PLAN.md`)
4. Current phase's summary files (`*-SUMMARY.md`)
</required_reading>
<purpose>
Mark current phase complete and advance to next. This is the natural point
where progress tracking happens - implicit via forward motion.
"Planning next phase" = "current phase is done"
</purpose>
<process>
<step name="load_project_state" priority="first">
Before transition, read project state:
```bash
cat .planning/STATE.md 2>/dev/null
```
Parse current position to verify we're transitioning the right phase.
Note accumulated context that may need updating after transition.
</step>
<step name="verify_completion">
Check current phase has all plan summaries:
```bash
ls .planning/phases/XX-current/*-PLAN.md 2>/dev/null | sort
ls .planning/phases/XX-current/*-SUMMARY.md 2>/dev/null | sort
```
**Verification logic:**
- Count PLAN files
- Count SUMMARY files
- If counts match: all plans complete
- If counts don't match: incomplete
**Check workflow config for gate behavior:**
```bash
cat .planning/config.json 2>/dev/null
```
Parse the config:
- If `mode: "yolo"` → auto-approve transition (if all complete)
- If `mode: "interactive"` → prompt user
- If `mode: "custom"` → check `gates.confirm_transition`
**If all plans complete:**
**If auto-approved:**
```
⚡ Auto-approved: Transition Phase [X] → Phase [X+1]
Phase [X] complete - all [Y] plans finished.
Proceeding to mark done and advance...
```
Proceed directly to cleanup_handoff.
**If prompting:**
Ask: "Phase [X] complete - all [Y] plans finished. Ready to mark done and move to Phase [X+1]?"
**If plans incomplete:**
**SAFETY RAIL: always_confirm_destructive applies here.**
Skipping incomplete plans is destructive - ALWAYS prompt regardless of mode.
Present:
```
Phase [X] has incomplete plans:
- {phase}-01-SUMMARY.md ✓ Complete
- {phase}-02-SUMMARY.md ✗ Missing
- {phase}-03-SUMMARY.md ✗ Missing
⚠️ Safety rail: Skipping plans requires confirmation (destructive action)
Options:
1. Continue current phase (execute remaining plans)
2. Mark complete anyway (skip remaining plans)
3. Review what's left
```
Wait for user decision.
</step>
<step name="cleanup_handoff">
Check for lingering handoffs:
```bash
ls .planning/phases/XX-current/.continue-here*.md 2>/dev/null
```
If found, delete them - phase is complete, handoffs are stale.
</step>
<step name="update_roadmap">
Update the roadmap file:
```bash
ROADMAP_FILE=".planning/ROADMAP.md"
```
Update the file:
- Mark current phase: `[x] Complete`
- Add completion date
- Update plan count to final (e.g., "3/3 plans complete")
- Update Progress table
- Keep next phase as `[ ] Not started`
**Example:**
```markdown
## Phases
- [x] Phase 1: Foundation (completed 2025-01-15)
- [ ] Phase 2: Authentication ← Next
- [ ] Phase 3: Core Features
## Progress
| Phase | Plans Complete | Status | Completed |
| ----------------- | -------------- | ----------- | ---------- |
| 1. Foundation | 3/3 | Complete | 2025-01-15 |
| 2. Authentication | 0/2 | Not started | - |
| 3. Core Features | 0/1 | Not started | - |
```
</step>
<step name="archive_prompts">
If prompts were generated for the phase, they stay in place.
The `completed/` subfolder pattern from create-meta-prompts handles archival.
</step>
<step name="update_current_position_after_transition">
Update Current Position section in STATE.md to reflect phase completion and transition.
**Format:**
```markdown
Phase: [next] of [total] ([Next phase name])
Plan: Not started
Status: Ready to plan
Last activity: [today] - Phase [X] complete, transitioned to Phase [X+1]
Progress: [updated progress bar]
```
**Instructions:**
- Increment phase number to next phase
- Reset plan to "Not started"
- Set status to "Ready to plan"
- Update last activity to describe transition
- Recalculate progress bar based on completed plans
**Example - transitioning from Phase 2 to Phase 3:**
Before:
```markdown
## Current Position
Phase: 2 of 4 (Authentication)
Plan: 2 of 2 in current phase
Status: Phase complete
Last activity: 2025-01-20 - Completed 02-02-PLAN.md
Progress: ███████░░░ 60%
```
After:
```markdown
## Current Position
Phase: 3 of 4 (Core Features)
Plan: Not started
Status: Ready to plan
Last activity: 2025-01-20 - Phase 2 complete, transitioned to Phase 3
Progress: ███████░░░ 60%
```
**Step complete when:**
- [ ] Phase number incremented to next phase
- [ ] Plan status reset to "Not started"
- [ ] Status shows "Ready to plan"
- [ ] Last activity describes the transition
- [ ] Progress bar still reflects total completed plans
</step>
<step name="review_accumulated_context">
Review and update Accumulated Context section in STATE.md.
**Blockers/Concerns:**
- Review blockers from completed phase
- If addressed in this phase: Remove from list
- If still relevant for future: Keep with note "Carried from Phase X"
- Add any new concerns from completed phase's summaries
**Deferred Issues:**
- Count open issues in ISSUES.md
- Update count: "[N] open issues - see ISSUES.md"
- If many accumulated, note: "Consider addressing ISS-XXX, ISS-YYY in next phase"
**Example:**
Before:
```markdown
### Blockers/Concerns Carried Forward
- ⚠️ [Phase 1] Database schema not indexed for common queries
- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
### Deferred Issues
- ISS-001: Rate limiting on sync endpoint (Phase 2) - Medium
```
After (if database indexing was addressed in Phase 2):
```markdown
### Blockers/Concerns Carried Forward
- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
### Deferred Issues
- ISS-001: Rate limiting on sync endpoint (Phase 2) - Medium
- ISS-002: Better sync error messages (Phase 2) - Quick
```
**Step complete when:**
- [ ] Resolved blockers removed from list
- [ ] Unresolved blockers kept with phase prefix
- [ ] New concerns from completed phase added
- [ ] Deferred issues count updated
</step>
<step name="update_brief_alignment">
Perform brief alignment check after phase completion to verify work matches original vision.
**Instructions:**
1. Re-read PROJECT.md core requirements
2. Assess what was built in completed phase
3. Compare against project's problem statement and success criteria
4. Determine alignment status:
- ✓ Aligned: Work delivers on project goals, no scope drift
- ⚠️ Drift detected: Some divergence from original vision
- ✗ Misaligned: Work doesn't serve the project
**Format:**
```markdown
## Brief Alignment
Last checked: [today] (Phase [X] completion)
Status: [✓ Aligned / ⚠️ Drift detected / ✗ Misaligned]
Assessment: [One sentence describing alignment state]
Drift notes: [Details if drift detected, otherwise "None"]
```
**Example - transitioning after Phase 2 completion:**
Before:
```markdown
## Brief Alignment
Last checked: Project start
Status: ✓ Aligned
Assessment: No work done yet - baseline alignment.
Drift notes: None
```
After:
```markdown
## Brief Alignment
Last checked: 2025-01-20 (Phase 2 completion)
Status: ✓ Aligned
Assessment: Auth phase delivered JWT-based authentication as specified. Sync phase next aligns with project's real-time requirements.
Drift notes: None
```
**Alternative example - drift detected:**
After (with drift):
```markdown
## Brief Alignment
Last checked: 2025-01-20 (Phase 2 completion)
Status: ⚠️ Drift detected
Assessment: Auth phase added OAuth2 support beyond project's JWT requirement.
Drift notes: OAuth2 adds complexity not in original scope. Consider if this serves user needs or gold-plating.
```
**Step complete when:**
- [ ] PROJECT.md core requirements reviewed
- [ ] Completed phase work assessed against project goals
- [ ] Last checked updated to current date with phase reference
- [ ] Status reflects actual alignment (Aligned/Drift/Misaligned)
- [ ] Assessment explains the alignment state in one sentence
- [ ] Drift notes document any divergence from project goals
</step>
<step name="update_session_continuity_after_transition">
Update Session Continuity section in STATE.md to reflect transition completion.
**Format:**
```markdown
Last session: [today]
Stopped at: Phase [X] complete, ready to plan Phase [X+1]
Resume file: None
```
**Example - after completing Phase 2 transition:**
Before:
```markdown
## Session Continuity
Last session: 2025-01-20
Stopped at: Completed 02-02-PLAN.md
Resume file: None
```
After:
```markdown
## Session Continuity
Last session: 2025-01-20 16:45
Stopped at: Phase 2 complete, ready to plan Phase 3
Resume file: None
```
**Step complete when:**
- [ ] Last session timestamp updated to current date and time
- [ ] Stopped at describes phase completion and next phase
- [ ] Resume file confirmed as None (transitions don't use resume files)
</step>
<step name="offer_next_phase">
**Check if there's a next phase in the current milestone:**
Re-read the ROADMAP file:
- Parse current milestone version (e.g., "v1.0" from "## Current Milestone: v1.0 Foundation")
- Look for phases after the current one in the current milestone section
- If next phase exists: offer to plan it
- If no next phase (milestone 100% complete): offer to complete milestone with parsed version
**Check workflow config for gate behavior:**
Read config (already parsed).
- If `mode: "yolo"` → auto-continue
- If `mode: "interactive"` → prompt user
- If `mode: "custom"` → check `gates.confirm_transition` (reused for continuation)
**If next phase exists:**
**If auto-approved:**
```
Phase [X] marked complete.
Next: Phase [X+1] - [Name]
⚡ Auto-continuing: Plan Phase [X+1] in detail
```
Exit skill and invoke SlashCommand("/gsd:plan-phase [X+1]")
**If prompting:**
```
Phase [X] marked complete.
Next: Phase [X+1] - [Name]
What would you like to do?
1. Discuss Phase [X+1] context (/gsd:discuss-phase [X+1])
2. Plan Phase [X+1] in detail (/gsd:plan-phase [X+1])
3. Review roadmap
4. Take a break (done for now)
```
**If no next phase (milestone 100% complete):**
**If auto-approved:**
```
Phase [X] marked complete.
🎉 Milestone [version] is 100% complete - all phases finished!
⚡ Auto-continuing: Complete milestone and archive
```
Exit skill and invoke SlashCommand("/gsd:complete-milestone [version]")
**If prompting:**
```
Phase [X] marked complete.
🎉 Milestone [version] is 100% complete - all phases finished!
What would you like to do?
1. Complete milestone and archive (/gsd:complete-milestone [version])
2. Review accomplishments
3. Take a break (done for now)
```
</step>
</process>
<implicit_tracking>
Progress tracking is IMPLICIT:
- "Plan phase 2" → Phase 1 must be done (or ask)
- "Plan phase 3" → Phases 1-2 must be done (or ask)
- Transition workflow makes it explicit in ROADMAP.md
No separate "update progress" step. Forward motion IS progress.
</implicit_tracking>
<partial_completion>
If user wants to move on but phase isn't fully complete:
```
Phase [X] has incomplete plans:
- {phase}-02-PLAN.md (not executed)
- {phase}-03-PLAN.md (not executed)
Options:
1. Mark complete anyway (plans weren't needed)
2. Defer work to later phase
3. Stay and finish current phase
```
Respect user judgment - they know if work matters.
**If marking complete with incomplete plans:**
- Update ROADMAP: "2/3 plans complete" (not "3/3")
- Note in transition message which plans were skipped
</partial_completion>
<success_criteria>
Transition is complete when:
- [ ] Current phase plan summaries verified (all exist or user chose to skip)
- [ ] Any stale handoffs deleted
- [ ] ROADMAP.md updated with completion status and plan count
- [ ] STATE.md updated (position, blockers, alignment, session)
- [ ] Brief alignment check performed
- [ ] Progress table updated
- [ ] User knows next steps
</success_criteria>

30
package.json Normal file
View File

@@ -0,0 +1,30 @@
{
"name": "get-shit-done-cc",
"version": "1.0.0",
"description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
"bin": {
"get-shit-done": "./bin/install.js"
},
"files": [
"bin",
"commands",
"get-shit-done"
],
"keywords": [
"claude",
"claude-code",
"ai",
"meta-prompting",
"context-engineering",
"spec-driven-development"
],
"author": "TÂCHES",
"license": "MIT",
"repository": {
"type": "git",
"url": "git+https://github.com/glittercowboy/get-shit-done.git"
},
"engines": {
"node": ">=16.7.0"
}
}