Workflow Agents - Get Shit Done

GSD spawns specialized agents during planning and execution. These agents improve quality but add tokens and time. Configure them based on project needs.

Agent Overview

Agent	Stage	Purpose	Default
Researcher	Planning	Investigates domain/stack before planning	`true`
Plan Checker	Planning	Verifies plans achieve phase goals	`true`
Verifier	Execution	Confirms must-haves after execution	`true`
Nyquist Validation	Planning	Maps requirements to automated tests	`true`
Auto-Advance	Pipeline	Chains discuss → plan → execute	`false`

Configuration

Set in .planning/config.json under workflow:

{
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "auto_advance": false,
    "nyquist_validation": true
  }
}

Update via:

/gsd:settings

Research Agent

What It Does

Spawns 4 parallel researchers during plan-phase:

Stack Researcher — Investigates technologies, libraries, APIs
Features Researcher — Explores similar features, UX patterns
Architecture Researcher — Studies implementation approaches
Pitfalls Researcher — Identifies common mistakes, edge cases

Output: {phase}-RESEARCH.md

When to Enable

Complex or unfamiliar domain
Using new technologies
Need best practices guidance
Want comprehensive context

When to Disable

Familiar domain
Simple CRUD work
Iterating on existing patterns
Conserving tokens

Token Impact

Adds ~4x researcher contexts (parallel) to each plan-phase. Model used: Depends on profile

Quality: Opus (high cost)
Balanced: Sonnet (medium cost)
Budget: Haiku (low cost)

Command Override

/gsd:plan-phase --skip-research  # Force skip
/gsd:plan-phase --research       # Force enable

Plan Checker Agent

What It Does

Verifies plans achieve phase goals before execution. Checks 8 dimensions:

Completeness — All requirements addressed
Atomicity — Tasks are small enough (2-3 per plan)
Dependencies — Proper sequencing and wave allocation
Verifiability — Clear success criteria
XML Structure — Proper formatting for executor
File Coverage — All necessary files identified
Edge Cases — Error handling included
Validation — Automated test coverage (if Nyquist enabled)

Loops up to 3 times until plans pass all checks. Output: Annotations in plan review, iteration feedback

When to Enable

Complex phases
Critical work
Want high-quality plans
Unfamiliar domain

When to Disable

Simple phases
Speed is critical
Trust initial plans
Budget constraints

Token Impact

Adds 1-3 plan-checker contexts per plan-phase (iterative). Model used: Depends on profile

Quality: Sonnet
Balanced: Sonnet
Budget: Haiku

Command Override

/gsd:plan-phase --skip-verify  # Force skip

Verifier Agent

What It Does

Confirms must-haves were delivered after execute-phase. Checks:

Requirements Coverage — All phase requirements addressed
Files Created — Planned files exist
Tests Pass — Automated tests succeed
No Stubs — Implementation complete, not placeholder
Integration — Components work together

Output: {phase}-VERIFICATION.md

Verification Results

Status	Meaning	Next Step
PASS	All must-haves delivered	Proceed to next phase
PARTIAL	Some issues found	Review via `/gsd:verify-work`
FAIL	Critical gaps	Fix and re-execute

When to Enable

Complex phases
Critical deliverables
Want automated validation
Reduce manual testing burden

When to Disable

Simple phases
Manual UAT preferred
Budget constraints
Obvious success criteria

Token Impact

Adds 1 verifier context per execute-phase. Model used: Depends on profile

Quality: Sonnet
Balanced: Sonnet
Budget: Haiku

Manual Verification Alternative

Disable verifier and use manual UAT instead:

/gsd:verify-work [N]

Walks through testable deliverables with auto-diagnosis on failures.

Auto-Advance

What It Does

Chains stages automatically without manual /clear and command re-entry:

discuss-phase → plan-phase → execute-phase

Each stage still runs in a subagent with fresh context (same isolation as manual workflow).

When to Enable

Running known phases in batch
Trust the pipeline
Hands-off execution
Multiple phases queued

When to Disable

Want to review between stages
Complex phases needing oversight
First time using GSD
Prefer manual control (default)

How It Works

Complete discuss-phase → auto-spawn plan-phase
Complete plan-phase → auto-spawn execute-phase
Complete execute-phase → stop (manual decision for next phase)

Auto-advance does NOT chain phases together (e.g., phase 1 → phase 2). It only chains stages within a single phase.

Configuration

{
  "workflow": {
    "auto_advance": true
  }
}

Or via /gsd:settings → “Auto-advance pipeline?”

Token Impact

No additional tokens (same subagents as manual workflow).

Nyquist Validation

What It Does

Maps requirements to automated test coverage during plan-phase. Ensures feedback mechanism exists before code is written. Process:

Detect existing test infrastructure (Jest, Pytest, RSpec, etc.)
Map each requirement to specific test command
Identify test scaffolding needed (Wave 0 tasks)
Enforce automated verify commands in plans

Output: {phase}-VALIDATION.md — the feedback contract

Why “Nyquist”?

Named after the Nyquist sampling theorem: to accurately capture a signal, you must sample at twice its frequency. In GSD: To verify implementation quality, you must validate at a higher frequency than you commit. Automated tests provide that rapid feedback loop.

When to Enable

Production code
Complex logic
Want test coverage enforced
Building for maintainability
Default for most work

When to Disable

Rapid prototyping
Spike work
UI-only phases
Test infrastructure doesn’t exist yet
Budget constraints

Token Impact

Adds validation research during plan-phase (minor increase). Model used: Same as phase researcher (see profiles)

Plan-Check Integration

When Nyquist is enabled, plan-checker enforces an 8th dimension: 8. Validation — Each task must have automated verify command Plans lacking test coverage will not be approved until:

Tests are added to Wave 0 (scaffolding), OR
Requirement is explicitly marked manual-only

Retroactive Validation

For phases executed without Nyquist, retroactively audit coverage:

/gsd:validate-phase [N]

Scans implementation, maps tests, fills gaps.

Configuration

{
  "workflow": {
    "nyquist_validation": true
  }
}

Or via /gsd:settings → “Enable Nyquist Validation?”

Performance Profiles

Combine agent settings for different scenarios:

Maximum Quality

{
  "model_profile": "quality",
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "nyquist_validation": true
  }
}

Use for: Critical work, complex domains, production systems.

Balanced (Default)

{
  "model_profile": "balanced",
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "nyquist_validation": true
  }
}

Use for: Most development work.

Speed Mode

{
  "model_profile": "budget",
  "workflow": {
    "research": false,
    "plan_check": false,
    "verifier": false,
    "nyquist_validation": false
  }
}

Use for: Prototypes, iteration, familiar domains.

Batch Mode

{
  "model_profile": "balanced",
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "auto_advance": true
  }
}

Use for: Running known phases unattended.

Agent Coordination Architecture

Planning Stage

/gsd:plan-phase N
      │
      ├─> Phase Researcher (x4 parallel)
      │     └─> RESEARCH.md
      │
      ├─> Nyquist Validator
      │     └─> VALIDATION.md
      │
      ├─> Planner
      │     └─> Draft plans
      │
      └─> Plan Checker (loop 1-3x)
            └─> PLAN files

Execution Stage

/gsd:execute-phase N
      │
      ├─> Wave 1 Executors (parallel)
      ├─> Wave 2 Executors (parallel)
      ├─> Wave N Executors (parallel)
      │
      └─> Verifier
            └─> VERIFICATION.md

Token and Time Estimates

Typical phase with 3 plans:

Configuration	Time	Tokens	Quality
All agents (quality)	20-30 min	~400K	Highest
All agents (balanced)	15-25 min	~200K	High
All agents (budget)	10-20 min	~100K	Good
No agents (budget)	5-10 min	~50K	Acceptable

Estimates vary based on phase complexity, codebase size, and domain familiarity.

Best Practices

Start with Defaults

All agents enabled with balanced profile. Adjust based on experience.

Disable Selectively

Disable agents per-phase via command overrides:

# Simple phase, skip research
/gsd:plan-phase 5 --skip-research

# Trust the plan, skip verification
/gsd:plan-phase 6 --skip-verify

Match Agents to Risk

High-risk phases → all agents enabled. Low-risk phases → disable agents for speed.

Monitor Token Usage

If costs are high, disable research first (biggest impact), then plan-check, then verifier.

Use Auto-Advance for Known Work

Once you trust the pipeline, enable auto-advance for batch execution.

Configuration Schema — Full config.json reference
Model Profiles — Per-agent model breakdown
Commands — Command overrides and workflow

Configuration

File Structure

Resources

​Agent Overview

​Configuration

​Research Agent

​What It Does

​When to Enable

​When to Disable

​Token Impact

​Command Override

​Plan Checker Agent

​What It Does

​When to Enable

​When to Disable

​Token Impact

​Command Override

​Verifier Agent

​What It Does

​Verification Results

​When to Enable

​When to Disable

​Token Impact

​Manual Verification Alternative

​Auto-Advance

​What It Does

​When to Enable

​When to Disable

​How It Works

​Configuration

​Token Impact

​Nyquist Validation

​What It Does

​Why “Nyquist”?

​When to Enable

​When to Disable

​Token Impact

​Plan-Check Integration

​Retroactive Validation

​Configuration

​Performance Profiles

​Maximum Quality

​Balanced (Default)

​Speed Mode

​Batch Mode

​Agent Coordination Architecture

​Planning Stage

​Execution Stage

​Token and Time Estimates

​Best Practices

​Start with Defaults

​Disable Selectively

​Match Agents to Risk

​Monitor Token Usage

​Use Auto-Advance for Known Work

​Related References

Agent Overview

Configuration

Research Agent

What It Does

When to Enable

When to Disable

Token Impact

Command Override

Plan Checker Agent

What It Does

When to Enable

When to Disable

Token Impact

Command Override

Verifier Agent

What It Does

Verification Results

When to Enable

When to Disable

Token Impact

Manual Verification Alternative

Auto-Advance

What It Does

When to Enable

When to Disable

How It Works

Configuration

Token Impact

Nyquist Validation

What It Does

Why “Nyquist”?

When to Enable

When to Disable

Token Impact

Plan-Check Integration

Retroactive Validation

Configuration

Performance Profiles

Maximum Quality

Balanced (Default)

Speed Mode

Batch Mode

Agent Coordination Architecture

Planning Stage

Execution Stage

Token and Time Estimates

Best Practices

Start with Defaults

Disable Selectively

Match Agents to Risk

Monitor Token Usage

Use Auto-Advance for Known Work

Related References