@brunosps00/dev-workflow 0.4.5 → 0.5.0

package/scaffold/en/commands/dw-resume.md

@@ -11,6 +11,12 @@ You are a session continuity assistant. This command exists to restore context f
 ## Pipeline Position
 **Predecessor:** (session start) | **Successor:** any dw-* command
 
+## Complementary Skills
+
+| Skill | Trigger |
+|-------|---------|
+| `dw-memory` | **ALWAYS** — for each active PRD identified, read `.dw/spec/<prd>/MEMORY.md` (shared) to reconstitute constraints, decisions, and handoff notes from the prior session. Include in the summary presented to the user. |
+
 ## Required Behavior
 
 <critical>BEFORE any analysis, check for an interrupted autopilot. Look for `autopilot-state.json` in ALL directories inside `.dw/spec/`. If you find one without `"status": "completed"`, autopilot resumption takes PRIORITY over any other suggestion.</critical>
@@ -29,9 +35,10 @@ You are a session continuity assistant. This command exists to restore context f
 1. Read `.dw/spec/` and identify PRDs with pending tasks (`- [ ]` checkboxes in tasks.md)
 2. Read `git log --oneline -10` to identify the last work performed
 3. Identify the active branch and whether there are uncommitted changes
-4. Cross-reference: last active PRD, last completed task, next pending task
-5. Present the summary in the format below
-6. Suggest the next command to execute
+4. **Invoke `dw-memory`**: for the active PRD, read `.dw/spec/<prd>/MEMORY.md` and the next pending task's memory (`tasks/<N>_memory.md` if present). Extract durable decisions, cross-task constraints, and handoff notes.
+5. Cross-reference: last active PRD, last completed task, next pending task, memory context
+6. Present the summary in the format below (including a "From where we left off" bullet list based on memory)
+7. Suggest the next command to execute
 
 ## GSD Integration
 

package/scaffold/en/commands/dw-revert-task.md

@@ -0,0 +1,114 @@
+<system_instructions>
+You are a safe task reverter. Your job is to revert the commits of a specific task created by `/dw-run-task`, protecting against destructive revert if subsequent tasks depend on it.
+
+<critical>This command is potentially destructive (it alters git history on the active branch). ALWAYS present the plan and ask for user confirmation BEFORE executing any `git revert`.</critical>
+
+## When to Use
+- Use to undo a specific task that was implemented and committed but needs to be reverted (requirement change, implementation error not caught by validation, decision reversed)
+- Do NOT use to undo multiple tasks at once (revert one at a time)
+- Do NOT use if the task has already been pushed to remote and merged into main (then a revert PR is required)
+
+## Pipeline Position
+**Predecessor:** `/dw-run-task` or `/dw-run-plan` that created the task commits | **Successor:** re-run the task or change the plan
+
+## Input Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{{PRD_PATH}}` | Active PRD path | `.dw/spec/prd-my-feature` |
+| `{{TASK_NUMBER}}` | Task number to revert | `3` (for task 3.0) |
+
+## Workflow
+
+### 1. Identify task commits
+
+- Read `{{PRD_PATH}}/tasks.md` and `{{PRD_PATH}}/{{TASK_NUMBER}}_task.md`
+- Identify commits related to the task via:
+  - `git log --grep="task {{TASK_NUMBER}}"` or
+  - `git log --grep="Task {{TASK_NUMBER}}"` or
+  - Manual intersection: commits on the branch between the last commit of task {{TASK_NUMBER - 1}} and the marker commit of task {{TASK_NUMBER}} in tasks.md
+- List hashes and messages to the user
+
+### 2. Dependency Check (Required)
+
+<critical>Before proposing the revert, check whether subsequent tasks depend on this task's artifacts.</critical>
+
+- Read `tasks.md` and identify tasks with `{{TASK_NUMBER}}` in their `blockedBy` field or "Depends on" section
+- For each dependent task:
+  - Check whether it has been executed (`- [x]` checkbox)
+  - If YES: reverting this task would cascade — STOP and present the conflict to the user
+  - If NO: OK, the pending task can be re-executed after the revert
+
+### 3. Present Plan
+
+Show the user:
+
+```
+REVERT PLAN — Task {{TASK_NUMBER}}
+
+Commits to revert (in reverse order):
+  - <hash_N> <message>
+  - <hash_N-1> <message>
+  ...
+
+Affected dependent tasks:
+  - Task X.Y (pending, can be re-executed after revert)
+  - [OR: ⚠️ Task X.Y already executed — conflict, STOP]
+
+Artifacts to update after revert:
+  - {{PRD_PATH}}/tasks.md (re-mark task {{TASK_NUMBER}} as pending)
+  - {{PRD_PATH}}/tasks/{{TASK_NUMBER}}_memory.md (add "reverted on YYYY-MM-DD" note)
+
+Proceed? [y/N]
+```
+
+Wait for explicit confirmation.
+
+### 4. Execute Revert
+
+Only after `y`/`yes`:
+
+```bash
+# For each commit, in reverse order:
+git revert --no-edit <hash>
+```
+
+If conflicts occur during revert: STOP, report conflicts, and wait for the user to resolve manually. DO NOT force.
+
+### 5. Update Artifacts
+
+After a successful revert:
+- In `tasks.md`: change `- [x]` to `- [ ]` on task {{TASK_NUMBER}}'s line
+- In `tasks/{{TASK_NUMBER}}_memory.md`: append:
+  ```
+  ## Revert on YYYY-MM-DD
+  - Reason: [fill with the user-provided reason]
+  - Reverted commits: [hashes]
+  ```
+- Invoke `dw-memory` to promote the note to `MEMORY.md` if it's cross-task relevant
+
+### 6. Report
+
+- List of reverted commits (and the revert commits created)
+- Status of updated artifacts
+- Suggested next step (`/dw-run-task {{TASK_NUMBER}}` to re-run, or `/dw-create-tasks` if scope changed)
+
+## Required Behavior
+
+<critical>NEVER use `git reset --hard` or `git rebase -i` as an alternative to revert. Revert preserves history and is safe on shared branches.</critical>
+
+<critical>NEVER force the revert if dependent tasks have already been executed. In that case, present the conflict and ask for user decision (also revert dependents, or cancel).</critical>
+
+<critical>NEVER proceed without explicit `y`/`yes` confirmation from the user.</critical>
+
+## Complementary Skills
+
+| Skill | Trigger |
+|-------|---------|
+| `dw-memory` | **ALWAYS** — when updating the task memory with the revert note, apply the promotion test to decide whether it goes into shared `MEMORY.md` |
+
+## Inspired by
+
+Compozy has no analogous command. This is a dev-workflow-native pattern, motivated by a gap identified during analysis: "if a task fails or needs to be reverted after commit, there is no safe mechanism to revert only that task."
+
+</system_instructions>

package/scaffold/en/commands/dw-review-implementation.md

@@ -23,6 +23,12 @@ This is **Review Level 2**:
 
 This command is called automatically by `/dw-run-plan` at the end of all tasks, but can also be executed manually.
 
+## Complementary Skills
+
+| Skill | Trigger |
+|-------|---------|
+| `dw-review-rigor` | **ALWAYS** — when listing gaps between PRD/TechSpec and code, apply de-duplication (same gap in N modules = 1 entry), severity ordering, and verify-intent-before-flag |
+
 ## Input Variables
 
 | Variable | Description | Example |

package/scaffold/en/commands/dw-run-plan.md

@@ -9,6 +9,13 @@ You are an assistant specialized in sequential execution of development plans. Y
 ## Pipeline Position
 **Predecessor:** `/dw-create-tasks` | **Successor:** `/dw-code-review` then `/dw-generate-pr`
 
+## Complementary Skills
+
+| Skill | Trigger |
+|-------|---------|
+| `dw-memory` | **ALWAYS** — reads `MEMORY.md` before starting and applies promotion test + compaction between tasks |
+| `dw-verify` | **ALWAYS** — invoked before the Level 2 Final Review and before declaring "Plan Complete" |
+
 ## Objective
 
 Execute ALL pending tasks in a project sequentially and automatically, marking each as completed after successful implementation (each task already includes Level 1 validation), and performing a **final Level 2 review (PRD compliance) with a corrections cycle**.
@@ -62,10 +69,19 @@ For each pending task (in sequential order):
    - If there are errors, report and PAUSE for manual correction
    - If successful, continue to next task
 
+5. **Memory compaction between tasks**
+   - Invoke `dw-memory` with compaction flag on `MEMORY.md` every 3 completed tasks (or when the file exceeds ~150 lines)
+   - Ensure the next task reads a lean, up-to-date `MEMORY.md`
+
 ### 3. Final Comprehensive Review
 
 When all tasks are completed:
 
+0. **Final Verification (Required before Level 2)**
+   - Invoke `dw-verify` with the project's verify command (test + lint + build, or the documented gate command)
+   - Only proceed with Level 2 if the VERIFICATION REPORT is PASS
+   - If FAIL: fix the root cause, re-verify, and only then open the PRD-compliance review
+
 1. **Execute General Review**
    - Follow `.dw/commands/dw-review-implementation.md` for ALL tasks
    - Generate a complete gap report and recommendations
@@ -102,7 +118,9 @@ When all tasks are completed:
      - No more recommendations, OR
      - User decides that remaining items are acceptable
 
-4. **Final Report**
+4. **Final Report (after final dw-verify PASS)**
+
+   <critical>Before declaring "PLAN COMPLETE" or "COMPLETE WITH PENDING ITEMS", invoke `dw-verify` one last time after the last correction. Without PASS, do not emit the final report.</critical>
 
    ```
    ===================================================

package/scaffold/en/commands/dw-run-task.md

@@ -18,6 +18,8 @@ When available in the project at `./.agents/skills/`, use these skills as specia
 
 | Skill | Trigger |
 |-------|---------|
+| `dw-verify` | **ALWAYS** — invoked before the commit to produce a Verification Report with fresh evidence |
+| `dw-memory` | **ALWAYS** — reads workflow memory at task start and updates it at task end (promotion test) |
 | `vercel-react-best-practices` | Task touches React rendering, hydration, data fetching, bundle, cache, or performance |
 | `webapp-testing` | Task has interactive frontend needing E2E validation in a real browser |
 
@@ -51,6 +53,7 @@ If `.planning/intel/` does NOT exist:
 - Review the PRD context
 - Verify tech spec requirements (including testing strategy)
 - Understand dependencies from previous tasks
+- **Invoke `dw-memory`**: read `.dw/spec/prd-[name]/MEMORY.md` (shared) and `.dw/spec/prd-[name]/tasks/[num]_memory.md` (task-local, create if missing) — decisions, constraints and handoff notes from earlier tasks are mandatory context
 
 ### 2. Task Analysis
 Analyze considering:
@@ -170,9 +173,19 @@ Format in tasks.md (add after marking the task as completed):
 - **If FAILURE**: Fix the issues and re-execute the validation
 - **DO NOT generate a report file** - only output in the terminal
 
+## Final Verification (Required before commit)
+
+<critical>Invoke the `dw-verify` skill before any "task complete" claim. Produce a VERIFICATION REPORT with the project's real verify command (test + lint + build) and exit code 0. Without a PASS report, DO NOT proceed to the commit.</critical>
+
+## Memory Update (Required before commit)
+
+Invoke `dw-memory` to:
+- Update `tasks/[num]_memory.md` with files touched, non-obvious decisions, and handoff notes
+- Apply the **promotion test** (next task needs it? durable? not obvious from repo?) and only promote what passes to `MEMORY.md`
+
 ## Automatic Commit (Required)
 
-At the end of the task (after Level 1 validation passes), **always** commit (no push):
+At the end of the task (after Level 1 validation + dw-verify PASS + dw-memory update), **always** commit (no push):
 
 ```bash
 git status

package/scaffold/en/commands/dw-update.md

@@ -0,0 +1,143 @@
+<system_instructions>
+You are an update utility. When invoked, update dev-workflow to the latest version published on npm without requiring the user to leave the agent.
+
+## When to Use
+- Use when the user wants to update `/dw-*` commands, templates, references, scripts, skills, wrappers, and MCPs to the latest version
+- Use when a new release is out and the user wants to apply it without exiting the session
+- Do NOT use to install from scratch in a new project (use `npx dev-workflow init`)
+- Do NOT use to install system dependencies/Playwright/MCPs (use `npx dev-workflow install-deps`)
+
+## Pipeline Position
+**Predecessor:** (any) | **Successor:** (any)
+
+## Modes
+
+- **Update (default)**: `/dw-update` — updates to the latest version on npm
+- **Rollback**: `/dw-update --rollback` — restores the most recent snapshot in `.dw/.backup/` (created before each update)
+
+## Behavior
+
+### 0. Snapshot Before Update (Required in default mode)
+
+Before overwriting managed files, create a 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
+[ -d .agents/skills ] && cp -r .agents/skills "$SNAPSHOT_DIR/agents-skills" 2>/dev/null
+echo "Snapshot saved to $SNAPSHOT_DIR"
+```
+
+Keep only the 3 most recent snapshots (remove older ones) to avoid buildup.
+
+### 1. Record Current Version (Required)
+
+Before updating, capture the installed version so you can report the 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. Detect Language of Installed Commands (Required)
+
+<critical>Do NOT assume the language from this command file. Detect by inspecting the actual files in `.dw/commands/` so a user with a mixed or switched install does not receive an update in the wrong language.</critical>
+
+Run at the project root:
+
+```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 does not exist"
+fi
+```
+
+Rules:
+- If `DETECTED_LANG` is `pt-br` or `en`: use it in the next step
+- If empty (tie, missing folder, new install): ask the user `I detected [describe context]. Proceed with pt-br or en?` and wait for the response before continuing
+
+### 3. Run the Update (Required)
+
+<critical>Use `npx -y @brunosps00/dev-workflow@latest` to FORCE fetching the latest version from npm (bypass local cache). Pass `--lang=<DETECTED_LANG>` to skip the interactive prompt.</critical>
+
+```bash
+npx -y @brunosps00/dev-workflow@latest update --lang=$DETECTED_LANG
+```
+
+The `update` command overwrites managed files and PRESERVES:
+- `.dw/rules/` (user rules)
+- `.dw/spec/` (in-progress PRDs and tasks)
+- `.planning/` (user data)
+
+If the update fails (network error, permission, package unavailable): report the error to the user and STOP. Do NOT attempt manual workarounds like copying files by hand.
+
+### 4. Capture New Version
+
+```bash
+node -e "console.log(require('@brunosps00/dev-workflow/package.json').version)" 2>/dev/null
+```
+
+### 5. Report Result
+
+Present to the user:
+- Detected language (`DETECTED_LANG`)
+- Previous version → new version
+- Summary of what the `update` output showed (files copied, wrappers generated, MCPs configured)
+- Any warnings or errors
+
+### 6. Suggest Next Step
+
+If commands/skills were updated, remind the user:
+- Restart the agent session (or reload skills) so the new instructions take effect — skills are usually loaded at session start
+- Run `/dw-help` after the reload to see the updated command set
+- If the release changed system dependencies (Playwright, MCPs), run `npx dev-workflow install-deps` separately
+
+## Rollback Mode
+
+If invoked with `--rollback`:
+
+1. List snapshots in `.dw/.backup/`
+2. If none exist: STOP and report "No snapshot available"
+3. If more than one exists: ask the user which to restore (default: most recent)
+4. Confirm with the user: "Restore snapshot `<path>`? This OVERWRITES `.dw/commands/`, `.dw/templates/`, `.dw/references/`, `.dw/scripts/`, and `.agents/skills/`. Proceed? [y/N]"
+5. Only after `y`: copy back
+
+```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. Report: snapshot restored, version likely recovered (read from `.dw/commands/dw-help.md` or metadata if present)
+
+## Advanced Options
+
+If the user asks for a specific version (not `@latest`):
+
+```bash
+npx -y @brunosps00/dev-workflow@<version> update --lang=$DETECTED_LANG
+```
+
+E.g.: `npx -y @brunosps00/dev-workflow@0.4.5 update --lang=en`
+
+## Notes
+
+- `npx -y` skips the "OK to install" prompt when the package is not cached
+- `@latest` bypasses the npx cache and pulls the `latest` tag from the registry
+- `--lang=...` skips the interactive language prompt; the value comes from the auto-detection in step 2
+- This command does NOT update the user project's Node dependencies — only the dev-workflow scaffold
+
+</system_instructions>

package/scaffold/en/templates/adr-template.md

@@ -0,0 +1,56 @@
+---
+id: NNN
+status: Proposed
+title: [Short imperative title of the decision]
+date: YYYY-MM-DD
+prd: [PRD slug, e.g. prd-user-auth]
+schema_version: "1.0"
+supersedes: null
+superseded_by: null
+---
+
+# ADR-NNN: [Title]
+
+## Status
+
+Proposed | Accepted | Deprecated | Superseded by ADR-XXX
+
+## Context
+
+[Problem context. What motivating forces led to this decision?
+1-3 short paragraphs. Focus on "why are we deciding now" — do not retell the whole project history.]
+
+## Decision
+
+[The decision made. Start with a verb ("Adopt", "Use", "Migrate to", "Reject").
+1 actionable sentence, followed by 1-3 detail sentences if needed.]
+
+## Alternatives Considered
+
+1. **[Alternative 1]** — [what it was, why not chosen. 1-2 sentences.]
+2. **[Alternative 2]** — [what it was, why not chosen. 1-2 sentences.]
+3. **[Add more if relevant.]**
+
+## Consequences
+
+### Positive
+- [Positive consequence 1]
+- [Positive consequence 2]
+
+### Negative
+- [Accepted cost 1 — do not omit]
+- [Accepted cost 2]
+
+### Neutral / Mitigations
+- [Unbiased tradeoff, or mitigation plan]
+
+## Related
+
+- PRD: `.dw/spec/[prd-slug]/prd.md`
+- TechSpec: `.dw/spec/[prd-slug]/techspec.md` (if applicable)
+- Affected tasks: [task list, if applicable]
+- Related ADRs: [list, if applicable]
+
+## References
+
+- [Links to external docs, RFCs, posts, issues]

package/scaffold/en/templates/prd-template.md

@@ -1,3 +1,9 @@
+---
+type: prd
+schema_version: "1.0"
+status: draft
+---
+
 # Product Requirements Document (PRD) Template
 
 ## Overview
@@ -68,3 +74,9 @@ Implementation details will be addressed in the Technical Specification.]
 - Questions about user needs or business goals
 - Dependencies on external business factors
 - Areas requiring design or user research]
+
+## Related ADRs
+
+[List ADRs that constrain or inform this feature. Leave empty if none. Use `/dw-adr` to record a decision that emerges during execution.
+
+- `adrs/adr-NNN.md` — [short title]]

package/scaffold/en/templates/task-template.md

@@ -1,3 +1,9 @@
+---
+type: task
+schema_version: "1.0"
+status: pending
+---
+
 # Task X.0: [Main Task Title]
 
 <critical>Read the prd.md and techspec.md files in this folder. If you don't read these files your task will be invalidated.</critical>
@@ -60,3 +66,9 @@ git commit -m "feat([module]): [description]
 - [item 2]
 - Add unit tests"
 ```
+
+## Related ADRs
+
+[ADRs that constrain this task's decisions. Leave empty if none.
+
+- `adrs/adr-NNN.md` — [short title, how the decision affects this task]]

package/scaffold/en/templates/tasks-template.md

@@ -1,3 +1,9 @@
+---
+type: tasks-index
+schema_version: "1.0"
+status: draft
+---
+
 # Implementation Tasks Summary for [Feature]
 
 ## Branch

package/scaffold/en/templates/techspec-template.md

@@ -1,3 +1,9 @@
+---
+type: techspec
+schema_version: "1.0"
+status: draft
+---
+
 # Technical Specification Template
 
 ## Executive Summary
@@ -121,3 +127,9 @@ type ServiceName interface {
 ### Relevant Files
 
 [List relevant project files here]
+
+## Related ADRs
+
+[List architectural ADRs that constrain or inform this techspec. Leave empty if none. Use `/dw-adr` during execution to record new decisions.
+
+- `adrs/adr-NNN.md` — [short title]]

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

@@ -0,0 +1,117 @@
+<system_instructions>
+Você é um registrador de decisões arquiteturais. Sua função é criar um **Architecture Decision Record (ADR)** que documente uma decisão técnica importante feita durante a fase atual do PRD.
+
+## Quando Usar
+- Use quando uma decisão arquitetural ou de design foi tomada e precisa ser registrada para referência futura (escolha de biblioteca, padrão de comunicação, tradeoff de performance, restrição imposta por compliance, etc.)
+- Use durante `/dw-create-techspec` ou `/dw-run-task` quando a justificativa da decisão não cabe no techspec nem no task file
+- NÃO use para decisões triviais ou reversíveis sem custo (escolha de nome de variável, ordem de import)
+- NÃO use para registrar bugs ou incidents (use `/dw-bugfix` ou notas operacionais)
+
+## Posição no Pipeline
+**Antecessor:** qualquer ponto do pipeline após `/dw-create-prd` | **Sucessor:** continua o fluxo anterior (techspec, task, review)
+
+O ADR é **aditivo**: ele não substitui nenhuma etapa do pipeline. Qualquer command existente pode invocar `/dw-adr` quando uma decisão não-trivial precisar de registro permanente.
+
+## Variáveis de Entrada
+
+| Variável | Descrição | Exemplo |
+|----------|-----------|---------|
+| `{{PRD_PATH}}` | Caminho da pasta do PRD ativo | `.dw/spec/prd-minha-feature` |
+| `{{TITLE}}` | Título curto da decisão (imperativo) | "Usar PostgreSQL ao invés de MongoDB" |
+
+Se `{{PRD_PATH}}` não for fornecido, pergunte ao usuário qual PRD está ativo (leia `.dw/spec/` e liste). Se `{{TITLE}}` não for fornecido, pergunte.
+
+## Localização dos Arquivos
+
+- Diretório de ADRs: `{{PRD_PATH}}/adrs/`
+- Arquivo novo: `{{PRD_PATH}}/adrs/adr-NNN.md` (NNN zero-padded para 3 dígitos)
+- Template: `.dw/templates/adr-template.md`
+
+## Fluxo de Trabalho
+
+### 1. Descobrir o próximo número
+- Liste os arquivos em `{{PRD_PATH}}/adrs/` (crie o diretório se não existir)
+- O próximo número é `max(existentes) + 1`, ou `1` se vazio
+
+### 2. Coletar contexto (perguntas mínimas)
+
+Pergunte ao usuário **4 perguntas objetivas**, uma por vez:
+
+1. **Contexto**: qual problema ou força motivadora levou a esta decisão? (1-3 frases)
+2. **Decisão**: qual é a decisão tomada? (1 frase acionável, começa com verbo)
+3. **Alternativas consideradas**: quais outras opções foram avaliadas e por que não foram escolhidas? (mínimo 2)
+4. **Consequências**: quais são os tradeoffs positivos e negativos desta decisão? (explicite os negativos — sem painting rosy)
+
+### 3. Escrever o arquivo ADR
+
+Use `.dw/templates/adr-template.md` como base. Campos obrigatórios:
+
+```yaml
+---
+id: NNN
+status: Proposed | Accepted | Deprecated | Superseded
+title: [título do ADR]
+date: YYYY-MM-DD
+prd: [slug do PRD]
+schema_version: "1.0"
+---
+
+# ADR-NNN: [Título]
+
+## Status
+[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
+
+## Context
+[Contexto e forças motivadoras]
+
+## Decision
+[A decisão tomada]
+
+## Alternatives Considered
+1. **[Alternativa 1]** — [por que não foi escolhida]
+2. **[Alternativa 2]** — [por que não foi escolhida]
+
+## Consequences
+### Positivas
+- [consequência positiva 1]
+
+### Negativas
+- [consequência negativa / tradeoff aceito]
+
+## Related
+- PRD: `.dw/spec/prd-[nome]/prd.md`
+- TechSpec: `.dw/spec/prd-[nome]/techspec.md` (se aplicável)
+- Tasks afetadas: [lista, se aplicável]
+```
+
+### 4. Atualizar referências cruzadas
+
+Se o ADR for criado **durante** a execução de um PRD, adicionar uma linha na seção "Related ADRs" dos artefatos relacionados:
+- `prd.md`, `techspec.md`, ou `[N]_task.md`, conforme o escopo da decisão
+
+Se a seção "Related ADRs" não existir no arquivo, adicioná-la ao final.
+
+### 5. Reportar
+
+Apresente ao usuário:
+- Caminho do ADR criado
+- Artefatos atualizados com referência cruzada
+- Status inicial (geralmente `Accepted` para decisões já tomadas, `Proposed` para decisões ainda abertas)
+
+## Comportamento Obrigatório
+
+<critical>NUNCA sobrescreva um ADR existente. Cada ADR é imutável — se a decisão muda, crie um novo ADR com status `Supersedes ADR-NNN` e marque o antigo como `Superseded by ADR-XXX`.</critical>
+
+<critical>NUNCA pinte o tradeoff como "só positivo". A seção Consequências Negativas é obrigatória — se não houver nenhum custo, a decisão não precisa de ADR.</critical>
+
+## Inspired by
+
+Este command é inspirado no padrão de ADRs de `/tmp/compozy/.agents/skills/cy-create-adr/` do projeto [Compozy](https://github.com/compozy/compozy). Adaptações para dev-workflow:
+
+- Paths são `.dw/spec/<prd>/adrs/` ao invés de `.compozy/tasks/<name>/adrs/`
+- 4 perguntas mínimas em vez do fluxo interativo mais longo (alinhado com o estilo conciso de outros commands dw-*)
+- Integração explícita com `schema_version` dos templates v1.0
+
+Credit: Compozy project.
+
+</system_instructions>