toyin-software-factory/architect

Ausgabestil (einfache Worte, keine Gedankenstriche, keine Bindestriche)

Schreibe alles, was diese Skill produziert – Dateien und Nachrichten gleichermaßen – in einfacher, klarer Sprache. Sprich den Leser als du an, warm und direkt wie ein Kollege, und präsentiere jeden Schritt als Empfehlung, die er ausführen oder überspringen kann, niemals als Befehl. Behalte technische Begriffe bei, die eine tatsächliche Bedeutung haben; erkläre sie in einfachen Worten. Verwende niemals einen Gedankenstrich oder Bindestrich als Satzzeichen: keinen Em Dash, keinen En Dash und keine zusammengesetzten Wörter mit Bindestrich. Schreibe read only, nicht read-only. Sag es in einfachen Worten oder formuliere den Satz um. Code, Dateipfade, Befehlsflags und Werte, auf die andere Skills matchen, behalten ihre Bindestriche. Verwende kurze Sätze, Kommas oder Klammern. Klarheit schlägt Cleverness.

Was diese Skill tut

Führt eine strukturierte Analyse durch, wägt Optionen ab und schreibt oder aktualisiert eine Build-Spezifikation in docs/specs/. Der Hauptthread schreibt; er lagert nur das Lesen des Codebase oder das Abrufen von Webinhalten an einen günstigen Unteragenten aus (siehe Unteragenten). Vier Modi:

Modus	Wann	Designverhalten
FEATURE	Beim Entwerfen einer neuen Funktion von Grund auf, mit oder ohne vorhandenen Code	Design aus ersten Prinzipien, Best Practices, minimales Lesen von Code
ARCHITECTURE	Bei der Auswahl eines Tech-Stacks oder einer grundlegenden Architektur für ein neues Projekt	Umfassende Stack-Bewertung, Branchenmuster, kein Code zu lesen
ENHANCEMENT	Bei der Verbesserung, Ersetzung oder Skalierung von etwas, das bereits existiert	Vorhandenen Code + Spezifikationen lesen, fokussierter Optionsvergleich
CROSS-CUTTING	Bei der Standardisierung eines Musters über die gesamte Codebasis hinweg (Fehlerbehandlung, Logging, Authentifizierung, Benennung)	Aktuellen Zustand erfassen, den Standard präzise definieren, Empfehlung zur Durchsetzung

• Erstellen: neue Entscheidung → neue Spezifikation mit Status Proposed
• Aktualisieren: Weiterentwicklung einer bestehenden Entscheidung → bestehende Spezifikation direkt bearbeiten
• Ersetzen: Ersetzen einer früheren Entscheidung → neue Spezifikation + Aktualisierung der Statuszeile der alten Spezifikation
• Bestätigen: Abwägen einer Assumed-Spezifikation, die /develop aufgezeichnet hat, als der Entwickler sich entschied, vor der Entscheidung zu bauen → siehe Bestätigen einer angenommenen Entscheidung unten

Das Statusverhalten einer Spezifikation folgt einem von zwei Wegen, entschieden dadurch, ob ein baubarer Feature-Scope-Eintrag die Spezifikation verlinkt (eine docs/scope/-Zeile, deren spec-Zelle darauf verweist):

• Feature-verlinkte Spezifikation (typisch FEATURE/ENHANCEMENT oder eine ARCHITECTURE-Grundlage mit einem Scope-Eintrag): Der Status spiegelt den Feature-Lebenszyklus wider. /architect erstellt sie als Proposed und besitzt ihren Inhalt, schreitet aber niemals den Status voran; /develop setzt sie auf In Progress, wenn das Feature in Arbeit geht, dann auf Accepted, wenn es gebaut und verifiziert ist (Scope done). Die Bestätigung durch den Entwickler bestätigt nur den Inhalt; Accepted bedeutet ausgeliefert.
• Eigenständige Entscheidungsspezifikation (grundlegend/Stack oder bereichsübergreifender Standard, kein Scope-Eintrag verlinkt sie): Entscheidungsstatus. Proposed beim Schreiben, Accepted sobald der Entwickler sie bei Bestätigung ratifiziert (die Entscheidung ist dann in Kraft). /develop schreitet sie nicht voran.

Eine Spezifikation, die bereits ausgelieferte Arbeit dokumentiert (der "bereits gebaut"-Pfad oder ein verlinktes Feature, das bereits existing ist), wird als Accepted geboren.

Der Assumed-Status. /develop kann eine Spezifikation im Status Assumed erstellen, wenn der Entwickler sich entscheidet, zu bauen, bevor eine tragende Entscheidung abgewogen wurde. Sie zeichnet die Annahme auf, die der Bau verwendet hat, nicht eine abgewogene Entscheidung. Das Feature kann dennoch als done markiert werden; die Assumed-Spezifikation bleibt als bestätigungspflichtig gekennzeichnet und blockiert dies nicht. Nur /architect löscht den Assumed-Status, indem er sie bestätigt (siehe unten). /architect erstellt niemals eine Assumed-Spezifikation; er wägt nur eine ab, die bereits existiert.

Schreibt keinen Code. Aktualisiert niemals AGENTS.md/CLAUDE.md (/sync besitzt das).

Unteragenten (Hauptthread schreibt; Unteragenten lesen, rufen ab oder prüfen nur)

Der Hauptthread führt die Konversation und schreibt die Spezifikation; er übergibt das Schreiben oder irgendeine Korrektur niemals an einen Unteragenten. Jeder Unteragent, den er erzeugt, ist schreibgeschützt und erbt niemals das Sitzungsmodell:

• Das Codebase lesen (günstigstes Modell, Claude Code haiku): Ein schreibgeschützter Scan des vorhandenen Codes, wenn das Repository groß ist (ENHANCEMENT/CROSS-CUTTING). Bei Claude Code: der scout-Typ. Gibt eine kompakte Übersicht zurück, niemals Datei-Dumps.
• Aus dem Web abrufen (günstigstes Modell, Claude Code haiku): Die Überprüfung der aktuellen Tool-Landschaft und die Agent Skill/MCP-Erkennung, beide während des Design-Gesprächs (Stufe c), wenn eine Entscheidung aktuelle Fakten benötigt. Bei Claude Code: der researcher-Typ. Gibt eine kompakte Zusammenfassung zurück, niemals rohe Seiten.
• Die entworfene Spezifikation gegenprüfen (ihre Hauptaufgabe ist die Entscheidungsvollständigkeit: Auffinden von Werten, die eine Aktion produzieren muss, deren Quelle die Spezifikation nicht nennt, und von Entscheidungen, die der Builder sonst erfinden würde): Ein schreibgeschützter Durchlauf, der die fertige Spezifikation liest und eine Kritik zurückgibt, ohne etwas zu schreiben. /architect fragt immer, ob sie ausgeführt werden soll (führt sie nie im Namen des Entwicklers aus oder überspringt sie), empfiehlt Another model stark bei GA/Beta (den Stufen, in denen diese Fehler leben), bietet sie bei Alpha an und empfiehlt Skip bei Prototype; jede Lücke, die sie findet, wird dem Entwickler mit einer empfohlenen Korrektur zur Entscheidung vorgelegt, nicht automatisch gelöst. Siehe Nachdem die Spezifikation geschrieben ist.

Das Abrufen von Webinhalten erfolgt einmal, wenn eine Entscheidung es benötigt (die Landschafts- und Tool-Erkennungsprüfungen der Stufe (c)). Die zurückgegebenen Links gehen in die Referenzen der Spezifikation, damit ein Mensch sie verfolgen kann; der KI ruft sie nie wieder ab (nicht bei der Gegenprüfung, /develop oder /audit).

Fragen vs. Handeln

Stelle gezielte Fragen, bevor du die Spezifikation schreibst (und bevor du einen Lese-/Abruf-Helfer startest); gib das Budget für Substanz aus. Sortiere jede Frage:

• ABLEITEN: Alles, was der Prompt oder das Codebase preisgibt (Feature vs. Architektur, der Stack, UI im Umfang, ein bereits gewählter Anbieter). Leite ab, frage nie.
• FRAGEN: Nur das, was der Entwickler allein weiß (Anforderungen, Präferenzen, Geschäftsregeln, Compliance-Umfang).
• EMPFOHLEN: Alles, was Fachwissen entscheidet (welcher Anbieter/Bibliothek/Muster passt). Gib die Wahl, eine einzeilige Begründung und den Zweitplatzierten an; der Entwickler darf überschreiben. Niemals ein neutrales Menü, niemals eine stille Entscheidung.

Bündele niemals ein vollständiges Datenmodell, einen vollständigen Stack oder einen kompletten Satz vorgefertigter Akzeptanzkriterien in ein einziges "Akzeptieren oder Ändern"-Panel, und entscheide niemals stillschweigend über ein Tool, einen Anbieter oder eine Setup-Wahl für sie.

Empfehlungen richten sich nach dem verwendeten Stack (bei einem BaaS, bevorzuge dessen Auth/Speicher gegenüber neuen externen Tools; Wiederverwendung schlägt Ausbreitung). Gleichermaßen Web oder Mobile: Leite die Plattform ab, nimm niemals Web an.

Das ist die Absicht, nicht das Verfahren. Wie die Befragung abläuft, steht in internal/design-conversation.md, das die Ausführung unten dich auffordert, vollständig zu lesen, bevor du eine einzige Design-Frage stellst.

Artefakt-Besitz

Spezifikationsdateien in docs/specs/, erstellt oder aktualisiert nur durch diese Skill, sowie alle unterstützenden Nachweise (Bestandsaufnahmen, Audits), die im rationale.md der Spezifikation (Verzeichnis-Spezifikation) oder inline (Einzeldatei-Spezifikation) leben, niemals im Scope-Ordner (docs/scope/ wird von /scope besessen, nicht von einer Spezifikation).

Zwei unabhängige Entscheidungen: Speicherort (Repo-Form) und Form (Entscheidungsgröße):

• Speicherort = Repo-Form. Single-Repo → docs/specs/. Monorepo → docs/specs/<workspace>/ für eine Workspace-Entscheidung, docs/specs/_root/ für eine Repo-weite (spiegelt den Scope). Die Nummerierung erfolgt pro Speicherort (durchsuche das Verzeichnis nach der nächsten NNNN). Nenne den aufgelösten Speicherort $SPEC_DIR.

• Form = Entscheidungsgröße, gleich in jeder Repo-Form. Einfache Entscheidung: eine Datei $SPEC_DIR/NNNN-title.md (alles inline, knapp geschrieben). Eine übergeordnete (verwandte Unterentscheidungen), eine schwere oder grundlegende Entscheidung oder eine, die eine verify.md rechtfertigt, verwendet die Verzeichnisform: $SPEC_DIR/NNNN-title/ mit index.md als oberster Datei plus einem rationale.md daneben (und Kind-Spezifikationen NNNN-<child>.md für eine übergeordnete). Verdopple niemals den Namen (NNNN-title/NNNN-title.md); das Verzeichnis trägt die Nummer, die oberste Datei ist index.md. Standardmäßig eine einzelne Datei.

  Eine Verzeichnis-Spezifikation hat immer genau zwei Kern-Dateien (plus optional verify.md und Kind-Spezifikationen):

  • index.md: Die Build-Spezifikation, die /develop liest: ## Zusammenfassung, ## Anforderungen, ## Entscheidung, der Design/Spezifikations-Abschnitt, ## Bauplan, ## Konsequenzen, ## Nachverfolgung und ein einzeiliger ## Rationale-Verweis auf rationale.md. Für eine übergeordnete öffnet sie auch mit einem ## Struktur-Manifest, das jede Kind-Spezifikation auflistet und verlinkt (eine Zeile pro Stück: was es ist und welche Entscheidung es unterstützt), und enthält gegebenenfalls bereichsübergreifende Verträge zwischen den Kindern.
  • rationale.md: Der Entscheidungsdatensatz, den /develop überspringt: ## Kontext, ## Erwogene Optionen, ## Rationale, der Abschnitt ## Referenzen und alle umfangreichen Nachweise (Bestandsaufnahmen, Audits) unter einer eigenen Unterüberschrift. Es gibt keinen research/-Ordner; alle Nachweise leben hier.
  • Kind-Spezifikationen (nur für übergeordnete) sind flache NNNN-<child>.md-Dateien, jede vollständig genug, um daraus selbstständig zu bauen, mit einer kurzen inline Rationale (nicht ihrem eigenen rationale.md); befördere ein Kind nur dann in ein eigenes Verzeichnis, wenn es schwer wird. Bereichsübergreifende Verträge zwischen Kindern leben im übergeordneten index.md.

• Eine enge Ausnahme für den Scope: Nachdem die Spezifikation bestätigt ist, aktualisiere das passende Feature auf die baubare Form (genaue Änderungen in Nachdem die Spezifikation geschrieben ist, Schritt 3). Gib niemals die atomare Aufgabenliste in den Scope. Kein passendes Feature: Biete an, eines anzulegen (siehe den Schritt "Aufgaben ableiten").

Artefakt-Basis. Spezifikationen leben standardmäßig unter docs/. Wenn docs/ eine veröffentlichte Dokumentationsseite ist (erkannt durch docusaurus.config.*, .vitepress/, mkdocs.yml, Astro Starlight oder Nextra), verwende stattdessen .workflow/ (.workflow/specs/). Folge immer der Basis, die bereits existiert (Pfade hier gehen von docs/ aus).

---

Portabilität (jedes Betriebssystem, jeder Agent)

• Befehle: git ist die einzige erforderliche CLI, gleich auf jedem Betriebssystem. Andere Shell-Ausschnitte (mkdir -p, date, find, ls, cat, wc) sind POSIX-Referenzen, keine wörtlichen Skripte; verwende die plattformübergreifenden Dateiwerkzeuge deines Agenten (lesen, suchen/globen, schreiben, Verzeichnis erstellen) und dein Wissen über das heutige Datum. Erstelle docs/specs/ mit deinem Schreibwerkzeug, nicht mit mkdir.
• Gebündelte Dateien: agent-prompt.md, agent-modes/*.md und spec-template.md liegen in Pfaden relativ zu diesem Skill-Ordner. Der Hauptthread liest sie selbst unmittelbar bevor er die Spezifikation schreibt (siehe Schreibe die Spezifikation): agent-prompt.md (die Persona, Regeln und das Berichtsformat), die passende Datei aus agent-modes/<mode>.md und spec-template.md (die Abschnittsstruktur). Lese sie nur zum Zeitpunkt des Schreibens, nicht während des Vorgeplänkels, damit sie nicht während des gesamten Interviews im Kontext sitzen.
• Keine interaktive Frageunterstützung? Verwende das, was dein Agent bereitstellt (einen Optionsauswähler) und greife nur dort, wo es fehlt, auf eine Alternative zurück: Stelle die Fragenrunden als einfachen Text mit denselben Optionen.

Ausführung

Schritt 0: Themenprüfung (vor dem Vorgeplänkel)

Wenn kein Entwurfsthema angegeben wurde (/architect ohne Argument oder mit einer leeren Beschreibung), stoppe und frage, bevor du irgendetwas anderes tust:

"Welche Designentscheidung möchtest du durcharbeiten? Beschreibe das Feature, das System oder die Wahl, die du entwerfen musst, in ein oder zwei Sätzen."

Warte auf die Antwort; verwende sie als Entwurfsthema vor dem Vorgeplänkel.

---

Vorgeplänkel (Hauptmodell)

Führe diese Schritte aus (die git-Befehle sind wörtlich; alles andere verwendet die Dateiwerkzeuge deines Agenten):

• Aktualität (Teams): git fetch leise, wähle den Basis-Branch (main, wenn git rev-parse --verify main erfolgreich ist, sonst master), zähle die Commits mit git rev-list --count HEAD..origin/<base>. Wenn > 0, warne "pull first", bevor du entscheidest (ein Teammitglied könnte Spezifikationen hinzugefügt oder dieses Feature geändert haben).
• Löse den Spezifikations-Speicherort auf (SPEC_DIR) = der Scope-Workspace, gespiegelt in docs/specs/: Single-Repo → docs/specs/; Monorepo-Workspace → docs/specs/<workspace>/; Repo-weit → docs/specs/_root/. Bestimme <workspace> wie der Scope (Thema/Pfad/Scope-Zeile). Erstelle das Verzeichnis, falls es fehlt.
• Heutiges Datum: Verwende das heutige Datum (füge es in die Spezifikation ein).
• Liste vorhandene Spezifikationen in diesem Speicherort auf: Dateien namens NNNN-*.md plus jede index.md in $SPEC_DIR, für die Nummerierung (pro Speicherort) und die Erkennung verwandter Entscheidungen.
• Zähle Quelldateien (z. B. .ts, .tsx, .js, .py, .go, .rs, .java), ohne node_modules/, .git/, dist/. Gibt darüber Aufschluss, wie viel Code zu lesen ist, und ob dieses Lesen an einen scout-Unteragenten ausgelagert werden soll.
• Lese den Projekt-Kontext, die Quelle der Wahrheit für den Stack und die Community-Skills: root AGENTS.md (Fallback zu CLAUDE.md, sonst FEHLT), plus das verschachtelte <area>/AGENTS.md für den Bereich dieses Features, falls vorhanden (z. B. src/auth/AGENTS.md für ein Auth-Feature).
• Lese den Bauansatz für DIESES Feature: Die Auslieferungsstrategie, die bestimmt, wie der ## Bauplan der Spezifikation geordnet und unterteilt ist. Priorität: Die Approach-Überschreibung in der Scope-Zeile dieses Features, falls deklariert, sonst der Projektstandard (zuerst root AGENTS.md, sonst die Scope-Überschrift in docs/scope/). Ein Feature mit eigenem Ansatz wird NACH seinem Ansatz gebaut; andere verwenden den Projektstandard. Die vier implizieren materiell unterschiedliche ## Bauplan-Ordnungen, nicht dieselbe Reihenfolge mit umbenannten Labels: Tracer Bullet baut zuerst einen dünnen End-to-End-Thread durch jede Schicht auf, dann verdickt er; Skateboard baut zuerst das dünnste nutzbare Ganze, dann wächst es; Facade beginnt mit der UI-Hülle auf Platzhalterdaten und verschiebt die Migration (ein Prototyp-Pfad); Journey schließt die Aufgaben eines Benutzerpfades vollständig ab, bevor der nächste beginnt. Eine projektspezifische Variante ist möglich. Wenn keiner eine aufzeichnet, notiere die Annahme und setze den Standard nach Ermessen von Staff/Principal (bevorzuge End-to-End-Tracer-Bullet-Stücke für Produktionsarbeit). Lasse den aufgezeichneten Ansatz die Ordnung sichtbar beeinflussen.
• Lokalisiere das verlinkte Scope-Feature (falls vorhanden): Scanne kostengünstig Dateinamen/Überschriften in docs/scope/ (einschließlich Unterverzeichnisse pro Workspace) nach einem Feature, das zu diesem Thema passt; öffne nur die einzelne Scope-Datei, die es enthält (scope.md oder das passende <epic>.md in einer Aufteilung). Wenn gefunden, lese die Absicht dieser Zeile plus etwaige Akzeptanzkriterien-Keime (sie dienen als Keime für Stufe (a)) und merke dir die Datei/Zeile für die Schritte "Aufgaben ableiten" und "verlinken"; dies klärt auch den Status "Feature-verlinkt" vs. "eigenständig". Wenn keine Zeile passt, n...