@tianhai/pi-workflow-kit 0.16.0 → 0.18.1

package/README.md

@@ -1,6 +1,6 @@
 # pi-workflow-kit
 
-> Stop AI agents from rushing to code. Enforce a structured brainstorm→plan→execute→finalize workflow with TDD discipline.
+> Stop AI agents from rushing to code. Enforce a structured brainstorm→plan→execute→verify→finalize workflow with TDD discipline.
 
 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.
 
@@ -28,29 +28,30 @@ 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…) |
+| **Brainstorm** / **Plan** / **Verify** | 🔒 Blocked outside `docs/plans/` | 🔒 Read-only only (grep, find, cat, git status, curl…) |
 | **Execute** / **Finalize** | ✅ 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.
 
-### 🧠 6 Workflow Skills
+### 🧠 7 Workflow Skills
 
 Guide the agent through a disciplined development process:
 
-```
-brainstorm → design-review → plan → execute → finalize
-                                    ↕
-                                 diagnose (anytime)
-```
+brainstorm → plan → [design-review?] → execute → [verify?] → finalize
+                ↕
+             diagnose (anytime)
+
+For multi-feature designs, the plan→execute loop repeats per feature.
 
 | 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 |
-| **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, debate tradeoffs, produce a design doc with a Features table |
+| **Design Review** | `/skill:pwk-design-review` | Audit plan and design for production risks (security, scalability, fault tolerance) |
+| **Plan** | `/skill:pwk-writing-plans` | Plan one feature at a time from the Features table — bite-sized TDD tasks with acceptance criteria |
+| **Execute** | `/skill:pwk-executing-tasks` | Implement tasks one-by-one with TDD discipline and pre-commit checkpoint review gates |
+| **Verify** | `/skill:pwk-verify` | Three expert review passes (security, optimization, traceability) on implemented code |
+| **Finalize** | `/skill:pwk-finalizing` | Archive plan docs, update README/CHANGELOG, create PR |
+| **Diagnose** | `/skill:pwk-diagnose` | 6-phase debugging loop: reproduce → hypothesize → instrument → fix → verify |
 
 ## The Workflow in Detail
 
@@ -58,13 +59,24 @@ brainstorm → design-review → plan → execute → 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:finalizing      →  ship it
-```
+/skill:pwk-brainstorming   →  discuss and design (names features)
+/skill:pwk-writing-plans   →  plan next feature from the Features table
+/skill:pwk-design-review   →  audit for production risks (on demand)
+/skill:pwk-executing-tasks →  implement with TDD
+/skill:pwk-verify           →  review code for security, optimization, and traceability
+/skill:pwk-finalizing       →  ship it
+
+### Feature-Based Planning
+
+Design docs include a `## Features` table that tracks each feature's status:
+
+| # | Feature | Status | Notes |
+|---|---------|--------|-------|
+| 1 | User signup | ✅ done | |
+| 2 | Email verification | 🔄 planned | Plan: docs/plans/...-email-verification-implementation.md |
+| 3 | Password reset | ⬜ pending | |
+
+This enables incremental development — plan and execute one feature at a time, then loop back for the next.
 
 ### TDD Three-Scenario Model
 
@@ -112,24 +124,23 @@ 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 design doc with Features table)
 # (write/edit are blocked — your code is safe)
 
-> /skill:design-review
+> /skill:pwk-writing-plans
 
-# (agent audits for security, scalability, fault tolerance)
-# (trivial changes can skip this step)
-
-> /skill:writing-plans
-
-# (agent breaks design into TDD tasks with acceptance criteria)
-> /skill:executing-tasks
+# (agent picks next feature, breaks into TDD tasks)
+# (triggers design review for non-trivial features)
+> /skill:pwk-executing-tasks
 
 # (agent implements with TDD, cognitive persona shifts, all tools unlocked)
-> /skill:finalizing
+> /skill:pwk-verify
+
+# (agent runs security, optimization, and traceability reviews on implemented code)
+> /skill:pwk-finalizing
 
 # (agent archives docs, curates lessons, creates PR)
 ```
@@ -146,14 +157,15 @@ 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/verify
 ├── skills/
-│   ├── brainstorming/SKILL.md
-│   ├── design-review/SKILL.md
-│   ├── writing-plans/SKILL.md
-│   ├── executing-tasks/SKILL.md
-│   ├── finalizing/SKILL.md
-│   └── diagnose/SKILL.md
+│   ├── pwk-brainstorming/SKILL.md
+│   ├── pwk-design-review/SKILL.md
+│   ├── pwk-writing-plans/SKILL.md
+│   ├── pwk-executing-tasks/SKILL.md
+│   ├── pwk-verify/SKILL.md
+│   ├── pwk-finalizing/SKILL.md
+│   └── pwk-diagnose/SKILL.md
 ├── tests/
 │   └── workflow-guard.test.ts
 ├── package.json

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
+- **4 workflow skills** that guide the agent through a structured feature-based workflow
+- **3 on-demand skills** for design review, verification, and debugging
+- **1 extension** that hard-blocks source writes during brainstorm, plan, and verify phases
 
 ## Installation
 
@@ -31,54 +32,70 @@ 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. For multi-feature designs, the plan→execute loop repeats per feature:
 
 ```
-/skill:brainstorming  →  /skill:writing-plans  →  /skill:executing-tasks  →  /skill:finalizing
+/skill:pwk-brainstorming  →  /skill:pwk-writing-plans  →  /skill:pwk-executing-tasks  →  loop or /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.
 
-Outcome: `docs/plans/YYYY-MM-DD-<topic>-design.md`
+Outcome: `docs/plans/YYYY-MM-DD-<topic>-design.md` with a `## Features` table
 
 Optionally writes ADRs to `docs/plans/adr/` for significant architectural decisions.
 
 ### 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 Features table, pick the next `⬜ pending` feature, and create a per-feature implementation plan with exact file paths, complete code, and TDD scenarios. Optionally set up a branch or worktree.
 
-Outcome: `docs/plans/YYYY-MM-DD-<topic>-implementation.md`
+Outcome: `docs/plans/YYYY-MM-DD-<topic>-<feature-name>-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 the plan task-by-task. Each task: implement → run tests → fix if needed → commit. When the feature is done, marks it `✅ done` in the design doc and suggests planning the next feature.
 
 ### 4. Finalize
 
 ```
-/skill:finalizing
+/skill:pwk-finalizing
 ```
 
 Archive plan docs, update CHANGELOG/README, create PR, clean up worktree.
 
-### 5. Diagnose (on demand)
+### 5. Design Review (on demand)
 
 ```
-/skill:diagnose
+/skill:pwk-design-review
+```
+
+Audit a plan doc for production risks — security, scalability, fault tolerance, and operational hazards. Triggered by writing-plans for non-trivial features. Review findings append to the plan doc, not the design doc.
+
+### 6. Verify (on demand)
+
+```
+/skill:pwk-verify
+```
+
+Post-implementation verification with three expert passes — security, optimization, and traceability. Run after executing a feature or before finalizing.
+
+### 7. Diagnose (on demand)
+
+```
+/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.
@@ -88,6 +105,7 @@ A 6-phase debugging loop you invoke when something is broken. Build a feedback l
 The `workflow-guard` extension watches `write` and `edit` tool calls:
 
 - **During brainstorm and plan**: blocks writes outside `docs/plans/`. The agent can read code and use bash, but cannot modify source files.
+- **During verify**: same read-only enforcement — the agent can inspect code but not modify it.
 - **During execute and finalize**: no restrictions. All tools available.
 
 No configuration needed. It activates automatically after install.

package/docs/lessons.md

@@ -0,0 +1,18 @@
+# Lessons Learned
+
+<!--
+Agent: read this at the start of each task during executing-tasks.
+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
+
+- When adding instructions that reference artifacts from another skill (e.g., "extract metadata from plan doc"), always add a guard for when that artifact doesn't exist — not all workflows use all artifacts
+- When reordering instructions within a step, verify all conditional branches still reference the correct context (e.g., hazard checks that say "this feature" must run after feature identification)
+
+## Documentation
+
+- When adding a new phase to an extension, update ALL comments and error messages — stale comments in one place create confusion about the actual behavior
+- When renaming skills with a prefix, check for `/skill:` references in prose and code blocks separately — backtick-enclosed references in code examples may use a different pattern than prose references

package/docs/oversight-model.md

@@ -6,10 +6,16 @@
 
 Skills teach the agent the workflow. There are 4:
 
-- **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 design doc with a Features table
+- **pwk-writing-plans** — plan one feature at a time from the Features table
+- **pwk-executing-tasks** — implement tasks, mark features done, loop to next feature
+- **pwk-finalizing** — archive docs, create PR
+
+Plus 3 on-demand skills:
+
+- **pwk-design-review** — audit a plan doc for production risks (triggered by writing-plans)
+- **pwk-verify** — post-implementation verification with security, optimization, and traceability passes
+- **pwk-diagnose** — 6-phase debugging loop
 
 They explain *what* to do and *when* to do it.
 
@@ -17,7 +23,7 @@ They explain *what* to do and *when* to do it.
 
 The `workflow-guard` extension enforces one rule:
 
-> During brainstorm and plan phases, `write` and `edit` are **hard-blocked** outside `docs/plans/`.
+> During brainstorm, plan, and verify 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.
 

package/docs/plans/2026-06-03-karpathy-guidelines-ab-comparison.md

@@ -0,0 +1,166 @@
+# A/B Comparison: Writing Plans — Karpathy Behavioral Guidelines
+
+## Setup
+- **Same design doc** (bookmarks: CRUD + search)
+- **Same Go project scaffold**
+- **Same prompt** (no questions, full plan with concrete code)
+- **Variant A** (WITHOUT guidelines): 292-line SKILL.md — original writing-plans skill
+- **Variant B** (WITH guidelines): 354-line SKILL.md — with Behavioral Guidelines section appended
+
+---
+
+## Structural Comparison
+
+| Dimension | A (Without) | B (With) |
+|---|---|---|
+| **Total tasks** | 4 | 6 |
+| **Lines in plan** | ~1,054 | ~1,019 |
+| **New files per plan** | 7 files in Task 1 alone | 1-2 files per task |
+| **External dependency** | None (stdlib only) | `github.com/google/uuid` |
+
+---
+
+## Task Decomposition
+
+### A (Without) — 4 tasks
+| Task | Scope | Files touched |
+|---|---|---|
+| 1 | Bookmark + ALL infrastructure (model, store interface, mem store with full CRUD, service, handler, errors, route, tests) | 7 files |
+| 2 | Delete bookmark | 3 files |
+| 3 | List bookmarks (paginated, cursor) | 3 files |
+| 4 | Search bookmarks (keyword + pagination) | 3 files |
+
+### B (With) — 6 tasks
+| Task | Scope | Files touched |
+|---|---|---|
+| 1 | Scaffold (go.mod + model only) | 2 files |
+| 2 | Bookmark a message (store + handler + test + route) | 4 files |
+| 3 | List bookmarks (offset/limit pagination) | 4 files |
+| 4 | Remove a bookmark | 4 files |
+| 5 | Search bookmarks (keyword) | 4 files |
+| 6 | Final wiring + integration lifecycle test | 2 files |
+
+---
+
+## Detailed Analysis by Guideline
+
+### Simplicity First
+
+**A (Without):** ⚠️ **Overbuilt in Task 1.** Task 1 creates a `BookmarkStore` interface with 4 methods (Create, Delete, ListByUser, SearchByUser) — methods that won't be used until Tasks 2-4. It also creates the full `MemoryStore` implementation with all 4 methods, an `errors.go` file, a `Service` struct, AND the handler — all in a single task. The store interface is the full contract upfront before any task exercises most of it.
+
+**B (With):** ✅ **Minimal per task.** Task 1 only creates `go.mod` + the `Bookmark` struct. Task 2 introduces `Store` with only `Create`, and `MemStore` with only `Create`. `List` is added to the interface in Task 3, `Delete` in Task 4, `Search` in Task 5 — each method appears when it's needed, not before.
+
+**Verdict:** Guidelines had a clear positive effect. Plan B builds only what each task needs.
+
+### Surgical Changes
+
+**A (Without):** ⚠️ Task 1 touches 7 files in one go (model, store interface, store mem, errors, service, handler, main.go). The Task 1 description says "create the full vertical slice" which bundles infrastructure that isn't tested yet.
+
+**B (With):** ✅ Each task touches 1-2 files for new code. Task 1 creates 2 files (go.mod, model.go). Task 2 adds 3 new files + modifies main.go. No task creates more than 4 files.
+
+**Verdict:** Guidelines had a clear positive effect. Plan B has tighter blast radius per task.
+
+### Think Before Coding (surface assumptions)
+
+**A (Without):** ❌ Silent assumptions throughout:
+- Used cursor-based pagination without noting the design just said "paginated" — didn't surface that offset-based vs cursor-based is a choice
+- Added `sync.RWMutex` and concurrent safety without the design mentioning concurrency
+- Created a `Service` layer between handler and store without justification
+
+**B (With):** ⚠️ Still has assumptions but more defensible:
+- Used offset/limit pagination (simpler, matches "paginated" literally)
+- No concurrency concerns added (store uses `sync.Mutex` only, no RWMutex overhead)
+- No `Service` layer — handler calls store directly
+- Did add `github.com/google/uuid` dependency without asking — minor assumption
+
+**Verdict:** Marginal positive effect. Plan B is less presumptuous but both plans made assumptions. Neither explicitly surfaced tradeoffs to the user.
+
+### Goal-Driven Execution
+
+**A (Without):** ✅ Good acceptance criteria with Given/When/Then. Has a `checkpoint: test` on 3/4 tasks and `checkpoint: done` on the last task.
+
+**B (With):** ✅ Good acceptance criteria. Has `checkpoint: test` on 3 tasks, `checkpoint: done` on 1, and no checkpoint on 2 simpler tasks. Added a full lifecycle integration test in Task 6 that wasn't in A.
+
+**Verdict:** Roughly equivalent. Both plans have strong acceptance criteria (required by the base skill). The lifecycle test in B is a nice bonus that catches integration issues.
+
+---
+
+## Unrelated Observations (noise, not guidelines)
+
+| Observation | A (Without) | B (With) |
+|---|---|---|
+| Pagination style | Cursor-based (more complex) | Offset-based (simpler) |
+| External deps | None | `google/uuid` |
+| Handler method naming | `Create`, `Delete`, `List`, `Search` | `CreateBookmark`, `DeleteBookmark`, `ListBookmarks`, `SearchBookmarks` |
+| Test structure | Single `TestXxx` with `t.Run` subtests | Separate top-level test functions |
+| `make([]T, 0, len)` usage | Yes (mem store candidates) | Yes (list handler, search handler) |
+
+---
+
+## Overall Assessment
+
+| Guideline | Effect | Evidence |
+|---|---|---|
+| **Simplicity First** | ✅ Strong positive | B builds incrementally; A front-loads the full store interface |
+| **Surgical Changes** | ✅ Positive | B touches fewer files per task (1-4 vs 7 in Task 1) |
+| **Think Before Coding** | ⚠️ Marginal | B made fewer silent assumptions but neither surfaced tradeoffs explicitly |
+| **Goal-Driven Execution** | ≈ Neutral | Both strong; base skill already enforces acceptance criteria |
+
+**Bottom line (iteration 1):** The guidelines measurably improved the plan. The biggest win is **Simplicity First** — Plan B's incremental interface growth (adding methods to `Store` as each task needs them) is clearly better than Plan A's upfront full-contract approach. This is exactly the kind of thing "no abstractions for single-use code" catches.
+
+**Weakness:** Neither plan explicitly called out assumptions or asked clarifying questions — the "Think Before Coding" guideline had the weakest signal. The guidelines alone may not be enough to overcome the model's tendency to fill gaps silently.
+
+---
+
+## Iteration 2: Revised Guidelines
+
+### What changed
+
+The guidelines were reworked from 4 generic coding rules to 3 planning-specific principles:
+
+| v1 (Generic) | v2 (Planning-Specific) | Why |
+|---|---|---|
+| Think Before Coding | **Surface Assumptions** | v1 said "ask" — the agent ignores this when told not to ask. v2 says "annotate in the plan" with a concrete `> **Assumption:** ...` format and examples of what to annotate. |
+| Simplicity First | **Build Only What Each Task Needs** | Kept the same core principle but added the specific anti-pattern from the v1 A/B test: "don't define interface methods that no task exercises yet." |
+| Surgical Changes | **One Task, One Change** | Reframed from "don't touch adjacent code" to "each task should trace to exactly one user-facing behavior" with a concrete guardrail (max 4 new files). |
+| Goal-Driven Execution | *(removed)* | Redundant — the base skill already enforces Given/When/Then acceptance criteria. |
+
+### Iteration 2 Plan (v2 guidelines) vs Iteration 1 Plans
+
+| Dimension | A (No guidelines) | B1 (v1 guidelines) | B2 (v2 guidelines) |
+|---|---|---|---|
+| **Total tasks** | 4 | 6 | 4 |
+| **Max files/task** | 7 (Task 1) | 4 | 4 |
+| **Assumptions annotated** | 0 | 0 | **4** (header below) |
+| **External deps** | None | `google/uuid` | None |
+| **Store interface** | 4 methods upfront in Task 1 | 1 method per task | 1 method per task |
+| **Service layer** | Yes (unjustified) | No | No |
+
+### The big win: Surface Assumptions
+
+Plan B2 opens with four explicit assumption annotations:
+
+```
+> **Assumption:** User identification via X-User-ID request header since
+> no auth system exists in the project.
+
+> **Assumption:** Bookmarks include a Note field so users can annotate
+> bookmarks. The design says "search by keyword" but doesn't specify
+> the field.
+
+> **Assumption:** Offset/limit pagination (not cursor-based).
+
+> **Assumption:** In-memory store behind a Store interface.
+```
+
+None of the previous plans (A or B1) did this. The v1 "Think Before Coding" guideline was completely invisible in output. The v2 "Surface Assumptions" guideline produced visible, reviewable annotations on the first run.
+
+### Iteration 2 Assessment
+
+| Guideline | v1 Effect | v2 Effect | Improvement |
+|---|---|---|---|
+| **Surface Assumptions** (was Think Before Coding) | ⚠️ Invisible | ✅ 4 explicit annotations | Complete turnaround — concrete format + examples fixed the weakest signal |
+| **Build Only What's Needed** (was Simplicity First) | ✅ Strong | ✅ Strong | Maintained — interface still grows incrementally |
+| **One Task, One Change** (was Surgical Changes) | ✅ Positive | ✅ Positive | Maintained — max 4 files/task |
+
+**Bottom line (iteration 2):** The v2 guidelines fixed the weakest signal from v1. "Surface Assumptions" went from invisible to producing 4 explicit, reviewable annotations. The other two principles maintained their positive effect. The removal of "Goal-Driven Execution" (redundant) reduced noise without losing signal.

package/docs/plans/completed/2026-06-03-add-verify-skill-design.md

@@ -0,0 +1,51 @@
+# Add Verify Skill — Design Doc
+
+## Context
+
+Based on [Chris LeMa's "The Last Prompt"](https://chrislema.com/the-last-prompt-you-need-when-building-software-with-ai), we need a post-implementation code verification phase in pi-workflow-kit. The existing `design-review` skill validates architecture *intentions* at the design-doc level, but there's no review of the *actual implemented code*. This is where the most dangerous bugs hide: signature mismatches between layers, dead code, duplicated logic, and security holes that pass tests but break in production.
+
+## Decision
+
+### Add a `verify` skill (new)
+
+A single skill triggered by `/skill:verify` that runs three sequential expert review passes over implemented code:
+
+1. **Security** 🔴 — adversarial review as if a junior wrote it and the best security expert is auditing
+2. **Optimization** 🟡 — dead code, duplication, over/under-engineering, performance
+3. **Traceability** 🔵 — end-to-end call chain verification across every layer boundary
+
+Output: structured markdown report at `docs/plans/*-verification-report.md` with findings and actionable task list.
+
+### Keep `design-review` unchanged
+
+`design-review` stays between brainstorm and plan — it validates architecture before task breakdown. Moving it would lose the cheap "catch it before you build it" value.
+
+### Update README
+
+Add `verify` to the workflow diagram, skill table, and quick start. The pipeline becomes:
+
+```
+brainstorm → design-review → plan → execute → verify → finalize
+```
+
+## Workflow Integration
+
+```
+brainstorm → design-review (optional) → plan → execute → verify → finalize
+                                                 ↑         ↑
+                                           existing         new
+```
+
+- `verify` runs after `executing-tasks` and before `finalizing`
+- It's optional — trivial changes can skip it
+- The report's remediation task list feeds directly into a follow-up `/skill:writing-plans` if fixes are needed
+- Read-only: can write to `docs/plans/` only, cannot modify source code
+
+## Files to Change
+
+1. **`skills/verify/SKILL.md`** — new skill (full content in `docs/plans/2026-06-03-verify-skill-design.md`)
+2. **`README.md`** — update workflow diagram, skill table, quick start, and project structure
+
+## Production Risks
+
+Simple change — no design review needed. We're adding a new SKILL.md and updating documentation. No code execution, no external integrations, no security surface.

package/docs/plans/completed/2026-06-03-add-verify-skill-implementation.md

@@ -0,0 +1,111 @@
+# Implementation Plan: Add Verify Skill
+
+Design: `docs/plans/2026-06-03-add-verify-skill-design.md`
+
+## Overview
+
+Add a `verify` skill to pi-workflow-kit — a post-implementation code verification phase that runs three expert review passes (security, optimization, traceability) over implemented code. Also update the README to reflect the expanded workflow pipeline.
+
+Full SKILL.md content is in `docs/plans/2026-06-03-verify-skill-design.md` (lines 7-176, inside the code fence).
+
+## Task 1: Create the verify skill
+
+<!-- tdd: trivial -->
+
+Acceptance Criteria (QA Engineer Hat):
+- **Happy Path**:
+  - Given: No `skills/verify/` directory exists
+  - When: `skills/verify/SKILL.md` is created
+  - Then: The file contains valid YAML frontmatter with `name: verify` and a description mentioning security, optimization, and traceability. The file body contains all three review pass sections, the report format template, and the principles section.
+- **Edge Case (skill already exists)**:
+  - Given: `skills/verify/SKILL.md` already exists
+  - When: Task runs
+  - Then: The existing file is overwritten with the new content
+
+Files:
+- `skills/verify/SKILL.md`
+
+Steps:
+1. Create the directory `skills/verify/`
+2. Create `skills/verify/SKILL.md` with the full content from the design draft. The content is the markdown inside the code fence in `docs/plans/2026-06-03-verify-skill-design.md` (lines 8-176). Copy it exactly — it includes:
+   - YAML frontmatter with name and description
+   - # Verify heading and intro paragraph
+   - ## Process section (5 steps)
+   - ## Pass 1 — Security Review 🔴 (framing, what to look for, severity table)
+   - ## Pass 2 — Optimization Review 🟡 (framing, what to look for, priority table)
+   - ## Pass 3 — Traceability Review 🔵 (framing, what to look for 4 sub-items, severity table)
+   - ## Report Format section (full template with summary table, findings sections, remediation task list)
+   - ## Principles section (5 bullets)
+
+## Task 2: Update README with verify skill
+
+<!-- tdd: trivial -->
+
+Acceptance Criteria (QA Engineer Hat):
+- **Happy Path**:
+  - Given: README.md has the current workflow (brainstorm → design-review → plan → execute → finalize)
+  - When: README is updated
+  - Then: All five sections are updated — tagline, workflow diagram, skill table, phase control, quick start, and project structure — to include `verify` between execute and finalize.
+- **Edge Case (verify already in README)**:
+  - Given: README already contains verify references
+  - When: Task runs
+  - Then: No duplicate entries are introduced
+
+Files:
+- `README.md`
+
+Steps:
+
+1. Update the tagline (line 3) — change `brainstorm→plan→execute→finalize` to `brainstorm→plan→execute→verify→finalize`:
+   ```
+   > Stop AI agents from rushing to code. Enforce a structured brainstorm→plan→execute→verify→finalize workflow with TDD discipline.
+   ```
+
+2. Update the "🧠 6 Workflow Skills" heading (line 36) to "🧠 7 Workflow Skills"
+
+3. Update the workflow diagram (lines 40-44) to:
+   ```
+   brainstorm → design-review → plan → execute → verify → finalize
+                                            ↕
+                                         diagnose (anytime)
+   ```
+
+4. Add verify to the skill table (after the Execute row, before Finalize):
+   ```
+   | **Verify** | `/skill:verify` | Three expert review passes (security, optimization, traceability) on implemented code |
+   ```
+
+5. Update the phase control section (lines 61-67) to add verify:
+   ```
+   /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
+   ```
+
+6. Update the quick start section (lines 110-135) to add verify between executing-tasks and finalizing:
+   ```
+   > /skill:executing-tasks
+
+   # (agent implements with TDD, cognitive persona shifts, all tools unlocked)
+   > /skill:verify
+
+   # (agent runs security, optimization, and traceability reviews on implemented code)
+   > /skill:finalizing
+
+   # (agent archives docs, curates lessons, creates PR)
+   ```
+
+7. Update the project structure (lines 146-161) to add verify:
+   ```
+   ├── 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
+   ```

package/docs/plans/completed/2026-06-03-add-verify-skill-progress.md

@@ -0,0 +1,11 @@
+# Progress: Add Verify Skill
+
+Plan: docs/plans/2026-06-03-add-verify-skill-implementation.md
+Branch: add-verify-skill
+Started: 2026-06-03T13:00:00Z
+Last updated: 2026-06-03T13:00:00Z
+
+| # | Status | Task | Commit |
+|---|--------|------|--------|
+| 1 | ✅ done | Create the verify skill | c48d47a |
+| 2 | ✅ done | Update README with verify skill | ea37ea8 |