@tianhai/pi-workflow-kit 0.18.1 → 1.1.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,118 +9,35 @@ Ship the completed work.
 
 ## Pre-finalization checks
 
-### Check for skipped tasks
-
-Before archiving, if a progress file exists (`docs/plans/*-progress.md`), read it and check for any `⏭ skipped` tasks. If found, warn:
-
-```
-⚠️ Tasks 4 and 7 were skipped. Continue with finalizing, or go back?
-```
-
-Wait for the user to confirm before proceeding.
+1. **Run the FULL test suite** — every test must pass, and only a green suite ships. Resume spans sessions; re-run the suite yourself rather than trust the previous session's ending state. Anything failing → send the user back to `/skill:pwk-executing-tasks`.
+2. Read the progress file (`docs/plans/*-progress.md`):
+   - **Any `❌ failed`** → **block**. Present counts and reasons; continue only when the user sends the task back to executing-tasks, or explicitly types `--force-failed` to acknowledge shipping with incomplete requirements.
+   - **Only `⏭ skipped`** → warn and confirm ("Requirement N was skipped. Continue, or go back?").
 
 ## 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:
+1. **Derive the topic** — progress file → `Plan:` ref → plan's `Design:` ref → design-doc filename → `<topic>`. Ambiguous with several designs in flight? Ask.
+2. **Delete consumed plan docs** — only this design's three artifacts, matched by the exact topic slug (with the `YYYY-MM-DD-` prefix) so similarly-named plans for other topics survive:
 
-   ```
-   ⚠️ Design doc has N unplanned features. Archive anyway, or go back to plan them?
+   ```bash
+   rm -f docs/plans/????-??-??-<topic>-design.md docs/plans/????-??-??-<topic>-implementation.md docs/plans/????-??-??-<topic>-progress.md
    ```
 
-   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"
-   ```
+   The `????-??-??-` glob enforces the dated filename; a bare `*<topic>*` would over-match unrelated docs (e.g. topic `auth` would also hit `feature-auth-redesign-design.md`). Verify with `ls docs/plans/` before and after. `rm -f` handles missing files. `docs/adr/`, `docs/lessons.md`, `CHANGELOG.md`, and `README.md` are permanent — leave them entirely out of the delete set.
+3. **Curate lessons (Agile Scrum Master hat)** — if `docs/lessons.md` exists: add missed lessons, generalize domain-specific rules into generic patterns, de-duplicate, categorize, retire stale rules. None exists but lessons were learned? Create it.
+4. **Update documentation** — if the API or surface changed: `README.md`, `CHANGELOG.md`, any inline docs.
+5. **Choose a merge strategy** — ask the human:
 
-   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).
+   1. **Create PR** — `git push origin <branch>` then `gh pr create`.
+   2. **Rebase & merge** *(recommended)* — rebase onto parent, `--ff-only` merge, push parent, delete branch.
+   3. **Squash & merge** — squash onto parent, push, delete branch.
+   4. **Merge commit** — `--no-ff` merge, push parent, delete branch.
 
-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
+   For 2–4, confirm the detected parent branch before proceeding.
+6. **Clean up** — remove the worktree if one was used: `git worktree remove ../<repo>-<topic>`.
 
-   If `docs/lessons.md` doesn't exist but lessons were learned this session, create it with the standard format:
-
-   ```markdown
-   # 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.
-   -->
-
-   ## Rules
-
-   - <rule 1>
-   - <rule 2>
-   ```
+## Principles
 
-3. **Update documentation** — if the API or surface changed:
-   - Update README.md
-   - Update CHANGELOG.md
-   - Update any inline docs
-
-4. **Choose a merge strategy** — ask the human which option 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:
-      ```
-      - ✅ 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/[\^~].*//')
-      git checkout "$parent" && git pull
-      git checkout - && git rebase "$parent"
-      git checkout "$parent" && git merge --ff-only -
-      git push origin "$parent"
-      git branch -d - && git push origin --delete -
-      ```
-
-   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 with the human before proceeding.
-
-5. **Clean up** — if a worktree was used, remove it:
-   ```
-   git worktree remove ../<repo>-<feature-name>
-   ```
+- Delete **only** the active design's artifacts — un-started designs (from a split) stay in `docs/plans/`.
+- ADRs are permanent institutional memory — they stay out of archive/rotation forever.
+- Bump the package version if this is a published change (major 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. This skill **does not unlock the guard** — it needs no writes, so it runs fine inside the brainstorm/plan read-only phase. If you want source edits after a status check, invoke the skill for the next phase yourself (the guard follows the skill).
+
+## 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,79 @@
 ---
 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.
+Turn the design doc's requirements into a **behavioral spec** the executor implements against.
 
-## Process
-
-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).
-
-   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.
+One design doc = one plan = one PR. The plan lists **all** the design's requirements in build order; the executor builds them one at a time.
 
-   Then evaluate whether the feature — whether from the design doc or from the user's description and codebase exploration — involves any of the following:
+Your writes go into `docs/plans/` and nowhere else. Source code and configuration get written later, in `pwk-executing-tasks` — this phase produces the document the executor builds from.
 
-   - 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
-
-   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."
+## Process
 
-   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:
+1. **Find the design doc** — glob `docs/plans/*-design.md`. If none, ask the user to run `/skill:pwk-brainstorming` first; if several, ask which. **Read `docs/lessons.md`** if it exists — known patterns belong in the acceptance criteria.
+2. **Create the feature branch** — `git checkout -b <topic>` (branch creation is allowed in the plan phase). Design + plan docs live on this branch, committed at the start of `pwk-executing-tasks`.
+3. **Read the `## Requirements` list** — the plan covers **all** of them. If the design has none, derive requirements from its described behaviors and confirm with the human before proceeding.
+4. **Write the plan** — for each requirement:
+   - **Acceptance criteria** — `Given/When/Then` behavioral statements defining "done". Write observable behaviors, not implementation steps; cover edge and error cases.
+   - **Integration tests** — test name + what each asserts. This is the spec the executor writes tests from.
+   - **`### Checkpoints: full | spec | none`** — how many human stops. `full` = tests + complete (default); `spec` = tests stop only (clear spec, low implementation risk — the complete checkpoint is dropped); `none` = trivial only (config line, typo).
+   - **`### Review: parallel | inline | skip`** — `parallel` = four reviewers via subagent (default, non-trivial diffs); `inline` = one `pwk-code-review` pass (small/medium diffs); `skip` = trivial diffs with no behavioral surface.
+   - Tag every requirement — missing tags default to `full` / `parallel`. **`spec` requires at least `inline` review** — dropping the complete checkpoint is only safe when review covers implementation quality; never combine `spec` with `Review: skip` (use `Checkpoints: none` instead).
+   - **Production-risk notes** — carry forward the design's `## Production-risk areas`, if any.
+   - **Challenge the design first** *(if production-risk areas exist)* — stress-test the design against the flagged risks before writing criteria. If a risk invalidates a design choice, stop and return to `/skill:pwk-brainstorming` rather than planning around a flawed design.
+   - **Ordering** — dependencies come **earlier** in the list; the executor runs in listed order with no dependency graph. Aim for vertical slices that merge cleanly on their own.
+
+   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`.
-```
+   ### Checkpoints: full | spec | none
+   ### Review: parallel | inline | skip
 
-**`checkpoint: done`** — gate after all steps including refactor/lessons:
-```markdown
-## Task 3: Add login endpoint
+   ### Production-risk notes
+   - <from the design's Production-risk areas, if any>
 
-<!-- tdd: new-feature -->
-<!-- checkpoint: done -->
+   ## Requirement 2: <name>
+   …
 
-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.
-
-Vertical slices ensure every committed task leaves the codebase in a testable state and reduces the blast radius of a bad task.
-
-## TDD in the plan
-
-Label each task with its TDD scenario:
+   ## Feature acceptance
+   Derived from the design doc. One end-to-end test exercising the requirements *together*:
+   - `should <the PRD's end-to-end claim>` — Given <starting state>, When <trigger>, Then <composed outcome across requirements>.
+   ```
 
-| 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 |
+   **If the design has no `## Feature acceptance` section**, stop and ask the human to run `/skill:pwk-brainstorming` to add one — the feature's definition-of-done is missing. (A trivial single-requirement design may fold the scenario into that requirement's criteria; note it and skip the separate section.)
 
-## Checkpoint labels
+   **If `## Production-risk areas` flagged** schema migrations, new dependencies, external APIs, or seed data, emit a `## Setup` section between `## Overview` and `## Requirement 1` (dependencies, migrations, seed data, and how to verify setup worked).
 
-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.
+5. **Audit before presenting:**
+   - Every requirement has criteria **and** matching tests, a checkpoint tag, a review tag.
+   - No `spec` + `skip` combination.
+   - A `## Feature acceptance` section exists (or the trivial-fold note).
+   - Production-risk areas from the design are reflected.
+6. **Workspace isolation** — you're on the `<topic>` branch. 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** and wait for approval. On approval, hand off: "Ready to execute? Run `/skill:pwk-executing-tasks`" (running it is what exits the gated plan phase).
 
-| 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` |
+## What belongs in the plan — and what stays out
 
-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 plan carries: observable behavior (acceptance criteria), the test names + assertions that prove it, and per-requirement tags. Everything about implementation *how* — code, signatures, file-by-file breakdowns, micro-task decomposition — stays with the executor, which picks structure against the spec. That's the division that keeps the plan stable when a detail shifts mid-implementation.
 
 ## 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`"