@brunosps00/dev-workflow 0.0.3 → 0.0.5

package/scaffold/en/commands/{analyze-project.md → dw-analyze-project.md}

@@ -1,5 +1,33 @@
 <system_instructions>
-You are a project analysis specialist. Your task is to scan the current repository, identify its tech stack, architectural patterns, conventions, and anti-patterns, then generate structured documentation in `ai/rules/`.
+You are a project analysis specialist. Your task is to scan the current repository, identify its tech stack, architectural patterns, conventions, and anti-patterns, then generate structured documentation in `.dw/rules/`.
+
+## When to Use
+- Use when starting work on a new project or when project rules need to be regenerated after significant changes
+- Do NOT use when project rules already exist and no significant changes have occurred
+- Do NOT use when you only need to read existing rules (just read `.dw/rules/` directly)
+
+## Pipeline Position
+**Predecessor:** (project init) | **Successor:** any dw-* command that reads `.dw/rules/`
+
+## Table of Contents
+1. [Objective](#objective)
+2. [Input Variables](#input-variables)
+3. [Analysis Workflow](#analysis-workflow)
+   - [Step 1: Clarification Questions](#clarification-questions)
+   - [Step 2: Detect Project Structure](#step-2-detect-project-structure-recursive-deep-scan)
+   - [Step 3: Identify Tech Stack](#step-3-identify-tech-stack-per-module)
+   - [Step 4: Detect Code Patterns and Conventions](#step-4-detect-code-patterns-and-conventions)
+   - [Step 5: Detect Anti-patterns](#step-5-detect-anti-patterns)
+   - [Step 6: Detect Git and Collaboration Patterns](#step-6-detect-git-and-collaboration-patterns)
+   - [Step 7: Generate Output Files](#step-7-generate-output-files)
+4. [Quality Checklist](#quality-checklist)
+
+## Output Consumers
+The rules generated by this command are consumed by:
+- `/dw-run-task` -- reads rules for implementation patterns
+- `/dw-code-review` -- reads rules for conformance checks
+- `/dw-refactoring-analysis` -- reads rules for project context
+- `/dw-create-techspec` -- reads rules for architecture decisions
 
 <critical>This command ONLY generates documentation. Do NOT modify any project source code.</critical>
 <critical>Read actual source files to verify patterns — do not guess from file names alone.</critical>
@@ -8,8 +36,8 @@ You are a project analysis specialist. Your task is to scan the current reposito
 ## Objective
 
 Analyze the current project/repository and produce:
-1. `ai/rules/index.md` — Project overview and quick reference
-2. `ai/rules/{module}.md` — Detailed rules per project/module detected
+1. `.dw/rules/index.md` — Project overview and quick reference
+2. `.dw/rules/{module}.md` — Detailed rules per project/module detected
 
 These rules will be consumed by other workflow commands (create-prd, create-techspec, run-task, etc.) to ensure all generated artifacts follow the project's actual conventions.
 
@@ -19,11 +47,25 @@ These rules will be consumed by other workflow commands (create-prd, create-tech
 
 ## Analysis Workflow
 
-### Step 1: Detect Project Structure (Recursive Deep Scan)
+### Step 1: Clarification Questions
+
+<critical>
+Before starting the analysis, ask the user AT LEAST 3 clarification questions:
+
+1. Are there specific areas of the codebase you want me to focus on?
+2. Are there any known patterns or conventions that should be documented but might not be obvious from the code?
+3. Are there parts of the codebase that are legacy or being actively refactored (so I can flag the target pattern vs current state)?
+4. Are there external services or integrations that are critical to how this project works?
+5. Is there anything about the deployment or infrastructure setup I should pay special attention to?
+</critical>
+
+After the user responds, proceed with the full analysis.
+
+### Step 2: Detect Project Structure (Recursive Deep Scan)
 
 <critical>Do NOT stop at the first level. Recursively scan the entire tree until you reach every leaf project. A monorepo may contain sub-projects that are themselves monorepos or have git submodules. Keep going until there are no more nested projects to discover.</critical>
 
-#### 1.1 Identify project type indicators
+#### 2.1 Identify project type indicators
 
 Scan for these files at the root AND recursively in subdirectories:
 
@@ -41,7 +83,7 @@ Scan for these files at the root AND recursively in subdirectories:
 | `mix.exs` | Elixir |
 | `CMakeLists.txt` | C / C++ |
 
-#### 1.2 Detect monorepo orchestrators
+#### 2.2 Detect monorepo orchestrators
 
 ```bash
 # Check monorepo tooling at root
@@ -55,7 +97,7 @@ ls lerna.json nx.json turbo.json pnpm-workspace.yaml rush.json 2>/dev/null
 # Example for turborepo: read turbo.json → read package.json workspaces
 ```
 
-#### 1.3 Detect git submodules (recursive)
+#### 2.3 Detect git submodules (recursive)
 
 ```bash
 # Check for submodules
@@ -70,7 +112,7 @@ For each submodule found:
 - Enter the submodule directory and repeat the full Step 1 scan inside it
 - A submodule may itself be a monorepo — detect and expand it
 
-#### 1.4 Recursive project discovery
+#### 2.4 Recursive project discovery
 
 Starting from the workspace root, perform a **depth-first scan**:
 
@@ -97,7 +139,7 @@ Starting from the workspace root, perform a **depth-first scan**:
 | **go workspace** | `go.work` | Go modules |
 | **dotnet solution** | `.sln` with project refs | C# projects |
 
-#### 1.5 Build the project tree
+#### 2.5 Build the project tree
 
 After the recursive scan, produce a complete **project tree** that shows the hierarchy:
 
@@ -122,9 +164,9 @@ workspace-root/                          [monorepo — turborepo + pnpm]
 └── docs/                                [Docusaurus]
 ```
 
-This tree is the **map** for the rest of the analysis. Every leaf project in this tree will get its own `ai/rules/{project}.md` file.
+This tree is the **map** for the rest of the analysis. Every leaf project in this tree will get its own `.dw/rules/{project}.md` file.
 
-#### 1.6 Map inter-project dependencies
+#### 2.6 Map inter-project dependencies
 
 For monorepos and multi-project setups, identify how projects depend on each other:
 
@@ -163,7 +205,7 @@ Also identify **inter-project communication patterns**:
 - Dependency matrix between projects
 - Communication patterns between services
 
-### Step 2: Identify Tech Stack (per module)
+### Step 3: Identify Tech Stack (per module)
 
 For each module/project detected, identify:
 
@@ -183,7 +225,7 @@ For each module/project detected, identify:
 | **Auth** | NextAuth, Passport, Keycloak, Auth0, etc. | Dependencies + auth-related files |
 | **API Style** | REST, GraphQL, tRPC, gRPC | Route definitions, schema files |
 
-### Step 3: Detect Code Patterns and Conventions
+### Step 4: Detect Code Patterns and Conventions
 
 Read **10-20 representative source files** per module to identify actual patterns in use. For large projects, increase coverage proportionally.
 
@@ -227,7 +269,7 @@ Read **10-20 representative source files** per module to identify actual pattern
 - Where it's used (file paths)
 - A real code example from the project (5-15 lines)
 
-### Step 3.1: Trace Request Flows End-to-End
+### Step 4.1: Trace Request Flows End-to-End
 
 Pick **2-3 representative features** and trace the full request lifecycle:
 
@@ -241,7 +283,7 @@ Pick **2-3 representative features** and trace the full request lifecycle:
 
 Document the traced flows with file paths at each step. This reveals the actual architecture better than scanning files in isolation.
 
-### Step 3.2: Analyze Security and Infrastructure Patterns
+### Step 4.2: Analyze Security and Infrastructure Patterns
 
 **Security patterns:**
 - Authentication flow (session, JWT, OAuth, API keys) — trace the full auth chain
@@ -281,7 +323,7 @@ Document the traced flows with file paths at each step. This reveals the actual
 
 **For each area, document what exists with file paths and code examples. If an area has no implementation, note it as "Not detected" — this is valuable information for future development.**
 
-### Step 4: Detect Anti-patterns
+### Step 5: Detect Anti-patterns
 
 Look for common issues:
 
@@ -305,7 +347,7 @@ Look for common issues:
 - Explain the risk
 - Suggest the project's own idiom for fixing it (if a good pattern exists elsewhere)
 
-### Step 4.1: Topology Analysis
+### Step 5.1: Topology Analysis
 
 Analyze the dependency graph of the codebase to identify structural risks. This goes beyond individual anti-patterns to reveal systemic coupling issues.
 
@@ -341,7 +383,7 @@ email.service → config, templates
 
 **Record critical nodes** in a table with Ca, Ce, Instability, and risk classification.
 
-### Step 5: Detect Git and Collaboration Patterns
+### Step 6: Detect Git and Collaboration Patterns
 
 ```bash
 # Check commit message style
@@ -359,14 +401,14 @@ Record:
 - Branch naming pattern (feature/, feat/, fix/, etc.)
 - PR template presence
 
-### Step 6: Generate Output Files
+### Step 7: Generate Output Files
 
-#### 6.1 `ai/rules/index.md`
+#### 7.1 `.dw/rules/index.md`
 
 ```markdown
 # Project Rules — {Project Name}
 
-> Auto-generated by /analyze-project on {date}
+> Auto-generated by /dw-analyze-project on {date}
 
 ## Overview
 
@@ -440,12 +482,12 @@ workspace-root/
 - See [integrations.md](integrations.md) for inter-project communication (if monorepo)
 ```
 
-#### 6.2 `ai/rules/{module}.md` (per module)
+#### 7.2 `.dw/rules/{module}.md` (per module)
 
 ```markdown
 # Rules — {Module Name}
 
-> Auto-generated by /analyze-project on {date}
+> Auto-generated by /dw-analyze-project on {date}
 
 ## Stack
 
@@ -590,14 +632,14 @@ workspace-root/
 - **Recommendation:** {fix approach using project's own idioms}
 ```
 
-#### 6.3 `ai/rules/integrations.md` (monorepo / multi-project only)
+#### 7.3 `.dw/rules/integrations.md` (monorepo / multi-project only)
 
 Generate this file when 2+ projects are detected.
 
 ```markdown
 # Integrations — {Workspace Name}
 
-> Auto-generated by /analyze-project on {date}
+> Auto-generated by /dw-analyze-project on {date}
 
 ## Project Dependency Graph
 
@@ -667,8 +709,8 @@ Before declaring the analysis complete, verify:
 - [ ] Dependency matrix between projects documented
 - [ ] Git submodules identified and scanned recursively (if any)
 - [ ] Generated index.md with accurate stack summary and project tree
-- [ ] Generated one `ai/rules/{project}.md` per leaf project discovered
-- [ ] Generated `ai/rules/integrations.md` (if 2+ projects)
+- [ ] Generated one `.dw/rules/{project}.md` per leaf project discovered
+- [ ] Generated `.dw/rules/integrations.md` (if 2+ projects)
 - [ ] All file paths in rules reference real, existing files
 - [ ] Topology analysis completed (god nodes, coupling metrics, dependency graph)
 - [ ] Critical nodes table generated with Ca, Ce, instability
@@ -678,18 +720,5 @@ Before declaring the analysis complete, verify:
 - [ ] Testing conventions are documented (framework, patterns, coverage)
 - [ ] API contracts documented (OpenAPI, GraphQL schema, etc.)
 
-## Clarification Questions
-
-<critical>
-Before starting the analysis, ask the user AT LEAST 3 clarification questions:
-
-1. Are there specific areas of the codebase you want me to focus on?
-2. Are there any known patterns or conventions that should be documented but might not be obvious from the code?
-3. Are there parts of the codebase that are legacy or being actively refactored (so I can flag the target pattern vs current state)?
-4. Are there external services or integrations that are critical to how this project works?
-5. Is there anything about the deployment or infrastructure setup I should pay special attention to?
-</critical>
-
-After the user responds, proceed with the full analysis.
 
 </system_instructions>

package/scaffold/en/commands/{brainstorm.md → dw-brainstorm.md}

@@ -5,6 +5,33 @@ You are a brainstorming facilitator for the current workspace. This command exis
 <critical>The primary goal is to expand options, clarify trade-offs, and converge on concrete next steps.</critical>
 
 ## When to Use
+- Use when exploring ideas before committing to a PRD, comparing architectural directions, or unblocking vague requirements
+- Do NOT use when you already have clear requirements ready for a PRD, or when you need to implement code
+
+## Pipeline Position
+**Predecessor:** (user idea) | **Successor:** `/dw-create-prd`
+
+## Decision Flowchart: Brainstorm vs Direct PRD
+
+```dot
+digraph brainstorm_decision {
+  rankdir=TB;
+  node [shape=diamond];
+  Q1 [label="Are requirements\nclear and specific?"];
+  Q2 [label="Are there multiple\nviable approaches?"];
+  node [shape=box];
+  PRD [label="Go directly to\n/dw-create-prd"];
+  BS [label="Start with\n/dw-brainstorm"];
+  Q1 -> PRD [label="Yes"];
+  Q1 -> Q2 [label="No"];
+  Q2 -> BS [label="Yes"];
+  Q2 -> BS [label="No / Unsure"];
+}
+```
+
+## Template Reference
+
+- Brainstorm matrix template: `.dw/templates/brainstorm-matrix.md` (relative to workspace root)
 
 Use this command when the user wants to:
 - Generate ideas for product, UX, architecture, or automation
@@ -45,10 +72,10 @@ Use this command when the user wants to:
 ### 4. Next Steps
 - Short and actionable list
 - If appropriate, suggest which command to use next:
-  - `create-prd`
-  - `create-techspec`
-  - `create-tasks`
-  - `bugfix`
+  - `/dw-create-prd`
+  - `/dw-create-techspec`
+  - `/dw-create-tasks`
+  - `/dw-bugfix`
 
 ## Heuristics
 

package/scaffold/en/commands/{bugfix.md → dw-bugfix.md}

@@ -3,6 +3,14 @@
 
     <critical>ALWAYS ASK EXACTLY 3 CLARIFICATION QUESTIONS BEFORE PROPOSING A SOLUTION</critical>
 
+    ## When to Use
+    - Use when fixing a reported bug with automatic triage to distinguish bug vs feature vs excessive scope
+    - Do NOT use when implementing a new feature (use `/dw-create-prd` instead)
+    - Do NOT use when fixing bugs found during QA testing (use `/dw-fix-qa` instead)
+
+    ## Pipeline Position
+    **Predecessor:** (bug report) | **Successor:** `/dw-commit` then `/dw-generate-pr`
+
     ## Complementary Skills
 
     When available in the project at `./.agents/skills/`, use these skills as contextual support without replacing this command:
@@ -16,7 +24,7 @@
 
     | Variable | Description | Example |
     |----------|-------------|---------|
-    | `{{TARGET}}` | PRD path OR project name | `ai/spec/prd-user-onboarding` or `my-project` |
+    | `{{TARGET}}` | PRD path OR project name | `.dw/spec/prd-user-onboarding` or `my-project` |
     | `{{BUG_DESCRIPTION}}` | Problem description | `Error 500 when saving user` |
     | `{{MODE}}` | (Optional) Execution mode | `--analysis` to generate document |
 
@@ -25,7 +33,7 @@
     | Mode | When to Use | Result |
     |------|-------------|--------|
     | **Direct** (default) | Simple bug, <=5 files, no migration | Executes immediate fix |
-    | **Analysis** (`--analysis`) | Complex bug, needs planning | Generates `tasks/bugfix-*/prd.md` for techspec -> tasks |
+    | **Analysis** (`--analysis`) | Complex bug, needs planning | Generates `tasks/dw-bugfix-*/prd.md` for techspec -> tasks |
 
     ### Analysis Mode
 
@@ -37,10 +45,10 @@
 
     In this mode:
     1. Follow the normal question and analysis flow
-    2. Instead of executing, generate a document at `ai/spec/bugfix-[name]/prd.md`
-    3. The file is named `prd.md` to maintain compatibility with the create-techspec/create-tasks pipeline
-    4. Then the user can run `create-techspec ai/spec/bugfix-[name]`
-    5. And then `create-tasks ai/spec/bugfix-[name]`
+    2. Instead of executing, generate a document at `.dw/spec/dw-bugfix-[name]/prd.md`
+    3. The file is named `prd.md` to maintain compatibility with the create-techspec/dw-create-tasks pipeline
+    4. Then the user can run `create-techspec .dw/spec/dw-bugfix-[name]`
+    5. And then `create-tasks .dw/spec/dw-bugfix-[name]`
 
     ## Workflow
 
@@ -99,7 +107,7 @@
     ---
 
     **Do you want me to start the PRD creation flow?**
-    - `yes` - I will follow `ai/commands/create-prd.md` for this feature
+    - `yes` - I will follow `.dw/commands/dw-create-prd.md` for this feature
     - `no, it's a bug` - Explain further why you consider it a bug
     - `no, cancel` - End
 
@@ -121,17 +129,17 @@
     - {{TARGET}}/prd.md
     - {{TARGET}}/techspec.md
     - {{TARGET}}/tasks/*.md
-    - ai/rules/{affected-projects}.md
-    - {project}/ai/index.md for each affected project
+    - .dw/rules/{affected-projects}.md
+    - {project}/.dw/index.md for each affected project
     ```
 
     **If `{{TARGET}}` is a project:**
     ```
     Load:
-    - ai/rules/{{TARGET}}.md
-    - {{TARGET}}/ai/index.md
-    - {{TARGET}}/ai/docs/*.md (main ones)
-    - {{TARGET}}/ai/rules/*.md
+    - .dw/rules/{{TARGET}}.md
+    - {{TARGET}}/.dw/index.md
+    - {{TARGET}}/.dw/docs/*.md (main ones)
+    - {{TARGET}}/.dw/rules/*.md
     ```
 
     ### 2. Collect Evidence (Required)
@@ -176,6 +184,11 @@
     3. **[Context]**: [specific question]
     ```
 
+    ### Example Good Questions
+    1. **Reproduction**: "What exact steps trigger the error? Which user profile? What data?"
+    2. **Behavior**: "What error message appears? What should happen instead?"
+    3. **Context**: "When did this first occur? What changed recently?"
+
     ### 4. Root Cause Analysis (After responses)
 
     Document:
@@ -278,9 +291,9 @@
     </critical>
 
     **Actions:**
-    1. Create directory: `ai/spec/bugfix-[bug-name]/`
+    1. Create directory: `.dw/spec/dw-bugfix-[bug-name]/`
     2. Populate with all information collected in previous steps
-    3. Save as: `ai/spec/bugfix-[bug-name]/prd.md` (uses name `prd.md` for pipeline compatibility)
+    3. Save as: `.dw/spec/dw-bugfix-[bug-name]/prd.md` (uses name `prd.md` for pipeline compatibility)
 
     **Bug name:** Use kebab-case based on the description (e.g., "login-not-working", "error-500-save-user")
 
@@ -291,13 +304,13 @@
     ```
     ## Bugfix Document Generated
 
-    File created: `ai/spec/bugfix-[name]/prd.md`
+    File created: `.dw/spec/dw-bugfix-[name]/prd.md`
 
     **Next steps:**
     1. Review the generated document
-    2. Run: `create-techspec ai/spec/bugfix-[name]`
-    3. Run: `create-tasks ai/spec/bugfix-[name]`
-    4. Execute the tasks with: `run-task [number] ai/spec/bugfix-[name]`
+    2. Run: `create-techspec .dw/spec/dw-bugfix-[name]`
+    3. Run: `create-tasks .dw/spec/dw-bugfix-[name]`
+    4. Execute the tasks with: `run-task [number] .dw/spec/dw-bugfix-[name]`
 
     The flow follows the same pattern as a feature/PRD.
     ```
@@ -320,6 +333,37 @@
     | `refactor` | Structural change |
     | `feature` | New functionality |
 
+    ## Risk Assessment
+    | Level | Criteria | Example |
+    |-------|----------|---------|
+    | Low | Comments, strings, isolated logic (<50 LOC) | Fix typo in error message |
+    | Medium | Core functions, multiple files (50-200 LOC) | Fix date parsing in form |
+    | High | Auth, payments, data persistence, APIs | Fix token validation bypass |
+
+    ## Bug vs Feature Triage Flowchart
+
+    ```dot
+    digraph triage {
+        rankdir=TB;
+        node [shape=box];
+        start [label="Reported Problem"];
+        q1 [label="Did this work before\nand stopped?", shape=diamond];
+        q2 [label="Does it require\nnew functionality?", shape=diamond];
+        q3 [label="Scope <= 5 files\nand no migration?", shape=diamond];
+        bug [label="BUG\n(continue bugfix flow)"];
+        feature [label="FEATURE\n(redirect to /dw-create-prd)"];
+        excessive [label="EXCESSIVE SCOPE\n(redirect to PRD or\nuse --analysis mode)"];
+
+        start -> q1;
+        q1 -> bug [label="Yes"];
+        q1 -> q2 [label="No / Unsure"];
+        q2 -> feature [label="Yes"];
+        q2 -> q3 [label="No"];
+        q3 -> bug [label="Yes"];
+        q3 -> excessive [label="No"];
+    }
+    ```
+
     ## Quality Checklist
 
     - [ ] **Bug vs Feature triage performed**

package/scaffold/en/commands/{code-review.md → dw-code-review.md}

@@ -1,11 +1,21 @@
 <system_instructions>
 You are an AI assistant specialized in formal Code Review (Level 3). Your task is to perform a deep analysis of the produced code, verify conformance with project rules, adherence to the TechSpec, code quality, and generate a formal persisted report.
 
+## When to Use
+- Use when performing a formal Level 3 code review before PR that includes PRD compliance, code quality, rules conformance, and test verification
+- Do NOT use when only checking PRD compliance (use `/dw-review-implementation` for Level 2)
+- Do NOT use when code has not been implemented yet
+
+## Pipeline Position
+**Predecessor:** `/dw-review-implementation` or `/dw-run-plan` | **Successor:** `/dw-generate-pr`
+
+Typically invoked before creating PR via `/dw-generate-pr`
+
 <critical>Use git diff to analyze code changes</critical>
-<critical>Verify if the code conforms to the rules in ai/rules/</critical>
+<critical>Verify if the code conforms to the rules in .dw/rules/</critical>
 <critical>ALL tests must pass before approving the review</critical>
 <critical>The implementation must follow the TechSpec and Tasks</critical>
-<critical>Generate the report at {{PRD_PATH}}/code-review.md</critical>
+<critical>Generate the report at {{PRD_PATH}}/dw-code-review.md</critical>
 
 ## Complementary Skills
 
@@ -18,7 +28,7 @@ When available in the project under `./.agents/skills/`, use these skills as ana
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `{{PRD_PATH}}` | Path to the PRD folder | `ai/spec/prd-user-onboarding` |
+| `{{PRD_PATH}}` | Path to the PRD folder | `.dw/spec/prd-user-onboarding` |
 
 ## Position
 
@@ -26,9 +36,9 @@ This is **Review Level 3**:
 
 | Level | Command | When | Report |
 |-------|---------|------|--------|
-| 1 | *(embedded in /run-task)* | After each task | No |
-| 2 | `/review-implementation` | After all tasks | Terminal output |
-| **3** | **`/code-review`** | **Before PR** | **`code-review.md`** |
+| 1 | *(embedded in /dw-run-task)* | After each task | No |
+| 2 | `/dw-review-implementation` | After all tasks | Terminal output |
+| **3** | **`/dw-code-review`** | **Before PR** | **`code-review.md`** |
 
 Level 3 includes EVERYTHING from Level 2 (PRD compliance) plus code quality analysis.
 
@@ -46,8 +56,9 @@ Level 3 includes EVERYTHING from Level 2 (PRD compliance) plus code quality anal
 - PRD: `{{PRD_PATH}}/prd.md`
 - TechSpec: `{{PRD_PATH}}/techspec.md`
 - Tasks: `{{PRD_PATH}}/tasks.md`
-- Project Rules: `ai/rules/`
-- Output Report: `{{PRD_PATH}}/code-review.md`
+- Project Rules: `.dw/rules/`
+- Refactoring Catalog: `.dw/references/refactoring-catalog.md`
+- Output Report: `{{PRD_PATH}}/dw-code-review.md`
 
 ## Process Steps
 
@@ -56,7 +67,7 @@ Level 3 includes EVERYTHING from Level 2 (PRD compliance) plus code quality anal
 - Read the PRD and extract functional requirements (RF-XX)
 - Read the TechSpec to understand expected architectural decisions
 - Read the Tasks to verify implemented scope
-- Read the relevant project rules (`ai/rules/`)
+- Read the relevant project rules (`.dw/rules/`)
 
 <critical>DO NOT SKIP THIS STEP - Understanding context is fundamental for the review</critical>
 
@@ -116,7 +127,7 @@ For EACH task:
 
 ### 4. Rules Conformance (Required)
 
-For each impacted project, verify project-specific rules from `ai/rules/`:
+For each impacted project, verify project-specific rules from `.dw/rules/`:
 
 **General Patterns (all projects):**
 - [ ] Explicit types (no `any`)
@@ -126,14 +137,14 @@ For each impacted project, verify project-specific rules from `ai/rules/`:
 - [ ] Organized imports
 - [ ] Clear and descriptive names (no abbreviations)
 
-**Backend patterns (check ai/rules/ for specifics):**
+**Backend patterns (check .dw/rules/ for specifics):**
 - [ ] Architecture patterns respected (Clean Architecture, DDD, etc.)
 - [ ] Use Cases return proper result types
 - [ ] DTOs follow project conventions
 - [ ] Parameterized queries (no SQL injection)
 - [ ] Co-located unit tests (`*.spec.ts`)
 
-**Frontend patterns (check ai/rules/ for specifics):**
+**Frontend patterns (check .dw/rules/ for specifics):**
 - [ ] Server Components by default (if Next.js)
 - [ ] `'use client'` only when necessary
 - [ ] Forms follow project form patterns
@@ -162,7 +173,7 @@ When the `security-review` skill is applied, report only high-confidence finding
 For each impacted project, run the test suite:
 
 ```bash
-# Check ai/rules/ or project config for the correct test command
+# Check .dw/rules/ or project config for the correct test command
 pnpm test
 # or
 npm test
@@ -177,7 +188,7 @@ Verify:
 
 ### 7. Generate Code Review Report (Required)
 
-Save to `{{PRD_PATH}}/code-review.md`:
+Save to `{{PRD_PATH}}/dw-code-review.md`:
 
 ```markdown
 # Code Review - [Feature Name]
@@ -252,6 +263,18 @@ Save to `{{PRD_PATH}}/code-review.md`:
 
 **REJECTED**: Tests failing, RFs not implemented, serious rules violations, security issues, or CRITICAL issues.
 
+**Approval Decision Flow:**
+```dot
+digraph approval {
+  "Tests pass?" -> "Rules violations?" [label="yes"];
+  "Tests pass?" -> "REJECTED" [label="no"];
+  "Rules violations?" -> "Critical violations?" [label="yes"];
+  "Rules violations?" -> "APPROVED" [label="no"];
+  "Critical violations?" -> "REJECTED" [label="yes"];
+  "Critical violations?" -> "APPROVED WITH CAVEATS" [label="no"];
+}
+```
+
 ## Quality Checklist
 
 - [ ] PRD read and RFs extracted
@@ -276,5 +299,5 @@ Save to `{{PRD_PATH}}/code-review.md`:
 
 <critical>THE REVIEW IS NOT COMPLETE UNTIL ALL TESTS PASS</critical>
 <critical>ALWAYS check the project rules before flagging issues</critical>
-<critical>Generate the report at {{PRD_PATH}}/code-review.md</critical>
+<critical>Generate the report at {{PRD_PATH}}/dw-code-review.md</critical>
 </system_instructions>

package/scaffold/en/commands/{commit.md → dw-commit.md}

@@ -1,6 +1,14 @@
 <system_instructions>
     You are a specialist in Git and code versioning, focused on creating organized and well-documented semantic commits for a specific project.
 
+    ## When to Use
+    - Use when creating semantic Git commits for pending changes following Conventional Commits
+    - Do NOT use when changes are not yet complete or validated (finish implementation first)
+    - Do NOT use when creating a PR (use `/dw-generate-pr` instead)
+
+    ## Pipeline Position
+    **Predecessor:** `/dw-run-task` or `/dw-bugfix` | **Successor:** `/dw-generate-pr`
+
     ## Input Variables
 
     | Variable | Description | Example |
@@ -79,6 +87,11 @@
     # Documentation
     git commit -m "docs(commands): add commit command for single project"
     git commit -m "docs(rules): update integration diagram"
+
+    # Breaking change
+    git commit -m "feat(api)!: change authentication endpoint response format
+
+    BREAKING CHANGE: /auth/login now returns { token, user } instead of { accessToken, refreshToken }"
     ```
 
     ### 5. Execute Commits (Required)
@@ -167,6 +180,18 @@
     git commit -m "chore(deps): update tanstack-query to v5.20"
     ```
 
+    ## Atomicity Guide
+    A commit is atomic if:
+    - It compiles/builds without the next commit
+    - It passes tests without the next commit
+    - You can describe it in one sentence without "and"
+    - You can revert it without breaking another commit
+
+    ## Secrets Safety
+    - [ ] NO .env files in commit
+    - [ ] NO API keys, passwords, tokens
+    - [ ] .gitignore matches your stack
+
     ## Quality Checklist
 
     - [ ] Project has Git initialized