@brunosps00/dev-workflow 0.8.1 → 0.9.0

package/scaffold/skills/dw-codebase-intel/references/intel-format.md

@@ -0,0 +1,208 @@
+# Intel format — schemas of `.dw/intel/` files
+
+Every command that reads `.dw/intel/` depends on these schemas. Treat this file as the contract.
+
+## Layout
+
+```
+.dw/intel/
+├── stack.json           # languages, frameworks, build/test tooling
+├── files.json           # per-file imports/exports/type
+├── apis.json            # routes, endpoints, CLI commands
+├── deps.json            # third-party dependencies + usage
+├── arch.md              # architectural overview (markdown)
+└── .last-refresh.json   # change detection (timestamps + sha256 hashes)
+```
+
+## Common `_meta` block (all JSON files)
+
+```json
+{
+  "_meta": {
+    "updated_at": "2026-05-06T12:34:56.789Z",
+    "version": 3
+  }
+}
+```
+
+- `updated_at`: ISO-8601 UTC timestamp, set on every write
+- `version`: integer, starts at 1, increments on every update (full or partial)
+
+## `stack.json`
+
+```json
+{
+  "_meta": { "updated_at": "...", "version": 1 },
+  "languages": ["TypeScript", "JavaScript"],
+  "frameworks": ["Express", "React"],
+  "tools": ["ESLint", "Jest", "Docker"],
+  "build_system": "npm scripts",
+  "test_framework": "Jest",
+  "package_manager": "npm",
+  "content_formats": ["Markdown", "YAML", "EJS"]
+}
+```
+
+Field rules:
+- `languages`: ordered by line count (most-prevalent first)
+- `frameworks`: full names (no abbreviations) — `"Next.js"` not `"next"`
+- `tools`: dev tooling that affects code shape (linter, formatter, bundler, container runtime)
+- `build_system`: detected from manifest (`npm scripts`, `Vite`, `webpack`, `esbuild`, `dotnet`, `cargo`, etc.)
+- `test_framework`: detected from manifest (`Jest`, `Vitest`, `Pytest`, `xUnit`, `cargo test`, etc.); `"none"` if no test setup detected
+- `package_manager`: from lockfile (`npm`, `pnpm`, `yarn`, `poetry`, `uv`, `dotnet`, `cargo`)
+- `content_formats`: non-code formats with structural significance (markdown for docs/skills, YAML for configs, JSON Schema, OpenAPI, Protobuf, etc.)
+
+## `files.json`
+
+```json
+{
+  "_meta": { "updated_at": "...", "version": 1 },
+  "entries": {
+    "src/server.ts": {
+      "exports": ["createServer", "default"],
+      "imports": ["./config", "express", "./routes/users"],
+      "type": "entry-point"
+    },
+    "src/routes/users.ts": {
+      "exports": ["userRouter"],
+      "imports": ["express", "../db", "../schemas/user"],
+      "type": "module"
+    }
+  }
+}
+```
+
+Field rules:
+- Key: file path relative to project root, forward slashes
+- `exports`: array of ACTUAL exported symbol names. NOT descriptions. `["createServer", "default"]` is correct; `["server creation"]` is wrong.
+- `imports`: array of import specifiers (relative paths or package names) — preserve as the source code writes them
+- `type`: one of `entry-point`, `module`, `config`, `test`, `script`, `type-def`, `style`, `template`, `data`
+
+Coverage: target the most important 50-100 files. Skip generated code, test files (unless they reveal architecture), `node_modules/dist/build`.
+
+## `apis.json`
+
+```json
+{
+  "_meta": { "updated_at": "...", "version": 1 },
+  "entries": {
+    "GET /api/users": {
+      "method": "GET",
+      "path": "/api/users",
+      "params": ["page", "limit"],
+      "file": "src/routes/users.ts",
+      "description": "List users with pagination"
+    },
+    "CLI: dw-init": {
+      "method": "CLI",
+      "path": "dev-workflow init",
+      "params": ["--lang", "--force"],
+      "file": "bin/dev-workflow.js",
+      "description": "Scaffold .dw/ structure into a project"
+    }
+  }
+}
+```
+
+Field rules:
+- Key format: `"<METHOD> <PATH>"` for HTTP, `"CLI: <command>"` for CLI, `"GraphQL: <operation>"`, `"Handler: <event>"`, etc.
+- `method`: HTTP verb, or `"CLI"`, `"GraphQL"`, `"gRPC"`, `"Event"`, `"Subscription"`
+- `path`: the route/command/operation name
+- `params`: query/body/CLI flag names — array of strings
+- `file`: source path
+- `description`: one-line summary derived from the handler's first comment or function name
+
+If no API surfaces detected, write `{ "_meta": {...}, "entries": {} }` — never omit the file.
+
+## `deps.json`
+
+```json
+{
+  "_meta": { "updated_at": "...", "version": 1 },
+  "entries": {
+    "express": {
+      "version": "^4.18.0",
+      "type": "production",
+      "used_by": ["src/server.ts", "src/routes/users.ts"],
+      "invocation": "require"
+    },
+    "vitest": {
+      "version": "^2.0.0",
+      "type": "development",
+      "used_by": ["package.json#test"],
+      "invocation": "npm test"
+    }
+  }
+}
+```
+
+Field rules:
+- Key: package name (npm), distribution name (PyPI), package id (NuGet), crate name (crates.io)
+- `version`: semver range from manifest
+- `type`: `production` | `development` | `peer` | `optional`
+- `used_by`: array of file paths that import the dep (verified by Grep) OR npm-script keys for tooling deps
+- `invocation`:
+  - `require` if directly imported in code
+  - npm script command (`npm run lint`, `npm test`) if exercised via script
+  - `implicit` if a runtime/framework dep that's not directly imported (e.g., `react-dom` in a Next.js project)
+
+## `arch.md`
+
+```markdown
+---
+updated_at: "2026-05-06T12:34:56.789Z"
+---
+
+## Architecture Overview
+
+The project follows a layered architecture: HTTP routes → application services → repository layer → ORM → database.
+
+## Key Components
+
+| Component | Path | Responsibility |
+|-----------|------|----------------|
+| Server bootstrap | `src/server.ts` | Express app initialization + middleware wiring |
+| Route handlers | `src/routes/` | HTTP request validation and response shaping |
+| Application services | `src/services/` | Business logic, orchestration |
+| Repositories | `src/repositories/` | Data access via Prisma |
+| Schemas | `src/schemas/` | Zod validation schemas, shared with frontend |
+
+## Data Flow
+
+`HTTP request` → `route handler (validates with Zod)` → `service` → `repository (Prisma)` → `Postgres` → response
+
+## Conventions
+
+- File naming: kebab-case (`user-routes.ts`, `order-service.ts`)
+- Function naming: camelCase, verb-first (`createOrder`, `findUserById`)
+- Tests: co-located, `.test.ts` suffix
+- Imports: absolute via `@/` alias for cross-module, relative for sibling files
+```
+
+## `.last-refresh.json`
+
+```json
+{
+  "updated_at": "2026-05-06T12:34:56.789Z",
+  "files": {
+    "stack.json": "a3c8b1...",
+    "files.json": "f9e2d7...",
+    "apis.json": "1b4f8a...",
+    "deps.json": "5c2e6b...",
+    "arch.md": "9d7c3e..."
+  }
+}
+```
+
+Hashes are SHA-256 of file contents at the moment of refresh. Used by `/dw-map-codebase` to detect drift on the next run and decide whether a partial update is enough.
+
+## Validation rules
+
+When `intel-updater` finishes, all 5 files MUST satisfy:
+
+1. Valid JSON (parseable)
+2. `_meta.updated_at` is ISO-8601
+3. `_meta.version` is a positive integer
+4. All file paths in `files.json`, `apis.json`, `deps.json` exist on disk (or were excluded for known reasons)
+5. `exports` arrays contain only actual symbols (no descriptions, no spaces in entries)
+6. No secrets/credentials/tokens in any file

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.