Spec-Driven Coding

Structured approach to building software: discover → spec → match stack → implement with fresh-context iterations.

Overview

Four phases:

1. Discovery — Gather requirements, produce structured spec
2. Stack Matching — Find or create a tech-stack skill for the project
3. Planning — Generate AGENTS.md with spec + stack patterns + execution rules
4. Implementation — Execute using Ralph Wiggum pattern (fresh context per iteration)

Phase 1: Discovery

Conversational requirements gathering (3-5 exchanges max). Gather:

• Goal: What are we building?
• Language/Framework: Tech stack (respect user preferences from USER.md)
• Features: Specific functionality
• Requirements: Constraints, APIs, integrations
• Project name: For directory/repo

Produce a spec JSON and save to .spec.json:

{
  "goal": "Build a CLI tool for ...",
  "project_name": "my-tool",
  "language": "Go",
  "framework": "cobra",
  "features": ["Feature 1", "Feature 2"],
  "requirements": ["Must support X"]
}

Confirm spec with user before proceeding.

Phase 2: Stack Matching

Tech-stack skills capture how we build with a given stack. They accumulate patterns, conventions, and preferences over time so every project is built the way we want.

Finding a Stack

Check stacks/ directory for a matching stack file:

• Match on language, framework, tags
• Read the matched stack file for patterns and conventions

Available stacks: (read from stacks/ dir)

• cloudflare-hono.md — Cloudflare Workers + Hono + Durable Objects
• go-cli.md — Go CLI with Cobra/Tooey

Creating a New Stack

If no stack matches, create one during discovery:

1. Ask user about their preferences for this stack (project structure, naming, patterns, testing)
2. Research the framework docs if needed (web_fetch official docs)
3. Create a new stack file in stacks/<name>.md

Stack file format:

# Tech Stack: {Name}

**Tags:** tag1, tag2, tag3

{Description of when to use this stack}

## Project Structure
{preferred directory layout}

## Conventions
- **Naming:** {conventions}
- **Extensions:** {file types}

## Key Patterns
{Code examples for routing, DB, error handling, etc.}

## Dependencies
{default packages to install}

## Preferences
{build commands, runtime choices, style preferences}

Improving Stacks

After completing a project, review what worked and update the stack:

• Add patterns discovered during implementation
• Fix conventions that caused issues
• Add dependencies that were needed
• Update preferences based on lessons learned

This is the key differentiator: stacks improve with every project. Over time, they encode exactly how we build things.

Phase 3: Planning

Generate an AGENTS.md that becomes the single source of truth for implementation.

See references/agents-template.md for the template. The AGENTS.md combines:

• Project spec (from Phase 1)
• Tech stack patterns and conventions (from Phase 2)
• Execution rules — see references/execution-rules.md
• Current project structure
• Implementation plan (ordered steps)

Save as AGENTS.md in the project root.

Phase 4: Implementation (Ralph Wiggum Pattern)

Each iteration is a separate sessions_spawn = genuinely fresh context.

See references/ralph-pattern.md for full implementation guide.

Why Ralph?

Context degrades over long sessions. By spawning a new session per iteration, each gets a full 200K context window. No accumulated confusion, no contradictions.

How It Works

The main session is the orchestrator — it does NOT implement. It only:

1. Initializes .ralph-state.json
2. Spawns iterations via sessions_spawn (each = fresh context)
3. Reads state file after each spawn returns
4. Reports progress to user
5. Loops until status: "completed" or max iterations

Orchestrator Loop

# Pseudocode — main session runs this
init_state(task, project_dir)

while state.status == "running" and state.iteration < max:
    sessions_spawn(task=build_iteration_prompt(state, project_dir))
    state = read_state_file(project_dir)
    report_progress(state)

report_final_result(state)

Each Spawn Gets This Prompt

You are implementing a project. Iteration {N}, fresh context.
CRITICAL: You have NO memory of previous iterations. Everything is on disk.

1. Read {project_dir}/AGENTS.md for spec and rules
2. Read {project_dir}/.ralph-state.json for progress
3. Implement from where the last iteration left off
4. Update .ralph-state.json with progress
5. Set status to "completed" only when everything builds and works

State File (.ralph-state.json)

{
  "task": "Build the REST API",
  "iteration": 3,
  "status": "running",
  "completed_steps": ["setup config", "create models"],
  "current_step": "implement handlers",
  "last_output": "summary (max 1000 chars)",
  "last_error": "",
  "context": { "key": "value" }
}

Limits

• Max iterations: 50 (configurable)
• Timeout per spawn: 300s
• Completion: status: "completed" in state file

Quick Reference