@tianhai/pi-workflow-kit 0.17.1 → 0.18.1

package/docs/plans/completed/2026-06-09-incremental-workflow-and-rename-verification-report.md

@@ -0,0 +1,81 @@
+# Verification Report: Incremental workflow and skill rename
+
+**Date:** 2026-06-09
+**Scope:** 10 commits on `incremental-workflow-and-rename` — pwk- prefix rename, feature-based planning, design-review repositioning, verify phase in workflow-guard
+**Reviewer:** AI verify skill (security + optimization + traceability)
+
+## Summary
+
+| Pass | Critical | High | Medium | Low |
+|------|----------|------|--------|-----|
+| Security | 0 | 0 | 0 | 0 |
+| Optimization | — | 0 | 0 | 3 |
+| Traceability | 0 | 0 | 2 | 1 |
+| **Total** | **0** | **0** | **2** | **4** |
+
+## 🔴 Security Findings
+
+No findings. This is a documentation/configuration-only change — no HTTP endpoints, no SQL queries, no user inputs, no secrets, no auth logic. No external attack surface.
+
+## 🟡 Optimization Findings
+
+### [O-001] P2 — Stale `shouldBlockFilePath` docstring
+
+**Location:** `extensions/workflow-guard.ts:150`
+
+**Issue:** JSDoc says "Only writes under docs/plans/ are allowed during brainstorm and plan phases" — missing the verify phase added in this change.
+
+**Fix:** Change to "...during brainstorm, plan, and verify phases."
+
+### [O-002] P2 — Stale `DESTRUCTIVE_PATTERNS` comment
+
+**Location:** `extensions/workflow-guard.ts:15`
+
+**Issue:** Comment says "Destructive commands blocked in brainstorm/plan phases" — missing verify.
+
+**Fix:** Change to "...in brainstorm/plan/verify phases."
+
+### [O-003] P2 — Inconsistent backtick formatting
+
+**Location:** `skills/pwk-executing-tasks/SKILL.md:158`
+
+**Issue:** `**Read \`docs/lessons.md\` if it exists**` is missing the closing backtick. All other skills use backtick-enclosed format: `**Read \`docs/lessons.md\`**`.
+
+**Fix:** Add closing backtick: `**Read \`docs/lessons.md\` if it exists**`
+
+## 🔵 Traceability Findings
+
+### [T-001] Medium — `writing-plans` hazard check runs before feature identification
+
+**Location:** `skills/pwk-writing-plans/SKILL.md:11-27`
+
+**Issue:** Step 1 evaluates the hazard checklist (database, auth, etc.) *before* reading the Features table to identify the next `⬜ pending` feature. The hazard prompt says "This feature involves..." but the feature isn't known yet. Flow is: read design doc → evaluate hazards → *then* read Features table → mark `🔄 planned`.
+
+**Fix:** Move the Features table reading before the hazard check. Flow should be: read design doc → find next `⬜ pending` feature → mark `🔄 planned` → *then* evaluate hazards for that specific feature.
+
+### [T-002] Medium — `executing-tasks` step 2 re-reads full Features table every task
+
+**Location:** `skills/pwk-executing-tasks/SKILL.md:158`
+
+**Issue:** Per-task step 2 says "Read the design doc's Features table for context on the overall feature set." This re-reads the entire table on every task execution — redundant and imprecise.
+
+**Fix:** Change to "skim the Features table for current feature status" to avoid re-processing the whole table.
+
+### [T-003] Low — `design-review` trivial case may target nonexistent plan doc
+
+**Location:** `skills/pwk-design-review/SKILL.md:12-22`
+
+**Issue:** Step 1 allows proceeding if either doc exists. Step 2 says to append to the plan doc. If only the design doc exists (no plan doc yet), the agent would try to append to a nonexistent file. Edge case since design-review runs after writing-plans, but the instructions don't enforce this.
+
+**Fix:** In step 2, add: "If no plan doc exists, skip and say: 'No plan doc found. Run `/skill:pwk-writing-plans` first.'"
+
+## Remediation Task List
+
+| ID | Priority | Finding | Estimated Effort |
+|----|----------|---------|-----------------|
+| O-001 | P2 | Stale `shouldBlockFilePath` docstring missing verify | small |
+| O-002 | P2 | Stale `DESTRUCTIVE_PATTERNS` comment missing verify | small |
+| O-003 | P2 | Missing closing backtick in executing-tasks lessons reference | small |
+| T-001 | Medium | Hazard check ordering in writing-plans (should run after feature identification) | small |
+| T-002 | Medium | executing-tasks re-reads full Features table every task | small |
+| T-003 | Low | design-review trivial case may target nonexistent plan doc | small |

package/docs/plans/completed/2026-06-09-verification-fixes-implementation.md

@@ -0,0 +1,69 @@
+# Implementation Plan: Verification findings fix
+
+## Overview
+
+Fix 6 findings from `docs/plans/2026-06-09-incremental-workflow-and-rename-verification-report.md`.
+
+All findings are small effort — documentation/comment fixes and minor instruction reordering.
+
+## Task 1: Fix stale comments in workflow-guard.ts
+
+<!-- tdd: trivial -->
+
+Fix O-001 and O-002.
+
+Files:
+- `extensions/workflow-guard.ts`
+
+Steps:
+1. Change `shouldBlockFilePath` JSDoc: "during brainstorm and plan phases" → "during brainstorm, plan, and verify phases"
+2. Change `DESTRUCTIVE_PATTERNS` comment: "blocked in brainstorm/plan phases" → "blocked in brainstorm/plan/verify phases"
+
+## Task 2: Fix backtick formatting in executing-tasks
+
+<!-- tdd: trivial -->
+
+Fix O-003.
+
+Files:
+- `skills/pwk-executing-tasks/SKILL.md`
+
+Steps:
+1. In per-task step 2, change `**Read \`docs/lessons.md` if it exists**` to `**Read \`docs/lessons.md\` if it exists**` (add closing backtick)
+
+## Task 3: Reorder writing-plans hazard check after feature identification
+
+<!-- tdd: trivial -->
+
+Fix T-001. The hazard checklist currently runs before reading the Features table. Move the Features table reading to before the hazard check so the prompt can say "This feature involves..." accurately.
+
+Files:
+- `skills/pwk-writing-plans/SKILL.md`
+
+Steps:
+1. Move the Features table paragraph (currently at the end of step 1) to just after the design doc reading, before the hazard checklist
+2. Verify the flow is now: read design doc → find next `⬜ pending` feature → mark `🔄 planned` → evaluate hazards for that feature
+
+## Task 4: Narrow executing-tasks Features table read
+
+<!-- tdd: trivial -->
+
+Fix T-002.
+
+Files:
+- `skills/pwk-executing-tasks/SKILL.md`
+
+Steps:
+1. In per-task step 2, change "Read the design doc's Features table for context on the overall feature set" to "Check the current feature's status in the design doc's Features table"
+
+## Task 5: Add plan doc guard to design-review trivial case
+
+<!-- tdd: trivial -->
+
+Fix T-003.
+
+Files:
+- `skills/pwk-design-review/SKILL.md`
+
+Steps:
+1. In step 2, add a guard before the triviality check: "If no plan doc was found in step 1, skip this check and say: 'No plan doc found to append to. Run `/skill:pwk-writing-plans` first.' and stop."

package/docs/plans/completed/2026-06-09-verification-fixes-progress.md

@@ -0,0 +1,14 @@
+# Progress: Verification fixes
+
+Plan: docs/plans/2026-06-09-verification-fixes-implementation.md
+Branch: incremental-workflow-and-rename
+Started: 2026-06-09T23:10:00
+Last updated: 2026-06-09T23:10:00
+
+| # | Status | Task | Commit |
+|---|--------|------|--------|
+| 1 | ✅ done | Fix stale comments in workflow-guard.ts (O-001, O-002) | c5ab39f |
+| 2 | ✅ done | Fix backtick formatting in executing-tasks (O-003) | c5ab39f |
+| 3 | ✅ done | Reorder writing-plans hazard check after feature identification (T-001) | c5ab39f |
+| 4 | ✅ done | Narrow executing-tasks Features table read (T-002) | c5ab39f |
+| 5 | ✅ done | Add plan doc guard to design-review trivial case (T-003) | c5ab39f |

package/docs/workflow-phases.md

@@ -3,50 +3,56 @@
 `pi-workflow-kit` has 4 phases and 1 utility skill. You invoke each one explicitly with `/skill:`.
 
 ```
-brainstorm → plan → execute → finalize
+brainstorm → plan → [design-review?] → execute → [verify?] → finalize
+```
+
+For complex features, each phase loops per feature:
+```
+brainstorm (name features) → plan next feature → [design-review?] → execute feature → [verify?] → loop...
 ```
 
 ## 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`
+- Produce `docs/plans/YYYY-MM-DD-<topic>-design.md` with a `## Features` table listing all features and their status
 
 Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
 
 ## plan
 
 ```
-/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`
+- 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
 
 Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
 
 ## execute
 
 ```
-/skill:executing-tasks
+/skill:pwk-executing-tasks
 ```
 
-- Read the implementation plan
+- Read the plan doc, resolve the design doc and feature row from metadata
 - Implement tasks one at a time: implement → test → fix → commit
-- Handle code review feedback by verifying criticism before implementing
+- Mark feature `✅ done` in the design doc's Features table when complete
+- Suggest planning the next feature or verifying
 
 No write restrictions. All tools available.
 
 ## finalize
 
 ```
-/skill:finalizing
+/skill:pwk-finalizing
 ```
 
 - Archive plan docs to `docs/plans/completed/`
@@ -59,7 +65,7 @@ No write restrictions. All tools available.
 ## diagnose
 
 ```
-/skill:diagnose
+/skill:pwk-diagnose
 ```
 
 Not a pipeline phase. A utility skill invoked on demand when debugging is needed.

package/extensions/workflow-guard.ts

@@ -4,14 +4,14 @@ 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.
+ * 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.
  */
 
-type Phase = "brainstorm" | "plan" | null;
+type Phase = "brainstorm" | "plan" | "verify" | null;
 
-// Destructive commands blocked in brainstorm/plan phases
+// Destructive commands blocked in brainstorm/plan/verify phases
 const DESTRUCTIVE_PATTERNS = [
   /\brm\b/i,
   /\brmdir\b/i,
@@ -145,12 +145,13 @@ export function isSafeCommand(command: string): boolean {
 }
 
 const SKILL_TO_PHASE: Record<string, Phase> = {
-  brainstorming: "brainstorm",
-  "writing-plans": "plan",
+  "pwk-brainstorming": "brainstorm",
+  "pwk-writing-plans": "plan",
+  "pwk-verify": "verify",
 };
 
 /** Determine if a write/edit to filePath should be blocked during the given phase.
- *  Only writes under docs/plans/ are allowed during brainstorm and plan phases.
+ *  Only writes under docs/plans/ are allowed during brainstorm, plan, and verify phases.
  */
 export function shouldBlockFilePath(filePath: string, cwd: string): boolean {
   const absolute = resolve(cwd, filePath);
@@ -179,7 +180,7 @@ export default function (pi: ExtensionAPI) {
         return;
       }
     }
-    if (text.startsWith("/skill:executing-tasks") || text.startsWith("/skill:finalizing")) {
+    if (text.startsWith("/skill:pwk-executing-tasks") || text.startsWith("/skill:pwk-finalizing")) {
       phase = null;
     }
   });
@@ -195,7 +196,7 @@ export default function (pi: ExtensionAPI) {
         }
         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: `⚠️ ${phase.toUpperCase()} PHASE: Bash command blocked (not allowlisted). Only read-only commands are permitted during brainstorming, planning, and verification.\nCommand: ${command}`,
         };
       }
       return;
@@ -217,7 +218,7 @@ export default function (pi: ExtensionAPI) {
 
     return {
       block: true,
-      reason: `⚠️ ${phase.toUpperCase()} PHASE: Cannot ${event.toolName} to ${filePath}. Only docs/plans/ is writable during brainstorming and planning.`,
+      reason: `⚠️ ${phase.toUpperCase()} PHASE: Cannot ${event.toolName} to ${filePath}. Only docs/plans/ is writable during brainstorming, planning, and verification.`,
     };
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "0.17.1",
+  "version": "0.18.1",
   "description": "Enforce structured brainstorm→plan→execute→finalize workflow with TDD discipline in AI coding agents",
   "keywords": [
     "pi-package",
@@ -46,6 +46,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.3.15",
     "@earendil-works/pi-coding-agent": "*",
+    "@types/node": "^25.9.2",
     "vitest": "^4.0.18"
   }
 }

package/skills/{brainstorming → pwk-brainstorming}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: brainstorming
+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."
 ---
 
@@ -30,10 +30,22 @@ Read-only exploration. You may **not** edit or create any files except under `do
 
    ADRs live under `docs/plans/adr/` and are archived during finalizing alongside the design doc.
 
-   For non-trivial designs, note any 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). You don't need to audit them here — just flag them for the design-review stage.
+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.
 
-   For trivial changes (config, naming, simple field additions), note "Simple change — no design review needed" in the design doc.
-5. **Write the design doc** — save it to `docs/plans/YYYY-MM-DD-<topic>-design.md`. Organize features as end-to-end slices (each slice delivers one observable behavior through all relevant layers) so the planning phase can decompose them directly into tasks. Branch creation, committing, and workspace setup are handled by `/skill:executing-tasks`.
+   Table format:
+   ```markdown
+   ## Features
+
+   | # | Feature | Status | Observable Behavior |
+   |---|---------|--------|---------------------|
+   | 1 | Feature name | ⬜ pending | What the user can do when this is complete |
+   ```
+
+   Status values: `⬜ pending`, `🔄 planned`, `✅ done`, `⏭ skipped`.
+
+   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).
+
+   Branch creation, committing, and workspace setup are handled by `/skill:pwk-executing-tasks`.
 
 ## Principles
 
@@ -44,5 +56,4 @@ Read-only exploration. You may **not** edit or create any files except under `do
 
 ## After the design
 
-- **Non-trivial design**: Ask: "Design looks good. Run `/skill:design-review` to check for production risks before planning."
-- **Trivial change**: Ask: "Simple change — skip design review. Ready to plan? Run `/skill:writing-plans`"
+Ask: "Ready to plan? Run `/skill:pwk-writing-plans`"

package/skills/{design-review → pwk-design-review}/SKILL.md

@@ -1,17 +1,17 @@
 ---
-name: design-review
-description: "Audit a design doc for production risks — security, scalability, fault tolerance, and operational hazards. Use after brainstorming for non-trivial designs, or when you want to stress-test a design for production readiness."
+name: pwk-design-review
+description: "Audit a plan and design doc for production risks — security, scalability, fault tolerance, and operational hazards. Use after writing-plans for non-trivial features, when the plan has concrete code that makes hazard checks meaningful."
 ---
 
 # Design Review
 
-Read-only exploration of the design doc. You **may** edit the design doc to append review findings. You may **not** edit source code or configuration.
+Read-only exploration of the design and plan docs. You **may** edit the plan doc to append review findings. You may **not** edit source code or configuration.
 
 ## Process
 
-1. **Find the design doc** — look for `docs/plans/*-design.md`. If none exists, say "No design doc found. Run `/skill:brainstorming` first." and stop.
+1. **Find the design and plan docs** — look for `docs/plans/*-design.md` and `docs/plans/*-implementation.md`. If neither exists, say "No design or plan doc found. Run `/skill:pwk-brainstorming` first." and stop. Read the plan doc for concrete code context alongside the design doc for architectural context.
 
-2. **Check triviality** — if the design doc notes "Simple change — no design review needed", append a brief section:
+2. **Check triviality** — if a plan doc was found in step 1 and the design doc notes "Simple change — no design review needed", append a brief section to the plan doc:
 
    ```markdown
    ## Architectural Review
@@ -19,9 +19,11 @@ Read-only exploration of the design doc. You **may** edit the design doc to appe
    **Status**: Skipped — trivial change. No high-risk operations detected.
    ```
 
-   Then say: "Ready to plan? Run `/skill:writing-plans`" and stop.
+   Then say: "Review complete — no action needed. Ready to execute? Run `/skill:pwk-executing-tasks`" and stop.
 
-3. **Read the design doc in full** — understand the architecture, data flow, components, and error handling proposed.
+   If no plan doc was found, skip this check and say: "No plan doc found to append to. Run `/skill:pwk-writing-plans` first." and stop.
+
+3. **Read the design and plan docs in full** — understand the architecture from the design doc, and concrete code from the plan doc. The plan doc's implementation details (SQL queries, type definitions, function bodies) are what the hazard checks audit.
 
 4. **🏛️ Architectural Pillars Review** — evaluate the design against the 6 Pillars of Production-Grade Design:
 
@@ -55,7 +57,7 @@ Read-only exploration of the design doc. You **may** edit the design doc to appe
 
 7. **Present findings** — show the full review to the user. For each triggered hazard or Socratic risk, propose a concrete mitigation. Wait for user feedback and incorporate changes.
 
-8. **Append to design doc** — add a `## Architectural Review` section to the design doc. Two cases:
+8. **Append to plan doc** — add a `## Architectural Review` section to the plan doc (not the design doc — review is per-feature, and the plan doc is the per-feature artifact). Two cases:
 
    **All clear** (no hazards triggered, no Socratic risks):
    ```markdown
@@ -110,4 +112,4 @@ Read-only exploration of the design doc. You **may** edit the design doc to appe
 
 ## After the review
 
-Ask: "Ready to plan? Run `/skill:writing-plans`"
+Ask: "Review complete. Ready to execute? Run `/skill:pwk-executing-tasks`"

package/skills/{diagnose → pwk-diagnose}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: diagnose
+name: pwk-diagnose
 description: "Disciplined debugging loop for hard bugs and performance regressions. Use when a test fails unexpectedly, a bug is found during execution, or something is broken. Use this skill whenever the user reports a bug, says 'this doesn't work', 'something's wrong', 'help me debug', or when tests fail for unclear reasons. Works at any point in the workflow — brainstorm, execute, or standalone."
 ---
 

package/skills/{executing-tasks → pwk-executing-tasks}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: executing-tasks
-description: "Use this to implement an approved plan task-by-task. Run after writing-plans, before finalizing."
+name: pwk-executing-tasks
+description: "Use this to implement an approved plan task-by-task. Run after pwk-writing-plans, before finalizing."
 ---
 
 # Executing Tasks
@@ -10,7 +10,7 @@ Implement the plan from `docs/plans/*-implementation.md` task by task, with file
 ## Before you start
 
 1. **Check git state** — run `git status` and `git log --oneline -5`. Note any uncommitted changes.
-2. **Find the plan** — look for `docs/plans/*-implementation.md`. If none exist, say "No implementation plan found. Run `/skill:writing-plans` first." and stop. If multiple exist, ask the user which one to execute.
+2. **Find the plan** — look for `docs/plans/*-design.md` to get the Features table. Find the feature with status `🔄 planned`. The plan doc is `docs/plans/YYYY-MM-DD-<topic>-<slugified-feature-name>-implementation.md`. If no design doc exists, fall back to looking for a single `*-implementation.md` (backward compatibility with plans not using the feature table). This covers plans created without a brainstorm session (no design doc or Features table). If multiple plan docs exist and no design doc, ask the user which one to execute.
 3. **Check for existing progress** — look for `docs/plans/*-progress.md`. If one exists matching the plan, this is a **resume** (see [Resume](#resume)). If not, this is a **first run** (see [First run](#first-run)).
 
 ## First run
@@ -38,6 +38,9 @@ Implement the plan from `docs/plans/*-implementation.md` task by task, with file
       ```
 
    b. Move plan docs into the worktree:
+
+      > When using the feature table, all plan docs for this design move together — completed feature plans, the current feature's plan, and the design doc. This is intentional: the worktree works on one design at a time.
+
       ```
       mv docs/plans/*-design.md <worktree>/docs/plans/ 2>/dev/null || true
       mv docs/plans/*-implementation.md <worktree>/docs/plans/ 2>/dev/null || true
@@ -60,7 +63,7 @@ Implement the plan from `docs/plans/*-implementation.md` task by task, with file
       To continue, start a new session there:
         cd ../<repo>-<feature-name> && pi
 
-      Then run: /skill:executing-tasks
+      Then run: /skill:pwk-executing-tasks
       ```
 
    e. **Create the progress file** in the worktree — save to `<worktree>/docs/plans/<plan-name>-progress.md`:
@@ -119,7 +122,7 @@ Implement the plan from `docs/plans/*-implementation.md` task by task, with file
    - Show the failure reason from the progress file
    - Ask: "Retry, skip, or abort?"
 4. **Handle pending task** — proceed normally
-5. **All done** — if no `⬜ pending` or `❌ failed` tasks remain, show summary and suggest `/skill:finalizing`
+5. **All done** — if no `⬜ pending` or `❌ failed` tasks remain, show summary and suggest `/skill:pwk-finalizing`
 6. **Begin task execution** — proceed from the identified task
 
 ## Progress file
@@ -155,7 +158,7 @@ Implement the plan from `docs/plans/*-implementation.md` task by task, with file
 For each task:
 
 1. **Mark in-progress** — update the progress file: `🔄 in-progress`
-2. **Read the plan** — read the plan's overview section (everything before `## Task 1:`). Skim all `## Task N:` headings for dependency awareness. Then read the current task's body in full. **Read `docs/lessons.md` if it exists** — follow all rules listed there while working on this task.
+2. **Read the plan** — read the plan's overview section (everything before `## Task 1:`). Extract the `Design:` and `Feature:` metadata to know which design doc and feature row this execution covers. If no `Design:` or `Feature:` metadata is present, the plan covers the entire design (no feature table). Skip design doc reading and proceed directly to task execution. Otherwise, check the current feature's status in the design doc's Features table. Skim all `## Task N:` headings for dependency awareness. Then read the current task's body in full. **Read `docs/lessons.md`** if it exists — follow all rules listed there while working on this task.
 3. **Execute the plan steps** — follow each numbered step in the task body, in order. As you work, shift your cognitive focus through three frames:
 
    **QA Test frame** (when writing/running tests): Focus entirely on translating the task's `Given/When/Then` Acceptance Criteria into precise failing tests. Before running tests, verify the test environment is sandboxed — no real database connections, API calls, or live services. External dependencies must be mocked or stubbed. Ensure the test environment is isolated (e.g., `NODE_ENV=test`, `GO_ENV=test`, or equivalent for your stack).
@@ -183,17 +186,18 @@ For each task:
    > "Always validate required ID fields at the service boundary — missing IDs should return 400, not 500"
 6. **Commit** — after all steps are done (no checkpoint gates remain in the task), `git add` the relevant files and commit with a clear message.
 7. **Update progress** — mark `✅ done` + record the commit hash.
-8. **Suggest session break if needed** — after completing ~3-5 tasks since the last break, suggest:
+8. **Update design doc** — if the progress file shows all tasks for the current feature are `✅ done`, find the design doc (from plan metadata), and mark the current feature row as `✅ done` in the Features table.
+9. **Suggest session break if needed** — after completing ~3-5 tasks since the last break, suggest:
    ```
    ✅ Tasks N-M done (commits: abc, def)
    Progress: X/Y tasks done
    ⏭  Next: Task [N+1] — [description]
    💡 Context is building up. For clean context on remaining tasks:
-      /new  then  /skill:executing-tasks
+      /new  then  /skill:pwk-executing-tasks
       (or just say "continue" to keep going here)
    ```
    Also suggest at checkpoint review pauses when multiple tasks have been completed since the last break. Respect the user's choice if they say "continue".
-9. **Loop** — go back to step 1 for the next `⬜ pending` task, or see [After all tasks](#after-all-tasks) if none remain.
+10. **Loop** — go back to step 1 for the next `⬜ pending` task, or see [After all tasks](#after-all-tasks) if none remain.
 
 ### `docs/lessons.md` format
 
@@ -263,7 +267,7 @@ What would you like to do?
 - **request changes** — tell me what to change in the tests
 - **revert** — undo this task and go back to pending
 - **skip** — skip this task entirely
-- **stop** — pause here, resume later with /skill:executing-tasks
+- **stop** — pause here, resume later with /skill:pwk-executing-tasks
 - **status** — show the full progress table
 ```
 
@@ -291,7 +295,7 @@ What would you like to do?
 - **request changes** — tell me what to change, I'll update and re-present
 - **revert** — undo this task and go back to pending
 - **skip** — skip this task entirely
-- **stop** — pause here, resume later with /skill:executing-tasks
+- **stop** — pause here, resume later with /skill:pwk-executing-tasks
 - **status** — show the full progress table
 ```
 
@@ -335,16 +339,42 @@ When the user shares code review feedback (outside of a checkpoint pause):
 
 ## After all tasks
 
-When no `⬜ pending` or `❌ failed` tasks remain, show a summary:
+When no `⬜ pending` or `❌ failed` tasks remain for the current feature, read the design doc's Features table. Show the per-task summary from the progress file, then check for more features:
+
+### More features remaining
 
 ```
-✅ All tasks complete!
+✅ Feature "<feature name>" complete.
+
+| # | Status | Task |
+|---|--------|------|
+| 1 | ✅ done | Create User model |
+| 2 | ✅ done | Add signup endpoint |
+
+⏭  Next: "<next pending feature name>"
+💡 Options:
+   - Plan next feature: /skill:pwk-writing-plans
+   - Verify this feature first: /skill:pwk-verify
+   - Or just say "continue"
+```
+
+### All features complete
+
+```
+✅ All features complete!
+
+| # | Status | Feature |
+|---|--------|---------|
+| 1 | ✅ done | User signup |
+| 2 | ✅ done | Email verification |
+| 3 | ⏭ skipped | Password reset |
 
 | # | Status | Task |
 |---|--------|------|
 | 1 | ✅ done | Create User model |
-| 2 | ✅ done | Write User model tests |
-| 3 | ⏭ skipped | Add auth middleware |
+| 2 | ✅ done | Add signup endpoint |
+| ... | ... | ... |
 
-Ready to ship? Run `/skill:finalizing`
+   - Verify everything: /skill:pwk-verify
+   - Ship: /skill:pwk-finalizing
 ```

package/skills/{finalizing → pwk-finalizing}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: finalizing
+name: pwk-finalizing
 description: "Use this after all tasks are complete to clean up, document, and ship the work."
 ---
 
@@ -21,13 +21,20 @@ Wait for the user to confirm before proceeding.
 
 ## Process
 
-1. **Move planning docs** — archive the design, implementation, progress docs, and ADRs (if any), then commit:
+1. **Move planning docs** — before archiving, check the design doc's `## Features` table (if one exists). If any features have status `⬜ pending` or `🔄 planned`, warn:
+
+   ```
+   ⚠️ Design doc has N unplanned features. Archive anyway, or go back to plan them?
+   ```
+
+   Wait for the user to confirm before proceeding. Then archive the design, implementation, progress docs, and ADRs (if any), then commit:
    ```
    mkdir -p docs/plans/completed
    mkdir -p docs/plans/completed/adr
    mv docs/plans/*-design.md docs/plans/completed/ 2>/dev/null || true
    mv docs/plans/*-implementation.md docs/plans/completed/ 2>/dev/null || true
    mv docs/plans/*-progress.md docs/plans/completed/ 2>/dev/null || true
+   mv docs/plans/*-verification-report.md docs/plans/completed/ 2>/dev/null || true
    mv docs/plans/adr/*.md docs/plans/completed/adr/ 2>/dev/null || true
    rmdir docs/plans/adr 2>/dev/null || true
    git add docs/plans/ && git commit -m "chore: archive planning docs"

package/skills/{verify → pwk-verify}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: verify
+name: pwk-verify
 description: "Post-implementation code verification with three expert review passes — security, optimization, and traceability. Use after executing-tasks and before finalizing to catch issues that pass tests but break in production. Runs the 'last prompt' pattern: adversarial security review, dead code and duplication audit, and end-to-end contract verification across every layer. Use this skill whenever the user says 'verify', 'review the code', 'check for issues', 'security review', 'the last prompt', 'audit', or when code has been implemented and needs a quality gate before shipping."
 ---
 
@@ -11,7 +11,7 @@ The core insight: code that passes tests is not code that's ready. Working code
 
 ## Process
 
-1. **Check what's been done** — run `git log --oneline` and `git diff --stat` to understand the scope of recent changes. If nothing has been implemented, say "No code changes found. Run `/skill:executing-tasks` first." and stop.
+1. **Check what's been done** — run `git log --oneline` and `git diff --stat` to understand the scope of recent changes. If nothing has been implemented, say "No code changes found. Run `/skill:pwk-executing-tasks` first." and stop.
 
 2. **Identify the project's layers** — before reviewing, map the codebase's architecture. Look for layer boundaries: UI/handlers/routes → services/business logic → repositories/data access → database/models. Note the patterns: does the project use controllers, handlers, or routes? Services or use cases? Repositories or DAOs? This map drives the traceability pass.
 
@@ -19,7 +19,7 @@ The core insight: code that passes tests is not code that's ready. Working code
 
 4. **Compile the report** — write all findings to `docs/plans/*-verification-report.md`. Present the report to the user and wait for feedback.
 
-5. **Offer to create a remediation plan** — after the report, ask: "Want me to create a fix plan from these findings? Run `/skill:writing-plans` to turn the task list into executable tasks."
+5. **Offer to create a remediation plan** — after the report, ask: "Want me to create a fix plan from these findings? Run `/skill:pwk-writing-plans` to turn the task list into executable tasks."
 
 ## Pass 1 — Security Review 🔴