|
| 1 | +--- |
| 2 | +sidebar_position: 7 |
| 3 | +title: Spec Driven Development |
| 4 | +description: How ralph-starter implements Spec Driven Development for AI coding agents |
| 5 | +keywords: [sdd, spec driven development, openspec, spec-kit, specs, workflow] |
| 6 | +--- |
| 7 | + |
| 8 | +# Spec Driven Development |
| 9 | + |
| 10 | +Spec Driven Development (SDD) is a methodology where you write a structured specification before any code is generated. The spec becomes the contract between human intent and AI execution. |
| 11 | + |
| 12 | +ralph-starter is built around this principle: **pull specs from where they already live, validate them, then run autonomous loops until done.** |
| 13 | + |
| 14 | +## Why specs matter for AI coding |
| 15 | + |
| 16 | +Without a spec, AI agents guess. A vague prompt like "add authentication" produces plausible but wrong code. You waste iterations fixing misunderstandings. |
| 17 | + |
| 18 | +With a clear spec: |
| 19 | +- **2 loops** instead of 5 |
| 20 | +- **$0.50** instead of $3+ |
| 21 | +- **Correct output** instead of close-but-wrong |
| 22 | + |
| 23 | +The spec is the highest-leverage investment in any AI coding workflow. |
| 24 | + |
| 25 | +## How ralph-starter does SDD |
| 26 | + |
| 27 | +``` |
| 28 | +Spec → Validate → Plan → Agent builds → Lint/Build/Test → Commit → PR |
| 29 | +``` |
| 30 | + |
| 31 | +### 1. Pull specs from any source |
| 32 | + |
| 33 | +Your specs already exist somewhere. ralph-starter fetches them: |
| 34 | + |
| 35 | +```bash |
| 36 | +# From OpenSpec directories |
| 37 | +ralph-starter run --from openspec:add-auth |
| 38 | + |
| 39 | +# From GitHub issues |
| 40 | +ralph-starter run --from github --project myorg/api --label ready |
| 41 | + |
| 42 | +# From Linear tickets |
| 43 | +ralph-starter run --from linear --project "Backend" |
| 44 | + |
| 45 | +# From Notion docs |
| 46 | +ralph-starter run --from notion --project "https://notion.so/spec-abc" |
| 47 | + |
| 48 | +# From Figma designs |
| 49 | +ralph-starter figma |
| 50 | +``` |
| 51 | + |
| 52 | +### 2. Validate before building |
| 53 | + |
| 54 | +The `--spec-validate` flag checks completeness before spending tokens: |
| 55 | + |
| 56 | +```bash |
| 57 | +ralph-starter run --from openspec:add-auth --spec-validate |
| 58 | +``` |
| 59 | + |
| 60 | +The validator scores specs 0-100 based on: |
| 61 | + |
| 62 | +| Check | Points | What it looks for | |
| 63 | +|-------|--------|-------------------| |
| 64 | +| Proposal/rationale | 20 | `## Proposal`, `## Why`, `## Overview` section | |
| 65 | +| RFC 2119 keywords | 25 / 10 | 25 if SHALL, MUST, SHOULD, MAY present; 10 partial credit if absent but content >200 chars | |
| 66 | +| Design section | 15 | `## Design`, `## Architecture`, `## Technical` | |
| 67 | +| Task breakdown | 15 | `## Tasks` or `- [ ]` checklists | |
| 68 | +| Acceptance criteria | 15 | Given/When/Then blocks | |
| 69 | +| Content depth | 10 / 5 | 10 if >= 500 chars; 5 if 200-499 chars | |
| 70 | + |
| 71 | +Specs scoring below 40/100 are flagged before the loop starts. |
| 72 | + |
| 73 | +### 3. Autonomous execution |
| 74 | + |
| 75 | +Once validated, ralph-starter runs the loop: |
| 76 | +1. Build iteration context from spec + plan |
| 77 | +2. Spawn the AI agent with trimmed prompt |
| 78 | +3. Collect agent output |
| 79 | +4. Run validation (lint, build, tests) |
| 80 | +5. If validation fails, feed errors back to agent |
| 81 | +6. If validation passes, commit |
| 82 | +7. Repeat until task is complete |
| 83 | + |
| 84 | +## The `spec` command |
| 85 | + |
| 86 | +ralph-starter includes a dedicated CLI for spec operations: |
| 87 | + |
| 88 | +```bash |
| 89 | +# Validate all specs in the project |
| 90 | +ralph-starter spec validate |
| 91 | + |
| 92 | +# List available specs (auto-detects format) |
| 93 | +ralph-starter spec list |
| 94 | + |
| 95 | +# Show completeness metrics |
| 96 | +ralph-starter spec summary |
| 97 | +``` |
| 98 | + |
| 99 | +It auto-detects **OpenSpec**, **Spec-Kit**, or **raw markdown** format. |
| 100 | + |
| 101 | +## Comparison: ralph-starter vs other SDD tools |
| 102 | + |
| 103 | +| Capability | ralph-starter | OpenSpec | Spec-Kit | Kiro | |
| 104 | +|-----------|--------------|---------|---------|------| |
| 105 | +| **Spec format** | Any (OpenSpec, Spec-Kit, raw, GitHub, Linear, Notion, Figma) | OpenSpec only | Spec-Kit only | EARS notation | |
| 106 | +| **Execution** | Fully autonomous loops | Manual (`/opsx:apply`) | Manual per phase | IDE-integrated agents | |
| 107 | +| **Agent support** | Claude Code, Cursor, Codex, OpenCode, Amp | Any chat agent | Any chat agent | Kiro agents only | |
| 108 | +| **Validation** | Lint + build + test + visual | None | None | Agent hooks | |
| 109 | +| **Spec validation** | 0-100 scoring with RFC 2119 check | Zod schema | Phase gates | Auto-generated | |
| 110 | +| **Multi-source** | GitHub, Linear, Notion, Figma, OpenSpec, URLs, files | Local filesystem | Local filesystem | IDE workspace | |
| 111 | +| **Cost tracking** | Per-iteration token + cost tracking | N/A | N/A | Subscription model | |
| 112 | +| **Lock-in** | None (CLI, any OS) | None | GitHub ecosystem | AWS account required | |
| 113 | +| **Pricing** | Free + pay-per-API | Free | Free | $19-39/month | |
| 114 | + |
| 115 | +## Writing good specs |
| 116 | + |
| 117 | +A spec does not need to be long. 10-20 lines is enough: |
| 118 | + |
| 119 | +```markdown |
| 120 | +## Proposal |
| 121 | + |
| 122 | +Add JWT authentication to the Express API. |
| 123 | + |
| 124 | +## Requirements |
| 125 | + |
| 126 | +- POST /api/auth/login takes { email, password }, validates against users table |
| 127 | +- Return { token, expiresIn } on success, 401 with { error } on failure |
| 128 | +- Token TTL: 24h |
| 129 | +- Auth middleware in src/middleware/auth.ts (Authorization: Bearer header) |
| 130 | +- The API MUST reject expired tokens with 401 |
| 131 | +- The API SHALL rate-limit login attempts to 5/minute per IP |
| 132 | + |
| 133 | +## Tasks |
| 134 | + |
| 135 | +- [ ] Create auth middleware |
| 136 | +- [ ] Add login endpoint |
| 137 | +- [ ] Add token refresh endpoint |
| 138 | +- [ ] Write tests |
| 139 | + |
| 140 | +## Acceptance Criteria |
| 141 | + |
| 142 | +Given: A user with valid credentials |
| 143 | +When: They POST to /api/auth/login |
| 144 | +Then: They receive a JWT token with 24h TTL |
| 145 | + |
| 146 | +Given: A request with an expired token |
| 147 | +When: It hits a protected endpoint |
| 148 | +Then: The API returns 401 Unauthorized |
| 149 | +``` |
| 150 | + |
| 151 | +This spec takes 3 minutes to write. It tells the agent exactly what to build, where to put it, and how to verify it works. |
| 152 | + |
| 153 | +## Supported spec formats |
| 154 | + |
| 155 | +### OpenSpec |
| 156 | + |
| 157 | +``` |
| 158 | +openspec/ |
| 159 | +├── changes/ |
| 160 | +│ └── add-auth/ |
| 161 | +│ ├── proposal.md |
| 162 | +│ ├── design.md |
| 163 | +│ ├── tasks.md |
| 164 | +│ └── specs/ |
| 165 | +│ └── auth/ |
| 166 | +│ └── spec.md |
| 167 | +└── specs/ |
| 168 | + └── api/ |
| 169 | + └── spec.md |
| 170 | +``` |
| 171 | + |
| 172 | +```bash |
| 173 | +ralph-starter run --from openspec:add-auth |
| 174 | +``` |
| 175 | + |
| 176 | +### Spec-Kit (GitHub) |
| 177 | + |
| 178 | +``` |
| 179 | +specs/ |
| 180 | +├── constitution.md |
| 181 | +├── specification.md |
| 182 | +├── plan.md |
| 183 | +└── tasks.md |
| 184 | +``` |
| 185 | + |
| 186 | +```bash |
| 187 | +ralph-starter spec validate # auto-detects Spec-Kit format |
| 188 | +``` |
| 189 | + |
| 190 | +### Raw markdown |
| 191 | + |
| 192 | +``` |
| 193 | +specs/ |
| 194 | +├── auth-spec.md |
| 195 | +├── api-spec.md |
| 196 | +└── db-migration.md |
| 197 | +``` |
| 198 | + |
| 199 | +```bash |
| 200 | +ralph-starter run --from ./specs/auth-spec.md |
| 201 | +``` |
| 202 | + |
| 203 | +## Next steps |
| 204 | + |
| 205 | +- [OpenSpec source docs](/docs/sources/openspec) -- How to use OpenSpec with ralph-starter |
| 206 | +- [Spec CLI reference](/docs/cli/spec) -- Full `ralph-starter spec` command docs |
| 207 | +- [Workflow presets](/docs/guides/workflow-presets) -- Pre-configured SDD presets |
0 commit comments