--- name: plan description: 'Technical implementation plan — the technical HOW: architecture, data model, API contracts, research, test scenarios. Use when the user wants the technical design of a feature (how to structure/build it, define contracts/schema), whether or not a formal spec.md exists yet. Triggers: "plan", "criar plano", "planejar implementacao", "desenho tecnico", "definir arquitetura/contratos/modelo de dados". Skip when defining WHAT/for-whom in natural language (use specify) or breaking work into tasks (create-tasks).' argument-hint: "[caminho para spec ou descricao da feature]" allowed-tools: - Read - Write - Edit - Glob - Grep - Bash - Agent --- # Skill: Plano de Implementacao Tecnico Gere um plano de implementacao completo a partir de uma feature spec, cobrindo arquitetura, decisoes tecnicas, modelo de dados e contratos. ## Pre-requisitos **Obrigatorio**: `docs/specs/{feature}/spec.md` ja existente. Sem spec, abortar. **Recomendado**: - `/clarify` executado (reduz NEEDS CLARIFICATION na Etapa 3) - `docs/constitution.md` existente (usado como gate — violacoes sao bloqueantes) ## Proximos passos 1. `/checklist` — gerar quality gate antes de implementar 2. `/create-tasks` — decompor o plano em backlog executavel 3. `/analyze` — apos ter tasks, validar consistencia cross-artifact ## Argumentos $ARGUMENTS --- ## Leitura de artefatos foundational (briefing + constitution) Antes de ler `docs/briefing.md` (ou o legado `docs/01-briefing-discovery/briefing.md`) ou `docs/constitution.md` direto do disco, verifique se ha cache valido populado pelo agente-00c ou feature-00c. Aditivo — se nao houver cache, leia direto do disco conforme comportamento padrao (FR-CACHE-014). 1. **Detectar agente ativo**: variavel `AGENTE_00C_STATE_DIR` setada, OU `/.claude/agente-00c-state/state.json` existente, OU `/.claude/feature-00c-state//state.json`. 2. **Se ativo**, tente consumir o resumo via Bash: ```bash ~/.claude/skills/agente-00c-runtime/scripts/state-cache.sh get-resumo \ --state-dir "$SD" --artifact briefing ``` - **Exit 0** + stdout nao-vazio: use o resumo como conteudo. - **Exit 1**: cache miss (campo ausente, estrategia=passthrough, drift detectado) — caia em leitura direta. - **Exit 2**: erro fatal (state.json corrompido) — aborte com diagnostico do stderr. Mesmo protocolo para `--artifact constitution`. NOTA: esta skill tem dependencia HARD em `docs/constitution.md` (gate de violacoes na ETAPA 2). Se cache miss + arquivo source ausente em disco, isso eh erro de pre-requisito, nao falha do cache. 3. **Apos consumo** (hit ou miss), registre metrica via: ```bash ~/.claude/skills/agente-00c-runtime/scripts/state-cache.sh metrics-bump \ --state-dir "$SD" --tipo \ [--chars-economizados N] ``` onde N = `source_chars - resumo_chars` quando hit, ou 0 caso contrario. 4. **Standalone** (sem state.json): leia direto do disco. Comportamento identico a versao pre-cache. Spec: `docs/specs/_archived/agente-00c-artifact-cache/spec.md` FR-CACHE-008. --- ## FLUXO DE EXECUCAO ``` 1. CONTEXTO Carregar spec, constitution e projeto | 2. CONSTITUTION CHECK Gate obrigatorio antes de prosseguir | 3. TECHNICAL CONTEXT Preencher stack, deps, constraints | 4. PHASE 0 — RESEARCH Resolver unknowns, pesquisar libs | 5. PHASE 1 — DESIGN Modelo de dados, contratos, quickstart | 6. PLAN DOCUMENT Consolidar plano final | 7. RE-CHECK Revalidar constitution pos-design | 8. SALVAMENTO Salvar artefatos e reportar ``` --- ## ETAPA 1: CONTEXTO ### 1.1 Localizar Spec Use $ARGUMENTS para encontrar a spec: 1. **Caminho direto**: usar como fornecido 2. **Nome da feature**: buscar `docs/specs/{name}/spec.md` 3. **Glob**: listar `docs/specs/*/spec.md` e pedir ao usuario para escolher Se spec nao encontrada: instruir usuario a rodar `/specify` primeiro. ### 1.2 Carregar Documentos ``` OBRIGATORIO: -- Feature spec (spec.md) OPCIONAL (se existirem): -- docs/constitution.md (principios de governanca) -- CLAUDE.md (convencoes do projeto) -- README.md (contexto geral) -- docs/specs/{feature}/research.md (pesquisa previa, se rerrun) ``` ### 1.3 Extrair da Spec - User stories com prioridades - Functional requirements - Key entities - Success criteria - Edge cases - [NEEDS CLARIFICATION] pendentes (devem ser resolvidos antes ou durante Phase 0) --- ## ETAPA 2: CONSTITUTION CHECK ### 2.1 Gate Obrigatorio Se `docs/constitution.md` existe: 1. Carregar todos os principios MUST/SHOULD 2. Para cada principio, verificar se a feature spec esta em conformidade 3. Documentar resultado: ```markdown ## Constitution Check *GATE: Deve passar antes do Phase 0. Re-checar apos Phase 1.* | Principio | Status | Notas | |-----------|--------|-------| | [Nome] | PASS / FAIL / N/A | [Detalhes] | ``` 4. Se FAIL em principio MUST: **ERROR** — nao prosseguir ate resolver Se constitution nao existe: pular esta etapa e documentar "No constitution found". --- ## ETAPA 3: TECHNICAL CONTEXT ### 3.1 Preencher Contexto Ver secao **Technical Context** em `templates/plan.md` (mesmo diretorio desta skill). Preencher cada campo detectando do projeto e da spec — marcar unknowns como `NEEDS CLARIFICATION` apenas apos tentar inferir do codebase. ### 3.2 Inferencia Antes de marcar NEEDS CLARIFICATION, tentar inferir de: - `go.mod`, `package.json`, `pyproject.toml`, `Cargo.toml` — linguagem e deps - `Dockerfile`, `docker-compose.yml`, K8s manifests — platform - `CLAUDE.md` — convencoes e stack - Patterns existentes no projeto — testing, storage --- ## ETAPA 4: PHASE 0 — RESEARCH ### 4.0 Modo autonomo: NEEDS CLARIFICATION estrutural NAO se resolve aqui (FR-009) Antes de resolver qualquer unknown, detecte execucao autonoma pelo mesmo criterio da secao "Leitura de artefatos foundational" acima: variavel `AGENTE_00C_STATE_DIR` setada, OU `/.claude/agente-00c-state/state.json` existente, OU `/.claude/feature-00c-state//state.json` existente. **Fora de execucao autonoma** (uso interativo direto da skill): comportamento atual preservado, sem mudanca — siga para 4.1 normalmente. **Em execucao autonoma**: para cada `NEEDS CLARIFICATION` do Technical Context que corresponda a um dos eixos estruturais (linguagem/runtime, stack/ frameworks, arquitetura de alto nivel, persistencia principal, ambiente de execucao alvo, tier de entrega — ver `## Definicao: classe estrutural` da spec `structural-decision-human-gate`), o Phase 0 desta skill **NAO o resolve por inferencia**: deixe o campo como `NEEDS CLARIFICATION` em `research.md`/no Technical Context e retorne o controle ao orquestrador. Nao e responsabilidade desta skill decidir por conta propria uma stack, arquitetura ou plataforma-alvo — isso e responsabilidade do operador via bloqueio humano (`state-decisions.sh register --classe estrutural --eixo ` + `bloqueios.sh register`, ver a prosa do orquestrador). O gate de qualidade ja existente da tabela de gates (`## Quality Gates complementares`, secao `plan`/`owasp-security`+`doc-quality`) barra o artefato se um eixo estrutural ficar sem consentimento registrado — esta skill nao precisa implementar o gate, so **nao antecipar** a resolucao. NEEDS CLARIFICATION fora dos eixos estruturais (detalhe de implementacao, biblioteca dentro de uma stack ja decidida, nome de convencao) seguem normalmente para 4.1 — a excecao e so para os 6 eixos fechados. ### 4.1 Resolver Unknowns Para cada NEEDS CLARIFICATION no Technical Context: - Pesquisar no projeto por evidencias - Se nao resolvivel: criar task de pesquisa Para cada dependencia/tecnologia: - Verificar best practices para o contexto ### 4.2 Dispatch de Research (para unknowns complexos) Para projetos complexos, usar Agent para pesquisa paralela: ``` Agent 1: "Research {unknown} for {feature context}" Agent 2: "Find best practices for {tech} in {domain}" ``` ### 4.3 Consolidar em research.md Use `templates/research.md` como base. Uma secao `## Decision N` por unknown resolvido, com **Decision / Rationale / Alternatives considered**. **Output**: `docs/specs/{feature}/research.md` com todos os NEEDS CLARIFICATION resolvidos. --- ## ETAPA 5: PHASE 1 — DESIGN **Prerequisito**: research.md completo (todos os NEEDS CLARIFICATION resolvidos) ### 5.1 Modelo de Dados Base: `templates/data-model.md`. Extrair entidades da spec, uma secao `## Entity: Name` por entidade, com tabela de campos, relacionamentos e state transitions. **Output**: `docs/specs/{feature}/data-model.md` ### 5.2 Contratos de Interface Se o projeto expoe interfaces externas (APIs, CLI, eventos), use `templates/contracts.md` — um arquivo por grupo de endpoints em `docs/specs/{feature}/contracts/`. Pular se projeto e puramente interno (build scripts, one-off tools). **Output**: `docs/specs/{feature}/contracts/*.md` > **INEGOCIAVEL — contrato de interface EXISTENTE nao se inventa (Constitution VI).** > Ao documentar uma API/evento que JA EXISTE, as assinaturas de request/response > (nomes de campos, tipos, estrutura), URLs, endpoints e querystrings DEVEM ser > extraidos da fonte real: codigo-fonte do servico, OpenAPI/Swagger, doc oficial, ou > uma chamada de fato observada. Se voce nao tem o contrato e nao tem de onde busca-lo, > **PARE e registre bloqueio humano** — nunca suponha nomes de propriedades nem rotas. > (Projetar do zero um contrato AINDA inexistente e legitimo — marque-o explicitamente > como `[PROPOSTA — a validar na implementacao]`, distinto de um contrato afirmado como > real. O perigo e afirmar como real algo que voce inventou.) ### 5.3 Quickstart / Cenarios de Teste Base: `templates/quickstart.md`. Um cenario por fluxo critico (happy path + ao menos um error case), no formato "1. Passo → 2. Passo → **Expected**: resultado". **Output**: `docs/specs/{feature}/quickstart.md` **Obrigatorio para features com borda backend↔frontend**: incluir cenario "Roundtrip End-to-End" que faz uma chamada REAL ao backend (nao mock, nao fixture), captura o payload de resposta e compara o shape contra o contrato declarado em §5.4. Razao: 40 ondas historicas mascararam um drift snake_case vs camelCase porque os testes parseavam mocks (nao o payload real do backend) — apenas roundtrip empirico expoe esse tipo de divergencia antes do drift se acumular. ### 5.4 Convencoes de Borda (obrigatorio para features com 2+ camadas) Quando a feature atravessa fronteiras (backend ↔ frontend, DB ↔ backend, broker ↔ consumer), declarar EXPLICITAMENTE em uma tabela no `plan.md` qual e a fonte da verdade de cada convencao. Razao: dec-172 e dec-173 da execucao-fonte resolveram em FASE 8 (onda-040) uma divergencia snake_case vs camelCase que existia desde o contrato (dec-064). 40 ondas de retrabalho porque a convencao nao foi declarada upfront. Estrutura obrigatoria do `plan.md` (secao nova entre "Project Structure" e "Complexity Tracking"): ```markdown ## Convencoes de Borda | Camada | Case style | Validacao | Fonte da verdade | |--------|------------|-----------|------------------| | DB columns (PostgreSQL) | snake_case | constraint check + migration | `migrations/*.sql` | | Backend DTO (Go/TS) | camelCase | json tags / Zod | `internal/dto/*.go` ou `src/types/*.ts` | | Frontend DTO (TS) | camelCase | Zod parse no fetch | `web/src/types/*.ts` (re-export de shared-types) | | API payload (request/response) | camelCase | Zod em ambos os lados | `contracts/*.md` | | URL query/path params | kebab-case | router | `routes.ts` ou equivalente | **Mapper layer (DB ↔ DTO)**: localizacao + responsavel: - Backend: `internal/repository/mapper.go` (snake_case ↔ camelCase) - ORM auto-mapping: SIM/NAO — se SIM, citar lib (gorm, sqlc, kysely) **Validacao Zod**: - Em qual borda? request, response, ambos? - Schema compartilhado? localizar em `packages/shared-types/`? ``` Se a feature e single-layer (ex: biblioteca pura, CLI tool, script), pular essa secao com nota explicita "N/A — single-layer". **Output**: `docs/specs/{feature}/plan.md` §Convencoes de Borda --- ## ETAPA 6: PLAN DOCUMENT ### 6.1 Template do Plano Consolidar tudo em `templates/plan.md` preenchido com: - **Summary** — requisito primario + abordagem tecnica da pesquisa - **Technical Context** — da Etapa 3, com NEEDS CLARIFICATION ja resolvidos - **Constitution Check** — da Etapa 2 - **Project Structure** — documentacao (feature dir) + source code (arvore real do projeto) - **Complexity Tracking** — preencher APENAS se houve violacoes de constitution que precisam justificativa **Output**: `docs/specs/{feature}/plan.md` --- ## ETAPA 7: RE-CHECK ### 7.1 Revalidar Constitution Se constitution existe, re-checar principios apos design: - Design introduziu complexidade nao justificada? - Principios MUST continuam respeitados? - Atualizar tabela de Constitution Check se necessario --- ## ETAPA 8: SALVAMENTO ### 8.1 Artefatos Gerados Listar todos os arquivos criados: ```markdown ## Artefatos | Arquivo | Status | |---------|--------| | docs/specs/{feature}/plan.md | Criado | | docs/specs/{feature}/research.md | Criado | | docs/specs/{feature}/data-model.md | Criado | | docs/specs/{feature}/contracts/*.md | Criado (se aplicavel) | | docs/specs/{feature}/quickstart.md | Criado | ``` ### 8.2 Reportar ```markdown ## Plano Criado **Feature**: [short-name] **Diretorio**: docs/specs/{feature}/ **Artefatos**: [N] arquivos gerados **Constitution**: PASS / N/A **NEEDS CLARIFICATION restantes**: 0 ### Proximos Passos 1. `/checklist` — Gerar quality gate antes de implementar 2. `/create-tasks` — Decompor plano em tarefas executaveis 3. `/analyze` — Validar consistencia entre spec, plan e tasks (apos tasks) ``` --- ## REGRAS IMPORTANTES - **NEVER gerar codigo nesta fase** — apenas documentacao tecnica - **NEEDS CLARIFICATION devem ser resolvidos** no Phase 0 (nao deixar para implementacao) - **Constitution violations sao bloqueantes** — nao prosseguir sem resolver - **Usar Agent para pesquisa paralela** em projetos complexos com multiplas unknowns - **Paths devem ser reais** — verificar existencia de diretorios antes de referenciar - **Phase 0 vem antes de Phase 1** — nao projetar modelo de dados com unknowns pendentes --- ## Gotchas ### NUNCA gerar codigo nesta fase Plano e documentacao tecnica, nao implementacao. Se o impulso e escrever uma funcao ou SQL concreto, pare — vai para `/execute-task`. O plano descreve contratos, schemas e estrutura, nao implementa. ### NEEDS CLARIFICATION devem morrer no Phase 0, nao em Phase 1 Projetar modelo de dados ou contratos com unknowns pendentes e retrabalho garantido. Se Phase 0 nao resolveu, interromper e voltar ao usuario — nao prosseguir para design com lacunas tecnicas. ### Violacao de constitution em principio MUST e bloqueante Nao tente "documentar a violacao em Complexity Tracking e seguir". MUST nao negocia. Se o plano precisa violar um MUST, revisar escopo ou emendar constituicao primeiro. ### Paths no Project Structure devem ser REAIS Listar diretorios inventados ("/src/features/x") que nao existem no projeto cria plano desalinhado com o codebase. Sempre verificar estrutura existente antes de desenhar a arvore no plano. ### Re-check de constitution apos Phase 1 nao e formalidade Design pode introduzir complexidade nao justificada (4o servico, camada adicional) que viola principios. O re-check e o gate final — rode serio, nao marque "PASS" por inercia. ### Technical Context com "NEEDS CLARIFICATION" em campo inferivel e desleixo Antes de marcar unknown, tentar inferir de `go.mod`, `package.json`, `Dockerfile`, `CLAUDE.md`. Marcar "NEEDS CLARIFICATION: linguagem" num repo com `pyproject.toml` e sinal de que o Phase 0 nao leu o projeto.