nexus-core-v3 3.0.0

package/tasks/generate-documentation.md

@@ -0,0 +1,60 @@
+---
+id: generate-documentation
+agent: ux-design-expert
+title: Gerar a documentação da pattern library
+inputs: [design-system, componentes, tokens]
+outputs: [pattern library documentada, índice navegável, File List atualizada]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Gerar a documentação da pattern library
+
+**Objetivo:** transformar o design system construído (tokens, átomos, moléculas, organismos) em uma
+pattern library documentada e navegável — cada componente com uso, anatomia, variantes e regras de a11y.
+
+**Pré-condições:**
+- O design system existe (`*setup` rodou) e há ao menos um componente construído. Se não há nada
+  construído, **pare** — não documento o vazio.
+- Os componentes a documentar estão em produção e passaram no checklist de qualidade (testes + a11y).
+  Documento o que está pronto, não o rascunho.
+
+## Passos
+
+1. **Inventario o que existe** no design system: tokens, átomos, moléculas, organismos. Cada um vira
+   uma entrada na pattern library. Cruzo com a story/spec para garantir que documento só o real.
+2. **Documento os design tokens primeiro** — a fundação: cor, tipografia, espaçamento, raio. Mostro o
+   nome do token, o valor e onde se aplica. Tokens são o vocabulário; vêm antes dos componentes.
+3. **Para cada componente, escrevo a ficha:**
+   a. **anatomia** — partes e props do componente;
+   b. **variantes** — cada variante com exemplo visual/código e o token que a alimenta;
+   c. **quando usar / quando não usar** — a regra que evita uso errado;
+   d. **a11y** — comportamento de foco, teclado, semântica e contraste garantido.
+4. **Puxo os exemplos do código real**, não invento snippet. Cada exemplo reflete o componente como
+   ele existe — doc que diverge do código é pior que nenhuma doc.
+5. **Monto o índice navegável** organizado por nível Atomic (tokens → átomos → moléculas → organismos),
+   com links cruzados (uma molécula referencia os átomos que a compõem).
+6. **Verifico a cobertura:** todo componente em produção tem ficha; nenhuma ficha referencia componente
+   inexistente. Sinalizo lacunas em vez de inventar.
+7. **Salvo a pattern library** no destino do design system, **atualizo a File List** da story e faço
+   **commit local** (conventional commit com o id da story). **Nunca** `git push` — delego a publicação
+   (ex.: deploy do site da pattern library) ao @devops.
+
+## Critério de pronto (DoD)
+
+- [ ] Todos os tokens documentados (nome, valor, aplicação)
+- [ ] Todo componente em produção tem ficha: anatomia, variantes, uso/não-uso, a11y
+- [ ] Exemplos puxados do código real — nenhum snippet inventado
+- [ ] Índice navegável por nível Atomic, com links cruzados
+- [ ] Nenhuma ficha referencia componente inexistente
+- [ ] File List atualizada e commit local feito (sem `git push`)
+
+## Falha / recuperação
+
+- **Um componente não passou no checklist de qualidade (a11y/testes)** → não documento como "pronto";
+  marco como pendente e sinalizo, ou aguardo ele ficar pronto.
+- **A doc diverge do código** (exemplo desatualizado) → corrijo a doc para refletir o código; nunca o
+  contrário sem story.
+- **Encontro componente sem story/spec por trás** → sinalizo como dívida de rastreabilidade em vez de
+  legitimar via doc.
+- **Publicação/deploy do site da pattern library** → delego ao @devops; eu gero a doc, ele sobe.

package/tasks/generate-migration-strategy.md

@@ -0,0 +1,57 @@
+---
+id: generate-migration-strategy
+agent: ux-design-expert
+title: Gerar estratégia de migração em fases para o design system
+inputs: [shock report, padrões consolidados, design tokens]
+outputs: [estratégia de migração faseada, 'docs/stories/{story}/migration-strategy.md']
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Gerar estratégia de migração em fases para o design system
+
+**Objetivo:** transformar o caos medido e os tokens extraídos num plano de migração em fases — qual
+componente migra antes, com que risco, em que ordem — para que a app adote o design system sem
+parar de funcionar. Comece simples, refine com feedback.
+
+**Pré-condições:**
+- O shock report (`generate-shock-report`) já mostrou o estrago e o ROI por cluster. Sem ele,
+  **pare**: migração sem prioridade medida é chute.
+- Os design tokens (`extract-tokens`) e o mapeamento valor antigo → token já existem — é o que a
+  migração vai aplicar. Sem isso, falta o destino.
+- Existe story/spec que pede a migração. Sem rastro, elicito o escopo — não invento fases.
+
+## Passos
+
+1. **Listo os clusters a migrar** a partir do shock report, com volume de ocorrências e impacto
+   (quantas telas/áreas cada um toca).
+2. **Priorizo por valor × risco.** Alto volume + baixo risco primeiro (vitória rápida, prova o
+   modelo); alto risco/alta criticidade depois, com mais cuidado. Cada fase entrega valor sozinha.
+3. **Defino as fases** — tipicamente:
+   - **Fase 0 — fundação:** tokens cabeados, design system inicializado (já feito), sem trocar telas.
+   - **Fase 1 — átomos de alto volume e baixo risco** (ex.: botão, input) com strangler: novo
+     componente convive com o antigo até substituir.
+   - **Fase N — moléculas/organismos e áreas críticas**, uma por vez, com validação.
+4. **Para cada fase, especifico:** componentes alvo, mapeamento antigo → token/componente, critério
+   de pronto, plano de rollback (como voltar se quebrar) e o gate de validação (@qa) e a11y.
+5. **Marco os pontos de feedback.** Após cada fase, medir uso real e acessibilidade antes de seguir
+   — a próxima fase só começa com a anterior validada.
+6. **Defino fronteiras de autoridade no plano:** o que é design/construção do sistema (meu + build),
+   o que é integração na app (@dev), validação (@qa), e que toda subida é do @devops.
+7. **Escrevo** `docs/stories/{story}/migration-strategy.md`, rastreando cada fase à story/spec e ao
+   cluster do shock report. Registro na File List.
+
+## Critério de pronto (DoD)
+
+- [ ] Clusters priorizados por valor × risco, com volume e impacto explícitos
+- [ ] Fases definidas, cada uma entregando valor sozinha e com strangler onde aplicável
+- [ ] Cada fase tem alvo, mapeamento antigo → token/componente, critério de pronto, rollback e gate
+- [ ] Pontos de feedback/validação (uso + a11y) entre fases marcados
+- [ ] Fronteiras de autoridade explícitas (dev integra, qa valida, devops sobe); rastro à story
+
+## Falha / recuperação
+
+- **Shock report ou tokens ausentes** → HALT; não planejo migração sem o caos medido e o destino.
+- **Uma fase não tem rollback viável** → não a aprovo; quebro em passos menores até haver caminho de
+  volta seguro.
+- **Escopo cresce além da story** → paro e devolvo ao @sm/@po; não invento fases fora do rastro.

package/tasks/generate-shock-report.md

@@ -0,0 +1,56 @@
+---
+id: generate-shock-report
+agent: ux-design-expert
+title: Gerar o shock report — o caos de UI lado a lado com o ROI
+inputs: [auditoria de codebase, padrões consolidados]
+outputs: [relatório HTML do caos visual + ROI, 'docs/stories/{story}/shock-report.html']
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Gerar o shock report — o caos de UI lado a lado com o ROI
+
+**Objetivo:** transformar a redundância medida na auditoria num relatório HTML que mostra o caos
+visual lado a lado (os 47 botões diferentes), com o número que prova o estrago e o ROI da
+consolidação — para mover a decisão com dado, não com opinião.
+
+**Pré-condições:**
+- A auditoria (`audit-codebase`) já rodou e existe o inventário de padrões redundantes. Sem ele,
+  **pare**: shock report sem medição é opinião disfarçada de relatório.
+- A consolidação (`consolidate-patterns`) já agrupou os padrões similares, com a contagem de
+  ocorrências por cluster. Se faltar, rode `consolidate` antes.
+- Existe uma story/spec que pede a consolidação. Sem rastro, eu elicito o escopo — não invento.
+
+## Passos
+
+1. **Carrego o inventário e os clusters** da auditoria/consolidação: total de variantes por tipo de
+   componente (botões, inputs, cards…), e quantas se reduzem a quantas após o clustering.
+2. **Calculo a redução por tipo** — variantes antes → variantes depois, e o percentual (ex.: 47 →
+   3, 93,6% de redução). Esse é o número que abre o relatório.
+3. **Monto o lado a lado visual.** Cada cluster vira uma faixa do HTML: as variantes redundantes
+   renderizadas juntas (o caos) e a variante consolidada proposta (o destino). O olho tem que ver a
+   divergência, não só ler o número.
+4. **Puxo o ROI da task `calculate-roi`.** Não invento a economia: peço/uso o output de
+   `calculate-roi` (horas de manutenção evitadas, custo/ano). Se ele não existe, sinalizo que o ROI
+   é estimativa pendente — não chuto valor financeiro.
+5. **Renderizo o HTML** auto-contido (estilos inline, sem dependência externa para abrir no
+   browser), com: headline da redução, faixas lado a lado por cluster, tabela de ROI e rastro à
+   story/spec de origem.
+6. **Salvo em** `docs/stories/{story}/shock-report.html` e registro o arquivo na File List da story.
+7. **Roteio.** Relatório pronto vira insumo da decisão de migração (`generate-migration-strategy`).
+   Se precisar publicar/hospedar o HTML em algum lugar, **delego ao @devops** — eu não subo nada.
+
+## Critério de pronto (DoD)
+
+- [ ] Cada cluster aparece com contagem antes → depois e percentual de redução
+- [ ] O lado a lado visual renderiza o caos e o destino, abre no browser sem dependência externa
+- [ ] O ROI vem de `calculate-roi` (ou está marcado explicitamente como estimativa pendente)
+- [ ] O relatório rastreia à story/spec de origem; arquivo na File List
+- [ ] Nada foi publicado por mim (subida é do @devops)
+
+## Falha / recuperação
+
+- **Inventário ou clusters ausentes** → HALT; rodo `audit` / `consolidate` antes, não gero relatório
+  com dado faltando.
+- **ROI sem base** → não invento número financeiro; marco como pendente e sigo com a parte visual.
+- **A story que justifica a consolidação não existe** → paro e devolvo ao @sm/@po para criar o rastro.

package/tasks/mcp-management.md

@@ -0,0 +1,66 @@
+---
+id: mcp-management
+agent: devops
+title: Gerenciar servidores MCP — buscar, adicionar, listar, remover
+inputs: [operação MCP, nome/servidor]
+outputs: [catálogo MCP atualizado, lista de MCPs e tools, relatório da operação]
+elicit: true
+modes: [interactive]
+---
+
+# Gerenciar servidores MCP — buscar, adicionar, listar, remover
+
+**Objetivo:** operar a infraestrutura de MCP (buscar no catálogo, adicionar, listar e remover
+servidores) de forma centralizada e segura — eu, @devops, sou o **único** agente autorizado a
+configurar MCP; os demais são consumidores.
+
+**Pré-condições:**
+- A operação foi pedida ou delegada a mim (@devops). Se outro agente precisa de um MCP, ele **delega**
+  aqui — não configura por conta própria.
+- O runtime de MCP (Docker MCP Toolkit) está disponível. Se não estiver, **pare** e reporte que a
+  infraestrutura precisa ser provisionada antes.
+
+## Passos
+
+1. **Identifico a operação** pedida: `*search-mcp`, `*add-mcp`, `*list-mcps` ou `*remove-mcp`. Cada
+   uma rastreia a uma necessidade concreta de uma story/objetivo — não adiciono MCP "por garantia".
+2. **Buscar (`*search-mcp`):** consulto o catálogo do Docker MCP Toolkit pelo termo. Apresento os
+   candidatos (nome, propósito, tools que expõe) para o usuário escolher. Operação somente-leitura.
+3. **Listar (`*list-mcps`):** mostro os servidores MCP habilitados e as tools de cada um, sinalizando
+   quais exigem credencial. Somente-leitura.
+4. **Adicionar (`*add-mcp`):**
+   a. confirmo qual servidor e por quê (rastreia ao objetivo);
+   b. **PONTO DE ELICITAÇÃO** — se o servidor exige credencial (token/API key), **peço o segredo ao
+      usuário**; **nunca** invento, codifico em claro num arquivo versionado, nem deixo vazar para a
+      `main`. Segredo entra pela via de configuração segura do runtime;
+   c. habilito o servidor no Docker MCP Toolkit e **valido** com um list/health-check de que as tools
+      respondem (não ficam como "prompts" pendentes de auth).
+5. **Remover (`*remove-mcp`):**
+   a. **PONTO DE ELICITAÇÃO** — confirmo com o usuário, pois remover MCP pode quebrar agentes que o
+      consomem;
+   b. desabilito o servidor no toolkit e verifico que saiu da lista.
+6. **Varro segredos.** Qualquer credencial manipulada na operação não pode terminar num diff
+   versionado. Se a configuração tocou arquivo rastreado, confirmo que nenhum segredo ficou em claro
+   antes de qualquer subida — e subida de remoto, se houver, é **exclusiva minha** (@devops).
+7. **Reporto.** Resultado da operação, MCPs ativos resultantes e, em add/remove, o caminho de
+   reversão (re-habilitar/re-remover).
+
+## Critério de pronto (DoD)
+
+- [ ] A operação correta foi identificada e rastreia a um objetivo real
+- [ ] Add/remove confirmados pelo usuário no ponto de elicitação
+- [ ] Credenciais tratadas pela via segura — nenhum segredo em claro ou em diff versionado
+- [ ] MCP adicionado validado (tools respondem) ou removido confirmado (saiu da lista)
+- [ ] Relatório entregue com o estado final e o caminho de rollback
+
+## Falha / recuperação
+
+- **Servidor MCP adicionado fica como "prompts" em vez de "tools"** → a autenticação não passou;
+  reviso a credencial pela via segura do runtime e re-valido. Não dou por concluído um MCP que não
+  responde tools.
+- **Remoção quebra um agente consumidor** → re-habilito o servidor e reporto o impacto antes de
+  insistir na remoção.
+- **Outro agente tentou configurar MCP** → bloqueio e assumo a operação; configuração de MCP é
+  exclusiva do @devops.
+- **Runtime de MCP indisponível** → HALT, reporto que a infraestrutura precisa ser provisionada antes
+  de qualquer operação de MCP.

package/tasks/orchestrate.md

@@ -0,0 +1,50 @@
+---
+id: orchestrate
+agent: nexus-master
+title: Orquestrar — decompor e delegar a N sub-agentes
+inputs: [objetivo]
+outputs: [árvore de entregas, resultado costurado]
+elicit: false
+modes: [yolo]
+---
+
+# Orquestrar — decompor e delegar a N sub-agentes
+
+**Objetivo:** transformar um objetivo de construção em entregas reais, delegando frentes
+independentes a sub-agentes que executam em paralelo — via o motor (`nexus run`).
+
+**Pré-condições:**
+- O objetivo é **construção** (executar), não decisão. Se for uma decisão dura com trade-off real,
+  use a task `deliberate` (party-mode), não esta.
+- O objetivo rastreia a um pedido/story/spec. Sem isso, elicito o escopo — não invento.
+
+## Passos
+
+1. **Entendo o objetivo completo** e o classifico: é paralelizável? quais frentes existem? quem é o
+   dono de cada uma? (copy→@analyst/@pm, design→@ux, implementação→@dev, dados→@data-engineer,
+   qualidade→@qa, subida→@devops).
+2. **Decomponho em frentes com fronteiras limpas.** Cada frente: um dono, um input, um critério de
+   pronto. Frentes de baixo acoplamento correm em paralelo; as acopladas eu sequencio (deps).
+3. **Disparo o motor** (`nexus run "{objetivo}"`): o coordenador emite a decomposição, e o
+   SubagentOrchestrator spawna os sub-agentes por ondas, respeitando as dependências. Cada sub-agente
+   pode re-delegar (recursão), dentro dos freios. Com `--waves`, cada onda roda com paralelismo
+   pleno (sem teto de concorrência dentro da onda).
+4. **Respeito os freios.** `maxFanout`, `maxDepth` e `maxTotalRuns` têm teto. Se a decomposição
+   estoura, eu **recuso a decomposição inteira** e reformulo — não gero sub-agentes órfãos.
+5. **Costuro o resultado.** Recolho as entregas das frentes, verifico contra cada critério de pronto,
+   e entrego o todo — nomeando quem fez o quê.
+6. **Roteio o gate.** Implementado → @qa (quality gate). Aprovado e pronto pra subir → @devops.
+
+## Critério de pronto (DoD)
+
+- [ ] Cada frente tem dono, input e critério de pronto explícitos
+- [ ] A decomposição respeitou os freios (sem órfãos, sem estouro de budget)
+- [ ] Todas as frentes entregues e verificadas contra o critério
+- [ ] Resultado costurado e roteado ao gate (@qa) / subida (@devops)
+
+## Falha / recuperação
+
+- **Uma frente falha** → o motor bloqueia os dependentes dela; eu reporto a frente travada e decido
+  re-delegar ou escalar, sem dar por entregue o que não saiu.
+- **A decomposição estoura os freios** → recuso e reformulo em frentes maiores/menos acopladas.
+- **O objetivo era decisão, não construção** → troco para a task `deliberate`.

package/tasks/perform-market-research.md

@@ -0,0 +1,42 @@
+---
+id: perform-market-research
+agent: analyst
+title: Produzir pesquisa de mercado
+inputs: [objetivo da pesquisa / pergunta de mercado]
+outputs: ['docs/research/market-research-{slug}.md (achados com fontes citadas e "portanto")']
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Produzir pesquisa de mercado
+
+**Objetivo:** entregar uma análise de mercado rigorosa — dimensionamento, segmentos, tendências e dinâmica — onde todo achado rastreia a uma fonte verificável e termina num "portanto" acionável.
+
+**Pré-condições:**
+- A pergunta de mercado está clara e ligada a uma decisão (entrar num segmento? dimensionar demanda? validar timing?). Se vaga, **pare** e elícito (`*elicit`) — pesquisa sem pergunta é tempo queimado.
+- Há acesso a fontes (web search, relatórios, dados internos). Sem fonte verificável, o achado vira hipótese rotulada.
+
+## Passos
+
+1. **Aperto o objetivo até doer.** Defino a decisão que a pesquisa precisa destravar e o escopo (geografia, segmento, horizonte temporal). Registro no topo do documento.
+2. **Escolho o framework** adequado (ex.: TAM/SAM/SOM para dimensionamento, Porter para dinâmica, PESTEL para macro-tendências, segmentação por persona). Anuncio qual estou usando.
+3. **DIVIRJO — coleto largura.** Levanto mais fontes do que parece confortável: relatórios de indústria, dados públicos, notícias, players. Nesta fase não julgo, só coleto e creditos cada fonte.
+4. **CONVIRJO — filtro por evidência.** Mantenho o que tem fonte forte e datada; descarto ruído e fonte fraca. Cada número que sobrevive carrega de onde veio e quando.
+5. **Estruturo os achados** segundo o framework: dimensionamento, segmentos, tendências, dinâmica competitiva, barreiras. Marco explicitamente o que é dado citado vs. estimativa/hipótese minha.
+6. **Sintetizo em "portanto".** Cada bloco de achado termina numa implicação acionável para a decisão — em lista numerada, com a fonte ao lado.
+7. **Salvo** em `docs/research/market-research-{slug}.md` com seção de Fontes citada por completo, e roteio: estratégia/PRD → @pm.
+
+## Critério de pronto (DoD)
+
+- [ ] Decisão-alvo e escopo declarados no topo
+- [ ] Framework nomeado e aplicado
+- [ ] Divergência (coleta ampla) ocorreu antes da convergência (filtro)
+- [ ] Todo número/afirmação rastreia a uma fonte datada OU está marcado como hipótese
+- [ ] Cada bloco fecha com um "portanto" acionável
+- [ ] Documento salvo com seção de Fontes completa e roteado ao @pm
+
+## Falha / recuperação
+
+- **Fontes conflitam sobre um número** → apresento o intervalo e as fontes em vez de cravar um valor; explicito a incerteza.
+- **Não encontro fonte verificável para um ponto-chave** → marco como hipótese explícita e listo em "questões em aberto"; não invento dado.
+- **A pergunta se revela ampla demais no meio** → paro, reporto, e proponho fatiar em sub-perguntas com o usuário antes de seguir.

package/tasks/plan-create-context.md

@@ -0,0 +1,57 @@
+---
+id: plan-create-context
+agent: architect
+title: Gerar o contexto de projeto e arquivos para a story
+inputs: [story, implementation.yaml]
+outputs: [context.md (arquivos relevantes, padrões, contratos, restrições)]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Gerar o contexto de projeto e arquivos para a story
+
+**Objetivo:** reunir num único artefato tudo que o @dev precisa para implementar a story sem garimpar
+o codebase — arquivos relevantes, padrões a seguir, contratos a respeitar e restrições — para que a
+story seja autossuficiente.
+
+**Pré-condições:**
+- A story existe e está validada (não-Draft). Se estiver em Draft, **pare**.
+- Existe `implementation.yaml` da story (via `*create-plan`). Sem o plano, não sei quais camadas o
+  contexto precisa cobrir — rodo `*create-plan` primeiro.
+
+## Passos
+
+1. **Leia a story e o `implementation.yaml`.** As fases e subtasks dizem quais camadas e arquivos o
+   contexto tem que iluminar.
+2. **Mapeie os arquivos relevantes** que cada fase vai tocar ou consumir — caminhos absolutos,
+   curtos e precisos. Apenas o que importa para esta story; contexto inchado é tão ruim quanto contexto faltando.
+3. **Extraia os padrões existentes a seguir.** Convenções de nomenclatura, estrutura de pastas,
+   utilitários/componentes reusáveis (REUSE > ADAPT > CREATE), estilo de erro. O @dev segue o que já
+   existe, não inventa um dialeto novo.
+4. **Documente os contratos a respeitar.** Assinaturas de API, shapes de dados, fronteiras entre
+   camadas que a story cruza. Onde o contrato é da Dara (@data-engineer) ou da Uma
+   (@ux-design-expert), aponto o dono e o contrato — não detalho a implementação da camada deles.
+5. **Liste as restrições.** NFRs aplicáveis (latência, escala, segurança, orçamento), CONs do projeto
+   e os failure modes já anotados no plano. Cada item rastreia a um FR/NFR/CON ou ao plano — sem invenção.
+6. **Grave `context.md`** em `docs/specs/{storyId}/context.md`: arquivos relevantes, padrões,
+   contratos, restrições e a regra de autoridade (commit local pelo @dev; `git push`/PR/release pelo @devops).
+7. **Roteie ao @dev.** Story validada + plano + contexto = pronto para `dev-develop-story`.
+   Implementado → @qa (gate). Pronto para subir → @devops.
+
+## Critério de pronto (DoD)
+
+- [ ] Arquivos relevantes listados com caminho absoluto e enxutos ao que a story toca
+- [ ] Padrões existentes a seguir documentados (REUSE > ADAPT > CREATE)
+- [ ] Contratos entre camadas explícitos, com dono apontado onde for de especialista
+- [ ] Restrições (NFR/CON/failure modes) listadas e rastreáveis ao plano/spec
+- [ ] `docs/specs/{storyId}/context.md` gravado e válido
+- [ ] Roteado ao @dev com a regra de autoridade explícita
+
+## Falha / recuperação
+
+- **`implementation.yaml` ausente** → HALT, rodo `*create-plan` antes de gerar o contexto.
+- **Padrão/contrato necessário não existe no codebase** → registro a lacuna; se for decisão
+  arquitetural, decido (`*create-architecture`); se for de camada de especialista, delego (@data-engineer/@ux-design-expert).
+- **Item de contexto não rastreia a story/plano/FR/NFR/CON** → não entra. Contexto não é lugar para
+  inventar escopo (Art. IV).
+- **A story revelou-se ambígua ao montar o contexto** → paro, registro a lacuna e devolvo ao @sm/@po.

package/tasks/plan-create-implementation.md

@@ -0,0 +1,58 @@
+---
+id: plan-create-implementation
+agent: architect
+title: Criar plano de implementação com fases e subtasks
+inputs: [story, complexity.json]
+outputs: [implementation.yaml (fases, subtasks, deps, donos)]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Criar plano de implementação com fases e subtasks
+
+**Objetivo:** transformar uma story já dimensionada num plano de execução com fases ordenadas,
+subtasks rastreáveis a ACs e donos por camada — o mapa que o @dev segue sem ter que reinventar a rota.
+
+**Pré-condições:**
+- A story existe, está validada (não-Draft) e tem ACs. Se estiver em Draft, **pare** — não planejo o que o @po ainda não aprovou.
+- Existe `complexity.json` da story (via `*assess-complexity`). Sem a classe, não sei a profundidade
+  do plano — rodo `*assess-complexity` primeiro.
+
+## Passos
+
+1. **Leia a story e o `complexity.json`.** A classe (SIMPLE/STANDARD/COMPLEX) define a granularidade:
+   SIMPLE = poucas fases enxutas; COMPLEX = fases com fronteiras explícitas e ciclo de revisão.
+2. **Desenhe a espinha de fases.** Sequencie por dependência real (ex.: dados → backend → frontend →
+   integração → testes). Cada fase tem uma fronteira limpa e um motivo de existir.
+3. **Quebre cada fase em subtasks rastreáveis.** Toda subtask aponta para o(s) AC(s) que satisfaz. Sem
+   AC de origem, a subtask não entra — isso é invenção de escopo (Art. IV).
+4. **Aplique REUSE > ADAPT > CREATE** ao planejar: marque onde reusar padrão/utilitário existente,
+   onde adaptar e onde criar de fato — e registre o porquê de cada CREATE.
+5. **Atribua o dono de cada fase/subtask por camada.** Schema/DDL/RLS/query → @data-engineer.
+   UI/fluxos → @ux-design-expert. Código de aplicação → @dev. Eu costuro o contrato entre camadas;
+   não invado a lane do especialista.
+6. **Rode o teste do 10× nas fronteiras de integração.** Para cada costura, anote o failure mode ao
+   escalar (N+1, hot path, ponto único de falha). Plano sem "o que quebra" é meio plano.
+7. **Marque os pontos de quality gate.** Onde o @qa entra, o que ele verifica, e a regra de subida:
+   pronto para subir → delega ao @devops (`git push`/PR/release são exclusivos dele).
+8. **Grave `implementation.yaml`** em `docs/specs/{storyId}/implementation.yaml`: fases ordenadas,
+   subtasks com AC de origem e dono, dependências, failure modes anotados e pontos de gate.
+
+## Critério de pronto (DoD)
+
+- [ ] Fases ordenadas por dependência real, cada uma com fronteira e motivo
+- [ ] Toda subtask rastreia a pelo menos um AC da story
+- [ ] Dono atribuído por camada (sem invasão de lane)
+- [ ] Failure mode anotado em cada fronteira de integração (teste do 10×)
+- [ ] Pontos de quality gate (@qa) e regra de subida (@devops) marcados
+- [ ] `docs/specs/{storyId}/implementation.yaml` gravado e válido
+
+## Falha / recuperação
+
+- **Subtask que não rastreia a nenhum AC** → removo. Se é necessária de verdade, é um AC faltando —
+  devolvo ao @sm/@po, não invento o requisito.
+- **`complexity.json` ausente** → HALT, rodo `*assess-complexity` antes de planejar.
+- **Fronteira de integração sem failure mode definível** (dependência externa indefinida) → registro
+  o bloqueio e escalo, em vez de planejar sobre a versão feliz.
+- **Plano exige decisão arquitetural não tomada** (ex.: qual banco) → paro o planejamento, tomo/decido
+  a arquitetura (`*create-architecture`) e só então sigo.

package/tasks/po-close-story.md

@@ -0,0 +1,60 @@
+---
+id: po-close-story
+agent: po
+title: Fechar uma story concluída e atualizar epic/backlog
+inputs: [story]
+outputs: [story marcada Done, epic atualizado, backlog atualizado, próxima story sugerida]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Fechar uma story concluída e atualizar epic/backlog
+
+**Objetivo:** fechar o ciclo de uma story que passou pelo QA — confirmando que cada AC foi
+cumprido, atualizando epic e backlog, e sugerindo a próxima story — com a mesma rastreabilidade
+com que o ciclo foi aberto.
+
+**Pré-condições:**
+- A story está em status `InReview`/`Ready for Done` com o gate do @qa **PASS** (ou WAIVED com
+  justificativa registrada). Se o gate foi FAIL/CONCERNS sem resolução, **pare** — não fecho o que
+  o QA não liberou.
+- O epic de origem e o backlog estão acessíveis para atualização de contexto.
+
+## Passos
+
+1. **Releia os ACs originais** da story e confirme, um a um, que cada critério foi cumprido com
+   evidência (teste verde, gate do @qa). AC sem evidência de cumprimento bloqueia o fechamento.
+2. **Confirme o veredito do @qa.** O gate de qualidade está PASS (ou WAIVED com justificativa
+   registrada)? Sem isso, devolvo ao fluxo de QA em vez de fechar.
+3. **Verifique a rastreabilidade final.** Os FR/NFR/CON que a story prometia cumprir estão de fato
+   entregues? Atualizo o mapa de rastreabilidade do epic, marcando os requisitos como atendidos.
+4. **Marque a story `Done`** no arquivo em `docs/stories/`, registrando data de fechamento e o
+   veredito do @qa no Change Log.
+5. **Atualize o epic.** Marque a story como concluída no índice do epic e recalcule o progresso
+   (X de N stories). Se a conclusão revelou follow-ups, registre-os via `po-manage-story-backlog`.
+6. **Atualize o backlog.** Remova/arquive o item correspondente do "em andamento" e promova
+   dependentes que agora estão destravados.
+7. **Sugira a próxima story.** Olhe a sequência do epic e o backlog priorizado; aponte qual story
+   está pronta para entrar (dependências satisfeitas). Roteio a criação ao `@sm *draft` se ainda
+   não existir.
+8. **Delegue qualquer subida.** Se o fechamento envolve subir artefatos (push, PR, tag de release),
+   **eu não opero git remoto** — delego ao `@devops`. Eu fecho a story; o Gage publica.
+
+## Critério de pronto (DoD)
+
+- [ ] Cada AC confirmado como cumprido, com evidência
+- [ ] Gate do @qa confirmado PASS (ou WAIVED justificado)
+- [ ] Rastreabilidade final atualizada no epic (requisitos atendidos)
+- [ ] Story marcada `Done` com data e veredito no Change Log
+- [ ] Epic atualizado (progresso recalculado) e follow-ups registrados no backlog
+- [ ] Backlog atualizado e dependentes destravados promovidos
+- [ ] Próxima story sugerida (ou criação roteada ao @sm)
+
+## Falha / recuperação
+
+- **Algum AC não tem evidência de cumprimento** → não fecho; devolvo ao @dev/@qa com a lacuna
+  apontada. Fechar story incompleta vira retrabalho três fases depois.
+- **Gate do @qa não é PASS** → devolvo ao fluxo de QA (QA Loop) em vez de fechar.
+- **A conclusão revelou requisito inventado sem fonte** (Art. IV) → bloqueio o fechamento e exijo a
+  origem ou a remoção do escopo invadido antes de marcar Done.
+- **O fechamento exige push/PR/release** → delego ao @devops; nunca opero git remoto, nem aqui.

package/tasks/po-manage-story-backlog.md

@@ -0,0 +1,59 @@
+---
+id: po-manage-story-backlog
+agent: po
+title: Gerir o backlog de stories — adicionar, priorizar, agendar, revisar
+inputs: [ação (add|review|prioritize|schedule), item|prioridade|sprint]
+outputs: [backlog atualizado, revisão de backlog para planejamento de sprint]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Gerir o backlog de stories — adicionar, priorizar, agendar, revisar
+
+**Objetivo:** manter o backlog de stories coeso, priorizado e sequenciado — equilibrando o que é
+HIGH de verdade contra o que só parece urgente, sem nunca quebrar a ordem lógica das dependências.
+
+**Pré-condições:**
+- O arquivo de backlog existe (`docs/stories/backlog.md` ou índice equivalente). Se não existir e a
+  ação for `add`, eu o crio com a estrutura padrão.
+- Todo item adicionado rastreia a uma origem (FR/NFR/CON do PRD, follow-up de QA, dívida técnica
+  registrada). Item sem origem não entra (Art. IV — No Invention).
+
+## Passos
+
+1. **Identifique a ação:** `add` (incluir item), `review` (gerar revisão para sprint),
+   `prioritize` (re-priorizar) ou `schedule` (agendar para um sprint).
+2. **Para `add`:** registre o item com origem rastreável, tipo (story | follow-up | tech-debt |
+   enhancement), prioridade inicial (HIGH/MED/LOW) e dependências conhecidas. Item sem origem é
+   recusado; peço a fonte ao solicitante.
+3. **Para `prioritize`:** ajuste a prioridade do item pesando impacto real × urgência real, não a
+   pressão de quem pediu. Reordene de forma que dependências precedam dependentes — prioridade nunca
+   reescreve a ordem lógica.
+4. **Para `schedule`:** aloque o item a um sprint **somente se** suas dependências já estiverem
+   satisfeitas ou agendadas para sprint anterior. Story que precisa de schema inexistente não entra
+   só porque "é prioridade".
+5. **Para `review`:** gere a revisão de backlog para planejamento — itens por prioridade, status,
+   dependências e prontidão. Sinalize bloqueios de sequência e itens sem origem.
+6. **Persista as mudanças** no arquivo de backlog, mantendo o histórico de re-priorizações.
+7. **Roteie quando preciso:** item que vira story precisa ser escrito → `@sm *draft`. Item que muda
+   escopo/produto → `@pm`. Conflito de prioridade que altera o plano do epic → escalo ao
+   `@nexus-master`.
+
+## Critério de pronto (DoD)
+
+- [ ] Ação identificada e executada (add | review | prioritize | schedule)
+- [ ] Todo item tem origem rastreável e tipo definido
+- [ ] Dependências mapeadas; ordem lógica preservada (deps antes de dependentes)
+- [ ] Itens agendados têm dependências satisfeitas ou agendadas antes
+- [ ] Backlog persistido com histórico de re-priorizações
+- [ ] Revisão de sprint (se solicitada) lista prioridade, status, deps e bloqueios
+
+## Falha / recuperação
+
+- **Item sem origem rastreável** → recuso a inclusão e peço a fonte (FR/NFR/CON, follow-up, dívida).
+- **Pediram para agendar story com dependência faltante** → bloqueio o agendamento e sinalizo a
+  dependência. Prioridade sem ordem lógica é caos agendado.
+- **Conflito de prioridade entre stakeholders** → não decido escopo em silêncio; sinalizo e escalo
+  ao @nexus-master / @pm conforme a natureza do conflito.
+- **Item parece exigir push/release** → não é função de backlog; qualquer operação remota é do
+  @devops.

package/tasks/po-pull-story.md

@@ -0,0 +1,60 @@
+---
+id: po-pull-story
+agent: po
+title: Puxar atualizações de uma story da ferramenta de PM
+inputs: [story, ferramenta (clickup|github|jira|local)]
+outputs: [story local atualizada com mudanças remotas, conflitos sinalizados]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Puxar atualizações de uma story da ferramenta de PM
+
+**Objetivo:** trazer para a story local em `docs/stories/` as mudanças feitas na ferramenta de
+gestão (ClickUp / GitHub Issues / Jira / local) — status, comentários, checklist de ACs —
+mantendo a fonte de verdade coesa sem perder edições locais.
+
+**Pré-condições:**
+- A story existe em `docs/stories/` e já foi sincronizada antes (há mapa de IDs em `.nexus/`). Se
+  nunca houve sync, **pare** e oriente rodar `po-sync-story` primeiro.
+- O provider de PM está configurado em `.nexus/`. Sem provider, **pare** e reporte.
+
+## Passos
+
+1. **Recupere o mapa de IDs** (story local ↔ ID externo) em `.nexus/` e identifique o provider alvo.
+2. **Busque o estado remoto** do item na ferramenta: status, ACs/checklist, comentários relevantes,
+   prioridade, atribuições.
+3. **Compare remoto × local.** Liste o que mudou de cada lado desde a última sincronização —
+   distinguindo o que veio do time (na ferramenta) do que foi editado localmente.
+4. **Aplique remoto→local sem destruir a autoridade de escopo.** Status, checklist de ACs e
+   comentários podem ser refletidos na story. Mas mudança de **AC, título ou escopo** vinda da
+   ferramenta **eu não aplico em silêncio** — sinalizo, porque autoria de escopo é do @pm/@sm, não
+   minha (e nem da ferramenta).
+5. **Sinalize conflitos.** Onde local e remoto divergem no mesmo campo, não sobrescrevo cegamente;
+   apresento o conflito e a decisão fica com o dono do campo.
+6. **Atualize a story** em `docs/stories/` com as mudanças seguras e registre no Change Log a data e
+   a origem do pull.
+7. **Roteie o que mudou de escopo.** Se a ferramenta trouxe novo AC/escopo, roteio ao `@sm` (story)
+   ou `@pm` (produto) para autoria formal — e, se isso conflita com PRD/epic, escalo correção de
+   curso ao `@nexus-master`. Eu reflito metadados; não reescrevo escopo.
+
+## Critério de pronto (DoD)
+
+- [ ] Mapa de IDs recuperado e provider identificado
+- [ ] Estado remoto buscado (status, ACs, comentários, prioridade)
+- [ ] Diff remoto × local computado e apresentado
+- [ ] Mudanças seguras (status, checklist, comentários) refletidas na story
+- [ ] Mudanças de AC/título/escopo NÃO aplicadas em silêncio — sinalizadas e roteadas
+- [ ] Conflitos de campo sinalizados, não sobrescritos
+- [ ] Change Log da story atualizado com data e origem do pull
+
+## Falha / recuperação
+
+- **Sem mapa de IDs / story nunca sincronizada** → paro e oriento rodar `po-sync-story` antes.
+- **A ferramenta alterou AC/título/escopo** → não aplico por conta própria; sinalizo e roteio ao
+  @sm/@pm. Meu poder é GO/NO-GO e reflexo de metadados, não edição de escopo.
+- **Conflito remoto × local no mesmo campo** → sinalizo e deixo a decisão com o dono; não
+  sobrescrevo cegamente.
+- **Divergência cria conflito com PRD/epic** → escalo correção de curso ao @nexus-master, em voz
+  alta, sem resolver em silêncio.
+- **Falha de autenticação / provider** → reporto com contexto; credenciais e MCP são do @devops.