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:

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

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

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

Spec Parsing Guide

How to extract structured requirements from ambiguous, incomplete, or conversational natural-language specifications.

---

Parsing Strategy

Read the full spec once. On the second pass, extract fields into the structured interpretation table. Don't ask questions for anything you can reasonably infer.

Extraction Priority

1. Explicit statements — "Use PostgreSQL", "Build with Next.js" — non-negotiable 2. Strong signals — "users can sign up" implies auth + user model + database 3. Contextual inference — "dashboard" implies web app; "track expenses" implies CRUD + database 4. Defaults — When nothing is specified, pick the most common choice for the domain

---

Ambiguity Resolution

Stack Not Specified

Database Not Specified

Auth Not Specified

---

Common Spec Shapes

Shape 1: Stream of Consciousness

"I want an app where people can post recipes and other people can comment on them and save their favorites, maybe add a rating system too, and it should look nice on mobile"

Extract:

• Features: post recipes, comment, favorites, ratings
• UI: responsive / mobile-friendly
• Implies: auth (users), database (recipes, comments, favorites, ratings), web app

Shape 2: Feature List

"Features: 1. User registration 2. Create projects 3. Invite team members 4. Kanban board 5. File uploads"

Extract:

• Features: numbered list, each gets a route/component
• Auth: yes (registration)
• Database: yes (users, projects, teams, files)
• Complex features: kanban (drag-drop), file uploads (storage)

Shape 3: Technical Spec

"FastAPI backend with PostgreSQL. Endpoints: POST /items, GET /items, GET /items/{id}, PUT /items/{id}, DELETE /items/{id}. Use SQLAlchemy ORM. Add JWT auth."

Extract:

• Stack: explicit (FastAPI, PostgreSQL, SQLAlchemy, JWT)
• API: 5 CRUD endpoints, fully defined
• Minimal inference needed — generate exactly what's asked

Shape 4: Existing PRD

[Multi-page document with overview, user personas, feature requirements, acceptance criteria]

Extract:

• Read the overview first for scope
• Map feature requirements to files
• Use acceptance criteria as test case seeds
• Ignore personas, market analysis, timelines — they don't affect code generation

---

What to Ask vs. What to Infer

Ask (max 3 questions):

• Stack preference when the spec is truly ambiguous and could go multiple ways
• Database choice when both SQL and NoSQL are equally valid
• Deploy target when it materially affects the code (serverless vs. container)

Infer silently:

• Auth method (JWT for APIs, session for web apps)
• Testing framework (most popular for the stack)
• Linter / formatter (stack default)
• CSS approach (Tailwind for React/Next, stack default otherwise)
• Package versions (latest stable)

Never ask:

• "What folder structure do you want?" — use the stack convention
• "Do you want TypeScript?" — yes, always for JS projects
• "Should I add error handling?" — yes, always
• "Do you want tests?" — yes, always

Stack Templates

Quick-reference templates for common tech stacks. Each template defines: file structure, manifest, entry point, and build/run commands.

---

Next.js (TypeScript + Tailwind)

When: Web apps, dashboards, SaaS, landing pages with dynamic content.

Manifest: package.json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "test": "jest"
  }
}

Core deps: next, react, react-dom, tailwindcss, postcss, autoprefixer Auth: next-auth (default) or clerk Database: prisma (ORM) + @prisma/client Testing: jest, @testing-library/react

File structure:

src/app/layout.tsx        — Root layout with providers
src/app/page.tsx          — Homepage
src/app/api/*/route.ts    — API routes
src/components/*.tsx       — Shared components
src/lib/*.ts              — Utilities, DB client
prisma/schema.prisma      — Database schema (if DB)

Config files: tsconfig.json, tailwind.config.ts, next.config.ts, postcss.config.mjs

---

FastAPI (Python)

When: REST APIs, backends, microservices, data-driven services.

Manifest: requirements.txt

fastapi>=0.110.0
uvicorn>=0.29.0
sqlalchemy>=2.0.0
pydantic>=2.0.0
pytest>=8.0.0
httpx>=0.27.0

File structure:

main.py                   — FastAPI app, CORS, lifespan
models.py                 — SQLAlchemy models
schemas.py                — Pydantic schemas
database.py               — Engine, session factory
routers/*.py              — Route modules
tests/test_*.py           — pytest tests

Run: uvicorn main:app --reload Test: pytest

---

Express (TypeScript)

When: Node.js APIs, middleware-heavy backends, real-time services.

Manifest: package.json

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "test": "jest"
  }
}

Core deps: express, cors, dotenv Dev deps: typescript, tsx, @types/express, @types/node, jest, ts-jest

File structure:

src/index.ts              — App setup, middleware, listen
src/routes/*.ts           — Route handlers
src/middleware/*.ts        — Auth, validation, error handling
src/models/*.ts           — Data models / ORM entities
src/lib/*.ts              — Utilities
tests/*.test.ts           — Jest tests

---

Go (net/http or Gin)

When: High-performance APIs, CLI tools, systems programming.

Manifest: go.mod

File structure (API):

main.go                   — Entry point, router setup
handlers/*.go             — HTTP handlers
models/*.go               — Data structs
middleware/*.go            — Auth, logging
db/*.go                   — Database connection
*_test.go                 — Table-driven tests

File structure (CLI):

main.go                   — Entry point, flag parsing
cmd/*.go                  — Subcommands
internal/*.go             — Business logic
*_test.go                 — Tests

Run: go run . Test: go test ./... Build: go build -o app .

---

Rust (Actix-web or Axum)

When: High-performance, safety-critical APIs, systems.

Manifest: Cargo.toml

File structure:

src/main.rs               — Entry point, server setup
src/routes/*.rs           — Route handlers
src/models/*.rs           — Data structs, serde
src/db.rs                 — Database pool
src/error.rs              — Error types
tests/*.rs                — Integration tests

Run: cargo run Test: cargo test

---

Flutter (Dart)

When: Cross-platform mobile apps (iOS + Android).

Manifest: pubspec.yaml

File structure:

lib/main.dart             — Entry point, MaterialApp
lib/screens/*.dart        — Screen widgets
lib/widgets/*.dart        — Reusable components
lib/models/*.dart         — Data classes
lib/services/*.dart       — API clients, storage
lib/providers/*.dart      — State management
test/*_test.dart          — Widget tests

Run: flutter run Test: flutter test

---

Rails (Ruby)

When: Full-stack web apps, CRUD-heavy applications, rapid prototyping.

Manifest: Gemfile

File structure: Standard Rails conventions (app/, config/, db/, spec/).

Run: bin/rails server Test: bin/rspec

---

Django (Python)

When: Full-stack Python web apps, admin-heavy apps, content management.

Manifest: requirements.txt

django>=5.0
djangorestframework>=3.15
pytest-django>=4.8

File structure:

manage.py
config/settings.py        — Settings
config/urls.py            — Root URL config
apps/<name>/models.py     — Models
apps/<name>/views.py      — Views or ViewSets
apps/<name>/serializers.py — DRF serializers
apps/<name>/urls.py       — App URL config
tests/test_*.py

Run: python manage.py runserver Test: pytest

---

CI Template (.github/workflows/ci.yml)

Adapt per stack:

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup [runtime]
        uses: actions/setup-[runtime]@v5
        with:
          [runtime]-version: '[version]'
      - name: Install
        run: [install command]
      - name: Lint
        run: [lint command]
      - name: Test
        run: [test command]
      - name: Build
        run: [build command]

---

.gitignore Essentials by Stack

All stacks: .env, .DS_Store, *.log, IDE folders (.idea/, .vscode/)