nexus-core-v3 3.0.0

package/tasks/ci-cd-configuration.md

@@ -0,0 +1,51 @@
+---
+id: ci-cd-configuration
+agent: devops
+title: Configurar workflows de CI/CD
+inputs: [story/objetivo de infra, stack do projeto]
+outputs: [workflows do GitHub Actions, confirmação de configuração]
+elicit: true
+modes: [interactive]
+---
+
+# Configurar workflows de CI/CD
+
+**Objetivo:** criar ou atualizar os workflows do GitHub Actions que rodam os gates do projeto (lint,
+typecheck, test, build) em CI, espelhando o pre-push local. Gestão de CI/CD é exclusiva do @devops.
+
+**Pré-condições:**
+- O objetivo rastreia a uma story/spec de infraestrutura. Sem isso, **elicito** o escopo — não invento
+  pipeline.
+- O repositório tem git e remoto GitHub. Se for greenfield, **pare** e recomende `*environment-bootstrap`.
+
+## Passos
+
+1. **Detecte o contexto do repositório** — remoto, branch base e a stack (gerenciador de pacotes,
+   scripts de `lint`/`test`/`build`). Nunca assuma repo fixo.
+2. **Mapeie os gates do projeto** que o CI deve espelhar: os mesmos comandos do `pre-push-quality-gate`
+   (lint, typecheck, test, build). O CI é a rede de segurança remota do gate local.
+3. **Gere/atualize o workflow** em `.github/workflows/` — triggers (push/PR para a branch base), matriz
+   de versões se aplicável, e os jobs dos gates. Reuse padrão existente antes de criar do zero.
+4. **Revele a proposta.** Mostre o YAML do workflow e os gatilhos ao usuário.
+5. **[ELICITAÇÃO] Peça o "ok" explícito** para gravar/atualizar o workflow. Configuração de pipeline
+   muda o comportamento da entrega — pede confirmação.
+6. **Grave o arquivo do workflow** localmente (`git add`/`git commit` com o id da story). A subida ao
+   remoto segue pelo fluxo normal (`*push`) — eu não empurro fora do gate.
+7. **Reporte.** Devolvo o caminho do workflow, os gates cobertos e o próximo passo (subir via `*push`
+   para o CI rodar).
+
+## Critério de pronto (DoD)
+
+- [ ] Stack e gates do projeto mapeados dinamicamente
+- [ ] Workflow cobre os mesmos gates do pre-push (lint, typecheck, test, build)
+- [ ] Confirmação humana obtida antes de gravar/atualizar o workflow
+- [ ] Workflow versionado por commit local (subida segue por `*push`)
+- [ ] Caminho do workflow e gates cobertos reportados
+
+## Falha / recuperação
+
+- **Escopo ausente** → elicito a story/objetivo de infra; não invento pipeline.
+- **Stack sem scripts de gate** (sem `lint`/`test`/`build` definidos) → sinalizo a lacuna e devolvo ao
+  @dev para definir os scripts antes de cravar o CI sobre eles.
+- **Greenfield sem remoto** → recomendo `*environment-bootstrap` antes de configurar Actions.
+- **Usuário não confirma** → não gravo o workflow.

package/tasks/collect-visual-evidence.md

@@ -0,0 +1,62 @@
+---
+id: collect-visual-evidence
+agent: qa
+title: Coletar evidência visual (EvidenceManifest)
+inputs: [story, rotas, viewports]
+outputs: [.nexus/evidence/<story>/evidence-manifest.json, capturas .png]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Coletar evidência visual (EvidenceManifest)
+
+**Objetivo:** produzir prova VISUAL verificável de que a UI da story realmente renderiza e se comporta
+como afirmado — capturas das rotas alteradas em cada viewport, com hash — reunidas num
+`evidence-manifest.json` (contrato `EvidenceManifest`, ADR-E5). O motor valida o manifesto (arquivo
+existe + hash bate); a Quinn julga o conteúdo. Sem app rodando, não há evidência: o veredito é
+**BLOCKED honesto**, nunca um PASS no escuro.
+
+**Pré-condições:**
+- A story tem superfície visual (rotas/telas alteradas). Story puramente de backend/CLI não usa esta
+  task — a evidência dela é teste verde + log, não screenshot.
+- Existe um comando para subir o app (dev server / preview) e as rotas a capturar estão definidas
+  (da story ou do frontend-spec). Sem rotas, não há o que capturar — pergunte, não invente.
+
+## Passos
+
+1. **Suba o app.** Inicie o servidor de preview e espere ficar pronto. **Se o app não sobe** (erro de
+   build, porta ocupada, crash no boot) → PARE: o veredito é **BLOCKED** com o log do erro. UI que não
+   inicia não tem evidência a coletar — e isso é um achado, não um contratempo.
+2. **Defina a matriz de captura.** Para cada rota alterada × cada viewport-alvo (ex.: `375×812` mobile,
+   `768×1024` tablet, `1440×900` desktop), uma captura. Estados que a AC menciona (vazio, carregando,
+   erro, hover, acordeão aberto) são capturas próprias — o "antes/depois" de uma interação são dois
+   arquivos, não um.
+3. **Capture com o browser real.** Navegue até a rota, ajuste o viewport, aguarde a rede/estado
+   estabilizar e tire o screenshot em disco sob `.nexus/evidence/<story>/`. Console com erro durante a
+   captura é achado — anexe junto (encadeia `*console-check`). Captura não é "abri e pareceu ok": é o
+   arquivo salvo.
+4. **Calcule o hash.** Para cada arquivo, compute o SHA-256 do conteúdo. O hash é o que torna a
+   evidência à prova de troca silenciosa: o motor recusa manifesto cujo hash não bate com o arquivo.
+5. **Escreva o manifesto.** Grave `.nexus/evidence/<story>/evidence-manifest.json` conforme o contrato
+   `EvidenceManifest`: `storyId` + `capturas[]`, cada uma com `rota`, `viewport`, `arquivo`,
+   `timestamp`, `sha256`. Manifesto sem nenhuma captura para uma story visual é FAIL, não vazio ok.
+6. **Devolva para o gate.** As capturas viram `evidenceRefs` no `<verdict>` da Quinn. É a Quinn que
+   julga se a evidência sustenta o "pronto" — esta task só a produz de forma honesta e verificável.
+
+## Critério de pronto (DoD)
+
+- [ ] App subiu (ou BLOCKED registrado com o log real do erro de boot)
+- [ ] Toda rota alterada × viewport-alvo capturada; estados de AC como capturas próprias
+- [ ] Cada arquivo existe em `.nexus/evidence/<story>/` e tem SHA-256 calculado
+- [ ] `evidence-manifest.json` válido contra o contrato `EvidenceManifest` (parseia, hashes batem)
+- [ ] Erros de console durante a captura anexados como achado, não descartados
+
+## Falha / recuperação
+
+- **App não sobe** → BLOCKED com o log; não há evidência a inventar. É a resposta correta do gate.
+- **Rota alterada sem captura** → manifesto incompleto = FAIL; a cobertura declarada tem de bater com a
+  real (declarado=real vale para evidência também).
+- **Hash não bate com o arquivo** → o motor recusa o manifesto (fail-closed); recapture, não edite o
+  JSON à mão.
+- **Sem viewports/rotas definidos** → pergunte à story/frontend-spec; capturar "o que der" não é
+  evidência, é ruído.

package/tasks/compose-molecule.md

@@ -0,0 +1,57 @@
+---
+id: compose-molecule
+agent: ux-design-expert
+title: Compor uma molécula a partir de átomos existentes
+inputs: [nome da molécula, átomos existentes, design tokens, story/spec]
+outputs: [molécula + testes + a11y, 'docs/design-system/molecules/{molécula}/']
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Compor uma molécula a partir de átomos existentes
+
+**Objetivo:** combinar átomos já construídos numa molécula de produção (ex.: campo de busca = input +
+botão + label) — testada, sobre tokens, com a11y preservada no conjunto — sem reinventar átomo.
+
+**Pré-condições:**
+- Os átomos necessários já existem em `docs/design-system/atoms/` e estão prontos (testados,
+  WCAG AA). Se um átomo faltar, **pare**: composição não inventa átomo — isso é `build-component`.
+- A molécula rastreia a uma story/spec ou a um padrão consolidado. Sem rastro, elicito — não invento
+  composição.
+
+## Passos
+
+1. **Identifico os átomos que compõem a molécula** a partir da story/spec e confirmo que cada um já
+   existe e está pronto. Falta de átomo → roteio para `build-component`, não improviso aqui.
+2. **Componho sobre os átomos**, sem fork: uso os átomos como estão, passando props; não duplico
+   nem reescrevo lógica que já vive no átomo. Reaproveitar é o ponto.
+3. **Defino a API da molécula** (props, estados do conjunto, eventos) rastreando a uma necessidade
+   real. Layout e espaçamento entre átomos vêm de tokens — zero valor hardcoded.
+4. **Garanto a acessibilidade do conjunto**, não só dos átomos: ordem de foco coerente, rótulos
+   associados (ex.: label ↔ input), agrupamento semântico, anúncio de estado/erro do grupo. WCAG AA
+   no conjunto é piso.
+5. **Escrevo os testes** que provam a composição: a molécula renderiza com os átomos certos, a
+   interação entre eles funciona (ex.: busca dispara), foco e estados do grupo se comportam.
+6. **Rodo `accessibility-wcag-checklist`** na molécula. Reprovou em AA → não entrego; corrijo antes.
+7. **Rodo lint + typecheck + os testes.** Vermelho não vira entregue.
+8. **Documento o uso** da molécula (átomos que a compõem, props, exemplos) para a pattern library e
+   salvo em `docs/design-system/molecules/{molécula}/`. Atualizo a File List da story.
+9. **Roteio.** Molécula pronta → @dev integra na app, @qa valida. Pronto pra subir → @devops — nunca
+   eu.
+
+## Critério de pronto (DoD)
+
+- [ ] Composta só de átomos prontos existentes (sem reinventar átomo, sem fork)
+- [ ] API definida e rastreada à story; layout/espaçamento via tokens (zero hardcode)
+- [ ] A11y do conjunto garantida (ordem de foco, rótulos, agrupamento) e validada pelo checklist
+- [ ] Testes da composição verdes; lint limpo; typecheck 0
+- [ ] Documentação de uso escrita; File List atualizada; nada subido por mim
+
+## Falha / recuperação
+
+- **Falta um átomo** → não improviso dentro da molécula; roteio para `build-component` e pauso a
+  composição até o átomo estar pronto.
+- **Reprova WCAG AA no conjunto** → HALT; corrijo a acessibilidade do grupo antes de entregar.
+- **Teste da composição não passa após 3 tentativas no mesmo ponto** → HALT, registro o bloqueio.
+- **A story não define a composição o suficiente** → paro e devolvo ao @sm/@po; não invento a
+  molécula.

package/tasks/consolidate-patterns.md

@@ -0,0 +1,54 @@
+---
+id: consolidate-patterns
+agent: ux-design-expert
+title: Reduzir redundância por clustering inteligente
+inputs: [audit-report, inventário de padrões de UI]
+outputs: [padrões consolidados, mapa antigo→novo, métricas de redução]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Reduzir redundância por clustering inteligente
+
+**Objetivo:** transformar o inventário caótico da auditoria num conjunto enxuto de padrões
+canônicos, agrupando variantes similares por clustering e provando a redução com número.
+
+**Pré-condições:**
+- Existe um audit-report da task `audit-codebase` com inventário e métricas. Sem ele, **pare** —
+  consolidar sem medir antes é consolidar no escuro.
+- O inventário traz a localização (arquivo:linha) de cada padrão, para o mapa antigo→novo rastrear ao
+  código real.
+
+## Passos
+
+1. **Carregue o inventário** do audit-report: todos os padrões com suas propriedades visuais (cor,
+   espaçamento, tipografia, raio, etc.).
+2. **Agrupe por similaridade (clustering).** Padrões com propriedades próximas caem no mesmo cluster
+   — ex.: 12 tons de azul que servem à mesma intenção viram um candidato a token único.
+3. **Eleja o padrão canônico de cada cluster:** o representante que melhor atende a necessidade,
+   respeitando contraste WCAG AA. O canônico nunca pode reprovar em acessibilidade.
+4. **Monte o mapa antigo→novo:** cada variante original aponta para o padrão canônico que a
+   substitui, com a localização (arquivo:linha) de origem. É o rastro da migração.
+5. **Calcule a redução:** nº de variantes antes → nº de canônicos depois, e o percentual (ex.: 47 → 3,
+   93,6%). Número antes de opinião.
+6. **Sinalize divergências que precisam de decisão humana** (dois canônicos legítimos, conflito de
+   marca) em vez de fundir à força — registro a escolha pendente.
+7. **Registre os padrões consolidados** e o mapa em `docs/stories/{epic}/audit/consolidation.md`, e
+   roteie: alimenta `extract-tokens` (tokens dos canônicos) e `generate-shock-report` (visual + ROI).
+
+## Critério de pronto (DoD)
+
+- [ ] Todos os padrões do inventário agrupados em clusters
+- [ ] Um padrão canônico por cluster, cada um aprovado em contraste WCAG AA
+- [ ] Mapa antigo→novo com localização (arquivo:linha) de cada variante
+- [ ] Métrica de redução calculada (antes → depois → %)
+- [ ] Divergências que exigem decisão humana sinalizadas, não fundidas à força
+- [ ] Consolidação registrada e roteada a `extract-tokens` / `generate-shock-report`
+
+## Falha / recuperação
+
+- **Não há audit-report** → volto para `audit-codebase`; não consolido sem o inventário medido.
+- **Um cluster não tem canônico que passe em a11y** → não rebaixo o critério; escalo a necessidade de
+  um novo padrão acessível em vez de eleger um que reprova em contraste.
+- **Conflito de marca/identidade entre canônicos** → registro como decisão pendente e busco validação
+  antes de fundir — não invento a regra de marca.

package/tasks/create-brownfield-prd.md

@@ -0,0 +1,54 @@
+---
+id: create-brownfield-prd
+agent: pm
+title: Criar o PRD para projeto existente (brownfield)
+inputs: [pedido de evolução, sistema existente/código rodando, docs de arquitetura (se houver)]
+outputs: [docs/prd/prd.md ancorado no que já roda, com impacto e compatibilidade mapeados]
+elicit: true
+modes: [interactive]
+---
+
+# Criar o PRD para projeto existente (brownfield)
+
+**Objetivo:** escrever um PRD para evoluir um sistema que **já roda** — ancorado no comportamento atual,
+com impacto e compatibilidade explícitos, sem quebrar o que os usuários já usam.
+
+**Pré-condições:**
+- O sistema existente é acessível (código, docs ou alguém que conheça). Se ninguém sabe como funciona
+  hoje, **pare** e delegue o levantamento ao @architect/@analyst antes de prometer mudança.
+- O pedido de evolução tem um "por quê" rastreável a dor/oportunidade. Sem isso, **pare** e elicite.
+
+## Passos
+
+1. **Ancore no estado atual.** Mapeie o que o sistema já faz, quais fluxos os usuários dependem e onde a
+   mudança encosta. Se faltar entendimento do legado, delegue o assessment ao @architect (não invente
+   como funciona).
+2. **Cave o "por quê" da evolução** até a dor/oportunidade real e a métrica que ela move.
+3. **Recorte o MVP da mudança** (MoSCoW/RICE) — o menor incremento que prova a hipótese sem regredir o
+   que já funciona.
+4. **[ELICITAÇÃO] Valide impacto e compatibilidade com o stakeholder.** Apresente: o que muda, o que
+   **não pode quebrar** (compatibilidade retroativa, migração de dados, usuários ativos) e o recorte.
+   Pare e espere o GO real — risco em brownfield é alto demais pra presumir aceite.
+5. **Escreva o PRD** a partir de `templates/prd-tmpl.md`, com seções extras de brownfield: estado atual,
+   delta proposto, riscos de regressão, estratégia de migração/rollback. Cada FR/NFR com critério de
+   aceite verificável e rastro ao "por quê".
+6. **Marque os quality gates** onde a regressão é mais provável; preveja a validação do @qa.
+7. **Salve em `docs/prd/prd.md`** e roteie: schema/migração → @data-engineer; arquitetura do delta →
+   @architect; quebra em epics → `create-epic`; subir no remoto → @devops.
+
+## Critério de pronto (DoD)
+
+- [ ] Estado atual mapeado e o delta proposto é explícito
+- [ ] Riscos de regressão e estratégia de migração/rollback documentados
+- [ ] Todo FR/NFR com critério de aceite verificável e métrica de sucesso
+- [ ] Impacto e compatibilidade **confirmados pelo stakeholder** (elicitação cumprida)
+- [ ] PRD salvo em `docs/prd/prd.md`; nada de `git push` (delegado ao @devops)
+
+## Falha / recuperação
+
+- **Não entendo o sistema atual** → delego o levantamento ao @architect/@analyst; não escrevo PRD em
+  cima de suposição do legado.
+- **Stakeholder não aceita o risco de regressão** → seguro o PRD, registro o trade-off e reformulo o
+  recorte para reduzir o impacto.
+- **A mudança exige decisão de schema/arquitetura** → delego ao @data-engineer/@architect; trago o
+  "o quê"/"por quê", não o "como".

package/tasks/create-competitor-analysis.md

@@ -0,0 +1,42 @@
+---
+id: create-competitor-analysis
+agent: analyst
+title: Mapear concorrentes e posicionamento
+inputs: [objetivo / mercado ou categoria a analisar]
+outputs: ['docs/research/competitor-analysis-{slug}.md (matriz de concorrentes + posicionamento + "portanto")']
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Mapear concorrentes e posicionamento
+
+**Objetivo:** mapear o cenário competitivo — quem são os players, como se posicionam, onde estão suas forças e brechas — com cada afirmação rastreável a uma fonte e fechando em oportunidades acionáveis.
+
+**Pré-condições:**
+- O mercado/categoria a analisar está definido, ligado a uma decisão (diferenciação? entrada? precificação?). Se vago, **pare** e elícito o foco.
+- Há acesso a fontes públicas dos concorrentes (sites, pricing, reviews, notícias). Sem fonte, a avaliação vira hipótese rotulada.
+
+## Passos
+
+1. **Defino o objetivo e o eixo de comparação.** Qual decisão isto destrava, e quais dimensões importam (preço, features, segmento, canal, posicionamento). Registro no topo.
+2. **DIVIRJO — levanto os players.** Identifico concorrentes diretos, indiretos e substitutos — mais amplo do que o óbvio. Crédito a fonte de cada um.
+3. **Coleto os dados por dimensão.** Para cada concorrente: proposta de valor, segmento-alvo, pricing, features-chave, forças e fraquezas — cada célula com sua fonte e data.
+4. **CONVIRJO numa matriz.** Monto a matriz comparativa (concorrentes × dimensões) e um mapa de posicionamento (ex.: 2 eixos relevantes). Descarto dado fraco ou não-verificável.
+5. **Identifico brechas e ameaças.** Onde ninguém atende bem? Onde estão os fossos defensáveis? Marco o que é evidência vs. minha leitura/hipótese.
+6. **Sintetizo em "portanto".** Lista numerada de oportunidades de diferenciação e riscos competitivos, cada uma com a fonte e a implicação para a decisão.
+7. **Salvo** em `docs/research/competitor-analysis-{slug}.md` com matriz, mapa de posicionamento e Fontes; roteio: estratégia → @pm, decisões técnicas/diferenciação → @architect.
+
+## Critério de pronto (DoD)
+
+- [ ] Objetivo e dimensões de comparação declarados
+- [ ] Concorrentes diretos, indiretos e substitutos levantados (divergência) antes da matriz
+- [ ] Matriz comparativa e mapa de posicionamento construídos
+- [ ] Cada célula rastreia a uma fonte datada OU está marcada como hipótese
+- [ ] Brechas/oportunidades em lista numerada com "portanto" acionável
+- [ ] Documento salvo com Fontes e roteado ao consumidor (@pm / @architect)
+
+## Falha / recuperação
+
+- **Concorrente sem informação pública suficiente** → preencho o que há, marco lacunas como "não verificável" e não preencho por suposição.
+- **Posicionamento ambíguo entre fontes** → registro a divergência em vez de cravar; explicito a incerteza no mapa.
+- **A categoria é ampla/fragmentada demais** → paro, reporto, e proponho recortar por segmento com o usuário antes de mapear.

package/tasks/create-deep-research-prompt.md

@@ -0,0 +1,62 @@
+---
+id: create-deep-research-prompt
+agent: architect
+title: Gerar prompt de pesquisa profunda sobre tecnologia/padrão
+inputs: [tópico de pesquisa, contexto do projeto]
+outputs: [prompt de pesquisa estruturado]
+elicit: true
+modes: [interactive]
+---
+
+# Gerar prompt de pesquisa profunda sobre tecnologia/padrão
+
+**Objetivo:** transformar uma dúvida arquitetural (qual tecnologia, qual padrão, qual trade-off) num
+prompt de pesquisa profunda bem delimitado — com perguntas, critérios de avaliação e restrições do
+projeto — para que a pesquisa volte com decisão, não com um passeio genérico pela internet.
+
+**Pré-condições:**
+- Existe um tópico que rastreia a uma decisão de arquitetura real do projeto (uma escolha de stack,
+  um padrão, uma comparação). Sem isso, **pare** e elicite — não pesquiso curiosidade, pesquiso
+  decisão.
+- Há contexto do projeto disponível (NFRs, restrições). Se faltar, elicito antes — pesquisa sem
+  restrição produz resposta que não cabe no projeto.
+
+## Passos
+
+1. **Delimite a decisão por trás do tópico.** Que escolha arquitetural essa pesquisa precisa
+   sustentar? "React vs Svelte" não é a pergunta; "qual framework de UI minimiza custo de
+   manutenção para um time de 3 com esta escala-alvo" é. **Elicito** essa precisão com o usuário.
+2. **Liste as restrições do projeto** que a pesquisa deve respeitar: NFRs (escala, latência,
+   disponibilidade), orçamento, stack atual, capacidade do time, prazo. A resposta tem que caber
+   nelas — tecnologia chata por padrão, empolgante só onde o problema exige.
+3. **Formule as perguntas de pesquisa**, da mais decisiva para a periférica. Cada pergunta deve
+   produzir um achado acionável: maturidade, custo de operação, curva de aprendizado, riscos de
+   escala, comunidade/suporte, fit com o stack atual.
+4. **Defina os critérios de avaliação** com que as opções serão comparadas — e o teste do 10× entre
+   eles: o que quebra com cada opção quando o sistema escalar. Sem critério explícito, a pesquisa
+   vira coleção de opiniões.
+5. **Monte o prompt estruturado**: contexto + restrições + perguntas + critérios + formato de saída
+   esperado (tabela comparativa, recomendação com rastro). Valido com o usuário antes de fechar —
+   esse é o ponto de elicitação sagrado.
+6. **Entregue o prompt ao executor de pesquisa** (@analyst, ou a ferramenta de pesquisa configurada
+   via `nexus run`). O achado volta como insumo rastreável para `create-doc` / `spec-assess-complexity`
+   — e cada decisão de arquitetura que ele sustentar passa a rastrear a esse achado (No Invention).
+
+## Critério de pronto (DoD)
+
+- [ ] A decisão arquitetural por trás do tópico está delimitada e validada com o usuário
+- [ ] As restrições do projeto (NFRs, orçamento, stack, time) estão explícitas no prompt
+- [ ] As perguntas estão ordenadas por poder de decisão e cada uma pede um achado acionável
+- [ ] Os critérios de avaliação e o teste do 10× entre opções estão definidos
+- [ ] O formato de saída esperado está especificado; o prompt foi validado antes de entregar
+
+## Falha / recuperação
+
+- **O tópico não rastreia a uma decisão real** → paro e elicito a decisão; não gero prompt para
+  pesquisa sem dono nem propósito.
+- **Faltam restrições do projeto** → elicito antes de montar o prompt; uma pesquisa sem restrição
+  devolve uma recomendação que não cabe e gera retrabalho.
+- **O ponto de elicitação seria pulado em modo não-interativo** → recuso: `elicit: true` exige a
+  validação real do usuário sobre as perguntas e critérios.
+- **A pesquisa volta sem sustentar a decisão** → reformulo as perguntas e re-disparo; não fecho uma
+  decisão de arquitetura sobre um achado que não responde o que importava.

package/tasks/create-doc.md

@@ -0,0 +1,62 @@
+---
+id: create-doc
+agent: architect
+title: Conceber a arquitetura a partir de um template
+inputs: [template, contexto do projeto]
+outputs: [documento de arquitetura preenchido]
+elicit: true
+modes: [interactive]
+---
+
+# Conceber a arquitetura a partir de um template
+
+**Objetivo:** produzir um documento de arquitetura completo (fullstack / backend / frontend /
+brownfield) preenchendo um template seção a seção — registrando a *decisão* e o *porquê* de cada
+trade-off, não só o diagrama.
+
+**Pré-condições:**
+- Existe um template alvo em `templates/`. Se o template não for indicado, **pare** e pergunte qual —
+  não escolho a forma do documento por conta própria.
+- Existe contexto rastreável: PRD, NFRs, restrições. Sem isso, elicito antes de desenhar — arquitetura
+  sem requisito é ficção.
+
+## Passos
+
+1. **Carregue o template** e leia sua estrutura inteira. Identifico quais seções exigem elicitação
+   (`elicit: true`) — esses pontos NÃO podem ser pulados "por eficiência".
+2. **Levante os NFRs explicitamente** antes de qualquer seção de design: escala-alvo, latência,
+   disponibilidade, segurança, orçamento, prazo. NFR não declarado é a causa nº 1 de arquitetura que
+   parece certa e quebra em produção.
+3. **Preencha seção a seção, em ordem.** Para cada seção do template:
+   a. redijo o conteúdo rastreando cada afirmação a um FR/NFR/CON ou achado de pesquisa (No Invention);
+   b. nas fronteiras estruturais, rodo o teste do 10× e registro o failure mode, não só o caminho feliz;
+   c. **num ponto de elicitação, paro e apresento as opções ao usuário** no formato do template,
+      validando a resposta antes de seguir. Esse ponto é sagrado.
+4. **Documente o porquê de cada trade-off**, não só a escolha. Tecnologia chata por padrão,
+   empolgante por exceção — e cada exceção justificada no doc. Decisão sem rastro vira mito de equipe
+   em seis meses.
+5. **Roteie cada camada ao dono.** Schema/DDL detalhado → @data-engineer (eu defino a tecnologia e o
+   contrato; ela implementa). Fluxos/UI → @ux-design-expert. Eu costuro o sistema; não invado a lane
+   do especialista.
+6. **Revise contra o checklist** (`execute-checklist` com o checklist de arquitetura) e salve o
+   documento no destino do projeto (`docs/architecture/`). Implementado depois → @qa; subida → @devops.
+
+## Critério de pronto (DoD)
+
+- [ ] Todas as seções do template preenchidas, nenhum ponto de elicitação pulado
+- [ ] NFRs declarados explicitamente e refletidos nas decisões de design
+- [ ] Cada afirmação rastreia a um FR/NFR/CON ou achado de pesquisa (No Invention)
+- [ ] Cada fronteira estrutural tem failure mode ao escalar declarado (teste do 10×)
+- [ ] Cada trade-off tem o porquê registrado; camadas de especialista roteadas ao dono
+- [ ] Documento validado contra o checklist e salvo em `docs/architecture/`
+
+## Falha / recuperação
+
+- **Falta contexto para uma seção (NFR ausente, requisito ambíguo)** → paro nessa seção, elicito o
+  que falta e só então sigo. Não preencho com suposição.
+- **Um ponto de elicitação seria pulado por modo não-interativo** → recuso: `elicit: true` exige
+  interação real; sem ela, o documento não fica pronto.
+- **Uma seção exige decisão de schema/UI fora da minha lane** → defino o contrato e delego a
+  implementação da camada ao dono (@data-engineer / @ux-design-expert).
+- **O checklist reprova o documento** → corrijo as seções apontadas antes de declarar pronto; não
+  salvo como final uma arquitetura que falhou no gate.

package/tasks/create-epic.md

@@ -0,0 +1,49 @@
+---
+id: create-epic
+agent: pm
+title: Estruturar o epic a partir do PRD
+inputs: [docs/prd/prd.md]
+outputs: ['docs/epics/{epicNum}.epic.md com fronteiras, dependências e quality gates']
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Estruturar o epic a partir do PRD
+
+**Objetivo:** quebrar o PRD em epics com fronteiras limpas, dependências mapeadas e quality gates
+previstos — e **delegar a criação das stories ao @sm** (Gate 1). Eu desenho o epic; eu não crio a story.
+
+**Pré-condições:**
+- O PRD existe em `docs/prd/` com FRs/NFRs e critérios de aceite. Se o PRD não está pronto, **pare** e
+  rode `create-prd` / `create-brownfield-prd` antes.
+- Os FRs têm rastro ao "por quê". Se há feature órfã no PRD, **pare** e resolva na origem (No invention).
+
+## Passos
+
+1. **Agrupe os FRs em epics de fronteira limpa.** Cada epic entrega um incremento de valor coeso e
+   independente o quanto der. Nada de epic "guarda-chuva" sem foco.
+2. **Mapeie dependências entre epics** (o que precisa do quê primeiro) e ordene por valor x dependência —
+   o que destrava mais cedo, vai primeiro.
+3. **Escreva cada epic** a partir de `templates/epic-tmpl.md`: objetivo, FRs cobertos (com rastro ao
+   PRD), critério de aceite do epic, dependências e **quality gates previstos** (onde o @qa entra).
+4. **Preveja os agentes especializados de cada frente** (implementação → @dev, dados → @data-engineer,
+   UX → @ux-design-expert, subida → @devops). Qualidade entra no plano, não depois.
+5. **Salve em `docs/epics/{epicNum}.epic.md`** e registre a ordem de execução sugerida.
+6. **Delegue a criação das stories ao @sm (Gate 1).** Eu estruturo o epic e entrego ao River para o
+   `*draft`. **Não furo essa fronteira**, mesmo que "seja rápido". Validação das stories → @po.
+
+## Critério de pronto (DoD)
+
+- [ ] Cada epic tem objetivo, FRs cobertos (com rastro ao PRD) e critério de aceite
+- [ ] Dependências entre epics mapeadas e ordem de execução definida
+- [ ] Quality gates e agentes especializados previstos por epic
+- [ ] Epics salvos em `docs/epics/`; **stories delegadas ao @sm** (não criadas por mim)
+- [ ] Nenhum FR órfão ou inventado — tudo rastreia ao PRD
+
+## Falha / recuperação
+
+- **Um FR não cabe em nenhum epic limpo** → reviso o agrupamento; não crio epic guarda-chuva pra
+  esconder o problema.
+- **Dependências formam ciclo** → reordeno ou recorto o escopo do epic até quebrar o ciclo.
+- **PRD está ambíguo/incompleto** → volto ao `create-prd`; não invento o requisito que falta.
+- **Pressão para eu mesma criar a story** → recuso e delego ao @sm; a fronteira do Gate 1 não negocia.

package/tasks/create-front-end-spec.md

@@ -0,0 +1,56 @@
+---
+id: create-front-end-spec
+agent: ux-design-expert
+title: Escrever a especificação de frontend detalhada
+inputs: [personas, wireframes, story/spec, design tokens disponíveis]
+outputs: [front-end-spec.md, mapeamento componente→AC]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Escrever a especificação de frontend detalhada
+
+**Objetivo:** consolidar pesquisa, wireframes e tokens numa spec de frontend precisa e rastreável,
+que diga ao @dev exatamente o que construir — comportamento, estados, a11y e tokens — sem ambiguidade
+e sem escopo inventado.
+
+**Pré-condições:**
+- Existem wireframes (`ux-create-wireframe`) e, idealmente, pesquisa de usuário. Sem wireframe,
+  **pare** — a spec não nasce de nada.
+- A story/spec define os ACs no escopo. Toda seção da front-end spec vai rastrear a um AC/FR/NFR.
+
+## Passos
+
+1. **Liste os componentes e telas** da spec a partir dos wireframes, classificando por nível Atomic
+   Design (átomo → molécula → organismo → template → página). Reuso vem antes de criação.
+2. **Para cada componente, especifique:** anatomia, variantes, estados (default, hover, foco,
+   desabilitado, carregando, erro), comportamento de interação e responsividade.
+3. **Amarre os design tokens:** cor, espaçamento, tipografia e raio referenciam tokens nomeados —
+   **zero valor hardcoded** na spec. Token ausente vira pendência para `extract-tokens`.
+4. **Especifique a acessibilidade por componente:** papel/semântica ARIA quando aplicável, ordem de
+   foco, contraste AA, alvo de toque, alternativa textual, comportamento com teclado e leitor de
+   tela. A11y é seção obrigatória, não apêndice.
+5. **Defina os critérios de UX testáveis** (ex.: "foco visível em todo controle", "estado de erro
+   anuncia mensagem ao leitor de tela") para o @qa conseguir verificar.
+6. **Mapeie cada seção da spec a um AC/FR/NFR** da story. Seção órfã sai — é invenção.
+7. **Registre a spec** em `docs/stories/{epic}/front-end-spec.md` e roteie: vai para o @dev
+   implementar e alimenta `generate-ai-frontend-prompt` / `build-component`.
+
+## Critério de pronto (DoD)
+
+- [ ] Componentes classificados por nível Atomic Design, reuso priorizado
+- [ ] Cada componente com anatomia, variantes, estados e comportamento
+- [ ] Tokens nomeados em todo valor visual — nenhum hardcoded
+- [ ] Seção de acessibilidade WCAG AA por componente
+- [ ] Critérios de UX testáveis definidos para o @qa
+- [ ] Cada seção rastreia a um AC/FR/NFR; spec registrada em `docs/stories/`
+
+## Falha / recuperação
+
+- **Faltam wireframes** → volto para `ux-create-wireframe` antes de especificar.
+- **Não há design tokens** → escrevo a spec referenciando tokens-alvo e registro a pendência de
+  `extract-tokens`/`setup-design-system`; não hardcodo para "destravar".
+- **Decisão de stack/arquitetura de frontend surge** → delego à Aria (@architect); a spec descreve
+  o comportamento de UX, não escolhe a tecnologia.
+- **A story não cobre um comportamento que a spec exigiria** → paro, registro a lacuna e devolvo ao
+  @sm/@po.

package/tasks/create-migration-plan.md

@@ -0,0 +1,57 @@
+---
+id: create-migration-plan
+agent: data-engineer
+title: Planejar a migração com estratégia de rollback
+inputs: [schema, políticas RLS, índices, estado atual do banco]
+outputs: [plano de migração, scripts up/down, docs/data/migration-plan.md]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Planejar a migração com estratégia de rollback
+
+**Objetivo:** transformar as mudanças de schema/RLS/índices em um plano de migração seguro e
+reversível — nada chega ao banco sem snapshot antes e script de rollback pronto.
+
+**Pré-condições:**
+- O DDL alvo existe (schema, RLS e/ou índices já desenhados). Sem alvo, não há plano.
+- O estado atual do banco é conhecido (ou snapshotável). Se não dá para inspecionar o estado vigente,
+  **pare** — migração sem baseline é salto no escuro.
+
+## Passos
+
+1. **Faça o diff** entre o estado atual e o DDL alvo: o que cria, altera, remove. Cada mudança no
+   plano rastreia a uma story/spec — sem invenção de coluna ou tabela.
+2. **Ordene as operações por dependência:** tipos/enums e tabelas referenciadas antes; FKs, índices e
+   políticas RLS depois. Essa ordem é o que `db-verify-order` vai validar.
+3. **Escreva o script `up` idempotente** (`IF NOT EXISTS`/`IF EXISTS`, `ADD COLUMN IF NOT EXISTS`):
+   rodar duas vezes tem que ser seguro. Migration que só roda uma vez vai trair num replay.
+4. **Escreva o script `down` (rollback) correspondente** para cada operação do `up`. Se eu não sei
+   como desfazer uma mudança, eu não a coloco no plano — reversibilidade é pré-condição.
+5. **Classifique operações destrutivas** (drop de coluna/tabela, mudança de tipo com perda): exigem
+   snapshot obrigatório e, idealmente, migração em duas fases (expand/contract) para não derrubar a
+   aplicação em execução.
+6. **Defina a sequência de execução segura:** `db-snapshot` (baseline) → `db-dry-run` →
+   `db-verify-order` → revisão de qualidade. CRÍTICO bloqueia a aplicação; ALTO exige mitigação ou
+   rollback testado.
+7. **Documente em `docs/data/migration-plan.md`:** diff, ordem, scripts up/down, operações
+   destrutivas e a sequência de execução. A aplicação em si é a task `db-apply-migration` — aqui só
+   planejo.
+
+## Critério de pronto (DoD)
+
+- [ ] Diff completo entre estado atual e alvo, cada mudança rastreável
+- [ ] Operações ordenadas por dependência
+- [ ] Script `up` idempotente
+- [ ] Script `down` (rollback) cobrindo cada operação do `up`
+- [ ] Operações destrutivas marcadas com snapshot obrigatório e estratégia de fase
+- [ ] Sequência segura (snapshot → dry-run → verify-order → revisão) definida
+- [ ] `docs/data/migration-plan.md` escrito
+
+## Falha / recuperação
+
+- **Uma operação não tem rollback claro** → não entra no plano até eu saber desfazê-la; reformulo a
+  abordagem (ex.: expand/contract) para torná-la reversível.
+- **Estado atual do banco inacessível** → paro; não planejo migração sem baseline confiável.
+- **A migração exige push/deploy** → o plano é meu, mas a subida é do @devops; eu delego a aplicação
+  em ambiente remoto ao @devops, sem nunca dar `git push` ou tocar em pipeline.