@brunosps00/dev-workflow 0.8.1 → 0.9.0

package/scaffold/en/commands/dw-execute-phase.md

@@ -0,0 +1,149 @@
+<system_instructions>
+You are a phase execution orchestrator. Your job is to spawn the `dw-executor` agent (from the `dw-execute-phase` bundled skill) to execute every task in `.dw/spec/prd-<slug>/tasks.md` in waves, with one atomic commit per task. Before spawning the executor, you MUST gate on the `dw-plan-checker` agent — execution does not start until plan-checker returns PASS.
+
+<critical>NEVER execute without plan-checker PASS. The gate is non-negotiable. If plan-checker returns REVISE or BLOCK, abort and surface the verdict.</critical>
+<critical>One commit per task. The executor enforces this; do not bypass.</critical>
+<critical>Deviation Rule 3 (architectural conflict) aborts execution. Do not auto-retry.</critical>
+
+## When to Use
+
+- After `/dw-create-tasks` produces `tasks.md` and you want to execute the entire phase
+- When `/dw-autopilot` reaches the execution stage
+- After resolving REVISE issues from a previous plan-checker run
+- NOT for single-task changes (use `/dw-run-task` instead)
+- NOT for greenfield scaffolding (use `/dw-new-project` instead)
+
+## Pipeline Position
+
+**Predecessor:** `/dw-create-tasks` (and optionally `/dw-plan-checker` run manually first) | **Successor:** `/dw-run-qa` to validate against PRD, then `/dw-code-review` and `/dw-generate-pr`
+
+## Complementary Skills
+
+| Skill | Trigger |
+|-------|---------|
+| `dw-execute-phase` | **ALWAYS** — source of `dw-executor` and `dw-plan-checker` agents and reference docs (`wave-coordination.md`, `plan-verification.md`, `atomic-commits.md`) |
+| `dw-codebase-intel` | Optional — executor reads `.dw/intel/` for codebase facts during implementation |
+| `dw-verify` | **ALWAYS** — VERIFICATION REPORT after each phase completes (test + lint + build PASS) |
+
+## Input Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{{PRD_PATH}}` | Path to the PRD folder containing `tasks.md` | `.dw/spec/prd-checkout-v2` |
+| `{{START_FROM}}` | Optional. Resume from task NN (default 01) | `04` |
+| `{{MODE}}` | Optional. `full` (default), `wave-only N`, `up-to-task NN` | `full` |
+
+## Flags
+
+| Flag | Behavior |
+|------|----------|
+| (default) | Run all waves to completion with plan-checker gate |
+| `--skip-check` | DANGEROUS — skip plan-checker gate. Only allowed if plan-checker ran <30 min ago and returned PASS (verifier audit log). |
+| `--dry-run` | Run plan-checker only; do not spawn executor. |
+| `--from <NN>` | Resume from task NN (skips earlier tasks). Use with `/dw-resume`. |
+
+## File Locations
+
+- PRD: `{{PRD_PATH}}/prd.md`
+- TechSpec: `{{PRD_PATH}}/techspec.md`
+- Tasks: `{{PRD_PATH}}/tasks.md` (the plan being executed)
+- Per-task detail: `{{PRD_PATH}}/<NN>_task.md`
+- Deviations log: `{{PRD_PATH}}/deviations.md`
+- Phase summary (output): `{{PRD_PATH}}/SUMMARY.md`
+- Active session (checkpoint): `{{PRD_PATH}}/active-session.md`
+- Skill source: `.agents/skills/dw-execute-phase/{SKILL.md, agents/*.md, references/*.md}`
+
+## Required Behavior
+
+### Stage 1 — Plan-checker gate
+
+Spawn `dw-plan-checker` agent with the PRD path. The agent runs the 6-dimension verification (requirement coverage, task completeness, dependency soundness, artifact wiring, context budget, constraint compliance).
+
+Three possible verdicts:
+
+- **PASS** → proceed to Stage 2
+- **REVISE** → abort. Print the issues. Suggest re-running `/dw-create-tasks` with the issues as input. Exit status: `PHASE-REVISE-NEEDED`.
+- **BLOCK** → abort. Print the issues with file:line citations. Exit status: `PHASE-BLOCKED`. User must resolve manually before re-running.
+
+If `--skip-check` is passed AND a recent plan-checker PASS exists in audit log (within 30 min), skip Stage 1. Otherwise reject the flag.
+
+### Stage 2 — Executor dispatch
+
+Spawn `dw-executor` agent with:
+
+- `prd_path: {{PRD_PATH}}`
+- `start_from: {{START_FROM}}` (default `01`)
+- `mode: {{MODE}}` (default `full`)
+- `required_reading:` block citing `SKILL.md`, `agents/executor.md`, `references/wave-coordination.md`, `references/atomic-commits.md`
+
+The executor:
+
+1. Computes waves from `Depends on:` fields
+2. For each wave, dispatches subagents in parallel (one per task)
+3. Each subagent implements + verifies + commits atomically
+4. Marks `[x]` in `tasks.md` after each task commits
+5. Writes `SUMMARY.md` after the final wave
+6. Checkpoints to `active-session.md` if context budget hits 70%
+
+### Stage 3 — Verification
+
+After executor returns, run `dw-verify` skill: full project test + lint + build must PASS.
+
+If verification fails → status `PHASE-VERIFICATION-FAILED`. The phase committed code (atomically per task) but the aggregate project state has issues. Surface to user — likely needs `/dw-fix-qa` next.
+
+### Stage 4 — Report
+
+Print:
+
+```
+## Phase Execution Complete
+
+PRD: {{PRD_PATH}}
+Status: <COMPLETE | PARTIAL | CHECKPOINT>
+Tasks: <N> total, <N> committed, <N> deviations
+Waves: <N> (max width: <N>)
+Duration: <minutes>
+Final commit: <SHA>
+
+VERIFICATION REPORT:
+- Lint: PASS/FAIL
+- Tests: PASS/FAIL
+- Build: PASS/FAIL
+
+Next steps:
+- Run /dw-run-qa to validate against PRD acceptance criteria
+- Run /dw-code-review for the formal Level 3 review
+- Then /dw-generate-pr to ship
+```
+
+## Critical Rules
+
+- <critical>plan-checker PASS is a hard gate. NEVER execute without it (except with `--skip-check` AND a fresh prior PASS).</critical>
+- <critical>The executor owns commit format. NEVER post-process commits from this command.</critical>
+- <critical>Rule 3 deviations (architectural conflicts) abort the phase. Do not auto-retry.</critical>
+- <critical>Checkpoint > push-through. If the executor checkpoints, do NOT auto-restart; let the user invoke `/dw-resume`.</critical>
+- Do NOT push to remote. `/dw-generate-pr` handles the push.
+- Do NOT skip dimensions in plan-checker via flags. Plan-checker is non-negotiable.
+
+## Error Handling
+
+- Plan-checker returns BLOCK → exit `PHASE-BLOCKED`, surface issues, no auto-replan
+- Executor returns `EXEC-BLOCKED` (Rule 3 deviation) → exit `PHASE-BLOCKED`, the deviation is in `deviations.md`
+- Executor returns `EXEC-PARTIAL` → some tasks committed, recoverable via `/dw-resume`
+- Executor returns `CHECKPOINT` → context budget exhausted, `/dw-resume` to continue
+- Plan-checker times out (>5 min) → exit with status `PLAN-CHECK-TIMEOUT`, suggest reducing phase size
+
+## Integration With Other dw-* Commands
+
+- **`/dw-create-tasks`** — predecessor; produces the `tasks.md` this command executes
+- **`/dw-plan-checker`** — manual invocation of just the gate (this command bundles it)
+- **`/dw-resume`** — restores from `active-session.md` after CHECKPOINT
+- **`/dw-run-task`** — runs a single task; `/dw-execute-phase` runs the whole phase
+- **`/dw-run-plan`** — older command; v0.9.0 makes it an alias for this command (both call the same agents)
+- **`/dw-run-qa`** — successor; validates the implemented phase against PRD
+
+## Inspired by
+
+`dw-execute-phase` is dev-workflow-native. The two-stage gate-then-execute pattern, the wave-based parallel dispatch, atomic-commit-per-task, deviation handling, and checkpoint protocol are adapted from [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (`/gsd-execute-phase`, `gsd-executor`, `gsd-plan-checker`) by gsd-build (MIT license). dev-workflow specifics: writes to `.dw/spec/prd-<slug>/` (not `.planning/<phase>/`), uses dev-workflow's PRD/TechSpec/Tasks hierarchy, integrates with `dw-verify` and `dw-codebase-intel` skills.
+
+</system_instructions>

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

@@ -30,6 +30,9 @@ You are a workspace help assistant. When invoked, present the user with a comple
 | 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. |
+| map codebase, intel index, code map, knowledge graph, queryable index | `/dw-map-codebase` | Builds .dw/intel/ (stack/files/apis/deps/arch) so /dw-intel and other commands stop re-exploring the codebase. |
+| execute phase, parallel tasks, wave, dispatch, atomic commits | `/dw-execute-phase` | Runs a PRD phase in waves with atomic commits per task, deviation handling, and a hard plan-checker gate before any code is touched. |
+| plan check, verify plan, plan validation, goal backward | `/dw-plan-checker` | Goal-backward verification of tasks.md before execution. PASS / REVISE / BLOCK across 6 dimensions. |
 | 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 |
 | hotfix, quick change | `/dw-quick` | One-off task with guarantees, no PRD |
@@ -396,8 +399,8 @@ Commands work across multiple AI tools, all pointing to the same source `.dw/com
 **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. Visual design (`ui-ux-pro-max`) works with any framework.
 
-**Q: What is GSD and do I need to install it?**
-- GSD (get-shit-done-cc) is an optional engine that enables advanced features: parallel execution, plan verification, codebase intelligence, and cross-session persistence. Install with `npx dev-workflow install-deps`. Without GSD, all commands work normally.
+**Q: How do I get codebase intelligence and parallel execution?**
+- Both are native to dev-workflow as of v0.9.0. Run `/dw-map-codebase` to build the queryable index in `.dw/intel/`, then `/dw-intel "<question>"` to query it. For parallel execution, `/dw-execute-phase` dispatches tasks in waves with atomic commits per task. No external dependency needed.
 
 **Q: Does `/dw-quick` replace `/dw-run-task`?**
 - No. `/dw-quick` is for one-off changes without a PRD. `/dw-run-task` executes tasks from a structured plan with PRD and TechSpec.

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

@@ -1,17 +1,26 @@
 <system_instructions>
-You are a codebase intelligence assistant. This command exists to answer questions about the project using the knowledge index generated by `/dw-analyze-project`.
+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`).
 
 <critical>This command is read-only. Do NOT modify code or project files.</critical>
-<critical>Always cite information sources (file, line, section).</critical>
+<critical>Always cite information sources (file path, line number when applicable).</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>
 
 ## When to Use
-- Use to understand how something works in the project
+
+- 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-quick` or `/dw-run-task`)
 
 ## Pipeline Position
-**Predecessor:** `/dw-analyze-project` (generates the index) | **Successor:** any dw-* command
+
+**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
+
+## Complementary Skills
+
+| 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). |
 
 ## Input Variables
 
@@ -19,42 +28,102 @@ You are a codebase intelligence assistant. This command exists to answer questio
 |----------|-------------|---------|
 | `{{QUERY}}` | Question about the codebase | "how does authentication work?" |
 
+## File Locations
+
+- Machine-readable intel (queried first): `.dw/intel/{stack,files,apis,deps}.json` + `.dw/intel/arch.md`
+- Refresh metadata: `.dw/intel/.last-refresh.json`
+- Human-readable rules (queried second): `.dw/rules/{index,<module>,integrations}.md`
+- Direct grep fallback (queried last): the project source files
+
 ## Required Behavior
 
-1. Receive the user's question
-2. Query knowledge sources in priority order:
-   a. `.planning/intel/` (if exists — GSD index, richer)
-   b. `.dw/rules/` (project rules, always available)
-   c. Direct codebase search (grep, glob) as complement
-3. Synthesize the answer with concrete references
-4. Cite sources: file, section, line when applicable
+### 1. Stale-index check
+
+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 `.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.`
+
+Don't refuse to answer — return the best info available.
+
+### 2. Query shape detection
+
+Classify the user's `{{QUERY}}` into one of the shapes documented in `.agents/skills/dw-codebase-intel/references/query-patterns.md`:
+
+- **where-is** — primary: `files.json`, secondary: `apis.json`
+- **what-uses** — primary: `deps.json` (libs) or `files.json` (symbols)
+- **architecture-of** — primary: `arch.md`, secondary: `stack.json`
+- **stack** — primary: `stack.json`
+- **dep-info** — primary: `deps.json`
+- **api-list** — primary: `apis.json`
+- **find-export** — primary: `files.json` (search `exports` arrays)
+- **convention** — primary: `arch.md`, secondary: `.dw/rules/`
+
+### 3. Search execution
+
+Read the primary file and search for matches (case-insensitive). Rank:
 
-## GSD Integration
+1. Exact symbol/path match
+2. Substring match in keys
+3. Substring match in descriptions
 
-<critical>When .planning/intel/ exists, querying via /gsd-intel is MANDATORY as the primary source. Do NOT skip this query.</critical>
+If primary yields zero matches, fall back to secondary, then to grep.
 
-If GSD (get-shit-done-cc) is installed and `.planning/intel/` exists:
-- Delegate to `/gsd-intel "{{QUERY}}"` for indexed lookup
-- GSD returns information from: architectural assumptions, decision spaces, behavioral references, UI patterns
-- Enrich with `.dw/rules/` data when relevant
+### 4. Cross-reference
 
-If GSD is NOT installed:
-- Use `.dw/rules/` as primary source
-- Complement with direct codebase search (grep for patterns, read key files)
-- Suggest: "For richer intel, run `/dw-analyze-project` with GSD installed"
+For richer answers, cross-reference the primary match with related intel:
+
+- A file from `files.json` → look up its dependencies in `deps.json`
+- An API from `apis.json` → resolve its handler file via `apis.json[entry].file`, then list that file's exports from `files.json`
+- A dep from `deps.json` → list `used_by` and look up each entry in `files.json` for context
+
+### 5. Synthesize and cite
+
+Don't dump JSON. Write a 3-8 line answer that:
+
+- Addresses the user's question directly
+- Cites file paths in backticks
+- Includes line numbers when known (read the file briefly if needed)
+- Mentions related concepts the user may want to follow up on
 
 ## Response Format
 
-### Answer: [topic]
+```markdown
+[⚠ stale warning if applicable]
+
+## Answer: [topic]
+
+[Structured answer, 3-8 lines, prose. Cite paths inline.]
+
+## Sources
+
+- `.dw/intel/files.json` — entries for `<file_a>`, `<file_b>`
+- `.dw/intel/apis.json` — `<endpoint>`
+- `.dw/rules/<module>.md` — convention "<name>"
+- `<src/path/file.ts>:<line>` — direct code reference (only if a file was opened)
+
+## Related Commands
+
+- `/<dw-cmd>` — [why useful as next step]
+```
+
+## Heuristics
+
+- **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.
+- **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
 
-[Structured answer based on consulted sources]
+- <critical>Read-only. NEVER edit code or project files from this command.</critical>
+- <critical>Cite paths. Every claim about the codebase must reference a real file.</critical>
+- <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).
 
-### Sources
-- `.planning/intel/[file].md` — [relevant section]
-- `.dw/rules/[file].md` — [referenced convention]
-- `src/[path]:[line]` — [code reference]
+## Inspired by
 
-### Related Commands
-- [Suggestion of dw- command to act on the information]
+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/`.
 
 </system_instructions>

package/scaffold/en/commands/dw-map-codebase.md

@@ -0,0 +1,125 @@
+<system_instructions>
+You are a codebase intelligence orchestrator. Your job is to spawn the `dw-intel-updater` agent (from the `dw-codebase-intel` bundled skill) to read the project's source files and write a queryable index to `.dw/intel/`. Other dev-workflow commands (`/dw-intel`, `/dw-create-prd`, `/dw-create-techspec`, `/dw-code-review`, etc.) read this index instead of doing expensive codebase exploration on every invocation.
+
+<critical>This command writes to `.dw/intel/` only. Never modifies application code.</critical>
+<critical>Use the `dw-intel-updater` agent — do NOT inline the intel-generation logic in this command. The agent owns the schema contract.</critical>
+
+## When to Use
+
+- **First scan**: a fresh project with no `.dw/intel/` yet. Run a full scan.
+- **Incremental refresh**: after a feature branch / large PR landed and source files changed. Run with `--files <paths>` to update only the affected entries.
+- **Scheduled refresh**: every 1-4 weeks to keep the index fresh; the staleness heuristic in `/dw-intel` warns when >7 days old.
+- **After dependency changes**: `/dw-deps-audit --execute` updates lockfiles and may touch deps. Re-run `/dw-map-codebase` afterwards to refresh `deps.json`.
+- Do NOT use for greenfield projects with no source yet — `/dw-new-project` already seeded `.dw/rules/index.md` minimally; nothing to map.
+
+## Pipeline Position
+
+**Predecessor:** any project with source files (run after `/dw-new-project` for greenfield, or as the first command on a brownfield repo) | **Successor:** `/dw-intel "<query>"` for ad-hoc questions, or `/dw-analyze-project` to enrich `.dw/rules/` with conventions/anti-patterns derived from the intel
+
+## Complementary Skills
+
+| Skill | Trigger |
+|-------|---------|
+| `dw-codebase-intel` | **ALWAYS** — source of the `dw-intel-updater` agent and reference docs (`intel-format.md`, `incremental-update.md`, `query-patterns.md`) |
+
+## Input Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{{FOCUS}}` | Optional. `full` (default if no `--files`), `partial` (when `--files` is set) | `partial` |
+| `{{FILES}}` | Optional. Space-separated list of paths to refresh (only meaningful with `--files`) | `src/auth/index.ts src/routes/auth.ts` |
+| `{{SINCE}}` | Optional alternative to `--files`. Git ref to derive changed files from | `HEAD~5` or `origin/main` |
+
+## Flags
+
+| Flag | Behavior |
+|------|----------|
+| (default) | Full scan if `.dw/intel/` is missing OR `.last-refresh.json` is older than 30 days; otherwise prompts whether to refresh fully or skip |
+| `--full` | Force full scan regardless of state |
+| `--files <a> <b> ...` | Partial update only for the listed paths |
+| `--since <gitref>` | Partial update for files changed since `<gitref>` (uses `git diff --name-only <gitref>...HEAD`) |
+
+## File Locations
+
+- Output index: `.dw/intel/{stack,files,apis,deps}.json` + `.dw/intel/arch.md`
+- Refresh metadata: `.dw/intel/.last-refresh.json`
+- Skill source: `.agents/skills/dw-codebase-intel/{SKILL.md, agents/intel-updater.md, references/*.md}`
+
+## Required Behavior
+
+### 1. State detection
+
+- Check `.dw/intel/.last-refresh.json` if it exists.
+- Compute project state: greenfield (no source files) → abort with hint; brownfield with no `.dw/intel/` → first scan; existing `.dw/intel/` → decide refresh path.
+
+### 2. Mode selection
+
+| Condition | Mode |
+|-----------|------|
+| No `.dw/intel/` | full |
+| `--full` flag | full |
+| `--files <list>` flag | partial with explicit list |
+| `--since <ref>` flag | partial with `git diff --name-only <ref>...HEAD` derived list |
+| `.last-refresh.json` >30 days old | prompt user: full / partial / skip |
+| Otherwise | partial since last refresh, derived from `git log --name-only --since=<last_refresh_date>` |
+
+### 3. Spawn `dw-intel-updater`
+
+Construct the spawn prompt for the agent. Required fields:
+
+- `focus: full` or `focus: partial --files <space-separated paths>`
+- `project_root: <absolute path>`
+- Optional `required_reading:` block listing the SKILL.md and references (the agent reads these for context)
+
+Spawn the agent and wait for completion.
+
+### 4. Verify output
+
+After the agent returns:
+
+- Verify `.dw/intel/{stack,files,apis,deps}.json` exist and parse as valid JSON.
+- Verify `.dw/intel/arch.md` exists.
+- Verify `.dw/intel/.last-refresh.json` was written and the hashes match the freshly written files.
+- If any of the above fails, report the failure with the agent's output and abort with status `MAP-FAILED`.
+
+### 5. Report
+
+Print a tight summary:
+
+```
+## Codebase Map Refreshed
+
+Mode: full | partial (<N> files)
+Files written:
+- .dw/intel/stack.json     (<bytes>) — <N> languages, <N> frameworks
+- .dw/intel/files.json     (<bytes>) — <N> entries
+- .dw/intel/apis.json      (<bytes>) — <N> endpoints
+- .dw/intel/deps.json      (<bytes>) — <N> deps (<production>/<development>)
+- .dw/intel/arch.md        (<lines>) — <pattern name>
+- .dw/intel/.last-refresh.json
+
+Next steps:
+- Query the index:           /dw-intel "<question>"
+- Build human-readable rules: /dw-analyze-project
+- Audit deps:                /dw-deps-audit --scan-only
+```
+
+## Critical Rules
+
+- <critical>The agent owns the schema. If the schema needs to change, update the agent file under `.agents/skills/dw-codebase-intel/` first; this command just orchestrates.</critical>
+- <critical>NEVER write `.dw/intel/` manually from this command — always via the agent.</critical>
+- <critical>Atomic writes: the agent writes to `.tmp` files and renames. If a partial write happens, the prior index is preserved.</critical>
+- Do NOT include secrets in any output. The agent's forbidden-files list (`.env*`, `*.key`, `*.pem`, `id_rsa`, etc.) is enforced; if anything leaks through, treat as a CRITICAL bug.
+
+## Error Handling
+
+- Agent fails → print stdout/stderr, mark `.dw/intel/` as last-known-good (the prior index is preserved by atomic write), exit non-zero.
+- No source files in scope → abort: `"No source files detected (TS/JS/Python/C#/Rust). Run /dw-new-project first or check the project root."`
+- `git diff --since` fails (not a git repo, bad ref) → fall back to full scan with a warning.
+- Source file referenced in existing `.dw/intel/` no longer exists → the agent removes its entry on the next partial update.
+
+## Inspired by
+
+`dw-map-codebase` is dev-workflow-native. The orchestration pattern (spawn agent, wait, verify, report) and the file-scope conventions are adapted from [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (`/gsd-map-codebase` + `gsd-intel-updater`) by gsd-build (MIT). dev-workflow specifics: writes to `.dw/intel/` (not `.planning/intel/`), uses a single agent (intel-updater) instead of multiple parallel mappers (the human-readable analysis lives separately in `/dw-analyze-project`), and integrates with `--since <gitref>` for git-aware partial updates.
+
+</system_instructions>

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

@@ -188,7 +188,7 @@ Adapt `dev:db:migrate` per chosen ORM (Prisma: `pnpm prisma migrate dev`; Alembi
 
 Per stack, append to whatever `create-*` tools already generated:
 - Add `.env` (gitignore must exclude it).
-- Add `.dw/spec/`, `.planning/` if user is also using GSD (preserved by dev-workflow conventions).
+- The `.dw/` directory is preserved across updates by `/dw-update` (rules, spec, intel are user data).
 - For `.dockerignore`: exclude `.git`, `node_modules`, `.dw`, `.agents`, `tests`, `*.md` (in prod images).
 
 #### 3.7 Generate GitHub Actions CI workflow

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

@@ -0,0 +1,144 @@
+<system_instructions>
+You are a plan verification orchestrator. Your job is to spawn the `dw-plan-checker` agent (from the `dw-execute-phase` bundled skill) to verify that a phase's `tasks.md` will achieve the PRD goal — BEFORE any code is touched.
+
+This is a standalone manual gate. `/dw-execute-phase` and `/dw-autopilot` invoke the same agent automatically; this command lets you run just the gate to inspect the plan quality without committing to execution.
+
+<critical>This command is read-only. Plan-checker NEVER modifies files.</critical>
+<critical>Output one of three verdicts: PASS, REVISE, BLOCK. No middle ground.</critical>
+
+## When to Use
+
+- Before invoking `/dw-execute-phase` if you want to inspect the plan quality first
+- After a partial execution to verify remaining tasks still make sense
+- After manual edits to `tasks.md` (always re-verify before re-executing)
+- During `/dw-create-tasks` revisions to confirm the planner addressed prior REVISE issues
+- NOT for verifying implementation correctness (use `/dw-run-qa`)
+- NOT for code-quality review (use `/dw-code-review`)
+
+## Pipeline Position
+
+**Predecessor:** `/dw-create-tasks` (or manual edits to `tasks.md`) | **Successor:** `/dw-execute-phase` if PASS; `/dw-create-tasks --revise` if REVISE; manual intervention if BLOCK
+
+## Complementary Skills
+
+| Skill | Trigger |
+|-------|---------|
+| `dw-execute-phase` | **ALWAYS** — source of `dw-plan-checker` agent and `references/plan-verification.md` |
+| `dw-codebase-intel` | Optional — agent reads `.dw/intel/` to verify plan against actual codebase facts |
+
+## Input Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{{PRD_PATH}}` | Path to the PRD folder containing `tasks.md` | `.dw/spec/prd-checkout-v2` |
+
+## File Locations
+
+- Inputs (read-only): `{{PRD_PATH}}/{prd.md, techspec.md, tasks.md, <NN>_task.md}`, `.dw/rules/*.md`, `.dw/intel/*` (if exists), `./CLAUDE.md`
+- Audit log (append-only): `.dw/audit/plan-checks-<YYYY-MM-DD>.log` (records each verdict for `--skip-check` audit trail)
+
+## Required Behavior
+
+### 1. Load context
+
+Verify the PRD path exists and contains `tasks.md`. Read `prd.md`, `techspec.md`, `tasks.md`, and any `<NN>_task.md` files referenced.
+
+### 2. Spawn the agent
+
+Spawn `dw-plan-checker` agent with:
+
+- `prd_path: {{PRD_PATH}}`
+- `required_reading:` block citing `.agents/skills/dw-execute-phase/SKILL.md` and `.agents/skills/dw-execute-phase/references/plan-verification.md`
+
+The agent runs the 6-dimension verification:
+
+1. **Requirement Coverage** — every RF-XX has a task
+2. **Task Completeness** — files / action / verification / done present
+3. **Dependency Soundness** — no cycles, no broken refs, waves ≤ 8 wide
+4. **Artifact Wiring** — every produced artifact is consumed downstream or referenced in PRD
+5. **Context Budget** — ≤ 12 tasks, ≤ 30 aggregate files
+6. **Constraint Compliance** — no violations of `.dw/rules/`, CONTEXT.md `## Decisions`, CLAUDE.md
+
+### 3. Process verdict
+
+**PASS:**
+
+- Append to `.dw/audit/plan-checks-<YYYY-MM-DD>.log`:
+  ```
+  <ISO-8601>  PASS  {{PRD_PATH}}  <task_count> tasks, <wave_count> waves
+  ```
+- Print: `Plan verification PASS — proceed to /dw-execute-phase {{PRD_PATH}}`
+
+**REVISE:**
+
+- Append to audit log with `REVISE` verdict
+- Print the issues per dimension
+- Suggest: `/dw-create-tasks --revise --issues <generated-issues-file>` OR manual edits
+- Exit status: `PLAN-CHECK-REVISE`
+
+**BLOCK:**
+
+- Append to audit log with `BLOCK` verdict
+- Print the conflicting issues with file:line
+- Suggest: resolve the locked-decision conflict (update CONTEXT.md, OR change the plan to honor it)
+- Exit status: `PLAN-CHECK-BLOCK`
+
+### 4. Output format
+
+```markdown
+# Plan Verification — <prd-slug>
+
+**Verdict:** PASS | REVISE | BLOCK
+**PRD:** {{PRD_PATH}}
+**Tasks file:** {{PRD_PATH}}/tasks.md (<N> tasks across <M> waves)
+**Verified at:** <ISO-8601>
+
+## Dimensions
+
+| # | Dimension | Status | Issues |
+|---|-----------|--------|--------|
+| 1 | Requirement Coverage | ✓ / ✗ | <count> |
+| 2 | Task Completeness | ✓ / ✗ | <count> |
+| 3 | Dependency Soundness | ✓ / ✗ | <count> |
+| 4 | Artifact Wiring | ✓ / ✗ | <count> |
+| 5 | Context Budget | ✓ / ✗ | <count> |
+| 6 | Constraint Compliance | ✓ / ✗ | <count> |
+
+## Issues (REVISE/BLOCK only)
+
+[detailed issues per dimension; cite file:line]
+
+## Recommendation
+
+- PASS → `/dw-execute-phase {{PRD_PATH}}`
+- REVISE → `/dw-create-tasks --revise` and re-run this command
+- BLOCK → resolve [list of locked-decision conflicts] then re-plan
+```
+
+## Critical Rules
+
+- <critical>The agent owns verification logic. NEVER inline checks in this command.</critical>
+- <critical>Read-only. Plan-checker MUST NOT modify any file in the project.</critical>
+- <critical>Audit log is append-only. NEVER edit prior entries.</critical>
+- <critical>BLOCK is reserved for hard conflicts (locked decisions, cycles). REVISE is for fixable issues.</critical>
+- Do NOT auto-trigger `/dw-create-tasks` on REVISE. The user decides whether to re-run.
+
+## Error Handling
+
+- `tasks.md` missing → exit `PLAN-CHECK-FAILED` with hint: "Run `/dw-create-tasks {{PRD_PATH}}` first"
+- `prd.md` missing → exit `PLAN-CHECK-FAILED`: "PRD not found; is the path correct?"
+- Agent times out (>5 min) → exit `PLAN-CHECK-TIMEOUT`: "Plan too large; consider splitting via `/dw-create-tasks --split`"
+- Cycle detected in dependencies → BLOCK with the cycle path; do NOT attempt to break it automatically
+
+## Integration With Other dw-* Commands
+
+- **`/dw-create-tasks`** — predecessor; produces the `tasks.md` this command verifies
+- **`/dw-execute-phase`** — wraps this command as a gate before execution
+- **`/dw-autopilot`** — wraps `/dw-create-tasks` → this command → `/dw-execute-phase` with hard gates between
+- **`/dw-resume`** — when resuming after a checkpoint, this command verifies the remaining tasks still satisfy the goal
+
+## Inspired by
+
+`dw-plan-checker` is dev-workflow-native. The 6-dimension goal-backward verification protocol is adapted from [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (`/gsd-plan-phase`, `gsd-plan-checker`) by gsd-build (MIT license). dev-workflow specifics: verifies `tasks.md` (not GSD's PLAN.md), uses dev-workflow's PRD/TechSpec/Tasks vocabulary, audit log for `--skip-check` trail.
+
+</system_instructions>