gsd-orchestration
GSD Orchestration
"The complexity is in the system, not in your workflow." — TÂCHES
Philosophy
GSD solves context rot — the quality degradation as Claude fills its context window. Each task runs in fresh context. Plans are atomic. Verification is built-in.
Quick Reference
| Command | Purpose |
|---|---|
gsd init |
New project: questions → research → requirements → roadmap |
gsd discuss [N] |
Capture decisions for phase N (NO CODE) |
gsd plan [N] |
Create atomic task plans for phase N |
gsd execute [N] |
Run tasks with fresh context per task |
gsd verify [N] |
Verify deliverables work as expected |
gsd status |
Current position and next action |
gsd complete [N] |
Archive phase, update state |
Parallel Execution Commands (NEW)
| Command | Purpose |
|---|---|
gsd execute-all |
Execute all phases sequentially (background optional) |
gsd execute-parallel [N] |
Execute phase N with parallel tasks where possible |
gsd execute-overnight |
Full autopilot mode for unattended execution |
gsd check-conflicts [N] |
Analyze PLANs for file conflicts before parallel execution |
gsd status --live |
Live monitoring of running background agents |
Core Workflow
gsd init → gsd discuss 1 → gsd plan 1 → gsd execute 1 → gsd verify 1 → gsd complete 1
↓
gsd discuss 2 → gsd plan 2 → ...
For detailed workflow instructions, see references/WORKFLOW.md.
Project Structure
.gsd/
├── PROJECT.md # Vision, goals, tech stack (always loaded)
├── REQUIREMENTS.md # Scoped v1/v2 requirements
├── ROADMAP.md # All phases with status
├── STATE.md # Current position, blockers, decisions
└── phases/
└── phase-N/
├── CONTEXT.md # Decisions from discuss
├── ARCHITECTURE.md # AI agent architecture (if AI phase)
├── RESEARCH.md # Domain research (optional)
├── PLAN-1.md # Atomic task plan
├── PLAN-2.md # Atomic task plan
└── SUMMARY.md # What was built
Context Engineering Rules
Critical: These rules prevent context rot.
- Fresh context per task - Clear mental state between tasks
- Load only relevant files - Never load all .gsd/ files at once
- Maximum 3 tasks per plan - Keeps execution focused
- Size limits:
- PROJECT.md: ~500 lines max
- Each PLAN.md: ~200 lines max
- RESEARCH.md: ~1000 lines max
For context engineering principles, see references/CONTEXT-ENGINEERING.md.
Configuration
This skill is configured for:
- 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
Command Implementations
gsd init
Context to load: Nothing - fresh start
Process:
- Ask 5 focused questions: project description, core problem, target user, tech stack, success criteria
- Optional: Spawn research subagent for complex domains
- Generate: PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md
Output: "Project initialized. Run gsd discuss 1 to begin."
gsd discuss [N]
Context to load: PROJECT.md, ROADMAP.md (phase N), STATE.md (decisions)
CRITICAL RULE: NO CODE. NO FILE CREATION. Only conversation.
Process:
- Summarize phase goal
- Offer agent-architect for complex phases (see ARCHITECT-INTEGRATION.md)
- Identify gray areas (visual, API, data, CLI decisions)
- Ask clarifying questions until clear
- Generate
.gsd/phases/phase-N/CONTEXT.md
Output format:
## Phase [N] Discussion Complete
### Decisions Made:
- [Decision 1 with reasoning]
- [Decision 2 with reasoning]
### Out of Scope:
- [Deferred item with reason]
### Edge Cases Identified:
- [Edge case 1 and how to handle]
- [Edge case 2 and how to handle]
Ready to plan? Run: `gsd plan [N]`
CONTEXT.md template:
# Phase [N] Context
## Decisions
- **[Topic]**: [Decision] - [Reasoning]
- **[Topic]**: [Decision] - [Reasoning]
## Out of Scope
- [Item] - [Why deferred/rejected]
## Edge Cases
- [Case] → [How to handle]
## Open Questions
- [Question that needs answering during planning]
gsd plan [N]
Context to load:
- 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)
Process:
-
Research (optional): Spawn researcher subagent for complex/unfamiliar domains
-
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
- If ARCHITECTURE.md present (agent-architect was used):
-
Validate: Check plan completeness
Generate: Task plans using XML format.
For XML task templates, see references/XML-TEMPLATES.md.
Output: .gsd/phases/phase-N/PLAN-1.md, PLAN-2.md, etc.
Planning depth (adaptive based on configuration):
- Quick: Minimal specs, basic acceptance criteria
- Standard: Clear descriptions, testable criteria
- Comprehensive: Detailed specs, edge cases, examples
- Adaptive: Adjust based on task complexity
Each PLAN.md should be executable - another Claude instance can implement it without additional context.
gsd execute [N]
For EACH task in phase:
Context to load (fresh per task):
- PROJECT.md (tech stack only - ~50 lines)
- Current PLAN-X.md (full)
- Relevant source files only
Process:
- Announce: "Starting Task [X]: [Name]"
- Execute according to plan
- Self-verify against acceptance criteria
- Commit (if git workflow enabled):
git add -A && git commit -m "type(phase-N): description - Detail 1 - Detail 2 Co-Authored-By: Claude <noreply@anthropic.com>" - Announce: "Task [X] complete - [summary]"
- Clear context
- Next task
Commit types: feat, fix, docs, refactor, test, chore
Between tasks output:
---
✓ Task 1 complete: [one-line summary]
Clearing context for Task 2...
Loading: PROJECT.md (tech), PLAN-2.md, [relevant files]
Starting Task 2: [Name]
---
Important: The "clearing context" announcement is a mental cue to actually reset context. Don't carry forward details from previous tasks.
gsd verify [N]
Context to load:
- ROADMAP.md (phase N goals)
- All PLAN-X.md files for phase
- STATE.md
Process:
- Extract testable deliverables from plans
- For each deliverable:
- Automated: Run test commands (based on configuration)
- Manual: Provide verification instructions
- Document results
- If all pass → suggest
gsd complete [N] - If any fail → identify failing task, suggest fix
Verification based on configuration:
- Automated tests: pytest, jest, npm test, go test, etc.
- Manual checks: curl commands, UI walkthrough, CLI usage
Output:
## Verification Results: Phase [N]
### Automated Tests
[✓ / ✗] Unit tests pass
[✓ / ✗] Integration tests pass
[✓ / ✗] Type checking clean
[✓ / ✗] Linter clean
### Manual Checks
- [ ] Check 1: [specific instruction]
- [ ] Check 2: [specific instruction]
### Overall Status
[PASS / FAIL with summary]
[If PASS]
All verification passed. Run `gsd complete [N]` to finalize.
[If FAIL]
Issues found:
- Task [X]: [specific failure]
Suggested action: Fix and re-verify
gsd status
Context to load: STATE.md only
Output:
# GSD Status
**Project**: [Name]
**Phase**: [N] - [Phase Name]
**Status**: [Not Started / Planning / Executing / Verifying]
## Progress
[■■■□□□□□□□] 30% (3/10 phases)
## Completed Phases
- Phase 1: [Name] ✓
- Phase 2: [Name] ✓
## Current Phase Tasks
- [x] Task 1: [brief description]
- [ ] Task 2: [brief description] ← YOU ARE HERE
- [ ] Task 3: [brief description]
## Next Action
`gsd execute 3` (continue with task 2)
## Recent Decisions
- [Most recent decision from STATE.md]
## Blockers
[None / list of blockers]
gsd complete [N]
Process:
- Generate SUMMARY.md (deliverables, files, decisions, metrics)
- Update STATE.md (mark complete, advance to N+1)
- Update ROADMAP.md (mark requirements done)
- Optional: Git tag if milestone complete
Output: "Phase [N] complete ✓. Run gsd discuss [N+1] for next phase."
Parallel Execution Commands
GSD supports parallel execution using the Fan-Out / Fan-In pattern with automatic dependency detection.
Critical Claude Code Constraints (enforced by the platform):
- 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
For complete documentation, see references/PARALLEL-EXECUTION.md. For detailed command reference, see references/COMMANDS-REFERENCE.md.
Quick Command Summary
| Command | Syntax | Purpose |
|---|---|---|
execute-all |
gsd execute-all [--from N] [--to M] [--background] |
Run all phases sequentially |
execute-parallel |
gsd execute-parallel [N] [--max-agents N] |
Fan-Out/Fan-In parallel execution |
execute-overnight |
gsd execute-overnight [--from N] [--parallel] |
Full autopilot for unattended execution |
check-conflicts |
gsd check-conflicts [N] [--fix] |
Detect file conflicts before parallel |
status --live |
gsd status --live [--interval N] |
Real-time monitoring of background agents |
Overnight Execution Workflow
# Day: Plan all phases
gsd discuss 1 && gsd plan 1
gsd discuss 2 && gsd plan 2
# ... repeat for all phases
# Before sleep: Check conflicts and start
gsd check-conflicts 2 --fix
gsd execute-overnight --from 2 --parallel
# Next morning: Check results
gsd status
Additional Commands
gsd add-phase
Append a new phase to the roadmap interactively.
gsd pause
Save current state for resuming later. Updates STATE.md with pause timestamp and context.
gsd resume
Restore from paused state. Shows what was in progress and suggests next action.
gsd quick [description]
Execute a quick ad-hoc task without full planning workflow. Useful for small fixes.
Subagent Architecture
When spawning subagents, use minimal focused context:
| Subagent | Purpose | Context |
|---|---|---|
| Researcher | Investigate domain | Query + PROJECT.md tech stack |
| Planner | Create task plans | Phase goal + CONTEXT.md |
| Checker | Validate plans | Plan + requirements |
| Executor | Implement tasks | Single PLAN.md + relevant files |
Rule: The orchestrator (main GSD) never does heavy lifting. It spawns, waits, integrates.
Best Practices
- Fresh context per task - Never accumulate across tasks
- No code during discuss - Discuss is for requirements only
- Atomic means atomic - If >15 min, split it
- Verify everything - Even if it "looks right"
- Document decisions - Future Claude instances need this
- Commit per task - Git bisect finds exact failures
- Keep PROJECT.md lean - Details go in REQUIREMENTS or phase docs
- One phase at a time - Complete current before planning next
- Prompts as markdown files - For agent projects, store prompts in
prompts/*.md
For complete command reference, see references/COMMANDS-REFERENCE.md.
When to Use GSD
Use GSD when:
- Projects taking > 2 hours
- Multiple interconnected features
- Need to maintain context across sessions
- Want systematic verification
- Working on production code
Skip GSD when:
- Quick scripts (< 1 hour)
- Exploratory prototyping
- Single-file changes
- Emergency hotfixes
- You already have detailed specs
Integrations
agent-architect Integration
During gsd discuss [N], GSD offers professional architectural design via agent-architect for complex phases. Creates ARCHITECTURE.md with 5-phase design process covering strategy, components, tools, orchestration, and production readiness.
See: references/ARCHITECT-INTEGRATION.md
Domain Skill Integration
GSD auto-detects domain-specific needs (ML/DL, etc.) from PROJECT.md and offers specialized expertise during discuss/plan/execute phases.
See: references/DOMAIN-INTEGRATION.md
File Size Management
To keep context loading efficient:
| File | Target Lines | Max Lines |
|---|---|---|
| PROJECT.md | 200-300 | 500 |
| REQUIREMENTS.md | 500-800 | 1000 |
| ROADMAP.md | 300-400 | 500 |
| STATE.md | 100-150 | 200 |
| PLAN-X.md | 100-150 | 200 |
| CONTEXT.md | 150-200 | 300 |
If files exceed max, refactor or split into reference documents.