@brunosps00/dev-workflow 2.2.0 → 2.3.0

package/scaffold/en/agent-instructions.md

@@ -1,156 +1,50 @@
 <!-- dev-workflow:start -->
-# dev-workflow — AI Agent Instructions
-
-This project uses [`@brunosps00/dev-workflow`](https://www.npmjs.com/package/@brunosps00/dev-workflow) (`dw-*` commands) for structured AI-driven development. The commands compose into a PRD → TechSpec → Tasks → Implement → Review → Commit → PR pipeline with hard gates for security, constitution compliance, and verification.
-
-**The whole point of this file:** when the user states an intent that matches the Trigger Map below, run the matching `dw-*` command **without asking permission first** — unless the change is genuinely trivial (see Escape Hatches).
-
-## Auto-Sizing Matrix
-
-Before picking a command from the Trigger Map, gauge the change's actual scope. The same intent ("fix this", "add this") can mean very different amounts of work; the matrix names four sizes and routes each to a different entry point. **Pick the smallest one that fits — under-routing wastes ceremony, over-routing hides scope.**
-
-| Size | What it looks like | Route to |
-|------|---------------------|----------|
-| **Small** | ≤3 files, no migration, no new endpoint, can be summarized in one sentence. Examples: typo, log message, single-line config, dependency bump, version pin. | Just do it inline. No `dw-*` command. |
-| **Medium** | Clear feature or bug, <10 numbered tasks expected, single component or single service, no architectural decisions. Examples: add a form field with validation, fix a regression in a known module, wire a new API endpoint into an existing handler. | `/dw-bugfix` (for bugs) or `/dw-plan` (for features) — straight, not via `/dw-autopilot`. |
-| **Large** | Multi-component feature, ≥10 tasks expected, touches multiple modules, has user-visible UX surface AND backend. Examples: add a new entity end-to-end (model + migration + API + UI), introduce a third-party integration, redesign a flow. | `/dw-autopilot "<wish>"` — first invocation plans and stops; second invocation resumes via `/dw-goal` for Run → Review → QA/Fix → Review, then Commit → PR. |
-| **Complex** | New domain, ambiguous requirements, architectural decision required, regulatory or compliance surface, or scope that spans multiple PRDs. Examples: introduce event sourcing, rebuild auth, multi-tenancy, a new product line. | `/dw-opportunities` first if the idea is not yet known; otherwise `/dw-brainstorm "<idea>"` (auto-dispatches research/council modes), then `/dw-plan --council` so the techspec stage runs the multi-advisor debate. |
-
-**Safety valve:** if you start in Small or Medium but the work reveals it's actually Large (the inline listing exceeds 5 steps, or `/dw-bugfix` triggers its `Step 5.0` valve), STOP and escalate. There is no flag to bypass. Escalation is the correct outcome.
-
-**Adapted from** [`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). The four-size matrix is theirs; the mapping to `dw-*` commands is dev-workflow-specific.
-
-## Trigger Map
-
-| User intent (literal or paraphrased) | Auto-trigger |
-|--------------------------------------|--------------|
-| "Implement X" / "Build Y" / "Add feature Z" / "I need ..." / "Create ..." | `/dw-autopilot "X"` |
-| "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` |
+# dev-workflow — Agent instructions
 
-**Priority:** when in doubt between two commands, `/dw-autopilot` is the safest default for any non-trivial feature request. If a planned autopilot has already stopped with `status: plan_complete`, resume it instead of starting a new plan; the execution phase is owned by `/dw-goal`.
+Use the smallest workflow that satisfies the user's intent and risk. Continue authorized work through implementation, relevant verification, and correction of failures. User instructions and existing authorization take precedence over workflow defaults; platform permissions still apply.
 
-## Hard Gates (the commands enforce these — don't bypass)
+## Routing
 
-- **`.dw/constitution.md`**: principles with `severity: high` or `critical` block PRs / techspecs without an ADR justifying the deviation. Missing constitution? Commands auto-install defaults at `severity: info` (non-blocking) and continue — never blocks on absence.
-- **`.dw/spec/<prd>/tasks-validation.md`**: auto-generated at the end of `/dw-plan tasks`. Any FAIL dimension blocks user approval until resolved or explicitly overridden.
-- **Verification**: `/dw-generate-pr` requires a fresh `dw-verify` PASS (tests + lint + build) after the last edit.
-- **Security**: TS / Python / C# / Rust projects must pass `/dw-secure-audit` (OWASP + Semgrep + gitleaks + Trivy + lockfile audit) before the PR opens.
+| Intent and scope | Action |
+|---|---|
+| Explanation, code lookup, or exploration | Inspect relevant sources and answer directly. |
+| Small, clear, low-risk edit | Implement directly and verify proportionally. |
+| Bug requiring investigation | `/dw-bugfix`; a known small fix can stay inline. |
+| Feature needing specification | `/dw-plan`; for an end-to-end implementation request, continue after task approval. |
+| Multi-component implementation through validation | `/dw-autopilot`; approve the task/execution plan, then continue in the same invocation. |
+| Unresolved product or architecture decisions | `/dw-brainstorm`, then `/dw-plan` when aligned. Use council only when multiple perspectives help the decision. |
+| Execute approved tasks | `/dw-run`; `/dw-goal` for durable execution. |
+| Resume existing work | `/dw-resume` or `/dw-run --resume`; reuse saved decisions and evidence. |
+| Review / QA / commit / PR explicitly requested | `/dw-review` / `/dw-qa` / `/dw-commit` / `/dw-generate-pr`. |
 
-## Escape Hatches — do NOT auto-trigger
+Do not start a second pipeline inside an active workflow. A request only to plan or investigate ends with the requested artifact. Increased file count or effort is not itself a reason to stop: reorganize within approved scope and ask only about material new scope, conflicting requirements, or missing decisions.
 
-When any of these apply, answer directly and do **not** invoke a `dw-*` command:
+For specialized commands consult `.dw/references/command-routing.md` or `/dw-help`. Do not load the full catalog for routine work.
 
-- One-line typo, rename, import sort, comment fix.
-- Pure exploration: "how does this work?", "show me X", "explain Y".
-- Aesthetic preference: "I prefer this style" — apply, don't run a pipeline.
-- User explicitly says "do this directly" / "skip autopilot" / "no need for a PRD" — honor it.
-- The conversation is already inside a `dw-*` flow (you're already executing tasks; don't start a new pipeline).
+## Planning and delegation
 
-## Zoom-out pattern (for unfamiliar code areas)
+During task breakdown, propose local or cross-tool development and a model, effort, and agent assignment for each task based on ambiguity, dependencies, risk, and scope. Read `.dw/references/execution-contract.md` at this stage and when executing/resuming the plan. Approval covers these assignments and declared fallbacks for the run.
 
-When you land in an area of the codebase you don't know and orientation costs more than the task itself, **don't dive into files first** — ask `dw-code-explorer` to produce a map. Give it the project's domain glossary (`.dw/rules/index.md`) and tell it: "zoom out one level — show me the relevant modules, their public surfaces, who calls them, and the data flow between them, using domain glossary vocabulary." Get the lay of the land, then dive. This avoids the trap of reading the deepest file first and reconstructing the architecture from leaves upward.
+Claude can delegate implementation through `/dw-codex-run`; Codex can use `/dw-claude-run`. The parent owns review, corrections, and continuation. Local agents inherit the session model unless the approved task overrides it. Delegate bounded independent work when it improves quality or time; keep tightly coupled or small work local. At most 3 workers per workstream, and never concurrent writers in the same worktree.
 
-Adapted from [`mattpocock/skills/zoom-out`](https://github.com/mattpocock/skills/tree/main/zoom-out) (MIT).
+Read relevant files first. Use `.dw/intel/` or a code-explorer for broad or unfamiliar flows when useful, checking index claims against current source. Load skill entrypoints only for matching tasks, and references only for the selected mode. Subagents receive a compact packet and return evidence and decisions, not full logs.
 
-## Subagent Dispatch Discipline
+## Completion and boundaries
 
-Project agents are installed in `.claude/agents/`, `.opencode/agent/`, `.agents/agents/`, and `.github/agents/` when supported. Claude Code and OpenCode can use native subagents. Copilot receives custom agents. Codex should treat `.agents/agents/` as delegable profiles when subagents are available, or as a manual prompt pack otherwise.
+An approved implementation plan continues through implementation, review, QA where applicable, and fixes. Do not stop merely because the first implementation is ready or an external runner returned. Reuse decisions already resolved in the conversation. Preserve partial work and durable checkpoints on interruption.
 
-Use a subagent when:
+A ready delivery meets acceptance criteria, has no unresolved blocking finding, and has valid verification evidence. Evidence stays valid while its inputs, environment, and scope remain equivalent; a new message does not invalidate it. Follow `dw-verify` at delivery gates. Do not add tests for low-impact edits just to satisfy a template.
 
-- The task will generate verbose output: logs, tests, broad grep, QA evidence, browser traces, or research notes.
-- The task is read-only, parallelizable, and has a clear boundary.
-- The task has a compact return value: findings, map, changed files, verification result, or blockers.
-- You need an independent review: security, silent failure, language-specific correctness, or PR readiness.
-
-Do not use a subagent when:
-
-- The task needs frequent user dialogue.
-- Planning, implementation, and testing share too much live context.
-- The change is small enough to do inline.
-- The subagent would need the full parent transcript to avoid guessing.
-- The delegated task would itself need to spawn other subagents.
-
-Limits:
+Merge, push, publication, and destructive operations require applicable authorization; do not ask again when already authorized. Prepare and validate the concrete result before requesting a missing final authorization. A worktree isolates Git changes, not operating-system permissions.
 
-- Run at most 3 subagents concurrently per workstream.
-- Default output should stay near the registry budget, usually 900-1200 words.
-- Subagents summarize logs; they return failing lines, paths, commands, decisions, and risks, not full transcripts.
-- The parent is the only final synthesizer.
-- The parent passes an input packet, not raw conversation history. Use `/dw-subtask-start`, `/dw-subtask-complete`, and `/dw-subtask-resume` for local handoffs.
-
-Claude-only: prefer named subagents for isolated research, review, build, and QA work. Use forks only when the subtask genuinely needs the parent context.
-
-Agent routing:
-
-- Use `dw-code-explorer` before planning or debugging unfamiliar areas.
-- Use `dw-build-fixer` only after an actual build/typecheck/lint failure.
-- Use `dw-code-reviewer`, `dw-security-reviewer`, and `dw-silent-failure-hunter` during `/dw-review`.
-- Use language-specific agents when their module is installed and the diff matches the language.
+## Project contracts
 
-## Skill Loading Discipline
+- Respect `.dw/constitution.md`; high/critical deviations need the defined ADR process. Missing constitution does not block: use non-blocking defaults.
+- Approved task plans need valid dependencies and `tasks-validation.md`; repair internal inconsistencies before asking for approval.
+- Complete project-required checks. Security and PR gates remain applicable; secrets and unresolved blocking findings cannot be hidden by a score or a green build.
+- Formal task execution retains scoped atomic commits and requirement traceability. Direct small edits do not imply a commit or PR request.
 
-Skills are compact protocols first. Read the `SKILL.md` entrypoint, then load files under `references/`, `assets/`, `rules/`, or `scripts/` only when the trigger, task, or output requires that deeper material. If a skill feels duplicated, too broad, or expensive for the current task, run `/dw-skill-health`.
+## Customization
 
-## Workflow Reference
-
-```
-/dw-autopilot "wish"  ────►  First invocation plans: PRD → TechSpec → Tasks → STOP
-/dw-autopilot         ────►  Second invocation resumes: /dw-goal → Commit → PR
-
-  --- OR step-by-step ---
-
-/dw-brainstorm ─► /dw-plan ─► /dw-goal ─► /dw-commit ─► /dw-generate-pr
-```
-
-Full command list and contextual help: `/dw-help`.
-
-## Editing this section
-
-This block lives between `<!-- dev-workflow:start -->` and `<!-- dev-workflow:end -->` markers. Anything you write **outside** these markers in `CLAUDE.md` / `AGENTS.md` is preserved on every `dev-workflow update`. Anything **inside** is refreshed from the package — your edits inside the block will be overwritten.
-
-To customize the trigger map permanently, copy the block content to outside the markers (or to a separate file like `.dw/agent-instructions-custom.md`) and edit there.
+This managed block lives between `<!-- dev-workflow:start -->` and `<!-- dev-workflow:end -->` markers and is refreshed on update. Put project-specific instructions outside the markers; do not duplicate the entire block. Configuration and explicit project overrides remain authoritative for their scope.
 <!-- dev-workflow:end -->

package/scaffold/en/commands/dw-analyze-project.md

@@ -344,6 +344,8 @@ Document the traced flows with file paths at each step. This reveals the actual
 
 ### Step 5: Detect Anti-patterns
 
+For a frontend module, read `dw-ui-discipline/references/frontend-engineering.md` from the installed skills location. Use `.dw/templates/frontend-quality-template.md` to include observed controls, gaps and adoption proposals in that module's `.dw/rules/<module>.md`. Inspect actual scripts/configuration and CI; record unexecuted checks explicitly. Preserve existing policy and distinguish it from recommendations. This documentation-only command does not install tools, change source/configuration or enable new CI gates.
+
 Look for common issues:
 
 | Anti-pattern | Detection method | Severity |

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

@@ -1,259 +1,36 @@
 <system_instructions>
-You are the full pipeline orchestrator. This command receives a user's wish and drives the PRD-to-PR workflow in two invocations:
+# Continuous implementation orchestrator
 
-1. **Planning invocation:** research/brainstorm when needed, PRD, TechSpec, Tasks, then STOP.
-2. **Execution invocation:** resume from `autopilot-state.json`, run `/dw-goal --from-autopilot <prd-slug>`, then commit and PR gate.
+`/dw-autopilot "<wish>"` plans and carries approved work through implementation and validation. `/dw-autopilot --from-prd <slug>` starts from `.dw/spec/<slug>/prd.md`; missing PRD blocks with its path. `/dw-autopilot` without a wish resumes saved state. Do not impose a second invocation after task approval. A user request only to plan or an active platform Plan mode still ends at the planning artifact.
 
-<critical>The first invocation MUST stop after the planning artifacts are complete. Do not run implementation, QA, review, commit, or PR in the first invocation.</critical>
-<critical>The second invocation MUST resume from the saved state and delegate Run → Review → QA/Fix → Review to `/dw-goal --from-autopilot <prd-slug>`.</critical>
-<critical>Each step that invokes a `/dw-*` command MUST follow the complete instructions from `.dw/commands/`. Read and execute the full command, not a summarized version.</critical>
+## Planning
 
-## When to Use
-- Use when you want to go from an idea to a PR with minimal manual intervention but a hard planning stop.
-- Use for complete features that require planning, execution, quality gates, and PR readiness.
-- Do NOT use for small, well-scoped one-off tasks; use `/dw-run` with an existing plan.
-- Do NOT use for surgical bug fixes; use `/dw-bugfix`.
-- Do NOT use when the user wants manual control between every phase; use individual commands.
+1. Inspect relevant source/rules and existing decisions. Use `.dw/intel/` when useful; research only unknown technologies/domains/integrations. Brainstorm only unresolved choices, not a mandatory three-option interview.
+2. Invoke `/dw-plan` or its relevant stages to produce PRD, TechSpec, tasks and tasks-validation.md. Reuse answered decisions and aligned handoffs. Ask material uncovered questions with the available interview tool; do not re-ask discovered facts.
+3. At task breakdown present local/cross-tool development, concrete model/effort and relevant agents by task complexity. Follow `.dw/references/execution-contract.md`, write/validate execution-plan.json, and obtain approval of the same task/assignment matrix. Existing stage approvals remain honored; do not repeat them.
+4. Save `autopilot-state.json` with `status: plan_complete`, `current_step: goal`, planning artifacts, approved assignments path and `next_command: /dw-goal --from-autopilot <slug>`. In an implementation request continue immediately to execution. In a planning-only request report the plan and preserve this resume point.
 
-## Pipeline Position
-**Predecessor:** user wish | **Successor:** `/dw-goal`, `/dw-commit`, `/dw-generate-pr`
+## Execution and delivery
 
-## Complementary Skills / Commands
+Arm `/dw-report` once (idempotent, skipped when `DW_REPORT_AUTO=off`). Invoke `/dw-goal --from-autopilot <slug>` to own `/dw-run` → full `/dw-review` → applicable `/dw-qa` → `/dw-qa --fix` for Open bugs → post-QA review when edits or new findings invalidate the prior review. Do not substitute coverage-only review for the full review. External runners return to the parent for corrections and continuation; they do not end the goal.
 
-| Skill or command | Trigger |
-|------------------|---------|
-| `dw-memory` | ALWAYS — preserve decisions across planning, goal execution, QA, review, and PR. |
-| `dw-verify` | ALWAYS — invoked by gates and downstream commands before approval/commit/PR claims. |
-| `/dw-goal` | ALWAYS on the second invocation — durable execution-quality objective. |
+Use `dw-memory` for durable decisions and `dw-verify` for valid evidence. Security Gate remains mandatory where applicable: `/dw-secure-audit` produces `.dw/secure-audit/audit-summary.md`; missing/invalid evidence is regenerated and blocking findings are fixed. SECRET findings always block (no ADR escape). Reuse a valid scan instead of repeating it solely at another checkpoint.
 
-## Input Variables
+The goal completes only with acceptance criteria met, required review/QA artifacts and valid checks, and no unresolved blocking finding. For escalated `prd-bugfix-*`, find the originating `.dw/bugfixes/*/escalated.md`, produce missing SUMMARY.md from evidence, and close the index.
 
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `{{WISH}}` | Description of what the user wants to build in default mode. | `"push notification preferences"` |
-| `{{PRD_SLUG}}` | Existing PRD slug when `--from-prd` is used. | `prd-bugfix-stripe-webhook-retry` |
-| `{{MODE}}` | Optional invocation flag. | `--from-prd <slug>` |
+Inspect scoped task commits and remaining bookkeeping; `/dw-commit` handles an authorized final commit when needed. Do not create empty commits or demand an extra commit for already committed work. Prepare the validated branch/worktree and delivery summary. Merge, push and PR publication proceed only within existing authorization. If final authorization is absent, present the concrete result and request only that action; do not re-ask permission already granted.
 
-## Invocation Modes
+## Durable state
 
-| Invocation | Behavior |
-|------------|----------|
-| `/dw-autopilot "<wish>"` | Planning invocation from scratch. Runs Codebase Intelligence → optional Research → Brainstorm → PRD → TechSpec → Tasks, writes state, then stops. |
-| `/dw-autopilot --from-prd <slug>` | Planning invocation from an existing PRD. Starts at PRD approval, then TechSpec → Tasks, writes state, then stops. |
-| `/dw-autopilot` on a PRD with `autopilot-state.json status=plan_complete` | Execution invocation. Runs `/dw-goal --from-autopilot <slug>`, then commit and PR gate. |
+Preserve `autopilot-state.json` fields: mode, wish, prd_path, from_prd_slug, current_step, completed_steps, skipped_steps, skip_reasons, gates_passed, step_artifacts, goal_slug, next_command, started_at, last_updated. Add `execution_plan` and `execution_state` paths. Record evidence, not merely file existence, before marking a step complete.
 
-## Required Pause Points
-
-Autopilot pauses at:
-
-1. **PRD approval** before TechSpec.
-2. **Tasks approval** before marking planning complete.
-3. **Mandatory planning stop** after Tasks are approved and state is saved.
-4. **PR gate** after the execution goal and commit complete.
-
-Between these points, execute automatically while still respecting blocking questions required by the underlying command.
-
-## Session Resumption
-
-If this command is re-invoked on the same PRD:
-
-<critical>Read `.dw/spec/<prd-slug>/autopilot-state.json` first. If `status` is `plan_complete`, do not repeat planning. Start the execution invocation by formally invoking `/dw-goal --from-autopilot <prd-slug>`.</critical>
-
-State meanings:
-
-| Status | Action |
-|--------|--------|
-| missing state | Start normal planning invocation. |
-| `planning` | Resume from `current_step`, respecting completed/skipped steps. |
-| `plan_complete` | Start execution invocation via `/dw-goal --from-autopilot <prd-slug>`. |
-| `goal_active` | Continue `/dw-goal resume` or `/dw-goal --from-autopilot <prd-slug>` according to `.dw/goals/autopilot-<prd-slug>/status.json`. |
-| `goal_complete` | Continue to commit and PR gate. |
-| `completed` | Report already completed and show PR/commit summary if available. |
-
-## Planning Invocation
-
-### Step 0: Resolve Invocation Mode
-
-1. If `--from-prd <slug>` is present:
-   - Resolve to `.dw/spec/<slug>/`.
-   - Verify `prd.md` exists; otherwise STOP with: `--from-prd target .dw/spec/<slug>/prd.md not found. Run /dw-plan prd or fix the slug.`
-   - Create or update `autopilot-state.json` with `mode: "from-prd"`, `status: "planning"`, `skipped_steps: [1,2,3,4]`, and `skip_reasons["1-4"] = "from-prd-mode"`.
-   - Jump to PRD approval using the existing PRD.
-2. Otherwise:
-   - Create or update `autopilot-state.json` with `mode: "autopilot"`, `status: "planning"`, original wish, and `current_step: 1`.
-
-### Step 1: Codebase Intelligence
-
-<critical>If `.dw/intel/` exists, query it via `/dw-intel` before planning. Fall back to `.dw/rules/` and direct grep if absent.</critical>
-
-- Identify tech stack, existing patterns, related features, and project constraints.
-- If `.dw/intel/` is absent, suggest `/dw-intel --build` for richer future context, but continue with `.dw/rules/` and direct inspection.
-
-### Step 2: Research (Conditional)
-
-Run `/dw-brainstorm --research` when the feature involves new technology, unknown domain, external APIs, regulation, or high-impact architecture. Otherwise skip and record the reason in `skip_reasons`.
-
-### Step 3: Brainstorm (Interactive)
-
-Run `/dw-brainstorm` with accumulated context. Present three directions and wait for the user to choose one before continuing.
-
-### Step 4: PRD
-
-Run `/dw-plan prd` using brainstorm/research findings.
-
-<critical>The PRD stage must use the structured interview tool when available. If unavailable, ask the required questions in chat and record the fallback. The user must answer; do not infer answers.</critical>
-
-After `prd.md` exists, present PRD summary and wait for explicit approval. If the user requests edits, update and re-present.
-
-### Step 5: TechSpec
-
-Run `/dw-plan techspec` from the approved PRD.
-
-<critical>The TechSpec stage must use the structured interview tool when available. If unavailable, ask the required questions in chat and record the fallback. The user must answer; do not infer answers.</critical>
-
-After `techspec.md` exists, present TechSpec summary and wait for explicit approval.
-
-### Step 6: Tasks
-
-Run `/dw-plan tasks` from PRD + TechSpec. Verify:
-- `tasks.md` exists.
-- per-task files exist.
-- `tasks-validation.md` exists and passes or has an explicit user override.
-
-### Step 7: Tasks Approval and Mandatory Stop
-
-Present task summary, dependencies, and total effort. Wait for explicit approval.
-
-After approval:
-
-1. Save `.dw/spec/<prd-slug>/autopilot-state.json` with:
-
-```json
-{
-  "status": "plan_complete",
-  "current_step": "goal",
-  "next_command": "/dw-goal --from-autopilot <prd-slug>"
-}
-```
-
-2. Include `completed_steps` for all completed planning steps and `step_artifacts` for `prd.md`, `techspec.md`, `tasks.md`, per-task files, and `tasks-validation.md`.
-3. STOP and tell the user the planning phase is complete. Do not run implementation in this invocation.
-
-## Execution Invocation
-
-### Step 8: Durable Execution Goal
-
-First arm the progress loop: invoke `/dw-report` (auto-arm contract — idempotent, skipped when `DW_REPORT_AUTO=off`). It reports done / doing / remaining every 10 minutes through the goal, the Security Gate, commit, and PR, and disarms itself with a final report at the PR gate.
-
-When `autopilot-state.json status=plan_complete`, formally invoke:
-
-```text
-/dw-goal --from-autopilot <prd-slug>
-```
-
-The goal owns this sequence:
-
-1. `/dw-run <prd-path>`
-2. `/dw-review <prd-path>` (full review: coverage, quality, conventions, constitution, verify)
-3. `/dw-qa <prd-path>`
-4. `/dw-qa --fix <prd-path>` if QA found Open bugs
-5. `/dw-review <prd-path>` again after QA/fixes
-6. **Security Gate** — the post-QA `/dw-review` (step 5) triggers `/dw-secure-audit`, producing a fresh `.dw/secure-audit/audit-summary.md`. This step **ensures** that verdict is APPROVED: if it is missing/stale/REJECTED, run `/dw-secure-audit <prd-path>` standalone, then loop back to `/dw-bugfix` per finding and re-check. SECRET findings always block (no ADR escape). Do not force a second full scan when a fresh APPROVED summary already exists.
-
-<critical>Do not substitute `/dw-review --coverage-only` for the goal reviews. The autopilot quality goal requires full `/dw-review` before QA and after QA fixes.</critical>
-
-After `/dw-goal` completes, verify `.dw/goals/autopilot-<prd-slug>/status.json` has `status: "complete"`, then set `autopilot-state.json status: "goal_complete"`.
-
-### Step 9: Bugfix Loop Close (Conditional)
-
-If `mode == "from-prd"` and the PRD slug matches `prd-bugfix-*`, close the bugfix index before commit:
-- Find `.dw/bugfixes/*/escalated.md` that references the PRD slug.
-- If `SUMMARY.md` is missing, write it from available PRD, TechSpec, QA, and diff evidence using `.dw/templates/bugfix-summary-template.md`.
-- Never fabricate verification evidence.
-- Record artifacts in `autopilot-state.json`.
-
-### Step 10: Pre-Commit Audit
-
-Before `/dw-commit`, verify:
-- `.dw/goals/autopilot-<prd-slug>/status.json` is complete.
-- `<prd-path>/QA/review-consolidated.md` exists from the final post-QA review.
-- `<prd-path>/QA/qa-report.md` and `<prd-path>/QA/bugs.md` exist.
-- **Security Gate passed:** `.dw/secure-audit/audit-summary.md` exists, is fresh (post-last-edit), and status is APPROVED. If missing/stale/REJECTED → STOP (do not commit).
-- `autopilot-state.json` records planning artifacts and the completed goal.
-
-If anything is missing, STOP and re-run the missing formal command. Do not commit partial work.
-
-### Step 11: Commit
-
-Run `/dw-commit` automatically. Do not wait for approval after the goal is complete.
-
-### Step 12: Pull Request Gate
-
-Ask: **"Commits completed. Do you want to generate the Pull Request?"**
-
-- YES: run `/dw-generate-pr`.
-- NO: report that commits are ready and PR can be generated later.
-
-Mark `autopilot-state.json status: "completed"` after commit, and include PR link if generated.
-
-## State Persistence
-
-`autopilot-state.json` must include:
-
-```json
-{
-  "mode": "autopilot",
-  "status": "planning",
-  "wish": "original user description",
-  "prd_path": ".dw/spec/prd-name",
-  "from_prd_slug": null,
-  "current_step": 1,
-  "completed_steps": [],
-  "skipped_steps": [],
-  "skip_reasons": {},
-  "gates_passed": [],
-  "step_artifacts": {},
-  "goal_slug": null,
-  "next_command": null,
-  "started_at": "2026-05-20T00:00:00Z",
-  "last_updated": "2026-05-20T00:00:00Z"
-}
-```
-
-Update state after each completed or skipped step. A step is complete only after required artifacts exist.
-
-## Progress Format
-
-Report progress after each step:
-
-```text
-=== AUTOPILOT =====================================
-  OK [1] Codebase Intelligence
-  OK [2] Research (skipped — known domain)
-  OK [3] Brainstorm
-  OK [4] PRD
-  OK [5] TechSpec
-  OK [6] Tasks
-  STOP [PLAN COMPLETE] Next: /dw-goal --from-autopilot prd-name
-===================================================
-```
-
-During execution invocation:
-
-```text
-=== AUTOPILOT =====================================
-  OK [PLAN] Already complete
-  RUN [GOAL] /dw-goal --from-autopilot prd-name
-  NEXT [COMMIT] after goal status=complete
-===================================================
-```
-
-## Anti-patterns
-
-- Do not continue into implementation during the first invocation.
-- Do not skip `/dw-goal` during the second invocation.
-- Do not replace full `/dw-review` with a narrower review in the execution goal.
-- Do not mark state complete from manual validation alone.
-- Do not re-run planning when `status=plan_complete`; resume the goal.
+| status | Resume action |
+|---|---|
+| missing / planning | Continue only unfinished planning; preserve resolved decisions. |
+| plan_complete | Execute approved plan through `/dw-goal --from-autopilot <slug>` when implementation is requested. |
+| goal_active | `/dw-goal resume` using saved task/executor state. |
+| goal_complete | Prepare delivery and remaining authorized commit/publication actions. |
+| completed | Report validated delivery and links/branch; publication may still be pending authorization. |
 
+Update state after each checkpoint. Report current task, evidence and remaining work compactly. Preserve checkpoints on user pause or actual blocker; fix recoverable in-scope failures and continue.
 </system_instructions>

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

@@ -264,11 +264,11 @@
     | Question | If YES -> |
     |----------|-----------|
     | Needs migration/schema change? | Redirect to PRD |
-    | Affects more than 5 files? | Redirect to PRD |
+    | Broader file scope? | Reassess organization and actual risk; no automatic stop |
     | Requires new endpoint? | Redirect to PRD |
     | Changes existing API contract? | Redirect to PRD |
     | Affects multiple projects? | Redirect to PRD |
-    | Estimate > 2 hours of implementation? | Redirect to PRD |
+    | Larger implementation estimate? | Reorganize/checkpoint within approved scope |
 
     **If excessive scope detected:**
     ```
@@ -300,45 +300,19 @@
     - With `--analysis`: Go to step 6
     - Without `--analysis`: Continue to step 5
 
-    ### 5.0. Safety Valve (MANDATORY before step 5)
+    ### 5.0. Safety Valve (before implementation)
 
-    <critical>
-    BEFORE drafting the numbered task list in step 5, sketch the inline steps you intend to write.
-    If that sketch reveals **more than 5 distinct numbered tasks**, OR **any cross-file dependency that means tasks must be executed in a specific order**, OR **a task that requires running database migration / refactor / new endpoint / API contract change**, then the bugfix scope was UNDERESTIMATED and you MUST escalate.
-    </critical>
-
-    **Why this exists:** the triage at step 0 catches scope problems from the symptom description. The checkpoint at 4.1 catches them after root cause analysis. This valve catches the remaining case — when the fix itself, once laid out, reveals more complexity than triage and root cause analysis predicted. There is NO bypass flag. Escalation is the correct outcome.
-
-    **Escalation procedure:**
-
-    1. Allocate `NNN` for `.dw/bugfixes/NNN-<slug>/`. Write `TASK.md` with the triage, clarifications, root cause, and the would-be plan.
-    2. Create `.dw/spec/prd-bugfix-<slug>/` and write `prd.md` there (use `.dw/templates/bugfix-template.md`). This is the path `/dw-plan` expects.
-    3. Write `.dw/bugfixes/NNN-<slug>/escalated.md` with: `Escalated to /dw-plan on <YYYY-MM-DD> — reason: <which valve criterion tripped> → see .dw/spec/prd-bugfix-<slug>/`.
-    4. Report to the user:
-
-    ```
-    ## Scope larger than a bugfix
-
-    Listing the fix produced [N] tasks / [cross-file deps] / [forbidden change type].
-    Per the safety valve, this is no longer a surgical bugfix.
-
-    Bugfix index preserved at `.dw/bugfixes/NNN-<slug>/{TASK.md, escalated.md}`.
-    PRD created at `.dw/spec/prd-bugfix-<slug>/prd.md`.
-
-    Next — pick one:
-      - Manual chain: `/dw-plan techspec prd-bugfix-<slug>` → `/dw-plan tasks prd-bugfix-<slug>` → `/dw-run` → `/dw-qa` → `/dw-review` → `/dw-commit` → `/dw-generate-pr`.
-      - Hand off to autopilot: `/dw-autopilot --from-prd prd-bugfix-<slug>` — runs the planning phase from the existing PRD, stops after Tasks, then a later autopilot invocation resumes through `/dw-goal`.
-    ```
+    Inspect the proposed fix for material scope or architecture changes. Task count, file count, ordering dependencies and larger estimates are signals to organize work, not automatic blockers. Refactoring required to fix approved behavior can remain in scope. A new product contract, sensitive migration or unresolved architecture decision needs a concrete proposal before dependent implementation.
 
-    5. Stop this command. Do not proceed to step 5. The user (or autopilot) invokes `/dw-plan` or `/dw-autopilot --from-prd` next.
+    When a structured plan is needed, preserve `.dw/bugfixes/NNN-<slug>/TASK.md`, create `.dw/spec/prd-bugfix-<slug>/prd.md` using the bugfix template, and record the cross-reference in `escalated.md`. Continue through `/dw-plan` or `/dw-autopilot --from-prd prd-bugfix-<slug>` according to existing user intent. The task breakdown proposes executor/model/agents; after approval continue in the same invocation. Do not re-ask permission to organize an already authorized fix. An analysis-only request still ends with its report.
 
-    **If the valve does NOT trip:** Continue to step 5.
+    If no material new decision or structured plan is needed, continue to step 5.
 
     ### 5. Propose Numbered Tasks (Required)
 
     <critical>
     List ALL necessary tasks, numbered sequentially.
-    Wait for approval before executing.
+    Use existing approval for the same task scope; ask only for new material decisions before executing.
     </critical>
 
     **Format:**
@@ -425,8 +399,8 @@
 
     Option B (hand off to autopilot):
     1. Run: `/dw-autopilot --from-prd prd-bugfix-<slug>`
-    2. Autopilot runs PRD approval, TechSpec, and Tasks, then stops with `status: plan_complete`.
-    3. A later autopilot invocation resumes via `/dw-goal --from-autopilot prd-bugfix-<slug>` for Run, full Review, QA/Fix, and post-QA full Review before commit/PR.
+    2. Autopilot runs PRD approval, TechSpec, and Tasks, records `status: plan_complete` and continues after task/execution approval.
+    3. The same invocation continues via `/dw-goal --from-autopilot prd-bugfix-<slug>` for Run, full Review, QA/Fix, and post-QA full Review before commit/PR.
 
     The bugfix index entry stays queryable via `/dw-intel "bugfix history in <module>"`. Downstream `/dw-review --bugfix <slug>` and `/dw-qa --bugfix <slug>` still target `.dw/bugfixes/NNN-<slug>/` when you want a focused review of just the eventual surgical patch.
     ```