---
name: spec
description: >
  Kick off Phase 4 (Specification). Builds the North Star spec document with enough
  detail for every ticket to go through a full dev cycle. Works for both full project
  specs and feature-level specs.
---

# Phase 4: Specification

You are beginning the Specification phase. Your goal is to produce the definitive spec that serves as the North Star for all development work.

## Prerequisites

- Approved design document from Phase 3 (check `docs/designs/`)

## Process

1. **Determine scope.** Is this a full project spec or a feature spec?
   - **Full project spec:** Covers the entire system end-to-end
   - **Feature spec:** References the parent project spec, covers only the delta
2. **Delegate to architect.** The `architect` agent writes the spec with input from relevant specialist agents.
3. **For every component/feature, define:**
   - What it does (behavior, not implementation)
   - What "passing" looks like (specific, testable acceptance criteria)
   - What "failing" looks like (expected error behaviors)
   - How to test it (unit, integration, E2E)
   - Metrics to track (performance, reliability, cost)
   - Dependencies on other components
4. **Save** to `docs/specs/<project-or-feature-slug>-spec-<date>.md`
5. **Present to user** and ask for approval before Phase 5.

## Output: Spec Template

```markdown
## Specification: [Project/Feature Name]
### Date: [date]
### Type: Project Spec | Feature Spec
### Parent Spec: [link, if feature spec]
### Status: Draft | Approved

### Overview
[What this spec covers and why it exists]

### Goals
1. [Measurable goal]
2. [Measurable goal]

### Non-Goals
- [Explicitly out of scope]

### Components

#### [Component/Feature Name]
**Behavior:** [What it does — describe from the user's perspective]

**Acceptance Criteria:**
- [ ] [Specific, testable criterion]
- [ ] [Another criterion]

**Failure Modes:**
- [What happens when X fails]
- [Expected error messages/behaviors]

**Testing Strategy:**
- Unit: [what to test at unit level]
- Integration: [what to test across components]
- E2E: [end-to-end scenarios]

**Metrics:**
- [Performance metric and target]
- [Reliability metric and target]

**Dependencies:**
- [Other components this depends on]

### API Contracts
[If applicable — endpoint definitions, request/response schemas]

### Data Models
[Schema definitions for all persistent data]

### Migration Strategy
[If applicable — how to get from current state to target state]

### Rollback Plan
[How to undo if something goes wrong]

### Estimated Effort
| Component | Complexity | Estimated Tickets | Notes |
|-----------|-----------|-------------------|-------|
| ...       | ...       | ...               | ...   |
```

## Full Project Spec vs Feature Spec

| Aspect | Project Spec | Feature Spec |
|--------|-------------|--------------|
| Scope | Entire system | Single feature or enhancement |
| Components | All | Only affected components |
| Data models | Complete schema | Delta changes only |
| References | Standalone | Must reference parent project spec |
| Effort | Days–weeks | Hours–days |

## Rules

- Every acceptance criterion must be testable by an automated test or a clear manual procedure
- Specs describe behavior, not implementation — leave "how" to the dev phase
- If you can't define what "passing" looks like, the feature isn't well enough understood — go back to research
- Do not proceed to Phase 5 without explicit user approval
