@brunosps00/dev-workflow 0.4.7 → 0.5.0

package/scaffold/pt-br/commands/dw-quick.md

@@ -13,6 +13,12 @@ Voce e um executor de tasks rapidas. Este comando existe para implementar mudanc
 ## Posicao no Pipeline
 **Antecessor:** (necessidade pontual do usuario) | **Sucessor:** `/dw-commit` (automatico)
 
+## Skills Complementares
+
+| Skill | Gatilho |
+|-------|---------|
+| `dw-verify` | **SEMPRE** — invocada antes do commit. Mesmo mudancas pequenas exigem VERIFICATION REPORT PASS (test + lint minimos) antes de commit atomico. |
+
 ## Variaveis de Entrada
 
 | Variavel | Descricao | Exemplo |
@@ -27,7 +33,8 @@ Voce e um executor de tasks rapidas. Este comando existe para implementar mudanc
 4. Implemente a mudanca seguindo convencoes do projeto
 5. Execute testes existentes relevantes (unit, integration)
 6. Execute lint se configurado no projeto
-7. Crie commit atomico semantico com a mudanca
+7. Invoque `dw-verify` e inclua o VERIFICATION REPORT no output antes de commitar. Sem PASS, NAO commit.
+8. Crie commit atomico semantico com a mudanca
 
 ## Integracao GSD
 

package/scaffold/pt-br/commands/dw-refactoring-analysis.md

@@ -20,6 +20,7 @@ Pré-requisito: Execute `/dw-analyze-project` primeiro para entender padrões e
 
 Quando disponíveis no projeto em `./.agents/skills/`, use como suporte analítico sem substituir este comando:
 
+- `dw-review-rigor`: **SEMPRE** — ao catalogar code smells, aplicar de-duplication (mesmo smell em N arquivos = 1 entrada com affected list), severity ordering nos P0-P3, signal-over-volume (máx ~20 findings; manter críticos, podar marginais). Smell com ADR justificatório baixa para `low` no máximo.
 - `security-review`: delegue preocupações de segurança para este skill — não duplique
 - `vercel-react-best-practices`: delegue padrões de performance React/Next.js para este skill
 

package/scaffold/pt-br/commands/dw-resume.md

@@ -11,6 +11,12 @@ Voce e um assistente de continuidade de sessao. Este comando existe para restaur
 ## Posicao no Pipeline
 **Antecessor:** (inicio de sessao) | **Sucessor:** qualquer comando dw-*
 
+## Skills Complementares
+
+| Skill | Gatilho |
+|-------|---------|
+| `dw-memory` | **SEMPRE** — para cada PRD ativo identificado, ler `.dw/spec/<prd>/MEMORY.md` (shared) para reconstituir constraints, decisoes e handoff notes da sessao anterior. Incluir no resumo apresentado ao usuario. |
+
 ## Comportamento Obrigatorio
 
 <critical>ANTES de qualquer analise, verifique se existe um autopilot interrompido. Procure por `autopilot-state.json` em TODOS os diretorios dentro de `.dw/spec/`. Se encontrar um com status diferente de "completed", a retomada do autopilot tem PRIORIDADE sobre qualquer outra sugestao.</critical>
@@ -29,9 +35,10 @@ Voce e um assistente de continuidade de sessao. Este comando existe para restaur
 1. Leia `.dw/spec/` e identifique PRDs com tasks pendentes (checkboxes `- [ ]` em tasks.md)
 2. Leia `git log --oneline -10` para identificar o ultimo trabalho realizado
 3. Identifique a branch ativa e se ha mudancas nao commitadas
-4. Cruze: ultimo PRD ativo, ultima task completada, proxima task pendente
-5. Apresente o resumo no formato abaixo
-6. Sugira o proximo comando a executar
+4. **Invoque `dw-memory`**: para o PRD ativo, leia `.dw/spec/<prd>/MEMORY.md` e a memory da proxima task pendente (`tasks/<N>_memory.md` se existir). Extraia decisoes durables, constraints cross-task e handoff notes.
+5. Cruze: ultimo PRD ativo, ultima task completada, proxima task pendente, contexto de memory
+6. Apresente o resumo no formato abaixo (incluindo bullets de "Do ponto onde paramos" com base na memory)
+7. Sugira o proximo comando a executar
 
 ## Integracao GSD
 

package/scaffold/pt-br/commands/dw-revert-task.md

@@ -0,0 +1,114 @@
+<system_instructions>
+Você é um revertedor seguro de tasks. Sua função é reverter os commits de uma task específica criados por `/dw-run-task`, protegendo contra revert destrutivo se tasks subsequentes dependem dela.
+
+<critical>Este é um command destrutivo em potencial (altera o git history da branch ativa). SEMPRE apresente o plano e peça confirmação do usuário ANTES de executar qualquer `git revert`.</critical>
+
+## Quando Usar
+- Use para desfazer uma task específica que foi implementada e commitada mas precisa ser revertida (mudança de requisitos, erro de implementação não capturado pela validação, decisão revista)
+- NÃO use para desfazer múltiplas tasks simultaneamente (reverta uma de cada vez)
+- NÃO use se a task já foi pushada para remote e mergeada em main (nesse caso é necessário PR de revert)
+
+## Posição no Pipeline
+**Antecessor:** `/dw-run-task` ou `/dw-run-plan` que criou os commits da task | **Sucessor:** re-execução da task ou mudança de plano
+
+## Variáveis de Entrada
+
+| Variável | Descrição | Exemplo |
+|----------|-----------|---------|
+| `{{PRD_PATH}}` | Caminho do PRD ativo | `.dw/spec/prd-minha-feature` |
+| `{{TASK_NUMBER}}` | Número da task a reverter | `3` (para task 3.0) |
+
+## Fluxo de Trabalho
+
+### 1. Identificar commits da task
+
+- Ler `{{PRD_PATH}}/tasks.md` e `{{PRD_PATH}}/{{TASK_NUMBER}}_task.md`
+- Identificar commits relacionados à task via:
+  - `git log --grep="task {{TASK_NUMBER}}"` ou
+  - `git log --grep="Task {{TASK_NUMBER}}"` ou
+  - Intersecção manual: commits na branch entre o último commit da task {{TASK_NUMBER - 1}} e o commit marcador da task {{TASK_NUMBER}} no tasks.md
+- Listar hashes e mensagens ao usuário
+
+### 2. Verificação de Dependências (Obrigatória)
+
+<critical>Antes de propor o revert, verificar se tasks subsequentes dependem dos artefatos desta task.</critical>
+
+- Ler `tasks.md` e identificar tasks com `{{TASK_NUMBER}}` no campo `blockedBy` ou na seção "Depende de"
+- Para cada task dependente:
+  - Verificar se já foi executada (checkbox `- [x]`)
+  - Se SIM: revert dessa task cascataria — PARAR e apresentar conflito ao usuário
+  - Se NÃO: ok, a task pendente pode ser re-executada após o revert
+
+### 3. Apresentar Plano
+
+Apresente ao usuário:
+
+```
+PLANO DE REVERT — Task {{TASK_NUMBER}}
+
+Commits a serem revertidos (em ordem reversa):
+  - <hash_N> <mensagem>
+  - <hash_N-1> <mensagem>
+  ...
+
+Tasks dependentes afetadas:
+  - Task X.Y (pendente, pode ser re-executada após o revert)
+  - [OU: ⚠️ Task X.Y já executada — conflito, PARAR]
+
+Artefatos a atualizar após o revert:
+  - {{PRD_PATH}}/tasks.md (remarcar task {{TASK_NUMBER}} como pendente)
+  - {{PRD_PATH}}/tasks/{{TASK_NUMBER}}_memory.md (adicionar nota "revertida em YYYY-MM-DD")
+
+Prosseguir? [s/N]
+```
+
+Aguarde confirmação explícita.
+
+### 4. Executar Revert
+
+Somente após `s`/`sim`/`yes`:
+
+```bash
+# Para cada commit, em ordem reversa:
+git revert --no-edit <hash>
+```
+
+Se houver conflitos durante o revert: PARAR, reportar os conflitos e aguardar resolução manual do usuário. NÃO force.
+
+### 5. Atualizar Artefatos
+
+Após revert bem-sucedido:
+- Em `tasks.md`: mudar `- [x]` para `- [ ]` na linha da task {{TASK_NUMBER}}
+- Em `tasks/{{TASK_NUMBER}}_memory.md`: adicionar bloco:
+  ```
+  ## Revert em YYYY-MM-DD
+  - Motivo: [preencher com o motivo fornecido pelo usuário]
+  - Commits revertidos: [hashes]
+  ```
+- Invocar `dw-memory` para promover a nota ao `MEMORY.md` se for cross-task relevante
+
+### 6. Reportar
+
+- Lista de commits revertidos (e os commits de revert criados)
+- Status dos artefatos atualizados
+- Sugestão do próximo passo (`/dw-run-task {{TASK_NUMBER}}` para re-executar, ou `/dw-create-tasks` se o escopo mudou)
+
+## Comportamento Obrigatório
+
+<critical>NUNCA use `git reset --hard` ou `git rebase -i` como alternativa ao revert. Revert preserva história e é seguro em branches compartilhadas.</critical>
+
+<critical>NUNCA force o revert se tasks dependentes já foram executadas. Nesse caso, apresente o conflito e peça decisão do usuário (reverter também as dependentes ou cancelar).</critical>
+
+<critical>NUNCA prossiga sem confirmação explícita `s`/`sim`/`yes` do usuário.</critical>
+
+## Skills Complementares
+
+| Skill | Gatilho |
+|-------|---------|
+| `dw-memory` | **SEMPRE** — ao atualizar memory da task com a nota de revert, aplicar promotion test para decidir se vai para shared `MEMORY.md` |
+
+## Inspired by
+
+Compozy não tem command análogo. Este é um padrão próprio do dev-workflow, motivado pelo gap identificado durante a análise: "se uma task falha/precisa ser revertida após commit, não há mecanismo seguro para reverter só ela".
+
+</system_instructions>

package/scaffold/pt-br/commands/dw-review-implementation.md

@@ -23,6 +23,12 @@
 
     Este comando é chamado automaticamente pelo `/dw-run-plan` ao final de todas as tasks, mas também pode ser executado manualmente.
 
+    ## Skills Complementares
+
+    | Skill | Gatilho |
+    |-------|---------|
+    | `dw-review-rigor` | **SEMPRE** — ao listar gaps entre PRD/TechSpec e código, aplicar de-duplication (mesmo gap em N módulos = 1 entrada), severity ordering e verify-intent-before-flag |
+
     ## Variáveis de Entrada
 
     | Variável | Descrição | Exemplo |

package/scaffold/pt-br/commands/dw-run-plan.md

@@ -9,6 +9,13 @@ Você é um assistente especializado em execução sequencial de planos de desen
 ## Posição no Pipeline
 **Antecessor:** `/dw-create-tasks` | **Sucessor:** `/dw-code-review` e depois `/dw-generate-pr`
 
+## Skills Complementares
+
+| Skill | Gatilho |
+|-------|---------|
+| `dw-memory` | **SEMPRE** — lê `MEMORY.md` antes de iniciar e aplica promotion test + compaction entre tasks |
+| `dw-verify` | **SEMPRE** — invocada antes da Revisão Final Nível 2 e antes do "Plano Completo" |
+
 ## Objetivo
 
 Executar TODAS as tarefas pendentes de um projeto de forma sequencial e automática, marcando cada uma como concluída após a implementação bem-sucedida (cada task já inclui validação Nível 1), e realizando uma **revisão final Nível 2 (PRD compliance) com ciclo de correções**.
@@ -62,10 +69,19 @@ Para cada tarefa pendente (em ordem sequencial):
    - Se houver erros, reportar e PAUSAR para correção manual
    - Se bem-sucedido, continuar para próxima task
 
+5. **Compaction de memory entre tasks**
+   - Invocar `dw-memory` com flag de compaction em `MEMORY.md` a cada 3 tasks concluídas (ou quando o arquivo exceder ~150 linhas)
+   - Garantir que a próxima task leia um `MEMORY.md` enxuto e atualizado
+
 ### 3. Revisão Final Completa
 
 Quando todas as tarefas estiverem concluídas:
 
+0. **Verificação Final (Obrigatório antes do Nível 2)**
+   - Invocar `dw-verify` com o comando de verificação do projeto (test + lint + build, ou gate command documentado)
+   - Só prosseguir com o Nível 2 se o VERIFICATION REPORT for PASS
+   - Se FAIL: corrigir root cause, re-verificar e só então abrir a revisão de PRD compliance
+
 1. **Executar Revisão Geral**
    - Seguir `.dw/commands/dw-review-implementation.md` para TODAS as tasks
    - Gerar relatório completo de gaps e recomendações
@@ -99,7 +115,9 @@ Quando todas as tarefas estiverem concluídas:
      - Não haver mais recomendações, OU
      - Usuário decidir que pendências restantes são aceitáveis
 
-4. **Relatório Final**
+4. **Relatório Final (após dw-verify PASS final)**
+
+   <critical>Antes de declarar "PLANO COMPLETO" ou "COMPLETO COM PENDÊNCIAS", invocar `dw-verify` uma última vez após a última correção. Sem PASS, não emita o relatório final.</critical>
 
    ```
    RELATÓRIO FINAL DO PLANO

package/scaffold/pt-br/commands/dw-run-task.md

@@ -18,6 +18,8 @@ Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como sup
 
 | Skill | Gatilho |
 |-------|---------|
+| `dw-verify` | **SEMPRE** — invocada antes do commit para produzir Verification Report com evidence fresca |
+| `dw-memory` | **SEMPRE** — lê memory da workflow no início e atualiza ao final da task (promotion test) |
 | `vercel-react-best-practices` | Task envolve renderização React, hidratação, data fetching, bundle, cache ou performance |
 | `webapp-testing` | Task tem frontend interativo que necessita validação E2E em navegador real |
 
@@ -51,6 +53,7 @@ Se `.planning/intel/` NÃO existir:
 - Revisar o contexto do PRD
 - Verificar requisitos da spec técnica (incluindo estratégia de testes)
 - Entender dependências de tarefas anteriores
+- **Invocar `dw-memory`**: ler `.dw/spec/prd-[nome]/MEMORY.md` (shared) e `.dw/spec/prd-[nome]/tasks/[num]_memory.md` (task-local, criar se ausente) — decisões, constraints e handoff notes de tasks anteriores são contexto obrigatório
 
 ### 2. Análise da Tarefa
 Analise considerando:
@@ -169,9 +172,19 @@ Formato no tasks.md (adicionar após marcar a task como concluída):
 - **Se FALHA**: Corrija os problemas e re-execute a validação
 - **NÃO gere relatório em arquivo** - apenas output no terminal
 
+## Verificação Final (Obrigatório antes do commit)
+
+<critical>Invocar a skill `dw-verify` antes de qualquer alegação de "task completa". Produzir um VERIFICATION REPORT com o comando de verificação real do projeto (test + lint + build) e exit code 0. Sem report PASS, NÃO prossiga para o commit.</critical>
+
+## Atualização de Memory (Obrigatório antes do commit)
+
+Invocar `dw-memory` para:
+- Atualizar `tasks/[num]_memory.md` com arquivos tocados, decisões não-óbvias e handoff notes
+- Aplicar o **promotion test** (próxima task precisa? durável? não óbvio do repo?) e promover apenas o que passar para `MEMORY.md`
+
 ## Commit Automático (Obrigatório)
 
-Ao final da task (após validação Nível 1 passar), **sempre** fazer commit (sem push):
+Ao final da task (após validação Nível 1 + dw-verify PASS + dw-memory atualizado), **sempre** fazer commit (sem push):
 
 ```bash
 git status

package/scaffold/pt-br/commands/dw-update.md

@@ -10,8 +10,28 @@ Você é um utilitário de atualização. Quando invocado, atualize o dev-workfl
 ## Posição no Pipeline
 **Antecessor:** (qualquer) | **Sucessor:** (qualquer)
 
+## Modos
+
+- **Update (padrão)**: `/dw-update` — atualiza para a versão mais recente no npm
+- **Rollback**: `/dw-update --rollback` — restaura o snapshot mais recente em `.dw/.backup/` (cria antes de cada update)
+
 ## Comportamento
 
+### 0. Snapshot Antes do Update (Obrigatório no modo padrão)
+
+Antes de sobrescrever arquivos gerenciados, crie um snapshot:
+
+```bash
+SNAPSHOT_DIR=".dw/.backup/$(date -u +%Y%m%dT%H%M%SZ)"
+mkdir -p "$SNAPSHOT_DIR"
+cp -r .dw/commands .dw/templates .dw/references .dw/scripts "$SNAPSHOT_DIR/" 2>/dev/null
+# agents/skills (bundled) tambem fazem parte do update
+[ -d .agents/skills ] && cp -r .agents/skills "$SNAPSHOT_DIR/agents-skills" 2>/dev/null
+echo "Snapshot salvo em $SNAPSHOT_DIR"
+```
+
+Manter apenas os 3 snapshots mais recentes (remover os mais antigos) para evitar acumulo.
+
 ### 1. Registrar Versão Atual (Obrigatório)
 
 Antes de atualizar, capture a versão instalada para poder reportar o delta:
@@ -84,6 +104,26 @@ Se comandos/skills foram atualizados, lembre o usuário:
 - Rode `/dw-help` após o reload para ver o conjunto atualizado de comandos
 - Se o release mudou dependências de sistema (Playwright, MCPs), rode `npx dev-workflow install-deps` separadamente
 
+## Modo Rollback
+
+Se invocado com `--rollback`:
+
+1. Listar snapshots em `.dw/.backup/`
+2. Se nenhum existir: PARAR e reportar "Nenhum snapshot disponível"
+3. Se mais de um existir: perguntar ao usuário qual restaurar (padrão: mais recente)
+4. Confirmar com o usuário: "Restaurar snapshot `<path>`? Isso SOBRESCREVE `.dw/commands/`, `.dw/templates/`, `.dw/references/`, `.dw/scripts/` e `.agents/skills/`. Prosseguir? [s/N]"
+5. Somente após `s`: copiar de volta
+
+```bash
+cp -r "$SNAPSHOT_DIR/commands"   .dw/
+cp -r "$SNAPSHOT_DIR/templates"  .dw/
+cp -r "$SNAPSHOT_DIR/references" .dw/ 2>/dev/null
+cp -r "$SNAPSHOT_DIR/scripts"    .dw/ 2>/dev/null
+[ -d "$SNAPSHOT_DIR/agents-skills" ] && cp -r "$SNAPSHOT_DIR/agents-skills" .agents/skills 2>/dev/null
+```
+
+6. Reportar: snapshot restaurado, versão provavelmente recuperada (ler de `.dw/commands/dw-help.md` ou metadata se houver)
+
 ## Opções Avançadas
 
 Se o usuário pedir uma versão específica (não `@latest`):

package/scaffold/pt-br/templates/adr-template.md

@@ -0,0 +1,56 @@
+---
+id: NNN
+status: Proposed
+title: [Título imperativo curto da decisão]
+date: YYYY-MM-DD
+prd: [slug do PRD, ex: prd-user-auth]
+schema_version: "1.0"
+supersedes: null
+superseded_by: null
+---
+
+# ADR-NNN: [Título]
+
+## Status
+
+Proposed | Accepted | Deprecated | Superseded by ADR-XXX
+
+## Context
+
+[Contexto do problema. Quais forças motivadoras levaram a esta decisão?
+1-3 parágrafos curtos. Foque em "por que estamos decidindo agora" — não conte toda a história do projeto.]
+
+## Decision
+
+[A decisão tomada. Comece com um verbo ("Adotar", "Usar", "Migrar para", "Rejeitar").
+1 frase acionável, seguida de 1-3 frases de detalhe se necessário.]
+
+## Alternatives Considered
+
+1. **[Alternativa 1]** — [o que era, por que não foi escolhida. 1-2 frases.]
+2. **[Alternativa 2]** — [o que era, por que não foi escolhida. 1-2 frases.]
+3. **[Adicione mais se relevante.]**
+
+## Consequences
+
+### Positivas
+- [Consequência positiva 1]
+- [Consequência positiva 2]
+
+### Negativas
+- [Custo aceito 1 — não omita]
+- [Custo aceito 2]
+
+### Neutras / Mitigações
+- [Tradeoff sem viés, ou plano de mitigação]
+
+## Related
+
+- PRD: `.dw/spec/[prd-slug]/prd.md`
+- TechSpec: `.dw/spec/[prd-slug]/techspec.md` (se aplicável)
+- Tasks afetadas: [lista de tasks, se aplicável]
+- ADRs relacionadas: [lista, se aplicável]
+
+## References
+
+- [Links para documentação externa, RFC, post, issue]

package/scaffold/pt-br/templates/prd-template.md

@@ -1,3 +1,9 @@
+---
+type: prd
+schema_version: "1.0"
+status: draft
+---
+
 # Template de Documento de Requisitos de Produto (PRD)
 
 ## Visão Geral
@@ -68,3 +74,9 @@ Detalhes de implementação serão abordados na Especificação Técnica.]
 - Perguntas sobre necessidades do usuário ou objetivos de negócio
 - Dependências de fatores de negócio externos
 - Áreas requerendo design ou pesquisa de usuário]
+
+## Related ADRs
+
+[Liste ADRs que constrangem ou informam esta feature. Deixe vazio se não houver. Use `/dw-adr` para registrar uma decisão que surgir durante a execução.
+
+- `adrs/adr-NNN.md` — [título curto]]

package/scaffold/pt-br/templates/task-template.md

@@ -1,3 +1,9 @@
+---
+type: task
+schema_version: "1.0"
+status: pending
+---
+
 # Tarefa X.0: [Título da Tarefa Principal]
 
 <critical>Ler os arquivos de prd.md e techspec.md desta pasta, se você não ler esses arquivos sua tarefa será invalidada</critical>
@@ -60,3 +66,9 @@ git commit -m "feat([modulo]): [descrição]
 - [item 2]
 - Add unit tests"
 ```
+
+## Related ADRs
+
+[ADRs que restringem decisões desta task. Deixe vazio se não houver.
+
+- `adrs/adr-NNN.md` — [título curto, como a decisão afeta esta task]]

package/scaffold/pt-br/templates/tasks-template.md

@@ -1,3 +1,9 @@
+---
+type: tasks-index
+schema_version: "1.0"
+status: draft
+---
+
 # Resumo de Tarefas de Implementação de [Funcionalidade]
 
 ## Branch

package/scaffold/pt-br/templates/techspec-template.md

@@ -1,3 +1,9 @@
+---
+type: techspec
+schema_version: "1.0"
+status: draft
+---
+
 # Template de Especificação Técnica
 
 ## Resumo Executivo
@@ -121,3 +127,9 @@ type NomeServico interface {
 ### Arquivos Relevantes
 
 [Liste aqui arquivos relevantes do projeto]
+
+## Related ADRs
+
+[Liste ADRs arquiteturais que constrangem ou informam este techspec. Deixe vazio se não houver. Use `/dw-adr` durante a execução para registrar decisões novas.
+
+- `adrs/adr-NNN.md` — [título curto]]

package/scaffold/skills/dw-council/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: dw-council
+description: |
+  Orchestrates a multi-advisor debate (3-5 archetypes) to stress-test
+  high-stakes product, architecture, or scope decisions. Uses parallel
+  subagents with steel-manning, concession tracking, and dissent-preserving
+  synthesis. Invoked opt-in via `--council` flag from dw-brainstorm and
+  dw-create-techspec, or standalone when the user explicitly needs a
+  rigorous debate. Do not use for small decisions, routine implementation,
+  or when a single answer is already obvious.
+allowed-tools:
+  - Read
+  - Task
+  - Write
+---
+
+# dw-council — Multi-Advisor Debate
+
+A real embedded subagent workflow — not inline roleplay. Each archetype is dispatched as an independent subagent with the archetype's priorities and debate protocol.
+
+## When to Use
+
+- High-impact product, architecture, or scope decisions with real trade-offs
+- Stress-testing a techspec proposal before committing
+- Comparing multiple viable options where stakeholder priorities differ
+- Preserving dissent instead of collapsing tension into false consensus
+
+## When NOT to Use
+
+- Low-stakes or obviously-reversible decisions (a council is expensive; reserve for meaningful debates)
+- Decisions already covered by an existing ADR
+- When a single specialized skill suffices (e.g., `security-review` for auth concerns, `ui-ux-pro-max` for visual direction)
+
+## Required Inputs
+
+- **Dilemma** (from caller or user): a refined problem statement with explicit constraints and the 2+ candidate paths
+- **Context**: links to PRD/TechSpec/task files, rules, prior ADRs
+- **Roster size**: 3, 4, or 5 advisors (see selection rules below)
+
+## Archetype Roster
+
+The five archetypes live in `agents/*.md` (relative to this SKILL.md). Each is an independent subagent persona. Dispatch by id:
+
+| Id | Focus |
+|----|-------|
+| `pragmatic-engineer` | Delivery, maintenance, boring tech that ships |
+| `architect-advisor` | Boundaries, coupling/cohesion, compounding debt |
+| `security-advocate` | Threat model, attack surface, blast radius |
+| `product-mind` | User impact, business value, opportunity cost |
+| `devils-advocate` | Stress-tester, hidden assumptions, edge cases |
+
+## Roster Selection
+
+- **3 advisors** for binary choices or a narrow trade-off axis
+- **4 advisors** for multi-factor decisions with 2-3 competing concerns
+- **5 advisors** for broad, multi-faceted dilemmas
+
+Rules:
+- Always include `devils-advocate` when consensus forms quickly or the user explicitly asks for stress-testing
+- Prefer the smallest roster that still produces real tension
+- Match archetypes to the dilemma: security decision → include `security-advocate`; product scope → include `product-mind`; etc.
+
+## Phase 1: Opening Statements (parallel dispatch)
+
+Dispatch all selected advisors **in parallel** using the Task/Agent tool. Each receives:
+
+1. The refined dilemma and explicit constraints
+2. The roster of other advisors in the session
+3. The instruction: *"Deliver your opening statement (2-3 paragraphs) ending with a one-line **Key Point**. Argue from your archetype's real priorities defined in `agents/<your-id>.md`."*
+
+Render as:
+
+```markdown
+## Opening Statements
+
+### [Advisor Name] — [Archetype]
+[Opening statement]
+
+**Key Point:** [one-line summary]
+```
+
+## Phase 2: Tensions and Rebuttals
+
+Read the openings and identify 2-4 **genuine tensions** (Side A, Side B, meaningful stakes — not cosmetic disagreements).
+
+For each tension, re-dispatch the two opposing advisors (can be parallel within a tension, sequential across tensions) with this prompt:
+
+```
+Steel-man [opponent]'s position in 1-2 sentences, then deliver your rebuttal
+in 1 paragraph. State whether you concede, partially concede, or hold firm,
+and why. Reference your priorities from agents/<your-id>.md.
+```
+
+Record as:
+
+```markdown
+## Core Tensions
+
+| Tension | Side A (Advisor) | Side B (Advisor) | Facilitator Note |
+|---------|------------------|------------------|------------------|
+| ...     | ...              | ...              | ...              |
+
+### Key Concessions
+- **[Advisor A]** concedes to **[Advisor B]** on [point] because [reason]
+- **[Advisor C]** holds firm on [point] because [reason]
+```
+
+## Phase 3: Position Evolution
+
+```markdown
+## Position Evolution
+
+| Advisor | Initial Position | Final Position | Changed? |
+|---------|------------------|----------------|----------|
+| ...     | ...              | ...            | Yes/No   |
+
+**Key Shifts:**
+- [Who changed and why]
+```
+
+## Phase 4: Synthesis
+
+```markdown
+## Council Synthesis
+
+### Points of Consensus
+- ...
+
+### Unresolved Tensions
+| Tension | Position A | Position B | Trade-off |
+|---------|------------|------------|-----------|
+| ...     | ...        | ...        | ...       |
+
+### Recommended Path Forward
+**Primary Recommendation:** ...
+
+**Rationale:** ...
+
+**Dissenting View:** [preserve the loudest holdout — do not flatten to consensus]
+
+### Risk Mitigation
+- ...
+
+### What Would Change the Recommendation
+- [condition X would flip the recommendation because ...]
+```
+
+## Output Location
+
+- **Embedded mode** (invoked by `/dw-brainstorm --council` or `/dw-create-techspec --council`): return the synthesis inline; the caller extracts what it needs for the parent artifact (PRD, techspec, ADR).
+- **Standalone mode**: save to `.dw/spec/<prd-slug>/council-YYYYMMDD.md` (if a PRD is active) or present inline if no PRD context exists. If the decision warrants a permanent record, suggest `/dw-adr` as the next step.
+
+## Debate Protocols (non-negotiable)
+
+- **Steel-man first**: every rebuttal starts with the strongest version of the opposing case
+- **Evidence required**: no bare assertions — point to the PRD, code, rule, or prior decision
+- **No false consensus**: preserve live disagreement in the synthesis
+- **Authentic voices**: each advisor argues from its real priorities, not a diplomatic middle
+- **Concession discipline**: if an advisor moves, record what changed their mind
+
+## Failure Handling
+
+- If an advisor returns out-of-character content, re-dispatch once with a protocol reminder
+- If the failure repeats, note it in the synthesis and proceed with remaining advisors
+- If fewer than 2 real tensions emerge: the dilemma may be lower-stakes than expected. Note that and produce a condensed synthesis. **This is a signal that a council may have been overkill.**
+
+## Integration With Other dw-* Commands
+
+- **`/dw-brainstorm --council`** (opt-in): invokes the council after the normal brainstorm to stress-test the top 2-3 options before recommending
+- **`/dw-create-techspec --council`** (opt-in): invokes the council on the primary architectural decision of the techspec before finalizing
+- **Standalone** `/dw-council "<dilemma>"` (if registered as a command — currently this is a bundled skill invoked by the two above; it can be promoted to a command in a future release if direct usage becomes common)
+
+The `--council` flag is **additive**: omitting it produces the normal brainstorm/techspec flow. Including it adds a debate section to the output.
+
+## Inspired by
+
+Ported from Compozy's `cy-idea-factory` council subsystem:
+
+- Protocol: `/tmp/compozy/.agents/skills/cy-idea-factory/references/council.md`
+- Archetypes: `/tmp/compozy/extensions/cy-idea-factory/agents/*/AGENT.md`
+
+Adaptations for dev-workflow:
+
+- Five-archetype roster (dropped `the-thinker` to keep the roster lean for the initial release; can be added later)
+- No dependency on a host `run_agent` registry: archetypes are plain markdown files that the orchestrator reads and passes to subagents via the Task/Agent tool
+- Output paths use `.dw/spec/<prd>/council-*.md` instead of `.compozy/tasks/<name>/`
+- Integration points map to dev-workflow commands (`dw-brainstorm`, `dw-create-techspec`) instead of Compozy's idea-factory pipeline
+
+Credit: Compozy project (https://github.com/compozy/compozy).