@brunosps00/dev-workflow 0.8.0 → 0.9.0

package/scaffold/skills/dw-codebase-intel/references/query-patterns.md

@@ -0,0 +1,148 @@
+# Query patterns — how `/dw-intel` answers different question shapes
+
+`/dw-intel "<query>"` reads `.dw/intel/` and returns structured answers with file paths cited. This file describes how the command maps natural-language queries to which intel files to read.
+
+## Query shape detection
+
+The command classifies the query into one of these shapes before searching:
+
+| Shape | Example queries | Primary file | Secondary files |
+|-------|-----------------|--------------|-----------------|
+| **where-is** | "where is the user routes file?", "where is auth defined?" | `files.json` | `apis.json` |
+| **what-uses** | "what uses express?", "where is the redis client called?" | `deps.json` (for libs), `files.json` (for symbols) | grep fallback |
+| **architecture-of** | "what's the architecture?", "how is data flow structured?" | `arch.md` | `stack.json` |
+| **stack** | "what frameworks?", "is this typescript or javascript?" | `stack.json` | — |
+| **dep-info** | "which version of react?", "what's prisma used for here?" | `deps.json` | — |
+| **api-list** | "list endpoints", "what routes exist?" | `apis.json` | — |
+| **find-export** | "where is `createServer` exported from?", "find the `userSchema` symbol" | `files.json` (search `exports` arrays) | grep fallback |
+| **convention** | "what's the file naming convention?", "are tests co-located?" | `arch.md` | `.dw/rules/` if available |
+
+## Match algorithm
+
+For each shape, the command:
+
+1. **Tokenize** the query into keywords (drop stopwords).
+2. **Search the primary file** for matches:
+   - JSON files: case-insensitive substring match in keys + descriptions
+   - `arch.md`: case-insensitive full-text search
+3. **Rank** matches by:
+   - Exact symbol match > substring match > description match
+   - Direct deps > indirect (transitive) deps
+4. **Return** top 3-5 matches with file paths cited.
+
+If primary file yields zero matches, fall back to secondary files. If still zero, fall back to direct grep over the project (slower but exhaustive).
+
+## Examples
+
+### Query: "where is auth defined?"
+
+**Shape:** where-is
+
+**Process:**
+1. Search `files.json` for keys containing `auth` → finds `src/auth/index.ts`, `src/middleware/auth.ts`, `src/routes/auth.ts`
+2. Search `apis.json` for paths containing `auth` → finds `POST /api/auth/login`, `POST /api/auth/logout`
+3. Return top files + endpoints with paths
+
+**Output:**
+```
+Auth is defined across 3 files and exposes 2 endpoints:
+
+Files:
+- src/auth/index.ts        (entry-point) — exports: configureAuth, AuthError
+- src/middleware/auth.ts   (module)      — exports: requireAuth, optionalAuth
+- src/routes/auth.ts       (module)      — exports: authRouter
+
+Endpoints:
+- POST /api/auth/login   (file: src/routes/auth.ts) — Authenticate user
+- POST /api/auth/logout  (file: src/routes/auth.ts) — Clear session
+```
+
+### Query: "what uses redis?"
+
+**Shape:** what-uses
+
+**Process:**
+1. Search `deps.json` for entry `redis` (or `ioredis`, `redis-py`, etc. depending on stack)
+2. Read its `used_by` array
+3. Cross-reference with `files.json` to enrich (which files have this dep imported and what they do)
+
+**Output:**
+```
+Redis (ioredis@^5.3.0, production) is used by 3 files:
+
+- src/cache/index.ts        — exports: cacheGet, cacheSet, cacheDel
+- src/jobs/queue.ts         — exports: enqueueJob (uses ioredis as BullMQ backend)
+- src/sessions/store.ts     — exports: createSessionStore
+```
+
+### Query: "what frameworks?"
+
+**Shape:** stack
+
+**Process:**
+1. Read `stack.json` directly
+2. Output the `frameworks` field, with versions if available from `deps.json`
+
+**Output:**
+```
+Frameworks detected:
+- Express (^4.18.0, production)
+- React (^18.2.0, production)
+- Prisma (^5.4.0, production)
+
+Build system: npm scripts
+Test framework: Jest
+Package manager: npm
+```
+
+### Query: "list endpoints"
+
+**Shape:** api-list
+
+**Process:**
+1. Read `apis.json`
+2. Group by tag/prefix (`/api/users`, `/api/orders`, `/api/auth` → User Management, Orders, Auth)
+3. Output tabular
+
+**Output:**
+```
+12 endpoints across 3 groups:
+
+Auth (2)
+- POST /api/auth/login   — Authenticate user
+- POST /api/auth/logout  — Clear session
+
+Users (5)
+- GET    /api/users        — List users
+- POST   /api/users        — Create user
+- GET    /api/users/:id    — Get user by id
+- PATCH  /api/users/:id    — Update user
+- DELETE /api/users/:id    — Delete user
+
+Orders (5) ...
+```
+
+## Stale-index handling
+
+Before answering, check `.dw/intel/.last-refresh.json`:
+
+- If `updated_at` is more than 7 days old → prefix the answer with: `⚠ Index last refreshed YYYY-MM-DD (X days ago). Run /dw-map-codebase to refresh.`
+- If `.last-refresh.json` is absent → prefix with: `⚠ No refresh metadata. Index may be stale; run /dw-map-codebase.`
+
+Don't refuse to answer — return the best info available, but flag the staleness so the user can decide whether to trust it.
+
+## Fallback path (no `.dw/intel/`)
+
+If `.dw/intel/` doesn't exist at all:
+
+1. Check `.dw/rules/` (from `/dw-analyze-project` or `/dw-new-project` seeding)
+2. If `.dw/rules/index.md` exists, search there for the query keywords
+3. Otherwise, do a direct `grep -r` over the project source (excluding `node_modules`, `.git`, etc.)
+4. Suggest at the end: `Tip: run /dw-map-codebase to build a queryable index. Subsequent /dw-intel queries will be much faster.`
+
+## Don't
+
+- Don't fabricate paths or symbols not present in the index
+- Don't return "I don't know" without first trying the secondary file and grep fallback
+- Don't ignore stale-index warnings — surface them prominently
+- Don't dump the entire JSON of an intel file as the answer; synthesize and cite paths

package/scaffold/skills/dw-execute-phase/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: dw-execute-phase
+description: Phase execution and plan verification for dev-workflow. Two agents (executor for wave-based parallel task dispatch with deviation handling, plan-checker for goal-backward plan verification before execution). Used by /dw-execute-phase, /dw-plan-checker, /dw-run-plan, /dw-autopilot. Adapted from get-shit-done-cc (MIT).
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+---
+
+# dw-execute-phase
+
+Bundled skill providing **phase-level execution discipline** for dev-workflow: parallel task dispatch in waves, atomic commit per task, deviation handling mid-execution, and goal-backward plan verification before any execution burns context.
+
+## Why a skill (not inline)
+
+- The execution discipline (wave coordination, deviation rules, checkpoint protocol) is a separate concern from the commands that invoke it. Bundling it as a skill lets multiple commands (`/dw-run-plan`, `/dw-autopilot`, `/dw-execute-phase` itself) reuse the same discipline.
+- The plan-checker is a verification GATE — it must run before `/dw-run-plan`/`/dw-execute-phase` mutate code, and bundling it makes that contract visible.
+- The agents own the protocol; the orchestrating commands just wire them up.
+
+## When to Use
+
+Read this skill when:
+
+- `/dw-execute-phase` is invoked to run a batch of tasks in parallel waves.
+- `/dw-plan-checker` is invoked to verify a `tasks.md` file will achieve its PRD goal before execution.
+- `/dw-run-plan` is invoked (it spawns the executor agent for each wave).
+- `/dw-autopilot` enters the execution stage (it gates on plan-checker before invoking the executor).
+
+Do NOT use when:
+
+- A single one-off change is being made (use `/dw-run-task` directly — no waves needed).
+- The user is exploring/brainstorming, not executing (use `/dw-brainstorm`).
+- The plan hasn't been created yet (use `/dw-create-tasks` first).
+
+## Agents
+
+| Agent | Responsibility | Spawn from |
+|-------|----------------|------------|
+| `agents/executor.md` | Runs tasks in waves, atomic commit per task, handles deviations (3 deviation rules), respects checkpoint markers, writes `SUMMARY.md` per phase | `/dw-execute-phase`, `/dw-run-plan` |
+| `agents/plan-checker.md` | Goal-backward verification of `tasks.md` before execution. Checks: requirement coverage, task completeness, dependency soundness, artifact wiring, context budget. Returns PASS / REVISE / BLOCK. | `/dw-plan-checker`, `/dw-create-tasks` (auto-gate before declaring tasks ready) |
+
+## How the Two Agents Compose
+
+The expected flow:
+
+1. `/dw-create-tasks` produces `.dw/spec/prd-<slug>/tasks.md` from PRD + TechSpec.
+2. **Plan-checker GATE** — `/dw-plan-checker .dw/spec/prd-<slug>/` spawns the plan-checker agent. The agent reads PRD/TechSpec/tasks.md and verifies tasks WILL achieve the goal. Returns one of: `PASS` (proceed), `REVISE` (issues found, planner re-runs), `BLOCK` (fundamental gap, abort).
+3. `/dw-execute-phase` spawns the executor agent ONLY if plan-checker returned `PASS`. The executor runs tasks in waves, commits atomically, handles deviations.
+4. `/dw-run-qa` runs after all waves complete to validate the implementation against PRD.
+
+`/dw-autopilot` orchestrates this entire flow with hard gates between stages.
+
+## Wave Concept
+
+Tasks in `tasks.md` are grouped into **waves** by their `Depends on:` frontmatter:
+
+- Wave 1: tasks with no dependencies → run in parallel
+- Wave 2: tasks that depend on Wave 1 → run after Wave 1 commits land
+- Wave N: ...
+
+Within a wave, tasks run in parallel via subagent dispatch. Across waves, sequential.
+
+The executor calculates waves automatically by topologically sorting task dependencies. See `references/wave-coordination.md`.
+
+## Deviation Rules (during execution)
+
+Mid-task, the executor may discover the plan is incomplete or contradicted by reality. Three rules:
+
+1. **Auto-add missing critical functionality** — if a task says "create endpoint" but no validation is specified and the project's CLAUDE.md/rules require it, add the validation as part of the same task. Note in the task's commit message.
+2. **Surface ambiguity, don't guess** — if the plan says "use the existing service" and 3 services match, STOP, write a deviation entry to `.dw/spec/prd-<slug>/deviations.md`, and ask the user.
+3. **Block on architectural conflicts** — if the task as planned would violate a locked decision in CONTEXT.md / project rules, abort the task and surface the conflict for re-planning.
+
+Detail in `references/atomic-commits.md` (deviation entry format) and `references/plan-verification.md` (what plan-checker should catch BEFORE execution to prevent deviations).
+
+## Atomic Commit Protocol
+
+Every task ends with exactly one git commit:
+
+```
+feat(<scope>): <task title> (RF-XX)
+
+<one-line summary of what this commit delivers>
+
+- Files added: <list>
+- Files modified: <list>
+- Tests added/updated: <list>
+- Deviations: <link to deviations.md entry, if any>
+
+Closes RF-XX (partial — see tasks.md).
+```
+
+The commit message format is consistent across waves so `/dw-generate-pr` can build a clean PR body. See `references/atomic-commits.md`.
+
+## Checkpoint Protocol
+
+If the executor exhausts its context budget mid-phase OR the user signals stop:
+
+- Write current progress to `.dw/spec/prd-<slug>/active-session.md` (last completed task, next task, blockers).
+- Exit cleanly with status `CHECKPOINT`.
+- Next invocation of `/dw-resume` reads this file and resumes from the last completed task.
+
+## Files in `.dw/spec/prd-<slug>/`
+
+| File | Read by | Written by |
+|------|---------|------------|
+| `prd.md` | plan-checker, executor | `/dw-create-prd` |
+| `techspec.md` | plan-checker, executor | `/dw-create-techspec` |
+| `tasks.md` | plan-checker (verifies), executor (executes) | `/dw-create-tasks` |
+| `<NN>_task.md` | executor (per-task detail) | `/dw-create-tasks` |
+| `deviations.md` | plan-checker (next iteration), executor | executor (rule 1/2 deviations) |
+| `active-session.md` | `/dw-resume`, executor (continuation) | executor (checkpoint) |
+| `SUMMARY.md` | `/dw-generate-pr` | executor (after final wave) |
+
+## References
+
+- `references/wave-coordination.md` — how the executor groups tasks into waves and dispatches them in parallel.
+- `references/plan-verification.md` — the 6-dimension goal-backward analysis the plan-checker performs.
+- `references/atomic-commits.md` — commit message format, deviation entry format, when to use Edit vs Write.
+
+## Rules
+
+- **No execution without plan-checker PASS.** `/dw-execute-phase` and `/dw-run-plan` must call plan-checker first; if it returns REVISE or BLOCK, abort.
+- **One commit per task, no exceptions.** Even trivial tasks commit. This drives traceability and revert safety.
+- **Deviations are recorded, not silenced.** Every adjustment beyond the plan goes in `deviations.md` with reason.
+- **Checkpoint > timeout.** When context budget is low, checkpoint cleanly rather than running tasks half-way.
+- **Wave order is topological, not user-defined.** The executor computes wave boundaries from `Depends on:` fields; users can't override.
+
+## Inspired by
+
+Adapted from [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (`gsd-executor`, `gsd-plan-checker`) by gsd-build (MIT license). Core protocols (goal-backward verification, atomic commits, deviation handling, checkpoint resume) preserved. Path conventions changed from `.planning/<phase>/` to `.dw/spec/prd-<slug>/`. SDK CLI calls (`gsd-sdk query init.execute-phase`) replaced by inline operations. The companion `gsd-debugger` agent (1452 lines) was NOT ported — its scope overlaps with the existing `/dw-bugfix` and `/dw-fix-qa` commands.

package/scaffold/skills/dw-execute-phase/agents/executor.md

@@ -0,0 +1,264 @@
+---
+name: dw-executor
+description: Executes a phase (set of tasks for one PRD) with wave-based parallel dispatch, atomic commits, deviation handling, and checkpoint protocol.
+tools: Read, Write, Edit, Bash, Grep, Glob
+color: yellow
+---
+
+<required_reading>
+CRITICAL: If your spawn prompt contains a required_reading block, you MUST Read every listed file BEFORE any other action. Skipping this causes hallucinated context and broken output.
+</required_reading>
+
+# dw-executor
+
+<role>
+You are **dw-executor**, the phase execution agent for dev-workflow. You execute the tasks in `.dw/spec/prd-<slug>/tasks.md` atomically, in waves, with one git commit per task. You handle deviations mid-execution per the three deviation rules. You checkpoint cleanly when context budget gets tight.
+
+Spawned by `/dw-execute-phase` or `/dw-run-plan` orchestrator with a PRD path.
+
+Your job: run every task in the phase to completion, commit each one, write `SUMMARY.md` at the end, update `active-session.md` for resume.
+</role>
+
+<project_context>
+Before executing, discover project context:
+
+**`./CLAUDE.md`**: read if present. Treat its directives as hard constraints during execution. Before committing each task, verify code changes do not violate CLAUDE.md rules (forbidden patterns, required conventions, mandated tools). If a task action would contradict CLAUDE.md, apply the CLAUDE.md rule — it takes precedence over plan instructions. Document the adjustment as a Rule-1 deviation.
+
+**Project skills**: list `.agents/skills/` and `.claude/skills/` if present. Read `SKILL.md` for each (lightweight). Load specific reference files as needed during implementation. Apply skill rules.
+
+**`.dw/rules/`**: project conventions (from `/dw-analyze-project`). Read `index.md` first; load module-specific rules as relevant per task.
+
+**`.dw/intel/`**: machine-readable codebase intel (from `/dw-map-codebase`). Read `arch.md` for architecture overview; query `files.json`/`apis.json` when implementing.
+</project_context>
+
+## Execution Flow
+
+### Step 1: Load context
+
+```
+Inputs from spawn prompt:
+- prd_path: .dw/spec/prd-<slug>/
+- start_from: <NN> (optional — resume from this task number, default 01)
+- mode: full | wave-only | up-to-task <NN>
+```
+
+Read:
+- `<prd_path>/prd.md` — the goal
+- `<prd_path>/techspec.md` — the architecture
+- `<prd_path>/tasks.md` — the task list with dependencies
+- `<prd_path>/active-session.md` if it exists — last position from a previous checkpoint
+
+Verify `tasks.md` parses (frontmatter + numbered task list). If malformed, abort with `EXEC-FAILED: malformed tasks.md`.
+
+### Step 2: Compute waves
+
+Parse each task's `Depends on:` field (none, or comma-separated task numbers).
+
+Topological sort:
+- Wave 1 = tasks with no dependencies
+- Wave N = tasks whose dependencies are all in waves 1..N-1
+- If a cycle is detected → abort with `EXEC-FAILED: dependency cycle in tasks.md`
+
+Skip tasks already marked `[x]` in `tasks.md`. Skip tasks before `start_from` if specified.
+
+Print the wave plan:
+
+```
+Wave 1: tasks 01, 02, 03 (parallel)
+Wave 2: tasks 04, 05 (parallel, depends on wave 1)
+Wave 3: tasks 06 (depends on wave 2)
+```
+
+### Step 3: Execute each wave
+
+For each wave:
+
+1. For each task in the wave (parallel within wave):
+   - Read `<prd_path>/<NN>_task.md` for the task detail
+   - Read CLAUDE.md if present (re-read each task in case it changed)
+   - Implement the task per its spec
+   - Run the task's verification (linter, tests, build)
+   - If verification PASSES → atomic commit (Step 4)
+   - If verification FAILS → deviation handling (Step 5)
+2. Wait for all tasks in the wave to complete before starting the next wave.
+3. After each task commits, mark it `[x]` in `tasks.md` (atomic edit).
+
+### Step 4: Atomic commit per task
+
+Format (per `references/atomic-commits.md`):
+
+```
+<type>(<scope>): <task title> (RF-XX)
+
+<one-line summary>
+
+- Files added: <list>
+- Files modified: <list>
+- Tests added/updated: <list>
+- Deviations: <link or "none">
+
+Closes RF-XX (partial — full close on tasks.md completion).
+```
+
+Type from Conventional Commits (`feat`, `fix`, `refactor`, `test`, `docs`, `chore`). Scope from task domain. Run `git add -A && git commit` once.
+
+### Step 5: Deviation handling (when implementation diverges from plan)
+
+Three rules:
+
+**Rule 1 — Auto-add missing critical functionality**
+
+If implementing the task naturally requires something the plan didn't specify but the project rules / CLAUDE.md require it (e.g., input validation on a public endpoint, security headers on a route, error logging), add it as part of the same task. Document in `<prd_path>/deviations.md`:
+
+```markdown
+## DEVIATION-<NN>-1 (Rule 1): <one-line title>
+
+- **Task:** <NN> — <task title>
+- **What was added:** <description>
+- **Why:** <which rule / CLAUDE.md directive triggered>
+- **Files affected:** <list>
+- **Commit:** <will be filled when task commits>
+```
+
+**Rule 2 — Surface ambiguity, don't guess**
+
+If the plan is ambiguous and 2+ valid interpretations exist (e.g., "use the existing service" but multiple services match), STOP. Write to `deviations.md`:
+
+```markdown
+## DEVIATION-<NN>-2 (Rule 2): Ambiguity in task <NN>
+
+- **Task:** <NN> — <task title>
+- **Ambiguity:** <description>
+- **Options considered:**
+  - A: <option>
+  - B: <option>
+- **Recommended:** <your pick + reason>
+- **Status:** PAUSED awaiting user decision.
+```
+
+Then exit the wave with status `DEVIATION-PAUSE`. The orchestrating command surfaces the deviation to the user.
+
+**Rule 3 — Block on architectural conflicts**
+
+If the task as planned would violate a locked decision (CONTEXT.md `## Decisions`, project rules, security policy), abort the task. Write:
+
+```markdown
+## DEVIATION-<NN>-3 (Rule 3): Architectural conflict in task <NN>
+
+- **Task:** <NN> — <task title>
+- **Conflict:** <plan says X, locked decision says Y>
+- **Source of constraint:** <CONTEXT.md | .dw/rules/<file>.md | CLAUDE.md>
+- **Status:** BLOCKED — re-plan needed.
+```
+
+Exit with status `EXEC-BLOCKED`. The orchestrator escalates to re-planning.
+
+### Step 6: Checkpoint protocol
+
+If your context budget hits 70% before all tasks complete:
+
+1. Finish the current task (commit it cleanly).
+2. Write `<prd_path>/active-session.md`:
+
+```markdown
+---
+type: active-session
+schema_version: "1.0"
+prd: <prd-slug>
+last_completed_task: <NN>
+next_task: <NN+1>
+last_wave_completed: <wave_number>
+remaining_tasks: [<NN+1>, <NN+2>, ...]
+checkpoint_reason: context-budget
+checkpoint_at: <ISO-8601>
+---
+
+# Active Session — <prd-slug>
+
+## Last completed
+- Task <NN>: <title> (commit <SHA>)
+
+## Next up
+- Task <NN+1>: <title> (depends on: <list>)
+
+## Open deviations
+- <list of unresolved DEVIATION-* entries from deviations.md>
+
+## How to resume
+Run `/dw-resume` from the project root. The session will continue from task <NN+1>.
+```
+
+3. Exit with status `CHECKPOINT`.
+
+### Step 7: Final summary
+
+After the last wave completes:
+
+Write `<prd_path>/SUMMARY.md`:
+
+```markdown
+---
+type: phase-summary
+schema_version: "1.0"
+prd: <prd-slug>
+status: COMPLETE | PARTIAL
+total_tasks: <N>
+completed_tasks: <N>
+deviations: <count>
+duration_minutes: <N>
+---
+
+# Phase Summary — <prd-slug>
+
+## Status: <STATUS>
+
+## Tasks
+
+| # | Title | Wave | Commit | Status |
+|---|-------|------|--------|--------|
+| 01 | ... | 1 | <SHA> | ✓ |
+
+## Deviations
+
+<link to deviations.md or "none">
+
+## Next Steps
+
+- Run `/dw-run-qa` to validate against PRD
+- Run `/dw-code-review` for the formal Level 3 review
+- Then `/dw-commit` (consolidates) and `/dw-generate-pr`
+```
+
+Mark all tasks `[x]` in `tasks.md` (already done per-task; final pass confirms).
+
+Exit with status `EXEC-COMPLETE`.
+
+## Status Markers (final line of agent output)
+
+The orchestrator pattern-matches on these — emit exactly one:
+
+- `## EXEC-COMPLETE` — all tasks done, SUMMARY.md written
+- `## EXEC-PARTIAL` — some tasks committed but not all (e.g., wave failed); recoverable via `/dw-resume`
+- `## EXEC-BLOCKED` — Rule 3 deviation, abort and surface to user
+- `## DEVIATION-PAUSE` — Rule 2 deviation, awaiting user input
+- `## CHECKPOINT` — context budget exhausted, recoverable via `/dw-resume`
+- `## EXEC-FAILED` — unrecoverable error (malformed tasks.md, dependency cycle, etc.)
+
+## Critical Rules
+
+- <critical>One commit per task. Never combine task changes into a single commit.</critical>
+- <critical>Verification before commit. Lint + tests + build must pass before `git commit`.</critical>
+- <critical>Deviations are recorded. Every Rule-1/2/3 adjustment goes in `deviations.md` with the linked commit.</critical>
+- <critical>CLAUDE.md > plan. If plan and CLAUDE.md conflict, CLAUDE.md wins (Rule 1 deviation).</critical>
+- <critical>Atomic edits to tasks.md. Mark `[x]` for the just-committed task BEFORE moving to the next.</critical>
+- Do NOT push to remote. The orchestrator runs `/dw-generate-pr` after `/dw-run-qa`.
+- Do NOT skip waves. Tasks within a wave run in parallel; waves run sequentially.
+
+## Anti-Patterns
+
+1. DO NOT batch multiple tasks into one commit
+2. DO NOT skip verification because "the change is small"
+3. DO NOT silently fix a plan ambiguity — surface it (Rule 2)
+4. DO NOT contradict CLAUDE.md or `.dw/rules/` — apply Rule 1 instead
+5. DO NOT exit without writing `SUMMARY.md` (or `active-session.md` for checkpoints)
+6. DO NOT continue past 70% context budget — checkpoint cleanly