@tianhai/pi-workflow-kit 0.17.1 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-workflow-kit
 
-> Stop AI agents from rushing to code. Enforce a structured brainstorm→plan→execute→verify→finalize workflow with TDD discipline.
+> Stop AI agents from rushing to code. Enforce a structured brainstorm→plan→execute→finalize workflow with test-first discipline and per-requirement code review.
 
 AI coding agents tend to skip design and jump straight into implementation, producing over-engineered or misaligned code. **pi-workflow-kit** solves this by hard-blocking write operations during brainstorm and planning phases — the agent *literally cannot modify your source files* until you approve the design.
 
@@ -20,6 +20,14 @@ No setup needed — skills and guards activate automatically after install.
 pi -e npm:@tianhai/pi-workflow-kit
 ```
 
+**Optional — parallel code review.** Per-requirement review can run four specialized reviewers in parallel via the `subagent` tool. Install [`pi-subagents`](https://pi.dev/packages/pi-subagents) to enable it:
+
+```bash
+pi install npm:pi-subagents
+```
+
+The four reviewers (`pwk-spec-reviewer`, `pwk-tracing-reviewer`, `pwk-smell-reviewer`, `pwk-hazard-reviewer`) ship with this kit as **package agents** — `pi-subagents` discovers them automatically, no extra setup. Without `pi-subagents`, `pwk-executing-tasks` falls back to inline `/skill:pwk-code-review`.
+
 ## What You Get
 
 ### 🛡️ Workflow Guard (extension)
@@ -28,28 +36,35 @@ Enforces phase-appropriate tool access — not just guidelines, but hard blocks:
 
 | Phase | `write` / `edit` | `bash` |
 |-------|:-:|:-:|
-| **Brainstorm** / **Plan** | 🔒 Blocked outside `docs/plans/` | 🔒 Read-only only (grep, find, cat, git status, curl…) |
-| **Execute** / **Finalize** | ✅ Full access | ✅ Full access |
+| **Brainstorm** / **Plan** | 🔒 Blocked outside `docs/plans/` | 🔒 Destructive commands blocked (simple blacklist) |
+| **Execute** / **Code-review** / **Finalize** / **Diagnose** / **Status** | ✅ Full access | ✅ Full access |
 
-The agent can read code and discuss design with you during brainstorm/plan, but it physically cannot modify source files or run mutating commands.
+The agent can read code and discuss design with you during brainstorm/plan, but it physically cannot modify source files. Bash during gated phases is governed by a simple common-blacklist (a command is allowed unless it matches a destructive pattern), and a short phase reminder is shown once when the gated phase begins so the model self-restricts.
+
+Phases transition only when you invoke a skill (`/skill:pwk-brainstorming` → read-only; `/skill:pwk-executing-tasks` → unrestricted) — no message keyword unlocks the guard. Need to override it? `/pwk-guard on` forces a read-only lock, `off` disables the guard entirely, `auto` (default) returns to skill-driven phases. The subcommands autocomplete after the command.
 
 ### 🧠 7 Workflow Skills
 
 Guide the agent through a disciplined development process:
 
-brainstorm → design-review → plan → execute → verify → finalize
-                                           ↕
-                                        diagnose (anytime)
+```
+brainstorm → writing-plans → executing-tasks → finalizing
+                             (per requirement: tests → checkpoint → implement → checkpoint → code-review)
+                                ↕
+                   diagnose (anytime)   ·   status (anytime)
+```
+
+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.
 
 | Phase | Trigger | What Happens |
 |-------|---------|--------------|
-| **Brainstorm** | `/skill:brainstorming` | Explore approaches, debate tradeoffs, produce a design doc |
-| **Design Review** | `/skill:design-review` | Audit design for production risks (security, scalability, fault tolerance) |
-| **Plan** | `/skill:writing-plans` | Break design into bite-sized TDD tasks with acceptance criteria and concrete code |
-| **Execute** | `/skill:executing-tasks` | Implement tasks one-by-one with TDD discipline and pre-commit checkpoint review gates |
-| **Verify** | `/skill:verify` | Three expert review passes (security, optimization, traceability) on implemented code |
-| **Finalize** | `/skill:finalizing` | Archive plan docs, update README/CHANGELOG, create PR |
-| **Diagnose** | `/skill:diagnose` | 6-phase debugging loop: reproduce → hypothesize → instrument → fix → verify |
+| **Brainstorm** | `/skill:pwk-brainstorming` | Explore approaches, produce a design doc with a `## Requirements` list |
+| **Plan** | `/skill:pwk-writing-plans` | Turn each requirement into **acceptance criteria + integration tests** — a behavioral spec (no implementation code) |
+| **Execute** | `/skill:pwk-executing-tasks` | Per requirement: write tests (red) → **checkpoint: tests** → implement (green) → **checkpoint: complete** → code-review |
+| **Code review** | `/skill:pwk-code-review` | Per requirement: code tracing, spec alignment, code smells (applies fixes), production hazard check |
+| **Finalize** | `/skill:pwk-finalizing` | Delete consumed plan docs, update README/CHANGELOG, create PR |
+| **Diagnose** | `/skill:pwk-diagnose` | Debugging loop: reproduce → hypothesise → instrument → fix → cleanup |
+| **Status** | `/skill:pwk-status` | Read-only overview of all active design topics — phase + progress. Use when resuming or juggling several designs in parallel worktrees. Not a pipeline phase. |
 
 ## The Workflow in Detail
 
@@ -57,51 +72,61 @@ brainstorm → design-review → plan → execute → verify → finalize
 
 You control each phase — the agent never advances on its own. Invoke a skill to move forward:
 
-/skill:brainstorming   →  discuss and design
-/skill:design-review   →  audit for production risks (non-trivial designs)
-/skill:writing-plans   →  break into tasks
-/skill:executing-tasks →  implement with TDD
-/skill:verify          →  review code for security, optimization, and traceability issues
-/skill:finalizing      →  ship it
+```
+/skill:pwk-brainstorming   →  discuss and design (lists Requirements)
+/skill:pwk-writing-plans   →  turn each Requirement into acceptance criteria + integration tests
+/skill:pwk-executing-tasks →  implement per requirement with two mandatory checkpoints
+/skill:pwk-code-review     →  auto-runs per-requirement inside executing-tasks; also invocable manually for ad-hoc reviews
+/skill:pwk-finalizing       →  ship it
+```
+
+### Behavioral-Spec Planning
+
+Plans specify *what*, not *how*. For each requirement, the plan gives **acceptance criteria + integration-test cases** — no implementation code, no file-by-file recipe. The executor has full autonomy to choose structure, signatures, and internals. A fine-grained implementation plan invalidates the moment a detail shifts; acceptance criteria + integration tests survive implementation changes.
 
-### TDD Three-Scenario Model
+### Test-First per Requirement
 
-Each task is labeled with its TDD scenario during planning:
+Each requirement is implemented test-first:
 
-| Scenario | When | Rule |
-|----------|------|------|
-| **New feature** | Adding new behavior | Write failing test → implement → pass |
-| **Modifying tested code** | Changing existing behavior | Run existing tests first → modify → verify |
-| **Trivial** | Config, docs, naming | Use judgment |
+1. Write the integration tests (red)
+2. ⏸ **checkpoint: tests** — you review the test design
+3. Implement to green (full autonomy)
+4. ⏸ **checkpoint: complete** — you review the implementation
+5. Commit → code review
 
 ### Lessons Learned
 
-A persistent rules file (`docs/lessons.md`) helps the agent learn from repeat mistakes across sessions. When the agent catches itself making the same error — like forgetting to run `make lint` — it writes a rule immediately. Future sessions (even after `/new`) pick it up automatically.
+A persistent rules file (`docs/lessons.md`) helps the agent learn from repeat mistakes across sessions. When the agent catches itself making the same error, it writes a generic rule immediately. Future sessions (even after `/new`) pick it up automatically.
 
 ```
 brainstorm → reads lessons (design context)
-plan        → reads lessons (task breakdown)
-execute     → reads lessons per task, writes new ones on repeat mistakes
-finalize    → reviews and retires stale rules
+plan        → reads lessons (acceptance criteria / tests)
+execute     → reads lessons per requirement, writes new ones on repeat mistakes
+finalize    → reviews, generalizes, and retires stale rules
 ```
 
 Rules are simple imperative bullets:
 
-- After completing each task, run `make lint && make fmt` before committing
+- After completing each requirement, run `make lint && make fmt` before committing
 - Never import `testify` in this project
 - Always check for existing test helpers before writing new ones
 
-No configuration needed — the file is created automatically when the first lesson is written.
+No configuration needed — the file ships with starter rules and grows as the agent learns.
 
-### Checkpoint Review Gates
+### Two Mandatory Checkpoints per Requirement
 
-Optionally label tasks with a `checkpoint` to pause for human review. At each checkpoint the agent stops and waits for your feedback — you can approve, ask for changes, or send it back to rethink. Only when you're satisfied does it move on to the next task.
+Each requirement has **two hard human-review gates** (not optional):
 
-| Checkpoint | When to Use | What Happens |
+| Checkpoint | What's done | What you review |
 |---|---|---|
-| *(none)* | Trivial tasks, well-understood changes | Auto-advance, no pause |
-| `checkpoint: test` | Test design matters | Agent writes the failing test, then pauses for your review. Verify the test covers the right cases before the agent implements. |
-| `checkpoint: done` | Implementation review matters | Agent implements and passes tests, then pauses for your review. Verify the implementation is correct before committing. |
+| **tests** | Integration tests written, confirmed failing | Are the right behaviors being specified? |
+| **complete** | Implemented, tests green, refactored | Is the implementation correct before committing? |
+
+The agent stops and waits at each — approve, request changes, or send it back.
+
+### Before You Ship: the Integration Gate
+
+Per-requirement review checks each diff in isolation. Before finalizing, the agent runs an **integration gate**: the **full test suite** (not just the last requirement's) must pass, and it confirms the requirements compose into the feature the design described. Finalize re-runs the full suite too — it never ships a red suite, even across resumed sessions.
 
 ## Quick Start
 
@@ -110,36 +135,30 @@ Optionally label tasks with a `checkpoint` to pause for human review. At each ch
 pi install npm:@tianhai/pi-workflow-kit
 
 # Start a new feature
-> /skill:brainstorming
+> /skill:pwk-brainstorming
 > I want to add OAuth2 login to our API
 
-# (agent explores approaches, writes design doc)
+# (agent explores approaches, writes a design doc with a Requirements list)
 # (write/edit are blocked — your code is safe)
 
-> /skill:design-review
-
-# (agent audits for security, scalability, fault tolerance)
-# (trivial changes can skip this step)
+> /skill:pwk-writing-plans
 
-> /skill:writing-plans
+# (agent turns each Requirement into acceptance criteria + integration tests)
 
-# (agent breaks design into TDD tasks with acceptance criteria)
-> /skill:executing-tasks
+> /skill:pwk-executing-tasks
 
-# (agent implements with TDD, cognitive persona shifts, all tools unlocked)
-> /skill:verify
+# (per requirement: writes tests → checkpoint → implements → checkpoint → code-review)
 
-# (agent runs security, optimization, and traceability reviews on implemented code)
-> /skill:finalizing
+> /skill:pwk-finalizing
 
-# (agent archives docs, curates lessons, creates PR)
+# (agent deletes consumed plan docs, curates lessons, creates PR)
 ```
 
 ## Why?
 
 - **AI agents skip design.** Left unchecked, they jump to code and over-engineer. This forces a think-first workflow.
-- **TDD needs structure.** The three-scenario model gives the agent clear rules for when to write tests first.
-- **You stay in control.** Checkpoint review gates let you approve test designs and implementations before the agent commits.
+- **Specs beat recipes.** Plans are behavioral specs (acceptance criteria + tests), not implementation recipes — they don't invalidate when details change.
+- **You stay in control.** Two mandatory checkpoints per requirement let you approve test design and implementation before the agent commits.
 - **Enforced, not suggested.** Hard blocks mean the agent can't ignore the rules — not even accidentally.
 
 ## Project
@@ -147,15 +166,23 @@ pi install npm:@tianhai/pi-workflow-kit
 ```
 pi-workflow-kit/
 ├── extensions/
-│   └── workflow-guard.ts      # Write blocker during brainstorm/plan
+│   └── workflow-guard.ts      # Write blocker during brainstorm/plan; destructive-bash blacklist
 ├── skills/
-│   ├── brainstorming/SKILL.md
-│   ├── design-review/SKILL.md
-│   ├── writing-plans/SKILL.md
-│   ├── executing-tasks/SKILL.md
-│   ├── verify/SKILL.md
-│   ├── finalizing/SKILL.md
-│   └── diagnose/SKILL.md
+│   ├── pwk-brainstorming/SKILL.md
+│   ├── pwk-writing-plans/SKILL.md
+│   ├── pwk-executing-tasks/SKILL.md
+│   ├── pwk-code-review/SKILL.md
+│   ├── pwk-finalizing/SKILL.md
+│   ├── pwk-status/SKILL.md
+│   └── pwk-diagnose/SKILL.md
+├── agents/                   # package agents for parallel code-review (discovered by pi-subagents)
+├── docs/
+│   ├── developer-usage-guide.md
+│   ├── workflow-phases.md
+│   ├── oversight-model.md
+│   ├── lessons.md
+│   ├── adr/                  # permanent architectural decisions (never archived)
+│   └── plans/                # active design/plan/progress docs (deleted after finalization)
 ├── tests/
 │   └── workflow-guard.test.ts
 ├── package.json
@@ -170,4 +197,4 @@ npm test
 
 ## License
 
-[MIT](LICENSE)
+[MIT](LICENSE)

package/agents/pwk-hazard-reviewer.md

@@ -0,0 +1,24 @@
+---
+name: pwk-hazard-reviewer
+description: Production-hazard reviewer — audits for unbounded ops, missing indexes, unbounded concurrency, long transactions, injection, silent swallowing loops. Read-only reporter.
+tools: read, grep, find, ls, bash
+systemPromptMode: replace
+---
+
+# PWK Hazard Reviewer
+
+You are a production-hazards reviewer. Execute the task instructions below faithfully using read-only tools (`read`, `grep`, `find`, `bash`). **Report findings only — do NOT modify files.** Flag hazards and non-trivial issues for the main agent / human to decide.
+
+## Checklist — audit each changed file
+
+For each item below, write `[SAFE]` (1-line justification) or `[TRIGGERED]` (concrete mitigation):
+
+1. **Unbounded operations** — multi-key deletions/scans (`KEYS`, raw `SCAN` loops), 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/suppressing exceptions without logging/back-off
+
+Also check the design doc's `## Production-risk areas`, if any.

package/agents/pwk-smell-reviewer.md

@@ -0,0 +1,17 @@
+---
+name: pwk-smell-reviewer
+description: Code-smell reviewer — flags shallow modules, duplication, missing seams, premature abstraction, poor naming, magic values, dead code. Read-only reporter.
+tools: read, grep, find, ls, bash
+systemPromptMode: replace
+---
+
+# PWK Smell Reviewer
+
+You are a code-smell reviewer. Execute the task instructions below faithfully using read-only tools (`read`, `grep`, `find`, `bash`). **Report findings only — do NOT modify files.** Flag only: smells that require large refactors risky to the requirement; everything else is for the main agent to fix.
+
+## Checklist — report what you find
+
+- Shallow modules (interface nearly as complex as implementation)
+- Duplication
+- Missing seams / premature abstraction
+- Poor naming, magic values, dead code

package/agents/pwk-spec-reviewer.md

@@ -0,0 +1,14 @@
+---
+name: pwk-spec-reviewer
+description: Spec-alignment reviewer — checks each acceptance criterion has covering code and tests; flags gaps and scope creep. Read-only reporter.
+tools: read, grep, find, ls, bash
+systemPromptMode: replace
+---
+
+# PWK Spec Reviewer
+
+You are a spec-alignment reviewer. Execute the task instructions below faithfully using read-only tools (`read`, `grep`, `find`, `bash`). **Report findings only — do NOT modify files.**
+
+## Checklist
+
+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.

package/agents/pwk-tracing-reviewer.md

@@ -0,0 +1,14 @@
+---
+name: pwk-tracing-reviewer
+description: Code-tracing reviewer — traces new/changed paths end-to-end against tests; flags untested branches, dead branches, and broken traces. Read-only reporter.
+tools: read, grep, find, ls, bash
+systemPromptMode: replace
+---
+
+# PWK Trace Reviewer
+
+You are a code-tracing reviewer. Execute the task instructions below faithfully using read-only tools (`read`, `grep`, `find`, `bash`). **Report findings only — do NOT modify files.**
+
+## Checklist
+
+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.

package/docs/developer-usage-guide.md

@@ -4,8 +4,9 @@ How to install and use `pi-workflow-kit` with the Pi coding agent.
 
 ## What you get
 
-- **4 skills** that guide the agent through a structured workflow
-- **1 extension** that hard-blocks source writes during brainstorm and plan phases
+- **5 pipeline skills** — brainstorm → writing-plans → executing-tasks → finalizing, with code-review running per requirement during execution.
+- **2 utility skills** — diagnose (debugging) and status (multi-topic overview), both on demand.
+- **1 extension** — hard-blocks source writes during brainstorm and writing-plans, and blocks destructive bash via a simple common-blacklist.
 
 ## Installation
 
@@ -31,82 +32,93 @@ Or in `.pi/settings.json` / `~/.pi/agent/config.json`:
 
 ## The workflow
 
-You control each phase by invoking the skill:
+You control each phase by invoking the skill. A design doc is one PR; a requirement is one testable slice within it. For multi-design work (a large issue split), run the pipeline once per design doc:
 
 ```
-/skill:brainstorming  →  /skill:writing-plans  →  /skill:executing-tasks  →  /skill:finalizing
+/skill:pwk-brainstorming  →  /skill:pwk-writing-plans  →  /skill:pwk-executing-tasks  →  /skill:pwk-finalizing
 ```
 
 ### 1. Brainstorm
 
 ```
-/skill:brainstorming
+/skill:pwk-brainstorming
 ```
 
-Explore the idea through collaborative dialogue. The agent reads code, asks questions one at a time, proposes 2-3 approaches, and presents the design in sections for your review.
+Explore the idea through collaborative dialogue. The agent reads code, asks questions, proposes approaches, and presents the design for your review.
 
-Outcome: `docs/plans/YYYY-MM-DD-<topic>-design.md`
-
-Optionally writes ADRs to `docs/plans/adr/` for significant architectural decisions.
+Outcome: `docs/plans/YYYY-MM-DD-<topic>-design.md` — descriptive, opening with a `## Requirements` list. May split a large issue into multiple design docs. ADRs go to `docs/adr/` (permanent).
 
 ### 2. Plan
 
 ```
-/skill:writing-plans
+/skill:pwk-writing-plans
 ```
 
-Read the design doc and break it into bite-sized tasks with exact file paths, complete code, and TDD scenarios. Optionally set up a branch or worktree.
+Read the design doc's Requirements and turn each into **acceptance criteria + integration-test cases** — a behavioral spec (no implementation code).
 
-Outcome: `docs/plans/YYYY-MM-DD-<topic>-implementation.md`
+Outcome: `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
 
 ### 3. Execute
 
 ```
-/skill:executing-tasks
+/skill:pwk-executing-tasks
 ```
 
-Implement the plan task-by-task. Each task: implement → run tests → fix if needed → commit.
+Implement requirement-by-requirement with **full autonomy**: write the integration tests (red) → **checkpoint: tests** → implement to green → **checkpoint: complete** → commit → code-review. Two mandatory human checkpoints per requirement. After all requirements, an **integration gate** runs the full suite and confirms the requirements compose into the feature before finalize.
+
+### 4. Code review (per requirement)
+
+The `pwk-executing-tasks` skill invokes the `subagent` tool automatically (programmatic, not user-driven). Four specialized reviewers launch in parallel — each reviewing from a different dimension (spec gaps & scope creep, end-to-end code tracing, code smells, production hazards). The reviewers ship as **package agents** (`agents/pwk-*.md`, declared via the `pi-subagents.agents` manifest key) and are discovered natively by the optional **`pi-subagents`** package — no copy step. All report findings only; no agent edits files or produces commits. The main agent collects results, applies smell fixes itself, runs integration tests after each fix, then updates progress to `✅ done`.
+
+*Fallback:* if `pi-subagents` is not installed (so the `subagent` tool is unavailable), the skill falls back to inline `/skill:pwk-code-review` as before. Install it to enable parallel review:
 
-### 4. Finalize
+```bash
+pi install npm:pi-subagents
+```
+
+### 5. Finalize
 
 ```
-/skill:finalizing
+/skill:pwk-finalizing
 ```
 
-Archive plan docs, update CHANGELOG/README, create PR, clean up worktree.
+**Pre-check: run the full test suite** — never ship a red suite (resume spans sessions). Then delete consumed plan docs (code + tests are the source of truth), curate lessons, update CHANGELOG/README, create PR or merge.
 
-### 5. Diagnose (on demand)
+### Diagnose (on demand)
 
 ```
-/skill:diagnose
+/skill:pwk-diagnose
 ```
 
-A 6-phase debugging loop you invoke when something is broken. Build a feedback loop first, then reproduce, hypothesise, instrument, fix, and cleanup. Not a pipeline phase — use whenever needed.
+A debugging loop you invoke when something is broken. Not a pipeline phase.
 
-## What the extension does
+### Status (on demand)
 
-The `workflow-guard` extension watches `write` and `edit` tool calls:
+```
+/skill:pwk-status
+```
 
-- **During brainstorm and plan**: blocks writes outside `docs/plans/`. The agent can read code and use bash, but cannot modify source files.
-- **During execute and finalize**: no restrictions. All tools available.
+A read-only overview of all active design topics — which phase each is in and how far along. Use when resuming work or juggling several designs in parallel (e.g. across worktrees) and you're unsure which topic to continue. Not a pipeline phase.
 
-No configuration needed. It activates automatically after install.
+## What the extension does
 
-## TDD guidance
+The `workflow-guard` extension watches `write`/`edit` and `bash` tool calls:
 
-The plan labels each task with a TDD scenario:
+- **During brainstorm and writing-plans**: blocks writes outside `docs/plans/`, and blocks destructive bash via a simple common-blacklist (a command is allowed unless it matches a destructive pattern). A short phase reminder is shown once when the gated phase begins so the model self-restricts.
+- **During executing-tasks, code-review, finalizing**: no restrictions.
+- **Phases are skill-driven**: the guard follows the skill you invoke — it never unlocks on message keywords. To override, run `/pwk-guard on` (force read-only), `off` (disable), or `auto` (default; skill-driven). Subcommands autocomplete.
+
+The destructive blacklist covers common file-mutating vectors (redirects, `tee`, `cp`/`mv`/`touch`/`rm`, `git commit`/`apply`, `npm install`, in-place editors like `sed -i`/`perl -i`, `patch`, `find -delete`). Exotic vectors (interpreter escapes like `node -e`, `python -c`, `| bash`) rely on the phase reminder — the guard is advisory, not a security boundary.
+
+No configuration needed. It activates automatically after install.
 
-| Scenario | When | Rule |
-|----------|------|------|
-| New feature | Adding new behavior | Write failing test → implement → pass |
-| Modifying tested code | Changing existing behavior | Run existing tests first → modify → verify |
-| Trivial | Config, docs, naming | Use judgment |
+## Test-first discipline
 
-This is guidance in the skill instructions, not runtime enforcement.
+Plans specify *what* (acceptance criteria + integration tests); the executor writes the tests first (red), then implements to green. This keeps the spec stable — implementation details can change without invalidating the plan.
 
 ## Tips
 
-- Start with brainstorming for anything non-trivial
-- Use writing-plans before touching code for multi-step work
-- Put all plan artifacts under `docs/plans/`
-- During execute, the agent handles code review feedback by verifying criticism before implementing
+- Start with brainstorming for anything non-trivial.
+- The plan is a behavioral spec, not an implementation recipe — let the executor choose how.
+- Each requirement has two mandatory checkpoints: use them to steer test design and implementation.
+- Put all plan artifacts under `docs/plans/`; ADRs under `docs/adr/`.

package/docs/lessons.md

@@ -0,0 +1,13 @@
+# Lessons Learned
+
+<!--
+Agent: read this during brainstorm (design), writing-plans (acceptance criteria + tests), executing-tasks (per requirement), and finalizing (curation).
+Follow every rule. Add new rules when you catch yourself making repeat mistakes.
+Rules must be generic patterns applicable to any domain or feature — not specific to one service, entity, or use case.
+Retire rules that no longer apply during finalizing.
+-->
+
+## Cross-Skill Consistency
+
+
+## Documentation

package/docs/oversight-model.md

@@ -4,14 +4,20 @@
 
 ## Skills
 
-Skills teach the agent the workflow. There are 4:
+Skills teach the agent the workflow. There are 5 pipeline skills:
 
-- **brainstorming** — explore ideas, produce a design doc
-- **writing-plans** — break design into TDD tasks
-- **executing-tasks** — implement tasks, handle code review
-- **finalizing** — archive docs, create PR
+- **pwk-brainstorming** — explore ideas, produce a descriptive design doc that opens with a `## Requirements` list
+- **pwk-writing-plans** — turn each requirement into acceptance criteria + integration-test cases (a behavioral spec, no implementation code)
+- **pwk-executing-tasks** — implement requirement-by-requirement, test-first, with two mandatory human checkpoints per requirement
+- **pwk-code-review** — the inline reviewer (code tracing, spec alignment, code smells, production hazards). During `pwk-executing-tasks`, per-requirement review instead runs **four specialized reviewers in parallel** via the `subagent` tool, each from a fresh context (spec gaps & scope creep, tracing, smells, hazards). These ship as package agents (`agents/pwk-*.md`) discovered natively by the optional **`pi-subagents`** package; all report findings only — fixes are applied by the executing-tasks main agent. Falls back to inline `/skill:pwk-code-review` when `pi-subagents` is not installed.
+- **pwk-finalizing** — delete consumed plan docs, curate lessons, update docs, create PR or merge
 
-They explain *what* to do and *when* to do it.
+Plus 2 on-demand skills:
+
+- **pwk-status** — read-only overview of all active design topics (phase + progress), for resuming or juggling parallel designs
+- **pwk-diagnose** — 6-phase debugging loop, invoked anytime something is broken
+
+They explain *what* to do and *when* to do it. Phase control is manual — you invoke each skill with `/skill:`; the agent never advances on its own.
 
 ## Extension
 
@@ -19,10 +25,14 @@ The `workflow-guard` extension enforces one rule:
 
 > During brainstorm and plan phases, `write` and `edit` are **hard-blocked** outside `docs/plans/`.
 
-The agent can still use `read` and `bash` for investigation. It literally cannot call `write` or `edit` on source files — the tools are blocked at the extension level.
+The agent can still use `read` and `bash` for investigation. During those gated phases, `bash` is governed by a simple destructive-command blacklist (`rm`, `>`, `git commit`, `npm install`, in-place editors, etc.) — a command is allowed unless it matches a destructive pattern. A short phase reminder is shown once when the gated phase begins so the model self-restricts.
+
+During executing-tasks, code-review, and finalizing, nothing is restricted.
+
+Phases follow the skill you invoke — there is no message-keyword unlock. `/pwk-guard on|off|auto` manually overrides the guard (`on` = force read-only lock, `off` = disabled, `auto` = skill-driven, the default); subcommands autocomplete.
 
 ## Enforcement style
 
-Hard block for write boundaries. No warnings, no escalation, no prompts. Either the tool call is allowed or it's blocked.
+Hard block for write boundaries during gated phases. No warnings, no escalation, no prompts. Either the tool call is allowed or it's blocked.
 
-TDD, debugging, and code review are guidance in the skill instructions, not runtime-enforced.
+TDD, checkpoints, debugging, and code review are guidance in the skill instructions, not runtime-enforced. The bash blacklist covers common destructive vectors only; exotic escapes (interpreter one-liners, piped shells) rely on the phase reminder — the guard is advisory, not a security boundary.