@brunosps00/dev-workflow 0.4.7 → 0.5.0

package/README.md

@@ -10,13 +10,15 @@ npx @brunosps00/dev-workflow init
 
 This will:
 1. Ask you to select a language (English or Portuguese)
-2. Create `.dw/commands/` with 23 workflow commands
-3. Create `.dw/templates/` with document templates
+2. Create `.dw/commands/` with 26 workflow commands
+3. Create `.dw/templates/` with document templates (PRD, TechSpec, Tasks, ADR, etc.)
 4. Create `.dw/rules/` (populated by `/dw-analyze-project`)
-5. Install bundled skills (ui-ux-pro-max, security-review, etc.) to `.agents/skills/`
+5. Install bundled skills (`dw-verify`, `dw-memory`, `dw-review-rigor`, `ui-ux-pro-max`, `security-review`, etc.) to `.agents/skills/`
 6. Generate skill wrappers for Claude Code, Codex, Copilot, and OpenCode
 7. Configure MCP servers (Context7 + Playwright)
 
+> **Compozy-inspired disciplines.** Since 0.5.0, dev-workflow bundles three primitives — `dw-verify`, `dw-memory`, `dw-review-rigor` — adapted from the [Compozy](https://github.com/compozy/compozy) project and invoked internally by existing commands. See [docs/compozy-integration.md](docs/compozy-integration.md) for what was ported and what was not.
+
 Optional dependencies (Playwright browsers, react-doctor, GSD):
 ```bash
 npx @brunosps00/dev-workflow install-deps
@@ -81,7 +83,15 @@ Audits the codebase for code smells and refactoring opportunities using Martin F
 Analyzes pending changes, groups them by feature or logical context, and creates atomic semantic commits following the Conventional Commits format. Uses allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`, `build`.
 
 #### `/dw-generate-pr`
-Pushes the branch to remote and creates a Pull Request on GitHub with a structured description. Collects information from the PRD and modified files, runs tests, then generates a PR body with summary, changes grouped by module, test plan, and deploy notes.
+Pushes the branch to remote and creates a Pull Request on GitHub with a structured description. Collects information from the PRD and modified files, runs tests, then generates a PR body with summary, changes grouped by module, test plan, and deploy notes. **Hard gate**: requires a fresh `dw-verify` PASS in the current session before the push.
+
+#### `/dw-revert-task`
+Safely reverts the commits of a specific task created by `/dw-run-task`, with dependency-aware checks (blocks if subsequent tasks already executed depend on it) and explicit user confirmation. Updates `tasks.md` to re-mark the task as pending.
+
+### Architectural Decisions
+
+#### `/dw-adr`
+Records an Architecture Decision Record (ADR) for a non-trivial decision during PRD execution. Creates `.dw/spec/<prd>/adrs/adr-NNN.md` with Context / Decision / Alternatives / Consequences, and updates cross-references in the PRD/TechSpec/Task. Inspired by the ADR pattern from [Compozy](https://github.com/compozy/compozy).
 
 ### Intelligence
 
@@ -154,7 +164,7 @@ All wrappers point to `.dw/commands/` as the single source of truth.
 ```
 your-project/
 ├── .dw/
-│   ├── commands/          # 23 workflow command files
+│   ├── commands/          # 26 workflow command files
 │   ├── templates/         # Document templates (PRD, TechSpec, etc.)
 │   ├── rules/             # Project-specific rules (run /dw-analyze-project)
 │   ├── references/        # Reference documentation
@@ -170,7 +180,20 @@ your-project/
 
 ## Bundled Skills
 
-Skills installed to `.agents/skills/` for use by all commands:
+Skills installed to `.agents/skills/` for use by all commands.
+
+### Workflow discipline (invoked internally by dw-* commands)
+
+These are not slash commands — they are primitives other commands call to enforce discipline. You never invoke them directly; the commands that need them do so transparently.
+
+| Skill | Description | Invoked by | Inspired by |
+|-------|-------------|------------|-------------|
+| **dw-verify** | Enforces fresh verification evidence before any completion, commit, or PR claim — with Iron Law, gate function, and Verification Report template | `dw-run-task`, `dw-run-plan`, `dw-fix-qa`, `dw-bugfix`, `dw-code-review`, `dw-generate-pr`, `dw-quick` | [Compozy](https://github.com/compozy/compozy) `cy-final-verify` |
+| **dw-memory** | Two-tier workflow memory (shared `MEMORY.md` + per-task `<N>_memory.md`) with promotion test and compaction rules, so cross-task context persists cleanly | `dw-run-task`, `dw-run-plan`, `dw-autopilot`, `dw-resume` | [Compozy](https://github.com/compozy/compozy) `cy-workflow-memory` |
+| **dw-review-rigor** | Review discipline: de-duplication, severity ordering, verify-intent-before-flagging, skip-linter-issues, signal-over-volume | `dw-code-review`, `dw-review-implementation`, `dw-refactoring-analysis` | [Compozy](https://github.com/compozy/compozy) `cy-review-round` |
+| **dw-council** | Multi-advisor debate (3-5 archetypes) with steel-manning, concession tracking, and dissent-preserving synthesis. Opt-in only. | `dw-brainstorm --council`, `dw-create-techspec --council` | [Compozy](https://github.com/compozy/compozy) `cy-idea-factory` |
+
+### Domain expertise
 
 | Skill | Description | Source | License |
 |-------|-------------|--------|---------|

package/lib/constants.js

@@ -1,5 +1,6 @@
 const COMMANDS = {
   en: [
+    { name: 'dw-adr', description: 'Record an Architecture Decision Record (ADR) for a non-trivial decision during PRD execution' },
     { name: 'dw-analyze-project', description: 'Analyze repository stack, patterns, and conventions to generate project rules' },
     { name: 'dw-autopilot', description: 'Full pipeline orchestrator from a wish to a PR with minimal intervention (research, PRD, tasks, execution, QA, review, commit)' },
     { name: 'dw-brainstorm', description: 'Explore ideas and directions before starting implementation' },
@@ -20,12 +21,14 @@ const COMMANDS = {
     { name: 'dw-refactoring-analysis', description: 'Audit codebase for code smells and refactoring opportunities with prioritized report' },
     { name: 'dw-resume', description: 'Restore session context and suggest the next workflow step' },
     { name: 'dw-review-implementation', description: 'Review if all PRD requirements were correctly implemented' },
+    { name: 'dw-revert-task', description: 'Safely revert the commits of a specific task with dependency-aware checks' },
     { name: 'dw-run-plan', description: 'Execute ALL tasks sequentially until the plan is complete' },
     { name: 'dw-run-qa', description: 'Run visual QA with browser automation, E2E tests, and accessibility' },
     { name: 'dw-run-task', description: 'Execute a single task with built-in validation and testing' },
     { name: 'dw-update', description: 'Update dev-workflow to the latest version published on npm without leaving the agent session' },
   ],
   'pt-br': [
+    { name: 'dw-adr', description: 'Registrar um Architecture Decision Record (ADR) para uma decisao nao-trivial durante o PRD' },
     { name: 'dw-analyze-project', description: 'Analisa stack, patterns e convencoes do repositorio para gerar regras do projeto' },
     { name: 'dw-autopilot', description: 'Orquestrador completo de um desejo ate o PR com minima intervencao (pesquisa, PRD, tasks, execucao, QA, review, commit)' },
     { name: 'dw-brainstorm', description: 'Explorar ideias e direcoes antes de comecar a implementacao' },
@@ -46,6 +49,7 @@ const COMMANDS = {
     { name: 'dw-refactoring-analysis', description: 'Auditar codebase para code smells e oportunidades de refatoracao com relatorio priorizado' },
     { name: 'dw-resume', description: 'Restaurar contexto da sessao e sugerir o proximo passo do workflow' },
     { name: 'dw-review-implementation', description: 'Revisar se todos os requisitos do PRD foram implementados corretamente' },
+    { name: 'dw-revert-task', description: 'Reverter com seguranca os commits de uma task especifica com checks de dependencia' },
     { name: 'dw-run-plan', description: 'Executar TODAS as tasks sequencialmente ate completar o plano' },
     { name: 'dw-run-qa', description: 'Executar QA visual com automacao de browser, testes E2E e acessibilidade' },
     { name: 'dw-run-task', description: 'Executar uma task com validacao e testes integrados' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"

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

@@ -0,0 +1,117 @@
+<system_instructions>
+You are an architectural-decision recorder. Your job is to create an **Architecture Decision Record (ADR)** documenting an important technical decision made during the current PRD phase.
+
+## When to Use
+- Use when an architectural or design decision has been made and needs to be recorded for future reference (library choice, communication pattern, performance tradeoff, compliance-imposed constraint, etc.)
+- Use during `/dw-create-techspec` or `/dw-run-task` when the rationale for the decision does not fit in the techspec or the task file
+- Do NOT use for trivial or cheaply-reversible decisions (variable names, import order)
+- Do NOT use to record bugs or incidents (use `/dw-bugfix` or operational notes)
+
+## Pipeline Position
+**Predecessor:** any point in the pipeline after `/dw-create-prd` | **Successor:** continue the previous flow (techspec, task, review)
+
+The ADR is **additive**: it does not replace any pipeline stage. Any existing command can invoke `/dw-adr` when a non-trivial decision needs a permanent record.
+
+## Input Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{{PRD_PATH}}` | Path to the active PRD folder | `.dw/spec/prd-my-feature` |
+| `{{TITLE}}` | Short imperative title of the decision | "Use PostgreSQL instead of MongoDB" |
+
+If `{{PRD_PATH}}` is not provided, ask the user which PRD is active (read `.dw/spec/` and list). If `{{TITLE}}` is not provided, ask.
+
+## File Locations
+
+- ADR directory: `{{PRD_PATH}}/adrs/`
+- New file: `{{PRD_PATH}}/adrs/adr-NNN.md` (NNN zero-padded to 3 digits)
+- Template: `.dw/templates/adr-template.md`
+
+## Workflow
+
+### 1. Discover the next number
+- List files in `{{PRD_PATH}}/adrs/` (create the directory if missing)
+- Next number is `max(existing) + 1`, or `1` if empty
+
+### 2. Gather context (minimum questions)
+
+Ask the user **4 focused questions**, one at a time:
+
+1. **Context**: what problem or motivating force led to this decision? (1-3 sentences)
+2. **Decision**: what is the decision? (1 actionable sentence, starts with a verb)
+3. **Alternatives considered**: what other options were evaluated and why were they not chosen? (minimum 2)
+4. **Consequences**: what are the positive and negative tradeoffs? (name the negatives explicitly — no rosy painting)
+
+### 3. Write the ADR file
+
+Use `.dw/templates/adr-template.md` as the base. Required fields:
+
+```yaml
+---
+id: NNN
+status: Proposed | Accepted | Deprecated | Superseded
+title: [ADR title]
+date: YYYY-MM-DD
+prd: [PRD slug]
+schema_version: "1.0"
+---
+
+# ADR-NNN: [Title]
+
+## Status
+[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
+
+## Context
+[Context and motivating forces]
+
+## Decision
+[The decision made]
+
+## Alternatives Considered
+1. **[Alternative 1]** — [why not chosen]
+2. **[Alternative 2]** — [why not chosen]
+
+## Consequences
+### Positive
+- [positive consequence 1]
+
+### Negative
+- [negative consequence / accepted tradeoff]
+
+## Related
+- PRD: `.dw/spec/prd-[name]/prd.md`
+- TechSpec: `.dw/spec/prd-[name]/techspec.md` (if applicable)
+- Affected tasks: [list, if applicable]
+```
+
+### 4. Update cross-references
+
+If the ADR is created **during** a PRD execution, add a line to the "Related ADRs" section of related artifacts:
+- `prd.md`, `techspec.md`, or `[N]_task.md`, matching the decision's scope
+
+If the "Related ADRs" section does not exist in the file, add it at the end.
+
+### 5. Report
+
+Present to the user:
+- Path of the created ADR
+- Artifacts updated with cross-reference
+- Initial status (usually `Accepted` for decisions already made, `Proposed` for open ones)
+
+## Required Behavior
+
+<critical>NEVER overwrite an existing ADR. Each ADR is immutable — if the decision changes, create a new ADR with status `Supersedes ADR-NNN` and mark the old one as `Superseded by ADR-XXX`.</critical>
+
+<critical>NEVER paint the tradeoff as "all upside". The Negative Consequences section is required — if there's no cost, the decision does not need an ADR.</critical>
+
+## Inspired by
+
+This command is inspired by the ADR pattern in `/tmp/compozy/.agents/skills/cy-create-adr/` from the [Compozy](https://github.com/compozy/compozy) project. Adaptations for dev-workflow:
+
+- Paths are `.dw/spec/<prd>/adrs/` instead of `.compozy/tasks/<name>/adrs/`
+- 4 minimum questions instead of Compozy's longer interactive flow (aligned with the concise style of other dw-* commands)
+- Explicit integration with `schema_version` of v1.0 templates
+
+Credit: Compozy project.
+
+</system_instructions>

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

@@ -33,6 +33,13 @@ A step that invokes a `/dw-xxx` command is ONLY considered complete when the art
 ## Pipeline Position
 **Predecessor:** (user's wish) | **Successor:** (PR merge)
 
+## Complementary Skills
+
+| Skill | Trigger |
+|-------|---------|
+| `dw-memory` | **ALWAYS** — the memory thread runs through every phase (brainstorm -> PRD -> techspec -> tasks -> execution -> QA -> review -> PR). Decisions at one gate feed context into the next. |
+| `dw-verify` | **ALWAYS** — invoked at each gate (PRD, Tasks, PR) before asking user approval; and before the final commit + push. |
+
 ## Input Variables
 
 | Variable | Description | Example |

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

@@ -11,6 +11,11 @@ You are a brainstorming facilitator for the current workspace. This command exis
 ## Pipeline Position
 **Predecessor:** (user idea) | **Successor:** `/dw-create-prd`
 
+## Flags
+
+- **(default)**: normal brainstorm with 3-7 options (conservative, balanced, bold) and trade-offs
+- **`--council`**: after the normal brainstorm, invoke the `dw-council` skill to stress-test the top 2-3 options via 3-5 archetypes (pragmatic-engineer, architect-advisor, security-advocate, product-mind, devils-advocate). Useful when the choice is high-impact and there is genuine dissent between paths.
+
 ## Decision Flowchart: Brainstorm vs Direct PRD
 
 ```dot
@@ -33,6 +38,7 @@ digraph brainstorm_decision {
 
 When available in the project under `./.agents/skills/`, use these skills to enrich ideation:
 
+- `dw-council` (opt-in via `--council`): multi-advisor stress-test of the most promising options with mandatory steel-manning and concession tracking. **DO NOT invoke by default** — only when the flag is present or when consensus forms too quickly (false-consensus signal).
 - `ui-ux-pro-max`: use when brainstorming involves frontend, UI style direction, design system choices, or visual identity exploration
 - `vercel-react-best-practices`: use when brainstorming React/Next.js architecture or performance trade-offs
 - `security-review`: use when brainstorming touches auth, data handling, or security-sensitive features

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

@@ -15,6 +15,7 @@
 
     When available in the project at `./.agents/skills/`, use these skills as contextual support without replacing this command:
 
+    - `dw-verify`: **ALWAYS** — in Direct mode, invoked before committing the fix. The VERIFICATION REPORT must show the original bug symptom no longer reproduces (not just that tests pass).
     - `vercel-react-best-practices`: use when the bug affects React/Next.js and there is suspicion of render, hydration, fetching, waterfall, bundle, or re-render issues
     - `webapp-testing`: use when the fix requires a reproducible E2E/retest flow in a web app
     - `security-review`: use when the root cause touches auth, authorization, external input, upload, secrets, SQL, XSS, SSRF, or other sensitive surfaces
@@ -281,6 +282,14 @@
     - `adjust` - Tell me what to modify in the plan
     ```
 
+    ### 5.5. Final Verification (Direct mode — required before commit)
+
+    <critical>After applying the approved tasks in Direct mode, invoke `dw-verify` before committing. The VERIFICATION REPORT must show:
+    1. The project's verify command (test + lint + build) with exit 0.
+    2. Original-symptom reproduction: the scenario that triggered the bug no longer triggers it.
+    
+    Without PASS on both, DO NOT commit. Report what failed and return to step 4 (root-cause analysis).</critical>
+
     ### 6. Generate Bugfix Document (Analysis Mode)
 
     <critical>

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

@@ -21,6 +21,8 @@ Typically invoked before creating PR via `/dw-generate-pr`
 
 When available in the project under `./.agents/skills/`, use these skills as analytical support without replacing this command:
 
+- `dw-review-rigor`: **ALWAYS** — applies de-duplication (same pattern in N files = 1 finding), severity ordering (critical → high → medium → low), verify-before-flag, skip-what-linter-catches, and signal-over-volume. The report's "Issues Found" table follows this discipline.
+- `dw-verify`: **ALWAYS** — invoked before emitting an `APPROVED` or `APPROVED WITH CAVEATS` verdict. Without a VERIFICATION REPORT PASS (test + lint + build), the verdict cannot be APPROVED.
 - `security-review`: use when auth, authorization, external input, upload, SQL, external integration, secrets, SSRF, XSS, or sensitive surfaces are present
 - `vercel-react-best-practices`: use when the diff touches React/Next.js to review rendering, fetching, bundle, hydration, and performance patterns
 
@@ -196,6 +198,22 @@ Verify:
 
 <critical>THE REVIEW CANNOT BE APPROVED IF ANY TEST FAILS</critical>
 
+### 6.5. Apply `dw-review-rigor` (Required)
+
+Before writing the "Issues Found" table, invoke the `dw-review-rigor` skill and apply the five rules:
+
+1. **De-duplicate**: if the same pattern appears in N files, emit 1 finding with the list of affected files — never N identical findings.
+2. **Severity ordering**: always present in critical → high → medium → low order (not by file).
+3. **Verify intent before flagging**: check adjacent comments, ADRs in `.dw/spec/*/adrs/`, test coverage, rules in `.dw/rules/`. Do not flag patterns with documented justification.
+4. **Skip what the linter catches**: run the project linter first; anything it already reports is not a finding.
+5. **Signal over volume**: ~8 precise findings beats 30 marginal ones. Keep all critical/high; prune medium/low to the most impactful.
+
+If prior reviews exist in `{{PRD_PATH}}/reviews/` or a previous `{{PRD_PATH}}/dw-code-review.md` round, read them and emit **only NEW findings** — do not re-flag items already tracked.
+
+### 6.6. Final Verification (Required before verdict)
+
+<critical>Invoke `dw-verify` and include the VERIFICATION REPORT at the start of the report. Without PASS, the verdict can only be `REJECTED` — never `APPROVED` or `APPROVED WITH CAVEATS`.</critical>
+
 ### 7. Generate Code Review Report (Required)
 
 Save to `{{PRD_PATH}}/dw-code-review.md`:

package/scaffold/en/commands/dw-create-tasks.md

@@ -42,10 +42,22 @@
     - Organize sequencing
     - Include unit tests as subtasks of each task
 
+    3.5. **Circular Dependency Check (Pre-flight)**
+    - Before writing any file, build the dependency graph (`blockedBy` field or "Depends on" between tasks)
+    - Detect cycles: if task A depends on B and B depends (directly or transitively) on A, there's a cycle
+    - If a cycle exists: **DO NOT write the files**. Present the cycle to the user and request restructuring (e.g., extract shared responsibility, invert dependency, merge tasks)
+    - If no cycle: proceed
+
     4. **Generate Individual Task Files**
     - Create a file for each main task
     - Detail subtasks and success criteria
     - Include mandatory unit tests
+    - **Codebase-aware enrichment (Optional but recommended)**: for tasks that touch known codebase areas, dispatch a parallel Agent Explore (one per task or one per area) to populate:
+      - "Relevant Files": paths and why they're relevant to the task
+      - "Dependent Files": paths that may need cascading changes
+      - "Applicable Rules": links to `.dw/rules/*.md` that constrain the task
+      - "Related ADRs": files in `.dw/spec/<prd>/adrs/` that constrain decisions
+      This enrichment is additive: it does not block task generation, it only improves the quality of the context `dw-run-task` receives later.
 
     ## Task Creation Guidelines
 

package/scaffold/en/commands/dw-create-techspec.md

@@ -13,10 +13,16 @@
     ## Pipeline Position
     **Predecessor:** `/dw-create-prd` | **Successor:** `/dw-create-tasks`
 
+    ## Flags
+
+    - **(default)**: generate a normal techspec from the PRD
+    - **`--council`**: before finalizing the techspec, invoke the `dw-council` skill on the primary architectural decision (e.g. monolith vs microservices, SQL vs NoSQL, lib X vs Y). The council output becomes an "Architectural Debate" section in the techspec, and firm decisions become an ADR via `/dw-adr`. Useful when the techspec introduces a high-impact structural choice.
+
     ## Complementary Skills
 
     When available in the project under `./.agents/skills/`, use these skills as support:
 
+    - `dw-council` (opt-in via `--council`): multi-advisor debate on the primary architectural decision with steel-manning. **DO NOT invoke by default**.
     - `vercel-react-best-practices`: use when defining frontend architecture for React/Next.js projects
     - `ui-ux-pro-max`: use when defining design system decisions, color palettes, typography, and UI style for the TechSpec
     - `security-review`: use when the feature touches auth, authorization, or sensitive data handling
@@ -96,6 +102,8 @@
     - Review project patterns in `{{RULES_PATH}}`
     - Confirm that the PRD exists at `{{PRD_PATH}}` or `spec/prd-[feature-name]/prd.md`
 
+    <critical>Hard gate: if the PRD has an "Open Questions" / "Questões em Aberto" section with unresolved items, STOP. Present the questions to the user and request resolution before writing the techspec. A techspec built on undefined requirements guarantees rework.</critical>
+
     ## Workflow
 
     ### 1. Analyze PRD (Required)

package/scaffold/en/commands/dw-fix-qa.md

@@ -17,6 +17,7 @@ You are an AI assistant specialized in post-QA bug fixing with evidence-driven r
 
 When available in the project under `./.agents/skills/`, use these skills as operational support without replacing this command:
 
+- `dw-verify`: **ALWAYS** — invoked before marking any bug as `Fixed` or `Closed` in `QA/bugs.md`. Without a VERIFICATION REPORT PASS (test + lint + build) **and** retest evidence, status stays `Reopened` or `Under review`.
 - `webapp-testing`: support for structuring retests, captures, and scripts when complementary to Playwright MCP
 - `vercel-react-best-practices`: use only if the fix affects React/Next.js frontend and there is risk of rendering, hydration, fetching, or performance regression
 
@@ -88,6 +89,10 @@ For each fixed bug:
 7. Record in the QA report which user/profile was used in the retest
 8. If the retest requires persistent auth, request inspection beyond MCP, or more faithful real-browser reproduction, record this in the report
 
+### 3.5. Final Verification Before Status Change
+
+<critical>Invoke the `dw-verify` skill before changing any bug's status to `Fixed` or `Closed`. The VERIFICATION REPORT (test + lint + build) must be PASS **and** Playwright retest evidence must be saved. Without both, the status does not change.</critical>
+
 ### 4. Update Artifacts
 
 Update `QA/bugs.md` for each bug:

package/scaffold/en/commands/dw-generate-pr.md

@@ -9,6 +9,14 @@ You are an assistant specialized in creating well-documented Pull Requests. Your
 ## Pipeline Position
 **Predecessor:** `/dw-code-review` or `/dw-commit` | **Successor:** (merge)
 
+## Complementary Skills
+
+| Skill | Trigger |
+|-------|---------|
+| `dw-verify` | **ALWAYS** — invoked before `git push`. Without a VERIFICATION REPORT PASS in the current session AFTER the last code edit, the PR **CANNOT** be created. |
+
+<critical>Hard gate: if the current session has no VERIFICATION REPORT PASS from `dw-verify` produced AFTER the last edit/commit, STOP and invoke `dw-verify` before proceeding. A PR is a permanent artifact — it demands the highest verification standard.</critical>
+
 ## Usage
 
 ```

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

@@ -11,7 +11,26 @@ You are a workspace help assistant. When invoked, present the user with a comple
 ## Behavior
 
 - If invoked without arguments (`/dw-help`): show the complete guide below
-- If invoked with an argument (`/dw-help create-prd`): show only the detailed section for that command
+- If invoked with an argument matching a command (`/dw-help dw-create-prd`): show only that command's detailed section
+- If invoked with a **keyword that is not a command name** (`/dw-help bug`, `/dw-help review`, `/dw-help design`): perform contextual lookup — identify the most relevant command(s) for the keyword and present each with 1-2 lines of justification ("for bugs, use `/dw-bugfix` because..."). Use the mapping table below.
+
+### Contextual mapping (keyword → suggested command)
+
+| Keyword(s) | Suggested command | Why |
+|------------|-------------------|-----|
+| bug, error, failure, issue | `/dw-bugfix` | Auto-triage bug vs feature + fix |
+| review, quality | `/dw-code-review` | Formal Level-3 review with report |
+| qa, visual test, playwright | `/dw-run-qa` | E2E QA with browser automation |
+| refactor, smell, fowler | `/dw-refactoring-analysis` | Prioritized code-smell audit |
+| design, ui, redesign | `/dw-redesign-ui` | Audit + propose + implement visual |
+| decision, adr, architecture | `/dw-adr` | Record an Architecture Decision Record |
+| debate, council, stress-test, opinions | `/dw-brainstorm --council` or `/dw-create-techspec --council` | Invokes `dw-council` for a multi-advisor debate |
+| revert, rollback task | `/dw-revert-task` | Safe revert with dependency checks |
+| hotfix, quick change | `/dw-quick` | One-off task with guarantees, no PRD |
+| resume, where I left off | `/dw-resume` | Restore previous session context |
+| research | `/dw-deep-research` | Multi-source research with citations |
+| idea, brainstorm | `/dw-brainstorm` | Structured ideation with trade-offs |
+| update dev-workflow | `/dw-update` | Update to latest npm version |
 
 ---
 
@@ -137,6 +156,13 @@ This workspace uses an AI command system that automates the full development cyc
 | `/dw-commit` | Semantic commit (Conventional Commits) | - | Commit |
 | `/dw-commit-all` | Commit across all submodules (inside-out) | - | Commits |
 | `/dw-generate-pr` | Push + create PR + copy body + open URL | Target branch | PR on GitHub |
+| `/dw-revert-task` | Safely revert a specific task's commits (dependency checks + confirmation) | PRD path + task number | Reverted commits + updated `tasks.md` |
+
+### Architectural Decisions
+
+| Command | What it does | Input | Output |
+|---------|-------------|-------|--------|
+| `/dw-adr` | Record an Architecture Decision Record (ADR) for a non-trivial decision during a PRD | PRD path + title | `.dw/spec/<prd>/adrs/adr-NNN.md` + cross-refs updated |
 
 ### Maintenance
 
@@ -145,8 +171,21 @@ This workspace uses an AI command system that automates the full development cyc
 | `/dw-list-tasks` | Lists tasks and progress for a PRD | PRD path | Status table |
 | `/dw-task-summary` | Shows details of a task without executing | Number + path | Task summary |
 | `/dw-archive-prd` | Moves completed PRD to `.dw/archived/prd/` | PRD path | Archived PRD |
-| `/dw-help` | This command guide | (optional) command | This document |
-| `/dw-update` | Updates dev-workflow to the latest version on npm without leaving the agent | (none) | Updated managed files |
+| `/dw-help` | This command guide (supports keyword lookup: `/dw-help bug`) | (optional) command or keyword | This document or filtered section |
+| `/dw-update` | Updates dev-workflow to the latest version on npm without leaving the agent (supports `--rollback`) | (none) or `--rollback` | Updated or restored managed files |
+
+### Bundled Skills (invoked internally — not commands)
+
+Skills in `.agents/skills/` that commands above invoke transparently. You don't call them directly.
+
+| Skill | Invoked by | Role |
+|-------|------------|------|
+| `dw-verify` | run-task, run-plan, fix-qa, bugfix, code-review, generate-pr, quick | Iron Law: no success claim without a PASS VERIFICATION REPORT |
+| `dw-memory` | run-task, run-plan, autopilot, resume, revert-task | Two-tier workflow memory (shared + task-local) with promotion test |
+| `dw-review-rigor` | code-review, review-implementation, refactoring-analysis | De-duplication, severity ordering, verify-intent-before-flag, signal-over-volume |
+| `dw-council` | brainstorm `--council`, create-techspec `--council` | Multi-advisor debate (3-5 archetypes) with steel-manning, concession tracking, and dissent-preserving synthesis. Opt-in. |
+
+Inspired by skills from the [Compozy](https://github.com/compozy/compozy) project (`cy-final-verify`, `cy-workflow-memory`, `cy-review-round`).
 
 ## Review Architecture (3 Levels)
 

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

@@ -13,6 +13,12 @@ You are a quick task executor. This command exists to implement one-off changes
 ## Pipeline Position
 **Predecessor:** (user's ad-hoc need) | **Successor:** `/dw-commit` (automatic)
 
+## Complementary Skills
+
+| Skill | Trigger |
+|-------|---------|
+| `dw-verify` | **ALWAYS** — invoked before the commit. Even small changes require a VERIFICATION REPORT PASS (minimal test + lint) before the atomic commit. |
+
 ## Input Variables
 
 | Variable | Description | Example |
@@ -27,7 +33,8 @@ You are a quick task executor. This command exists to implement one-off changes
 4. Implement the change following project conventions
 5. Run relevant existing tests (unit, integration)
 6. Run lint if configured in the project
-7. Create atomic semantic commit with the change
+7. Invoke `dw-verify` and include the VERIFICATION REPORT in the output before committing. Without PASS, DO NOT commit.
+8. Create atomic semantic commit with the change
 
 ## GSD Integration
 

package/scaffold/en/commands/dw-refactoring-analysis.md

@@ -20,6 +20,7 @@ Prerequisite: Run `/dw-analyze-project` first to understand project patterns and
 
 When available in the project under `./.agents/skills/`, use these skills as analytical support without replacing this command:
 
+- `dw-review-rigor`: **ALWAYS** — when cataloging code smells, apply de-duplication (same smell in N files = 1 entry with affected list), severity ordering across P0-P3, signal-over-volume (max ~20 findings; keep criticals, prune marginal ones). A smell with a justifying ADR drops to `low` at most.
 - `security-review`: defer security concerns to this skill — do not duplicate
 - `vercel-react-best-practices`: defer React/Next.js performance patterns to this skill
 

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>