implement-commit

Skill „Implement Commit“

Führt Commits aus einem implementation-plan.toml mithilfe einer mechanischen TDD-Pipeline aus.

Wann verwenden

• Implementierungsplan vorhanden unter docs/features/NNNN-name/implementation-plan.toml
• Bereit zum Schreiben von Code

Orchestrator-Rolle

Du bist ein mechanischer Orchestrator. Der Treiber (ic-driver.py) kümmert sich um die Zustandsübergänge.

Du tust nur:

1. Treiberbefehle aufrufen
2. Spawn-Aktionen ausführen
3. Ergebnisse zurückmelden

Du MUSST keine relevanten Dateien lesen, es sei denn, etwas schlägt fehl – spare deine Tokens, vertraue dem ic-driver

Setup

import json
from pydantic import BaseModel
from typing import Literal

# Pfade
feature_dir = "docs/features/NNNN-feature"
plan_path = f"{feature_dir}/implementation-plan.toml"
state_dir = ".ic"
driver = "skills/implement-commit/ic-driver.py"
workspace = "."  # Aus Plan-Meta

# Antwortmodelle
class PhaseResult(BaseModel):
    status: Literal["ok", "problems"]
    files_created: list[str] = []
    files_modified: list[str] = []
    notes: str | None = None

class GateDiscovery(BaseModel):
    designer_gate: str
    test_gate: str

class FormatterDiscovery(BaseModel):
    fmt_cmd: str
    lint_cmd: str

class StyleResult(BaseModel):
    status: Literal["accept", "violations"]
    violations: list[str] = []

class ArbiterResult(BaseModel):
    proceed: bool
    reasoning: str

# Agentendateien für Spawns
agents = {
    "designer": "skills/implement-commit/agents/designer.md",
    "tester": "skills/implement-commit/agents/tester.md",
    "implementor": "skills/implement-commit/agents/implementor.md",
    "arbiter": "skills/implement-commit/agents/arbiter.md",
}
style_guides = {
    "designer": "docs/style/rust-design.md",
    "tester": "docs/style/rust-test.md",
    "implementor": "docs/style/rust-impl.md",
}

Hauptschleife

Für jeden Commit (in Abhängigkeitsreihenfolge):

commit_id = 1  # Aus Abhängigkeitsanalyse
state_path = f"{state_dir}/commit-{commit_id}.json"

# Initialisieren
bash(f"python {driver} init --plan {plan_path} --commit {commit_id} --state {state_path}", on_error="raise")

# Schleife steuern
while True:
    try:
        output = bash(f"python {driver} next --state {state_path}", on_error="raise")
    except BashError as e:
        # Treiber braucht LLM-Hilfe – siehe „Eskalation behandeln“ unten
        handle_escalation(e, state_path)
        continue
    
    action = json.loads(output)
    
    if action["action"] == "done":
        break
    
    if action["action"] == "spawn":
        result = execute_spawn(action)
        bash(
            f"python {driver} report --state {state_path} --result '{json.dumps(result)}'",
            on_error="raise"
        )

Spawn ausführen

def execute_spawn(action: dict) -> dict:
    phase = action.get("phase")
    
    # Kontextdateien bestimmen
    context_files = [f"{feature_dir}/design.md"]
    if phase and phase in agents:
        context_files.append(agents[phase])
        if phase in style_guides:
            context_files.append(style_guides[phase])
    
    # Antwortmodell bestimmen
    if action.get("response_schema") == "GateDiscovery":
        model = GateDiscovery
    elif action.get("response_schema") == "FormatterDiscovery":
        model = FormatterDiscovery
    elif action.get("style_review"):
        model = StyleResult
    elif action.get("arbiter"):
        model = ArbiterResult
    else:
        model = PhaseResult
    
    # Spawn ausführen
    result = spawn(
        prompt=action["prompt"],
        context_files=context_files,
        response_model=model,
        read_only=action.get("style_review") or action.get("scope_review"),
        isolate_to=Cwd(workspace) if not action.get("style_review") else None,
    )
    
    result_dict = result.parsed.model_dump()
    # Aktion-Flags für die Treiber-Zustandsmaschine erhalten
    if action.get("arbiter"):
        result_dict["arbiter"] = True
    return result_dict

Eskalation behandeln

Wenn der Treiber mit Exit-Code 1 endet, braucht er LLM-Hilfe:

def handle_escalation(e: BashError, state_path: str):
    # Eskalation aus stderr parsen
    escalation = json.loads(e.stderr)
    error = escalation["error"]
    
    # LLM-Eingriff – das Problem verstehen und beheben
    # Hier denkst DU – der Treiber hat dir die Kontrolle gegeben
    
    if "gate failed" in error.lower():
        # Könnte Code-Fehler oder Gate-Fehlkonfiguration sein
        # Einen Fixer spawnen oder Gates anpassen
        spawn(
            prompt=f"Behebe diesen Gate-Fehler: {error}",
            context_files=[...],
            isolate_to=Cwd(workspace),
        )
    elif "arbiter rejected" in error.lower():
        # Stilprobleme zu schwerwiegend
        agent_feedback(f"Stilprüfung fehlgeschlagen: {error}")
    elif "scope violations" in error.lower():
        # Änderungen außerhalb des Gültigkeitsbereichs
        agent_feedback(f"Bereichsverletzung: {error}")
    else:
        agent_feedback(f"Unbekannte Eskalation: {error}")
    
    # Nach der Behebung fortsetzen
    bash(f"python {driver} resume --state {state_path}", on_error="raise")

Treiberbefehle

Befehl	Zweck
init	Zustandsdatei für einen Commit erstellen
next	Nächste Aktion (Spawn) abrufen oder Gate/Bash direkt ausführen
report	Spawn-Ergebnis melden, Zustand weiterschalten
resume	Nach LLM-Eingriff fortsetzen
status	Aktuellen Zustand anzeigen (Debugging)

Zustandsmaschine

EXPLORE_GATES -> EXPLORE_FORMATTERS ->
DESIGNER_PHASE -> DESIGNER_GATE -> DESIGNER_STYLE ->
TESTER_PHASE -> TESTER_GATE -> TESTER_STYLE ->
IMPLEMENTOR_PHASE -> IMPLEMENTOR_GATE -> IMPLEMENTOR_STYLE ->
SCOPE_REVIEW -> FORMAT -> COMMIT -> DONE

• Gate-Fehler wiederholen die Phase (bis zu 2×), dann Eskalation
• Stil-Verstöße durchlaufen eine Schleife (bis zu 3×), dann wird der Arbiter aufgerufen
• Der Treiber führt Gates/Format/Commit direkt aus (kein LLM-Overhead)
• Nur Spawns erfordern Aktionen des Orchestrators

Dateien

skills/implement-commit/
├── SKILL.md           # Diese Datei
├── ic-driver.py       # Zustandsmaschinen-Treiber
└── agents/
    ├── designer.md    # Erstellt Typen und Signaturen
    ├── tester.md      # Schreibt Tests
    ├── implementor.md # Implementiert die Logik
    └── arbiter.md     # Entscheidet über Bestehen/Fehlschlagen der Stilprüfung

Prüfer verwenden separate Skills: review-scope, review-style.