PWRL Plan — Pure Skill Orchestrator
Erstelle dauerhafte Implementierungspläne, die zur Ausführung übergeben werden können. Orchestriert eine deterministische Pipeline von Mikro-Skills: Scope → Research → Design → Generate. Keine Agentenabhängigkeit, keine Fallback-Pfade.
Zweck
Pläne erfassen Entscheidungen, Strukturen und Ansätze vor der Ausführung. Sie ermöglichen:
- Klaren Umfang und Erfolgskriterien
- Identifizierte Risiken und Abhängigkeiten
- Konkrete Implementierungseinheiten mit Abnahmekriterien
- Wiederverwendung von Wissen durch zugehörige Learnings
- Vertrauen, dass die Arbeit nicht aus dem Ruder läuft
Kern-Workflow: Vier-Phasen-Pipeline
EINGABE (Aufgabenbeschreibung)
↓
PHASE 1: Scope (pwrl-plan-scope)
→ Kontext sammeln, Domäne validieren, Anforderungen bootstrappen
→ Ausgabe: Artefakt mit abgestecktem Kontext
↓
PHASE 2: Research (pwrl-plan-research)
→ Muster entdecken, Risiken identifizieren, externe Recherche empfehlen
→ Ausgabe: Artefakt mit Forschungsergebnissen
↓
PHASE 3: Design (pwrl-plan-design)
→ In Einheiten zerlegen, Abhängigkeiten abbilden, Komplexität bewerten
→ Ausgabe: Design-Artefakt mit Einheitenzerlegung
↓
PHASE 4: Generate (pwrl-plan-generate)
→ Stufe wählen, Plan rendern, Learnings einbetten, in docs/plans/ speichern
→ Ausgabe: Finales Plan-Dokument als Datei
↓
AUSGABE (Plan-Datei bereit zur Ausführung)
Phasendetails
Phase 1: Scope (pwrl-plan-scope)
Zweck: Einstiegspunkt in den Planungs-Workflow. Sammelt Kontext, prüft bestehende Pläne und Learnings, validiert die Domäne und gibt ein Objekt mit abgestecktem Kontext zurück.
Mikro-Skill: pwrl-plan-scope
Eingabe:
- Benutzer gibt Aufgabenbeschreibung, Anforderungsdokument oder Ziel an
- Bei leerer Eingabe wird der Benutzer gefragt: "Was möchtest du planen?"
Verarbeitung:
- Existierende Pläne in
docs/plans/prüfen; Fortsetzung/Überprüfung/Archivierung/Löschung/Neuanlage vorschlagen - Domäne validieren (Software vs. Nicht-Software)
- Problemrahmen, gewünschtes Verhalten und Erfolgskriterien bootstrappen
docs/learnings/INDEX.mdnach verwandten Learnings durchsuchendocs/requirements/unddocs/brainstorms/nach passenden Dokumenten durchsuchen- Kontext mit Benutzer bestätigen
- Interaktionsmodus abfragen:
- Detailiert: Schritt-für-Schritt-Interaktion in jeder Phase (überprüfen, bestätigen, anpassen)
- Yolo: Vollautomatisierung von Phase 1 bis Phase 4, nur finale Bestätigung
- Scope-Artefakt mit Interaktionsmodus generieren
Ausgabe: Artefakt mit abgestecktem Kontext, bestehend aus:
- Problemrahmen, gewünschtes Verhalten, Erfolgskriterien
- Verwandte Learnings (hohe Relevanz)
- Identifizierte Lernlücken
- Gefundene Anforderungen
- Interaktionsmodus (detailiert oder yolo)
Siehe: pwrl-plan-scope/SKILL.md für den detaillierten Workflow
Phase 2: Research (pwrl-plan-research)
Zweck: Lokale Muster, Technologie-Stack und Risikobereiche entdecken. Externe Recherche bei Bedarf empfehlen.
Mikro-Skill: pwrl-plan-research
Eingabe: Artefakt mit abgestecktem Kontext aus Phase 1
Verarbeitung:
- Technologie-Stack aus
package.json,Dockerfileund Codebasis-Struktur erkennen - Lokale Muster entdecken (Architektur, asynchroner Stil, Testen, Organisation)
- Hochrisikobereiche identifizieren (Sicherheit, Leistung, Migrationen, verteilte Systeme, Compliance)
- Externe Recherche für Hochrisikobereiche empfehlen (optional)
- Erkenntnisse aus verwandten Learnings integrieren
- Forschungsergebnisse zusammenstellen
Ausgabe: Forschungs-Artefakt mit:
- Erkannter Technologie-Stack
- Identifizierte lokale Muster
- Risikobereiche mit Empfehlungen
- Externe Forschungsergebnisse (falls durchgeführt)
- Notizen zur Integration von Learnings
Siehe: pwrl-plan-research/SKILL.md für den detaillierten Workflow
Phase 3: Design (pwrl-plan-design)
Zweck: Arbeit in Implementierungseinheiten zerlegen, Abhängigkeiten und Risiken identifizieren, Komplexität bewerten.
Mikro-Skill: pwrl-plan-design
Eingabe: Artefakt mit abgestecktem Kontext + Forschungsergebnisse
Verarbeitung:
- Arbeitseinheiten aus Erfolgskriterien und Risikobereichen identifizieren
- Abhängigkeiten zwischen Einheiten abbilden (topologische Sortierung)
- Zirkuläre Abhängigkeiten erkennen; zur Refaktorierung auffordern
- Risikominderungseinheiten erstellen
- Mermaid-Diagramme für komplexe Workflows (5+ Einheiten) generieren
- Komplexität bewerten (NIEDRIG/MITTEL/HOCH)
- Aufwand schätzen
- Zerlegung mit Benutzer bestätigen
Ausgabe: Design-Artefakt mit:
- Implementierungseinheiten (U1, U2, ..., UX) mit Testszenarien und Abnahmekriterien
- Abhängigkeitsgraph und topologische Reihenfolge
- Risikominderungen
- Mermaid-Diagramme (falls komplex)
- Komplexitätsbewertung und Aufwandsschätzung
Siehe: pwrl-plan-design/SKILL.md für den detaillierten Workflow
Phase 4: Generate (pwrl-plan-generate)
Zweck: Stufe (Schnell/Standard/Tief) wählen, Plan mit Stufenvorlage rendern, Learnings einbetten, in docs/plans/ speichern.
Mikro-Skill: pwrl-plan-generate
Eingabe: Design-Artefakt (aus Phase 3) + Scope-Artefakt (aus Phase 1)
Verarbeitung:
- Stufe basierend auf Komplexität/Einheiten/Aufwand automatisch wählen; bei Uneindeutigkeit nachfragen
- SCHNELL: NIEDRIGE Komplexität, 1-3 Einheiten, <5 Stunden
- STANDARD: MITTLERE Komplexität, 4-8 Einheiten, 5-20 Stunden
- TIEF: HOHE Komplexität, 9+ Einheiten, 20+ Stunden
- Plan mit stufenspezifischer Vorlage rendern
- Top 3-5 hochrelevante Learnings aus dem Scope einbetten
- Eindeutigen Dateinamen generieren:
YYYY-MM-DD-NNN-<slug>.md - Dateinamenskonflikte behandeln (Sequenz erhöhen oder vorhandene aktualisieren)
- Plan in
docs/plans/speichern
Ausgabe: In Datei gespeichertes Plan-Dokument mit:
- Problem & Umfang
- Erfolgskriterien
- Implementierungseinheiten (stufenspezifischer Detailgrad)
- Risikoanalyse (STANDARD/TIEF)
- Verwandte Learnings (STANDARD/TIEF)
- Lernlücken (TIEF)
- Ausrollhinweise (STANDARD/TIEF)
Siehe: pwrl-plan-generate/SKILL.md für den detaillierten Workflow
Planungsstufen
| Stufe | Am besten geeignet für | Dateien | Risiko | Zeitaufwand |
|---|---|---|---|---|
| SCHNELL | Fehlerbehebungen, kleine Anpassungen | 1-3 | NIEDRIG | 5-15 min |
| STANDARD | Die meisten Funktionen | 4-8 | MITTEL | 30-45 min |
| TIEF | Architektur, Sicherheit, Migrationen | 9+ | HOCH | 1-2 Stunden |
Siehe references/planning-tiers.md für vollständige Stufen-Entscheidungskriterien und Vorlagenbeispiele.
Kernprinzipien
- Deterministische Pipeline: Phasen werden stets in Reihenfolge ausgeführt: Scope → Research → Design → Generate (keine Verzweigungen, kein Fallback)
- Fokus auf Entscheidungen: Ansatz, Struktur, Risiken und Abfolge erfassen (keine Codesimulation)
- Passende Größe: Kleine Aufgaben → kurze Pläne; komplexe Arbeit → mehr Struktur
- Planung von Ausführung trennen: Implementierung während der Planung nicht simulieren
- Konkret sein: Bestimmte Dateien, Komponenten und Abhängigkeiten verwenden
- Portabel bleiben: Nur repository-relative Pfade verwenden
- Transparente Artefakte: Jede Phase erzeugt explizites Ausgabeartefakt für die nächste Phase
Fehlerbehandlung & Wiederherstellung
Philosophie: Explizit fehlschlagen, nicht still. Jede Phase hat klare Fehlerbehandlung mit Wiederherstellungsvorschlägen.
Phase 1 (Scope) Fehler
- Leere Eingabe: Benutzer nach Aufgabenbeschreibung fragen; wiederholen
- Nicht-Software-Domäne: Fehler zurückgeben; alternatives Tool vorschlagen
- Mehrdeutige Eingabe: Klärende Fragen stellen; mit Benutzerantworten bootstrappen
- Keine Learnings/Anforderungen: Fortfahren (kein Fehler)
Wiederherstellung: Benutzer kann wiederholen, Klarstellung geben oder abbrechen
Phase 2 (Research) Fehler
- Codeanalyse schlägt fehl: Mit minimalen Tech-Stack-Informationen fortfahren
- Hochrisikobereich identifiziert: Externe Recherche empfehlen; Benutzer kann zustimmen oder überspringen
Wiederherstellung: Benutzer kann Recherche zustimmen, überspringen oder manuell untersuchen
Phase 3 (Design) Fehler
- Zirkuläre Abhängigkeit erkannt: Zyklus-Pfad melden; Benutzer zur Refaktorierung auffordern
- Zu viele Einheiten (15+): Vor Komplexität warnen; Konsolidierung vorschlagen
- Unzureichende Details: Auffordern, Testszenarien hinzuzufügen oder Einheiten aufzuteilen
Wiederherstellung: Benutzer kann refaktorieren, konsolidieren oder mit Kenntnis fortfahren
Phase 4 (Generate) Fehler
- Dateinamenskonflikt: Optionen anbieten: aktualisieren, erhöhen oder abbrechen
- Stufenauswahl mehrdeutig: Benutzer zur Stufenwahl auffordern
- Fehlgeschlagenes Dateischreiben: Berechtigungen/Verzeichnis prüfen; wiederholen oder manuelle Speicherung vorschlagen
Wiederherstellung: Benutzer kann Aktion wählen oder manuell speichern
Wichtige Ausgaben
Jeder Plan enthält (stufenabhängig):
- Problem & Umfang: Klarer Problemrahmen und gewünschtes Verhalten
- Erfolgskriterien: 1-3 spezifische Bedingungen für den Abschluss
- Implementierungseinheiten: Benannte U-IDs mit Abhängigkeiten, Dateien, Ansatz und Abnahmekriterien
- Verwandte Learnings: Verknüpfte Lern-Dateien mit Anwendbarkeitsnotizen (STANDARD/TIEF)
- Lernlücken: Bereiche, die nach der Implementierung dokumentiert werden müssen (TIEF)
- Stufenspezifische Abschnitte: Risikoanalyse, Alternativen, Ausrollhinweise (STANDARD/TIEF)
Interaktionsmethode
- Die
ask_user_questions-Erweiterung der Plattform für alle Entscheidungen verwenden - Jeweils eine Frage stellen
- Nach Möglichkeit Multiple-Choice-Fragen verwenden
- Wenn die Eingabe leer ist, fragen: "Was möchtest du planen? Beschreibe die Aufgabe oder das Projekt."
- Bei Fehlern klare Wiederherstellungsvorschläge geben
Architektur: Kein Agenten-Routing
Unterschied zur vorherigen Version:
Vorher: Skill prüfte, ob ein Agent verfügbar war, und delegierte dann entweder an den Agent ODER führte einen monolithischen Fallback aus (zwei Codepfade)
Nachher: Skill ruft Mikro-Skills direkt in Sequenz auf – eine einzige deterministische Pipeline, keine Verzweigung:
pwrl-plan Orchestrator
├── 1. pwrl-plan-scope aufrufen → Scope-Artefakt erhalten
├── 2. pwrl-plan-research aufrufen → Forschungs-Artefakt erhalten
├── 3. pwrl-plan-design aufrufen → Design-Artefakt erhalten
└── 4. pwrl-plan-generate aufrufen → Plan-Datei speichern
Vorteile:
- ✅ Einfacher zu verstehen (einzelner Codepfad)
- ✅ Leichter zu testen (keine Verzweigungslogik)
- ✅ Wartbarer (Mikro-Skills unabhängig testbar)
- ✅ Zusammensetzbarer (Mikro-Skills in anderen Workflows wiederverwendbar)
- ✅ Bessere Fehlerbehandlung (explizit in jeder Phase)
Mikro-Skill-Referenzen
- pwrl-plan-scope — Kontext- & Umfangserfassung
- pwrl-plan-research — Musterentdeckung & Risikoidentifikation
- pwrl-plan-design — Einheitenzerlegung & Abhängigkeitsabbildung
- pwrl-plan-generate — Plan-Rendering & Dateigenerierung
Verwandte Dokumentation
- references/planning-tiers.md — Stufendefinitionen und Entscheidungskriterien
- docs/guides/micro-skill-patterns.md — Wie man mit neuen Mikro-Skills erweitert
- docs/guides/skill-architecture-refactoring.md — Begründung für die Refaktorierung
Tests & Validierung
Umfassende Testabdeckung:
- 30+ Tests für pwrl-plan-scope (U1.1)
- 25+ Tests für pwrl-plan-research (U1.2)
- 35+ Tests für pwrl-plan-design (U1.3)
- 30+ Tests für pwrl-plan-generate (U1.4)
- 30+ Integrationstests für die vollständige Orchestrierungspipeline
Rückwärtskompatibilität:
- Gleiches Ein-/Ausgabeverhalten wie die vorherige Version
- Vorhandene Pläne wurden erfolgreich generiert
- Keine bahnbrechenden Änderungen für Benutzer
Häufig gestellte Fragen
F: Was passiert, wenn eine Phase fehlschlägt? Kann ich sie überspringen oder wiederholen?
A: Ja. Jede Phase hat eine explizite Fehlerbehandlung mit Wiederherstellungsvorschlägen. Du kannst wiederholen, Klarstellungen geben, den Umfang anpassen oder abbrechen. Keine stillen Fehler.
F: Kann ich nur einen Mikro-Skill verwenden (z. B. nur aus dem Design generieren)?
A: Der Orchestrator erwartet, alle vier Phasen in Sequenz aufzurufen. Wenn du einen einzelnen Mikro-Skill verwenden möchtest, ruf ihn direkt beim Namen auf: /pwrl-plan-scope, /pwrl-plan-design usw.
F: Warum kein Agenten-Routing?
A: Agenten fügten Komplexität ohne Mehrwert hinzu. Die Mikro-Skill-Pipeline ist deterministisch, testbar und leichter zu verstehen. Direkte Skill-Aufrufe sind einfacher und wartbarer.
F: Kann ich dies für andere Workflows erweitern?
A: Ja! Die Mikro-Skills sind wiederverwendbar. Beispielsweise kann pwrl-work pwrl-plan-design für die Einheitenzerlegung verwenden. Siehe docs/guides/micro-skill-patterns.md.
Status: Reine Skill-Pipeline (kein Agenten-Routing) Version: 2.0 (refaktoriert von agentenabhängiger Architektur) Erstellt: 2026-06-11