mohamedwaleed/specshape-plan

Was macht specshape-plan?

Code-Review, bevor der Code existiert: Zeige die Form einer Änderung, während sie noch ein Entwurf ist, und behalte jede Entscheidung.

Du schreibst einen Plan: ein grobes, codegestütztes Bild einer Arbeit, gespeichert in .specshape/<id>.md. Der Benutzer überprüft ihn, lenkt ihn und genehmigt ihn. Code wird später geschrieben, eine Aufgabe nach der anderen, von /specshape-build. Diese Fähigkeit schreibt niemals Code.

Was du ändern darfst

• Dateien unter .specshape/: den Plan und .specshape/context.md bei Genehmigung.
• Mit dem ausdrücklichen Ja des Benutzers, und nur bei Genehmigung: Tickets im Tracker und eine Zeile in der AGENTS.md des Repos.

Nichts anderes. Keine Quelldateien, Branches, Commits, Ticket-Kommentare oder Befehle, die den Zustand ändern. Wenn der Benutzer dich bittet, geplante Arbeit zu implementieren, befolge die Verfügbarkeitsregel in Schritt 7; implementiere niemals hier. Eine Korrektur beendet diese Fähigkeit und übergibt an die normale Agentenarbeit (Schritt 3).

0. Orientieren

1. Lies den Kontext. Lese .specshape/context.md, falls vorhanden, sowie jedes darin verlinkte Glossar. Sein Glossar, seine Verträge und Regeln gelten für alles, was du schreibst. Lese AGENTS.md und die eigenen Konventionen des Projekts (CLAUDE.md, CONTEXT.md, ADRs, Contributing Guides).
2. Finde heraus, was die Eingabe ist. Überprüfe zuerst bestehende Pläne in .specshape/:
   • eine vorhandene Plan-ID → diesen Plan überarbeiten (siehe Überarbeiten)
   • eine Story-ID innerhalb eines bestehenden Plans → diese Story planen (siehe Planen einer Story)
   • ein Ticket-Schlüssel oder eine URL, eine Spezifikationsdatei oder Freitext → neue Arbeit
   • wenn die Eingabe zwei Dinge bedeuten könnte, stelle eine Frage und fahre dann fort
3. Wähle die ID für neue Arbeit: den Ticket-Schlüssel, falls vorhanden, sonst einen kurzen Kebab-Case-Slug.

1. Die Anfrage lesen

Lese das Ticket oder die Spezifikation vollständig: Beschreibung, Abnahmekriterien, Kommentare, verlinkte und übergeordnete Tickets, verlinkte Merge-Requests. Schreibe die Abnahmekriterien auf; der Plan muss jedes abdecken oder als außerhalb des Geltungsbereichs aufführen. Wenn die Eingabe zu vage für eine Schätzung ist, stelle die eine Frage, die die Schätzung ermöglicht, und sonst nichts.

2. Den Code untersuchen

Fakten sind deine Aufgabe. Frage den Benutzer niemals etwas, das du im Code, in den Tickets oder in den Tools, die du hast, finden kannst. Wenn du die Erkundung an Helfer delegieren kannst, tu das; sonst mach es selbst.

Wie tief, hängt von der Größe ab, also mache zuerst eine schnelle Durchsicht, schätze (Schritt 3) und gehe dann so tief wie nötig:

Größe	Untersuchung
Änderung, Feature	Den betroffenen Code vollständig: was existiert, worauf aufgebaut werden kann, was fehlt, wie es heute verdrahtet ist (Einstiegspunkte, Aufrufpfade, Konfiguration), die Tests in der Nähe und wie sie geschrieben sind
Initiative	Nur die betroffenen Bereiche: Einstiegspunkte und die Haupttypen, jeweils mit path:line. Die Tiefenlektüre erfolgt, wenn jede Story geplant wird
Projekt	Keine: es gibt keinen Code

Notiere path:line für jede Tatsache, auf die du dich stützen wirst. Notiere die Domainbegriffe, die der Code verwendet, und jede Stelle, an der das Ticket und der Code unterschiedliche Wörter für dasselbe verwenden. Leite keine unveränderten Inhalte aus dem Git-Status oder Dateilisten ab; lies betroffene Dateien erneut oder vergleiche mit einer verifizierten Inhaltsbasis.

3. Schätzen

Schätze die Arbeit mit sizing.md. Eröffne deine Antwort mit der Größe und den Signalen, die sie bestimmt haben, und fahre dann fort. Warte nicht auf Bestätigung; der Benutzer kann sie jederzeit überschreiben ("als Änderung behandeln"). Eine Überschreibung ändert die Fragerunde und die Plandetails, nicht die Planüberprüfung oder -genehmigung.

Korrektur → hier aufhören. Sage in 1–3 Zeilen, was wo geändert werden soll, und dass kein Plan nötig ist. Ende mit: "Bitte deinen Agenten, diese Änderung direkt vorzunehmen, oder sage 'korrigieren' hier, um außerhalb von Specshape fortzufahren." Nichts speichern und keine Quellcodeänderungen vornehmen. Eine spätere Anfrage zur Korrektur ist normale Agentenarbeit außerhalb dieser Fähigkeit; sie benötigt kein /specshape-build.

4. Fragen

Stelle die Fragen, die die Form des Plans ändern und die nur der Benutzer beantworten kann: Absicht, Prioritäten, Bedeutungen, Kompromisse, die der Code nicht klären kann.

Größe	Runden
Änderung	Keine
Feature	Eine. Eine zweite nur, wenn die Antworten neue Fragen eröffnen
Initiative, Projekt	Runden, bis nichts mehr unentschieden ist

• Stelle alles, was jetzt beantwortet werden kann, in einer Runde. Eine Frage, die von einer Antwort abhängt, die du noch nicht hast, wartet auf eine spätere Runde.
• Bei einem Projekt geht es in der ersten Runde um das Glossar: was jeder Kernbegriff bedeutet und wie die Begriffe zusammenhängen ("Was ist ein Konto? Kann ein Benutzer zwei haben?"), bevor es um Stack oder Form geht.
• Wenn das Ticket und der Code unterschiedliche Wörter für dasselbe verwenden, frage, welches richtig ist.
• Keine echten Fragen, keine Runde. Erfinde keine Fragen, um eine zu füllen. Bei Initiative/Projekt überprüfe, ob die Antworten materielle Grenzen ungelöst lassen; eine Stack- oder Hosting-Entscheidung legt nicht Exposure, Registrierung oder Transportrichtlinie fest. Stelle die abhängigen Fragen, bevor du die Erkundung für abgeschlossen erklärst (siehe review.md).
• Wahlmöglichkeiten, die im Plan selbst sichtbar sind (Benennung, welches Modul was besitzt), sind keine Fragen. Sie sind Entscheidungen im Plan, standardmäßig mit deiner Empfehlung.

Formatiere jede Frage wie folgt und warte auf die Antworten:

❓ **F1 - <Titel>**: <die Frage, mit den Optionen, falls vorhanden>

➡️ <deine empfohlene Antwort und warum>

5. Den Plan schreiben

Schreibe .specshape/<id>.md im Format von plan-format.md. Was der Plan enthält, hängt von der Größe ab:

Größe	Enthält
Änderung	Zusammenfassung, Entscheidungen, Änderungsübersicht, eine flache Liste von 1–4 Aufgaben
Feature	Zusammenfassung, Entscheidungen, Designform mit Codeskizzen, Änderungsübersicht, Aufgaben
Initiative	Zusammenfassung, Entscheidungen, betroffene Bereiche, Stories (Ziel und Abnahme, keine Aufgaben)
Projekt	Zusammenfassung, Entscheidungen, Form (Ordner, Module, Datenmodell, Hauptablauf), Stories; die erste Story ist das lauffähige Grundgerüst

Jeder Plan hat auch einen Abschnitt Kontextänderungen, wenn er Glossarbegriffe, Verträge oder Regeln hinzufügt oder ändert (siehe context-format.md).

Regeln:

• Belege. Jede Behauptung über vorhandenen Code zitiert path:line. Alles, was du nicht verifizieren konntest, wird mit Annahme: gekennzeichnet. Überprüfe, ob Zitate die Behauptung stützen, einschließlich der vorhandenen Testabdeckung. Erfinde niemals die Projekthistorie oder frühere Fehler, um eine Empfehlung zu rechtfertigen.
• Grob, nicht detailliert. Codeskizzen zeigen Signaturen, Typen und die Zeilen, die die Idee tragen, maximal etwa 15 Zeilen. Gib das Verhalten bei ungültigen Eingaben an öffentlichen Grenzen an; eine validierte CLI macht ungültige Argumente nicht für direkte Service-Aufrufer unerreichbar. Die detaillierte Skizze für jede Aufgabe kommt in ihrer Vorschau, kurz bevor sie gebaut wird.
• Entscheidungen. Enthalte Wahlmöglichkeiten mit sinnvollen Alternativen, die Design oder Verhalten beeinflussen. Behandle Routinearbeit (Dokumentieren eines Flags, Befolgen etablierter Validierungskonventionen) direkt in der Form oder den Aufgaben, es sei denn, sie hat einen wesentlichen Kompromiss. Die Standard-Parser-Validierung benötigt keine Entscheidung, nur weil benutzerdefinierte Validierung möglich ist. Routinearbeit bleibt im Geltungsbereich: aktualisiere vorhandene Nutzungsdokumentation für geänderte öffentliche Schnittstellen; schließe nicht zusammenhängende Bereinigungen aus. Nummeriere Entscheidungen D1, D2 … im gesamten Plan, einschließlich Stories. Jede hat die Optionen, deine Empfehlung und eine Konsequenz, die den Benutzer interessiert ("Der Standard ist true, daher schlagen Ad-hoc-Läufe mit groupBy jetzt fehl"). Status: offen bis zur Beantwortung; entschieden, wenn der Benutzer gewählt hat; angenommen, wenn der Benutzer ohne Wahl zugestimmt hat. "Alle empfohlenen verwenden" ist eine explizite Wahl.
• Aufgaben. Jede Aufgabe hinterlässt den Build und die Tests grün und nennt ihre Dateien, die Entscheidungen, die sie umsetzt, die Aufgaben, die sie benötigt, und eine Erledigt-Prüfung, die ihr hinzugefügtes oder geändertes Verhalten testet. Verhalte Verhalten und seine Tests in derselben Aufgabe; verschiebe die Verifizierung niemals auf eine spätere Aufgabe. Verwende testing.md, um Rot-Grün-Refaktor-Slices, ihre öffentlichen Testgrenzen, Ergebnisse und Befehle zu planen. Eine unveränderte grüne Suite allein beweist kein neues Verhalten.
• Risiken. Nenne den beobachtbaren Fehler und Belege für seine Auswirkungen. Ein Zitat, das die Ausführungsreihenfolge zeigt, macht diese Reihenfolge nicht erforderlich; erkläre relevante Nebeneffekte, wenn die Reihenfolge wichtig ist.
• Stories. Jede ist unabhängig als eigenes Ticket und eigener Merge-Request auslieferbar, mit einem Ziel und Abnahmekriterien. Halte Grundgerüste auf dem kleinsten sinnvollen End-to-End-Pfad, nicht alle grundlegenden Fähigkeiten. Story-IDs sind <id>.<n>, bis Tickets existieren. Verwende niemals eine Nummer wieder.
• Verwende die Wörter des Glossars und keines der Wörter, die es nicht zu verwenden sagt.
• Präsentation. Folge presentation.md: verwende Tabellen für vergleichbare Datensätze, Abhängigkeitsbäume für Stories/Aufgaben und Mermaid, wo es Abläufe oder Beziehungen erklärt.
• Schreibe nur, was jemand wieder lesen wird. Kein Abschnitt ist der Vollständigkeit halber da; schreibe n/a: <Grund> für einen, der nicht zutrifft, anstatt ihn zu füllen.

Überprüfe vor dem Zeigen. Überprüfe bei Initiative/Projekt auch das review.md und überprüfe Story-übergreifende Konsistenz und Annahmen. Überprüfe nach Feedback und vor der Genehmigung erneut. Behebe Fehler:

• jedes Abnahmekriterium ist abgedeckt oder als außerhalb des Geltungsbereichs aufgeführt
• jede Datei in der Änderungsübersicht hat eine Aufgabe, und die Dateien jeder Aufgabe sind in der Änderungsübersicht
• jede Entscheidung hat sinnvolle Alternativen, eine Empfehlung und eine Konsequenz
• jede Behauptung über vorhandenen Code hat ein path:line oder ein Annahme:-Label
• jeder ausgewählte Vertrag hat eine Verifizierung, einschließlich permissiver Standards oder Fallbacks
• jede Verhaltensaufgabe enthält ihre Tests, die öffentliche Testgrenze und Rot-Grün-Refaktor-Prüfungen; jede Story hat ein Ziel und Abnahmekriterien
• Entscheidungen, Stories/Aufgaben, Kontext und Aussagen außerhalb des Geltungsbereichs stimmen im beobachtbaren Verhalten überein
• kein Glossarbegriff, Vertrag oder keine Regel im Kontext wird widersprochen
• base_commit ist der aktuelle HEAD; wenn kein Commit verfügbar ist, lasse es weg und erkläre warum

6. Zeigen und überprüfen

Zeigen:

• immer vollständig: die Zusammenfassung und die offenen Entscheidungen, da dies das ist, worauf der Benutzer reagiert
• Änderung, Feature: den vollständigen Planbody, einschließlich tatsächlicher Codeskizzen, Änderungsübersicht, Aufgaben und Erledigt-Prüfungen. Eine Zusammenfassung, Beschreibung der Form oder ein Link zur gespeicherten Datei ist kein Ersatz
• Initiative, Projekt: die Story-Übersichtstabelle mit Abhängigkeiten und Abhängigkeitsbaum, dann den Pfad zur Plandatei für den Rest
• Geplante Story-Überprüfung: ihre Zusammenfassung, Abnahme, offenen Entscheidungen, Form, vollständige Änderungsübersicht, Aufgabentabellen und Abhängigkeitsbaum. Zeige die Dateien, Grenzen, Ergebnisse und Prüfbefehle jeder Aufgabe; ein gemeinsamer Suite-Befehl oder eine Prosa-Aufgabenliste ist kein Ersatz

Ende mit dem, was du vom Benutzer brauchst:

Wähle D1a oder D1b, gib Feedback oder sage genehmigt.

Verwende die tatsächlichen offenen Entscheidungs-IDs; bei keiner frage nur nach Feedback oder Genehmigung.

Bei Feedback:

• überarbeite den Plan, erhöhe version und ersetze die Zeile Geändert seit mit dem, was sich geändert hat
• markiere beantwortete Entscheidungen als entschieden
• wenn der Benutzer eine dauerhafte Präferenz angibt ("nie Versionsnummern in Klassennamen") oder eine projektweite Wahrheit, füge sie zu Kontextänderungen hinzu; sie wird bei Genehmigung angewendet

7. Bei Genehmigung

1. Zeichne explizite Wahlmöglichkeiten als entschieden und nicht gewählte Empfehlungen als angenommen auf. Überprüfe die Konsistenz des Plans erneut, setze dann status: genehmigt und approved: <Datum> und aktualisiere base_commit, wenn ein Commit existiert. Erhöhe die Version, wenn Wahlmöglichkeiten den Planinhalt ändern.
2. Wende die Kontextänderungen auf .specshape/context.md an, erstelle sie bei Bedarf. Wenn das Repo bereits ein Glossar hat, verlinke darauf und füge nur das hinzu, was fehlt; verwende das kanonische Glossar des übergeordneten Elements, wenn du eine Story planst. Plane auch keine doppelten Definitionen in Projektdokumenten ein. Leere dann den Abschnitt Kontextänderungen des Plans.
3. Initiative oder Projekt: Biete die Tickets an. Liste die Tickets auf, die du erstellen wirst: eines pro Story, als Kinder des Eingabe-Tickets (des Epics) oder unter einem neuen Epic für ein Projekt. Jedes enthält den Titel, das Ziel, die Abnahmekriterien und einen Link zum Plan, nicht die Aufgaben. Erstelle sie erst, nachdem der Benutzer zugestimmt hat, und verwende den Tracker-Zugriff, den du hast. Ersetze jede lokale Story-ID mit ihrem Ticket-Schlüssel im Plan. Überprüfe verfügbare Tracker-Integrationen und die Quelle des Eingabe-Tickets; fehlende Git-Remotes beweisen nicht fehlenden Tracker-Zugriff. Wenn der Zugriff nicht verfügbar ist, sage dies und behalte lokale IDs. Wenn nur das Ziel unbekannt ist, frage, welcher Tracker/welches Projekt verwendet werden soll.
4. Erster Plan in diesem Repo: Biete an, eine Zeile zu AGENTS.md hinzuzufügen, und füge sie nur nach einem Ja hinzu: "Lies .specshape/context.md, falls vorhanden, bevor du an diesem Code arbeitest. Pläne leben in .specshape/." Hänge hinzu: "Verwende für geplante Arbeit /specshape-build.", nur wenn diese Fähigkeit verfügbar ist. Verwende die gleiche Verfügbarkeitsfeststellung für dieses Angebot und den nächsten Schritt; überprüfe die vorgeschlagene Zeile, bevor du sie zeigst.
5. Sage, was als Nächstes kommt:
   • Änderung oder Feature: /specshape-build <id> A1, wenn diese Fähigkeit verfügbar ist. Andernfalls sage, der Plan ist bereit für die Implementierung, aber /specshape-build ist nicht verfügbar. Hör auf, ohne Code zu schreiben.
   • Initiative oder Projekt: /specshape-plan <erste Story-ID>. Bevor du eine andere Story vorschlägst, überprüfe ihre Voraussetzungen; wenn sie nicht gebaut sind, erkläre, dass die Vorausplanung auf Annahmen beruht und vor dem Build anhand der implementierten Schnittstellen erneut validiert werden muss. Halte die Übergabe treu zu den gespeicherten Aufgabendefinitionen und Erledigt-Prüfungen. Hänge keine neuen manuellen Prüfungen oder Anforderungen an; überarbeite und überprüfe zuerst den Plan, wenn eine weitere Prüfung benötigt wird.

Planen einer Story

Eingabe: eine Story-ID aus einem genehmigten Plan.

1. Wenn der übergeordnete Plan nicht genehmigt ist, sage dies und stopp.
2. Lese die Abhängigkeiten der Story und untersuche ihren betroffenen Code vollständig, so wie er jetzt ist. Wenn vorausgesetzter Code fehlt, kennzeichne die angenommenen Schnittstellen und nenne, was vor dem Build erneut validiert werden muss. Für das lauffähige Grundgerüst eines Projekts, verankere es in den Entscheidungen und der Form des übergeordneten Elements. Leite keinen unveränderten Code aus Status- oder Dateilisten ab. Wende review.md auf neue Grenzwahlmöglichkeiten an.
3. Frage, ob die Story Fragen aufwirft, die nur der Benutzer beantworten kann (Feature-Regeln).
4. Fülle die Story des Plans …

… [abgeschnitten für Übersetzung]