refactoring framework

.claude/commands/decision.md

@@ -0,0 +1,11 @@
+Erstelle einen neuen Eintrag im Entscheidungsprotokoll.
+
+1. Lies docs/templates/decisions-log-entry.md als Vorlage
+2. Frage den User nach folgenden Informationen (sofern nicht schon aus dem Kontext bekannt):
+   - Was wurde entschieden?
+   - Warum stand diese Entscheidung an?
+   - Welche Alternativen wurden verworfen und warum?
+   - Ist die Entscheidung endgültig oder revisierbar?
+3. Fülle das Template mit den Antworten aus
+4. Füge den Eintrag OBEN in docs/B_planning/decisions-log.md ein (nach dem Header)
+5. Bestehende Einträge werden NIEMALS verändert

.claude/commands/new-discovery.md

@@ -0,0 +1,9 @@
+Erstelle ein neues Discovery-Dokument.
+
+1. Lies docs/templates/discovery-document.md als Vorlage
+2. Frage den User (sofern nicht aus dem Kontext bekannt):
+   - Welchen Aspekt des Legacy-Systems dokumentiert dieses Dokument?
+   - Wie soll die Datei heißen? (Vorschlag: kebab-case, z.B. domain-model.md)
+3. Erstelle die Datei in docs/A_discovery/ basierend auf dem Template
+4. Setze das Erstelldatum auf heute
+5. Trage einen Querverweis in status.md ein, dass ein neues Dokument angelegt wurde

.claude/commands/phase-transition.md

@@ -0,0 +1,28 @@
+Führe einen Phasenwechsel durch.
+
+## Voraussetzungen prüfen
+1. Lies task.md der aktuellen Phase
+2. Prüfe: Sind ALLE Definition-of-Done-Punkte mit [x] markiert?
+3. Falls nein: Liste die offenen Punkte und frage den User, ob trotzdem gewechselt werden soll
+
+## Phasenwechsel durchführen
+1. Erstelle einen Eintrag in docs/B_planning/decisions-log.md:
+   - Typ: Prozess
+   - Entscheidung: "Phase N abgeschlossen, Wechsel zu Phase N+1"
+   - Offene Punkte aus der alten Phase dokumentieren
+
+2. Neue Phase vorbereiten:
+   - Falls task.md und status.md für die neue Phase noch nicht existieren:
+     Erstelle sie basierend auf docs/templates/status.md
+   - task.md der neuen Phase muss ein Ziel und Definition-of-Done-Punkte enthalten
+   - Frage den User nach dem Ziel und den erwarteten Ergebnissen der neuen Phase
+
+3. CLAUDE.md aktualisieren:
+   - "Aktuelle Phase" auf die neue Phase setzen
+   - "Arbeitsverzeichnis" auf das neue Phasenverzeichnis ändern
+   - "Schreibrechte" anpassen (neue Phase + decisions-log)
+
+4. Zusammenfassung zeigen:
+   - Was wurde in der abgeschlossenen Phase erreicht?
+   - Was ist das Ziel der neuen Phase?
+   - Was sind die ersten Schritte?

.claude/commands/session-end.md

@@ -0,0 +1,23 @@
+Führe den Session-Abschluss durch. Lies zuerst CLAUDE.md um die aktive Phase zu bestimmen, dann:
+
+1. **status.md aktualisieren** — Lies die aktuelle status.md der aktiven Phase und aktualisiere sie:
+   - Erledigtes markieren mit [x]
+   - Aktuellen Stand in 2-3 Sätzen beschreiben
+   - Nächste Schritte auflisten
+   - Offene Fragen / Blocker notieren
+   - Bewusst Ausgeklammertes dokumentieren
+
+2. **Entscheidungen protokollieren** — Falls in dieser Session Entscheidungen getroffen wurden:
+   - Erstelle für jede Entscheidung einen Eintrag nach docs/templates/decisions-log-entry.md
+   - Füge ihn oben in docs/B_planning/decisions-log.md ein
+
+3. **task.md aktualisieren** — Markiere abgeschlossene Definition-of-Done-Punkte mit [x]
+
+4. **Zusammenfassung** — Zeige dem User:
+   - Was wurde in dieser Session erreicht?
+   - Was sind die nächsten Schritte?
+   - Welche offenen Fragen bleiben?
+
+5. **Phase prüfen** — Falls alle DoD-Punkte in task.md erledigt sind:
+   - Weise den User darauf hin, dass ein Phasenwechsel ansteht
+   - Verweise auf den /project:phase-transition Command

.claude/commands/session-start.md

@@ -0,0 +1,18 @@
+Lies folgende Dateien in dieser Reihenfolge, ohne sofort zu handeln:
+1. CLAUDE.md
+2. task.md der aktiven Phase (siehe "Aktiver Scope" in CLAUDE.md)
+3. status.md der aktiven Phase
+4. docs/B_planning/decisions-log.md (nur die letzten 5 Einträge)
+
+Fasse danach in 3-5 Sätzen zusammen:
+- Was ist das Gesamtziel des Projekts?
+- Was ist das Ziel dieser Phase?
+- Was wurde zuletzt erreicht, und wo stehen wir gerade?
+- Was sind bekannte offene Fragen oder Blocker?
+
+Frage dann den User:
+> Was ist dein Ziel für diese Session?
+> Was ist explizit nicht in Scope heute?
+> Welches konkrete Ergebnis (Datei, Dokument, Funktion) soll am Ende stehen?
+
+Warte auf die Antworten, bevor du mit der inhaltlichen Arbeit beginnst.

.claude/settings.local.json

@@ -1,7 +1,9 @@
 {
   "permissions": {
     "allow": [
-      "Skill(review)"
+      "Skill(review)",
+      "Bash(mkdir:*)",
+      "Bash(mv:*)"
     ]
   }
 }

CLAUDE.md

@@ -13,20 +13,65 @@ Der rote Faden war durchgehend: Struktur vor Inhalt. Das Gerüst steht, bevor di
 Liegt in: legacy/
 Regel: Keine Datei in legacy/ wird verändert. Nur lesen.
 
+## Regeln
+@rules/framework-constraints.md
+@rules/session-protocol.md
+
 ## Aktiver Scope
 Aktuelle Phase: 1 — Discovery
 Arbeitsverzeichnis: docs/A_discovery/
-Schreibrechte: docs/A_discovery/**, docs/B_planning/decisions-log.md, 
+Schreibrechte: docs/A_discovery/**, docs/B_planning/decisions-log.md
-               phase-1/status.md
+Keine Änderungen an: src/**, legacy/**, docs/templates/**
-Keine Änderungen an: src/**, legacy/**
 
 ## Konventionen
 - Entscheidungen immer in decisions-log.md eintragen (oben anfügen, nie editieren)
 - Jede Session endet mit aktuellem status.md
 - Offene Fragen explizit notieren, nicht stillschweigend überspringen
 
+## Verzeichnisstruktur
+```
+legacy/                          — Legacy-Code (read-only)
+docs/
+  A_discovery/                   — Phase 1: Analyse des Legacy-Codes
+    task.md                      — Aufgabendefinition & Definition of Done
+    status.md                    — Aktueller Stand (wird jede Session aktualisiert)
+  B_planning/                    — Phase 2: Architektur & Entscheidungen
+    task.md                      — Aufgabendefinition & Definition of Done
+    status.md                    — Aktueller Stand
+    decisions-log.md             — Entscheidungsprotokoll (append-only)
+  C_integration/                 — Phase 3: Umsetzung
+    task.md                      — Aufgabendefinition & Definition of Done
+    status.md                    — Aktueller Stand
+  templates/                     — Vorlagen (read-only, nie direkt editieren)
+rules/                           — Regeln für Claude (automatisch geladen)
+.claude/commands/                — Projekt-Commands (/project:...)
+```
+
+## Workflow-Commands
+- `/project:session-start` — Session beginnen (Kontext laden, Session-Ziel klären)
+- `/project:session-end` — Session abschließen (Status, Entscheidungen, offene Fragen)
+- `/project:decision` — Neue Entscheidung im Log protokollieren
+- `/project:new-discovery` — Neues Discovery-Dokument aus Template anlegen
+- `/project:phase-transition` — Phasenwechsel durchführen (DoD prüfen, CLAUDE.md aktualisieren)
+
 ## Session-Einstieg
+Nutze `/project:session-start` oder manuell:
 1. Diese Datei lesen
-2. phase-N/task.md lesen
+2. task.md der aktiven Phase lesen
-3. phase-N/status.md lesen
+3. status.md der aktiven Phase lesen
-4. Kurze Zusammenfassung, dann auf Bestätigung warten
+4. docs/B_planning/decisions-log.md lesen (letzte 5 Einträge)
+5. Kurze Zusammenfassung, dann Session-Ziel mit dem User klären
+6. Auf Bestätigung warten
+
+## Session-Ende
+Nutze `/project:session-end` oder manuell:
+1. status.md der aktiven Phase aktualisieren
+2. Entscheidungen in docs/B_planning/decisions-log.md eintragen
+3. In task.md abgeschlossene Punkte markieren
+4. Offene Fragen oder nächste Schritte explizit notieren
+
+## Phasenwechsel
+Ein Phasenwechsel erfolgt über `/project:phase-transition` wenn:
+- Alle Definition-of-Done-Punkte in task.md der aktuellen Phase [x] sind
+- Der User den Wechsel bestätigt
+Dabei wird: Decision-Log-Eintrag erstellt, neue Phase vorbereitet, CLAUDE.md aktualisiert.

README.md

@@ -0,0 +1,63 @@
+# 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
+
+**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.
+
+## 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
+```

docs/A_discovery/status.md

@@ -0,0 +1,20 @@
+# Status — Phase 1: Discovery
+
+Letzte Aktualisierung: 2026-03-20
+Session-Nr.: 0
+
+## Erledigtes
+- [x] Projektgerüst erstellt (Verzeichnisstruktur, Templates, CLAUDE.md)
+
+## Aktueller Stand
+Framework steht. Noch kein Legacy-Code analysiert. Bereit für erste Discovery-Session.
+
+## Nächste Schritte
+1. Legacy-Code in legacy/ ablegen
+2. Erste Analyse: domain-model.md beginnen
+
+## Offene Fragen / Blocker
+- Legacy-Code muss noch ins Projekt kopiert werden
+
+## Nicht angefasst (bewusst ausgeklammert)
+- Keine Punkte verschoben

docs/A_discovery/task.md

@@ -14,5 +14,3 @@ die Capabilities und die KI-Kandidaten dokumentiert sind.
 - Architekturentscheidungen für das neue System
 - Embedding- oder KI-Strategie
 - Irgendwelcher neuer Code
-```
-

docs/B_planning/decisions-log.md

@@ -0,0 +1,4 @@
+# Decisions Log
+
+<!-- Neue Einträge oben einfügen. Bestehende Einträge nie editieren. -->
+<!-- Vorlage: docs/templates/decisions-log-entry.md -->

docs/B_planning/status.md

@@ -0,0 +1,20 @@
+# Status — Phase 2: Planung
+
+Letzte Aktualisierung: —
+Session-Nr.: 0
+
+## Erledigtes
+— Phase noch nicht gestartet —
+
+## Aktueller Stand
+Wartet auf Abschluss von Phase 1 (Discovery).
+
+## Nächste Schritte
+1. Phase 1 abschließen
+2. Discovery-Ergebnisse als Input für Architekturentscheidungen nutzen
+
+## Offene Fragen / Blocker
+- Abhängig von Phase 1
+
+## Nicht angefasst (bewusst ausgeklammert)
+- Noch keine

docs/B_planning/task.md

@@ -0,0 +1,15 @@
+# Phase 2 — Planung
+
+## Ziel
+Auf Basis der Discovery-Ergebnisse die Architektur, Technologie-Entscheidungen
+und den Umsetzungsplan für das neue System definieren.
+
+## Ergebnisse (Definition of Done)
+- [ ] docs/B_planning/architecture.md — Systemarchitektur, Komponenten, Schnittstellen
+- [ ] docs/B_planning/tech-stack.md — Technologie-Entscheidungen mit Begründung
+- [ ] docs/B_planning/migration-strategy.md — Wie wird vom alten zum neuen System migriert?
+- [ ] docs/B_planning/implementation-plan.md — Priorisierte Arbeitspakete
+
+## Nicht in Scope
+- Implementierung von Code
+- KI-Modell-Training oder -Evaluation

docs/C_integration/status.md

@@ -0,0 +1,20 @@
+# Status — Phase 3: Umsetzung
+
+Letzte Aktualisierung: —
+Session-Nr.: 0
+
+## Erledigtes
+— Phase noch nicht gestartet —
+
+## Aktueller Stand
+Wartet auf Abschluss von Phase 2 (Planung).
+
+## Nächste Schritte
+1. Phase 2 abschließen
+2. Implementierung gemäß Umsetzungsplan beginnen
+
+## Offene Fragen / Blocker
+- Abhängig von Phase 2
+
+## Nicht angefasst (bewusst ausgeklammert)
+- Noch keine

docs/C_integration/task.md

@@ -0,0 +1,14 @@
+# Phase 3 — Umsetzung
+
+## Ziel
+Das neue System auf Basis der Planungsergebnisse implementieren,
+den Legacy-Code ablösen und die Migration durchführen.
+
+## Ergebnisse (Definition of Done)
+- [ ] Neues System implementiert gemäß Architektur aus Phase 2
+- [ ] Datenmigration durchgeführt und verifiziert
+- [ ] Legacy-Funktionalität vollständig abgedeckt
+- [ ] Dokumentation aktualisiert
+
+## Nicht in Scope
+- Wird in Phase 2 definiert

docs/templates/discovery-document.md

@@ -19,7 +19,7 @@ Wie wurde dieses Wissen gewonnen?
 
 ## Befunde
 
-[Hier der eigentliche Inhalt — struktur je nach Dokumenttyp:]
+[Hier der eigentliche Inhalt — Struktur je nach Dokumenttyp:]
 
 ### [Abschnitt 1]
 ...
@@ -35,8 +35,8 @@ Dinge, die unklar geblieben sind oder nur vermutet werden.
 
 ## Querverweise
 Welche anderen Discovery-Dokumente oder Entscheidungen hängen damit zusammen?
-- docs/discovery/___
+- docs/A_discovery/___
-- docs/planning/decisions-log.md → Eintrag vom ___
+- docs/B_planning/decisions-log.md → Eintrag vom ___
 
 ## Nächste Schritte
 Was muss auf Basis dieses Dokuments als nächstes passieren?

docs/templates/session_end_static.md

@@ -1,5 +1,5 @@
 Am Ende der Session, bevor du aufhörst:
-- Aktualisiere phase-N/status.md mit dem aktuellen Stand
+1. Aktualisiere docs/A_discovery/status.md (bzw. aktive Phase) mit dem aktuellen Stand
-- Trage getroffene Entscheidungen in decisions-log.md ein
+2. Trage getroffene Entscheidungen in docs/B_planning/decisions-log.md ein
-- Markiere in task.md, was abgeschlossen ist
+3. Markiere in task.md der aktiven Phase, was abgeschlossen ist
-- Notiere offene Fragen oder nächste Schritte explizit
+4. Notiere offene Fragen oder nächste Schritte explizit

docs/templates/session_goal_dynamic.md

@@ -1,3 +0,0 @@
-Das Ziel dieser Session ist: [konkrete Aufgabe].
-Nicht in Scope heute: [was du explizit ausklammern willst].
-Ergebnis am Ende soll sein: [konkretes Artefakt — Datei, Funktion, Dokument].

docs/templates/session_start_static.md

@@ -1,9 +1,8 @@
 Lies zunächst diese Dateien in dieser Reihenfolge, ohne sofort zu handeln:
 1. CLAUDE.md
-2. docs/planning/session-plan.md
+2. docs/A_discovery/task.md (bzw. aktive Phase)
-3. docs/planning/decisions-log.md (nur die letzten 5 Einträge)
+3. docs/A_discovery/status.md (bzw. aktive Phase)
-4. phase-N/task.md
+4. docs/B_planning/decisions-log.md (nur die letzten 5 Einträge)
-5. phase-N/status.md
 
 Fasse danach in 3-5 Sätzen zusammen:
 - Was ist das Gesamtziel des Projekts?

docs/templates/status.md

@@ -4,8 +4,8 @@ Letzte Aktualisierung: YYYY-MM-DD
 Session-Nr.: N
 
 ## Erledigtes
-- [ ] Aufgabe A → erledigt, Ergebnis: [Datei/Befund]
+- [x] Aufgabe A → erledigt, Ergebnis: [Datei/Befund]
-- [ ] Aufgabe B → erledigt, Ergebnis: [Datei/Befund]
+- [x] Aufgabe B → erledigt, Ergebnis: [Datei/Befund]
 
 ## Aktueller Stand
 [2-3 Sätze: Wo stehen wir? Was ist der Zwischenstand?]

rules/framework-constraints.md

@@ -0,0 +1,7 @@
+- Never write to legacy/ — read-only, no exceptions
+- Never write to docs/templates/ — read-only, use as reference only
+- Only write to the active phase directory defined in CLAUDE.md "Aktiver Scope"
+- docs/B_planning/decisions-log.md is always writable (append-only, never edit existing entries)
+- Before any file write: verify target path is within allowed scope
+- CLAUDE.md is only modified during phase transitions
+- Never delete or rename existing discovery documents or decision entries

rules/session-protocol.md

@@ -0,0 +1,7 @@
+- Every session starts with the session-start protocol — no content work before context is restored
+- After reading context files: summarize state, then ask for the user's session goal
+- No content work before user confirms the session goal
+- Uncertainties are never silently skipped — log them in status.md or open-questions.md
+- At the end of a session: always ask "Soll ich den Session-Abschluss machen?" before closing
+- Use docs/templates/ as structural reference when creating new documents
+- When all Definition-of-Done items are complete: proactively inform the user that a phase transition is possible