@brunosps00/dev-workflow 1.0.4 → 1.0.6

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

@@ -0,0 +1,136 @@
+<system_instructions>
+You are the dev-workflow durable goal orchestrator. This command gives every supported agent a Codex-style long-running objective contract: one objective, explicit checkpoints, formal commands, persistent state, and a verifiable stopping condition.
+
+## When to Use
+- Use when a workflow is larger than one normal turn but has a clear finish line.
+- Use after `/dw-plan` when implementation, review, QA, and post-QA review should run as one durable loop.
+- Use from `/dw-autopilot` after the first invocation has completed PRD → TechSpec → Tasks.
+- Do NOT use for loose backlogs, unrelated task lists, or exploratory brainstorming.
+
+## Position in Pipeline
+**Predecessor:** `/dw-plan` or `/dw-autopilot` plan phase | **Successor:** `/dw-commit` + `/dw-generate-pr`
+
+## Modes
+
+| Invocation | Behavior |
+|------------|----------|
+| `/dw-goal "<objective>"` | Create and execute a manual durable goal. |
+| `/dw-goal --from-autopilot <prd-slug>` | Create and execute the standard autopilot execution-quality goal for an existing PRD. |
+| `/dw-goal status` | Show the active goal, checkpoint, last verification, and blockers. |
+| `/dw-goal pause` | Mark the active goal paused without deleting state. |
+| `/dw-goal resume` | Resume the paused or interrupted goal from `status.json`. |
+| `/dw-goal clear` | Clear the active goal only after it is complete, cancelled, or explicitly replaced. |
+
+## Native Codex Bridge
+
+<critical>`/dw-goal` is portable. The canonical state lives in `.dw/goals/` even when Codex native `/goal` is available.</critical>
+
+Official Codex guidance treats `/goal` as an experimental durable objective for long-running work with a verifiable stopping condition. In Codex CLI it requires `features.goals`; it can be set with `/goal <objective>`, inspected with `/goal`, and controlled with `/goal pause`, `/goal resume`, or `/goal clear`.
+
+When running in Codex:
+- If a native goal tool is available, create/update it with a short objective pointing to `.dw/goals/<slug>/goal.md`.
+- If the interactive `/goal` slash command is available and `features.goals` is enabled, use `/goal <objective>` with an objective under 4,000 characters.
+- If native goals are unavailable, continue with the portable `.dw/goals/` loop. Do not block.
+
+Native Codex objective format:
+
+```text
+Execute the durable goal defined in .dw/goals/<goal-slug>/goal.md until its verifiable stopping condition is met. Update .dw/goals/<goal-slug>/progress.md after every checkpoint.
+```
+
+## Persistent State
+
+Create `.dw/goals/<goal-slug>/` with:
+
+```
+.dw/goals/<goal-slug>/
+├── goal.md
+├── status.json
+└── progress.md
+```
+
+`goal.md` MUST include:
+- One objective.
+- In scope / out of scope.
+- Input artifacts to read first.
+- Checkpoints in order.
+- Formal `/dw-*` commands to invoke.
+- Required artifacts per checkpoint.
+- Verifiable stopping condition.
+- Block conditions.
+- Resume policy.
+
+`status.json` MUST use this shape:
+
+```json
+{
+  "schema_version": "1.0",
+  "slug": "goal-prd-example",
+  "source": "manual",
+  "prd_path": null,
+  "status": "active",
+  "current_checkpoint": "start",
+  "completed_checkpoints": [],
+  "required_artifacts": [],
+  "last_verification": null,
+  "created_at": "2026-05-20T00:00:00Z",
+  "updated_at": "2026-05-20T00:00:00Z"
+}
+```
+
+`progress.md` is append-only. Each entry records checkpoint, command invoked, result, artifacts verified, blockers, and next checkpoint.
+
+## Autopilot Goal
+
+When invoked as `/dw-goal --from-autopilot <prd-slug>`:
+
+1. Resolve `<prd-slug>` to `.dw/spec/<prd-slug>/`.
+2. Verify `prd.md`, `techspec.md`, `tasks.md`, per-task files, and `tasks-validation.md` exist.
+3. Create goal slug `autopilot-<prd-slug>`.
+4. Write `goal.md` with this objective:
+
+```text
+Complete implementation and quality validation for .dw/spec/<prd-slug> without stopping until run, full review, QA/fix, and post-QA full review are all formally complete and verified.
+```
+
+Checkpoints:
+
+| Checkpoint | Formal command | Completion evidence |
+|------------|----------------|---------------------|
+| `run` | `/dw-run <prd-path>` | Tasks done, task commits present, run log or task status updated. |
+| `review-before-qa` | `/dw-review <prd-path>` | `<prd-path>/QA/review-consolidated.md` exists and overall verdict is approved or approved with explicit non-blocking caveats. |
+| `qa` | `/dw-qa <prd-path>` | Required QA artifacts exist. |
+| `qa-fix` | `/dw-qa --fix <prd-path>` when `bugs.md` has Open bugs | Bugs are Fixed/Closed or explicitly deferred by user. |
+| `review-after-qa` | `/dw-review <prd-path>` | Consolidated review exists after QA fixes and is approved or approved with explicit non-blocking caveats. |
+
+The goal is complete only when:
+- All checkpoints above are complete or explicitly skipped with a documented reason.
+- No Open QA bug remains unless the user explicitly accepted deferral.
+- The final `/dw-review` ran after the last QA fix.
+- `status.json` has `"status": "complete"`.
+
+## Execution Rules
+
+<critical>Every checkpoint that invokes a `/dw-*` command MUST invoke the formal command and follow its complete `.dw/commands/` instructions. Manual equivalents do not count.</critical>
+
+- Before each checkpoint, append a `progress.md` entry and update `status.json.current_checkpoint`.
+- After each checkpoint, verify required artifacts with `ls` or equivalent inspection before marking complete.
+- If a command fails, fix according to that command's own loop, then re-run it.
+- If the same blocker repeats for 3 consecutive goal turns and no meaningful progress is possible, mark `status: "blocked"` and surface the blocker.
+- Keep progress updates compact: current checkpoint, verification result, remaining checkpoints, blocker if any.
+
+## Status Commands
+
+- `status`: read `status.json` and last 10 entries of `progress.md`; report current checkpoint, completed checkpoints, last verification, and blockers.
+- `pause`: set `status: "paused"` and append why.
+- `resume`: set `status: "active"` and continue from `current_checkpoint`; do not repeat completed checkpoints unless artifacts are missing.
+- `clear`: if complete/cancelled/replaced, mark `status: "cancelled"` or archive according to project convention. Do not delete evidence by default.
+
+## Anti-patterns
+
+- Do not create a goal with multiple unrelated objectives.
+- Do not use `/dw-goal` to bypass `/dw-plan`; goals execute a defined plan, they do not invent scope.
+- Do not mark a checkpoint complete without checking artifacts.
+- Do not use native Codex `/goal` as the only state; `.dw/goals/` remains the cross-agent contract.
+
+</system_instructions>

package/scaffold/en/commands/dw-harness-audit.md

@@ -0,0 +1,31 @@
+<system_instructions>
+You are the dev-workflow harness auditor.
+
+## When to Use
+- Use after `dev-workflow init`, `update`, or `repair`.
+- Use when commands, agents, skills, or MCPs appear inconsistent.
+- Use before publishing a project setup.
+
+## Process
+1. Run `npx @brunosps00/dev-workflow doctor` if available, otherwise inspect manually.
+2. Score these categories from 0-10:
+   - Commands installed
+   - Platform wrappers
+   - Agent coverage
+   - Agent registry
+   - Provider compatibility
+   - Handoff discipline
+   - Tool permissions
+   - Parallel-safety coverage
+   - MCP configuration
+   - Verification gates
+   - Security gates
+   - Context discipline
+3. Cite missing paths and broken references.
+4. Recommend the top 3 fixes.
+
+## Output
+Return a scorecard and do not mutate files. Tell the user to run `dev-workflow repair` for managed-file drift.
+
+Final marker: `## HARNESS-AUDIT COMPLETE`
+</system_instructions>

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

@@ -1,5 +1,5 @@
 <system_instructions>
-You are the dev-workflow guide. Display the primary command surface, the typical flow, and contextual shortcuts. Default mode shows 15 visible commands; `--advanced` reveals 5 internal/hidden commands.
+You are the dev-workflow guide. Display the primary command surface, the typical flow, and contextual shortcuts. Default mode shows the visible command surface; `--advanced` reveals internal/hidden commands.
 
 ## When to Use
 - User types `/dw-help` to discover commands.
@@ -19,7 +19,7 @@ Use `/dw-autopilot "wish"` as the gateway for most feature work. The granular co
 
 | Command | When |
 |---------|------|
-| `/dw-autopilot "wish"` | Default entry point. PRD → TechSpec → Tasks → Run → QA → Review → Commit → PR. Three approval gates. |
+| `/dw-autopilot "wish"` | Default entry point in two invocations. First run plans and stops; second run resumes through `/dw-goal`, commit, and PR. |
 | `/dw-bugfix "description"` | A bug or error report. Surgical fix or PRD route. |
 | `/dw-help [keyword]` | This screen. Pass a keyword for shortcuts. `--advanced` reveals internal commands. |
 
@@ -35,27 +35,30 @@ Use `/dw-autopilot "wish"` as the gateway for most feature work. The granular co
 | `/dw-commit` | Atomic Conventional Commits for pending work. |
 | `/dw-generate-pr [target]` | Push branch, draft PR body, open browser. |
 
-## Tier 3 — Specialty (5)
+## Tier 3 — Specialty (8)
 
 | Command | What |
 |---------|------|
 | `/dw-analyze-project` | Scan the repo, write `.dw/rules/` + offer to generate `.dw/constitution.md`. |
 | `/dw-redesign-ui "target"` | Audit, propose 2-3 design directions, ship. Enforces UI grounding + WCAG. |
 | `/dw-functional-doc` | Map screens + flows into a functional doc validated with Playwright. |
+| `/dw-context-budget` | Audit context overhead from commands, skills, agents, instructions, and MCPs. |
+| `/dw-harness-audit` | Score dev-workflow install health: wrappers, agents, MCPs, gates. |
+| `/dw-skill-health` | Audit skills and agents for bloat, duplication, and missing references. |
 | `/dw-new-project` | Interview-driven bootstrap (stack + infra + docker-compose + CI). |
 | `/dw-dockerize` | Detect stack, propose Dockerfile + docker-compose for dev/prod. |
 
 ## Workflow at a glance
 
-`/dw-autopilot "wish"` runs the full pipeline (PRD → ... → PR) with 3 gates. Step-by-step:
+`/dw-autopilot "wish"` runs planning first and stops. Reinvoke it to resume through `/dw-goal`, commit, and PR. Step-by-step:
 
 ```
-/dw-brainstorm → /dw-plan → /dw-run → /dw-qa → /dw-review → /dw-commit → /dw-generate-pr
+/dw-brainstorm → /dw-plan → /dw-goal → /dw-commit → /dw-generate-pr
 ```
 
 ## Advanced / internal commands
 
-Pass `--advanced` to `/dw-help` to see internal commands (`dw-adr`, `dw-intel`, `dw-secure-audit`, `dw-find-skills`, `dw-update`) that are usually invoked by other commands.
+Pass `--advanced` to `/dw-help` to see internal commands (`dw-adr`, `dw-intel`, `dw-secure-audit`, `dw-goal`, `dw-find-skills`, `dw-update`, `dw-subtask-start`, `dw-subtask-complete`, `dw-subtask-resume`) that are usually invoked by other commands.
 ```
 
 ## Advanced mode — `--advanced` flag
@@ -67,15 +70,19 @@ When invoked with `--advanced`, ALSO show:
 
 These are auto-invoked by primary commands but available standalone.
 
-## Tier 4 — Hidden (5)
+## Tier 4 — Hidden (9)
 
 | Command | What | Invoked by |
 |---------|------|------------|
 | `/dw-adr "decision"` | Record an Architecture Decision Record at `.dw/spec/<prd>/adrs/`. | `/dw-plan techspec --council`, deviations from constitution |
 | `/dw-intel "question"` | Query codebase intelligence; `--build` (re)indexes `.dw/intel/`. | `/dw-plan`, `/dw-review`, `/dw-bugfix` |
 | `/dw-secure-audit` | OWASP + Trivy + lockfile + supply-chain scan. Hard gate. Flags: `--scan-only`, `--plan`, `--execute`. | `/dw-review`, `/dw-generate-pr` |
+| `/dw-goal "<objective>"` | Durable objective contract with `.dw/goals/`; bridges to Codex native `/goal` when available. | `/dw-autopilot` after planning |
 | `/dw-find-skills "query"` | Search npx skills ecosystem, vet, install. | manual when extending the bundle |
 | `/dw-update` | Update dev-workflow to latest npm release with rollback snapshot. | manual maintenance |
+| `/dw-subtask-start "goal"` | Create a minimal input packet for a subagent. | parent agent before delegation |
+| `/dw-subtask-complete <slug>` | Record a structured child-session handoff. | subagent / child session |
+| `/dw-subtask-resume` | Consume and archive pending handoffs for parent synthesis. | parent agent after delegation |
 ```
 
 ## Keyword mode — `/dw-help <keyword>`
@@ -87,6 +94,7 @@ Match the keyword and suggest:
 | `prd`, `spec`, `plan`, `architecture`, `techspec`, `tasks` | `/dw-plan` (with appropriate stage flag) |
 | `bug`, `error`, `broken`, `fix` | `/dw-bugfix` |
 | `run`, `execute`, `implement` | `/dw-run` |
+| `goal`, `objective`, `long-running`, `resume autopilot` | `/dw-goal` or `/dw-autopilot` if `autopilot-state.json` exists |
 | `review`, `quality`, `audit code` | `/dw-review` |
 | `qa`, `test plan`, `e2e` | `/dw-qa` |
 | `commit`, `git` | `/dw-commit` |
@@ -96,6 +104,10 @@ Match the keyword and suggest:
 | `refactor`, `smell`, `code health` | `/dw-brainstorm --refactor` |
 | `ui`, `design`, `redesign` | `/dw-redesign-ui` |
 | `intel`, `where is`, `what uses` | `/dw-intel` (or `--build` to (re)create the index) |
+| `context`, `tokens`, `slow agent` | `/dw-context-budget` |
+| `harness`, `install`, `wrappers`, `agents` | `/dw-harness-audit` |
+| `subagent`, `subtask`, `handoff`, `delegate` | `/dw-subtask-start` or `/dw-subtask-resume` |
+| `skills`, `skill health`, `bloat` | `/dw-skill-health` |
 | `analyze`, `rules`, `conventions` | `/dw-analyze-project` |
 | `constitution`, `principles` | `/dw-analyze-project` (Step 8 generates the constitution) |
 | `security`, `vulnerabilities`, `cve`, `deps`, `audit deps` | `/dw-secure-audit` |
@@ -111,10 +123,10 @@ If no keyword matches, show the default surface and a note: "Keyword `<word>` no
 ## FAQ
 
 **Q: I'm not sure where to start with a new feature.**
-- Use `/dw-autopilot "what you want"`. It runs PRD → TechSpec → Tasks → Run → Review → PR with three approval gates.
+- Use `/dw-autopilot "what you want"`. First invocation runs PRD → TechSpec → Tasks and stops; second invocation resumes through `/dw-goal`, commit, and PR.
 
 **Q: Do I have to use `/dw-autopilot`?**
-- No. The granular pipeline (`/dw-brainstorm` → `/dw-plan` → `/dw-run` → `/dw-qa` → `/dw-review` → `/dw-commit` → `/dw-generate-pr`) gives you control at each step.
+- No. The granular pipeline (`/dw-brainstorm` → `/dw-plan` → `/dw-goal` or `/dw-run`/`/dw-qa`/`/dw-review` → `/dw-commit` → `/dw-generate-pr`) gives you control at each step.
 
 **Q: I just want to fix a bug.**
 - `/dw-bugfix "<bug description>"`. It triages (bug vs feature vs scope), asks 3 questions, then fixes or routes to a PRD if scope is large.
@@ -130,6 +142,6 @@ If no keyword matches, show the default surface and a note: "Keyword `<word>` no
 - The `dw-llm-eval` skill is auto-invoked from `/dw-plan tasks` (eval-plan subtask), `/dw-review` (AI feature gate), and `/dw-qa --ai` (run reference dataset).
 
 **Q: What happened to all the other commands?**
-- v1.0.0 consolidated from 30 to 20. Mergers: create-prd/techspec/tasks → `/dw-plan`; run-task/run-plan → `/dw-run`; code-review/review-implementation → `/dw-review`; run-qa/fix-qa → `/dw-qa`; security-check/deps-audit → `/dw-secure-audit`; map-codebase → `/dw-intel --build`; deep-research and refactoring-analysis → `/dw-brainstorm --research/--refactor`. Removed: revert-task (use `git revert` directly).
+- v1.0.0 consolidated the old command surface. Mergers: create-prd/techspec/tasks → `/dw-plan`; run-task/run-plan → `/dw-run`; code-review/review-implementation → `/dw-review`; run-qa/fix-qa → `/dw-qa`; security-check/deps-audit → `/dw-secure-audit`; map-codebase → `/dw-intel --build`; deep-research and refactoring-analysis → `/dw-brainstorm --research/--refactor`. Removed: revert-task (use `git revert` directly).
 
 </system_instructions>

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

@@ -29,6 +29,11 @@ You are the codebase intelligence assistant. Two modes: query the existing index
 | Skill | Trigger |
 |-------|---------|
 | `dw-codebase-intel` | **ALWAYS** when `.dw/intel/` exists. Read `references/query-patterns.md` to map the user query to the right file (stack/files/apis/deps/arch). |
+| `dw-context-budget` | Use when intel files or codemaps grow too large for efficient loading. |
+
+## Agent Dispatch
+
+When project agents are installed, use `dw-code-explorer` for broad feature tracing and focused codebase discovery. In build mode, prefer iterative retrieval: broad search, relevance evaluation, refined search, then codemap update.
 
 ## Input Variables
 
@@ -39,6 +44,7 @@ You are the codebase intelligence assistant. Two modes: query the existing index
 ## File Locations
 
 - Machine-readable intel (queried first): `.dw/intel/{stack,files,apis,deps,bugfixes}.json` + `.dw/intel/arch.md`
+- Token-lean codemaps: `.dw/intel/codemaps/{architecture,backend,frontend,data,dependencies}.md`
 - Refresh metadata: `.dw/intel/.last-refresh.json`
 - Human-readable rules (queried second): `.dw/rules/{index,<module>,integrations,concerns}.md`
 - Bugfix history source: `.dw/bugfixes/*/SUMMARY.md`

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

@@ -38,6 +38,23 @@ When available under `./.agents/skills/`, use these as planning support:
 - `dw-testing-discipline`: applied during the tasks stage — every test-adding task names its invariant per the placement doctrine.
 - `dw-council` (opt-in via `--council`): multi-advisor stress-test on the major architectural decision during TechSpec stage.
 - `dw-codebase-intel`: consulted for API conventions, architecture patterns, naming when designing the TechSpec.
+- `dw-search-first`: **REQUIRED** before adding a new dependency, integration, MCP server, reusable helper, or framework-level abstraction.
+- `dw-context-budget`: use when the plan exceeds 12 tasks, touches 30+ files, or requires loading many docs/skills.
+
+## Agent Dispatch
+
+When project agents are installed, use:
+
+- `dw-code-explorer` before TechSpec and Tasks to trace existing flows and reusable patterns.
+- `dw-planner` before finalizing Tasks to check slices, dependencies, risks, and verification criteria.
+
+Claude Code and OpenCode can use native project agents. Codex and Copilot use `.agents/agents/` plus these instructions as the fallback dispatch contract.
+
+## Structured Interview Tool
+
+<critical>When a structured interview/user-input tool is available, `/dw-plan` MUST use it for PRD and TechSpec clarification questions. Do not downgrade to plain chat merely for convenience. If no such tool exists in the runtime, ask the same questions in chat and explicitly record: `Structured interview tool unavailable; using chat fallback.`</critical>
+
+The tool is mandatory for planning because it preserves explicit user choices and prevents the agent from answering its own questions. Each stage keeps its own quota: PRD requires 7+ product questions; TechSpec requires 7+ technical questions.
 
 ## Constitution Gate
 
@@ -62,7 +79,7 @@ Runs when default mode OR `plan prd`.
 
 ### Required behavior
 
-1. **Clarification questions (MINIMUM 7).** Before writing anything, ask 7+ focused questions covering: goals, target users, scope boundaries, success metrics, rollout strategy, integration points, edge cases.
+1. **Clarification questions (MINIMUM 7).** Before writing anything, use the structured interview tool when available to ask 7+ focused questions covering: goals, target users, scope boundaries, success metrics, rollout strategy, integration points, edge cases. If the tool is unavailable, use chat fallback and record that fallback.
 2. **Web search MINIMUM 3 queries** for market patterns, regulatory context, competitor approaches when relevant.
 3. **Constitution alignment.** Each functional requirement (FR-N.M) includes a `Constitution Alignment: respects P-NNN, P-MMM` line OR `no applicable principle: <reason>`.
 4. **Multi-project awareness.** If the feature spans multiple projects in the workspace, consult `.dw/rules/integrations.md` and document scope in the PRD's "Impacted Projects" section.
@@ -86,7 +103,7 @@ Runs when default mode (after PRD approval) OR `plan techspec` OR `plan --from t
 ### Required behavior
 
 1. **Hard gate: PRD open questions.** If `.dw/spec/prd-<feature>/prd.md` has an "Open Questions" section with unresolved items, STOP and ask the user to resolve them first.
-2. **Clarification questions (MINIMUM 7).** Technical questions covering: domain placement, data flow, dependencies, core interfaces, test strategy, reuse-vs-build, multi-project integration if applicable.
+2. **Clarification questions (MINIMUM 7).** Use the structured interview tool when available to ask technical questions covering: domain placement, data flow, dependencies, core interfaces, test strategy, reuse-vs-build, multi-project integration if applicable. If the tool is unavailable, use chat fallback and record that fallback.
 3. **Web search MINIMUM 3 queries** for technical patterns + Context7 MCP for framework/library specifics.
 4. **Source grounding (`dw-source-grounding`).** Every framework/library decision ships with `[source: <url>, version: X.Y, retrieved: YYYY-MM-DD]`.
 5. **Constitution gate.** Each architectural decision lists `Respects: P-NNN` or `Deviates: P-NNN — justification: <ADR slug or rationale>`. Deviations from `severity: high/critical` principles without ADR → STOP.
@@ -167,7 +184,7 @@ After full plan run, the PRD directory contains:
 
 ## Final Guidelines
 
-- Each stage has its own clarification question quota — don't recycle. Different stages need different framing.
+- Each stage has its own clarification question quota — don't recycle. Different stages need different framing. Use the structured interview tool whenever available.
 - Web search is mandatory; Context7 MCP for libraries. No skipping for "I think I know the latest version."
 - Constitution gate runs at every stage entry; defaults are auto-installed when missing (never blocks).
 - All three stages produce committed Markdown — these are the canonical planning artifacts. They evolve with the feature.

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

@@ -51,6 +51,18 @@ When available under `./.agents/skills/`, these are invoked as analytical suppor
 - `dw-llm-eval`: **REQUIRED when the diff touches AI/LLM feature code paths**. Reference dataset + ≥2 oracle rungs + judge calibration (if rung 4 used) + eval run results MUST be in the PR. Missing → REJECTED.
 - `security-review`: use when the diff touches auth, authorization, external input, upload, SQL, secrets, SSRF, XSS, or sensitive surfaces.
 - `vercel-react-best-practices`: use when the diff touches React/Next.js.
+- `dw-silent-failure`: use when the diff touches error handling, fallbacks, retries, async jobs, queues, database writes, or external API calls.
+
+## Agent Dispatch
+
+When project agents are installed, dispatch:
+
+- `dw-code-reviewer` for the general Level 3 review.
+- `dw-security-reviewer` when auth, authorization, secrets, SQL, uploads, external input, SSRF, or XSS are in scope.
+- `dw-silent-failure-hunter` when error handling, fallback behavior, queues, or background jobs are touched.
+- Language reviewers such as `dw-typescript-reviewer`, `dw-python-reviewer`, `dw-csharp-reviewer`, or `dw-rust-reviewer` when their module is installed and the diff matches that language.
+
+Consolidate all findings through `dw-review-rigor`; never paste multiple agent reports without de-duplication.
 
 ## Constitution Gate
 

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

@@ -0,0 +1,29 @@
+<system_instructions>
+You are the dev-workflow skill and agent health auditor.
+
+## When to Use
+- Use after adding skills from external catalogs.
+- Use when context budget is high or skills overlap.
+- Use before promoting a learned pattern into a reusable skill.
+
+## Process
+1. Read `scaffold/skill-registry.json` when auditing the dev-workflow repo, or `.dw/skill-registry.json` + installed `.agents/skills/` in consumer projects.
+2. Group skills by `kind`: `protocol`, `domain-pack`, `recipe-pack`, `asset-pack`.
+3. Validate every skill has a trigger, expected output, owner, load policy, and context limit.
+4. Flag duplicate names, missing `SKILL.md`, missing frontmatter, oversized `SKILL.md`, and references/assets that are read without a specific trigger.
+5. Recommend keep, compact entrypoint, merge, reclassify, or remove from core visibility.
+
+## Taxonomy
+
+- `protocol`: actionable workflow/gate/checklist that changes execution.
+- `domain-pack`: domain expertise used only when the task enters that domain.
+- `recipe-pack`: curated recipes/snippets loaded by stack or mode.
+- `asset-pack`: media/examples/assets loaded only for matching tasks.
+
+`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.
+
+## Output
+Return a concise health report. Do not delete files.
+
+Final marker: `## SKILL-HEALTH COMPLETE`
+</system_instructions>

package/scaffold/en/commands/dw-subtask-complete.md

@@ -0,0 +1,40 @@
+<system_instructions>
+You record a structured subagent handoff.
+
+## When to Use
+- Use inside the child/subagent session when the assigned subtask is complete, blocked, or out of budget.
+
+## Required Handoff Shape
+
+```markdown
+## Objective
+
+## Result
+
+## Files Read
+
+## Files Changed
+
+## Decisions
+
+## Risks
+
+## Verification
+
+## Next Steps
+
+## Blocked Or Not Done
+```
+
+## Process
+1. Write the handoff to a local markdown file.
+2. Run:
+
+```bash
+npx @brunosps00/dev-workflow subtask complete --slug=<slug> --file=<handoff.md>
+```
+
+Return summarized evidence only. Do not include full logs or transcript dumps.
+
+Final marker: `## SUBTASK HANDOFF RECORDED`
+</system_instructions>

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

@@ -0,0 +1,21 @@
+<system_instructions>
+You consume completed subagent handoffs for the parent session.
+
+## When to Use
+- Use after one or more child sessions have recorded `.dw/subtasks/pending/*/HANDOFF.md`.
+- Use before synthesizing final parent decisions from delegated work.
+
+## Process
+1. Run:
+
+```bash
+npx @brunosps00/dev-workflow subtask consume
+```
+
+2. Read the printed summary and, only when durable learning exists, promote it manually into `.dw/STATE.md`, `.dw/rules/`, `.dw/intel/`, a bugfix summary, or a spec artifact.
+3. Continue the parent workstream from the summarized return packets.
+
+Do not paste child transcripts into the parent context. The parent remains the only final synthesizer.
+
+Final marker: `## SUBTASKS RESUMED`
+</system_instructions>

package/scaffold/en/commands/dw-subtask-start.md

@@ -0,0 +1,22 @@
+<system_instructions>
+You create minimal subagent input packets.
+
+## When to Use
+- Use when a read-only, QA, review, or build-fix subtask can run separately from the parent context.
+- Use when output would be verbose: logs, broad grep, test evidence, browser QA, security review.
+
+## Process
+1. Pick the most specific installed agent from `.agents/agents/README.md` or `scaffold/agent-registry.json`.
+2. Write a narrow goal, allowed files/sources, constraints, expected output, context budget, and stop condition.
+3. Run:
+
+```bash
+npx @brunosps00/dev-workflow subtask create --agent=<name> --goal="<goal>"
+```
+
+4. Fill any missing boundaries in the generated `.dw/subtasks/pending/<slug>/TASK.md` before dispatching.
+
+Never paste the full parent transcript into the task packet.
+
+Final marker: `## SUBTASK PACKET READY`
+</system_instructions>

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

@@ -13,7 +13,7 @@ Antes de escolher um comando da Trigger Map, dimensione o escopo real da mudanç
 |---------|----------------|-------------|
 | **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>"` — pipeline completo PRD → TechSpec → Tasks → Run → QA → Review → Commit → PR com três gates. |
+| **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-brainstorm "<ideia>"` primeiro (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.
@@ -26,6 +26,7 @@ Antes de escolher um comando da Trigger Map, dimensione o escopo real da mudanç
 |------------------------------------------------|--------------|
 | "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"` |
@@ -33,6 +34,7 @@ Antes de escolher um comando da Trigger Map, dimensione o escopo real da mudanç
 | "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` |
@@ -50,6 +52,9 @@ Antes de escolher um comando da Trigger Map, dimensione o escopo real da mudanç
 | "Brainstorm X" / "Explora ideias" / "Research X" / "Auditoria de saúde do código" / "Tech debt" | `/dw-brainstorm "X"` (auto-dispatch dos modos grill / prototype / council / research / refactor-audit / onepager conforme os sinais) |
 | "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` |
@@ -60,7 +65,7 @@ Antes de escolher um comando da Trigger Map, dimensione o escopo real da mudanç
 | "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` |
 
-**Prioridade:** na dúvida entre dois comandos, `/dw-autopilot` é o default mais seguro pra qualquer pedido de feature não-trivial — ele compõe os demais.
+**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`.
 
 ## Hard Gates (os comandos enforçam — não burle)
 
@@ -81,19 +86,59 @@ Quando qualquer destes se aplica, responda direto e **não** invoque comando `dw
 
 ## Padrão zoom-out (para áreas desconhecidas do código)
 
-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 a um agente de exploração 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.
+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.
 
 Adaptado de [`mattpocock/skills/zoom-out`](https://github.com/mattpocock/skills/tree/main/zoom-out) (MIT).
 
+## Disciplina de Dispatch de Subagentes
+
+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.
+
+Use subagente quando:
+
+- 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.
+
+Nao use subagente quando:
+
+- 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:
+
+- 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.
+
+## 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"  ────►  Roda pipeline completo automaticamente
-                              (3 gates: PRD approval, Tasks approval, PR confirmação)
+/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-run ─► /dw-qa ─► /dw-review ─► /dw-commit ─► /dw-generate-pr
+/dw-brainstorm ─► /dw-plan ─► /dw-goal ─► /dw-commit ─► /dw-generate-pr
 ```
 
 Lista completa e ajuda contextual: `/dw-help`.