get shit down (gsd) initialize
This commit is contained in:
Nuwan
parent
e86726c4fc
commit
e39ebb5e23
|
|
@ -0,0 +1,207 @@
|
|||
---
|
||||
name: gsd:add-phase
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase {N}: {description}**
|
||||
|
||||
`/gsd:plan-phase {N}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:add-phase <description>` — add another phase
|
||||
- Review roadmap
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<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>
|
||||
|
|
@ -0,0 +1,106 @@
|
|||
---
|
||||
type: prompt
|
||||
name: gsd:complete-milestone
|
||||
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>
|
||||
|
|
@ -0,0 +1,202 @@
|
|||
---
|
||||
name: gsd:consider-issues
|
||||
description: Review deferred issues with codebase context, close resolved ones, identify urgent ones
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
- Grep
|
||||
- Glob
|
||||
- Edit
|
||||
- AskUserQuestion
|
||||
- SlashCommand
|
||||
---
|
||||
|
||||
<objective>
|
||||
Review all open issues from ISSUES.md with current codebase context. Identify which issues are resolved (can close), which are now urgent (should address), and which can continue waiting.
|
||||
|
||||
This prevents issue pile-up by providing a triage mechanism with codebase awareness.
|
||||
</objective>
|
||||
|
||||
<context>
|
||||
@.planning/ISSUES.md
|
||||
@.planning/STATE.md
|
||||
@.planning/ROADMAP.md
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="verify">
|
||||
**Verify issues file exists:**
|
||||
|
||||
If no `.planning/ISSUES.md`:
|
||||
```
|
||||
No issues file found.
|
||||
|
||||
This means no enhancements have been deferred yet (Rule 5 hasn't triggered).
|
||||
|
||||
Nothing to review.
|
||||
```
|
||||
Exit.
|
||||
|
||||
If ISSUES.md exists but has no open issues (only template or empty "Open Enhancements"):
|
||||
```
|
||||
No open issues to review.
|
||||
|
||||
All clear - continue with current work.
|
||||
```
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="parse">
|
||||
**Parse all open issues:**
|
||||
|
||||
Extract from "## Open Enhancements" section:
|
||||
- ISS number (ISS-001, ISS-002, etc.)
|
||||
- Brief description
|
||||
- Discovered phase/date
|
||||
- Type (Performance/Refactoring/UX/Testing/Documentation/Accessibility)
|
||||
- Description details
|
||||
- Effort estimate
|
||||
|
||||
Build list of issues to analyze.
|
||||
</step>
|
||||
|
||||
<step name="analyze">
|
||||
**For each open issue, perform codebase analysis:**
|
||||
|
||||
1. **Check if still relevant:**
|
||||
- Search codebase for related code/files mentioned in issue
|
||||
- If code no longer exists or was significantly refactored: likely resolved
|
||||
|
||||
2. **Check if accidentally resolved:**
|
||||
- Look for commits/changes that may have addressed this
|
||||
- Check if the enhancement was implemented as part of other work
|
||||
|
||||
3. **Assess current urgency:**
|
||||
- Is this blocking upcoming phases?
|
||||
- Has this become a pain point mentioned in recent summaries?
|
||||
- Is this now affecting code we're actively working on?
|
||||
|
||||
4. **Check natural fit:**
|
||||
- Does this align with an upcoming phase in the roadmap?
|
||||
- Would addressing it now touch the same files as current work?
|
||||
|
||||
**Categorize each issue:**
|
||||
- **Resolved** - Can be closed (code changed, no longer applicable)
|
||||
- **Urgent** - Should address before continuing (blocking or causing problems)
|
||||
- **Natural fit** - Good candidate for upcoming phase X
|
||||
- **Can wait** - Keep deferred, no change in status
|
||||
</step>
|
||||
|
||||
<step name="report">
|
||||
**Present categorized report:**
|
||||
|
||||
```
|
||||
# Issue Review
|
||||
|
||||
**Analyzed:** [N] open issues
|
||||
**Last reviewed:** [today's date]
|
||||
|
||||
## Resolved (can close)
|
||||
|
||||
### ISS-XXX: [description]
|
||||
**Reason:** [Why it's resolved - code changed, implemented elsewhere, no longer applicable]
|
||||
**Evidence:** [What you found - file changes, missing code, etc.]
|
||||
|
||||
[Repeat for each resolved issue, or "None" if none resolved]
|
||||
|
||||
---
|
||||
|
||||
## Urgent (should address now)
|
||||
|
||||
### ISS-XXX: [description]
|
||||
**Why urgent:** [What changed - blocking next phase, causing active problems, etc.]
|
||||
**Recommendation:** Insert plan before Phase [X] / Add to current phase
|
||||
**Effort:** [Quick/Medium/Substantial]
|
||||
|
||||
[Repeat for each urgent issue, or "None - all issues can wait" if none urgent]
|
||||
|
||||
---
|
||||
|
||||
## Natural Fit for Upcoming Work
|
||||
|
||||
### ISS-XXX: [description]
|
||||
**Fits with:** Phase [X] - [phase name]
|
||||
**Reason:** [Same files, same subsystem, natural inclusion]
|
||||
|
||||
[Repeat for each, or "None" if no natural fits]
|
||||
|
||||
---
|
||||
|
||||
## Can Wait (no change)
|
||||
|
||||
### ISS-XXX: [description]
|
||||
**Status:** Still valid, not urgent, keep deferred
|
||||
|
||||
[Repeat for each, or list ISS numbers if many]
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="offer_actions">
|
||||
**Offer batch actions:**
|
||||
|
||||
Based on analysis, present options:
|
||||
|
||||
```
|
||||
## Actions
|
||||
|
||||
What would you like to do?
|
||||
```
|
||||
|
||||
Use AskUserQuestion with appropriate options based on findings:
|
||||
|
||||
**If resolved issues exist:**
|
||||
- "Close resolved issues" - Move to Closed Enhancements section
|
||||
- "Review each first" - Show details before closing
|
||||
|
||||
**If urgent issues exist:**
|
||||
- "Insert urgent phase" - Create phase to address urgent issues (/gsd:insert-phase)
|
||||
- "Add to current plan" - Include in next plan being created
|
||||
- "Defer anyway" - Keep as-is despite urgency
|
||||
|
||||
**If natural fits exist:**
|
||||
- "Note for phase planning" - Will be picked up during /gsd:plan-phase
|
||||
- "Add explicit reminder" - Update issue with "Include in Phase X"
|
||||
|
||||
**Always include:**
|
||||
- "Done for now" - Exit without changes
|
||||
</step>
|
||||
|
||||
<step name="execute_actions">
|
||||
**Execute selected actions:**
|
||||
|
||||
**If closing resolved issues:**
|
||||
1. Read current ISSUES.md
|
||||
2. For each resolved issue:
|
||||
- Remove from "## Open Enhancements"
|
||||
- Add to "## Closed Enhancements" with resolution note:
|
||||
```
|
||||
### ISS-XXX: [description]
|
||||
**Resolved:** [date] - [reason]
|
||||
```
|
||||
3. Write updated ISSUES.md
|
||||
4. Update STATE.md deferred issues count
|
||||
|
||||
**If inserting urgent phase:**
|
||||
- Display the command for user to run after clearing: `/gsd:insert-phase [after-phase] Address urgent issues ISS-XXX, ISS-YYY`
|
||||
|
||||
**If noting for phase planning:**
|
||||
- Update issue's "Suggested phase" field with specific phase number
|
||||
- These will be picked up by /gsd:plan-phase workflow
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] All open issues analyzed against current codebase
|
||||
- [ ] Each issue categorized (resolved/urgent/natural-fit/can-wait)
|
||||
- [ ] Clear reasoning provided for each categorization
|
||||
- [ ] Actions offered based on findings
|
||||
- [ ] ISSUES.md updated if user takes action
|
||||
- [ ] STATE.md updated if issue count changes
|
||||
</success_criteria>
|
||||
|
|
@ -0,0 +1,115 @@
|
|||
---
|
||||
name: gsd:create-roadmap
|
||||
description: Create roadmap with phases for the project
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- AskUserQuestion
|
||||
- Glob
|
||||
---
|
||||
|
||||
<objective>
|
||||
Create project roadmap with phase breakdown.
|
||||
|
||||
Roadmaps define what work happens in what order. Run after /gsd:new-project.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@./.claude/get-shit-done/workflows/create-roadmap.md
|
||||
@./.claude/get-shit-done/templates/roadmap.md
|
||||
@./.claude/get-shit-done/templates/state.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/config.json
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="validate">
|
||||
```bash
|
||||
# Verify project exists
|
||||
[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md found. Run /gsd:new-project first."; exit 1; }
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="check_existing">
|
||||
Check if roadmap already exists:
|
||||
|
||||
```bash
|
||||
[ -f .planning/ROADMAP.md ] && echo "ROADMAP_EXISTS" || echo "NO_ROADMAP"
|
||||
```
|
||||
|
||||
**If ROADMAP_EXISTS:**
|
||||
Use AskUserQuestion:
|
||||
- header: "Roadmap exists"
|
||||
- question: "A roadmap already exists. What would you like to do?"
|
||||
- options:
|
||||
- "View existing" - Show current roadmap
|
||||
- "Replace" - Create new roadmap (will overwrite)
|
||||
- "Cancel" - Keep existing roadmap
|
||||
|
||||
If "View existing": `cat .planning/ROADMAP.md` and exit
|
||||
If "Cancel": Exit
|
||||
If "Replace": Continue with workflow
|
||||
</step>
|
||||
|
||||
<step name="create_roadmap">
|
||||
Follow the create-roadmap.md workflow starting from detect_domain step.
|
||||
|
||||
The workflow handles:
|
||||
- Domain expertise detection
|
||||
- Phase identification
|
||||
- Research flags for each phase
|
||||
- Confirmation gates (respecting config mode)
|
||||
- ROADMAP.md creation
|
||||
- STATE.md initialization
|
||||
- Phase directory creation
|
||||
- Git commit
|
||||
</step>
|
||||
|
||||
<step name="done">
|
||||
```
|
||||
Roadmap created:
|
||||
- Roadmap: .planning/ROADMAP.md
|
||||
- State: .planning/STATE.md
|
||||
- [N] phases defined
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase 1: [Name]** — [Goal from ROADMAP.md]
|
||||
|
||||
`/gsd:plan-phase 1`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:discuss-phase 1` — gather context first
|
||||
- `/gsd:research-phase 1` — investigate unknowns
|
||||
- Review roadmap
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<output>
|
||||
- `.planning/ROADMAP.md`
|
||||
- `.planning/STATE.md`
|
||||
- `.planning/phases/XX-name/` directories
|
||||
</output>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] PROJECT.md validated
|
||||
- [ ] ROADMAP.md created with phases
|
||||
- [ ] STATE.md initialized
|
||||
- [ ] Phase directories created
|
||||
- [ ] Changes committed
|
||||
</success_criteria>
|
||||
|
|
@ -0,0 +1,47 @@
|
|||
---
|
||||
name: gsd:discuss-milestone
|
||||
description: Gather context for next milestone through adaptive questioning
|
||||
---
|
||||
|
||||
<objective>
|
||||
Help you figure out what to build in the next milestone through collaborative thinking.
|
||||
|
||||
Purpose: After completing a milestone, explore what features you want to add, improve, or fix. Features first — scope and phases derive from what you want to build.
|
||||
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 with **ALL questions using AskUserQuestion**:
|
||||
- Use AskUserQuestion: "What do you want to add, improve, or fix?" with feature categories
|
||||
- Use AskUserQuestion to dig into features they mention
|
||||
- Use AskUserQuestion to help them articulate what matters most
|
||||
- Use AskUserQuestion for decision gate (ready / ask more / let me add context)
|
||||
4. Hand off to /gsd:new-milestone with gathered context
|
||||
|
||||
**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
|
||||
</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>
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
---
|
||||
name: gsd:discuss-phase
|
||||
description: Gather phase context through adaptive questioning before planning
|
||||
argument-hint: "[phase]"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Help the user articulate their vision for a phase through collaborative thinking.
|
||||
|
||||
Purpose: Understand HOW the user imagines this phase working — what it looks like, what's essential, what's out of scope. You're a thinking partner helping them crystallize their vision, not an interviewer gathering technical requirements.
|
||||
|
||||
Output: {phase}-CONTEXT.md capturing the user's vision for the phase
|
||||
</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 with **ALL questions using AskUserQuestion**:
|
||||
- Present phase from roadmap
|
||||
- Use AskUserQuestion: "How do you imagine this working?" with interpretation options
|
||||
- Use AskUserQuestion to follow their thread — probe what excites them
|
||||
- Use AskUserQuestion to sharpen the core — what's essential for THIS phase
|
||||
- Use AskUserQuestion to find boundaries — what's explicitly out of scope
|
||||
- Use AskUserQuestion for decision gate (ready / ask more / let me add context)
|
||||
- Create CONTEXT.md capturing their vision
|
||||
5. Offer next steps (research or plan the phase)
|
||||
|
||||
**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
|
||||
|
||||
User is the visionary, you are the builder:
|
||||
- Ask about vision, feel, essential outcomes
|
||||
- DON'T ask about technical risks (you figure those out)
|
||||
- DON'T ask about codebase patterns (you read the code)
|
||||
- DON'T ask about success metrics (too corporate)
|
||||
- DON'T interrogate about constraints they didn't mention
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- Phase validated against roadmap
|
||||
- Vision gathered through collaborative thinking (not interrogation)
|
||||
- CONTEXT.md captures: how it works, what's essential, what's out of scope
|
||||
- User knows next steps (research or plan the phase)
|
||||
</success_criteria>
|
||||
|
|
@ -0,0 +1,129 @@
|
|||
---
|
||||
name: gsd:execute-plan
|
||||
description: Execute a PLAN.md file
|
||||
argument-hint: "[path-to-PLAN.md]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- Task
|
||||
- AskUserQuestion
|
||||
- SlashCommand
|
||||
---
|
||||
|
||||
<objective>
|
||||
Execute a PLAN.md file with per-task atomic commits, create SUMMARY.md, update project state.
|
||||
|
||||
Commit strategy:
|
||||
- Each task → 1 commit immediately after completion (feat/fix/test/refactor)
|
||||
- Plan completion → 1 metadata commit (docs: SUMMARY + STATE + ROADMAP)
|
||||
|
||||
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
|
||||
@./.claude/get-shit-done/references/tdd.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>
|
||||
**Per-Task Commits:**
|
||||
|
||||
After each task completes:
|
||||
1. Stage only files modified by that task
|
||||
2. Commit with format: `{type}({phase}-{plan}): {task-name}`
|
||||
3. Types: feat, fix, test, refactor, perf, chore
|
||||
4. Record commit hash for SUMMARY.md
|
||||
|
||||
**Plan Metadata Commit:**
|
||||
|
||||
After all tasks complete:
|
||||
1. Stage planning artifacts only: PLAN.md, SUMMARY.md, STATE.md, ROADMAP.md
|
||||
2. Commit with format: `docs({phase}-{plan}): complete [plan-name] plan`
|
||||
3. NO code files (already committed per-task)
|
||||
|
||||
**NEVER use:**
|
||||
- `git add .`
|
||||
- `git add -A`
|
||||
- `git add src/` or any broad directory
|
||||
|
||||
**Always stage files individually.**
|
||||
|
||||
See ./.claude/get-shit-done/references/git-integration.md for full commit strategy.
|
||||
</commit_rules>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- [ ] All tasks executed
|
||||
- [ ] Each task committed individually (feat/fix/test/refactor)
|
||||
- [ ] SUMMARY.md created with substantive content and commit hashes
|
||||
- [ ] STATE.md updated (position, decisions, issues, session)
|
||||
- [ ] ROADMAP updated (plan count, phase status)
|
||||
- [ ] Metadata committed with docs({phase}-{plan}): complete [plan-name] plan
|
||||
- [ ] User informed of next steps
|
||||
</success_criteria>
|
||||
|
|
@ -0,0 +1,315 @@
|
|||
---
|
||||
name: gsd:help
|
||||
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
|
||||
2. `/gsd:create-roadmap` - Create roadmap and phases
|
||||
3. `/gsd:plan-phase <number>` - Create detailed plan for first phase
|
||||
4. `/gsd:execute-plan <path>` - Execute the plan
|
||||
|
||||
## Core Workflow
|
||||
|
||||
```
|
||||
Initialization → Planning → Execution → Milestone Completion
|
||||
```
|
||||
|
||||
### Project Initialization
|
||||
|
||||
**`/gsd:new-project`**
|
||||
Initialize new project with brief and configuration.
|
||||
|
||||
- Creates `.planning/PROJECT.md` (vision and requirements)
|
||||
- Creates `.planning/config.json` (workflow mode)
|
||||
- Asks for workflow mode (interactive/yolo) upfront
|
||||
- Commits initialization files to git
|
||||
|
||||
Usage: `/gsd:new-project`
|
||||
|
||||
**`/gsd:create-roadmap`**
|
||||
Create roadmap and state tracking for initialized project.
|
||||
|
||||
- Creates `.planning/ROADMAP.md` (phase breakdown)
|
||||
- Creates `.planning/STATE.md` (project memory)
|
||||
- Creates `.planning/phases/` directories
|
||||
|
||||
Usage: `/gsd:create-roadmap`
|
||||
|
||||
**`/gsd:map-codebase`**
|
||||
Map an existing codebase for brownfield projects.
|
||||
|
||||
- Analyzes codebase with parallel Explore agents
|
||||
- Creates `.planning/codebase/` with 7 focused documents
|
||||
- Covers stack, architecture, structure, conventions, testing, integrations, concerns
|
||||
- Use before `/gsd:new-project` on existing codebases
|
||||
|
||||
Usage: `/gsd:map-codebase`
|
||||
|
||||
### Phase Planning
|
||||
|
||||
**`/gsd:discuss-phase <number>`**
|
||||
Help articulate your vision for a phase before planning.
|
||||
|
||||
- Captures how you imagine this phase working
|
||||
- Creates CONTEXT.md with your vision, essentials, and boundaries
|
||||
- Use when you have ideas about how something should look/feel
|
||||
|
||||
Usage: `/gsd:discuss-phase 2`
|
||||
|
||||
**`/gsd:research-phase <number>`**
|
||||
Comprehensive ecosystem research for niche/complex domains.
|
||||
|
||||
- Discovers standard stack, architecture patterns, pitfalls
|
||||
- Creates RESEARCH.md with "how experts build this" knowledge
|
||||
- Use for 3D, games, audio, shaders, ML, and other specialized domains
|
||||
- Goes beyond "which library" to ecosystem knowledge
|
||||
|
||||
Usage: `/gsd:research-phase 3`
|
||||
|
||||
**`/gsd:list-phase-assumptions <number>`**
|
||||
See what Claude is planning to do before it starts.
|
||||
|
||||
- Shows Claude's intended approach for a phase
|
||||
- Lets you course-correct if Claude misunderstood your vision
|
||||
- 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
|
||||
|
||||
**`/gsd:remove-phase <number>`**
|
||||
Remove a future phase and renumber subsequent phases.
|
||||
|
||||
- Deletes phase directory and all references
|
||||
- Renumbers all subsequent phases to close the gap
|
||||
- Only works on future (unstarted) phases
|
||||
- Git commit preserves historical record
|
||||
|
||||
Usage: `/gsd:remove-phase 17`
|
||||
Result: Phase 17 deleted, phases 18-20 become 17-19
|
||||
|
||||
### Milestone Management
|
||||
|
||||
**`/gsd:discuss-milestone`**
|
||||
Figure out what you want to build in the next milestone.
|
||||
|
||||
- Reviews what shipped in previous milestone
|
||||
- Helps you identify features to add, improve, or fix
|
||||
- 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`
|
||||
|
||||
### Issue Management
|
||||
|
||||
**`/gsd:consider-issues`**
|
||||
Review deferred issues with codebase context.
|
||||
|
||||
- Analyzes all open issues against current codebase state
|
||||
- Identifies resolved issues (can close)
|
||||
- Identifies urgent issues (should address now)
|
||||
- Identifies natural fits for upcoming phases
|
||||
- Offers batch actions (close, insert phase, note for planning)
|
||||
|
||||
Usage: `/gsd:consider-issues`
|
||||
|
||||
### 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
|
||||
├── ISSUES.md # Deferred enhancements (created when needed)
|
||||
├── config.json # Workflow mode & gates
|
||||
├── codebase/ # Codebase map (brownfield projects)
|
||||
│ ├── STACK.md # Languages, frameworks, dependencies
|
||||
│ ├── ARCHITECTURE.md # Patterns, layers, data flow
|
||||
│ ├── STRUCTURE.md # Directory layout, key files
|
||||
│ ├── CONVENTIONS.md # Coding standards, naming
|
||||
│ ├── TESTING.md # Test setup, patterns
|
||||
│ ├── INTEGRATIONS.md # External services, APIs
|
||||
│ └── CONCERNS.md # Tech debt, known issues
|
||||
└── phases/
|
||||
├── 01-foundation/
|
||||
│ ├── 01-01-PLAN.md
|
||||
│ └── 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:create-roadmap
|
||||
/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>
|
||||
|
|
@ -0,0 +1,227 @@
|
|||
---
|
||||
name: gsd:insert-phase
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase {decimal_phase}: {description}** — urgent insertion
|
||||
|
||||
`/gsd:plan-phase {decimal_phase}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- Review insertion impact: Check if Phase {next_integer} dependencies still make sense
|
||||
- Review roadmap
|
||||
|
||||
---
|
||||
```
|
||||
</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>
|
||||
|
|
@ -0,0 +1,50 @@
|
|||
---
|
||||
name: gsd:list-phase-assumptions
|
||||
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>
|
||||
|
|
@ -0,0 +1,84 @@
|
|||
---
|
||||
name: gsd:map-codebase
|
||||
description: Analyze codebase with parallel Explore agents to produce .planning/codebase/ documents
|
||||
argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- Write
|
||||
- Task
|
||||
---
|
||||
|
||||
<objective>
|
||||
Analyze existing codebase using parallel Explore agents to produce structured codebase documents.
|
||||
|
||||
This command spawns multiple Explore agents to analyze different aspects of the codebase in parallel, each with fresh context.
|
||||
|
||||
Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@./.claude/get-shit-done/workflows/map-codebase.md
|
||||
@./.claude/get-shit-done/templates/codebase/stack.md
|
||||
@./.claude/get-shit-done/templates/codebase/architecture.md
|
||||
@./.claude/get-shit-done/templates/codebase/structure.md
|
||||
@./.claude/get-shit-done/templates/codebase/conventions.md
|
||||
@./.claude/get-shit-done/templates/codebase/testing.md
|
||||
@./.claude/get-shit-done/templates/codebase/integrations.md
|
||||
@./.claude/get-shit-done/templates/codebase/concerns.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Focus area: $ARGUMENTS (optional - if provided, tells agents to focus on specific subsystem)
|
||||
|
||||
**Load project state if exists:**
|
||||
Check for .planning/STATE.md - loads context if project already initialized
|
||||
|
||||
**This command can run:**
|
||||
- Before /gsd:new-project (brownfield codebases) - creates codebase map first
|
||||
- After /gsd:new-project (greenfield codebases) - updates codebase map as code evolves
|
||||
- Anytime to refresh codebase understanding
|
||||
</context>
|
||||
|
||||
<when_to_use>
|
||||
**Use map-codebase for:**
|
||||
- Brownfield projects before initialization (understand existing code first)
|
||||
- Refreshing codebase map after significant changes
|
||||
- Onboarding to an unfamiliar codebase
|
||||
- Before major refactoring (understand current state)
|
||||
- When STATE.md references outdated codebase info
|
||||
|
||||
**Skip map-codebase for:**
|
||||
- Greenfield projects with no code yet (nothing to map)
|
||||
- Trivial codebases (<5 files)
|
||||
</when_to_use>
|
||||
|
||||
<process>
|
||||
1. Check if .planning/codebase/ already exists (offer to refresh or skip)
|
||||
2. Create .planning/codebase/ directory structure
|
||||
3. Spawn 4 parallel Explore agents to analyze codebase:
|
||||
- Agent 1: Stack + Integrations (technology focus)
|
||||
- Agent 2: Architecture + Structure (organization focus)
|
||||
- Agent 3: Conventions + Testing (quality focus)
|
||||
- Agent 4: Concerns (issues focus)
|
||||
4. Wait for all agents to complete, collect findings
|
||||
5. Write 7 codebase documents using templates:
|
||||
- STACK.md - Languages, frameworks, key dependencies
|
||||
- ARCHITECTURE.md - System design, patterns, data flow
|
||||
- STRUCTURE.md - Directory layout, module organization
|
||||
- CONVENTIONS.md - Code style, naming, patterns
|
||||
- TESTING.md - Test structure, coverage, practices
|
||||
- INTEGRATIONS.md - APIs, databases, external services
|
||||
- CONCERNS.md - Technical debt, risks, issues
|
||||
6. Offer next steps (typically: /gsd:new-project or /gsd:plan-phase)
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] .planning/codebase/ directory created
|
||||
- [ ] All 7 codebase documents written
|
||||
- [ ] Documents follow template structure
|
||||
- [ ] Parallel agents completed without errors
|
||||
- [ ] User knows next steps
|
||||
</success_criteria>
|
||||
|
|
@ -0,0 +1,59 @@
|
|||
---
|
||||
name: gsd:new-milestone
|
||||
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 (per depth setting: quick 3-5, standard 5-8, comprehensive 8-12):
|
||||
- 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)
|
||||
- Phases defined per depth setting (quick: 3-5, standard: 5-8, comprehensive: 8-12)
|
||||
- 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>
|
||||
|
|
@ -0,0 +1,315 @@
|
|||
---
|
||||
name: gsd:new-project
|
||||
description: Initialize a new project with deep context gathering and PROJECT.md
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
- Write
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<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 and config.json.
|
||||
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
|
||||
@./.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>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="setup">
|
||||
|
||||
**MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
|
||||
|
||||
1. **Abort if project exists:**
|
||||
```bash
|
||||
[ -f .planning/PROJECT.md ] && echo "ERROR: Project already initialized. Use /gsd:progress" && exit 1
|
||||
```
|
||||
|
||||
2. **Initialize git repo in THIS directory** (required even if inside a parent repo):
|
||||
```bash
|
||||
# Check if THIS directory is already a git repo root (handles .git file for worktrees too)
|
||||
if [ -d .git ] || [ -f .git ]; then
|
||||
echo "Git repo exists in current directory"
|
||||
else
|
||||
git init
|
||||
echo "Initialized new git repo"
|
||||
fi
|
||||
```
|
||||
|
||||
3. **Detect existing code (brownfield detection):**
|
||||
```bash
|
||||
# Check for existing code files
|
||||
CODE_FILES=$(find . -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.swift" -o -name "*.java" 2>/dev/null | grep -v node_modules | grep -v .git | head -20)
|
||||
HAS_PACKAGE=$([ -f package.json ] || [ -f requirements.txt ] || [ -f Cargo.toml ] || [ -f go.mod ] || [ -f Package.swift ] && echo "yes")
|
||||
HAS_CODEBASE_MAP=$([ -d .planning/codebase ] && echo "yes")
|
||||
```
|
||||
|
||||
**You MUST run all bash commands above using the Bash tool before proceeding.**
|
||||
|
||||
</step>
|
||||
|
||||
<step name="brownfield_offer">
|
||||
|
||||
**If existing code detected and .planning/codebase/ doesn't exist:**
|
||||
|
||||
Check the results from setup step:
|
||||
- If `CODE_FILES` is non-empty OR `HAS_PACKAGE` is "yes"
|
||||
- AND `HAS_CODEBASE_MAP` is NOT "yes"
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Existing Code"
|
||||
- question: "I detected existing code in this directory. Would you like to map the codebase first?"
|
||||
- options:
|
||||
- "Map codebase first" — Run /gsd:map-codebase to understand existing architecture (Recommended)
|
||||
- "Skip mapping" — Proceed with project initialization
|
||||
|
||||
**If "Map codebase first":**
|
||||
```
|
||||
Run `/gsd:map-codebase` first, then return to `/gsd:new-project`
|
||||
```
|
||||
Exit command.
|
||||
|
||||
**If "Skip mapping":** Continue to question step.
|
||||
|
||||
**If no existing code detected OR codebase already mapped:** Continue to question step.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="question">
|
||||
|
||||
**1. Open (FREEFORM — do NOT use AskUserQuestion):**
|
||||
|
||||
Ask inline: "What do you want to build?"
|
||||
|
||||
Wait for their freeform response. This gives you the context needed to ask intelligent follow-up questions.
|
||||
|
||||
**2. Follow the thread (NOW use AskUserQuestion):**
|
||||
|
||||
Based on their response, use AskUserQuestion with options that probe what they mentioned:
|
||||
- header: "[Topic they mentioned]"
|
||||
- question: "You mentioned [X] — what would that look like?"
|
||||
- options: 2-3 interpretations + "Something else"
|
||||
|
||||
**3. Sharpen the core:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Core"
|
||||
- question: "If you could only nail one thing, what would it be?"
|
||||
- options: Key aspects they've mentioned + "All equally important" + "Something else"
|
||||
|
||||
**4. Find boundaries:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Scope"
|
||||
- question: "What's explicitly NOT in v1?"
|
||||
- options: Things that might be tempting + "Nothing specific" + "Let me list them"
|
||||
|
||||
**5. Ground in reality:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Constraints"
|
||||
- question: "Any hard constraints?"
|
||||
- options: Relevant constraint types + "None" + "Yes, let me explain"
|
||||
|
||||
**6. Decision gate:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Ready?"
|
||||
- question: "Ready to create PROJECT.md, or explore more?"
|
||||
- options (ALL THREE REQUIRED):
|
||||
- "Create PROJECT.md" — Finalize and continue
|
||||
- "Ask more questions" — I'll dig deeper
|
||||
- "Let me add context" — You have more to share
|
||||
|
||||
If "Ask more questions" → check coverage gaps from `questioning.md` → return to step 2.
|
||||
If "Let me add context" → receive input via their response → return to step 2.
|
||||
Loop until "Create PROJECT.md" selected.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="project">
|
||||
|
||||
Synthesize all context into `.planning/PROJECT.md` using the template from `templates/project.md`.
|
||||
|
||||
**For greenfield projects:**
|
||||
|
||||
Initialize requirements as hypotheses:
|
||||
|
||||
```markdown
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
|
||||
(None yet — ship to validate)
|
||||
|
||||
### Active
|
||||
|
||||
- [ ] [Requirement 1]
|
||||
- [ ] [Requirement 2]
|
||||
- [ ] [Requirement 3]
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- [Exclusion 1] — [why]
|
||||
- [Exclusion 2] — [why]
|
||||
```
|
||||
|
||||
All Active requirements are hypotheses until shipped and validated.
|
||||
|
||||
**For brownfield projects (codebase map exists):**
|
||||
|
||||
Infer Validated requirements from existing code:
|
||||
|
||||
1. Read `.planning/codebase/ARCHITECTURE.md` and `STACK.md`
|
||||
2. Identify what the codebase already does
|
||||
3. These become the initial Validated set
|
||||
|
||||
```markdown
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
|
||||
- ✓ [Existing capability 1] — existing
|
||||
- ✓ [Existing capability 2] — existing
|
||||
- ✓ [Existing capability 3] — existing
|
||||
|
||||
### Active
|
||||
|
||||
- [ ] [New requirement 1]
|
||||
- [ ] [New requirement 2]
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- [Exclusion 1] — [why]
|
||||
```
|
||||
|
||||
**Key Decisions:**
|
||||
|
||||
Initialize with any decisions made during questioning:
|
||||
|
||||
```markdown
|
||||
## Key Decisions
|
||||
|
||||
| Decision | Rationale | Outcome |
|
||||
|----------|-----------|---------|
|
||||
| [Choice from questioning] | [Why] | — Pending |
|
||||
```
|
||||
|
||||
**Last updated footer:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
*Last updated: [date] after initialization*
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
</step>
|
||||
|
||||
<step name="depth">
|
||||
|
||||
Ask planning depth preference:
|
||||
|
||||
Use AskUserQuestion:
|
||||
|
||||
- header: "Depth"
|
||||
- question: "How thorough should planning be?"
|
||||
- options:
|
||||
- "Quick" — Ship fast, minimal phases/plans (3-5 phases, 1-3 plans each)
|
||||
- "Standard" — Balanced scope and speed (5-8 phases, 3-5 plans each)
|
||||
- "Comprehensive" — Thorough coverage, more phases/plans (8-12 phases, 5-10 plans each)
|
||||
|
||||
**Depth controls compression tolerance, not artificial inflation.** All depths use 2-3 tasks per plan. Comprehensive means "don't compress complex work"—it doesn't mean "pad simple work to hit a number."
|
||||
|
||||
Create `.planning/config.json` with chosen mode and depth using `templates/config.json` structure.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="commit">
|
||||
|
||||
```bash
|
||||
git add .planning/PROJECT.md .planning/config.json
|
||||
git commit -m "$(cat <<'EOF'
|
||||
docs: initialize [project-name]
|
||||
|
||||
[One-liner from PROJECT.md]
|
||||
|
||||
Creates PROJECT.md with requirements and constraints.
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="done">
|
||||
|
||||
Present completion with next steps (see ./.claude/get-shit-done/references/continuation-format.md):
|
||||
|
||||
```
|
||||
Project initialized:
|
||||
|
||||
- Project: .planning/PROJECT.md
|
||||
- Config: .planning/config.json (mode: [chosen mode])
|
||||
[If .planning/codebase/ exists:] - Codebase: .planning/codebase/ (7 documents)
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**[Project Name]** — create roadmap
|
||||
|
||||
`/gsd:create-roadmap`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<output>
|
||||
|
||||
- `.planning/PROJECT.md`
|
||||
- `.planning/config.json`
|
||||
|
||||
</output>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- [ ] Deep questioning completed (not rushed)
|
||||
- [ ] PROJECT.md captures full context with evolutionary structure
|
||||
- [ ] Requirements initialized as hypotheses (greenfield) or with inferred Validated (brownfield)
|
||||
- [ ] Key Decisions table initialized
|
||||
- [ ] config.json has workflow mode
|
||||
- [ ] All committed to git
|
||||
|
||||
</success_criteria>
|
||||
|
|
@ -0,0 +1,123 @@
|
|||
---
|
||||
name: gsd:pause-work
|
||||
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
|
||||
</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>
|
||||
```
|
||||
|
|
@ -0,0 +1,205 @@
|
|||
---
|
||||
name: gsd:plan-fix
|
||||
description: Plan fixes for UAT issues from verify-work
|
||||
argument-hint: "[plan, e.g., '04-02']"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
- Write
|
||||
- Glob
|
||||
- Grep
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<objective>
|
||||
Create FIX.md plan from UAT issues found during verify-work.
|
||||
|
||||
Purpose: Plan fixes for issues logged in phase-scoped ISSUES.md files.
|
||||
Output: {plan}-FIX.md in the phase directory, ready for execution.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@./.claude/get-shit-done/references/plan-format.md
|
||||
@./.claude/get-shit-done/references/checkpoints.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Plan number: $ARGUMENTS (required - e.g., "04-02" or "09-01")
|
||||
|
||||
**Load project state:**
|
||||
@.planning/STATE.md
|
||||
@.planning/ROADMAP.md
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="parse">
|
||||
**Parse plan argument:**
|
||||
|
||||
$ARGUMENTS should be a plan number like "04-02" or "09-01".
|
||||
Extract phase number (XX) and plan number (NN).
|
||||
|
||||
If no argument provided:
|
||||
```
|
||||
Error: Plan number required.
|
||||
|
||||
Usage: /gsd:plan-fix 04-02
|
||||
|
||||
This creates a fix plan from .planning/phases/XX-name/04-02-ISSUES.md
|
||||
```
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="find">
|
||||
**Find ISSUES.md file:**
|
||||
|
||||
Search for matching ISSUES.md:
|
||||
```bash
|
||||
ls .planning/phases/*/{plan}-ISSUES.md 2>/dev/null
|
||||
```
|
||||
|
||||
If not found:
|
||||
```
|
||||
No ISSUES.md found for plan {plan}.
|
||||
|
||||
ISSUES.md files are created by /gsd:verify-work when UAT finds issues.
|
||||
If no issues were found during testing, no fix plan is needed.
|
||||
```
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="read">
|
||||
**Read issues:**
|
||||
|
||||
Read the ISSUES.md file.
|
||||
Parse each issue:
|
||||
- ID (UAT-XXX)
|
||||
- Title
|
||||
- Severity (critical/major/minor)
|
||||
- Description/steps to reproduce
|
||||
- Acceptance criteria
|
||||
|
||||
Count total issues by severity.
|
||||
</step>
|
||||
|
||||
<step name="plan">
|
||||
**Create fix tasks:**
|
||||
|
||||
For each issue (or logical group):
|
||||
- Create one task per issue OR
|
||||
- Group related minor issues into single task
|
||||
|
||||
Task structure:
|
||||
```xml
|
||||
<task type="auto">
|
||||
<name>Fix UAT-001: [issue title]</name>
|
||||
<files>[affected files from issue]</files>
|
||||
<action>
|
||||
[What to fix based on issue description]
|
||||
[Reference original acceptance criteria]
|
||||
</action>
|
||||
<verify>[Test that issue is resolved]</verify>
|
||||
<done>[Issue acceptance criteria met]</done>
|
||||
</task>
|
||||
```
|
||||
|
||||
Prioritize: critical → major → minor
|
||||
</step>
|
||||
|
||||
<step name="write">
|
||||
**Write FIX.md:**
|
||||
|
||||
Create `.planning/phases/XX-name/{plan}-FIX.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
phase: XX-name
|
||||
plan: {plan}-FIX
|
||||
type: fix
|
||||
---
|
||||
|
||||
<objective>
|
||||
Fix {N} UAT issues from plan {plan}.
|
||||
|
||||
Source: {plan}-ISSUES.md
|
||||
Priority: {critical count} critical, {major count} major, {minor count} minor
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@./.claude/get-shit-done/workflows/execute-phase.md
|
||||
@./.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/STATE.md
|
||||
@.planning/ROADMAP.md
|
||||
|
||||
**Issues being fixed:**
|
||||
@.planning/phases/XX-name/{plan}-ISSUES.md
|
||||
|
||||
**Original plan for reference:**
|
||||
@.planning/phases/XX-name/{plan}-PLAN.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
[Generated fix tasks]
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
Before declaring plan complete:
|
||||
- [ ] All critical issues fixed
|
||||
- [ ] All major issues fixed
|
||||
- [ ] Minor issues fixed or documented as deferred
|
||||
- [ ] Original acceptance criteria from issues met
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- All UAT issues from {plan}-ISSUES.md addressed
|
||||
- Tests pass
|
||||
- Ready for re-verification
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/XX-name/{plan}-FIX-SUMMARY.md`
|
||||
</output>
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="offer">
|
||||
**Offer execution:**
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ✓ Fix Plan Created
|
||||
|
||||
**{plan}-FIX.md** — {N} issues to fix
|
||||
|
||||
| Severity | Count |
|
||||
|----------|-------|
|
||||
| Critical | {n} |
|
||||
| Major | {n} |
|
||||
| Minor | {n} |
|
||||
|
||||
---
|
||||
|
||||
Would you like to:
|
||||
1. Execute the fix plan now
|
||||
2. Review the plan first
|
||||
3. Modify the plan before executing
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
Use AskUserQuestion to get response.
|
||||
If execute: `/gsd:execute-plan .planning/phases/XX-name/{plan}-FIX.md`
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] ISSUES.md found and parsed
|
||||
- [ ] Fix tasks created for each issue
|
||||
- [ ] FIX.md written with proper structure
|
||||
- [ ] User offered to execute or review
|
||||
</success_criteria>
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
---
|
||||
name: gsd:plan-phase
|
||||
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/tdd.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
|
||||
|
||||
**Load phase context if exists (created by /gsd:discuss-phase):**
|
||||
Check for and read `.planning/phases/XX-name/{phase}-CONTEXT.md` - contains research findings, clarifications, and decisions from phase discussion.
|
||||
|
||||
**Load codebase context if exists:**
|
||||
Check for `.planning/codebase/` and load relevant documents based on phase type.
|
||||
</context>
|
||||
|
||||
<process>
|
||||
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>
|
||||
|
|
@ -0,0 +1,317 @@
|
|||
---
|
||||
name: gsd:progress
|
||||
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>
|
||||
|
||||
|
||||
<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 current state (What This Is, Core Value, Requirements)
|
||||
</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 based on verified counts.**
|
||||
|
||||
**Step 1: Count plans, summaries, and issues in current phase**
|
||||
|
||||
List files in the current phase directory:
|
||||
|
||||
```bash
|
||||
ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l
|
||||
ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
|
||||
ls -1 .planning/phases/[current-phase-dir]/*-ISSUES.md 2>/dev/null | wc -l
|
||||
ls -1 .planning/phases/[current-phase-dir]/*-FIX.md 2>/dev/null | wc -l
|
||||
ls -1 .planning/phases/[current-phase-dir]/*-FIX-SUMMARY.md 2>/dev/null | wc -l
|
||||
```
|
||||
|
||||
State: "This phase has {X} plans, {Y} summaries, {Z} issues files, {W} fix plans."
|
||||
|
||||
**Step 1.5: Check for unaddressed UAT issues**
|
||||
|
||||
For each *-ISSUES.md file, check if matching *-FIX.md exists.
|
||||
For each *-FIX.md file, check if matching *-FIX-SUMMARY.md exists.
|
||||
|
||||
Track:
|
||||
- `issues_without_fix`: ISSUES.md files without FIX.md
|
||||
- `fixes_without_summary`: FIX.md files without FIX-SUMMARY.md
|
||||
|
||||
**Step 2: Route based on counts**
|
||||
|
||||
| Condition | Meaning | Action |
|
||||
|-----------|---------|--------|
|
||||
| fixes_without_summary > 0 | Unexecuted fix plans exist | Go to **Route A** (with FIX.md) |
|
||||
| issues_without_fix > 0 | UAT issues need fix plans | Go to **Route E** |
|
||||
| summaries < plans | Unexecuted plans exist | Go to **Route A** |
|
||||
| summaries = plans AND plans > 0 | Phase complete | Go to Step 3 |
|
||||
| plans = 0 | Phase not yet planned | Go to **Route B** |
|
||||
|
||||
---
|
||||
|
||||
**Route A: Unexecuted plan exists**
|
||||
|
||||
Find the first PLAN.md without matching SUMMARY.md.
|
||||
Read its `<objective>` section.
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md]
|
||||
|
||||
`/gsd:execute-plan [full-path-to-PLAN.md]`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Route B: Phase needs planning**
|
||||
|
||||
Check if `{phase}-CONTEXT.md` exists in phase directory.
|
||||
|
||||
**If CONTEXT.md exists:**
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase {N}: {Name}** — {Goal from ROADMAP.md}
|
||||
<sub>✓ Context gathered, ready to plan</sub>
|
||||
|
||||
`/gsd:plan-phase {phase-number}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
**If CONTEXT.md does NOT exist:**
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase {N}: {Name}** — {Goal from ROADMAP.md}
|
||||
|
||||
`/gsd:plan-phase {phase}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:discuss-phase {phase}` — gather context first
|
||||
- `/gsd:research-phase {phase}` — investigate unknowns
|
||||
- `/gsd:list-phase-assumptions {phase}` — see Claude's assumptions
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Route E: UAT issues need fix plans**
|
||||
|
||||
ISSUES.md exists without matching FIX.md. User needs to plan fixes.
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ⚠ UAT Issues Found
|
||||
|
||||
**{plan}-ISSUES.md** has {N} issues without a fix plan.
|
||||
|
||||
`/gsd:plan-fix {plan}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:execute-plan [path]` — continue with other work first
|
||||
- `/gsd:verify-work {phase}` — run more UAT testing
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Step 3: Check milestone status (only when phase complete)**
|
||||
|
||||
Read ROADMAP.md and identify:
|
||||
1. Current phase number
|
||||
2. All phase numbers in the current milestone section
|
||||
|
||||
Count total phases and identify the highest phase number.
|
||||
|
||||
State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."
|
||||
|
||||
**Route based on milestone status:**
|
||||
|
||||
| Condition | Meaning | Action |
|
||||
|-----------|---------|--------|
|
||||
| current phase < highest phase | More phases remain | Go to **Route C** |
|
||||
| current phase = highest phase | Milestone complete | Go to **Route D** |
|
||||
|
||||
---
|
||||
|
||||
**Route C: Phase complete, more phases remain**
|
||||
|
||||
Read ROADMAP.md to get the next phase's name and goal.
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ✓ Phase {Z} Complete
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
|
||||
|
||||
`/gsd:plan-phase {Z+1}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:verify-work {Z}` — user acceptance test before continuing
|
||||
- `/gsd:discuss-phase {Z+1}` — gather context first
|
||||
- `/gsd:research-phase {Z+1}` — investigate unknowns
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Route D: Milestone complete**
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## 🎉 Milestone Complete
|
||||
|
||||
All {N} phases finished!
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Complete Milestone** — archive and prepare for next
|
||||
|
||||
`/gsd:complete-milestone`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:verify-work` — user acceptance test before completing 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>
|
||||
|
|
@ -0,0 +1,338 @@
|
|||
---
|
||||
name: gsd:remove-phase
|
||||
description: Remove a future phase from roadmap and renumber subsequent phases
|
||||
argument-hint: <phase-number>
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Glob
|
||||
---
|
||||
|
||||
<objective>
|
||||
Remove an unstarted future phase from the roadmap and renumber all subsequent phases to maintain a clean, linear sequence.
|
||||
|
||||
Purpose: Clean removal of work you've decided not to do, without polluting context with cancelled/deferred markers.
|
||||
Output: Phase deleted, all subsequent phases renumbered, git commit as historical record.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
</execution_context>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="parse_arguments">
|
||||
Parse the command arguments:
|
||||
- Argument is the phase number to remove (integer or decimal)
|
||||
- Example: `/gsd:remove-phase 17` → phase = 17
|
||||
- Example: `/gsd:remove-phase 16.1` → phase = 16.1
|
||||
|
||||
If no argument provided:
|
||||
|
||||
```
|
||||
ERROR: Phase number required
|
||||
Usage: /gsd:remove-phase <phase-number>
|
||||
Example: /gsd:remove-phase 17
|
||||
```
|
||||
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="load_state">
|
||||
Load project state:
|
||||
|
||||
```bash
|
||||
cat .planning/STATE.md 2>/dev/null
|
||||
cat .planning/ROADMAP.md 2>/dev/null
|
||||
```
|
||||
|
||||
Parse current phase number from STATE.md "Current Position" section.
|
||||
</step>
|
||||
|
||||
<step name="validate_phase_exists">
|
||||
Verify the target phase exists in ROADMAP.md:
|
||||
|
||||
1. Search for `### Phase {target}:` heading
|
||||
2. If not found:
|
||||
|
||||
```
|
||||
ERROR: Phase {target} not found in roadmap
|
||||
Available phases: [list phase numbers]
|
||||
```
|
||||
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="validate_future_phase">
|
||||
Verify the phase is a future phase (not started):
|
||||
|
||||
1. Compare target phase to current phase from STATE.md
|
||||
2. Target must be > current phase number
|
||||
|
||||
If target <= current phase:
|
||||
|
||||
```
|
||||
ERROR: Cannot remove Phase {target}
|
||||
|
||||
Only future phases can be removed:
|
||||
- Current phase: {current}
|
||||
- Phase {target} is current or completed
|
||||
|
||||
To abandon current work, use /gsd:pause-work instead.
|
||||
```
|
||||
|
||||
Exit.
|
||||
|
||||
3. Check for SUMMARY.md files in phase directory:
|
||||
|
||||
```bash
|
||||
ls .planning/phases/{target}-*/*-SUMMARY.md 2>/dev/null
|
||||
```
|
||||
|
||||
If any SUMMARY.md files exist:
|
||||
|
||||
```
|
||||
ERROR: Phase {target} has completed work
|
||||
|
||||
Found executed plans:
|
||||
- {list of SUMMARY.md files}
|
||||
|
||||
Cannot remove phases with completed work.
|
||||
```
|
||||
|
||||
Exit.
|
||||
</step>
|
||||
|
||||
<step name="gather_phase_info">
|
||||
Collect information about the phase being removed:
|
||||
|
||||
1. Extract phase name from ROADMAP.md heading: `### Phase {target}: {Name}`
|
||||
2. Find phase directory: `.planning/phases/{target}-{slug}/`
|
||||
3. Find all subsequent phases (integer and decimal) that need renumbering
|
||||
|
||||
**Subsequent phase detection:**
|
||||
|
||||
For integer phase removal (e.g., 17):
|
||||
- Find all phases > 17 (integers: 18, 19, 20...)
|
||||
- Find all decimal phases >= 17.0 and < 18.0 (17.1, 17.2...) → these become 16.x
|
||||
- Find all decimal phases for subsequent integers (18.1, 19.1...) → renumber with their parent
|
||||
|
||||
For decimal phase removal (e.g., 17.1):
|
||||
- Find all decimal phases > 17.1 and < 18 (17.2, 17.3...) → renumber down
|
||||
- Integer phases unchanged
|
||||
|
||||
List all phases that will be renumbered.
|
||||
</step>
|
||||
|
||||
<step name="confirm_removal">
|
||||
Present removal summary and confirm:
|
||||
|
||||
```
|
||||
Removing Phase {target}: {Name}
|
||||
|
||||
This will:
|
||||
- Delete: .planning/phases/{target}-{slug}/
|
||||
- Renumber {N} subsequent phases:
|
||||
- Phase 18 → Phase 17
|
||||
- Phase 18.1 → Phase 17.1
|
||||
- Phase 19 → Phase 18
|
||||
[etc.]
|
||||
|
||||
Proceed? (y/n)
|
||||
```
|
||||
|
||||
Wait for confirmation.
|
||||
</step>
|
||||
|
||||
<step name="delete_phase_directory">
|
||||
Delete the target phase directory if it exists:
|
||||
|
||||
```bash
|
||||
if [ -d ".planning/phases/{target}-{slug}" ]; then
|
||||
rm -rf ".planning/phases/{target}-{slug}"
|
||||
echo "Deleted: .planning/phases/{target}-{slug}/"
|
||||
fi
|
||||
```
|
||||
|
||||
If directory doesn't exist, note: "No directory to delete (phase not yet created)"
|
||||
</step>
|
||||
|
||||
<step name="renumber_directories">
|
||||
Rename all subsequent phase directories:
|
||||
|
||||
For each phase directory that needs renumbering (in reverse order to avoid conflicts):
|
||||
|
||||
```bash
|
||||
# Example: renaming 18-dashboard to 17-dashboard
|
||||
mv ".planning/phases/18-dashboard" ".planning/phases/17-dashboard"
|
||||
```
|
||||
|
||||
Process in descending order (20→19, then 19→18, then 18→17) to avoid overwriting.
|
||||
|
||||
Also rename decimal phase directories:
|
||||
- `17.1-fix-bug` → `16.1-fix-bug` (if removing integer 17)
|
||||
- `17.2-hotfix` → `17.1-hotfix` (if removing decimal 17.1)
|
||||
</step>
|
||||
|
||||
<step name="rename_files_in_directories">
|
||||
Rename plan files inside renumbered directories:
|
||||
|
||||
For each renumbered directory, rename files that contain the phase number:
|
||||
|
||||
```bash
|
||||
# Inside 17-dashboard (was 18-dashboard):
|
||||
mv "18-01-PLAN.md" "17-01-PLAN.md"
|
||||
mv "18-02-PLAN.md" "17-02-PLAN.md"
|
||||
mv "18-01-SUMMARY.md" "17-01-SUMMARY.md" # if exists
|
||||
# etc.
|
||||
```
|
||||
|
||||
Also handle CONTEXT.md and DISCOVERY.md (these don't have phase prefixes, so no rename needed).
|
||||
</step>
|
||||
|
||||
<step name="update_roadmap">
|
||||
Update ROADMAP.md:
|
||||
|
||||
1. **Remove the phase section entirely:**
|
||||
- Delete from `### Phase {target}:` to the next phase heading (or section end)
|
||||
|
||||
2. **Remove from phase list:**
|
||||
- Delete line `- [ ] **Phase {target}: {Name}**` or similar
|
||||
|
||||
3. **Remove from Progress table:**
|
||||
- Delete the row for Phase {target}
|
||||
|
||||
4. **Renumber all subsequent phases:**
|
||||
- `### Phase 18:` → `### Phase 17:`
|
||||
- `- [ ] **Phase 18:` → `- [ ] **Phase 17:`
|
||||
- Table rows: `| 18. Dashboard |` → `| 17. Dashboard |`
|
||||
- Plan references: `18-01:` → `17-01:`
|
||||
|
||||
5. **Update dependency references:**
|
||||
- `**Depends on:** Phase 18` → `**Depends on:** Phase 17`
|
||||
- For the phase that depended on the removed phase:
|
||||
- `**Depends on:** Phase 17` (removed) → `**Depends on:** Phase 16`
|
||||
|
||||
6. **Renumber decimal phases:**
|
||||
- `### Phase 17.1:` → `### Phase 16.1:` (if integer 17 removed)
|
||||
- Update all references consistently
|
||||
|
||||
Write updated ROADMAP.md.
|
||||
</step>
|
||||
|
||||
<step name="update_state">
|
||||
Update STATE.md:
|
||||
|
||||
1. **Update total phase count:**
|
||||
- `Phase: 16 of 20` → `Phase: 16 of 19`
|
||||
|
||||
2. **Recalculate progress percentage:**
|
||||
- New percentage based on completed plans / new total plans
|
||||
|
||||
Do NOT add a "Roadmap Evolution" note - the git commit is the record.
|
||||
|
||||
Write updated STATE.md.
|
||||
</step>
|
||||
|
||||
<step name="update_file_contents">
|
||||
Search for and update phase references inside plan files:
|
||||
|
||||
```bash
|
||||
# Find files that reference the old phase numbers
|
||||
grep -r "Phase 18" .planning/phases/17-*/ 2>/dev/null
|
||||
grep -r "Phase 19" .planning/phases/18-*/ 2>/dev/null
|
||||
# etc.
|
||||
```
|
||||
|
||||
Update any internal references to reflect new numbering.
|
||||
</step>
|
||||
|
||||
<step name="commit">
|
||||
Stage and commit the removal:
|
||||
|
||||
```bash
|
||||
git add .planning/
|
||||
git commit -m "chore: remove phase {target} ({original-phase-name})"
|
||||
```
|
||||
|
||||
The commit message preserves the historical record of what was removed.
|
||||
</step>
|
||||
|
||||
<step name="completion">
|
||||
Present completion summary:
|
||||
|
||||
```
|
||||
Phase {target} ({original-name}) removed.
|
||||
|
||||
Changes:
|
||||
- Deleted: .planning/phases/{target}-{slug}/
|
||||
- Renumbered: Phases {first-renumbered}-{last-old} → {first-renumbered-1}-{last-new}
|
||||
- Updated: ROADMAP.md, STATE.md
|
||||
- Committed: chore: remove phase {target} ({original-name})
|
||||
|
||||
Current roadmap: {total-remaining} phases
|
||||
Current position: Phase {current} of {new-total}
|
||||
|
||||
---
|
||||
|
||||
## What's Next
|
||||
|
||||
Would you like to:
|
||||
- `/gsd:progress` — see updated roadmap status
|
||||
- Continue with current phase
|
||||
- Review roadmap
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<anti_patterns>
|
||||
|
||||
- Don't remove completed phases (have SUMMARY.md files)
|
||||
- Don't remove current or past phases
|
||||
- Don't leave gaps in numbering - always renumber
|
||||
- Don't add "removed phase" notes to STATE.md - git commit is the record
|
||||
- Don't ask about each decimal phase - just renumber them
|
||||
- Don't modify completed phase directories
|
||||
</anti_patterns>
|
||||
|
||||
<edge_cases>
|
||||
|
||||
**Removing a decimal phase (e.g., 17.1):**
|
||||
- Only affects other decimals in same series (17.2 → 17.1, 17.3 → 17.2)
|
||||
- Integer phases unchanged
|
||||
- Simpler operation
|
||||
|
||||
**No subsequent phases to renumber:**
|
||||
- Removing the last phase (e.g., Phase 20 when that's the end)
|
||||
- Just delete and update ROADMAP.md, no renumbering needed
|
||||
|
||||
**Phase directory doesn't exist:**
|
||||
- Phase may be in ROADMAP.md but directory not created yet
|
||||
- Skip directory deletion, proceed with ROADMAP.md updates
|
||||
|
||||
**Decimal phases under removed integer:**
|
||||
- Removing Phase 17 when 17.1, 17.2 exist
|
||||
- 17.1 → 16.1, 17.2 → 16.2
|
||||
- They maintain their position in execution order (after current last integer)
|
||||
|
||||
</edge_cases>
|
||||
|
||||
<success_criteria>
|
||||
Phase removal is complete when:
|
||||
|
||||
- [ ] Target phase validated as future/unstarted
|
||||
- [ ] Phase directory deleted (if existed)
|
||||
- [ ] All subsequent phase directories renumbered
|
||||
- [ ] Files inside directories renamed ({old}-01-PLAN.md → {new}-01-PLAN.md)
|
||||
- [ ] ROADMAP.md updated (section removed, all references renumbered)
|
||||
- [ ] STATE.md updated (phase count, progress percentage)
|
||||
- [ ] Dependency references updated in subsequent phases
|
||||
- [ ] Changes committed with descriptive message
|
||||
- [ ] No gaps in phase numbering
|
||||
- [ ] User informed of changes
|
||||
</success_criteria>
|
||||
|
|
@ -0,0 +1,91 @@
|
|||
---
|
||||
name: gsd:research-phase
|
||||
description: Research how to implement a phase before planning
|
||||
argument-hint: "[phase]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- Write
|
||||
- WebFetch
|
||||
- WebSearch
|
||||
- mcp__context7__*
|
||||
---
|
||||
|
||||
<objective>
|
||||
Comprehensive research on HOW to implement a phase before planning.
|
||||
|
||||
This is for niche/complex domains where Claude's training data is sparse or outdated. Research discovers:
|
||||
- What libraries exist for this problem
|
||||
- What architecture patterns experts use
|
||||
- What the standard stack looks like
|
||||
- What problems people commonly hit
|
||||
- What NOT to hand-roll (use existing solutions)
|
||||
|
||||
Output: RESEARCH.md with ecosystem knowledge that informs quality planning.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@./.claude/get-shit-done/workflows/research-phase.md
|
||||
@./.claude/get-shit-done/templates/research.md
|
||||
@./.claude/get-shit-done/references/research-pitfalls.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Phase number: $ARGUMENTS (required)
|
||||
|
||||
**Load project state:**
|
||||
@.planning/STATE.md
|
||||
|
||||
**Load roadmap:**
|
||||
@.planning/ROADMAP.md
|
||||
|
||||
**Load phase context if exists:**
|
||||
Check for `.planning/phases/XX-name/{phase}-CONTEXT.md` - bonus context from discuss-phase.
|
||||
</context>
|
||||
|
||||
<process>
|
||||
1. Validate phase number argument (error if missing or invalid)
|
||||
2. Check if phase exists in roadmap - extract phase description
|
||||
3. Check if RESEARCH.md already exists (offer to update or use existing)
|
||||
4. Load CONTEXT.md if it exists (bonus context for research direction)
|
||||
5. Follow research-phase.md workflow:
|
||||
- Analyze phase to identify knowledge gaps
|
||||
- Determine research domains (architecture, ecosystem, patterns, pitfalls)
|
||||
- Execute comprehensive research via Context7, official docs, WebSearch
|
||||
- Cross-verify all findings
|
||||
- Create RESEARCH.md with actionable ecosystem knowledge
|
||||
6. Offer next steps (plan the phase)
|
||||
</process>
|
||||
|
||||
<when_to_use>
|
||||
**Use research-phase for:**
|
||||
- 3D graphics (Three.js, WebGL, procedural generation)
|
||||
- Game development (physics, collision, AI, procedural content)
|
||||
- Audio/music (Web Audio API, DSP, synthesis)
|
||||
- Shaders (GLSL, Metal, ISF)
|
||||
- ML/AI integration (model serving, inference, pipelines)
|
||||
- Real-time systems (WebSockets, WebRTC, sync)
|
||||
- Specialized frameworks with active ecosystems
|
||||
- Any domain where "how do experts do this" matters
|
||||
|
||||
**Skip research-phase for:**
|
||||
- Standard web dev (auth, CRUD, REST APIs)
|
||||
- Well-known patterns (forms, validation, testing)
|
||||
- Simple integrations (Stripe, SendGrid with clear docs)
|
||||
- Commodity features Claude handles well
|
||||
</when_to_use>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Phase validated against roadmap
|
||||
- [ ] Domain/ecosystem identified from phase description
|
||||
- [ ] Comprehensive research executed (Context7 + official docs + WebSearch)
|
||||
- [ ] All WebSearch findings cross-verified with authoritative sources
|
||||
- [ ] RESEARCH.md created with ecosystem knowledge
|
||||
- [ ] Standard stack/libraries identified
|
||||
- [ ] Architecture patterns documented
|
||||
- [ ] Common pitfalls catalogued
|
||||
- [ ] What NOT to hand-roll is clear
|
||||
- [ ] User knows next steps (plan phase)
|
||||
</success_criteria>
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
---
|
||||
name: gsd:resume-work
|
||||
description: Resume work from previous session with full context restoration
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
- Write
|
||||
- AskUserQuestion
|
||||
- SlashCommand
|
||||
---
|
||||
|
||||
<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>
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
---
|
||||
name: gsd:verify-work
|
||||
description: Guide manual user acceptance testing of recently built features
|
||||
argument-hint: "[optional: phase or plan number, e.g., '4' or '04-02']"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- Edit
|
||||
- Write
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<objective>
|
||||
Guide the user through manual acceptance testing of recently built features.
|
||||
|
||||
Purpose: Validate that what Claude thinks was built actually works from the user's perspective. The USER performs all testing — Claude generates the test checklist, guides the process, and captures issues.
|
||||
|
||||
Output: Validation of features, any issues logged to phase-scoped ISSUES.md
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@./.claude/get-shit-done/workflows/verify-work.md
|
||||
@./.claude/get-shit-done/templates/uat-issues.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Scope: $ARGUMENTS (optional)
|
||||
- If provided: Test specific phase or plan (e.g., "4" or "04-02")
|
||||
- If not provided: Test most recently completed plan
|
||||
|
||||
**Load project state:**
|
||||
@.planning/STATE.md
|
||||
|
||||
**Load roadmap:**
|
||||
@.planning/ROADMAP.md
|
||||
</context>
|
||||
|
||||
<process>
|
||||
1. Validate arguments (if provided, parse as phase or plan number)
|
||||
2. Find relevant SUMMARY.md (specified or most recent)
|
||||
3. Follow verify-work.md workflow:
|
||||
- Extract testable deliverables
|
||||
- Generate test checklist
|
||||
- Guide through each test via AskUserQuestion
|
||||
- Collect and categorize issues
|
||||
- Log issues to `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md`
|
||||
- Present summary with verdict
|
||||
4. Offer next steps based on results:
|
||||
- If all passed: Continue to next phase
|
||||
- If issues found: `/gsd:plan-fix {phase} {plan}` to create fix plan
|
||||
</process>
|
||||
|
||||
<anti_patterns>
|
||||
- Don't run automated tests (that's for CI/test suites)
|
||||
- Don't make assumptions about test results — USER reports outcomes
|
||||
- Don't skip the guidance — walk through each test
|
||||
- Don't dismiss minor issues — log everything user reports
|
||||
- Don't fix issues during testing — capture for later
|
||||
</anti_patterns>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Test scope identified from SUMMARY.md
|
||||
- [ ] Checklist generated based on deliverables
|
||||
- [ ] User guided through each test
|
||||
- [ ] All test results captured (pass/fail/partial/skip)
|
||||
- [ ] Any issues logged to phase-scoped ISSUES.md (not global)
|
||||
- [ ] Summary presented with verdict
|
||||
- [ ] User knows next steps based on results
|
||||
</success_criteria>
|
||||
|
|
@ -0,0 +1,287 @@
|
|||
<overview>
|
||||
Plans execute autonomously. Checkpoints formalize 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>
|
||||
|
||||
## checkpoint:human-verify (90% of checkpoints)
|
||||
|
||||
**When:** Claude completed automated work, human confirms it works correctly.
|
||||
|
||||
**Use for:** Visual UI checks, interactive flows, functional verification, audio/video quality, animation smoothness, accessibility testing.
|
||||
|
||||
**Structure:**
|
||||
```xml
|
||||
<task type="checkpoint:human-verify" gate="blocking">
|
||||
<what-built>[What Claude automated]</what-built>
|
||||
<how-to-verify>[Numbered steps - URLs, commands, expected behavior]</how-to-verify>
|
||||
<resume-signal>[How to continue - "approved" or describe issues]</resume-signal>
|
||||
</task>
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```xml
|
||||
<task type="auto">
|
||||
<name>Deploy to Vercel</name>
|
||||
<action>Run `vercel --yes` to deploy. Capture URL.</action>
|
||||
<verify>vercel ls shows deployment, curl {url} returns 200</verify>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking">
|
||||
<what-built>Deployed to https://myapp.vercel.app</what-built>
|
||||
<how-to-verify>
|
||||
Visit URL and confirm:
|
||||
1. Homepage loads without errors
|
||||
2. All images/assets load
|
||||
3. No console errors
|
||||
</how-to-verify>
|
||||
<resume-signal>Type "approved" or describe issues</resume-signal>
|
||||
</task>
|
||||
```
|
||||
|
||||
## checkpoint:decision (9% of checkpoints)
|
||||
|
||||
**When:** Human must make choice that affects implementation direction.
|
||||
|
||||
**Use for:** Technology selection, architecture decisions, design choices, feature prioritization.
|
||||
|
||||
**Structure:**
|
||||
```xml
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<decision>[What's being decided]</decision>
|
||||
<context>[Why this matters]</context>
|
||||
<options>
|
||||
<option id="option-a"><name>[Name]</name><pros>[Benefits]</pros><cons>[Tradeoffs]</cons></option>
|
||||
<option id="option-b"><name>[Name]</name><pros>[Benefits]</pros><cons>[Tradeoffs]</cons></option>
|
||||
</options>
|
||||
<resume-signal>[How to indicate choice]</resume-signal>
|
||||
</task>
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```xml
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<decision>Select authentication provider</decision>
|
||||
<context>Need user auth. Three options with different tradeoffs.</context>
|
||||
<options>
|
||||
<option id="supabase"><name>Supabase Auth</name><pros>Built-in with DB, free tier, RLS integration</pros><cons>Less customizable, ecosystem lock-in</cons></option>
|
||||
<option id="clerk"><name>Clerk</name><pros>Beautiful UI, best DX</pros><cons>Paid after 10k MAU</cons></option>
|
||||
<option id="nextauth"><name>NextAuth.js</name><pros>Free, self-hosted, max control</pros><cons>More setup, DIY security</cons></option>
|
||||
</options>
|
||||
<resume-signal>Select: supabase, clerk, or nextauth</resume-signal>
|
||||
</task>
|
||||
```
|
||||
|
||||
## checkpoint:human-action (1% - rare)
|
||||
|
||||
**When:** Action has NO CLI/API and requires human-only interaction.
|
||||
|
||||
**Use ONLY for:** Email verification links, SMS 2FA codes, manual account approvals, 3D Secure payment flows, OAuth app approvals.
|
||||
|
||||
**Do NOT use for:** Deployments (use CLI), creating resources (use CLI/API), builds/tests (use Bash), file operations (use Write/Edit).
|
||||
|
||||
**Structure:**
|
||||
```xml
|
||||
<task type="checkpoint:human-action" gate="blocking">
|
||||
<action>[Unavoidable manual step]</action>
|
||||
<instructions>[What Claude automated] [ONE thing requiring human action]</instructions>
|
||||
<verification>[What Claude checks afterward]</verification>
|
||||
<resume-signal>[How to continue]</resume-signal>
|
||||
</task>
|
||||
```
|
||||
|
||||
**Example (email verification):**
|
||||
```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>
|
||||
```
|
||||
|
||||
</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]
|
||||
|
||||
[Checkpoint-specific content]
|
||||
|
||||
[Resume signal instruction]
|
||||
════════════════════════════════════════
|
||||
```
|
||||
|
||||
3. **Wait for user response** - do not hallucinate completion
|
||||
4. **Verify if possible** - check files, run tests
|
||||
5. **Resume execution** - continue only after confirmation
|
||||
|
||||
</execution_protocol>
|
||||
|
||||
<authentication_gates>
|
||||
|
||||
**Critical:** When Claude tries CLI/API and gets auth error, this is NOT a failure - it's a gate requiring human input to unblock automation.
|
||||
|
||||
**Pattern:** Claude tries automation → auth error → creates checkpoint → you authenticate → Claude retries → continues
|
||||
|
||||
**Gate protocol:**
|
||||
1. Recognize it's not a failure - missing auth is expected
|
||||
2. Stop current task - don't retry repeatedly
|
||||
3. Create checkpoint:human-action dynamically
|
||||
4. Provide exact authentication steps
|
||||
5. Verify authentication works
|
||||
6. Retry the original task
|
||||
7. Continue normally
|
||||
|
||||
**Example (Vercel auth gate):**
|
||||
```xml
|
||||
<!-- Claude tries to deploy -->
|
||||
<task type="auto">
|
||||
<name>Deploy to Vercel</name>
|
||||
<action>Run `vercel --yes` to deploy</action>
|
||||
</task>
|
||||
|
||||
<!-- If vercel returns "Error: Not authenticated" -->
|
||||
<task type="checkpoint:human-action" gate="blocking">
|
||||
<action>Authenticate Vercel CLI so I can continue</action>
|
||||
<instructions>
|
||||
I tried to deploy but got authentication error.
|
||||
Run: vercel login (opens browser)
|
||||
</instructions>
|
||||
<verification>vercel whoami returns your account</verification>
|
||||
<resume-signal>Type "done" when authenticated</resume-signal>
|
||||
</task>
|
||||
|
||||
<!-- After auth, Claude retries automatically -->
|
||||
<task type="auto">
|
||||
<name>Retry deployment</name>
|
||||
<action>Run `vercel --yes` (now authenticated)</action>
|
||||
</task>
|
||||
```
|
||||
|
||||
**Key distinction:**
|
||||
- Pre-planned checkpoint: "I need you to do X" (wrong - Claude should automate)
|
||||
- Auth gate: "I tried to automate X but need credentials" (correct - unblocks automation)
|
||||
|
||||
</authentication_gates>
|
||||
|
||||
<automation_reference>
|
||||
|
||||
**The rule:** If it has CLI/API, Claude does it. Never ask human to perform automatable work.
|
||||
|
||||
| Service | CLI/API | Key Commands | Auth Gate |
|
||||
|---------|---------|--------------|-----------|
|
||||
| Vercel | `vercel` | `--yes`, `env add`, `--prod`, `ls` | `vercel login` |
|
||||
| Railway | `railway` | `init`, `up`, `variables set` | `railway login` |
|
||||
| Fly | `fly` | `launch`, `deploy`, `secrets set` | `fly auth login` |
|
||||
| Stripe | `stripe` + API | `listen`, `trigger`, API calls | API key in .env |
|
||||
| Supabase | `supabase` | `init`, `link`, `db push`, `gen types` | `supabase login` |
|
||||
| Upstash | `upstash` | `redis create`, `redis get` | `upstash auth login` |
|
||||
| PlanetScale | `pscale` | `database create`, `branch create` | `pscale auth login` |
|
||||
| GitHub | `gh` | `repo create`, `pr create`, `secret set` | `gh auth login` |
|
||||
| Node | `npm`/`pnpm` | `install`, `run build`, `test` | N/A |
|
||||
| Xcode | `xcodebuild` | `-project`, `-scheme`, `build`, `test` | N/A |
|
||||
|
||||
**Env files:** Use Write/Edit tools. Never ask human to create .env manually.
|
||||
|
||||
**Quick reference:**
|
||||
|
||||
| Action | Automatable? | Claude does it? |
|
||||
|--------|--------------|-----------------|
|
||||
| Deploy to Vercel | Yes (`vercel`) | YES |
|
||||
| Create Stripe webhook | Yes (API) | YES |
|
||||
| Write .env file | Yes (Write tool) | YES |
|
||||
| Create Upstash DB | Yes (`upstash`) | YES |
|
||||
| Run tests | Yes (`npm test`) | YES |
|
||||
| Click email verification link | No | NO |
|
||||
| Enter credit card with 3DS | No | NO |
|
||||
|
||||
</automation_reference>
|
||||
|
||||
<guidelines>
|
||||
|
||||
**DO:**
|
||||
- Automate everything with CLI/API before checkpoint
|
||||
- Be specific: "Visit https://myapp.vercel.app" not "check deployment"
|
||||
- Number verification steps
|
||||
- State expected outcomes
|
||||
- Make verification executable
|
||||
|
||||
**DON'T:**
|
||||
- Ask human to do work Claude can automate
|
||||
- Assume knowledge: "Configure the usual settings"
|
||||
- Mix multiple verifications in one checkpoint
|
||||
- Use checkpoints too frequently (verification fatigue)
|
||||
|
||||
**Placement:**
|
||||
- After automation completes (not before)
|
||||
- After UI buildout
|
||||
- Before dependent work (decisions)
|
||||
- At integration points
|
||||
|
||||
</guidelines>
|
||||
|
||||
<anti_patterns>
|
||||
|
||||
**BAD: Asking human to automate**
|
||||
```xml
|
||||
<task type="checkpoint:human-action">
|
||||
<action>Deploy to Vercel</action>
|
||||
<instructions>Visit vercel.com/new, import repo, click Deploy</instructions>
|
||||
</task>
|
||||
```
|
||||
Why bad: Vercel has CLI. Use `vercel --yes`.
|
||||
|
||||
**BAD: Too many checkpoints**
|
||||
```xml
|
||||
<task type="auto">Create schema</task>
|
||||
<task type="checkpoint:human-verify">Check schema</task>
|
||||
<task type="auto">Create API</task>
|
||||
<task type="checkpoint:human-verify">Check API</task>
|
||||
```
|
||||
Why bad: Verification fatigue. Combine into one checkpoint at end.
|
||||
|
||||
**GOOD: Claude automates, human verifies once**
|
||||
```xml
|
||||
<task type="auto">Create schema</task>
|
||||
<task type="auto">Create API</task>
|
||||
<task type="auto">Create UI</task>
|
||||
|
||||
<task type="checkpoint:human-verify">
|
||||
<what-built>Complete auth flow</what-built>
|
||||
<how-to-verify>Test full flow: register, login, access protected page</how-to-verify>
|
||||
</task>
|
||||
```
|
||||
|
||||
</anti_patterns>
|
||||
|
||||
<summary>
|
||||
|
||||
**The golden rule:** If Claude CAN automate it, Claude MUST automate it.
|
||||
|
||||
**Checkpoint priority:**
|
||||
1. **checkpoint:human-verify** (90%) - Claude automated, human confirms visual/functional correctness
|
||||
2. **checkpoint:decision** (9%) - Human makes architectural/technology choices
|
||||
3. **checkpoint:human-action** (1%) - Truly unavoidable manual steps with no API/CLI
|
||||
|
||||
**When NOT to use checkpoints:**
|
||||
- Things Claude can verify programmatically (tests, builds)
|
||||
- File operations (Claude can read/write)
|
||||
- Anything with CLI/API available
|
||||
|
||||
</summary>
|
||||
|
|
@ -0,0 +1,255 @@
|
|||
# Continuation Format
|
||||
|
||||
Standard format for presenting next steps after completing a command or workflow.
|
||||
|
||||
## Core Structure
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**{identifier}: {name}** — {one-line description}
|
||||
|
||||
`{command to copy-paste}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `{alternative option 1}` — description
|
||||
- `{alternative option 2}` — description
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Format Rules
|
||||
|
||||
1. **Always show what it is** — name + description, never just a command path
|
||||
2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
|
||||
3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
|
||||
4. **`/clear` explanation** — always include, keeps it concise but explains why
|
||||
5. **"Also available" not "Other options"** — sounds more app-like
|
||||
6. **Visual separators** — `---` above and below to make it stand out
|
||||
|
||||
## Variants
|
||||
|
||||
### Execute Next Plan
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
|
||||
|
||||
`/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- Review plan before executing
|
||||
- `/gsd:list-phase-assumptions 2` — check assumptions
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
### Execute Final Plan in Phase
|
||||
|
||||
Add note that this is the last plan and what comes after:
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
|
||||
<sub>Final plan in Phase 2</sub>
|
||||
|
||||
`/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**After this completes:**
|
||||
- Phase 2 → Phase 3 transition
|
||||
- Next: **Phase 3: Core Features** — User dashboard and settings
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
### Plan a Phase
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase 2: Authentication** — JWT login flow with refresh tokens
|
||||
|
||||
`/gsd:plan-phase 2`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:discuss-phase 2` — gather context first
|
||||
- `/gsd:research-phase 2` — investigate unknowns
|
||||
- Review roadmap
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
### Phase Complete, Ready for Next
|
||||
|
||||
Show completion status before next action:
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ✓ Phase 2 Complete
|
||||
|
||||
3/3 plans executed
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase 3: Core Features** — User dashboard, settings, and data export
|
||||
|
||||
`/gsd:plan-phase 3`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:discuss-phase 3` — gather context first
|
||||
- `/gsd:research-phase 3` — investigate unknowns
|
||||
- Review what Phase 2 built
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
### Multiple Equal Options
|
||||
|
||||
When there's no clear primary action:
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase 3: Core Features** — User dashboard, settings, and data export
|
||||
|
||||
**To plan directly:** `/gsd:plan-phase 3`
|
||||
|
||||
**To discuss context first:** `/gsd:discuss-phase 3`
|
||||
|
||||
**To research unknowns:** `/gsd:research-phase 3`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
### Milestone Complete
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
## 🎉 Milestone v1.0 Complete
|
||||
|
||||
All 4 phases shipped
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Plan v1.1** — Enhanced features and optimizations
|
||||
|
||||
`/gsd:discuss-milestone`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:new-milestone` — create directly if scope is clear
|
||||
- Review accomplishments before moving on
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Pulling Context
|
||||
|
||||
### For phases (from ROADMAP.md):
|
||||
|
||||
```markdown
|
||||
### Phase 2: Authentication
|
||||
**Goal**: JWT login flow with refresh tokens
|
||||
```
|
||||
|
||||
Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
|
||||
|
||||
### For plans (from ROADMAP.md):
|
||||
|
||||
```markdown
|
||||
Plans:
|
||||
- [ ] 02-03: Add refresh token rotation
|
||||
```
|
||||
|
||||
Or from PLAN.md `<objective>`:
|
||||
|
||||
```xml
|
||||
<objective>
|
||||
Add refresh token rotation with sliding expiry window.
|
||||
|
||||
Purpose: Extend session lifetime without compromising security.
|
||||
</objective>
|
||||
```
|
||||
|
||||
Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### Don't: Command-only (no context)
|
||||
|
||||
```
|
||||
## To Continue
|
||||
|
||||
Run `/clear`, then paste:
|
||||
/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md
|
||||
```
|
||||
|
||||
User has no idea what 02-03 is about.
|
||||
|
||||
### Don't: Missing /clear explanation
|
||||
|
||||
```
|
||||
`/gsd:plan-phase 3`
|
||||
|
||||
Run /clear first.
|
||||
```
|
||||
|
||||
Doesn't explain why. User might skip it.
|
||||
|
||||
### Don't: "Other options" language
|
||||
|
||||
```
|
||||
Other options:
|
||||
- Review roadmap
|
||||
```
|
||||
|
||||
Sounds like an afterthought. Use "Also available:" instead.
|
||||
|
||||
### Don't: Fenced code blocks for commands
|
||||
|
||||
```
|
||||
```
|
||||
/gsd:plan-phase 3
|
||||
```
|
||||
```
|
||||
|
||||
Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.
|
||||
|
|
@ -0,0 +1,254 @@
|
|||
<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 plan completion |
|
||||
| RESEARCH.md created | NO | Intermediate |
|
||||
| DISCOVERY.md created | NO | Intermediate |
|
||||
| **Task completed** | YES | Atomic unit of work (1 commit per task) |
|
||||
| **Plan completed** | YES | Metadata commit (SUMMARY + STATE + ROADMAP) |
|
||||
| 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="task-completion">
|
||||
## Task Completion (During Plan Execution)
|
||||
|
||||
Each task gets its own commit immediately after completion.
|
||||
|
||||
```
|
||||
{type}({phase}-{plan}): {task-name}
|
||||
|
||||
- [Key change 1]
|
||||
- [Key change 2]
|
||||
- [Key change 3]
|
||||
```
|
||||
|
||||
**Commit types:**
|
||||
- `feat` - New feature/functionality
|
||||
- `fix` - Bug fix
|
||||
- `test` - Test-only (TDD RED phase)
|
||||
- `refactor` - Code cleanup (TDD REFACTOR phase)
|
||||
- `perf` - Performance improvement
|
||||
- `chore` - Dependencies, config, tooling
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Standard task
|
||||
git add src/api/auth.ts src/types/user.ts
|
||||
git commit -m "feat(08-02): create user registration endpoint
|
||||
|
||||
- POST /auth/register validates email and password
|
||||
- Checks for duplicate users
|
||||
- Returns JWT token on success
|
||||
"
|
||||
|
||||
# TDD task - RED phase
|
||||
git add src/__tests__/jwt.test.ts
|
||||
git commit -m "test(07-02): add failing test for JWT generation
|
||||
|
||||
- Tests token contains user ID claim
|
||||
- Tests token expires in 1 hour
|
||||
- Tests signature verification
|
||||
"
|
||||
|
||||
# TDD task - GREEN phase
|
||||
git add src/utils/jwt.ts
|
||||
git commit -m "feat(07-02): implement JWT generation
|
||||
|
||||
- Uses jose library for signing
|
||||
- Includes user ID and expiry claims
|
||||
- Signs with HS256 algorithm
|
||||
"
|
||||
```
|
||||
|
||||
</format>
|
||||
|
||||
<format name="plan-completion">
|
||||
## Plan Completion (After All Tasks Done)
|
||||
|
||||
After all tasks committed, one final metadata commit captures plan completion.
|
||||
|
||||
```
|
||||
docs({phase}-{plan}): complete [plan-name] plan
|
||||
|
||||
Tasks completed: [N]/[N]
|
||||
- [Task 1 name]
|
||||
- [Task 2 name]
|
||||
- [Task 3 name]
|
||||
|
||||
SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
|
||||
```
|
||||
|
||||
What to commit:
|
||||
|
||||
```bash
|
||||
git add .planning/phases/XX-name/{phase}-{plan}-PLAN.md
|
||||
git add .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
|
||||
git add .planning/STATE.md
|
||||
git add .planning/ROADMAP.md
|
||||
git commit
|
||||
```
|
||||
|
||||
**Note:** Code files NOT included - already committed per-task.
|
||||
|
||||
</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>
|
||||
|
||||
**Old approach (per-plan commits):**
|
||||
```
|
||||
a7f2d1 feat(checkout): Stripe payments with webhook verification
|
||||
3e9c4b feat(products): catalog with search, filters, and pagination
|
||||
8a1b2c feat(auth): JWT with refresh rotation using jose
|
||||
5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold
|
||||
2f4a8d docs: initialize ecommerce-app (5 phases)
|
||||
```
|
||||
|
||||
**New approach (per-task commits):**
|
||||
```
|
||||
# Phase 04 - Checkout
|
||||
1a2b3c docs(04-01): complete checkout flow plan
|
||||
4d5e6f feat(04-01): add webhook signature verification
|
||||
7g8h9i feat(04-01): implement payment session creation
|
||||
0j1k2l feat(04-01): create checkout page component
|
||||
|
||||
# Phase 03 - Products
|
||||
3m4n5o docs(03-02): complete product listing plan
|
||||
6p7q8r feat(03-02): add pagination controls
|
||||
9s0t1u feat(03-02): implement search and filters
|
||||
2v3w4x feat(03-01): create product catalog schema
|
||||
|
||||
# Phase 02 - Auth
|
||||
5y6z7a docs(02-02): complete token refresh plan
|
||||
8b9c0d feat(02-02): implement refresh token rotation
|
||||
1e2f3g test(02-02): add failing test for token refresh
|
||||
4h5i6j docs(02-01): complete JWT setup plan
|
||||
7k8l9m feat(02-01): add JWT generation and validation
|
||||
0n1o2p chore(02-01): install jose library
|
||||
|
||||
# Phase 01 - Foundation
|
||||
3q4r5s docs(01-01): complete scaffold plan
|
||||
6t7u8v feat(01-01): configure Tailwind and globals
|
||||
9w0x1y feat(01-01): set up Prisma with database
|
||||
2z3a4b feat(01-01): create Next.js 15 project
|
||||
|
||||
# Initialization
|
||||
5c6d7e docs: initialize ecommerce-app (5 phases)
|
||||
```
|
||||
|
||||
Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
|
||||
|
||||
</example_log>
|
||||
|
||||
<anti_patterns>
|
||||
|
||||
**Still don't commit (intermediate artifacts):**
|
||||
- PLAN.md creation (commit with plan completion)
|
||||
- RESEARCH.md (intermediate)
|
||||
- DISCOVERY.md (intermediate)
|
||||
- Minor planning tweaks
|
||||
- "Fixed typo in roadmap"
|
||||
|
||||
**Do commit (outcomes):**
|
||||
- Each task completion (feat/fix/test/refactor)
|
||||
- Plan completion metadata (docs)
|
||||
- Project initialization (docs)
|
||||
|
||||
**Key principle:** Commit working code and shipped outcomes, not planning process.
|
||||
|
||||
</anti_patterns>
|
||||
|
||||
<commit_strategy_rationale>
|
||||
|
||||
## Why Per-Task Commits?
|
||||
|
||||
**Context engineering for AI:**
|
||||
- Git history becomes primary context source for future Claude sessions
|
||||
- `git log --grep="{phase}-{plan}"` shows all work for a plan
|
||||
- `git diff <hash>^..<hash>` shows exact changes per task
|
||||
- Less reliance on parsing SUMMARY.md = more context for actual work
|
||||
|
||||
**Failure recovery:**
|
||||
- Task 1 committed ✅, Task 2 failed ❌
|
||||
- Claude in next session: sees task 1 complete, can retry task 2
|
||||
- Can `git reset --hard` to last successful task
|
||||
|
||||
**Debugging:**
|
||||
- `git bisect` finds exact failing task, not just failing plan
|
||||
- `git blame` traces line to specific task context
|
||||
- Each commit is independently revertable
|
||||
|
||||
**Observability:**
|
||||
- Solo developer + Claude workflow benefits from granular attribution
|
||||
- Atomic commits are git best practice
|
||||
- "Commit noise" irrelevant when consumer is Claude, not humans
|
||||
|
||||
</commit_strategy_rationale>
|
||||
|
|
@ -0,0 +1,428 @@
|
|||
<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>
|
||||
|
||||
<tdd_plans>
|
||||
**TDD work uses dedicated plans.**
|
||||
|
||||
TDD features require 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. This is fundamentally heavier than standard tasks and would consume 50-60% of context if embedded in a multi-task plan.
|
||||
|
||||
**When to create a TDD plan:**
|
||||
- Business logic with defined inputs/outputs
|
||||
- API endpoints with request/response contracts
|
||||
- Data transformations and parsing
|
||||
- Validation rules
|
||||
- Algorithms with testable behavior
|
||||
|
||||
**When to use standard plans (skip TDD):**
|
||||
- UI layout and styling
|
||||
- Configuration changes
|
||||
- Glue code connecting existing components
|
||||
- One-off scripts
|
||||
|
||||
**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
|
||||
→ Yes: Create a TDD plan (one feature per plan)
|
||||
→ No: Use standard plan, add tests after if needed
|
||||
|
||||
See `./tdd.md` for TDD plan structure and execution guidance.
|
||||
</tdd_plans>
|
||||
|
||||
<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/DISCOVERY.md # Discovery 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>
|
||||
|
||||
<note_on_tdd>
|
||||
**TDD candidates get dedicated plans.**
|
||||
|
||||
If email validation warrants TDD, create a TDD plan for it. See `./tdd.md` for TDD plan structure.
|
||||
</note_on_tdd>
|
||||
|
||||
<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>
|
||||
|
|
@ -0,0 +1,157 @@
|
|||
<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>
|
||||
|
||||
<test_driven_when_beneficial>
|
||||
|
||||
Use TDD when the work WOULD benefit from it. Not dogma—pragmatism.
|
||||
|
||||
**TDD candidates (create dedicated TDD plan):**
|
||||
- Business logic with defined inputs/outputs
|
||||
- API endpoints and handlers
|
||||
- Data transformations and parsing
|
||||
- Validation rules
|
||||
- State machines and workflows
|
||||
- Anything where you can describe expected behavior before implementing
|
||||
|
||||
**Skip TDD (use standard plan):**
|
||||
- UI layout and styling
|
||||
- Exploratory prototyping
|
||||
- One-off scripts and migrations
|
||||
- Configuration changes
|
||||
- Glue code with no logic
|
||||
|
||||
**Decision heuristic:**
|
||||
Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
|
||||
→ Yes: Create a TDD plan (one feature per plan)
|
||||
→ No: Standard plan, add tests after if needed
|
||||
|
||||
**Why TDD gets its own plan:**
|
||||
TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. This consumes 40-50% of context for a single feature. Dedicated TDD plans ensure full quality throughout the cycle.
|
||||
|
||||
**TDD plan structure:**
|
||||
1. Write failing test (RED) → commit
|
||||
2. Implement to pass (GREEN) → commit
|
||||
3. Refactor if needed → commit
|
||||
|
||||
This is about design quality, not test coverage metrics.
|
||||
|
||||
See `./.claude/get-shit-done/references/tdd.md` for TDD plan structure.
|
||||
</test_driven_when_beneficial>
|
||||
|
||||
<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>
|
||||
|
||||
<atomic_commits>
|
||||
|
||||
**Git commits = context engineering for Claude.**
|
||||
|
||||
Each task gets its own commit immediately after completion:
|
||||
- Format: `{type}({phase}-{plan}): {task-description}`
|
||||
- Types: feat, fix, test, refactor, perf, chore, docs
|
||||
- One final metadata commit per plan: `docs({phase}-{plan}): complete [plan-name]`
|
||||
|
||||
**Why per-task commits:**
|
||||
- Git history becomes primary context source for future Claude sessions
|
||||
- `git bisect` finds exact failing task, not just failing plan
|
||||
- Each task independently revertable
|
||||
- Better failure recovery (task 1 committed ✅, retry task 2)
|
||||
- Observability optimized for AI workflow, not human browsing
|
||||
|
||||
**Plans produce 3-4 commits total:**
|
||||
- 2-3 task commits (working code)
|
||||
- 1 metadata commit (SUMMARY + STATE + ROADMAP)
|
||||
|
||||
See `./.claude/get-shit-done/references/git-integration.md` for complete strategy.
|
||||
</atomic_commits>
|
||||
|
||||
<anti_enterprise>
|
||||
|
||||
NEVER include:
|
||||
- Team structures, RACI matrices
|
||||
- Stakeholder management
|
||||
- Sprint ceremonies
|
||||
- Human dev time estimates (hours, days, weeks—Claude works differently)
|
||||
- Change management processes
|
||||
- Documentation for documentation's sake
|
||||
|
||||
If it sounds like corporate PM theater, delete it.
|
||||
</anti_enterprise>
|
||||
</principles>
|
||||
|
|
@ -0,0 +1,162 @@
|
|||
<questioning_guide>
|
||||
The initialization phase is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
|
||||
|
||||
<philosophy>
|
||||
**You are a thinking partner, not an interviewer.**
|
||||
|
||||
The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
|
||||
|
||||
Don't interrogate. Collaborate.
|
||||
</philosophy>
|
||||
|
||||
<critical_rule>
|
||||
**ALL questions MUST use AskUserQuestion.**
|
||||
|
||||
Never ask questions inline as plain text. Every exploration question uses the AskUserQuestion tool with thoughtful options that help the user articulate their vision.
|
||||
|
||||
This applies to:
|
||||
- Opening questions ("What do you want to build?")
|
||||
- Follow-up questions ("You mentioned X — what would that look like?")
|
||||
- Sharpening questions ("What's essential vs nice-to-have?")
|
||||
- Boundary questions ("What's out of scope?")
|
||||
- Decision gates ("Ready to proceed?")
|
||||
|
||||
The AskUserQuestion format helps users think by presenting concrete options to react to, rather than facing a blank text field.
|
||||
</critical_rule>
|
||||
|
||||
<conversation_arc>
|
||||
**1. Open**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Vision"
|
||||
- question: "What do you want to build?"
|
||||
- options: Contextual starting points if available, otherwise broad categories + "Let me describe it"
|
||||
|
||||
Let them respond. Then follow up based on what they said.
|
||||
|
||||
**2. Follow the thread**
|
||||
|
||||
Whatever they said — dig into it. What excited them? What problem sparked this?
|
||||
|
||||
Use AskUserQuestion with options that probe what they mentioned:
|
||||
- header: "[Topic they mentioned]"
|
||||
- question: "You mentioned [X] — what would that actually look like?"
|
||||
- options: 2-3 interpretations of what they might mean + "Something else"
|
||||
|
||||
**3. Sharpen the core**
|
||||
|
||||
Help them distinguish the essential from the nice-to-have.
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Core"
|
||||
- question: "If you could only nail one thing, what would it be?"
|
||||
- options: Key features/aspects they've mentioned + "All equally important" + "Something else"
|
||||
|
||||
**4. Find the boundaries**
|
||||
|
||||
What is this NOT? Explicit exclusions prevent scope creep later.
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Scope"
|
||||
- question: "What's explicitly NOT in v1?"
|
||||
- options: Things that might be tempting to include + "Nothing specific" + "Let me list them"
|
||||
|
||||
**5. Ground in reality**
|
||||
|
||||
Only ask about constraints that actually exist. Don't invent concerns.
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Constraints"
|
||||
- question: "Any hard constraints?"
|
||||
- options: Common constraint types relevant to context + "None" + "Yes, let me explain"
|
||||
</conversation_arc>
|
||||
|
||||
<good_vs_bad>
|
||||
**BAD — Inline text questions:**
|
||||
- Asking "What is your target audience?" as plain text
|
||||
- Free-form "Tell me more about X" without options
|
||||
- Any question that leaves the user staring at a blank input
|
||||
|
||||
**GOOD — AskUserQuestion with options:**
|
||||
- header: "Audience"
|
||||
- question: "Who is this for?"
|
||||
- options: ["Just me", "My team", "Public users", "Let me describe"]
|
||||
|
||||
**BAD — Corporate speak:**
|
||||
- "What are your success criteria?"
|
||||
- "What's your budget?"
|
||||
- "Have you done X before?" (irrelevant — Claude builds)
|
||||
|
||||
**GOOD — Concrete options that help them think:**
|
||||
- header: "Done"
|
||||
- question: "How will you know this is working?"
|
||||
- options: ["I'm using it daily", "Specific metric improves", "Replaces current workflow", "Let me describe"]
|
||||
|
||||
**BAD — Checklist walking:**
|
||||
- Ask about audience → ask about constraints → ask about tech stack (regardless of what user said)
|
||||
|
||||
**GOOD — Following threads with targeted options:**
|
||||
- User mentions frustration → AskUserQuestion with specific frustration interpretations as options → their selection reveals the core value prop
|
||||
</good_vs_bad>
|
||||
|
||||
<probing_techniques>
|
||||
When answers are vague, don't accept them. Probe with AskUserQuestion:
|
||||
|
||||
**"Make it good"** →
|
||||
- header: "Good"
|
||||
- question: "What does 'good' mean here?"
|
||||
- options: ["Fast", "Beautiful", "Simple", "Reliable", "Let me describe"]
|
||||
|
||||
**"Users"** →
|
||||
- header: "Users"
|
||||
- question: "Which users?"
|
||||
- options: ["Just me", "My team", "Specific type of person", "Let me describe"]
|
||||
|
||||
**"It should be easy to use"** →
|
||||
- header: "Easy"
|
||||
- question: "Easy how?"
|
||||
- options: ["Fewer clicks", "No learning curve", "Works on mobile", "Let me describe"]
|
||||
|
||||
Specifics are everything. Vague in = vague out.
|
||||
</probing_techniques>
|
||||
|
||||
<coverage_check>
|
||||
By the end of questioning, you should understand:
|
||||
|
||||
- [ ] What they're building (the thing)
|
||||
- [ ] Why it needs to exist (the motivation)
|
||||
- [ ] Who it's for (even if just themselves)
|
||||
- [ ] What "done" looks like (measurable outcome)
|
||||
- [ ] What's NOT in scope (boundaries)
|
||||
- [ ] Any real constraints (tech, timeline, compatibility)
|
||||
- [ ] What exists already (greenfield vs brownfield)
|
||||
|
||||
If gaps remain, weave questions naturally into the conversation. Don't suddenly switch to checklist mode.
|
||||
</coverage_check>
|
||||
|
||||
<decision_gate>
|
||||
When you feel you understand the vision, use AskUserQuestion:
|
||||
|
||||
- header: "Ready?"
|
||||
- question: "Ready to create PROJECT.md, or explore more?"
|
||||
- options (ALL THREE REQUIRED):
|
||||
- "Create PROJECT.md" - Finalize and continue
|
||||
- "Ask more questions" - I'll dig into areas we haven't covered
|
||||
- "Let me add context" - You have more to share
|
||||
|
||||
If "Ask more questions" → identify gaps from coverage check → ask naturally → return to gate.
|
||||
|
||||
Loop until "Create PROJECT.md" selected.
|
||||
</decision_gate>
|
||||
|
||||
<anti_patterns>
|
||||
- **Interrogation** - Firing questions without building on answers
|
||||
- **Checklist walking** - Going through domains regardless of conversation flow
|
||||
- **Corporate speak** - "What are your success criteria?" "Who are your stakeholders?"
|
||||
- **Rushing** - Minimizing questions to get to "the work"
|
||||
- **Assuming** - Filling gaps with assumptions instead of asking
|
||||
- **User skills** - NEVER ask about user's technical experience. Claude builds — user's skills are irrelevant.
|
||||
- **Premature constraints** - Asking about tech stack before understanding the idea
|
||||
- **Shallow acceptance** - Taking vague answers without probing for specifics
|
||||
</anti_patterns>
|
||||
</questioning_guide>
|
||||
|
|
@ -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>
|
||||
|
|
@ -0,0 +1,172 @@
|
|||
<scope_estimation>
|
||||
Plans must maintain consistent quality from first task to last. This requires understanding quality degradation and splitting aggressively.
|
||||
|
||||
<quality_insight>
|
||||
Claude degrades when it *perceives* context pressure and enters "completion mode."
|
||||
|
||||
| Context Usage | Quality | Claude's State |
|
||||
|---------------|---------|----------------|
|
||||
| 0-30% | PEAK | Thorough, comprehensive |
|
||||
| 30-50% | GOOD | Confident, solid work |
|
||||
| 50-70% | DEGRADING | Efficiency mode begins |
|
||||
| 70%+ | POOR | Rushed, minimal |
|
||||
|
||||
**The 40-50% inflection point:** Claude sees context mounting and thinks "I'd better conserve now." Result: "I'll complete the remaining tasks more concisely" = quality crash.
|
||||
|
||||
**The rule:** Stop BEFORE quality degrades, not at context limit.
|
||||
</quality_insight>
|
||||
|
||||
<context_target>
|
||||
**Plans should complete within ~50% of context usage.**
|
||||
|
||||
Why 50% not 80%?
|
||||
- No context anxiety possible
|
||||
- Quality maintained start to finish
|
||||
- Room for unexpected complexity
|
||||
- If you target 80%, you've already spent 40% in degradation mode
|
||||
</context_target>
|
||||
|
||||
<task_rule>
|
||||
**Each plan: 2-3 tasks maximum. Stay under 50% context.**
|
||||
|
||||
| Task Complexity | Tasks/Plan | Context/Task | Total |
|
||||
|-----------------|------------|--------------|-------|
|
||||
| Simple (CRUD, config) | 3 | ~10-15% | ~30-45% |
|
||||
| Complex (auth, payments) | 2 | ~20-30% | ~40-50% |
|
||||
| Very complex (migrations, refactors) | 1-2 | ~30-40% | ~30-50% |
|
||||
|
||||
**When in doubt: Default to 2 tasks.** Better to have an extra plan than degraded quality.
|
||||
</task_rule>
|
||||
|
||||
<tdd_plans>
|
||||
**TDD features get their own plans. Target ~40% context.**
|
||||
|
||||
TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. This is fundamentally heavier than linear task execution.
|
||||
|
||||
| TDD Feature Complexity | Context Usage |
|
||||
|------------------------|---------------|
|
||||
| Simple utility function | ~25-30% |
|
||||
| Business logic with edge cases | ~35-40% |
|
||||
| Complex algorithm | ~40-50% |
|
||||
|
||||
**One feature per TDD plan.** If features are trivial enough to batch, they're trivial enough to skip TDD.
|
||||
|
||||
**Why TDD plans are separate:**
|
||||
- TDD consumes 40-50% context for a single feature
|
||||
- Dedicated plans ensure full quality throughout RED-GREEN-REFACTOR
|
||||
- Each TDD feature gets fresh context, peak quality
|
||||
|
||||
See `./.claude/get-shit-done/references/tdd.md` for TDD plan structure.
|
||||
</tdd_plans>
|
||||
|
||||
<split_signals>
|
||||
|
||||
<always_split>
|
||||
- **More than 3 tasks** - Even if tasks seem small
|
||||
- **Multiple subsystems** - DB + API + UI = separate plans
|
||||
- **Any task with >5 file modifications** - Split by file groups
|
||||
- **Checkpoint + implementation work** - Checkpoints in one plan, implementation after in separate plan
|
||||
- **Discovery + implementation** - DISCOVERY.md in one plan, implementation in another
|
||||
</always_split>
|
||||
|
||||
<consider_splitting>
|
||||
- Estimated >5 files modified total
|
||||
- Complex domains (auth, payments, data modeling)
|
||||
- Any uncertainty about approach
|
||||
- Natural semantic boundaries (Setup -> Core -> Features)
|
||||
</consider_splitting>
|
||||
</split_signals>
|
||||
|
||||
<splitting_strategies>
|
||||
**By subsystem:** Auth → 01: DB models, 02: API routes, 03: Protected routes, 04: UI components
|
||||
|
||||
**By dependency:** Payments → 01: Stripe setup, 02: Subscription logic, 03: Frontend integration
|
||||
|
||||
**By complexity:** Dashboard → 01: Layout shell, 02: Data fetching, 03: Visualization
|
||||
|
||||
**By verification:** Deploy → 01: Vercel setup (checkpoint), 02: Env config (auto), 03: CI/CD (checkpoint)
|
||||
</splitting_strategies>
|
||||
|
||||
<anti_patterns>
|
||||
**Bad - Comprehensive plan:**
|
||||
```
|
||||
Plan: "Complete Authentication System"
|
||||
Tasks: 8 (models, migrations, API, JWT, middleware, hashing, login form, register form)
|
||||
Result: Task 1-3 good, Task 4-5 degrading, Task 6-8 rushed
|
||||
```
|
||||
|
||||
**Good - Atomic plans:**
|
||||
```
|
||||
Plan 1: "Auth Database Models" (2 tasks)
|
||||
Plan 2: "Auth API Core" (3 tasks)
|
||||
Plan 3: "Auth API Protection" (2 tasks)
|
||||
Plan 4: "Auth UI Components" (2 tasks)
|
||||
Each: 30-40% context, peak quality, atomic commits (2-3 task commits + 1 metadata commit)
|
||||
```
|
||||
</anti_patterns>
|
||||
|
||||
<estimating_context>
|
||||
| Files Modified | Context Impact |
|
||||
|----------------|----------------|
|
||||
| 0-3 files | ~10-15% (small) |
|
||||
| 4-6 files | ~20-30% (medium) |
|
||||
| 7+ files | ~40%+ (large - split) |
|
||||
|
||||
| Complexity | Context/Task |
|
||||
|------------|--------------|
|
||||
| Simple CRUD | ~15% |
|
||||
| Business logic | ~25% |
|
||||
| Complex algorithms | ~40% |
|
||||
| Domain modeling | ~35% |
|
||||
|
||||
**2 tasks:** Simple ~30%, Medium ~50%, Complex ~80% (split)
|
||||
**3 tasks:** Simple ~45%, Medium ~75% (risky), Complex 120% (impossible)
|
||||
</estimating_context>
|
||||
|
||||
<depth_calibration>
|
||||
**Depth controls compression tolerance, not artificial inflation.**
|
||||
|
||||
| Depth | Typical Phases | Typical Plans/Phase | Tasks/Plan |
|
||||
|-------|----------------|---------------------|------------|
|
||||
| Quick | 3-5 | 1-3 | 2-3 |
|
||||
| Standard | 5-8 | 3-5 | 2-3 |
|
||||
| Comprehensive | 8-12 | 5-10 | 2-3 |
|
||||
|
||||
Tasks/plan is CONSTANT at 2-3. The 50% context rule applies universally.
|
||||
|
||||
**Key principle:** Derive from actual work. Depth determines how aggressively you combine things, not a target to hit.
|
||||
|
||||
- Comprehensive auth = 8 plans (because auth genuinely has 8 concerns)
|
||||
- Comprehensive "add favicon" = 1 plan (because that's all it is)
|
||||
|
||||
Don't pad small work to hit a number. Don't compress complex work to look efficient.
|
||||
|
||||
**Comprehensive depth example:**
|
||||
Auth system at comprehensive depth = 8 plans (not 3 big ones):
|
||||
- 01: DB models (2 tasks)
|
||||
- 02: Password hashing (2 tasks)
|
||||
- 03: JWT generation (2 tasks)
|
||||
- 04: JWT validation middleware (2 tasks)
|
||||
- 05: Login endpoint (2 tasks)
|
||||
- 06: Register endpoint (2 tasks)
|
||||
- 07: Protected route patterns (2 tasks)
|
||||
- 08: Auth UI components (3 tasks)
|
||||
|
||||
Each plan: fresh context, peak quality. More plans = more thoroughness, same quality per plan.
|
||||
</depth_calibration>
|
||||
|
||||
<summary>
|
||||
**2-3 tasks, 50% context target:**
|
||||
- All tasks: Peak quality
|
||||
- Git: Atomic per-task commits (each task = 1 commit, plan = 1 metadata commit)
|
||||
- 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.
|
||||
|
||||
**Depth rule:** Depth increases plan COUNT, never plan SIZE.
|
||||
|
||||
**Commit rule:** Each plan produces 3-4 commits total (2-3 task commits + 1 docs commit). More granular history = better observability for Claude.
|
||||
</summary>
|
||||
</scope_estimation>
|
||||
|
|
@ -0,0 +1,263 @@
|
|||
<overview>
|
||||
TDD is about design quality, not coverage metrics. The red-green-refactor cycle forces you to think about behavior before implementation, producing cleaner interfaces and more testable code.
|
||||
|
||||
**Principle:** If you can describe the behavior as `expect(fn(input)).toBe(output)` before writing `fn`, TDD improves the result.
|
||||
|
||||
**Key insight:** TDD work is fundamentally heavier than standard tasks—it requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. TDD features get dedicated plans to ensure full context is available throughout the cycle.
|
||||
</overview>
|
||||
|
||||
<when_to_use_tdd>
|
||||
## When TDD Improves Quality
|
||||
|
||||
**TDD candidates (create a TDD plan):**
|
||||
- Business logic with defined inputs/outputs
|
||||
- API endpoints with request/response contracts
|
||||
- Data transformations, parsing, formatting
|
||||
- Validation rules and constraints
|
||||
- Algorithms with testable behavior
|
||||
- State machines and workflows
|
||||
- Utility functions with clear specifications
|
||||
|
||||
**Skip TDD (use standard plan with `type="auto"` tasks):**
|
||||
- UI layout, styling, visual components
|
||||
- Configuration changes
|
||||
- Glue code connecting existing components
|
||||
- One-off scripts and migrations
|
||||
- Simple CRUD with no business logic
|
||||
- Exploratory prototyping
|
||||
|
||||
**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
|
||||
→ Yes: Create a TDD plan
|
||||
→ No: Use standard plan, add tests after if needed
|
||||
</when_to_use_tdd>
|
||||
|
||||
<tdd_plan_structure>
|
||||
## TDD Plan Structure
|
||||
|
||||
Each TDD plan implements **one feature** through the full RED-GREEN-REFACTOR cycle.
|
||||
|
||||
```markdown
|
||||
---
|
||||
phase: XX-name
|
||||
plan: NN
|
||||
type: tdd
|
||||
---
|
||||
|
||||
<objective>
|
||||
[What feature and why]
|
||||
Purpose: [Design benefit of TDD for this feature]
|
||||
Output: [Working, tested feature]
|
||||
</objective>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@relevant/source/files.ts
|
||||
</context>
|
||||
|
||||
<feature>
|
||||
<name>[Feature name]</name>
|
||||
<files>[source file, test file]</files>
|
||||
<behavior>
|
||||
[Expected behavior in testable terms]
|
||||
Cases: input → expected output
|
||||
</behavior>
|
||||
<implementation>[How to implement once tests pass]</implementation>
|
||||
</feature>
|
||||
|
||||
<verification>
|
||||
[Test command that proves feature works]
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- Failing test written and committed
|
||||
- Implementation passes test
|
||||
- Refactor complete (if needed)
|
||||
- All 2-3 commits present
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create SUMMARY.md with:
|
||||
- RED: What test was written, why it failed
|
||||
- GREEN: What implementation made it pass
|
||||
- REFACTOR: What cleanup was done (if any)
|
||||
- Commits: List of commits produced
|
||||
</output>
|
||||
```
|
||||
|
||||
**One feature per TDD plan.** If features are trivial enough to batch, they're trivial enough to skip TDD—use a standard plan and add tests after.
|
||||
</tdd_plan_structure>
|
||||
|
||||
<execution_flow>
|
||||
## Red-Green-Refactor Cycle
|
||||
|
||||
**RED - Write failing test:**
|
||||
1. Create test file following project conventions
|
||||
2. Write test describing expected behavior (from `<behavior>` element)
|
||||
3. Run test - it MUST fail
|
||||
4. If test passes: feature exists or test is wrong. Investigate.
|
||||
5. Commit: `test({phase}-{plan}): add failing test for [feature]`
|
||||
|
||||
**GREEN - Implement to pass:**
|
||||
1. Write minimal code to make test pass
|
||||
2. No cleverness, no optimization - just make it work
|
||||
3. Run test - it MUST pass
|
||||
4. Commit: `feat({phase}-{plan}): implement [feature]`
|
||||
|
||||
**REFACTOR (if needed):**
|
||||
1. Clean up implementation if obvious improvements exist
|
||||
2. Run tests - MUST still pass
|
||||
3. Only commit if changes made: `refactor({phase}-{plan}): clean up [feature]`
|
||||
|
||||
**Result:** Each TDD plan produces 2-3 atomic commits.
|
||||
</execution_flow>
|
||||
|
||||
<test_quality>
|
||||
## Good Tests vs Bad Tests
|
||||
|
||||
**Test behavior, not implementation:**
|
||||
- Good: "returns formatted date string"
|
||||
- Bad: "calls formatDate helper with correct params"
|
||||
- Tests should survive refactors
|
||||
|
||||
**One concept per test:**
|
||||
- Good: Separate tests for valid input, empty input, malformed input
|
||||
- Bad: Single test checking all edge cases with multiple assertions
|
||||
|
||||
**Descriptive names:**
|
||||
- Good: "should reject empty email", "returns null for invalid ID"
|
||||
- Bad: "test1", "handles error", "works correctly"
|
||||
|
||||
**No implementation details:**
|
||||
- Good: Test public API, observable behavior
|
||||
- Bad: Mock internals, test private methods, assert on internal state
|
||||
</test_quality>
|
||||
|
||||
<framework_setup>
|
||||
## Test Framework Setup (If None Exists)
|
||||
|
||||
When executing a TDD plan but no test framework is configured, set it up as part of the RED phase:
|
||||
|
||||
**1. Detect project type:**
|
||||
```bash
|
||||
# JavaScript/TypeScript
|
||||
if [ -f package.json ]; then echo "node"; fi
|
||||
|
||||
# Python
|
||||
if [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo "python"; fi
|
||||
|
||||
# Go
|
||||
if [ -f go.mod ]; then echo "go"; fi
|
||||
|
||||
# Rust
|
||||
if [ -f Cargo.toml ]; then echo "rust"; fi
|
||||
```
|
||||
|
||||
**2. Install minimal framework:**
|
||||
| Project | Framework | Install |
|
||||
|---------|-----------|---------|
|
||||
| Node.js | Jest | `npm install -D jest @types/jest ts-jest` |
|
||||
| Node.js (Vite) | Vitest | `npm install -D vitest` |
|
||||
| Python | pytest | `pip install pytest` |
|
||||
| Go | testing | Built-in |
|
||||
| Rust | cargo test | Built-in |
|
||||
|
||||
**3. Create config if needed:**
|
||||
- Jest: `jest.config.js` with ts-jest preset
|
||||
- Vitest: `vitest.config.ts` with test globals
|
||||
- pytest: `pytest.ini` or `pyproject.toml` section
|
||||
|
||||
**4. Verify setup:**
|
||||
```bash
|
||||
# Run empty test suite - should pass with 0 tests
|
||||
npm test # Node
|
||||
pytest # Python
|
||||
go test ./... # Go
|
||||
cargo test # Rust
|
||||
```
|
||||
|
||||
**5. Create first test file:**
|
||||
Follow project conventions for test location:
|
||||
- `*.test.ts` / `*.spec.ts` next to source
|
||||
- `__tests__/` directory
|
||||
- `tests/` directory at root
|
||||
|
||||
Framework setup is a one-time cost included in the first TDD plan's RED phase.
|
||||
</framework_setup>
|
||||
|
||||
<error_handling>
|
||||
## Error Handling
|
||||
|
||||
**Test doesn't fail in RED phase:**
|
||||
- Feature may already exist - investigate
|
||||
- Test may be wrong (not testing what you think)
|
||||
- Fix before proceeding
|
||||
|
||||
**Test doesn't pass in GREEN phase:**
|
||||
- Debug implementation
|
||||
- Don't skip to refactor
|
||||
- Keep iterating until green
|
||||
|
||||
**Tests fail in REFACTOR phase:**
|
||||
- Undo refactor
|
||||
- Commit was premature
|
||||
- Refactor in smaller steps
|
||||
|
||||
**Unrelated tests break:**
|
||||
- Stop and investigate
|
||||
- May indicate coupling issue
|
||||
- Fix before proceeding
|
||||
</error_handling>
|
||||
|
||||
<commit_pattern>
|
||||
## Commit Pattern for TDD Plans
|
||||
|
||||
TDD plans produce 2-3 atomic commits (one per phase):
|
||||
|
||||
```
|
||||
test(08-02): add failing test for email validation
|
||||
|
||||
- Tests valid email formats accepted
|
||||
- Tests invalid formats rejected
|
||||
- Tests empty input handling
|
||||
|
||||
feat(08-02): implement email validation
|
||||
|
||||
- Regex pattern matches RFC 5322
|
||||
- Returns boolean for validity
|
||||
- Handles edge cases (empty, null)
|
||||
|
||||
refactor(08-02): extract regex to constant (optional)
|
||||
|
||||
- Moved pattern to EMAIL_REGEX constant
|
||||
- No behavior changes
|
||||
- Tests still pass
|
||||
```
|
||||
|
||||
**Comparison with standard plans:**
|
||||
- Standard plans: 1 commit per task, 2-4 commits per plan
|
||||
- TDD plans: 2-3 commits for single feature
|
||||
|
||||
Both follow same format: `{type}({phase}-{plan}): {description}`
|
||||
|
||||
**Benefits:**
|
||||
- Each commit independently revertable
|
||||
- Git bisect works at commit level
|
||||
- Clear history showing TDD discipline
|
||||
- Consistent with overall commit strategy
|
||||
</commit_pattern>
|
||||
|
||||
<context_budget>
|
||||
## Context Budget
|
||||
|
||||
TDD plans target **~40% context usage** (lower than standard plans' ~50%).
|
||||
|
||||
Why lower:
|
||||
- RED phase: write test, run test, potentially debug why it didn't fail
|
||||
- GREEN phase: implement, run test, potentially iterate on failures
|
||||
- REFACTOR phase: modify code, run tests, verify no regressions
|
||||
|
||||
Each phase involves reading files, running commands, analyzing output. The back-and-forth is inherently heavier than linear task execution.
|
||||
|
||||
Single feature focus ensures full quality throughout the cycle.
|
||||
</context_budget>
|
||||
|
|
@ -0,0 +1,255 @@
|
|||
# Architecture Template
|
||||
|
||||
Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code organization.
|
||||
|
||||
**Purpose:** Document how the code is organized at a conceptual level. Complements STRUCTURE.md (which shows physical file locations).
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
# Architecture
|
||||
|
||||
**Analysis Date:** [YYYY-MM-DD]
|
||||
|
||||
## Pattern Overview
|
||||
|
||||
**Overall:** [Pattern name: e.g., "Monolithic CLI", "Serverless API", "Full-stack MVC"]
|
||||
|
||||
**Key Characteristics:**
|
||||
- [Characteristic 1: e.g., "Single executable"]
|
||||
- [Characteristic 2: e.g., "Stateless request handling"]
|
||||
- [Characteristic 3: e.g., "Event-driven"]
|
||||
|
||||
## Layers
|
||||
|
||||
[Describe the conceptual layers and their responsibilities]
|
||||
|
||||
**[Layer Name]:**
|
||||
- Purpose: [What this layer does]
|
||||
- Contains: [Types of code: e.g., "route handlers", "business logic"]
|
||||
- Depends on: [What it uses: e.g., "data layer only"]
|
||||
- Used by: [What uses it: e.g., "API routes"]
|
||||
|
||||
**[Layer Name]:**
|
||||
- Purpose: [What this layer does]
|
||||
- Contains: [Types of code]
|
||||
- Depends on: [What it uses]
|
||||
- Used by: [What uses it]
|
||||
|
||||
## Data Flow
|
||||
|
||||
[Describe the typical request/execution lifecycle]
|
||||
|
||||
**[Flow Name] (e.g., "HTTP Request", "CLI Command", "Event Processing"):**
|
||||
|
||||
1. [Entry point: e.g., "User runs command"]
|
||||
2. [Processing step: e.g., "Router matches path"]
|
||||
3. [Processing step: e.g., "Controller validates input"]
|
||||
4. [Processing step: e.g., "Service executes logic"]
|
||||
5. [Output: e.g., "Response returned"]
|
||||
|
||||
**State Management:**
|
||||
- [How state is handled: e.g., "Stateless - no persistent state", "Database per request", "In-memory cache"]
|
||||
|
||||
## Key Abstractions
|
||||
|
||||
[Core concepts/patterns used throughout the codebase]
|
||||
|
||||
**[Abstraction Name]:**
|
||||
- Purpose: [What it represents]
|
||||
- Examples: [e.g., "UserService, ProjectService"]
|
||||
- Pattern: [e.g., "Singleton", "Factory", "Repository"]
|
||||
|
||||
**[Abstraction Name]:**
|
||||
- Purpose: [What it represents]
|
||||
- Examples: [Concrete examples]
|
||||
- Pattern: [Pattern used]
|
||||
|
||||
## Entry Points
|
||||
|
||||
[Where execution begins]
|
||||
|
||||
**[Entry Point]:**
|
||||
- Location: [Brief: e.g., "src/index.ts", "API Gateway triggers"]
|
||||
- Triggers: [What invokes it: e.g., "CLI invocation", "HTTP request"]
|
||||
- Responsibilities: [What it does: e.g., "Parse args, route to command"]
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Strategy:** [How errors are handled: e.g., "Exception bubbling to top-level handler", "Per-route error middleware"]
|
||||
|
||||
**Patterns:**
|
||||
- [Pattern: e.g., "try/catch at controller level"]
|
||||
- [Pattern: e.g., "Error codes returned to user"]
|
||||
|
||||
## Cross-Cutting Concerns
|
||||
|
||||
[Aspects that affect multiple layers]
|
||||
|
||||
**Logging:**
|
||||
- [Approach: e.g., "Winston logger, injected per-request"]
|
||||
|
||||
**Validation:**
|
||||
- [Approach: e.g., "Zod schemas at API boundary"]
|
||||
|
||||
**Authentication:**
|
||||
- [Approach: e.g., "JWT middleware on protected routes"]
|
||||
|
||||
---
|
||||
|
||||
*Architecture analysis: [date]*
|
||||
*Update when major patterns change*
|
||||
```
|
||||
|
||||
<good_examples>
|
||||
```markdown
|
||||
# Architecture
|
||||
|
||||
**Analysis Date:** 2025-01-20
|
||||
|
||||
## Pattern Overview
|
||||
|
||||
**Overall:** CLI Application with Plugin System
|
||||
|
||||
**Key Characteristics:**
|
||||
- Single executable with subcommands
|
||||
- Plugin-based extensibility
|
||||
- File-based state (no database)
|
||||
- Synchronous execution model
|
||||
|
||||
## Layers
|
||||
|
||||
**Command Layer:**
|
||||
- Purpose: Parse user input and route to appropriate handler
|
||||
- Contains: Command definitions, argument parsing, help text
|
||||
- Location: `src/commands/*.ts`
|
||||
- Depends on: Service layer for business logic
|
||||
- Used by: CLI entry point (`src/index.ts`)
|
||||
|
||||
**Service Layer:**
|
||||
- Purpose: Core business logic
|
||||
- Contains: FileService, TemplateService, InstallService
|
||||
- Location: `src/services/*.ts`
|
||||
- Depends on: File system utilities, external tools
|
||||
- Used by: Command handlers
|
||||
|
||||
**Utility Layer:**
|
||||
- Purpose: Shared helpers and abstractions
|
||||
- Contains: File I/O wrappers, path resolution, string formatting
|
||||
- Location: `src/utils/*.ts`
|
||||
- Depends on: Node.js built-ins only
|
||||
- Used by: Service layer
|
||||
|
||||
## Data Flow
|
||||
|
||||
**CLI Command Execution:**
|
||||
|
||||
1. User runs: `gsd new-project`
|
||||
2. Commander parses args and flags
|
||||
3. Command handler invoked (`src/commands/new-project.ts`)
|
||||
4. Handler calls service methods (`src/services/project.ts` → `create()`)
|
||||
5. Service reads templates, processes files, writes output
|
||||
6. Results logged to console
|
||||
7. Process exits with status code
|
||||
|
||||
**State Management:**
|
||||
- File-based: All state lives in `.planning/` directory
|
||||
- No persistent in-memory state
|
||||
- Each command execution is independent
|
||||
|
||||
## Key Abstractions
|
||||
|
||||
**Service:**
|
||||
- Purpose: Encapsulate business logic for a domain
|
||||
- Examples: `src/services/file.ts`, `src/services/template.ts`, `src/services/project.ts`
|
||||
- Pattern: Singleton-like (imported as modules, not instantiated)
|
||||
|
||||
**Command:**
|
||||
- Purpose: CLI command definition
|
||||
- Examples: `src/commands/new-project.ts`, `src/commands/plan-phase.ts`
|
||||
- Pattern: Commander.js command registration
|
||||
|
||||
**Template:**
|
||||
- Purpose: Reusable document structures
|
||||
- Examples: PROJECT.md, PLAN.md templates
|
||||
- Pattern: Markdown files with substitution variables
|
||||
|
||||
## Entry Points
|
||||
|
||||
**CLI Entry:**
|
||||
- Location: `src/index.ts`
|
||||
- Triggers: User runs `gsd <command>`
|
||||
- Responsibilities: Register commands, parse args, display help
|
||||
|
||||
**Commands:**
|
||||
- Location: `src/commands/*.ts`
|
||||
- Triggers: Matched command from CLI
|
||||
- Responsibilities: Validate input, call services, format output
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Strategy:** Throw exceptions, catch at command level, log and exit
|
||||
|
||||
**Patterns:**
|
||||
- Services throw Error with descriptive messages
|
||||
- Command handlers catch, log error to stderr, exit(1)
|
||||
- Validation errors shown before execution (fail fast)
|
||||
|
||||
## Cross-Cutting Concerns
|
||||
|
||||
**Logging:**
|
||||
- Console.log for normal output
|
||||
- Console.error for errors
|
||||
- Chalk for colored output
|
||||
|
||||
**Validation:**
|
||||
- Zod schemas for config file parsing
|
||||
- Manual validation in command handlers
|
||||
- Fail fast on invalid input
|
||||
|
||||
**File Operations:**
|
||||
- FileService abstraction over fs-extra
|
||||
- All paths validated before operations
|
||||
- Atomic writes (temp file + rename)
|
||||
|
||||
---
|
||||
|
||||
*Architecture analysis: 2025-01-20*
|
||||
*Update when major patterns change*
|
||||
```
|
||||
</good_examples>
|
||||
|
||||
<guidelines>
|
||||
**What belongs in ARCHITECTURE.md:**
|
||||
- Overall architectural pattern (monolith, microservices, layered, etc.)
|
||||
- Conceptual layers and their relationships
|
||||
- Data flow / request lifecycle
|
||||
- Key abstractions and patterns
|
||||
- Entry points
|
||||
- Error handling strategy
|
||||
- Cross-cutting concerns (logging, auth, validation)
|
||||
|
||||
**What does NOT belong here:**
|
||||
- Exhaustive file listings (that's STRUCTURE.md)
|
||||
- Technology choices (that's STACK.md)
|
||||
- Line-by-line code walkthrough (defer to code reading)
|
||||
- Implementation details of specific features
|
||||
|
||||
**File paths ARE welcome:**
|
||||
Include file paths as concrete examples of abstractions. Use backtick formatting: `src/services/user.ts`. This makes the architecture document actionable for Claude when planning.
|
||||
|
||||
**When filling this template:**
|
||||
- Read main entry points (index, server, main)
|
||||
- Identify layers by reading imports/dependencies
|
||||
- Trace a typical request/command execution
|
||||
- Note recurring patterns (services, controllers, repositories)
|
||||
- Keep descriptions conceptual, not mechanical
|
||||
|
||||
**Useful for phase planning when:**
|
||||
- Adding new features (where does it fit in the layers?)
|
||||
- Refactoring (understanding current patterns)
|
||||
- Identifying where to add code (which layer handles X?)
|
||||
- Understanding dependencies between components
|
||||
</guidelines>
|
||||
|
|
@ -0,0 +1,310 @@
|
|||
# Codebase Concerns Template
|
||||
|
||||
Template for `.planning/codebase/CONCERNS.md` - captures known issues and areas requiring care.
|
||||
|
||||
**Purpose:** Surface actionable warnings about the codebase. Focused on "what to watch out for when making changes."
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
# Codebase Concerns
|
||||
|
||||
**Analysis Date:** [YYYY-MM-DD]
|
||||
|
||||
## Tech Debt
|
||||
|
||||
**[Area/Component]:**
|
||||
- Issue: [What's the shortcut/workaround]
|
||||
- Why: [Why it was done this way]
|
||||
- Impact: [What breaks or degrades because of it]
|
||||
- Fix approach: [How to properly address it]
|
||||
|
||||
**[Area/Component]:**
|
||||
- Issue: [What's the shortcut/workaround]
|
||||
- Why: [Why it was done this way]
|
||||
- Impact: [What breaks or degrades because of it]
|
||||
- Fix approach: [How to properly address it]
|
||||
|
||||
## Known Bugs
|
||||
|
||||
**[Bug description]:**
|
||||
- Symptoms: [What happens]
|
||||
- Trigger: [How to reproduce]
|
||||
- Workaround: [Temporary mitigation if any]
|
||||
- Root cause: [If known]
|
||||
- Blocked by: [If waiting on something]
|
||||
|
||||
**[Bug description]:**
|
||||
- Symptoms: [What happens]
|
||||
- Trigger: [How to reproduce]
|
||||
- Workaround: [Temporary mitigation if any]
|
||||
- Root cause: [If known]
|
||||
|
||||
## Security Considerations
|
||||
|
||||
**[Area requiring security care]:**
|
||||
- Risk: [What could go wrong]
|
||||
- Current mitigation: [What's in place now]
|
||||
- Recommendations: [What should be added]
|
||||
|
||||
**[Area requiring security care]:**
|
||||
- Risk: [What could go wrong]
|
||||
- Current mitigation: [What's in place now]
|
||||
- Recommendations: [What should be added]
|
||||
|
||||
## Performance Bottlenecks
|
||||
|
||||
**[Slow operation/endpoint]:**
|
||||
- Problem: [What's slow]
|
||||
- Measurement: [Actual numbers: "500ms p95", "2s load time"]
|
||||
- Cause: [Why it's slow]
|
||||
- Improvement path: [How to speed it up]
|
||||
|
||||
**[Slow operation/endpoint]:**
|
||||
- Problem: [What's slow]
|
||||
- Measurement: [Actual numbers]
|
||||
- Cause: [Why it's slow]
|
||||
- Improvement path: [How to speed it up]
|
||||
|
||||
## Fragile Areas
|
||||
|
||||
**[Component/Module]:**
|
||||
- Why fragile: [What makes it break easily]
|
||||
- Common failures: [What typically goes wrong]
|
||||
- Safe modification: [How to change it without breaking]
|
||||
- Test coverage: [Is it tested? Gaps?]
|
||||
|
||||
**[Component/Module]:**
|
||||
- Why fragile: [What makes it break easily]
|
||||
- Common failures: [What typically goes wrong]
|
||||
- Safe modification: [How to change it without breaking]
|
||||
- Test coverage: [Is it tested? Gaps?]
|
||||
|
||||
## Scaling Limits
|
||||
|
||||
**[Resource/System]:**
|
||||
- Current capacity: [Numbers: "100 req/sec", "10k users"]
|
||||
- Limit: [Where it breaks]
|
||||
- Symptoms at limit: [What happens]
|
||||
- Scaling path: [How to increase capacity]
|
||||
|
||||
## Dependencies at Risk
|
||||
|
||||
**[Package/Service]:**
|
||||
- Risk: [e.g., "deprecated", "unmaintained", "breaking changes coming"]
|
||||
- Impact: [What breaks if it fails]
|
||||
- Migration plan: [Alternative or upgrade path]
|
||||
|
||||
## Missing Critical Features
|
||||
|
||||
**[Feature gap]:**
|
||||
- Problem: [What's missing]
|
||||
- Current workaround: [How users cope]
|
||||
- Blocks: [What can't be done without it]
|
||||
- Implementation complexity: [Rough effort estimate]
|
||||
|
||||
## Test Coverage Gaps
|
||||
|
||||
**[Untested area]:**
|
||||
- What's not tested: [Specific functionality]
|
||||
- Risk: [What could break unnoticed]
|
||||
- Priority: [High/Medium/Low]
|
||||
- Difficulty to test: [Why it's not tested yet]
|
||||
|
||||
---
|
||||
|
||||
*Concerns audit: [date]*
|
||||
*Update as issues are fixed or new ones discovered*
|
||||
```
|
||||
|
||||
<good_examples>
|
||||
```markdown
|
||||
# Codebase Concerns
|
||||
|
||||
**Analysis Date:** 2025-01-20
|
||||
|
||||
## Tech Debt
|
||||
|
||||
**Database queries in React components:**
|
||||
- Issue: Direct Supabase queries in 15+ page components instead of server actions
|
||||
- Files: `app/dashboard/page.tsx`, `app/profile/page.tsx`, `app/courses/[id]/page.tsx`, `app/settings/page.tsx` (and 11 more in `app/`)
|
||||
- Why: Rapid prototyping during MVP phase
|
||||
- Impact: Can't implement RLS properly, exposes DB structure to client
|
||||
- Fix approach: Move all queries to server actions in `app/actions/`, add proper RLS policies
|
||||
|
||||
**Manual webhook signature validation:**
|
||||
- Issue: Copy-pasted Stripe webhook verification code in 3 different endpoints
|
||||
- Files: `app/api/webhooks/stripe/route.ts`, `app/api/webhooks/checkout/route.ts`, `app/api/webhooks/subscription/route.ts`
|
||||
- Why: Each webhook added ad-hoc without abstraction
|
||||
- Impact: Easy to miss verification in new webhooks (security risk)
|
||||
- Fix approach: Create shared `lib/stripe/validate-webhook.ts` middleware
|
||||
|
||||
## Known Bugs
|
||||
|
||||
**Race condition in subscription updates:**
|
||||
- Symptoms: User shows as "free" tier for 5-10 seconds after successful payment
|
||||
- Trigger: Fast navigation after Stripe checkout redirect, before webhook processes
|
||||
- Files: `app/checkout/success/page.tsx` (redirect handler), `app/api/webhooks/stripe/route.ts` (webhook)
|
||||
- Workaround: Stripe webhook eventually updates status (self-heals)
|
||||
- Root cause: Webhook processing slower than user navigation, no optimistic UI update
|
||||
- Fix: Add polling in `app/checkout/success/page.tsx` after redirect
|
||||
|
||||
**Inconsistent session state after logout:**
|
||||
- Symptoms: User redirected to /dashboard after logout instead of /login
|
||||
- Trigger: Logout via button in mobile nav (desktop works fine)
|
||||
- File: `components/MobileNav.tsx` (line ~45, logout handler)
|
||||
- Workaround: Manual URL navigation to /login works
|
||||
- Root cause: Mobile nav component not awaiting supabase.auth.signOut()
|
||||
- Fix: Add await to logout handler in `components/MobileNav.tsx`
|
||||
|
||||
## Security Considerations
|
||||
|
||||
**Admin role check client-side only:**
|
||||
- Risk: Admin dashboard pages check isAdmin from Supabase client, no server verification
|
||||
- Files: `app/admin/page.tsx`, `app/admin/users/page.tsx`, `components/AdminGuard.tsx`
|
||||
- Current mitigation: None (relying on UI hiding)
|
||||
- Recommendations: Add middleware to admin routes in `middleware.ts`, verify role server-side
|
||||
|
||||
**Unvalidated file uploads:**
|
||||
- Risk: Users can upload any file type to avatar bucket (no size/type validation)
|
||||
- File: `components/AvatarUpload.tsx` (upload handler)
|
||||
- Current mitigation: Supabase bucket limits to 2MB (configured in dashboard)
|
||||
- Recommendations: Add file type validation (image/* only) in `lib/storage/validate.ts`
|
||||
|
||||
## Performance Bottlenecks
|
||||
|
||||
**/api/courses endpoint:**
|
||||
- Problem: Fetching all courses with nested lessons and authors
|
||||
- File: `app/api/courses/route.ts`
|
||||
- Measurement: 1.2s p95 response time with 50+ courses
|
||||
- Cause: N+1 query pattern (separate query per course for lessons)
|
||||
- Improvement path: Use Prisma include to eager-load lessons in `lib/db/courses.ts`, add Redis caching
|
||||
|
||||
**Dashboard initial load:**
|
||||
- Problem: Waterfall of 5 serial API calls on mount
|
||||
- File: `app/dashboard/page.tsx`
|
||||
- Measurement: 3.5s until interactive on slow 3G
|
||||
- Cause: Each component fetches own data independently
|
||||
- Improvement path: Convert to Server Component with single parallel fetch
|
||||
|
||||
## Fragile Areas
|
||||
|
||||
**Authentication middleware chain:**
|
||||
- File: `middleware.ts`
|
||||
- Why fragile: 4 different middleware functions run in specific order (auth -> role -> subscription -> logging)
|
||||
- Common failures: Middleware order change breaks everything, hard to debug
|
||||
- Safe modification: Add tests before changing order, document dependencies in comments
|
||||
- Test coverage: No integration tests for middleware chain (only unit tests)
|
||||
|
||||
**Stripe webhook event handling:**
|
||||
- File: `app/api/webhooks/stripe/route.ts`
|
||||
- Why fragile: Giant switch statement with 12 event types, shared transaction logic
|
||||
- Common failures: New event type added without handling, partial DB updates on error
|
||||
- Safe modification: Extract each event handler to `lib/stripe/handlers/*.ts`
|
||||
- Test coverage: Only 3 of 12 event types have tests
|
||||
|
||||
## Scaling Limits
|
||||
|
||||
**Supabase Free Tier:**
|
||||
- Current capacity: 500MB database, 1GB file storage, 2GB bandwidth/month
|
||||
- Limit: ~5000 users estimated before hitting limits
|
||||
- Symptoms at limit: 429 rate limit errors, DB writes fail
|
||||
- Scaling path: Upgrade to Pro ($25/mo) extends to 8GB DB, 100GB storage
|
||||
|
||||
**Server-side render blocking:**
|
||||
- Current capacity: ~50 concurrent users before slowdown
|
||||
- Limit: Vercel Hobby plan (10s function timeout, 100GB-hrs/mo)
|
||||
- Symptoms at limit: 504 gateway timeouts on course pages
|
||||
- Scaling path: Upgrade to Vercel Pro ($20/mo), add edge caching
|
||||
|
||||
## Dependencies at Risk
|
||||
|
||||
**react-hot-toast:**
|
||||
- Risk: Unmaintained (last update 18 months ago), React 19 compatibility unknown
|
||||
- Impact: Toast notifications break, no graceful degradation
|
||||
- Migration plan: Switch to sonner (actively maintained, similar API)
|
||||
|
||||
## Missing Critical Features
|
||||
|
||||
**Payment failure handling:**
|
||||
- Problem: No retry mechanism or user notification when subscription payment fails
|
||||
- Current workaround: Users manually re-enter payment info (if they notice)
|
||||
- Blocks: Can't retain users with expired cards, no dunning process
|
||||
- Implementation complexity: Medium (Stripe webhooks + email flow + UI)
|
||||
|
||||
**Course progress tracking:**
|
||||
- Problem: No persistent state for which lessons completed
|
||||
- Current workaround: Users manually track progress
|
||||
- Blocks: Can't show completion percentage, can't recommend next lesson
|
||||
- Implementation complexity: Low (add completed_lessons junction table)
|
||||
|
||||
## Test Coverage Gaps
|
||||
|
||||
**Payment flow end-to-end:**
|
||||
- What's not tested: Full Stripe checkout -> webhook -> subscription activation flow
|
||||
- Risk: Payment processing could break silently (has happened twice)
|
||||
- Priority: High
|
||||
- Difficulty to test: Need Stripe test fixtures and webhook simulation setup
|
||||
|
||||
**Error boundary behavior:**
|
||||
- What's not tested: How app behaves when components throw errors
|
||||
- Risk: White screen of death for users, no error reporting
|
||||
- Priority: Medium
|
||||
- Difficulty to test: Need to intentionally trigger errors in test environment
|
||||
|
||||
---
|
||||
|
||||
*Concerns audit: 2025-01-20*
|
||||
*Update as issues are fixed or new ones discovered*
|
||||
```
|
||||
</good_examples>
|
||||
|
||||
<guidelines>
|
||||
**What belongs in CONCERNS.md:**
|
||||
- Tech debt with clear impact and fix approach
|
||||
- Known bugs with reproduction steps
|
||||
- Security gaps and mitigation recommendations
|
||||
- Performance bottlenecks with measurements
|
||||
- Fragile code that breaks easily
|
||||
- Scaling limits with numbers
|
||||
- Dependencies that need attention
|
||||
- Missing features that block workflows
|
||||
- Test coverage gaps
|
||||
|
||||
**What does NOT belong here:**
|
||||
- Opinions without evidence ("code is messy")
|
||||
- Complaints without solutions ("auth sucks")
|
||||
- Future feature ideas (that's for product planning)
|
||||
- Normal TODOs (those live in code comments)
|
||||
- Architectural decisions that are working fine
|
||||
- Minor code style issues
|
||||
|
||||
**When filling this template:**
|
||||
- **Always include file paths** - Concerns without locations are not actionable. Use backticks: `src/file.ts`
|
||||
- Be specific with measurements ("500ms p95" not "slow")
|
||||
- Include reproduction steps for bugs
|
||||
- Suggest fix approaches, not just problems
|
||||
- Focus on actionable items
|
||||
- Prioritize by risk/impact
|
||||
- Update as issues get resolved
|
||||
- Add new concerns as discovered
|
||||
|
||||
**Tone guidelines:**
|
||||
- Professional, not emotional ("N+1 query pattern" not "terrible queries")
|
||||
- Solution-oriented ("Fix: add index" not "needs fixing")
|
||||
- Risk-focused ("Could expose user data" not "security is bad")
|
||||
- Factual ("3.5s load time" not "really slow")
|
||||
|
||||
**Useful for phase planning when:**
|
||||
- Deciding what to work on next
|
||||
- Estimating risk of changes
|
||||
- Understanding where to be careful
|
||||
- Prioritizing improvements
|
||||
- Onboarding new Claude contexts
|
||||
- Planning refactoring work
|
||||
|
||||
**How this gets populated:**
|
||||
Explore agents detect these during codebase mapping. Manual additions welcome for human-discovered issues. This is living documentation, not a complaint list.
|
||||
</guidelines>
|
||||
|
|
@ -0,0 +1,307 @@
|
|||
# Coding Conventions Template
|
||||
|
||||
Template for `.planning/codebase/CONVENTIONS.md` - captures coding style and patterns.
|
||||
|
||||
**Purpose:** Document how code is written in this codebase. Prescriptive guide for Claude to match existing style.
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
# Coding Conventions
|
||||
|
||||
**Analysis Date:** [YYYY-MM-DD]
|
||||
|
||||
## Naming Patterns
|
||||
|
||||
**Files:**
|
||||
- [Pattern: e.g., "kebab-case for all files"]
|
||||
- [Test files: e.g., "*.test.ts alongside source"]
|
||||
- [Components: e.g., "PascalCase.tsx for React components"]
|
||||
|
||||
**Functions:**
|
||||
- [Pattern: e.g., "camelCase for all functions"]
|
||||
- [Async: e.g., "no special prefix for async functions"]
|
||||
- [Handlers: e.g., "handleEventName for event handlers"]
|
||||
|
||||
**Variables:**
|
||||
- [Pattern: e.g., "camelCase for variables"]
|
||||
- [Constants: e.g., "UPPER_SNAKE_CASE for constants"]
|
||||
- [Private: e.g., "_prefix for private members" or "no prefix"]
|
||||
|
||||
**Types:**
|
||||
- [Interfaces: e.g., "PascalCase, no I prefix"]
|
||||
- [Types: e.g., "PascalCase for type aliases"]
|
||||
- [Enums: e.g., "PascalCase for enum name, UPPER_CASE for values"]
|
||||
|
||||
## Code Style
|
||||
|
||||
**Formatting:**
|
||||
- [Tool: e.g., "Prettier with config in .prettierrc"]
|
||||
- [Line length: e.g., "100 characters max"]
|
||||
- [Quotes: e.g., "single quotes for strings"]
|
||||
- [Semicolons: e.g., "required" or "omitted"]
|
||||
|
||||
**Linting:**
|
||||
- [Tool: e.g., "ESLint with eslint.config.js"]
|
||||
- [Rules: e.g., "extends airbnb-base, no console in production"]
|
||||
- [Run: e.g., "npm run lint"]
|
||||
|
||||
## Import Organization
|
||||
|
||||
**Order:**
|
||||
1. [e.g., "External packages (react, express, etc.)"]
|
||||
2. [e.g., "Internal modules (@/lib, @/components)"]
|
||||
3. [e.g., "Relative imports (., ..)"]
|
||||
4. [e.g., "Type imports (import type {})"]
|
||||
|
||||
**Grouping:**
|
||||
- [Blank lines: e.g., "blank line between groups"]
|
||||
- [Sorting: e.g., "alphabetical within each group"]
|
||||
|
||||
**Path Aliases:**
|
||||
- [Aliases used: e.g., "@/ for src/, @components/ for src/components/"]
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Patterns:**
|
||||
- [Strategy: e.g., "throw errors, catch at boundaries"]
|
||||
- [Custom errors: e.g., "extend Error class, named *Error"]
|
||||
- [Async: e.g., "use try/catch, no .catch() chains"]
|
||||
|
||||
**Error Types:**
|
||||
- [When to throw: e.g., "invalid input, missing dependencies"]
|
||||
- [When to return: e.g., "expected failures return Result<T, E>"]
|
||||
- [Logging: e.g., "log error with context before throwing"]
|
||||
|
||||
## Logging
|
||||
|
||||
**Framework:**
|
||||
- [Tool: e.g., "console.log, pino, winston"]
|
||||
- [Levels: e.g., "debug, info, warn, error"]
|
||||
|
||||
**Patterns:**
|
||||
- [Format: e.g., "structured logging with context object"]
|
||||
- [When: e.g., "log state transitions, external calls"]
|
||||
- [Where: e.g., "log at service boundaries, not in utils"]
|
||||
|
||||
## Comments
|
||||
|
||||
**When to Comment:**
|
||||
- [e.g., "explain why, not what"]
|
||||
- [e.g., "document business logic, algorithms, edge cases"]
|
||||
- [e.g., "avoid obvious comments like // increment counter"]
|
||||
|
||||
**JSDoc/TSDoc:**
|
||||
- [Usage: e.g., "required for public APIs, optional for internal"]
|
||||
- [Format: e.g., "use @param, @returns, @throws tags"]
|
||||
|
||||
**TODO Comments:**
|
||||
- [Pattern: e.g., "// TODO(username): description"]
|
||||
- [Tracking: e.g., "link to issue number if available"]
|
||||
|
||||
## Function Design
|
||||
|
||||
**Size:**
|
||||
- [e.g., "keep under 50 lines, extract helpers"]
|
||||
|
||||
**Parameters:**
|
||||
- [e.g., "max 3 parameters, use object for more"]
|
||||
- [e.g., "destructure objects in parameter list"]
|
||||
|
||||
**Return Values:**
|
||||
- [e.g., "explicit returns, no implicit undefined"]
|
||||
- [e.g., "return early for guard clauses"]
|
||||
|
||||
## Module Design
|
||||
|
||||
**Exports:**
|
||||
- [e.g., "named exports preferred, default exports for React components"]
|
||||
- [e.g., "export from index.ts for public API"]
|
||||
|
||||
**Barrel Files:**
|
||||
- [e.g., "use index.ts to re-export public API"]
|
||||
- [e.g., "avoid circular dependencies"]
|
||||
|
||||
---
|
||||
|
||||
*Convention analysis: [date]*
|
||||
*Update when patterns change*
|
||||
```
|
||||
|
||||
<good_examples>
|
||||
```markdown
|
||||
# Coding Conventions
|
||||
|
||||
**Analysis Date:** 2025-01-20
|
||||
|
||||
## Naming Patterns
|
||||
|
||||
**Files:**
|
||||
- kebab-case for all files (command-handler.ts, user-service.ts)
|
||||
- *.test.ts alongside source files
|
||||
- index.ts for barrel exports
|
||||
|
||||
**Functions:**
|
||||
- camelCase for all functions
|
||||
- No special prefix for async functions
|
||||
- handleEventName for event handlers (handleClick, handleSubmit)
|
||||
|
||||
**Variables:**
|
||||
- camelCase for variables
|
||||
- UPPER_SNAKE_CASE for constants (MAX_RETRIES, API_BASE_URL)
|
||||
- No underscore prefix (no private marker in TS)
|
||||
|
||||
**Types:**
|
||||
- PascalCase for interfaces, no I prefix (User, not IUser)
|
||||
- PascalCase for type aliases (UserConfig, ResponseData)
|
||||
- PascalCase for enum names, UPPER_CASE for values (Status.PENDING)
|
||||
|
||||
## Code Style
|
||||
|
||||
**Formatting:**
|
||||
- Prettier with .prettierrc
|
||||
- 100 character line length
|
||||
- Single quotes for strings
|
||||
- Semicolons required
|
||||
- 2 space indentation
|
||||
|
||||
**Linting:**
|
||||
- ESLint with eslint.config.js
|
||||
- Extends @typescript-eslint/recommended
|
||||
- No console.log in production code (use logger)
|
||||
- Run: npm run lint
|
||||
|
||||
## Import Organization
|
||||
|
||||
**Order:**
|
||||
1. External packages (react, express, commander)
|
||||
2. Internal modules (@/lib, @/services)
|
||||
3. Relative imports (./utils, ../types)
|
||||
4. Type imports (import type { User })
|
||||
|
||||
**Grouping:**
|
||||
- Blank line between groups
|
||||
- Alphabetical within each group
|
||||
- Type imports last within each group
|
||||
|
||||
**Path Aliases:**
|
||||
- @/ maps to src/
|
||||
- No other aliases defined
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Patterns:**
|
||||
- Throw errors, catch at boundaries (route handlers, main functions)
|
||||
- Extend Error class for custom errors (ValidationError, NotFoundError)
|
||||
- Async functions use try/catch, no .catch() chains
|
||||
|
||||
**Error Types:**
|
||||
- Throw on invalid input, missing dependencies, invariant violations
|
||||
- Log error with context before throwing: logger.error({ err, userId }, 'Failed to process')
|
||||
- Include cause in error message: new Error('Failed to X', { cause: originalError })
|
||||
|
||||
## Logging
|
||||
|
||||
**Framework:**
|
||||
- pino logger instance exported from lib/logger.ts
|
||||
- Levels: debug, info, warn, error (no trace)
|
||||
|
||||
**Patterns:**
|
||||
- Structured logging with context: logger.info({ userId, action }, 'User action')
|
||||
- Log at service boundaries, not in utility functions
|
||||
- Log state transitions, external API calls, errors
|
||||
- No console.log in committed code
|
||||
|
||||
## Comments
|
||||
|
||||
**When to Comment:**
|
||||
- Explain why, not what: // Retry 3 times because API has transient failures
|
||||
- Document business rules: // Users must verify email within 24 hours
|
||||
- Explain non-obvious algorithms or workarounds
|
||||
- Avoid obvious comments: // set count to 0
|
||||
|
||||
**JSDoc/TSDoc:**
|
||||
- Required for public API functions
|
||||
- Optional for internal functions if signature is self-explanatory
|
||||
- Use @param, @returns, @throws tags
|
||||
|
||||
**TODO Comments:**
|
||||
- Format: // TODO: description (no username, using git blame)
|
||||
- Link to issue if exists: // TODO: Fix race condition (issue #123)
|
||||
|
||||
## Function Design
|
||||
|
||||
**Size:**
|
||||
- Keep under 50 lines
|
||||
- Extract helpers for complex logic
|
||||
- One level of abstraction per function
|
||||
|
||||
**Parameters:**
|
||||
- Max 3 parameters
|
||||
- Use options object for 4+ parameters: function create(options: CreateOptions)
|
||||
- Destructure in parameter list: function process({ id, name }: ProcessParams)
|
||||
|
||||
**Return Values:**
|
||||
- Explicit return statements
|
||||
- Return early for guard clauses
|
||||
- Use Result<T, E> type for expected failures
|
||||
|
||||
## Module Design
|
||||
|
||||
**Exports:**
|
||||
- Named exports preferred
|
||||
- Default exports only for React components
|
||||
- Export public API from index.ts barrel files
|
||||
|
||||
**Barrel Files:**
|
||||
- index.ts re-exports public API
|
||||
- Keep internal helpers private (don't export from index)
|
||||
- Avoid circular dependencies (import from specific files if needed)
|
||||
|
||||
---
|
||||
|
||||
*Convention analysis: 2025-01-20*
|
||||
*Update when patterns change*
|
||||
```
|
||||
</good_examples>
|
||||
|
||||
<guidelines>
|
||||
**What belongs in CONVENTIONS.md:**
|
||||
- Naming patterns observed in the codebase
|
||||
- Formatting rules (Prettier config, linting rules)
|
||||
- Import organization patterns
|
||||
- Error handling strategy
|
||||
- Logging approach
|
||||
- Comment conventions
|
||||
- Function and module design patterns
|
||||
|
||||
**What does NOT belong here:**
|
||||
- Architecture decisions (that's ARCHITECTURE.md)
|
||||
- Technology choices (that's STACK.md)
|
||||
- Test patterns (that's TESTING.md)
|
||||
- File organization (that's STRUCTURE.md)
|
||||
|
||||
**When filling this template:**
|
||||
- Check .prettierrc, .eslintrc, or similar config files
|
||||
- Examine 5-10 representative source files for patterns
|
||||
- Look for consistency: if 80%+ follows a pattern, document it
|
||||
- Be prescriptive: "Use X" not "Sometimes Y is used"
|
||||
- Note deviations: "Legacy code uses Y, new code should use X"
|
||||
- Keep under ~150 lines total
|
||||
|
||||
**Useful for phase planning when:**
|
||||
- Writing new code (match existing style)
|
||||
- Adding features (follow naming patterns)
|
||||
- Refactoring (apply consistent conventions)
|
||||
- Code review (check against documented patterns)
|
||||
- Onboarding (understand style expectations)
|
||||
|
||||
**Analysis approach:**
|
||||
- Scan src/ directory for file naming patterns
|
||||
- Check package.json scripts for lint/format commands
|
||||
- Read 5-10 files to identify function naming, error handling
|
||||
- Look for config files (.prettierrc, eslint.config.js)
|
||||
- Note patterns in imports, comments, function signatures
|
||||
</guidelines>
|
||||
|
|
@ -0,0 +1,280 @@
|
|||
# External Integrations Template
|
||||
|
||||
Template for `.planning/codebase/INTEGRATIONS.md` - captures external service dependencies.
|
||||
|
||||
**Purpose:** Document what external systems this codebase communicates with. Focused on "what lives outside our code that we depend on."
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
# External Integrations
|
||||
|
||||
**Analysis Date:** [YYYY-MM-DD]
|
||||
|
||||
## APIs & External Services
|
||||
|
||||
**Payment Processing:**
|
||||
- [Service] - [What it's used for: e.g., "subscription billing, one-time payments"]
|
||||
- SDK/Client: [e.g., "stripe npm package v14.x"]
|
||||
- Auth: [e.g., "API key in STRIPE_SECRET_KEY env var"]
|
||||
- Endpoints used: [e.g., "checkout sessions, webhooks"]
|
||||
|
||||
**Email/SMS:**
|
||||
- [Service] - [What it's used for: e.g., "transactional emails"]
|
||||
- SDK/Client: [e.g., "sendgrid/mail v8.x"]
|
||||
- Auth: [e.g., "API key in SENDGRID_API_KEY env var"]
|
||||
- Templates: [e.g., "managed in SendGrid dashboard"]
|
||||
|
||||
**External APIs:**
|
||||
- [Service] - [What it's used for]
|
||||
- Integration method: [e.g., "REST API via fetch", "GraphQL client"]
|
||||
- Auth: [e.g., "OAuth2 token in AUTH_TOKEN env var"]
|
||||
- Rate limits: [if applicable]
|
||||
|
||||
## Data Storage
|
||||
|
||||
**Databases:**
|
||||
- [Type/Provider] - [e.g., "PostgreSQL on Supabase"]
|
||||
- Connection: [e.g., "via DATABASE_URL env var"]
|
||||
- Client: [e.g., "Prisma ORM v5.x"]
|
||||
- Migrations: [e.g., "prisma migrate in migrations/"]
|
||||
|
||||
**File Storage:**
|
||||
- [Service] - [e.g., "AWS S3 for user uploads"]
|
||||
- SDK/Client: [e.g., "@aws-sdk/client-s3"]
|
||||
- Auth: [e.g., "IAM credentials in AWS_* env vars"]
|
||||
- Buckets: [e.g., "prod-uploads, dev-uploads"]
|
||||
|
||||
**Caching:**
|
||||
- [Service] - [e.g., "Redis for session storage"]
|
||||
- Connection: [e.g., "REDIS_URL env var"]
|
||||
- Client: [e.g., "ioredis v5.x"]
|
||||
|
||||
## Authentication & Identity
|
||||
|
||||
**Auth Provider:**
|
||||
- [Service] - [e.g., "Supabase Auth", "Auth0", "custom JWT"]
|
||||
- Implementation: [e.g., "Supabase client SDK"]
|
||||
- Token storage: [e.g., "httpOnly cookies", "localStorage"]
|
||||
- Session management: [e.g., "JWT refresh tokens"]
|
||||
|
||||
**OAuth Integrations:**
|
||||
- [Provider] - [e.g., "Google OAuth for sign-in"]
|
||||
- Credentials: [e.g., "GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET"]
|
||||
- Scopes: [e.g., "email, profile"]
|
||||
|
||||
## Monitoring & Observability
|
||||
|
||||
**Error Tracking:**
|
||||
- [Service] - [e.g., "Sentry"]
|
||||
- DSN: [e.g., "SENTRY_DSN env var"]
|
||||
- Release tracking: [e.g., "via SENTRY_RELEASE"]
|
||||
|
||||
**Analytics:**
|
||||
- [Service] - [e.g., "Mixpanel for product analytics"]
|
||||
- Token: [e.g., "MIXPANEL_TOKEN env var"]
|
||||
- Events tracked: [e.g., "user actions, page views"]
|
||||
|
||||
**Logs:**
|
||||
- [Service] - [e.g., "CloudWatch", "Datadog", "none (stdout only)"]
|
||||
- Integration: [e.g., "AWS Lambda built-in"]
|
||||
|
||||
## CI/CD & Deployment
|
||||
|
||||
**Hosting:**
|
||||
- [Platform] - [e.g., "Vercel", "AWS Lambda", "Docker on ECS"]
|
||||
- Deployment: [e.g., "automatic on main branch push"]
|
||||
- Environment vars: [e.g., "configured in Vercel dashboard"]
|
||||
|
||||
**CI Pipeline:**
|
||||
- [Service] - [e.g., "GitHub Actions"]
|
||||
- Workflows: [e.g., "test.yml, deploy.yml"]
|
||||
- Secrets: [e.g., "stored in GitHub repo secrets"]
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
**Development:**
|
||||
- Required env vars: [List critical vars]
|
||||
- Secrets location: [e.g., ".env.local (gitignored)", "1Password vault"]
|
||||
- Mock/stub services: [e.g., "Stripe test mode", "local PostgreSQL"]
|
||||
|
||||
**Staging:**
|
||||
- Environment-specific differences: [e.g., "uses staging Stripe account"]
|
||||
- Data: [e.g., "separate staging database"]
|
||||
|
||||
**Production:**
|
||||
- Secrets management: [e.g., "Vercel environment variables"]
|
||||
- Failover/redundancy: [e.g., "multi-region DB replication"]
|
||||
|
||||
## Webhooks & Callbacks
|
||||
|
||||
**Incoming:**
|
||||
- [Service] - [Endpoint: e.g., "/api/webhooks/stripe"]
|
||||
- Verification: [e.g., "signature validation via stripe.webhooks.constructEvent"]
|
||||
- Events: [e.g., "payment_intent.succeeded, customer.subscription.updated"]
|
||||
|
||||
**Outgoing:**
|
||||
- [Service] - [What triggers it]
|
||||
- Endpoint: [e.g., "external CRM webhook on user signup"]
|
||||
- Retry logic: [if applicable]
|
||||
|
||||
---
|
||||
|
||||
*Integration audit: [date]*
|
||||
*Update when adding/removing external services*
|
||||
```
|
||||
|
||||
<good_examples>
|
||||
```markdown
|
||||
# External Integrations
|
||||
|
||||
**Analysis Date:** 2025-01-20
|
||||
|
||||
## APIs & External Services
|
||||
|
||||
**Payment Processing:**
|
||||
- Stripe - Subscription billing and one-time course payments
|
||||
- SDK/Client: stripe npm package v14.8
|
||||
- Auth: API key in STRIPE_SECRET_KEY env var
|
||||
- Endpoints used: checkout sessions, customer portal, webhooks
|
||||
|
||||
**Email/SMS:**
|
||||
- SendGrid - Transactional emails (receipts, password resets)
|
||||
- SDK/Client: @sendgrid/mail v8.1
|
||||
- Auth: API key in SENDGRID_API_KEY env var
|
||||
- Templates: Managed in SendGrid dashboard (template IDs in code)
|
||||
|
||||
**External APIs:**
|
||||
- OpenAI API - Course content generation
|
||||
- Integration method: REST API via openai npm package v4.x
|
||||
- Auth: Bearer token in OPENAI_API_KEY env var
|
||||
- Rate limits: 3500 requests/min (tier 3)
|
||||
|
||||
## Data Storage
|
||||
|
||||
**Databases:**
|
||||
- PostgreSQL on Supabase - Primary data store
|
||||
- Connection: via DATABASE_URL env var
|
||||
- Client: Prisma ORM v5.8
|
||||
- Migrations: prisma migrate in prisma/migrations/
|
||||
|
||||
**File Storage:**
|
||||
- Supabase Storage - User uploads (profile images, course materials)
|
||||
- SDK/Client: @supabase/supabase-js v2.x
|
||||
- Auth: Service role key in SUPABASE_SERVICE_ROLE_KEY
|
||||
- Buckets: avatars (public), course-materials (private)
|
||||
|
||||
**Caching:**
|
||||
- None currently (all database queries, no Redis)
|
||||
|
||||
## Authentication & Identity
|
||||
|
||||
**Auth Provider:**
|
||||
- Supabase Auth - Email/password + OAuth
|
||||
- Implementation: Supabase client SDK with server-side session management
|
||||
- Token storage: httpOnly cookies via @supabase/ssr
|
||||
- Session management: JWT refresh tokens handled by Supabase
|
||||
|
||||
**OAuth Integrations:**
|
||||
- Google OAuth - Social sign-in
|
||||
- Credentials: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET (Supabase dashboard)
|
||||
- Scopes: email, profile
|
||||
|
||||
## Monitoring & Observability
|
||||
|
||||
**Error Tracking:**
|
||||
- Sentry - Server and client errors
|
||||
- DSN: SENTRY_DSN env var
|
||||
- Release tracking: Git commit SHA via SENTRY_RELEASE
|
||||
|
||||
**Analytics:**
|
||||
- None (planned: Mixpanel)
|
||||
|
||||
**Logs:**
|
||||
- Vercel logs - stdout/stderr only
|
||||
- Retention: 7 days on Pro plan
|
||||
|
||||
## CI/CD & Deployment
|
||||
|
||||
**Hosting:**
|
||||
- Vercel - Next.js app hosting
|
||||
- Deployment: Automatic on main branch push
|
||||
- Environment vars: Configured in Vercel dashboard (synced to .env.example)
|
||||
|
||||
**CI Pipeline:**
|
||||
- GitHub Actions - Tests and type checking
|
||||
- Workflows: .github/workflows/ci.yml
|
||||
- Secrets: None needed (public repo tests only)
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
**Development:**
|
||||
- Required env vars: DATABASE_URL, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY
|
||||
- Secrets location: .env.local (gitignored), team shared via 1Password vault
|
||||
- Mock/stub services: Stripe test mode, Supabase local dev project
|
||||
|
||||
**Staging:**
|
||||
- Uses separate Supabase staging project
|
||||
- Stripe test mode
|
||||
- Same Vercel account, different environment
|
||||
|
||||
**Production:**
|
||||
- Secrets management: Vercel environment variables
|
||||
- Database: Supabase production project with daily backups
|
||||
|
||||
## Webhooks & Callbacks
|
||||
|
||||
**Incoming:**
|
||||
- Stripe - /api/webhooks/stripe
|
||||
- Verification: Signature validation via stripe.webhooks.constructEvent
|
||||
- Events: payment_intent.succeeded, customer.subscription.updated, customer.subscription.deleted
|
||||
|
||||
**Outgoing:**
|
||||
- None
|
||||
|
||||
---
|
||||
|
||||
*Integration audit: 2025-01-20*
|
||||
*Update when adding/removing external services*
|
||||
```
|
||||
</good_examples>
|
||||
|
||||
<guidelines>
|
||||
**What belongs in INTEGRATIONS.md:**
|
||||
- External services the code communicates with
|
||||
- Authentication patterns (where secrets live, not the secrets themselves)
|
||||
- SDKs and client libraries used
|
||||
- Environment variable names (not values)
|
||||
- Webhook endpoints and verification methods
|
||||
- Database connection patterns
|
||||
- File storage locations
|
||||
- Monitoring and logging services
|
||||
|
||||
**What does NOT belong here:**
|
||||
- Actual API keys or secrets (NEVER write these)
|
||||
- Internal architecture (that's ARCHITECTURE.md)
|
||||
- Code patterns (that's PATTERNS.md)
|
||||
- Technology choices (that's STACK.md)
|
||||
- Performance issues (that's CONCERNS.md)
|
||||
|
||||
**When filling this template:**
|
||||
- Check .env.example or .env.template for required env vars
|
||||
- Look for SDK imports (stripe, @sendgrid/mail, etc.)
|
||||
- Check for webhook handlers in routes/endpoints
|
||||
- Note where secrets are managed (not the secrets)
|
||||
- Document environment-specific differences (dev/staging/prod)
|
||||
- Include auth patterns for each service
|
||||
|
||||
**Useful for phase planning when:**
|
||||
- Adding new external service integrations
|
||||
- Debugging authentication issues
|
||||
- Understanding data flow outside the application
|
||||
- Setting up new environments
|
||||
- Auditing third-party dependencies
|
||||
- Planning for service outages or migrations
|
||||
|
||||
**Security note:**
|
||||
Document WHERE secrets live (env vars, Vercel dashboard, 1Password), never WHAT the secrets are.
|
||||
</guidelines>
|
||||
|
|
@ -0,0 +1,186 @@
|
|||
# Technology Stack Template
|
||||
|
||||
Template for `.planning/codebase/STACK.md` - captures the technology foundation.
|
||||
|
||||
**Purpose:** Document what technologies run this codebase. Focused on "what executes when you run the code."
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
# Technology Stack
|
||||
|
||||
**Analysis Date:** [YYYY-MM-DD]
|
||||
|
||||
## Languages
|
||||
|
||||
**Primary:**
|
||||
- [Language] [Version] - [Where used: e.g., "all application code"]
|
||||
|
||||
**Secondary:**
|
||||
- [Language] [Version] - [Where used: e.g., "build scripts, tooling"]
|
||||
|
||||
## Runtime
|
||||
|
||||
**Environment:**
|
||||
- [Runtime] [Version] - [e.g., "Node.js 20.x"]
|
||||
- [Additional requirements if any]
|
||||
|
||||
**Package Manager:**
|
||||
- [Manager] [Version] - [e.g., "npm 10.x"]
|
||||
- Lockfile: [e.g., "package-lock.json present"]
|
||||
|
||||
## Frameworks
|
||||
|
||||
**Core:**
|
||||
- [Framework] [Version] - [Purpose: e.g., "web server", "UI framework"]
|
||||
|
||||
**Testing:**
|
||||
- [Framework] [Version] - [e.g., "Jest for unit tests"]
|
||||
- [Framework] [Version] - [e.g., "Playwright for E2E"]
|
||||
|
||||
**Build/Dev:**
|
||||
- [Tool] [Version] - [e.g., "Vite for bundling"]
|
||||
- [Tool] [Version] - [e.g., "TypeScript compiler"]
|
||||
|
||||
## Key Dependencies
|
||||
|
||||
[Only include dependencies critical to understanding the stack - limit to 5-10 most important]
|
||||
|
||||
**Critical:**
|
||||
- [Package] [Version] - [Why it matters: e.g., "authentication", "database access"]
|
||||
- [Package] [Version] - [Why it matters]
|
||||
|
||||
**Infrastructure:**
|
||||
- [Package] [Version] - [e.g., "Express for HTTP routing"]
|
||||
- [Package] [Version] - [e.g., "PostgreSQL client"]
|
||||
|
||||
## Configuration
|
||||
|
||||
**Environment:**
|
||||
- [How configured: e.g., ".env files", "environment variables"]
|
||||
- [Key configs: e.g., "DATABASE_URL, API_KEY required"]
|
||||
|
||||
**Build:**
|
||||
- [Build config files: e.g., "vite.config.ts, tsconfig.json"]
|
||||
|
||||
## Platform Requirements
|
||||
|
||||
**Development:**
|
||||
- [OS requirements or "any platform"]
|
||||
- [Additional tooling: e.g., "Docker for local DB"]
|
||||
|
||||
**Production:**
|
||||
- [Deployment target: e.g., "Vercel", "AWS Lambda", "Docker container"]
|
||||
- [Version requirements]
|
||||
|
||||
---
|
||||
|
||||
*Stack analysis: [date]*
|
||||
*Update after major dependency changes*
|
||||
```
|
||||
|
||||
<good_examples>
|
||||
```markdown
|
||||
# Technology Stack
|
||||
|
||||
**Analysis Date:** 2025-01-20
|
||||
|
||||
## Languages
|
||||
|
||||
**Primary:**
|
||||
- TypeScript 5.3 - All application code
|
||||
|
||||
**Secondary:**
|
||||
- JavaScript - Build scripts, config files
|
||||
|
||||
## Runtime
|
||||
|
||||
**Environment:**
|
||||
- Node.js 20.x (LTS)
|
||||
- No browser runtime (CLI tool only)
|
||||
|
||||
**Package Manager:**
|
||||
- npm 10.x
|
||||
- Lockfile: `package-lock.json` present
|
||||
|
||||
## Frameworks
|
||||
|
||||
**Core:**
|
||||
- None (vanilla Node.js CLI)
|
||||
|
||||
**Testing:**
|
||||
- Vitest 1.0 - Unit tests
|
||||
- tsx - TypeScript execution without build step
|
||||
|
||||
**Build/Dev:**
|
||||
- TypeScript 5.3 - Compilation to JavaScript
|
||||
- esbuild - Used by Vitest for fast transforms
|
||||
|
||||
## Key Dependencies
|
||||
|
||||
**Critical:**
|
||||
- commander 11.x - CLI argument parsing and command structure
|
||||
- chalk 5.x - Terminal output styling
|
||||
- fs-extra 11.x - Extended file system operations
|
||||
|
||||
**Infrastructure:**
|
||||
- Node.js built-ins - fs, path, child_process for file operations
|
||||
|
||||
## Configuration
|
||||
|
||||
**Environment:**
|
||||
- No environment variables required
|
||||
- Configuration via CLI flags only
|
||||
|
||||
**Build:**
|
||||
- `tsconfig.json` - TypeScript compiler options
|
||||
- `vitest.config.ts` - Test runner configuration
|
||||
|
||||
## Platform Requirements
|
||||
|
||||
**Development:**
|
||||
- macOS/Linux/Windows (any platform with Node.js)
|
||||
- No external dependencies
|
||||
|
||||
**Production:**
|
||||
- Distributed as npm package
|
||||
- Installed globally via npm install -g
|
||||
- Runs on user's Node.js installation
|
||||
|
||||
---
|
||||
|
||||
*Stack analysis: 2025-01-20*
|
||||
*Update after major dependency changes*
|
||||
```
|
||||
</good_examples>
|
||||
|
||||
<guidelines>
|
||||
**What belongs in STACK.md:**
|
||||
- Languages and versions
|
||||
- Runtime requirements (Node, Bun, Deno, browser)
|
||||
- Package manager and lockfile
|
||||
- Framework choices
|
||||
- Critical dependencies (limit to 5-10 most important)
|
||||
- Build tooling
|
||||
- Platform/deployment requirements
|
||||
|
||||
**What does NOT belong here:**
|
||||
- File structure (that's STRUCTURE.md)
|
||||
- Architectural patterns (that's ARCHITECTURE.md)
|
||||
- Every dependency in package.json (only critical ones)
|
||||
- Implementation details (defer to code)
|
||||
|
||||
**When filling this template:**
|
||||
- Check package.json for dependencies
|
||||
- Note runtime version from .nvmrc or package.json engines
|
||||
- Include only dependencies that affect understanding (not every utility)
|
||||
- Specify versions only when version matters (breaking changes, compatibility)
|
||||
|
||||
**Useful for phase planning when:**
|
||||
- Adding new dependencies (check compatibility)
|
||||
- Upgrading frameworks (know what's in use)
|
||||
- Choosing implementation approach (must work with existing stack)
|
||||
- Understanding build requirements
|
||||
</guidelines>
|
||||
|
|
@ -0,0 +1,285 @@
|
|||
# Structure Template
|
||||
|
||||
Template for `.planning/codebase/STRUCTURE.md` - captures physical file organization.
|
||||
|
||||
**Purpose:** Document where things physically live in the codebase. Answers "where do I put X?"
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
# Codebase Structure
|
||||
|
||||
**Analysis Date:** [YYYY-MM-DD]
|
||||
|
||||
## Directory Layout
|
||||
|
||||
[ASCII tree of top-level directories with purpose]
|
||||
|
||||
```
|
||||
[project-root]/
|
||||
├── [dir]/ # [Purpose]
|
||||
├── [dir]/ # [Purpose]
|
||||
├── [dir]/ # [Purpose]
|
||||
└── [file] # [Purpose]
|
||||
```
|
||||
|
||||
## Directory Purposes
|
||||
|
||||
**[Directory Name]:**
|
||||
- Purpose: [What lives here]
|
||||
- Contains: [Types of files: e.g., "*.ts source files", "component directories"]
|
||||
- Key files: [Important files in this directory]
|
||||
- Subdirectories: [If nested, describe structure]
|
||||
|
||||
**[Directory Name]:**
|
||||
- Purpose: [What lives here]
|
||||
- Contains: [Types of files]
|
||||
- Key files: [Important files]
|
||||
- Subdirectories: [Structure]
|
||||
|
||||
## Key File Locations
|
||||
|
||||
**Entry Points:**
|
||||
- [Path]: [Purpose: e.g., "CLI entry point"]
|
||||
- [Path]: [Purpose: e.g., "Server startup"]
|
||||
|
||||
**Configuration:**
|
||||
- [Path]: [Purpose: e.g., "TypeScript config"]
|
||||
- [Path]: [Purpose: e.g., "Build configuration"]
|
||||
- [Path]: [Purpose: e.g., "Environment variables"]
|
||||
|
||||
**Core Logic:**
|
||||
- [Path]: [Purpose: e.g., "Business services"]
|
||||
- [Path]: [Purpose: e.g., "Database models"]
|
||||
- [Path]: [Purpose: e.g., "API routes"]
|
||||
|
||||
**Testing:**
|
||||
- [Path]: [Purpose: e.g., "Unit tests"]
|
||||
- [Path]: [Purpose: e.g., "Test fixtures"]
|
||||
|
||||
**Documentation:**
|
||||
- [Path]: [Purpose: e.g., "User-facing docs"]
|
||||
- [Path]: [Purpose: e.g., "Developer guide"]
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
**Files:**
|
||||
- [Pattern]: [Example: e.g., "kebab-case.ts for modules"]
|
||||
- [Pattern]: [Example: e.g., "PascalCase.tsx for React components"]
|
||||
- [Pattern]: [Example: e.g., "*.test.ts for test files"]
|
||||
|
||||
**Directories:**
|
||||
- [Pattern]: [Example: e.g., "kebab-case for feature directories"]
|
||||
- [Pattern]: [Example: e.g., "plural names for collections"]
|
||||
|
||||
**Special Patterns:**
|
||||
- [Pattern]: [Example: e.g., "index.ts for directory exports"]
|
||||
- [Pattern]: [Example: e.g., "__tests__ for test directories"]
|
||||
|
||||
## Where to Add New Code
|
||||
|
||||
**New Feature:**
|
||||
- Primary code: [Directory path]
|
||||
- Tests: [Directory path]
|
||||
- Config if needed: [Directory path]
|
||||
|
||||
**New Component/Module:**
|
||||
- Implementation: [Directory path]
|
||||
- Types: [Directory path]
|
||||
- Tests: [Directory path]
|
||||
|
||||
**New Route/Command:**
|
||||
- Definition: [Directory path]
|
||||
- Handler: [Directory path]
|
||||
- Tests: [Directory path]
|
||||
|
||||
**Utilities:**
|
||||
- Shared helpers: [Directory path]
|
||||
- Type definitions: [Directory path]
|
||||
|
||||
## Special Directories
|
||||
|
||||
[Any directories with special meaning or generation]
|
||||
|
||||
**[Directory]:**
|
||||
- Purpose: [e.g., "Generated code", "Build output"]
|
||||
- Source: [e.g., "Auto-generated by X", "Build artifacts"]
|
||||
- Committed: [Yes/No - in .gitignore?]
|
||||
|
||||
---
|
||||
|
||||
*Structure analysis: [date]*
|
||||
*Update when directory structure changes*
|
||||
```
|
||||
|
||||
<good_examples>
|
||||
```markdown
|
||||
# Codebase Structure
|
||||
|
||||
**Analysis Date:** 2025-01-20
|
||||
|
||||
## Directory Layout
|
||||
|
||||
```
|
||||
get-shit-done/
|
||||
├── bin/ # Executable entry points
|
||||
├── commands/ # Slash command definitions
|
||||
│ └── gsd/ # GSD-specific commands
|
||||
├── get-shit-done/ # Skill resources
|
||||
│ ├── references/ # Principle documents
|
||||
│ ├── templates/ # File templates
|
||||
│ └── workflows/ # Multi-step procedures
|
||||
├── src/ # Source code (if applicable)
|
||||
├── tests/ # Test files
|
||||
├── package.json # Project manifest
|
||||
└── README.md # User documentation
|
||||
```
|
||||
|
||||
## Directory Purposes
|
||||
|
||||
**bin/**
|
||||
- Purpose: CLI entry points
|
||||
- Contains: install.js (installer script)
|
||||
- Key files: install.js - handles npx installation
|
||||
- Subdirectories: None
|
||||
|
||||
**commands/gsd/**
|
||||
- Purpose: Slash command definitions for Claude Code
|
||||
- Contains: *.md files (one per command)
|
||||
- Key files: new-project.md, plan-phase.md, execute-plan.md
|
||||
- Subdirectories: None (flat structure)
|
||||
|
||||
**get-shit-done/references/**
|
||||
- Purpose: Core philosophy and guidance documents
|
||||
- Contains: principles.md, questioning.md, plan-format.md
|
||||
- Key files: principles.md - system philosophy
|
||||
- Subdirectories: None
|
||||
|
||||
**get-shit-done/templates/**
|
||||
- Purpose: Document templates for .planning/ files
|
||||
- Contains: Template definitions with frontmatter
|
||||
- Key files: project.md, roadmap.md, plan.md, summary.md
|
||||
- Subdirectories: codebase/ (new - for stack/architecture/structure templates)
|
||||
|
||||
**get-shit-done/workflows/**
|
||||
- Purpose: Reusable multi-step procedures
|
||||
- Contains: Workflow definitions called by commands
|
||||
- Key files: execute-phase.md, research-phase.md
|
||||
- Subdirectories: None
|
||||
|
||||
## Key File Locations
|
||||
|
||||
**Entry Points:**
|
||||
- `bin/install.js` - Installation script (npx entry)
|
||||
|
||||
**Configuration:**
|
||||
- `package.json` - Project metadata, dependencies, bin entry
|
||||
- `.gitignore` - Excluded files
|
||||
|
||||
**Core Logic:**
|
||||
- `bin/install.js` - All installation logic (file copying, path replacement)
|
||||
|
||||
**Testing:**
|
||||
- `tests/` - Test files (if present)
|
||||
|
||||
**Documentation:**
|
||||
- `README.md` - User-facing installation and usage guide
|
||||
- `CLAUDE.md` - Instructions for Claude Code when working in this repo
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
**Files:**
|
||||
- kebab-case.md: Markdown documents
|
||||
- kebab-case.js: JavaScript source files
|
||||
- UPPERCASE.md: Important project files (README, CLAUDE, CHANGELOG)
|
||||
|
||||
**Directories:**
|
||||
- kebab-case: All directories
|
||||
- Plural for collections: templates/, commands/, workflows/
|
||||
|
||||
**Special Patterns:**
|
||||
- {command-name}.md: Slash command definition
|
||||
- *-template.md: Could be used but templates/ directory preferred
|
||||
|
||||
## Where to Add New Code
|
||||
|
||||
**New Slash Command:**
|
||||
- Primary code: `commands/gsd/{command-name}.md`
|
||||
- Tests: `tests/commands/{command-name}.test.js` (if testing implemented)
|
||||
- Documentation: Update `README.md` with new command
|
||||
|
||||
**New Template:**
|
||||
- Implementation: `get-shit-done/templates/{name}.md`
|
||||
- Documentation: Template is self-documenting (includes guidelines)
|
||||
|
||||
**New Workflow:**
|
||||
- Implementation: `get-shit-done/workflows/{name}.md`
|
||||
- Usage: Reference from command with `@./.claude/get-shit-done/workflows/{name}.md`
|
||||
|
||||
**New Reference Document:**
|
||||
- Implementation: `get-shit-done/references/{name}.md`
|
||||
- Usage: Reference from commands/workflows as needed
|
||||
|
||||
**Utilities:**
|
||||
- No utilities yet (`install.js` is monolithic)
|
||||
- If extracted: `src/utils/`
|
||||
|
||||
## Special Directories
|
||||
|
||||
**get-shit-done/**
|
||||
- Purpose: Resources installed to ./.claude/
|
||||
- Source: Copied by bin/install.js during installation
|
||||
- Committed: Yes (source of truth)
|
||||
|
||||
**commands/**
|
||||
- Purpose: Slash commands installed to ./.claude/commands/
|
||||
- Source: Copied by bin/install.js during installation
|
||||
- Committed: Yes (source of truth)
|
||||
|
||||
---
|
||||
|
||||
*Structure analysis: 2025-01-20*
|
||||
*Update when directory structure changes*
|
||||
```
|
||||
</good_examples>
|
||||
|
||||
<guidelines>
|
||||
**What belongs in STRUCTURE.md:**
|
||||
- Directory layout (ASCII tree)
|
||||
- Purpose of each directory
|
||||
- Key file locations (entry points, configs, core logic)
|
||||
- Naming conventions
|
||||
- Where to add new code (by type)
|
||||
- Special/generated directories
|
||||
|
||||
**What does NOT belong here:**
|
||||
- Conceptual architecture (that's ARCHITECTURE.md)
|
||||
- Technology stack (that's STACK.md)
|
||||
- Code implementation details (defer to code reading)
|
||||
- Every single file (focus on directories and key files)
|
||||
|
||||
**When filling this template:**
|
||||
- Use `tree -L 2` or similar to visualize structure
|
||||
- Identify top-level directories and their purposes
|
||||
- Note naming patterns by observing existing files
|
||||
- Locate entry points, configs, and main logic areas
|
||||
- Keep directory tree concise (max 2-3 levels)
|
||||
|
||||
**ASCII tree format:**
|
||||
```
|
||||
root/
|
||||
├── dir1/ # Purpose
|
||||
│ ├── subdir/ # Purpose
|
||||
│ └── file.ts # Purpose
|
||||
├── dir2/ # Purpose
|
||||
└── file.ts # Purpose
|
||||
```
|
||||
|
||||
**Useful for phase planning when:**
|
||||
- Adding new features (where should files go?)
|
||||
- Understanding project organization
|
||||
- Finding where specific logic lives
|
||||
- Following existing conventions
|
||||
</guidelines>
|
||||
|
|
@ -0,0 +1,480 @@
|
|||
# Testing Patterns Template
|
||||
|
||||
Template for `.planning/codebase/TESTING.md` - captures test framework and patterns.
|
||||
|
||||
**Purpose:** Document how tests are written and run. Guide for adding tests that match existing patterns.
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
# Testing Patterns
|
||||
|
||||
**Analysis Date:** [YYYY-MM-DD]
|
||||
|
||||
## Test Framework
|
||||
|
||||
**Runner:**
|
||||
- [Framework: e.g., "Jest 29.x", "Vitest 1.x"]
|
||||
- [Config: e.g., "jest.config.js in project root"]
|
||||
|
||||
**Assertion Library:**
|
||||
- [Library: e.g., "built-in expect", "chai"]
|
||||
- [Matchers: e.g., "toBe, toEqual, toThrow"]
|
||||
|
||||
**Run Commands:**
|
||||
```bash
|
||||
[e.g., "npm test" or "npm run test"] # Run all tests
|
||||
[e.g., "npm test -- --watch"] # Watch mode
|
||||
[e.g., "npm test -- path/to/file.test.ts"] # Single file
|
||||
[e.g., "npm run test:coverage"] # Coverage report
|
||||
```
|
||||
|
||||
## Test File Organization
|
||||
|
||||
**Location:**
|
||||
- [Pattern: e.g., "*.test.ts alongside source files"]
|
||||
- [Alternative: e.g., "__tests__/ directory" or "separate tests/ tree"]
|
||||
|
||||
**Naming:**
|
||||
- [Unit tests: e.g., "module-name.test.ts"]
|
||||
- [Integration: e.g., "feature-name.integration.test.ts"]
|
||||
- [E2E: e.g., "user-flow.e2e.test.ts"]
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
[Show actual directory pattern, e.g.:
|
||||
src/
|
||||
lib/
|
||||
utils.ts
|
||||
utils.test.ts
|
||||
services/
|
||||
user-service.ts
|
||||
user-service.test.ts
|
||||
]
|
||||
```
|
||||
|
||||
## Test Structure
|
||||
|
||||
**Suite Organization:**
|
||||
```typescript
|
||||
[Show actual pattern used, e.g.:
|
||||
|
||||
describe('ModuleName', () => {
|
||||
describe('functionName', () => {
|
||||
it('should handle success case', () => {
|
||||
// arrange
|
||||
// act
|
||||
// assert
|
||||
});
|
||||
|
||||
it('should handle error case', () => {
|
||||
// test code
|
||||
});
|
||||
});
|
||||
});
|
||||
]
|
||||
```
|
||||
|
||||
**Patterns:**
|
||||
- [Setup: e.g., "beforeEach for shared setup, avoid beforeAll"]
|
||||
- [Teardown: e.g., "afterEach to clean up, restore mocks"]
|
||||
- [Structure: e.g., "arrange/act/assert pattern required"]
|
||||
|
||||
## Mocking
|
||||
|
||||
**Framework:**
|
||||
- [Tool: e.g., "Jest built-in mocking", "Vitest vi", "Sinon"]
|
||||
- [Import mocking: e.g., "vi.mock() at top of file"]
|
||||
|
||||
**Patterns:**
|
||||
```typescript
|
||||
[Show actual mocking pattern, e.g.:
|
||||
|
||||
// Mock external dependency
|
||||
vi.mock('./external-service', () => ({
|
||||
fetchData: vi.fn()
|
||||
}));
|
||||
|
||||
// Mock in test
|
||||
const mockFetch = vi.mocked(fetchData);
|
||||
mockFetch.mockResolvedValue({ data: 'test' });
|
||||
]
|
||||
```
|
||||
|
||||
**What to Mock:**
|
||||
- [e.g., "External APIs, file system, database"]
|
||||
- [e.g., "Time/dates (use vi.useFakeTimers)"]
|
||||
- [e.g., "Network calls (use mock fetch)"]
|
||||
|
||||
**What NOT to Mock:**
|
||||
- [e.g., "Pure functions, utilities"]
|
||||
- [e.g., "Internal business logic"]
|
||||
|
||||
## Fixtures and Factories
|
||||
|
||||
**Test Data:**
|
||||
```typescript
|
||||
[Show pattern for creating test data, e.g.:
|
||||
|
||||
// Factory pattern
|
||||
function createTestUser(overrides?: Partial<User>): User {
|
||||
return {
|
||||
id: 'test-id',
|
||||
name: 'Test User',
|
||||
email: 'test@example.com',
|
||||
...overrides
|
||||
};
|
||||
}
|
||||
|
||||
// Fixture file
|
||||
// tests/fixtures/users.ts
|
||||
export const mockUsers = [/* ... */];
|
||||
]
|
||||
```
|
||||
|
||||
**Location:**
|
||||
- [e.g., "tests/fixtures/ for shared fixtures"]
|
||||
- [e.g., "factory functions in test file or tests/factories/"]
|
||||
|
||||
## Coverage
|
||||
|
||||
**Requirements:**
|
||||
- [Target: e.g., "80% line coverage", "no specific target"]
|
||||
- [Enforcement: e.g., "CI blocks <80%", "coverage for awareness only"]
|
||||
|
||||
**Configuration:**
|
||||
- [Tool: e.g., "built-in coverage via --coverage flag"]
|
||||
- [Exclusions: e.g., "exclude *.test.ts, config files"]
|
||||
|
||||
**View Coverage:**
|
||||
```bash
|
||||
[e.g., "npm run test:coverage"]
|
||||
[e.g., "open coverage/index.html"]
|
||||
```
|
||||
|
||||
## Test Types
|
||||
|
||||
**Unit Tests:**
|
||||
- [Scope: e.g., "test single function/class in isolation"]
|
||||
- [Mocking: e.g., "mock all external dependencies"]
|
||||
- [Speed: e.g., "must run in <1s per test"]
|
||||
|
||||
**Integration Tests:**
|
||||
- [Scope: e.g., "test multiple modules together"]
|
||||
- [Mocking: e.g., "mock external services, use real internal modules"]
|
||||
- [Setup: e.g., "use test database, seed data"]
|
||||
|
||||
**E2E Tests:**
|
||||
- [Framework: e.g., "Playwright for E2E"]
|
||||
- [Scope: e.g., "test full user flows"]
|
||||
- [Location: e.g., "e2e/ directory separate from unit tests"]
|
||||
|
||||
## Common Patterns
|
||||
|
||||
**Async Testing:**
|
||||
```typescript
|
||||
[Show pattern, e.g.:
|
||||
|
||||
it('should handle async operation', async () => {
|
||||
const result = await asyncFunction();
|
||||
expect(result).toBe('expected');
|
||||
});
|
||||
]
|
||||
```
|
||||
|
||||
**Error Testing:**
|
||||
```typescript
|
||||
[Show pattern, e.g.:
|
||||
|
||||
it('should throw on invalid input', () => {
|
||||
expect(() => functionCall()).toThrow('error message');
|
||||
});
|
||||
|
||||
// Async error
|
||||
it('should reject on failure', async () => {
|
||||
await expect(asyncCall()).rejects.toThrow('error message');
|
||||
});
|
||||
]
|
||||
```
|
||||
|
||||
**Snapshot Testing:**
|
||||
- [Usage: e.g., "for React components only" or "not used"]
|
||||
- [Location: e.g., "__snapshots__/ directory"]
|
||||
|
||||
---
|
||||
|
||||
*Testing analysis: [date]*
|
||||
*Update when test patterns change*
|
||||
```
|
||||
|
||||
<good_examples>
|
||||
```markdown
|
||||
# Testing Patterns
|
||||
|
||||
**Analysis Date:** 2025-01-20
|
||||
|
||||
## Test Framework
|
||||
|
||||
**Runner:**
|
||||
- Vitest 1.0.4
|
||||
- Config: vitest.config.ts in project root
|
||||
|
||||
**Assertion Library:**
|
||||
- Vitest built-in expect
|
||||
- Matchers: toBe, toEqual, toThrow, toMatchObject
|
||||
|
||||
**Run Commands:**
|
||||
```bash
|
||||
npm test # Run all tests
|
||||
npm test -- --watch # Watch mode
|
||||
npm test -- path/to/file.test.ts # Single file
|
||||
npm run test:coverage # Coverage report
|
||||
```
|
||||
|
||||
## Test File Organization
|
||||
|
||||
**Location:**
|
||||
- *.test.ts alongside source files
|
||||
- No separate tests/ directory
|
||||
|
||||
**Naming:**
|
||||
- unit-name.test.ts for all tests
|
||||
- No distinction between unit/integration in filename
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
src/
|
||||
lib/
|
||||
parser.ts
|
||||
parser.test.ts
|
||||
services/
|
||||
install-service.ts
|
||||
install-service.test.ts
|
||||
bin/
|
||||
install.ts
|
||||
(no test - integration tested via CLI)
|
||||
```
|
||||
|
||||
## Test Structure
|
||||
|
||||
**Suite Organization:**
|
||||
```typescript
|
||||
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
|
||||
|
||||
describe('ModuleName', () => {
|
||||
describe('functionName', () => {
|
||||
beforeEach(() => {
|
||||
// reset state
|
||||
});
|
||||
|
||||
it('should handle valid input', () => {
|
||||
// arrange
|
||||
const input = createTestInput();
|
||||
|
||||
// act
|
||||
const result = functionName(input);
|
||||
|
||||
// assert
|
||||
expect(result).toEqual(expectedOutput);
|
||||
});
|
||||
|
||||
it('should throw on invalid input', () => {
|
||||
expect(() => functionName(null)).toThrow('Invalid input');
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**Patterns:**
|
||||
- Use beforeEach for per-test setup, avoid beforeAll
|
||||
- Use afterEach to restore mocks: vi.restoreAllMocks()
|
||||
- Explicit arrange/act/assert comments in complex tests
|
||||
- One assertion focus per test (but multiple expects OK)
|
||||
|
||||
## Mocking
|
||||
|
||||
**Framework:**
|
||||
- Vitest built-in mocking (vi)
|
||||
- Module mocking via vi.mock() at top of test file
|
||||
|
||||
**Patterns:**
|
||||
```typescript
|
||||
import { vi } from 'vitest';
|
||||
import { externalFunction } from './external';
|
||||
|
||||
// Mock module
|
||||
vi.mock('./external', () => ({
|
||||
externalFunction: vi.fn()
|
||||
}));
|
||||
|
||||
describe('test suite', () => {
|
||||
it('mocks function', () => {
|
||||
const mockFn = vi.mocked(externalFunction);
|
||||
mockFn.mockReturnValue('mocked result');
|
||||
|
||||
// test code using mocked function
|
||||
|
||||
expect(mockFn).toHaveBeenCalledWith('expected arg');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**What to Mock:**
|
||||
- File system operations (fs-extra)
|
||||
- Child process execution (child_process.exec)
|
||||
- External API calls
|
||||
- Environment variables (process.env)
|
||||
|
||||
**What NOT to Mock:**
|
||||
- Internal pure functions
|
||||
- Simple utilities (string manipulation, array helpers)
|
||||
- TypeScript types
|
||||
|
||||
## Fixtures and Factories
|
||||
|
||||
**Test Data:**
|
||||
```typescript
|
||||
// Factory functions in test file
|
||||
function createTestConfig(overrides?: Partial<Config>): Config {
|
||||
return {
|
||||
targetDir: '/tmp/test',
|
||||
global: false,
|
||||
...overrides
|
||||
};
|
||||
}
|
||||
|
||||
// Shared fixtures in tests/fixtures/
|
||||
// tests/fixtures/sample-command.md
|
||||
export const sampleCommand = `---
|
||||
description: Test command
|
||||
---
|
||||
Content here`;
|
||||
```
|
||||
|
||||
**Location:**
|
||||
- Factory functions: define in test file near usage
|
||||
- Shared fixtures: tests/fixtures/ (for multi-file test data)
|
||||
- Mock data: inline in test when simple, factory when complex
|
||||
|
||||
## Coverage
|
||||
|
||||
**Requirements:**
|
||||
- No enforced coverage target
|
||||
- Coverage tracked for awareness
|
||||
- Focus on critical paths (parsers, service logic)
|
||||
|
||||
**Configuration:**
|
||||
- Vitest coverage via c8 (built-in)
|
||||
- Excludes: *.test.ts, bin/install.ts, config files
|
||||
|
||||
**View Coverage:**
|
||||
```bash
|
||||
npm run test:coverage
|
||||
open coverage/index.html
|
||||
```
|
||||
|
||||
## Test Types
|
||||
|
||||
**Unit Tests:**
|
||||
- Test single function in isolation
|
||||
- Mock all external dependencies (fs, child_process)
|
||||
- Fast: each test <100ms
|
||||
- Examples: parser.test.ts, validator.test.ts
|
||||
|
||||
**Integration Tests:**
|
||||
- Test multiple modules together
|
||||
- Mock only external boundaries (file system, process)
|
||||
- Examples: install-service.test.ts (tests service + parser)
|
||||
|
||||
**E2E Tests:**
|
||||
- Not currently used
|
||||
- CLI integration tested manually
|
||||
|
||||
## Common Patterns
|
||||
|
||||
**Async Testing:**
|
||||
```typescript
|
||||
it('should handle async operation', async () => {
|
||||
const result = await asyncFunction();
|
||||
expect(result).toBe('expected');
|
||||
});
|
||||
```
|
||||
|
||||
**Error Testing:**
|
||||
```typescript
|
||||
it('should throw on invalid input', () => {
|
||||
expect(() => parse(null)).toThrow('Cannot parse null');
|
||||
});
|
||||
|
||||
// Async error
|
||||
it('should reject on file not found', async () => {
|
||||
await expect(readConfig('invalid.txt')).rejects.toThrow('ENOENT');
|
||||
});
|
||||
```
|
||||
|
||||
**File System Mocking:**
|
||||
```typescript
|
||||
import { vi } from 'vitest';
|
||||
import * as fs from 'fs-extra';
|
||||
|
||||
vi.mock('fs-extra');
|
||||
|
||||
it('mocks file system', () => {
|
||||
vi.mocked(fs.readFile).mockResolvedValue('file content');
|
||||
// test code
|
||||
});
|
||||
```
|
||||
|
||||
**Snapshot Testing:**
|
||||
- Not used in this codebase
|
||||
- Prefer explicit assertions for clarity
|
||||
|
||||
---
|
||||
|
||||
*Testing analysis: 2025-01-20*
|
||||
*Update when test patterns change*
|
||||
```
|
||||
</good_examples>
|
||||
|
||||
<guidelines>
|
||||
**What belongs in TESTING.md:**
|
||||
- Test framework and runner configuration
|
||||
- Test file location and naming patterns
|
||||
- Test structure (describe/it, beforeEach patterns)
|
||||
- Mocking approach and examples
|
||||
- Fixture/factory patterns
|
||||
- Coverage requirements
|
||||
- How to run tests (commands)
|
||||
- Common testing patterns in actual code
|
||||
|
||||
**What does NOT belong here:**
|
||||
- Specific test cases (defer to actual test files)
|
||||
- Technology choices (that's STACK.md)
|
||||
- CI/CD setup (that's deployment docs)
|
||||
|
||||
**When filling this template:**
|
||||
- Check package.json scripts for test commands
|
||||
- Find test config file (jest.config.js, vitest.config.ts)
|
||||
- Read 3-5 existing test files to identify patterns
|
||||
- Look for test utilities in tests/ or test-utils/
|
||||
- Check for coverage configuration
|
||||
- Document actual patterns used, not ideal patterns
|
||||
|
||||
**Useful for phase planning when:**
|
||||
- Adding new features (write matching tests)
|
||||
- Refactoring (maintain test patterns)
|
||||
- Fixing bugs (add regression tests)
|
||||
- Understanding verification approach
|
||||
- Setting up test infrastructure
|
||||
|
||||
**Analysis approach:**
|
||||
- Check package.json for test framework and scripts
|
||||
- Read test config file for coverage, setup
|
||||
- Examine test file organization (collocated vs separate)
|
||||
- Review 5 test files for patterns (mocking, structure, assertions)
|
||||
- Look for test utilities, fixtures, factories
|
||||
- Note any test types (unit, integration, e2e)
|
||||
- Document commands for running tests
|
||||
</guidelines>
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
{
|
||||
"mode": "interactive",
|
||||
"depth": "standard",
|
||||
"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
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,161 @@
|
|||
# Phase Context Template
|
||||
|
||||
Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures the user's vision for a phase.
|
||||
|
||||
**Purpose:** Document how the user imagines the phase working. This is vision context, not technical analysis. Technical details come from research.
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
# Phase [X]: [Name] - Context
|
||||
|
||||
**Gathered:** [date]
|
||||
**Status:** [Ready for research / Ready for planning]
|
||||
|
||||
<vision>
|
||||
## How This Should Work
|
||||
|
||||
[User's description of how they imagine this phase working. What happens when someone uses it? What does it look/feel like? This is the "pitch" version, not the technical spec.]
|
||||
|
||||
</vision>
|
||||
|
||||
<essential>
|
||||
## What Must Be Nailed
|
||||
|
||||
[The core of this phase. If we only get one thing right, what is it? What's the non-negotiable that makes this phase successful?]
|
||||
|
||||
- [Essential thing 1]
|
||||
- [Essential thing 2]
|
||||
- [Essential thing 3 if applicable]
|
||||
|
||||
</essential>
|
||||
|
||||
<boundaries>
|
||||
## What's Out of Scope
|
||||
|
||||
[Explicit exclusions for this phase. What are we NOT building? Where does this phase end and the next begin?]
|
||||
|
||||
- [Not doing X - that's Phase Y]
|
||||
- [Not including Z - deferred]
|
||||
- [Explicitly excluding W]
|
||||
|
||||
</boundaries>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
[Any particular things the user has in mind. References to existing products/features they like. Specific behaviors or interactions. "I want it to work like X" or "When you click Y, it should Z."]
|
||||
|
||||
[If none: "No specific requirements - open to standard approaches"]
|
||||
|
||||
</specifics>
|
||||
|
||||
<notes>
|
||||
## Additional Context
|
||||
|
||||
[Anything else captured during the discussion that doesn't fit above. User's priorities, concerns mentioned, relevant background.]
|
||||
|
||||
[If none: "No additional notes"]
|
||||
|
||||
</notes>
|
||||
|
||||
---
|
||||
|
||||
*Phase: XX-name*
|
||||
*Context gathered: [date]*
|
||||
```
|
||||
|
||||
<good_examples>
|
||||
```markdown
|
||||
# Phase 3: User Dashboard - Context
|
||||
|
||||
**Gathered:** 2025-01-20
|
||||
**Status:** Ready for research
|
||||
|
||||
<vision>
|
||||
## How This Should Work
|
||||
|
||||
When users log in, they land on a dashboard that shows them everything important at a glance. I imagine it feeling calm and organized - not overwhelming like Jira or cluttered like Notion.
|
||||
|
||||
The main thing is seeing their active projects and what needs attention. Think of it like a "what should I work on today" view. It should feel personal, not like enterprise software.
|
||||
|
||||
</vision>
|
||||
|
||||
<essential>
|
||||
## What Must Be Nailed
|
||||
|
||||
- **At-a-glance clarity** - Within 2 seconds of landing, user knows what needs their attention
|
||||
- **Personal feel** - This is YOUR dashboard, not a team dashboard. It should feel like opening your personal notebook.
|
||||
|
||||
</essential>
|
||||
|
||||
<boundaries>
|
||||
## What's Out of Scope
|
||||
|
||||
- Team features (shared dashboards, permissions) - that's a future milestone
|
||||
- Analytics/reporting - just show what needs attention, not graphs
|
||||
- Customizable layouts - keep it simple, one good layout
|
||||
- Mobile optimization - desktop first for now
|
||||
|
||||
</boundaries>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- I like how Linear's home screen highlights what's assigned to you without noise
|
||||
- Should show projects in a card format, not a list
|
||||
- Maybe a "Today" section at the top with urgent stuff
|
||||
- Dark mode is essential (already have this from Phase 2)
|
||||
|
||||
</specifics>
|
||||
|
||||
<notes>
|
||||
## Additional Context
|
||||
|
||||
User mentioned they've abandoned several dashboards before because they felt too "corporate." The key differentiator is making it feel personal and calm.
|
||||
|
||||
Priority is clarity over features. Better to show less and make it obvious than show everything.
|
||||
|
||||
</notes>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 03-user-dashboard*
|
||||
*Context gathered: 2025-01-20*
|
||||
```
|
||||
</good_examples>
|
||||
|
||||
<guidelines>
|
||||
**This template captures VISION, not technical specs.**
|
||||
|
||||
The user is the visionary. They know:
|
||||
- How they imagine it working
|
||||
- What it should feel like
|
||||
- What's essential vs nice-to-have
|
||||
- References to things they like
|
||||
|
||||
The user does NOT know (and shouldn't be asked):
|
||||
- Codebase patterns (Claude reads the code)
|
||||
- Technical risks (Claude identifies during research)
|
||||
- Implementation constraints (Claude figures out)
|
||||
- Success metrics (Claude infers from the work)
|
||||
|
||||
**Content should read like:**
|
||||
- A founder describing their product vision
|
||||
- "When you use this, it should feel like..."
|
||||
- "The most important thing is..."
|
||||
- "I don't want it to be like X, I want it to feel like Y"
|
||||
|
||||
**Content should NOT read like:**
|
||||
- A technical specification
|
||||
- Risk assessment matrix
|
||||
- Success criteria checklist
|
||||
- Codebase analysis
|
||||
|
||||
**After creation:**
|
||||
- File lives in phase directory: `.planning/phases/XX-name/{phase}-CONTEXT.md`
|
||||
- Research phase adds technical context (patterns, risks, constraints)
|
||||
- Planning phase creates executable tasks informed by both vision AND research
|
||||
</guidelines>
|
||||
|
|
@ -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>
|
||||
|
|
@ -0,0 +1,146 @@
|
|||
# Discovery Template
|
||||
|
||||
Template for `.planning/phases/XX-name/DISCOVERY.md` - shallow research for library/option decisions.
|
||||
|
||||
**Purpose:** Answer "which library/option should we use" questions during mandatory discovery in plan-phase.
|
||||
|
||||
For deep ecosystem research ("how do experts build this"), use `/gsd:research-phase` which produces RESEARCH.md.
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
phase: XX-name
|
||||
type: discovery
|
||||
topic: [discovery-topic]
|
||||
---
|
||||
|
||||
<session_initialization>
|
||||
Before beginning discovery, 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>
|
||||
|
||||
<discovery_objective>
|
||||
Discover [topic] to inform [phase name] implementation.
|
||||
|
||||
Purpose: [What decision/implementation this enables]
|
||||
Scope: [Boundaries]
|
||||
Output: DISCOVERY.md with recommendation
|
||||
</discovery_objective>
|
||||
|
||||
<discovery_scope>
|
||||
<include>
|
||||
- [Question to answer]
|
||||
- [Area to investigate]
|
||||
- [Specific comparison if needed]
|
||||
</include>
|
||||
|
||||
<exclude>
|
||||
- [Out of scope for this discovery]
|
||||
- [Defer to implementation phase]
|
||||
</exclude>
|
||||
</discovery_scope>
|
||||
|
||||
<discovery_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 discovery, 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)
|
||||
|
||||
</discovery_protocol>
|
||||
|
||||
|
||||
<output_structure>
|
||||
Create `.planning/phases/XX-name/DISCOVERY.md`:
|
||||
|
||||
```markdown
|
||||
# [Topic] Discovery
|
||||
|
||||
## 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 discovery:**
|
||||
- Technology choice unclear (library A vs B)
|
||||
- Best practices needed for unfamiliar integration
|
||||
- API/library investigation required
|
||||
- Single decision pending
|
||||
|
||||
**When NOT to use:**
|
||||
- Established patterns (CRUD, auth with known library)
|
||||
- Implementation details (defer to execution)
|
||||
- Questions answerable from existing project context
|
||||
|
||||
**When to use RESEARCH.md instead:**
|
||||
- Niche/complex domains (3D, games, audio, shaders)
|
||||
- Need ecosystem knowledge, not just library choice
|
||||
- "How do experts build this" questions
|
||||
- Use `/gsd:research-phase` for these
|
||||
</guidelines>
|
||||
|
|
@ -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.
|
||||
|
|
@ -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>
|
||||
|
|
@ -0,0 +1,93 @@
|
|||
# Milestone Context Template
|
||||
|
||||
Template for `.planning/MILESTONE-CONTEXT.md` - temporary handoff file from discuss-milestone to create-milestone.
|
||||
|
||||
**Purpose:** Persist milestone discussion context so `/clear` can be used between commands. This file is consumed by `/gsd:new-milestone` and deleted after the milestone is created.
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
# Milestone Context
|
||||
|
||||
**Generated:** [date]
|
||||
**Status:** Ready for /gsd:new-milestone
|
||||
|
||||
<features>
|
||||
## Features to Build
|
||||
|
||||
[Features identified during discussion - the substance of this milestone]
|
||||
|
||||
- **[Feature 1]**: [description]
|
||||
- **[Feature 2]**: [description]
|
||||
- **[Feature 3]**: [description]
|
||||
|
||||
</features>
|
||||
|
||||
<scope>
|
||||
## Scope
|
||||
|
||||
**Suggested name:** v[X.Y] [Theme Name]
|
||||
**Estimated phases:** [N]
|
||||
**Focus:** [One sentence theme/focus]
|
||||
|
||||
</scope>
|
||||
|
||||
<phase_mapping>
|
||||
## Phase Mapping
|
||||
|
||||
[How features map to phases - rough breakdown]
|
||||
|
||||
- Phase [N]: [Feature/goal]
|
||||
- Phase [N+1]: [Feature/goal]
|
||||
- Phase [N+2]: [Feature/goal]
|
||||
|
||||
</phase_mapping>
|
||||
|
||||
<constraints>
|
||||
## Constraints
|
||||
|
||||
[Any constraints or boundaries mentioned during discussion]
|
||||
|
||||
- [Constraint 1]
|
||||
- [Constraint 2]
|
||||
|
||||
</constraints>
|
||||
|
||||
<notes>
|
||||
## Additional Context
|
||||
|
||||
[Anything else captured during discussion that informs the milestone]
|
||||
|
||||
</notes>
|
||||
|
||||
---
|
||||
|
||||
*This file is temporary. It will be deleted after /gsd:new-milestone creates the milestone.*
|
||||
```
|
||||
|
||||
<guidelines>
|
||||
**This is a handoff artifact, not permanent documentation.**
|
||||
|
||||
The file exists only to pass context from `discuss-milestone` to `create-milestone` across a `/clear` boundary.
|
||||
|
||||
**Lifecycle:**
|
||||
1. `/gsd:discuss-milestone` creates this file at end of discussion
|
||||
2. User runs `/clear` (safe now - context is persisted)
|
||||
3. `/gsd:new-milestone` reads this file
|
||||
4. `/gsd:new-milestone` uses context to populate milestone
|
||||
5. `/gsd:new-milestone` deletes this file after successful creation
|
||||
|
||||
**Content should include:**
|
||||
- Features identified (the core of what to build)
|
||||
- Suggested milestone name/theme
|
||||
- Rough phase mapping
|
||||
- Any constraints or scope boundaries
|
||||
- Notes from discussion
|
||||
|
||||
**Content should NOT include:**
|
||||
- Technical analysis (that comes during phase research)
|
||||
- Detailed phase specifications (create-milestone handles that)
|
||||
- Implementation details
|
||||
</guidelines>
|
||||
|
|
@ -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>
|
||||
|
|
@ -0,0 +1,303 @@
|
|||
# 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 discovery exists:]
|
||||
@.planning/phases/XX-name/DISCOVERY.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)
|
||||
- **TDD candidates** - Features that warrant TDD become their own TDD plans
|
||||
</scope_guidance>
|
||||
|
||||
<tdd_plan_note>
|
||||
**TDD features get dedicated plans.**
|
||||
|
||||
TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR) that consume 40-50% context for a single feature. Features warranting TDD (business logic, validation, algorithms, API contracts) each get their own TDD plan.
|
||||
|
||||
**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
|
||||
→ Yes: Create a TDD plan (one feature per plan)
|
||||
→ No: Standard task in standard plan
|
||||
|
||||
See `./.claude/get-shit-done/references/tdd.md` for TDD plan structure.
|
||||
</tdd_plan_note>
|
||||
|
||||
<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>
|
||||
|
|
@ -0,0 +1,184 @@
|
|||
# PROJECT.md Template
|
||||
|
||||
Template for `.planning/PROJECT.md` — the living project context document.
|
||||
|
||||
<template>
|
||||
|
||||
```markdown
|
||||
# [Project Name]
|
||||
|
||||
## What This Is
|
||||
|
||||
[Current accurate description — 2-3 sentences. What does this product do and who is it for?
|
||||
Use the user's language and framing. Update whenever reality drifts from this description.]
|
||||
|
||||
## Core Value
|
||||
|
||||
[The ONE thing that matters most. If everything else fails, this must work.
|
||||
One sentence that drives prioritization when tradeoffs arise.]
|
||||
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
|
||||
<!-- Shipped and confirmed valuable. -->
|
||||
|
||||
(None yet — ship to validate)
|
||||
|
||||
### Active
|
||||
|
||||
<!-- Current scope. Building toward these. -->
|
||||
|
||||
- [ ] [Requirement 1]
|
||||
- [ ] [Requirement 2]
|
||||
- [ ] [Requirement 3]
|
||||
|
||||
### Out of Scope
|
||||
|
||||
<!-- Explicit boundaries. Includes reasoning to prevent re-adding. -->
|
||||
|
||||
- [Exclusion 1] — [why]
|
||||
- [Exclusion 2] — [why]
|
||||
|
||||
## Context
|
||||
|
||||
[Background information that informs implementation:
|
||||
- Technical environment or ecosystem
|
||||
- Relevant prior work or experience
|
||||
- User research or feedback themes
|
||||
- Known issues to address]
|
||||
|
||||
## Constraints
|
||||
|
||||
- **[Type]**: [What] — [Why]
|
||||
- **[Type]**: [What] — [Why]
|
||||
|
||||
Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Performance, Security
|
||||
|
||||
## Key Decisions
|
||||
|
||||
<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
|
||||
|
||||
| Decision | Rationale | Outcome |
|
||||
|----------|-----------|---------|
|
||||
| [Choice] | [Why] | [✓ Good / ⚠️ Revisit / — Pending] |
|
||||
|
||||
---
|
||||
*Last updated: [date] after [trigger]*
|
||||
```
|
||||
|
||||
</template>
|
||||
|
||||
<guidelines>
|
||||
|
||||
**What This Is:**
|
||||
- Current accurate description of the product
|
||||
- 2-3 sentences capturing what it does and who it's for
|
||||
- Use the user's words and framing
|
||||
- Update when the product evolves beyond this description
|
||||
|
||||
**Core Value:**
|
||||
- The single most important thing
|
||||
- Everything else can fail; this cannot
|
||||
- Drives prioritization when tradeoffs arise
|
||||
- Rarely changes; if it does, it's a significant pivot
|
||||
|
||||
**Requirements — Validated:**
|
||||
- Requirements that shipped and proved valuable
|
||||
- Format: `- ✓ [Requirement] — [version/phase]`
|
||||
- These are locked — changing them requires explicit discussion
|
||||
|
||||
**Requirements — Active:**
|
||||
- Current scope being built toward
|
||||
- These are hypotheses until shipped and validated
|
||||
- Move to Validated when shipped, Out of Scope if invalidated
|
||||
|
||||
**Requirements — Out of Scope:**
|
||||
- Explicit boundaries on what we're not building
|
||||
- Always include reasoning (prevents re-adding later)
|
||||
- Includes: considered and rejected, deferred to future, explicitly excluded
|
||||
|
||||
**Context:**
|
||||
- Background that informs implementation decisions
|
||||
- Technical environment, prior work, user feedback
|
||||
- Known issues or technical debt to address
|
||||
- Update as new context emerges
|
||||
|
||||
**Constraints:**
|
||||
- Hard limits on implementation choices
|
||||
- Tech stack, timeline, budget, compatibility, dependencies
|
||||
- Include the "why" — constraints without rationale get questioned
|
||||
|
||||
**Key Decisions:**
|
||||
- Significant choices that affect future work
|
||||
- Add decisions as they're made throughout the project
|
||||
- Track outcome when known:
|
||||
- ✓ Good — decision proved correct
|
||||
- ⚠️ Revisit — decision may need reconsideration
|
||||
- — Pending — too early to evaluate
|
||||
|
||||
**Last Updated:**
|
||||
- Always note when and why the document was updated
|
||||
- Format: `after Phase 2` or `after v1.0 milestone`
|
||||
- Triggers review of whether content is still accurate
|
||||
|
||||
</guidelines>
|
||||
|
||||
<evolution>
|
||||
|
||||
PROJECT.md evolves throughout the project lifecycle.
|
||||
|
||||
**After each phase transition:**
|
||||
1. Requirements invalidated? → Move to Out of Scope with reason
|
||||
2. Requirements validated? → Move to Validated with phase reference
|
||||
3. New requirements emerged? → Add to Active
|
||||
4. Decisions to log? → Add to Key Decisions
|
||||
5. "What This Is" still accurate? → Update if drifted
|
||||
|
||||
**After each milestone:**
|
||||
1. Full review of all sections
|
||||
2. Core Value check — still the right priority?
|
||||
3. Audit Out of Scope — reasons still valid?
|
||||
4. Update Context with current state (users, feedback, metrics)
|
||||
|
||||
</evolution>
|
||||
|
||||
<brownfield>
|
||||
|
||||
For existing codebases:
|
||||
|
||||
1. **Map codebase first** via `/gsd:map-codebase`
|
||||
|
||||
2. **Infer Validated requirements** from existing code:
|
||||
- What does the codebase actually do?
|
||||
- What patterns are established?
|
||||
- What's clearly working and relied upon?
|
||||
|
||||
3. **Gather Active requirements** from user:
|
||||
- Present inferred current state
|
||||
- Ask what they want to build next
|
||||
|
||||
4. **Initialize:**
|
||||
- Validated = inferred from existing code
|
||||
- Active = user's goals for this work
|
||||
- Out of Scope = boundaries user specifies
|
||||
- Context = includes current codebase state
|
||||
|
||||
</brownfield>
|
||||
|
||||
<state_reference>
|
||||
|
||||
STATE.md references PROJECT.md:
|
||||
|
||||
```markdown
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated [date])
|
||||
|
||||
**Core value:** [One-liner from Core Value section]
|
||||
**Current focus:** [Current phase name]
|
||||
```
|
||||
|
||||
This ensures Claude reads current PROJECT.md context.
|
||||
|
||||
</state_reference>
|
||||
|
|
@ -0,0 +1,529 @@
|
|||
# Research Template
|
||||
|
||||
Template for `.planning/phases/XX-name/{phase}-RESEARCH.md` - comprehensive ecosystem research before planning.
|
||||
|
||||
**Purpose:** Document what Claude needs to know to implement a phase well - not just "which library" but "how do experts build this."
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
# Phase [X]: [Name] - Research
|
||||
|
||||
**Researched:** [date]
|
||||
**Domain:** [primary technology/problem domain]
|
||||
**Confidence:** [HIGH/MEDIUM/LOW]
|
||||
|
||||
<research_summary>
|
||||
## Summary
|
||||
|
||||
[2-3 paragraph executive summary]
|
||||
- What was researched
|
||||
- What the standard approach is
|
||||
- Key recommendations
|
||||
|
||||
**Primary recommendation:** [one-liner actionable guidance]
|
||||
</research_summary>
|
||||
|
||||
<standard_stack>
|
||||
## Standard Stack
|
||||
|
||||
The established libraries/tools for this domain:
|
||||
|
||||
### Core
|
||||
| Library | Version | Purpose | Why Standard |
|
||||
|---------|---------|---------|--------------|
|
||||
| [name] | [ver] | [what it does] | [why experts use it] |
|
||||
| [name] | [ver] | [what it does] | [why experts use it] |
|
||||
|
||||
### Supporting
|
||||
| Library | Version | Purpose | When to Use |
|
||||
|---------|---------|---------|-------------|
|
||||
| [name] | [ver] | [what it does] | [use case] |
|
||||
| [name] | [ver] | [what it does] | [use case] |
|
||||
|
||||
### Alternatives Considered
|
||||
| Instead of | Could Use | Tradeoff |
|
||||
|------------|-----------|----------|
|
||||
| [standard] | [alternative] | [when alternative makes sense] |
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
npm install [packages]
|
||||
# or
|
||||
yarn add [packages]
|
||||
```
|
||||
</standard_stack>
|
||||
|
||||
<architecture_patterns>
|
||||
## Architecture Patterns
|
||||
|
||||
### Recommended Project Structure
|
||||
```
|
||||
src/
|
||||
├── [folder]/ # [purpose]
|
||||
├── [folder]/ # [purpose]
|
||||
└── [folder]/ # [purpose]
|
||||
```
|
||||
|
||||
### Pattern 1: [Pattern Name]
|
||||
**What:** [description]
|
||||
**When to use:** [conditions]
|
||||
**Example:**
|
||||
```typescript
|
||||
// [code example from Context7/official docs]
|
||||
```
|
||||
|
||||
### Pattern 2: [Pattern Name]
|
||||
**What:** [description]
|
||||
**When to use:** [conditions]
|
||||
**Example:**
|
||||
```typescript
|
||||
// [code example]
|
||||
```
|
||||
|
||||
### Anti-Patterns to Avoid
|
||||
- **[Anti-pattern]:** [why it's bad, what to do instead]
|
||||
- **[Anti-pattern]:** [why it's bad, what to do instead]
|
||||
</architecture_patterns>
|
||||
|
||||
<dont_hand_roll>
|
||||
## Don't Hand-Roll
|
||||
|
||||
Problems that look simple but have existing solutions:
|
||||
|
||||
| Problem | Don't Build | Use Instead | Why |
|
||||
|---------|-------------|-------------|-----|
|
||||
| [problem] | [what you'd build] | [library] | [edge cases, complexity] |
|
||||
| [problem] | [what you'd build] | [library] | [edge cases, complexity] |
|
||||
| [problem] | [what you'd build] | [library] | [edge cases, complexity] |
|
||||
|
||||
**Key insight:** [why custom solutions are worse in this domain]
|
||||
</dont_hand_roll>
|
||||
|
||||
<common_pitfalls>
|
||||
## Common Pitfalls
|
||||
|
||||
### Pitfall 1: [Name]
|
||||
**What goes wrong:** [description]
|
||||
**Why it happens:** [root cause]
|
||||
**How to avoid:** [prevention strategy]
|
||||
**Warning signs:** [how to detect early]
|
||||
|
||||
### Pitfall 2: [Name]
|
||||
**What goes wrong:** [description]
|
||||
**Why it happens:** [root cause]
|
||||
**How to avoid:** [prevention strategy]
|
||||
**Warning signs:** [how to detect early]
|
||||
|
||||
### Pitfall 3: [Name]
|
||||
**What goes wrong:** [description]
|
||||
**Why it happens:** [root cause]
|
||||
**How to avoid:** [prevention strategy]
|
||||
**Warning signs:** [how to detect early]
|
||||
</common_pitfalls>
|
||||
|
||||
<code_examples>
|
||||
## Code Examples
|
||||
|
||||
Verified patterns from official sources:
|
||||
|
||||
### [Common Operation 1]
|
||||
```typescript
|
||||
// Source: [Context7/official docs URL]
|
||||
[code]
|
||||
```
|
||||
|
||||
### [Common Operation 2]
|
||||
```typescript
|
||||
// Source: [Context7/official docs URL]
|
||||
[code]
|
||||
```
|
||||
|
||||
### [Common Operation 3]
|
||||
```typescript
|
||||
// Source: [Context7/official docs URL]
|
||||
[code]
|
||||
```
|
||||
</code_examples>
|
||||
|
||||
<sota_updates>
|
||||
## State of the Art (2024-2025)
|
||||
|
||||
What's changed recently:
|
||||
|
||||
| Old Approach | Current Approach | When Changed | Impact |
|
||||
|--------------|------------------|--------------|--------|
|
||||
| [old] | [new] | [date/version] | [what it means for implementation] |
|
||||
|
||||
**New tools/patterns to consider:**
|
||||
- [Tool/Pattern]: [what it enables, when to use]
|
||||
- [Tool/Pattern]: [what it enables, when to use]
|
||||
|
||||
**Deprecated/outdated:**
|
||||
- [Thing]: [why it's outdated, what replaced it]
|
||||
</sota_updates>
|
||||
|
||||
<open_questions>
|
||||
## Open Questions
|
||||
|
||||
Things that couldn't be fully resolved:
|
||||
|
||||
1. **[Question]**
|
||||
- What we know: [partial info]
|
||||
- What's unclear: [the gap]
|
||||
- Recommendation: [how to handle during planning/execution]
|
||||
|
||||
2. **[Question]**
|
||||
- What we know: [partial info]
|
||||
- What's unclear: [the gap]
|
||||
- Recommendation: [how to handle]
|
||||
</open_questions>
|
||||
|
||||
<sources>
|
||||
## Sources
|
||||
|
||||
### Primary (HIGH confidence)
|
||||
- [Context7 library ID] - [topics fetched]
|
||||
- [Official docs URL] - [what was checked]
|
||||
|
||||
### Secondary (MEDIUM confidence)
|
||||
- [WebSearch verified with official source] - [finding + verification]
|
||||
|
||||
### Tertiary (LOW confidence - needs validation)
|
||||
- [WebSearch only] - [finding, marked for validation during implementation]
|
||||
</sources>
|
||||
|
||||
<metadata>
|
||||
## Metadata
|
||||
|
||||
**Research scope:**
|
||||
- Core technology: [what]
|
||||
- Ecosystem: [libraries explored]
|
||||
- Patterns: [patterns researched]
|
||||
- Pitfalls: [areas checked]
|
||||
|
||||
**Confidence breakdown:**
|
||||
- Standard stack: [HIGH/MEDIUM/LOW] - [reason]
|
||||
- Architecture: [HIGH/MEDIUM/LOW] - [reason]
|
||||
- Pitfalls: [HIGH/MEDIUM/LOW] - [reason]
|
||||
- Code examples: [HIGH/MEDIUM/LOW] - [reason]
|
||||
|
||||
**Research date:** [date]
|
||||
**Valid until:** [estimate - 30 days for stable tech, 7 days for fast-moving]
|
||||
</metadata>
|
||||
|
||||
---
|
||||
|
||||
*Phase: XX-name*
|
||||
*Research completed: [date]*
|
||||
*Ready for planning: [yes/no]*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Good Example
|
||||
|
||||
```markdown
|
||||
# Phase 3: 3D City Driving - Research
|
||||
|
||||
**Researched:** 2025-01-20
|
||||
**Domain:** Three.js 3D web game with driving mechanics
|
||||
**Confidence:** HIGH
|
||||
|
||||
<research_summary>
|
||||
## Summary
|
||||
|
||||
Researched the Three.js ecosystem for building a 3D city driving game. The standard approach uses Three.js with React Three Fiber for component architecture, Rapier for physics, and drei for common helpers.
|
||||
|
||||
Key finding: Don't hand-roll physics or collision detection. Rapier (via @react-three/rapier) handles vehicle physics, terrain collision, and city object interactions efficiently. Custom physics code leads to bugs and performance issues.
|
||||
|
||||
**Primary recommendation:** Use R3F + Rapier + drei stack. Start with vehicle controller from drei, add Rapier vehicle physics, build city with instanced meshes for performance.
|
||||
</research_summary>
|
||||
|
||||
<standard_stack>
|
||||
## Standard Stack
|
||||
|
||||
### Core
|
||||
| Library | Version | Purpose | Why Standard |
|
||||
|---------|---------|---------|--------------|
|
||||
| three | 0.160.0 | 3D rendering | The standard for web 3D |
|
||||
| @react-three/fiber | 8.15.0 | React renderer for Three.js | Declarative 3D, better DX |
|
||||
| @react-three/drei | 9.92.0 | Helpers and abstractions | Solves common problems |
|
||||
| @react-three/rapier | 1.2.1 | Physics engine bindings | Best physics for R3F |
|
||||
|
||||
### Supporting
|
||||
| Library | Version | Purpose | When to Use |
|
||||
|---------|---------|---------|-------------|
|
||||
| @react-three/postprocessing | 2.16.0 | Visual effects | Bloom, DOF, motion blur |
|
||||
| leva | 0.9.35 | Debug UI | Tweaking parameters |
|
||||
| zustand | 4.4.7 | State management | Game state, UI state |
|
||||
| use-sound | 4.0.1 | Audio | Engine sounds, ambient |
|
||||
|
||||
### Alternatives Considered
|
||||
| Instead of | Could Use | Tradeoff |
|
||||
|------------|-----------|----------|
|
||||
| Rapier | Cannon.js | Cannon simpler but less performant for vehicles |
|
||||
| R3F | Vanilla Three | Vanilla if no React, but R3F DX is much better |
|
||||
| drei | Custom helpers | drei is battle-tested, don't reinvent |
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
npm install three @react-three/fiber @react-three/drei @react-three/rapier zustand
|
||||
```
|
||||
</standard_stack>
|
||||
|
||||
<architecture_patterns>
|
||||
## Architecture Patterns
|
||||
|
||||
### Recommended Project Structure
|
||||
```
|
||||
src/
|
||||
├── components/
|
||||
│ ├── Vehicle/ # Player car with physics
|
||||
│ ├── City/ # City generation and buildings
|
||||
│ ├── Road/ # Road network
|
||||
│ └── Environment/ # Sky, lighting, fog
|
||||
├── hooks/
|
||||
│ ├── useVehicleControls.ts
|
||||
│ └── useGameState.ts
|
||||
├── stores/
|
||||
│ └── gameStore.ts # Zustand state
|
||||
└── utils/
|
||||
└── cityGenerator.ts # Procedural generation helpers
|
||||
```
|
||||
|
||||
### Pattern 1: Vehicle with Rapier Physics
|
||||
**What:** Use RigidBody with vehicle-specific settings, not custom physics
|
||||
**When to use:** Any ground vehicle
|
||||
**Example:**
|
||||
```typescript
|
||||
// Source: @react-three/rapier docs
|
||||
import { RigidBody, useRapier } from '@react-three/rapier'
|
||||
|
||||
function Vehicle() {
|
||||
const rigidBody = useRef()
|
||||
|
||||
return (
|
||||
<RigidBody
|
||||
ref={rigidBody}
|
||||
type="dynamic"
|
||||
colliders="hull"
|
||||
mass={1500}
|
||||
linearDamping={0.5}
|
||||
angularDamping={0.5}
|
||||
>
|
||||
<mesh>
|
||||
<boxGeometry args={[2, 1, 4]} />
|
||||
<meshStandardMaterial />
|
||||
</mesh>
|
||||
</RigidBody>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 2: Instanced Meshes for City
|
||||
**What:** Use InstancedMesh for repeated objects (buildings, trees, props)
|
||||
**When to use:** >100 similar objects
|
||||
**Example:**
|
||||
```typescript
|
||||
// Source: drei docs
|
||||
import { Instances, Instance } from '@react-three/drei'
|
||||
|
||||
function Buildings({ positions }) {
|
||||
return (
|
||||
<Instances limit={1000}>
|
||||
<boxGeometry />
|
||||
<meshStandardMaterial />
|
||||
{positions.map((pos, i) => (
|
||||
<Instance key={i} position={pos} scale={[1, Math.random() * 5 + 1, 1]} />
|
||||
))}
|
||||
</Instances>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Anti-Patterns to Avoid
|
||||
- **Creating meshes in render loop:** Create once, update transforms only
|
||||
- **Not using InstancedMesh:** Individual meshes for buildings kills performance
|
||||
- **Custom physics math:** Rapier handles it better, every time
|
||||
</architecture_patterns>
|
||||
|
||||
<dont_hand_roll>
|
||||
## Don't Hand-Roll
|
||||
|
||||
| Problem | Don't Build | Use Instead | Why |
|
||||
|---------|-------------|-------------|-----|
|
||||
| Vehicle physics | Custom velocity/acceleration | Rapier RigidBody | Wheel friction, suspension, collisions are complex |
|
||||
| Collision detection | Raycasting everything | Rapier colliders | Performance, edge cases, tunneling |
|
||||
| Camera follow | Manual lerp | drei CameraControls or custom with useFrame | Smooth interpolation, bounds |
|
||||
| City generation | Pure random placement | Grid-based with noise for variation | Random looks wrong, grid is predictable |
|
||||
| LOD | Manual distance checks | drei <Detailed> | Handles transitions, hysteresis |
|
||||
|
||||
**Key insight:** 3D game development has 40+ years of solved problems. Rapier implements proper physics simulation. drei implements proper 3D helpers. Fighting these leads to bugs that look like "game feel" issues but are actually physics edge cases.
|
||||
</dont_hand_roll>
|
||||
|
||||
<common_pitfalls>
|
||||
## Common Pitfalls
|
||||
|
||||
### Pitfall 1: Physics Tunneling
|
||||
**What goes wrong:** Fast objects pass through walls
|
||||
**Why it happens:** Default physics step too large for velocity
|
||||
**How to avoid:** Use CCD (Continuous Collision Detection) in Rapier
|
||||
**Warning signs:** Objects randomly appearing outside buildings
|
||||
|
||||
### Pitfall 2: Performance Death by Draw Calls
|
||||
**What goes wrong:** Game stutters with many buildings
|
||||
**Why it happens:** Each mesh = 1 draw call, hundreds of buildings = hundreds of calls
|
||||
**How to avoid:** InstancedMesh for similar objects, merge static geometry
|
||||
**Warning signs:** GPU bound, low FPS despite simple scene
|
||||
|
||||
### Pitfall 3: Vehicle "Floaty" Feel
|
||||
**What goes wrong:** Car doesn't feel grounded
|
||||
**Why it happens:** Missing proper wheel/suspension simulation
|
||||
**How to avoid:** Use Rapier vehicle controller or tune mass/damping carefully
|
||||
**Warning signs:** Car bounces oddly, doesn't grip corners
|
||||
</common_pitfalls>
|
||||
|
||||
<code_examples>
|
||||
## Code Examples
|
||||
|
||||
### Basic R3F + Rapier Setup
|
||||
```typescript
|
||||
// Source: @react-three/rapier getting started
|
||||
import { Canvas } from '@react-three/fiber'
|
||||
import { Physics } from '@react-three/rapier'
|
||||
|
||||
function Game() {
|
||||
return (
|
||||
<Canvas>
|
||||
<Physics gravity={[0, -9.81, 0]}>
|
||||
<Vehicle />
|
||||
<City />
|
||||
<Ground />
|
||||
</Physics>
|
||||
</Canvas>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Vehicle Controls Hook
|
||||
```typescript
|
||||
// Source: Community pattern, verified with drei docs
|
||||
import { useFrame } from '@react-three/fiber'
|
||||
import { useKeyboardControls } from '@react-three/drei'
|
||||
|
||||
function useVehicleControls(rigidBodyRef) {
|
||||
const [, getKeys] = useKeyboardControls()
|
||||
|
||||
useFrame(() => {
|
||||
const { forward, back, left, right } = getKeys()
|
||||
const body = rigidBodyRef.current
|
||||
if (!body) return
|
||||
|
||||
const impulse = { x: 0, y: 0, z: 0 }
|
||||
if (forward) impulse.z -= 10
|
||||
if (back) impulse.z += 5
|
||||
|
||||
body.applyImpulse(impulse, true)
|
||||
|
||||
if (left) body.applyTorqueImpulse({ x: 0, y: 2, z: 0 }, true)
|
||||
if (right) body.applyTorqueImpulse({ x: 0, y: -2, z: 0 }, true)
|
||||
})
|
||||
}
|
||||
```
|
||||
</code_examples>
|
||||
|
||||
<sota_updates>
|
||||
## State of the Art (2024-2025)
|
||||
|
||||
| Old Approach | Current Approach | When Changed | Impact |
|
||||
|--------------|------------------|--------------|--------|
|
||||
| cannon-es | Rapier | 2023 | Rapier is faster, better maintained |
|
||||
| vanilla Three.js | React Three Fiber | 2020+ | R3F is now standard for React apps |
|
||||
| Manual InstancedMesh | drei <Instances> | 2022 | Simpler API, handles updates |
|
||||
|
||||
**New tools/patterns to consider:**
|
||||
- **WebGPU:** Coming but not production-ready for games yet (2025)
|
||||
- **drei Gltf helpers:** <useGLTF.preload> for loading screens
|
||||
|
||||
**Deprecated/outdated:**
|
||||
- **cannon.js (original):** Use cannon-es fork or better, Rapier
|
||||
- **Manual raycasting for physics:** Just use Rapier colliders
|
||||
</sota_updates>
|
||||
|
||||
<sources>
|
||||
## Sources
|
||||
|
||||
### Primary (HIGH confidence)
|
||||
- /pmndrs/react-three-fiber - getting started, hooks, performance
|
||||
- /pmndrs/drei - instances, controls, helpers
|
||||
- /dimforge/rapier-js - physics setup, vehicle physics
|
||||
|
||||
### Secondary (MEDIUM confidence)
|
||||
- Three.js discourse "city driving game" threads - verified patterns against docs
|
||||
- R3F examples repository - verified code works
|
||||
|
||||
### Tertiary (LOW confidence - needs validation)
|
||||
- None - all findings verified
|
||||
</sources>
|
||||
|
||||
<metadata>
|
||||
## Metadata
|
||||
|
||||
**Research scope:**
|
||||
- Core technology: Three.js + React Three Fiber
|
||||
- Ecosystem: Rapier, drei, zustand
|
||||
- Patterns: Vehicle physics, instancing, city generation
|
||||
- Pitfalls: Performance, physics, feel
|
||||
|
||||
**Confidence breakdown:**
|
||||
- Standard stack: HIGH - verified with Context7, widely used
|
||||
- Architecture: HIGH - from official examples
|
||||
- Pitfalls: HIGH - documented in discourse, verified in docs
|
||||
- Code examples: HIGH - from Context7/official sources
|
||||
|
||||
**Research date:** 2025-01-20
|
||||
**Valid until:** 2025-02-20 (30 days - R3F ecosystem stable)
|
||||
</metadata>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 03-city-driving*
|
||||
*Research completed: 2025-01-20*
|
||||
*Ready for planning: yes*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Guidelines
|
||||
|
||||
**When to create:**
|
||||
- Before planning phases in niche/complex domains
|
||||
- When Claude's training data is likely stale or sparse
|
||||
- When "how do experts do this" matters more than "which library"
|
||||
|
||||
**Structure:**
|
||||
- Use XML tags for section markers (matches GSD templates)
|
||||
- Seven core sections: summary, standard_stack, architecture_patterns, dont_hand_roll, common_pitfalls, code_examples, sources
|
||||
- All sections required (drives comprehensive research)
|
||||
|
||||
**Content quality:**
|
||||
- Standard stack: Specific versions, not just names
|
||||
- Architecture: Include actual code examples from authoritative sources
|
||||
- Don't hand-roll: Be explicit about what problems to NOT solve yourself
|
||||
- Pitfalls: Include warning signs, not just "don't do this"
|
||||
- Sources: Mark confidence levels honestly
|
||||
|
||||
**Integration with planning:**
|
||||
- RESEARCH.md loaded as @context reference in PLAN.md
|
||||
- Standard stack informs library choices
|
||||
- Don't hand-roll prevents custom solutions
|
||||
- Pitfalls inform verification criteria
|
||||
- Code examples can be referenced in task actions
|
||||
|
||||
**After creation:**
|
||||
- File lives in phase directory: `.planning/phases/XX-name/{phase}-RESEARCH.md`
|
||||
- Referenced during planning workflow
|
||||
- plan-phase loads it automatically when present
|
||||
|
|
@ -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):**
|
||||
- Phase count depends on depth setting (quick: 3-5, standard: 5-8, comprehensive: 8-12)
|
||||
- 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
|
||||
|
|
@ -0,0 +1,210 @@
|
|||
# State Template
|
||||
|
||||
Template for `.planning/STATE.md` — the project's living memory.
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
# Project State
|
||||
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated [date])
|
||||
|
||||
**Core value:** [One-liner from PROJECT.md Core Value section]
|
||||
**Current focus:** [Current phase name]
|
||||
|
||||
## 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
|
||||
|
||||
Decisions are logged in PROJECT.md Key Decisions table.
|
||||
Recent decisions affecting current work:
|
||||
|
||||
- [Phase X]: [Decision summary]
|
||||
- [Phase Y]: [Decision summary]
|
||||
|
||||
### Deferred Issues
|
||||
|
||||
[From ISSUES.md — list open items with phase of origin]
|
||||
|
||||
None yet.
|
||||
|
||||
### Blockers/Concerns
|
||||
|
||||
[Issues that affect future work]
|
||||
|
||||
None yet.
|
||||
|
||||
## 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 spanning all phases and sessions.
|
||||
|
||||
**Problem it solves:** Information is captured in summaries, issues, and decisions but not systematically consumed. Sessions start without context.
|
||||
|
||||
**Solution:** A single, small file that's:
|
||||
- Read first in every workflow
|
||||
- Updated after every significant action
|
||||
- Contains digest of accumulated context
|
||||
- Enables instant session restoration
|
||||
|
||||
</purpose>
|
||||
|
||||
<lifecycle>
|
||||
|
||||
**Creation:** After ROADMAP.md is created (during init)
|
||||
- Reference PROJECT.md (read it for current context)
|
||||
- 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)
|
||||
- Note new decisions (detail in PROJECT.md)
|
||||
- Update deferred issues list
|
||||
- Add blockers/concerns
|
||||
- transition: After phase marked complete
|
||||
- Update progress bar
|
||||
- Clear resolved blockers
|
||||
- Refresh Project Reference date
|
||||
|
||||
</lifecycle>
|
||||
|
||||
<sections>
|
||||
|
||||
### Project Reference
|
||||
Points to PROJECT.md for full context. Includes:
|
||||
- Core value (the ONE thing that matters)
|
||||
- Current focus (which phase)
|
||||
- Last update date (triggers re-read if stale)
|
||||
|
||||
Claude reads PROJECT.md directly for requirements, constraints, and decisions.
|
||||
|
||||
### 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:** Reference to PROJECT.md Key Decisions table, plus recent decisions summary for quick access. Full decision log lives in PROJECT.md.
|
||||
|
||||
**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
|
||||
|
||||
### 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 100 lines.
|
||||
|
||||
It's a DIGEST, not an archive. If accumulated context grows too large:
|
||||
- Keep only 3-5 recent decisions in summary (full log in PROJECT.md)
|
||||
- Reference ISSUES.md instead of listing all: "12 open issues — see ISSUES.md"
|
||||
- Keep only active blockers, remove resolved ones
|
||||
|
||||
The goal is "read once, know where we are" — if it's too long, that fails.
|
||||
|
||||
</size_constraint>
|
||||
|
||||
<guidelines>
|
||||
|
||||
**When created:**
|
||||
- During project initialization (after ROADMAP.md)
|
||||
- Reference PROJECT.md (extract core value and current focus)
|
||||
- Initialize empty sections
|
||||
|
||||
**When read:**
|
||||
- Every workflow starts by reading STATE.md
|
||||
- Then read PROJECT.md for full context
|
||||
- Provides instant context restoration
|
||||
|
||||
**When updated:**
|
||||
- After each plan execution (update position, note decisions, update issues/blockers)
|
||||
- After phase transitions (update progress bar, clear resolved blockers, refresh project reference)
|
||||
|
||||
**Size management:**
|
||||
- Keep under 100 lines total
|
||||
- Recent decisions only in STATE.md (full log in PROJECT.md)
|
||||
- Reference ISSUES.md instead of listing all issues
|
||||
- Keep only active blockers
|
||||
|
||||
**Sections:**
|
||||
- Project Reference: Pointer to PROJECT.md with core value
|
||||
- Current Position: Where we are now (phase, plan, status)
|
||||
- Performance Metrics: Velocity tracking
|
||||
- Accumulated Context: Recent decisions, deferred issues, blockers
|
||||
- Session Continuity: Resume information
|
||||
|
||||
</guidelines>
|
||||
|
|
@ -0,0 +1,273 @@
|
|||
# Summary Template
|
||||
|
||||
Template for `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md` - phase completion documentation.
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
phase: XX-name
|
||||
plan: YY
|
||||
subsystem: [primary category: auth, payments, ui, api, database, infra, testing, etc.]
|
||||
tags: [searchable tech: jwt, stripe, react, postgres, prisma]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: [prior phase this depends on]
|
||||
provides: [what that phase built that this uses]
|
||||
provides:
|
||||
- [bullet list of what this phase built/delivered]
|
||||
affects: [list of phase names or keywords that will need this context]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: [libraries/tools added in this phase]
|
||||
patterns: [architectural/code patterns established]
|
||||
|
||||
key-files:
|
||||
created: [important files created]
|
||||
modified: [important files modified]
|
||||
|
||||
key-decisions:
|
||||
- "Decision 1"
|
||||
- "Decision 2"
|
||||
|
||||
patterns-established:
|
||||
- "Pattern 1: description"
|
||||
- "Pattern 2: description"
|
||||
|
||||
issues-created: [ISS-XXX, ISS-YYY] # From ISSUES.md if any
|
||||
|
||||
# Metrics
|
||||
duration: Xmin
|
||||
completed: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# 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]
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: [task name]** - `abc123f` (feat/fix/test/refactor)
|
||||
2. **Task 2: [task name]** - `def456g` (feat/fix/test/refactor)
|
||||
3. **Task 3: [task name]** - `hij789k` (feat/fix/test/refactor)
|
||||
|
||||
**Plan metadata:** `lmn012o` (docs: complete plan)
|
||||
|
||||
_Note: TDD tasks may have multiple commits (test → feat → refactor)_
|
||||
|
||||
## 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]
|
||||
- **Committed in:** [hash] (part of task commit)
|
||||
|
||||
[... 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]*
|
||||
```
|
||||
|
||||
<frontmatter_guidance>
|
||||
**Purpose:** Enable automatic context assembly via dependency graph. Frontmatter makes summary metadata machine-readable so plan-phase can scan all summaries quickly and select relevant ones based on dependencies.
|
||||
|
||||
**Fast scanning:** Frontmatter is first ~25 lines, cheap to scan across all summaries without reading full content.
|
||||
|
||||
**Dependency graph:** `requires`/`provides`/`affects` create explicit links between phases, enabling transitive closure for context selection.
|
||||
|
||||
**Subsystem:** Primary categorization (auth, payments, ui, api, database, infra, testing) for detecting related phases.
|
||||
|
||||
**Tags:** Searchable technical keywords (libraries, frameworks, tools) for tech stack awareness.
|
||||
|
||||
**Key-files:** Important files for @context references in PLAN.md.
|
||||
|
||||
**Patterns:** Established conventions future phases should maintain.
|
||||
|
||||
**Population:** Frontmatter is populated during summary creation in execute-phase.md. See `<step name="create_summary">` for field-by-field guidance.
|
||||
</frontmatter_guidance>
|
||||
|
||||
<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
|
||||
- **Committed in:** abc123f (Task 2 commit)
|
||||
|
||||
**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
|
||||
- **Committed in:** def456g (Task 4 commit)
|
||||
|
||||
### 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
|
||||
|
||||
**Frontmatter completion:**
|
||||
- MANDATORY: Complete all frontmatter fields during summary creation
|
||||
- See <frontmatter_guidance> for field purposes
|
||||
- Frontmatter enables automatic context assembly for future planning
|
||||
|
||||
**One-liner requirements:**
|
||||
- Must be substantive (describe what shipped, not "phase complete")
|
||||
- Should tell someone what was accomplished
|
||||
- Examples: "JWT auth with refresh rotation using jose library" not "Authentication implemented"
|
||||
|
||||
**Performance tracking:**
|
||||
- Include duration, start/end timestamps
|
||||
- Used for velocity metrics in STATE.md
|
||||
|
||||
**Deviations section:**
|
||||
- Documents unplanned work handled via deviation rules
|
||||
- Separate from "Issues Encountered" (which is planned work problems)
|
||||
- Auto-fixed issues: What was wrong, how fixed, verification
|
||||
- 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>
|
||||
|
|
@ -0,0 +1,143 @@
|
|||
# UAT Issues Template
|
||||
|
||||
Template for `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md` - phase-scoped issues discovered during user acceptance testing.
|
||||
|
||||
**Purpose:** Capture issues found during /gsd:verify-work. Unlike global ISSUES.md (for deferred enhancements), this file tracks bugs and problems in specific delivered work.
|
||||
|
||||
**Location:** Same directory as the SUMMARY.md being tested.
|
||||
|
||||
---
|
||||
|
||||
## File Template
|
||||
|
||||
```markdown
|
||||
# UAT Issues: Phase [X] Plan [Y]
|
||||
|
||||
**Tested:** [date]
|
||||
**Source:** [path to SUMMARY.md that was tested]
|
||||
**Tester:** User via /gsd:verify-work
|
||||
|
||||
## Open Issues
|
||||
|
||||
### UAT-001: [Brief description]
|
||||
|
||||
**Discovered:** [date]
|
||||
**Phase/Plan:** [XX]-[YY]
|
||||
**Severity:** [Blocker/Major/Minor/Cosmetic]
|
||||
**Feature:** [Which feature from the test checklist]
|
||||
**Description:** [User's description of the problem]
|
||||
**Expected:** [What should have happened]
|
||||
**Actual:** [What actually happened]
|
||||
**Repro:** [Steps to reproduce, if captured]
|
||||
|
||||
### UAT-002: [Brief description]
|
||||
|
||||
...
|
||||
|
||||
## Resolved Issues
|
||||
|
||||
[Moved here after /gsd:plan-fix executes and fixes are verified]
|
||||
|
||||
### UAT-001: [Brief description]
|
||||
**Resolved:** [date] - Fixed in [phase]-[plan]-FIX.md
|
||||
**Commit:** [hash]
|
||||
|
||||
---
|
||||
|
||||
*Phase: XX-name*
|
||||
*Plan: YY*
|
||||
*Tested: [date]*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Severity Guide
|
||||
|
||||
| Severity | Definition | Example |
|
||||
|----------|------------|---------|
|
||||
| **Blocker** | Feature completely unusable | App crashes on button click |
|
||||
| **Major** | Feature works but significant problem | Form submits but data not saved |
|
||||
| **Minor** | Feature usable but has issues | Button text slightly cut off |
|
||||
| **Cosmetic** | Visual only, no functional impact | Wrong shade of color |
|
||||
|
||||
---
|
||||
|
||||
## UAT Numbering
|
||||
|
||||
- **Prefix:** `UAT-` (distinguishes from ISS- enhancement issues)
|
||||
- **Scope:** Per-file numbering (UAT-001, UAT-002, etc. within each file)
|
||||
- **No global numbering:** Each {phase}-{plan}-ISSUES.md has its own sequence
|
||||
|
||||
---
|
||||
|
||||
<good_examples>
|
||||
```markdown
|
||||
# UAT Issues: Phase 5 Plan 2
|
||||
|
||||
**Tested:** 2025-01-15
|
||||
**Source:** .planning/phases/05-auth/05-02-SUMMARY.md
|
||||
**Tester:** User via /gsd:verify-work
|
||||
|
||||
## Open Issues
|
||||
|
||||
### UAT-001: Login form doesn't show validation errors
|
||||
|
||||
**Discovered:** 2025-01-15
|
||||
**Phase/Plan:** 05-02
|
||||
**Severity:** Major
|
||||
**Feature:** User login form
|
||||
**Description:** When I enter an invalid email, nothing happens. No error message appears.
|
||||
**Expected:** Red error message below email field saying "Invalid email format"
|
||||
**Actual:** Field border turns red but no text explanation
|
||||
**Repro:**
|
||||
1. Go to /login
|
||||
2. Enter "notanemail" in email field
|
||||
3. Click Login button
|
||||
|
||||
### UAT-002: Password field allows paste
|
||||
|
||||
**Discovered:** 2025-01-15
|
||||
**Phase/Plan:** 05-02
|
||||
**Severity:** Cosmetic
|
||||
**Feature:** User login form
|
||||
**Description:** Can paste into password field. Minor UX inconsistency.
|
||||
**Expected:** Paste disabled (matches signup form)
|
||||
**Actual:** Paste works in login but not signup
|
||||
**Repro:** Ctrl+V in password field
|
||||
|
||||
## Resolved Issues
|
||||
|
||||
[None yet]
|
||||
|
||||
---
|
||||
|
||||
*Phase: 05-auth*
|
||||
*Plan: 02*
|
||||
*Tested: 2025-01-15*
|
||||
```
|
||||
</good_examples>
|
||||
|
||||
<guidelines>
|
||||
**When to create:**
|
||||
- First time /gsd:verify-work finds an issue for a plan
|
||||
- One file per plan tested
|
||||
|
||||
**Location:**
|
||||
- `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md`
|
||||
- Lives alongside SUMMARY.md being tested
|
||||
|
||||
**Difference from global ISSUES.md:**
|
||||
- Global ISSUES.md: Deferred enhancements (Rule 5 - nice-to-haves)
|
||||
- UAT ISSUES.md: Actual problems found during testing
|
||||
|
||||
**Workflow:**
|
||||
1. /gsd:verify-work creates this file with issues
|
||||
2. /gsd:plan-fix reads this file and creates FIX.md plan
|
||||
3. After FIX.md executes, issues move to "Resolved" section
|
||||
4. File becomes historical record of what was found and fixed
|
||||
|
||||
**Resolution:**
|
||||
- Don't delete resolved issues - move to "Resolved Issues" section
|
||||
- Include fix reference (commit hash, plan that fixed it)
|
||||
- File serves as audit trail
|
||||
</guidelines>
|
||||
|
|
@ -0,0 +1,643 @@
|
|||
<purpose>
|
||||
|
||||
Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical record in MILESTONES.md, performs full PROJECT.md evolution review, 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. Performs full PROJECT.md evolution review
|
||||
5. 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
|
||||
```
|
||||
|
||||
<config-check>
|
||||
|
||||
```bash
|
||||
cat .planning/config.json 2>/dev/null
|
||||
```
|
||||
|
||||
</config-check>
|
||||
|
||||
<if mode="yolo">
|
||||
|
||||
```
|
||||
⚡ Auto-approved: Milestone scope verification
|
||||
|
||||
[Show breakdown summary without prompting]
|
||||
|
||||
Proceeding to stats gathering...
|
||||
```
|
||||
|
||||
Proceed directly to gather_stats step.
|
||||
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="custom with gates.confirm_milestone_scope true">
|
||||
|
||||
```
|
||||
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.
|
||||
|
||||
</if>
|
||||
|
||||
</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="evolve_project_full_review">
|
||||
|
||||
Perform full PROJECT.md evolution review at milestone completion.
|
||||
|
||||
**Read all phase summaries in this milestone:**
|
||||
|
||||
```bash
|
||||
cat .planning/phases/*-*/*-SUMMARY.md
|
||||
```
|
||||
|
||||
**Full review checklist:**
|
||||
|
||||
1. **"What This Is" accuracy:**
|
||||
- Read current description
|
||||
- Compare to what was actually built
|
||||
- Update if the product has meaningfully changed
|
||||
|
||||
2. **Core Value check:**
|
||||
- Is the stated core value still the right priority?
|
||||
- Did shipping reveal a different core value?
|
||||
- Update if the ONE thing has shifted
|
||||
|
||||
3. **Requirements audit:**
|
||||
|
||||
**Validated section:**
|
||||
- All Active requirements shipped in this milestone → Move to Validated
|
||||
- Format: `- ✓ [Requirement] — v[X.Y]`
|
||||
|
||||
**Active section:**
|
||||
- Remove requirements that moved to Validated
|
||||
- Add any new requirements for next milestone
|
||||
- Keep requirements that weren't addressed yet
|
||||
|
||||
**Out of Scope audit:**
|
||||
- Review each item — is the reasoning still valid?
|
||||
- Remove items that are no longer relevant
|
||||
- Add any requirements invalidated during this milestone
|
||||
|
||||
4. **Context update:**
|
||||
- Current codebase state (LOC, tech stack)
|
||||
- User feedback themes (if any)
|
||||
- Known issues or technical debt to address
|
||||
|
||||
5. **Key Decisions audit:**
|
||||
- Extract all decisions from milestone phase summaries
|
||||
- Add to Key Decisions table with outcomes where known
|
||||
- Mark ✓ Good, ⚠️ Revisit, or — Pending for each
|
||||
|
||||
6. **Constraints check:**
|
||||
- Any constraints that changed during development?
|
||||
- Update as needed
|
||||
|
||||
**Update PROJECT.md:**
|
||||
|
||||
Make all edits inline. Update "Last updated" footer:
|
||||
|
||||
```markdown
|
||||
---
|
||||
*Last updated: [date] after v[X.Y] milestone*
|
||||
```
|
||||
|
||||
**Example full evolution (v1.0 → v1.1 prep):**
|
||||
|
||||
Before:
|
||||
|
||||
```markdown
|
||||
## What This Is
|
||||
|
||||
A real-time collaborative whiteboard for remote teams.
|
||||
|
||||
## Core Value
|
||||
|
||||
Real-time sync that feels instant.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
|
||||
(None yet — ship to validate)
|
||||
|
||||
### Active
|
||||
|
||||
- [ ] Canvas drawing tools
|
||||
- [ ] Real-time sync < 500ms
|
||||
- [ ] User authentication
|
||||
- [ ] Export to PNG
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- Mobile app — web-first approach
|
||||
- Video chat — use external tools
|
||||
```
|
||||
|
||||
After v1.0:
|
||||
|
||||
```markdown
|
||||
## What This Is
|
||||
|
||||
A real-time collaborative whiteboard for remote teams with instant sync and drawing tools.
|
||||
|
||||
## Core Value
|
||||
|
||||
Real-time sync that feels instant.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
|
||||
- ✓ Canvas drawing tools — v1.0
|
||||
- ✓ Real-time sync < 500ms — v1.0 (achieved 200ms avg)
|
||||
- ✓ User authentication — v1.0
|
||||
|
||||
### Active
|
||||
|
||||
- [ ] Export to PNG
|
||||
- [ ] Undo/redo history
|
||||
- [ ] Shape tools (rectangles, circles)
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- Mobile app — web-first approach, PWA works well
|
||||
- Video chat — use external tools
|
||||
- Offline mode — real-time is core value
|
||||
|
||||
## Context
|
||||
|
||||
Shipped v1.0 with 2,400 LOC TypeScript.
|
||||
Tech stack: Next.js, Supabase, Canvas API.
|
||||
Initial user testing showed demand for shape tools.
|
||||
```
|
||||
|
||||
**Step complete when:**
|
||||
|
||||
- [ ] "What This Is" reviewed and updated if needed
|
||||
- [ ] Core Value verified as still correct
|
||||
- [ ] All shipped requirements moved to Validated
|
||||
- [ ] New requirements added to Active for next milestone
|
||||
- [ ] Out of Scope reasoning audited
|
||||
- [ ] Context updated with current state
|
||||
- [ ] All milestone decisions added to Key Decisions
|
||||
- [ ] "Last updated" footer reflects milestone completion
|
||||
|
||||
</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 PROJECT.md:
|
||||
- Key decisions made during this milestone
|
||||
- Requirements that were validated
|
||||
|
||||
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}} — Key decisions from PROJECT.md
|
||||
- {{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
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="update_state">
|
||||
|
||||
Update STATE.md to reflect milestone completion.
|
||||
|
||||
**Project Reference:**
|
||||
|
||||
```markdown
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated [today])
|
||||
|
||||
**Core value:** [Current core value from PROJECT.md]
|
||||
**Current focus:** [Next milestone or "Planning next milestone"]
|
||||
```
|
||||
|
||||
**Current Position:**
|
||||
|
||||
```markdown
|
||||
Phase: [Next phase] of [Total] ([Phase name])
|
||||
Plan: Not started
|
||||
Status: Ready to plan
|
||||
Last activity: [today] — v[X.Y] milestone complete
|
||||
|
||||
Progress: [updated progress bar]
|
||||
```
|
||||
|
||||
**Accumulated Context:**
|
||||
|
||||
- Clear decisions summary (full log in PROJECT.md)
|
||||
- Clear resolved blockers
|
||||
- Keep open blockers for next milestone
|
||||
|
||||
</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/STATE.md
|
||||
git add .planning/milestones/v[X.Y]-ROADMAP.md
|
||||
|
||||
# Commit with descriptive message
|
||||
git commit -m "$(cat <<'EOF'
|
||||
chore: complete v[X.Y] milestone
|
||||
|
||||
- Added MILESTONES.md entry
|
||||
- Evolved PROJECT.md with validated requirements
|
||||
- Reorganized ROADMAP.md with milestone grouping
|
||||
- Created milestone archive: milestones/v[X.Y]-ROADMAP.md
|
||||
- Updated STATE.md
|
||||
- Tagged v[X.Y]
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
Confirm: "Committed: chore: complete v[X.Y] milestone"
|
||||
|
||||
</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 Up
|
||||
|
||||
**Plan Next Milestone** — define v[X.Y+1] features and scope
|
||||
|
||||
`/gsd:discuss-milestone`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:new-milestone` — create directly if scope is clear
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</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 full evolution review completed
|
||||
- [ ] All shipped requirements moved to Validated
|
||||
- [ ] Key Decisions updated with outcomes
|
||||
- [ ] ROADMAP.md reorganized with milestone grouping
|
||||
- [ ] Milestone archive created
|
||||
- [ ] STATE.md updated with fresh project reference
|
||||
- [ ] Git tag created (v[X.Y])
|
||||
- [ ] Milestone commit made
|
||||
- [ ] User knows next steps
|
||||
|
||||
</success_criteria>
|
||||
|
|
@ -0,0 +1,416 @@
|
|||
<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"
|
||||
cat .planning/MILESTONE-CONTEXT.md 2>/dev/null || echo "No milestone context file"
|
||||
```
|
||||
|
||||
Extract:
|
||||
|
||||
- Previous milestone version (e.g., v1.0)
|
||||
- Last phase number used
|
||||
- Deferred issues from STATE.md
|
||||
- Project context from PROJECT.md (What This Is, Core Value)
|
||||
|
||||
**Check for milestone context from discuss-milestone:**
|
||||
|
||||
If `.planning/MILESTONE-CONTEXT.md` exists:
|
||||
- This contains context from `/gsd:discuss-milestone`
|
||||
- Extract: features, suggested name, phase mapping, constraints
|
||||
- Use this to pre-populate milestone details (skip prompting for info already gathered)
|
||||
|
||||
**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 MILESTONE-CONTEXT.md exists (from /gsd:discuss-milestone):**
|
||||
Use the features, scope, and constraints from the context file.
|
||||
Use the suggested milestone name from `<scope>` section.
|
||||
Use the phase mapping from `<phase_mapping>` section.
|
||||
|
||||
**If called directly (no MILESTONE-CONTEXT.md):**
|
||||
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]
|
||||
|
||||
**Check depth setting and gather phases accordingly:**
|
||||
|
||||
```bash
|
||||
cat .planning/config.json 2>/dev/null | grep depth
|
||||
```
|
||||
|
||||
| Depth | Phases/Milestone |
|
||||
|-------|------------------|
|
||||
| Quick | 3-5 |
|
||||
| Standard | 5-8 |
|
||||
| Comprehensive | 8-12 |
|
||||
|
||||
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">
|
||||
<config-check>
|
||||
```bash
|
||||
cat .planning/config.json 2>/dev/null
|
||||
```
|
||||
</config-check>
|
||||
|
||||
<if mode="yolo">
|
||||
```
|
||||
⚡ Auto-approved: Milestone phases ([N] phases)
|
||||
|
||||
1. Phase [X]: [Name] - [goal]
|
||||
2. Phase [X+1]: [Name] - [goal]
|
||||
...
|
||||
|
||||
Proceeding to create milestone structure...
|
||||
```
|
||||
|
||||
Proceed directly to update_roadmap step.
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="missing OR custom with gates.confirm_phases true">
|
||||
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">
|
||||
Write new milestone details to `.planning/ROADMAP.md`.
|
||||
|
||||
**File to update:** `.planning/ROADMAP.md`
|
||||
|
||||
The main ROADMAP.md file holds full phase details for the active milestone. Archive files in `milestones/` are created only when a milestone ships (via `/gsd:complete-milestone`).
|
||||
|
||||
**Process:**
|
||||
|
||||
**1. Update Milestones section:**
|
||||
|
||||
Add the new milestone to the milestones list. Completed milestones show as links to their archive files, new milestone shows as in-progress.
|
||||
|
||||
```markdown
|
||||
## Milestones
|
||||
|
||||
- ✅ **v1.0 [Previous]** - [link to milestones/v1.0-ROADMAP.md] (Phases 1-9, shipped YYYY-MM-DD)
|
||||
- 🚧 **v[X.Y] [Name]** - Phases [N]-[M] (in progress)
|
||||
```
|
||||
|
||||
**2. Add full phase details:**
|
||||
|
||||
Write complete phase sections for all phases in this milestone. Each phase gets full details including goal, dependencies, research assessment, and plan placeholders.
|
||||
|
||||
```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 in this milestone ...]
|
||||
```
|
||||
|
||||
**3. Update Progress table:**
|
||||
|
||||
Add rows for all new phases with milestone attribution.
|
||||
|
||||
```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="cleanup_context">
|
||||
Delete the temporary milestone context file if it exists:
|
||||
|
||||
```bash
|
||||
rm -f .planning/MILESTONE-CONTEXT.md
|
||||
```
|
||||
|
||||
This file was a handoff artifact from `/gsd:discuss-milestone`. Now that the milestone is created, the context is persisted in ROADMAP.md and the temporary file is no longer needed.
|
||||
</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
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase [N]: [Name]** — [Goal from ROADMAP.md]
|
||||
|
||||
`/gsd:plan-phase [N]`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:discuss-phase [N]` — gather context first
|
||||
- `/gsd:research-phase [N]` — investigate unknowns
|
||||
- Review roadmap
|
||||
|
||||
---
|
||||
```
|
||||
</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
|
||||
- Respect depth setting for phase count (quick: 3-5, standard: 5-8, comprehensive: 8-12)
|
||||
- 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)
|
||||
- [ ] Phases defined per depth setting (quick: 3-5, standard: 5-8, comprehensive: 8-12)
|
||||
- [ ] 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>
|
||||
```
|
||||
|
|
@ -0,0 +1,481 @@
|
|||
<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">
|
||||
Derive phases from the actual work needed.
|
||||
|
||||
**Check depth setting:**
|
||||
```bash
|
||||
cat .planning/config.json 2>/dev/null | grep depth
|
||||
```
|
||||
|
||||
<depth_guidance>
|
||||
**Depth controls compression tolerance, not artificial inflation.**
|
||||
|
||||
| Depth | Typical Phases | Typical Plans/Phase | Tasks/Plan |
|
||||
|-------|----------------|---------------------|------------|
|
||||
| Quick | 3-5 | 1-3 | 2-3 |
|
||||
| Standard | 5-8 | 3-5 | 2-3 |
|
||||
| Comprehensive | 8-12 | 5-10 | 2-3 |
|
||||
|
||||
**Key principle:** Derive phases from actual work. Depth determines how aggressively you combine things, not a target to hit.
|
||||
|
||||
- Comprehensive auth system = 8 phases (because auth genuinely has 8 concerns)
|
||||
- Comprehensive "add favicon" = 1 phase (because that's all it is)
|
||||
|
||||
For comprehensive depth:
|
||||
- Don't compress multiple features into single phases
|
||||
- Each major capability gets its own phase
|
||||
- Let small things stay small—don't pad to hit a number
|
||||
- If you're tempted to combine two things, make them separate phases instead
|
||||
|
||||
For quick depth:
|
||||
- Combine related work aggressively
|
||||
- Focus on critical path only
|
||||
- Defer nice-to-haves to future milestones
|
||||
</depth_guidance>
|
||||
|
||||
**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
|
||||
|
||||
**Deriving phases:**
|
||||
|
||||
1. List all distinct systems/features/capabilities required
|
||||
2. Group related work into coherent deliverables
|
||||
3. Each phase should deliver ONE complete, verifiable thing
|
||||
4. If a phase delivers multiple unrelated capabilities: split it
|
||||
5. If a phase can't stand alone as a complete deliverable: merge it
|
||||
6. Order by dependencies
|
||||
|
||||
Good phases are:
|
||||
|
||||
- **Coherent**: Each delivers one complete, verifiable capability
|
||||
- **Sequential**: Later phases build on earlier
|
||||
- **Independent**: Can be verified and committed on its own
|
||||
|
||||
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">
|
||||
<config-check>
|
||||
```bash
|
||||
cat .planning/config.json 2>/dev/null
|
||||
```
|
||||
Note: Config may not exist yet (project initialization). If missing, default to interactive mode.
|
||||
</config-check>
|
||||
|
||||
<if mode="yolo">
|
||||
```
|
||||
⚡ 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 step.
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="missing OR custom with gates.confirm_phases true">
|
||||
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">
|
||||
<if mode="yolo">
|
||||
```
|
||||
⚡ Auto-approved: Create roadmap with [N] phases
|
||||
|
||||
Proceeding to create .planning/ROADMAP.md...
|
||||
```
|
||||
|
||||
Proceed directly to create_structure step.
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="missing OR custom with gates.confirm_roadmap true">
|
||||
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
|
||||
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated [today's date])
|
||||
|
||||
**Core value:** [Copy Core Value from PROJECT.md]
|
||||
**Current focus:** Phase 1 — [First phase name]
|
||||
|
||||
## 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%
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
**Velocity:**
|
||||
- Total plans completed: 0
|
||||
- Average duration: —
|
||||
- Total execution time: 0 hours
|
||||
|
||||
**By Phase:**
|
||||
|
||||
| Phase | Plans | Total | Avg/Plan |
|
||||
|-------|-------|-------|----------|
|
||||
| — | — | — | — |
|
||||
|
||||
**Recent Trend:**
|
||||
- Last 5 plans: —
|
||||
- Trend: —
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
### Decisions
|
||||
|
||||
Decisions are logged in PROJECT.md Key Decisions table.
|
||||
Recent decisions affecting current work:
|
||||
|
||||
(None yet)
|
||||
|
||||
### Deferred Issues
|
||||
|
||||
None yet.
|
||||
|
||||
### Blockers/Concerns
|
||||
|
||||
None yet.
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: [today's date and time]
|
||||
Stopped at: Project initialization complete
|
||||
Resume file: None
|
||||
```
|
||||
|
||||
**Key points:**
|
||||
|
||||
- Project Reference points to PROJECT.md for full context
|
||||
- Claude reads PROJECT.md directly for requirements, constraints, decisions
|
||||
- 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)
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase 1: [Name]** — [Goal from ROADMAP.md]
|
||||
|
||||
`/gsd:plan-phase 1`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:discuss-phase 1` — gather context first
|
||||
- `/gsd:research-phase 1` — investigate unknowns
|
||||
- Review roadmap
|
||||
|
||||
---
|
||||
```
|
||||
</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 impose arbitrary phase counts (let the work determine the count)
|
||||
|
||||
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)
|
||||
- [ ] Phases defined with clear names (count derived from work, not imposed)
|
||||
- [ ] **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>
|
||||
```
|
||||
|
|
@ -0,0 +1,293 @@
|
|||
<purpose>
|
||||
Execute discovery at the appropriate depth level.
|
||||
Produces DISCOVERY.md (for Level 2-3) that informs PLAN.md creation.
|
||||
|
||||
Called from plan-phase.md's mandatory_discovery step with a depth parameter.
|
||||
|
||||
NOTE: For comprehensive ecosystem research ("how do experts build this"), use /gsd:research-phase instead, which produces RESEARCH.md.
|
||||
</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 | DISCOVERY.md | Choosing between options, new integration |
|
||||
| 3 | Deep Dive | 1+ hour | Detailed DISCOVERY.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/discovery.md `<discovery_protocol>` 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 Discovery)
|
||||
- `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 DISCOVERY.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 Discovery (15-30 minutes)**
|
||||
|
||||
For: Choosing between options, new external integration.
|
||||
|
||||
**Process:**
|
||||
|
||||
1. **Identify what to discover:**
|
||||
|
||||
- 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 DISCOVERY.md** using ./.claude/get-shit-done/templates/discovery.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/DISCOVERY.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 discovery** using ./.claude/get-shit-done/templates/discovery.md:
|
||||
|
||||
- Define 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 DISCOVERY.md:**
|
||||
|
||||
- Full structure from ./.claude/get-shit-done/templates/discovery.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/DISCOVERY.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_discovery_scope">
|
||||
Use ./.claude/get-shit-done/templates/discovery.md.
|
||||
|
||||
Include:
|
||||
|
||||
- Clear discovery objective
|
||||
- Scoped include/exclude lists
|
||||
- Source preferences (official docs, Context7, current year)
|
||||
- Output structure for DISCOVERY.md
|
||||
</step>
|
||||
|
||||
<step name="execute_discovery">
|
||||
Run the discovery:
|
||||
- Use web search for current info
|
||||
- Use Context7 MCP for library docs
|
||||
- Prefer current year sources
|
||||
- Structure findings per template
|
||||
</step>
|
||||
|
||||
<step name="create_discovery_output">
|
||||
Write `.planning/phases/XX-name/DISCOVERY.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 DISCOVERY.md, check confidence level.
|
||||
|
||||
If confidence is LOW:
|
||||
Use AskUserQuestion:
|
||||
|
||||
- header: "Low Confidence"
|
||||
- question: "Discovery 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: "Discovery complete (medium confidence). [brief reason]. Proceed to planning?"
|
||||
|
||||
If confidence is HIGH:
|
||||
Proceed directly, just note: "Discovery complete (high confidence)."
|
||||
</step>
|
||||
|
||||
<step name="open_questions_gate">
|
||||
If DISCOVERY.md has open_questions:
|
||||
|
||||
Present them inline:
|
||||
"Open questions from discovery:
|
||||
|
||||
- [Question 1]
|
||||
- [Question 2]
|
||||
|
||||
These may affect implementation. Acknowledge and proceed? (yes / address first)"
|
||||
|
||||
If "address first": Gather user input on questions, update discovery.
|
||||
</step>
|
||||
|
||||
<step name="offer_next">
|
||||
```
|
||||
Discovery complete: .planning/phases/XX-name/DISCOVERY.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 discovery (dig deeper)
|
||||
4. Review discovery
|
||||
|
||||
```
|
||||
|
||||
NOTE: DISCOVERY.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
|
||||
- DISCOVERY.md created with recommendation
|
||||
- Confidence level MEDIUM or higher
|
||||
- Ready to inform PLAN.md creation
|
||||
|
||||
**Level 3 (Deep Dive):**
|
||||
- Discovery scope defined
|
||||
- Context7 exhaustively consulted
|
||||
- All WebSearch findings verified against authoritative sources
|
||||
- DISCOVERY.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>
|
||||
|
|
@ -0,0 +1,236 @@
|
|||
<purpose>
|
||||
Help the user figure out what they want to build in the next milestone through collaborative thinking.
|
||||
|
||||
You're a thinking partner helping them crystallize their vision for what's next. Features first — everything else (scope, phases) derives from what they want to build.
|
||||
</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">
|
||||
**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
|
||||
|
||||
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
|
||||
|
||||
**1. Open:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Next"
|
||||
- question: "What do you want to add, improve, or fix in this milestone?"
|
||||
- options: [Deferred issues from STATE.md if any] + ["New features", "Improvements to existing", "Bug fixes", "Let me describe"]
|
||||
|
||||
**2. Explore features:**
|
||||
|
||||
Based on their response, use AskUserQuestion:
|
||||
|
||||
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"]
|
||||
|
||||
**3. Prioritize:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Priority"
|
||||
- question: "Which of these matters most?"
|
||||
- options: [Features they mentioned + "All equally important" + "Let me prioritize"]
|
||||
|
||||
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]
|
||||
```
|
||||
|
||||
**4. Decision gate:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Ready?"
|
||||
- question: "Ready to create the milestone, or explore more?"
|
||||
- options (ALL THREE REQUIRED):
|
||||
- "Create milestone" - Proceed to /gsd:new-milestone
|
||||
- "Ask more questions" - Help me think through this more
|
||||
- "Let me add context" - I have more to share
|
||||
|
||||
If "Ask more questions" → return to step 2 with new probes.
|
||||
If "Let me add context" → receive input → return to step 2.
|
||||
Loop until "Create milestone" selected.
|
||||
</step>
|
||||
|
||||
<step name="write_context">
|
||||
Write milestone context to file for handoff.
|
||||
|
||||
**File:** `.planning/MILESTONE-CONTEXT.md`
|
||||
|
||||
Use template from ./.claude/get-shit-done/templates/milestone-context.md
|
||||
|
||||
Populate with:
|
||||
- Features identified during discussion
|
||||
- Suggested milestone name and theme
|
||||
- Estimated phase count
|
||||
- How features map to phases
|
||||
- Any constraints or scope boundaries mentioned
|
||||
|
||||
```bash
|
||||
# Write the context file
|
||||
cat > .planning/MILESTONE-CONTEXT.md << 'EOF'
|
||||
# Milestone Context
|
||||
|
||||
**Generated:** [today's date]
|
||||
**Status:** Ready for /gsd:new-milestone
|
||||
|
||||
<features>
|
||||
## Features to Build
|
||||
|
||||
- **[Feature 1]**: [description]
|
||||
- **[Feature 2]**: [description]
|
||||
- **[Feature 3]**: [description]
|
||||
|
||||
</features>
|
||||
|
||||
<scope>
|
||||
## Scope
|
||||
|
||||
**Suggested name:** v[X.Y] [Theme Name]
|
||||
**Estimated phases:** [N]
|
||||
**Focus:** [One sentence theme/focus]
|
||||
|
||||
</scope>
|
||||
|
||||
<phase_mapping>
|
||||
## Phase Mapping
|
||||
|
||||
- Phase [N]: [Feature/goal]
|
||||
- Phase [N+1]: [Feature/goal]
|
||||
- Phase [N+2]: [Feature/goal]
|
||||
|
||||
</phase_mapping>
|
||||
|
||||
<constraints>
|
||||
## Constraints
|
||||
|
||||
- [Any constraints mentioned]
|
||||
|
||||
</constraints>
|
||||
|
||||
<notes>
|
||||
## Additional Context
|
||||
|
||||
[Anything else from discussion]
|
||||
|
||||
</notes>
|
||||
|
||||
---
|
||||
|
||||
*This file is temporary. It will be deleted after /gsd:new-milestone creates the milestone.*
|
||||
EOF
|
||||
```
|
||||
</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]
|
||||
|
||||
Context saved to `.planning/MILESTONE-CONTEXT.md`
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Create Milestone v[X.Y]** — [Theme Name]
|
||||
|
||||
`/gsd:new-milestone`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
</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)
|
||||
- **MILESTONE-CONTEXT.md created** with features, scope, and phase mapping
|
||||
- Context handed off to /gsd:new-milestone
|
||||
</success_criteria>
|
||||
|
|
@ -0,0 +1,247 @@
|
|||
<purpose>
|
||||
Gather phase context through collaborative thinking before planning. Help the user articulate their vision for how this phase should work, look, and feel.
|
||||
|
||||
You are a thinking partner, not an interviewer. The user is the visionary — you are the builder. Your job is to understand their vision, not interrogate them about technical details you can figure out yourself.
|
||||
</purpose>
|
||||
|
||||
<philosophy>
|
||||
**User = founder/visionary. Claude = builder.**
|
||||
|
||||
The user doesn't know (and shouldn't need to know):
|
||||
- Codebase patterns (you read the code)
|
||||
- Technical risks (you identify during research)
|
||||
- Implementation constraints (you figure those out)
|
||||
- Success metrics (you infer from the work)
|
||||
|
||||
The user DOES know:
|
||||
- How they imagine it working
|
||||
- What it should look/feel like
|
||||
- What's essential vs nice-to-have
|
||||
- Any specific things they have in mind
|
||||
|
||||
Ask about vision. Figure out implementation yourself.
|
||||
</philosophy>
|
||||
|
||||
<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:progress 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
|
||||
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, continue to questioning
|
||||
If "View existing": Read and display CONTEXT.md, then offer update/skip
|
||||
If "Skip": Exit workflow
|
||||
|
||||
**If doesn't exist:**
|
||||
Continue to questioning.
|
||||
</step>
|
||||
|
||||
<step name="questioning">
|
||||
**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
|
||||
|
||||
Present initial context from roadmap, then immediately use AskUserQuestion:
|
||||
|
||||
```
|
||||
Phase ${PHASE}: ${PHASE_NAME}
|
||||
|
||||
From the roadmap: ${PHASE_DESCRIPTION}
|
||||
```
|
||||
|
||||
**1. Open:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Vision"
|
||||
- question: "How do you imagine this working?"
|
||||
- options: 2-3 interpretations based on the phase description + "Let me describe it"
|
||||
|
||||
**2. Follow the thread:**
|
||||
|
||||
Based on their response, use AskUserQuestion:
|
||||
- header: "[Topic they mentioned]"
|
||||
- question: "You mentioned [X] — what would that look like?"
|
||||
- options: 2-3 interpretations + "Something else"
|
||||
|
||||
**3. Sharpen the core:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Essential"
|
||||
- question: "What's the most important part of this phase?"
|
||||
- options: Key aspects they've mentioned + "All equally important" + "Something else"
|
||||
|
||||
**4. Find boundaries:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Scope"
|
||||
- question: "What's explicitly out of scope for this phase?"
|
||||
- options: Things that might be tempting + "Nothing specific" + "Let me list them"
|
||||
|
||||
**5. Capture specifics (optional):**
|
||||
|
||||
If they seem to have specific ideas, use AskUserQuestion:
|
||||
- header: "Specifics"
|
||||
- question: "Any particular look/feel/behavior in mind?"
|
||||
- options: Contextual options based on what they've said + "No specifics" + "Let me describe"
|
||||
|
||||
CRITICAL — What NOT to ask:
|
||||
- Technical risks (you figure those out)
|
||||
- Codebase patterns (you read the code)
|
||||
- Success metrics (too corporate)
|
||||
- Constraints they didn't mention (don't interrogate)
|
||||
|
||||
**6. Decision gate:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Ready?"
|
||||
- question: "Ready to capture this context, or explore more?"
|
||||
- options (ALL THREE REQUIRED):
|
||||
- "Create CONTEXT.md" - I've shared my vision
|
||||
- "Ask more questions" - Help me think through this more
|
||||
- "Let me add context" - I have more to share
|
||||
|
||||
If "Ask more questions" → return to step 2 with new probes.
|
||||
If "Let me add context" → receive input → return to step 2.
|
||||
Loop until "Create CONTEXT.md" selected.
|
||||
</step>
|
||||
|
||||
<step name="write_context">
|
||||
Create CONTEXT.md capturing the user's vision.
|
||||
|
||||
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 with VISION context (not technical analysis):
|
||||
|
||||
- `<vision>`: How the user imagines this working
|
||||
- `<essential>`: What must be nailed in this phase
|
||||
- `<boundaries>`: What's explicitly out of scope
|
||||
- `<specifics>`: Any particular look/feel/behavior mentioned
|
||||
- `<notes>`: Any other context gathered
|
||||
|
||||
Do NOT populate with your own technical analysis. That comes during research/planning.
|
||||
|
||||
Write file.
|
||||
</step>
|
||||
|
||||
<step name="confirm_creation">
|
||||
Present CONTEXT.md summary:
|
||||
|
||||
```
|
||||
Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
|
||||
|
||||
## Vision
|
||||
[How they imagine it working]
|
||||
|
||||
## Essential
|
||||
[What must be nailed]
|
||||
|
||||
## Boundaries
|
||||
[What's out of scope]
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase ${PHASE}: [Name]** — [Goal from ROADMAP.md]
|
||||
|
||||
`/gsd:plan-phase ${PHASE}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:research-phase ${PHASE}` — investigate unknowns
|
||||
- Review/edit CONTEXT.md before continuing
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="git_commit">
|
||||
Commit phase context:
|
||||
|
||||
```bash
|
||||
git add .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
|
||||
git commit -m "$(cat <<'EOF'
|
||||
docs(${PHASE}): capture phase context
|
||||
|
||||
Phase ${PHASE}: ${PHASE_NAME}
|
||||
- Vision and goals documented
|
||||
- Essential requirements identified
|
||||
- Scope boundaries defined
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
Confirm: "Committed: docs(${PHASE}): capture phase context"
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- Phase validated against roadmap
|
||||
- Vision gathered through collaborative thinking (not interrogation)
|
||||
- User's imagination captured: how it works, what's essential, what's out of scope
|
||||
- CONTEXT.md created in phase directory
|
||||
- CONTEXT.md committed to git
|
||||
- User knows next steps (typically: research or plan the phase)
|
||||
</success_criteria>
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -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>
|
||||
|
|
@ -0,0 +1,434 @@
|
|||
<purpose>
|
||||
Orchestrate parallel Explore agents to analyze codebase and produce structured documents in .planning/codebase/
|
||||
|
||||
Each agent has fresh context and focuses on specific aspects. Output is concise and actionable for planning.
|
||||
</purpose>
|
||||
|
||||
<philosophy>
|
||||
**Why parallel agents:**
|
||||
- Fresh context per domain (no token contamination)
|
||||
- Thorough analysis without context exhaustion
|
||||
- Each agent optimized for its domain (tech vs organization vs quality vs issues)
|
||||
- Faster execution (agents run simultaneously)
|
||||
|
||||
**Document quality over length:**
|
||||
Include enough detail to be useful as reference. Prioritize practical examples (especially code patterns) over arbitrary brevity. A 200-line TESTING.md with real patterns is more valuable than a 74-line summary.
|
||||
|
||||
**Always include file paths:**
|
||||
Documents are reference material for Claude when planning/executing. Vague descriptions like "UserService handles users" are not actionable. Always include actual file paths formatted with backticks: `src/services/user.ts`. This allows Claude to navigate directly to relevant code without re-searching. Do NOT include line numbers (they go stale), just file paths.
|
||||
</philosophy>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="check_existing" priority="first">
|
||||
Check if .planning/codebase/ already exists:
|
||||
|
||||
```bash
|
||||
ls -la .planning/codebase/ 2>/dev/null
|
||||
```
|
||||
|
||||
**If exists:**
|
||||
|
||||
```
|
||||
.planning/codebase/ already exists with these documents:
|
||||
[List files found]
|
||||
|
||||
What's next?
|
||||
1. Refresh - Delete existing and remap codebase
|
||||
2. Update - Keep existing, only update specific documents
|
||||
3. Skip - Use existing codebase map as-is
|
||||
```
|
||||
|
||||
Wait for user response.
|
||||
|
||||
If "Refresh": Delete .planning/codebase/, continue to create_structure
|
||||
If "Update": Ask which documents to update, continue to spawn_agents (filtered)
|
||||
If "Skip": Exit workflow
|
||||
|
||||
**If doesn't exist:**
|
||||
Continue to create_structure.
|
||||
</step>
|
||||
|
||||
<step name="create_structure">
|
||||
Create .planning/codebase/ directory:
|
||||
|
||||
```bash
|
||||
mkdir -p .planning/codebase
|
||||
```
|
||||
|
||||
**Expected output files:**
|
||||
- STACK.md (from stack.md template)
|
||||
- ARCHITECTURE.md (from architecture.md template)
|
||||
- STRUCTURE.md (from structure.md template)
|
||||
- CONVENTIONS.md (from conventions.md template)
|
||||
- TESTING.md (from testing.md template)
|
||||
- INTEGRATIONS.md (from integrations.md template)
|
||||
- CONCERNS.md (from concerns.md template)
|
||||
|
||||
Continue to spawn_agents.
|
||||
</step>
|
||||
|
||||
<step name="spawn_agents">
|
||||
Spawn 4 parallel Explore agents to analyze codebase.
|
||||
|
||||
Use Task tool with `subagent_type="Explore"` and `run_in_background=true` for parallel execution.
|
||||
|
||||
**Agent 1: Stack + Integrations (Technology Focus)**
|
||||
|
||||
Task tool parameters:
|
||||
```
|
||||
subagent_type: "Explore"
|
||||
run_in_background: true
|
||||
task_description: "Analyze codebase technology stack and external integrations"
|
||||
```
|
||||
|
||||
Prompt:
|
||||
```
|
||||
Analyze this codebase for technology stack and external integrations.
|
||||
|
||||
IMPORTANT: Always include actual file paths in your findings. Use backtick formatting like `src/config/database.ts`. This makes the output actionable for planning.
|
||||
|
||||
Focus areas:
|
||||
1. Languages (check file extensions, package manifests)
|
||||
2. Runtime environment (Node.js, Python, etc. - check .nvmrc, .python-version, engines field)
|
||||
3. Package manager and lockfiles
|
||||
4. Frameworks (web, testing, build tools)
|
||||
5. Key dependencies (critical packages for functionality)
|
||||
6. External services (APIs, databases, auth providers)
|
||||
7. Third-party integrations (payment, analytics, etc.)
|
||||
8. Configuration approach (.env, config files)
|
||||
|
||||
Search for:
|
||||
- package.json / requirements.txt / Cargo.toml / go.mod
|
||||
- .env files, .env.example
|
||||
- Config files (vite.config, webpack.config, tsconfig.json)
|
||||
- API client code, database connection code
|
||||
- Import statements for major libraries
|
||||
|
||||
Output findings for populating these sections:
|
||||
- STACK.md: Languages, Runtime, Frameworks, Dependencies, Configuration
|
||||
- INTEGRATIONS.md: External APIs, Services, Third-party tools
|
||||
|
||||
For each finding, include the file path where you found it. Example:
|
||||
- "TypeScript 5.3 - `package.json`"
|
||||
- "Supabase client - `src/lib/supabase.ts`"
|
||||
- "Stripe integration - `src/services/stripe.ts`, `src/webhooks/stripe.ts`"
|
||||
|
||||
If something is not found, note "Not detected" for that category.
|
||||
```
|
||||
|
||||
**Agent 2: Architecture + Structure (Organization Focus)**
|
||||
|
||||
Task tool parameters:
|
||||
```
|
||||
subagent_type: "Explore"
|
||||
run_in_background: true
|
||||
task_description: "Analyze codebase architecture patterns and directory structure"
|
||||
```
|
||||
|
||||
Prompt:
|
||||
```
|
||||
Analyze this codebase architecture and directory structure.
|
||||
|
||||
IMPORTANT: Always include actual file paths in your findings. Use backtick formatting like `src/index.ts`. This makes the output actionable for planning.
|
||||
|
||||
Focus areas:
|
||||
1. Overall architectural pattern (monolith, microservices, layered, etc.)
|
||||
2. Conceptual layers (API, service, data, utility)
|
||||
3. Data flow and request lifecycle
|
||||
4. Key abstractions and patterns (services, controllers, repositories)
|
||||
5. Entry points (main files, server files, CLI entry)
|
||||
6. Directory organization and purposes
|
||||
7. Module boundaries
|
||||
8. Naming conventions for directories and files
|
||||
|
||||
Search for:
|
||||
- Entry points: index.ts, main.ts, server.ts, app.ts, cli.ts
|
||||
- Directory structure patterns (src/, lib/, components/, services/)
|
||||
- Import patterns (what imports what)
|
||||
- Recurring code patterns (base classes, interfaces, common abstractions)
|
||||
|
||||
Output findings for populating these sections:
|
||||
- ARCHITECTURE.md: Pattern, Layers, Data Flow, Abstractions, Entry Points
|
||||
- STRUCTURE.md: Directory layout, Organization, Key locations
|
||||
|
||||
For each finding, include the file path. Examples:
|
||||
- "CLI entry point: `bin/install.js`"
|
||||
- "Service layer: `src/services/*.ts` (UserService, ProjectService)"
|
||||
- "API routes: `src/routes/api/*.ts`"
|
||||
|
||||
If something is not clear, provide best-guess interpretation based on code structure.
|
||||
```
|
||||
|
||||
**Agent 3: Conventions + Testing (Quality Focus)**
|
||||
|
||||
Task tool parameters:
|
||||
```
|
||||
subagent_type: "Explore"
|
||||
run_in_background: true
|
||||
task_description: "Analyze coding conventions and test patterns"
|
||||
```
|
||||
|
||||
Prompt:
|
||||
```
|
||||
Analyze this codebase for coding conventions and testing practices.
|
||||
|
||||
IMPORTANT: Always include actual file paths in your findings. Use backtick formatting like `vitest.config.ts`. This makes the output actionable for planning.
|
||||
|
||||
Focus areas:
|
||||
1. Code style (indentation, quotes, semicolons, formatting)
|
||||
2. File naming conventions (kebab-case, PascalCase, etc.)
|
||||
3. Function/variable naming patterns
|
||||
4. Comment and documentation style
|
||||
5. Test framework and structure
|
||||
6. Test organization (unit, integration, e2e)
|
||||
7. Test coverage approach
|
||||
8. Linting and formatting tools
|
||||
|
||||
Search for:
|
||||
- Config files: .eslintrc, .prettierrc, tsconfig.json
|
||||
- Test files: *.test.*, *.spec.*, __tests__/
|
||||
- Test setup: vitest.config, jest.config
|
||||
- Code patterns across multiple files
|
||||
- README or CONTRIBUTING docs
|
||||
|
||||
Output findings for populating these sections:
|
||||
- CONVENTIONS.md: Code Style, Naming, Patterns, Documentation
|
||||
- TESTING.md: Framework, Structure, Coverage, Tools
|
||||
|
||||
For each finding, include file paths. Examples:
|
||||
- "Prettier config: `.prettierrc`"
|
||||
- "Test pattern: `src/**/*.test.ts` (co-located with source)"
|
||||
- "Example of naming convention: `src/services/user-service.ts`"
|
||||
|
||||
Look at actual code files to infer conventions if config files are missing.
|
||||
```
|
||||
|
||||
**Agent 4: Concerns (Issues Focus)**
|
||||
|
||||
Task tool parameters:
|
||||
```
|
||||
subagent_type: "Explore"
|
||||
run_in_background: true
|
||||
task_description: "Identify technical debt and areas of concern"
|
||||
```
|
||||
|
||||
Prompt:
|
||||
```
|
||||
Analyze this codebase for technical debt, known issues, and areas of concern.
|
||||
|
||||
CRITICAL: Always include actual file paths in your findings. Use backtick formatting like `src/auth/login.ts`. Concerns without file paths are not actionable. For each issue found, specify exactly where it is.
|
||||
|
||||
Focus areas:
|
||||
1. TODO and FIXME comments
|
||||
2. Complex or hard-to-understand code
|
||||
3. Missing error handling (try/catch, error checks)
|
||||
4. Security patterns (hardcoded secrets, unsafe operations)
|
||||
5. Outdated dependencies (check versions against current)
|
||||
6. Missing tests for critical code
|
||||
7. Duplicate code patterns
|
||||
8. Performance concerns (N+1 queries, inefficient loops)
|
||||
9. Documentation gaps (complex code without comments)
|
||||
|
||||
Search for:
|
||||
- TODO, FIXME, HACK, XXX comments
|
||||
- Large functions or files (>200 lines)
|
||||
- Repeated code patterns
|
||||
- Missing .env.example when .env is used
|
||||
- Dependencies with known vulnerabilities (check versions)
|
||||
- Error-prone patterns (no validation, no error handling)
|
||||
|
||||
Output findings for populating:
|
||||
- CONCERNS.md: Technical Debt, Issues, Security, Performance, Documentation
|
||||
|
||||
For EVERY concern, include file paths. Examples:
|
||||
- "Direct DB queries in components: `src/pages/Dashboard.tsx`, `src/pages/Profile.tsx`"
|
||||
- "Missing error handling: `src/api/webhook.ts` (Stripe webhook has no try/catch)"
|
||||
- "TODO: 'fix race condition' in `src/services/subscription.ts`"
|
||||
|
||||
Be constructive - focus on actionable concerns, not nitpicks.
|
||||
If codebase is clean, note that rather than inventing problems.
|
||||
```
|
||||
|
||||
Continue to collect_results.
|
||||
</step>
|
||||
|
||||
<step name="collect_results">
|
||||
Wait for all 4 agents to complete.
|
||||
|
||||
Use TaskOutput tool to collect results from each agent. Since agents were run with `run_in_background=true`, retrieve their output.
|
||||
|
||||
**Collection pattern:**
|
||||
|
||||
For each agent, use TaskOutput tool to get the full exploration findings.
|
||||
|
||||
**Aggregate findings by document:**
|
||||
|
||||
From Agent 1 output, extract:
|
||||
- STACK.md sections: Languages, Runtime, Frameworks, Dependencies, Configuration, Platform
|
||||
- INTEGRATIONS.md sections: External APIs, Services, Authentication, Webhooks
|
||||
|
||||
From Agent 2 output, extract:
|
||||
- ARCHITECTURE.md sections: Pattern Overview, Layers, Data Flow, Key Abstractions, Entry Points
|
||||
- STRUCTURE.md sections: Directory Layout, Key Locations, Organization
|
||||
|
||||
From Agent 3 output, extract:
|
||||
- CONVENTIONS.md sections: Code Style, Naming Conventions, Common Patterns, Documentation Style
|
||||
- TESTING.md sections: Framework, Structure, Coverage, Tools
|
||||
|
||||
From Agent 4 output, extract:
|
||||
- CONCERNS.md sections: Technical Debt, Known Issues, Security, Performance, Missing
|
||||
|
||||
**Handling missing findings:**
|
||||
|
||||
If an agent didn't find information for a section, use placeholder:
|
||||
- "Not detected" (for infrastructure/tools that may not exist)
|
||||
- "Not applicable" (for patterns that don't apply to this codebase)
|
||||
- "No significant concerns" (for CONCERNS.md if codebase is clean)
|
||||
|
||||
Continue to write_documents.
|
||||
</step>
|
||||
|
||||
<step name="write_documents">
|
||||
Write all 7 codebase documents using templates and agent findings.
|
||||
|
||||
**Template filling process:**
|
||||
|
||||
For each document:
|
||||
|
||||
1. **Read template file** from `./.claude/get-shit-done/templates/codebase/{name}.md`
|
||||
2. **Extract the "File Template" section** - this is the markdown code block containing the actual document structure
|
||||
3. **Fill template placeholders** with agent findings:
|
||||
- Replace `[YYYY-MM-DD]` with current date
|
||||
- Replace `[Placeholder text]` with specific findings from agents
|
||||
- If agent found nothing for a section, use appropriate placeholder:
|
||||
- "Not detected" for optional infrastructure
|
||||
- "Not applicable" for patterns that don't fit this codebase
|
||||
- "No significant concerns" for clean codebase areas
|
||||
4. **Write to .planning/codebase/{NAME}.md** (uppercase filename)
|
||||
|
||||
**Example filling pattern:**
|
||||
|
||||
Template placeholder:
|
||||
```
|
||||
**Primary:**
|
||||
- [Language] [Version] - [Where used: e.g., "all application code"]
|
||||
```
|
||||
|
||||
Agent finding:
|
||||
```
|
||||
Found: TypeScript 5.3 used in all .ts files throughout src/
|
||||
```
|
||||
|
||||
Filled result:
|
||||
```
|
||||
**Primary:**
|
||||
- TypeScript 5.3 - All application code
|
||||
```
|
||||
|
||||
**Document writing order:**
|
||||
|
||||
1. **STACK.md** (from stack.md template + Agent 1 findings)
|
||||
2. **INTEGRATIONS.md** (from integrations.md template + Agent 1 findings)
|
||||
3. **ARCHITECTURE.md** (from architecture.md template + Agent 2 findings)
|
||||
4. **STRUCTURE.md** (from structure.md template + Agent 2 findings)
|
||||
5. **CONVENTIONS.md** (from conventions.md template + Agent 3 findings)
|
||||
6. **TESTING.md** (from testing.md template + Agent 3 findings)
|
||||
7. **CONCERNS.md** (from concerns.md template + Agent 4 findings)
|
||||
|
||||
After all documents written, continue to verify_output.
|
||||
</step>
|
||||
|
||||
<step name="verify_output">
|
||||
Verify all documents created successfully:
|
||||
|
||||
```bash
|
||||
ls -la .planning/codebase/
|
||||
wc -l .planning/codebase/*.md
|
||||
```
|
||||
|
||||
**Verification checklist:**
|
||||
- All 7 documents exist
|
||||
- No empty documents
|
||||
- Templates populated with findings
|
||||
|
||||
If any checks fail, report issues to user.
|
||||
|
||||
Continue to commit_codebase_map.
|
||||
</step>
|
||||
|
||||
<step name="commit_codebase_map">
|
||||
Commit the codebase map:
|
||||
|
||||
```bash
|
||||
git add .planning/codebase/*.md
|
||||
git commit -m "$(cat <<'EOF'
|
||||
docs: map existing codebase
|
||||
|
||||
- STACK.md - Technologies and dependencies
|
||||
- ARCHITECTURE.md - System design and patterns
|
||||
- STRUCTURE.md - Directory layout
|
||||
- CONVENTIONS.md - Code style and patterns
|
||||
- TESTING.md - Test structure
|
||||
- INTEGRATIONS.md - External services
|
||||
- CONCERNS.md - Technical debt and issues
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
Continue to offer_next.
|
||||
</step>
|
||||
|
||||
<step name="offer_next">
|
||||
Present completion summary and next steps.
|
||||
|
||||
**Output format:**
|
||||
|
||||
```
|
||||
Codebase mapping complete.
|
||||
|
||||
Created .planning/codebase/:
|
||||
- STACK.md ([N] lines) - Technologies and dependencies
|
||||
- ARCHITECTURE.md ([N] lines) - System design and patterns
|
||||
- STRUCTURE.md ([N] lines) - Directory layout and organization
|
||||
- CONVENTIONS.md ([N] lines) - Code style and patterns
|
||||
- TESTING.md ([N] lines) - Test structure and practices
|
||||
- INTEGRATIONS.md ([N] lines) - External services and APIs
|
||||
- CONCERNS.md ([N] lines) - Technical debt and issues
|
||||
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Initialize project** — use codebase context for planning
|
||||
|
||||
`/gsd:new-project`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- Re-run mapping: `/gsd:map-codebase`
|
||||
- Review specific file: `cat .planning/codebase/STACK.md`
|
||||
- Edit any document before proceeding
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
End workflow.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- .planning/codebase/ directory created
|
||||
- 4 parallel Explore agents spawned with run_in_background=true
|
||||
- Agent prompts are specific and actionable
|
||||
- TaskOutput used to collect all agent results
|
||||
- All 7 codebase documents written using template filling
|
||||
- Documents follow template structure with actual findings
|
||||
- Clear completion summary with line counts
|
||||
- User offered clear next steps in GSD style
|
||||
</success_criteria>
|
||||
|
|
@ -0,0 +1,488 @@
|
|||
<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 between consecutive integers (2.1 between 2 and 3)
|
||||
- Filesystem sorting works automatically (2 < 2.1 < 2.2 < 3)
|
||||
- Directory format: `02.1-description/`, Plan format: `02.1-01-PLAN.md`
|
||||
|
||||
**Validation:** Integer X must exist and be complete, X+1 must exist, decimal X.Y must not exist, Y >= 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. ./.claude/get-shit-done/references/tdd.md
|
||||
6. .planning/ROADMAP.md
|
||||
7. .planning/PROJECT.md
|
||||
|
||||
**Load domain expertise from ROADMAP:**
|
||||
- Parse ROADMAP.md's `## Domain Expertise` section for paths
|
||||
- Read each domain SKILL.md (these serve as indexes)
|
||||
- Determine phase type and load ONLY references relevant to THIS phase type from each SKILL.md's `<references_index>`
|
||||
</required_reading>
|
||||
|
||||
<purpose>
|
||||
Create an executable phase prompt (PLAN.md). PLAN.md IS the prompt that Claude executes - not a document that gets transformed.
|
||||
</purpose>
|
||||
|
||||
<planning_principles>
|
||||
**Secure by design:** Assume hostile input on every boundary. Validate, parameterize, authenticate, fail closed.
|
||||
|
||||
**Performance by design:** Assume production load, not demo conditions. Plan for efficient data access, appropriate caching, minimal round trips.
|
||||
|
||||
**Observable by design:** Plan to debug your own work. Include meaningful error messages, appropriate logging, and clear failure states.
|
||||
</planning_principles>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="load_project_state" priority="first">
|
||||
Read `.planning/STATE.md` and parse:
|
||||
- Current position (which phase we're planning)
|
||||
- Accumulated decisions (constraints on this phase)
|
||||
- Deferred issues (candidates for inclusion)
|
||||
- Blockers/concerns (things this phase may address)
|
||||
- Brief alignment status
|
||||
|
||||
If STATE.md missing but .planning/ exists, offer to reconstruct or continue without.
|
||||
</step>
|
||||
|
||||
<step name="load_codebase_context">
|
||||
Check for codebase map:
|
||||
|
||||
```bash
|
||||
ls .planning/codebase/*.md 2>/dev/null
|
||||
```
|
||||
|
||||
**If .planning/codebase/ exists:** Load relevant documents based on phase type:
|
||||
|
||||
| Phase Keywords | Load These |
|
||||
|----------------|------------|
|
||||
| UI, frontend, components | CONVENTIONS.md, STRUCTURE.md |
|
||||
| API, backend, endpoints | ARCHITECTURE.md, CONVENTIONS.md |
|
||||
| database, schema, models | ARCHITECTURE.md, STACK.md |
|
||||
| testing, tests | TESTING.md, CONVENTIONS.md |
|
||||
| integration, external API | INTEGRATIONS.md, STACK.md |
|
||||
| refactor, cleanup | CONCERNS.md, ARCHITECTURE.md |
|
||||
| setup, config | STACK.md, STRUCTURE.md |
|
||||
| (default) | STACK.md, ARCHITECTURE.md |
|
||||
|
||||
Track extracted constraints for PLAN.md context section.
|
||||
</step>
|
||||
|
||||
<step name="identify_phase">
|
||||
Check roadmap and existing 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:** Regex `^(\d+)(?:\.(\d+))?$` - Group 1: integer, Group 2: decimal (optional)
|
||||
|
||||
**If decimal phase:** Validate integer X exists and is complete, X+1 exists in roadmap, decimal X.Y doesn't exist, Y >= 1.
|
||||
|
||||
Read any existing PLAN.md or DISCOVERY.md in the phase directory.
|
||||
</step>
|
||||
|
||||
<step name="mandatory_discovery">
|
||||
**Discovery is MANDATORY unless you can prove current context exists.**
|
||||
|
||||
<discovery_decision>
|
||||
**Level 0 - Skip** (pure internal work, existing patterns only)
|
||||
- ALL work follows established codebase patterns (grep confirms)
|
||||
- No new external dependencies
|
||||
- Pure internal refactoring or feature extension
|
||||
- Examples: Add delete button, add field to model, create CRUD endpoint
|
||||
|
||||
**Level 1 - Quick Verification** (2-5 min)
|
||||
- Single known library, confirming syntax/version
|
||||
- Low-risk decision (easily changed later)
|
||||
- Action: Context7 resolve-library-id + query-docs, no DISCOVERY.md needed
|
||||
|
||||
**Level 2 - Standard Research** (15-30 min)
|
||||
- Choosing between 2-3 options
|
||||
- New external integration (API, service)
|
||||
- Medium-risk decision
|
||||
- Action: Route to workflows/discovery-phase.md depth=standard, produces DISCOVERY.md
|
||||
|
||||
**Level 3 - Deep Dive** (1+ hour)
|
||||
- Architectural decision with long-term impact
|
||||
- Novel problem without clear patterns
|
||||
- High-risk, hard to change later
|
||||
- Action: Route to workflows/discovery-phase.md depth=deep, full DISCOVERY.md
|
||||
|
||||
**Depth indicators:**
|
||||
- Level 2+: New library not in package.json, external API, "choose/select/evaluate" in description, roadmap marked Research: Yes
|
||||
- Level 3: "architecture/design/system", multiple external services, data modeling, auth design, real-time/distributed
|
||||
</discovery_decision>
|
||||
|
||||
If roadmap flagged `Research: Likely`, Level 0 (skip) is not available.
|
||||
|
||||
For niche domains (3D, games, audio, shaders, ML), suggest `/gsd:research-phase` before plan-phase.
|
||||
</step>
|
||||
|
||||
<step name="read_project_history">
|
||||
**Intelligent context assembly from frontmatter dependency graph:**
|
||||
|
||||
**1. Scan all summary frontmatter (cheap - first ~25 lines):**
|
||||
|
||||
```bash
|
||||
for f in .planning/phases/*/*-SUMMARY.md; do
|
||||
# Extract frontmatter only (between first two --- markers)
|
||||
sed -n '1,/^---$/p; /^---$/q' "$f" | head -30
|
||||
done
|
||||
```
|
||||
|
||||
Parse YAML to extract: phase, subsystem, requires, provides, affects, tags, key-decisions, key-files
|
||||
|
||||
**2. Build dependency graph for current phase:**
|
||||
|
||||
- **Check affects field:** Which prior phases have current phase in their `affects` list? → Direct dependencies
|
||||
- **Check subsystem:** Which prior phases share same subsystem? → Related work
|
||||
- **Check requires chains:** If phase X requires phase Y, and we need X, we also need Y → Transitive dependencies
|
||||
- **Check roadmap:** Any phases marked as dependencies in ROADMAP.md phase description?
|
||||
|
||||
**3. Select relevant summaries:**
|
||||
|
||||
Auto-select phases that match ANY of:
|
||||
- Current phase name/number appears in prior phase's `affects` field
|
||||
- Same `subsystem` value
|
||||
- In `requires` chain (transitive closure)
|
||||
- Explicitly mentioned in STATE.md decisions as affecting current phase
|
||||
|
||||
Typical selection: 2-4 prior phases (immediately prior + related subsystem work)
|
||||
|
||||
**4. Extract context from frontmatter (WITHOUT opening full summaries yet):**
|
||||
|
||||
From selected phases' frontmatter, extract:
|
||||
- **Tech available:** Union of all tech-stack.added lists
|
||||
- **Patterns established:** Union of all tech-stack.patterns and patterns-established
|
||||
- **Key files:** Union of all key-files (for @context references)
|
||||
- **Decisions:** Extract key-decisions from frontmatter
|
||||
|
||||
**5. Now read FULL summaries for selected phases:**
|
||||
|
||||
Only now open and read complete SUMMARY.md files for the selected relevant phases. Extract:
|
||||
- Detailed "Accomplishments" section
|
||||
- "Next Phase Readiness" warnings/blockers
|
||||
- "Issues Encountered" that might affect current phase
|
||||
- "Deviations from Plan" for patterns
|
||||
|
||||
**From STATE.md:** Decisions → constrain approach. Deferred issues → candidates. Blockers → may need to address.
|
||||
|
||||
**From ISSUES.md:**
|
||||
|
||||
```bash
|
||||
cat .planning/ISSUES.md 2>/dev/null
|
||||
```
|
||||
|
||||
Assess each open issue - relevant to this phase? Waiting long enough? Natural to address now? Blocking something?
|
||||
|
||||
**Answer before proceeding:**
|
||||
- Q1: What decisions from previous phases constrain this phase?
|
||||
- Q2: Are there deferred issues that should become tasks?
|
||||
- Q3: Are there concerns from "Next Phase Readiness" that apply?
|
||||
- Q4: Given all context, does the roadmap's description still make sense?
|
||||
|
||||
**Track for PLAN.md context section:**
|
||||
- Which summaries were selected (for @context references)
|
||||
- Tech stack available (from frontmatter)
|
||||
- Established patterns (from frontmatter)
|
||||
- Key files to reference (from frontmatter)
|
||||
- Applicable decisions (from frontmatter + full summary)
|
||||
- Issues being addressed (from ISSUES.md)
|
||||
- Concerns being verified (from "Next Phase Readiness")
|
||||
</step>
|
||||
|
||||
<step name="gather_phase_context">
|
||||
Understand:
|
||||
- Phase goal (from roadmap)
|
||||
- What exists already (scan codebase if mid-project)
|
||||
- Dependencies met (previous phases complete?)
|
||||
- Any {phase}-RESEARCH.md (from /gsd:research-phase)
|
||||
- Any DISCOVERY.md (from mandatory discovery)
|
||||
- Any {phase}-CONTEXT.md (from /gsd:discuss-phase)
|
||||
|
||||
```bash
|
||||
# If mid-project, understand current state
|
||||
ls -la src/ 2>/dev/null
|
||||
cat package.json 2>/dev/null | head -20
|
||||
|
||||
# Check for ecosystem research (from /gsd:research-phase)
|
||||
cat .planning/phases/XX-name/${PHASE}-RESEARCH.md 2>/dev/null
|
||||
|
||||
# Check for phase context (from /gsd:discuss-phase)
|
||||
cat .planning/phases/XX-name/${PHASE}-CONTEXT.md 2>/dev/null
|
||||
```
|
||||
|
||||
**If RESEARCH.md exists:** Use standard_stack (these libraries), architecture_patterns (follow in task structure), dont_hand_roll (NEVER custom solutions for listed problems), common_pitfalls (inform verification), code_examples (reference in actions).
|
||||
|
||||
**If CONTEXT.md exists:** Honor vision, prioritize essential, respect boundaries, incorporate specifics.
|
||||
|
||||
**If neither exist:** Suggest /gsd:research-phase for niche domains, /gsd:discuss-phase for simpler domains, or proceed with roadmap only.
|
||||
</step>
|
||||
|
||||
<step name="break_into_tasks">
|
||||
Decompose phase into tasks and identify TDD candidates.
|
||||
|
||||
**Standard tasks need:**
|
||||
- **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
|
||||
|
||||
**TDD detection:** For each potential task, evaluate TDD fit:
|
||||
|
||||
TDD candidates (create dedicated TDD plans):
|
||||
- Business logic with defined inputs/outputs
|
||||
- API endpoints with request/response contracts
|
||||
- Data transformations, parsing, formatting
|
||||
- Validation rules and constraints
|
||||
- Algorithms with testable behavior
|
||||
- State machines and workflows
|
||||
|
||||
Standard tasks (remain in standard plans):
|
||||
- UI layout, styling, visual components
|
||||
- Configuration changes
|
||||
- Glue code connecting existing components
|
||||
- One-off scripts and migrations
|
||||
- Simple CRUD with no business logic
|
||||
|
||||
**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
|
||||
→ Yes: Create a dedicated TDD plan for this feature (one feature per TDD plan)
|
||||
→ No: Standard task in standard plan
|
||||
|
||||
**Why TDD gets its own plan:** TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. Embedded in a multi-task plan, TDD work consumes 50-60% of context alone, degrading quality for remaining tasks.
|
||||
|
||||
**Test framework:** If project has no test setup and TDD plans are needed, the first TDD plan's RED phase handles framework setup as part of writing the first test.
|
||||
|
||||
See `./.claude/get-shit-done/references/tdd.md` for TDD plan structure.
|
||||
|
||||
**Checkpoints:** Visual/functional verification → checkpoint:human-verify. Implementation choices → checkpoint:decision. Manual action (email, 2FA) → checkpoint:human-action (rare).
|
||||
|
||||
**Critical:** If external resource has CLI/API (Vercel, Stripe, etc.), use type="auto" to automate. Only checkpoint for verification AFTER automation.
|
||||
|
||||
See ./.claude/get-shit-done/references/checkpoints.md for checkpoint structure.
|
||||
</step>
|
||||
|
||||
<step name="estimate_scope">
|
||||
After tasks, assess against quality degradation curve.
|
||||
|
||||
**Check depth setting:**
|
||||
```bash
|
||||
cat .planning/config.json 2>/dev/null | grep depth
|
||||
```
|
||||
|
||||
<depth_aware_splitting>
|
||||
**Depth controls compression tolerance, not artificial inflation.**
|
||||
|
||||
| Depth | Typical Plans/Phase | Tasks/Plan |
|
||||
|-------|---------------------|------------|
|
||||
| Quick | 1-3 | 2-3 |
|
||||
| Standard | 3-5 | 2-3 |
|
||||
| Comprehensive | 5-10 | 2-3 |
|
||||
|
||||
**Key principle:** Derive plans from actual work. Depth determines how aggressively you combine things, not a target to hit.
|
||||
|
||||
- Comprehensive auth phase = 8 plans (because auth genuinely has 8 concerns)
|
||||
- Comprehensive "add config file" phase = 1 plan (because that's all it is)
|
||||
|
||||
For comprehensive depth:
|
||||
- Create MORE plans when the work warrants it, not bigger ones
|
||||
- If a phase has 15 tasks, that's 5-8 plans (not 3 plans with 5 tasks each)
|
||||
- Don't compress to look efficient—thoroughness is the goal
|
||||
- Let small phases stay small—don't pad to hit a number
|
||||
- Each plan stays focused: 2-3 tasks, single concern
|
||||
|
||||
For quick depth:
|
||||
- Combine aggressively into fewer plans
|
||||
- 1-3 plans per phase is fine
|
||||
- Focus on critical path
|
||||
</depth_aware_splitting>
|
||||
|
||||
**ALWAYS split if:** >3 tasks, multiple subsystems, >5 files in any task, complex domains (auth, payments).
|
||||
|
||||
**If scope appropriate (2-3 tasks, single subsystem, <5 files/task):** Proceed to confirm_breakdown.
|
||||
|
||||
**If large (>3 tasks):** Split by subsystem, dependency, complexity, or autonomous vs interactive.
|
||||
|
||||
**Each plan must be:** 2-3 tasks max, ~50% context target, independently committable.
|
||||
|
||||
**Autonomous optimization:** No checkpoints → subagent (fresh context). Has checkpoints → main context. Group autonomous work together.
|
||||
|
||||
See ./.claude/get-shit-done/references/scope-estimation.md for complete guidance.
|
||||
</step>
|
||||
|
||||
<step name="confirm_breakdown">
|
||||
<if mode="yolo">
|
||||
Auto-approve and proceed to write_phase_prompt.
|
||||
</if>
|
||||
|
||||
<if mode="interactive">
|
||||
Present breakdown inline:
|
||||
|
||||
```
|
||||
Phase [X] breakdown:
|
||||
|
||||
### Tasks ({phase}-01-PLAN.md)
|
||||
1. [Task] - [brief] [type]
|
||||
2. [Task] - [brief] [type]
|
||||
|
||||
Autonomous: [yes/no]
|
||||
|
||||
Does this look right? (yes / adjust / start over)
|
||||
```
|
||||
|
||||
For multiple plans, show each plan with its tasks.
|
||||
|
||||
Wait for confirmation. If "adjust": revise. If "start over": return to gather_phase_context.
|
||||
</if>
|
||||
</step>
|
||||
|
||||
<step name="write_phase_prompt">
|
||||
Use template from `./.claude/get-shit-done/templates/phase-prompt.md`.
|
||||
|
||||
**Single plan:** Write to `.planning/phases/XX-name/{phase}-01-PLAN.md`
|
||||
|
||||
**Multiple plans:** Write separate files ({phase}-01-PLAN.md, {phase}-02-PLAN.md, etc.)
|
||||
|
||||
Each plan follows template structure with:
|
||||
- Frontmatter (phase, plan, type, domain)
|
||||
- Objective (plan-specific goal, purpose, output)
|
||||
- Execution context (execute-phase.md, summary template, checkpoints.md if needed)
|
||||
- Context (@references to PROJECT, ROADMAP, STATE, codebase docs, RESEARCH/DISCOVERY/CONTEXT if exist, prior summaries, source files, prior decisions, deferred issues, concerns)
|
||||
- Tasks (XML format with types)
|
||||
- Verification, Success criteria, Output specification
|
||||
|
||||
**Context section population from frontmatter analysis:**
|
||||
|
||||
Inject automatically-assembled context package from read_project_history step:
|
||||
|
||||
```markdown
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
|
||||
# Auto-selected based on dependency graph (from frontmatter):
|
||||
@.planning/phases/XX-name/YY-ZZ-SUMMARY.md
|
||||
@.planning/phases/AA-name/BB-CC-SUMMARY.md
|
||||
|
||||
# Key files from frontmatter (relevant to this phase):
|
||||
@path/to/important/file.ts
|
||||
@path/to/another/file.ts
|
||||
|
||||
**Tech stack available:** [extracted from frontmatter tech-stack.added]
|
||||
**Established patterns:** [extracted from frontmatter patterns-established]
|
||||
**Constraining decisions:**
|
||||
- [Phase X]: [decision from frontmatter]
|
||||
- [Phase Y]: [decision from frontmatter]
|
||||
|
||||
**Issues being addressed:** [If any from ISSUES.md]
|
||||
</context>
|
||||
```
|
||||
|
||||
This ensures every PLAN.md gets optimal context automatically assembled via dependency graph, making execution as informed as possible.
|
||||
|
||||
For multi-plan phases: each plan has focused scope, references previous plan summaries (via frontmatter selection), last plan's success criteria includes "Phase X complete".
|
||||
</step>
|
||||
|
||||
<step name="git_commit">
|
||||
Commit phase plan(s):
|
||||
|
||||
```bash
|
||||
# Stage all PLAN.md files for this phase
|
||||
git add .planning/phases/${PHASE}-*/${PHASE}-*-PLAN.md
|
||||
|
||||
# Also stage DISCOVERY.md if it was created during mandatory_discovery
|
||||
git add .planning/phases/${PHASE}-*/DISCOVERY.md 2>/dev/null
|
||||
|
||||
git commit -m "$(cat <<'EOF'
|
||||
docs(${PHASE}): create phase plan
|
||||
|
||||
Phase ${PHASE}: ${PHASE_NAME}
|
||||
- [N] plan(s) created
|
||||
- [X] total tasks defined
|
||||
- Ready for execution
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
Confirm: "Committed: docs(${PHASE}): create phase plan"
|
||||
</step>
|
||||
|
||||
<step name="offer_next">
|
||||
```
|
||||
Phase plan created: .planning/phases/XX-name/{phase}-01-PLAN.md
|
||||
[X] tasks defined.
|
||||
|
||||
---
|
||||
|
||||
## Next Up
|
||||
|
||||
**{phase}-01: [Plan Name]** - [objective summary]
|
||||
|
||||
`/gsd:execute-plan .planning/phases/XX-name/{phase}-01-PLAN.md`
|
||||
|
||||
<sub>`/clear` first - fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- Review/adjust tasks before executing
|
||||
[If multiple plans: - View all plans: `ls .planning/phases/XX-name/*-PLAN.md`]
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<task_quality>
|
||||
**Good tasks:** Specific files, actions, verification
|
||||
- "Add User model to Prisma schema with email, passwordHash, createdAt"
|
||||
- "Create POST /api/auth/login endpoint with bcrypt validation"
|
||||
|
||||
**Bad tasks:** Vague, not actionable
|
||||
- "Set up authentication" / "Make it secure" / "Handle edge cases"
|
||||
|
||||
If you can't specify Files + Action + Verify + Done, the task is too vague.
|
||||
|
||||
**TDD candidates get dedicated plans.** If "Create price calculator with discount rules" warrants TDD, create a TDD plan for it. See `./.claude/get-shit-done/references/tdd.md` for TDD plan structure.
|
||||
</task_quality>
|
||||
|
||||
<anti_patterns>
|
||||
- No story points or hour estimates
|
||||
- No team assignments
|
||||
- No acceptance criteria committees
|
||||
- No sub-sub-sub tasks
|
||||
Tasks are instructions for Claude, not Jira tickets.
|
||||
</anti_patterns>
|
||||
|
||||
<success_criteria>
|
||||
Phase planning complete when:
|
||||
- [ ] STATE.md read, project history absorbed
|
||||
- [ ] Mandatory discovery completed (Level 0-3)
|
||||
- [ ] Prior decisions, issues, concerns synthesized
|
||||
- [ ] PLAN file(s) exist with XML structure
|
||||
- [ ] Each plan: Objective, context, tasks, verification, success criteria, output
|
||||
- [ ] @context references included (STATE, RESEARCH/DISCOVERY if exist, relevant summaries)
|
||||
- [ ] Each plan: 2-3 tasks (~50% context)
|
||||
- [ ] Each task: Type, Files (if auto), Action, Verify, Done
|
||||
- [ ] Checkpoints properly structured
|
||||
- [ ] If RESEARCH.md exists: "don't hand-roll" items NOT being custom-built
|
||||
- [ ] PLAN file(s) committed to git
|
||||
- [ ] User knows next steps
|
||||
</success_criteria>
|
||||
|
|
@ -0,0 +1,436 @@
|
|||
<purpose>
|
||||
Comprehensive research on HOW to implement a phase before planning.
|
||||
|
||||
Triggered by /gsd:research-phase command when the domain is niche, complex, or Claude's training is likely stale.
|
||||
|
||||
Produces RESEARCH.md with ecosystem knowledge that informs quality planning - not just "which library" but "how do experts build this."
|
||||
</purpose>
|
||||
|
||||
<when_to_use>
|
||||
**This workflow is for domains where Claude fails without research:**
|
||||
- 3D graphics (Three.js, Babylon.js, procedural generation, level design)
|
||||
- Game development (physics engines, collision, AI, ECS patterns)
|
||||
- Audio/music (Web Audio, DSP, synthesis, MIDI)
|
||||
- Shaders (GLSL, Metal, ISF, compute shaders)
|
||||
- ML/AI integration (model serving, inference, vector DBs)
|
||||
- Real-time systems (WebSockets, WebRTC, CRDT sync)
|
||||
- Specialized frameworks with active ecosystems Claude may not know
|
||||
|
||||
**Skip this for commodity domains:**
|
||||
- Standard auth (JWT, OAuth)
|
||||
- CRUD APIs
|
||||
- Forms and validation
|
||||
- Well-documented integrations (Stripe, SendGrid)
|
||||
</when_to_use>
|
||||
|
||||
<key_insight>
|
||||
The current "mandatory discovery" in plan-phase asks: "Which library should I use?"
|
||||
|
||||
This workflow asks: "What do I not know that I don't know?"
|
||||
|
||||
For niche domains, the question isn't library selection - it's:
|
||||
- What's the established architecture pattern?
|
||||
- What libraries form the standard stack?
|
||||
- What problems do people commonly hit?
|
||||
- What's SOTA vs what Claude thinks is SOTA?
|
||||
- What should NOT be hand-rolled?
|
||||
</key_insight>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="validate_phase" priority="first">
|
||||
Phase number: $ARGUMENTS (required)
|
||||
|
||||
Validate phase exists in roadmap:
|
||||
|
||||
```bash
|
||||
if [ -f .planning/ROADMAP.md ]; then
|
||||
grep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md
|
||||
fi
|
||||
```
|
||||
|
||||
**If phase not found:**
|
||||
```
|
||||
Error: Phase ${PHASE} not found in roadmap.
|
||||
|
||||
Use /gsd:progress to see available phases.
|
||||
```
|
||||
Exit workflow.
|
||||
|
||||
**If phase found:**
|
||||
Extract:
|
||||
- Phase number
|
||||
- Phase name
|
||||
- Phase description
|
||||
- Any "Research: Likely" flags
|
||||
|
||||
Continue to check_existing.
|
||||
</step>
|
||||
|
||||
<step name="check_existing">
|
||||
Check if RESEARCH.md already exists for this phase:
|
||||
|
||||
```bash
|
||||
ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
|
||||
ls .planning/phases/${PHASE}-*/${PHASE}-RESEARCH.md 2>/dev/null
|
||||
```
|
||||
|
||||
**If exists:**
|
||||
```
|
||||
Phase ${PHASE} already has research: [path to RESEARCH.md]
|
||||
|
||||
What's next?
|
||||
1. Update research - Refresh with new findings
|
||||
2. View existing - Show me the current research
|
||||
3. Skip - Use existing research as-is
|
||||
```
|
||||
|
||||
Wait for user response.
|
||||
|
||||
If "Update research": Load existing RESEARCH.md, proceed to research with update mindset
|
||||
If "View existing": Read and display RESEARCH.md, then offer update/skip
|
||||
If "Skip": Exit workflow
|
||||
|
||||
**If doesn't exist:**
|
||||
Continue to load_context.
|
||||
</step>
|
||||
|
||||
<step name="load_context">
|
||||
Load available context to inform research direction:
|
||||
|
||||
**1. Project context:**
|
||||
```bash
|
||||
cat .planning/PROJECT.md 2>/dev/null | head -50
|
||||
```
|
||||
|
||||
**2. Phase context (if exists from /gsd:discuss-phase):**
|
||||
```bash
|
||||
cat .planning/phases/${PHASE}-*/${PHASE}-CONTEXT.md 2>/dev/null
|
||||
```
|
||||
|
||||
If CONTEXT.md exists, use it to understand:
|
||||
- User's specific goals for this phase
|
||||
- Constraints mentioned
|
||||
- Any preferences stated
|
||||
|
||||
**3. Prior phase decisions:**
|
||||
```bash
|
||||
cat .planning/STATE.md 2>/dev/null | grep -A20 "## Accumulated Decisions"
|
||||
```
|
||||
|
||||
These may constrain technology choices.
|
||||
|
||||
Present what was found:
|
||||
```
|
||||
Research context for Phase ${PHASE}: ${PHASE_NAME}
|
||||
|
||||
Roadmap description: ${PHASE_DESCRIPTION}
|
||||
|
||||
[If CONTEXT.md exists:]
|
||||
Phase context available - will incorporate user preferences.
|
||||
|
||||
[If prior decisions exist:]
|
||||
Prior decisions to respect: [list relevant ones]
|
||||
|
||||
Proceeding with ecosystem research...
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="identify_domains">
|
||||
Analyze the phase description to identify what needs researching.
|
||||
|
||||
**Ask: "What knowledge do I need to actually implement this well?"**
|
||||
|
||||
Categories to consider:
|
||||
|
||||
**1. Core Technology:**
|
||||
- What's the primary technology/framework?
|
||||
- What version is current? (Claude's training may be stale)
|
||||
- What's the standard setup/toolchain?
|
||||
|
||||
**2. Ecosystem/Stack:**
|
||||
- What libraries do experts pair with this?
|
||||
- What's the "blessed" stack for this problem domain?
|
||||
- What helper libraries exist that I might not know about?
|
||||
|
||||
**3. Architecture Patterns:**
|
||||
- How do experts structure this type of project?
|
||||
- What design patterns apply?
|
||||
- What's the recommended project organization?
|
||||
|
||||
**4. Common Pitfalls:**
|
||||
- What do beginners get wrong?
|
||||
- What are the "gotchas" in this domain?
|
||||
- What mistakes lead to rewrites?
|
||||
|
||||
**5. What NOT to Hand-Roll:**
|
||||
- What existing solutions should be used instead of custom code?
|
||||
- What problems look simple but have nasty edge cases?
|
||||
- What libraries solve problems I don't know I have?
|
||||
|
||||
**6. Current State of the Art:**
|
||||
- What's changed recently in this ecosystem?
|
||||
- What approaches are now considered outdated?
|
||||
- What new tools/patterns have emerged?
|
||||
|
||||
Present research scope:
|
||||
```
|
||||
Research domains identified:
|
||||
|
||||
1. Core: [e.g., "Three.js for 3D web graphics"]
|
||||
2. Ecosystem: [e.g., "Physics engine, asset loading, controls"]
|
||||
3. Patterns: [e.g., "Scene graph architecture, game loop patterns"]
|
||||
4. Pitfalls: [e.g., "Performance, memory, mobile compatibility"]
|
||||
5. Don't hand-roll: [e.g., "Physics, collision detection, procedural generation"]
|
||||
6. SOTA check: [e.g., "WebGPU vs WebGL, drei ecosystem"]
|
||||
|
||||
Proceeding with comprehensive research...
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="execute_research">
|
||||
Execute research systematically for each domain identified.
|
||||
|
||||
**CRITICAL: Source hierarchy - Context7 BEFORE WebSearch**
|
||||
|
||||
Claude's training data is 6-18 months stale. Treat pre-existing knowledge as hypothesis, not fact.
|
||||
|
||||
<research_protocol>
|
||||
|
||||
**For each domain, in order:**
|
||||
|
||||
**1. Context7 First (authoritative, current):**
|
||||
```
|
||||
For core technology:
|
||||
- mcp__context7__resolve-library-id with libraryName: "[main technology]"
|
||||
- mcp__context7__get-library-docs with topic: "getting started"
|
||||
- mcp__context7__get-library-docs with topic: "[specific concern]"
|
||||
|
||||
For ecosystem libraries:
|
||||
- Resolve and fetch docs for each major library
|
||||
- Focus on integration patterns, not just API reference
|
||||
```
|
||||
|
||||
**2. Official Documentation:**
|
||||
- Use WebFetch for official docs not in Context7
|
||||
- Check for "ecosystem" or "community" pages
|
||||
- Look for "awesome-{technology}" lists
|
||||
- Check GitHub trending/stars for the domain
|
||||
|
||||
**3. WebSearch for Ecosystem Discovery:**
|
||||
```
|
||||
Ecosystem discovery queries (use {current_year}):
|
||||
- "[technology] best practices {current_year}"
|
||||
- "[technology] recommended libraries {current_year}"
|
||||
- "[technology] common mistakes"
|
||||
- "[technology] vs [alternative] {current_year}"
|
||||
- "how to build [type of thing] with [technology]"
|
||||
- "[technology] performance optimization"
|
||||
- "[technology] project structure"
|
||||
|
||||
For niche domains:
|
||||
- "[technology] tutorials {current_year}"
|
||||
- "[technology] examples github"
|
||||
- "[technology] showcase"
|
||||
```
|
||||
|
||||
**4. Cross-Verification (MANDATORY):**
|
||||
Every WebSearch finding MUST be verified:
|
||||
- Check Context7 or official docs to confirm
|
||||
- Mark confidence level (HIGH if verified, MEDIUM if partially verified, LOW if WebSearch only)
|
||||
- Flag contradictions between sources
|
||||
|
||||
</research_protocol>
|
||||
|
||||
<research_execution>
|
||||
Execute research queries and document findings as you go:
|
||||
|
||||
**Core Technology Findings:**
|
||||
- Current version: [from Context7]
|
||||
- Key changes since [Claude's training]: [from docs/WebSearch]
|
||||
- Setup approach: [verified pattern]
|
||||
|
||||
**Ecosystem Stack:**
|
||||
- [Library 1]: [what it does, why it's standard, version]
|
||||
- [Library 2]: [what it does, why it's standard, version]
|
||||
- [Library 3]: [what it does, why it's standard, version]
|
||||
|
||||
**Architecture Patterns:**
|
||||
- [Pattern 1]: [what it is, when to use]
|
||||
- [Pattern 2]: [what it is, when to use]
|
||||
- Project structure: [recommended organization]
|
||||
|
||||
**Common Pitfalls:**
|
||||
- [Pitfall 1]: [what goes wrong, how to avoid]
|
||||
- [Pitfall 2]: [what goes wrong, how to avoid]
|
||||
- [Pitfall 3]: [what goes wrong, how to avoid]
|
||||
|
||||
**Don't Hand-Roll:**
|
||||
- [Problem]: Use [library] instead because [reason]
|
||||
- [Problem]: Use [library] instead because [reason]
|
||||
|
||||
**SOTA Updates:**
|
||||
- [Old approach]: Now superseded by [new approach]
|
||||
- [New tool]: [what it enables]
|
||||
</research_execution>
|
||||
|
||||
</step>
|
||||
|
||||
<step name="quality_check">
|
||||
Before creating RESEARCH.md, run through research-pitfalls.md checklist:
|
||||
|
||||
**From ./.claude/get-shit-done/references/research-pitfalls.md:**
|
||||
|
||||
- [ ] All enumerated items investigated (not just some)
|
||||
- [ ] Negative claims verified with official docs
|
||||
- [ ] Multiple sources cross-referenced for critical claims
|
||||
- [ ] URLs provided for authoritative sources
|
||||
- [ ] 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
|
||||
|
||||
**Additional checks for ecosystem research:**
|
||||
- [ ] Checked for libraries Claude might not know about
|
||||
- [ ] Verified version numbers are current
|
||||
- [ ] Confirmed patterns still recommended (not deprecated)
|
||||
- [ ] Looked for "don't do this" warnings in docs
|
||||
- [ ] Checked for breaking changes in recent versions
|
||||
</step>
|
||||
|
||||
<step name="write_research">
|
||||
Create RESEARCH.md using accumulated findings.
|
||||
|
||||
**File location:** `.planning/phases/${PHASE}-${SLUG}/${PHASE}-RESEARCH.md`
|
||||
|
||||
**If phase directory doesn't exist:**
|
||||
Create it: `.planning/phases/${PHASE}-${SLUG}/`
|
||||
|
||||
Use template from ./.claude/get-shit-done/templates/research.md
|
||||
|
||||
Populate sections with verified findings from research execution.
|
||||
|
||||
**Critical content requirements:**
|
||||
|
||||
**1. Standard Stack section:**
|
||||
- List specific libraries with versions
|
||||
- Explain what each does and why it's standard
|
||||
- Note any alternatives and when to use them
|
||||
|
||||
**2. Architecture Patterns section:**
|
||||
- Document recommended patterns with code examples if available
|
||||
- Include project structure recommendations
|
||||
- Note what patterns to avoid
|
||||
|
||||
**3. Don't Hand-Roll section:**
|
||||
- Be explicit about what problems have existing solutions
|
||||
- Explain why custom solutions are worse
|
||||
- List the libraries to use instead
|
||||
|
||||
**4. Common Pitfalls section:**
|
||||
- Specific mistakes with explanations
|
||||
- How to avoid each
|
||||
- Warning signs to watch for
|
||||
|
||||
**5. Code Examples section:**
|
||||
- Include verified code patterns from Context7/official docs
|
||||
- Show the "right way" to do common operations
|
||||
- Note any gotchas in the examples
|
||||
|
||||
Write file.
|
||||
</step>
|
||||
|
||||
<step name="confirm_creation">
|
||||
Present RESEARCH.md summary to user:
|
||||
|
||||
```
|
||||
Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-RESEARCH.md
|
||||
|
||||
## Research Summary
|
||||
|
||||
**Domain:** [what was researched]
|
||||
|
||||
**Standard Stack:**
|
||||
- [Library 1] - [brief what/why]
|
||||
- [Library 2] - [brief what/why]
|
||||
- [Library 3] - [brief what/why]
|
||||
|
||||
**Key Patterns:**
|
||||
- [Pattern 1]
|
||||
- [Pattern 2]
|
||||
|
||||
**Don't Hand-Roll:**
|
||||
- [Thing 1] - use [library] instead
|
||||
- [Thing 2] - use [library] instead
|
||||
|
||||
**Top Pitfalls:**
|
||||
- [Pitfall 1]
|
||||
- [Pitfall 2]
|
||||
|
||||
**Confidence:** [HIGH/MEDIUM/LOW] - [brief reason]
|
||||
|
||||
What's next?
|
||||
1. Plan this phase (/gsd:plan-phase ${PHASE}) - RESEARCH.md will be loaded automatically
|
||||
2. Dig deeper - Research specific areas more thoroughly
|
||||
3. Review full RESEARCH.md
|
||||
4. Done for now
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="git_commit">
|
||||
Commit phase research:
|
||||
|
||||
```bash
|
||||
git add .planning/phases/${PHASE}-${SLUG}/${PHASE}-RESEARCH.md
|
||||
git commit -m "$(cat <<'EOF'
|
||||
docs(${PHASE}): complete phase research
|
||||
|
||||
Phase ${PHASE}: ${PHASE_NAME}
|
||||
- Standard stack identified
|
||||
- Architecture patterns documented
|
||||
- Common pitfalls catalogued
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
Confirm: "Committed: docs(${PHASE}): complete phase research"
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Phase validated against roadmap
|
||||
- [ ] Research domains identified from phase description
|
||||
- [ ] Context7 consulted for all relevant libraries
|
||||
- [ ] Official docs consulted where Context7 lacks coverage
|
||||
- [ ] WebSearch used for ecosystem discovery
|
||||
- [ ] All WebSearch findings cross-verified
|
||||
- [ ] Quality checklist completed
|
||||
- [ ] RESEARCH.md created with comprehensive ecosystem knowledge
|
||||
- [ ] Standard stack documented with versions
|
||||
- [ ] Architecture patterns documented
|
||||
- [ ] "Don't hand-roll" list is clear and actionable
|
||||
- [ ] Common pitfalls catalogued
|
||||
- [ ] Confidence levels assigned honestly
|
||||
- [ ] RESEARCH.md committed to git
|
||||
- [ ] User knows next steps (plan phase)
|
||||
</success_criteria>
|
||||
|
||||
<integration_with_planning>
|
||||
When /gsd:plan-phase runs after research:
|
||||
|
||||
1. plan-phase detects RESEARCH.md exists in phase directory
|
||||
2. RESEARCH.md loaded as @context reference
|
||||
3. "Standard stack" informs library choices in tasks
|
||||
4. "Don't hand-roll" prevents custom solutions where libraries exist
|
||||
5. "Common pitfalls" inform verification criteria
|
||||
6. "Architecture patterns" inform task structure
|
||||
7. "Code examples" can be referenced in task actions
|
||||
|
||||
This produces higher quality plans because Claude knows:
|
||||
- What tools experts use
|
||||
- What patterns to follow
|
||||
- What mistakes to avoid
|
||||
- What NOT to build from scratch
|
||||
</integration_with_planning>
|
||||
|
|
@ -0,0 +1,287 @@
|
|||
<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, then PROJECT.md:
|
||||
|
||||
```bash
|
||||
cat .planning/STATE.md
|
||||
cat .planning/PROJECT.md
|
||||
```
|
||||
|
||||
**From STATE.md extract:**
|
||||
|
||||
- **Project Reference**: Core value and current focus
|
||||
- **Current Position**: Phase X of Y, Plan A of B, Status
|
||||
- **Progress**: Visual progress bar
|
||||
- **Recent Decisions**: Key decisions affecting current work
|
||||
- **Deferred Issues**: Open items awaiting attention
|
||||
- **Blockers/Concerns**: Issues carried forward
|
||||
- **Session Continuity**: Where we left off, any resume files
|
||||
|
||||
**From PROJECT.md extract:**
|
||||
|
||||
- **What This Is**: Current accurate description
|
||||
- **Requirements**: Validated, Active, Out of Scope
|
||||
- **Key Decisions**: Full decision log with outcomes
|
||||
- **Constraints**: Hard limits on implementation
|
||||
|
||||
</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 PROJECT.md "What This Is"] ║
|
||||
║ ║
|
||||
║ 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 vision (how user imagines it working)
|
||||
→ 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** → Show command for user to run after clearing:
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**{phase}-{plan}: [Plan Name]** — [objective from PLAN.md]
|
||||
|
||||
`/gsd:execute-plan [path]`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
- **Plan phase** → Show command for user to run after clearing:
|
||||
```
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase [N]: [Name]** — [Goal from ROADMAP.md]
|
||||
|
||||
`/gsd:plan-phase [phase-number]`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:discuss-phase [N]` — gather context first
|
||||
- `/gsd:research-phase [N]` — investigate unknowns
|
||||
|
||||
---
|
||||
```
|
||||
- **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
|
||||
</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 "What This Is" and Core Value
|
||||
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>
|
||||
|
|
@ -0,0 +1,580 @@
|
|||
<required_reading>
|
||||
|
||||
**Read these files NOW:**
|
||||
|
||||
1. `.planning/STATE.md`
|
||||
2. `.planning/PROJECT.md`
|
||||
3. `.planning/ROADMAP.md`
|
||||
4. Current phase's plan files (`*-PLAN.md`)
|
||||
5. 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 and PROJECT.md evolution happen.
|
||||
|
||||
"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
|
||||
cat .planning/PROJECT.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
|
||||
|
||||
<config-check>
|
||||
|
||||
```bash
|
||||
cat .planning/config.json 2>/dev/null
|
||||
```
|
||||
|
||||
</config-check>
|
||||
|
||||
**If all plans complete:**
|
||||
|
||||
<if mode="yolo">
|
||||
|
||||
```
|
||||
⚡ 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 step.
|
||||
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="custom with gates.confirm_transition true">
|
||||
|
||||
Ask: "Phase [X] complete — all [Y] plans finished. Ready to mark done and move to Phase [X+1]?"
|
||||
|
||||
Wait for confirmation before proceeding.
|
||||
|
||||
</if>
|
||||
|
||||
**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="evolve_project">
|
||||
|
||||
Evolve PROJECT.md to reflect learnings from completed phase.
|
||||
|
||||
**Read phase summaries:**
|
||||
|
||||
```bash
|
||||
cat .planning/phases/XX-current/*-SUMMARY.md
|
||||
```
|
||||
|
||||
**Assess requirement changes:**
|
||||
|
||||
1. **Requirements validated?**
|
||||
- Any Active requirements shipped in this phase?
|
||||
- Move to Validated with phase reference: `- ✓ [Requirement] — Phase X`
|
||||
|
||||
2. **Requirements invalidated?**
|
||||
- Any Active requirements discovered to be unnecessary or wrong?
|
||||
- Move to Out of Scope with reason: `- [Requirement] — [why invalidated]`
|
||||
|
||||
3. **Requirements emerged?**
|
||||
- Any new requirements discovered during building?
|
||||
- Add to Active: `- [ ] [New requirement]`
|
||||
|
||||
4. **Decisions to log?**
|
||||
- Extract decisions from SUMMARY.md files
|
||||
- Add to Key Decisions table with outcome if known
|
||||
|
||||
5. **"What This Is" still accurate?**
|
||||
- If the product has meaningfully changed, update the description
|
||||
- Keep it current and accurate
|
||||
|
||||
**Update PROJECT.md:**
|
||||
|
||||
Make the edits inline. Update "Last updated" footer:
|
||||
|
||||
```markdown
|
||||
---
|
||||
*Last updated: [date] after Phase [X]*
|
||||
```
|
||||
|
||||
**Example evolution:**
|
||||
|
||||
Before:
|
||||
|
||||
```markdown
|
||||
### Active
|
||||
|
||||
- [ ] JWT authentication
|
||||
- [ ] Real-time sync < 500ms
|
||||
- [ ] Offline mode
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- OAuth2 — complexity not needed for v1
|
||||
```
|
||||
|
||||
After (Phase 2 shipped JWT auth, discovered rate limiting needed):
|
||||
|
||||
```markdown
|
||||
### Validated
|
||||
|
||||
- ✓ JWT authentication — Phase 2
|
||||
|
||||
### Active
|
||||
|
||||
- [ ] Real-time sync < 500ms
|
||||
- [ ] Offline mode
|
||||
- [ ] Rate limiting on sync endpoint
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- OAuth2 — complexity not needed for v1
|
||||
```
|
||||
|
||||
**Step complete when:**
|
||||
|
||||
- [ ] Phase summaries reviewed for learnings
|
||||
- [ ] Validated requirements moved from Active
|
||||
- [ ] Invalidated requirements moved to Out of Scope with reason
|
||||
- [ ] Emerged requirements added to Active
|
||||
- [ ] New decisions logged with rationale
|
||||
- [ ] "What This Is" updated if product changed
|
||||
- [ ] "Last updated" footer reflects this transition
|
||||
|
||||
</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 reflects total completed plans
|
||||
|
||||
</step>
|
||||
|
||||
<step name="update_project_reference">
|
||||
|
||||
Update Project Reference section in STATE.md.
|
||||
|
||||
```markdown
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated [today])
|
||||
|
||||
**Core value:** [Current core value from PROJECT.md]
|
||||
**Current focus:** [Next phase name]
|
||||
```
|
||||
|
||||
Update the date and current focus to reflect the transition.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="review_accumulated_context">
|
||||
|
||||
Review and update Accumulated Context section in STATE.md.
|
||||
|
||||
**Decisions:**
|
||||
|
||||
- Note recent decisions from this phase (3-5 max)
|
||||
- Full log lives in PROJECT.md Key Decisions table
|
||||
|
||||
**Blockers/Concerns:**
|
||||
|
||||
- Review blockers from completed phase
|
||||
- If addressed in this phase: Remove from list
|
||||
- If still relevant for future: Keep with "Phase X" prefix
|
||||
- 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
|
||||
|
||||
- ⚠️ [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
|
||||
|
||||
- ⚠️ [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:**
|
||||
|
||||
- [ ] Recent decisions noted (full log in PROJECT.md)
|
||||
- [ ] 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_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
|
||||
```
|
||||
|
||||
**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">
|
||||
|
||||
**MANDATORY: Verify milestone status before presenting next steps.**
|
||||
|
||||
**Step 1: Read ROADMAP.md and identify phases in current milestone**
|
||||
|
||||
Read the ROADMAP.md file and extract:
|
||||
1. Current phase number (the phase just transitioned from)
|
||||
2. All phase numbers in the current milestone section
|
||||
|
||||
To find phases, look for:
|
||||
- Phase headers: lines starting with `### Phase` or `#### Phase`
|
||||
- Phase list items: lines like `- [ ] **Phase X:` or `- [x] **Phase X:`
|
||||
|
||||
Count total phases and identify the highest phase number in the milestone.
|
||||
|
||||
State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."
|
||||
|
||||
**Step 2: Route based on milestone status**
|
||||
|
||||
| Condition | Meaning | Action |
|
||||
|-----------|---------|--------|
|
||||
| current phase < highest phase | More phases remain | Go to **Route A** |
|
||||
| current phase = highest phase | Milestone complete | Go to **Route B** |
|
||||
|
||||
---
|
||||
|
||||
**Route A: More phases remain in milestone**
|
||||
|
||||
Read ROADMAP.md to get the next phase's name and goal.
|
||||
|
||||
**If next phase exists:**
|
||||
|
||||
<if mode="yolo">
|
||||
|
||||
```
|
||||
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>
|
||||
|
||||
<if mode="interactive" OR="custom with gates.confirm_transition true">
|
||||
|
||||
```
|
||||
## ✓ Phase [X] Complete
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
|
||||
|
||||
`/gsd:plan-phase [X+1]`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:discuss-phase [X+1]` — gather context first
|
||||
- `/gsd:research-phase [X+1]` — investigate unknowns
|
||||
- Review roadmap
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</if>
|
||||
|
||||
---
|
||||
|
||||
**Route B: Milestone complete (all phases done)**
|
||||
|
||||
<if mode="yolo">
|
||||
|
||||
```
|
||||
Phase {X} marked complete.
|
||||
|
||||
🎉 Milestone {version} is 100% complete — all {N} phases finished!
|
||||
|
||||
⚡ Auto-continuing: Complete milestone and archive
|
||||
```
|
||||
|
||||
Exit skill and invoke SlashCommand("/gsd:complete-milestone {version}")
|
||||
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="custom with gates.confirm_transition true">
|
||||
|
||||
```
|
||||
## ✓ Phase {X}: {Phase Name} Complete
|
||||
|
||||
🎉 Milestone {version} is 100% complete — all {N} phases finished!
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Complete Milestone {version}** — archive and prepare for next
|
||||
|
||||
`/gsd:complete-milestone {version}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- Review accomplishments before archiving
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</if>
|
||||
|
||||
</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
|
||||
- [ ] PROJECT.md evolved (requirements, decisions, description if needed)
|
||||
- [ ] STATE.md updated (position, project reference, context, session)
|
||||
- [ ] Progress table updated
|
||||
- [ ] User knows next steps
|
||||
|
||||
</success_criteria>
|
||||
|
|
@ -0,0 +1,202 @@
|
|||
<purpose>
|
||||
Guide manual user acceptance testing of recently built features. Extract deliverables from SUMMARY.md, generate test checklist, guide user through each test, log issues to phase-scoped file.
|
||||
|
||||
The USER performs all testing — Claude generates the checklist, guides the process, and captures issues.
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="identify">
|
||||
**Determine what to test:**
|
||||
|
||||
If $ARGUMENTS provided:
|
||||
- Parse as phase number (e.g., "4") or plan number (e.g., "04-02")
|
||||
- Find corresponding SUMMARY.md file(s)
|
||||
|
||||
If no arguments:
|
||||
- Find most recently modified SUMMARY.md
|
||||
|
||||
```bash
|
||||
find .planning/phases -name "*SUMMARY.md" -type f -exec ls -lt {} + | head -5
|
||||
```
|
||||
|
||||
Read the SUMMARY.md to understand what was built.
|
||||
</step>
|
||||
|
||||
<step name="extract">
|
||||
**Extract testable deliverables from SUMMARY.md:**
|
||||
|
||||
Parse for:
|
||||
1. **Accomplishments** - Features/functionality added
|
||||
2. **Files Created/Modified** - What changed
|
||||
3. **User-facing changes** - UI, workflows, interactions
|
||||
|
||||
Focus on USER-OBSERVABLE outcomes, not implementation details.
|
||||
|
||||
Examples:
|
||||
- "Check-in menu item added to navigation" → User can see/click Check-in in nav
|
||||
- "HomePage refreshes after check-in" → After check-in, home shows updated state
|
||||
</step>
|
||||
|
||||
<step name="generate">
|
||||
**Generate manual test checklist:**
|
||||
|
||||
Create structured test plan:
|
||||
|
||||
```
|
||||
# User Acceptance Test: [Plan/Phase Name]
|
||||
|
||||
**Scope:** [What was built - from SUMMARY.md]
|
||||
**Testing:** Manual user validation
|
||||
|
||||
## Pre-flight
|
||||
- [ ] Application builds and runs without errors
|
||||
- [ ] Application launches to expected state
|
||||
|
||||
## Feature Tests
|
||||
|
||||
### [Feature 1 from deliverables]
|
||||
**What to test:** [User-observable behavior]
|
||||
**Steps:**
|
||||
1. [Specific action to take]
|
||||
2. [What to look for]
|
||||
3. [Expected result]
|
||||
|
||||
### [Feature 2 from deliverables]
|
||||
...
|
||||
|
||||
## Edge Cases
|
||||
- [ ] [Relevant edge case based on feature]
|
||||
- [ ] [Another edge case]
|
||||
|
||||
## Visual/UX Check
|
||||
- [ ] UI matches expected design
|
||||
- [ ] No visual glitches or layout issues
|
||||
- [ ] Responsive to interactions
|
||||
```
|
||||
|
||||
Present this checklist to user.
|
||||
</step>
|
||||
|
||||
<step name="guide">
|
||||
**Guide user through each test:**
|
||||
|
||||
For each test item, use AskUserQuestion:
|
||||
- header: "[Feature name]"
|
||||
- question: "[Test description] - Did this work as expected?"
|
||||
- options:
|
||||
- "Pass" — Works correctly
|
||||
- "Fail" — Doesn't work as expected
|
||||
- "Partial" — Works but with issues
|
||||
- "Skip" — Can't test right now
|
||||
|
||||
**If Pass:** Move to next test
|
||||
|
||||
**If Fail or Partial:**
|
||||
Follow up with AskUserQuestion:
|
||||
- header: "Issue details"
|
||||
- question: "What went wrong?"
|
||||
- options:
|
||||
- "Crashes/errors" — Application error or exception
|
||||
- "Wrong behavior" — Does something unexpected
|
||||
- "Missing feature" — Expected functionality not present
|
||||
- "UI/visual issue" — Looks wrong but functions
|
||||
- "Let me describe" — Free-form description needed
|
||||
</step>
|
||||
|
||||
<step name="collect">
|
||||
**Collect and categorize issues:**
|
||||
|
||||
For each failed/partial test, gather:
|
||||
- Feature affected
|
||||
- What went wrong (from user input)
|
||||
- Severity:
|
||||
- **Blocker** — Can't use the feature at all
|
||||
- **Major** — Feature works but significant problem
|
||||
- **Minor** — Small issue, feature still usable
|
||||
- **Cosmetic** — Visual only, no functional impact
|
||||
</step>
|
||||
|
||||
<step name="log">
|
||||
**Log issues to phase-scoped file:**
|
||||
|
||||
If any issues found:
|
||||
|
||||
1. Create `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md` if doesn't exist
|
||||
2. Use template from `@./.claude/get-shit-done/templates/uat-issues.md`
|
||||
3. Add each issue:
|
||||
|
||||
```markdown
|
||||
### UAT-[NNN]: [Brief description]
|
||||
|
||||
**Discovered:** [date] during user acceptance testing
|
||||
**Phase/Plan:** [phase]-[plan] that was tested
|
||||
**Severity:** [Blocker/Major/Minor/Cosmetic]
|
||||
**Description:** [User's description of the problem]
|
||||
**Expected:** [What should have happened]
|
||||
**Actual:** [What actually happened]
|
||||
```
|
||||
|
||||
**Note:** Issues go to phase-scoped file, NOT global `.planning/ISSUES.md`. This keeps UAT findings tied to the specific work being tested and enables `/gsd:plan-fix` to address them.
|
||||
</step>
|
||||
|
||||
<step name="summarize">
|
||||
**Present test summary:**
|
||||
|
||||
```
|
||||
# Test Results: [Plan/Phase Name]
|
||||
|
||||
**Tests run:** [N]
|
||||
**Passed:** [N]
|
||||
**Failed:** [N]
|
||||
**Partial:** [N]
|
||||
**Skipped:** [N]
|
||||
|
||||
## Issues Found
|
||||
[List any issues with severity]
|
||||
|
||||
## Verdict
|
||||
[Based on results:]
|
||||
- ALL PASS: "All tests passed. Feature validated."
|
||||
- MINOR ISSUES: "Feature works with minor issues logged."
|
||||
- MAJOR ISSUES: "Significant issues found - review before proceeding."
|
||||
- BLOCKERS: "Blocking issues found - must fix before continuing."
|
||||
|
||||
## Next Steps
|
||||
[Based on verdict:]
|
||||
- If clean: Suggest proceeding to next phase
|
||||
- If issues: Suggest /gsd:plan-fix to address
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="offer">
|
||||
**Offer next actions based on results:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Next"
|
||||
- question: "What would you like to do?"
|
||||
- options (based on results):
|
||||
|
||||
If all passed:
|
||||
- "Continue to next phase" — Proceed with confidence
|
||||
- "Test more" — Run additional manual tests
|
||||
- "Done" — Finish testing session
|
||||
|
||||
If issues found:
|
||||
- "Plan fixes" — Create plan to address issues (/gsd:plan-fix)
|
||||
- "Log and continue" — Issues logged, proceed anyway
|
||||
- "Review issues" — Look at logged issues in detail
|
||||
- "Done" — Finish testing session
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Test scope identified from SUMMARY.md
|
||||
- [ ] Checklist generated based on deliverables
|
||||
- [ ] User guided through each test via AskUserQuestion
|
||||
- [ ] All test results captured (pass/fail/partial/skip)
|
||||
- [ ] Any issues logged to phase-scoped ISSUES.md
|
||||
- [ ] Summary presented with verdict
|
||||
- [ ] User knows next steps based on results
|
||||
</success_criteria>
|
||||
Loading…
Reference in New Issue