/zerg:design
Generate technical architecture and a task graph for parallel execution.
Synopsis
/zerg:design
Description
/zerg:design reads the approved requirements for the active feature and produces two key artifacts: a technical design document (design.md) and a task graph (task-graph.json). Together, these define the architecture and break the work into parallelizable tasks with exclusive file ownership.
The command requires that /zerg:plan has been run and that the resulting requirements.md has been marked as APPROVED.
Design Phases
The command proceeds through six phases:
Architecture Design -- Analyzes functional requirements, maps data flow, defines component interfaces, and documents key architectural decisions with rationale.
Implementation Plan -- Breaks the architecture into dependency levels that enable parallel execution:
- Level 1 (Foundation): Types, interfaces, schemas, configuration. No dependencies.
- Level 2 (Core): Business logic services, data access, utilities. Depends on Level 1.
- Level 3 (Integration): API routes, event handlers, middleware. Depends on Level 2.
- Level 4 (Testing): Unit, integration, and E2E tests. Depends on Level 3.
- Level 5 (Quality): Documentation, type coverage, lint fixes. Depends on Level 4.
Task Graph Generation -- Produces task-graph.json containing every task with its ID, title, description, level, dependencies, file ownership (create/modify/read), verification command, and time estimate.
Generate design.md -- Writes the full design document including overview, architecture diagrams, data models, API design, database schema, key decisions, implementation plan, file ownership matrix, risk assessment, and testing strategy.
Task Graph Validation -- Checks for circular dependencies, exclusive file ownership, and valid verification commands.
User Approval -- Presents the design for review. The user responds with approved or changes needed.
File Ownership
Each file in the project is assigned to exactly one task. This eliminates merge conflicts during parallel execution. The ownership is recorded in both design.md and task-graph.json.
Task Graph Schema
Each task in task-graph.json includes:
| Field |
Description |
id |
Unique task identifier (e.g., TASK-001) |
title |
Short description of the task |
description |
Detailed instructions for the worker |
phase |
Named phase (foundation, core, integration, testing, quality) |
level |
Numeric dependency level (1-5) |
dependencies |
List of task IDs that must complete first |
files.create |
Files this task creates |
files.modify |
Files this task modifies |
files.read |
Files this task reads (no ownership claim) |
verification.command |
Shell command to verify task completion |
verification.timeout_seconds |
Maximum time for verification |
estimate_minutes |
Estimated completion time |
Options
This command takes no options. It operates on the active feature detected from .gsd/.current-feature.
Prerequisites
/zerg:init must have been run/zerg:plan <feature> must have been runrequirements.md must exist with Status: APPROVED
Examples
# Generate design for the active feature
/zerg:design
Output
On completion, the following files are created or updated:
.gsd/specs/<feature>/
design.md # Technical design document
task-graph.json # Machine-readable task graph
Tasks are also registered in the Claude Code Task system with subjects following the pattern [L<level>] <title> and with dependency chains wired via blockedBy relationships.
Completion Criteria
design.md exists with Status: APPROVEDtask-graph.json is valid JSON with no circular dependencies- All tasks have verification commands
- File ownership is exclusive (no two tasks modify the same file)
- User has explicitly approved the design
- Claude Code Tasks are created for all tasks with correct dependencies
See Also
- [[zerg-plan]] -- Must complete before design
- [[zerg-rush]] -- Next step after design is approved
- [[zerg-Reference]] -- Full command index
1---2name: zerg-design3description: Generate technical architecture and a task graph for parallel execution.4---5# /zerg:design67Generate technical architecture and a task graph for parallel execution.89## Synopsis1011```12/zerg:design13```1415## Description1617`/zerg:design` reads the approved requirements for the active feature and produces two key artifacts: a technical design document (`design.md`) and a task graph (`task-graph.json`). Together, these define the architecture and break the work into parallelizable tasks with exclusive file ownership.1819The command requires that `/zerg:plan` has been run and that the resulting `requirements.md` has been marked as `APPROVED`.2021### Design Phases2223The command proceeds through six phases:24251. **Architecture Design** -- Analyzes functional requirements, maps data flow, defines component interfaces, and documents key architectural decisions with rationale.26272. **Implementation Plan** -- Breaks the architecture into dependency levels that enable parallel execution:28 - **Level 1 (Foundation):** Types, interfaces, schemas, configuration. No dependencies.29 - **Level 2 (Core):** Business logic services, data access, utilities. Depends on Level 1.30 - **Level 3 (Integration):** API routes, event handlers, middleware. Depends on Level 2.31 - **Level 4 (Testing):** Unit, integration, and E2E tests. Depends on Level 3.32 - **Level 5 (Quality):** Documentation, type coverage, lint fixes. Depends on Level 4.33343. **Task Graph Generation** -- Produces `task-graph.json` containing every task with its ID, title, description, level, dependencies, file ownership (create/modify/read), verification command, and time estimate.35364. **Generate design.md** -- Writes the full design document including overview, architecture diagrams, data models, API design, database schema, key decisions, implementation plan, file ownership matrix, risk assessment, and testing strategy.37385. **Task Graph Validation** -- Checks for circular dependencies, exclusive file ownership, and valid verification commands.39406. **User Approval** -- Presents the design for review. The user responds with `approved` or `changes needed`.4142### File Ownership4344Each file in the project is assigned to exactly one task. This eliminates merge conflicts during parallel execution. The ownership is recorded in both `design.md` and `task-graph.json`.4546### Task Graph Schema4748Each task in `task-graph.json` includes:4950| Field | Description |51|-------|-------------|52| `id` | Unique task identifier (e.g., `TASK-001`) |53| `title` | Short description of the task |54| `description` | Detailed instructions for the worker |55| `phase` | Named phase (foundation, core, integration, testing, quality) |56| `level` | Numeric dependency level (1-5) |57| `dependencies` | List of task IDs that must complete first |58| `files.create` | Files this task creates |59| `files.modify` | Files this task modifies |60| `files.read` | Files this task reads (no ownership claim) |61| `verification.command` | Shell command to verify task completion |62| `verification.timeout_seconds` | Maximum time for verification |63| `estimate_minutes` | Estimated completion time |6465## Options6667This command takes no options. It operates on the active feature detected from `.gsd/.current-feature`.6869## Prerequisites7071- `/zerg:init` must have been run72- `/zerg:plan <feature>` must have been run73- `requirements.md` must exist with `Status: APPROVED`7475## Examples7677```bash78# Generate design for the active feature79/zerg:design80```8182## Output8384On completion, the following files are created or updated:8586```87.gsd/specs/<feature>/88 design.md # Technical design document89 task-graph.json # Machine-readable task graph90```9192Tasks are also registered in the Claude Code Task system with subjects following the pattern `[L<level>] <title>` and with dependency chains wired via `blockedBy` relationships.9394## Completion Criteria9596- `design.md` exists with `Status: APPROVED`97- `task-graph.json` is valid JSON with no circular dependencies98- All tasks have verification commands99- File ownership is exclusive (no two tasks modify the same file)100- User has explicitly approved the design101- Claude Code Tasks are created for all tasks with correct dependencies102103## See Also104105- [[zerg-plan]] -- Must complete before design106- [[zerg-rush]] -- Next step after design is approved107- [[zerg-Reference]] -- Full command index
tools-only