@tianhai/pi-workflow-kit 0.17.1 → 1.0.0

package/docs/workflow-phases.md

@@ -1,69 +1,98 @@
 # Workflow Phases
 
-`pi-workflow-kit` has 4 phases and 1 utility skill. You invoke each one explicitly with `/skill:`.
+`pi-workflow-kit` has 5 pipeline skills plus 2 utility skills. You invoke each one explicitly with `/skill:`.
 
 ```
-brainstorm → plan → execute → finalize
+brainstorm → writing-plans → executing-tasks → finalizing
+                          (per requirement: tests → ⏸ checkpoint → implement → ⏸ checkpoint → code-review)
 ```
 
+A design doc is one PR; a requirement is one testable slice within it. For multi-design work (a large issue split into several design docs — each its own PR), run the pipeline once per design doc.
+
 ## brainstorm
 
 ```
-/skill:brainstorming
+/skill:pwk-brainstorming
 ```
 
-- Explore requirements and shape the design
-- Ask questions one at a time, propose approaches
-- Produce `docs/plans/YYYY-MM-DD-<topic>-design.md`
+- Explore requirements and shape the design.
+- Produce `docs/plans/YYYY-MM-DD-<topic>-design.md` — descriptive, opening with a `## Requirements` list.
+- May split a large issue into multiple design docs (human-approved).
+- ADRs go to `docs/adr/` (permanent, never archived).
 
 Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
 
-## plan
+## writing-plans
 
 ```
-/skill:writing-plans
+/skill:pwk-writing-plans
 ```
 
-- Read the design doc
-- Break into bite-sized tasks with TDD scenarios
-- Optionally set up a branch or worktree
-- Produce `docs/plans/YYYY-MM-DD-<topic>-implementation.md`
+- Creates the feature branch first (`git checkout -b <topic>`), so design + plan docs live on the branch, not `main`.
+- Reads the design doc's `## Requirements`; for each, derives **acceptance criteria + integration-test cases** (a behavioral spec, no implementation code), lists requirements in build order (dependencies positioned earlier), and challenges the design when `## Production-risk areas` is present.
+- Produce `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
 
-Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
+Write boundary: only `docs/plans/` is writable.
 
-## execute
+## executing-tasks
 
 ```
-/skill:executing-tasks
+/skill:pwk-executing-tasks
 ```
 
-- Read the implementation plan
-- Implement tasks one at a time: implement → test → fix → commit
-- Handle code review feedback by verifying criticism before implementing
+- Per requirement: write the integration tests (red) → **⏸ checkpoint: tests** → implement to green (full autonomy — the executor chooses structure/signatures/internals) → **⏸ checkpoint: complete** → commit → **per-requirement review** (four parallel reviewers via the `subagent` tool; falls back to inline `/skill:pwk-code-review` when `pi-subagents` is absent — see [code-review](#code-review)).
+- Two **mandatory** human checkpoints per requirement.
+- Progress tracked in `docs/plans/*-progress.md`.
+- After all requirements: **integration gate** — run the full suite and confirm the requirements compose into the feature before `/skill:pwk-finalizing`.
 
 No write restrictions. All tools available.
 
-## finalize
+## code-review
 
 ```
-/skill:finalizing
+/skill:pwk-code-review
 ```
 
-- Archive plan docs to `docs/plans/completed/`
-- Update CHANGELOG, README if needed
-- Create PR
-- Clean up worktree if one was used
+The **inline reviewer**: code tracing, spec alignment (vs acceptance criteria), code smells (applies fixes), production hazard check. Unlocked — may modify code to fix smells.
 
-No write restrictions. All tools available.
+**Not a phase you drive manually.** During `pwk-executing-tasks`, per-requirement review runs **four specialized reviewers in parallel** via the `subagent` tool (spec, tracing, smell, hazard — each fresh-context, read-only reporters); this skill is the **fallback** when [`pi-subagents`](https://pi.dev/packages/pi-subagents) is not installed. You can also invoke `/skill:pwk-code-review` standalone for an ad-hoc review of any diff.
+
+No write restrictions.
+
+## finalizing
+
+```
+/skill:pwk-finalizing
+```
+
+- **Pre-check: run the full test suite** — don't ship a red suite (resume spans sessions; don't trust the last execute session).
+- Delete consumed plan docs (per-`<topic>`) — code + tests are the source of truth; ADRs stay at `docs/adr/`.
+- Curate `docs/lessons.md`, update README/CHANGELOG, create PR or merge.
+
+No write restrictions.
+
+## status
+
+```
+/skill:pwk-status
+```
+
+Read-only overview of all active pipeline topics (phase + progress) when several designs are in flight. Not a pipeline phase.
 
 ## diagnose
 
 ```
-/skill:diagnose
+/skill:pwk-diagnose
 ```
 
 Not a pipeline phase. A utility skill invoked on demand when debugging is needed.
 
-- Build a feedback loop (failing test, curl script, etc.)
-- Reproduce, hypothesise, instrument, fix, cleanup
-- No write restrictions (used during execute/finalize, or outside the pipeline)
+No write restrictions.
+
+## Manual override
+
+`/pwk-guard on|off|auto` overrides the guard regardless of phase: `on` forces a read-only lock, `off` disables the guard entirely, `auto` (default) returns to skill-driven phases. Subcommands autocomplete. Use it as an escape hatch when the guard blocks something you genuinely need; phase transitions otherwise happen only via `/skill:` commands.
+
+## Continuity across sessions
+
+A new session resumes by invoking the skill for the phase to continue. The skill globs `docs/plans/` for its artifact (progress file / plan doc), resumes the single match, or asks if several. Each resumption skill reports what it found on entry — no registry file needed; the `<topic>` slug in the filenames is the identity.

package/extensions/workflow-guard.ts

@@ -4,14 +4,15 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 /**
  * Workflow Guard extension.
  *
- * Blocks write/edit outside docs/plans/ and unsafe bash during brainstorm and plan phases.
- * You control phases explicitly via /skill: commands — no auto-detection,
- * no state persistence, no prompts.
+ * Blocks write/edit outside docs/plans/ and destructive bash during brainstorm and plan phases.
+ * Bash uses a simple common-blacklist (DESTRUCTIVE_PATTERNS) — a command is allowed unless it matches
+ * a destructive pattern. A short phase reminder is appended after the user's message each turn via
+ * before_agent_start. You control phases explicitly via /skill: commands — no auto-detection, no prompts.
  */
 
 type Phase = "brainstorm" | "plan" | null;
 
-// Destructive commands blocked in brainstorm/plan phases
+// Destructive commands blocked in brainstorm/plan phases (simple common blacklist)
 const DESTRUCTIVE_PATTERNS = [
   /\brm\b/i,
   /\brmdir\b/i,
@@ -27,15 +28,22 @@ const DESTRUCTIVE_PATTERNS = [
   /\btruncate\b/i,
   /\bdd\b/i,
   /\bshred\b/i,
-  /(^|[^<])>(?!>)/,
-  />>/,
   /\bnpm\s+(install|uninstall|update|ci|link|publish)/i,
   /\byarn\s+(add|remove|install|publish)/i,
   /\bpnpm\s+(add|remove|install|publish)/i,
   /\bpip\s+(install|uninstall)/i,
   /\bapt(-get)?\s+(install|remove|purge|update|upgrade)/i,
   /\bbrew\s+(install|uninstall|upgrade)/i,
-  /\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|branch\s+-[dD]|stash(?!\s+list)|cherry-pick|revert|tag(?!\s+(-l|--list))|init|clone)/i,
+  // git add/commit/apply merge files and are blocked below. Plain `git branch`/`checkout`/`switch`
+  // only create or move between branches (no source-file changes), so they are intentionally allowed
+  // during gated phases — pwk-writing-plans creates the feature branch before authoring the plan.
+  /\bgit\s+(add|commit|push|pull|merge|rebase|reset|branch\s+-[dD]|stash(?!\s+list)|cherry-pick|revert|tag(?!\s+(-l|--list))|init|clone|apply)/i,
+  // Edit-via-bash vectors: in-place editors, patch appliers, find-delete (bypass the write/edit tool block)
+  /\bsed\b.*\s-i\b/i,
+  /\bperl\b.*\s-[a-z]*i\b/i,
+  /\bawk\b.*-i\s+inplace\b/i,
+  /^\s*patch\b/i, // command-position only — avoids FP on "patch" in paths/searches (grep/cat/cd)
+  /\bfind\b.*\s-delete\b/i,
   /\bsudo\b/i,
   /\bsu\b/i,
   /\bkill\b/i,
@@ -48,73 +56,9 @@ const DESTRUCTIVE_PATTERNS = [
   /^\s*(vim?|nano|emacs|code|subl)\b/i,
 ];
 
-const SAFE_PATTERNS = [
-  /^\s*cat\b/,
-  /^\s*head\b/,
-  /^\s*tail\b/,
-  /^\s*less\b/,
-  /^\s*more\b/,
-  /^\s*grep\b/,
-  /^\s*find\b/,
-  /^\s*ls\b/,
-  /^\s*pwd\b/,
-  /^\s*echo\b/,
-  /^\s*printf\b/,
-  /^\s*wc\b/,
-  /^\s*sort\b/,
-  /^\s*uniq\b/,
-  /^\s*diff\b/,
-  /^\s*file\b/,
-  /^\s*stat\b/,
-  /^\s*du\b/,
-  /^\s*df\b/,
-  /^\s*tree\b/,
-  /^\s*which\b/,
-  /^\s*whereis\b/,
-  /^\s*type\b/,
-  /^\s*env\b/,
-  /^\s*printenv\b/,
-  /^\s*uname\b/,
-  /^\s*whoami\b/,
-  /^\s*id\b/,
-  /^\s*date\b/,
-  /^\s*cal\b/,
-  /^\s*uptime\b/,
-  /^\s*ps\b/,
-  /^\s*top\b/,
-  /^\s*htop\b/,
-  /^\s*free\b/,
-  /^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get)/i,
-  /^\s*git\s+ls-/i,
-  /^\s*npm\s+(list|ls|view|info|search|outdated|audit)/i,
-  /^\s*yarn\s+(list|info|why|audit)/i,
-  /^\s*node\s+--version/i,
-  /^\s*python\s+--version/i,
-  /^\s*curl\s/i,
-  /^\s*wget\s+-O\s*-/i,
-  /^\s*jq\b/,
-  /^\s*sed\s+-n/i,
-  /^\s*awk\b/,
-  /^\s*rg\b/,
-  /^\s*fd\b/,
-  /^\s*bat\b/,
-  /^\s*eza\b/,
-  /^\s*cd\b/,
-  /^\s*gh\s+pr\s+(view|list|diff|checks|status)\b/i,
-  /^\s*gh\s+issue\s+(view|list)\b/i,
-  /^\s*gh\s+repo\s+(view|fork|list)\b/i,
-  /^\s*gh\s+release\s+(view|list|download)\b/i,
-  /^\s*gh\s+run\s+(view|list)\b/i,
-  /^\s*git\s+blame\b/,
-  /^\s*git\s+shortlog\b/,
-  /^\s*git\s+stash\s+list\b/i,
-  /^\s*git\s+tag\s+(-l|--list)\b/i,
-  /^\s*git\s+describe\b/,
-  /^\s*go\s+doc\b/,
-  /^\s*go\s+list\b/,
-  /^\s*go\s+version\b/,
-  /^\s*go\s+env\b/,
-];
+// Redirect operators — tested on a quote-stripped command so '>' inside quoted
+// arguments (e.g. grep 'x > y') doesn't false-positive.
+const REDIRECT_PATTERNS = [/(^|[^<])>(?!>)/, />>/];
 
 /** Split a compound command into individual sub-commands.
  * Splits on &&, ||, and ; operators, ignoring leading whitespace.
@@ -134,19 +78,63 @@ function stripHarmlessRedirects(cmd: string): string {
   return cmd.replace(/\s*2\s*>\s*(\/dev\/null|&1)\b/g, "");
 }
 
+/** Blank out single- and double-quoted substrings so operators (>,
+ *  >>, &&) inside quoted arguments don't trigger destructive-pattern
+ *  false-positives. Replaces quoted content and quote chars with spaces,
+ *  preserving length so operators outside quotes still match.
+ *  Advisory only — not a full shell parser. */
+function stripQuoted(cmd: string): string {
+  let out = "";
+  let i = 0;
+  let inQuote = false;
+  while (i < cmd.length) {
+    const ch = cmd[i];
+    const code = cmd.charCodeAt(i);
+    if (inQuote) {
+      if (code === 0x5c) {
+        out += "  ";
+        i += 2;
+        continue;
+      }
+      out += " ";
+      if (code === 0x22 || code === 0x27) {
+        inQuote = false;
+      }
+      i++;
+      continue;
+    }
+    if (code === 0x22 || code === 0x27) {
+      inQuote = true;
+      out += " ";
+      i++;
+      continue;
+    }
+    out += ch;
+    i++;
+  }
+  return out;
+}
+
 export function isSafeCommand(command: string): boolean {
-  const parts = splitCompoundCommand(command);
-  return parts.every((part) => {
+  return splitCompoundCommand(command).every((part) => {
     const cleaned = stripHarmlessRedirects(part);
-    const isDestructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(cleaned));
-    const isSafe = SAFE_PATTERNS.some((p) => p.test(cleaned));
-    return !isDestructive && isSafe;
+    if (REDIRECT_PATTERNS.some((p) => p.test(stripQuoted(cleaned)))) return false;
+    return !DESTRUCTIVE_PATTERNS.some((p) => p.test(cleaned));
   });
 }
 
 const SKILL_TO_PHASE: Record<string, Phase> = {
-  brainstorming: "brainstorm",
-  "writing-plans": "plan",
+  "pwk-brainstorming": "brainstorm",
+  "pwk-writing-plans": "plan",
+};
+
+/** Phase-aware reminder appended after the user's message each turn while a gated phase is active.
+ *  Returned as a message (not a system-prompt change) so it sits at the tail of the request and
+ *  never invalidates the cached prefix. */
+const PHASE_REMINDERS: Record<Exclude<Phase, null>, string> = {
+  brainstorm:
+    "[pi-workflow-kit] BRAINSTORM phase: read-only. No source edits; writes only under docs/plans/. No mutations.",
+  plan: "[pi-workflow-kit] PLAN phase: read-only. No source edits; writes only under docs/plans/. No mutations.",
 };
 
 /** Determine if a write/edit to filePath should be blocked during the given phase.
@@ -163,10 +151,84 @@ export function getCurrentPhase(): Phase {
 }
 
 let phase: Phase = null;
+// True on the turn a gated phase is entered; consumed once by before_agent_start so the reminder
+// is shown only on the first turn of the phase (and re-armed on any later phase change into it).
+let pendingPhaseReminder = false;
+
+/**
+ * Manual guard override set by `/pwk-guard`.
+ * - null  → "auto": enforcement follows the skill-driven phase (default).
+ * - "on"  → force a read-only lock (enforce regardless of phase).
+ * - "off" → disable the guard entirely (escape hatch).
+ * Skill transitions still update `phase` while an override is active, so returning
+ * to `auto` recovers the correct state; enforcement itself ignores `phase`.
+ */
+let guardOverride: "on" | "off" | null = null;
+
+/** Is the guard actively enforcing read-only right now? */
+function enforceActive(): boolean {
+  if (guardOverride === "off") return false;
+  if (guardOverride === "on") return true;
+  return phase !== null;
+}
+
+/** Label for the current enforcement context, used in block reasons and reminders. */
+function enforceLabel(): string {
+  return guardOverride === "on" ? "GUARD ON" : phase ? phase.toUpperCase() : "";
+}
 
 export default function (pi: ExtensionAPI) {
   pi.on("session_start", () => {
     phase = null;
+    pendingPhaseReminder = false;
+    guardOverride = null;
+  });
+
+  // --- Manual override (escape hatch) -----------------------------------
+  // Phases are driven by `/skill:` commands; `/pwk-guard` lets the user pin the
+  // guard regardless of phase. `/pwk-guard auto` returns control to skill transitions.
+  pi.registerCommand("pwk-guard", {
+    description:
+      "Manual guard override: /pwk-guard on (force read-only lock) | off (disable guard) | auto (skill-driven phases, default).",
+    getArgumentCompletions: (prefix) => {
+      const p = (prefix ?? "").trim().toLowerCase();
+      const opts = [
+        { value: "on", label: "on", description: "Force read-only lock (ignore skill phases)" },
+        { value: "off", label: "off", description: "Disable the guard entirely" },
+        { value: "auto", label: "auto", description: "Follow skill-driven phases (default)" },
+      ];
+      const matched = opts.filter((o) => o.value.startsWith(p));
+      return matched.length ? matched : opts;
+    },
+    handler: async (args, ctx) => {
+      const arg = (args ?? "").trim().toLowerCase();
+      if (arg === "auto") {
+        guardOverride = null;
+        if (phase) pendingPhaseReminder = true; // re-announce the active gated phase, if any
+        ctx.ui.notify("Guard AUTO — enforcement follows skill-driven phases.", "info");
+        return;
+      }
+      if (arg !== "on" && arg !== "off") {
+        ctx.ui.notify("Usage: /pwk-guard on | off | auto", "info");
+        return;
+      }
+      guardOverride = arg;
+      pendingPhaseReminder = false; // override announces itself via the message below
+      pi.sendMessage({
+        customType: "pwk-guard:override",
+        content:
+          arg === "on"
+            ? "[pi-workflow-kit] GUARD ON (manual override): read-only lock active — no source edits; writes only under docs/plans/. No mutations. Use /pwk-guard auto to resume skill-driven phases."
+            : "[pi-workflow-kit] GUARD OFF (manual override): enforcement disabled — writes and bash are unrestricted. Use /pwk-guard auto to resume skill-driven phases.",
+        display: false,
+      });
+      ctx.ui.notify(
+        arg === "on"
+          ? "Guard ON — read-only lock active (skill phases ignored)."
+          : "Guard OFF — enforcement disabled (skill phases ignored).",
+        arg === "on" ? "warning" : "info",
+      );
+    },
   });
 
   pi.on("input", (event) => {
@@ -175,27 +237,65 @@ export default function (pi: ExtensionAPI) {
     if (match) {
       const skill = match[1];
       if (skill in SKILL_TO_PHASE) {
-        phase = SKILL_TO_PHASE[skill];
+        const nextPhase = SKILL_TO_PHASE[skill];
+        if (phase !== nextPhase) {
+          phase = nextPhase;
+          // The reminder is a phase-entry cue; only relevant when the guard is auto-driven.
+          if (guardOverride === null) pendingPhaseReminder = true;
+        }
         return;
       }
     }
-    if (text.startsWith("/skill:executing-tasks") || text.startsWith("/skill:finalizing")) {
+    // Phase transitions happen only via skills — no message keyword unlocks the plan phase.
+    // Run /skill:pwk-executing-tasks (or any non-gated skill) to leave a gated phase.
+    if (
+      text.startsWith("/skill:pwk-executing-tasks") ||
+      text.startsWith("/skill:pwk-finalizing") ||
+      text.startsWith("/skill:pwk-code-review") ||
+      text.startsWith("/skill:pwk-diagnose") ||
+      text.startsWith("/skill:pwk-status")
+    ) {
       phase = null;
     }
   });
 
+  // Show the phase reminder exactly once: on the first turn of a gated phase (before_agent_start
+  // fires before the LLM is called). It is NOT repeated every turn. Re-armed on any phase change.
+  // Returned as a tail-appended custom message so it never touches the cached system-prompt prefix.
+  //
+  // Note: a soft reminder on every *permitted* bash call is not possible — tool_call can only
+  // return { block, reason }, not a message. So at bash time the reminder surfaces only when a
+  // destructive command is actually blocked (the reactive `reason` in the tool_call handler).
+  pi.on("before_agent_start", async () => {
+    if (!phase || !pendingPhaseReminder) return {};
+    pendingPhaseReminder = false;
+    // Override states announce themselves via the /pwk-guard handler; this reminder
+    // is the auto-mode phase-entry cue only.
+    if (guardOverride !== null) return {};
+    return {
+      message: {
+        customType: "pwk-phase-reminder",
+        content: PHASE_REMINDERS[phase],
+        display: false,
+      },
+    };
+  });
+
   pi.on("tool_call", (event, ctx) => {
-    if (!phase) return;
+    if (!enforceActive()) return;
+    const label = enforceLabel();
+    const manual = guardOverride === "on";
+    const scope = manual ? "manual read-only lock" : `${label.toLowerCase()} phase`;
 
     if (event.toolName === "bash") {
       const command = (event.input as { command?: string }).command ?? "";
       if (!isSafeCommand(command)) {
         if (ctx.hasUI) {
-          ctx.ui.notify(`Blocked bash command during ${phase} phase: ${command}`, "warning");
+          ctx.ui.notify(`Blocked bash command (${scope}): ${command}`, "warning");
         }
         return {
           block: true,
-          reason: `⚠️ ${phase.toUpperCase()} PHASE: Bash command blocked (not allowlisted). Only read-only commands are permitted during brainstorming and planning.\nCommand: ${command}`,
+          reason: `⚠️ ${label}: read-only — no source writes or destructive bash. Only read-only commands are permitted.\nBlocked command: ${command}`,
         };
       }
       return;
@@ -209,15 +309,14 @@ export default function (pi: ExtensionAPI) {
     if (!shouldBlockFilePath(filePath, ctx.cwd)) return;
 
     if (ctx.hasUI) {
-      ctx.ui.notify(
-        `Blocked ${event.toolName} to ${filePath} during ${phase} phase. Only docs/plans/ is writable.`,
-        "warning",
-      );
+      ctx.ui.notify(`Blocked ${event.toolName} to ${filePath} (${scope}). Only docs/plans/ is writable.`, "warning");
     }
 
     return {
       block: true,
-      reason: `⚠️ ${phase.toUpperCase()} PHASE: Cannot ${event.toolName} to ${filePath}. Only docs/plans/ is writable during brainstorming and planning.`,
+      reason: `⚠️ ${label}: Cannot ${event.toolName} to ${filePath}. Only docs/plans/ is writable${
+        manual ? " under the manual read-only lock" : " during brainstorming and planning"
+      }.`,
     };
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "0.17.1",
+  "version": "1.0.0",
   "description": "Enforce structured brainstorm→plan→execute→finalize workflow with TDD discipline in AI coding agents",
   "keywords": [
     "pi-package",
@@ -27,7 +27,11 @@
   "files": [
     "extensions/",
     "skills/",
-    "docs/",
+    "agents/",
+    "docs/developer-usage-guide.md",
+    "docs/workflow-phases.md",
+    "docs/oversight-model.md",
+    "docs/lessons.md",
     "LICENSE",
     "README.md"
   ],
@@ -39,13 +43,25 @@
       "skills"
     ]
   },
+  "pi-subagents": {
+    "agents": [
+      "./agents"
+    ]
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
-    "@sinclair/typebox": "*"
+    "@sinclair/typebox": "*",
+    "pi-subagents": "*"
+  },
+  "peerDependenciesMeta": {
+    "pi-subagents": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.15",
     "@earendil-works/pi-coding-agent": "*",
+    "@types/node": "^25.9.2",
     "vitest": "^4.0.18"
   }
 }

package/skills/pwk-brainstorming/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: pwk-brainstorming
+description: "Use this before any creative work — creating features, building components, adding functionality, or modifying behavior. Explores intent and design before implementation. Use this skill whenever the user describes something they want to build, change, or improve, even if they don't say 'brainstorm' — phrases like 'I want to add X', 'let's build Y', 'we need a way to Z', or 'help me design' all apply."
+---
+
+# Brainstorming
+
+Read-only exploration. You may **not** edit or create any files except under `docs/plans/`.
+
+## Granularity
+
+**A design doc is one pull request; a requirement is one testable slice within it.** Two decomposition levels answer two different questions:
+
+- **How many PRs?** — split a large issue into **multiple design docs** only when each part could ship as its own PR (independently reviewable and mergeable). Each design doc runs its own plan → execute → finalize pipeline → its own PR. Example: "add OAuth" and "add dark mode" are unrelated → two design docs.
+- **How to build one PR incrementally?** — within a design doc, decompose the work into **requirements**, each "one testable behavior." The plan covers all of them; the executor builds them one at a time. Example: "add OAuth" = R1 redirect flow, R2 token refresh, R3 error states → one design doc, three requirements, one PR.
+
+Requirements are the leaf unit — never split further. Decision rule: **could this part be reviewed and merged on its own?** Yes → separate design doc. No → one design doc, multiple requirements. Most work is a single design doc; splitting is opt-in.
+
+## Process
+
+1. **Check git state** — run `git status` and `git log --oneline -5`. If there's uncommitted work, ask the user what to do with it first.
+2. **Discovery** *(skip if this is a brand-new repo with no `docs/plans/`)* — glob `docs/plans/*-design.md`. Report active topics found (e.g. `In-flight: auth (plan), billing (brainstorm)`). Multiple designs may run in parallel. If the new idea continues an existing topic, ask the human whether to extend it or start fresh before designing.
+3. **Understand the idea** — read existing code, docs, and recent commits. Grep for related functionality, check package.json/dependencies and module structure. **Check `docs/lessons.md`** if it exists — known constraints and patterns may affect the design. Read only what's necessary to ground the design — don't read the entire codebase. Ask questions to refine the idea. Prefer multiple choice when possible. After each question, check: can you clearly articulate (a) what the user wants to build, (b) why, and (c) key constraints? If yes, present your understanding as a short summary and ask: "Should I proceed with this, or is there more to add?" The human decides when to move on.
+4. **Explore approaches** — propose 2-3 approaches. For each approach, sketch the concrete interface (types, method signatures, example caller code) so the comparison is grounded in actual code, not abstract descriptions. Lead with your recommendation.
+5. **Present the design** — break it into focused sections. Each section should be one screen of reading. Present each section to the human and wait for approval before continuing. Cover: architecture, components, data flow, error handling, testing. On feedback, incorporate it and re-present the revised section.
+
+   When a significant architectural decision is identified, offer to write a lightweight ADR to `docs/adr/`. Only write an ADR when all three are true:
+
+   1. **Hard to reverse** — changing your mind later has meaningful cost
+   2. **Surprising without context** — a future reader will wonder "why?"
+   3. **A real trade-off** — there were genuine alternatives
+
+   ADR format — a title and 1-3 sentences covering context, decision, and why:
+
+   ```markdown
+   # <Short title of the decision>
+
+   <1-3 sentences: context, decision, and why.>
+   ```
+
+   ADRs live under `docs/adr/` permanently — they are institutional memory, never archived.
+
+6. **Write the design doc** — save it to `docs/plans/YYYY-MM-DD-<topic>-design.md` as a descriptive document (not a task list). **Open with a `## Requirements` list** — each requirement one testable behavior the user will get (`pwk-writing-plans` derives acceptance criteria + integration tests per requirement). Then cover: problem, approaches considered, architecture, components, data flow, error handling, and testing.
+
+   If the design touches any production-risk area — database schema changes or migrations, authentication or authorization, external API or service integrations, concurrency or batch processing, file uploads or large data flows, Redis/caching/message queues — add a short `## Production-risk areas` section noting them. `pwk-writing-plans` carries these notes into the plan, and `pwk-code-review` audits them after each requirement.
+
+   **Splitting large issues:** if the work is large enough to be multiple PRs, propose splitting it into multiple design docs (one per sub-issue, each with its own `<topic>`) and get the human's approval first — see [Granularity](#granularity) for the decision rule. Each design doc then runs its own pipeline.
+
+   Branch creation and workspace setup happen at the end of `/skill:pwk-writing-plans` (after the plan is approved); the design + plan docs are committed at the start of `pwk-executing-tasks`. Until then the session is read-only and uncommitted.
+
+## Principles
+
+- One question at a time
+- YAGNI — remove unnecessary features
+- Design for testability
+- Always explore alternatives before settling
+
+## After the design
+
+Ask: "Ready to plan? Run `/skill:pwk-writing-plans`"

package/skills/pwk-code-review/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: pwk-code-review
+description: "Review a completed requirement's code — trace the logic, check spec alignment against the acceptance criteria, fix code smells, and run a production hazard check. Runs after each requirement in pwk-executing-tasks. Unlocked: may edit code to apply smell fixes."
+---
+
+# Code Review
+
+Review the code just implemented for a requirement. **Unlocked** — you may edit code to apply smell fixes; flag everything else as a follow-up.
+
+## Process
+
+1. **Identify the scope** — the requirement just completed (from the progress file / most recent commit). Read its acceptance criteria and integration tests from the plan doc. Run `git log --oneline -5` and `git diff` to see exactly what changed for this requirement.
+
+2. **🔍 Code tracing** — trace the new/changed code paths end-to-end against the integration tests. For each path: does data flow correctly from entry to the asserted outcome? Note any branch the tests don't exercise, any dead branch, any path where the trace breaks.
+
+3. **📐 Spec alignment** — for each acceptance criterion, point to the code and the test that satisfy it. A criterion with no covering code or no test is a **gap**. Code that does more than the criteria specify is **scope creep** — flag it.
+
+4. **🧹 Code smells — fix these directly:**
+   - Shallow modules (interface nearly as complex as the implementation)
+   - Duplication
+   - Missing seams / premature abstraction
+   - Poor naming, magic values, dead code
+   Apply the fix, re-run the integration tests (must stay green), and commit. If a smell needs a refactor large enough to risk the requirement, **flag** it instead of applying.
+
+5. **⚠️ Production hazard check** — audit the changed code against the high-risk hazards. For each, write `[SAFE]` (1-line justification) or `[TRIGGERED]` (concrete mitigation):
+   1. **Unbounded operations** — multi-key deletions/scans (`KEYS`, raw `SCAN` loops), or full-table loads filtered in memory.
+   2. **Missing indexes** — hot queries on unindexed columns (table scans under load).
+   3. **Unbounded concurrency** — unthrottled fan-out (`Promise.all` without batch limits).
+   4. **Long-running transactions** — holding DB connections/locks across slow external calls.
+   5. **Query/command interpolation** — raw variables merged into SQL or shell (injection).
+   6. **Unrestricted uploads / temp flooding** — uploads to local temp without limits or `finally` cleanup.
+   7. **Silent swallowing loops** — background workers catching and suppressing exceptions without logging/back-off.
+   Also check the design's `## Production-risk areas`, if any.
+
+6. **Report** — summarize: tracing findings, spec gaps, smells fixed (with commits), hazards `[TRIGGERED]`. Non-trivial findings become follow-up items — the user decides whether to address now or defer.
+7. **Mark done** — update the requirement's progress-file row from `🔎 review` to `✅ done`. Done means reviewed, not just committed.
+
+## Principles
+
+- **Tracing and spec alignment are the core** — they catch what tests miss: untested branches, missing criteria, scope creep.
+- **Fix smells in place; flag everything else.** Don't redesign.
+- **Be proportional** — a one-function change doesn't need the depth of a batch pipeline.
+
+## After the review
+
+Return to `/skill:pwk-executing-tasks` for the next requirement, or `/skill:pwk-finalizing` if all requirements are done.