@brunosps00/dev-workflow 0.4.5 → 0.5.0

package/scaffold/skills/dw-council/agents/security-advocate.md

@@ -0,0 +1,48 @@
+---
+id: security-advocate
+title: The Security Advocate
+description: Threat-modeling advisor focused on attack surface, blast radius, compliance, data protection, and concrete mitigations.
+---
+
+You are **The Security Advocate**, one archetype in a Council of Advisors. You assume adversaries are competent and motivated, and you reason from threat models, blast radius, compliance obligations, and defense in depth.
+
+Your priorities, in order:
+
+1. Threat modeling (who attacks this, how, what they gain)
+2. Attack surface changes
+3. Blast radius and containment
+4. Compliance and data protection obligations
+5. Defense in depth
+
+You ask:
+- Who attacks this, and how?
+- What do they gain on success?
+- How is compromise contained?
+- Which obligations remain non-optional even under schedule pressure?
+
+Do not:
+
+- Dismiss realistic risks because mitigation is inconvenient
+- Accept "we'll add security later" without explicit risk acceptance, named owner, and trigger condition
+- Treat compliance as optional or "figure out later"
+
+When asked for an opening statement:
+
+- Identify the relevant threat model
+- Name the attack surface and blast-radius consequences
+- Recommend the minimum acceptable controls for a ship-ready path
+- End with a one-line `**Key Point:** ...`
+
+When rebutting:
+
+- Steel-man the convenience or velocity case first
+- Concede when the threat is genuinely remote and mitigation is disproportionate
+- Otherwise hold firm on the controls required to make the path acceptable, and say exactly which mitigation would move you
+
+When arguing in a dev-workflow context:
+
+- If the project has `security-review` as a bundled skill, treat its confidence-rated findings as high-signal evidence
+- Cite PRD sections that describe sensitive data or auth surfaces
+- Reference prior `QA/bugs.md` entries if security-related bugs were found before
+
+Your job is not to block delivery. Your job is to stop the council from shipping an avoidable incident.

package/scaffold/skills/dw-memory/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: dw-memory
+description: |
+  Maintains workflow-scoped memory for dev-workflow PRD runs using
+  .dw/spec/prd-<name>/MEMORY.md (shared) and .dw/spec/prd-<name>/tasks/<N>_memory.md
+  (task-local). Use when a dev-workflow command needs to persist or recall
+  durable cross-task context (decisions, constraints, risks) across task
+  executions. Invoked from dw-run-task, dw-run-plan, dw-autopilot, and
+  dw-resume. Do not use for PR review remediation, user preferences, or
+  event-log summarization.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+---
+
+# dw-memory — Workflow Memory
+
+Two-tier memory for a PRD workflow. Callers pass the PRD slug; this skill manages the files.
+
+## Required Inputs (from caller)
+
+- PRD slug (e.g., `prd-user-auth`) → resolves to `.dw/spec/<slug>/`.
+- Current task number (1-based), e.g., `3` → task-local file is `.dw/spec/<slug>/tasks/3_memory.md`.
+- Optional flag: `compact: true|false` indicating whether either file must be compacted before proceeding.
+
+If the PRD directory or `tasks/` subdirectory does not exist, stop and report — do not guess paths.
+
+## File Layout
+
+```
+.dw/spec/<prd-slug>/
+  prd.md                          # PRD (authoritative, not memory)
+  techspec.md                     # TechSpec (authoritative)
+  tasks.md                        # task index (authoritative)
+  MEMORY.md                       # shared workflow memory (this skill)
+  tasks/
+    1_task.md
+    1_memory.md                   # task-local memory for task 1
+    2_task.md
+    2_memory.md
+    ...
+```
+
+Create `MEMORY.md` and `<N>_memory.md` on first use with the template below. Never create any other memory files.
+
+## Templates
+
+### MEMORY.md (shared, cross-task)
+
+```
+# Workflow Memory — <PRD slug>
+
+## Current State
+- Last task completed: <N> — <one-line summary>
+- Active task: <N+1>
+- Branch: <branch-name>
+
+## Durable Decisions
+- <decision 1> — <one-line rationale>
+
+## Cross-Task Constraints
+- <constraint discovered during implementation that affects multiple tasks>
+
+## Open Risks
+- <risk> — <what would trigger it, what to watch for>
+
+## Handoff Notes
+- <what the next task or agent needs to know that is not in the PRD/TechSpec/code>
+```
+
+### <N>_memory.md (task-local)
+
+```
+# Task <N> Memory
+
+## Objective Snapshot
+<current understanding of the task objective in 1-3 lines>
+
+## Files Touched
+- path/to/file.ext — <why>
+
+## Debug Notes
+- <observation that was non-obvious to arrive at>
+
+## Workarounds Applied (task-local only)
+- <workaround> — <why justified here, not elsewhere>
+
+## Next Step
+<what to do next if interrupted>
+```
+
+## Workflow
+
+### 1. Load before editing code
+- Read `MEMORY.md` and the current task's `<N>_memory.md` **before** any code change.
+- Treat these as mandatory context for the run, not optional notes.
+- If the caller marks either file for compaction, apply the Compaction Rules (below) before continuing.
+
+### 2. Keep memory current while the task runs
+- Update `<N>_memory.md` whenever:
+  - the objective understanding changes,
+  - a non-obvious decision is made,
+  - a learning appears that the next step needs,
+  - an error reshapes the plan.
+- Promote to `MEMORY.md` only facts that pass the Promotion Test.
+- Keep operational details (files touched, debug steps, local workarounds) in `<N>_memory.md`.
+
+### 3. Close out cleanly
+- Update memory **before any completion claim, handoff, or commit** (this pairs with `dw-verify`).
+- Record only facts that help the next task start faster and with fewer mistakes.
+- If `MEMORY.md` has grown noisy or repetitive, compact it using the Compaction Rules.
+
+## Critical Rules
+
+- Do not invent history, decisions, or status.
+- Do not copy large code blocks, stack traces, or full PRD/TechSpec sections into memory files.
+- Do not duplicate facts that are obvious from the repository, `git diff`, task file, PRD, or TechSpec.
+- Do not read unrelated task memory files unless `MEMORY.md` or the caller explicitly points to them.
+- Shared memory is durable and cross-task. Task memory is local and operational.
+
+## Promotion Decision Test
+
+Before promoting an item from `<N>_memory.md` to `MEMORY.md`, ask:
+
+1. Will another task need this to avoid a mistake or rediscovery?
+2. Is this fact durable across multiple runs, not just the current execution?
+3. Is this information NOT already obvious from the PRD, TechSpec, task files, or the repository itself?
+
+All three must be "yes" to promote. If any is "no", the item stays in task memory.
+
+### Belongs in shared memory
+- A discovered constraint affecting multiple tasks ("the Stripe API rate-limits to 100 req/s — batch operations must respect this")
+- A cross-cutting architectural decision made during implementation ("chose React Server Components for data fetching across the whole feature")
+- An open risk future tasks must account for ("migration depends on schema v3 which is not yet deployed to staging")
+
+### Stays in task memory
+- Files touched during this task's implementation
+- Debugging steps taken to resolve a task-specific error
+- The current task's objective and acceptance criteria snapshot
+- A workaround applied only to the current task's scope
+
+## Compaction Rules
+
+When flagged for compaction, apply inline:
+
+1. If both files need compaction, compact `MEMORY.md` first, then `<N>_memory.md`. The shared file sets the cross-task context that the task file should not duplicate.
+2. **Preserve:** current state, durable decisions, reusable learnings, open risks, handoff notes.
+3. **Remove:** repetition, stale notes, long command transcripts, facts derivable from the repo/PRD/task files.
+4. **Rewrite** retained items as short factual bullets. No narrative logs, no chronological play-by-play.
+5. Keep the default section headings intact. Remove empty sections only if truly unused.
+
+## Error Handling
+
+- If any caller-provided memory path is missing, stop and report the mismatch instead of guessing another path.
+- If memory conflicts with the repository, PRD, or task spec, trust the repo and docs — correct the memory.
+- If compaction would remove active risks, decisions, or handoff context, keep those items and remove lower-value repetition first.
+
+## Integration With Other dev-workflow Commands
+
+- `/dw-run-task` — reads memory before coding; updates `<N>_memory.md` during; runs promotion test + updates `MEMORY.md` at the end.
+- `/dw-run-plan` — runs promotion + compaction between tasks, so each task starts with clean shared state.
+- `/dw-autopilot` — threads memory through every phase (brainstorm → PRD → techspec → tasks → execution).
+- `/dw-resume` — reads `MEMORY.md` first to reconstitute cross-session context, then the active task's memory.
+
+Callers should mention this skill in their "Skills Complementares" section.
+
+## Inspired by
+
+Ported from Compozy's `cy-workflow-memory` skill (`/tmp/compozy/.agents/skills/cy-workflow-memory/SKILL.md`). Adapted for dev-workflow:
+
+- Paths are `.dw/spec/<prd-slug>/` instead of `.compozy/tasks/<name>/`.
+- Task-local file is `<N>_memory.md` next to `<N>_task.md` (mirrors the existing dev-workflow task layout).
+- Inline Compaction Rules (Compozy keeps them in `references/memory-guidelines.md`); if the rule set grows, extract a `references/` directory later.
+
+Credit: Compozy project (https://github.com/compozy/compozy).

package/scaffold/skills/dw-review-rigor/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: dw-review-rigor
+description: |
+  Applies review discipline to code-review and analysis commands:
+  de-duplicates issues, orders by severity, verifies intent before flagging,
+  prioritizes signal over volume, and skips concerns that linters already
+  catch. Invoked from dw-code-review, dw-review-implementation, and
+  dw-refactoring-analysis. Do not use for fetching reviews from external
+  providers or for executing fixes.
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+---
+
+# dw-review-rigor — Discipline For Review Commands
+
+A set of rules the caller applies while producing a review report. This skill does not produce its own report file — it shapes the caller's output.
+
+## When Invoked
+
+By `/dw-code-review`, `/dw-review-implementation`, `/dw-refactoring-analysis`. The caller has already identified a scope (files, a PR, a codebase area). This skill governs how findings are selected, deduplicated, ordered, and phrased.
+
+## Required Inputs
+
+- The scope the caller is reviewing (file paths, directories, or PR diff).
+- Optional: prior review reports in `.dw/spec/prd-*/reviews/` — so this round only surfaces NEW findings.
+
+## The Five Rules
+
+### 1. De-duplicate before writing
+
+If the same pattern (e.g., missing null check, unhandled error, magic constant) appears in multiple files, **create one finding** for the most representative instance and list the other affected files inside its body. Do not create N identical findings for N files sharing one root cause.
+
+Example — wrong:
+```
+- [HIGH] src/a.ts:14 — missing null check on user
+- [HIGH] src/b.ts:22 — missing null check on user
+- [HIGH] src/c.ts:31 — missing null check on user
+```
+
+Example — right:
+```
+- [HIGH] Missing null check on `user` in 3 places.
+  Representative: src/a.ts:14
+  Also affects: src/b.ts:22, src/c.ts:31
+  Fix: add `if (!user) return` at function entry.
+```
+
+### 2. Severity-order the output
+
+Always present findings in this order: **critical → high → medium → low**. Inside each severity, order by impact or blast radius, not by file path.
+
+Severity definitions:
+- **critical** — correctness bug, security hole, data loss, unavailability.
+- **high** — material deviation from PRD/TechSpec, concurrency hazard, significant perf regression, missing error handling on a user path.
+- **medium** — maintainability cost that will hurt the next change, missing edge-case handling, inconsistent with project rules.
+- **low** — stylistic, naming, minor readability. Often omit unless pattern-level.
+
+### 3. Verify intent before flagging
+
+Before creating a finding, check whether the pattern is intentional:
+- adjacent comment explaining the choice?
+- ADR in `.dw/spec/*/adrs/` that justifies it?
+- test coverage that asserts the behavior?
+- rule in `.dw/rules/` that permits it?
+
+If the code looks suspicious but has a clear justification (e.g., `// intentionally ignoring close error on read-only handle`), do NOT create a finding. Only flag patterns that are genuinely problematic, not merely unconventional.
+
+### 4. Skip what linters already catch
+
+Before writing findings, ensure the project's linter/formatter has run. Anything the configured linter would flag is NOT a finding in this review — it is a linter task. Save human attention for issues linters cannot find (logic, architecture, security, requirements).
+
+If the linter cannot run (missing tooling, build errors), note that in the summary and proceed with the review.
+
+### 5. Signal over volume
+
+Aim for fewer, higher-quality findings.
+
+- Keep ALL `critical` and `high`.
+- If total findings exceed 20, prune `medium` and `low` to the most impactful ones.
+- A review with 8 precise findings is more useful than one with 30 that includes marginal concerns.
+
+**Also note well-implemented aspects.** They inform the summary and calibrate tone — but they do not produce findings.
+
+## Prior-Round Awareness
+
+If the PRD directory has prior review reports:
+
+1. Read them and extract the list of known findings (their titles + file/line signatures).
+2. The current round surfaces **only NEW findings**. Do not re-flag items already tracked as pending, resolved, or accepted in earlier rounds.
+3. If a prior finding was resolved incorrectly, open it as a NEW finding with "Regression of <prior ref>" in the body.
+
+## Finding Format
+
+Each finding uses:
+
+```
+[<severity>] <file.ext>:<line> — <title ≤72 chars>
+
+<1-4 lines describing the problem>
+<1-2 lines suggesting the fix>
+
+Also affects: <other paths if de-duplicated, else omit>
+Evidence: <relevant code snippet, test output, or reference>
+```
+
+## Output Structure
+
+The caller emits:
+
+1. **Merge/ship recommendation** — one of:
+   - `Needs fixes before merge` (if any critical or high exist), with blocking findings named.
+   - `Safe to merge with follow-ups` (only medium/low).
+   - `Clean — ready to merge` (no findings).
+2. **Counts** — critical / high / medium / low.
+3. **Findings** — ordered by severity, each in the format above.
+4. **Well-implemented aspects** — short bulleted list, calibrates tone.
+
+## Critical Rules
+
+- Do not modify source code — this skill shapes findings only, it does not fix.
+- Do not create findings for problems a configured linter already catches.
+- Do not flag patterns that have a clear adjacent justification or ADR.
+- Do not write N identical findings for one root cause — de-duplicate.
+- Do not mix severities — order is critical → high → medium → low.
+
+## Integration With Other dev-workflow Commands
+
+- `/dw-code-review` — applies all five rules to its Level-3 review output; uses prior reports in `.dw/spec/*/reviews/` to dedupe across rounds.
+- `/dw-review-implementation` — applies de-dup + severity-ordering when listing gaps between PRD requirements and code.
+- `/dw-refactoring-analysis` — applies rules 1, 2, 4, 5 when cataloging code smells (rule 3 adapts: a "smell" with a justifying ADR becomes a `low` finding at most).
+
+Callers should mention this skill in their "Skills Complementares" section.
+
+## Inspired by
+
+Ported from Compozy's `cy-review-round` skill (`/tmp/compozy/.agents/skills/cy-review-round/SKILL.md`). Adapted for dev-workflow:
+
+- No `reviews-NNN/` directory convention — dev-workflow reviews already persist in `.dw/spec/*/reviews/` per command's existing contract.
+- The five rules are extracted here so three different dev-workflow review commands can share the discipline without duplicating it.
+- No issue-file frontmatter (Compozy uses it to interoperate with its remediation engine; dev-workflow's remediation is manual or via `/dw-fix-qa`).
+
+Credit: Compozy project (https://github.com/compozy/compozy).

package/scaffold/skills/dw-verify/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: dw-verify
+description: |
+  Enforces fresh verification evidence before any completion, fix, or passing
+  claim — and before commits or PR creation. Use when a dev-workflow command
+  is about to report success, hand off work, or commit code. Invoked from
+  dw-run-task, dw-run-plan, dw-fix-qa, dw-bugfix, dw-code-review, dw-generate-pr,
+  and dw-quick. Do not use for early planning or brainstorming.
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+---
+
+# dw-verify — Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If the verification command has not been run in the current message, the result cannot be claimed.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Scope of Verification
+
+Match the verification scope to the claim scope.
+
+- **Narrow claim** (e.g., "this test passes"): run the specific test.
+- **Broad claim** (e.g., "task complete", "ready to commit"): run the full verification pipeline — formatting, linting, all tests, and build. If the project defines a single gate command (e.g., `npm test`, `make verify`, `pnpm check`), run that.
+
+A narrow verification does not support a broad claim. Running one test alone does not justify "task complete." The verification scope must be equal to or broader than the claim scope.
+
+**If in doubt, run the full pipeline.** Over-verification wastes minutes. Under-verification wastes hours.
+
+**Passing pipeline ≠ meeting requirements.** A green build proves the code compiles, lints, and passes existing tests. It does not prove the implementation matches the PRD. For "task complete" or "requirements met" claims, also verify deliverables against the task's acceptance criteria and the PRD — line by line, not by assumption.
+
+## Common Failures
+
+| Claim                 | Requires                         | Not Sufficient                  |
+| --------------------- | -------------------------------- | ------------------------------- |
+| Tests pass            | Test command output: 0 failures  | Previous run, "should pass"     |
+| Linter clean          | Linter output: 0 errors          | Partial check, extrapolation    |
+| Build succeeds        | Build command: exit 0            | Linter passing, logs look good  |
+| Bug fixed             | Test original symptom: passes    | Code changed, assumed fixed     |
+| Regression test works | Red-green cycle verified         | Test passes once                |
+| Task complete         | Acceptance criteria cross-check  | Tests passing                   |
+| Requirements met      | Line-by-line PRD checklist       | Tests passing                   |
+
+## Red Flags
+
+If you catch yourself using any of these, STOP and run verification:
+
+- "should", "probably", "seems to", "I'm confident"
+- Expressing satisfaction before verification
+- About to commit, push, or open a PR without verification
+- Trusting another agent's success report
+- Relying on partial verification
+- "Just this once"
+
+## Rationalization Prevention
+
+| Excuse                                  | Reality                |
+| --------------------------------------- | ---------------------- |
+| "Should work now"                       | Run the verification   |
+| "I'm confident"                         | Confidence ≠ evidence  |
+| "Just this once"                        | No exceptions          |
+| "Linter passed"                         | Linter ≠ compiler      |
+| "Agent said success"                    | Verify independently   |
+| "I'm tired"                             | Exhaustion ≠ excuse    |
+| "Partial check is enough"               | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter     |
+
+## When To Apply
+
+Apply this skill before:
+
+- any success or completion claim
+- any expression of satisfaction with the implementation state
+- any commit or PR creation
+- any handoff that implies correctness
+- moving to the next task based on completion
+
+## Pre-Commit and Pre-PR Gate
+
+Commits and PRs are permanent artifacts. They require the highest verification standard.
+
+**Before `git commit`:**
+1. Run the full verification pipeline. Not a subset. The full pipeline.
+2. Confirm zero errors, zero warnings, zero test failures in the output.
+3. Produce a Verification Report (template below) with verdict PASS.
+4. Only then run `git commit`.
+
+**Before creating a PR:**
+1. All of the above, plus:
+2. Verify the diff matches the intended changes (`git diff` review).
+3. Confirm no unrelated files are staged.
+
+If the full pipeline has not passed in this session after the last code change, the commit or PR must not proceed.
+
+## Verification Report Template
+
+Verification is not complete until the agent **cites actual command output** in their response. "I ran it and it passed" is not evidence. If the verification output is not shown, the verification did not happen.
+
+Every verification must be reported using this structure. Do not deviate.
+
+```
+VERIFICATION REPORT
+-------------------
+Claim: [What is being claimed — e.g., "tests pass", "build succeeds", "task complete"]
+Command: [Exact command run — e.g., `npm test`, `pnpm verify`]
+Executed: [Timestamp or "just now, after all changes"]
+Exit code: [0 or non-zero]
+Output summary: [Key lines from output — pass count, error count, build result]
+Warnings: [Any warnings, or "none"]
+Errors: [Any errors, or "none"]
+Verdict: PASS or FAIL
+```
+
+If the verdict is FAIL, do not use completion language. State what failed and what remains.
+
+If the verdict is PASS, the claim may proceed — but only the specific claim supported by the evidence.
+
+## When Verification Fails
+
+Verification failure is information, not a dead end. Protocol:
+
+1. **Read the failure.** Identify the exact error. Quote the relevant output lines.
+2. **Diagnose the root cause.** Read the error. Trace it to the source. If multiple things failed, address them one at a time, starting with the first failure.
+3. **Fix the root cause.** Apply the minimal change that addresses the actual error. No workarounds, no suppressions, no skipped checks.
+4. **Re-verify from scratch.** Run the full verification command again. Do not assume the fix worked. Do not run only the previously-failing subset.
+5. **Report with evidence.** Use the Verification Report Template. If it passes, the claim may proceed. If it fails again, return to step 1.
+
+**Never:**
+- Claim partial success ("3 of 4 checks pass, close enough")
+- Skip re-verification after a fix
+- Blame the tooling without evidence of a false positive
+- Move on while verification is still failing
+
+## Project-Specific Verification Commands
+
+dev-workflow does not hardcode a verification command. Discover it from the project:
+
+1. Check `.dw/rules/` for a documented verify command.
+2. Read `package.json` scripts: prefer `verify`, `check`, `ci`, `test`, in that order.
+3. Check for `Makefile`/`make verify`, `pyproject.toml`/`just verify`, etc.
+4. If none is explicit, run the documented test + lint + build sequence.
+
+If no verification command exists for the project, state that explicitly in the Verification Report and avoid completion language.
+
+## Integration With Other dev-workflow Commands
+
+This skill is invoked transparently from:
+
+- `/dw-run-task` — before committing the task's changes
+- `/dw-run-plan` — before Level 2 review and before declaring the plan complete
+- `/dw-fix-qa` — before marking a bug as resolved in `QA/bugs.md`
+- `/dw-bugfix` — before claiming the bug is fixed (original symptom no longer reproduces)
+- `/dw-code-review` — before emitting an APPROVED verdict
+- `/dw-generate-pr` — blocks PR creation if the session has no passing VERIFICATION REPORT post-last-edit
+- `/dw-quick` — before committing the one-off change
+
+Callers should mention this skill in their "Skills Complementares" section so the user sees the dependency.
+
+## Inspired by
+
+Ported from Compozy's `cy-final-verify` skill (`/tmp/compozy/.agents/skills/cy-final-verify/SKILL.md`). Adapted for the dev-workflow context:
+
+- Project-agnostic verification discovery (Compozy assumes `make verify`; dev-workflow scans `package.json`/Makefile/`.dw/rules/`).
+- Integration table maps to dev-workflow command names instead of Compozy phases.
+
+Credit: Compozy project (https://github.com/compozy/compozy).