jacklicn/agent-workflow

Erstellen eines Workflows

Ein Workflow ist eine wiederverwendbare Prozesseinheit, die übersetzt, „was der Benutzer tun möchte“ in „was zuerst zu tun ist, was als nächstes, welches Tool jeder Schritt verwendet und was er produziert“. Diese Fähigkeit führt Sie von den Benutzeranforderungen zu einer WORKFLOW.md, die der Spezifikation unter docs/workflow/index.md entspricht.

Lesen Sie die Spezifikation vor dem Erstellen: docs/workflow/index.md (dreistufige progressive Offenlegung, Eins-zu-Eins-Zuordnung von Graph zu Schritt, Prozessregeln, Tool-Call-Konventionen).

Wann verwenden

• Der Benutzer bittet um „Erstellen eines Workflows / Prozesses / standardisierten Ablaufs“
• Der Benutzer beschreibt eine mehrschrittige Aufgabe, die in einen automatisch ausgeführten Ablauf gegossen werden soll
• Der Benutzer bittet um Änderung oder Verbesserung eines bestehenden Workflows
• Der Benutzer hat in der Sitzung etwas Wiederverwendbares und Mehrschrittiges getan und sagt „diesen Ablauf festigen“

Erstellungsprozess

Phase 1: Die Absicht verstehen

Zuerst interviewen; nicht übereilt Dateien schreiben:

1. Welche Aufgabe löst es? Geben Sie der Aufgabenklasse einen Namen (z.B. „Code-Review“, „Release-Notes“).
2. Auslöseszenario: Wann wird der Benutzer es verwenden? Sammeln Sie Auslösewörter (Deutsch + Englisch).
3. Eingaben und Ausgaben: Welche Eingaben werden benötigt (Dateien/Verzeichnisse/Zeichenketten)? Was wird produziert (Dateien/Berichte)?
4. Vorhandene Schritte: Hat der Benutzer bereits einen gewohnten Ablauf? Extrahieren Sie Tool-Aufrufsequenzen, Korrekturen und Eingabe-/Ausgabeformate aus dem Sitzungsverlauf.
5. Grenzen und Regeln: Was darf nicht getan werden? Wo landen Artefakte? Wie werden Fehler behandelt?

Füllen Sie fehlende Informationen mit ask_user, bevor Sie zur nächsten Phase übergehen.

Phase 2: Das Flussdiagramm entwerfen

Zeichnen Sie den Ausführungsfluss mit Mermaid, unter Beachtung der Graph-Schritt-Zuordnungsregel (Spezifikation 5.2.1):

• Jeder Knoten muss einen passenden Schrittabschnitt haben; jeder Schritt muss genau einmal im Graph vorkommen
• Knotennamen stimmen exakt mit Schrittnamen überein und sind global eindeutig (das step-N-Präfix muss nicht in Knoten erscheinen)
• Entscheidungsknoten verwenden Rauten {}, müssen ebenfalls einen Schrittabschnitt haben und mit Branch angeben, wohin jeder Zweig führt
• Parallele Schritte (Scatter) sind ein Knoten im Graph
• Der Graph muss vollständig sein: Start, Verzweigungen, Ende

Zeigen Sie dem Benutzer den Graph zur Bestätigung, bevor Sie die Schritte schreiben.

Phase 3: Die WORKFLOW.md schreiben

Erstellen Sie das Verzeichnis und die Dateien unter <workspace>/workflows/<name>/:

1. Frontmatter (Metadaten der Ebene 1):
   • name: kebab-case, passend zum Verzeichnisnamen, nur Kleinbuchstaben/Ziffern/Bindestriche
   • description: Funktion + Nutzungszeitpunkt + Auslösewörter (Deutsch und Englisch), bestimmt die Auslöserate
   • inputs / outputs: explizit deklarieren, als erforderlich markieren
   • version / tags: optional
2. Überblick: Ein Absatz, der angibt, was es tut, wann es verwendet wird und was es produziert
3. Flussdiagramm: Der Mermaid-Graph, konsistent mit Phase 2
4. Schritte: Ein Abschnitt ### <id>: <name> pro Schritt, mit Attributen: Tools / Input / Depends on / Action / Check (Entscheidungsknoten fügen Branch hinzu, optional when)
5. Prozessregeln: Reihenfolge-Einschränkungen, Datenabhängigkeiten, Validierungstore, Nebeneffekt-Einschränkungen, Endzustandsprüfung
6. Tool-Call-Konventionen: Bevorzugen Sie integrierte Tools, Skripte als Rückfall, mehr lesen weniger schreiben, Pfadkonventionen

Progressive Offenlegung: Platzieren Sie lange Tabellen in REFERENCES.md, deterministische Logik in scripts/, halten Sie den Hauptteil schlank (<500 Zeilen).

Phase 4: Selbstprüfung und Validierung

Nach dem Schreiben gegen die Spezifikation prüfen:

• Eins-zu-Eins-Zuordnung von Graph zu Schritt: Keine „verwaisten“ Knoten im Graph, keine „verwaisten“ Schritte in den Abschnitten
• Knotennamen eindeutig und passend zu Schrittnamen
• Jeder Schritt hat eine konkrete, entscheidbare Check (z.B. „Datei existiert und ist nicht leer“, nicht „Erfolg bestätigen“)
• Toolnamen sind präzise (read_file / exec, nicht „die Datei anzeigen“)
• inputs / outputs konsistent mit den Schrittverweisen
• Regeln decken Fehlerbehandlung ab (Wiederholung / Rollback / Benutzer fragen)
• Frontmatter description enthält Funktion und Auslösewörter

Verwenden Sie workflow_list, um zu bestätigen, dass der neue Workflow erkannt wird, und workflow_get <name>, um zu überprüfen, ob er lesbar ist.

Phase 5: Ausliefern

Teilen Sie dem Benutzer mit:

• Den Workflow-Namen und -Pfad
• Das Auslöseszenario (welche Formulierung löst es aus)
• Eine Flussübersicht (wie viele Schritte, Entscheidungen/Parallelität)
• Optional: Schlagen Sie 2–3 echte Testanfragen vor, um die Funktionsfähigkeit zu überprüfen

Ändern eines bestehenden Workflows

• Lesen Sie zuerst den aktuellen Inhalt mit workflow_get <name>
• Behalten Sie den name im Frontmatter und den Verzeichnisnamen unverändert
• Befolgen Sie für Änderungen dieselbe Spezifikation; führen Sie nach der Bearbeitung die Selbstprüfung aus Phase 4 durch

Hinweise

• Nur in das Workspace-Verzeichnis workflows/ schreiben, niemals integrierte schreibgeschützte Workflows ändern; ein gleichnamiger Workspace-Workflow überschreibt den integrierten
• Ein Workflow löst eine Aufgabenklasse; häufen Sie keine unzusammenhängenden Abläufe an
• Halten Sie die Schritte zwischen 3 und 8; teilen Sie darüber hinaus auf oder referenzieren Sie einen Unter-Workflow
• Schreiben Sie niemals bösartige oder irreführende Anweisungen; Regeln müssen überprüfbar sein