@tianhai/pi-workflow-kit 0.18.1 → 1.0.0

package/docs/workflow-phases.md

@@ -1,15 +1,13 @@
 # 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 → [design-review?] → execute → [verify?] → finalize
+brainstorm → writing-plans → executing-tasks → finalizing
+                          (per requirement: tests → ⏸ checkpoint → implement → ⏸ checkpoint → code-review)
 ```
 
-For complex features, each phase loops per feature:
-```
-brainstorm (name features) → plan next feature → [design-review?] → execute feature → [verify?] → loop...
-```
+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
 
@@ -17,50 +15,69 @@ brainstorm (name features) → plan next feature → [design-review?] → execut
 /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` with a `## Features` table listing all features and their status
+- 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:pwk-writing-plans
 ```
 
-- Read the design doc's Features table, identify the next `⬜ pending` feature
-- Mark it `🔄 planned` and create a per-feature implementation plan
-- Produce `docs/plans/YYYY-MM-DD-<topic>-<feature-name>-implementation.md`
-- Optionally trigger design review for non-trivial features
+- 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:pwk-executing-tasks
 ```
 
-- Read the plan doc, resolve the design doc and feature row from metadata
-- Implement tasks one at a time: implement → test → fix → commit
-- Mark feature `✅ done` in the design doc's Features table when complete
-- Suggest planning the next feature or verifying
+- 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:pwk-code-review
+```
+
+The **inline reviewer**: code tracing, spec alignment (vs acceptance criteria), code smells (applies fixes), production hazard check. Unlocked — may modify code to fix smells.
+
+**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
 ```
 
-- Archive plan docs to `docs/plans/completed/`
-- Update CHANGELOG, README if needed
-- Create PR
-- Clean up worktree if one was used
+- **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. All tools available.
+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
 
@@ -70,6 +87,12 @@ No write restrictions. All tools available.
 
 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, plan, and verify 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" | "verify" | null;
+type Phase = "brainstorm" | "plan" | null;
 
-// Destructive commands blocked in brainstorm/plan/verify 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,24 +78,67 @@ 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> = {
   "pwk-brainstorming": "brainstorm",
   "pwk-writing-plans": "plan",
-  "pwk-verify": "verify",
+};
+
+/** 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.
- *  Only writes under docs/plans/ are allowed during brainstorm, plan, and verify phases.
+ *  Only writes under docs/plans/ are allowed during brainstorm and plan phases.
  */
 export function shouldBlockFilePath(filePath: string, cwd: string): boolean {
   const absolute = resolve(cwd, filePath);
@@ -164,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) => {
@@ -176,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:pwk-executing-tasks") || text.startsWith("/skill:pwk-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, planning, and verification.\nCommand: ${command}`,
+          reason: `⚠️ ${label}: read-only — no source writes or destructive bash. Only read-only commands are permitted.\nBlocked command: ${command}`,
         };
       }
       return;
@@ -210,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, planning, and verification.`,
+      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.18.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,9 +43,20 @@
       "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",

package/skills/pwk-brainstorming/SKILL.md

@@ -7,14 +7,24 @@ description: "Use this before any creative work — creating features, building
 
 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. **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.
-3. **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.
-4. **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.
+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/plans/adr/`. Only write an ADR when all three are true:
+   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?"
@@ -28,24 +38,15 @@ Read-only exploration. You may **not** edit or create any files except under `do
    <1-3 sentences: context, decision, and why.>
    ```
 
-   ADRs live under `docs/plans/adr/` and are archived during finalizing alongside the design doc.
+   ADRs live under `docs/adr/` permanently — they are institutional memory, never archived.
 
-5. **Write the design doc** — save it to `docs/plans/YYYY-MM-DD-<topic>-design.md`. Include a `## Features` table listing each feature as a testable, observable behavior. Simple features get one row. Complex features get many.
-
-   Table format:
-   ```markdown
-   ## Features
-
-   | # | Feature | Status | Observable Behavior |
-   |---|---------|--------|---------------------|
-   | 1 | Feature name | ⬜ pending | What the user can do when this is complete |
-   ```
+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.
 
-   Status values: `⬜ pending`, `🔄 planned`, `✅ done`, `⏭ skipped`.
+   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.
 
-   For trivial changes where the entire feature is a single row, note "Simple change — no design review needed" below the table. For non-trivial designs, note areas that may need production-risk review (database schema changes, authentication or authorization, external API integrations, concurrency or batch processing, file uploads or large data flows, Redis/caching/message queues).
+   **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, committing, and workspace setup are handled by `/skill:pwk-executing-tasks`.
+   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