# MORPH-SPEC Runtime Instructions

> by Polymorphism Tech — Spec-driven development harness for Claude Code

## Como começar cada sessão

1. Leia `.morph/framework/MORPH.md` — o charter NLH com papéis, fases, gates e skills.
2. Leia `.morph/state.json` — índice fino e gitignored (status + updatedAt por feature), reconstruído a cada load. **Não o edite à mão.** Estado autoritativo e commitado de cada feature: `.morph/features/{feature}/feature.json`.
3. Se existir `.morph/features/{feature}/handoff.md` para a feature ativa, **leia-o antes de re-derivar contexto à mão** — documento de retomada comprimido (regenere com `morph-spec handoff <f>` se parecer velho).
4. Assuma o papel correspondente (Orchestrator/Specialist/Evaluator) e continue o trabalho. Não aguarde instrução do usuário se há trabalho pendente entre gates.

Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.

## Regras críticas

**NUNCA:**
- Pular para código sem proposal aprovado (Gate 1) e plano aprovado (Gate 2).
- Modificar o contrato do plano depois do Gate 2 — `spec.md`, `mandate.md`, e os campos `title`/`description`/`dependencies`/`effort`/`doneCriteria`/`group`/`agent`/`standards` de `tasks.json` ficam congelados (`protect-spec-files` bloqueia `Write`/`Edit`); mutáveis: `status`/`outputs`/`notes` (ver SEMPRE). **Fato errado sobre o código não exige revogar gate**: bloco `## Errata` append-only no fim, corpo intacto (MORPH.md §3). **Use cases (`2-plan/usecases/UC-*.md`) NÃO congelam** — editáveis por design.
- Escrever critérios de aceite no `proposal.md` — pertencem aos use cases (pós-condição **observável em teste**, chega **literal** ao `doneCriteria`).
- Editar `.morph/specs/usecases/` à mão — só o `finish` escreve lá (lê de `2-plan/usecases/`, carimba `status: implemented`, sobrescreve por ID). Mudar um UC existente (`bug`): copie para `2-plan/usecases/` da feature e corrija lá.
- Listar perguntas em texto simples — sempre `AskUserQuestion` (1-4 perguntas por chamada).
- Usar `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, repository genérico (`IRepository<T>`/`IUnitOfWork`), ou SQL cru sem justificativa.
- Editar `taskScores`, `gateDecisions` ou gates de `feature.json` à mão — sempre via `morph-spec score`/`gate-check`/`approve` (timestamps server-side; Edit manual colide com o hook `state-sync`).

**SEMPRE:**
- Auto-advance entre tarefas durante a fase implement — não pause sem ambiguidade bloqueante.
- Abrir toda feature `feature`/`bug` com a escolha de **modo de descoberta** (entrevista ou automático), depois de varrer o ambiente. **No modo entrevista, uma pergunta por chamada de `AskUserQuestion`** — o "1-4 por chamada" não é licença para agrupar a entrevista. O Gate 1 pausa sempre nesse modo.
- Atualizar `tasks.json` ao concluir cada task gravando só os campos mutáveis `status`/`outputs`/`notes` — via `Write` OU `Edit`.
- Apresentar gates com o template fixo (MORPH.md/morph-plan). **A pergunta PRECISA nomear a feature** ("Gate 2 — Plano de {feature} aprovado?") — é por esse nome que `state-sync` atribui a aprovação ao `feature.json` certo. Sem nome, com mais de uma feature na árvore, ele **recusa gravar** — aprove com `morph-spec approve <feature> <gate>`.
- Registrar decisões não triviais em `decisions.md`.
- Aplicar `morph-eval` após cada tarefa; silêncio em score ≥ 9 é o sinal correto. Score < 9 dispara o loop de correção autônomo, sem escalar ao humano entre tarefas. No Gate 3, o score composto vem do **avaliador independente** despachado pela `morph-review` — nunca de auto-avaliação de quem implementou.
- Em `hotfix`, o Gate 3 pausa **sempre** para um humano, mesmo em `trust: auto` — `approve ... review --mode auto` é recusado; aprove com `--approver`.
- Confirmar antes de `finish`/`archive`/`delete` se o SessionStart avisar que outra sessão tem claim vivo na mesma feature.
- **Contrato do relatório final** em todo dispatch de sub-agent: (1) grava o relatório em arquivo canônico ANTES de encerrar — `.morph/features/{f}/3-implement/reports/{taskId}.md` (avaliador: `4-review/evaluator-report.md`) — com os 4 itens obrigatórios (o quê / arquivos / problemas / auto-score 0-10); é o retorno autoritativo, nunca chamar `SendMessage`; (2) não tocar `tasks.json`/`feature.json`/`state.json` nem o board de sessão; (3) sem build/test compartilhado em batch paralelo sem isolamento. Racional completo: `MORPH.md` §6. Templates: `morph-implement` §4, `morph-apply` §3b. **O orquestrador lê o arquivo ao retomar controle** — nunca confia só na mensagem de retorno da tool.

## Slash commands

| Comando | Propósito |
|---------|-----------|
| `/morph-proposal {feature}` | Entendimento de negócio + plano (Gates 1 e 2). Passo 0 roteia por tipo de trabalho (`feature`/`bug`/`chore`/`hotfix`) |
| `/morph-hotfix {feature}` | ADW cirúrgico de hotfix (scout → fix → gate humano → ship) |
| `/morph-apply {feature}` | Execução autônoma + review (Gate 3) |
| `/morph-status [feature]` | Status da feature ativa (ou a especificada) |
| `/morph-archive {feature}` | Arquiva-**sem-integrar** (legadas/faxina) — wrapper de `archive`. Fechamento normal = `finish --pr\|--merge` |
| `/morph-preflight` | Validação pré-deploy (specs, contratos, testes, infra) |
| `/morph-troubleshoot [erro]` | Diagnóstico de erros .NET/Next.js com root-cause analysis |

**Comandos CLI de gate e de estado** (a LLM os usa em vez de editar o estado à mão):

| Comando | Propósito |
|---------|-----------|
| `approve <f> <gate> --mode auto` | Aprova gate em `trust:auto`. Gate 3 exige `evaluator-report.md` (ou `--self-assessed`); `hotfix` nunca aceita `--mode auto` — use `--approver` |
| `advance <f>` | Aprova o gate corrente + já cria a pasta da próxima fase |
| `score <f> <task> <n> [--dims a,c,q,t]` | Grava `taskScores` server-side (nunca à mão) |
| `gate-check <f> <gate> [--json]` | Default: decide via sinais do disco (`shouldPauseGate`) |
| `gate-decision <f> <gate> --pause <bool>` | Escape manual: risco que o disco não vê |
| `create <f> --description "..." --type <t>` | Nasce a feature + `feature.json`; `--worktree` já isola |
| `list [--all] [--json]` | Quadro de auditoria: feature × workType × status × gates |
| `delete <f> [--archive] [--force]` | Remove feature; recusa se gate aprovado sem `--force` |
| `retype <f> <tipo>` | Muda o workType mid-flight; bloqueado após o Gate 3 |
| `finish <f> --pr\|--merge` | Encerramento único: arquiva, promove use cases, desmonta worktree. Integra só no `--merge`; `--pr` abre PR e fica `aguardando-merge` até alguém mergear |
| `archive <f>` | Arquiva sem integrar (legadas/faxina) |
| `worktree setup\|provision\|link\|remove\|list` | Ciclo do worktree; `provision` = isolamento de task; `remove` é a única remoção segura |
| `branch prune [--dry-run]` | Apaga branch já integrada, inclusive squash-merge; nunca a com PR aberto |
| `handoff <f>` | Regenera o documento de retomada da feature |
| `fleet` | Visão agregada de toda feature ativa (raiz + worktrees) |
| `claim [f] [--release] [--list]` | Posse advisory — confirme antes de `finish`/`archive`/`delete` se outra sessão tiver claim vivo |
| `dag <f>` | DAG de `tasks.json`: sequencial/paralelo, recomenda isolamento |
| `graph status\|build\|refresh` | Grafo de codebase. `status` reporta frescor: o rebuild do hook é assíncrono |
| `graph affected\|explain <sym>` | Blast radius e vizinhança saneados. Sem grafo, caia para grep — nunca é erro |
| `verify <f> [task] [--json]` | Build+testes+validadores+e2e, antes do juiz LLM |
| `e2e up\|status\|down <f>` | Stack de verificação (docker compose) |
| `doctor --worktrees [--prune]` | Reconcilia git × disco × features; só `--prune` remove algo |
| `report-check <f> [task] [--json]` | Audita relatório de sub-agent vs. trabalho entregue |
| `telemetry [--feature] [--limit]` | Caminho de execução da sessão a partir de `events.jsonl` |
| `cost [f] [--by task\|phase]` | Custo (bytes/duração) a partir do mesmo log |

Prefixo de todo comando: `morph-spec`. Flags/exemplos: `.morph/framework/CLI.md`.

## Skills core (em `.claude/skills/`)

| Skill | Quando usar |
|-------|-------------|
| `morph-brainstorming` | Entender negócio, escanear stack, produzir proposal.md |
| `morph-stack-scan` | Detectar desvios de stack em projeto brownfield |
| `morph-uiux` | Ramo opcional uiux — design system, mockups, componentes, fluxos |
| `morph-plan` | Destilar use cases e produzir spec.md + mandate.md + tasks.json |
| `morph-implement` | Executar uma tarefa com auto-advance entre tasks |
| `morph-eval` | Aplicar rubricas e produzir score 0-10 |
| `morph-review` | Produzir review-report.md (Gate 3) |
| `morph-hotfix` | ADW cirúrgico de hotfix — scout → fix → gate humano → ship |
| `morph-standards` | Localizar standard sob demanda |

## Roteamento por tipo de trabalho

`workType` (`create --type <tipo>` ou classificado de `--request`) dimensiona o pipeline: `feature` completo (+ ramo uiux quando há superfície de UI), `bug` enxuto, `chore` fast-track (Gates 1/2 por política), `hotfix` scout→fix→gate humano→ship. Canônico: `MORPH.md` §2.1/§5.

Features independentes rodam em paralelo, uma por git worktree (`create --worktree`/`worktree setup`), bloco de portas próprio + handoff.md. Fechamento: `finish <f> --pr|--merge`; agregado: `fleet`. Canônico: `MORPH.md` §2.2.

## Personas (em `.claude/agents/`)

Despache tasks de domínio com `subagent_type: "morph-{id}"` — a persona é o **system prompt** do subagent registrado (gerado de `agents.json`, a fonte única). Tipo não registrado (stack não instalado): fallback `general-purpose` + campo `persona` colado no prompt, **registrando nas `notes` da task** (detalhe: `morph-apply` §3b).

<!-- morph-agents:start -->
_Lista derivada na instalação (`morph-spec setup-infra`). Se este bloco está vazio, rode `morph-spec setup-infra --reinstall`._
<!-- morph-agents:end -->

Drift entre `agents.json` e os `.md` gerados é detectado por `morph-spec doctor` — nunca edite `.claude/agents/morph-*.md` à mão.

## Regra de precedência de skills

Prefira `morph-*` a `superpowers:*` equivalentes (`brainstorming`→`morph-brainstorming`, `writing-plans`→`morph-plan`, `executing-plans`→`morph-apply`, `test-driven-development`→seguir `mandate.md`, TDD embutido, `using-git-worktrees`→`morph-spec worktree setup|provision`): `morph-*` aplica Gates e paths corretos de `.morph/`; `superpowers:*` é genérico, sem esse contexto.

*MORPH-SPEC v5 by Polymorphism Tech*