"The complexity is in the system, not in your workflow." — TÂCHES

1. Fresh context per task - Clear mental state between tasks
2. Load only relevant files - Never load all .gsd/ files at once
3. Maximum 3 tasks per plan - Keeps execution focused
4. Size limits:
   • PROJECT.md: ~500 lines max
   • Each PLAN.md: ~200 lines max
   • RESEARCH.md: ~1000 lines max

• Project types: Mixed (all types - adaptive based on project)
• Verification: Automated tests + manual checks
• Planning depth: Adaptive (adjust based on complexity)
• Git workflow: Atomic commits per task with conventional format

1. Ask 5 focused questions: project description, core problem, target user, tech stack, success criteria
2. Optional: Spawn research subagent for complex domains
3. Generate: PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md

gsd discuss 1

1. Summarize phase goal
2. Offer agent-architect for complex phases (see ARCHITECT-INTEGRATION.md)
3. Identify gray areas (visual, API, data, CLI decisions)
4. Ask clarifying questions until clear
5. Generate

   .gsd/phases/phase-N/CONTEXT.md

undefined

• [Decision 1 with reasoning]
• [Decision 2 with reasoning]

• [Deferred item with reason]

• [Edge case 1 and how to handle]
• [Edge case 2 and how to handle]

gsd plan [N]

**CONTEXT.md template**:
```markdown

• [Topic]: [Decision] - [Reasoning]
• [Topic]: [Decision] - [Reasoning]

• [Item] - [Why deferred/rejected]

• [Case] → [How to handle]

• [Question that needs answering during planning]

---

• PROJECT.md (tech stack section)
• ROADMAP.md (phase N only)
• CONTEXT.md (if exists)
• ARCHITECTURE.md (if exists from agent-architect) ← Architectural decisions
• Previous phase SUMMARY.md (if exists)

1. Research (optional): Spawn researcher subagent for complex/unfamiliar domains
2. Plan: Break into 2-3 atomic tasks
   • If ARCHITECTURE.md present (agent-architect was used):
     • Use agent definitions (identity + task dispatch templates) → Task for implementing agents
     • Use tool specifications (built-in + custom MCP + external MCP) → Task for tools + MCP setup
     • Use orchestration pattern + guiding skill → Task for orchestration + interaction loop
     • Reference architecture decisions in all plans
     • Instruct prompts to be stored as markdown files in

       prompts/

       directory
   • Standard phases: Break phase into logical atomic tasks
3. Validate: Check plan completeness

.gsd/phases/phase-N/PLAN-1.md

PLAN-2.md

• Quick: Minimal specs, basic acceptance criteria
• Standard: Clear descriptions, testable criteria
• Comprehensive: Detailed specs, edge cases, examples
• Adaptive: Adjust based on task complexity

• PROJECT.md (tech stack only - ~50 lines)
• Current PLAN-X.md (full)
• Relevant source files only

1. Announce: "Starting Task [X]: [Name]"
2. Execute according to plan
3. Self-verify against acceptance criteria
4. Commit (if git workflow enabled):
   bash

   git add -A && git commit -m "type(phase-N): description
   
   - Detail 1
   - Detail 2
   
   Co-Authored-By: Claude <noreply@anthropic.com>"

5. Announce: "Task [X] complete - [summary]"
6. Clear context
7. Next task

---
✓ Task 1 complete: [one-line summary]

Clearing context for Task 2...
Loading: PROJECT.md (tech), PLAN-2.md, [relevant files]

Starting Task 2: [Name]
---

• ROADMAP.md (phase N goals)
• All PLAN-X.md files for phase
• STATE.md

1. Extract testable deliverables from plans
2. For each deliverable:
   • Automated: Run test commands (based on configuration)
   • Manual: Provide verification instructions
3. Document results
4. If all pass → suggest

   gsd complete [N]

5. If any fail → identify failing task, suggest fix

• Automated tests: pytest, jest, npm test, go test, etc.
• Manual checks: curl commands, UI walkthrough, CLI usage

undefined

• Check 1: [specific instruction]
• Check 2: [specific instruction]

gsd complete [N]

• Task [X]: [specific failure] Suggested action: Fix and re-verify

---

• Phase 1: [Name] ✓
• Phase 2: [Name] ✓

• Task 1: [brief description]
• Task 2: [brief description] ← YOU ARE HERE
• Task 3: [brief description]

• [Most recent decision from STATE.md]

1. Generate SUMMARY.md (deliverables, files, decisions, metrics)
2. Update STATE.md (mark complete, advance to N+1)
3. Update ROADMAP.md (mark requirements done)
4. Optional: Git tag if milestone complete

gsd discuss [N+1]

• No MCP tools in background agents - Use built-in tools only (Read, Write, Edit, Bash, Glob, Grep)
• No nested subagents - Orchestrator spawns all agents, agents cannot delegate
• Max ~10 concurrent agents - Batch execution for larger phases

1. Fresh context per task - Never accumulate across tasks
2. No code during discuss - Discuss is for requirements only
3. Atomic means atomic - If >15 min, split it
4. Verify everything - Even if it "looks right"
5. Document decisions - Future Claude instances need this
6. Commit per task - Git bisect finds exact failures
7. Keep PROJECT.md lean - Details go in REQUIREMENTS or phase docs
8. One phase at a time - Complete current before planning next
9. Prompts as markdown files - For agent projects, store prompts in

   prompts/*.md

• Projects taking > 2 hours
• Multiple interconnected features
• Need to maintain context across sessions
• Want systematic verification
• Working on production code

• Quick scripts (< 1 hour)
• Exploratory prototyping
• Single-file changes
• Emergency hotfixes
• You already have detailed specs