@tianhai/pi-workflow-kit 0.17.1 → 1.0.0

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."
 ---
 
@@ -53,4 +53,5 @@ Required before declaring done:
 - Regression test passes (or absence of seam is documented)
 - All `[DEBUG-...]` instrumentation removed
 - Ask: what would have prevented this bug?
-- If the bug was caused by an architectural problem (no good test seam, tangled callers, hidden coupling), suggest writing an ADR to `docs/plans/adr/` capturing that insight
+- If the answer is a repeatable pattern, append a **generic** rule to `docs/lessons.md` (strip domain specifics) so future sessions catch it early.
+- If the bug was caused by an architectural problem (no good test seam, tangled callers, hidden coupling), suggest writing an ADR to `docs/adr/` capturing that insight

package/skills/pwk-executing-tasks/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: pwk-executing-tasks
+description: "Implement a plan requirement-by-requirement with test-first discipline and full autonomy. Run after pwk-writing-plans. Each requirement: write integration tests (red) → checkpoint → implement to green → checkpoint → pwk-code-review."
+---
+
+# Executing Tasks
+
+Implement the plan from `docs/plans/*-implementation.md` requirement-by-requirement, with file-based progress tracking.
+
+The plan is a **behavioral spec** (acceptance criteria + integration tests). You have **full autonomy** to choose structure, signatures, and internals — the acceptance criteria and integration tests define *what*; you decide *how*. Do not ask the plan for implementation steps; it deliberately doesn't contain them.
+
+## Before you start
+
+1. **Check git state** — `git status` and `git log --oneline -5`. Note uncommitted changes.
+2. **Find the plan + report** — look for `docs/plans/*-implementation.md`. If several, list them and ask which. Print a one-line discovery report, e.g. `Found: design "auth" — execute phase (1/3 requirements done)`. If a matching `*-progress.md` exists, this is a **resume** (see [Resume](#resume)).
+3. **Workspace isolation should already be done** — `pwk-writing-plans` set up the branch/worktree before handoff. If you land here still on `main`, tell the user the workspace wasn't set up and suggest doing it before executing.
+
+## First run
+
+1. **Parse the plan** — read all `## Requirement N:` headings. Build the progress table with all requirements as `⬜ pending`. Process them in **listed order** — the plan is already in build order; do not reorder.
+2. **Setup pre-flight** — if the plan has a `## Setup` section, follow it: install dependencies, apply migrations, and seed data. Run the existing test suite to confirm nothing broke. **⏸ CHECKPOINT: setup** — present the migration/output to the human and wait for approval.
+   - **approve** → continue.
+   - **request changes** → revise and re-present.
+   (Only runs on the first `First run` — the progress file is created after this step, so a resumed session skips setup.)
+3. **Create the progress file** at `docs/plans/<plan-name>-progress.md`:
+
+   ```markdown
+   # Progress: <topic>
+
+   Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
+   Branch: <branch>
+   Started: <ISO timestamp>
+   Last updated: <ISO timestamp>
+
+   | # | Status | Requirement | Commit |
+   |---|--------|-------------|--------|
+   | 1 | ⬜ pending | <requirement name> | — |
+   ```
+4. **Commit the plan docs** — `git add docs/plans/ && git commit -m "docs: add implementation plan"`.
+5. Begin requirement 1 (see [Per-requirement execution](#per-requirement-execution)).
+
+## Resume
+
+1. Read the progress file. Find the first requirement that is `⬜ pending`, `🔄 in-progress`, `⏸ tests-review`, or `⏸ complete-review`.
+2. Resume from the recorded state:
+   - `⏸ tests-review` / `⏸ complete-review` → re-present that checkpoint and wait.
+   - `🔄 in-progress` mid-write → continue the requirement.
+   - `⬜ pending` → start it.
+
+## Progress file
+
+Path: `docs/plans/<plan-name>-progress.md`. Update the matching row directly (not via pattern matching that could corrupt the table). Update `Last updated` on every change.
+
+| Status | Meaning |
+|--------|---------|
+| `⬜ pending` | Not started |
+| `🔄 in-progress` | Writing tests or implementing |
+| `⏸ tests-review` | Paused at checkpoint: tests, awaiting human approval |
+| `⏸ complete-review` | Paused at checkpoint: complete, awaiting human approval |
+| `🔎 review` | Committed; `pwk-code-review` in progress |
+| `✅ done` | `pwk-code-review` complete (smells fixed, hazards noted), all green |
+| `❌ failed` | Could not complete; partial work discarded/reverted (append `Failed: <reason>`) |
+| `⏭ skipped` | User chose to skip |
+
+## Per-requirement execution
+
+For each requirement:
+
+1. **Mark in-progress** — `🔄 in-progress`.
+2. **Write the integration tests (red).** Read the requirement's acceptance criteria + integration-test cases from the plan and write the actual test files. Run them — confirm they **fail** (red). If they pass immediately, the behavior may already exist or the tests are wrong; investigate before proceeding.
+3. **⏸ CHECKPOINT: tests.** Stop. Do not implement yet. Mark `⏸ tests-review`. Present the integration tests and the failing output to the human, and wait for approval. The human reviews whether the right behaviors are being specified.
+   - **approve** → return to `🔄 in-progress` and continue.
+   - **request changes** → revise the tests, re-run, re-present.
+4. **Implement (green).** With full autonomy, implement whatever is needed to make the integration tests pass and satisfy the acceptance criteria — you choose the structure, modules, signatures, and internals. Run the tests after each meaningful change. Refactor for clarity (shallow modules, no duplication, seam discipline) while tests stay green.
+5. **Learn.** If you caught a repeat mistake, append a **generic** rule to `docs/lessons.md` (strip domain specifics).
+6. **⏸ CHECKPOINT: complete.** Stop. Do **not** commit yet. Mark `⏸ complete-review`. Run the tests (show passing output) and `git diff`, present the implementation to the human, and wait for approval.
+   - **approve** → return to `🔄 in-progress` and continue.
+   - **request changes** → revise, re-run, re-present at this same checkpoint.
+7. **Commit.** `git add` the relevant files and commit with a clear message. (Status stays `🔄 in-progress` — not done yet.)
+8. **Code review.** Mark `🔎 review`. Attempt isolated code-review via the `subagent` tool — four agents review the same diff in parallel, each from a different dimension (each gets a fresh context window, zero pollution from previous requirements):
+
+   Gather the requirement's scope: acceptance criteria, integration test cases, and git diff (`git log --oneline -5 && git diff HEAD~N..HEAD`).
+
+   **If the `subagent` tool is available**, invoke it with parallel tasks:
+   ```json
+   {
+     "tasks": [
+       {"agent": "pwk-spec-reviewer", "task": "<scope + diff here>\n\n## Spec Review\nFor each acceptance criterion, point to the code and test that satisfy it. Flag gaps (criterion with no covering code or test) and scope creep (code beyond criteria). Report only — do not modify files. Your findings are collected by the parent agent which applies fixes and commits changes."},
+       {"agent": "pwk-tracing-reviewer", "task": "<scope + diff here>\n\n## Trace Review\nTrace every new/changed code path end-to-end against tests. Note untested branches, dead branches, paths where the trace breaks. Report only — do not modify files. Your findings are collected by the parent agent which applies fixes and commits changes."},
+       {"agent": "pwk-smell-reviewer", "task": "<scope + diff here>\n\n## Smell Review\nReport: shallow modules (interface ≈ implementation complexity), duplication, missing seams / premature abstraction, poor naming, magic values, dead code. Flag only: smells requiring risky large refactors. Report only — do not modify files. Your findings are collected by the parent agent which applies fixes and commits changes."},
+       {"agent": "pwk-hazard-reviewer", "task": "<scope + diff here>\n\n## Hazard Review\nAudit changed code against these hazards: unbounded ops (KEYS/SCAN/full-table loads), missing indexes, unbounded concurrency (Promise.all without limits), long-running transactions, query/command interpolation (injection), unrestricted uploads/temp flooding, silent swallowing loops. Write [SAFE] (1-line reason) or [TRIGGERED] (mitigation). Report only — do not modify files. Your findings are collected by the parent agent which applies fixes and commits changes."}
+     ],
+     "agentScope": "both",
+     "cwd": "<repo-root>"
+   }
+   ```
+
+   **On success:** collect all findings. For smell-review findings: identify the smells, apply the fixes yourself (re-run integration tests after changes — must stay green, commit). For trace/spec/hazard findings: flag as follow-ups for human decision or later fix. Update the progress-file row to `✅ done`. Flag non-trivial issues as follow-ups.
+
+   **Fallback** (subagent unavailable or returns error): revert to inline review — run `/skill:pwk-code-review` for this requirement as before.
+9. **Loop** — go to step 1 for the next `⬜ pending` requirement, or see [After all requirements](#after-all-requirements).
+
+### Checkpoint gates are mandatory
+
+Both checkpoints are **hard stops, not optional**. When you reach one:
+- Stop executing immediately. Do not pass it without explicit human approval.
+- **Never** `git add` or `git commit` before the human approves at a checkpoint.
+- Mark the progress file to the review status **before** pausing.
+
+## User override commands
+
+| User says | Agent does |
+|-----------|-----------|
+| `skip` | Mark current requirement `⏭ skipped`, move to next |
+| `status` | Show the progress table |
+| `stop` | Restore current requirement to its pre-in-progress state, suggest `/new` to resume later |
+| `retry` | Re-read the requirement, start over |
+
+## Receiving feedback (outside a checkpoint)
+
+When the user shares review feedback outside a checkpoint: verify the criticism against the code, evaluate the suggestion, then implement (with tests) or push back with evidence. Don't blindly apply.
+
+## After all requirements
+
+When no `⬜ pending` or `❌ failed` requirements remain, run the **integration gate** before suggesting finalize. Per-requirement code-review only saw each requirement's diff in isolation — this is where you prove the requirements *compose* into the feature:
+
+1. **Run the FULL test suite** (not just the last requirement's tests). Every test must pass. A failure here means one requirement regressed another — fix it now, in execute context, while the progress file and fix autonomy are at hand.
+2. **Confirm the requirements compose** into the feature the design doc described. Each requirement passed alone; do they deliver the intended end-to-end behavior *together*? If integration exposes a gap, fix it here (with tests) before shipping.
+
+Only when the full suite is green and the feature works end-to-end:
+
+```
+✅ All requirements complete — integration verified!
+
+| # | Status | Requirement |
+|---|--------|-------------|
+| 1 | ✅ done | <name> |
+| … | … | … |
+
+   - Ship: /skill:pwk-finalizing
+```
+
+## If you're stuck
+
+1. Re-read the requirement's acceptance criteria — you may have drifted.
+2. Check `git log` for context.
+3. Ask the user — clarify beats guessing.
+4. If still stuck:
+   - Discard uncommitted changes (`git restore .`).
+   - If the requirement has already been committed (step 7 completed), also revert its commit(s) so partial work leaves no trace on the shipped branch (`git revert HEAD --no-edit` if only the requirement commit; `git revert HEAD~N..HEAD --no-edit` if multiple commits including code-review smell fixes).
+
+   **Never leave a failed requirement's partial work on the shipped branch.** Dead code from incomplete requirements must be cleaned up before moving on.
+5. Mark `❌ failed` with the reason and move on.
+6. Check `docs/lessons.md` — a prior lesson may apply.

package/skills/pwk-finalizing/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: pwk-finalizing
+description: "Use after all requirements are complete to delete consumed plan docs, curate lessons, update documentation, and ship the work."
+---
+
+# Finalizing
+
+Ship the completed work.
+
+## Pre-finalization checks
+
+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.
+
+2. Read the progress file (`docs/plans/*-progress.md`). Check for failed or skipped rows:
+
+   - **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.
+
+     Never merge a branch that carries incomplete requirements without explicit acknowledgment.
+
+   - **Only `⏭ skipped`** (no `❌ failed`) → present a warning and confirm:
+
+     ```
+     ⚠️ Requirement 4 was skipped. Continue with finalizing, or go back?
+     ```
+
+     Continue on confirmation; abort otherwise.
+
+## Process
+
+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.
+
+2. **Delete consumed plan docs** — only this design's artifacts; leave other (un-started) design docs in place:
+
+   ```bash
+   rm -f docs/plans/*<topic>*-design.md
+   rm -f docs/plans/*<topic>*-implementation.md
+   rm -f docs/plans/*<topic>*-progress.md
+   ```
+
+   Each `rm -f` gracefully handles a missing file. **Do not touch `docs/adr/`**, `docs/lessons.md`, `CHANGELOG.md`, or `README.md` — those are permanent.
+
+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.
+
+4. **Update documentation** — if the API or surface changed: update `README.md`, `CHANGELOG.md`, and any inline docs.
+
+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 "<summary>"
+      ```
+   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, delete branch.
+   4. **Merge commit** — merge with `--no-ff`, push parent, delete branch.
+
+   For options 2–4, confirm the detected parent branch before proceeding.
+
+6. **Clean up** — if a worktree was used, remove it:
+   ```
+   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

@@ -0,0 +1,83 @@
+---
+name: pwk-writing-plans
+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
+
+Turn the design doc's requirements into a **behavioral spec** the executor implements against.
+
+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).
+
+You may only create or edit files under `docs/plans/`. Do not modify source code or configuration.
+
+## Process
+
+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.
+
+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.
+
+   Save to `docs/plans/YYYY-MM-DD-<topic>-implementation.md`:
+
+   ```markdown
+   # Implementation Plan: <topic>
+
+   ## Overview
+   Design: docs/plans/YYYY-MM-DD-<topic>-design.md
+
+   ## Requirement 1: <name>
+
+   ### Acceptance criteria
+   - Given … When … Then …
+   - Given … When … Then … (edge cases)
+
+   ### Integration tests
+   - `should <behavior>` — asserts <observable outcome>
+   - `should <error case>` — asserts <failure outcome>
+
+   ### Production-risk notes
+   - <from the design's Production-risk areas, if any>
+
+   ## Requirement 2: <name>
+   …
+   ```
+
+   **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`:
+
+   ```markdown
+   ## Setup
+
+   - **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)
+   ```
+
+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.
+
+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").
+
+## What the plan is NOT
+
+- **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.
+
+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`"

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

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

package/docs/plans/completed/2026-04-11-checkpoint-review-gates-design.md

@@ -1,50 +0,0 @@
-# Checkpoint Review Gates for Task Execution
-
-## Problem
-
-Executing-tasks runs through tasks without pausing. There's no way for the human to review tests before implementation, or review implementation before committing. The TDD labels in plans are advisory, not enforceable. There's no configuration for review gates.
-
-## Design
-
-Add optional `checkpoint` labels to individual tasks in the implementation plan. Executing-tasks pauses at checkpoint boundaries for human review.
-
-## Checkpoint labels
-
-Each task can optionally include a `checkpoint` label:
-
-- **`checkpoint: test`** — pause after writing the failing test, before implementing
-- **`checkpoint: done`** — pause after implementation + tests pass, before committing
-- **No label** — auto-advance, no pause
-
-The label is orthogonal to the TDD scenario. A "new feature" task with `checkpoint: test` means: write failing test → pause → implement → run tests → commit. Without a checkpoint, the same task flows straight through.
-
-## Who sets checkpoints
-
-The agent decides which tasks get checkpoints during plan writing, based on complexity and risk. The user reviews the plan before execution and can add, remove, or change checkpoints.
-
-## Changes
-
-### writing-plans/SKILL.md
-
-Add `checkpoint` as an optional field in the task format section, with the two values and the "no label means auto-advance" rule. Update the TDD table to show how checkpoints interact with each scenario. Add guidance for the agent on when to use each checkpoint value.
-
-### executing-tasks/SKILL.md
-
-Update the per-task lifecycle to handle checkpoints:
-
-- **No checkpoint** — existing flow unchanged
-- **`checkpoint: test`** — write failing test → show diff → pause for review → proceed based on human input → implement → run tests → fix if needed → commit
-- **`checkpoint: done`** — implement → run tests → fix if needed → show diff → pause for review → proceed based on human input → commit
-
-The pause is a simple conversation stop — the agent shows what was done and the diff, then waits. The human can say anything: change the test, tweak the implementation, approve, revert, adjust the plan. No rigid menu.
-
-Pause message format:
-
-```
-⏸ Paused at checkpoint: [test|done] for task [N]
-
-**What was done:** [brief summary]
-**Diff:** [show relevant diff]
-
-Review and let me know how to proceed.
-```