nexus-core-v3 3.0.0

package/tasks/dev-develop-story.md

@@ -0,0 +1,61 @@
+---
+id: dev-develop-story
+agent: dev
+title: Implementar uma story
+inputs: [story]
+outputs: [código, testes, File List atualizada, status InProgress→Ready for Review]
+elicit: false
+modes: [interactive, yolo, preflight]
+---
+
+# Implementar uma story
+
+**Objetivo:** transformar uma story aprovada em código testado e rastreável, atualizando só as
+seções do Dev Record — sem inventar escopo e sem tocar no que não é meu.
+
+**Pré-condições:**
+- A story existe e NÃO está em `Draft` (foi validada pelo @po). Se estiver em Draft, **pare** e
+  reporte: implementar uma story não-validada é retrabalho garantido.
+- A story tem critérios de aceite (ACs) e a seção de Testing. Se faltar, **pare** e devolva ao @sm.
+
+## Passos
+
+1. **Leia a story COMPLETA antes de tocar em código** — ACs, notas de dev, seção de Testing. A story
+   tem tudo que você precisa; não carregue PRD/arquitetura a menos que a story mande explicitamente.
+2. **Procure padrão existente antes de criar** (REUSE > ADAPT > CREATE). Se já existe um utilitário/
+   componente que resolve, use; se quase resolve, adapte sem quebrar quem consome; só crie do zero
+   quando nada serve — e registre o porquê.
+3. **Implemente um AC por vez.** Para cada critério de aceite:
+   a. escreva o código mínimo que satisfaz o AC, seguindo os padrões do projeto;
+   b. escreva o teste que prova o AC (não marque o AC sem teste verde);
+   c. rode `lint` + `typecheck` + os testes da área;
+   d. **checkpoint de autocrítica** (a cada ~30 linhas): isto quebra algum consumidor? cobre o caso
+      de erro? é o caminho feliz só?
+4. **Atualize a File List** da story a cada arquivo criado/modificado. É o rastro do que você mexeu.
+5. **Rode a verificação completa** antes de declarar pronto: lint limpo, typecheck 0, toda a suíte
+   verde. Vermelho não vira "Ready for Review".
+6. **Revisão de qualidade pré-commit** (`nexus run` review ou ferramenta configurada): rode na
+   mudança não-commitada. CRITICAL → corrijo agora (máx. 2 iterações). HIGH → corrijo se der na 2ª
+   iteração, senão registro como dívida. MEDIUM/LOW → registro, não bloqueio.
+7. **Commit local** (`git add`/`git commit`, conventional commit com o id da story). **Nunca** `git
+   push` — isso é do @devops; eu deixo pronto e delego a subida.
+8. **Marque a story** `Ready for Review` e preencha Completion Notes + Change Log. Roteio para o @qa.
+
+## Critério de pronto (DoD)
+
+- [ ] Todos os ACs implementados, cada um com teste verde
+- [ ] lint limpo, typecheck 0, suíte completa verde
+- [ ] File List, Completion Notes e Change Log atualizados
+- [ ] Revisão pré-commit sem CRITICAL aberto
+- [ ] Commit local feito; nada de `git push` (delegado ao @devops)
+- [ ] Só toquei nas seções do Dev Record da story — não em ACs, escopo ou título
+
+## Falha / recuperação
+
+- **Teste não passa após 3 tentativas no mesmo ponto** → HALT, registro no Debug Log e reporto o
+  bloqueio em vez de empurrar com gambiarra.
+- **CRITICAL da revisão persiste após 2 iterações** → HALT, não marco Ready for Review; reporto.
+- **Descobri que a story está incompleta/ambígua no meio** → paro, registro a lacuna e devolvo ao
+  @sm/@po. Não invento o requisito que falta.
+- **A mudança exige tocar fora do meu escopo** (schema, infra, UI) → delego ao dono (@data-engineer,
+  @devops, @ux-design-expert) em vez de invadir a lane.

package/tasks/document-project.md

@@ -0,0 +1,59 @@
+---
+id: document-project
+agent: architect
+title: Gerar a documentação de arquitetura do projeto
+inputs: [codebase]
+outputs: [documentação de arquitetura, mapa de dependências, riscos estruturais]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Gerar a documentação de arquitetura do projeto
+
+**Objetivo:** produzir uma documentação de arquitetura fiel ao que o codebase **realmente é** — não
+ao que deveria ser — para que qualquer agente ou humano entenda o sistema, suas fronteiras e onde ele
+racha, sem ter que reler o repositório inteiro.
+
+**Pré-condições:**
+- O repositório está acessível e legível. Se estiver vazio ou inacessível, **pare** e reporte.
+- Há um destino de documentação (`docs/architecture/`). Se já existir doc, eu atualizo o que mudou em
+  vez de reescrever do zero.
+
+## Passos
+
+1. **Reconheça o terreno.** Identifico stack, linguagens, gerenciador de pacotes, entrypoints e a
+   convenção de organização (por camada / feature / domínio). Documento o que existe, sem julgar.
+2. **Mapeie as camadas e fronteiras.** Frontend, backend, dados, infra: o que cada camada faz, onde
+   ela termina e onde fala com a próxima. Cada fronteira de serviço e contrato de API vira uma seção.
+3. **Levante o mapa de dependências** (`Grep`/`Glob`, code-intel se disponível). Módulos internos,
+   dependências externas e — crucial — qualquer ciclo de dependência. Anoto acoplamentos que viram
+   gargalo.
+4. **Documente o fluxo de dados** das entradas às saídas: como um request atravessa as camadas, onde
+   os dados persistem, onde há cache/fila. Para a camada de dados, registro a tecnologia e o contrato;
+   o schema detalhado é território da @data-engineer.
+5. **Anote os riscos estruturais (teste do 10×).** Para cada fronteira crítica, o que quebra ao
+   escalar: N+1, hot path, ponto único de falha, acoplamento perigoso. Registro o failure mode
+   observado — documentação honesta inclui as rachaduras.
+6. **Escreva no template e salve.** Preencho a documentação a partir do template de arquitetura, salvo
+   em `docs/architecture/` e entrego como base para `analyze-project-structure`,
+   `architect-analyze-impact` ou um assessment brownfield. Subida do doc → @devops.
+
+## Critério de pronto (DoD)
+
+- [ ] Stack, entrypoints e convenção de organização documentados como realmente são
+- [ ] Cada camada e fronteira de serviço descrita, com seus contratos de API
+- [ ] Mapa de dependências completo, com ciclos identificados
+- [ ] Fluxo de dados ponta a ponta documentado
+- [ ] Riscos estruturais anotados com failure mode ao escalar (teste do 10×)
+- [ ] Documentação salva em `docs/architecture/`, sem invenção (reflete o codebase, não o desejo)
+
+## Falha / recuperação
+
+- **O codebase é grande demais para documentar de uma vez** → priorizo as camadas e fronteiras
+  críticas primeiro, marco o resto como pendente explícito; não invento o que não inspecionei.
+- **Não consigo determinar o comportamento real de um módulo** → registro a incerteza como tal, em
+  vez de afirmar uma arquitetura que estou supondo (No Invention vale para documentação também).
+- **A camada de dados exige detalhamento de schema/DDL** → documento a tecnologia e o contrato e
+  delego o aprofundamento de schema à @data-engineer.
+- **A documentação precisa ser commitada e subida** → faço o registro local; a subida ao remoto é
+  exclusiva do @devops.

package/tasks/execute-checklist.md

@@ -0,0 +1,57 @@
+---
+id: execute-checklist
+agent: architect
+title: Rodar um checklist de arquitetura
+inputs: [checklist, artefato a validar]
+outputs: [veredito por item, lista de correções, decisão GO/NO-GO]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Rodar um checklist de arquitetura
+
+**Objetivo:** validar um artefato de arquitetura (documento, plano, design) contra um checklist item
+a item, emitindo um veredito objetivo por item e uma decisão final — para que "feito" e "feito
+direito" não sejam a mesma palavra na base da fé.
+
+**Pré-condições:**
+- Existe um checklist alvo em `checklists/` e um artefato a validar. Se faltar qualquer um, **pare**
+  e reporte — não há gate sem critério e sem objeto.
+- O artefato está num estado avaliável (não um rascunho pela metade). Se estiver, devolvo para
+  completar antes.
+
+## Passos
+
+1. **Carregue o checklist completo** e o artefato a validar. Leio todos os itens antes de começar
+   para entender o que cada um exige — um checklist mal lido aprova o que deveria barrar.
+2. **Avalie item a item, em ordem.** Para cada item, confronto o artefato com o critério e emito um
+   veredito: **PASS** (atende), **FAIL** (não atende) ou **PARTIAL** (atende em parte). Registro a
+   evidência concreta — qual seção/decisão sustenta o veredito. Sem evidência, não é PASS.
+3. **No modo interativo, pare em pontos de confirmação** quando o item exigir julgamento do usuário;
+   no modo yolo, avalio autonomamente e marco os itens que precisariam de confirmação humana.
+4. **Para cada FAIL/PARTIAL, especifique a correção.** O que exatamente falta e onde — não "melhorar
+   a seção X", mas a lacuna concreta e acionável. Correção vaga não conserta nada.
+5. **Compute a decisão final.** GO (todos os itens críticos PASS) ou NO-GO (há FAIL crítico) com a
+   lista de correções obrigatórias. A severidade de cada item vem do próprio checklist.
+6. **Roteie o resultado.** GO → o artefato segue (implementação → @dev, schema → @data-engineer,
+   subida → @devops). NO-GO → devolvo ao autor do artefato com a lista de correções; não passo
+   adiante o que não passou.
+
+## Critério de pronto (DoD)
+
+- [ ] Todos os itens do checklist avaliados, cada um com veredito (PASS/FAIL/PARTIAL) e evidência
+- [ ] Cada FAIL/PARTIAL tem a correção concreta e acionável especificada
+- [ ] Pontos de confirmação interativa respeitados (não pulados "por eficiência")
+- [ ] Decisão final GO/NO-GO computada pela severidade dos itens do checklist
+- [ ] Resultado roteado: GO segue ao próximo dono; NO-GO volta ao autor com correções
+
+## Falha / recuperação
+
+- **Um item do checklist é ambíguo demais para avaliar** → registro como inconclusivo, não como PASS;
+  escalo a interpretação em vez de inventar o critério.
+- **O artefato está incompleto demais para validar** → paro o gate e devolvo para completar; não
+  avalio um rascunho pela metade como se fosse final.
+- **Há FAIL crítico** → emito NO-GO e devolvo; não há override informal de um item crítico — quem
+  decide waiver é a autoridade do processo, não eu sozinha no meio da validação.
+- **O checklist alvo não existe ou está corrompido** → reporto e não improviso critérios; uma
+  validação sem checklist válido é teatro, não gate.

package/tasks/execute-epic-plan.md

@@ -0,0 +1,52 @@
+---
+id: execute-epic-plan
+agent: pm
+title: Executar o epic em waves paralelas
+inputs: ['docs/epics/{epicNum}.epic.md', stories criadas pelo @sm]
+outputs: [árvore de execução por waves, stories implementadas e roteadas ao gate]
+elicit: false
+modes: [yolo]
+---
+
+# Executar o epic em waves paralelas
+
+**Objetivo:** orquestrar a execução de um epic estruturado em ondas paralelas — disparando o motor
+(`nexus run`), respeitando dependências e budget, e roteando cada entrega ao quality gate.
+
+**Pré-condições:**
+- O epic existe em `docs/epics/` com fronteiras, dependências e quality gates (saída de `create-epic`).
+  Se o epic não está estruturado, **pare** e rode `create-epic` antes.
+- As stories do epic foram criadas pelo @sm e validadas pelo @po. Story em `Draft` não entra em
+  execução — eu não crio nem valido story (Gate 1); se faltam, delego ao @sm/@po.
+
+## Passos
+
+1. **Leia o epic completo** e monte o grafo de dependências entre as stories. Identifique o que é
+   paralelizável (baixo acoplamento) e o que precisa ser sequenciado.
+2. **Agrupe as stories em waves.** Cada wave: um conjunto de stories independentes que correm em
+   paralelo. Stories acopladas vão em waves seguintes, respeitando as deps.
+3. **Dispare o motor por wave** (`nexus run "{objetivo da wave}"`): o coordenador decompõe e o
+   orquestrador spawna os sub-agentes (cada story → @dev/@data-engineer/@ux conforme a frente).
+4. **Respeite os freios.** `maxFanout`, `maxDepth`, `maxTotalRuns` e budget têm teto. Se uma wave estoura
+   a decomposição, **recuso a wave inteira** e reformulo em frentes maiores/menos acopladas — sem
+   sub-agentes órfãos.
+5. **Costure as entregas da wave.** Recolha o resultado de cada story, verifique contra o critério de
+   aceite do epic, e só então libere a próxima wave (as que dependiam dela).
+6. **Roteie cada entrega ao gate.** Implementado → @qa (quality gate previsto no epic). Aprovado e pronto
+   pra subir → **@devops** (`git push`/PR/release são exclusivos dele — eu delego, sempre).
+
+## Critério de pronto (DoD)
+
+- [ ] Stories agrupadas em waves respeitando o grafo de dependências
+- [ ] Cada wave disparada via `nexus run`, dentro dos freios (sem órfãos, sem estouro de budget)
+- [ ] Entregas costuradas e verificadas contra o critério de aceite do epic
+- [ ] Cada entrega roteada ao @qa; subida delegada ao @devops
+- [ ] Eu não criei nem validei story (Gate 1 respeitado)
+
+## Falha / recuperação
+
+- **Uma story da wave falha** → o motor bloqueia os dependentes; reporto a frente travada e decido
+  re-delegar ou escalar, sem dar a wave por entregue.
+- **A wave estoura os freios/budget** → recuso e reformulo em frentes maiores/menos acopladas.
+- **Faltam stories validadas** → delego criação ao @sm e validação ao @po; não furo o Gate 1.
+- **Pediram que eu suba o código** → recuso e delego ao @devops; `git push`/PR/release não são meus.

package/tasks/execute-subtask.md

@@ -0,0 +1,51 @@
+---
+id: execute-subtask
+agent: dev
+title: Executar uma subtask do implementation.yaml
+inputs: [subtask-id, implementation.yaml]
+outputs: [código da subtask, File List atualizada, status da subtask: done]
+elicit: false
+modes: [yolo, interactive]
+---
+
+# Executar uma subtask do implementation.yaml
+
+**Objetivo:** implementar uma única subtask atômica do plano de execução pelo menor caminho,
+deixando-a pronta para verificação — sem tocar em nada além do que a subtask delimita.
+
+**Pré-condições:**
+- Existe um `implementation.yaml` (plano de execução) com a subtask referenciada pelo `subtask-id`.
+  Se o id não existe no plano, **pare** e reporte — não invento subtask.
+- As dependências (`depends_on`) da subtask já estão `done`. Se uma dependência está aberta, **pare**:
+  executar fora de ordem gera retrabalho.
+
+## Passos
+
+1. **Carrego a subtask** do `implementation.yaml`: seu objetivo, os arquivos que ela toca
+   (`files`), o critério de aceite local e a verificação configurada (`verify`). Leio só essa
+   subtask e o contexto que ela mesma referencia — não o plano inteiro.
+2. **Confirmo o escopo.** A subtask define quais arquivos posso tocar. Se o trabalho exige mexer
+   fora dessa lista, **paro** e reporto a fronteira estourada — não invado escopo de outra subtask.
+3. **Procuro padrão existente antes de criar** (REUSE > ADAPT > CREATE). Reuso utilitário/componente
+   que já resolve; adapto se quase resolve; só crio do zero quando nada serve.
+4. **Implemento pelo menor caminho** que satisfaz o critério local da subtask, seguindo os padrões
+   do projeto. Sem super-construção: resolvo o que a subtask pede, nada além.
+5. **Atualizo a File List** com cada arquivo criado/modificado/deletado nesta subtask.
+6. **Marco a subtask como `done`** no `implementation.yaml` (campo de status) e a roteio para a
+   verificação (`verify-subtask`). Não declaro pronto sem passar pela verificação.
+
+## Critério de pronto (DoD)
+
+- [ ] A subtask foi implementada dentro da sua lista de arquivos (`files`) — sem extravasar escopo
+- [ ] Reúso foi avaliado antes de criar estrutura nova
+- [ ] File List atualizada com tudo que foi tocado
+- [ ] Subtask marcada `done` no `implementation.yaml` e roteada para `verify-subtask`
+
+## Falha / recuperação
+
+- **A subtask exige tocar arquivos fora da sua lista** → HALT e reporto; o escopo da subtask precisa
+  ser corrigido no plano, não burlado.
+- **Uma dependência (`depends_on`) não está pronta** → paro e reporto a ordem quebrada.
+- **3 tentativas falhas no mesmo ponto** → HALT, registro o bloqueio e reporto; não empilho hipótese.
+- **A subtask está ambígua mesmo com o contexto do plano** → devolvo ao @architect (dono do
+  `implementation.yaml`) para esclarecer — não invento o requisito que falta.

package/tasks/extend-pattern.md

@@ -0,0 +1,63 @@
+---
+id: extend-pattern
+agent: ux-design-expert
+title: Adicionar variante a um componente existente
+inputs: [componente-base, variante-pedida, story]
+outputs: [variante implementada, testes, tokens, doc atualizada, File List atualizada]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Adicionar variante a um componente existente
+
+**Objetivo:** estender um componente atômico já existente com uma nova variante (tamanho, estado,
+intent) sem fork e sem quebrar quem já consome — variante nasce com a11y e tokens embutidos.
+
+**Pré-condições:**
+- O componente-base existe no design system e está em produção. Se não existe, **pare** — isto é um
+  `*build`, não um `*extend`.
+- A variante pedida rastreia a uma story/spec/FR-NFR ou achado de pesquisa. Sem rastro, **pare** e
+  sinalizo: não invento variante por gosto.
+- Os design tokens já cobrem (ou comportam) os valores da nova variante. Se faltar token, rodo
+  `*tokenize` antes — nada de hex solto.
+
+## Passos
+
+1. **Leio o componente-base inteiro** — props, variantes existentes, contrato público, testes. Mapeio
+   quem consome (busca de usos) para saber o que NÃO posso quebrar.
+2. **Confirmo a rastreabilidade da variante** à story/spec. Identifico o eixo da variante (ex.: novo
+   `intent="danger"`, novo `size="xs"`) e checo que não duplica uma variante já existente.
+3. **Estendo via prop/variante, nunca por fork.** Adiciono o valor ao tipo/enum da prop, sem mudar a
+   assinatura existente. Defaults e variantes atuais permanecem idênticos (mudança aditiva, não breaking).
+4. **Puxo todos os valores de design token.** Cor, espaçamento, tipografia e raio da nova variante vêm
+   dos tokens consolidados — zero hardcoded.
+5. **Escrevo o teste da variante** (render + estados) e **rodo a auditoria de a11y** (`*a11y-check`):
+   contraste, foco visível, navegação por teclado e semântica da nova variante.
+6. **Rodo a suíte completa** do componente para provar que nenhum consumidor quebrou (regressão das
+   variantes antigas + a nova verde).
+7. **Atualizo a documentação** da pattern library (`*document`) com a nova variante: exemplo, quando
+   usar, quando não usar.
+8. **Atualizo a File List** da story e faço **commit local** (conventional commit com o id da story).
+   **Nunca** `git push` — entrego pronto e delego a subida ao @devops.
+
+## Critério de pronto (DoD)
+
+- [ ] Variante rastreia a uma story/spec/FR-NFR — sem invenção
+- [ ] Mudança é aditiva: nenhuma variante/consumidor existente quebrou (regressão verde)
+- [ ] Zero valor hardcoded — tudo via design token
+- [ ] a11y WCAG AA aprovada para a nova variante (contraste, foco, teclado, semântica)
+- [ ] Teste da variante verde + suíte completa verde
+- [ ] Doc da pattern library atualizada (uso / não-uso)
+- [ ] File List atualizada e commit local feito (sem `git push`)
+
+## Falha / recuperação
+
+- **A variante quebraria um consumidor existente** → não é `*extend`, é refatoração de contrato. HALT,
+  escalo para @architect/@dev decidir a migração antes de prosseguir.
+- **a11y reprova na nova variante** → bloqueio a entrega, não marco pronto. Acessibilidade é piso, não
+  melhoria futura.
+- **Falta token para a variante** → paro, rodo `*tokenize` para criar o token, e só então estendo —
+  nunca hardcode como atalho.
+- **A variante não rastreia a nenhuma story/spec** → paro e sinalizo como hipótese; busco a evidência
+  antes de implementar.
+- **A mudança exige integrar na app além do design system** → delego ao @dev em vez de invadir a lane.

package/tasks/extend-squad.md

@@ -0,0 +1,60 @@
+---
+id: extend-squad
+agent: squad-creator
+title: Estender um squad existente sem quebrar o que já roda
+inputs: ['id do squad', 'necessidade nova (membro, task ou knowledge)']
+outputs: ['blueprint incremental <squad>{json}</squad> validado', 'squads/{id}/ estendido pelo motor']
+elicit: true
+modes: [interactive, yolo]
+---
+
+# Estender um squad existente sem quebrar o que já roda
+
+**Objetivo:** adicionar membros, tasks ou knowledge a um squad já materializado — mudança ADITIVA,
+validada pelo motor, que preserva os membros e contratos existentes.
+
+**Pré-condições:**
+- `squads/{id}/` existe e passa em `validate-squad`. Estender squad quebrado é empilhar dívida:
+  primeiro o FAIL é sanado, depois se estende.
+- A necessidade nova rastreia à missão do squad (ou a uma extensão explícita dela, com novo
+  `traceRef`). Sem rastro, não entra.
+
+## Passos
+
+1. **Leia o squad REAL** (`squad.yaml` + `agents/` + `tasks/` do squad) antes de propor qualquer
+   adição (Lei 2). Rode `validate-squad {id}` — FAIL bloqueia a extensão até ser sanado.
+2. **Elicite a necessidade** (ponto de elicitação em modo interativo): que gap apareceu? É lente
+   nova (membro), procedimento novo (task) ou craft novo (knowledge)? Em yolo, derive dos inputs e
+   declare as suposições.
+3. **Cheque REUSE antes de CREATE — duas vezes:** o gap é coberto (a) por um membro atual do squad?
+   (b) pelo time core? Se sim em qualquer um, a extensão é **delegação/referência**, não membro
+   novo. Só o gap real vira adição.
+4. **Verifique os limites da composição:** a adição mantém o time em chief+2..chief+7, lentes
+   distintas, chief único e `Orchestrator`, zero colisão de autoridade com o core. Estourou a
+   faixa → renegocie (fatiar a missão) em vez de inchar o time.
+5. **Preencha os templates** (`agent-dna-tmpl` / `squad-task-tmpl`) para as adições e **emita UM
+   bloco `<squad>{json}</squad>` incremental**: mesmo shape do `create-squad`, com o `manifest`
+   atualizado (version bump) e SOMENTE os agents/tasks/knowledge novos ou alterados. Membro
+   existente não é reescrito de carona (Lei 5 — diff mínimo).
+6. **Dispare o motor** (`nexus squad extend`): ele valida o blueprint incremental contra o squad
+   existente e materializa. Conflito (id duplicado, autoridade colidente) → o motor recusa; corrija
+   e re-emita.
+7. **Prove:** rode `validate-squad {id}` no squad estendido e reporte o resultado real.
+
+## Critério de pronto (DoD)
+
+- [ ] Squad de partida validado (PASS) antes da extensão
+- [ ] Necessidade rastreada à missão (ou extensão dela com `traceRef` novo)
+- [ ] REUSE checado contra o squad E contra o core antes de criar qualquer coisa
+- [ ] Blueprint incremental emitido num único bloco `<squad>{json}</squad>`, com version bump e sem reescrever membros intactos
+- [ ] Motor validou e materializou; conflito zero
+- [ ] `validate-squad` pós-extensão PASS, reportado
+
+## Falha / recuperação
+
+- **O squad de partida está FAIL** → HALT da extensão; reporte os issues e conserte-os primeiro
+  (issue aditivo → esta task; estrutural → `create-squad` re-emite).
+- **A adição colide com membro/task existente** → o motor recusa; renomeie ou funda com o
+  existente — nunca sobrescreva por cima.
+- **A necessidade não rastreia à missão** → não é extensão, é squad novo ou escopo do core:
+  devolva a decisão ao usuário com as duas opções.

package/tasks/extract-patterns.md

@@ -0,0 +1,64 @@
+---
+id: extract-patterns
+agent: analyst
+title: Extrair e documentar padrões de código do codebase
+inputs: [codebase, objetivo (story/spec/área-alvo)]
+outputs: [catálogo de padrões rastreáveis (docs/research/patterns.md)]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Extrair e documentar padrões de código do codebase
+
+**Objetivo:** mapear os padrões recorrentes de um codebase existente (convenções, estruturas,
+abordagens de erro, camadas) e documentá-los como catálogo acionável — cada padrão rastreando a
+ocorrências reais no código, nunca a um palpite.
+
+**Pré-condições:**
+- Há um codebase acessível e um objetivo que define o recorte: a área/story/spec para a qual os
+  padrões importam. Sem recorte, eu **paro e elícito** (`*elicit`) — varrer o repositório inteiro
+  sem pergunta é tempo queimado.
+- Existe um destino de saída em `docs/research/`. Se não existir, eu crio o diretório antes de
+  escrever.
+
+## Passos
+
+1. **Aperto o recorte até doer.** Qual decisão estes padrões precisam destravar? (ex.: o @dev vai
+   implementar uma story e precisa seguir a convenção da casa; o @architect vai decidir reuso). Se o
+   recorte não estiver claro, paro e elícito — não invento o escopo.
+2. **Divirjo: coleto largo.** Uso `Grep`/`Glob` para varrer a área-alvo e levanto candidatos a padrão
+   sem julgar ainda — nomenclatura, estrutura de pastas, tratamento de erro, camadas (controller/
+   service/repo), imports, formato de teste, validação, logging. Nesta fase só coleto e mapeio onde
+   cada candidato aparece.
+3. **Convirjo: filtro por evidência.** Um padrão só entra no catálogo se aparece em **2+ ocorrências
+   reais** no código. Ocorrência única é exceção, não padrão — registro como nota, não como regra.
+   Cada padrão sobrevivente carrega os arquivos:linha onde foi observado.
+4. **Classifico cada padrão** em: convenção forte (consistente em toda a área), convenção parcial
+   (coexiste com variações — sinalizo o conflito) ou anti-padrão recorrente (aparece, mas viola boa
+   prática — marco explicitamente). Não maquio inconsistência como consistência.
+5. **Sintetizo o "portanto".** Para cada padrão documento: nome, descrição, exemplo mínimo do próprio
+   código, ocorrências rastreáveis e a ação acionável — "ao implementar nesta área, siga X / evite Y".
+6. **Escrevo o catálogo** em `docs/research/patterns.md` com fonte ao lado de cada item. O que é
+   suposição minha (sem ocorrência verificável) vai marcado como hipótese, nunca como fato.
+7. **Faço o handoff limpo.** Roteio o catálogo a quem consome: implementação → @dev (para seguir a
+   convenção da casa), decisão de reuso/arquitetura → @architect. Eu municio; eles decidem.
+
+## Critério de pronto (DoD)
+
+- [ ] O recorte (área/story/spec) está explícito no topo do catálogo
+- [ ] Todo padrão documentado tem 2+ ocorrências reais rastreadas (arquivo:linha)
+- [ ] Cada padrão tem exemplo do próprio código + ação acionável ("portanto")
+- [ ] Conflitos e anti-padrões estão sinalizados, não maquiados
+- [ ] Suposições sem fonte estão marcadas como hipótese, não como fato
+- [ ] Catálogo salvo em `docs/research/patterns.md` e roteado ao consumidor (@dev/@architect)
+
+## Falha / recuperação
+
+- **O recorte não está claro / objetivo ausente** → paro e elícito (`*elicit`); não varro o repo
+  inteiro nem invento o escopo.
+- **Nenhum padrão atinge 2+ ocorrências** → reporto que a área não tem convenção estabelecida (achado
+  válido por si) em vez de promover ruído a regra.
+- **Padrões conflitam entre si** → documento ambos os lados com suas ocorrências e sinalizo o conflito
+  ao consumidor; não escolho o "certo" — isso é decisão do @architect.
+- **A extração exige rodar/mover código ou subir algo** → não é meu papel; delego ao @dev (mudança) ou
+  ao @devops (subida/MCP). Eu observo e documento, não administro.

package/tasks/extract-tokens.md

@@ -0,0 +1,59 @@
+---
+id: extract-tokens
+agent: ux-design-expert
+title: Extrair design tokens dos padrões consolidados
+inputs: [padrões consolidados, story/spec de design system]
+outputs: [design tokens (cor, espaçamento, tipografia, raio, sombra), docs/design-system/tokens/]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Extrair design tokens dos padrões consolidados
+
+**Objetivo:** transformar os padrões visuais consolidados num conjunto de design tokens nomeados e
+versionados — a fonte única de verdade para cor, espaçamento, tipografia, raio e sombra. Daqui pra
+frente, nada é hardcoded.
+
+**Pré-condições:**
+- A consolidação (`consolidate-patterns`) já reduziu a redundância e existe o conjunto de variantes
+  vencedoras. Sem isso, **pare**: tokenizar o caos só normaliza o caos.
+- Há uma story/spec pedindo o design system (ou a migração que o exige). Sem rastro, elicito — não
+  invento paleta nem escala.
+
+## Passos
+
+1. **Leio os padrões consolidados** e extraio os valores brutos recorrentes: cores usadas,
+   espaçamentos, tamanhos/pesos de fonte, raios de borda, sombras.
+2. **Agrupo cada dimensão numa escala semântica**, não numa lista de hex solto:
+   - **cor:** primária/secundária/neutra + estados (success/warning/danger/info), com nomes de
+     intenção (ex.: `color.action.primary`), não de aparência (`color.blue-500` só como referência).
+   - **espaçamento:** escala consistente (ex.: 4/8/12/16/24/32) com nomes (`space.xs…space.2xl`).
+   - **tipografia:** família, escala de tamanho, pesos e line-heights nomeados.
+   - **raio e sombra:** níveis nomeados (`radius.sm/md/lg`, `shadow.1/2/3`).
+3. **Valido contraste WCAG AA** em cada par texto/fundo dos tokens de cor — contraste reprovado não
+   vira token: ajusto o valor ou marco o par como proibido. Acessibilidade é piso, não enfeite.
+4. **Escrevo os tokens** em formato consumível (ex.: JSON/CSS custom properties) em
+   `docs/design-system/tokens/`, organizados por dimensão, com versão e referência aos padrões de
+   origem (rastro — cada token sabe de onde veio).
+5. **Registro divergências resolvidas:** quando dois valores quase iguais viraram um só token,
+   anoto o mapeamento (valor antigo → token) para a migração depois consumir.
+6. **Atualizo a File List** da story com os arquivos de token criados.
+7. **Roteio.** Tokens prontos alimentam `setup-design-system` e `build-component`. Decisão de stack
+   de tokens (ex.: ferramenta de build/transform) é da Aria (@architect) — eu trago a lente de UX e
+   delego. Subida é do @devops.
+
+## Critério de pronto (DoD)
+
+- [ ] Cada dimensão (cor, espaçamento, tipografia, raio, sombra) tem escala semântica nomeada
+- [ ] Todo par texto/fundo de cor passou em contraste WCAG AA (ou está marcado como proibido)
+- [ ] Tokens escritos em `docs/design-system/tokens/`, versionados e com rastro à origem
+- [ ] Mapeamento valor antigo → token registrado para a migração
+- [ ] Zero valor hardcoded sobrando como decisão final; File List atualizada
+
+## Falha / recuperação
+
+- **Padrões não consolidados** → HALT; volto à `consolidate-patterns`, não tokenizo redundância.
+- **Cor reprova contraste e não há ajuste óbvio** → não publico o token; sinalizo o conflito e busco
+  o valor acessível antes de fechar a paleta.
+- **A escala fica ambígua (muitos valores próximos sem critério)** → elicito a decisão de design em
+  vez de inventar a regra de arredondamento.

package/tasks/facilitate-brainstorming-session.md

@@ -0,0 +1,42 @@
+---
+id: facilitate-brainstorming-session
+agent: analyst
+title: Facilitar uma sessão de brainstorming
+inputs: [tópico]
+outputs: ['docs/research/brainstorm-{slug}.md (ideias divergidas, convergidas e priorizadas)']
+elicit: true
+modes: [interactive]
+---
+
+# Facilitar uma sessão de brainstorming
+
+**Objetivo:** conduzir uma ideação estruturada que primeiro abre o leque (divergir) e depois corta com critério (convergir), entregando um conjunto priorizado e acionável de ideias rastreáveis ao tópico.
+
+**Pré-condições:**
+- Existe um tópico/objetivo de ideação definido. Se for vago ("preciso de ideias"), **pare** e elícito (`*elicit`) o foco real — brainstorm sem alvo é ruído.
+- A decisão que esta sessão precisa destravar está clara. Se não, aperto o objetivo antes de gerar uma ideia sequer.
+
+## Passos
+
+1. **Enquadro o tópico com o usuário.** Confirmo a pergunta central e o que conta como "boa ideia" aqui (critério de sucesso). Registro isso no topo do documento. **(ponto de elicitação — exige a resposta real do usuário, não pode ser pulado)**
+2. **Escolho técnicas nomeadas** adequadas ao tópico (ex.: SCAMPER, What-If, First Principles, Crazy 8s, Mind Mapping, Reverse Brainstorming). Anuncio qual técnica estou aplicando — método sobre achismo.
+3. **DIVIRJO primeiro.** Gero amplitude deliberada de ideias — mais do que parece confortável. Nesta fase **não julgo**: só coleto e mapeio. Convido o usuário a contribuir a cada rodada de técnica.
+4. **Marco a transição.** Anuncio explicitamente "fechando o leque, começando a tesoura" — nunca convirjo antes de ter divergido de verdade.
+5. **CONVIRJO com critério.** Agrupo ideias por tema, removo duplicatas e filtro pelo critério de sucesso definido no passo 1. Cada ideia que sobrevive carrega o porquê.
+6. **Priorizo.** Classifico as ideias sobreviventes (ex.: impacto × esforço, ou "agora / próximo / depois"). Entrego como lista numerada para escolha.
+7. **Sintetizo em "portanto".** Para as ideias top, escrevo o próximo passo acionável e o dono sugerido (PRD → @pm, arquitetura → @architect, story → @sm).
+8. **Salvo o documento** em `docs/research/brainstorm-{slug}.md` com: tópico, técnicas usadas, ideias divergidas, agrupamento, priorização e os "portanto".
+
+## Critério de pronto (DoD)
+
+- [ ] Tópico e critério de sucesso confirmados com o usuário (elicitação cumprida)
+- [ ] Pelo menos uma técnica nomeada aplicada e registrada
+- [ ] Fase de divergência ocorreu antes da convergência (rastro no documento)
+- [ ] Ideias priorizadas em lista numerada, cada top item com "portanto" acionável e dono sugerido
+- [ ] Documento salvo em `docs/research/brainstorm-{slug}.md`
+
+## Falha / recuperação
+
+- **Usuário não consegue definir o critério de sucesso** → paro na elicitação e ofereço 2-3 enquadramentos para escolha; não improviso o alvo.
+- **A sessão converge cedo demais** (usuário quer fechar na 1ª ideia) → registro a ideia, mas insisto em ao menos uma rodada de divergência antes de priorizar.
+- **Nenhuma ideia sobrevive ao filtro** → reporto que o critério pode estar estreito demais; reabro a divergência com técnica diferente em vez de forçar um resultado fraco.

package/tasks/generate-ai-frontend-prompt.md

@@ -0,0 +1,57 @@
+---
+id: generate-ai-frontend-prompt
+agent: ux-design-expert
+title: Gerar prompt para ferramentas de UI por IA
+inputs: [wireframes, front-end spec, design tokens disponíveis]
+outputs: [prompt estruturado para v0/Lovable/similar]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Gerar prompt para ferramentas de UI por IA
+
+**Objetivo:** traduzir wireframes e spec de frontend num prompt estruturado e rastreável que uma
+ferramenta de geração de UI por IA (v0, Lovable, etc.) consiga executar fielmente — sem inventar
+requisito fora da spec.
+
+**Pré-condições:**
+- Existem wireframes (`ux-create-wireframe`) e/ou uma front-end spec que descrevem as telas e o
+  comportamento. Sem fonte, **pare** — o prompt não pode inventar a UI.
+- Os design tokens (cor, espaçamento, tipografia, raio) estão disponíveis ou referenciáveis. Sem
+  tokens, sinalizo que o output virá com valores genéricos a corrigir depois.
+
+## Passos
+
+1. **Reúna os insumos:** wireframes, spec de frontend, design tokens e os ACs da story. O prompt só
+   pode afirmar o que esses insumos sustentam.
+2. **Estruture o prompt em blocos claros:** (a) contexto e objetivo da tela; (b) layout e hierarquia;
+   (c) componentes e estados (vazio/carregando/erro/sucesso); (d) tokens a usar (não hex solto);
+   (e) requisitos de acessibilidade (foco visível, semântica, contraste WCAG AA); (f) stack/framework
+   alvo da ferramenta.
+3. **Ancore cada requisito do prompt** a um wireframe, item da spec ou AC. Frase do prompt que não
+   rastreia a um insumo é invenção — corto.
+4. **Inclua as restrições de acessibilidade como obrigatórias**, não como "se possível": contraste
+   AA, navegação por teclado, alt text, ordem de foco. O output gerado nasce com a11y ou volta.
+5. **Adicione as guardas de tokens:** instruo a ferramenta a consumir os design tokens nomeados em
+   vez de valores hardcoded, para o resultado já nascer consistente com o design system.
+6. **Registre o prompt** em `docs/stories/{epic}/ai-prompts/` (ou na seção de UX da story) com a
+   indicação da ferramenta-alvo e dos insumos que o originaram.
+7. **Marque o output como rascunho a auditar:** o que a IA gerar passa pela minha auditoria de a11y e
+   de tokens antes de virar componente de produção — não entra direto.
+
+## Critério de pronto (DoD)
+
+- [ ] Prompt estruturado em blocos (contexto, layout, componentes/estados, tokens, a11y, stack)
+- [ ] Cada requisito do prompt rastreia a um wireframe, spec ou AC
+- [ ] Acessibilidade WCAG AA escrita como obrigatória no prompt
+- [ ] Guarda de tokens presente (sem hardcoded no output esperado)
+- [ ] Prompt registrado com ferramenta-alvo e insumos de origem
+
+## Falha / recuperação
+
+- **Faltam wireframes ou spec** → não escrevo prompt no escuro; volto para `ux-create-wireframe` ou
+  `create-front-end-spec` primeiro.
+- **Não há design tokens** → gero o prompt com aviso explícito de que o output exigirá tokenização
+  posterior (`extract-tokens`) antes de produção.
+- **O output da IA viola a11y ou usa hardcoded** → reprovo na auditoria e refino o prompt; não
+  promovo a componente de produção.