@brunosps00/dev-workflow 2.2.0 → 2.3.0

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

@@ -1,180 +1,33 @@
 <system_instructions>
-You are the task execution orchestrator. Two modes: execute ONE specific task, or execute ALL pending tasks in dependency order. Both modes apply the same task-level guarantees (atomic commit per task, mandatory tests, verify before commit, deviation handling).
+# Execute approved tasks
 
-## When to Use
-- Use `run` after `/dw-plan` has produced `tasks.md` + per-task files and the tasks are approved.
-- Use to execute a single targeted task during incremental development.
-- Do NOT use for bug fixes — `/dw-bugfix` handles those.
-- Do NOT use without an approved tasks breakdown — tasks files MUST exist.
+Use `/dw-run` for all pending tasks, `/dw-run <task-id>` for one, and `/dw-run --resume` to continue. Inputs are the task ID and active `.dw/spec/<prd>/` directory. Tasks and dependencies must exist and be approved. For investigation without a plan use `/dw-bugfix`.
 
-## Pipeline Position
-**Predecessor:** `/dw-plan` (with tasks approved) | **Successor:** `/dw-review` then `/dw-commit` + `/dw-generate-pr`
+## Assignment and preparation
 
-## Modes
+Read `.dw/references/execution-contract.md` and the relevant task file. Consume `execution-plan.json` when present; validate it with `node .dw/scripts/lib/workflow-contract.mjs validate <plan.json>`. Cross-check IDs/dependencies against tasks.md. Legacy schema 1.0 tasks without assignments execute locally. Never infer cross-tool authorization from installed CLIs alone.
 
-| Invocation | Behavior |
-|------------|----------|
-| `/dw-run` | **Default.** Executes ALL pending tasks from `tasks.md` in dependency order. Wave-based parallel dispatch for independent tasks. Atomic commit per task. After all complete, runs Level 2 review (PRD compliance). |
-| `/dw-run <task-id>` | Executes ONE specific task by ID (e.g., `1.0`, `2.3`). Includes Level 1 validation. Atomic commit on success. |
-| `/dw-run --resume` | Resumes an interrupted multi-task plan from where it stopped. Reads `.dw/spec/<prd>/active-session.md` if present; otherwise continues from first pending task. |
+Respect applicable constitution decisions and the task's requirement IDs (`FR-N.M` / `RF-N.M`). Missing constitution uses non-blocking defaults. Inspect relevant source and project rules; query `.dw/intel/` only when useful and check freshness. Do not require a full repository map before every task.
 
-## Inputs
+Load skills by need: `dw-verify` for evidence, `dw-memory` for relevant durable decisions/checkpoints, `dw-testing-discipline` when designing tests, `dw-ui-discipline` for UI, `dw-llm-eval` for AI behavior, `dw-execute-phase` for dependency/plan checks. Use `dw-search-first` for new dependencies and `dw-minimalism` for a concrete abstraction/scope decision, not before each new function. Use `dw-simplification` for an explicitly scoped cleanup after verification. For explicitly requested TDD/test first/red-green-refactor, use `dw-testing-discipline/references/tdd-loop.md` for that task.
 
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `{{TASK_ID}}` | Specific task identifier (optional — defaults to all pending) | `1.0`, `2.3`, `5.1` |
-| `{{PRD_PATH}}` | Path to PRD directory containing tasks (optional — auto-detect from active branch) | `.dw/spec/prd-invoice-export` |
+## Execution loop
 
-## Complementary Skills
+1. Arm `/dw-report` once (idempotent, skipped when `DW_REPORT_AUTO=off`). Validate task coverage, dependency graph and acceptance checks using `dw-execute-phase`; repair internal inconsistencies before execution, ask only for missing material decisions.
+2. Choose the next task whose dependencies are complete on the execution branch. Independent tasks may run concurrently only with approved agents/worktrees and a defined integration path. One writer per worktree; coupled tasks stay sequential.
+3. Use the approved task executor/model/effort/agents. Local assignments execute in the current workflow. Cross-tool assignments invoke `/dw-codex-run`, `/dw-claude-run`, or `/dw-copilot-run` with the prepared task packet. The parent owns the objective throughout.
+4. Implement acceptance criteria with project patterns, tests from the approved strategy and necessary failure handling. When a worker returns, independently inspect diff and criteria; inspect/reuse valid evidence or run affected checks through `dw-verify`. Fix in-scope failures automatically, using the same external session when applicable.
+5. Commit only scoped task changes after valid verification; retain atomic commits and requirement IDs. Include task status in the commit, then record its SHA in the `Commit` column of tasks.md and run-log.md. Commit remaining bookkeeping in the next task or final metadata commit; never `git add .` across unrelated changes.
+6. Update `execution-state.json`, `active-session.md` and run-log.md with completed tasks, assignments, branch/worktree, exact sessions, verification and next step. Continue remaining approved tasks; `--checkpoint` explicitly requests a pause between waves.
+7. After all tasks, run `/dw-review` for requirement coverage and code quality. Correct in-scope findings automatically; user decisions are needed only for scope changes or deferrals. Full implementation workflows continue to applicable `/dw-qa` and fixes under `/dw-goal` or the invoking orchestrator. A single-task request ends after that task's validated handoff.
 
-When available under `./.agents/skills/`, these skills are invoked per task:
+## Resume and blockers
 
-- `dw-verify`: **ALWAYS** — before each task's commit, produces a Verification Report (test + lint + build all GREEN). Without PASS, no commit. The Iron Law of verification.
-- `dw-memory`: **ALWAYS** — reads workflow memory at task start; updates at task end with the promotion test (lessons that apply to next task get promoted to shared MEMORY.md).
-- Instincts (lazy): at task start, also load any high-confidence instinct (`.dw/memory/instincts/`, confidence ≥0.7) whose `trigger` matches the task — learned project conventions promoted by `/dw-learn`. Match by trigger only; never bulk-load the set.
-- `dw-execute-phase`: provides `plan-checker` (6-dimension goal-backward verification before any code is touched in plan mode) and `executor` (atomic commit + deviation handling) agents.
-- `dw-testing-discipline`: applies the placement doctrine, 6 agent guardrails, and 25 anti-patterns when adding tests during the task.
-- `dw-testing-discipline` test-first mode: ONLY when the task text or user explicitly says `TDD`, `test first`, or `red-green-refactor`, execute that task through `references/tdd-loop.md` (confirm public seams with the user → write ONE red test → run and observe red → implement minimum green → run and observe green → next slice; refactor only after the loop via `dw-simplification`). This is not the default `/dw-run` mode.
-- `dw-ui-discipline`: when the task touches UI, the 4 grounding questions must be answered before any visual decision lands.
-- `dw-llm-eval`: when the task touches AI feature code paths, the reference dataset + oracle ladder rules apply.
-- `dw-minimalism`: **before writing new code** — climb the YAGNI decision ladder (need it? reuse? stdlib? native? installed dep? one line?) at the active intensity, then write the minimum. Hands new dependencies to `dw-search-first`.
-- `vercel-react-best-practices`: when the task touches React/Next.js performance.
+A resume request already authorizes continuation. Inspect saved state and actual worktree rather than asking “continue?” again. Keep completed tasks and approved assignments; validate dependencies and prior evidence. Recover missing session IDs only from task-specific logs with identity checks; otherwise reconstruct a new session in the same worktree without discarding changes. See execution-contract for cross-provider limitations.
 
-## Constitution Gate
+Missing dependency: finish its pending approved task first; ask only if it is outside the plan. Verification failure: diagnose, fix and rerun invalidated checks. Missing test framework: discover the configured runner before asking. Increased complexity: record a deviation and split/reorder within approved scope. New product behavior, architectural conflict or unapproved dependency: propose the material change and wait only on dependent work. Preserve checkpoints at a real impasse or user pause.
 
-<critical>BEFORE executing any task, check `.dw/constitution.md`. If MISSING, auto-install defaults via the v0.11 pattern. If PRESENT, the task's `Constitution Alignment` line (set during `/dw-plan` Stage 3) is consulted as the task executes — code must respect the claimed principles.</critical>
-
-## Codebase Intelligence
-
-<critical>If `.dw/intel/` exists, query it via `/dw-intel` before implementation to align with existing patterns.</critical>
-- Per-task: `/dw-intel "patterns for <task topic>"` to surface relevant conventions.
-
-## Mode 1: ONE task (`run <task-id>`)
-
-### Prerequisites
-- `tasks.md` + per-task files exist in `.dw/spec/<prd>/`.
-- The target task's dependencies are completed (check `task.md` "Depends on" section).
-
-### Behavior
-
-1. **Read the task file:** `.dw/spec/<prd>/<task-id>_task.md`. Understand inputs, FRs covered, acceptance criteria, subtasks.
-2. **Plan implementation:**
-   - List files to create/modify.
-   - Identify test additions per subtask.
-   - Confirm dependencies (if missing, STOP and surface).
-3. **Implement:**
-   - Follow project patterns from `.dw/rules/` and `.dw/intel/`.
-   - Apply complementary skills (UI gate, test discipline, etc.).
-   - Mandatory unit tests for backend/services per testspec.
-   - Match the testing framework specified in `.dw/rules/`.
-4. **Validate (Level 1):**
-   - Run the project's test command.
-   - Check acceptance criteria from the task file.
-   - Run `dw-verify` to produce the Verification Report (test + lint + build GREEN).
-   - For interactive frontend, also validate real behavior via `dw-testing-discipline` Playwright recipes if regression risk is meaningful.
-5. **Commit:**
-   - Atomic commit message: `feat(<scope>): <task title> (#<task-id>)`.
-   - Reference the FRs covered.
-   - One task = one commit (unless the task explicitly has subtask milestones that earn separate commits).
-6. **Update tasks.md:** set this task's `Status` to `Done` and write the short SHA (`git rev-parse --short HEAD`) into its `Commit` column. This is the only record linking a task to its diff — do not skip it.
-7. **Report:** what was done, what tests were added, what was validated.
-
-### STOP CONDITIONS
-- Dependencies not satisfied → ask user how to proceed.
-- Verification Report FAIL → do not commit; report what's broken.
-- Task scope creep detected mid-implementation → STOP and ask user to scope.
-
-## Mode 2: ALL pending tasks (default `run`)
-
-### Prerequisites
-- `tasks.md` + per-task files exist with declared dependencies.
-- `tasks-validation.md` shows PASS (or explicit override).
-- The branch is created: `feat/prd-<feature-slug>`.
-
-### Behavior
-
-0. **Arm the progress loop:** invoke `/dw-report` (auto-arm contract — idempotent when `.dw/reports/.active.json` is already live; skipped when `DW_REPORT_AUTO=off`). It reports done / doing / remaining every 10 minutes while the waves run and disarms itself with a final report after the final Level 2 review.
-1. **Plan check (via `dw-execute-phase/plan-checker` agent):**
-   - 6-dimension goal-backward verification: are these tasks actually going to deliver what the PRD promises?
-   - If FAIL on any dimension, STOP and report to user before any code is touched.
-2. **Build dependency graph:**
-   - Topological sort of tasks.
-   - Identify independent tasks that can run in parallel waves.
-3. **Wave-based parallel dispatch (via `dw-execute-phase/executor` agent):**
-   - Each wave contains tasks with no inter-dependencies.
-   - Execute waves serially; within a wave, tasks dispatch in parallel.
-   - Per-task: same Level 1 flow as Mode 1 (implement → validate → atomic commit).
-4. **Deviation handling:**
-   - If a task encounters scope creep, STOP that task, surface to user.
-   - If a task fails verification, the wave halts. No subsequent waves run until resolved.
-5. **Checkpoint between waves:**
-   - Print wave summary: tasks completed, commits, any deviations.
-   - Continue automatically unless `--checkpoint` was passed (then wait for user OK).
-6. **Final Level 2 review:**
-   - After all tasks complete, automatically invoke `/dw-review` (the merged review command — runs both PRD compliance check and code quality review).
-   - Present consolidated review report.
-   - Interactive corrections cycle: review surfaces gaps → user decides to fix, defer, or accept.
-
-### Output
-
-```
-.dw/spec/<prd>/
-├── active-session.md      # written at checkpoint; consumed by --resume
-├── run-log.md             # per-wave execution log with commit SHAs
-└── review-consolidated.md # final L2+L3 review (from /dw-review)
-```
-
-## Mode 3: Resume (`run --resume`)
-
-### Prerequisites
-- Previous `run` (Mode 2) was interrupted.
-- `active-session.md` exists in the current PRD's `.dw/spec/<prd>/` directory.
-
-### Behavior
-
-1. Read `active-session.md` to determine which task/wave the session stopped at.
-2. Surface to user: "Resuming from wave N, task X.0. Previously completed: <list>. Continue?"
-3. On confirmation, resume from the next pending task with the same Mode 2 behavior (including step 0 — arm `/dw-report`).
-
-If `active-session.md` doesn't exist but uncompleted tasks remain, treat as Mode 2 fresh start.
-
-## Across all modes: deviation handling
-
-When implementation cannot proceed as planned:
-
-| Deviation | Action |
-|-----------|--------|
-| Task requires new dependency not in TechSpec | STOP. Suggest `/dw-plan techspec --update` to revise. |
-| Acceptance criterion is ambiguous | STOP. Ask user for clarification. |
-| Test framework decision missing | STOP. Use `dw-testing-discipline` placement doctrine to propose; ask for sign-off. |
-| Pattern from `.dw/rules/` doesn't fit cleanly | STOP. Surface the friction; propose either an ADR-justified deviation or a rules update. |
-| Hidden complexity emerges (task estimated 2h, looks like 8h) | STOP. Surface; either split the task via `/dw-plan tasks --update` or accept the delay with note. |
-
-## Reporting
-
-After every run (Mode 1, 2, or 3 completion), print:
-
-- Tasks completed with commit SHAs.
-- Files touched count.
-- Tests added (unit + E2E if applicable).
-- Verification Report verdict per task.
-- For Mode 2: final consolidated review status.
-- For Mode 2: any deviations encountered and how they were resolved.
-
-## Anti-patterns
-
-- Skipping `dw-verify` to "save time before commit" — produces commits that don't build.
-- Running tasks without dependency satisfaction — produces commits that won't work in isolation.
-- Letting wave-based parallel run without watching for deviations — silent scope creep compounds.
-- Committing multiple tasks in one commit — breaks bisect, breaks revert granularity.
-- Skipping the final Level 2 review in Mode 2 — ships features that don't fully match the PRD.
-
-## Final Guidelines
-
-- Atomic commits are non-negotiable. One task = one commit (or one subtask-bundle if explicit).
-- Tests are mandatory per the testing strategy section of the TechSpec.
-- Verification Report PASS is the gate, not the goal — never weaken assertions to make tests pass.
-- Deviation surfacing is a feature, not a bug. Stop and ask. The user prefers an interruption to a wrong implementation.
-- For multi-day plans, `--resume` is your friend. Don't restart from zero.
+## Completion report
 
+Return completed task IDs and commit SHAs, affected files, valid checks, unresolved findings and next step. `/dw-review` writes `<prd-path>/QA/review-consolidated.md`. Durable state and logs remain in the spec directory; worker audit/session files stay outside disposable worktrees. A passed gate proves its scope only; never weaken assertions or hide a blocking finding. Merge, push and publication require applicable authorization.
 </system_instructions>

package/scaffold/en/commands/dw-skill-health.md

@@ -24,7 +24,14 @@ You are the dev-workflow skill and agent health auditor.
 
 `SKILL.md` should be a short router/protocol. Long rules, examples, palettes, recipes, services, and assets must stay in references/assets/rules/recipes and be loaded lazily.
 
+## Discovery and context budgets
+
+Check managed instructions ≤6000 bytes, skill entrypoints ≤8000 bytes and descriptions ≤250 characters. In package source run `npm run validate`; in consumers inspect installed files. Distinguish discovery metadata from on-demand bodies. Flag unconditional reference loading and broad overlapping triggers, not every platform copy as duplicate live context. Check routed reference paths and preserve attribution/Structured Return when compacting. Model candidates may be stale: propose updates to routing.json after verifying availability; never overwrite owner choices silently.
+
 ## Output
+
+When `.dw/config/routing-defaults.json` exists, compare its current candidates with the owner's `.dw/config/routing.json`. Report relevant differences and validate proposed models/capabilities before adoption. Different values can be intentional; do not treat them as failed migration or overwrite them automatically. Approved task assignments take precedence over either candidate file.
+
 Return a concise health report with a structured-return section. Do not delete files.
 
 Include:

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

@@ -38,7 +38,7 @@ Keep only the 3 most recent snapshots (remove older ones) to avoid buildup.
 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
+node -e 'try { const s = JSON.parse(require("node:fs").readFileSync(".dw/install-state.json", "utf8")); console.log(s.version || "unknown"); } catch { console.log("unknown"); }'
 ```
 
 ### 2. Detect Language of Installed Commands (Required)
@@ -71,7 +71,7 @@ Rules:
 
 ### 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>
+<critical>Use `npx -y @brunosps00/dev-workflow@latest` to select the version tagged `latest` on npm. Pass `--lang=<DETECTED_LANG>` to skip the interactive prompt.</critical>
 
 ```bash
 npx -y @brunosps00/dev-workflow@latest update --lang=$DETECTED_LANG
@@ -90,9 +90,23 @@ If the update fails (network error, permission, package unavailable): report the
 ### 4. Capture New Version
 
 ```bash
-node -e "console.log(require('@brunosps00/dev-workflow/package.json').version)" 2>/dev/null
+node -e 'const s = JSON.parse(require("node:fs").readFileSync(".dw/install-state.json", "utf8")); if (s.package !== "@brunosps00/dev-workflow" || !s.version) process.exit(1); console.log(s.version);'
 ```
 
+### Upgrade compatibility checks
+
+Read the refreshed `.dw/commands/dw-update.md` after the CLI completes. Use `.dw/install-state.json` and the CLI's `Installed version` output for the version delta: an `npx` package need not be resolvable from the consumer's `node_modules`. A missing or invalid new install state is a failed verification; do not claim the update succeeded.
+
+For an upgrade from before 2.3.0 (or an unknown legacy version):
+
+- Verify `.dw/references/execution-contract.md`, `.dw/scripts/lib/workflow-contract.mjs` and `.dw/templates/frontend-quality-template.md` were delivered. Managed commands, skills, wrappers and instruction blocks refresh through normal `update`; no `--force` is needed.
+- Compare `.dw/config/routing.json` with the newly managed `.dw/config/routing-defaults.json` during `/dw-skill-health`. Keep active owner choices and approved assignments. Propose specific model/effort changes after checking capabilities; updating scaffold files alone does not authorize changing providers.
+- Preserve `.dw/spec/`, `.dw/goals/`, `.dw/STATE.md`, execution/session state, rules and `.dw/templates/overrides/`. Schema 1.0 plans remain valid and local by default. For an active `execution-plan.json`, run `node .dw/scripts/lib/workflow-contract.mjs validate <plan-path>`; report invalid plans without rewriting approvals or resetting progress. New task plans use schema 1.1.
+- Inspect task template overrides for old schemas/routing rules and report any differences that shadow the new managed templates; do not replace owner overrides automatically.
+- If frontend quality documentation is relevant and missing, have `/dw-analyze-project` add the baseline to the existing module rules, scoped to that documentation. Preserve existing gates; propose tooling separately. Skip this action for `update files only`.
+
+Do not force-convert active work or globally regenerate product documentation to adopt the release. Record compatibility findings and retain session reload as the final step.
+
 ### 5. Report Result
 
 Present to the user:
@@ -156,7 +170,7 @@ 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
+- `@latest` selects the registry tag; verify the installed result rather than assuming a local package lookup identifies the executed CLI
 - `--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
 

package/scaffold/en/references/command-routing.md

@@ -0,0 +1,53 @@
+# Command routing
+
+Use the installed root routing rules first. Consult this catalog only to locate a specialized command. A command suggestion is not authorization to publish, merge, or start an unrelated workflow.
+
+## Trigger Map
+
+| User intent (literal or paraphrased) | Auto-trigger |
+|--------------------------------------|--------------|
+| "Implement X" / "Build Y" / "Add feature Z" / "I need ..." / "Create ..." | `/dw-plan` / `/dw-autopilot` |
+| "Autopilot this PRD" / "Take this PRD to PR" / continue a bugfix escalation autonomously | `/dw-autopilot --from-prd <slug>` (existing PRD at `.dw/spec/<slug>/`) |
+| "Resume autopilot" / "continue after plan" / `autopilot-state.json` has `status: plan_complete` | `/dw-autopilot` (or `/dw-goal --from-autopilot <slug>` if the user specifically asks for the goal step) |
+| Pasted error / "X is broken" / "Bug in Y" / failing test screenshot | `/dw-bugfix "X"` |
+| "Plan this feature" / "Write a PRD + techspec + tasks" | `/dw-plan "X"` |
+| "Write a PRD for X" / "Spec out Y" | `/dw-plan prd "X"` |
+| "Design the architecture" / "Make the techspec" | `/dw-plan techspec` |
+| "Break this into tasks" | `/dw-plan tasks` |
+| "Run this task" (with task ID) | `/dw-run <ID>` |
+| "Run all pending tasks" / "Execute the plan" | `/dw-run` |
+| "Run this as a goal" / "durable goal" / "long-running objective" | `/dw-goal "<objective>"` |
+| "Continue where I left off" | `/dw-run --resume` |
+| "Pause work" / "End the session" / "Save where we are" | `/dw-pause` |
+| "Report every N minutes" / "Keep me posted while this runs" / "Give me status reports" | `/dw-report [--every <N>m]` |
+| "Create a worktree for X" / "Clean up the worktrees" / "Merge worktree X" / "How many worktrees are left?" | `/dw-worktree create <slug>` / `/dw-worktree clean --apply` / `/dw-worktree merge <slug>` / `/dw-worktree list` |
+| "Resume" / "Where did we stop?" / "Pick up where we left off" | `/dw-resume` |
+| "QA this feature" / "Run the test plan" | `/dw-qa` |
+| "Fix the QA bugs" | `/dw-qa --fix` |
+| "Evaluate the AI feature" / "Test the RAG / classifier" | `/dw-qa --ai` |
+| "Walk me through this feature" / "UAT this with me" / "Let's do a manual run-through" | `/dw-qa --uat` |
+| "Review this bugfix" / "Code-review fix `<slug>`" | `/dw-review --bugfix <slug>` |
+| "QA this bugfix" / "Validate fix `<slug>`" | `/dw-qa --bugfix <slug>` |
+| "Review my PR" / "Check code quality" / "Is this ready to ship?" | `/dw-review` |
+| "Just the PRD coverage check" | `/dw-review --coverage-only` |
+| "Just the code quality review" | `/dw-review --code-only` |
+| "Time to commit" / changes are validated and ready | `/dw-commit` |
+| "Open a PR" / "Ship this" | `/dw-generate-pr` |
+| "Suggest new ideas" / "What should we build next?" / "Find opportunities" / "Roadmap ideas" | `/dw-opportunities` |
+| "What security improvements should we consider?" / "Find security opportunities" | `/dw-opportunities "security"` |
+| "Brainstorm X" / "Explore this idea" / "Research X" | `/dw-brainstorm "X"` (auto-dispatches grill / prototype / council / research / onepager based on signals) |
+| "Code-health audit" / "Find tech debt" / "Refactor opportunities" / "Smells in X" | `/dw-refactor "X"` |
+| "Where is X?" / "What uses Y?" / "How is Z structured?" | `/dw-intel "<question>"` |
+| "Rebuild the codebase index" / "Refresh intel" | `/dw-intel --build` |
+| "Context is heavy" / "Audit token usage" / "Why is the agent slow?" | `/dw-context-budget` |
+| "Check dev-workflow install" / "Are agents/wrappers healthy?" | `/dw-harness-audit` |
+| "Audit skills" / "Skills feel duplicated or bloated" | `/dw-skill-health` |
+| "Redesign this UI" / "Audit and ship a new design" | `/dw-redesign-ui "<target>"` |
+| "Audit dependencies" / "Are we behind on packages?" | `/dw-secure-audit --plan` |
+| "Scan for vulnerabilities" / "Security check" | `/dw-secure-audit` |
+| "Analyze this project" / "Generate rules" | `/dw-analyze-project` |
+| "Open a new project" / "Bootstrap a stack" | `/dw-new-project` |
+| "Dockerize this" / "Add docker-compose" | `/dw-dockerize` |
+| "Functional doc" / "Map screens and flows" | `/dw-functional-doc` |
+| "Install Azure skills" / "Setup Microsoft docs MCP" / "Add Azure expertise" / "I'm going to work on Azure" | `/dw-install-azure-skills` |
+| "Install AWS skills" / "Setup AWS MCP" / "Add AWS expertise" / "I'm going to work on AWS" | `/dw-install-aws-skills` |

package/scaffold/en/references/execution-contract.md

@@ -0,0 +1,55 @@
+# Task execution contract
+
+Read during task breakdown, dispatch, or resume. The parent coordinates the approved plan through validation; runner return is a handoff, not the end of the objective.
+
+## Planning assignments
+
+Choose development locally or across tools at `/dw-plan tasks`, not on every dispatch. Present a task matrix with complexity, rationale, tool, model, effort, agents, dependencies, and checks. Use `light` for mechanical low-risk work, `standard` for known patterns with bounded decisions, and `heavy` for architecture, uncertainty, or sensitive surfaces. File counts and commit types alone do not determine complexity.
+
+Use `.dw/config/routing.json` as model candidates, not proof of availability. Inspect installed CLI version/help for flags and supported configuration; use provider documentation or available model metadata for model IDs. Help/version alone does not prove authentication or account access. Preserve explicit model choices. Prefer configured models that satisfy the task; propose upgrades when useful, citing source/date. Local agents inherit the current session model unless an explicit task override is supported and approved. Do not choose an arbitrary different tier just to call a review independent.
+
+Claude orchestration can propose `codex` (`/dw-codex-run`), Codex can propose `claude` (`/dw-claude-run`). Copilot/OpenCode retain local execution and may use explicitly selected adapters. Keep coupled/small work local unless the user chooses otherwise. Use only installed, relevant agents; no mandatory fan-out. Validate agent names against `.dw/agent-registry.json` and the installed profiles.
+
+Alongside tasks.md and the per-task Markdown, write `execution-plan.json`:
+
+```json
+{
+  "schema_version": "1.1",
+  "approved": false,
+  "tasks": [{
+    "id": "1.0",
+    "depends_on": [],
+    "execution": {
+      "complexity": "standard",
+      "rationale": "Known service pattern; bounded behavior change",
+      "tool": "local",
+      "model": "inherit",
+      "effort": "inherit",
+      "agents": [],
+      "fallbacks": []
+    }
+  }]
+}
+```
+
+For external tools resolve concrete model/effort before approval. Fallback entries contain `tool`, `model`, `effort`; only approved alternatives may be used. Validate with `node .dw/scripts/lib/workflow-contract.mjs validate <plan.json>` and cross-check the IDs/dependencies against tasks.md. Mark `approved: true` only after user approval of the same assignments; record the approval in the plan's decision log. Changed assignments require approval unless explicitly requested or covered by an approved fallback. An agent-authored boolean is a record, not independent proof of consent.
+
+Resolution precedence: current explicit user instruction → approved task assignment → project configuration → tool default. For a saved plan, configuration/defaults are used to propose missing assignments, never silently replace approved ones. Model rejection uses an approved fallback or blocks with evidence; no unapproved provider change. Plans at schema 1.0 without execution metadata run locally; do not force a migration or retroactive delegation decision.
+
+## Dependency and worktree ownership
+
+For WRITE dispatch create a dedicated worktree through `/dw-worktree create`. Record its starting revision and branch. Tasks in a dependency chain use the same execution branch/worktree, with one writer at a time, even when successive tasks select different CLIs. The next task sees completed dependency commits on that branch; never create it afresh from main. Use separate worktrees for independent tasks only when the approved plan defines how their branches will be integrated before dependent work. Do not merge into the owner's branch merely to move to the next task.
+
+Stage only scoped changes. Commit implementation and task status together; then record the resulting SHA in tasks.md/run-log (a SHA cannot include itself in its own commit). Include that bookkeeping in the next scoped commit or final metadata commit; leave no unreported dirty bookkeeping at delivery. Do not amend or stage unrelated files automatically.
+
+## Durable state and resume
+
+Persist `execution-state.json` beside the plan, with schema_version `1.1` and a `tasks` object keyed by task ID. Each entry records the approved assignment, worktree, branch/base revision, provider session ID, audit/prompt paths, attempt, status, checkpoint, commit SHA, and verification records. Store audit/session files outside disposable worktrees. Update before dispatch and after every handoff; preserve completed work on interruption.
+
+Resume inspects saved task identity, actual diff, branch, dependencies, and evidence before continuing. Keep the approved executor and session. If its sidecar is absent, recover the exact session from that task's audit log and verify provider/worktree/task identity. Never blindly use `--last` or `-c`. If the ID cannot be recovered, start a new session in the same worktree from the approved task, state, diff and logs; record loss of conversational context. A session from one provider cannot be resumed by another provider. Never reset/clean partial work to retry.
+
+## Completion and authorization
+
+The worker implements and checks its task, then returns evidence and unresolved findings. The parent independently inspects the diff and acceptance criteria, verifies evidence validity, sends in-scope corrections to the same worker, and continues dependencies. No new confirmation is needed for an already approved run/resume or ordinary corrections. Only material scope changes, unavailable approved alternatives, permission restrictions, and unresolved product/architecture decisions block dependent work; continue independent authorized work when possible.
+
+Review quality rests on acceptance criteria and blocking findings, not a numeric score. Reuse verified check output for equivalent inputs/environment/scope; rerun affected checks after edits. Finish required project checks at delivery. Merge, push and publication remain separate authorization boundaries. Without that authorization, report the prepared branch/worktree and validated result.

package/scaffold/en/templates/frontend-quality-template.md

@@ -0,0 +1,43 @@
+---
+type: frontend-quality
+schema_version: "1.0"
+status: draft
+---
+
+# Frontend quality baseline
+
+Use for a requested frontend audit or quality-tooling plan. Embed in the existing `.dw/rules/<module>.md` for an audit, or in the feature's TechSpec for implementation. A feature needs only affected rows. This template records decisions; it does not configure tools or authorize new gates.
+
+- Module and scope: [workspace, runtime entry points, relevant diff]
+- Observed at: [revision plus working-tree changes, date]
+- Stack: [framework/compiler/runner/package-manager versions, lockfile]
+- Existing policy: [instructions, rules, scripts and CI paths]
+
+## Controls
+
+Keep observation and proposal separate. Preserve existing required checks. Policy values: `required`, `advisory`, `deferred`, `not_applicable`. An unadopted proposal is `deferred`; record execution separately as `passed`, `failed` or `not_run`. Explain exclusions and missing evidence. Do not mark missing tools as passed or silently enforce a proposed gate.
+
+| ID | Risk/control to inspect | Observed configuration and gaps | Policy / proposed change | Exact command, cwd and scope | Evidence / execution |
+|---|---|---|---|---|---|
+| contract | API authority, generated client drift, runtime validation | | | | |
+| types | Effective TypeScript strictness and unsafe escapes | | | | |
+| lint | Relevant framework, test and accessibility diagnostics | | | | |
+| boundaries | Allowed imports, server/client separation, production entry points | | | | |
+| custom-rules | Repeated defect, detector fixtures and actionable errors | | | | |
+| feedback | Discoverable local rules and optional hook feedback | | | | |
+| mutation | Critical behavior, survivor investigation and cache validity | | | | |
+| dead-code | Runtime/public reachability, generated files, reviewed exclusions | | | | |
+| duplication | Shared business rules versus intentional repeated markup | | | | |
+| ci | Required jobs, observable failures, deploy dependencies and repository rules | | | | |
+
+## Adoption and validation
+
+- Next change: [risk it removes, files/config to change, compatible tool already present or proposed dependency]
+- Existing debt: [baseline location; keep it distinct from newly introduced defects]
+- Promotion condition: [evidence needed to move advisory to required; decision owner]
+- Exceptions: [specific rule/path, reason, owner and review trigger; no blanket exclusions]
+- Detector checks: [deliberately invalid fixture, legitimate fixture, alias/generated-path cases and unsupported cases]
+- Analysis limits: [not executed, unavailable service, incomplete graph or CI/repository settings not inspected]
+- Delivery checks: [required commands and behavioral acceptance; reuse evidence only for equivalent inputs/environment/scope]
+
+For operational guidance, read `dw-ui-discipline/references/frontend-engineering.md` from the installed skills location. Put accepted implementation work in the task execution matrix; continue under existing authorization. An audit alone ends with the documented findings and proposed changes.

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

@@ -1,72 +1,52 @@
 ---
 type: task
-schema_version: "1.0"
+schema_version: "1.1"
 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>
+Read the relevant PRD/TechSpec sections and task constraints; use the links below.
 
 ## Overview
 
 [Brief task description]
 
-**Functional Requirements covered**: FR-X.Y, FR-X.Z (maximum 2 per task)
+**Functional Requirements covered**: FR-X.Y, FR-X.Z
 Depends on: none
 
 <requirements>
 [List of mandatory requirements]
 </requirements>
 
-## Subtasks
+## Execution assignment
 
-### Implementation
-- [ ] X.1 [Subtask description]
-- [ ] X.2 [Subtask description]
+Mirror this task's approved entry in `execution-plan.json` (see `.dw/references/execution-contract.md`).
 
-### Unit Tests (Mandatory for Backend)
-- [ ] X.3 Create tests for [service/use-case]
-- [ ] X.4 Create tests for [controller/adapter]
+| Complexity + rationale | Tool | Model / effort | Agents | Approved fallbacks |
+|---|---|---|---|---|
+| standard — [reason] | local | inherit / inherit | none | none |
 
-## Unit Tests
+## Implementation
 
-### Test Cases
+- [ ] [Behavior to deliver]
+- [ ] [Relevant verification and acceptance checks]
 
-| Method | Cases |
-|--------|-------|
-| `[method1]` | Happy path, edge case, error |
-| `[method2]` | Happy path, not found |
+## Verification and success criteria
 
-### Required Mocks
-- `[repository/service]` - mocked via mock function
+| Behavior / risk | Existing suite or new test | Command / observable evidence |
+|---|---|---|
+| [Required outcome] | [Lowest effective layer; new test only if needed] | [Project command or inspection] |
 
-## Implementation Details
+Use the project's test strategy. Define mocks only at justified boundaries; do not impose coverage percentages or a new test for every edit. Include important failure cases where applicable.
 
-[Relevant sections from the tech spec - reference techspec.md instead of duplicating content]
+## Relevant files and decisions
 
-## Success Criteria
+[Source paths and relevant TechSpec/ADR sections; do not duplicate entire documents.]
 
-- [Measurable outcomes]
-- [Quality requirements]
-- **Unit tests passing**
-- **Minimum 80% coverage** on services/use-cases
+## Commit on completion
 
-## Relevant Files
-- [Files relevant to this task]
-- [File].spec.ts - Unit tests
-
-## Commit on Completion
-
-When completing this task, commit:
-```bash
-git add .
-git commit -m "feat([module]): [description]
-
-- [item 1]
-- [item 2]
-- Add unit tests"
-```
+Use the scoped atomic commit protocol in `/dw-run`. Stage only this task's files, retain requirement IDs, record the resulting SHA in tasks.md/run-log, and include final bookkeeping before delivery. No push or merge is implied.
 
 ## Related ADRs
 

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

@@ -1,6 +1,6 @@
 ---
 type: tasks-index
-schema_version: "1.0"
+schema_version: "1.1"
 status: draft
 ---
 
@@ -34,10 +34,13 @@ feat/prd-[feature-name]
 - [ ] 2.0 Main Task Title        Depends on: 1.0
 - [ ] 3.0 Main Task Title        Depends on: 1.0, 2.0
 
+## Execution plan
+
+Propose local or cross-tool development per task during breakdown. Summarize complexity/rationale, tool, model/effort, agents, dependencies and verification. Store validated assignments and approved fallbacks in `execution-plan.json`; use `.dw/references/execution-contract.md`. Record approval of the same matrix before execution.
+
 ## Workflow
 
-Each task follows this flow:
-1. `/execute-task [N]_task.md` - Implements the task
-2. Unit tests included in the implementation
-3. Commit at the end of each task (no push)
-4. Next task or `/dw-generate-pr [target-branch]` when all tasks are completed
+1. `/dw-run` consumes the approved assignments in dependency order.
+2. Each task implements, verifies and commits scoped changes; the parent reviews external-worker handoffs and routes corrections.
+3. Continue approved implementation through final review and applicable QA. A planning-only request ends at the plan.
+4. Prepare the validated delivery; integrate/push/publish only within existing authorization.

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

@@ -78,6 +78,10 @@ type ServiceName interface {
 
 ## Development Sequencing
 
+### Frontend Quality (when applicable)
+
+[Read the module's existing quality baseline. Use relevant rows from `.dw/templates/frontend-quality-template.md` for changed API contracts, types, import boundaries or quality tooling. Record authoritative sources, exact checks, current policy, proposed adoption and behavioral evidence. Keep advisory diagnostics distinct from required gates; do not expand a UI feature into a repository-wide tooling migration.]
+
 ### Build Order
 
 [Define implementation sequence: