feat: add uncommitted planning mode (#107)

* feat: add uncommitted planning mode

Add config option to keep planning docs local-only (not committed to git).
Useful for OSS contributions, client projects, or keeping planning private.

Config options in .planning/config.json:
- planning.commit_docs: true/false (default: true)
- planning.search_gitignored: true/false (default: false)

When commit_docs=false:
- All git operations for .planning/ files are skipped
- User should add .planning/ to .gitignore
- Planning system works normally, just not tracked

Updated files:
- config.json template: added planning section
- execute-plan.md: conditional git commits
- execute-phase.md: conditional git commits
- create-roadmap.md: conditional git commits
- help.md: documented new config options
- planning-config.md: reference doc for config behavior

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: extend commit_docs check to all agents/commands/workflows

Add COMMIT_PLANNING_DOCS config check to all files that commit
.planning/ artifacts, ensuring consistent behavior when
commit_docs=false is set in config.json.

Updated:
- 5 agents (planner, executor, debugger, phase-researcher, synthesizer)
- 8 commands (add-todo, check-todos, execute-phase, new-milestone,
  pause-work, plan-milestone-gaps, remove-phase, research-project)
- 7 workflows (complete-milestone, create-milestone, define-requirements,
  diagnose-issues, discuss-phase, map-codebase, verify-work)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(progress): use Bash instead of Glob for .planning/ check

Glob respects .gitignore, so projects with gitignored .planning/
directories would fail with "No planning structure found."

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(new-milestone): integrate full research/requirements/roadmap flow

Previously routed to non-existent /gsd:research-project and
/gsd:define-requirements commands. Now handles the full flow inline
like new-project does:

- Phase 7: Research Decision (spawns 4 milestone-aware researchers)
- Phase 8: Define Requirements (scopes features, creates REQUIREMENTS.md)
- Phase 9: Create Roadmap (continues phase numbering from previous milestone)
- Phase 10: Done

Key adaptations for milestones:
- Research focuses on NEW features only
- Requirements add to existing, don't start fresh
- Phase numbering continues from previous milestone

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
dan bachelder
2026-01-19 14:49:05 -08:00
committed by GitHub
parent f8096792cc
commit 1f18ec8907
23 changed files with 608 additions and 264 deletions

View File

@@ -979,7 +979,16 @@ mkdir -p .planning/debug/resolved
mv .planning/debug/{slug}.md .planning/debug/resolved/ mv .planning/debug/{slug}.md .planning/debug/resolved/
``` ```
Commit: **Check planning config:**
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
**Commit the fix:**
If `COMMIT_PLANNING_DOCS=true` (default):
```bash ```bash
git add -A git add -A
git commit -m "fix: {brief description} git commit -m "fix: {brief description}
@@ -988,6 +997,16 @@ Root cause: {root_cause}
Debug session: .planning/debug/resolved/{slug}.md" Debug session: .planning/debug/resolved/{slug}.md"
``` ```
If `COMMIT_PLANNING_DOCS=false`:
```bash
# Only commit code changes, exclude .planning/
git add -A
git reset .planning/
git commit -m "fix: {brief description}
Root cause: {root_cause}"
```
Report completion and offer next steps. Report completion and offer next steps.
</step> </step>

View File

@@ -39,6 +39,17 @@ Options:
``` ```
**If .planning/ doesn't exist:** Error - project not initialized. **If .planning/ doesn't exist:** Error - project not initialized.
**Load planning config:**
```bash
# Check if planning docs should be committed (default: true)
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
# Auto-detect gitignored (overrides config)
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
Store `COMMIT_PLANNING_DOCS` for use in git operations.
</step> </step>
<step name="load_plan"> <step name="load_plan">
@@ -692,6 +703,10 @@ Resume file: [path to .continue-here if exists, else "None"]
<final_commit> <final_commit>
After SUMMARY.md and STATE.md updates: After SUMMARY.md and STATE.md updates:
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations for planning files, log "Skipping planning docs commit (commit_docs: false)"
**If `COMMIT_PLANNING_DOCS=true` (default):**
**1. Stage execution artifacts:** **1. Stage execution artifacts:**
```bash ```bash

View File

@@ -450,6 +450,11 @@ PHASE_DIR=$(ls -d .planning/phases/${PADDED_PHASE}-* .planning/phases/${PHASE}-*
# Read CONTEXT.md if exists (from /gsd:discuss-phase) # Read CONTEXT.md if exists (from /gsd:discuss-phase)
cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null
# Check if planning docs should be committed (default: true)
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
# Auto-detect gitignored (overrides config)
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
``` ```
**If CONTEXT.md exists**, it contains user decisions that MUST constrain your research: **If CONTEXT.md exists**, it contains user decisions that MUST constrain your research:
@@ -526,6 +531,10 @@ Where `PHASE_DIR` is the full path (e.g., `.planning/phases/01-foundation`)
## Step 6: Commit Research ## Step 6: Commit Research
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations, log "Skipping planning docs commit (commit_docs: false)"
**If `COMMIT_PLANNING_DOCS=true` (default):**
```bash ```bash
git add "${PHASE_DIR}/${PADDED_PHASE}-RESEARCH.md" git add "${PHASE_DIR}/${PADDED_PHASE}-RESEARCH.md"
git commit -m "docs(${PHASE}): research phase domain git commit -m "docs(${PHASE}): research phase domain

View File

@@ -953,6 +953,10 @@ After making edits, self-check:
### Step 6: Commit Revised Plans ### Step 6: Commit Revised Plans
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations, log "Skipping planning docs commit (commit_docs: false)"
**If `COMMIT_PLANNING_DOCS=true` (default):**
```bash ```bash
git add .planning/phases/${PHASE}-*/${PHASE}-*-PLAN.md git add .planning/phases/${PHASE}-*/${PHASE}-*-PLAN.md
git commit -m "fix(${PHASE}): revise plans based on checker feedback" git commit -m "fix(${PHASE}): revise plans based on checker feedback"
@@ -998,6 +1002,17 @@ Read `.planning/STATE.md` and parse:
- Blockers/concerns (things this phase may address) - Blockers/concerns (things this phase may address)
If STATE.md missing but .planning/ exists, offer to reconstruct or continue without. If STATE.md missing but .planning/ exists, offer to reconstruct or continue without.
**Load planning config:**
```bash
# Check if planning docs should be committed (default: true)
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
# Auto-detect gitignored (overrides config)
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
Store `COMMIT_PLANNING_DOCS` for use in git operations.
</step> </step>
<step name="load_codebase_context"> <step name="load_codebase_context">
@@ -1209,6 +1224,10 @@ Update ROADMAP.md to finalize phase placeholders created by add-phase or insert-
<step name="git_commit"> <step name="git_commit">
Commit phase plan(s) and updated roadmap: Commit phase plan(s) and updated roadmap:
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations, log "Skipping planning docs commit (commit_docs: false)"
**If `COMMIT_PLANNING_DOCS=true` (default):**
```bash ```bash
git add .planning/phases/${PHASE}-*/${PHASE}-*-PLAN.md .planning/ROADMAP.md git add .planning/phases/${PHASE}-*/${PHASE}-*-PLAN.md .planning/ROADMAP.md
git commit -m "docs(${PHASE}): create phase plan git commit -m "docs(${PHASE}): create phase plan

View File

@@ -48,6 +48,11 @@ cat .planning/research/STACK.md
cat .planning/research/FEATURES.md cat .planning/research/FEATURES.md
cat .planning/research/ARCHITECTURE.md cat .planning/research/ARCHITECTURE.md
cat .planning/research/PITFALLS.md cat .planning/research/PITFALLS.md
# Check if planning docs should be committed (default: true)
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
# Auto-detect gitignored (overrides config)
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
``` ```
Parse each file to extract: Parse each file to extract:
@@ -125,6 +130,10 @@ Write to `.planning/research/SUMMARY.md`
The 4 parallel researcher agents write files but do NOT commit. You commit everything together. The 4 parallel researcher agents write files but do NOT commit. You commit everything together.
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations, log "Skipping planning docs commit (commit_docs: false)"
**If `COMMIT_PLANNING_DOCS=true` (default):**
```bash ```bash
git add .planning/research/ git add .planning/research/
git commit -m "docs: complete project research git commit -m "docs: complete project research

View File

@@ -126,6 +126,17 @@ If `.planning/STATE.md` exists:
<step name="git_commit"> <step name="git_commit">
Commit the todo and any updated state: Commit the todo and any updated state:
**Check planning config:**
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations, log "Todo saved (not committed - commit_docs: false)"
**If `COMMIT_PLANNING_DOCS=true` (default):**
```bash ```bash
git add .planning/todos/pending/[filename] git add .planning/todos/pending/[filename]
[ -f .planning/STATE.md ] && git add .planning/STATE.md [ -f .planning/STATE.md ] && git add .planning/STATE.md

View File

@@ -177,6 +177,17 @@ Update STATE.md "### Pending Todos" section if exists.
<step name="git_commit"> <step name="git_commit">
If todo was moved to done/, commit the change: If todo was moved to done/, commit the change:
**Check planning config:**
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations, log "Todo moved (not committed - commit_docs: false)"
**If `COMMIT_PLANNING_DOCS=true` (default):**
```bash ```bash
git add .planning/todos/done/[filename] git add .planning/todos/done/[filename]
git rm --cached .planning/todos/pending/[filename] 2>/dev/null || true git rm --cached .planning/todos/pending/[filename] 2>/dev/null || true

View File

@@ -99,7 +99,9 @@ Phase: $ARGUMENTS
- Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line - Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line
10. **Commit phase completion** 10. **Commit phase completion**
Bundle all phase metadata updates in one commit: Check `COMMIT_PLANNING_DOCS` from config.json (default: true).
If false: Skip git operations for .planning/ files.
If true: Bundle all phase metadata updates in one commit:
- Stage: `git add .planning/ROADMAP.md .planning/STATE.md` - Stage: `git add .planning/ROADMAP.md .planning/STATE.md`
- Stage REQUIREMENTS.md if updated: `git add .planning/REQUIREMENTS.md` - Stage REQUIREMENTS.md if updated: `git add .planning/REQUIREMENTS.md`
- Commit: `docs({phase}): complete {phase-name} phase` - Commit: `docs({phase}): complete {phase-name} phase`

View File

@@ -337,6 +337,33 @@ Set during `/gsd:new-project`:
Change anytime by editing `.planning/config.json` Change anytime by editing `.planning/config.json`
## Planning Configuration
Configure how planning artifacts are managed in `.planning/config.json`:
**`planning.commit_docs`** (default: `true`)
- `true`: Planning artifacts committed to git (standard workflow)
- `false`: Planning artifacts kept local-only, not committed
When `commit_docs: false`:
- Add `.planning/` to your `.gitignore`
- Useful for OSS contributions, client projects, or keeping planning private
- All planning files still work normally, just not tracked in git
**`planning.search_gitignored`** (default: `false`)
- `true`: Add `--no-ignore` to broad ripgrep searches
- Only needed when `.planning/` is gitignored and you want project-wide searches to include it
Example config:
```json
{
"planning": {
"commit_docs": false,
"search_gitignored": true
}
}
```
## Common Workflows ## Common Workflows
**Starting a new project:** **Starting a new project:**

View File

@@ -8,37 +8,31 @@ allowed-tools:
- Bash - Bash
- Task - Task
- AskUserQuestion - AskUserQuestion
- Glob
--- ---
<objective> <objective>
Start a new milestone through unified flow: questioning → research (optional) → requirements → roadmap. Start a new milestone through unified flow: questioning → research (optional) → requirements → roadmap.
This is the brownfield equivalent of new-project. The project exists, PROJECT.md has history. This command gathers "what's next" and takes you through the full cycle. This is the brownfield equivalent of new-project. The project exists, PROJECT.md has history. This command gathers "what's next", updates PROJECT.md, then continues through the full requirements → roadmap cycle.
**Creates/Updates:** **Creates/Updates:**
- `.planning/PROJECT.md` — updated with new milestone goals - `.planning/PROJECT.md` — updated with new milestone goals
- `.planning/research/` — domain research (optional) - `.planning/research/` — domain research (optional, focuses on NEW features)
- `.planning/REQUIREMENTS.md` — scoped requirements - `.planning/REQUIREMENTS.md` — scoped requirements for this milestone
- `.planning/ROADMAP.md` — phase structure - `.planning/ROADMAP.md` — phase structure (continues numbering)
- `.planning/STATE.md` — updated project memory - `.planning/STATE.md` — reset for new milestone
**After this command:** Run `/gsd:plan-phase [N]` to start execution. **After this command:** Run `/gsd:plan-phase [N]` to start execution.
</objective> </objective>
<execution_context> <execution_context>
@~/.claude/get-shit-done/references/questioning.md @~/.claude/get-shit-done/references/questioning.md
@~/.claude/get-shit-done/references/ui-brand.md @~/.claude/get-shit-done/references/ui-brand.md
@~/.claude/get-shit-done/templates/project.md @~/.claude/get-shit-done/templates/project.md
@~/.claude/get-shit-done/templates/requirements.md @~/.claude/get-shit-done/templates/requirements.md
</execution_context> </execution_context>
<context> <context>
Milestone name: $ARGUMENTS (optional - will prompt if not provided) Milestone name: $ARGUMENTS (optional - will prompt if not provided)
**Load project context:** **Load project context:**
@@ -47,133 +41,40 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
@.planning/MILESTONES.md @.planning/MILESTONES.md
@.planning/config.json @.planning/config.json
**Load milestone context (if exists, from /gsd:discuss-milestone):**
@.planning/MILESTONE-CONTEXT.md
</context> </context>
<process> <process>
## Phase 1: Validate ## Phase 1: Load Context
**MANDATORY FIRST STEP — Execute these checks before ANY user interaction:** - Read PROJECT.md (existing project, Validated requirements, decisions)
- Read MILESTONES.md (what shipped previously)
- Read STATE.md (pending todos, blockers)
- Check for MILESTONE-CONTEXT.md (from /gsd:discuss-milestone)
1. **Verify project exists:** ## Phase 2: Gather Milestone Goals
```bash
[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md. Run /gsd:new-project first."; exit 1; }
```
2. **Check for active milestone (ROADMAP.md exists):** **If MILESTONE-CONTEXT.md exists:**
```bash - Use features and scope from discuss-milestone
[ -f .planning/ROADMAP.md ] && echo "ACTIVE_MILESTONE" || echo "READY_FOR_NEW" - Present summary for confirmation
```
**If ACTIVE_MILESTONE:** **If no context file:**
Use AskUserQuestion: - Present what shipped in last milestone
- header: "Active Milestone" - Ask: "What do you want to build next?"
- question: "A milestone is in progress. What would you like to do?" - Use AskUserQuestion to explore features
- options: - Probe for priorities, constraints, scope
- "Complete current first" — Run /gsd:complete-milestone
- "Continue anyway" — Start new milestone (will archive current)
If "Complete current first": Exit with routing to `/gsd:complete-milestone` ## Phase 3: Determine Milestone Version
If "Continue anyway": Continue to Phase 2
3. **Load previous milestone context:** - Parse last version from MILESTONES.md
```bash - Suggest next version (v1.0 → v1.1, or v2.0 for major)
cat .planning/MILESTONES.md 2>/dev/null || echo "NO_MILESTONES" - Confirm with user
cat .planning/STATE.md
```
## Phase 2: Present Context ## Phase 4: Update PROJECT.md
**Display stage banner:** Add/update these sections:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► NEW MILESTONE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
**Present what shipped:**
```
Last milestone: v[X.Y] [Name] (shipped [DATE])
Key accomplishments:
- [From MILESTONES.md]
- [From MILESTONES.md]
- [From MILESTONES.md]
Validated requirements:
- [From PROJECT.md Validated section]
Pending todos:
- [From STATE.md if any]
```
## Phase 3: Deep Questioning
**Display stage banner:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► QUESTIONING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
**Open the conversation:**
Ask inline (freeform, NOT AskUserQuestion):
"What do you want to build next?"
Wait for their response. This gives you the context needed to ask intelligent follow-up questions.
**Follow the thread:**
Based on what they said, ask follow-up questions that dig into their response. Use AskUserQuestion with options that probe what they mentioned — interpretations, clarifications, concrete examples.
Keep following threads. Each answer opens new threads to explore. Ask about:
- What excited them
- What problem sparked this
- What they mean by vague terms
- What it would actually look like
- What's already decided
Consult `questioning.md` for techniques:
- Challenge vagueness
- Make abstract concrete
- Surface assumptions
- Find edges
- Reveal motivation
**Decision gate:**
When you could update PROJECT.md with clear new goals, use AskUserQuestion:
- header: "Ready?"
- question: "I think I understand what you're after. Ready to update PROJECT.md?"
- options:
- "Update PROJECT.md" — Let's move forward
- "Keep exploring" — I want to share more / ask me more
If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally.
Loop until "Update PROJECT.md" selected.
## Phase 4: Determine Milestone Version
Parse last version from MILESTONES.md and suggest next:
Use AskUserQuestion:
- header: "Version"
- question: "What version is this milestone?"
- options:
- "v[X.Y+0.1] (patch)" — Minor update: [suggested name]
- "v[X+1].0 (major)" — Major release
- "Custom" — I'll specify
## Phase 5: Update PROJECT.md
Update `.planning/PROJECT.md` with new milestone section:
```markdown ```markdown
## Current Milestone: v[X.Y] [Name] ## Current Milestone: v[X.Y] [Name]
@@ -186,30 +87,49 @@ Update `.planning/PROJECT.md` with new milestone section:
- [Feature 3] - [Feature 3]
``` ```
Update Active requirements section with new goals (keep Validated section intact). Update Active requirements section with new goals.
Update "Last updated" footer. Update "Last updated" footer.
**Commit PROJECT.md:** ## Phase 5: Update STATE.md
```bash ```markdown
git add .planning/PROJECT.md ## Current Position
git commit -m "$(cat <<'EOF'
docs: start milestone v[X.Y] [Name]
[One-liner describing milestone focus] Phase: Not started (defining requirements)
EOF Plan: —
)" Status: Defining requirements
Last activity: [today] — Milestone v[X.Y] started
``` ```
## Phase 6: Research Decision Keep Accumulated Context section (decisions, blockers) from previous milestone.
## Phase 6: Cleanup and Commit
Delete MILESTONE-CONTEXT.md if exists (consumed).
Check planning config:
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
If `COMMIT_PLANNING_DOCS=false`: Skip git operations
If `COMMIT_PLANNING_DOCS=true` (default):
```bash
git add .planning/PROJECT.md .planning/STATE.md
git commit -m "docs: start milestone v[X.Y] [Name]"
```
## Phase 7: Research Decision
Use AskUserQuestion: Use AskUserQuestion:
- header: "Research" - header: "Research"
- question: "Research the domain ecosystem before defining requirements?" - question: "Research the domain ecosystem for new features before defining requirements?"
- options: - options:
- "Research first (Recommended)" — Discover patterns, expected features, architecture - "Research first (Recommended)" — Discover patterns, expected features, architecture for NEW capabilities
- "Skip research" — I know this domain well, go straight to requirements - "Skip research" — I know what I need, go straight to requirements
**If "Research first":** **If "Research first":**
@@ -219,7 +139,7 @@ Display stage banner:
GSD ► RESEARCHING GSD ► RESEARCHING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Researching [domain] ecosystem... Researching [new features] ecosystem...
``` ```
Create research directory: Create research directory:
@@ -227,46 +147,53 @@ Create research directory:
mkdir -p .planning/research mkdir -p .planning/research
``` ```
**Milestone context is "subsequent"** — Research focuses on new features, not re-researching validated requirements.
Display spawning indicator: Display spawning indicator:
``` ```
◆ Spawning 4 researchers in parallel... ◆ Spawning 4 researchers in parallel...
→ Stack research → Stack research (for new features)
→ Features research → Features research
→ Architecture research → Architecture research (integration)
→ Pitfalls research → Pitfalls research
``` ```
Spawn 4 parallel gsd-project-researcher agents with context: Spawn 4 parallel gsd-project-researcher agents with milestone-aware context:
``` ```
Task(prompt=" Task(prompt="
<research_type> <research_type>
Project Research — Stack dimension for [domain]. Project Research — Stack dimension for [new features].
</research_type> </research_type>
<milestone_context> <milestone_context>
Subsequent milestone (v[X.Y]). SUBSEQUENT MILESTONE — Adding [target features] to existing app.
Research what's needed to add [target features] to an existing [domain] app. Don't re-research the existing system. Existing validated capabilities (DO NOT re-research):
[List from PROJECT.md Validated requirements]
Focus ONLY on what's needed for the NEW features.
</milestone_context> </milestone_context>
<question> <question>
What's needed to add [target features] to [domain]? What stack additions/changes are needed for [new features]?
</question> </question>
<project_context> <project_context>
[PROJECT.md summary - core value, validated requirements, new goals] [PROJECT.md summary - current state, new milestone goals]
</project_context> </project_context>
<downstream_consumer> <downstream_consumer>
Your STACK.md feeds into roadmap creation. Be prescriptive: Your STACK.md feeds into roadmap creation. Be prescriptive:
- Specific libraries with versions - Specific libraries with versions for NEW capabilities
- Clear rationale for each choice - Integration points with existing stack
- What NOT to use and why - What NOT to add and why
</downstream_consumer> </downstream_consumer>
<quality_gate>
- [ ] Versions are current (verify with Context7/official docs, not training data)
- [ ] Rationale explains WHY, not just WHAT
- [ ] Integration with existing stack considered
</quality_gate>
<output> <output>
Write to: .planning/research/STACK.md Write to: .planning/research/STACK.md
Use template: ~/.claude/get-shit-done/templates/research-project/STACK.md Use template: ~/.claude/get-shit-done/templates/research-project/STACK.md
@@ -275,30 +202,39 @@ Use template: ~/.claude/get-shit-done/templates/research-project/STACK.md
Task(prompt=" Task(prompt="
<research_type> <research_type>
Project Research — Features dimension for [domain]. Project Research — Features dimension for [new features].
</research_type> </research_type>
<milestone_context> <milestone_context>
Subsequent milestone (v[X.Y]). SUBSEQUENT MILESTONE — Adding [target features] to existing app.
How do [target features] typically work? What's expected behavior? Existing features (already built):
[List from PROJECT.md Validated requirements]
Focus on how [new features] typically work, expected behavior.
</milestone_context> </milestone_context>
<question> <question>
What features are expected for [target features]? How do [target features] typically work? What's expected behavior?
</question> </question>
<project_context> <project_context>
[PROJECT.md summary] [PROJECT.md summary - new milestone goals]
</project_context> </project_context>
<downstream_consumer> <downstream_consumer>
Your FEATURES.md feeds into requirements definition. Categorize clearly: Your FEATURES.md feeds into requirements definition. Categorize clearly:
- Table stakes (must have) - Table stakes (must have for these features)
- Differentiators (competitive advantage) - Differentiators (competitive advantage)
- Anti-features (things to deliberately NOT build) - Anti-features (things to deliberately NOT build)
</downstream_consumer> </downstream_consumer>
<quality_gate>
- [ ] Categories are clear (table stakes vs differentiators vs anti-features)
- [ ] Complexity noted for each feature
- [ ] Dependencies on existing features identified
</quality_gate>
<output> <output>
Write to: .planning/research/FEATURES.md Write to: .planning/research/FEATURES.md
Use template: ~/.claude/get-shit-done/templates/research-project/FEATURES.md Use template: ~/.claude/get-shit-done/templates/research-project/FEATURES.md
@@ -307,30 +243,40 @@ Use template: ~/.claude/get-shit-done/templates/research-project/FEATURES.md
Task(prompt=" Task(prompt="
<research_type> <research_type>
Project Research — Architecture dimension for [domain]. Project Research — Architecture dimension for [new features].
</research_type> </research_type>
<milestone_context> <milestone_context>
Subsequent milestone (v[X.Y]). SUBSEQUENT MILESTONE — Adding [target features] to existing app.
How do [target features] integrate with existing [domain] architecture? Existing architecture:
[Summary from PROJECT.md or codebase map]
Focus on how [new features] integrate with existing architecture.
</milestone_context> </milestone_context>
<question> <question>
How should [target features] integrate with the existing system? How do [target features] integrate with existing [domain] architecture?
</question> </question>
<project_context> <project_context>
[PROJECT.md summary] [PROJECT.md summary - current architecture, new features]
</project_context> </project_context>
<downstream_consumer> <downstream_consumer>
Your ARCHITECTURE.md informs phase structure in roadmap. Include: Your ARCHITECTURE.md informs phase structure in roadmap. Include:
- Component boundaries (what talks to what) - Integration points with existing components
- Data flow (how information moves) - New components needed
- Suggested build order (dependencies between components) - Data flow changes
- Suggested build order
</downstream_consumer> </downstream_consumer>
<quality_gate>
- [ ] Integration points clearly identified
- [ ] New vs modified components explicit
- [ ] Build order considers existing dependencies
</quality_gate>
<output> <output>
Write to: .planning/research/ARCHITECTURE.md Write to: .planning/research/ARCHITECTURE.md
Use template: ~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md Use template: ~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md
@@ -339,21 +285,21 @@ Use template: ~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md
Task(prompt=" Task(prompt="
<research_type> <research_type>
Project Research — Pitfalls dimension for [domain]. Project Research — Pitfalls dimension for [new features].
</research_type> </research_type>
<milestone_context> <milestone_context>
Subsequent milestone (v[X.Y]). SUBSEQUENT MILESTONE — Adding [target features] to existing app.
What are common mistakes when adding [target features] to [domain]? Focus on common mistakes when ADDING these features to an existing system.
</milestone_context> </milestone_context>
<question> <question>
What pitfalls should we avoid when adding [target features]? What are common mistakes when adding [target features] to [domain]?
</question> </question>
<project_context> <project_context>
[PROJECT.md summary] [PROJECT.md summary - current state, new features]
</project_context> </project_context>
<downstream_consumer> <downstream_consumer>
@@ -363,6 +309,12 @@ Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
- Which phase should address it - Which phase should address it
</downstream_consumer> </downstream_consumer>
<quality_gate>
- [ ] Pitfalls are specific to adding these features (not generic)
- [ ] Integration pitfalls with existing system covered
- [ ] Prevention strategies are actionable
</quality_gate>
<output> <output>
Write to: .planning/research/PITFALLS.md Write to: .planning/research/PITFALLS.md
Use template: ~/.claude/get-shit-done/templates/research-project/PITFALLS.md Use template: ~/.claude/get-shit-done/templates/research-project/PITFALLS.md
@@ -370,7 +322,7 @@ Use template: ~/.claude/get-shit-done/templates/research-project/PITFALLS.md
", subagent_type="gsd-project-researcher", description="Pitfalls research") ", subagent_type="gsd-project-researcher", description="Pitfalls research")
``` ```
After all 4 agents complete, spawn synthesizer: After all 4 agents complete, spawn synthesizer to create SUMMARY.md:
``` ```
Task(prompt=" Task(prompt="
@@ -394,7 +346,7 @@ Commit after writing.
", subagent_type="gsd-research-synthesizer", description="Synthesize research") ", subagent_type="gsd-research-synthesizer", description="Synthesize research")
``` ```
Display research complete: Display research complete banner and key findings:
``` ```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► RESEARCH COMPLETE ✓ GSD ► RESEARCH COMPLETE ✓
@@ -402,16 +354,16 @@ Display research complete:
## Key Findings ## Key Findings
**Stack:** [from SUMMARY.md] **Stack additions:** [from SUMMARY.md]
**Table Stakes:** [from SUMMARY.md] **New feature table stakes:** [from SUMMARY.md]
**Watch Out For:** [from SUMMARY.md] **Watch Out For:** [from SUMMARY.md]
Files: `.planning/research/` Files: `.planning/research/`
``` ```
**If "Skip research":** Continue to Phase 7. **If "Skip research":** Continue to Phase 8.
## Phase 7: Define Requirements ## Phase 8: Define Requirements
Display stage banner: Display stage banner:
``` ```
@@ -424,24 +376,24 @@ Display stage banner:
Read PROJECT.md and extract: Read PROJECT.md and extract:
- Core value (the ONE thing that must work) - Core value (the ONE thing that must work)
- New milestone goals - Current milestone goals
- Validated requirements (what already works) - Validated requirements (what already exists)
- Stated constraints
**If research exists:** Read research/FEATURES.md and extract feature categories. **If research exists:** Read research/FEATURES.md and extract feature categories.
**Present features by category:** **Present features by category:**
``` ```
Here are the features for [milestone focus]: Here are the features for [new capabilities]:
## [Category 1] ## [Category 1]
**Table stakes:** **Table stakes:**
- [Feature] - Feature A
- [Feature] - Feature B
**Differentiators:** **Differentiators:**
- [Feature] - Feature C
- Feature D
**Research notes:** [any relevant notes] **Research notes:** [any relevant notes]
@@ -453,7 +405,7 @@ Here are the features for [milestone focus]:
**If no research:** Gather requirements through conversation instead. **If no research:** Gather requirements through conversation instead.
Ask: "What are the main things users need to be able to do in this milestone?" Ask: "What are the main things users need to be able to do with [new features]?"
For each capability mentioned: For each capability mentioned:
- Ask clarifying questions to make it specific - Ask clarifying questions to make it specific
@@ -470,11 +422,12 @@ For each category, use AskUserQuestion:
- options: - options:
- "[Feature 1]" — [brief description] - "[Feature 1]" — [brief description]
- "[Feature 2]" — [brief description] - "[Feature 2]" — [brief description]
- "None for this milestone" — Defer - "[Feature 3]" — [brief description]
- "None for this milestone" — Defer entire category
Track responses: Track responses:
- Selected features → v1 requirements - Selected features → this milestone's requirements
- Unselected table stakes → v2 (users expect these) - Unselected table stakes → future milestone
- Unselected differentiators → out of scope - Unselected differentiators → out of scope
**Identify gaps:** **Identify gaps:**
@@ -486,38 +439,39 @@ Use AskUserQuestion:
- "No, research covered it" — Proceed - "No, research covered it" — Proceed
- "Yes, let me add some" — Capture additions - "Yes, let me add some" — Capture additions
**Validate core value:**
Cross-check requirements against Core Value from PROJECT.md. If gaps detected, surface them.
**Generate REQUIREMENTS.md:** **Generate REQUIREMENTS.md:**
Create `.planning/REQUIREMENTS.md` with: Create `.planning/REQUIREMENTS.md` with:
- v1 Requirements grouped by category (checkboxes, REQ-IDs) - v1 Requirements for THIS milestone grouped by category (checkboxes, REQ-IDs)
- v2 Requirements (deferred) - Future Requirements (deferred to later milestones)
- Out of Scope (explicit exclusions with reasoning) - Out of Scope (explicit exclusions with reasoning)
- Traceability section (empty, filled by roadmap) - Traceability section (empty, filled by roadmap)
**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02) **REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, NOTIF-02)
Continue numbering from existing requirements if applicable.
**Requirement quality criteria:** **Requirement quality criteria:**
Good requirements are: Good requirements are:
- **Specific and testable:** "User can reset password via email link" (not "Handle password reset") - **Specific and testable:** "User can reset password via email link" (not "Handle password reset")
- **User-centric:** "User can X" (not "System does Y") - **User-centric:** "User can X" (not "System does Y")
- **Atomic:** One capability per requirement - **Atomic:** One capability per requirement (not "User can login and manage profile")
- **Independent:** Minimal dependencies on other requirements - **Independent:** Minimal dependencies on other requirements
**Present full requirements list for confirmation:** **Present full requirements list:**
Show every requirement (not counts) for user confirmation: Show every requirement (not counts) for user confirmation:
``` ```
## v1 Requirements ## Milestone v[X.Y] Requirements
### [Category] ### [Category 1]
- [ ] **[CAT]-01**: [Requirement description] - [ ] **CAT1-01**: User can do X
- [ ] **[CAT]-02**: [Requirement description] - [ ] **CAT1-02**: User can do Y
### [Category 2]
- [ ] **CAT2-01**: User can do Z
[... full list ...] [... full list ...]
@@ -530,18 +484,20 @@ If "adjust": Return to scoping.
**Commit requirements:** **Commit requirements:**
Check planning config (same pattern as Phase 6).
If committing:
```bash ```bash
git add .planning/REQUIREMENTS.md git add .planning/REQUIREMENTS.md
git commit -m "$(cat <<'EOF' git commit -m "$(cat <<'EOF'
docs: define v[X.Y] requirements docs: define milestone v[X.Y] requirements
[X] requirements across [N] categories [X] requirements across [N] categories
[Y] requirements deferred to v2
EOF EOF
)" )"
``` ```
## Phase 8: Create Roadmap ## Phase 9: Create Roadmap
Display stage banner: Display stage banner:
``` ```
@@ -552,15 +508,10 @@ Display stage banner:
◆ Spawning roadmapper... ◆ Spawning roadmapper...
``` ```
**Calculate starting phase number:** **Determine starting phase number:**
```bash Read MILESTONES.md to find the last phase number from previous milestone.
# Find highest existing phase number New phases continue from there (e.g., if v1.0 ended at phase 5, v1.1 starts at phase 6).
ls -d .planning/phases/[0-9]*-* 2>/dev/null | sort -V | tail -1 | grep -oE '[0-9]+' | head -1
```
If phases exist: New phases start at last + 1
If no phases: Start at Phase 1
Spawn gsd-roadmapper agent with context: Spawn gsd-roadmapper agent with context:
@@ -580,20 +531,22 @@ Task(prompt="
**Config:** **Config:**
@.planning/config.json @.planning/config.json
**Starting phase number:** [N] **Previous milestone (for phase numbering):**
@.planning/MILESTONES.md
</planning_context> </planning_context>
<instructions> <instructions>
Create roadmap: Create roadmap for milestone v[X.Y]:
1. Derive phases from requirements (don't impose structure) 1. Start phase numbering from [N] (continues from previous milestone)
2. Map every v1 requirement to exactly one phase 2. Derive phases from THIS MILESTONE's requirements (don't include validated/existing)
3. Derive 2-5 success criteria per phase (observable user behaviors) 3. Map every requirement to exactly one phase
4. Validate 100% coverage 4. Derive 2-5 success criteria per phase (observable user behaviors)
5. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability) 5. Validate 100% coverage of new requirements
6. Return ROADMAP CREATED with summary 6. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
7. Return ROADMAP CREATED with summary
Write files first, then return. Write files first, then return. This ensures artifacts persist even if context is lost.
</instructions> </instructions>
", subagent_type="gsd-roadmapper", description="Create roadmap") ", subagent_type="gsd-roadmapper", description="Create roadmap")
``` ```
@@ -607,9 +560,36 @@ Write files first, then return.
**If `## ROADMAP CREATED`:** **If `## ROADMAP CREATED`:**
Read the created ROADMAP.md and present it inline. Read the created ROADMAP.md and present it nicely inline:
**Ask for approval:** ```
---
## Proposed Roadmap
**[N] phases** | **[X] requirements mapped** | All milestone requirements covered ✓
| # | Phase | Goal | Requirements | Success Criteria |
|---|-------|------|--------------|------------------|
| [N] | [Name] | [Goal] | [REQ-IDs] | [count] |
| [N+1] | [Name] | [Goal] | [REQ-IDs] | [count] |
...
### Phase Details
**Phase [N]: [Name]**
Goal: [goal]
Requirements: [REQ-IDs]
Success criteria:
1. [criterion]
2. [criterion]
[... continue for all phases ...]
---
```
**CRITICAL: Ask for approval before committing:**
Use AskUserQuestion: Use AskUserQuestion:
- header: "Roadmap" - header: "Roadmap"
@@ -623,27 +603,46 @@ Use AskUserQuestion:
**If "Adjust phases":** **If "Adjust phases":**
- Get user's adjustment notes - Get user's adjustment notes
- Re-spawn roadmapper with revision context - Re-spawn roadmapper with revision context:
- Loop until approved ```
Task(prompt="
<revision>
User feedback on roadmap:
[user's notes]
**Commit roadmap:** Current ROADMAP.md: @.planning/ROADMAP.md
Update the roadmap based on feedback. Edit files in place.
Return ROADMAP REVISED with changes made.
</revision>
", subagent_type="gsd-roadmapper", description="Revise roadmap")
```
- Present revised roadmap
- Loop until user approves
**If "Review full file":** Display raw `cat .planning/ROADMAP.md`, then re-ask.
**Commit roadmap (after approval):**
Check planning config (same pattern as Phase 6).
If committing:
```bash ```bash
git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
git commit -m "$(cat <<'EOF' git commit -m "$(cat <<'EOF'
docs: create v[X.Y] roadmap ([N] phases) docs: create milestone v[X.Y] roadmap ([N] phases)
Phases: Phases:
1. [phase-name]: [requirements covered] [N]. [phase-name]: [requirements covered]
2. [phase-name]: [requirements covered] [N+1]. [phase-name]: [requirements covered]
... ...
All v1 requirements mapped to phases. All milestone requirements mapped to phases.
EOF EOF
)" )"
``` ```
## Phase 9: Done ## Phase 10: Done
Present completion with next steps: Present completion with next steps:
@@ -652,10 +651,10 @@ Present completion with next steps:
GSD ► MILESTONE INITIALIZED ✓ GSD ► MILESTONE INITIALIZED ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**v[X.Y] [Name]** **Milestone v[X.Y]: [Name]**
| Artifact | Location | | Artifact | Location |
|----------------|----------------------------- |----------------|-----------------------------|
| Project | `.planning/PROJECT.md` | | Project | `.planning/PROJECT.md` |
| Research | `.planning/research/` | | Research | `.planning/research/` |
| Requirements | `.planning/REQUIREMENTS.md` | | Requirements | `.planning/REQUIREMENTS.md` |
@@ -683,35 +682,20 @@ Present completion with next steps:
</process> </process>
<output>
- `.planning/PROJECT.md` (updated)
- `.planning/research/` (if research selected)
- `STACK.md`
- `FEATURES.md`
- `ARCHITECTURE.md`
- `PITFALLS.md`
- `SUMMARY.md`
- `.planning/REQUIREMENTS.md`
- `.planning/ROADMAP.md`
- `.planning/STATE.md`
</output>
<success_criteria> <success_criteria>
- [ ] PROJECT.md updated with Current Milestone section
- [ ] Project validated (PROJECT.md exists) - [ ] STATE.md reset for new milestone
- [ ] Previous milestone context presented - [ ] MILESTONE-CONTEXT.md consumed and deleted (if existed)
- [ ] Deep questioning completed (threads followed) - [ ] Research completed (if selected) — 4 parallel agents spawned, milestone-aware
- [ ] Milestone version determined - [ ] Requirements gathered (from research or conversation)
- [ ] PROJECT.md updated with new milestone goals → **committed** - [ ] User scoped each category
- [ ] Research completed (if selected) → **committed** - [ ] REQUIREMENTS.md created with REQ-IDs
- [ ] Requirements gathered and scoped - [ ] gsd-roadmapper spawned with phase numbering context
- [ ] REQUIREMENTS.md created with REQ-IDs → **committed** - [ ] Roadmap files written immediately (not draft)
- [ ] gsd-roadmapper spawned with context
- [ ] Roadmap files written immediately
- [ ] User feedback incorporated (if any) - [ ] User feedback incorporated (if any)
- [ ] ROADMAP.md, STATE.md → **committed** - [ ] ROADMAP.md created with phases continuing from previous milestone
- [ ] User knows next step is `/gsd:plan-phase [N]` - [ ] All commits made (if planning docs committed)
- [ ] User knows next step is `/gsd:discuss-phase [N]`
**Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.
</success_criteria> </success_criteria>

View File

@@ -90,6 +90,17 @@ Be specific enough for a fresh Claude to understand immediately.
</step> </step>
<step name="commit"> <step name="commit">
**Check planning config:**
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
**If `COMMIT_PLANNING_DOCS=true` (default):**
```bash ```bash
git add .planning/phases/*/.continue-here.md git add .planning/phases/*/.continue-here.md
git commit -m "wip: [phase-name] paused at task [X]/[Y]" git commit -m "wip: [phase-name] paused at task [X]/[Y]"

View File

@@ -158,6 +158,17 @@ mkdir -p ".planning/phases/{NN}-{name}"
## 8. Commit Roadmap Update ## 8. Commit Roadmap Update
**Check planning config:**
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
**If `COMMIT_PLANNING_DOCS=true` (default):**
```bash ```bash
git add .planning/ROADMAP.md git add .planning/ROADMAP.md
git commit -m "docs(roadmap): add gap closure phases {N}-{M}" git commit -m "docs(roadmap): add gap closure phases {N}-{M}"

View File

@@ -21,6 +21,12 @@ Provides situational awareness before continuing work.
<step name="verify"> <step name="verify">
**Verify planning structure exists:** **Verify planning structure exists:**
Use Bash (not Glob) to check—Glob respects .gitignore but .planning/ is often gitignored:
```bash
test -d .planning && echo "exists" || echo "missing"
```
If no `.planning/` directory: If no `.planning/` directory:
``` ```

View File

@@ -252,6 +252,17 @@ Update any internal references to reflect new numbering.
<step name="commit"> <step name="commit">
Stage and commit the removal: Stage and commit the removal:
**Check planning config:**
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
**If `COMMIT_PLANNING_DOCS=true` (default):**
```bash ```bash
git add .planning/ git add .planning/
git commit -m "chore: remove phase {target} ({original-phase-name})" git commit -m "chore: remove phase {target} ({original-phase-name})"

View File

@@ -0,0 +1,94 @@
<planning_config>
Configuration options for `.planning/` directory behavior.
<config_schema>
```json
"planning": {
"commit_docs": true,
"search_gitignored": false
}
```
| Option | Default | Description |
|--------|---------|-------------|
| `commit_docs` | `true` | Whether to commit planning artifacts to git |
| `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
</config_schema>
<commit_docs_behavior>
**When `commit_docs: true` (default):**
- Planning files committed normally
- SUMMARY.md, STATE.md, ROADMAP.md tracked in git
- Full history of planning decisions preserved
**When `commit_docs: false`:**
- Skip all `git add`/`git commit` for `.planning/` files
- User must add `.planning/` to `.gitignore`
- Useful for: OSS contributions, client projects, keeping planning private
**Checking the config:**
```bash
# Check config.json first
COMMIT_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
# Auto-detect gitignored (overrides config)
git check-ignore -q .planning 2>/dev/null && COMMIT_DOCS=false
```
**Auto-detection:** If `.planning/` is gitignored, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors when users have `.planning/` in `.gitignore`.
**Conditional git operations:**
```bash
if [ "$COMMIT_DOCS" = "true" ]; then
git add .planning/STATE.md
git commit -m "docs: update state"
fi
```
</commit_docs_behavior>
<search_behavior>
**When `search_gitignored: false` (default):**
- Standard rg behavior (respects .gitignore)
- Direct path searches work: `rg "pattern" .planning/` finds files
- Broad searches skip gitignored: `rg "pattern"` skips `.planning/`
**When `search_gitignored: true`:**
- Add `--no-ignore` to broad rg searches that should include `.planning/`
- Only needed when searching entire repo and expecting `.planning/` matches
**Note:** Most GSD operations use direct file reads or explicit paths, which work regardless of gitignore status.
</search_behavior>
<setup_uncommitted_mode>
To use uncommitted mode:
1. **Set config:**
```json
"planning": {
"commit_docs": false,
"search_gitignored": true
}
```
2. **Add to .gitignore:**
```
.planning/
```
3. **Existing tracked files:** If `.planning/` was previously tracked:
```bash
git rm -r --cached .planning/
git commit -m "chore: stop tracking planning docs"
```
</setup_uncommitted_mode>
</planning_config>

View File

@@ -1,6 +1,10 @@
{ {
"mode": "interactive", "mode": "interactive",
"depth": "standard", "depth": "standard",
"planning": {
"commit_docs": true,
"search_gitignored": false
},
"parallelization": { "parallelization": {
"enabled": true, "enabled": true,
"plan_level": true, "plan_level": true,

View File

@@ -620,6 +620,17 @@ git push origin v[X.Y]
Commit milestone completion including archive files and deletions. Commit milestone completion including archive files and deletions.
**Check planning config:**
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
**If `COMMIT_PLANNING_DOCS=true` (default):**
```bash ```bash
# Stage archive files (new) # Stage archive files (new)
git add .planning/milestones/v[X.Y]-ROADMAP.md git add .planning/milestones/v[X.Y]-ROADMAP.md

View File

@@ -156,6 +156,17 @@ For each gap in the Gaps section, add artifacts and missing fields:
Update status in frontmatter to "diagnosed". Update status in frontmatter to "diagnosed".
**Check planning config:**
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
**If `COMMIT_PLANNING_DOCS=true` (default):**
Commit the updated UAT.md: Commit the updated UAT.md:
```bash ```bash
git add ".planning/phases/XX-name/{phase}-UAT.md" git add ".planning/phases/XX-name/{phase}-UAT.md"

View File

@@ -393,6 +393,17 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
<step name="git_commit"> <step name="git_commit">
Commit phase context: Commit phase context:
**Check planning config:**
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
**If `COMMIT_PLANNING_DOCS=true` (default):**
```bash ```bash
git add "${PHASE_DIR}/${PADDED_PHASE}-CONTEXT.md" git add "${PHASE_DIR}/${PADDED_PHASE}-CONTEXT.md"
git commit -m "$(cat <<'EOF' git commit -m "$(cat <<'EOF'

View File

@@ -8,6 +8,7 @@ The orchestrator's job is coordination, not execution. Each subagent loads the f
<required_reading> <required_reading>
Read STATE.md before any operation to load project context. Read STATE.md before any operation to load project context.
Read config.json for planning behavior settings.
</required_reading> </required_reading>
<process> <process>
@@ -33,6 +34,17 @@ Options:
``` ```
**If .planning/ doesn't exist:** Error - project not initialized. **If .planning/ doesn't exist:** Error - project not initialized.
**Load planning config:**
```bash
# Check if planning docs should be committed (default: true)
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
# Auto-detect gitignored (overrides config)
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
Store `COMMIT_PLANNING_DOCS` for use in git operations.
</step> </step>
<step name="validate_phase"> <step name="validate_phase">
@@ -456,6 +468,17 @@ Update ROADMAP.md to reflect phase completion:
# Update status # Update status
``` ```
**Check planning config:**
If `COMMIT_PLANNING_DOCS=false` (set in load_project_state):
- Skip all git operations for .planning/ files
- Planning docs exist locally but are gitignored
- Log: "Skipping planning docs commit (commit_docs: false)"
- Proceed to offer_next step
If `COMMIT_PLANNING_DOCS=true` (default):
- Continue with git operations below
Commit phase completion (roadmap, state, verification): Commit phase completion (roadmap, state, verification):
```bash ```bash
git add .planning/ROADMAP.md .planning/STATE.md .planning/phases/{phase_dir}/*-VERIFICATION.md git add .planning/ROADMAP.md .planning/STATE.md .planning/phases/{phase_dir}/*-VERIFICATION.md

View File

@@ -4,6 +4,7 @@ Execute a phase prompt (PLAN.md) and create the outcome summary (SUMMARY.md).
<required_reading> <required_reading>
Read STATE.md before any operation to load project context. Read STATE.md before any operation to load project context.
Read config.json for planning behavior settings.
@~/.claude/get-shit-done/references/git-integration.md @~/.claude/get-shit-done/references/git-integration.md
</required_reading> </required_reading>
@@ -36,6 +37,17 @@ Options:
**If .planning/ doesn't exist:** Error - project not initialized. **If .planning/ doesn't exist:** Error - project not initialized.
This ensures every execution has full project context. This ensures every execution has full project context.
**Load planning config:**
```bash
# Check if planning docs should be committed (default: true)
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
# Auto-detect gitignored (overrides config)
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
Store `COMMIT_PLANNING_DOCS` for use in git operations.
</step> </step>
<step name="identify_plan"> <step name="identify_plan">
@@ -1513,6 +1525,17 @@ Commit execution metadata (SUMMARY + STATE + ROADMAP):
**Note:** All task code has already been committed during execution (one commit per task). **Note:** All task code has already been committed during execution (one commit per task).
PLAN.md was already committed during plan-phase. This final commit captures execution results only. PLAN.md was already committed during plan-phase. This final commit captures execution results only.
**Check planning config:**
If `COMMIT_PLANNING_DOCS=false` (set in load_project_state):
- Skip all git operations for .planning/ files
- Planning docs exist locally but are gitignored
- Log: "Skipping planning docs commit (commit_docs: false)"
- Proceed to next step
If `COMMIT_PLANNING_DOCS=true` (default):
- Continue with git operations below
**1. Stage execution artifacts:** **1. Stage execution artifacts:**
```bash ```bash

View File

@@ -211,6 +211,17 @@ Continue to commit_codebase_map.
<step name="commit_codebase_map"> <step name="commit_codebase_map">
Commit the codebase map: Commit the codebase map:
**Check planning config:**
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
**If `COMMIT_PLANNING_DOCS=true` (default):**
```bash ```bash
git add .planning/codebase/*.md git add .planning/codebase/*.md
git commit -m "$(cat <<'EOF' git commit -m "$(cat <<'EOF'

View File

@@ -285,6 +285,17 @@ Clear Current Test section:
[testing complete] [testing complete]
``` ```
**Check planning config:**
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
**If `COMMIT_PLANNING_DOCS=true` (default):**
Commit the UAT file: Commit the UAT file:
```bash ```bash
git add ".planning/phases/XX-name/{phase}-UAT.md" git add ".planning/phases/XX-name/{phase}-UAT.md"