@brunosps00/dev-workflow 0.9.0 → 0.11.0

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

@@ -23,6 +23,7 @@
     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
@@ -32,11 +33,29 @@
     <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 `.dw/intel/` does NOT exist:
     - Use `.dw/rules/` as context, falling back to grep
     - Suggest running `/dw-map-codebase` to enrich downstream context
 
+    ## Constitution Gate
+
+    <critical>BEFORE drafting architectural decisions, check `.dw/constitution.md`:
+
+    **If MISSING**: copy `templates/constitution-template.md` (project-local at `.dw/templates/constitution-template.md`, falling back to bundled scaffold) verbatim to `.dw/constitution.md`. Set frontmatter `mode: defaults`. Print in chat: "Installed defaults constitution at `.dw/constitution.md` (severity: info — won't block this techspec). Continuing." Then proceed.
+
+    **If PRESENT**: read it. Every framework / library / architectural choice in the techspec MUST carry one of:
+    - `Respects: P-NNN` — the decision actively honors the named principle(s).
+    - `Deviates: P-NNN — justification: <ADR slug or one-line rationale>` — the decision intentionally departs from the principle.
+
+    **Severity-graded gate:**
+    - Deviation from a `severity: info` principle → record only, never blocks.
+    - Deviation from a `severity: high` principle without a linked ADR (`.dw/spec/<prd>/adrs/adr-NNN.md`) → BLOCK the techspec. Instruct the user to either revise the decision OR create an ADR via `/dw-adr` documenting the trade-off.
+    - Deviation from a `severity: critical` principle → BLOCK the techspec with the same ADR requirement, additionally requiring reviewer acknowledgment captured in the ADR's `Approved by` field.
+
+    No exceptions for `high`/`critical` without an ADR. If the user pushes back, point them to `/dw-adr` — that's the escape hatch by design.</critical>
+
     ## Multi-Project Decision Flowchart
 
     ```dot

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,20 +23,14 @@ 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. |
 | 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 |
-| 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 |
@@ -130,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
@@ -168,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
 
@@ -293,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
@@ -334,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
@@ -400,10 +383,7 @@ Commands work across multiple AI tools, all pointing to the same source `.dw/com
 - 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: 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.
+- 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

@@ -10,7 +10,7 @@ You are a codebase intelligence assistant. This command answers questions about
 - 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
 

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
 

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

@@ -318,6 +318,32 @@ git diff <commit> -- path/to/file
 
 <critical>DO NOT APPROVE requirements without concrete evidence in the code</critical>
 <critical>ANALYZE the actual code, do not trust only the checkboxes in tasks.md</critical>
-<critical>If 100% of requirements were implemented and there are NO gaps: DO NOT enter plan mode, DO NOT create tasks, DO NOT dispatch agents. Just present the report and END.</critical>
-<critical>If gaps are found, enter the fix-review loop automatically. Do NOT wait for user instructions to fix gaps. Maximum 3 cycles before marking as BLOCKED.</critical>
+<critical>If 100% of requirements were implemented and there are NO gaps: DO NOT enter plan mode, DO NOT create tasks, DO NOT dispatch agents. Just present the Level 2 report, then proceed to Level 3 (next section).</critical>
+<critical>If gaps are found, enter the fix-review loop automatically. Do NOT wait for user instructions to fix gaps. Maximum 3 cycles before marking as BLOCKED. Level 3 only runs after the loop reaches APPROVED on Level 2.</critical>
+
+## Level 3 — Quality Layer (auto-invoked at the end)
+
+After Level 2 (PRD coverage) reaches APPROVED, **automatically invoke `/dw-code-review`** to add the formal quality layer (best practices, SOLID, DRY, complexity, security, conventions). Addresses the user expectation that a single review covers both "did we deliver everything?" (Level 2) and "is what we delivered well-built?" (Level 3).
+
+Pipeline:
+
+1. After Level 2 APPROVED, run `/dw-code-review {{PRD_PATH}}` with the same PRD scope.
+2. Wait for `/dw-code-review` to produce its verdict (APPROVED / APPROVED WITH CAVEATS / REJECTED).
+3. Write a consolidated summary at `{{PRD_PATH}}/QA/review-consolidated.md` referencing both:
+   - Level 2: `{{PRD_PATH}}/QA/review-coverage.md` (PRD compliance map)
+   - Level 3: `{{PRD_PATH}}/QA/dw-code-review.md` (formal review)
+4. Final status combines both verdicts:
+   - Level 2 APPROVED + Level 3 APPROVED → consolidated APPROVED
+   - Level 2 APPROVED + Level 3 APPROVED WITH CAVEATS → consolidated APPROVED WITH CAVEATS
+   - Level 2 APPROVED + Level 3 REJECTED → consolidated REJECTED (Level 3 wins)
+   - Level 2 REJECTED → never reaches Level 3 (loop fixes coverage first)
+
+### Flag to skip Level 3
+
+If the user runs `/dw-review-implementation --no-code-review`, skip Level 3 and emit only the Level 2 report. Use case: re-running coverage after a small targeted gap fix when a full Level 3 sweep was just done.
+
+### Why this auto-chain exists
+
+`dw-review-implementation` historically returned only Level 2 (coverage). Users expected a single review to also cover quality. Splitting the natural intent into two separate commands created friction. The auto-chain restores the natural "review the implementation" semantics: cover + quality, by default, in one invocation. Standalone `/dw-code-review` remains available for cases where only Level 3 is wanted (e.g., reviewing a cherry-picked refactor branch with no PRD).
+
 </system_instructions>

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

@@ -165,7 +165,7 @@ If a task FAILS during execution:
 
 ### Plan Verification (Pre-Execution)
 
-Before starting execution, delegate to `/dw-plan-checker {{PRD_PATH}}`:
+Before starting execution, spawn the **plan-checker agent** from `.agents/skills/dw-execute-phase/agents/plan-checker.md`:
 - The plan-checker agent verifies the 6 dimensions (requirement coverage, task completeness, dependency soundness, artifact wiring, context budget, constraint compliance)
 - If REVISE: present issues found and suggest fixes. Maximum 3 correction cycles via `/dw-create-tasks --revise`
 - If BLOCK: surface conflict to user, do NOT auto-replan
@@ -173,7 +173,7 @@ Before starting execution, delegate to `/dw-plan-checker {{PRD_PATH}}`:
 
 ### Parallel Execution (Wave-Based)
 
-After plan-checker PASS, delegate to `/dw-execute-phase {{PRD_PATH}}`:
+After plan-checker PASS, spawn the **executor agent** from `.agents/skills/dw-execute-phase/agents/executor.md`:
 - The executor agent analyzes each task's `Depends on:` field to build the dependency graph
 - Groups tasks into waves:
   - Wave 1: tasks with no dependencies (run in parallel)

package/scaffold/en/templates/constitution-template.md

@@ -0,0 +1,111 @@
+---
+schema_version: "1.0"
+generated_by: dev-workflow
+last_updated: YYYY-MM-DD
+mode: defaults | custom
+---
+
+# Project Constitution
+
+> Declarative principles this team has chosen to follow. PRDs, TechSpecs, and Code Reviews read this file as a hard gate. Anything that violates a principle with `severity: critical` or `high` is blocked unless explicitly justified by an ADR.
+
+## How this file works
+
+- **Each principle has an ID (`P-NNN`), a severity, a rule, a `Why`, and an `Enforcement`.**
+- **Severity ladder:** `info` (reports only, never blocks) → `high` (blocks PR without ADR) → `critical` (blocks PR without ADR, requires reviewer sign-off).
+- **Edit freely.** This file is yours to evolve. Promote principles from `info` to `high` once you trust the project enforces them.
+- **ADR escape hatch.** A PR that violates a `high`/`critical` principle is unblocked only when an ADR in the same feature documents the deviation and trade-off.
+- **Regenerate analytical version** anytime via `/dw-analyze-project` (offers to synthesize principles from observed code patterns).
+
+---
+
+## Code Quality
+
+**P-001 — No `any` / `unknown` casts in TypeScript without justification** (severity: info)
+**Rule:** Production code must not use `as any`, `as unknown`, or `// @ts-ignore` without an inline `// @ts-ignore — reason: <X>` comment naming the constraint.
+**Why:** Silent type escapes leak runtime bugs that the type system was meant to catch. Each escape is a contract the type system stops enforcing.
+**Enforcement:** `dw-code-review` greps the diff for `as any`/`@ts-ignore`/`@ts-expect-error` without an accompanying reason comment.
+
+**P-002 — Functions must be testable in isolation** (severity: info)
+**Rule:** A function that touches network, filesystem, database, or system clock must accept its dependency as a parameter (or via a factory) instead of importing it directly.
+**Why:** Code that constructs its own dependencies cannot be tested without integration setup. Tests slow down, get skipped, and bugs ship.
+**Enforcement:** `dw-code-review` flags functions importing `fs`, `axios`, `prisma`, `Date.now`, etc., directly inside business logic modules.
+
+---
+
+## Testing Standards
+
+**P-003 — Every bug fix ships with a regression test** (severity: info)
+**Rule:** A commit with type `fix:` must add or modify at least one test that would have caught the bug before the fix.
+**Why:** Without the test, the bug returns the next time someone refactors the area. The fix decays.
+**Enforcement:** `dw-code-review` checks that `fix:` commits include diff under `**/*test*` or `**/*spec*` paths.
+
+**P-004 — Tests must be deterministic** (severity: info)
+**Rule:** No sleep-based waits, no real-clock comparisons, no network calls to live services in unit tests. Mock at boundaries.
+**Why:** Flaky tests train the team to ignore failures. The next real failure goes unnoticed.
+**Enforcement:** `dw-code-review` greps tests for `setTimeout`, real fetch/axios calls, and `Date.now()` without `vi.useFakeTimers()`/`jest.useFakeTimers()`.
+
+---
+
+## UX Consistency
+
+**P-005 — User-facing strings live in a single source** (severity: info)
+**Rule:** All visible copy (labels, error messages, empty states) goes through a centralized i18n / strings module — not inline in components.
+**Why:** Inline strings drift in tone, break i18n efforts, and cause duplicate-but-different copies of the same message.
+**Enforcement:** `dw-code-review` flags JSX text nodes and error messages declared inside components instead of imported from `src/strings/`, `src/i18n/`, or equivalent.
+
+**P-006 — Loading + empty + error states are mandatory for any data-fetching UI** (severity: info)
+**Rule:** Any component or page that fetches data must explicitly render loading, empty, and error states — not just the happy path.
+**Why:** "Just the spinner" experiences and silent error states are the #1 source of user-reported bugs.
+**Enforcement:** `dw-review-implementation` checks data-fetching components for all three states in JSX or equivalent.
+
+---
+
+## Performance
+
+**P-007 — Performance changes must cite a measurement** (severity: info)
+**Rule:** Any commit that claims to improve performance must include the metric, the tool, and the before/after numbers in the commit body OR in the techspec.
+**Why:** Without measurement, "performance" optimization is guesswork — and usually wrong (see `dw-simplification` + `perf-discipline.md`).
+**Enforcement:** `dw-code-review` checks `perf:` commits for a numeric before/after; flags if missing.
+
+**P-008 — N+1 queries are flagged at code review** (severity: info)
+**Rule:** Loops or list operations that issue per-item database/HTTP calls must batch (e.g., `IN (...)`, `findMany`, DataLoader) or be explicitly justified.
+**Why:** N+1 patterns scale linearly with data size and silently degrade until production load reveals them.
+**Enforcement:** `dw-code-review` and `dw-refactoring-analysis` detect await-in-loop patterns against repository / API client modules.
+
+---
+
+## Security
+
+**P-009 — Server-side authorization on every state-changing endpoint** (severity: info)
+**Rule:** Any endpoint that creates, updates, or deletes data must verify caller authorization on the server. UI-level gating (hidden buttons, disabled forms) is not security.
+**Why:** Browsers are untrusted (see `webapp-testing/security-boundary.md`). UI gating is convenience; only server checks protect data.
+**Enforcement:** `dw-code-review` and `dw-security-check` require an explicit auth check (decorator, middleware, or in-handler assertion) on POST/PUT/PATCH/DELETE routes.
+
+**P-010 — Secrets never enter the repository** (severity: info)
+**Rule:** No API keys, passwords, signing keys, tokens, or production endpoints checked into source. `.env.example` documents shape only.
+**Why:** Repository history is permanent. A secret committed once is leaked even if reverted next commit.
+**Enforcement:** `dw-security-check` runs Trivy + secret scanners on the diff.
+
+---
+
+## Custom Principles
+
+> Add your team's specific principles below. Follow the same format: `**P-NNN — <name>** (severity: info|high|critical): <rule>. **Why:** <reason>. **Enforcement:** <how>.`
+
+<!-- Example:
+**P-100 — All financial calculations use Decimal, never Number** (severity: critical)
+**Rule:** Money values must use `Decimal` / `BigDecimal` types end-to-end. No `parseFloat`, no `Number` arithmetic.
+**Why:** IEEE 754 rounding errors accumulate to cents lost over millions of transactions; audited environments mandate exact arithmetic.
+**Enforcement:** `dw-code-review` greps for `Number(`/`parseFloat(` in any file under `src/billing/`, `src/payments/`, `src/finance/`.
+-->
+
+---
+
+## How to evolve this file
+
+1. **Live in `info` for at least one release.** Watch how often each principle is violated organically; the data tells you if it's worth promoting.
+2. **Promote to `high` once violations are rare and the team agrees.** PRs that violate a `high` principle now need an ADR.
+3. **Promote to `critical` for principles that protect users / data / compliance.** Treat these as load-bearing; the ADR escape requires reviewer sign-off, not just author opt-out.
+4. **Demote or remove principles that don't earn their weight.** A constitution is a tool, not a museum.
+5. **Re-run `/dw-analyze-project`** when the codebase shifts substantially (new stack, major refactor); it can propose updates grounded in fresh observation.

package/scaffold/en/templates/idea-onepager.md

@@ -86,5 +86,5 @@ Ideally 2-4 stories. If it's more than 5, it's probably not MVP.]
 Pick ONE:
 
 - **`/dw-create-prd`** using this one-pager as input — when the direction is clear but we need to detail user stories, acceptance criteria, and hand off to techspec
-- **`/dw-quick`** — when it's an IMPROVES so small that it fits in a single task (up to 3 files, no new endpoint/screen)
+- **`/dw-run-task`** — when it's an IMPROVES so small that it fits in a single task (up to 3 files, no new endpoint/screen) — write a quick PRD first
 - **Stop here** — if any "Open Question" is blocking, stop and resolve with the stakeholder before advancing

package/scaffold/pt-br/commands/dw-analyze-project.md

@@ -645,6 +645,67 @@ packages/auth → packages/db
 - Crie o diretório .dw/rules/ se não existir
 </critical>
 
+### Step 8: Constitution Generation (Opcional, mas Recomendado)
+
+Após escrever `.dw/rules/`, oferecer gerar `.dw/constitution.md` — os princípios declarativos que o time quer ver enforçados em PRDs, TechSpecs e Code Reviews.
+
+**Diferença vs `.dw/rules/`:**
+- `.dw/rules/` é **analítico** — o que o código É (padrões observados, anti-patterns, convenções).
+- `.dw/constitution.md` é **declarativo** — o que o código DEVE SER (regras às quais o time se compromete).
+
+**Comportamento:**
+
+Se `.dw/constitution.md` já existir, imprimir "Constituição já existe em `.dw/constitution.md` — pulando (edite manualmente se quiser atualizar)" e encerrar.
+
+Caso contrário, apresentar 3 opções no chat (use a UI de pergunta preferida quando disponível; caso contrário texto puro):
+
+```
+Uma constitution ajudaria PRDs/TechSpecs/PRs a permanecerem alinhados aos padrões.
+Três opções:
+
+  A) Sintetizar dos padrões observados (recomendado)
+     Leio `.dw/rules/` e proponho 5–8 princípios fundamentados no código real,
+     cada um com `Why:` ligado a evidência e `severity: info` (não bloqueia).
+     Você revisa e aprova antes de qualquer escrita.
+
+  B) Instalar template de defaults
+     Copia `templates/constitution-template.md` para `.dw/constitution.md` com
+     5 princípios canônicos (Qualidade, Testes, UX, Performance, Segurança)
+     pré-preenchidos em `severity: info`. Você customiza manualmente.
+
+  C) Pular
+     Sem constitution. Comandos downstream operam sem o gate.
+     Você pode rodar este step novamente re-executando `/dw-analyze-project`.
+```
+
+**Opção A — Sintetizar:**
+
+1. Ler `.dw/rules/index.md` + cada `.dw/rules/{module}.md`.
+2. Propor 5–8 princípios. Cada um deve:
+   - Ter ID único `P-NNN`.
+   - Mapear para uma observação em `.dw/rules/` (citar o arquivo + seção).
+   - Começar em `severity: info` (nunca propor `high`/`critical` automaticamente — isso é decisão do time).
+   - Seguir formato: `**P-NNN — <nome>** (severity: info): <regra>. **Why:** <fundamentar em evidência>. **Enforcement:** <como checar>.`
+3. **Mostrar os princípios propostos no chat como lista markdown** (não escreva o arquivo ainda). Incluir a citação de evidência para cada um.
+4. Perguntar: "Edita algum antes de eu gravar? Responda com os IDs para descartar/editar, ou 'aprovar' para escrever como está."
+5. Após aprovação (com edits aplicados), gravar em `.dw/constitution.md` usando a mesma estrutura de `templates/constitution-template.md`.
+6. Setar frontmatter `mode: custom` e `last_updated: <data ISO de hoje>`.
+
+**Opção B — Defaults:**
+
+1. Localizar `templates/constitution-template.md` (projeto-local em `.dw/templates/constitution-template.md`, com fallback para scaffold bundled).
+2. Copiar para `.dw/constitution.md` literalmente. Setar frontmatter `mode: defaults`.
+3. Imprimir: "Constituição defaults instalada em `.dw/constitution.md`. Todos os 10 princípios começam em `severity: info` — reportam mas não bloqueiam. Edite o arquivo para customizar, depois promova severities para `high`/`critical` quando confiar."
+
+**Opção C — Pular:**
+
+1. Nada a fazer.
+2. Imprimir: "Pulado. PRD/TechSpec/CodeReview rodarão sem o constitution gate. Re-rode `/dw-analyze-project` mais tarde se quiser habilitar."
+
+**Em qualquer opção:**
+- Nunca escrever `.dw/constitution.md` sem aprovação explícita (opção A) ou escolha explícita (opções B/C).
+- Constitution é commitada ao repositório como qualquer outro artefato do projeto — nunca gitignored.
+
 ## Checklist de Qualidade
 
 - [ ] Estrutura do repositório escaneada

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

@@ -26,7 +26,7 @@ Uma etapa que invoca um comando `/dw-xxx` SO e considerada completa quando os ar
 ## Quando Usar
 - Use quando quiser ir de uma ideia ate um PR com minima intervencao manual
 - Use para features completas que passam por todo o pipeline (pesquisa, planejamento, execucao, qualidade)
-- NAO use para mudancas pontuais (use `/dw-quick`)
+- NAO use para tasks pequenas e bem-escopadas — use `/dw-run-task` direto com um PRD curto
 - NAO use para corrigir bugs (use `/dw-bugfix`)
 - NAO use quando quiser controle manual entre cada fase (use os comandos individuais)
 
@@ -56,7 +56,7 @@ O autopilot para APENAS nestes 3 momentos:
 
 ## Retomada de Sessao
 
-Se este comando for invocado para retomar um autopilot interrompido (via `/dw-resume`):
+Se este comando for re-invocado no mesmo PRD apos interrupcao:
 
 <critical>Leia o arquivo `autopilot-state.json` no diretorio do PRD. Pule TODAS as etapas listadas em `completed_steps`. Retome a execucao a partir de `current_step`. Gates ja passados (listados em `gates_passed`) NAO devem ser reapresentados.</critical>
 
@@ -149,7 +149,7 @@ Avalie se as tasks envolvem frontend:
 ### Etapa 8: Execucao
 
 Execute `/dw-run-plan` com o path do PRD.
-- Siga TODAS as instrucoes do comando, incluindo o gate nativo do plan-checker (PASS obrigatorio) e execucao paralela em waves via `/dw-execute-phase`
+- Siga TODAS as instrucoes do comando, incluindo o gate nativo do plan-checker (PASS obrigatorio) e execucao paralela em waves via os agentes da skill bundled `dw-execute-phase`
 - Cada task segue `/dw-run-task` com validacao Level 1
 
 ### Etapa 9: Review de Implementacao (Loop)
@@ -250,11 +250,11 @@ Pergunte ao usuario: **"Commits realizados. Deseja gerar o Pull Request?"**
 
 ## Engine Nativo
 
-O autopilot depende de infraestrutura dev-workflow-native para inteligencia de codebase (`/dw-map-codebase` + `/dw-intel`), verificacao de plano (`/dw-plan-checker`), e execucao paralela (`/dw-execute-phase`). Os quatro vem bundled e nao precisam de dependencias externas. Veja as skills bundled `dw-codebase-intel` e `dw-execute-phase` em `.agents/skills/` para detalhes.
+O autopilot depende de infraestrutura dev-workflow-native para inteligencia de codebase (`/dw-map-codebase` + `/dw-intel`) e dos agentes bundled de execucao de fase (plan-checker + executor em `.agents/skills/dw-execute-phase/agents/`). Tudo bundled, sem dependencias externas. Veja as skills bundled `dw-codebase-intel` e `dw-execute-phase` em `.agents/skills/` para detalhes.
 
 ## Persistencia de Estado
 
-<critical>O autopilot DEVE salvar seu estado apos cada etapa completada para permitir retomada via `/dw-resume` em caso de interrupcao.</critical>
+<critical>O autopilot DEVE salvar seu estado apos cada etapa completada para permitir re-invocacao no mesmo PRD em caso de interrupcao.</critical>
 
 Salve o arquivo `.dw/spec/prd-[nome]/autopilot-state.json` com o seguinte formato:
 
@@ -286,7 +286,7 @@ Salve o arquivo `.dw/spec/prd-[nome]/autopilot-state.json` com o seguinte format
 
 - Atualize `current_step`, `completed_steps` e `step_artifacts` ANTES de iniciar a proxima etapa
 - Uma etapa SO vai para `completed_steps` apos verificar que seus artefatos existem no disco
-- Se a sessao cair, o `/dw-resume` lera este arquivo e continuara da etapa correta — e revalidara os artefatos antes de confiar em `completed_steps`
+- Se a sessao cair, re-invoque `/dw-autopilot` no mesmo PRD; o comando le `autopilot-state.json` e continua da etapa correta, revalidando artefatos antes de confiar em `completed_steps`
 - Ao finalizar o pipeline (apos commit ou PR), remova o arquivo ou marque `"status": "completed"`
 
 <critical>Apos CADA etapa completada, exiba o bloco de progresso atualizado ao usuario. Isso e OBRIGATORIO — o usuario DEVE ver o que foi feito e o que vem a seguir. Se uma etapa foi pulada, o motivo DEVE aparecer no bloco de progresso.</critical>

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

@@ -109,7 +109,7 @@ Use este comando quando o usuario quiser:
 - lista curta e executavel
 - se apropriado, sugira qual comando usar em seguida:
   - `/dw-create-prd` (principal sucessor; aceita one-pager como input reduzindo perguntas de clarificação)
-  - `/dw-quick` (se é IMPROVES pequeno que cabe em task única, ≤3 arquivos)
+  - `/dw-run-task` (se é IMPROVES pequeno que cabe em task única com um PRD curto)
   - `/dw-create-techspec`
   - `/dw-create-tasks`
   - `/dw-bugfix`

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

@@ -15,6 +15,7 @@
 
     Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como suporte contextual sem substituir este comando:
 
+    - `dw-debug-protocol`: **SEMPRE** — conduz o bug pelo six-step triage (Reproduzir → Localizar → Reduzir → Fix Root Cause → Guardar → Verificar End-to-End). Stop-the-line discipline; root-cause sobre symptom; regression test commitado no mesmo commit atômico. Bugs não-reprodutíveis seguem o sub-protocolo instrument-first — sem fix por palpite a não ser com acknowledgement explícito.
     - `dw-verify`: **SEMPRE** — em modo Direto, invocada antes do commit da correção. O VERIFICATION REPORT deve mostrar que o sintoma original do bug não se reproduz mais (não apenas que os testes passam).
     - `vercel-react-best-practices`: use quando o bug afeta React/Next.js e há suspeita de problemas de render, hidratação, fetching, waterfall, bundle ou re-render
     - `webapp-testing`: use quando a correção requer fluxo E2E/reteste reproduzível em uma web app

package/scaffold/pt-br/commands/dw-code-review.md

@@ -24,6 +24,7 @@ Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como apo
 - `dw-review-rigor`: **SEMPRE** — aplica de-duplication (mesmo pattern em N arquivos = 1 finding), severity ordering (critical → high → medium → low), verify-before-flag, skip-what-linter-catches, e signal-over-volume. A tabela "Problemas Encontrados" do relatório segue essa disciplina.
 - `dw-verify`: **SEMPRE** — invocada antes de emitir verdict `APROVADO` ou `APROVADO COM RESSALVAS`. Sem VERIFICATION REPORT PASS (test + lint + build), o verdict não pode sair como APROVADO.
 - `/dw-security-check`: **SEMPRE para projetos TS/Python/C#/Rust** — invocado como step 6.7 (Camada de Segurança) antes de emitir verdict. Se o projeto usa linguagem suportada e `security-check.md` não existe OU tem status REJECTED, o verdict é **REPROVADO** — sem exceção.
+- `dw-simplification`: use quando o diff toca código denso ou tortuoso — aplica Chesterton's Fence (entender POR QUÊ antes de propor remoção), protocolo de refactor preservando comportamento (test gate antes/depois) e métricas de complexidade (ciclomática, cognitiva, depth, fan-out) para que findings de "simplifique isso" sejam concretos, não opinativos.
 - `security-review`: use quando auth, autorização, input externo, upload, SQL, integração externa, secrets, SSRF, XSS ou superfícies sensíveis estiverem presentes
 - `vercel-react-best-practices`: use quando o diff tocar React/Next.js para revisar padrões de renderização, fetching, bundle, hidratação e performance
 
@@ -158,6 +159,34 @@ Para cada projeto impactado, verificar rules específicas em `.dw/rules/`:
 - [ ] Chamadas de API usam utilitários fetch do projeto
 - [ ] UI segue o design system do projeto
 
+### 4.1. Constitution Compliance (Obrigatório quando `.dw/constitution.md` existe)
+
+<critical>**Auto-create se ausente**: se `.dw/constitution.md` NÃO existir, copie `templates/constitution-template.md` (project-local `.dw/templates/constitution-template.md` primeiro, com fallback para scaffold bundled) literalmente com frontmatter `mode: defaults`. Imprimir no chat: "Constituição defaults instalada em `.dw/constitution.md` (todos os princípios em `severity: info` — reportam mas não bloqueiam este review). Seguindo." Depois prossiga.</critical>
+
+Para cada princípio em `.dw/constitution.md`, verificar o diff por violações:
+
+1. **Parsear princípios**: ler cada entrada `**P-NNN — <nome>** (severity: <S>)`; capturar `P-NNN`, `severity` e descrição de `Enforcement`.
+2. **Aplicar enforcement**: para cada princípio, rodar a checagem de enforcement contra o diff (grep, inspeção de arquivo ou pattern match conforme a linha Enforcement).
+3. **Classificar violações**:
+   - Princípio `severity: info` → adicione linha à tabela "Issues Found" com severity `low`. **Não bloqueia** o verdict.
+   - Princípio `severity: high` → adicione linha com severity `critical`. **Bloqueia** o verdict como `REJECTED` EXCETO se um ADR no `adrs/` do mesmo PRD documenta o desvio (busque `Deviates: P-NNN` no corpo de qualquer ADR).
+   - Princípio `severity: critical` → adicione linha com severity `critical` E exigir que o ADR tenha campo `Approved by:` não-vazio. Campo ausente = ainda `REJECTED`.
+4. **Sem skip silencioso**: se o diff for grande demais para analisar todos os princípios, reportar quais foram checados e quais foram pulados por escopo.
+
+**Formato de saída no relatório:**
+
+```markdown
+## Constitution Compliance
+
+| Princípio | Severity | Status | Evidência | ADR escape |
+|-----------|----------|--------|-----------|------------|
+| P-001 — Sem `any` casts | info | VIOLATED | src/foo.ts:42 | n/a |
+| P-009 — Auth server-side | high | VIOLATED | src/api/order.ts:18 sem auth middleware | none → BLOQUEIA |
+| P-010 — Secrets no repo | critical | PASS | — | — |
+```
+
+Se houver violação `high`/`critical` sem ADR escape: adicionar à linha de verdict "REPROVADO — violação(ões) de constitution sem ADR (ver seção Constitution Compliance)".
+
 ### 5. Análise de Qualidade de Código (Obrigatório)
 
 | Aspecto | Verificação |

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

@@ -9,6 +9,12 @@
     ## Posição no Pipeline
     **Antecessor:** `/dw-run-task` ou `/dw-bugfix` | **Sucessor:** `/dw-generate-pr`
 
+    ## Skills Complementares
+
+    Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como suporte operacional sem substituir este comando:
+
+    - `dw-git-discipline`: **SEMPRE** — aplica atomic commits (uma intenção lógica por commit; refactor separado de feature), formato Conventional Commits, lint+tests+build verdes ANTES do commit e proíbe pular hooks (`--no-verify`) ou amend de commits já empurrados. Em mudanças mistas, separa via `git add -p`.
+
     ## Variáveis de Entrada
 
     | Variável | Descrição | Exemplo |