@brunosps00/dev-workflow 1.0.4 → 1.0.5

package/scaffold/en/agent-instructions.md

@@ -50,6 +50,9 @@ Before picking a command from the Trigger Map, gauge the change's actual scope.
 | "Brainstorm X" / "Explore ideas" / "Research X" / "Code-health audit" / "Find tech debt" | `/dw-brainstorm "X"` (auto-dispatches grill / prototype / council / research / refactor-audit / onepager based on signals) |
 | "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` |
@@ -81,10 +84,50 @@ When any of these apply, answer directly and do **not** invoke a `dw-*` command:
 
 ## Zoom-out pattern (for unfamiliar code areas)
 
-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 an exploring agent 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.
+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.
 
 Adapted from [`mattpocock/skills/zoom-out`](https://github.com/mattpocock/skills/tree/main/zoom-out) (MIT).
 
+## Subagent Dispatch Discipline
+
+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.
+
+Use a subagent when:
+
+- 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:
+
+- 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.
+
+## Skill Loading Discipline
+
+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`.
+
 ## Workflow Reference
 
 ```

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

@@ -44,6 +44,15 @@
     - `dw-testing-discipline`: use when the fix requires a reproducible E2E/retest flow in a web app — `references/playwright-recipes.md` for recipes, core rules + 6 agent guardrails for any test the fix adds, flaky-discipline if the bug surfaces intermittently.
     - `dw-incident-response`: use when the bug has severity `critical` AND affects production AND was detected by alert/user-report (i.e., the bug IS an incident, not a backlog item). Triggers the 5-phase workflow (triage → investigation → resolution → communication → postmortem) with structured output in `.dw/incidents/`. Fixes ride on `/dw-bugfix` per the incident's resolution phase.
     - `security-review`: use when the root cause touches auth, authorization, external input, upload, secrets, SQL, XSS, SSRF, or other sensitive surfaces
+    - `dw-silent-failure`: use when the symptom may be hidden by swallowed errors, dangerous fallbacks, retries, queue workers, or async detachment
+
+    ## Agent Dispatch
+
+    When project agents are installed:
+    - Start with `dw-code-explorer` to trace reproduction flow and likely owners.
+    - Use `dw-build-fixer` or the language build-fixer only after a build/typecheck/test command fails.
+    - Use `dw-test-author` for the regression test.
+    - Use `dw-silent-failure-hunter` when the bug involves missing errors, incorrect success states, or fallback data.
 
     ## Input Variables
 

package/scaffold/en/commands/dw-context-budget.md

@@ -0,0 +1,28 @@
+<system_instructions>
+You are the context budget auditor for dev-workflow.
+
+## When to Use
+- Use when sessions feel slow, agents read too much, or the project has many skills/MCPs.
+- Use before adding large skill packs or extra MCP servers.
+- Use during `/dw-analyze-project` follow-up when the harness looks bloated.
+
+## Process
+1. Count approximate tokens for `CLAUDE.md`, `AGENTS.md`, `.dw/commands/*.md`, `.agents/skills/*/SKILL.md`, `.agents/agents/*.md`, `.claude/agents/*.md`, `.opencode/agent/*.md`, `.github/agents/*.agent.md`, `.dw/subtasks/pending/*/HANDOFF.md`, and `.claude/settings.json`.
+2. Estimate prose tokens as `words * 1.3`; estimate JSON/tool schemas as `chars / 4`.
+3. Flag:
+   - command files over 20KB,
+   - skill `SKILL.md` files over 12KB,
+   - agent files over 8KB,
+   - missing agent `output_budget_words` in `.dw/agent-registry.json` or scaffold registry,
+   - pending handoffs averaging over 1200 words,
+   - Copilot agents above 30k chars,
+   - more than 10 MCP servers,
+   - duplicate agent/skill names across platform folders,
+   - Claude/OpenCode agent files with provider-incompatible tool or permission fields.
+4. Recommend the top 5 savings with concrete paths.
+
+## Output
+Write a concise report in chat. If `.dw/reports/` exists, also write `.dw/reports/context-budget.md`.
+
+Final marker: `## CONTEXT-BUDGET COMPLETE`
+</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.
@@ -35,13 +35,16 @@ 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. |
 
@@ -55,7 +58,7 @@ Use `/dw-autopilot "wish"` as the gateway for most feature work. The granular co
 
 ## 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-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,7 +70,7 @@ When invoked with `--advanced`, ALSO show:
 
 These are auto-invoked by primary commands but available standalone.
 
-## Tier 4 — Hidden (5)
+## Tier 4 — Hidden (8)
 
 | Command | What | Invoked by |
 |---------|------|------------|
@@ -76,6 +79,9 @@ These are auto-invoked by primary commands but available standalone.
 | `/dw-secure-audit` | OWASP + Trivy + lockfile + supply-chain scan. Hard gate. Flags: `--scan-only`, `--plan`, `--execute`. | `/dw-review`, `/dw-generate-pr` |
 | `/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>`
@@ -96,6 +102,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` |
@@ -130,6 +140,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,17 @@ 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.
 
 ## Constitution Gate
 

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

@@ -50,6 +50,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` |
@@ -81,10 +84,50 @@ 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
 
 ```

package/scaffold/pt-br/commands/dw-bugfix.md

@@ -44,6 +44,15 @@
     - `dw-testing-discipline`: use quando a correção requer fluxo E2E/reteste reproduzível em web app — `references/playwright-recipes.md` pra recipes, core rules + 6 agent guardrails pra qualquer teste que o fix adicione, flaky-discipline se o bug aparece de forma intermitente.
     - `dw-incident-response`: use quando o bug tem severidade `critical` E afeta produção E foi detectado por alerta/user-report (ou seja, o bug É um incident, não item de backlog). Dispara o workflow de 5 fases (triage → investigation → resolution → communication → postmortem) com saída estruturada em `.dw/incidents/`. As correções rodam via `/dw-bugfix` durante a fase de resolution.
     - `security-review`: use quando a causa raiz toca auth, autorização, input externo, upload, secrets, SQL, XSS, SSRF ou outras superfícies sensíveis
+    - `dw-silent-failure`: use quando o sintoma pode estar escondido por erros engolidos, fallbacks perigosos, retries, queue workers ou async detachment
+
+    ## Agent Dispatch
+
+    Quando agentes do projeto estiverem instalados:
+    - Comece com `dw-code-explorer` para rastrear fluxo de reproducao e owners provaveis.
+    - Use `dw-build-fixer` ou o build-fixer de linguagem apenas depois que build/typecheck/test falhar.
+    - Use `dw-test-author` para o regression test.
+    - Use `dw-silent-failure-hunter` quando o bug envolver erros ausentes, success state incorreto ou fallback data.
 
     ## Variáveis de Entrada
 

package/scaffold/pt-br/commands/dw-context-budget.md

@@ -0,0 +1,28 @@
+<system_instructions>
+Voce e o auditor de orcamento de contexto do dev-workflow.
+
+## Quando Usar
+- Use quando sessoes parecerem lentas, agentes lerem arquivos demais, ou o projeto tiver muitas skills/MCPs.
+- Use antes de adicionar pacotes grandes de skills ou novos MCP servers.
+- Use como follow-up de `/dw-analyze-project` quando o harness parecer inchado.
+
+## Processo
+1. Estime tokens de `CLAUDE.md`, `AGENTS.md`, `.dw/commands/*.md`, `.agents/skills/*/SKILL.md`, `.agents/agents/*.md`, `.claude/agents/*.md`, `.opencode/agent/*.md`, `.github/agents/*.agent.md`, `.dw/subtasks/pending/*/HANDOFF.md` e `.claude/settings.json`.
+2. Estime prosa como `palavras * 1.3`; JSON/schema como `chars / 4`.
+3. Aponte:
+   - commands acima de 20KB,
+   - `SKILL.md` acima de 12KB,
+   - agentes acima de 8KB,
+   - agentes sem `output_budget_words` no `.dw/agent-registry.json` ou registry do scaffold,
+   - media de handoffs pendentes acima de 1200 palavras,
+   - agentes Copilot acima de 30k chars,
+   - mais de 10 MCP servers,
+   - nomes duplicados entre pastas de plataforma,
+   - agentes Claude/OpenCode com campos de tools ou permissions incompativeis com o provider.
+4. Recomende as 5 maiores economias com caminhos concretos.
+
+## Saida
+Responda com um relatorio conciso. Se `.dw/reports/` existir, escreva tambem `.dw/reports/context-budget.md`.
+
+Marcador final: `## CONTEXT-BUDGET COMPLETE`
+</system_instructions>

package/scaffold/pt-br/commands/dw-harness-audit.md

@@ -0,0 +1,31 @@
+<system_instructions>
+Voce e o auditor do harness dev-workflow.
+
+## Quando Usar
+- Use apos `dev-workflow init`, `update` ou `repair`.
+- Use quando comandos, agentes, skills ou MCPs parecerem inconsistentes.
+- Use antes de publicar um setup de projeto.
+
+## Processo
+1. Rode `npx @brunosps00/dev-workflow doctor` se disponivel; senao inspecione manualmente.
+2. Pontue de 0-10:
+   - Commands instalados
+   - Wrappers de plataforma
+   - Cobertura de agentes
+   - Registry de agentes
+   - Compatibilidade por provider
+   - Disciplina de handoff
+   - Permissoes de ferramentas
+   - Cobertura de parallel-safety
+   - MCP configuration
+   - Gates de verificacao
+   - Gates de seguranca
+   - Disciplina de contexto
+3. Cite paths ausentes e referencias quebradas.
+4. Recomende os 3 principais fixes.
+
+## Saida
+Retorne um scorecard e nao altere arquivos. Para drift de arquivo gerenciado, indique `dev-workflow repair`.
+
+Marcador final: `## HARNESS-AUDIT COMPLETE`
+</system_instructions>

package/scaffold/pt-br/commands/dw-help.md

@@ -1,5 +1,5 @@
 <system_instructions>
-Você é o guia do dev-workflow. Exibe a surface primária de comandos, o fluxo típico e atalhos contextuais. Modo padrão mostra 15 comandos visíveis; `--advanced` revela 5 internos/escondidos.
+Você é o guia do dev-workflow. Exibe a surface primária de comandos, o fluxo típico e atalhos contextuais. Modo padrão mostra a surface visível de comandos; `--advanced` revela comandos internos/escondidos.
 
 ## Quando Usar
 - Usuário digita `/dw-help` para descobrir comandos.
@@ -33,13 +33,16 @@ Use `/dw-autopilot "desejo"` como gateway pra maior parte do trabalho. Comandos
 | `/dw-commit` | Commits atômicos Conventional pra trabalho pendente. |
 | `/dw-generate-pr [target]` | Push branch, draft do PR body, abre browser. |
 
-## Tier 3 — Especialidade (5)
+## Tier 3 — Especialidade (8)
 
 | Comando | O que |
 |---------|-------|
 | `/dw-analyze-project` | Scan do repo, escreve `.dw/rules/` + oferece gerar `.dw/constitution.md`. |
 | `/dw-redesign-ui "target"` | Audit, propõe 2-3 direções, entrega. Enforça UI grounding + WCAG. |
 | `/dw-functional-doc` | Mapeia screens + flows em doc funcional validado com Playwright. |
+| `/dw-context-budget` | Audita contexto de commands, skills, agentes, instrucoes e MCPs. |
+| `/dw-harness-audit` | Pontua saude da instalacao: wrappers, agentes, MCPs e gates. |
+| `/dw-skill-health` | Audita skills e agentes por bloat, duplicacao e referencias quebradas. |
 | `/dw-new-project` | Bootstrap por entrevista (stack + infra + docker-compose + CI). |
 | `/dw-dockerize` | Detecta stack, propõe Dockerfile + docker-compose pra dev/prod. |
 
@@ -53,7 +56,7 @@ Use `/dw-autopilot "desejo"` como gateway pra maior parte do trabalho. Comandos
 
 ## Comandos avançados / internos
 
-Passe `--advanced` pra ver internos (`dw-adr`, `dw-intel`, `dw-secure-audit`, `dw-find-skills`, `dw-update`) — usualmente invocados por outros comandos.
+Passe `--advanced` pra ver internos (`dw-adr`, `dw-intel`, `dw-secure-audit`, `dw-find-skills`, `dw-update`, `dw-subtask-start`, `dw-subtask-complete`, `dw-subtask-resume`) — usualmente invocados por outros comandos.
 ```
 
 ## Modo advanced — flag `--advanced`
@@ -65,7 +68,7 @@ ALSO show:
 
 Auto-invocados por comandos primários mas disponíveis standalone.
 
-## Tier 4 — Hidden (5)
+## Tier 4 — Hidden (8)
 
 | Comando | O que | Invocado por |
 |---------|-------|--------------|
@@ -74,6 +77,9 @@ Auto-invocados por comandos primários mas disponíveis standalone.
 | `/dw-secure-audit` | OWASP + Trivy + lockfile + supply-chain scan. Hard gate. Flags: `--scan-only`, `--plan`, `--execute`. | `/dw-review`, `/dw-generate-pr` |
 | `/dw-find-skills "query"` | Busca npx skills ecosystem, valida, instala. | manual ao estender bundle |
 | `/dw-update` | Atualiza dev-workflow pro último release npm com snapshot rollback. | manutenção manual |
+| `/dw-subtask-start "goal"` | Cria um input packet minimo para subagente. | parent antes de delegar |
+| `/dw-subtask-complete <slug>` | Registra handoff estruturado da sessao child. | subagente / sessao child |
+| `/dw-subtask-resume` | Consome e arquiva handoffs pendentes para sintese do parent. | parent apos delegacao |
 ```
 
 ## Modo keyword — `/dw-help <palavra-chave>`
@@ -92,6 +98,10 @@ Auto-invocados por comandos primários mas disponíveis standalone.
 | `refactor`, `smell`, `code health` | `/dw-brainstorm --refactor` |
 | `ui`, `design`, `redesign` | `/dw-redesign-ui` |
 | `intel`, `onde está`, `o que usa` | `/dw-intel` (ou `--build`) |
+| `contexto`, `tokens`, `agente lento` | `/dw-context-budget` |
+| `harness`, `install`, `wrappers`, `agentes` | `/dw-harness-audit` |
+| `subagent`, `subtask`, `handoff`, `delegate`, `delegar` | `/dw-subtask-start` ou `/dw-subtask-resume` |
+| `skills`, `skill health`, `bloat` | `/dw-skill-health` |
 | `analyze`, `rules`, `convenções` | `/dw-analyze-project` |
 | `constitution`, `princípios` | `/dw-analyze-project` (Step 8) |
 | `security`, `vulnerabilidades`, `cve`, `deps` | `/dw-secure-audit` |
@@ -122,6 +132,6 @@ Sem match: surface padrão + nota.
 - Skill `dw-llm-eval` auto-invocada de `/dw-plan tasks`, `/dw-review`, `/dw-qa --ai`.
 
 **P: O que aconteceu com outros comandos?**
-- v1.0.0 consolidou 30 → 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 e refactoring-analysis → `/dw-brainstorm --research/--refactor`. Removidos: revert-task (use `git revert` direto).
+- v1.0.0 consolidou a surface antiga de comandos. 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 e refactoring-analysis → `/dw-brainstorm --research/--refactor`. Removidos: revert-task (use `git revert` direto).
 
 </system_instructions>

package/scaffold/pt-br/commands/dw-intel.md

@@ -29,6 +29,11 @@ Voce e o assistente de inteligencia do codebase. Dois modos: consultar o indice
 | Skill | Gatilho |
 |-------|---------|
 | `dw-codebase-intel` | **SEMPRE** quando `.dw/intel/` existir. Leia `references/query-patterns.md` para mapear a query do usuario para o arquivo certo (stack/files/apis/deps/arch). |
+| `dw-context-budget` | Use quando arquivos de intel ou codemaps ficarem grandes demais para carregamento eficiente. |
+
+## Agent Dispatch
+
+Quando agentes do projeto estiverem instalados, use `dw-code-explorer` para rastreamento amplo de feature e descoberta focada do codebase. Em build mode, prefira iterative retrieval: busca ampla, avaliacao de relevancia, busca refinada e depois update de codemap.
 
 ## Variaveis de Entrada
 
@@ -39,6 +44,7 @@ Voce e o assistente de inteligencia do codebase. Dois modos: consultar o indice
 ## Localizacao dos Arquivos
 
 - Intel machine-readable (consulta primeira): `.dw/intel/{stack,files,apis,deps,bugfixes}.json` + `.dw/intel/arch.md`
+- Codemaps token-lean: `.dw/intel/codemaps/{architecture,backend,frontend,data,dependencies}.md`
 - Metadados de refresh: `.dw/intel/.last-refresh.json`
 - Rules human-readable (consulta segunda): `.dw/rules/{index,<modulo>,integrations,concerns}.md`
 - Fonte do historico de bugfixes: `.dw/bugfixes/*/SUMMARY.md`