/gsd-plan-phase and /gsd-execute-phase) spawn agents automatically at the right point in the phase loop. What you see in your session is the orchestrator’s progress updates; the agents work in parallel in their own isolated context windows.
How fresh-context subagents work
When an orchestrator needs to perform heavy work — researching a domain, writing plans, implementing code — it spawns a subagent with a precisely scoped prompt. That subagent receives:- Its specific agent definition (role, tools, constraints)
- The subset of planning artifacts it needs for its task
- A model assignment based on the workflow profile
RESEARCH.md, a PLAN.md, a SUMMARY.md), and returns a compact result to the orchestrator. The orchestrator’s context never grows with the weight of the subagent’s work — only the result arrives back.
This architecture is why GSD Core can run four researchers in parallel, spawn multiple executors across wave boundaries, and keep the main session lean throughout a long phase.
Agent categories
Researchers
Researchers gather ecosystem knowledge before planning begins. They have web access (WebSearch, WebFetch) and Context7 MCP integration for library documentation. All researchers run in parallel — four instances per invocation, each covering a different dimension of the domain.gsd-phase-researcher
Researches how to implement a specific phase. Runs four parallel instances covering stack, features, architecture, and pitfalls. Produces
RESEARCH.md with a Package Legitimacy Audit table that removes hallucinated or suspicious packages before they reach the planner.gsd-project-researcher
Researches domain ecosystem before roadmap creation during
/gsd-new-project. Produces STACK.md, FEATURES.md, ARCHITECTURE.md, and PITFALLS.md in .planning/research/.gsd-ui-researcher
Produces UI design contracts for frontend phases during
/gsd-ui-phase. Detects your design system state (shadcn, Tailwind, existing tokens) and generates UI-SPEC.md.gsd-domain-researcher
Researches the business domain and real-world evaluation context for AI integration phases. Surfaces expert rubric ingredients, failure modes, and regulatory context for downstream evaluators.
Planners and checkers
Planners create execution plans from the research and context artifacts. Checkers verify plans meet quality standards before any code is written.gsd-planner
Creates two to three atomic execution plans per phase, reading
PROJECT.md, REQUIREMENTS.md, CONTEXT.md, and RESEARCH.md. Each plan contains structured <task> elements with explicit acceptance criteria, dependency ordering, and requirement traceability. Runs on the Opus model tier for maximum planning quality.gsd-roadmapper
Creates the project roadmap during
/gsd-new-project. Maps every v1 requirement to a phase, derives success criteria, and validates full coverage before presenting the roadmap for your approval.gsd-plan-checker
Verifies plans across eight dimensions before execution is permitted: requirement coverage, task atomicity, dependency ordering, file scope, verification commands, context fit, gap detection, and Nyquist compliance. Runs iteratively — up to three revision cycles — until plans pass all dimensions.
gsd-research-synthesizer
Combines the outputs of four parallel project researchers into a single
SUMMARY.md after /gsd-new-project. Runs sequentially after all researchers complete.Executors
Executors implement plans. Each executor runs in a fresh context window and produces atomic git commits — one commit per completed task — so the implementation history is granular and recoverable.gsd-executor
Implements a single
PLAN.md file. Reads the plan, the phase CONTEXT.md and RESEARCH.md, and the project-level PROJECT.md and STATE.md. Makes one atomic git commit per completed task. Writes a SUMMARY.md documenting what was built and any deviations from the plan. Multiple executors run in parallel within each wave; waves are sequenced by plan dependency.The executor is the only agent with
Edit tool access. It can modify source files. All other agents are read-only against implementation code — they analyze, plan, verify, or audit, but they do not change your code.Verifiers and auditors
Verifiers confirm that what was built satisfies the requirements. Auditors check specific quality dimensions like security, test coverage, and UI consistency.gsd-verifier
Runs after all executors complete. Performs a goal-backward analysis: checks the codebase against phase goals, runs the test suite, and writes
VERIFICATION.md with a PASS or FAIL verdict and specific evidence. Also audits test quality — checking for disabled tests, circular test patterns, and weak assertions.gsd-code-reviewer
Reviews source files for bugs, security vulnerabilities, and code quality problems. Produces a structured
REVIEW.md with severity-classified findings. Read-only — never modifies the code it reviews.gsd-security-auditor
Verifies that the threat mitigations declared in your
PLAN.md threat model are actually present in the implemented code. Does not scan blindly for new vulnerabilities — it verifies declared mitigations only. Supports ASVS levels 1, 2, and 3 for verification depth.gsd-nyquist-auditor
Fills test coverage gaps identified by the Nyquist validation pass. Generates test files but never modifies implementation code. Flags implementation bugs as escalations for you to address.
Mappers
Mappers explore the codebase and produce structured analysis documents for planning and context.gsd-codebase-mapper
Explores your existing codebase and writes seven structured analysis documents to
.planning/codebase/ — stack, architecture, conventions, concerns, structure, testing, and integrations. Runs four parallel instances covering different analysis dimensions. Use this before starting a new project on an existing codebase, or after a phase that significantly restructures the code.Debuggers and specialized agents
gsd-debugger
Investigates bugs using a scientific method with persistent session state. Tracks hypotheses, evidence, and eliminated theories across context resets. State is written to
.planning/debug/ and persists until you mark the bug resolved. Appends learnings to a persistent knowledge base on resolution.gsd-assumptions-analyzer
Deeply analyzes the codebase for a phase in assumptions mode (
discuss_mode: assumptions). Returns structured assumptions with evidence file paths, confidence levels (Confident, Likely, Unclear), and consequences if wrong — so the discussion starts from what the AI observed rather than from scratch.Agent tool permissions
Each agent has access only to the tools it needs for its role. The principle of least privilege keeps agents focused and prevents unintended side effects:| Agent | Can write code | Can search web | Can edit files |
|---|---|---|---|
| Researchers | No | Yes | No |
| Planner | No (writes plans only) | No | No |
| Plan-checker | No | No | No |
| Executor | Yes | No | Yes |
| Verifier | No | No | No |
| Codebase mapper | No | No | No |
| Debugger | No | Yes | Yes |
| Security auditor | No | No | No |
Agent spawn patterns
The table below maps the major workflow commands to the agents they spawn and the parallelism involved:| Command | Agents spawned | Parallelism |
|---|---|---|
/gsd-new-project | gsd-project-researcher × 4 → gsd-research-synthesizer → gsd-roadmapper | 4 parallel researchers, then sequential |
/gsd-discuss-phase | gsd-assumptions-analyzer (assumptions mode only) | Sequential |
/gsd-plan-phase | gsd-phase-researcher × 4 → gsd-research-synthesizer → gsd-planner → gsd-plan-checker | 4 parallel, then sequential (up to 3 check iterations) |
/gsd-execute-phase | gsd-executor × N → gsd-verifier | N parallel per wave, then sequential |
/gsd-map-codebase | gsd-codebase-mapper × 4 | 4 parallel |
/gsd-debug | gsd-debugger | Sequential, interactive |
/gsd-code-review | gsd-code-reviewer | Sequential |
/gsd-secure-phase | gsd-security-auditor | Sequential |