# Reverse-Engineering Framework for Claude Code

A project scaffold for multi-session reverse-engineering projects with Claude Code.
Keeps context coherent across sessions by storing everything in files — not in chat history.

## Quick Start

1. Copy this entire folder to your new project
2. Put your legacy code into `legacy/` (read-only, never modified)
3. Adapt `CLAUDE.md` to your project (update the goal description)
4. Adapt `docs/A_discovery/task.md` to your specific discovery goals
5. Start your first session with `/project:session-start`

## How It Works

The project has three phases, each in its own directory:

| Phase | Directory | Purpose |
|-------|-----------|---------|
| 1 — Discovery | `docs/A_discovery/` | Understand the legacy system |
| 2 — Planning | `docs/B_planning/` | Design the new system |
| 3 — Integration | `docs/C_integration/` | Build and migrate |

Each phase has a `task.md` (what needs to be done) and a `status.md` (where we are).
Decisions are tracked in `docs/B_planning/decisions-log.md` across all phases.

## Session Workflow

**Start a session:** `/project:session-start`
- Claude reads the project state, summarizes it, and asks you for your session goal.

**During a session:** Work normally. Use these as needed:
- `/project:decision` — Record an architectural or process decision
- `/project:new-discovery` — Create a new discovery document from template
- `/project:new-user-story` — Create a new user story from template

**End a session:** `/project:session-end`
- Claude updates status, logs decisions, marks completed tasks, and lists open questions.

**Switch phases:** `/project:phase-transition`
- Only when all Definition-of-Done items in the current phase are checked off.

## User Stories

User stories are created during Phase 2 (Planning) and bridge the gap between
"what the legacy system does" (Discovery) and "what we build" (Integration).

**Creating stories:** Use `/project:new-user-story`. Claude will ask for the role,
the desired capability, and the business value — then generate a story file from template.

**Where they live:** `docs/B_planning/user-stories/US-NNN-short-title.md` — one file per story.

**Numbering:** Stories are numbered sequentially (US-001, US-002, ...). Claude picks the next
free number automatically.

**Each story includes:**
- The story itself (As a ... I want ... so that ...)
- Testable acceptance criteria
- Traceability back to a discovery document or legacy function
- Explicit scope boundaries (what does NOT belong to this story)
- Priority using MoSCoW (Must / Should / Could / Won't)

**When to write them:** After Discovery has produced enough understanding of the legacy system.
Don't write stories before you know what the system actually does — that's what Phase 1 is for.

## Key Principles

- **Project lives in files, not sessions.** Every insight, decision, and status update is written down.
- **Structure before content.** The scaffold exists before any analysis begins.
- **Legacy code is read-only.** The `legacy/` folder is never modified.
- **Templates are read-only.** `docs/templates/` contains structural references, not working documents.
- **Decisions are append-only.** Once logged, entries in `decisions-log.md` are never edited.

## File Overview

```
CLAUDE.md                        — Project memory (Claude reads this first)
README.md                        — You are here
legacy/                          — Legacy code (read-only)
docs/
  A_discovery/                   — Phase 1 working directory
  B_planning/                    — Phase 2 working directory + decisions log
  C_integration/                 — Phase 3 working directory
  templates/                     — Document templates (read-only reference)
rules/                           — Constraints Claude follows automatically
.claude/commands/                — Slash commands for session workflow
```