@tianhai/pi-workflow-kit 0.18.1 → 1.0.0

package/skills/pwk-finalizing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pwk-finalizing
-description: "Use this after all tasks are complete to clean up, document, and ship the work."
+description: "Use after all requirements are complete to delete consumed plan docs, curate lessons, update documentation, and ship the work."
 ---
 
 # Finalizing
@@ -9,86 +9,49 @@ Ship the completed work.
 
 ## Pre-finalization checks
 
-### Check for skipped tasks
+1. **Run the FULL test suite.** Every test must pass. Resume spans sessions — don't assume the last execute session left the suite green. If anything fails, stop and send the user back to `/skill:pwk-executing-tasks` to fix; never archive or open a PR against a red suite.
 
-Before archiving, if a progress file exists (`docs/plans/*-progress.md`), read it and check for any `⏭ skipped` tasks. If found, warn:
+2. Read the progress file (`docs/plans/*-progress.md`). Check for failed or skipped rows:
 
-```
-⚠️ Tasks 4 and 7 were skipped. Continue with finalizing, or go back?
-```
+   - **Any `❌ failed`** → **block**. Present the count and reasons to the user. Do not continue until one of:
+     - The user sends the task back to `/skill:pwk-executing-tasks` to fix the failures, or
+     - The user explicitly types `--force-failed` to acknowledge shipping with known incomplete requirements.
 
-Wait for the user to confirm before proceeding.
+     Never merge a branch that carries incomplete requirements without explicit acknowledgment.
 
-## Process
-
-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?
-   ```
+   - **Only `⏭ skipped`** (no `❌ failed`) → present a warning and confirm:
 
-   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"
-   ```
+     ```
+     ⚠️ Requirement 4 was skipped. Continue with finalizing, or go back?
+     ```
 
-   Each `mv` gracefully handles the case where no matching files exist (e.g., if the user skipped straight from brainstorm to finalize without executing tasks).
+     Continue on confirmation; abort otherwise.
 
-2. **Review & Polish Lessons (Agile Scrum Master Hat)** — if `docs/lessons.md` exists, put on your **Agile Scrum Master Hat** to curate and optimize it for future sprints:
-   - **Add missed lessons** — capture any lessons from this session that weren't written during execution
-   - **Generalize domain-specific rules** — if a rule names a specific service, entity, or feature, either rewrite it as a generic pattern or remove it if no generic form exists
-   - **De-duplicate** — combine overlapping or redundant rules into single, sharper entries
-   - **Categorize** — group the rules under clear, structured markdown headers (e.g., `## Tool Usage`, `## Testing Patterns`, `## Architecture Rules`) to make the document highly scannable for future sessions. Keep the `## Rules` section as the append target for new entries during execution — categorization moves rules out of `## Rules` into the appropriate category headers.
-   - **Retire stale rules** — remove bullets that no longer apply
-   - If no changes are needed, leave it as-is
+## Process
 
-   If `docs/lessons.md` doesn't exist but lessons were learned this session, create it with the standard format:
+1. **Derive the topic** — from the progress file → its `Plan:` ref → the plan's `Design:` ref → the design-doc filename → `<topic>`. If several designs are in flight and it's ambiguous, ask which is being shipped.
 
-   ```markdown
-   # Lessons Learned
+2. **Delete consumed plan docs** — only this design's artifacts; leave other (un-started) design docs in place:
 
-   <!--
-   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.
-   -->
+   ```bash
+   rm -f docs/plans/*<topic>*-design.md
+   rm -f docs/plans/*<topic>*-implementation.md
+   rm -f docs/plans/*<topic>*-progress.md
+   ```
 
-   ## Rules
+   Each `rm -f` gracefully handles a missing file. **Do not touch `docs/adr/`**, `docs/lessons.md`, `CHANGELOG.md`, or `README.md` — those are permanent.
 
-   - <rule 1>
-   - <rule 2>
-   ```
+3. **Review & polish lessons (Agile Scrum Master Hat)** — if `docs/lessons.md` exists, curate it for future sprints: add missed lessons, generalize domain-specific rules into generic patterns, de-duplicate, categorize under clear headers, retire stale rules. If it doesn't exist but lessons were learned, create it with the standard format.
 
-3. **Update documentation** — if the API or surface changed:
-   - Update README.md
-   - Update CHANGELOG.md
-   - Update any inline docs
+4. **Update documentation** — if the API or surface changed: update `README.md`, `CHANGELOG.md`, and any inline docs.
 
-4. **Choose a merge strategy** — ask the human which option they prefer:
+5. **Choose a merge strategy** — ask the human which they prefer:
 
    1. **Create PR** — push and open a PR for external review:
       ```
       git push origin <branch>
-      gh pr create --title "feat: <summary>" --body "<task summary>"
-      ```
-
-      Use the progress file to generate the summary. Convert the task table to a bulleted list:
+      gh pr create --title "feat: <summary>" --body "<summary>"
       ```
-      - ✅ Create User model
-      - ✅ Write User model tests
-      - ⏭ Add auth middleware (skipped)
-      - ✅ Add login endpoint
-      ```
-
    2. **Rebase & merge** *(recommended)* — rebase onto parent, fast-forward merge, push parent, delete branch:
       ```
       parent=$(git show-branch -a 2>/dev/null | grep '\*' | grep -v "$(git branch --show-current)" | head -1 | sed 's/.*\[\(.*\)\].*/\1/' | sed 's/[\^~].*//')
@@ -98,29 +61,18 @@ Wait for the user to confirm before proceeding.
       git push origin "$parent"
       git branch -d - && git push origin --delete -
       ```
+   3. **Squash & merge** — squash all commits into one on parent, push, delete branch.
+   4. **Merge commit** — merge with `--no-ff`, push parent, delete branch.
 
-   3. **Squash & merge** — squash all commits into one on parent, push parent, delete branch:
-      ```
-      parent=$(git show-branch -a 2>/dev/null | grep '\*' | grep -v "$(git branch --show-current)" | head -1 | sed 's/.*\[\(.*\)\].*/\1/' | sed 's/[\^~].*//')
-      git checkout "$parent" && git pull
-      git merge --squash -
-      git commit -m "feat: <summary>"
-      git push origin "$parent"
-      git branch -d - && git push origin --delete -
-      ```
-
-   4. **Merge commit** — merge with `--no-ff`, push parent, delete branch:
-      ```
-      parent=$(git show-branch -a 2>/dev/null | grep '\*' | grep -v "$(git branch --show-current)" | head -1 | sed 's/.*\[\(.*\)\].*/\1/' | sed 's/[\^~].*//')
-      git checkout "$parent" && git pull
-      git checkout - && git merge --no-ff -m "Merge branch '<branch>'" -
-      git push origin "$parent"
-      git branch -d - && git push origin --delete -
-      ```
+   For options 2–4, confirm the detected parent branch before proceeding.
 
-   For options 2–4, confirm the detected parent branch with the human before proceeding.
-
-5. **Clean up** — if a worktree was used, remove it:
+6. **Clean up** — if a worktree was used, remove it:
    ```
-   git worktree remove ../<repo>-<feature-name>
+   git worktree remove ../<repo>-<topic>
    ```
+
+## Principles
+
+- Delete **only** the active design's artifacts — un-started designs (from a split) stay in `docs/plans/`.
+- ADRs are never archived.
+- Bump the package version if this is a published change (major bump for breaking changes).

package/skills/pwk-status/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: pwk-status
+description: "Show all active pipeline topics and their phase/progress. Use when the user asks 'where are we', 'status', 'what's in flight', or when resuming and unsure which design to continue. Read-only discovery. Not a pipeline phase."
+---
+
+# Status
+
+Report on all in-flight pipelines (split designs may run in parallel across worktrees). Read-only.
+
+## Process
+
+1. Glob `docs/plans/*-design.md`, `*-implementation.md`, `*-progress.md`.
+2. For each `<topic>`, infer the furthest artifact present:
+   - only `*-design.md` → brainstorm done, plan next
+   - `*-implementation.md` but no progress → plan done, execute next
+   - `*-progress.md` → execute phase — show `done/total` requirement count
+3. Print a one-line table, e.g.:
+
+   ```
+   | Topic   | Phase   | Progress | Branch           |
+   |---------|---------|----------|------------------|
+   | auth    | execute | 2/3 done | auth             |
+   | billing | plan    | —        | ../repo-billing  |
+   ```
+
+4. If none, say so and suggest `/skill:pwk-brainstorming`.
+
+Keep it short — this is orientation, not analysis. No writes; the `<topic>` slug is the identity.

package/skills/pwk-writing-plans/SKILL.md

@@ -1,358 +1,83 @@
 ---
 name: pwk-writing-plans
-description: "Use this to break a design into an implementation plan with bite-sized TDD tasks. Works with or without a prior brainstorm. Use this skill when the user says 'let's plan', 'break this down', 'write a plan', 'create tasks', or after a brainstorm session when they want to move to implementation. Also use when the user has a clear idea and wants to jump straight to a structured plan."
+description: "Turn a design doc's requirements into a behavioral spec — acceptance criteria + integration tests per requirement. Use after pwk-brainstorming, before pwk-executing-tasks. Use when the user says 'let's plan', 'write a plan', 'break this down', or after a brainstorm when ready to move to implementation."
 ---
 
 # Writing Plans
 
-You may only create or edit files under `docs/plans/`. Do not modify source code or configuration.
-
-## Process
+Turn the design doc's requirements into a **behavioral spec** the executor implements against.
 
-1. **Check for a design doc** — look for `docs/plans/*-design.md`. If one exists, use it as the basis for the plan. If the design doc is incomplete, fill gaps by asking the human. If no design doc exists, ask the user to describe what they want to build and read relevant code. **Read `docs/lessons.md`** if it exists — incorporate known patterns into the task breakdown (e.g., if a lesson says "always run lint before commit," include that in relevant task instructions).
+One design doc = one plan = one PR. The plan lists **all** the design's requirements; the executor builds them one at a time, in the order you list them (see **Ordering** below).
 
-   If the design doc has a `## Features` table, read it to identify the next feature with status `⬜ pending`. Mark that feature as `🔄 planned` by editing the design doc. This plan will cover only that one feature. If the design doc has no Features table, plan the entire design as before.
+You may only create or edit files under `docs/plans/`. Do not modify source code or configuration.
 
-   Then evaluate whether the feature — whether from the design doc or from the user's description and codebase exploration — involves any of the following:
+## Process
 
-   - Database schema changes or migrations
-   - Authentication or authorization logic
-   - External API or service integrations
-   - Concurrency or batch processing
-   - File uploads or large data flows
-   - Redis, caching, or message queues
+1. **Find the design doc** — look for `docs/plans/*-design.md`. (For a full multi-topic overview when several are in flight, use `/skill:pwk-status`.) If none, ask the user to run `/skill:pwk-brainstorming` first. If several exist (a large issue was split), list them and ask which to plan. **Read `docs/lessons.md`** if it exists — incorporate known patterns into the acceptance criteria and tests.
+2. **Create the feature branch first** — `git checkout -b <topic>` (branch creation is allowed in the plan phase). The design + plan docs are written on this branch (committed at the start of `pwk-executing-tasks`), not `main`.
+3. **Read the Requirements** — the design doc opens with a `## Requirements` list; each requirement is one testable behavior the user will get. This plan covers **all** requirements in the design doc (one pipeline per design doc). If the design has no Requirements list, derive the requirements from its described behaviors and confirm them with the human before proceeding.
 
-   If any apply, prompt the user: "This feature involves [list what you found] but hasn't been reviewed for production risks. Run `/skill:pwk-design-review` first, or type 'proceed' to skip."
+4. **Write the plan — acceptance criteria + integration tests per requirement.** For each requirement specify:
+   - **Acceptance criteria** — `Given/When/Then` behavioral statements that define "done" for that requirement.
+   - **Integration tests** — the concrete test cases that encode the acceptance criteria: a test name and what each asserts. This is the spec the executor writes and implements against.
+   - **Challenge the design first** *(if `## Production-risk areas` exists)* — before writing acceptance criteria, stress-test the design against the flagged risks: ask the uncomfortable "what breaks under load / on failure / on bad input" questions and confirm the approach holds. If a risk invalidates a design choice, stop and return to `/skill:pwk-brainstorming` rather than planning around a flawed design.
+   - **Ordering** — list requirements in the order they should be built. If a requirement depends on another, the dependency must come **earlier in the list**; the executor runs requirements in listed order and does not reorder. Aim for each requirement to be a vertical slice that merges cleanly on its own — if a dependency can't be sliced away, position resolves it (there is no parsed dependency graph).
+   - **Production-risk notes** *(if the design flagged any in `## Production-risk areas`)* — carried forward so the executor and `pwk-code-review` account for them.
 
-   If the design doc explicitly notes "Simple change — no design review needed", skip this check.
-2. **Write the implementation plan** — break the feature into tasks. Save to `docs/plans/YYYY-MM-DD-<topic>-<feature-name>-implementation.md` (derive `<feature-name>` from the feature's name in the table, slugified). If the design doc has no Features table, use `docs/plans/YYYY-MM-DD-<topic>-implementation.md`. Include metadata at the top of the plan doc so the executor can find the design doc and feature row:
+   Save to `docs/plans/YYYY-MM-DD-<topic>-implementation.md`:
 
    ```markdown
-   # Implementation Plan: <feature name>
+   # Implementation Plan: <topic>
 
    ## Overview
-
    Design: docs/plans/YYYY-MM-DD-<topic>-design.md
-   Feature: <feature name> (row N in Features table)
-   ```
-
-   If the design is too large for ~15 tasks for a single feature, flag this to the human and ask whether to reduce scope or proceed with the full plan.
-3. **Present the plan** — show the complete plan to the human. Wait for approval before suggesting execution.
-
-   Before presenting, run the **Plan Acceptance Audit**:
-   - **Vertical Slices**: Is every task a complete vertical slice (not horizontal)?
-   - **Task Sizing**: Is any single task too large or covering multiple complex behaviors? If so, split it.
-   - **QA Coverage**: Does every task have both a Happy Path and at least one Edge Case in its Acceptance Criteria?
-   - **Checkpoint Alignment**: Are `checkpoint: test` and `checkpoint: done` gates placed on the most critical or risky tasks?
-   - **Risk Enforcement**: If this plan doc's Architectural Review section flagged any hazards as `[TRIGGERED]`, verify the corresponding tasks have `checkpoint: done` and a `Hazard Mitigation Verification` section.
-
-   If any check fails, fix the plan before presenting.
-
-## Task format
-
-Each task should produce one testable change. The executing-tasks skill handles committing — do not include `git commit` in the task body.
-
-Each task must include:
-- Exact file paths to create/modify
-- **Acceptance Criteria (QA Engineer Hat)** — Put on your **QA Engineer Hat** to design exhaustive test coverage. Explicitly define:
-  - **Happy Path**: Expected behavior under normal operations.
-  - **Edge Cases & Error Paths**: What happens with empty inputs, limits exceeded, authentication failures, or error states.
-  Ensure every criteria block specifies the expected state and returned results using `Given/When/Then` behavioral blocks.
-- **Concrete code** — include the actual implementation, not a summary. Write out SQL schemas, type definitions, function signatures with bodies, route handler code, and test assertions. A developer should be able to copy-paste from the plan and have working code. For tasks that depend on types or utilities from earlier tasks, reference them explicitly (e.g., `import { User } from Task 2`) and include only the new code
-- Exact commands with expected output (e.g., `npx vitest run src/user/model.test.ts` → shows 1 test passing)
-
-Each task must use a numbered heading with optional metadata comments:
-
-```markdown
-## Task N: <description>
-
-<!-- tdd: new-feature -->
-```
-
-...where N starts at 1 and incrementally numbers each task in the plan.
-
-The metadata comments (placed right after the heading) are optional. If omitted, the executing-tasks skill infers the TDD scenario and checkpoint from context. When in doubt, include them explicitly.
-
-Valid TDD values: `new-feature`, `modifying-tested-code`, `trivial`
-
-Valid checkpoint values: `none`, `test`, `done`
-
-### Level of detail
-
-This is the #1 thing to get right. The plan is not a high-level outline — it's a detailed recipe that the executing-tasks skill will follow step by step. If you write "implement login handler" without showing the code, the executing agent has to guess, and that defeats the purpose of the plan.
-
-Think of it this way: the plan author (you, now) has the full design context, the domain model, and the architecture in mind. The plan executor (a future agent session) will have none of that context — just the plan file. Write accordingly.
-
-**What "concrete code" means in practice:**
-- SQL: `CREATE TABLE` statements with all columns, types, and constraints
-- Types/interfaces: full type definitions with fields
-- Functions: signature + body (the logic, not just the name)
-- Tests: concrete assertions (`expect(result.status).toBe(409)`) not descriptions ("test that it returns an error")
-- Routes: the actual handler code with validation, error handling, and response format
-- Config: exact values, not "configure appropriately"
-
-**Bad** (too vague — the executor must guess):
-```
-3. Implement bookmark model
-```
-
-**Good** (executor can copy-paste):
-```
-3. Implement `src/db/bookmarks.ts`:
-
-```ts
-import db from '../db.js';
-
-export function createBookmarksTable() {
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS bookmarks (
-      id TEXT PRIMARY KEY,
-      userId TEXT NOT NULL,
-      messageId TEXT NOT NULL,
-      createdAt TEXT DEFAULT (datetime('now')),
-      UNIQUE(userId, messageId)
-    )
-  `);
-}
-
-export function insertBookmark(userId: string, messageId: string) {
-  const id = crypto.randomUUID();
-  db.prepare('INSERT INTO bookmarks (id, userId, messageId) VALUES (?, ?, ?)').run(id, userId, messageId);
-  return { id, userId, messageId };
-}
-```
-```
-
-### Task body structure
-
-The examples below show the structure — headings, metadata comments, checkpoints, and step numbering. For the code content within steps, follow the detail level described above.
-
-**No checkpoint** — numbered steps only:
-```markdown
-## Task 1: Create User model
-
-<!-- tdd: new-feature -->
-
-Acceptance Criteria (QA Engineer Hat):
-- **Happy Path**:
-  - Given: Valid user data with name and email
-  - When: The User model is created
-  - Then: The model contains the correct fields and a generated ID
-- **Edge Case (duplicate email)**:
-  - Given: A user with email "test@example.com" already exists
-  - When: Another user is created with the same email
-  - Then: Creation fails with a unique constraint error
-
-Files:
-- `src/user/model.ts`
-- `src/user/model.test.ts`
-
-Steps:
-1. Write failing test for User model creation
-2. Run test — confirm it fails
-3. Implement User model
-4. Run test — confirm it passes
-```
-
-**`checkpoint: test`** — gate after test, before implementing:
-```markdown
-## Task 2: Write auth tests
-
-<!-- tdd: new-feature -->
-<!-- checkpoint: test -->
-
-Acceptance Criteria (QA Engineer Hat):
-- **Happy Path**:
-  - Given: A user with valid credentials exists
-  - When: Login is attempted
-  - Then: A valid session token is returned
-- **Edge Case (wrong password)**:
-  - Given: A user exists but password is incorrect
-  - When: Login is attempted
-  - Then: An authentication error is returned
 
-Files:
-- `src/auth/login.test.ts`
+   ## Requirement 1: <name>
 
-Steps:
-1. Write failing test for login with valid credentials
-2. Run test — confirm it fails
+   ### Acceptance criteria
+   - Given … When … Then …
+   - Given … When … Then … (edge cases)
 
-⏸ **CHECKPOINT: test** — present test review. Wait for human approval before implementing.
+   ### Integration tests
+   - `should <behavior>` — asserts <observable outcome>
+   - `should <error case>` — asserts <failure outcome>
 
-3. Implement login handler
-4. Run test — confirm it passes
-5. Refactor — check for shallow modules, duplication, seam discipline. Run tests after changes.
-6. Lessons — caught a mistake that applies to future tasks? Add rule to `docs/lessons.md`.
-```
+   ### Production-risk notes
+   - <from the design's Production-risk areas, if any>
 
-**`checkpoint: done`** — gate after all steps including refactor/lessons:
-```markdown
-## Task 3: Add login endpoint
-
-<!-- tdd: new-feature -->
-<!-- checkpoint: done -->
-
-Acceptance Criteria (QA Engineer Hat):
-- **Happy Path**:
-  - Given: A user with email "user@example.com" and password "secure123" exists
-  - When: A POST request with those credentials is sent to `/api/login`
-  - Then: Response returns `200 OK` with a signed JWT token
-- **Edge Case (invalid password)**:
-  - Given: A user exists but the password sent is "wrong-pass"
-  - When: A POST request is sent to `/api/login`
-  - Then: Response returns `401 Unauthorized`
-- **Edge Case (rate limiting)**:
-  - Given: 5 failed login attempts from the same IP
-  - When: A 6th attempt is sent
-  - Then: Response returns `429 Too Many Requests`
-
-Files:
-- `src/auth/login.ts`
-- `src/auth/login.test.ts`
-
-Steps:
-1. Write failing test for login with valid credentials
-2. Run test — confirm it fails
-3. Implement login handler
-4. Run test — confirm it passes
-5. Add edge case tests (invalid password, missing email)
-6. Refactor — check for shallow modules, duplication, seam discipline. Run tests after changes.
-7. Lessons — caught a mistake that applies to future tasks? Add rule to `docs/lessons.md`.
-
-⏸ **CHECKPOINT: done** — present implementation review. Wait for human approval before committing.
-```
-
-**Both checkpoints** — gate after test, then gate after refactor/lessons:
-```markdown
-## Task 4: Complex auth flow
-
-<!-- tdd: new-feature -->
-<!-- checkpoint: test -->
-<!-- checkpoint: done -->
-
-Acceptance Criteria (QA Engineer Hat):
-- **Happy Path**:
-  - Given: A valid OAuth2 authorization code
-  - When: The auth callback is invoked
-  - Then: A user session is created and the user is redirected to the dashboard
-- **Edge Case (expired code)**:
-  - Given: An expired or invalid authorization code
-  - When: The auth callback is invoked
-  - Then: The user is redirected to login with an error message
-
-Steps:
-1. Write failing test for auth flow
-2. Run test — confirm it fails
-
-⏸ **CHECKPOINT: test** — present test review. Wait for human approval before implementing.
-
-3. Implement auth flow
-4. Run test — confirm it passes
-5. Refactor — check for shallow modules, duplication, seam discipline. Run tests after changes.
-6. Lessons — caught a mistake that applies to future tasks? Add rule to `docs/lessons.md`.
-
-⏸ **CHECKPOINT: done** — present implementation review. Wait for human approval before committing.
-```
-
-
-## Vertical slices
-
-Each task should be a **vertical slice** — a thin path through ALL relevant layers end-to-end, delivering one complete piece of observable behavior.
-
-```
-WRONG (horizontal):
-  Task 1: Create database schema for users
-  Task 2: Write user API endpoints
-  Task 3: Build user UI components
-  Task 4: Wire everything together
-
-RIGHT (vertical):
-  Task 1: User can sign up (model + endpoint + validation + test)
-  Task 2: User can log in (auth check + token + test)
-  Task 3: User can view profile (query + endpoint + test)
-```
-
-Order tasks so each one can be verified independently and delivers a complete vertical slice. If a task requires infrastructure (models, types) that no previous task has created, include it in that task — don't create it as a separate task.
+   ## Requirement 2: <name>
+   …
+   ```
 
-Vertical slices ensure every committed task leaves the codebase in a testable state and reduces the blast radius of a bad task.
+   **If the design has `## Production-risk areas`** that flag schema migrations, new dependencies, external API integrations, or seed data, emit a `## Setup` section between `## Overview` and `## Requirement 1`:
 
-## TDD in the plan
+   ```markdown
+   ## Setup
 
-Label each task with its TDD scenario:
+   - **Dependencies:** what to install (and how)
+   - **Migrations:** each migration with a brief description
+   - **Seed / test data:** what data to prepare
+   - **Verify:** how to confirm setup worked (e.g. `npm test` still passes)
+   ```
 
-| Scenario | When | Instructions in the task |
-|---|---|---|
-| **New feature** | Adding new behavior | Write failing test → run it → implement → run it |
-| **Modifying tested code** | Changing existing behavior | Run existing tests first → modify → verify they pass |
-| **Trivial** | Config, docs, naming | Use judgment |
+5. **Before presenting — audit the spec:**
+   - Every requirement has acceptance criteria **and** matching integration tests.
+   - Acceptance criteria are observable behaviors, not implementation steps.
+   - Edge/error cases are covered.
+   - Production-risk areas from the design are reflected.
+   Fix gaps before presenting.
 
-## Checkpoint labels
+6. **Set up workspace isolation** *(before approving)* — you're already on the `<topic>` feature branch (step 2); the design + plan docs live here, not on `main` (committed at the start of `pwk-executing-tasks`). For larger work, offer a worktree (`git worktree add ../<repo>-<topic> <topic>`) and hand off to a new session there so `pwd` is the worktree. Wait for the user's choice.
+7. **Present the plan** — show the complete plan and wait for approval. On approval, hand off to `/skill:pwk-executing-tasks` — running it is what transitions out of the gated plan phase (the guard unlocks on the skill, not on the word "approve").
 
-Label each task with a `checkpoint` to require human review before proceeding. The checkpoint gate (`⏸ CHECKPOINT`) goes in the task body — the agent follows the plan step by step and pauses when it reaches the gate.
+## What the plan is NOT
 
-| Checkpoint | When to use | What the plan should include |
-|---|---|---|
-| *(none)* | Trivial tasks, well-understood changes | Numbered steps only |
-| **`checkpoint: test`** | Test design matters (API contracts, edge cases, complex behavior) | Steps up to test → `⏸ CHECKPOINT: test` → implement steps (including refactor/lessons) |
-| **`checkpoint: done`** | Implementation review matters (complex logic, security, performance) | Steps (including refactor/lessons) → `⏸ CHECKPOINT: done` |
-| Both | Non-obvious tests AND complex logic | Steps up to test → `⏸ CHECKPOINT: test` → implement steps (including refactor/lessons) → `⏸ CHECKPOINT: done` |
+- **Not an implementation recipe** — no exact code, no file-by-file breakdowns, no signatures, no stubs. (A fine-grained implementation plan invalidates the moment a detail shifts; acceptance criteria + integration tests survive implementation changes.)
+- **Not micro-tasks** — one coarse block per requirement. The executor decides how to structure and slice the implementation.
+- **Not the tests themselves** — the plan specifies *what* the tests prove (names + assertions); `pwk-executing-tasks` writes the actual test files first (red), then implements to green.
 
-Use judgment when assigning checkpoints. Prefer `checkpoint: test` for new features with non-obvious test design. Prefer `checkpoint: done` for tasks where the implementation approach is debatable. Most tasks should not need a checkpoint. The user can adjust checkpoints when reviewing the plan.
+The executor has **full autonomy** to choose structure, signatures, and internals — bounded only by the acceptance criteria and the two mandatory checkpoints per requirement (after integration tests are written, and after the requirement is complete), enforced by `pwk-executing-tasks`.
 
 ## After the plan
 
-Ask: "Ready to execute? Run `/skill:pwk-executing-tasks`"
-
-> After executing this feature, the executor will check for more `⬜ pending` features and suggest planning the next one.
-
-## Behavioral Guidelines
-
-Guidelines to reduce overcomplication and hidden assumptions in plans. Derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls, adapted for the planning context.
-
-**Tradeoff:** These guidelines bias toward caution over speed. For trivial plans (1-2 tasks), use judgment.
-
-### Surface Assumptions
-
-**When the design is ambiguous, annotate — don't silently pick.**
-
-When writing a plan, you'll encounter gaps: the design says "paginated" but doesn't specify how, says "validate input" but doesn't say which fields, or leaves the data layer unspecified. Your instinct will be to fill the gap and keep writing. Resist that.
-
-Instead, add a brief `> **Assumption:** ...` note in the plan at the point where you made the call:
-
-```
-> **Assumption:** Using offset/limit pagination because the design just says
-> "paginated". Cursor-based would be better for large datasets.
-```
-
-```
-> **Assumption:** No service layer — handler calls store directly. Add one
-> if cross-cutting concerns (logging, auth checks) emerge later.
-```
-
-This lets the reviewer see what you chose and why, without blocking progress. Common gaps worth annotating:
-- Pagination style, error handling strategy, concurrency model
-- Whether to add a service/middleware layer
-- Whether to add external dependencies
-- Naming conventions when the design doesn't specify
-
-### Build Only What Each Task Needs
-
-**Minimum code to deliver the task's observable behavior. Nothing more.**
-
-- No interface methods that no task exercises yet. If Task 2 creates a `Store` interface, it should have only the methods Task 2 calls. Add methods in the task that first needs them.
-- No layers (service, middleware, repository) unless the design explicitly requires them.
-- No error types, helper files, or shared packages until a task actually uses them.
-- No external dependencies when stdlib suffices. Every `go get` or `npm install` is a choice — default to no.
-- No "flexible" or "configurable" code that wasn't requested.
-
-If you find yourself writing a store with 4 methods where only 1 is used in this task, stop. Write 1 method. Add the rest when the tasks that need them arrive.
-
-### One Task, One Change
-
-**Each task should trace to exactly one user-facing behavior.**
-
-- If a task creates more than 4 new files, it's probably doing too much — split it.
-- If a task modifies existing files unrelated to its acceptance criteria, trim the scope.
-- Infrastructure (types, interfaces, module scaffolding) should live in the same task as the first code that uses it, not in a separate "setup" task — unless the infrastructure alone is complex enough to warrant its own task.
-- Every file listed in a task's `Files:` section should be directly necessary for that task's acceptance criteria to pass.
+Ask: "Ready to execute? Run `/skill:pwk-executing-tasks`"