@brunosps00/dev-workflow 0.15.0 → 1.0.0

package/README.md

@@ -10,7 +10,7 @@ npx @brunosps00/dev-workflow init
 
 This will:
 1. Ask you to select a language (English or Portuguese)
-2. Create `.dw/commands/` with 31 workflow commands
+2. Create `.dw/commands/` with 20 workflow commands
 3. Create `.dw/templates/` with document templates (PRD, TechSpec, Tasks, ADR, etc.)
 4. Create `.dw/rules/` (populated by `/dw-analyze-project`)
 5. Install bundled skills (`dw-verify`, `dw-memory`, `dw-review-rigor`, `dw-ui-discipline`, `dw-testing-discipline`, `security-review`, etc.) to `.agents/skills/`
@@ -26,132 +26,68 @@ npx @brunosps00/dev-workflow install-deps
 
 ## Commands
 
-### Planning
+dev-workflow v1.0.0 ships **20 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
 
-#### `/dw-brainstorm`
-Facilitates structured ideation before opening a PRD or implementation. Explores multiple directions — conservative, balanced, and bold — with trade-offs for each, then converges on concrete next steps. **Product-aware**: when PRDs or rules exist, automatically reads them to produce a Feature Inventory and tags each option as `[IMPROVES: <feature>]`, `[CONSOLIDATES: <A>+<B>]`, or `[NEW]`. With optional `--onepager` flag, generates a durable one-pager at `.dw/spec/ideas/<slug>.md` that `/dw-create-prd` can consume to reduce clarification questions. Inspired by [`addyosmani/agent-skills@idea-refine`](https://skills.sh/addyosmani/agent-skills/idea-refine), adapted to product-level (features) rather than code-level grounding. No code is written or project files modified by the brainstorm itself.
+### Tier 1 — Gateway (3)
 
-#### `/dw-autopilot`
-Full pipeline orchestrator that takes a wish and automatically runs the entire development flow: codebase intelligence (`/dw-map-codebase` + `/dw-intel`), research (conditional), brainstorm, PRD, techspec, tasks, execution (gated by goal-backward plan verification, then wave-based parallel dispatch from the `dw-execute-phase` bundled skill), QA, review, and commit. Stops at 3 gates: PRD approval, tasks approval, and PR confirmation.
+| Command | When |
+|---------|------|
+| **`/dw-autopilot "wish"`** | Default entry point. Full pipeline (PRD → TechSpec → Tasks → Run → QA → Review → Commit → PR) with 3 approval gates. |
+| **`/dw-bugfix "description"`** | A bug report or pasted error. Triages bug-vs-feature-vs-scope, surgical fix or routes to a PRD. |
+| **`/dw-help [keyword]`** | Discover commands. Pass a keyword for shortcuts; `--advanced` reveals internal commands. |
 
-#### `/dw-create-prd`
-Creates a Product Requirements Document by first asking at least 7 clarification questions to fully understand the feature. Generates a structured PRD with numbered functional requirements focused on what and why, saved to `.dw/spec/prd-[feature-name]/prd.md`.
+### Tier 2 — Pipeline granular (7)
 
-#### `/dw-create-techspec`
-Generates a Technical Specification from an existing PRD after performing web searches and asking at least 7 clarification questions. Evaluates existing libraries vs custom development, defines testing strategy, branch naming, and integration architecture. Output is saved to `.dw/spec/prd-[feature-name]/techspec.md`.
+Use these when you want step-by-step control instead of `/dw-autopilot`.
 
-#### `/dw-create-tasks`
-Breaks down the PRD and TechSpec into implementable tasks with a target of ~6 tasks per feature (max 2 functional requirements each). Creates individual task files with subtasks and success criteria, ensuring end-to-end coverage across backend, frontend, and functional UI. Requires approval before finalizing.
+| Command | What |
+|---------|------|
+| **`/dw-brainstorm "idea"`** | Refine an idea before PRD. Flags: `--onepager` (durable artifact), `--council` (multi-advisor debate), `--research` (multi-source cited research), `--refactor` (Fowler code-smell catalog). |
+| **`/dw-plan "feature"`** | PRD → TechSpec → Tasks sequentially with checkpoints. Stages: `prd`, `techspec`, `tasks`. Mandatory clarification questions, source-grounding, constitution gate, final consistency check. |
+| **`/dw-run [task-id]`** | Execute tasks. Default: all pending in dependency order with wave-based parallel dispatch. Single-task: pass an ID. `--resume` continues an interrupted plan. |
+| **`/dw-review`** | Level 2 (PRD coverage mapping) + Level 3 (code quality). Hard gates on dw-verify PASS, secure-audit, constitution violations. Flags: `--coverage-only`, `--code-only`. |
+| **`/dw-qa`** | Mode-aware QA. Auto-detects UI vs API. Flags: `--fix` (iterative QA + fix-retest loop), `--api`, `--ai` (run AI eval against reference dataset). |
+| **`/dw-commit`** | Atomic Conventional Commits for pending changes. Applies `dw-git-discipline` (one intent per commit, lint+tests+build green before). |
+| **`/dw-generate-pr [target]`** | Push the branch, draft a PR body with summary + test plan, open the browser. Hard gates: dw-verify PASS + secure-audit. |
 
-### Execution
+### Tier 3 — Specialty (5)
 
-#### `/dw-run-task`
-Executes a single task from the task list, implementing code that follows project patterns and includes mandatory unit tests. Performs Level 1 validation (acceptance criteria + tests + standards check) and creates a commit upon completion.
+| Command | What |
+|---------|------|
+| **`/dw-analyze-project`** | Scans the repo, writes `.dw/rules/` (per-module conventions, anti-patterns, naming). Step 8 offers to generate `.dw/constitution.md` (declarative principles the team commits to). Run once per project; refresh after major refactors. |
+| **`/dw-redesign-ui "target"`** | Audits a frontend page, runs the `dw-ui-discipline` 4-question grounding, proposes 2-3 design directions, ships the redesign. WCAG 2.2 AA accessibility floor is non-negotiable. |
+| **`/dw-functional-doc`** | Maps screens + user flows into a functional doc, validated end-to-end with Playwright. |
+| **`/dw-new-project`** | Bootstrap a new project from empty directory. Stack interview, wraps official `create-*` tools, composes docker-compose for dev, seeds `.env`, scripts, CI, `.dw/rules/`. |
+| **`/dw-dockerize`** | Reads existing project, detects stack + runtime deps, proposes Dockerfile + docker-compose for dev/prod with explicit trade-offs (Conservative/Balanced/Bold). |
 
-#### `/dw-run-plan`
-Executes all pending tasks via the `dw-execute-phase` bundled skill — gated by 6-dimension goal-backward verification (`plan-checker` agent) before any code is touched. Wave-based parallel dispatch (`executor` agent) for independent tasks; atomic commit per task; deviation handling. After all tasks complete, performs a final Level 2 review (PRD compliance) with an interactive corrections cycle until no gaps remain or the user accepts pending items.
+### Tier 4 — Hidden/Internal (5)
 
-#### `/dw-bugfix`
-Analyzes and fixes bugs with automatic triage that distinguishes between bugs, feature requests, and excessive scope. Asks exactly 3 clarification questions before proposing a solution. Supports Direct mode (executes fix immediately) and Analysis mode (`--analysis`) that generates a document for the techspec/tasks pipeline.
+These are auto-invoked by Tier 1-3 commands. Available standalone via `/dw-help --advanced`.
 
-#### `/dw-redesign-ui`
-Audits existing frontend pages or components, then runs the `dw-ui-discipline` hard-gate (brand authorities or curated defaults, surface job sentence, complete state matrix, scene sentence) before proposing 2-3 design directions. Each direction self-checks against the 14 anti-slop patterns. WCAG 2.2 AA floor is non-negotiable at validation. Framework-agnostic (React, Angular, Vue). Generates a design contract persisted for consistency across tasks.
-
-### Quality
-
-#### `/dw-run-qa`
-Validates the implementation against PRD, TechSpec, and Tasks. **Mode-aware**: in UI mode, drives Playwright MCP for E2E browser tests with happy paths, edge cases, negative flows, regressions, WCAG 2.2 accessibility, and screenshot evidence. In API mode (auto-detected when no UI deps are in the manifest, or forced via `--api`), composes per-RF `.http` / pytest+httpx / supertest / WebApplicationFactory / reqwest scripts from the bundled `api-testing-recipes` skill, executes them, and writes JSONL request/response logs to `QA/logs/api/` as evidence. The matrix expands to {200 happy / 4xx validation/auth/authz/not-found/conflict / 5xx / contract drift / cross-tenant denial}. Optional `--from-openapi` adds a baseline derived from the project's OpenAPI spec. Generates a QA report, documents bugs with mode-aware evidence, and detects stub/placeholder pages (UI) or unmapped spec endpoints (API).
-
-#### `/dw-fix-qa`
-Fixes bugs found during QA testing with evidence-driven retesting. **Mode-aware**: in UI mode replays the failing flow via Playwright MCP and saves a retest screenshot; in API mode replays the failing `.http`/recipe and appends a `verdict: PASS|FAIL` JSONL line to `QA/logs/api/BUG-NN-retest.log`. Runs iterative cycles of identify, fix, retest, updating `QA/bugs.md` and `QA/qa-report.md` with status and mode-correct evidence.
-
-#### `/dw-review-implementation`
-Compares documented requirements (PRD + TechSpec + Tasks) against actual code as a Level 2 review. Maps each requirement to endpoints and tasks with evidence, identifies gaps, partial implementations, and extra undocumented code. After the coverage map is complete, automatically chains `/dw-code-review` (Level 3 quality layer) so a single invocation produces a consolidated coverage + quality report — pass `--no-code-review` if you want only Level 2.
-
-#### `/dw-code-review`
-Performs a formal Level 3 code review before PR creation, verifying PRD compliance, code quality (SOLID, DRY, complexity, security), and conformance with project rules in `.dw/rules/`. Runs tests, verifies coverage targets, and generates a persistent report with APPROVED, APPROVED WITH CAVEATS, or REJECTED status.
-
-#### `/dw-refactoring-analysis`
-Audits the codebase for code smells and refactoring opportunities using Martin Fowler's catalog. Detects bloaters, change preventers, dispensables, couplers, conditional complexity, and DRY violations, then maps each to a concrete refactoring technique with before/after code sketches. Includes coupling/cohesion metrics, SOLID analysis, and a prioritized action plan (P0-P3).
-
-#### `/dw-security-check`
-Rigid multi-layer security check for **TypeScript, Python, C#, and Rust** projects. Combines OWASP static review (language-aware, via the bundled `security-review` skill), Trivy SCA/secret/IaC scanning (`trivy fs` + `trivy config`), and native lockfile audit (`npm audit` / `pip-audit` / `dotnet list package --vulnerable` / `cargo audit`). Consults Context7 MCP for framework-version-specific best practices (Next.js, Django, ASP.NET Core, Actix/Axum/Rocket, etc.). Hard gates: any CRITICAL or HIGH finding produces REJECTED status, blocking `/dw-code-review`, `/dw-review-implementation`, and `/dw-generate-pr`. No bypass flag. Requires Trivy (install via `install-deps`).
-
-#### `/dw-deps-audit`
-Supply-chain remediation orchestrator for **TypeScript, Python, C#, and Rust** projects. Runs three detection signals — `npm/pnpm/pip-audit/dotnet/cargo audit` for known CVEs, the `outdated` companions for stale versions, and an OSV.dev + GitHub Advisories cross-check (with a hardcoded fallback list of historical malicious-package incidents like `event-stream`, `ua-parser-js`, `node-ipc`) for supply-chain attacks. Classifies findings into COMPROMISED / CRITICAL / HIGH / OUTDATED-MAJOR / OUTDATED-MINOR tiers, maps each affected package to the files that import it and the tests that cover those files, then drafts a per-package update plan with three options (Conservative / Balanced / Bold) and trade-offs. Modes: `--scan-only` (CI), `--plan` (default — no file writes), `--execute` (applies updates with scoped tests, one `/dw-fix-qa` retry, atomic commits, and `/dw-run-qa` as final gate; reverts and marks BLOCKED if recovery fails). Complementary to `/dw-security-check`: that one is the single-shot gate, this one is the planner-and-remediator.
-
-### Git & PR
-
-#### `/dw-commit`
-Analyzes pending changes, groups them by feature or logical context, and creates atomic semantic commits following the Conventional Commits format. Uses allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`, `build`.
-
-#### `/dw-generate-pr`
-Pushes the branch to remote and creates a Pull Request on GitHub with a structured description. Collects information from the PRD and modified files, runs tests, then generates a PR body with summary, changes grouped by module, test plan, and deploy notes. **Hard gate**: requires a fresh `dw-verify` PASS in the current session before the push.
-
-#### `/dw-revert-task`
-Safely reverts the commits of a specific task created by `/dw-run-task`, with dependency-aware checks (blocks if subsequent tasks already executed depend on it) and explicit user confirmation. Updates `tasks.md` to re-mark the task as pending.
-
-### Project Bootstrap
-
-#### `/dw-new-project`
-Bootstraps a new project from an empty directory. Runs a wide stack interview (frontend/backend/fullstack, language, framework, db, cache, queue, email, storage, search, auth, observability, reverse proxy, scheduler, CI, linter), then wraps the right official `create-*` tools (`pnpm create next-app`, `pnpm create vite`, `pnpm dlx create-t3-app`, `dotnet new webapi`, `cargo new`, etc.) to scaffold the apps. Composes a `docker-compose.dev.yml` from the bundled `docker-compose-recipes` skill (postgres, redis, mailhog by default for email-in-dev, minio, meilisearch, jaeger, traefik, etc.), seeds `.env.example`, root scripts (`dev:up`/`down`/`logs`/`reset`), `.gitignore`/`.dockerignore`, GitHub Action, README with port table, and a minimal `.dw/rules/index.md`. Hard gate: presents a one-pager + plan and waits for explicit approval before touching disk.
-
-### Containerization
-
-#### `/dw-dockerize`
-Reads an existing project, detects language / framework / package manager / runtime infra deps (postgres, redis, queue, email, storage, search, OTel) by parsing manifests and import statements, then proposes Docker artifacts. Modes: `--dev` (default if no Dockerfile exists) generates `docker-compose.dev.yml` + `Dockerfile.dev` from the bundled `docker-compose-recipes` skill; `--prod` generates a multi-stage `Dockerfile` (Conservative slim / Balanced alpine / Bold distroless — brainstormed with trade-offs) + optional `docker-compose.prod.yml` with non-root user, healthcheck, no secrets baked in; `--both` ships both; `--audit` (default if Docker artifacts already exist) reports findings against `security-review/infrastructure/docker.md` without overwriting. Hard gate: presents the file tree and waits for approval before any write. Sister command to `/dw-new-project` — they share the `docker-compose-recipes` bundled skill.
-
-### Architectural Decisions
-
-#### `/dw-adr`
-Records an Architecture Decision Record (ADR) for a non-trivial decision during PRD execution. Creates `.dw/spec/<prd>/adrs/adr-NNN.md` with Context / Decision / Alternatives / Consequences, and updates cross-references in the PRD/TechSpec/Task. Inspired by the ADR pattern from [Compozy](https://github.com/compozy/compozy).
-
-### Intelligence
-
-#### `/dw-intel`
-Queries codebase intelligence to answer questions about patterns, conventions, and architecture. Reads `.dw/intel/` (built by `/dw-map-codebase`) as primary source, falls back to `.dw/rules/` and direct grep when absent. Surfaces stale-index warnings (>7 days). Always cites sources with file paths and line numbers.
-
-#### `/dw-analyze-project`
-Scans the repository to identify tech stack, architectural patterns, naming conventions, and anti-patterns. Generates structured documentation in `.dw/rules/` with a project overview (`index.md`) and per-module rule files containing real code examples. Also invokes `/dw-map-codebase` to build the queryable index in `.dw/intel/` (the two are complementary — rules are human-readable, intel is machine-queryable).
-
-#### `/dw-deep-research`
-Conducts multi-source research with citation tracking and verification across quick, standard, deep, and ultradeep modes. Executes parallel information gathering, triangulation, and cross-reference verification through 8+ phases, producing a professional report with complete bibliography.
-
-#### `/dw-functional-doc`
-Generates a functional documentation dossier with screen mapping, E2E flows, and Playwright validation. Maps routes, components, and user journeys into structured documentation with evidence.
-
-#### `/dw-help`
-Displays the complete guide of available commands, integration flows, and when to use each one. Can be invoked without arguments for the full guide or with a specific command name for a detailed section.
-
-#### `/dw-find-skills`
-Discovers skills from the open agent skills ecosystem (`npx skills` / [skills.sh](https://skills.sh/)) when no `dw-*` already covers the request. Checks the leaderboard first, then runs `npx skills find <query>` if needed, vets each candidate (install count, source reputation, GitHub stars), and presents 1–3 options with the install commands. Asks whether to install globally (`-g`, lands in `~/.agents/skills/`) or locally (this repo) before running `npx skills add`. Falls back to `/dw-brainstorm` or `/dw-run-task` when no skill matches. Ports the `find-skills` Claude superpowers skill into a `dw-*` command so every supported platform gets the same discovery on-ramp.
+| Command | What | Invoked by |
+|---------|------|------------|
+| **`/dw-adr "decision"`** | Records an Architecture Decision Record at `.dw/spec/<prd>/adrs/`. | `/dw-plan techspec --council`; deviations from constitution |
+| **`/dw-intel "question"`** | Query codebase intelligence (`.dw/intel/`). `--build` (re)creates the index. | `/dw-plan`, `/dw-review`, `/dw-bugfix` |
+| **`/dw-secure-audit`** | Unified security: OWASP + Trivy SCA/secret/IaC + lockfile + supply-chain check. Hard gate. Flags: `--scan-only`, `--plan`, `--execute`. | `/dw-review`, `/dw-generate-pr` (for TS/Python/C#/Rust) |
+| **`/dw-find-skills "query"`** | Searches `npx skills` ecosystem, vets, installs. | manual when extending the bundle |
+| **`/dw-update`** | Updates dev-workflow to latest npm release with rollback snapshot. | manual maintenance |
 
 ## Workflow
 
 ```
 /dw-autopilot "wish"  ------>  Runs entire pipeline automatically
-                                (gates: PRD approval, Tasks approval, PR confirmation)
-    --- OR ---
-
-/dw-brainstorm  ------>  /dw-create-prd  -->  .dw/spec/prd-{name}/prd.md
-                            |
-                        /dw-create-techspec  -->  .dw/spec/prd-{name}/techspec.md
-                            |
-                        /dw-create-tasks  -->  .dw/spec/prd-{name}/tasks.md + {N}_task.md
-                            |
-                        /dw-run-task (one at a time)
-                            |       or
-                        /dw-run-plan (all tasks — wave-based parallel native)
-                            |
-                        /dw-run-qa  -->  .dw/spec/prd-{name}/QA/
-                            |
-                        /dw-fix-qa (if bugs found)
-                            |
-                        /dw-review-implementation  -->  PRD compliance check
-                            |
-                        /dw-code-review  -->  .dw/spec/prd-{name}/QA/dw-code-review.md
-                            |
-                        /dw-commit + /dw-generate-pr
+                                (3 gates: PRD approval, Tasks approval, PR confirmation)
+    --- OR step-by-step ---
+
+/dw-brainstorm  -->  /dw-plan           -->  .dw/spec/prd-{name}/{prd,techspec,tasks}.md
+                          |
+                    /dw-run              -->  atomic commits per task, dependency-aware
+                          |
+                    /dw-qa               -->  .dw/spec/prd-{name}/QA/ (UI / API / --ai)
+                          |
+                    /dw-review           -->  L2 PRD coverage + L3 code quality
+                          |
+                    /dw-commit + /dw-generate-pr
 
 Shortcuts:
   /dw-intel "question"         Query codebase intelligence
@@ -227,7 +163,7 @@ All wrappers point to `.dw/commands/` as the single source of truth.
 ```
 your-project/
 ├── .dw/
-│   ├── commands/          # 30 workflow command files
+│   ├── commands/          # 20 workflow command files (v1.0.0)
 │   ├── templates/         # Document templates (PRD, TechSpec, etc.)
 │   │   └── overrides/     # Project-local template customizations (override > core)
 │   ├── rules/             # Project-specific rules (run /dw-analyze-project)
@@ -326,16 +262,58 @@ Incident response (`dw-incident-response`) adapted from [`wilsto/claude-code-sta
 
 LLM evaluation (`dw-llm-eval`) trajectory-match modes (strict / unordered / subset / superset) and tool-argument matching strategies adapted from [`langchain-ai/agentevals`](https://github.com/langchain-ai/agentevals) (MIT). The broader oracle-ladder framing, judge-calibration discipline, and reference-dataset principle are distilled from the open evaluations literature (OpenAI evals cookbook, Anthropic evals guidance, the academic eval-of-LLM body of work) and rewritten in our voice.
 
-## Migration from v0.12.x
+## Migration from v0.x (1.0.0 is a consolidation release)
+
+v1.0.0 consolidates 30 commands → 20. **The `dev-workflow update` command auto-removes obsolete wrappers** via the migrator that landed in v0.13.0; no manual action required.
+
+### Command renames (15 → 7 merged)
+
+| Old (v0.x) | New (v1.0.0) |
+|-----------|--------------|
+| `/dw-create-prd` | `/dw-plan prd` |
+| `/dw-create-techspec` | `/dw-plan techspec` |
+| `/dw-create-tasks` | `/dw-plan tasks` |
+| `/dw-run-task <id>` | `/dw-run <id>` |
+| `/dw-run-plan` | `/dw-run` |
+| `/dw-code-review` | `/dw-review --code-only` |
+| `/dw-review-implementation` | `/dw-review --coverage-only` |
+| `/dw-run-qa` | `/dw-qa` |
+| `/dw-fix-qa` | `/dw-qa --fix` |
+| `/dw-security-check` | `/dw-secure-audit` |
+| `/dw-deps-audit` | `/dw-secure-audit --plan` |
+| `/dw-map-codebase` | `/dw-intel --build` |
+| `/dw-deep-research` | `/dw-brainstorm --research` |
+| `/dw-refactoring-analysis` | `/dw-brainstorm --refactor` |
+
+### Removed (1)
+
+- `/dw-revert-task` → use `git revert <sha>` directly. No replacement.
+
+### Bundled skill swaps (already shipped in v0.13.0; carries over)
+
+- `ui-ux-pro-max` → `dw-ui-discipline`
+- `webapp-testing` → `dw-testing-discipline`
+
+### What the migrator does for you
+
+On the next `npx @brunosps00/dev-workflow update`, the following happens automatically:
+
+1. The 15 renamed commands' wrappers are detected as orphans (their names no longer exist in `lib/constants.js`) and removed from `.claude/skills/`, `.agents/skills/`, and `.opencode/commands/`.
+2. The migrator prints each removal with the friendly "old → new" mapping (e.g., `[orphan] Removing wrapper .agents/skills/dw-create-prd (replaced in v1.0.0 by 'dw-plan prd')`).
+3. The 20 new wrappers are installed for the consolidated commands.
+4. The 17 bundled skills are refreshed.
+
+### Backwards compatibility
+
+**There is none** — v1.0.0 is a clean cut per design. There are no aliases. Calling `/dw-create-prd` will not work; use `/dw-plan prd`. Update your team's runbooks and AI-agent instructions (CLAUDE.md / AGENTS.md) accordingly; the auto-trigger map in `agent-instructions.md` is already updated.
 
-The `dev-workflow update` command automatically removes the two replaced skills and installs the new ones — no manual action required:
+### CLAUDE.md / AGENTS.md updates
 
-- `ui-ux-pro-max` → replaced by `dw-ui-discipline` (auto-removed on update)
-- `webapp-testing` → replaced by `dw-testing-discipline` (auto-removed on update)
+The Trigger Map block (between `<!-- dev-workflow:start -->` and `<!-- dev-workflow:end -->`) refreshes automatically on update with the v1.0.0 command surface. Your edits outside the markers are preserved.
 
-The cleanup also detects and removes any **orphan `dw-*` wrappers** in `.claude/skills/`, `.agents/skills/`, and `.opencode/commands/` whose names no longer exist in the current scaffold (e.g., commands removed in v0.10 like `dw-execute-phase`, `dw-quick` that may still have wrappers from older installs).
+### Skill conventions
 
-If you had **custom edits** inside `.agents/skills/ui-ux-pro-max/` or `.agents/skills/webapp-testing/`, back them up before running update — the migrator removes the entire directory. If you customized templates instead, those live in `.dw/templates/overrides/` (introduced in v0.11) and are preserved.
+Skill description format ("pushy" trigger phrases ≤200 chars, "Use when X. Triggers on Y." pattern) and structural conventions (`SKILL.md` + `references/` / `scripts/` / `assets/` / `agents/` subdirectories, explicit `allowed-tools` in frontmatter) follow the official guidance from [`anthropics/skills/skill-creator`](https://github.com/anthropics/skills/tree/main/skills/skill-creator) (Apache 2.0). dev-workflow's 20 bundled skills are not derived from skill-creator's content — only its conventions are followed for auto-trigger reliability across Claude Code, Codex CLI, Copilot, and OpenCode.
 
 ## License
 

package/lib/constants.js

@@ -3,64 +3,44 @@ const COMMANDS = {
     { name: 'dw-adr', description: 'Records an architectural decision and the trade-offs accepted, before they get lost.' },
     { name: 'dw-analyze-project', description: 'Scans the repo to learn its stack and conventions, then writes the rules other commands rely on.' },
     { name: 'dw-autopilot', description: 'Trigger when user asks to implement, build, create, or add a feature non-trivially. Runs full PRD-to-PR pipeline with three gates.' },
-    { name: 'dw-brainstorm', description: 'Refines an idea using the product\'s existing features as ground truth, before any PRD.' },
+    { name: 'dw-brainstorm', description: 'Refine an idea against the product\'s existing features. Modes: default ideation, --research (multi-source cited research), --refactor (Fowler code-smell catalog), --onepager, --council.' },
     { name: 'dw-bugfix', description: 'Trigger when user reports a bug, pastes an error, or describes broken behavior. Triages with three questions, then fixes or routes to PRD.' },
-    { name: 'dw-code-review', description: 'Trigger when user asks to review code, check quality, or verify PR readiness. Level-3 review with APPROVED/REJECTED verdict.' },
     { name: 'dw-commit', description: 'Trigger when implementation is complete and pending changes need to be committed. Atomic commits with Conventional Commits messages.' },
-    { name: 'dw-create-prd', description: 'Trigger when user has a feature idea and needs a written spec before implementation. Asks the questions a techspec would otherwise inherit.' },
-    { name: 'dw-create-tasks', description: 'Trigger after PRD + techspec exist and the team is ready to break work into shippable units. Includes a 5-dimension consistency check.' },
-    { name: 'dw-create-techspec', description: 'Trigger when a PRD is approved and architecture must be defined before tasks. Adds framework choices, test strategy, and constitution alignment.' },
-    { name: 'dw-deep-research', description: 'Researches a topic across sources, tracks citations, and flags claims that don\'t check out.' },
-    { name: 'dw-deps-audit', description: 'Finds outdated and supply-chain-compromised packages, drafts a per-package update plan, and runs scoped QA after each upgrade.' },
     { name: 'dw-dockerize', description: 'Reads a project, detects the stack and runtime deps, then proposes Dockerfile and docker-compose for dev and prod with explicit trade-offs.' },
     { name: 'dw-find-skills', description: 'Searches the npx skills ecosystem for a skill matching what you need, vets it, and installs it where you choose.' },
-    { name: 'dw-fix-qa', description: 'Fixes bugs found in QA and retests them with screenshot evidence until they stay fixed.' },
     { name: 'dw-functional-doc', description: 'Maps screens and user flows into a functional doc, validated end-to-end with Playwright.' },
     { name: 'dw-generate-pr', description: 'Trigger when commits are ready and the branch needs a PR. Pushes branch and opens PR with summary + test plan + hard verify gate.' },
-    { name: 'dw-help', description: 'Lists every command and the flows that connect them. Pass a keyword for a contextual shortcut.' },
-    { name: 'dw-intel', description: 'Answers questions about the codebase by querying .dw/intel/ (built by /dw-map-codebase) with .dw/rules/ and grep as fallbacks.' },
-    { name: 'dw-map-codebase', description: 'Builds a queryable index in .dw/intel/ (stack, files, apis, deps, arch) so other commands stop re-exploring the codebase.' },
+    { name: 'dw-help', description: 'Lists primary commands and the flows that connect them. Pass --advanced to see internal/hidden commands.' },
+    { name: 'dw-intel', description: 'Codebase intelligence: query mode (default) answers questions citing .dw/intel/ + .dw/rules/; --build mode (re)builds the index.' },
     { name: 'dw-new-project', description: 'Interviews you about stack and infra, then scaffolds a working monorepo with docker-compose for dev, .env, scripts, CI, and seeded rules.' },
+    { name: 'dw-plan', description: 'Trigger when user has a feature idea and needs spec + architecture + tasks. Runs PRD → TechSpec → Tasks sequentially. Stages: prd / techspec / tasks; --from techspec; --council.' },
+    { name: 'dw-qa', description: 'Trigger when user wants to validate behavior beyond unit tests. Mode-aware (UI / API / --ai). --fix enters the iterative QA + fix-retest loop.' },
     { name: 'dw-redesign-ui', description: 'Audits a frontend page, proposes design directions you choose from, then ships the redesign.' },
-    { name: 'dw-refactoring-analysis', description: 'Catalogs code smells in Fowler\'s vocabulary and ranks them by impact, P0 to P3.' },
-    { name: 'dw-review-implementation', description: 'Maps every PRD requirement to the code that delivers it, then runs /dw-code-review for the Level 3 quality layer.' },
-    { name: 'dw-revert-task', description: 'Reverts the commits of one task, but only after checking nothing downstream depends on it.' },
-    { name: 'dw-run-plan', description: 'Trigger when user wants to execute all pending tasks. Goal-backward plan check, then wave-based parallel execution with atomic commits.' },
-    { name: 'dw-run-qa', description: 'Drives the browser to test happy paths, edge cases, and accessibility, with screenshot proof.' },
-    { name: 'dw-run-task', description: 'Trigger when user wants to execute one specific task by ID. Implements, validates with mandatory tests, commits when passing.' },
-    { name: 'dw-security-check', description: 'OWASP review plus Trivy CVE/secret/IaC scan for TS, Python, C#, or Rust. CRITICAL or HIGH blocks the PR.' },
+    { name: 'dw-review', description: 'Trigger when user asks to review code, check quality, or verify PR readiness. Default runs L2 (PRD coverage) + L3 (code quality). Flags --coverage-only / --code-only.' },
+    { name: 'dw-run', description: 'Trigger when user wants to execute tasks. Default runs all pending in dependency order; \'run <task-id>\' runs one; \'run --resume\' continues an interrupted plan.' },
+    { name: 'dw-secure-audit', description: 'Unified security audit: OWASP + Trivy SCA/secret/IaC + lockfile + supply-chain compromise check. Hidden; auto-invoked by /dw-review and /dw-generate-pr.' },
     { name: 'dw-update', description: 'Updates dev-workflow to the latest npm release in-place, with a snapshot you can roll back to.' },
   ],
   'pt-br': [
     { name: 'dw-adr', description: 'Registra uma decisao arquitetural e os trade-offs aceitos, antes que se percam.' },
     { name: 'dw-analyze-project', description: 'Escaneia o repo para aprender stack e convencoes, e escreve as regras que os outros commands usam.' },
     { name: 'dw-autopilot', description: 'Trigger quando usuario pede pra implementar, criar ou adicionar uma feature nao-trivial. Roda pipeline completo PRD-ao-PR com tres gates.' },
-    { name: 'dw-brainstorm', description: 'Refina uma ideia usando as features existentes do produto como base, antes de qualquer PRD.' },
+    { name: 'dw-brainstorm', description: 'Refina uma ideia contra features existentes do produto. Modos: ideacao default, --research (research multi-fonte citada), --refactor (catalogo de code smells Fowler), --onepager, --council.' },
     { name: 'dw-bugfix', description: 'Trigger quando usuario reporta bug, cola erro ou descreve comportamento quebrado. Tria com tres perguntas, depois corrige ou roteia pra PRD.' },
-    { name: 'dw-code-review', description: 'Trigger quando usuario pede pra revisar codigo, checar qualidade ou validar prontidao pra PR. Review Nivel 3 com veredicto APROVADO/REPROVADO.' },
     { name: 'dw-commit', description: 'Trigger quando implementacao esta completa e ha mudancas pendentes pra commit. Commits atomicos com mensagens Conventional Commits.' },
-    { name: 'dw-create-prd', description: 'Trigger quando usuario tem ideia de feature e precisa de spec escrito antes de implementar. Faz as perguntas que o techspec herdaria.' },
-    { name: 'dw-create-tasks', description: 'Trigger depois que PRD + techspec existem e o time vai quebrar em unidades entregaveis. Inclui consistency check em 5 dimensoes.' },
-    { name: 'dw-create-techspec', description: 'Trigger quando PRD esta aprovado e arquitetura precisa ser definida antes das tasks. Adiciona escolhas de framework, testes e alinhamento de constitution.' },
-    { name: 'dw-deep-research', description: 'Pesquisa um topico em varias fontes, rastreia citacoes e marca o que nao confere.' },
-    { name: 'dw-deps-audit', description: 'Encontra pacotes desatualizados e comprometidos por supply-chain, monta plano de update por pacote e roda QA do que foi afetado.' },
     { name: 'dw-dockerize', description: 'Le um projeto, detecta stack e deps de runtime, e propoe Dockerfile e docker-compose para dev e prod com trade-offs explicitos.' },
     { name: 'dw-find-skills', description: 'Busca no ecossistema npx skills uma skill que resolva o que voce precisa, valida e instala onde voce escolher.' },
-    { name: 'dw-fix-qa', description: 'Corrige bugs do QA e retesta com evidencia em screenshot ate ficarem estaveis.' },
     { name: 'dw-functional-doc', description: 'Mapeia telas e fluxos em um dossie funcional, validado E2E com Playwright.' },
     { name: 'dw-generate-pr', description: 'Trigger quando commits estao prontos e branch precisa de PR. Push da branch e abre PR com summary + test plan + hard verify gate.' },
-    { name: 'dw-help', description: 'Lista todos os commands e os fluxos que os conectam. Passe uma keyword para atalho contextual.' },
-    { name: 'dw-intel', description: 'Responde perguntas sobre o codebase consultando .dw/intel/ (do /dw-map-codebase) com .dw/rules/ e grep como fallback.' },
-    { name: 'dw-map-codebase', description: 'Constroi um indice queryable em .dw/intel/ (stack, files, apis, deps, arch) para outros comandos pararem de re-explorar o codebase.' },
+    { name: 'dw-help', description: 'Lista comandos primarios e fluxos que os conectam. Passe --advanced para ver comandos internos/escondidos.' },
+    { name: 'dw-intel', description: 'Inteligencia do codebase: modo query (default) responde citando .dw/intel/ + .dw/rules/; modo --build (re)constroi indice.' },
     { name: 'dw-new-project', description: 'Entrevista voce sobre stack e infra, depois faz scaffold de um monorepo com docker-compose para dev, .env, scripts, CI e rules seed.' },
+    { name: 'dw-plan', description: 'Trigger quando usuario tem ideia de feature e precisa spec + arquitetura + tasks. Roda PRD → TechSpec → Tasks sequencial. Stages: prd / techspec / tasks; --from techspec; --council.' },
+    { name: 'dw-qa', description: 'Trigger quando usuario quer validar comportamento alem de unit tests. Mode-aware (UI / API / --ai). --fix entra no loop iterativo QA + fix-retest.' },
     { name: 'dw-redesign-ui', description: 'Audita uma pagina frontend, propoe direcoes de design que voce escolhe, e entrega o redesign.' },
-    { name: 'dw-refactoring-analysis', description: 'Cataloga code smells no vocabulario de Fowler e ranqueia por impacto, P0 a P3.' },
-    { name: 'dw-review-implementation', description: 'Mapeia cada requisito do PRD ao codigo que o entrega, e roda /dw-code-review para a camada de qualidade Nivel 3.' },
-    { name: 'dw-revert-task', description: 'Reverte os commits de uma task, mas so depois de checar que nada a frente depende dela.' },
-    { name: 'dw-run-plan', description: 'Trigger quando usuario quer executar todas as tasks pendentes. Plan check goal-backward, depois execucao paralela em ondas com commits atomicos.' },
-    { name: 'dw-run-qa', description: 'Pilota o browser para testar fluxo feliz, edge cases e acessibilidade, com screenshot.' },
-    { name: 'dw-run-task', description: 'Trigger quando usuario quer executar uma task especifica por ID. Implementa, valida com testes obrigatorios, commita quando passa.' },
-    { name: 'dw-security-check', description: 'Review OWASP + scan Trivy CVE/secret/IaC para TS, Python, C# ou Rust. CRITICAL ou HIGH bloqueia PR.' },
+    { name: 'dw-review', description: 'Trigger quando usuario pede pra revisar codigo, checar qualidade ou validar prontidao pra PR. Default roda L2 (cobertura PRD) + L3 (qualidade). Flags --coverage-only / --code-only.' },
+    { name: 'dw-run', description: 'Trigger quando usuario quer executar tasks. Default roda todas pendentes em ordem de dependencia; \'run <task-id>\' roda uma; \'run --resume\' continua plan interrompido.' },
+    { name: 'dw-secure-audit', description: 'Audit unificado de seguranca: OWASP + Trivy SCA/secret/IaC + lockfile + supply-chain compromise. Hidden; auto-invocado por /dw-review e /dw-generate-pr.' },
     { name: 'dw-update', description: 'Atualiza o dev-workflow para o release mais recente no npm, com snapshot para rollback.' },
   ],
 };

package/lib/migrate-skills.js

@@ -2,6 +2,7 @@ const fs = require('fs');
 const path = require('path');
 const { COMMANDS } = require('./constants');
 const removedSkills = require('./removed-bundled-skills');
+const removedCommands = require('./removed-commands');
 
 /**
  * Cleanup-on-update for dev-workflow.
@@ -41,11 +42,17 @@ function migrate(projectRoot) {
     rmRecursive(entry.path);
   }
 
+  // Pre-build a map { commandName -> { removedIn, replacedBy } } for friendly messaging.
+  const removedCommandMap = new Map(removedCommands.map((r) => [r.name, r]));
+
   for (const entry of orphans) {
     const rel = path.relative(projectRoot, entry.path);
-    console.log(
-      `    \x1b[33m-\x1b[0m [orphan] Removing wrapper ${rel} — command no longer exists`
-    );
+    const baseName = entry.commandName;
+    const known = baseName ? removedCommandMap.get(baseName) : null;
+    const suffix = known
+      ? `(replaced in v${known.removedIn} by \`${known.replacedBy}\`)`
+      : `(command no longer exists)`;
+    console.log(`    \x1b[33m-\x1b[0m [orphan] Removing wrapper ${rel} ${suffix}`);
     rmRecursive(entry.path);
   }
 
@@ -114,7 +121,7 @@ function scanOrphanCommandWrappers(projectRoot) {
       const isExpected = loc.type === 'directory' ? entry.isDirectory() : entry.isFile();
       if (!isExpected) continue;
 
-      orphans.push({ path: path.join(loc.dir, entry.name) });
+      orphans.push({ path: path.join(loc.dir, entry.name), commandName: name });
     }
   }
 

package/lib/removed-commands.js

@@ -0,0 +1,30 @@
+/**
+ * Manifest of dw-* commands removed in past releases.
+ *
+ * APPEND-ONLY: never modify or remove entries. A removed command stays
+ * in this manifest forever so old installs still get cleaned up when
+ * the user runs `dev-workflow update`.
+ *
+ * Each entry surfaces a friendly "old → new" message during migrate-skills
+ * orphan-wrapper sweep. The mapping is informational — the actual cleanup
+ * is the generic orphan-wrapper scan that already matches dw-* names
+ * against the current `lib/constants.js`.
+ */
+module.exports = [
+  // v1.0.0 — pipeline consolidation
+  { name: 'dw-create-prd', removedIn: '1.0.0', replacedBy: 'dw-plan prd' },
+  { name: 'dw-create-techspec', removedIn: '1.0.0', replacedBy: 'dw-plan techspec' },
+  { name: 'dw-create-tasks', removedIn: '1.0.0', replacedBy: 'dw-plan tasks' },
+  { name: 'dw-run-task', removedIn: '1.0.0', replacedBy: 'dw-run <task-id>' },
+  { name: 'dw-run-plan', removedIn: '1.0.0', replacedBy: 'dw-run' },
+  { name: 'dw-code-review', removedIn: '1.0.0', replacedBy: 'dw-review --code-only' },
+  { name: 'dw-review-implementation', removedIn: '1.0.0', replacedBy: 'dw-review --coverage-only' },
+  { name: 'dw-run-qa', removedIn: '1.0.0', replacedBy: 'dw-qa' },
+  { name: 'dw-fix-qa', removedIn: '1.0.0', replacedBy: 'dw-qa --fix' },
+  { name: 'dw-security-check', removedIn: '1.0.0', replacedBy: 'dw-secure-audit' },
+  { name: 'dw-deps-audit', removedIn: '1.0.0', replacedBy: 'dw-secure-audit --plan' },
+  { name: 'dw-map-codebase', removedIn: '1.0.0', replacedBy: 'dw-intel --build' },
+  { name: 'dw-deep-research', removedIn: '1.0.0', replacedBy: 'dw-brainstorm --research' },
+  { name: 'dw-refactoring-analysis', removedIn: '1.0.0', replacedBy: 'dw-brainstorm --refactor' },
+  { name: 'dw-revert-task', removedIn: '1.0.0', replacedBy: 'git revert <sha>' },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "0.15.0",
+  "version": "1.0.0",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"

package/scaffold/en/agent-instructions.md

@@ -11,28 +11,42 @@ This project uses [`@brunosps00/dev-workflow`](https://www.npmjs.com/package/@br
 |--------------------------------------|--------------|
 | "Implement X" / "Build Y" / "Add feature Z" / "I need ..." / "Create ..." | `/dw-autopilot "X"` |
 | Pasted error / "X is broken" / "Bug in Y" / failing test screenshot | `/dw-bugfix "X"` |
-| "Run this task" (with task ID) | `/dw-run-task <ID>` |
-| "Run all pending tasks" / "Execute the plan" | `/dw-run-plan` |
-| "Review my PR" / "Check code quality" / "Is this ready to ship?" | `/dw-code-review` |
+| "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` |
+| "Continue where I left off" | `/dw-run --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` |
+| "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` |
-| "Write a PRD for X" / "Spec out Y" | `/dw-create-prd` |
-| "Design the architecture" / "Make the techspec" | `/dw-create-techspec` |
-| "Break this into tasks" | `/dw-create-tasks` |
+| "Brainstorm X" / "Explore ideas" | `/dw-brainstorm "X"` |
+| "Research X" / "Compare A vs B with citations" | `/dw-brainstorm --research "X"` |
+| "Code-health audit" / "Find tech debt" / "Refactoring opportunities" | `/dw-brainstorm --refactor` |
 | "Where is X?" / "What uses Y?" / "How is Z structured?" | `/dw-intel "<question>"` |
-| "Audit our dependencies" / "Are we behind on packages?" | `/dw-deps-audit` |
-| "Scan for vulnerabilities" / "Security check" | `/dw-security-check` |
-| "QA this feature" / "Run the test plan" | `/dw-run-qa` |
-| "Fix the QA bugs" | `/dw-fix-qa` |
+| "Rebuild the codebase index" / "Refresh intel" | `/dw-intel --build` |
+| "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` |
 
 **Priority:** when in doubt between two commands, `/dw-autopilot` is the safest default for any non-trivial feature request — it composes the rest.
 
 ## Hard Gates (the commands enforce these — don't bypass)
 
 - **`.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-create-tasks`. Any FAIL dimension blocks user approval until resolved or explicitly overridden.
+- **`.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-security-check` (Trivy + OWASP + lockfile audit) before the PR opens.
+- **Security**: TS / Python / C# / Rust projects must pass `/dw-secure-audit` (Trivy + OWASP + lockfile audit) before the PR opens.
 
 ## Escape Hatches — do NOT auto-trigger
 
@@ -52,10 +66,7 @@ When any of these apply, answer directly and do **not** invoke a `dw-*` command:
 
   --- OR step-by-step ---
 
-/dw-brainstorm ─► /dw-create-prd ─► /dw-create-techspec ─► /dw-create-tasks
-                                                              │
-                                                              ▼
-/dw-commit + /dw-generate-pr ◄──── /dw-code-review ◄──── /dw-run-plan
+/dw-brainstorm ─► /dw-plan ─► /dw-run ─► /dw-qa ─► /dw-review ─► /dw-commit ─► /dw-generate-pr
 ```
 
 Full command list and contextual help: `/dw-help`.

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

@@ -3,12 +3,12 @@ You are an architectural-decision recorder. Your job is to create an **Architect
 
 ## When to Use
 - Use when an architectural or design decision has been made and needs to be recorded for future reference (library choice, communication pattern, performance tradeoff, compliance-imposed constraint, etc.)
-- Use during `/dw-create-techspec` or `/dw-run-task` when the rationale for the decision does not fit in the techspec or the task file
+- Use during `/dw-plan techspec` or `/dw-run` when the rationale for the decision does not fit in the techspec or the task file
 - Do NOT use for trivial or cheaply-reversible decisions (variable names, import order)
 - Do NOT use to record bugs or incidents (use `/dw-bugfix` or operational notes)
 
 ## Pipeline Position
-**Predecessor:** any point in the pipeline after `/dw-create-prd` | **Successor:** continue the previous flow (techspec, task, review)
+**Predecessor:** any point in the pipeline after `/dw-plan prd` | **Successor:** continue the previous flow (techspec, task, review)
 
 The ADR is **additive**: it does not replace any pipeline stage. Any existing command can invoke `/dw-adr` when a non-trivial decision needs a permanent record.
 

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

@@ -24,10 +24,10 @@ You are a project analysis specialist. Your task is to scan the current reposito
 
 ## Output Consumers
 The rules generated by this command are consumed by:
-- `/dw-run-task` -- reads rules for implementation patterns
-- `/dw-code-review` -- reads rules for conformance checks
-- `/dw-refactoring-analysis` -- reads rules for project context
-- `/dw-create-techspec` -- reads rules for architecture decisions
+- `/dw-run` -- reads rules for implementation patterns
+- `/dw-review --code-only` -- reads rules for conformance checks
+- `/dw-brainstorm --refactor` -- reads rules for project context
+- `/dw-plan techspec` -- reads rules for architecture decisions
 
 <critical>This command ONLY generates documentation. Do NOT modify any project source code.</critical>
 <critical>Read actual source files to verify patterns — do not guess from file names alone.</critical>
@@ -230,13 +230,13 @@ For each module/project detected, identify:
 When React is detected, run `npx react-doctor@latest --verbose` and include the health score in the generated rules as a baseline metric.
 For Angular projects, run `ng lint` and document any warnings as baseline.
 
-<critical>Running /dw-map-codebase to generate the queryable index in .dw/intel/ is MANDATORY. The command CANNOT be considered complete without it.</critical>
+<critical>Running /dw-intel --build to generate the queryable index in .dw/intel/ is MANDATORY. The command CANNOT be considered complete without it.</critical>
 
 #### Codebase Intelligence (native)
 
-After generating rules in `.dw/rules/`, delegate to `/dw-map-codebase` to create the queryable index in `.dw/intel/`:
+After generating rules in `.dw/rules/`, delegate to `/dw-intel --build` to create the queryable index in `.dw/intel/`:
 - The index includes: stack (`stack.json`), file graph (`files.json`), API surface (`apis.json`), dependencies (`deps.json`), architecture overview (`arch.md`)
-- The index is incremental — `/dw-map-codebase --files <list>` updates only the touched entries; full scan only when needed
+- The index is incremental — `/dw-intel --build --files <list>` updates only the touched entries; full scan only when needed
 - Other dw-* commands query the index via `/dw-intel` (see the `dw-codebase-intel` bundled skill for schemas)
 
 ### Step 4: Detect Code Patterns and Conventions