@tianhai/pi-workflow-kit 0.18.1 → 1.0.0

package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-implementation.md

@@ -1,315 +0,0 @@
-# Implementation Plan: Incorporate mattpocock/skills Ideas
-
-Design doc: `docs/plans/2026-05-01-incorporate-mattpocock-skills-design.md`
-
-## Task 1: Update brainstorming skill — design it twice + ADRs
-
-<!-- tdd: trivial -->
-<!-- checkpoint: none -->
-
-Edit `skills/brainstorming/SKILL.md`:
-
-**Step 3** — change from:
-
-```
-3. **Explore approaches** — propose 2-3 approaches with trade-offs. Lead with your recommendation.
-```
-
-to:
-
-```
-3. **Explore approaches** — propose 2-3 approaches. For each approach, sketch the concrete interface (types, method signatures, example caller code) so the comparison is grounded in actual code, not abstract descriptions. Lead with your recommendation.
-```
-
-**Step 4** — change from:
-
-```
-4. **Present the design** — break it into sections of 200-300 words. Check after each section whether it looks right. Cover: architecture, components, data flow, error handling, testing.
-```
-
-to:
-
-```
-4. **Present the design** — break it into sections of 200-300 words. Check after each section whether it looks right. Cover: architecture, components, data flow, error handling, testing.
-
-   When a significant architectural decision is identified, offer to write a lightweight ADR to `docs/plans/adr/`. Only write an ADR when all three are true:
-
-   1. **Hard to reverse** — changing your mind later has meaningful cost
-   2. **Surprising without context** — a future reader will wonder "why?"
-   3. **A real trade-off** — there were genuine alternatives
-
-   ADR format — a title and 1-3 sentences covering context, decision, and why:
-
-   ```markdown
-   # <Short title of the decision>
-
-   <1-3 sentences: context, decision, and why.>
-   ```
-
-   ADRs live under `docs/plans/adr/` and are archived during finalizing alongside the design doc.
-```
-
-```bash
-git commit -m "feat(brainstorming): add design-it-twice interface sketches and ADR output"
-```
-
----
-
-## Task 2: Update writing-plans skill — vertical slices
-
-<!-- tdd: trivial -->
-<!-- checkpoint: none -->
-
-Edit `skills/writing-plans/SKILL.md` — add a new section after "## Task format" and before "## TDD in the plan":
-
-```markdown
-## 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)
-```
-
-Vertical slices ensure every committed task leaves the codebase in a testable state and reduces the blast radius of a bad task.
-```
-
-```bash
-git commit -m "feat(writing-plans): add vertical slice guidance with anti-pattern example"
-```
-
----
-
-## Task 3: Update executing-tasks skill — deep modules refactoring
-
-<!-- tdd: trivial -->
-<!-- checkpoint: none -->
-
-Edit `skills/executing-tasks/SKILL.md` — add a new section after "## TDD discipline":
-
-```markdown
-## Refactoring
-
-After all tests pass for a task, check for refactoring opportunities:
-
-- **Shallow modules** — is the interface nearly as complex as the implementation? Can complexity be hidden behind a simpler interface?
-- **Deletion test** — if you deleted this module, would complexity vanish (pass-through) or reappear across callers (earning its keep)?
-- **Duplication** — extract repeated patterns
-- **Seam discipline** — don't introduce abstraction unless something actually varies across it. One adapter = hypothetical seam. Two adapters = real seam
-
-Run tests after each refactor step. Never refactor while tests are failing.
-
-Key vocabulary: **depth** (lots of behavior behind a small interface), **seam** (where behavior can be altered without editing in place), **locality** (change concentrated in one place).
-```
-
-```bash
-git commit -m "feat(executing-tasks): add refactoring checklist with deep modules vocabulary"
-```
-
----
-
-## Task 4: Create diagnose skill
-
-<!-- tdd: trivial -->
-<!-- checkpoint: none -->
-
-Create `skills/diagnose/SKILL.md`:
-
-```markdown
----
-name: 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."
----
-
-# Diagnose
-
-A 6-phase debugging discipline. Phase 1 is the skill — spend disproportionate effort here.
-
-## Phase 1 — Build a feedback loop
-
-Create a fast, deterministic, agent-runnable pass/fail signal for the bug before doing anything else. Try in this order: failing test, curl script, CLI invocation, headless browser script.
-
-The loop must produce the failure mode the **user** described — not a nearby but different failure. Iterate on the loop itself: can you make it faster? Sharper? More deterministic?
-
-If you genuinely cannot build a loop, stop and say so. List what you tried. Ask for access to a reproducing environment or a captured artifact.
-
-Do not proceed until you have a loop you believe in.
-
-## Phase 2 — Reproduce
-
-Run the loop. Confirm:
-- The failure matches the user's reported symptom
-- The failure is reproducible across multiple runs
-- You've captured the exact symptom (error message, wrong output, slow timing)
-
-## Phase 3 — Hypothesise
-
-Generate 3-5 ranked hypotheses. Each must be falsifiable:
-
-> "If `<X>` is the cause, then `<changing Y>` will make the bug disappear / `<changing Z>` will make it worse."
-
-Show the ranked list to the user before testing. They often have domain knowledge that re-ranks instantly.
-
-## Phase 4 — Instrument
-
-Each probe must map to a specific hypothesis. Change one variable at a time. Tag every debug log with a unique prefix (e.g. `[DEBUG-a4f2]`) for easy cleanup later. Prefer a debugger breakpoint over logs when available.
-
-## Phase 5 — Fix + regression test
-
-Write the regression test **before** the fix — but only if there's a correct seam (one that exercises the real bug pattern at the call site). If no correct seam exists, note it — the codebase architecture is preventing the bug from being locked down.
-
-## Phase 6 — Cleanup
-
-Required before declaring done:
-- Original repro no longer triggers
-- Regression test passes (or absence of seam is documented)
-- All `[DEBUG-...]` instrumentation removed
-- Ask: what would have prevented this bug?
-```
-
-```bash
-git commit -m "feat(diagnose): add standalone debugging skill with 6-phase loop"
-```
-
----
-
-## Task 5: Update finalizing skill — archive ADRs
-
-<!-- tdd: trivial -->
-<!-- checkpoint: none -->
-
-Edit `skills/finalizing/SKILL.md` — update step 1 from:
-
-```
-1. **Move planning docs** — archive the design, implementation, and progress docs, then commit:
-   ```
-   mkdir -p docs/plans/completed
-   mv docs/plans/*-design.md docs/plans/completed/
-   mv docs/plans/*-implementation.md docs/plans/completed/
-   mv docs/plans/*-progress.md docs/plans/completed/
-   git add docs/plans/ && git commit -m "chore: archive planning docs"
-   ```
-```
-
-to:
-
-```
-1. **Move planning docs** — 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/
-   mv docs/plans/*-implementation.md docs/plans/completed/
-   mv docs/plans/*-progress.md docs/plans/completed/
-   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"
-   ```
-```
-
-```bash
-git commit -m "feat(finalizing): archive ADRs alongside planning docs"
-```
-
----
-
-## Task 6: Update documentation
-
-<!-- tdd: trivial -->
-<!-- checkpoint: none -->
-
-### README.md
-
-Update the intro line from:
-
-```
-**4 workflow skills** that guide the agent through a structured development process:
-```
-
-to:
-
-```
-**4 workflow skills** and **1 utility skill** that guide the agent through a structured development process:
-```
-
-Update the pipeline diagram from:
-
-```
-brainstorm → plan → execute → finalize
-```
-
-to:
-
-```
-brainstorm → plan → execute → finalize
-                          ↕
-                      diagnose (on demand)
-```
-
-Add `diagnose` to the skills table:
-
-```
-| `diagnose` | ~35 | 6-phase debugging loop: build feedback loop, reproduce, hypothesise, instrument, fix, cleanup |
-```
-
-Update the Architecture section to include `diagnose/`:
-
-```
-├── skills/
-│   ├── brainstorming/SKILL.md
-│   ├── writing-plans/SKILL.md
-│   ├── executing-tasks/SKILL.md
-│   ├── finalizing/SKILL.md
-│   └── diagnose/SKILL.md
-```
-
-### docs/developer-usage-guide.md
-
-Add to the brainstorm section (after "Outcome"):
-
-```
-- Optionally writes ADRs to `docs/plans/adr/` for significant architectural decisions
-```
-
-Add a new section after the 4 workflow phases:
-
-```markdown
-### 5. Diagnose (on demand)
-
-```
-/skill:diagnose
-```
-
-A 6-phase debugging loop you invoke when something is broken. Build a feedback loop first, then reproduce, hypothesise, instrument, fix, and cleanup. Not a pipeline phase — use whenever needed.
-```
-
-### docs/workflow-phases.md
-
-Add a new section at the end:
-
-```markdown
-## diagnose
-
-```
-/skill:diagnose
-```
-
-Not a pipeline phase. A utility skill invoked on demand when debugging is needed.
-
-- Build a feedback loop (failing test, curl script, etc.)
-- Reproduce, hypothesise, instrument, fix, cleanup
-- No write restrictions (used during execute/finalize, or outside the pipeline)
-```
-
-```bash
-git commit -m "docs: update README, usage guide, and workflow phases for new skills"
-```

package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-progress.md

@@ -1,15 +0,0 @@
-# Progress: incorporate-mattpocock-skills
-
-Plan: docs/plans/2026-05-01-incorporate-mattpocock-skills-implementation.md
-Branch: incorporate-mattpocock-skills
-Started: 2026-05-01T00:00:00Z
-Last updated: 2026-05-01T00:00:00Z
-
-| # | Status | Task | Commit |
-|---|--------|------|--------|
-| 1 | ✅ done | Update brainstorming skill — design it twice + ADRs | 0231b84 |
-| 2 | ✅ done | Update writing-plans skill — vertical slices | 22a46df |
-| 3 | ✅ done | Update executing-tasks skill — deep modules refactoring | c405634 |
-| 4 | ✅ done | Create diagnose skill | 5e39e2d |
-| 5 | ✅ done | Update finalizing skill — archive ADRs | e31a1af |
-| 6 | ✅ done | Update documentation (README, usage guide, workflow phases) | 8c1c4eb |

package/docs/plans/completed/2026-05-08-checkpoint-gates-design.md

@@ -1,235 +0,0 @@
-# Design: Checkpoint gates and pre-commit discipline
-
-## Problem
-
-The `executing-tasks` skill instructs the agent to pause at checkpoints for human review before committing. In practice, the agent commits first then presents the review, defeating the purpose of checkpoints.
-
-Root causes in executing-tasks:
-1. "PAUSE if" reads as optional — the agent interprets it as "if you remember"
-2. Steps 6-12 flow together as implement→commit — the pause gets swallowed
-3. The diff format asks for committed state — nudges the agent to commit first
-
-Root causes in writing-plans:
-4. Task format says `git commit` after each task — the agent sees the commit line past the checkpoint and skips to it
-5. Refactor and lessons are optional-sounding steps at the end of a long list — the agent skips them
-6. The plan body has no structural enforcement — everything is just text the agent reads at once
-
-Secondary issue: the agent skips steps 9 (Refactor if needed) and 10 (Learn from mistakes) because they're optional-sounding steps at the end of a long list.
-
-## Key insight
-
-The agent follows numbered steps and skips loose sections. **Output requirements** (things the agent has to produce) are stronger than instructions (things the agent is told to do). The checkpoint review format forces the agent to report refactoring and lessons — that's the enforcement mechanism.
-
-No-checkpoint tasks are simple enough that refactor/lessons genuinely aren't needed — the task author chose no checkpoint because the task is trivial.
-
-## Solution
-
-- **writing-plans**: Generate task bodies with numbered steps (including refactor/lessons for checkpointed tasks) and checkpoint gates. Never include `git commit` in the plan.
-- **executing-tasks**: Simplified runner — follow the plan step by step, pause at checkpoint gates, commit after approval.
-- **Progress file**: Use Status column to enforce checkpoint gates. Agent can't go from `🔄 in-progress` → `✅ done` if the task has a checkpoint — must go through `⏸ test-review` or `⏸ done-review` first.
-
-## Design
-
-### Writing-plans: task format
-
-The plan never includes `git commit`. That's the executing-tasks skill's responsibility.
-
-**No-checkpoint task:**
-
-```markdown
-## Task 1: Create User model
-
-<!-- tdd: new-feature -->
-<!-- checkpoint: none -->
-
-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 task:**
-
-```markdown
-## Task 2: Write auth tests
-
-<!-- tdd: new-feature -->
-<!-- checkpoint: test -->
-
-Files:
-- `src/auth/login.test.ts`
-
-Steps:
-1. Write failing test for login with valid credentials
-2. Run test — confirm it fails
-
-⏸ **CHECKPOINT: test** — present test review. Wait for human approval before implementing.
-
-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`.
-```
-
-**Checkpoint: done task:**
-
-```markdown
-## Task 3: Add login endpoint
-
-<!-- tdd: new-feature -->
-<!-- checkpoint: done -->
-
-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.
-```
-
-**Task with both checkpoints:**
-
-```markdown
-## Task 4: Complex auth flow
-
-<!-- tdd: new-feature -->
-<!-- checkpoint: test -->
-<!-- checkpoint: done -->
-
-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.
-```
-
-### Writing-plans: checkpoint labels table
-
-| Checkpoint | When to use | What the plan should say |
-|---|---|---|
-| *(none)* | Trivial tasks, well-understood changes | Numbered steps only |
-| **`checkpoint: test`** | Test design matters | Steps up to test → `⏸ CHECKPOINT: test` → implement steps (including refactor/lessons) |
-| **`checkpoint: done`** | Implementation review matters | 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` |
-
-### Executing-tasks: simplified runner
-
-The per-task execution becomes:
-
-1. Mark `🔄 in-progress` in progress file
-2. Read the current task from the plan
-3. Execute each numbered step in order
-4. When hitting `⏸ CHECKPOINT` in the plan:
-   - Update progress to `⏸ test-review` or `⏸ done-review`
-   - Present the checkpoint review (see format below)
-   - Wait for human approval
-   - On approval, update progress back to `🔄 in-progress`
-   - Continue with the next step
-5. After all steps are done (or for no-checkpoint tasks, after steps + commit):
-   - `git add` and commit with a clear message
-   - Update progress to `✅ done` + record commit hash
-
-### Progress file: Status-enforced gates
-
-Status values:
-
-| Status | Meaning |
-|--------|---------|
-| `⬜ pending` | Not started |
-| `🔄 in-progress` | Currently executing plan steps |
-| `⏸ test-review` | Paused at checkpoint: test, waiting for human approval |
-| `⏸ done-review` | Paused at checkpoint: done, waiting for human approval |
-| `✅ done` | Committed successfully |
-| `❌ failed` | Could not complete |
-| `⏭ skipped` | User chose to skip |
-
-Enforcement rules:
-- Agent cannot go from `🔄 in-progress` → `✅ done` if the task has a checkpoint
-- Must go through `⏸ test-review` or `⏸ done-review` first
-- Can only return to `🔄 in-progress` after human says "approve"
-- Can only go to `✅ done` after commit
-
-Example progress file:
-
-```markdown
-# Progress: Auth feature
-
-Plan: docs/plans/2026-05-08-auth-implementation.md
-Branch: auth-feature
-Started: 2026-05-08T10:00:00Z
-Last updated: 2026-05-08T10:05:00Z
-
-| # | Status | Task | Commit |
-|---|--------|------|--------|
-| 1 | ✅ done | Create User model | abc123 |
-| 2 | ⏸ done-review | Add login endpoint (checkpoint: done) | — |
-| 3 | ⬜ pending | Add auth middleware (checkpoint: done) | — |
-```
-
-### Checkpoint review format
-
-For `checkpoint: test`:
-
-```
-⏸ Paused at checkpoint: test for task [N]
-
-**Test written:** [show test code]
-**Expected behavior:** [what this validates]
-**Next:** Continue implementing after approval
-
-**Available actions:**
-- **Approve** — continue to implementation
-- **Request changes** — describe what to change
-- **Revert** — undo this task and mark it back to pending
-- `skip` — skip this task
-- `stop` — pause here, resume later with `/skill:executing-tasks`
-```
-
-For `checkpoint: done`:
-
-```
-⏸ Paused at checkpoint: done for task [N]
-
-**What was done:** [brief summary]
-**Refactoring done:** [what changed, or "none needed — [reason]"]
-**Lessons learned:** [new rule added, or "none"]
-**Diff:** [run `git diff --cached` or `git diff` — do NOT commit first]
-**Next:** Commit after approval
-
-**Available actions:**
-- **Approve** — commit and move to next task
-- **Request changes** — describe what to change
-- **Revert** — undo this task and mark it back to pending
-- `skip` — skip this task
-- `stop` — pause here, resume later with `/skill:executing-tasks`
-```
-
-## Files to change
-
-- `skills/writing-plans/SKILL.md` — update task format template and checkpoint labels section
-- `skills/executing-tasks/SKILL.md` — simplify per-task execution to plan-following runner, update progress file status values
-
-## What stays the same
-
-- executing-tasks: Before you start, First run, Resume, User override commands, Receiving code review, If you're stuck, After all tasks — all unchanged
-- writing-plans: Process steps, vertical slices, TDD section — all unchanged

package/docs/plans/completed/2026-05-08-checkpoint-gates-implementation.md

@@ -1,83 +0,0 @@
-# Implementation: Checkpoint gates and pre-commit discipline
-
-Design: `docs/plans/2026-05-08-checkpoint-gates-design.md`
-
-## Overview
-
-Update two skill files so that:
-1. `writing-plans` generates task bodies with checkpoint gates and numbered refactor/lessons steps, never includes `git commit`
-2. `executing-tasks` becomes a simplified plan-following runner with status-enforced checkpoint gates
-
-## Task 1: Update writing-plans task format and checkpoint labels
-
-<!-- tdd: trivial -->
-<!-- checkpoint: none -->
-
-Files:
-- `skills/writing-plans/SKILL.md`
-
-Changes:
-
-### Task format section
-
-Replace the task format section. Key changes:
-- Remove `git commit` from bullet points (commit is the executing-tasks skill's responsibility)
-- Remove `<!-- checkpoint: none -->` from the default template (omit when no checkpoint)
-- Add task body examples for each checkpoint type (none, test, done, both)
-- For checkpointed tasks, include numbered refactor and lessons steps
-- For checkpointed tasks, include `⏸ CHECKPOINT` gate in the task body
-- No task body should include `git commit`
-
-### Checkpoint labels section
-
-Replace the checkpoint labels table. Change the last column from "What happens during execution" to "What the plan should include", showing the gate structure for each checkpoint type.
-
-### TDD section
-
-Remove "→ commit" from the Instructions column — commit is not part of the plan.
-
-## Task 2: Update executing-tasks per-task execution and progress file
-
-<!-- tdd: trivial -->
-<!-- checkpoint: done -->
-
-Files:
-- `skills/executing-tasks/SKILL.md`
-
-Changes:
-
-### Per-task execution section
-
-Replace the current 15-step list with a simplified plan-following runner:
-
-1. Mark `🔄 in-progress` in progress file
-2. Read the current task from the plan
-3. Execute each numbered step in order
-4. When hitting `⏸ CHECKPOINT` in the plan:
-   - Update progress to `⏸ test-review` or `⏸ done-review`
-   - Present the checkpoint review
-   - Wait for human approval
-   - On approval, update progress back to `🔄 in-progress`
-   - Continue with the next step
-5. After all steps done:
-   - `git add` and commit with a clear message
-   - Update progress to `✅ done` + record commit hash
-
-Remove the inline refactor/lessons steps — they're now in the plan for checkpointed tasks.
-
-### Progress file section
-
-Add `⏸ test-review` and `⏸ done-review` status values. Add enforcement rule: agent cannot go from `🔄 in-progress` → `✅ done` if task has a checkpoint.
-
-### Checkpoint review section
-
-Update `checkpoint: done` review to include:
-- **Refactoring done:** field
-- **Lessons learned:** field
-- **Diff:** uses `git diff --cached` or `git diff`, with "do NOT commit first"
-
-Simplify available actions (remove "Adjust plan" since the plan drives execution).
-
-### Keep unchanged
-
-- Before you start, First run, Resume, User override commands, Receiving code review, If you're stuck, After all tasks

package/docs/plans/completed/2026-05-08-checkpoint-gates-progress.md

@@ -1,11 +0,0 @@
-# Progress: Checkpoint gates and pre-commit discipline
-
-Plan: docs/plans/2026-05-08-checkpoint-gates-implementation.md
-Branch: main
-Started: 2026-05-08T20:00:00Z
-Last updated: 2026-05-08T20:12:00Z
-
-| # | Status | Task | Commit |
-|---|--------|------|--------|
-| 1 | ✅ done | Update writing-plans task format and checkpoint labels | d39510c |
-| 2 | ✅ done | Update executing-tasks per-task execution and progress file (checkpoint: done) | 7c84f59 |