# 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.

## Batch-Modus: Mehrere Tasks automatisiert abarbeiten

Wenn die nächsten Schritte bereits geplant sind (z.B. Discovery-Waves, User Stories schreiben, Module analysieren), erspart der Batch-Modus den manuellen Session-Zyklus:

```
Vorher:  session-start → Aufgabe → session-end → clear → commit → repeat (pro Task)
Nachher: /project:run-batch → N Tasks laufen durch → Review → fertig
```

### So funktioniert's

**Starten:** `/project:run-batch` oder natürlichsprachlich ("Arbeite die nächsten 3 Tasks ab").

Claude liest die `task.md` der aktiven Phase, zeigt die offenen Tasks, und fragt nach:
- **Welche Tasks?** — alle, bestimmte Nummern, oder eine Gruppe
- **Checkpoint-Modus?** — wann soll für Review pausiert werden

### Checkpoint-Modi

| Modus | Verhalten | Wann verwenden |
|-------|-----------|----------------|
| `after-each` (Standard) | Pause nach jeder Gruppe, Zusammenfassung zeigen | Neue/unsichere Tasks |
| `after-batch:N` | N Gruppen durchlaufen, dann pausieren | "Mach 3, dann schau ich" |
| `at-end` | Alles durchlaufen, am Ende Review | Gut verstandene Tasks |

### Parallelisierung

Tasks sind in `task.md` unter `###`-Überschriften gruppiert:
- Tasks **unter dem gleichen Heading** laufen **parallel** (z.B. 3 Module gleichzeitig)
- **Zwischen Gruppen** wird **sequenziell** gearbeitet (Wave 2 wartet auf Wave 1)

### Was passiert im Hintergrund

1. Pro Task wird ein **Subagent** mit frischem Context gestartet
2. Jeder Subagent schreibt sein Ergebnis in eine **eigene Output-Datei**
3. Die Output-Dateien sind sofort in VS Code sichtbar — du kannst sie während des Laufs beobachten
4. Am **Checkpoint** zeigt Claude eine Tabelle mit Status und Zusammenfassung pro Task
5. Du entscheidest: `weiter`, `stopp`, oder `zeig mir [datei]`
6. Am Ende: Claude aktualisiert task.md, status.md und decisions-log.md und schlägt einen Commit vor

### Sicherheitsregeln

- **Phasengrenze ist ein harter Stopp** — der Batch läuft nie automatisch in die nächste Phase
- **Fehlgeschlagene Tasks** bleiben offen (`[ ]`) und werden beim Checkpoint gemeldet
- **Ohne bestätigte Parameter** startet kein Batch — Claude fragt immer nach

### Beispiel

```
Du: /project:run-batch

Claude: Ich sehe 5 offene Tasks in Phase 1 — Discovery:
  1. [ ] structure-map.md (Wave 1)
  2. [ ] entry-points.md (Wave 2)
  3. [ ] Module: auth (Wave 3)
  4. [ ] Module: invoicing (Wave 3)
  5. [ ] Module: reporting (Wave 3)

  Welche Tasks? (alle / Nummern / Gruppe)
  Checkpoint-Modus? (after-each / after-batch:N / at-end)

Du: alle, after-each

Claude: [dispatcht Wave 1 → Checkpoint → Wave 2 → Checkpoint → Wave 3 parallel → Checkpoint]
Claude: Batch abgeschlossen. 5/5 erfolgreich. Soll ich committen?
```

### Permissions

Damit der Batch nicht an Berechtigungsdialogen hängen bleibt, müssen die nötigen
Tools in `.claude/settings.json` freigeschaltet sein. Das Projekt enthält bereits
eine passende Konfiguration. Falls nicht vorhanden:

```json
{ "permissions": { "allow": ["Read", "Write", "Edit", "Glob", "Grep", "Agent"] } }
```

## 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
  batch-orchestration.md         — Rules for batch/subagent execution
.claude/commands/                — Slash commands for session workflow
  run-batch.md                   — Batch orchestrator command
.claude/settings.json            — Project-level tool permissions
```


# Remakrs

## How to use it?
Der Ablauf wäre:
1. Session 1: Legacy-Code ins Projekt, CLAUDE.md anpassen, task.md der Phase 1 mit ersten DoD-Punkten füllen
2. Session 2-N: Discovery-Arbeit — je ein DoD-Punkt pro Session (oder mehrere kleine)
3. Wenn alle DoD-Punkte ✅: Phasenwechsel zu Phase 2

Das Session-Protokoll ist kein Extra-Overhead für spezielle Anlässe — es ist der Standardrhythmus für jede Sitzung. Es stellt sicher, dass:
- Der Kontext vom letzten Mal wiederhergestellt wird
- Am Ende nichts verloren geht
- Entscheidungen dokumentiert werden
                                                                                                                                                                                                                                      
Die task.md muss auch nicht in Session 1 perfekt sein. Du kannst mit 2-3 DoD-Punkten starten und sie in späteren Sessions erweitern, wenn du den Legacy-Code besser verstehst.

Kurz: Jede Interaktion = eine Session. Das Protokoll ist der Herzschlag des Frameworks, nicht ein Sonderereignis.

## Wann Session-Workflow, wann Batch?

| Situation | Empfehlung |
|-----------|------------|
| Erkundend, unklar was als nächstes kommt | `/project:session-start` → manuell arbeiten |
| Nächste Schritte klar, Tasks in task.md definiert | `/project:run-batch` |
| Ein einzelner, klar definierter Task | Manuell oder Batch mit einem Item |
| Viele unabhängige Module analysieren | Batch mit Parallelisierung |

Der Batch-Modus ergänzt den Session-Workflow — er ersetzt ihn nicht grundsätzlich.
Für explorative Arbeit bleibt der manuelle Zyklus der richtige Ansatz.