Skip to content

Commit dc5e516

Browse files
ruben-cytonicclaude
ruben-cytonic
and
claude
committed
feat: spec driven development features, docs fix, and articles
- Fix broken /docs/cli/figma link in HeroSection (unblocks all docs CI) - Add spec-validator with completeness scoring (0-100) - Add --spec-validate flag to run command - Add ralph-starter spec command (validate, list, summary) - Create docs/docs/cli/figma.md - Add SDD blog post (EN), LinkedIn article (PT-BR), Twitter thread (EN) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent a389b89 commit dc5e516

10 files changed

Lines changed: 1014 additions & 1 deletion

File tree

‎content/linkedin-sdd-ralph-starter-pt-br.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# LinkedIn: Spec Driven Development com ralph-starter
2+
3+
## Formato
4+
- Artigo longo no LinkedIn
5+
- Idioma: Portugues brasileiro
6+
- Tom: Profissional, direto, com exemplos praticos
7+
- Publico: Devs brasileiros, tech leads, CTOs
8+
9+
---
10+
11+
## Titulo
12+
13+
Spec Driven Development: por que voce deveria parar de mandar "faz um CRUD" pro agente de IA
14+
15+
---
16+
17+
## Corpo
18+
19+
Nos ultimos meses eu vi uma mudanca silenciosa na forma como devs usam agentes de IA pra codar.
20+
21+
No comeco, todo mundo fazia a mesma coisa: abria o chat, escrevia "cria uma API de autenticacao", rezava, e torcia pro resultado fazer sentido. As vezes dava certo. Na maioria das vezes, nao.
22+
23+
O problema nunca foi o agente. O problema era a especificacao -- ou melhor, a falta dela.
24+
25+
Isso tem nome agora: Spec Driven Development (SDD).
26+
27+
A ideia e simples: antes de codar, voce escreve uma spec clara. Nao um documento de 50 paginas. Uma spec de 10-20 linhas que diz exatamente o que precisa ser feito, como validar, e quais sao os criterios de aceite.
28+
29+
Tem tres ferramentas ganhando tracao nesse espaco:
30+
31+
- **OpenSpec** (Fission AI) -- framework leve e tool-agnostic. Voce cria uma pasta openspec/ com proposal.md, design.md, tasks.md, e specs com keywords RFC 2119 (SHALL, MUST, SHOULD).
32+
33+
- **Spec-Kit** (GitHub) -- mais pesado, com 5 fases (constituicao, especificacao, planejamento, tarefas, implementacao). Bom pra projetos grandes.
34+
35+
- **Kiro** (AWS) -- IDE completa com agentes integrados. Poderoso, mas locked no ecossistema AWS.
36+
37+
Eu construi o ralph-starter justamente pra resolver esse gap. Ele puxa specs de qualquer lugar -- GitHub Issues, Linear, Notion, Figma, OpenSpec -- e roda loops autonomos de codificacao ate a tarefa estar completa.
38+
39+
O fluxo e assim:
40+
41+
```
42+
Spec -> Plano de implementacao -> Agente codifica -> Lint/Build/Testes -> Se falhou, alimenta o erro de volta -> Repete -> Commit + PR
43+
```
44+
45+
Na v0.5.0 a gente adicionou suporte nativo a OpenSpec:
46+
47+
```bash
48+
# Ler specs de um diretorio OpenSpec
49+
ralph-starter run --from openspec:minha-feature
50+
51+
# Validar completude da spec antes de rodar
52+
ralph-starter run --from openspec:minha-feature --spec-validate
53+
54+
# Listar specs disponiveis
55+
ralph-starter spec list
56+
57+
# Validar todas as specs do projeto
58+
ralph-starter spec validate
59+
```
60+
61+
O `--spec-validate` checa se sua spec tem:
62+
- Uma secao de proposta/racional (por que?)
63+
- Keywords RFC 2119 (SHALL, MUST)
64+
- Criterios de aceite (Given/When/Then)
65+
- Design e tasks
66+
67+
E retorna um score de 0 a 100. Se a spec estiver incompleta, o ralph-starter avisa antes de gastar tokens.
68+
69+
O resultado pratico: specs claras = menos iteracoes = menos custo = PRs melhores.
70+
71+
Eu costumava gastar 5 loops e $3+ pra resolver uma tarefa mal especificada. Agora gasto 3 minutos escrevendo uma spec boa e 2 loops resolvem. O custo cai pra ~$0.50.
72+
73+
Se voce esta usando qualquer agente de IA pra codar -- Claude Code, Cursor, Copilot, o que for -- comeca a escrever specs. Serio. E a maior alavanca de produtividade que voce vai encontrar esse ano.
74+
75+
ralph-starter e open source, MIT licensed:
76+
https://github.com/multivmlabs/ralph-starter
77+
78+
---
79+
80+
## Hashtags
81+
#SpecDrivenDevelopment #AICoding #OpenSource #DevTools #ralph-starter #OpenSpec #SDD

‎content/twitter-thread-sdd-ralph-starter.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Twitter/X Thread: Spec Driven Development with ralph-starter
2+
3+
## Instructions
4+
- Post as a thread (not a single tweet)
5+
- Each tweet under 280 characters
6+
- Include code screenshots where noted
7+
8+
---
9+
10+
## Tweet 1 (Hook)
11+
12+
Spec Driven Development is eating AI coding.
13+
14+
OpenSpec, Spec-Kit, Kiro -- everyone's building spec frameworks now.
15+
16+
Here's why specs matter more than prompts, and how ralph-starter fits in:
17+
18+
---
19+
20+
## Tweet 2 (The problem)
21+
22+
The #1 mistake with AI coding agents:
23+
24+
"Add authentication to the app"
25+
26+
3 words. Zero context. The agent guesses everything. You spend 5 iterations fixing what a 10-line spec would've nailed in 2.
27+
28+
---
29+
30+
## Tweet 3 (What is SDD)
31+
32+
Spec Driven Development = write a clear spec BEFORE the agent touches code.
33+
34+
Not a 50-page doc. A focused spec:
35+
- What to build (proposal)
36+
- How to build it (design)
37+
- How to verify it (acceptance criteria)
38+
39+
10-20 lines. 3 minutes to write.
40+
41+
---
42+
43+
## Tweet 4 (The landscape)
44+
45+
Three SDD tools gaining traction:
46+
47+
OpenSpec -- lightweight, tool-agnostic, fluid phases
48+
Spec-Kit -- GitHub's heavyweight 5-phase framework
49+
Kiro -- AWS's full IDE with built-in agents
50+
51+
Each has tradeoffs. None connects to your existing workflow.
52+
53+
---
54+
55+
## Tweet 5 (ralph-starter's angle)
56+
57+
ralph-starter takes a different approach:
58+
59+
Your specs already live in GitHub Issues, Linear tickets, Notion docs, Figma files.
60+
61+
Why rewrite them? Pull from where they are, run autonomous loops until done.
62+
63+
```
64+
ralph-starter run --from github --project myorg/repo
65+
ralph-starter run --from openspec:my-feature
66+
```
67+
68+
---
69+
70+
## Tweet 6 (New: OpenSpec + spec-validate)
71+
72+
Just shipped in v0.5.0:
73+
74+
Native OpenSpec support + spec validation.
75+
76+
```
77+
ralph-starter spec validate
78+
ralph-starter run --from openspec:auth --spec-validate
79+
```
80+
81+
Checks for RFC 2119 keywords (SHALL/MUST), acceptance criteria, design sections. Scores 0-100.
82+
83+
Low score = bad spec = wasted tokens.
84+
85+
---
86+
87+
## Tweet 7 (The numbers)
88+
89+
Before specs: 5 loops, $3+, wrong output
90+
After specs: 2 loops, ~$0.50, correct output
91+
92+
The spec IS the leverage. Not the model. Not the prompt engineering. The spec.
93+
94+
---
95+
96+
## Tweet 8 (Multi-agent)
97+
98+
ralph-starter works with any agent:
99+
100+
- Claude Code
101+
- Cursor
102+
- Codex CLI
103+
- OpenCode
104+
- Amp (Sourcegraph)
105+
106+
No lock-in. No IDE requirement. CLI that runs anywhere.
107+
108+
---
109+
110+
## Tweet 9 (CTA)
111+
112+
ralph-starter is open source, MIT licensed.
113+
114+
Pull specs from GitHub/Linear/Notion/Figma/OpenSpec.
115+
Run autonomous coding loops.
116+
Ship faster.
117+
118+
https://github.com/multivmlabs/ralph-starter
119+
120+
Star it if SDD resonates.

‎docs/blog/2026-04-08-spec-driven-development-ralph-starter.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
slug: spec-driven-development-ralph-starter
3+
title: Spec Driven Development with ralph-starter
4+
authors: [ruben]
5+
tags: [ralph-starter, sdd, openspec, specs, workflow]
6+
description: How ralph-starter brings Spec Driven Development to any AI coding agent, with native OpenSpec support, spec validation, and multi-source spec fetching.
7+
image: /img/blog/sdd-ralph-starter.png
8+
---
9+
10+
Spec Driven Development is the biggest shift in AI coding since agents learned to run tests. Here is how ralph-starter fits in.
11+
12+
<!-- truncate -->
13+
14+
## The problem with "just prompt it"
15+
16+
Most people use AI coding agents the same way: type a sentence, hit enter, hope for the best. "Add user auth." "Fix the sidebar." Three words and vibes.
17+
18+
I did this for weeks. The agent would generate something that looked plausible but missed what I actually wanted. I blamed the tool, but the problem was me. I was not giving it enough context.
19+
20+
Then I started writing specs -- not essays, just 10-20 lines describing what I actually wanted, how to verify it, and where things should go. The difference was night and day. 2 loops instead of 5. $0.50 instead of $3. Correct output instead of close-but-wrong.
21+
22+
This pattern has a name now: **Spec Driven Development (SDD)**.
23+
24+
## The SDD landscape
25+
26+
Three frameworks are leading the SDD conversation:
27+
28+
| Tool | Philosophy | Lock-in |
29+
|------|-----------|---------|
30+
| **OpenSpec** (Fission AI) | Lightweight, fluid, tool-agnostic | None |
31+
| **Spec-Kit** (GitHub) | Heavyweight, rigid 5-phase gates | GitHub ecosystem |
32+
| **Kiro** (AWS) | Full IDE with built-in agents | AWS account required |
33+
34+
OpenSpec organizes specs into changes with `proposal.md`, `design.md`, `tasks.md`, and requirement specs using RFC 2119 keywords (SHALL, MUST, SHOULD). It is the lightest of the three.
35+
36+
Spec-Kit enforces five phases: constitution, specification, plan, tasks, implement. Thorough but heavy.
37+
38+
Kiro bundles everything into a VS Code fork with agent hooks and EARS notation. Powerful but locked to AWS.
39+
40+
## Where ralph-starter fits
41+
42+
ralph-starter takes a different angle: **your specs already exist somewhere**.
43+
44+
They are in GitHub Issues. Linear tickets. Notion docs. Figma designs. OpenSpec directories. Why rewrite them in a new format?
45+
46+
ralph-starter pulls specs from where they already live:
47+
48+
```bash
49+
# From GitHub issues
50+
ralph-starter run --from github --project myorg/myrepo --label "ready"
51+
52+
# From OpenSpec directories
53+
ralph-starter run --from openspec:add-auth
54+
55+
# From Linear tickets
56+
ralph-starter run --from linear --project "Mobile App"
57+
58+
# From a Notion doc
59+
ralph-starter run --from notion --project "https://notion.so/spec-abc123"
60+
```
61+
62+
Then it runs autonomous loops: build context, spawn agent, collect output, run validation (lint/build/test), commit, repeat until done.
63+
64+
## New in v0.5.0: OpenSpec + spec validation
65+
66+
We just shipped native OpenSpec support and a spec validator:
67+
68+
```bash
69+
# List all OpenSpec changes in the project
70+
ralph-starter spec list
71+
72+
# Validate spec completeness (0-100 score)
73+
ralph-starter spec validate
74+
75+
# Validate before running -- stops if spec is too thin
76+
ralph-starter run --from openspec:my-feature --spec-validate
77+
```
78+
79+
The validator checks for:
80+
- Proposal or rationale section (why are we building this?)
81+
- RFC 2119 keywords (SHALL, MUST -- formal requirements)
82+
- Given/When/Then acceptance criteria (testable conditions)
83+
- Design section (how to build it)
84+
- Task breakdown (implementation steps)
85+
86+
A spec scoring below 40/100 gets flagged before the agent starts. This saves tokens on underspecified work.
87+
88+
## The new spec command
89+
90+
`ralph-starter spec` gives you a CLI for spec operations:
91+
92+
```bash
93+
# Validate all specs in the project
94+
ralph-starter spec validate
95+
96+
# List available specs (auto-detects OpenSpec, Spec-Kit, or raw)
97+
ralph-starter spec list
98+
99+
# Show completeness summary
100+
ralph-starter spec summary
101+
```
102+
103+
It auto-detects whether you are using OpenSpec format, GitHub Spec-Kit format, or plain markdown specs.
104+
105+
## The numbers
106+
107+
| Metric | Without specs | With specs |
108+
|--------|--------------|------------|
109+
| Loops per task | 5 | 2 |
110+
| Cost per task | ~$3.00 | ~$0.50 |
111+
| Output accuracy | Hit or miss | Consistent |
112+
| Time writing spec | 0 min | 3 min |
113+
114+
The 3 minutes spent writing a spec save 15 minutes of iteration and debugging. The spec is the leverage.
115+
116+
## What is next
117+
118+
We are working on:
119+
- **Spec coverage tracking** -- which requirements have been implemented?
120+
- **Spec-to-test generation** -- Given/When/Then to test stubs
121+
- **Living specs** -- specs that update as implementation diverges
122+
123+
SDD is not a fad. It is the natural evolution of AI-assisted coding. The spec is the interface between human intent and machine execution. The clearer the spec, the better the output.
124+
125+
ralph-starter is open source, MIT licensed: [github.com/multivmlabs/ralph-starter](https://github.com/multivmlabs/ralph-starter)

‎docs/docs/cli/figma.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
sidebar_position: 12
3+
title: figma
4+
description: Interactive Figma-to-code wizard
5+
keywords: [cli, figma, wizard, design, integration]
6+
---
7+
8+
# ralph-starter figma
9+
10+
Interactive wizard for building code from Figma designs.
11+
12+
## Synopsis
13+
14+
```bash
15+
ralph-starter figma [options]
16+
```
17+
18+
## Description
19+
20+
The `figma` command launches an interactive wizard that guides you through selecting a Figma file, choosing a mode (spec, tokens, components, assets, content), and running an autonomous coding loop to implement the design.
21+
22+
For non-interactive usage and detailed mode documentation, see [Figma Source](/docs/sources/figma).
23+
24+
## Options
25+
26+
| Option | Description | Default |
27+
|--------|-------------|---------|
28+
| `--commit` | Auto-commit after tasks | false |
29+
| `--push` | Push commits to remote | false |
30+
| `--pr` | Create pull request when done | false |
31+
| `--validate` | Run validation after iterations | true |
32+
| `--no-validate` | Skip validation | - |
33+
| `--max-iterations <n>` | Maximum loop iterations | 50 |
34+
| `--agent <name>` | Agent to use | auto-detect |
35+
36+
## Examples
37+
38+
```bash
39+
# Launch the interactive wizard
40+
ralph-starter figma
41+
42+
# With auto-commit and PR creation
43+
ralph-starter figma --commit --pr
44+
45+
# Using a specific agent
46+
ralph-starter figma --agent claude-code --max-iterations 10
47+
```
48+
49+
## See Also
50+
51+
- [Figma Source](/docs/sources/figma) - Detailed mode documentation, authentication, and troubleshooting
52+
- [run](/docs/cli/run) - Non-interactive Figma usage via `--from figma`

‎docs/src/components/HeroSection/index.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,7 @@ export default function HeroSection(): React.ReactElement {
205205
<span className={styles.integrationLabel}>Integrations</span>
206206
<div className={styles.integrationLogos}>
207207
{[
208-
{ id: 'figma' as const, to: '/docs/cli/figma', src: '/img/figma-logo.svg', alt: 'Figma' },
208+
{ id: 'figma' as const, to: '/docs/sources/figma', src: '/img/figma-logo.svg', alt: 'Figma' },
209209
{ id: 'github' as const, to: '/docs/sources/github', src: '/img/github logo.webp', alt: 'GitHub' },
210210
{ id: 'linear' as const, to: '/docs/sources/linear', src: '/img/linear.jpeg', alt: 'Linear' },
211211
{ id: 'notion' as const, to: '/docs/sources/notion', src: '/img/notion logo.png', alt: 'Notion' },

0 commit comments

Comments
 (0)