plano-de-implementacao-ad-hoc

Plano de Implementação Ad-Hoc

Caminho rápido de uma ideia aproximada para artefatos prontos para implementar-commit. Troca completude da documentação por velocidade.

Quando Usar

• Você tem um plano ou ideia aproximada discutida com o usuário
• Você deseja a verificação TDD do implementar-commit sem a cadeia completa de propor-*
• O recurso é bem compreendido o suficiente para pular iteração extensa de design

Pré-requisitos

• Plano aproximado aprovado pelo usuário (pode estar na conversa, em markdown, ou modelo mental)
• Caminho do espaço de trabalho conhecido
• Arquivos a serem modificados conhecidos

Papel do Orquestrador

Você é um ROTEADOR MECÂNICO. Você NÃO pensa sobre o recurso. Seu trabalho:

1. Reunir informações mínimas necessárias do usuário
2. Criar estrutura de diretório do recurso
3. Gerar subagentes com skills apropriadas como contexto
4. Passar saídas entre as fases
5. Verificar referências cruzadas

Configuração

from pydantic import BaseModel
from pathlib import Path
import os

class GatherResult(BaseModel):
    feature_name: str
    feature_id: str  # formato NNNN
    workspace: str
    files_to_modify: list[str]
    constraints: list[str]
    test_names: list[str]
    rough_plan_summary: str

class PhaseResult(BaseModel):
    success: bool
    artifact_path: str
    errors: list[str]

# Caminhos das skills para contexto do subagente
skills = {
    "design": "skills/propose-feature-design/SKILL.md",
    "test_plan": "skills/propose-feature-test-plan/SKILL.md",
    "impl_plan": "skills/propose-implementation-plan/SKILL.md",
}

# Guias de estilo (se disponíveis)
style_guides = [
    "docs/style/rust-design.md",
    "docs/style/rust-test.md",
    "docs/style/rust-impl.md",
]

Fase 0: Reunir

Reunir interativamente ou inferir do plano aproximado:

# Se ainda não for conhecido, pergunte ao usuário:
# 1. Nome do recurso → cria docs/features/NNNN-nome/
# 2. Arquivos a modificar → commits[].files
# 3. Restrições principais → entradas da tabela CC
# 4. Nomes dos testes → test-plan + commits[].tests

# Determinar próximo ID do recurso
existing = list(Path("docs/features").glob("[0-9][0-9][0-9][0-9]-*"))
next_id = f"{len(existing):04d}"

feature_dir = f"docs/features/{next_id}-{feature_name}"
os.makedirs(feature_dir, exist_ok=True)

Fase 1: Design Mínimo

Gerar subagente com a skill de design de recurso, mas instruir para saída MÍNIMA.

result = spawn(
    prompt=draft_spawn_prompt(SkillDefined(
        "Criar design.md MÍNIMO seguindo o procedimento da skill. "
        "GERAR APENAS: Visão Geral (1 parágrafo), Tabela de Restrições Críticas, Estrutura de Módulos. "
        "PULAR: Diagramas de arquitetura, prosa de Mecanismos de Solução, Padrões de Design, Decisões de Design."
    )),
    context_files=[
        skills["design"],
        *[g for g in style_guides if exists(g)],
    ],
    context_data={
        "feature_dir": feature_dir,
        "feature_name": gathered.feature_name,
        "constraints": gathered.constraints,
        "files": gathered.files_to_modify,
        "rough_plan": gathered.rough_plan_summary,
        "minimal_mode": True,
    },
    response_model=PhaseResult,
    isolate_to=Cwd(gathered.workspace)
)

Fase 2: Plano de Teste Mínimo

Gerar subagente com a skill de plano de teste de recurso.

result = spawn(
    prompt=draft_spawn_prompt(SkillDefined(
        "Criar test-plan.md MÍNIMO seguindo o procedimento da skill. "
        "GERAR APENAS: Tabela de Cobertura de Requisitos, Tabela de Verificação de Restrições Críticas. "
        "PULAR: Notas detalhadas de implementação de teste, prosa de teste de integração."
    )),
    context_files=[
        skills["test_plan"],
        f"{feature_dir}/design.md",  # Da Fase 1
        *[g for g in style_guides if exists(g)],
    ],
    context_data={
        "feature_dir": feature_dir,
        "test_names": gathered.test_names,
        "constraints": gathered.constraints,
        "minimal_mode": True,
    },
    response_model=PhaseResult,
    isolate_to=Cwd(gathered.workspace)
)

Fase 3: Plano de Implementação

Gerar subagente com a skill de plano de implementação.

result = spawn(
    prompt=draft_spawn_prompt(SkillDefined(
        "Criar implementation-plan.toml seguindo o procedimento da skill. "
        "Todos os campos obrigatórios - sem modo mínimo. "
        "Garantir que tests[] corresponda exatamente aos nomes de teste do test-plan.md."
    )),
    context_files=[
        skills["impl_plan"],
        f"{feature_dir}/design.md",
        f"{feature_dir}/test-plan.md",
        *[g for g in style_guides if exists(g)],
    ],
    context_data={
        "feature_dir": feature_dir,
        "workspace": gathered.workspace,
        "files": gathered.files_to_modify,
        "rough_plan": gathered.rough_plan_summary,
    },
    response_model=PhaseResult,
    isolate_to=Cwd(gathered.workspace)
)

Fase 4: Verificar Referências Cruzadas

Gerar verificador para checar cobertura de testes.

class VerifyResult(BaseModel):
    valid: bool
    missing_tests: list[str]  # No test-plan mas não no impl-plan
    orphan_tests: list[str]   # No impl-plan mas não no test-plan
    missing_constraints: list[str]  # CC-N não cobertos

result = spawn(
    prompt=draft_spawn_prompt(AdHoc(
        intents=["Verificar se implementation-plan.toml é válido para implementar-commit"],
        context=["Verificar todas as referências cruzadas entre artefatos"],
        goal=Verify(constraints=[
            "Cada teste em test-plan.md aparece exatamente uma vez em commits[].tests",
            "Cada CC-N em design.md tem verificação em test-plan.md",
            "Todos os commits[].files existem ou serão criados",
            "TOML é analisado corretamente",
        ])
    )),
    context_files=[
        f"{feature_dir}/design.md",
        f"{feature_dir}/test-plan.md",
        f"{feature_dir}/implementation-plan.toml",
    ],
    response_model=VerifyResult,
    read_only=True
)

if not result.parsed.valid:
    # Retornar à Fase 3 com erros
    pass

Entrega

Uma vez verificado, os artefatos estão prontos para implementar-commit:

docs/features/NNNN-nome-do-recurso/
├── design.md              # Mínimo: Visão Geral + tabela CC + Estrutura de Módulos
├── test-plan.md           # Mínimo: Apenas tabelas de cobertura
└── implementation-plan.toml  # Completo: Todos os campos obrigatórios

Informe o usuário:

Artefatos prontos. Execute a skill implementar-commit para executar o pipeline TDD.