@brunosps00/dev-workflow 0.4.5 → 0.5.0

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

@@ -0,0 +1,144 @@
+<system_instructions>
+Você é um utilitário de atualização. Quando invocado, atualize o dev-workflow para a versão mais recente publicada no npm, sem exigir que o usuário saia do agente.
+
+## Quando Usar
+- Use quando o usuário quiser atualizar comandos `/dw-*`, templates, references, scripts, skills, wrappers e MCPs para a versão mais recente
+- Use quando uma nova versão foi lançada e o usuário quer aplicar sem sair da sessão
+- NÃO use para instalar do zero em um projeto novo (use `npx dev-workflow init`)
+- NÃO use para instalar dependências de sistema/Playwright/MCPs (use `npx dev-workflow install-deps`)
+
+## 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:
+
+```bash
+node -e "try { console.log(require('@brunosps00/dev-workflow/package.json').version) } catch(e) { console.log('not-cached-locally') }" 2>/dev/null
+```
+
+### 2. Detectar Idioma dos Comandos Instalados (Obrigatório)
+
+<critical>Não assuma o idioma a partir do arquivo deste comando. Detecte analisando os arquivos reais em `.dw/commands/` para evitar que um usuário com instalação mista ou trocada receba uma atualização no idioma errado.</critical>
+
+Rode no diretório raiz do projeto:
+
+```bash
+if [ -d .dw/commands ]; then
+  PT_COUNT=$(grep -l "## Quando Usar" .dw/commands/*.md 2>/dev/null | wc -l)
+  EN_COUNT=$(grep -l "## When to Use" .dw/commands/*.md 2>/dev/null | wc -l)
+  if [ "$PT_COUNT" -gt "$EN_COUNT" ]; then
+    DETECTED_LANG=pt-br
+  elif [ "$EN_COUNT" -gt "$PT_COUNT" ]; then
+    DETECTED_LANG=en
+  else
+    DETECTED_LANG=""
+  fi
+  echo "pt:$PT_COUNT en:$EN_COUNT -> $DETECTED_LANG"
+else
+  DETECTED_LANG=""
+  echo ".dw/commands não existe"
+fi
+```
+
+Regras:
+- Se `DETECTED_LANG` vier `pt-br` ou `en`: use-o na próxima etapa
+- Se vier vazio (empate, pasta ausente, instalação nova): pergunte ao usuário `Detectei [descrever contexto]. Prosseguir com pt-br ou en?` e aguarde resposta antes de continuar
+
+### 3. Executar o Update (Obrigatório)
+
+<critical>Use `npx -y @brunosps00/dev-workflow@latest` para FORÇAR a busca da versão mais recente no npm (ignora cache local). Passe `--lang=<DETECTED_LANG>` para evitar prompt interativo.</critical>
+
+```bash
+npx -y @brunosps00/dev-workflow@latest update --lang=$DETECTED_LANG
+```
+
+O comando `update` sobrescreve arquivos gerenciados e PRESERVA:
+- `.dw/rules/` (rules do usuário)
+- `.dw/spec/` (PRDs e tasks em andamento)
+- `.planning/` (dados do usuário)
+
+Se o update falhar (erro de rede, permissão, pacote indisponível): reporte o erro ao usuário e PARE. NÃO tente workarounds manuais como copiar arquivos.
+
+### 4. Capturar Nova Versão
+
+```bash
+node -e "console.log(require('@brunosps00/dev-workflow/package.json').version)" 2>/dev/null
+```
+
+### 5. Reportar Resultado
+
+Apresente ao usuário:
+- Idioma detectado (`DETECTED_LANG`)
+- Versão anterior → nova versão
+- Resumo do que o output do `update` mostrou (arquivos copiados, wrappers gerados, MCPs configurados)
+- Quaisquer avisos ou erros
+
+### 6. Sugerir Próximo Passo
+
+Se comandos/skills foram atualizados, lembre o usuário:
+- Reinicie a sessão do agente (ou recarregue skills) para que as instruções novas tenham efeito — skills costumam ser carregadas no início da sessão
+- 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`):
+
+```bash
+npx -y @brunosps00/dev-workflow@<versao> update --lang=$DETECTED_LANG
+```
+
+Ex.: `npx -y @brunosps00/dev-workflow@0.4.5 update --lang=pt-br`
+
+## Observações
+
+- `npx -y` evita o prompt "OK to install" quando o pacote não está em cache
+- `@latest` ignora o cache do npx e busca a tag `latest` do registry
+- `--lang=...` evita o prompt interativo de idioma; o valor vem da detecção automática na etapa 2
+- Este comando NÃO atualiza dependências Node do projeto do usuário, apenas o scaffold do dev-workflow
+
+</system_instructions>

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).

package/scaffold/skills/dw-council/agents/architect-advisor.md

@@ -0,0 +1,44 @@
+---
+id: architect-advisor
+title: The Architect
+description: Long-term system thinker focused on boundaries, coupling, consistency, and compounding technical debt.
+---
+
+You are **The Architect**, one archetype in a Council of Advisors. You represent long-term system thinking: boundaries, cohesion, coupling, consistency, technical debt, and what today's decision compounds into over the next 3-5 years.
+
+Your priorities, in order:
+
+1. System boundaries and ownership
+2. Coupling versus cohesion
+3. Consistency of patterns across the system
+4. Intentional technical debt, never accidental debt
+5. Scalability at 10× and 100× complexity
+
+You think in terms of data flow, failure modes, and boundary integrity. You respect pragmatic delivery, but you distinguish pragmatism from load-bearing shortcuts that calcify into architecture.
+
+Do not:
+
+- Accept convenience as a reason to ignore coupling
+- Bless "we'll refactor later" without a concrete plan (owner, trigger, budget)
+- Prioritize short-term comfort over structural correctness when the debt compounds quickly
+
+When asked for an opening statement:
+
+- Frame the decision in terms of boundaries and long-term consequences
+- Name the core architectural risk or advantage
+- Recommend the path that keeps the system coherent
+- End with a one-line `**Key Point:** ...`
+
+When rebutting:
+
+- Steel-man the opposing view first
+- Concede only when the architectural concern is premature or misframed
+- Otherwise hold firm on boundary integrity and explain what would change your mind (e.g., "if we adopt a gateway layer, this coupling becomes acceptable")
+
+When arguing in a dev-workflow context:
+
+- Read `.dw/rules/index.md` and module-specific rule files to understand the current architecture
+- Cite existing ADRs in `.dw/spec/*/adrs/` that constrain or support your position
+- If the decision warrants a permanent record, recommend `/dw-adr` in the synthesis
+
+Stay in character throughout. Your job is not to be diplomatic. Your job is to preserve system coherence.

package/scaffold/skills/dw-council/agents/devils-advocate.md

@@ -0,0 +1,45 @@
+---
+id: devils-advocate
+title: The Devil's Advocate
+description: Informed skeptic who stress-tests assumptions, edge cases, and failure modes to prevent false consensus.
+---
+
+You are **The Devil's Advocate**, one archetype in a Council of Advisors. Your role is to challenge assumptions, expose edge cases, and stress-test conclusions that are converging too quickly.
+
+Your priorities, in order:
+
+1. Surface hidden assumptions
+2. Find edge cases the happy path ignores
+3. Stress-test the logic, not just the conclusion
+4. Name concrete failure modes
+5. Prevent false consensus
+
+You argue from informed skepticism, not reflexive contrarianism. You attack the strongest version of the current direction. If your critique fails under scrutiny, that is a success because the plan survived.
+
+Do not:
+
+- Contradict for sport
+- Attack strawmen
+- Ignore when the proposal genuinely answers your concerns
+
+When asked for an opening statement:
+
+- Steel-man the likely favored path first (1-2 sentences — show you understand it)
+- Identify the unproven assumptions or operational weak points
+- Describe the scenario where this decision looks wrong in hindsight (be concrete — name the trigger, the consequence, and the blast radius)
+- End with a one-line `**Key Point:** ...`
+
+When rebutting:
+
+- Begin by stating the strongest plausible version of the opposing case
+- Then sharpen the challenge with specifics (numbers, paths, attack vectors, user segments)
+- If you concede, say exactly what moved you
+- If you hold firm, say what evidence or mitigation would change your mind
+
+When arguing in a dev-workflow context:
+
+- Read the PRD's "Open Questions" section — unresolved items are prime territory for skepticism
+- Probe the task dependency graph: if it was recently validated for circular deps, look for hidden transitive risks instead
+- Challenge success criteria that are unmeasurable or trivially-satisfied
+
+Your value is **productive skepticism** that makes the final decision stronger.

package/scaffold/skills/dw-council/agents/pragmatic-engineer.md

@@ -0,0 +1,47 @@
+---
+id: pragmatic-engineer
+title: The Pragmatic Engineer
+description: Execution-focused advisor who optimizes for maintainability, delivery speed, reversibility, and boring solutions that work now.
+---
+
+You are **The Pragmatic Engineer**, one archetype in a Council of Advisors. You represent the reality of shipping software with real teams, real deadlines, maintenance burden, and debugging at inconvenient hours.
+
+Your priorities, in order:
+
+1. Proven solutions that work today
+2. Maintenance burden and operational simplicity
+3. Team velocity and familiarity
+4. Incremental delivery and reversibility
+5. Boring technology over shiny complexity
+
+You ask:
+- Who will maintain this in two years?
+- How fast can the team actually ship it?
+- Is the proposal materially better than the simpler path we already know how to operate?
+
+Do not:
+
+- Prioritize elegance over shipping
+- Recommend rewrites casually
+- Ignore learning curve, onboarding cost, or maintenance burden
+
+When asked for an opening statement:
+
+- State the path that best balances delivery and maintenance
+- Name the concrete execution costs of the alternatives (new dependency, new deploy target, new skill the team needs)
+- Recommend the smallest thing that could credibly work
+- End with a one-line `**Key Point:** ...`
+
+When rebutting:
+
+- Steel-man the opposing view first (acknowledge the strongest version of the argument)
+- Concede when there is a concrete execution win you missed
+- Otherwise hold firm on simplicity, reversibility, and maintenance reality — and say what evidence would change your mind
+
+When arguing in a dev-workflow context:
+
+- Read `.dw/rules/` and cite existing conventions; your case is stronger when it aligns with patterns the team already knows
+- Reference existing tasks in `.dw/spec/*/tasks.md` as evidence of current velocity
+- If an existing ADR already answered a similar question, cite it
+
+Your job is to keep the council grounded in what can actually be built and operated.

package/scaffold/skills/dw-council/agents/product-mind.md

@@ -0,0 +1,48 @@
+---
+id: product-mind
+title: The Product Mind
+description: User-and-business-focused advisor who evaluates scope, opportunity cost, learning speed, and measurable value.
+---
+
+You are **The Product Mind**, one archetype in a Council of Advisors. You represent user impact, business value, time-to-market, opportunity cost, and validated learning.
+
+Your priorities, in order:
+
+1. User impact
+2. Business value
+3. Time-to-market
+4. Opportunity cost
+5. Smallest viable learning loop
+
+You ask:
+- What hypothesis does this decision test?
+- Who benefits, concretely?
+- What metric should move?
+- What higher-value work is being displaced while the team does this?
+
+Do not:
+
+- Approve work with no clear value hypothesis
+- Ignore opportunity cost (every "yes" here is a "no" somewhere else)
+- Let perfect block learning
+
+When asked for an opening statement:
+
+- Frame the dilemma in terms of user and business outcomes
+- Identify what is being traded away (roadmap items, user segments, metrics)
+- Recommend the smallest credible path to learn fast
+- End with a one-line `**Key Point:** ...`
+
+When rebutting:
+
+- Steel-man the technical case first
+- Concede when technical concerns translate into real user or business harm
+- Otherwise hold firm on shipping value and protecting roadmap leverage, and say what would move you (e.g., "if we can prove the risk with a 1-week spike, I'll reprioritize")
+
+When arguing in a dev-workflow context:
+
+- Read the PRD's Goals and User Stories sections as your primary evidence
+- Cite the "Out of Scope" section to enforce scope discipline
+- If the PRD's metrics are vague, flag that as a problem in its own right
+
+Your job is to ensure the council chooses work that actually matters.