---
name: spec
description: >
  Spec-driven development v1.0. Cria e gere SPEC.md como contrato entre utilizador e Claude.
  Forca ambos a alinhar antes de codificar. Suporta 3 pesos (light/medium/heavy).
  Use when "spec", "especificacao", "requisitos", "requirements", "define scope",
  "approve spec", "check spec", "o que vamos fazer", "antes de comecar".
author: Descomplicar® Crescimento Digital
version: 1.0.0
quality_score: 70
user_invocable: true
category: productivity
tags: [spec, requirements, scope, planning, project, contract]
desk_project: 65
allowed-tools: Read, Write, Edit, Bash, Glob, mcp__desk-crm-v3, mcp__mcp-time
mcps: desk-crm-v3, mcp-time
---

# /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.**

---

## 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
      - <3 frases de requisitos, sem decisoes tecnicas -> light
      - Feature com decisoes -> medium
      - Projecto novo / multiplas fases -> heavy
   c. CONFIRMAR com utilizador: "Detecto [peso]. Concordas?"
5. EXTRAIR da conversa anterior:
   - Problema: o que o utilizador disse que esta mal ou falta
   - Solucao: o que foi discutido fazer
   - Scope items: accoes concretas mencionadas
   - Exclusoes: o que ficou de fora
   - Decisoes: escolhas ja feitas
   - SE info insuficiente: PERGUNTAR (Regra #9)
     "Preciso entender melhor: [pergunta especifica]"
6. GERAR SPEC.md usando template do peso
   - Preencher frontmatter com dados do projecto
   - NUNCA inventar requisitos
   - Se duvida, marcar com "[CONFIRMAR: ...]"
7. APRESENTAR ao utilizador:
   - Mostrar SPEC.md completo no chat
   - "Este spec captura o que precisa? Que alteracoes?"
   PARAR e esperar resposta.
8. ITERAR ate "esta bem" ou "aprovado"
9. Gravar SPEC.md no directorio actual com status: draft
10. "Spec criado como draft. Quando quiser aprovar: /spec approve"
    OU se utilizador ja disse "aprova": executar protocolo approve
```

**Anti-patterns na extracao:**
- Pedido vago ("faz bonito") -> PERGUNTAR "bonito como? que resultado visual?"
- Scope infinito ("melhora tudo") -> PERGUNTAR "quais os 3 items mais importantes?"
- Sem criterio de sucesso -> PERGUNTAR "como saberemos que esta feito?"

### `/spec approve`

```
1. Ler SPEC.md do directorio actual
   - Se nao existe: "Nenhum spec para aprovar. Use /spec create."
   - Se status ja e approved: "Spec ja aprovado em [data]."
2. Verificar status e draft ou review
3. MOSTRAR resumo ao utilizador:
   ---
   ## Spec para Aprovacao
   **Titulo:** [titulo]
   **Peso:** [peso]
   **Scope:** [N] items a fazer, [M] exclusoes
   **Criterios:** [K] criterios de aceitacao
   **Estimativa:** [Xh] (se heavy)
   ---
4. Usar AskUserQuestion:
   "Aprovar este spec? Apos aprovacao, alteracoes serao tracked como scope creep."
   Opcoes: "Aprovar" / "Preciso de alteracoes"
5. SO se "Aprovar":
   a. mcp__mcp-time__current_time -> data/hora
   b. Actualizar frontmatter:
      status: approved
      approved: YYYY-MM-DD
   c. Adicionar no final: <!-- APPROVED: YYYY-MM-DD by Emanuel -->
   d. Se .desk-project existe:
      - Comentar na task Desk (formato HTML #27):
        <h4>Spec Aprovado</h4>
        <p><strong>Titulo:</strong> [titulo]</p>
        <ul><li>Scope: [N] items</li><li>Peso: [peso]</li></ul>
        <hr>
        <p><strong>Skill:</strong> /spec | <strong>Data:</strong> YYYY-MM-DD</p>
   e. "Spec aprovado. Desenvolvimento pode avancar."
6. Se "Preciso de alteracoes":
   "Que alteracoes? Vou actualizar o draft."
```

### `/spec check`

```
1. Ler SPEC.md
   - Se nao existe: "Sem spec. A trabalhar sem contrato."
   - Se nao aprovado: "Spec em draft. Tratando como guia apenas."
2. Parse SPEC.md:
   - Extrair items de Scope (Faz)
   - Extrair items Nao Faz
   - Extrair Criterios de Aceitacao
3. Analisar trabalho recente:
   a. Se git repo: git diff --stat + git log --oneline -10
   b. Ficheiros modificados recentemente (Glob + stat)
4. Para cada item de Scope (Faz):
   - Avaliar se ha evidencia de trabalho (ficheiros, commits)
   - Marcar: done / in_progress / not_started
5. Detectar SCOPE CREEP:
   - Ficheiros modificados que NAO correspondem a nenhum item do scope
   - Funcionalidades novas nao previstas
   - Para cada deteccao: "SCOPE ALERT: [ficheiro/funcao] fora do spec"
6. OUTPUT:
   ---
   ## Spec Check: [titulo]

   ### Progresso: X/Y scope items
   - [x] Item 1 (ficheiros: a.php, b.js)
   - [ ] Item 2 (nao iniciado)
   - [~] Item 3 (em progresso)

   ### Criterios: X/Y verificaveis
   - [x] Criterio 1: verificado
   - [ ] Criterio 2: pendente

   ### Alertas de Scope
   - [ficheiro]: modificado mas fora do scope

   ### Recomendacao
   [Continuar / Parar e alinhar / Criar novo spec para extras]
   ---
```

### `/spec update`

```
1. Ler SPEC.md
2. SE status == approved ou in_progress:
   a. AVISAR: "Spec aprovado. Alteracoes serao registadas como scope delta."
   b. Perguntar: "O que mudou?"
   c. Adicionar seccao Alteracoes:
      ### [DATA] - [Descricao]
      - Adicionado: [item]
      - Removido: [item]
      - Razao: [porque]
   d. Incrementar scope_changes no frontmatter
   e. Actualizar status: amended
   f. CONFIRMAR com utilizador antes de gravar
3. SE status == draft:
   a. Edicao normal, sem tracking de amendments
   b. Perguntar o que alterar
   c. Aplicar e mostrar resultado
```

### `/spec bypass`

```
1. Criar ficheiro /tmp/claude-spec-gate-bypass com timestamp
2. "Bypass activo por 30 minutos. O hook spec-gate nao bloqueara."
3. "Usar para quick fixes. Para trabalho significativo, criar spec."
```

### `/spec review`

```
1. Ler SPEC.md
2. Verificar status == draft
3. Actualizar status: review
4. "Spec movido para review. Leia e use /spec approve quando pronto."
```

---

## Lifecycle dos Status

```
draft -> review -> approved -> in_progress -> completed
                      |
                      v
                   amended (alteracoes pos-aprovacao)
```

- **draft**: Criado, nao validado
- **review**: Pronto para revisao do Emanuel
- **approved**: Contrato aceite, trabalho pode comecar
- **in_progress**: Trabalho em curso (auto, quando primeiro ficheiro editado)
- **amended**: Aprovado mas com alteracoes (scope creep tracked)
- **completed**: Todos os items de scope e criterios verificados

---

## Integracao Phase Gates

| Gate | Equivalencia |
|------|-------------|
| G1: Scope aprovado | SPEC.md approved |
| G2: Prototipo funcional | Sprint mid-checkpoint |
| G3: Testes passam | /spec check -> todos criterios OK |
| G4: Docs completa | SPEC.md status -> completed |

---

## Regras de Ouro

1. **NUNCA** comecar codigo significativo sem spec (hook garante isto)
2. **NUNCA** auto-aprovar spec - so o Emanuel aprova
3. **NUNCA** inventar requisitos no spec - se falta info, PERGUNTAR
4. **SEMPRE** mostrar spec ao utilizador antes de gravar
5. **SEMPRE** marcar `[CONFIRMAR: ...]` quando ha ambiguidade
6. **SEMPRE** linkar ao Desk CRM quando .desk-project existe
7. Spec e contrato bilateral - ambos comprometem-se
8. Alteracoes apos aprovacao sao legtimas mas devem ser tracked