spec-to-repo

Spec to Repo

Turn a natural-language project specification into a complete, runnable starter repository. Not a template filler — a spec interpreter that generates real, working code for any stack.

When to Use

• User provides a text description of an app and wants code
• User has a PRD, requirements doc, or feature list and needs a codebase
• User says "build me an app that...", "scaffold this", "bootstrap a project"
• User wants a working starter repo, not just a file tree

Not this skill when the user wants a SaaS app with Stripe + Auth specifically — use product-team/saas-scaffolder instead.

Core Workflow

Phase 1 — Parse & Interpret

Read the spec. Extract these fields silently:

Field	Source	Required
App name	Explicit or infer from description	yes
Description	First sentence of spec	yes
Features	Bullet points or sentences describing behavior	yes
Tech stack	Explicit ("use FastAPI") or infer from context	yes
Auth	"login", "users", "accounts", "roles"	if mentioned
Database	"store", "save", "persist", "records", "schema"	if mentioned
API surface	"endpoint", "API", "REST", "GraphQL"	if mentioned
Deploy target	"Vercel", "Docker", "AWS", "Railway"	if mentioned

Stack inference rules (when user doesn't specify):

Signal	Inferred stack
"web app", "dashboard", "SaaS"	Next.js + TypeScript
"API", "backend", "microservice"	FastAPI (Python) or Express (Node)
"mobile app"	Flutter or React Native
"CLI tool"	Go or Python
"data pipeline"	Python
"high performance", "systems"	Rust or Go

After parsing, present a structured interpretation back to the user:

## Spec Interpretation

**App:** [name]
**Stack:** [framework + language]
**Features:**
1. [feature]
2. [feature]

**Database:** [yes/no — engine]
**Auth:** [yes/no — method]
**Deploy:** [target]

Does this match your intent? Any corrections before I generate?

Flag ambiguities. Ask at most 3 clarifying questions. If the user says "just build it", proceed with best-guess defaults.

Phase 2 — Architecture

Design the project before writing any files:

1. Select template — Match to a stack template from references/stack-templates.md
2. Define file tree — List every file that will be created
3. Map features to files — Each feature gets at minimum one file/component
4. Design database schema — If applicable, define tables/collections with fields and types
5. Identify dependencies — List every package with version constraints
6. Plan API routes — If applicable, list every endpoint with method, path, request/response shape

Present the file tree to the user before generating:

project-name/
├── README.md
├── .env.example
├── .gitignore
├── .github/workflows/ci.yml
├── package.json / requirements.txt / go.mod
├── src/
│   ├── ...
├── tests/
│   ├── ...
└── ...

Phase 3 — Generate

Write every file. Rules:

• Real code, not stubs. Every function has a real implementation. No // TODO: implement or pass placeholders.
• Syntactically valid. Every file must parse without errors in its language.
• Imports match dependencies. Every import must correspond to a package in the manifest (package.json, requirements.txt, go.mod, etc.).
• Types included. TypeScript projects use types. Python projects use type hints. Go projects use typed structs.
• Environment variables. Generate .env.example with every required variable, commented with purpose.
• README.md. Include: project description, prerequisites, setup steps (clone, install, configure env, run), and available scripts/commands.
• CI config. Generate .github/workflows/ci.yml with: install, lint (if linter in deps), test, build.
• .gitignore. Stack-appropriate ignores (node_modules, pycache, .env, build artifacts).

File generation order:

1. Manifest (package.json / requirements.txt / go.mod)
2. Config files (.env.example, .gitignore, CI)
3. Database schema / migrations
4. Core business logic
5. API routes / endpoints
6. UI components (if applicable)
7. Tests
8. README.md

Phase 4 — Validate

After generation, run through this checklist:

• Every imported package exists in the manifest
• Every file referenced by an import exists in the tree
• .env.example lists every env var used in code
• .gitignore covers build artifacts and secrets
• README has setup instructions that actually work
• No hardcoded secrets, API keys, or passwords
• At least one test file exists
• Build/start command is documented and would work

Run scripts/validate_project.py against the generated directory to catch common issues.

Examples

Example 1: Task Management API

Input spec:

"Build me a task management API. Users can create, list, update, and delete tasks. Tasks have a title, description, status (todo/in-progress/done), and due date. Use FastAPI with SQLite. Add basic auth with API keys."

Output file tree:

task-api/
├── README.md
├── .env.example              # API_KEY, DATABASE_URL
├── .gitignore
├── .github/workflows/ci.yml
├── requirements.txt          # fastapi, uvicorn, sqlalchemy, pytest
├── main.py                   # FastAPI app, CORS, lifespan
├── models.py                 # SQLAlchemy Task model
├── schemas.py                # Pydantic request/response schemas
├── database.py               # SQLite engine + session
├── auth.py                   # API key middleware
├── routers/
│   └── tasks.py              # CRUD endpoints
└── tests/
    └── test_tasks.py         # Smoke tests for each endpoint

Example 2: Recipe Sharing Web App

Input spec:

"I want a recipe sharing website. Users sign up, post recipes with ingredients and steps, browse other recipes, and save favorites. Use Next.js with Tailwind. Store data in PostgreSQL."

Output file tree:

recipe-share/
├── README.md
├── .env.example              # DATABASE_URL, NEXTAUTH_SECRET, NEXTAUTH_URL
├── .gitignore
├── .github/workflows/ci.yml
├── package.json              # next, react, tailwindcss, prisma, next-auth
├── tailwind.config.ts
├── tsconfig.json
├── next.config.ts
├── prisma/
│   └── schema.prisma         # User, Recipe, Ingredient, Favorite models
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx          # Homepage — recipe feed
│   │   ├── recipes/
│   │   │   ├── page.tsx      # Browse recipes
│   │   │   ├── [id]/page.tsx # Recipe detail
│   │   │   └── new/page.tsx  # Create recipe form
│   │   └── api/
│   │       ├── auth/[...nextauth]/route.ts
│   │       └── recipes/route.ts
│   ├── components/
│   │   ├── RecipeCard.tsx
│   │   ├── RecipeForm.tsx
│   │   └── Navbar.tsx
│   └── lib/
│       ├── prisma.ts
│       └── auth.ts
└── tests/
    └── recipes.test.ts

Example 3: CLI Expense Tracker

Input spec:

"Python CLI tool for tracking expenses. Commands: add, list, summary, export-csv. Store in a local SQLite file. No external API."

Output file tree:

expense-tracker/
├── README.md
├── .gitignore
├── .github/workflows/ci.yml
├── pyproject.toml
├── src/
│   └── expense_tracker/
│       ├── __init__.py
│       ├── cli.py            # argparse commands
│       ├── database.py       # SQLite operations
│       ├── models.py         # Expense dataclass
│       └── formatters.py     # Table + CSV output
└── tests/
    └── test_cli.py

Anti-Patterns

Anti-pattern	Fix
Placeholder code — // TODO: implement, pass, empty function bodies	Every function has a real implementation. If complex, implement a working simplified version.
Stack override — picking Next.js when the user said Flask	Always honor explicit tech preferences. Only infer when the user doesn't specify.
Missing .gitignore — committing node_modules or .env	Generate stack-appropriate .gitignore as one of the first files.
Phantom imports — importing packages not in the manifest	Cross-check every import against package.json / requirements.txt before finishing.
Over-engineering MVP — adding Redis caching, rate limiting, WebSockets to a v1	Build the minimum that works. The user can iterate.
Ignoring stated preferences — user says "PostgreSQL" and you generate MongoDB	Parse the spec carefully. Explicit preferences are non-negotiable.
Missing env vars — code reads process.env.X but .env.example doesn't list it	Every env var used in code must appear in .env.example with a comment.
No tests — shipping a repo with zero test files	At minimum: one smoke test per API endpoint or one test per core function.
Hallucinated APIs — generating code that calls library methods that don't exist	Stick to well-documented, stable APIs. When unsure, use the simplest approach.

Validation Script

scripts/validate_project.py

Checks a generated project directory for common issues:

# Validate a generated project
python3 scripts/validate_project.py /path/to/generated-project

# JSON output
python3 scripts/validate_project.py /path/to/generated-project --format json

Checks performed:

• README.md exists and is non-empty
• .gitignore exists
• .env.example exists (if code references env vars)
• Package manifest exists (package.json, requirements.txt, go.mod, Cargo.toml, pubspec.yaml)
• No .env file committed (secrets leak)
• At least one test file exists
• No TODO/FIXME placeholders in generated code

Progressive Enhancement

For complex specs, generate in stages:

1. MVP — Core feature only, working end-to-end
2. Auth — Add authentication if requested
3. Polish — Error handling, validation, loading states
4. Deploy — Docker, CI, deploy config

Ask the user after MVP: "Core is working. Want me to add auth/polish/deploy next, or iterate on what's here?"

Cross-References

• Related: product-team/saas-scaffolder — SaaS-specific scaffolding (Next.js + Stripe + Auth)
• Related: engineering/spec-driven-workflow — spec-first development methodology
• Related: engineering/database-designer — database schema design patterns
• Related: engineering-team/senior-fullstack — full-stack implementation patterns