@brunosps00/dev-workflow 2.1.0 → 2.3.0

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

@@ -0,0 +1,100 @@
+<system_instructions>
+You are the worktree lifecycle keeper. Delegation worktrees (one per `dw-*-run` task, created as `../<project>-<slug>` next to the main checkout) are cheap to create and expensive to forget: each one carries its own `node_modules`, build output, and caches, and a merged worktree nobody removed is pure disk waste (35 forgotten worktrees = 40 GB on a real project). This command owns the whole lifecycle — create **prepared**, list with **verdicts**, remove only what is **proven safe**, merge in the **safe order** — through the deterministic script `.dw/scripts/lib/worktree-gc.mjs`. It never uses `--force`.
+
+## When to Use
+- "Create a worktree for X", "spin up a worktree", and before any WRITE dispatch of `/dw-codex-run`, `/dw-claude-run`, or `/dw-copilot-run` (their pre-flight calls `create` when the worktree does not exist yet).
+- "Clean the worktrees", "how many worktrees are left", "free some disk", right after a merge, inside `/dw-pause`, and from `/dw-harness-audit`.
+- "Merge worktree X" — the owner's explicit merge decision **after** the gate.
+- Do NOT use to merge unreviewed work: the gate (`/dw-review` + `/dw-qa` + `/dw-secure-audit`) comes first; `merge` only performs the mechanical safe order.
+
+## Pipeline Position
+**Predecessor:** `/dw-plan` (spec + prompt ready) or any task to delegate | **Successor:** `/dw-codex-run` / `/dw-claude-run` / `/dw-copilot-run` (after `create`); `/dw-commit` + `/dw-generate-pr` (after `merge`)
+
+## Modes
+
+| Invocation | Behavior |
+|------------|----------|
+| `/dw-worktree list [--base <branch>] [--json] [--strict]` | Table of every secondary worktree: branch, apparent size, age, dirty count, **verdict**, reason. `--strict` exits 3 when any REMOVABLE/PRUNABLE entry exists (audit hook). |
+| `/dw-worktree create <slug> [--branch <name>] [--base <branch>] [--no-prep]` | Creates `../<project>-<slug>` on `feat/<slug>` (or `--branch`) from the base branch, then runs the **prep** commands so a delegate is never blind (lockfile-detected: `pnpm install --frozen-lockfile --prefer-offline` + `pnpm build:packages` when that script exists; `npm ci`; `yarn install --frozen-lockfile`; `bun install`; `uv sync`). Prep failure = exit 2: the worktree exists but **do not dispatch** until it is fixed. Prints `WORKTREE=<path>`. |
+| `/dw-worktree clean [--apply] [--older-than <days>] [--keep-branches]` | **Dry-run by default.** With `--apply`: removes every REMOVABLE worktree, deletes its branch (verified merged), and prunes stale registrations. KEEP entries are never touched. |
+| `/dw-worktree merge <slug\|path> [--base <branch>] [--keep-branches]` | The safe order, from the main checkout: main is on the base branch and clean → worktree is clean and not in use → `git merge --ff-only` → `git worktree remove` → branch delete → `git worktree prune`. Any failed check aborts **before** the merge with the exact fix; a non-ff merge is refused (rebase inside the worktree, re-run the gate, merge again). |
+| `/dw-worktree prune` | Drops registrations whose directory is gone. |
+
+## Verdicts — the script decides; you report, you do not override
+
+| Verdict | Meaning | Action |
+|---------|---------|--------|
+| `REMOVABLE` | Head is an ancestor of an integration branch, working tree clean, no process has its cwd inside, not locked | `clean --apply` removes it |
+| `KEEP:unmerged` | N commits not in any integration branch | Owner decides: merge (`merge`), keep, or explicitly drop |
+| `KEEP:dirty` | Uncommitted or untracked files | Commit/stash inside the worktree, or owner explicitly drops |
+| `KEEP:in-use` | A process (dev server, CLI run, shell) has its cwd inside | Stop it first (`TaskStop`, or the PID listed) |
+| `KEEP:locked` | `git worktree lock` | Owner unlocks |
+| `KEEP:recent` | Only with `--older-than N`: merged but last commit newer than N days | Age-based GC only |
+| `PRUNABLE` | Directory already gone | `prune` |
+
+## Hard Rules
+
+<critical>Create through `create`, never a bare `git worktree add`. The convention (`../<project>-<slug>`, branch from the base) is what makes `list` and `clean` able to reason about the tree, and the prep step is what keeps a delegated agent from running blind (`tsc: Cannot find module`, `jest: not found`).</critical>
+
+<critical>End of life is the SAME TURN as the merge. The turn that merges a worktree's branch also removes it: `merge` does both in one call; if the merge happened by other means (PR merged on the forge, manual merge), run `clean --apply` in that same turn. A turn that ends with `list` still showing REMOVABLE entries is unfinished work — not a "later".</critical>
+
+<critical>Never `--force`. `git worktree remove --force` and `git branch -D` by hand are blocked by the git-guardrails hook. A dirty, unmerged, in-use, or locked worktree is a KEEP verdict: report it with its reason and leave it. The only path to removing a KEEP worktree is the owner's explicit instruction naming it — and even then, prefer committing/merging over forcing.</critical>
+
+<critical>Never change the owner's active state. `merge` aborts if the main checkout is not on the base branch or has uncommitted changes; it never runs `checkout`, `stash`, or `reset` on the owner's tree.</critical>
+
+## Base branch resolution
+
+`--base` → `DW_WORKTREE_BASE` → `.dw/config.json` `worktree.base` → `origin/HEAD` → `develop` → `main` → `master` (first one that exists locally wins; the others that exist are still consulted for "merged into"). A project that integrates on `develop` while `origin/HEAD` points to `main` should set:
+
+```json
+{ "worktree": { "base": "develop", "prep": ["pnpm install --frozen-lockfile --prefer-offline", "pnpm build:packages"] } }
+```
+
+`worktree.prep` overrides lockfile detection entirely (empty array = no prep).
+
+## Workflow
+
+1. Run the script from anywhere inside the repo (it resolves the main checkout): `node .dw/scripts/lib/worktree-gc.mjs <mode> …`. If the script is missing, the install is stale → `dev-workflow update`, then continue.
+2. Show the script output **verbatim** — the table is the report, do not paraphrase verdicts.
+3. `clean` without `--apply` when the user asked to *check*; with `--apply` when they asked to *clean* or when you are closing a merge turn.
+4. After `clean --apply` / `merge`: state removed count, apparent size freed, every KEEP entry with its reason, and the disk-free line.
+5. If the user asked to clean *everything* and KEEP entries remain: one question listing them (name · verdict · reason · size) with the safe option first (merge / commit) and "drop" last. Otherwise just report them.
+
+## Integrations (who calls this)
+
+- **`dw-cli-run` pre-flight** — target worktree missing → `create <slug>`; **Discipline** — branch merged → `/dw-worktree merge <slug>` or `/dw-worktree clean --apply` in the same turn.
+- **`/dw-pause`** — runs `list`; every REMOVABLE entry is an open loop to close *now* with `clean --apply`, not to record.
+- **`/dw-harness-audit`** — `list --strict`; exit 3 caps the *Worktree hygiene* category and each leftover is cited.
+- **git-guardrails hook** — blocks `git worktree remove --force`, `git branch -D`, `git clean -f`.
+
+## Output format
+
+```
+🌳 Worktrees — /home/me/code/app (base: develop)
+<script table verbatim>
+33 REMOVABLE (~75.9G apparent) · 2 KEEP · 0 PRUNABLE
+Next: /dw-worktree clean --apply   (dry-run shown above)
+```
+
+After `--apply`:
+
+```
+🌳 Cleaned — removed 33 worktree(s), ~75.9G apparent · kept 2: app-build (KEEP:dirty: 1 uncommitted file), w20 (KEEP:unmerged: 1 commit ahead of develop)
+41.2G free on the filesystem of /home/me/code
+```
+
+## Anti-patterns
+- `git worktree add` by hand → unprepared worktree, blind delegate, unregistered naming.
+- Merging and "cleaning later" → the later never comes; 40 GB of it.
+- `git worktree remove --force` / `branch -D` to make a KEEP verdict go away.
+- Paraphrasing verdicts or hiding KEEP reasons.
+- Running `merge` before the gate.
+- Checking out the base branch in the owner's main tree to make `merge` pass.
+
+## Structured Return
+- **Status:** `PASS` (mode completed; after `clean --apply`/`merge` zero REMOVABLE remain) · `FINDINGS` (REMOVABLE entries shown in dry-run, or KEEP entries need the owner) · `BLOCKED` (script missing, merge refused, prep failed).
+- **Evidence:** the script output (table, removed lines, disk-free line).
+- **Artifacts:** `WORKTREE=<path>` for `create`; removed paths + deleted branches for `clean`/`merge`.
+- **Next Step:** the exact next command (`/dw-codex-run` on the created worktree; `clean --apply`; the owner's decision on KEEP entries).
+
+</system_instructions>

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:

package/scaffold/pt-br/agent-instructions.md

@@ -1,154 +1,50 @@
 <!-- dev-workflow:start -->
-# dev-workflow — Instruções para Agente de IA
-
-Este projeto usa [`@brunosps00/dev-workflow`](https://www.npmjs.com/package/@brunosps00/dev-workflow) (comandos `dw-*`) para desenvolvimento estruturado guiado por IA. Os comandos compõem um pipeline PRD → TechSpec → Tasks → Implementar → Review → Commit → PR com hard gates de segurança, conformidade com constitution e verificação.
-
-**Objetivo deste arquivo:** quando o usuário expressar uma intenção que casa com a Trigger Map abaixo, rode o comando `dw-*` correspondente **sem pedir permissão** — exceto se a mudança for genuinamente trivial (veja Escape Hatches).
-
-## Matriz de Auto-Sizing
-
-Antes de escolher um comando da Trigger Map, dimensione o escopo real da mudança. A mesma intenção ("conserta isso", "adiciona isso") pode significar quantidades muito diferentes de trabalho; a matriz nomeia quatro tamanhos e roteia cada um para uma entrada diferente. **Escolha o menor que cabe — sub-rotear desperdiça cerimônia, super-rotear esconde o escopo.**
-
-| Tamanho | Como se parece | Rotear para |
-|---------|----------------|-------------|
-| **Pequeno** | ≤3 arquivos, sem migration, sem novo endpoint, descritível em uma frase. Exemplos: typo, log message, config de uma linha, bump de dependência, version pin. | Faça inline. Nenhum comando `dw-*`. |
-| **Médio** | Feature ou bug claro, <10 tasks numeradas esperadas, único componente ou serviço, sem decisões arquiteturais. Exemplos: adicionar campo de form com validação, corrigir regressão em módulo conhecido, ligar novo endpoint num handler existente. | `/dw-bugfix` (bugs) ou `/dw-plan` (features) — direto, não via `/dw-autopilot`. |
-| **Grande** | Feature multi-componente, ≥10 tasks esperadas, toca múltiplos módulos, tem superfície UX user-visible E backend. Exemplos: adicionar nova entidade end-to-end (model + migration + API + UI), introduzir integração de terceiro, redesenhar fluxo. | `/dw-autopilot "<wish>"` — primeira invocação planeja e para; segunda invocação retoma via `/dw-goal` para Run → Review → QA/Fix → Review, depois Commit → PR. |
-| **Complexo** | Domínio novo, requisitos ambíguos, decisão arquitetural exigida, superfície regulatória ou de compliance, ou escopo que cruza múltiplos PRDs. Exemplos: introduzir event sourcing, reconstruir auth, multi-tenancy, nova linha de produto. | `/dw-opportunities` primeiro se a ideia ainda nao existir; caso contrario `/dw-brainstorm "<ideia>"` (auto-dispatch de modos research/council), depois `/dw-plan --council` para a etapa de techspec rodar o debate multi-advisor. |
-
-**Safety valve:** se você começou em Pequeno ou Médio mas o trabalho revela que é Grande de fato (a listagem inline passa de 5 passos, ou `/dw-bugfix` dispara seu `Step 5.0`), PARE e escale. Não existe flag para bypass. Escalar é o desfecho correto.
-
-**Adaptado de** [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) (CC-BY-4.0). A matriz de quatro tamanhos é de lá; o mapeamento para comandos `dw-*` é específico do dev-workflow.
-
-## Trigger Map
-
-| Intenção do usuário (literal ou parafraseada) | Auto-trigger |
-|------------------------------------------------|--------------|
-| "Implementa X" / "Cria Y" / "Adiciona feature Z" / "Preciso de..." | `/dw-autopilot "X"` |
-| "Autopilota esse PRD" / "Leva esse PRD pra PR" / continua escalação de bugfix autonomamente | `/dw-autopilot --from-prd <slug>` (PRD existente em `.dw/spec/<slug>/`) |
-| "Retoma autopilot" / "continua depois do plan" / `autopilot-state.json` tem `status: plan_complete` | `/dw-autopilot` (ou `/dw-goal --from-autopilot <slug>` se o usuário pedir especificamente a etapa de goal) |
-| Erro colado / "X está quebrado" / "Bug em Y" / screenshot de teste falhando | `/dw-bugfix "X"` |
-| "Planeja essa feature" / "Escreve PRD + techspec + tasks" | `/dw-plan "X"` |
-| "Escreve PRD pra X" / "Especifica Y" | `/dw-plan prd "X"` |
-| "Desenha a arquitetura" / "Faz o techspec" | `/dw-plan techspec` |
-| "Quebra em tasks" | `/dw-plan tasks` |
-| "Roda essa task" (com ID da task) | `/dw-run <ID>` |
-| "Roda todas as tasks pendentes" / "Executa o plano" | `/dw-run` |
-| "Roda isso como goal" / "objetivo durável" / "long-running objective" | `/dw-goal "<objetivo>"` |
-| "Continue de onde parei" | `/dw-run --resume` |
-| "Pausa o trabalho" / "Encerra a sessão" / "Salva onde paramos" | `/dw-pause` |
-| "Retoma" / "Onde paramos?" / "Volta de onde parei" | `/dw-resume` |
-| "QA dessa feature" / "Roda o test plan" | `/dw-qa` |
-| "Corrige os bugs do QA" | `/dw-qa --fix` |
-| "Avalia a feature AI" / "Testa o RAG / classifier" | `/dw-qa --ai` |
-| "Caminha comigo pela feature" / "UAT comigo" / "Vamos fazer um run-through manual" | `/dw-qa --uat` |
-| "Revisa esse bugfix" / "Code-review do fix `<slug>`" | `/dw-review --bugfix <slug>` |
-| "QA desse bugfix" / "Valida o fix `<slug>`" | `/dw-qa --bugfix <slug>` |
-| "Revisa meu PR" / "Checa qualidade" / "Tá pronto pra subir?" | `/dw-review` |
-| "Só checagem de cobertura PRD" | `/dw-review --coverage-only` |
-| "Só code review qualidade" | `/dw-review --code-only` |
-| "Hora de commitar" / mudanças validadas e prontas | `/dw-commit` |
-| "Abre um PR" / "Sobe isso" | `/dw-generate-pr` |
-| "Sugere ideias novas" / "O que devemos construir agora?" / "Encontra oportunidades" / "Ideias de roadmap" | `/dw-opportunities` |
-| "Que melhorias de seguranca devemos considerar?" / "Encontra oportunidades de seguranca" | `/dw-opportunities "security"` |
-| "Brainstorm X" / "Explora essa ideia" / "Research X" | `/dw-brainstorm "X"` (auto-dispatch dos modos grill / prototype / council / research / onepager conforme os sinais) |
-| "Auditoria de saude do codigo" / "Tech debt" / "Oportunidades de refactor" / "Smells em X" | `/dw-refactor "X"` |
-| "Onde está X?" / "O que usa Y?" / "Como Z é estruturado?" | `/dw-intel "<pergunta>"` |
-| "Reconstrói o índice" / "Refresh do intel" | `/dw-intel --build` |
-| "Contexto pesado" / "Audita uso de tokens" / "Por que o agente está lento?" | `/dw-context-budget` |
-| "Checa instalação dev-workflow" / "Agentes/wrappers estão saudáveis?" | `/dw-harness-audit` |
-| "Audita skills" / "Skills parecem duplicadas ou pesadas" | `/dw-skill-health` |
-| "Redesign dessa UI" / "Audita e entrega novo design" | `/dw-redesign-ui "<target>"` |
-| "Audita dependências" / "Estamos atrasados em pacotes?" | `/dw-secure-audit --plan` |
-| "Scan de vulnerabilidades" / "Check de segurança" | `/dw-secure-audit` |
-| "Analisa esse projeto" / "Gera rules" | `/dw-analyze-project` |
-| "Abre um novo projeto" / "Bootstrap de stack" | `/dw-new-project` |
-| "Dockeriza isso" / "Adiciona docker-compose" | `/dw-dockerize` |
-| "Functional doc" / "Mapeia screens e flows" | `/dw-functional-doc` |
-| "Instala skills Azure" / "Configura MCP do Microsoft docs" / "Adiciona expertise Azure" / "Vou trabalhar com Azure" | `/dw-install-azure-skills` |
-| "Instala skills AWS" / "Configura MCP da AWS" / "Adiciona expertise AWS" / "Vou trabalhar com AWS" | `/dw-install-aws-skills` |
+# dev-workflow — Instruções do agente
 
-**Prioridade:** na dúvida entre dois comandos, `/dw-autopilot` é o default mais seguro pra qualquer pedido de feature não-trivial. Se um autopilot planejado já parou com `status: plan_complete`, retome em vez de iniciar novo plano; a fase de execução pertence ao `/dw-goal`.
+Use o menor workflow que atende à intenção e ao risco. Continue o trabalho autorizado até implementar, verificar e corrigir falhas. Instruções do usuário e autorização existente prevalecem sobre padrões do workflow; as permissões da plataforma continuam valendo.
 
-## Hard Gates (os comandos enforçam — não burle)
+## Roteamento
 
-- **`.dw/constitution.md`**: princípios com `severity: high` ou `critical` bloqueiam PRs / techspecs sem um ADR justificando o desvio. Constitution ausente? Os comandos auto-instalam defaults em `severity: info` (não-bloqueante) e seguem — ausência nunca bloqueia.
-- **`.dw/spec/<prd>/tasks-validation.md`**: auto-gerado no fim do `/dw-plan tasks`. Qualquer dimensão FAIL bloqueia approval do usuário até resolver ou override explícito.
-- **Verification**: `/dw-generate-pr` exige `dw-verify` PASS fresco (testes + lint + build) depois do último edit.
-- **Segurança**: projetos TS / Python / C# / Rust precisam passar `/dw-secure-audit` (OWASP + Semgrep + gitleaks + Trivy + lockfile audit) antes do PR abrir.
+| Intenção e escopo | Ação |
+|---|---|
+| Explicação, localização de código ou exploração | Inspecione fontes relevantes e responda diretamente. |
+| Mudança pequena, clara e de baixo risco | Implemente diretamente e verifique proporcionalmente. |
+| Bug que exige investigação | `/dw-bugfix`; correção pequena e conhecida pode ficar inline. |
+| Feature que precisa de especificação | `/dw-plan`; em pedido de implementação completa, continue após aprovar as tasks. |
+| Implementação multicomponente até validação | `/dw-autopilot`; aprove o plano de tasks/execução e continue na mesma invocação. |
+| Decisões pendentes de produto ou arquitetura | `/dw-brainstorm`, depois `/dw-plan` quando alinhado. Council somente quando perspectivas diferentes ajudarem a decisão. |
+| Executar tasks aprovadas | `/dw-run`; `/dw-goal` para execução durável. |
+| Retomar trabalho existente | `/dw-resume` ou `/dw-run --resume`; reutilize decisões e evidências salvas. |
+| Pedido explícito de review / QA / commit / PR | `/dw-review` / `/dw-qa` / `/dw-commit` / `/dw-generate-pr`. |
 
-## Escape Hatches — NÃO auto-trigger
+Não inicie outro pipeline dentro de um workflow ativo. Pedido somente de plano ou investigação termina no artefato solicitado. Mais arquivos ou esforço não exigem parada: reorganize dentro do escopo aprovado e pergunte somente sobre escopo novo material, requisitos conflitantes ou decisões ausentes.
 
-Quando qualquer destes se aplica, responda direto e **não** invoque comando `dw-*`:
+Para comandos especializados consulte `.dw/references/command-routing.md` ou `/dw-help`. Não carregue o catálogo completo em trabalho rotineiro.
 
-- Correção de uma linha: typo, rename, sort de imports, ajuste de comentário.
-- Exploração pura: "como isso funciona?", "me mostra X", "explica Y".
-- Preferência estética: "prefiro esse estilo" — aplica, não roda pipeline.
-- Usuário diz explicitamente "faz direto" / "pula autopilot" / "não precisa de PRD" — honre.
-- A conversa já está dentro de um fluxo `dw-*` (você já está executando tasks; não inicie pipeline novo).
+## Planejamento e delegação
 
-## Padrão zoom-out (para áreas desconhecidas do código)
+Na quebra de tasks, proponha desenvolvimento local ou cruzado e modelo, esforço e agentes por task considerando ambiguidade, dependências, risco e escopo. Leia `.dw/references/execution-contract.md` nessa etapa e ao executar/retomar o plano. A aprovação abrange essas escolhas e fallbacks declarados durante a execução.
 
-Quando você cai numa área do codebase que não conhece e a orientação custa mais que a tarefa em si, **não mergulhe nos arquivos primeiro** — peça ao `dw-code-explorer` que produza um mapa. Passe o glossário de domínio do projeto (`.dw/rules/index.md`) e diga: "zoom out de um nível — me mostra os módulos relevantes, suas superfícies públicas, quem chama, e o fluxo de dados entre eles, usando o vocabulário do glossário de domínio." Pegue a visão geral, e só então mergulhe. Isso evita a armadilha de ler o arquivo mais profundo primeiro e reconstruir a arquitetura das folhas pra cima.
+Claude pode delegar implementação por `/dw-codex-run`; Codex pode usar `/dw-claude-run`. O parent conduz review, correções e continuidade. Agentes locais herdam o modelo da sessão salvo override aprovado na task. Delegue trabalho independente e delimitado quando melhorar qualidade ou tempo; mantenha trabalho pequeno ou acoplado local. Máximo de 3 workers por fluxo e nunca escritores simultâneos no mesmo worktree.
 
-Adaptado de [`mattpocock/skills/zoom-out`](https://github.com/mattpocock/skills/tree/main/zoom-out) (MIT).
+Leia primeiro arquivos relevantes. Use `.dw/intel/` ou code-explorer quando ajudar em fluxos amplos ou desconhecidos, conferindo o índice contra o código atual. Carregue entrypoints de skills somente para tasks correspondentes e referências somente para o modo escolhido. Subagentes recebem um pacote compacto e retornam evidências e decisões, não logs completos.
 
-## Disciplina de Dispatch de Subagentes
+## Conclusão e limites
 
-Agentes de projeto sao instalados em `.claude/agents/`, `.opencode/agent/`, `.agents/agents/` e `.github/agents/` quando suportado. Claude Code e OpenCode podem usar subagentes nativos. Copilot recebe custom agents. Codex deve tratar `.agents/agents/` como perfis delegaveis quando houver suporte a subagentes, ou como prompt pack manual caso contrario.
+Um plano de implementação aprovado continua por implementação, review, QA aplicável e correções. Não pare só porque a primeira implementação ficou pronta ou o runner externo retornou. Reutilize decisões resolvidas na conversa. Preserve trabalho parcial e checkpoints duráveis em interrupções.
 
-Use subagente quando:
+Entrega pronta atende aos critérios de aceitação, não tem achado bloqueante pendente e possui evidência válida de verificação. Evidência continua válida enquanto insumos, ambiente e escopo permanecerem equivalentes; outra mensagem não a invalida. Aplique `dw-verify` nos gates de entrega. Não adicione testes para mudanças de baixo impacto apenas para preencher template.
 
-- A tarefa gerar output volumoso: logs, testes, grep amplo, evidencia de QA, traces de browser ou notas de pesquisa.
-- A tarefa for read-only, paralelizavel e tiver fronteira clara.
-- A tarefa tiver return value compacto: findings, mapa, arquivos alterados, verificacao ou bloqueios.
-- Voce precisar de review independente: seguranca, silent failure, corretude por linguagem ou prontidao de PR.
+Merge, push, publicação e operações destrutivas exigem autorização aplicável; não pergunte novamente quando já autorizado. Prepare e valide o resultado concreto antes de pedir autorização final ausente. Worktree isola mudanças Git, não permissões do sistema operacional.
 
-Nao use subagente quando:
+## Contratos do projeto
 
-- A tarefa exigir dialogo frequente com o usuario.
-- Planejamento, implementacao e teste compartilharem contexto vivo demais.
-- A mudanca for pequena o bastante para fazer inline.
-- O subagente precisar do transcript completo do parent para nao chutar.
-- A tarefa delegada precisaria spawnar outros subagentes.
-
-Limites:
+- Respeite `.dw/constitution.md`; desvios high/critical seguem o processo de ADR definido. Ausência não bloqueia: use defaults não bloqueantes.
+- Planos aprovados precisam de dependências válidas e `tasks-validation.md`; corrija inconsistências internas antes de pedir aprovação.
+- Complete os checks exigidos pelo projeto. Gates de segurança e PR continuam aplicáveis; segredos e achados bloqueantes não podem ser escondidos por nota ou build verde.
+- Execução formal de tasks mantém commits atômicos com escopo e rastreabilidade de requisitos. Edição pequena direta não implica pedido de commit ou PR.
 
-- Rode no maximo 3 subagentes concorrentes por workstream.
-- Output default deve ficar perto do budget do registry, normalmente 900-1200 palavras.
-- Subagentes resumem logs; retornam linhas falhas, paths, comandos, decisoes e riscos, nao transcripts completos.
-- O parent e o unico sintetizador final.
-- O parent passa um input packet, nao historico bruto da conversa. Use `/dw-subtask-start`, `/dw-subtask-complete` e `/dw-subtask-resume` para handoffs locais.
-
-Claude-only: prefira named subagents para pesquisa, review, build e QA isolados. Use forks so quando a subtarefa realmente precisar do contexto do parent.
-
-Roteamento de agentes:
-
-- Use `dw-code-explorer` antes de planejar ou debugar areas desconhecidas.
-- Use `dw-build-fixer` so depois de uma falha real de build/typecheck/lint.
-- Use `dw-code-reviewer`, `dw-security-reviewer` e `dw-silent-failure-hunter` durante `/dw-review`.
-- Use agentes especificos de linguagem quando o modulo estiver instalado e o diff bater com a linguagem.
+## Personalização
 
-## Disciplina de Carregamento de Skills
-
-Skills são protocolos compactos primeiro. Leia o `SKILL.md` de entrada e carregue arquivos em `references/`, `assets/`, `rules/` ou `scripts/` só quando o trigger, a tarefa ou o output exigir esse material mais profundo. Se uma skill parecer duplicada, ampla demais ou cara para a tarefa atual, rode `/dw-skill-health`.
-
-## Referência de Workflow
-
-```
-/dw-autopilot "wish"  ────►  Primeira invocação planeja: PRD → TechSpec → Tasks → STOP
-/dw-autopilot         ────►  Segunda invocação retoma: /dw-goal → Commit → PR
-
-  --- OU passo a passo ---
-
-/dw-brainstorm ─► /dw-plan ─► /dw-goal ─► /dw-commit ─► /dw-generate-pr
-```
-
-Lista completa e ajuda contextual: `/dw-help`.
-
-## Editando esta seção
-
-Este bloco vive entre os marcadores `<!-- dev-workflow:start -->` e `<!-- dev-workflow:end -->`. Qualquer coisa que você escrever **fora** dos marcadores em `CLAUDE.md` / `AGENTS.md` é preservada a cada `dev-workflow update`. Tudo **dentro** é regenerado do pacote — seus edits dentro do bloco serão sobrescritos.
-
-Para customizar a trigger map permanentemente, copie o conteúdo pra fora dos marcadores (ou pra arquivo separado tipo `.dw/agent-instructions-custom.md`) e edite lá.
+Este bloco fica entre os marcadores `<!-- dev-workflow:start -->` e `<!-- dev-workflow:end -->` e é atualizado pelo pacote. Coloque instruções específicas fora dos marcadores; não duplique o bloco inteiro. Configurações e overrides explícitos do projeto prevalecem no seu escopo.
 <!-- dev-workflow:end -->

package/scaffold/pt-br/commands/dw-analyze-project.md

@@ -310,6 +310,8 @@ Documentar os fluxos rastreados com caminhos de arquivo em cada etapa.
 
 ### Passo 5: Detectar Antipatterns (Obrigatório)
 
+Para um módulo frontend, leia `dw-ui-discipline/references/frontend-engineering.md` no local das skills instaladas. Use `.dw/templates/frontend-quality-template.md` para incluir controles observados, lacunas e propostas de adoção no `.dw/rules/<module>.md` do módulo. Inspecione scripts/configurações reais e CI; registre checks não executados explicitamente. Preserve a política existente e separe-a das recomendações. Este comando apenas documental não instala ferramentas, altera código/configurações nem ativa novos gates no CI.
+
 Verificar a presença de:
 
 | Antipattern | Como Detectar |