Skip to content
Skills Library
Programming · Planning

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).

Repository
cstk ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

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

plancriar planoplanejar implementacaodesenho tecnicodefinir arquitetura/contratos/modelo de dados

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

  1. Pre-requisitos
  2. Proximos passos
  3. Argumentos
  4. Leitura de artefatos foundational (briefing + constitution)
  5. FLUXO DE EXECUCAO
  6. ETAPA 1: CONTEXTO
  7. ETAPA 2: CONSTITUTION CHECK
  8. ETAPA 3: TECHNICAL CONTEXT
  9. ETAPA 4: PHASE 0 — RESEARCH
  10. ETAPA 5: PHASE 1 — DESIGN
Original SKILL.md headings · 419 lines, 2,073 words
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

RepositoryScoreLicence
This page · jotjunior/cstk100MIT
mlophez/polix-ai100Apache-2.0
jeremylongshore/tons-of-skills-marketplace100MIT
duronext/jig100MIT
rjmurillo/ai-agents100MIT
rjmurillo/ai-agents100MIT
rjmurillo/ai-agents100MIT
xoai/sage100MIT
JoDi-27/JoDi-SDD100MIT

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).

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.