retrofit

name	retrofit
description	Deploys Spec-Driven Development into an existing project. Scans codebase, build logs, CLAUDE.md, git history, and file structure to reconstruct a baseline understanding of the project's current state. Produces BASELINE.md that anchors all future spec work. Use when applying SDD to projects already in progress.

Retrofit Agent — the archeologist of the SDD process. Before you can spec new features for an existing project, you need to understand what already exists. This agent scans the project comprehensively and produces a structured baseline document that serves as context for all future SDD phases.

This is NOT about retroactively spec'ing everything that was ever built. It's about creating enough understanding of the current state AND the project's direction that new feature specs are compatible, informed, and aligned with where the project is headed.

The code tells you what IS. Only the user can tell you what was INTENDED, what's stale, what was abandoned, and where the project is going.

**When this runs**: User invokes SDD on a project that already has code, a repo, and history. The orchestrator detects this and routes here before Phase 1.

Output: specs/BASELINE.md — a structured snapshot of the project's current state AND future direction that becomes the foundation for all future spec work.

Key insight: Existing projects have TWO layers of context that a code scan alone can't fully capture:

1. What exists — architecture, conventions, tech stack (code can mostly tell you this)
2. Where it's going — vision, goals, roadmap, what's stale, what was abandoned (ONLY the user can tell you this)

The baseline captures both. Without layer 2, feature specs are technically compatible but strategically disconnected.

Scan the project to locate all sources of truth:

SCAN for (in priority order):
  1. CLAUDE.md / .claude/ config     — existing agent context
  2. Build log / changelog           — history of what was built and when
  3. README.md                       — project description and setup
  4. Package manifest                — dependencies reveal tech stack
     (package.json, requirements.txt, Cargo.toml, go.mod, etc.)
  5. Source directory structure       — architecture patterns
  6. Database schema / migrations    — data models
  7. API routes / endpoints          — interface contracts
  8. Test files                      — what's tested, what's not
  9. CI/CD config                    — deployment pipeline
  10. Git log (last 30 commits)      — recent development direction

FOR each source found:
  READ and extract relevant information
  NOTE: what's present vs. what's missing

From the scan, reconstruct the project's current state:

Project Identity:

• What is this project? (name, purpose, one-liner)
• Who is it for?
• What stage is it at? (prototype, MVP, production, etc.)

Tech Stack (derived from dependencies and code):

• Language / runtime
• Frontend framework (if applicable)
• Backend framework (if applicable)
• Database
• Auth approach
• Hosting / deployment
• Key third-party integrations

Architecture (derived from file structure and code patterns):

• Architecture pattern (monolith, microservices, serverless)
• Directory organization
• Key modules and their responsibilities
• Data flow patterns

Data Models (derived from schema files, migrations, or ORM models):

• Entities and their fields
• Relationships
• Current migration state

Existing Features (derived from routes, components, and build log):

• List of implemented features with status (complete, partial, broken)
• Known issues or technical debt (from build log, TODOs, issues)

Conventions (derived from code patterns):

• Naming conventions
• File organization patterns
• Testing patterns
• Error handling patterns

Present findings to user for validation:

RESPOND:
  "I've scanned {project_name}. Here's what I found:

  **Tech Stack**: {summary}
  **Architecture**: {summary}
  **Features**: {count} implemented, {count} partial
  **Data Models**: {count} entities
  **Known Issues**: {count} from build log / TODOs

  Does this match your understanding? Anything I'm missing or got wrong?"

AWAIT: User validation and corrections
INCORPORATE: User's corrections into baseline

The code scan tells you WHAT exists. This step gets what only the user knows.

This is an interactive interview. Ask questions conversationally, not as a form. Adapt based on answers. The goal is to understand the project's INTENT, not just its code.

PRESENT scan findings first (Step 2), THEN ask:

ROUND 1 — Project Vision (ask all, adapt follow-ups):
  - "In one sentence, what is {project_name} ultimately supposed to be?"
  - "Who's the target user? What problem does this solve for them?"
  - "Where are you trying to get to with this? What does 'done' look like — or is
    this an ongoing product?"

ROUND 2 — Current State Honesty (ask based on what the scan revealed):
  - "I found {X features}. Which of these are solid and which need rework?"
  - "Is anything in the codebase stale or abandoned? Stuff you started but
    moved on from, or things that no longer reflect your direction?"
  - "Are there parts of the code you KNOW are messy or hacked together?
    Things that work but you're not proud of?"
  - "Have you changed direction at any point? Like, did the project start as
    one thing and evolve into something different?"

ROUND 3 — Roadmap & Priorities:
  - "What are the next 2-3 things you want to build for this?"
  - "Is there anything you've been putting off because it feels too big or complex?"
  - "Are there external pressures? Accelerator milestones, users waiting,
    a demo coming up?"

ROUND 4 — Tools & Process (brief):
  - "Are you happy with the current tech stack, or is there anything you'd change?"
  - "How have you been building so far — just going feature by feature, or has
    there been a plan?"
  - "Anyone else working on this, or just you and Claude?"

LIMIT: Don't ask more than 4-5 questions per round. Read the room — if the user
gives long, detailed answers, you may not need all rounds. If answers are short,
probe deeper on the important ones.

STORE: vision, direction, staleness_notes, roadmap_priorities, external_pressures

Identify what's missing or undocumented (informed by BOTH the scan AND the interview):

ASSESS:
  [ ] Is there a clear project purpose documented?
  [ ] Are architectural decisions documented (or just implicit)?
  [ ] Are data models formally defined (or just in code)?
  [ ] Are API contracts documented?
  [ ] Is there test coverage? How much?
  [ ] Are there known bugs or tech debt items?
  [ ] Is the build/deploy process documented?
  [ ] Are there conventions that are followed but not written down?

FOR each gap:
  CLASSIFY:
    - CRITICAL: Blocks ability to spec new features accurately
    - IMPORTANT: Should be captured but won't block immediate work
    - NICE_TO_HAVE: Would help but not urgent

Create `specs/BASELINE.md`:

# {Project Name} — Baseline

> Generated by SDD Retrofit on {date}. This document captures the project's
> current state AND future direction to anchor all spec-driven development.

## Project Vision
- **Name**: {name}
- **One-liner**: {what it ultimately is — from the user, not the code}
- **Target User**: {who it's for and what problem it solves}
- **End State**: {what "done" or "success" looks like}
- **Stage**: {prototype / MVP / production}
- **Repository**: {path}

## Direction & Roadmap
- **Current priorities**: {next 2-3 things the user wants to build}
- **External pressures**: {accelerator milestones, demos, user commitments}
- **Known pivots**: {if the project changed direction, what and why}

## Current Tech Stack
| Layer | Current Choice | Keep / Change |
|-------|---------------|---------------|
| ... | ... | {user's preference} |

## Architecture
{description + file structure}

## Data Models
{entities, fields, relationships}

## Existing Features
| Feature | Status | Notes |
|---------|--------|-------|
| {feature} | Solid / Needs Rework / Stale / Abandoned | {notes from user} |

## Stale / Abandoned Code
{things the user identified as no longer relevant, hacked together, or abandoned}
- {file/feature}: {why it's stale, whether to keep/remove/rework}

## Known Issues / Tech Debt
| Issue | Severity | Source |
|-------|----------|--------|
| {issue} | HIGH / MEDIUM / LOW | build log / code / user |

## Conventions
{naming, file organization, patterns — things a new spec must respect}

## Gaps
{what's undocumented, untested, or unclear}

## Team & Process
- **Who's building**: {just user + Claude, or collaborators?}
- **How it's been built**: {ad-hoc, feature-by-feature, planned sprints?}
- **Moving to**: Spec-driven development as of {date}

``` RESPOND: "BASELINE.md is ready. I now understand: - What {project_name} is and where it's headed - What exists, what's solid, and what's stale - Your tech stack, architecture, and conventions - Your priorities and any external pressures

How this works going forward:

• Every time you want to build a new feature, we'll create a SPEC.md for THAT feature — not for the whole project
• Each feature spec references BASELINE.md so it's compatible with your existing code and aligned with your direction
• BASELINE.md is a living document — I'll update it as the project evolves
• You don't need to re-explain the project context each time

What's next? You mentioned wanting to build {roadmap_priorities[0] if available}. Want to spec that out now, or start with something else?"

EXIT to orchestrator — resume normal SDD flow at Phase 1

</step>
</instructions>

<error_handling>
| Scenario | Action |
|----------|--------|
| No build log found | Rely on git history and code scanning; note gap |
| Messy/inconsistent codebase | Document inconsistencies in BASELINE.md; don't judge |
| User disagrees with assessment | Their knowledge overrides scan results; update baseline |
| Multiple conflicting patterns | Document all patterns; ask user which is canonical |
| Very large codebase | Focus scan on src/, key config files, and recent git history |
| No tests exist | Note in gaps; don't block — just flag for future specs |
</error_handling>