plan
/plan
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).
- Author
- jotjunior ↗
- Repository
- cstk ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 7
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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).
Triggers from the description
Arguments
/plan [caminho para spec ou descricao da feature]
Original author 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).
How it works
- Pre-requisitos
- Proximos passos
- Argumentos
- Leitura de artefatos foundational (briefing + constitution)
- FLUXO DE EXECUCAO
- ETAPA 1: CONTEXTO
- ETAPA 2: CONSTITUTION CHECK
- ETAPA 3: TECHNICAL CONTEXT
- ETAPA 4: PHASE 0 — RESEARCH
- ETAPA 5: PHASE 1 — DESIGN
SKILL.md preview
---
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 `<projeto-alvo>/.claude/agente-00c-state/state.json` existente,
OU `<projeto-alvo>/.claude/feature-00c-state/<short>/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 <hit|miss-drift|miss-disabled> \
[--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
`<projeto-alvo>/.claude/agente-00c-state/state.json` existente, OU
`<projeto-alvo>/.claude/feature-00c-state/<short>/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 <token>` +
`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.
Files in this package (7)
- SKILL.md 16 KB
- evals/triggers.jsonl 1 KB
- templates/contracts.md 1 KB
- templates/data-model.md 1 KB
- templates/plan.md 2 KB
- templates/quickstart.md 2 KB
- templates/research.md 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · jotjunior/cstk | 100 | MIT |
| mlophez/polix-ai | 100 | Apache-2.0 |
| jeremylongshore/tons-of-skills-marketplace | 100 | MIT |
| duronext/jig | 100 | MIT |
| rjmurillo/ai-agents | 100 | MIT |
| rjmurillo/ai-agents | 100 | MIT |
| rjmurillo/ai-agents | 100 | MIT |
| xoai/sage | 100 | MIT |
| JoDi-27/JoDi-SDD | 100 | MIT |
Database snapshot: 13.11.2026 · package version 3bb11409886e (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95technical-design
Turn business requirements into a technical plan, data model, interface contracts, and deployment plan. Use to establish technical design before production development, or to design affected modules and interfaces in an existing system. - 100prd-to-spec
Transform a PRD into a technical SPEC document — architecture, API design, data model, error handling, and implementation contracts. Triggers on: prd-to-spec, prd to spec, prd转spec, 需求转设计, 需求转规格, generate spec from prd, design from prd, 技术方案, 设计方案. - 100blueprint
Use when a written feature spec needs its technical plan: \"plan this spec\", \"how should we build this spec?\", \"make the technical plan for this feature\", a spec in specs/ with no plan.md yet, or a plan that a spec or constitution change has made stale. Not for a feature… - 90detailed-design
Produces the per-feature technical design — the first skill in the construction loop, run once for each vertical slice as it reaches the front of the implementation plan. Reads the feature's spec from the plan, the FR/UC IDs it implements, the architecture's conceptual domain… - 100prd-v06-technical-specification
Define implementation contracts (APIs and data models) that developers will build against during PRD v0.6 Architecture. Triggers on requests to define APIs, design database schema, create data models, or when user asks "define APIs", "data model", "database schema", "API… - 100spec-design
Write OpenSpec design.md and tasks.md artifacts. TRIGGER when: producing a technical design or task checklist for a spec-driven feature. SKIP: writing proposal.md (use spec-research); executing tasks.md (use spec-develop).