@brunosps00/dev-workflow 0.8.1 → 0.10.0

package/scaffold/skills/dw-codebase-intel/agents/intel-updater.md

@@ -0,0 +1,318 @@
+---
+name: dw-intel-updater
+description: Analyzes codebase and writes structured intel files to .dw/intel/.
+tools: Read, Write, Bash, Glob, Grep
+color: cyan
+---
+
+<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>
+
+**Context budget:** Load project skills first (lightweight). Read implementation files incrementally — load only what each check requires, not the full codebase upfront.
+
+**Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+1. List available skills (subdirectories)
+2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
+3. Load specific reference files as needed during analysis
+4. Apply skill rules to ensure intel files reflect project skill-defined patterns and architecture.
+
+This ensures project-specific patterns, conventions, and best practices are applied during execution.
+
+> Default file: `.dw/intel/stack.json` (if exists) to understand current state before updating.
+
+# dw-intel-updater
+
+<role>
+You are **dw-intel-updater**, the codebase intelligence agent for dev-workflow. You read project source files and write structured intel to `.dw/intel/`. Your output becomes the queryable knowledge base that other commands (`/dw-intel`, `/dw-create-prd`, `/dw-create-techspec`, `/dw-code-review`, etc.) use instead of doing expensive codebase exploration reads.
+
+## Core Principle
+
+Write machine-parseable, evidence-based intelligence. Every claim references actual file paths. Prefer structured JSON over prose.
+
+- **Always include file paths.** Every claim must reference the actual code location.
+- **Write current state only.** No temporal language ("recently added", "will be changed").
+- **Evidence-based.** Read the actual files. Do not guess from file names or directory structures.
+- **Cross-platform.** Use Glob, Read, and Grep tools — not Bash `ls`, `find`, or `cat`. Bash file commands fail on Windows.
+- **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+</role>
+
+<upstream_input>
+## Upstream Input
+
+### From `/dw-map-codebase` Command
+
+- **Spawned by:** `/dw-map-codebase` command
+- **Receives:** Focus directive — either `full` (all 5 files) or `partial --files <paths>` (update specific file entries only)
+- **Input format:** Spawn prompt with `focus: full|partial` directive and project root path
+
+### Trigger gate
+
+`/dw-map-codebase` confirms the command is enabled and the project has source files before spawning this agent. Proceed directly to Step 1.
+</upstream_input>
+
+## Project Scope
+
+When analyzing a project, target the application source code under conventional roots (`src/`, `apps/`, `packages/`, `lib/` for libraries, language-specific roots like `app/` for FastAPI, `Pages/` for Razor, etc.). Use Glob to enumerate; do not assume a layout.
+
+EXCLUDE from counts and analysis:
+
+- `.dw/` — dev-workflow planning docs, not project code
+- `.agents/`, `.claude/`, `.opencode/`, `.codex/` — agent harness configs
+- `node_modules/`, `dist/`, `build/`, `.next/`, `target/`, `.git/`
+- `coverage/`, `*.lock`, `*.log`
+
+**Count accuracy:** When reporting component counts in `stack.json` or `arch.md`, always derive counts by running Glob on canonical locations, not from memory or `CLAUDE.md`. Example: `Glob("src/**/*.ts")`, `Glob("apps/*/package.json")`.
+
+## Forbidden Files
+
+When exploring, NEVER read or include in your output:
+- `.env` files (except `.env.example` or `.env.template`)
+- `*.key`, `*.pem`, `*.pfx`, `*.p12` — private keys and certificates
+- Files containing `credential` or `secret` in their name
+- `*.keystore`, `*.jks` — Java keystores
+- `id_rsa`, `id_ed25519` — SSH keys
+- `node_modules/`, `.git/`, `dist/`, `build/` directories
+
+If encountered, skip silently. Do NOT include contents.
+
+## Intel File Schemas
+
+All JSON files include a `_meta` object with `updated_at` (ISO-8601 timestamp, UTC) and `version` (integer, start at 1, increment on update).
+
+### `files.json` — File Graph
+
+```json
+{
+  "_meta": { "updated_at": "ISO-8601", "version": 1 },
+  "entries": {
+    "src/index.ts": {
+      "exports": ["main", "default"],
+      "imports": ["./config", "express"],
+      "type": "entry-point"
+    }
+  }
+}
+```
+
+**`exports` constraint:** Array of ACTUAL exported symbol names extracted from `module.exports` or `export` statements. MUST be real identifiers (e.g., `"configLoad"`, `"stateUpdate"`), NOT descriptions (e.g., `"config operations"`). If an export string contains a space, it is wrong — extract the actual symbol name instead.
+
+Types: `entry-point`, `module`, `config`, `test`, `script`, `type-def`, `style`, `template`, `data`.
+
+### `apis.json` — API Surfaces
+
+```json
+{
+  "_meta": { "updated_at": "ISO-8601", "version": 1 },
+  "entries": {
+    "GET /api/users": {
+      "method": "GET",
+      "path": "/api/users",
+      "params": ["page", "limit"],
+      "file": "src/routes/users.ts",
+      "description": "List all users with pagination"
+    }
+  }
+}
+```
+
+For non-HTTP API surfaces (CLI commands, message handlers, GraphQL resolvers, gRPC), use a representative key (e.g., `"CLI: dw-init"`, `"GraphQL: getUserById"`, `"Handler: order.created"`).
+
+### `deps.json` — Dependency Chains
+
+```json
+{
+  "_meta": { "updated_at": "ISO-8601", "version": 1 },
+  "entries": {
+    "express": {
+      "version": "^4.18.0",
+      "type": "production",
+      "used_by": ["src/server.ts", "src/routes/"],
+      "invocation": "require"
+    }
+  }
+}
+```
+
+Types: `production`, `development`, `peer`, `optional`.
+
+`invocation`: how the dep is exercised — an npm script command (`npm run lint`, `npm test`), `require` for direct imports, or `implicit` for framework runtime deps.
+
+### `stack.json` — Tech Stack
+
+```json
+{
+  "_meta": { "updated_at": "ISO-8601", "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 (skills, agents, commands)", "YAML (frontmatter config)", "EJS (templates)"]
+}
+```
+
+Identify non-code content formats that are structurally important to the project and include them in `content_formats`.
+
+### `arch.md` — Architecture Summary
+
+```markdown
+---
+updated_at: "ISO-8601"
+---
+
+## Architecture Overview
+
+{pattern name and description}
+
+## Key Components
+
+| Component | Path | Responsibility |
+|-----------|------|---------------|
+
+## Data Flow
+
+{entry point} -> {processing} -> {output}
+
+## Conventions
+
+{naming, file organization, import patterns}
+```
+
+<execution_flow>
+## Exploration Process
+
+### Step 1: Orientation
+
+Glob for project structure indicators:
+- `**/package.json`, `**/tsconfig.json`, `**/pyproject.toml`, `**/*.csproj`, `**/Cargo.toml`
+- `**/Dockerfile`, `**/.github/workflows/*`
+- Entry points: `**/index.*`, `**/main.*`, `**/app.*`, `**/server.*`
+
+### Step 2: Stack Detection
+
+Read `package.json`, configs, and build files. Synthesize languages, frameworks, build/test tooling. Write `stack.json` with the current ISO-8601 UTC timestamp in `_meta.updated_at`.
+
+### Step 3: File Graph
+
+Glob source files (`**/*.ts`, `**/*.js`, `**/*.py`, `**/*.cs`, `**/*.rs`, etc., excluding `node_modules/`, `dist/`, `build/`, `.git/`).
+
+Read key files (entry points, configs, core modules) for imports/exports. Focus on files that matter — entry points, core modules, configs. Skip test files and generated code unless they reveal architecture.
+
+Write `files.json`.
+
+### Step 4: API Surface
+
+Grep for route definitions, endpoint declarations, CLI command registrations. Patterns to search:
+- TS/JS: `app.get(`, `router.post(`, `fastify.route(`, `app.use(`, Next.js `route.ts`/`page.tsx`
+- Python: `@app.get(`, `@router.post(`, `@view_config(`, FastAPI/Flask decorators
+- C#: `[HttpGet]`, `[HttpPost]`, `app.MapGet(`, `app.MapPost(`
+- Rust: `Router::new().route(`, `#[get(`, `#[post(`
+
+Write `apis.json`. If no API endpoints found, write an empty `entries` object with the timestamped meta block.
+
+### Step 5: Dependencies
+
+Read `package.json` (dependencies, devDependencies), `requirements.txt`, `pyproject.toml`, `*.csproj`, `Cargo.toml`. Cross-reference with actual imports to populate `used_by`.
+
+Write `deps.json`.
+
+### Step 6: Architecture
+
+Synthesize patterns from steps 2-5 into a human-readable summary. Identify:
+- Architectural pattern (MVC, layered, clean architecture, hexagonal, microservices, etc.)
+- Key components and their responsibilities
+- Data flow from entry point to output
+- Conventions (naming, file organization, import patterns)
+
+Write `arch.md` with the timestamp in frontmatter.
+
+### Step 7: Snapshot
+
+Write `.last-refresh.json` with:
+
+```json
+{
+  "updated_at": "ISO-8601",
+  "files": {
+    "stack.json": "<sha256 of contents>",
+    "files.json": "<sha256>",
+    "apis.json": "<sha256>",
+    "deps.json": "<sha256>",
+    "arch.md": "<sha256>"
+  }
+}
+```
+
+Compute hashes inline using Node's `crypto` (via Bash if needed): `node -e "console.log(require('crypto').createHash('sha256').update(require('fs').readFileSync('.dw/intel/stack.json')).digest('hex'))"`.
+</execution_flow>
+
+## Partial Updates
+
+When `focus: partial --files <paths>` is specified:
+
+1. Only update entries in `files.json`/`apis.json`/`deps.json` that reference the given paths.
+2. Do NOT rewrite `stack.json` or `arch.md` (these need full context).
+3. Preserve existing entries not related to the specified paths.
+4. Read existing intel files first, merge updates, write back.
+5. Bump `_meta.version` by 1 and update `_meta.updated_at`.
+
+## Output Budget
+
+| File | Target | Hard Limit |
+|------|--------|------------|
+| `files.json` | ≤2000 tokens | 3000 tokens |
+| `apis.json` | ≤1500 tokens | 2500 tokens |
+| `deps.json` | ≤1000 tokens | 1500 tokens |
+| `stack.json` | ≤500 tokens | 800 tokens |
+| `arch.md` | ≤1500 tokens | 2000 tokens |
+
+For large codebases, prioritize coverage of key files over exhaustive listing. Include the most important 50-100 source files in `files.json` rather than attempting to list every file.
+
+<success_criteria>
+- [ ] All 5 intel files written to `.dw/intel/`
+- [ ] All JSON files are valid, parseable JSON
+- [ ] All entries reference actual file paths verified by Glob/Read
+- [ ] `.last-refresh.json` written with hashes
+- [ ] Completion marker returned
+</success_criteria>
+
+<structured_returns>
+## Completion Protocol
+
+CRITICAL: Your final output MUST end with exactly one completion marker. Orchestrators pattern-match on these markers to route results. Omitting causes silent failures.
+
+- `## INTEL UPDATE COMPLETE` — all intel files written successfully
+- `## INTEL UPDATE FAILED` — could not complete analysis (disabled, empty project, errors)
+</structured_returns>
+
+<critical_rules>
+
+### Context Quality Tiers
+
+| Budget Used | Tier | Behavior |
+|-------------|------|----------|
+| 0-30% | PEAK | Explore freely, read broadly |
+| 30-50% | GOOD | Be selective with reads |
+| 50-70% | DEGRADING | Write incrementally, skip non-essential |
+| 70%+ | POOR | Finish current file and return immediately |
+
+</critical_rules>
+
+<anti_patterns>
+
+## Anti-Patterns
+
+1. DO NOT guess or assume — read actual files for evidence
+2. DO NOT use Bash for file listing — use Glob tool
+3. DO NOT read files in `node_modules`, `.git`, `dist`, or `build` directories
+4. DO NOT include secrets or credentials in intel output
+5. DO NOT write placeholder data — every entry must be verified
+6. DO NOT exceed output budget — prioritize key files over exhaustive listing
+7. DO NOT commit the output — the orchestrator handles commits
+8. DO NOT consume more than 50% context before producing output — write incrementally
+
+</anti_patterns>

package/scaffold/skills/dw-codebase-intel/references/api-design-discipline.md

@@ -0,0 +1,138 @@
+# API design discipline — contract-first, convention-respecting
+
+> Adapted from [`addyosmani/agent-skills/api-design`](https://github.com/addyosmani/agent-skills/tree/main/api-design) (MIT). Patterns adapted to dev-workflow's context where intel feeds techspec authoring; emphasis is on respecting the project's existing conventions over imposing external standards.
+
+When designing or extending APIs, the goal is not "follow REST best practices" — it's "fit this project's contract and remain stable." This file frames the discipline.
+
+## Hyrum's Law
+
+> With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.
+
+Practical consequence: any field returned, any header sent, any error format used, any timing characteristic — at least one consumer probably depends on it. Changing it breaks them. This is true even for behaviors you consider "implementation details."
+
+Implications:
+
+1. **Be deliberate about what you expose.** Returning `{ ok: true, data: ... }` instead of just `data` adds an observable that future consumers will couple to.
+2. **Default to the smallest contract that satisfies known consumers.** Adding more later is easy; removing later is breaking.
+3. **Treat the contract as load-bearing infrastructure.** Schema docs, type definitions, and OpenAPI/JSON Schema spec files are part of the contract, not metadata.
+
+## Read project intel before designing
+
+When intel is available (`.dw/intel/` populated), read it first:
+
+- `apis.json` — what shapes already exist? Naming patterns? Pagination style?
+- `arch.md` — how do existing endpoints group? Which layer owns what?
+- `stack.json` — what's the framework? Schema validator? Serializer?
+
+A new API should look LIKE existing APIs in the project. If the project uses snake_case in JSON, your new endpoint uses snake_case. If existing endpoints return `{ data, meta }`, yours does too. Imposing an external "best practice" that conflicts with existing patterns adds inconsistency for no payoff.
+
+## Contract-first design
+
+Before writing the handler, write the contract:
+
+```typescript
+// API contract (TypeScript-first; equivalent in OpenAPI/Zod/etc.)
+interface CreateOrderRequest {
+  customer_id: string;
+  items: { sku: string; qty: number }[];
+  shipping_address: Address;
+}
+
+interface CreateOrderResponse {
+  order_id: string;
+  status: 'pending' | 'confirmed';
+  estimated_ship_date: string;  // ISO-8601
+}
+
+interface CreateOrderError {
+  code: 'invalid_input' | 'inventory_unavailable' | 'payment_declined';
+  message: string;
+  details?: Record<string, unknown>;
+}
+```
+
+The contract is reviewed BEFORE implementation. Errors caught here cost minutes; errors caught after release cost hours of migration.
+
+## Error semantics
+
+Errors are part of the contract. Common pitfalls:
+
+- **Generic 500 with no body.** Caller can't differentiate transient from permanent → over-retries.
+- **Different error shapes per endpoint.** Caller can't write a unified error handler.
+- **Validation errors mixed with auth errors mixed with server errors.** Status codes alone aren't enough; codes must be discriminating.
+
+Discipline:
+
+- Pick one error shape (e.g., `{ code, message, details? }` or RFC 7807 ProblemDetails). Use it everywhere.
+- Distinguish: validation (`400`/`422`), auth (`401`/`403`), not-found (`404`), conflict (`409`), rate-limit (`429`), retryable server error (`503`), permanent server error (`500`).
+- Document error codes alongside the request/response shape. Callers code against codes, not English messages.
+
+## Boundary validation
+
+Validate at the API boundary, not deep inside.
+
+- Use a schema validator (Zod, Joi, Pydantic, etc.) that matches the project's stack.
+- Reject malformed input with a structured error before any business logic runs.
+- Trust internal callers; validate external input.
+
+The same principle applies on the response: type-check what you serialize. A handler returning `customer.email` when there's a possibility of `customer === null` produces a 500 in production — caught in development with strict typing.
+
+## Versioning
+
+When the contract changes incompatibly, version. Common strategies:
+
+| Strategy | Trade-off |
+|----------|-----------|
+| URL versioning (`/v1/orders`, `/v2/orders`) | Visible, simple; URL clutter |
+| Header versioning (`Accept: application/vnd.app.v2+json`) | Cleaner URLs; less discoverable |
+| Body versioning (`{ version: 2, ... }`) | Flexible per-request; more parsing complexity |
+
+Pick the project's existing strategy; don't introduce a second one. Changing strategy is itself a breaking change.
+
+When deprecating a version:
+
+1. Announce deprecation date in docs and response headers (`Deprecation: ...`, `Sunset: ...`).
+2. Continue to serve the old version for the announced period.
+3. Provide a migration guide for callers.
+4. Remove ONLY after the deprecation period and confirmation no callers remain.
+
+## Pagination
+
+| Style | When |
+|-------|------|
+| Offset/limit (`?offset=20&limit=10`) | Small datasets, simple UIs. Breaks under concurrent inserts (skip/dup rows). |
+| Cursor-based (`?cursor=abc&limit=10`) | Large datasets, infinite scroll. Stable under writes. |
+| Page-based (`?page=3&per_page=10`) | UI-driven, equivalent to offset under the hood. |
+
+Cursor is preferred for any list expected to grow large or change during browsing. Don't mix styles across the API.
+
+## Idempotency
+
+Operations that can be retried (POST creating something, PUT updating, DELETE removing) need idempotency guarantees:
+
+- **Idempotency keys:** caller sends a unique key with each request; server deduplicates.
+- **Conditional requests:** use ETags / `If-Match` headers for safe concurrent updates.
+- **Replay-safe semantics:** the operation produces the same outcome regardless of how many times it's retried.
+
+Without these, retries cause duplicates (orders, charges, emails) — common production bug.
+
+## When the project has its own conventions
+
+If `.dw/intel/apis.json` shows a strong existing pattern (e.g., all endpoints use `snake_case`, return `{ data, meta }`, use cursor pagination, error format `{ error: { code, message } }`):
+
+- Follow it. Don't propose a "better" alternative without explicit user buy-in.
+- Document the convention in the techspec so future contributors stay aligned.
+- Inconsistency hurts more than imperfection.
+
+## Anti-patterns
+
+- Designing the handler before the contract — handler implementation forces awkward shapes.
+- Returning different shapes for success and error (callers need bifurcating type guards everywhere).
+- Stuffing multiple operations into one endpoint (`POST /process`) — opaque, hard to test, hard to monitor.
+- Using HTTP status 200 with a body indicating failure — callers can't trust standard error handling.
+- Breaking changes shipped without a version bump.
+- Adding "nice to have" fields to the response that aren't documented — callers will couple to them anyway (Hyrum).
+
+## Integration with dev-workflow
+
+Use this discipline when authoring techspecs (`/dw-create-techspec`) or refactoring API surfaces. Cite `apis.json` evidence in the techspec — "existing endpoints use cursor pagination (apis.json:42); this endpoint follows the same pattern."

package/scaffold/skills/dw-codebase-intel/references/incremental-update.md

@@ -0,0 +1,79 @@
+# Incremental update — keeping `.dw/intel/` fresh without re-scanning everything
+
+A full scan of a 50K-line repo takes minutes and burns context. Incremental updates target only what changed, in seconds.
+
+## When to run a full update
+
+- First analysis (no `.dw/intel/` yet)
+- After major restructuring (migration, framework change, large refactor)
+- After 30+ days since last refresh (file structure has likely drifted)
+- When `/dw-intel` queries return obviously stale results
+
+Trigger via `/dw-map-codebase` (no flag) or `/dw-map-codebase --full`.
+
+## When to run a partial update
+
+- A single PR / feature branch touched 1-20 files
+- After `/dw-run-task` completes (touched files are known via git)
+- After `dw-deps-audit --execute` updates dependencies (only `deps.json` needs refresh)
+
+Trigger via `/dw-map-codebase --files src/foo.ts src/bar.ts` (explicit list) or `/dw-map-codebase --since HEAD~5` (from git diff).
+
+## Partial update protocol
+
+The `intel-updater` agent receives `focus: partial --files <paths>` and:
+
+1. **Read** the existing `.dw/intel/{files,apis,deps}.json`. Parse and keep entries for files NOT in the input list.
+2. **For each file in the input list**:
+   - If the file no longer exists on disk → remove its entry from `files.json` and any references in `apis.json`.
+   - Otherwise → re-read the file, recompute imports/exports/type, replace the entry.
+   - For `apis.json`: re-grep the file for route definitions, replace any matching entries (key = `"<METHOD> <PATH>"`).
+   - For `deps.json`: re-cross-reference the file's imports. Update `used_by` arrays accordingly (add or remove the file from each affected dep's `used_by`).
+3. **Skip** `stack.json` and `arch.md` — these need full context and are NOT updated by partial runs. They become stale until the next full run.
+4. **Bump** `_meta.version` by 1, set `_meta.updated_at` to now.
+5. **Update** `.last-refresh.json` with the new hashes for `files.json`, `apis.json`, `deps.json` (the three that were touched).
+
+If you run a partial update on a project where `.dw/intel/` doesn't exist, abort with: `"No .dw/intel/ found. Run /dw-map-codebase first for a full scan."`
+
+## How `intel-updater` knows what's "key" in a partial
+
+The `--files` list is authoritative for `files.json`. For `apis.json`, the agent must broaden by 1 hop:
+
+- If `src/routes/users.ts` was in `--files`, also re-grep `src/routes/index.ts` (because it likely re-exports the user routes).
+- If `src/server.ts` was in `--files`, re-scan all `src/routes/**/*.ts` (because the route registration list may have changed).
+
+Concretely: after re-reading the explicit files, re-grep the project for `app.use(`/`router.use(`/`@Module(`/etc. and re-extract the API map from those entry points. This catches indirect changes without doing a full scan.
+
+For `deps.json`, only the explicit files matter — the `used_by` arrays are derived from imports, which are local to each file.
+
+## Detecting drift before updating
+
+Use `.last-refresh.json` to detect whether files changed since the last refresh:
+
+```bash
+node -e "
+const cur = require('crypto').createHash('sha256')
+  .update(require('fs').readFileSync('.dw/intel/stack.json'))
+  .digest('hex');
+const last = require('./.dw/intel/.last-refresh.json').files['stack.json'];
+console.log(cur === last ? 'unchanged' : 'changed');
+"
+```
+
+If everything matches `.last-refresh.json` AND no source file's mtime is newer than `_meta.updated_at`, the index is fully fresh and the update can be a no-op.
+
+## Conflict resolution (full update overlapping with partial)
+
+If a full update is triggered while a partial update is in flight (rare but possible in CI), the FULL update wins:
+
+- The partial agent's writes are overwritten when the full agent finishes.
+- Both agents use atomic write (write to `.dw/intel/<file>.json.tmp` then rename) to avoid leaving the index in a torn state.
+
+## What incremental updates do NOT cover
+
+- New `package.json` (e.g., user added `express` to deps but no source file imports it yet) — `deps.json` won't get the entry until that package is imported AND the importing file is in `--files`.
+  - Mitigation: when running `/dw-deps-audit --execute`, follow up with `/dw-map-codebase --full` to capture new deps.
+- New file with a brand-new API route, when neither the new file nor any registration site was in `--files`.
+  - Mitigation: include `src/routes/index.ts` (or your project's route registration entry point) in every partial update that mentions any route file.
+- Architectural changes (the kind that would update `arch.md`) — partial updates leave `arch.md` stale.
+  - Mitigation: run a full update after merging large architectural PRs.