Spec Design

Instructions

Step 0: Check Prerequisites

Read the frontmatter of each prerequisite document. A document's status is in its YAML frontmatter status field. If no frontmatter exists, treat as DRAFT.

• HARD gate failed (missing or status is not APPROVED): Display: "Cannot proceed: requirements.md is missing or not APPROVED (current status: <status>). Run spec:approve <spec-name> requirements first." Use AskUserQuestion with options: "Run spec:approve now", "Cancel". Do NOT offer "proceed anyway".
• SOFT gate failed (missing or status is not APPROVED): Display: "Warning: research.md is missing or not APPROVED. Proceeding without research may lead to lower quality design." Use AskUserQuestion with options: "Proceed anyway", "Run spec:approve first", "Cancel".
• All gates pass: Proceed silently to Step 1.

Step 1: Locate Specification Documents

1. If $0 is provided, use it as the spec name and look in .specs/<spec-name>/
2. If no spec name provided, list available specs in .specs/ and use the AskUserQuestion tool to let the user choose
3. Read and analyze:
   • requirements.md — the requirements document (required)
   • research.md — the research document with chosen solutions (recommended)

Step 2: Analyze the Codebase

Before writing the design, analyze the codebase using parallel sub-agents. The depth of exploration depends on whether research.md exists:

2a. Codebase Exploration (launch in parallel)

Use the Task tool with subagent_type=Explore to run exploration agents in parallel.

When research.md EXISTS with CHOSEN solutions — run 2 focused validation agents:

1. Integration Validator — you are an Integration Validator. Find specific files, APIs, and models that will be affected. Verify that integration points described in research.md actually exist.
2. Impact Analyst — you are an Impact Analyst. Identify the exact files and components that will need to be created or modified. Map the full data flow.

The research already covers architecture and patterns — do NOT re-discover what is already documented.

When research.md is MISSING — run 4 broad discovery agents:

1. Architecture Scout — you are an Architecture Scout. Explore overall project structure, entry points, module boundaries, and dependency graph.
2. Patterns Analyst — you are a Patterns Analyst. Identify coding conventions, design patterns, naming styles, error handling approaches, and testing patterns used in the codebase.
3. Integration Validator — you are an Integration Validator. Find APIs, services, database models, external dependencies, and configuration files relevant to the requirements.
4. Impact Analyst — you are an Impact Analyst. Based on the requirements document, identify specific files and components that will need to be created or modified.

All agents MUST be launched in a single message (parallel tool calls) to maximize efficiency.

2b. Technology Research (launch in parallel with 2a)

Use external information sources to complement the research document — do not repeat investigation already captured in research.md. Focus on implementation-level details needed for the design:

1. Context7 MCP server — use resolve-library-id and query-docs to fetch up-to-date documentation for key dependencies found in package.json, go.mod, Cargo.toml, or equivalent manifest files. Query API references and implementation patterns relevant to the chosen solutions
2. Web search — use WebSearch to find implementation guides, code examples, and known pitfalls specific to the chosen approaches
3. Web fetch — if the requirements or research reference specific APIs, services, or specs (e.g., OAuth, OpenAPI schemas, RFC documents), use WebFetch to retrieve and analyze them

Launch these research tasks in parallel with the codebase exploration agents above.

2c. Synthesize Findings

After all parallel agents and research complete, synthesize the results into a unified understanding:

• Current architecture and where the new feature fits
• Existing patterns to follow (or consciously deviate from with justification)
• Technology constraints and best practices from documentation
• Files and components to create or modify
• Integration points and potential risks

Step 3: Create the Design Document

Create the document at .specs/<spec-name>/design.md with this structure:

The document MUST begin with YAML frontmatter before the first # heading:

---