---
name: spec
description: Spec-driven development — cria e gere SPEC.md como contrato entre utilizador e Claude. Suporta 3 pesos (light/medium/heavy).
disable-model-invocation: true
layer: wiki
---

# /spec v1.0 - Spec-Driven Development

Contrato bilateral: forca o Emanuel a definir o que quer e forca o Claude a provar que entendeu.

**Sem spec aprovado, sem codigo.**

## Contexto NotebookLM

ANTES de executar, consultar notebooks para contexto especializado:

| Notebook | ID | Consultar quando |
|----------|-----|-----------------|
| Gestão de Projectos e Agile | 0c9c079c-a426-486c-99eb-1564d42d37ad | Sempre |

```
mcp__notebooklm__notebook_query({
  notebook_id: "0c9c079c-a426-486c-99eb-1564d42d37ad",
  query: "<adaptar ao contexto do pedido do utilizador>"
})
```

Integrar insights do NotebookLM nas recomendações e decisões.

---

## Comandos

| Comando | Funcao |
|---------|--------|
| `/spec` | Mostrar spec actual ou guiar criacao |
| `/spec create` | Criar SPEC.md a partir de conversa |
| `/spec create light` | Spec minimo (<2h) |
| `/spec create heavy` | Spec completo com milestones e riscos |
| `/spec approve` | Marcar como aprovado (so Emanuel) |
| `/spec update` | Alterar spec (track amendments se aprovado) |
| `/spec check` | Validar trabalho actual vs spec |
| `/spec review` | Mover draft -> review |
| `/spec bypass` | Criar bypass temporario (30min) para quick fixes |

---

## Pesos

| Peso | Quando | Seccoes |
|------|--------|---------|
| **light** | Quick fix, tarefa simples, <2h | Problema, Solucao, Scope |
| **medium** | Feature, modulo, 2-8h | + Criterios de Aceitacao, Decisoes |
| **heavy** | Projecto novo, >8h | + Milestones, Riscos, Dependencias |

**Auto-deteccao de peso:**
- Conversa com <3 frases de requisitos -> light
- Feature especifica com decisoes tecnicas -> medium
- Projecto novo / multiplos componentes -> heavy
- O utilizador pode sempre forcar o peso

---

## Template SPEC.md

### Light

```markdown
---
spec_version: 1.0
weight: light
status: draft
created: YYYY-MM-DD
updated: YYYY-MM-DD
approved: null
desk_project: null
desk_task: null
---

# SPEC: [Titulo]

## Problema
[O que esta mal ou falta]

## Solucao
[O que se vai fazer]

## Scope
### Faz
- [ ] Item 1
- [ ] Item 2

### Nao Faz
- [Item excluido]
```

### Medium (default)

```markdown
---
spec_version: 1.0
weight: medium
status: draft
created: YYYY-MM-DD
updated: YYYY-MM-DD
approved: null
desk_project: null
desk_task: null
sprint: null
scope_changes: 0
---

# SPEC: [Titulo]

## Problema
[O que esta mal ou falta. Nas palavras do utilizador.]

## Solucao
[O que se vai fazer. Abordagem escolhida e porque.]

## Scope

### Faz
- [ ] Item 1
- [ ] Item 2

### Nao Faz
- Item excluido 1

## Criterios de Aceitacao
1. DADO [contexto] QUANDO [accao] ENTAO [resultado]
2. ...

## Decisoes Tecnicas

| Decisao | Razao |
|---------|-------|
| [Escolha] | [Porque] |

<!-- APPROVED: YYYY-MM-DD by [nome] -->
```

### Heavy

```markdown
---
spec_version: 1.0
weight: heavy
status: draft
created: YYYY-MM-DD
updated: YYYY-MM-DD
approved: null
desk_project: null
desk_task: null
sprint: null
scope_changes: 0
---

# SPEC: [Titulo]

## Problema
[Contexto completo do problema]

## Solucao
[Abordagem detalhada]

## Scope

### Faz
- [ ] Item 1
- [ ] Item 2

### Nao Faz
- Item excluido 1

## Criterios de Aceitacao
1. DADO [contexto] QUANDO [accao] ENTAO [resultado]
2. ...

## Decisoes Tecnicas

| Decisao | Razao |
|---------|-------|
| [Escolha] | [Porque] |

## Milestones

| # | Milestone | Data | Criterio |
|---|-----------|------|----------|
| M1 | [Nome] | [Data] | [Como saber que esta feito] |

## Riscos

| Risco | Probabilidade | Impacto | Mitigacao |
|-------|--------------|---------|-----------|
| [Risco] | Alta/Media/Baixa | Alto/Medio/Baixo | [Plano] |

## Dependencias
- [Dependencia externa 1]
- [Componente que precisa estar pronto primeiro]

## Alteracoes (pos-aprovacao)
### [DATA] - [Descricao]
- Adicionado: X
- Removido: Y
- Razao: Z

<!-- APPROVED: YYYY-MM-DD by [nome] -->
```

---

## Protocolos

### `/spec` (sem argumentos)

```
1. Procurar SPEC.md no directorio actual (ou pais, max 3 niveis)
2. SE encontrado:
   a. Ler e mostrar resumo:
      - Titulo, peso, status
      - Scope: X/Y items feitos
      - Aprovacao: sim/nao (data)
   b. Sugerir accoes: approve, check, update
3. SE nao encontrado:
   a. "Nenhum spec encontrado nesta pasta."
   b. "Quer criar um? Descreva o que precisa ou use /spec create."
```

### `/spec create` [weight]

```
1. mcp__mcp-time__current_time -> data actual
2. Verificar se SPEC.md ja existe
   - Se existe e status != completed:
     "Ja existe um spec activo. Usar /spec update ou apagar o existente?"
     PARAR e esperar resposta.
3. Detectar contexto do projecto:
   a. Ler .desk-project se existe -> project_id, project_name, desk_task
   b. Se nao existe: "Em que projecto estamos? (ou 'novo')"
4. Determinar peso:
   a. Se argumento dado (light/medium/heavy): usar esse
   b. Se nao: analisar conversa anterior