implementar-commit

Skill Implementar Commit

Execute commits a partir de um implementation-plan.toml usando um pipeline TDD mecânico.

Quando Usar

• O plano de implementação existe em docs/features/NNNN-name/implementation-plan.toml
• Pronto para escrever código

Papel do Orquestrador

Você é um orquestrador mecânico. O driver (ic-driver.py) lida com as transições de estado.

Você apenas:

1. Chama comandos do driver
2. Executa ações de spawn
3. Reporta resultados de volta

Você NÃO DEVE ler arquivos relevantes a menos que algo falhe - preserve seus tokens, confie no ic-driver

Configuração

import json
from pydantic import BaseModel
from typing import Literal

# Caminhos
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 = "."  # Do meta do plano

# Modelos de resposta
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

# Arquivos de agentes para 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",
}

Loop Principal

Para cada commit (em ordem de dependência):

commit_id = 1  # Da análise de dependências
state_path = f"{state_dir}/commit-{commit_id}.json"

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

# Loop de execução
while True:
    try:
        output = bash(f"python {driver} next --state {state_path}", on_error="raise")
    except BashError as e:
        # Driver precisa de ajuda LLM - veja Tratamento de Escalação abaixo
        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"
        )

Executar Spawn

def execute_spawn(action: dict) -> dict:
    phase = action.get("phase")
    
    # Determinar arquivos de contexto
    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])
    
    # Determinar modelo de resposta
    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
    
    # Executar spawn
    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()
    # Preservar flags de ação para a máquina de estados do driver
    if action.get("arbiter"):
        result_dict["arbiter"] = True
    return result_dict

Tratamento de Escalação

Quando o driver sai com código 1, ele precisa de ajuda LLM:

def handle_escalation(e: BashError, state_path: str):
    # Analisar escalação a partir do stderr
    escalation = json.loads(e.stderr)
    error = escalation["error"]
    
    # Intervenção LLM - entender e corrigir o problema
    # É aqui que você PENSA - o driver te deu controle
    
    if "gate failed" in error.lower():
        # Pode ser erro de código ou configuração incorreta do gate
        # Disparar um corretor ou ajustar gates
        spawn(
            prompt=f"Corrigir esta falha de gate: {error}",
            context_files=[...],
            isolate_to=Cwd(workspace),
        )
    elif "arbiter rejected" in error.lower():
        # Problemas de estilo muito graves
        agent_feedback(f"Revisão de estilo falhou: {error}")
    elif "scope violations" in error.lower():
        # Mudanças fora de escopo
        agent_feedback(f"Violação de escopo: {error}")
    else:
        agent_feedback(f"Escalação desconhecida: {error}")
    
    # Retomar após correção
    bash(f"python {driver} resume --state {state_path}", on_error="raise")

Comandos do Driver

Comando	Propósito
init	Criar arquivo de estado para um commit
next	Obter próxima ação (spawn) ou executar gate/bash diretamente
report	Reportar resultado do spawn, avançar estado
resume	Continuar após intervenção LLM
status	Mostrar estado atual (depuração)

Máquina de Estados

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

• Falhas de gate repetem a fase (até 2x), depois escalam
• Violações de estilo repetem (até 3x), depois invocam o arbiter
• Driver executa gates/format/commit diretamente (sem overhead LLM)
• Apenas spawns exigem ação do orquestrador

Arquivos

skills/implement-commit/
├── SKILL.md           # Este arquivo
├── ic-driver.py       # Driver da máquina de estados
└── agents/
    ├── designer.md    # Cria tipos e assinaturas
    ├── tester.md      # Escreve testes
    ├── implementor.md # Implementa lógica
    └── arbiter.md     # Decide prosseguir/falhar na revisão de estilo

Revisores usam skills separadas: review-scope, review-style.