@brunosps00/dev-workflow 0.8.1 → 0.10.0

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

@@ -24,18 +24,20 @@ When available in the project under `./.agents/skills/`, use these skills as ana
 - `dw-review-rigor`: **ALWAYS** — applies de-duplication (same pattern in N files = 1 finding), severity ordering (critical → high → medium → low), verify-before-flag, skip-what-linter-catches, and signal-over-volume. The report's "Issues Found" table follows this discipline.
 - `dw-verify`: **ALWAYS** — invoked before emitting an `APPROVED` or `APPROVED WITH CAVEATS` verdict. Without a VERIFICATION REPORT PASS (test + lint + build), the verdict cannot be APPROVED.
 - `/dw-security-check`: **ALWAYS for TS/Python/C#/Rust projects** — invoked as step 6.7 (Security Layer) before emitting a verdict. If the project uses a supported language and `security-check.md` is missing OR has REJECTED status, the verdict is **REJECTED** — no exception.
+- `dw-simplification`: use when the diff touches dense or twisty code — applies Chesterton's Fence (understand WHY before flagging removal), behavior-preserving refactor protocol (test gate before/after), and complexity metrics (cyclomatic, cognitive, depth, fan-out) so that "simplify this" findings are concrete, not vibes-based.
 - `security-review`: use when auth, authorization, external input, upload, SQL, external integration, secrets, SSRF, XSS, or sensitive surfaces are present
 - `vercel-react-best-practices`: use when the diff touches React/Next.js to review rendering, fetching, bundle, hydration, and performance patterns
 
 ## Codebase Intelligence
 
-<critical>If `.planning/intel/` exists, querying it is MANDATORY before writing requirements. Do NOT skip this step.</critical>
-- Internally run: `/gsd-intel "documented conventions, anti-patterns, and decision spaces"`
+<critical>If `.dw/intel/` exists, querying it via `/dw-intel` is MANDATORY before reviewing. Do NOT skip this step.</critical>
+- Internally run: `/dw-intel "documented conventions and anti-patterns"`
 - Prioritize findings that violate documented conventions
-- Check if questionable architectural decisions are intentional (documented as decision spaces)
+- Check if questionable architectural decisions are intentional (documented in `.dw/rules/`)
 
-If `.planning/intel/` does NOT exist:
-- Use `.dw/rules/` as context (current behavior)
+If `.dw/intel/` does NOT exist:
+- Use `.dw/rules/` as context, falling back to grep
+- Suggest running `/dw-map-codebase` after the review for richer downstream context
 
 ## Input Variables
 

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

@@ -9,6 +9,12 @@
     ## Pipeline Position
     **Predecessor:** `/dw-run-task` or `/dw-bugfix` | **Successor:** `/dw-generate-pr`
 
+    ## Complementary Skills
+
+    When available in the project under `./.agents/skills/`, use these skills as operational support without replacing this command:
+
+    - `dw-git-discipline`: **ALWAYS** — enforces atomic commits (one logical intent per commit; refactor separate from feature), Conventional Commits format, lint+tests+build green BEFORE the commit, and bans bypassing pre-commit hooks (`--no-verify`) or amending pushed commits. When mixed changes are detected, splits via `git add -p`.
+
     ## Input Variables
 
     | Variable | Description | Example |

package/scaffold/en/commands/dw-create-prd.md

@@ -42,12 +42,13 @@
 
     ## Codebase Intelligence
 
-    <critical>If `.planning/intel/` exists, querying it is MANDATORY before writing requirements. Do NOT skip this step.</critical>
-    - Internally run: `/gsd-intel "existing features in the [PRD topic] domain"`
+    <critical>If `.dw/intel/` exists, querying it via `/dw-intel` is MANDATORY before writing requirements. Do NOT skip this step.</critical>
+    - Internally run: `/dw-intel "existing features in the [PRD topic] domain"`
     - Use findings to avoid duplicating existing functionality and reference established patterns
 
-    If `.planning/intel/` does NOT exist:
-    - Use `.dw/rules/` as context (current behavior)
+    If `.dw/intel/` does NOT exist:
+    - Use `.dw/rules/` as context, falling back to grep
+    - Suggest running `/dw-map-codebase` for richer downstream context
 
     ## Multi-Project Features
 

package/scaffold/en/commands/dw-create-techspec.md

@@ -23,18 +23,21 @@
     When available in the project under `./.agents/skills/`, use these skills as support:
 
     - `dw-council` (opt-in via `--council`): multi-advisor debate on the primary architectural decision with steel-manning. **DO NOT invoke by default**.
+    - `dw-source-grounding` (**ALWAYS**): every framework/library decision must follow Detect → Fetch → Implement → Cite. The techspec emits inline citations `[source: <url>, version: X.Y, retrieved: YYYY-MM-DD]` next to each architectural decision.
     - `vercel-react-best-practices`: use when defining frontend architecture for React/Next.js projects
     - `ui-ux-pro-max`: use when defining design system decisions, color palettes, typography, and UI style for the TechSpec
     - `security-review`: use when the feature touches auth, authorization, or sensitive data handling
 
     ## Codebase Intelligence
 
-    <critical>If `.planning/intel/` exists, querying it is MANDATORY before writing requirements. Do NOT skip this step.</critical>
-    - Internally run: `/gsd-intel "architectural patterns and technical decisions in the project"`
+    <critical>If `.dw/intel/` exists, querying it via `/dw-intel` is MANDATORY before writing the techspec. Do NOT skip this step.</critical>
+    - Internally run: `/dw-intel "architectural patterns and technical decisions in the project"`
     - Align proposals with existing patterns; flag deviations explicitly
+    - When the techspec defines API endpoints, ALSO consult `dw-codebase-intel/references/api-design-discipline.md` (Hyrum's Law, contract-first, error semantics, boundary validation, versioning) — the new endpoint must match conventions surfaced in `apis.json`, not impose external "best practices" that conflict with existing patterns.
 
-    If `.planning/intel/` does NOT exist:
-    - Use `.dw/rules/` as context (current behavior)
+    If `.dw/intel/` does NOT exist:
+    - Use `.dw/rules/` as context, falling back to grep
+    - Suggest running `/dw-map-codebase` to enrich downstream context
 
     ## Multi-Project Decision Flowchart
 

package/scaffold/en/commands/dw-deep-research.md

@@ -13,6 +13,12 @@ You are an AI assistant specialized in conducting enterprise-grade research with
 <critical>Bibliography must be COMPLETE -- every citation, no placeholders, no ranges</critical>
 <critical>Operate independently -- infer assumptions from context, only stop for critical errors</critical>
 
+## Complementary Skills
+
+| Skill | Trigger |
+|-------|---------|
+| `dw-source-grounding` | **ALWAYS** — applies the Detect → Fetch → Implement → Cite protocol with the strict source-priority hierarchy (official versioned docs > changelogs > web standards > compatibility tables; Stack Overflow / blogs / training data are discovery only). Each finding ends with `[source: <url>, version: X.Y, retrieved: YYYY-MM-DD]`; the bibliography is built from these citations. |
+
 ## Input Variables
 
 | Variable | Description | Example |

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

@@ -29,6 +29,7 @@ This command is **distinct** from `/dw-security-check`:
 | `dw-verify` | **ALWAYS** — every phase emits a VERIFICATION REPORT (commands run, exit codes, artifacts) before the next phase starts |
 | `dw-review-rigor` | **ALWAYS** — applies de-duplication (same advisory across N packages = 1 finding with affected list), severity ordering, and signal-over-volume on the OUTDATED-MINOR list |
 | `security-review` (`references/supply-chain.md`) | **ALWAYS** when classifying findings — gives OWASP A06 (Vulnerable & Outdated Components) framing for the brainstorm trade-offs |
+| `dw-source-grounding` | **ALWAYS** in the brainstorm phase — each per-package update option (Conservative/Balanced/Bold) cites the official changelog/release notes for the target version: `[source: <url>, version: X.Y, retrieved: YYYY-MM-DD]`. Catches "agent recommends v5 because it sounds modern, but v5 dropped Node 18 support" errors. |
 | `dw-council` | Auto opt-in when ≥3 packages land in tier COMPROMISED — multi-advisor stress-test on remediation order and scope |
 | `webapp-testing` | Optional — when the project is frontend and the scoped test phase needs Playwright-aware test selection |
 

package/scaffold/en/commands/dw-find-skills.md

@@ -15,7 +15,7 @@ You are an agent skills discovery helper for this workspace. Your job is to help
 
 ## Pipeline Position
 
-**Predecessor:** any exploratory question | **Successor:** none (independent flow). If no skill is found, fall back to `/dw-brainstorm` (idea exploration) or `/dw-quick` (small one-off task) when applicable.
+**Predecessor:** any exploratory question | **Successor:** none (independent flow). If no skill is found, fall back to `/dw-brainstorm` (idea exploration) or `/dw-run-task` (small one-off task) when applicable.
 
 ## Complementary Skills
 
@@ -81,7 +81,7 @@ Browse skills at: https://skills.sh/
    - Acknowledge no match was found, no fabrication
    - Offer to help directly with general capabilities
    - Suggest `/dw-brainstorm` if the user wants to explore options before building it themselves
-   - Suggest `/dw-quick` if the request fits a small one-off change (≤ 3 files, no PRD)
+   - Suggest `/dw-run-task` if the request fits a small one-off change (≤ 3 files, no PRD)
    - Mention `npx skills init <name>` as a path to author the missing skill
 
 ## Common Skill Categories
@@ -128,7 +128,7 @@ I searched for skills related to "<query>" and didn't find a strong match
 
 I can still help directly with general capabilities. Or:
   /dw-brainstorm "<your idea>"   — if you want to explore approaches first
-  /dw-quick "<small change>"     — if it's a tiny change that fits one task
+  /dw-run-task "<small change>"  — if it's a tiny change that fits one task (write quick PRD first)
   npx skills init <name>         — if this would be valuable as a reusable skill
 ```
 
@@ -150,7 +150,7 @@ I can still help directly with general capabilities. Or:
 `dw-find-skills` ports the `find-skills` skill (from the Claude superpowers bundle, `~/.agents/skills/find-skills/SKILL.md`) into a `dw-*` workflow command so every supported platform (Claude Code, Codex, Copilot, OpenCode) gets the same discovery on-ramp. Adaptations for dev-workflow:
 
 - Pipeline integration: `/dw-help <keyword>` routes here when the keyword matches `skill`/`find skill`/`install skill`/`extend agent`.
-- Fallback to `/dw-brainstorm` or `/dw-quick` when no skill matches — keeps the user inside the workflow instead of dumping them empty-handed.
+- Fallback to `/dw-brainstorm` or `/dw-run-task` when no skill matches — keeps the user inside the workflow instead of dumping them empty-handed.
 - Explicit scope question (`-g` vs local) before installing, instead of always installing globally.
 
 Credit: the `find-skills` skill from the Claude superpowers ecosystem and the `npx skills` / [skills.sh](https://skills.sh/) project.

package/scaffold/en/commands/dw-fix-qa.md

@@ -18,6 +18,7 @@ You are an AI assistant specialized in post-QA bug fixing with evidence-driven r
 
 When available in the project under `./.agents/skills/`, use these skills as operational support without replacing this command:
 
+- `dw-debug-protocol`: **ALWAYS** — every bug-shaped finding (failing scenario, not missing feature) flows through the six-step triage. The retest evidence is the step-6 verification artifact; the regression test added in step 5 is what allows `Fixed` status to stick.
 - `dw-verify`: **ALWAYS** — invoked before marking any bug as `Fixed` or `Closed` in `QA/bugs.md`. Without a VERIFICATION REPORT PASS (test + lint + build) **and** retest evidence (screenshot in UI mode OR JSONL log line in API mode), status stays `Reopened` or `Under review`.
 - `webapp-testing`: (UI mode) support for structuring retests, captures, and scripts when complementary to Playwright MCP
 - `vercel-react-best-practices`: (UI mode) use only if the fix affects React/Next.js frontend and there is risk of rendering, hydration, fetching, or performance regression

package/scaffold/en/commands/dw-generate-pr.md

@@ -14,6 +14,7 @@ You are an assistant specialized in creating well-documented Pull Requests. Your
 | Skill | Trigger |
 |-------|---------|
 | `dw-verify` | **ALWAYS** — invoked before `git push`. Without a VERIFICATION REPORT PASS in the current session AFTER the last code edit, the PR **CANNOT** be created. |
+| `dw-git-discipline` | **ALWAYS** — validates branch naming (`<type>/<scope>` kebab-case), atomic-commit history (each commit single-intent, conventional message), branch lifetime (flag if >7 days old), and PR scope (suggest split if diff > ~400 lines). PR description follows summary + test plan structure, not a `git log` dump. |
 | `/dw-security-check` | **ALWAYS for TS/Python/C#/Rust projects** — `security-check.md` with status ≠ REJECTED is required for supported-language projects. |
 
 <critical>Hard gate 1 (verify): if the current session has no VERIFICATION REPORT PASS from `dw-verify` produced AFTER the last edit/commit, STOP and invoke `dw-verify` before proceeding. A PR is a permanent artifact — it demands the highest verification standard.</critical>

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

@@ -23,7 +23,6 @@ You are a workspace help assistant. When invoked, present the user with a comple
 | 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 |
-| decision, adr, architecture | `/dw-adr` | Record an Architecture Decision Record |
 | 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. |
@@ -32,8 +31,6 @@ You are a workspace help assistant. When invoked, present the user with a comple
 | 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 |
-| hotfix, quick change | `/dw-quick` | One-off task with guarantees, no PRD |
-| resume, where I left off | `/dw-resume` | Restore previous session context |
 | 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 |
@@ -127,9 +124,6 @@ This workspace uses an AI command system that automates the full development cyc
 | `/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-quick` | Execute a one-off task with workflow guarantees without PRD | Change description | Code + commit |
-| `/dw-resume` | Restore session context and suggest next step | (none) | Summary + suggestion |
-| `/dw-intel` | Query codebase intelligence about patterns and architecture | Question | Answer with sources |
 | `/dw-autopilot` | Full pipeline orchestrator: from a wish to a PR with minimal intervention | Wish description | PRD + code + commits + PR |
 
 ### Research
@@ -165,11 +159,15 @@ This workspace uses an AI command system that automates the full development cyc
 | `/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` |
 
-### Architectural Decisions
+### Internal commands (used by other dw-* commands; rarely invoked directly)
 
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/dw-adr` | Record an Architecture Decision Record (ADR) for a non-trivial decision during a PRD | PRD path + title | `.dw/spec/<prd>/adrs/adr-NNN.md` + cross-refs updated |
+| 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
 
@@ -290,16 +288,6 @@ LEVEL 3 - Formal Code Review (/dw-code-review)
 /dw-autopilot "description of what you want to build"  # Research → PRD → Tasks → Code → QA → PR
 ```
 
-### Quick Task
-```bash
-/dw-quick "change description"                     # Implement + validate + commit
-```
-
-### Resume Session
-```bash
-/dw-resume                                         # Restore context + suggest next step
-```
-
 ### Query Codebase
 ```bash
 /dw-intel "how does X work in this project?"       # Answer with sources
@@ -331,9 +319,7 @@ your-project/
 │   │   ├── dw-autopilot.md
 │   │   ├── dw-deep-research.md
 │   │   ├── dw-intel.md
-│   │   ├── dw-quick.md
 │   │   ├── dw-redesign-ui.md
-│   │   ├── dw-resume.md
 │   │   ├── dw-bugfix.md
 │   │   ├── dw-commit.md
 │   │   ├── dw-functional-doc.md
@@ -396,11 +382,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: 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.
+**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: 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.

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`)
+- Do NOT use to implement changes (use `/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-redesign-ui.md

@@ -64,17 +64,13 @@ Use diagnostic tools based on the project's framework:
 7. **VALIDATE**: capture after-state in BOTH resolutions (mobile and desktop), compare before/after, verify accessibility (WCAG 2.2 via `ui-ux-pro-max`), run react-doctor `--diff` if React. If `webapp-testing` is available, capture screenshots at 375px viewport (mobile) and 1440px viewport (desktop).
 8. **PERSIST CONTRACT**: if the user approved a direction, generate `design-contract.md` in the PRD directory (`.dw/spec/prd-[name]/design-contract.md`) with: approved direction, color palette, typography pairing, layout rules, accessibility rules, and component rules. This contract will be read by `dw-run-task` and `dw-run-plan` to ensure visual consistency.
 
-## GSD Integration
+## Codebase Intelligence
 
-<critical>When GSD is installed, registering the design contract in .planning/ and querying .planning/intel/ are MANDATORY.</critical>
+<critical>If `.dw/intel/` exists, querying it via `/dw-intel` is MANDATORY in the audit phase to surface existing UI patterns.</critical>
 
-If GSD (get-shit-done-cc) is installed in the project:
-- After generating the design contract, register in `.planning/` for cross-session persistence
-- Query `.planning/intel/` in the audit phase for existing UI patterns
-
-If GSD is NOT installed:
-- The design contract works normally (file-based in `.dw/spec/`)
-- Audit uses only `.dw/rules/` for context
+- Audit phase: internally run `/dw-intel "UI components, design patterns, layout conventions"` before proposing redesign directions
+- The design contract (`.dw/spec/prd-[name]/design-contract.md`) is the single source of truth for visual consistency — it's read by `/dw-run-task` and `/dw-run-plan` and persists across sessions naturally (no separate registration needed)
+- If `.dw/intel/` does NOT exist, fall back to `.dw/rules/` and direct grep over `apps/web/src/` (or equivalent frontend root)
 
 ## Preferred Response Format
 

package/scaffold/en/commands/dw-refactoring-analysis.md

@@ -21,8 +21,9 @@ Prerequisite: Run `/dw-analyze-project` first to understand project patterns and
 When available in the project under `./.agents/skills/`, use these skills as analytical support without replacing this command:
 
 - `dw-review-rigor`: **ALWAYS** — when cataloging code smells, apply de-duplication (same smell in N files = 1 entry with affected list), severity ordering across P0-P3, signal-over-volume (max ~20 findings; keep criticals, prune marginal ones). A smell with a justifying ADR drops to `low` at most.
+- `dw-simplification`: **ALWAYS** — every flagged smell is filtered through Chesterton's Fence (what does the construct DO, why was it added, what breaks if removed). Smells with no clear "why-was-it-there" answer get downgraded to `info` and a research note instead of a refactor proposal. Complexity metrics back the severity (cognitive complexity ≥16 or nesting depth ≥4 = `high` candidate; <10 = `low` at most).
 - `security-review`: defer security concerns to this skill — do not duplicate
-- `vercel-react-best-practices`: defer React/Next.js performance patterns to this skill
+- `vercel-react-best-practices`: defer React/Next.js performance patterns to this skill — when flagging perf-related smells, follow its `references/perf-discipline.md` (measure → identify → fix → verify → guard) and cite the metric + tool, not vibes
 
 ## Analysis Tools
 
@@ -31,13 +32,14 @@ For Angular projects, use `ng lint` as an analytical complement.
 
 ## Codebase Intelligence
 
-<critical>If `.planning/intel/` exists, querying it is MANDATORY before writing requirements. Do NOT skip this step.</critical>
-- Internally run: `/gsd-intel "tech debt, decision spaces, and known technical debt"`
-- Contextualize findings with already documented decisions
+<critical>If `.dw/intel/` exists, querying it via `/dw-intel` is MANDATORY before flagging refactoring opportunities. Do NOT skip this step.</critical>
+- Internally run: `/dw-intel "tech debt and known technical decisions"`
+- Contextualize findings with documented decisions in `.dw/rules/`
 - Avoid flagging as a smell something that is an intentional recorded decision
 
-If `.planning/intel/` does NOT exist:
-- Use `.dw/rules/` as context (current behavior)
+If `.dw/intel/` does NOT exist:
+- Use `.dw/rules/` as context, falling back to grep
+- Suggest running `/dw-map-codebase` to enrich downstream context
 
 ## Input Variables