@brunosps00/dev-workflow 0.15.0 → 1.0.0

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

@@ -1,391 +1,135 @@
 <system_instructions>
-You are a workspace help assistant. When invoked, present the user with a complete guide of available commands, their integration flows, and when to use each one.
+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.
 
 ## When to Use
-- Use when you need an overview of available commands, their integration flows, or guidance on which command to use next
-- Do NOT use when you already know which specific command to run
+- User types `/dw-help` to discover commands.
+- User types `/dw-help <keyword>` to find a contextual shortcut.
+- User types `/dw-help --advanced` to see internal/hidden commands.
 
-## Pipeline Position
-**Predecessor:** (any command or user question) | **Successor:** (any command)
+## Default mode — primary surface
 
-## Behavior
+Display the following (or its pt-br equivalent when invoked from pt-br):
 
-- If invoked without arguments (`/dw-help`): show the complete guide below
-- If invoked with an argument matching a command (`/dw-help dw-create-prd`): show only that command's detailed section
-- If invoked with a **keyword that is not a command name** (`/dw-help bug`, `/dw-help review`, `/dw-help design`): perform contextual lookup — identify the most relevant command(s) for the keyword and present each with 1-2 lines of justification ("for bugs, use `/dw-bugfix` because..."). Use the mapping table below.
+```markdown
+# dev-workflow — Primary Commands
 
-### Contextual mapping (keyword → suggested command)
+Use `/dw-autopilot "wish"` as the gateway for most feature work. The granular commands below give you control when you want it.
 
-| Keyword(s) | Suggested command | Why |
-|------------|-------------------|-----|
-| bug, error, failure, issue | `/dw-bugfix` | Auto-triage bug vs feature + fix |
-| review, quality | `/dw-code-review` | Formal Level-3 review with report |
-| qa, visual test, playwright | `/dw-run-qa` | E2E QA with browser automation |
-| refactor, smell, fowler | `/dw-refactoring-analysis` | Prioritized code-smell audit |
-| design, ui, redesign | `/dw-redesign-ui` | Audit + propose + implement visual |
-| debate, council, stress-test, opinions | `/dw-brainstorm --council` or `/dw-create-techspec --council` | Invokes `dw-council` for a multi-advisor debate |
-| security, vulnerability, owasp, trivy, cve | `/dw-security-check` | Rigid multi-layer check (OWASP static + Trivy SCA/IaC + native audit) for TS/Python/C#/Rust |
-| supply chain, outdated, compromised, malicious package, deps update, package upgrade, npm audit, pip-audit | `/dw-deps-audit` | Detect + classify + per-package update plan with scoped QA. Goes beyond `/dw-security-check` by adding remediation. |
-| skill, find skill, install skill, ecosystem, capability, extend agent | `/dw-find-skills` | Discover skills from skills.sh / `npx skills` and install them globally or locally |
-| new project, scaffold, bootstrap, start, kickoff, init project, fullstack, monorepo | `/dw-new-project` | Stack interview + create-* tools + docker-compose for dev. Runs after `npx dev-workflow init`. |
-| dockerize, docker, dockerfile, compose, container, prod image, multi-stage | `/dw-dockerize` | Reads existing project, brainstorms base image, generates Dockerfile + docker-compose for dev/prod/both, or audits existing artifacts. |
-| refine, refinement, idea, one-pager | `/dw-brainstorm --onepager` | Idea refinement with Product Inventory + classification (IMPROVES/CONSOLIDATES/NEW) + durable one-pager |
-| revert, rollback task | `/dw-revert-task` | Safe revert with dependency checks |
-| research | `/dw-deep-research` | Multi-source research with citations |
-| idea, brainstorm | `/dw-brainstorm` | Structured ideation with trade-offs |
-| update dev-workflow | `/dw-update` | Update to latest npm version |
+## Tier 1 — Gateway (3)
 
----
+| Command | When |
+|---------|------|
+| `/dw-autopilot "wish"` | Default entry point. PRD → TechSpec → Tasks → Run → QA → Review → Commit → PR. Three approval gates. |
+| `/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. |
 
-# Command Guide - AI Dev Workflow
+## Tier 2 — Pipeline granular (7)
 
-## Overview
+| Command | What |
+|---------|------|
+| `/dw-brainstorm "idea"` | Refine an idea before PRD. Flags: `--onepager`, `--council`, `--research`, `--refactor`. |
+| `/dw-plan "feature"` | PRD → TechSpec → Tasks sequentially with checkpoints. Stages: `prd`, `techspec`, `tasks`. |
+| `/dw-run [task-id]` | Execute all pending tasks or a single one. Flag `--resume`. |
+| `/dw-review` | Level 2 (PRD coverage) + Level 3 (code quality). Flags: `--coverage-only`, `--code-only`. |
+| `/dw-qa` | Mode-aware QA (UI / API auto-detect). Flags: `--fix`, `--api`, `--ai`. |
+| `/dw-commit` | Atomic Conventional Commits for pending work. |
+| `/dw-generate-pr [target]` | Push branch, draft PR body, open browser. |
 
-This workspace uses an AI command system that automates the full development cycle: from planning (PRD) to merge (PR). Commands are in `.dw/commands/` and are accessible in supported AI CLIs (e.g., Codex, Claude Code, OpenCode, GitHub Copilot), using the CLI prefix (`/command` or `$command`).
+## Tier 3 — Specialty (5)
 
-## Main Development Flow
+| 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-new-project` | Interview-driven bootstrap (stack + infra + docker-compose + CI). |
+| `/dw-dockerize` | Detect stack, propose Dockerfile + docker-compose for dev/prod. |
 
-```
-┌──────────────┐     ┌─────────────────┐     ┌───────────────┐
-│ /dw-create-prd  │────>│/dw-create-techspec │────>│ /dw-create-tasks │
-│ (WHAT)       │     │ (HOW)           │     │ (WHEN)        │
-└──────────────┘     └─────────────────┘     └───────┬───────┘
-                                                     │
-                                       ┌─────────────┴─────────────┐
-                                       ▼                           ▼
-                              ┌────────────────┐         ┌─────────────────┐
-                              │  /dw-run-task     │         │  /dw-run-plan      │
-                              │ (one at a time)│         │  (all auto)     │
-                              └───────┬────────┘         └────────┬────────┘
-                                      │                           │
-                              ┌───────┴───────┐                   │
-                              ▼               │                   │
-                    ┌──────────────────┐      │                   │
-                    │/dw-functional-doc│      │                   │
-                    │ (map screens &  │      │                   │
-                    │  flows)         │      │                   │
-                    └───────┬──────────┘      │                   │
-                            └───────┬─────────┘                   │
-                                      │                           │
-                                      └─────────┬─────────────────┘
-                                                │
-                                                ▼
-                                      ┌─────────────────┐
-                                      │ Validation Lv 1 │ (automatic, embedded)
-                                      │ criteria+tests  │
-                                      └────────┬────────┘
-                                               │
-                                ┌──────────────┼──────────────┐
-                                ▼              ▼              ▼
-                      ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐
-                      │  /dw-run-qa     │ │/review-impl. │ │  /dw-code-review       │
-                      │ (visual QA)  │ │(PRD compliance│ │ (formal code review)│
-                      └──────────────┘ │  Level 2)    │ │ (Level 3)           │
-                                       └──────────────┘ └─────────────────────┘
-                                                │
-                                ┌───────────────┴───────────────┐
-                                ▼                               ▼
-                      ┌──────────────┐                 ┌────────────────┐
-                      │  /dw-commit     │                 │ /dw-commit-all    │
-                      │ (one project)│                 │ (submodules)   │
-                      └──────┬───────┘                 └───────┬────────┘
-                             │                                 │
-                             └────────────┬────────────────────┘
-                                          ▼
-                                ┌──────────────────┐
-                                │  /dw-generate-pr    │
-                                │ (push + PR + URL)│
-                                └──────────────────┘
-                                          │
-                                          ▼
-                                ┌──────────────────┐
-                                │  /dw-archive-prd    │
-                                │  (post-merge)    │
-                                └──────────────────┘
-```
-
-## Command Table
-
-### Planning
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/dw-brainstorm` | Facilitates structured ideation before PRD or implementation | Problem, idea, or context | Options + trade-offs + recommendation |
-| `/dw-create-prd` | Creates PRD with min. 7 clarification questions | Feature description | `.dw/spec/prd-[name]/prd.md` |
-| `/dw-create-techspec` | Creates technical specification from the PRD | PRD path | `.dw/spec/prd-[name]/techspec.md` |
-| `/dw-create-tasks` | Breaks PRD+TechSpec into tasks (max 2 FRs/task) | PRD path | `.dw/spec/prd-[name]/tasks.md` + `*_task.md` |
-
-### Execution
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/dw-run-task` | Implements ONE task + Level 1 validation + commit | PRD path | Code + commit |
-| `/dw-run-plan` | Executes ALL tasks + final Level 2 review | PRD path | Code + commits + report |
-| `/dw-bugfix` | Analyzes and fixes bugs (bug vs feature triage) | Target + description | Fix + commit OR PRD (if feature) |
-| `/dw-fix-qa` | Fixes documented QA bugs and retests with evidence | PRD path | Code + `QA/bugs.md` + `QA/qa-report.md` updated |
-| `/dw-redesign-ui` | Audits, proposes, and implements visual redesign of pages/components | Target page/component | Redesign brief + code |
-| `/dw-autopilot` | Full pipeline orchestrator: from a wish to a PR with minimal intervention | Wish description | PRD + code + commits + PR |
-
-### Research
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/dw-analyze-project` | Analyzes project structure and generates documentation | Project path | Architecture overview |
-| `/dw-deep-research` | Multi-source research with citation tracking and verification | Topic or question | Research report with bibliography |
-| `/dw-functional-doc` | Maps screens, flows, and modules into a functional dossier with E2E coverage | Target URL/route + project | `.dw/flows/<project>/<slug>/` with docs, scripts, evidence |
-
-### Quality (3 Levels)
-
-| Level | Command | When | Generates Report? |
-|-------|---------|------|-------------------|
-| **1** | *(embedded in /dw-run-task)* | After each task | No (terminal output) |
-| **2** | `/dw-review-implementation` | After all tasks / manual | Yes (formatted output) |
-| **3** | `/dw-code-review` | Before PR / manual | Yes (`code-review.md`) |
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/dw-run-qa` | Visual QA with Playwright MCP + accessibility | PRD path | `QA/qa-report.md` + `QA/screenshots/` + `QA/logs/` |
-| `/dw-review-implementation` | Compares PRD vs code (FRs, endpoints, tasks) | PRD path | Gap report |
-| `/dw-code-review` | Formal code review (quality, rules, tests) | PRD path | `code-review.md` |
-| `/dw-refactoring-analysis` | Audit code smells and refactoring opportunities (Fowler's catalog) | PRD path | `refactoring-analysis.md` |
-| `/dw-security-check` | Rigid security check (OWASP static + Trivy SCA/IaC + native audit) for TS/Python/C#/Rust | PRD path or code | `security-check.md` |
-
-### Versioning
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/dw-commit` | Semantic commit (Conventional Commits) | - | Commit |
-| `/dw-commit-all` | Commit across all submodules (inside-out) | - | Commits |
-| `/dw-generate-pr` | Push + create PR + copy body + open URL | Target branch | PR on GitHub |
-| `/dw-revert-task` | Safely revert a specific task's commits (dependency checks + confirmation) | PRD path + task number | Reverted commits + updated `tasks.md` |
-
-### Internal commands (used by other dw-* commands; rarely invoked directly)
-
-| Command | What it does | Typically invoked by |
-|---------|-------------|----------------------|
-| `/dw-adr` | Record an Architecture Decision Record during PRD execution | `/dw-create-techspec`, `/dw-run-task` when a non-trivial decision arises |
-| `/dw-intel` | Query the codebase index built in `.dw/intel/` | `/dw-create-prd`, `/dw-create-techspec`, `/dw-code-review`, etc. |
-| `/dw-map-codebase` | Build/refresh the queryable codebase index in `.dw/intel/` | `/dw-analyze-project` (auto-runs after rules generation) |
-
-These are exposed as slash commands for occasional manual use (e.g., quickly recording an ADR mid-session, ad-hoc codebase queries) but most users never invoke them directly — they're called by the higher-level commands above.
-
-### Maintenance
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/dw-list-tasks` | Lists tasks and progress for a PRD | PRD path | Status table |
-| `/dw-task-summary` | Shows details of a task without executing | Number + path | Task summary |
-| `/dw-archive-prd` | Moves completed PRD to `.dw/archived/prd/` | PRD path | Archived PRD |
-| `/dw-help` | This command guide (supports keyword lookup: `/dw-help bug`) | (optional) command or keyword | This document or filtered section |
-| `/dw-update` | Updates dev-workflow to the latest version on npm without leaving the agent (supports `--rollback`) | (none) or `--rollback` | Updated or restored managed files |
+## Workflow at a glance
 
-### Bundled Skills (invoked internally — not commands)
-
-Skills in `.agents/skills/` that commands above invoke transparently. You don't call them directly.
-
-| Skill | Invoked by | Role |
-|-------|------------|------|
-| `dw-verify` | run-task, run-plan, fix-qa, bugfix, code-review, generate-pr, quick | core rule: no success claim without a PASS VERIFICATION REPORT |
-| `dw-memory` | run-task, run-plan, autopilot, resume, revert-task | Two-tier workflow memory (shared + task-local) with promotion test |
-| `dw-review-rigor` | code-review, review-implementation, refactoring-analysis | De-duplication, severity ordering, verify-intent-before-flag, signal-over-volume |
-| `dw-council` | brainstorm `--council`, create-techspec `--council` | Multi-advisor debate (3-5 archetypes) with steel-manning, concession tracking, and dissent-preserving synthesis. Opt-in. |
-
-Inspired by skills from the [Compozy](https://github.com/compozy/compozy) project (`cy-final-verify`, `cy-workflow-memory`, `cy-review-round`).
-
-## Review Architecture (3 Levels)
+`/dw-autopilot "wish"` runs the full pipeline (PRD → ... → PR) with 3 gates. Step-by-step:
 
 ```
-LEVEL 1 - Post-Task Validation (automatic, lightweight)
-├── Embedded in /dw-run-task
-├── Verifies task acceptance criteria
-├── Runs tests (pnpm test / npm test)
-├── Checks basic patterns (types, imports)
-├── No report file
-└── If fails: PAUSES execution
-
-LEVEL 2 - PRD Compliance (/dw-review-implementation)
-├── Compares ALL FRs from PRD vs actual code
-├── Verifies ALL endpoints from TechSpec
-├── Checks real status of each task (ignores checkboxes)
-├── Identifies gaps, partial implementations, extra code
-├── Called automatically at end of /dw-run-plan
-└── Available manually
-
-LEVEL 3 - Formal Code Review (/dw-code-review)
-├── Everything from Level 2 +
-├── Quality analysis (SOLID, DRY, complexity, security)
-├── Conformance with project rules (.dw/rules/)
-├── Tests with coverage
-├── Generates code-review.md in PRD directory
-└── Status: APPROVED / WITH CAVEATS / REJECTED
+/dw-brainstorm → /dw-plan → /dw-run → /dw-qa → /dw-review → /dw-commit → /dw-generate-pr
 ```
 
-## Common Flows
-
-### New Feature (Full)
-```bash
-/dw-brainstorm "initial idea"                      # 0. Explore options and trade-offs
-/dw-create-prd                                     # 1. Describe the feature
-/dw-create-techspec .dw/spec/prd-name              # 2. Generate tech spec
-/dw-create-tasks .dw/spec/prd-name                 # 3. Break into tasks
-/dw-run-plan .dw/spec/prd-name                     # 4. Execute all (includes Level 1+2)
-/dw-refactoring-analysis .dw/spec/prd-name         # 5. Audit code smells (optional)
-/dw-code-review .dw/spec/prd-name                  # 6. Formal code review (Level 3)
-/dw-generate-pr main                               # 7. Create PR
-/dw-archive-prd .dw/spec/prd-name                  # 8. After merge
-```
+## Advanced / internal commands
 
-### New Feature (Incremental)
-```bash
-/dw-brainstorm "initial idea"                      # 0. Explore options and trade-offs
-/dw-create-prd                                     # 1. PRD
-/dw-create-techspec .dw/spec/prd-name              # 2. TechSpec
-/dw-create-tasks .dw/spec/prd-name                 # 3. Tasks
-/dw-run-task .dw/spec/prd-name                     # 4. Task 1 (with Level 1)
-/dw-run-task .dw/spec/prd-name                     # 5. Task 2 (with Level 1)
-# ... repeat for each task
-/dw-review-implementation .dw/spec/prd-name        # 6. PRD review (Level 2)
-/dw-code-review .dw/spec/prd-name                  # 7. Code review (Level 3)
-/dw-generate-pr main                               # 8. PR
+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.
 ```
 
-### Simple Bug
-```bash
-/dw-bugfix "bug description"                       # Analyze and fix
-/dw-commit                                         # Commit the fix
-/dw-generate-pr main                               # PR
-```
+## Advanced mode — `--advanced` flag
 
-### Complex Bug
-```bash
-/dw-bugfix "description" --analysis                # Generate analysis document
-/dw-create-techspec .dw/spec/dw-bugfix-name           # TechSpec for the fix
-/dw-create-tasks .dw/spec/dw-bugfix-name              # Tasks for the fix
-/dw-run-plan .dw/spec/dw-bugfix-name                  # Execute all
-/dw-generate-pr main                               # PR
-```
+When invoked with `--advanced`, ALSO show:
 
-### Visual QA (Frontend)
-```bash
-/dw-run-qa .dw/spec/prd-name                       # QA with Playwright MCP
-# If bugs found:
-/dw-bugfix "description"                           # Fix each bug
-/dw-fix-qa .dw/spec/prd-name                       # Fix + retest full cycle
-```
+```markdown
+# dev-workflow — Advanced / Internal Commands
 
-### Frontend Redesign
-```bash
-/dw-analyze-project                                # 0. Understand project patterns
-/dw-redesign-ui "target page or component"         # 1. Audit + propose + implement
-/dw-run-qa .dw/spec/prd-name                       # 2. Visual QA (optional)
-/dw-code-review .dw/spec/prd-name                  # 3. Code review
-/dw-commit                                         # 4. Commit
-/dw-generate-pr main                               # 5. PR
-```
+These are auto-invoked by primary commands but available standalone.
 
-### Autopilot (Full Pipeline)
-```bash
-/dw-autopilot "description of what you want to build"  # Research → PRD → Tasks → Code → QA → PR
-```
+## Tier 4 — Hidden (5)
 
-### Query Codebase
-```bash
-/dw-intel "how does X work in this project?"       # Answer with sources
+| 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-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 |
 ```
 
-### Deep Research
-```bash
-/dw-deep-research "topic or question"              # Multi-source research with citations
-```
-
-## File Structure
-
-```
-your-project/
-├── .dw/
-│   ├── commands/              # Source of truth for commands
-│   │   ├── dw-help.md
-│   │   ├── dw-brainstorm.md
-│   │   ├── dw-create-prd.md
-│   │   ├── dw-create-techspec.md
-│   │   ├── dw-create-tasks.md
-│   │   ├── dw-run-task.md
-│   │   ├── dw-run-plan.md
-│   │   ├── dw-run-qa.md
-│   │   ├── dw-code-review.md
-│   │   ├── dw-refactoring-analysis.md
-│   │   ├── dw-review-implementation.md
-│   │   ├── dw-analyze-project.md
-│   │   ├── dw-autopilot.md
-│   │   ├── dw-deep-research.md
-│   │   ├── dw-intel.md
-│   │   ├── dw-redesign-ui.md
-│   │   ├── dw-bugfix.md
-│   │   ├── dw-commit.md
-│   │   ├── dw-functional-doc.md
-│   │   └── dw-generate-pr.md
-│   ├── templates/             # Document templates
-│   │   ├── prd-template.md
-│   │   ├── techspec-template.md
-│   │   ├── tasks-template.md
-│   │   ├── task-template.md
-│   │   ├── bugfix-template.md
-│   │   └── functional-doc/    # Functional dossier templates
-│   ├── scripts/               # Utility scripts
-│   │   └── functional-doc/    # Dossier generation & Playwright runner
-│   ├── references/            # Reference materials and external docs
-│   ├── rules/                 # Project-specific rules
-│   │   └── *.md
-│   ├── tasks/                 # Active PRDs and tasks
-│   │   └── prd-[name]/
-│   │       ├── prd.md
-│   │       ├── techspec.md
-│   │       ├── tasks.md
-│   │       └── *_task.md
-│   └── archived/prd/          # Completed PRDs
-├── .claude/skills/            # Claude Code skills
-├── .agents/skills/            # Codex/Copilot skills
-├── .opencode/commands/        # OpenCode commands
-└── .github/copilot-instructions.md  # Copilot instructions
-```
-
-## Tool Integration
-
-Commands work across multiple AI tools, all pointing to the same source `.dw/commands/`:
-
-| Tool | Location | Format |
-|------|----------|--------|
-| **Claude Code** | `.claude/skills/*/SKILL.md` | Skill referencing `.dw/commands/` |
-| **Codex CLI** | `.agents/skills/*/SKILL.md` | Skill referencing `.dw/commands/` |
-| **OpenCode** | `.opencode/commands/*.md` | Command referencing `.dw/commands/` |
-| **GitHub Copilot** | `.github/copilot-instructions.md` | Instructions listing the commands |
+## Keyword mode — `/dw-help <keyword>`
+
+Match the keyword and suggest:
+
+| Keyword | Suggest |
+|---------|---------|
+| `prd`, `spec`, `plan`, `architecture`, `techspec`, `tasks` | `/dw-plan` (with appropriate stage flag) |
+| `bug`, `error`, `broken`, `fix` | `/dw-bugfix` |
+| `run`, `execute`, `implement` | `/dw-run` |
+| `review`, `quality`, `audit code` | `/dw-review` |
+| `qa`, `test plan`, `e2e` | `/dw-qa` |
+| `commit`, `git` | `/dw-commit` |
+| `pr`, `pull request`, `merge` | `/dw-generate-pr` |
+| `idea`, `brainstorm`, `explore` | `/dw-brainstorm` |
+| `research`, `compare`, `state of the art` | `/dw-brainstorm --research` |
+| `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) |
+| `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` |
+| `adr`, `decision` | `/dw-adr` (also auto-invoked from `/dw-plan --council`) |
+| `docker`, `compose`, `container` | `/dw-dockerize` |
+| `new project`, `bootstrap`, `scaffold` | `/dw-new-project` |
+| `functional doc`, `screen map`, `e2e doc` | `/dw-functional-doc` |
+| `incident`, `outage`, `postmortem`, `sev-1`, `sev-2` | (Skill `dw-incident-response` auto-invoked from `/dw-bugfix` for prod-critical) |
+| `eval`, `llm`, `ai feature`, `rag` | (Skill `dw-llm-eval` invoked from `/dw-plan tasks`, `/dw-review`, `/dw-qa --ai`) |
+
+If no keyword matches, show the default surface and a note: "Keyword `<word>` not recognized — see commands above."
 
 ## FAQ
 
-**Q: What is the difference between `/dw-run-task` and `/dw-run-plan`?**
-- `/dw-run-task` executes ONE task with manual control between each one
-- `/dw-run-plan` executes ALL automatically with a final review
-
-**Q: Do I need to run `/dw-review-implementation` manually?**
-- Not if using `/dw-run-plan` (already included). Yes if using `/dw-run-task` incrementally.
+**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.
 
-**Q: When to use `/dw-code-review` vs `/dw-review-implementation`?**
-- `/dw-review-implementation` (Level 2): Checks if PRD FRs were implemented
-- `/dw-code-review` (Level 3): Additionally analyzes code quality and generates a formal report
+**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.
 
-**Q: Does `/dw-bugfix` always fix directly?**
-- No. It performs triage. If it is a feature (not a bug), it redirects to `/dw-create-prd`. If it is a complex bug, it can generate an analysis document with `--analysis`.
+**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.
 
-**Q: When should I use `/dw-deep-research`?**
-- For comprehensive multi-source analysis, technology comparisons, state-of-the-art reviews, or any topic requiring cited evidence. Not for simple lookups or debugging.
+**Q: How do I check if my project follows good patterns?**
+- `/dw-analyze-project` writes `.dw/rules/`. Then any command reads those rules for compliance.
 
-**Q: Does `/dw-redesign-ui` work with Angular?**
-- Yes. The command is framework-agnostic. For React it uses react-doctor and `vercel-react-best-practices`; for Angular it uses `ng lint` and Angular DevTools. UI discipline (`dw-ui-discipline`) works with any framework — enforces the hard-gate, anti-slop catalog, and WCAG floor regardless of stack.
+**Q: How do I get more flow recommendations during ideation?**
+- `/dw-brainstorm "idea" --council` adds a multi-advisor stress-test debate.
+- `/dw-brainstorm "topic" --research` runs a deep multi-source citation pipeline.
 
-**Q: How do I get codebase intelligence and parallel execution?**
-- Both are native to dev-workflow. Run `/dw-map-codebase` to build the queryable index in `.dw/intel/`, then `/dw-intel "<question>"` to query it. For parallel execution, `/dw-run-plan` invokes the bundled phase-execution agents (executor + plan-checker) directly to dispatch tasks in waves with atomic commits per task. No external dependency needed.
+**Q: Where do AI features get evaluated?**
+- 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: Does `/dw-autopilot` replace all other commands?**
-- No. It orchestrates existing commands in sequence. You can still use each command individually for manual control. Autopilot is for when you want to go from a wish to a PR with minimal intervention.
+**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).
 
 </system_instructions>

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

@@ -1,20 +1,28 @@
 <system_instructions>
-You are a codebase intelligence assistant. This command answers questions about the project using the queryable index in `.dw/intel/` (built by `/dw-map-codebase`) and the human-readable conventions in `.dw/rules/` (built by `/dw-analyze-project`).
+You are the codebase intelligence assistant. Two modes: query the existing index, or (re)build the index from source.
 
-<critical>This command is read-only. Do NOT modify code or project files.</critical>
-<critical>Always cite information sources (file path, line number when applicable).</critical>
+<critical>Query mode is read-only. Do NOT modify code or project files.</critical>
+<critical>Build mode writes to `.dw/intel/` only — never to source.</critical>
+<critical>Always cite information sources (file path, line number when applicable) in query mode.</critical>
 <critical>If the index is stale (>7 days old) or absent, surface that to the user — do NOT silently fall back without flagging.</critical>
 
+## Modes
+
+| Invocation | Behavior |
+|------------|----------|
+| `/dw-intel "<question>"` | **Default — query mode.** Answers using `.dw/intel/` (machine-readable) + `.dw/rules/` (human-readable) + grep fallback. |
+| `/dw-intel --build` | **Build mode.** Recursively scans the project and produces `.dw/intel/{stack,files,apis,deps}.json` + `.dw/intel/arch.md`. Use after major refactors, large file moves, or when intel is >7 days stale. |
+| `/dw-intel --build --incremental` | Incremental build: only re-reads files changed since `.last-refresh.json`. Faster but may miss large structural changes. |
+
 ## When to Use
 
-- Use to understand how something works in the project (auth flow, data model, route surface)
-- Use to find patterns, conventions, or architectural decisions
-- Use to verify if something already exists before implementing
-- Do NOT use to implement changes (use `/dw-run-task`)
+- **Query mode**: understand how something works in the project (auth flow, data model, route surface). Find patterns, conventions, or architectural decisions. Verify if something already exists before implementing.
+- **Build mode**: after major refactors, large dependency updates, or when `.dw/intel/` is empty or stale.
+- Do NOT use to implement changes (use `/dw-run`).
 
 ## Pipeline Position
 
-**Predecessor:** `/dw-map-codebase` (builds `.dw/intel/`) and/or `/dw-analyze-project` (builds `.dw/rules/`) | **Successor:** any `dw-*` command that needs to act on the intel
+**Predecessor (build mode):** any major project change | **Successor:** any `dw-*` command that needs intel
 
 ## Complementary Skills
 
@@ -41,9 +49,9 @@ You are a codebase intelligence assistant. This command answers questions about
 
 Before answering, read `.dw/intel/.last-refresh.json` if present:
 
-- If `updated_at` is more than 7 days old → prefix the answer with: `⚠ Index last refreshed YYYY-MM-DD (X days ago). Consider running /dw-map-codebase to refresh.`
+- If `updated_at` is more than 7 days old → prefix the answer with: `⚠ Index last refreshed YYYY-MM-DD (X days ago). Consider running /dw-intel --build to refresh.`
 - If `.dw/intel/` exists but `.last-refresh.json` is absent → prefix with: `⚠ No refresh metadata; index may be stale.`
-- If `.dw/intel/` does not exist at all → tell the user: `No .dw/intel/ found. Falling back to .dw/rules/ + grep. For richer answers, run /dw-map-codebase.`
+- If `.dw/intel/` does not exist at all → tell the user: `No .dw/intel/ found. Falling back to .dw/rules/ + grep. For richer answers, run /dw-intel --build.`
 
 Don't refuse to answer — return the best info available.
 
@@ -112,7 +120,7 @@ Don't dump JSON. Write a 3-8 line answer that:
 
 - **Prefer `.dw/intel/` over grep.** It's curated and faster. Grep only when intel is absent or stale.
 - **Cite paths, not contents.** The user can `Read` paths if they need the source.
-- **Don't fabricate.** If `.dw/intel/` doesn't have the answer and grep returns nothing, say so. Suggest `/dw-map-codebase` if `.dw/intel/` is missing.
+- **Don't fabricate.** If `.dw/intel/` doesn't have the answer and grep returns nothing, say so. Suggest `/dw-intel --build` if `.dw/intel/` is missing.
 - **Combine intel + rules.** A query about "how do we name service files?" should pull from `arch.md` (intel) AND `.dw/rules/<module>.md` (project conventions). The two complement.
 
 ## Critical Rules
@@ -122,8 +130,64 @@ Don't dump JSON. Write a 3-8 line answer that:
 - <critical>Surface stale-index warnings prominently — do not bury them at the bottom.</critical>
 - Do NOT include secrets/tokens/credentials in any answer (they should not be in `.dw/intel/` to begin with, but defense in depth).
 
+## Build mode (`--build`)
+
+When invoked with `--build`, the command produces or refreshes the queryable intel index. This was previously `/dw-intel --build`, now folded in.
+
+### Behavior
+
+1. **Detect project structure.** Recursive scan for entry points: package.json, requirements.txt, pyproject.toml, Cargo.toml, *.csproj, etc.
+2. **Detect monorepo orchestrators.** pnpm/nx/turborepo workspaces, lerna config, git submodules.
+3. **Stack identification.** For each detected module, identify language, framework, package manager, build tool. Output to `.dw/intel/stack.json`.
+4. **File inventory.** For source files (skip `node_modules/`, `.git/`, `dist/`, `build/`, `.dw/`): catalog with path, exports, primary purpose. Output to `.dw/intel/files.json`. Budget ≤2K tokens (prioritize coverage of key files over exhaustive listing for large repos).
+5. **API extraction.** Routes, RPC handlers, GraphQL resolvers, public CLI surface. Output to `.dw/intel/apis.json`. Budget ≤1.5K tokens.
+6. **Dependency map.** Internal cross-module imports + external packages with `used_by` arrays. Output to `.dw/intel/deps.json`. Budget ≤1K tokens.
+7. **Architecture summary.** Prose document describing the project's shape, key patterns, request flows, deployment topology. Output to `.dw/intel/arch.md`. Budget ≤1.5K tokens.
+8. **Refresh metadata.** Write `.dw/intel/.last-refresh.json` with `updated_at`, `version`, `mode` (full or incremental), files-scanned count.
+
+### Complementary skill for build mode
+
+| Skill | Trigger |
+|-------|---------|
+| `dw-codebase-intel` | **ALWAYS in build mode** — provides the `.dw/intel/` schema, the incremental-update protocol (which files to re-read, how to merge with existing entries), and the budget rules per file. |
+
+### Forbidden in build mode
+
+- Never read `.env*` (except `.env.example` / `.env.template`), `*.key`, `*.pem`, `*.pfx`, `*.p12`, `*.keystore`, `*.jks`, `id_rsa`, `id_ed25519`, or files matching `*credential*`/`*secret*` in name. Skip silently if encountered.
+- Never include secrets/tokens/credentials in any intel file.
+- Never use Bash `ls`/`find`/`cat` (cross-platform sensitivity); use Glob/Read/Grep.
+
+### Incremental mode (`--build --incremental`)
+
+Reads `.dw/intel/.last-refresh.json` to find the last build timestamp. Only re-reads files modified since. Faster but may miss:
+- New directories not previously catalogued.
+- Removed files (they remain in `files.json` until full build).
+
+Use full `--build` quarterly or after structural changes; incremental for routine refresh.
+
+### Output structure
+
+```
+.dw/intel/
+├── stack.json            # Detected stack per module
+├── files.json            # Source file inventory with exports + purposes
+├── apis.json             # Public API surface
+├── deps.json             # Dependency graph (internal + external)
+├── arch.md               # Architecture summary (prose)
+└── .last-refresh.json    # Metadata: updated_at, version, mode
+```
+
+### Why this skill exists
+
+Previously two commands: `/dw-intel` (query) and `/dw-intel --build` (build). The split was historical — one wrote, one read, but both shared the schema and the same `.dw/intel/` directory. Consolidating reduces:
+- Confusion ("which one do I run?").
+- Maintenance burden of two separate command files.
+- Path-walking docs duplicated across two files.
+
+Same operations, single mental entry point.
+
 ## Inspired by
 
-The query-patterns mapping (where-is / what-uses / architecture-of / etc.) and the JSON intel schema are adapted from the [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) project (MIT license). Path conventions changed from `.planning/intel/` to `.dw/intel/`.
+The query-patterns mapping (where-is / what-uses / architecture-of / etc.) and the JSON intel schema are adapted from the [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) project (MIT license). Path conventions changed from `.planning/intel/` to `.dw/intel/`. Build-mode behavior previously lived in `/dw-intel --build` (same upstream).
 
 </system_instructions>