@tianhai/pi-workflow-kit 0.5.3 → 0.7.0

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

@@ -0,0 +1,98 @@
+# Checkpoint Review Gates: Implementation Plan
+
+## Tasks
+
+### Task 1: Update writing-plans/SKILL.md — add checkpoint field and agent guidance
+
+**Scenario:** Trivial (docs)
+
+**File:** `skills/writing-plans/SKILL.md`
+
+Add a "Checkpoint labels" section after "TDD in the plan" with the optional `checkpoint` field, values, and agent guidance. Also update the TDD table to show how checkpoints interact with each scenario.
+
+After the "TDD in the plan" section, add:
+
+```
+## Checkpoint labels
+
+Optionally label each task with a `checkpoint` to require human review before proceeding:
+
+| Checkpoint | When to use | What happens during execution |
+|---|---|---|
+| *(none)* | Trivial tasks, well-understood changes | Auto-advance, no pause |
+| **`checkpoint: test`** | Test design matters (API contracts, edge cases, complex behavior) | Pause after writing the failing test, before implementing |
+| **`checkpoint: done`** | Implementation review matters (complex logic, security, performance) | Pause after implementation + tests pass, before committing |
+
+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.
+```
+
+Also update the "Task format" section — after the `git commit` bullet, add:
+
+```
+- Optional `checkpoint: test` or `checkpoint: done` label
+```
+
+**Commit:** `feat(writing-plans): add checkpoint labels for review gates`
+
+### Task 2: Update executing-tasks/SKILL.md — handle checkpoints in per-task lifecycle
+
+**Scenario:** Trivial (docs)
+
+**File:** `skills/executing-tasks/SKILL.md`
+
+Replace the "Per-task lifecycle" section with checkpoint-aware flows. Add a "Checkpoint review" section.
+
+Replace the existing "Per-task lifecycle" section with:
+
+```
+## Per-task lifecycle
+
+Check each task for a `checkpoint` label and follow the appropriate flow:
+
+### No checkpoint (auto-advance)
+
+1. **Implement** — write the code as described in the plan
+2. **Run tests** — verify the changes work
+3. **Fix if needed** — if tests fail, debug and fix before moving on
+4. **Commit** — `git add` the relevant files and commit with a clear message
+
+### checkpoint: test
+
+1. **Write the test** — follow the TDD scenario for the task
+2. **Pause for review** — show what was done and the diff, then wait for human input
+3. **Continue** — implement, run tests, fix if needed
+4. **Commit** — `git add` the relevant files and commit with a clear message
+
+### checkpoint: done
+
+1. **Implement** — write the code as described in the plan
+2. **Run tests** — verify the changes work
+3. **Fix if needed** — if tests fail, debug and fix before moving on
+4. **Pause for review** — show what was done and the diff, then wait for human input
+5. **Commit** — `git add` the relevant files and commit with a clear message
+```
+
+After the "TDD discipline" section, add:
+
+```
+## Checkpoint review
+
+When pausing at a checkpoint, present:
+
+```
+⏸ 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.
+```
+
+Wait for the human to respond. They may:
+- Approve and continue
+- Request changes to the test or implementation
+- Ask to revert the task
+- Adjust the remaining plan
+```
+
+**Commit:** `feat(executing-tasks): add checkpoint review gates`

package/docs/plans/completed/2026-04-11-finalizing-merge-options-design.md

@@ -0,0 +1,33 @@
+# Finalizing: Merge Strategy Options
+
+## Problem
+
+The finalizing skill hard-codes "Create PR" as the only shipping option. In practice, small features often don't need a PR — they can be merged directly back to the parent branch.
+
+## Design
+
+Add a merge strategy step after updating documentation. The human chooses one of four options:
+
+1. **Create PR** — push and open a PR for external review via `gh pr create`
+2. **Rebase & merge** (recommended) — rebase onto parent, fast-forward merge, push parent, delete feature branch. Preserves per-task commit history linearly.
+3. **Squash & merge** — squash all commits into one on parent, push parent, delete feature branch. Clean single-commit history.
+4. **Merge commit** — merge with `--no-ff`, push parent, delete feature branch. Preserves all commits and branch topology.
+
+### Flow for options 2–4 (local merge)
+
+1. Detect parent branch (compare `main` vs `master`, fall back to `git show-branch`)
+2. Switch to parent branch and pull latest
+3. Execute the chosen merge strategy:
+   - Rebase: `git rebase <parent>` on feature branch, then `git merge --ff-only <feature>` on parent
+   - Squash: `git merge --squash <feature>` on parent, then `git commit`
+   - Merge commit: `git merge --no-ff <feature>` on parent
+4. Push parent to origin
+5. Delete feature branch locally and remotely
+
+### Prompting
+
+The skill should ask the human which option they prefer, presenting rebase & merge as the default recommendation.
+
+## Changes
+
+- Update `skills/finalizing/SKILL.md` to replace the hard-coded PR step with the 4-option choice.

package/docs/plans/completed/2026-04-11-finalizing-merge-options-implementation.md

@@ -0,0 +1,75 @@
+# Finalizing: Merge Strategy Options — Implementation Plan
+
+## Context
+
+Replace the hard-coded "Create PR" step in the finalizing skill with a 4-option merge strategy prompt (Create PR, Rebase & merge, Squash & merge, Merge commit).
+
+Design doc: `docs/plans/2026-04-11-finalizing-merge-options-design.md`
+
+---
+
+## Task 1 — Replace the PR step with a merge strategy prompt
+
+**TDD scenario:** Trivial (skill docs, no code to test)
+
+**File:** `skills/finalizing/SKILL.md`
+
+Replace step 3 ("Create PR") and step 4 ("Clean up") with the new merge strategy section. Keep steps 1 and 2 unchanged.
+
+**New content for step 3 onwards:**
+
+```markdown
+3. **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>"
+      ```
+
+   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 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.
+
+4. **Clean up** — if a worktree was used, remove it:
+   ```
+   git worktree remove ../<repo>-<feature-name>
+   ```
+```
+
+**Commit:** `feat: add merge strategy options to finalizing skill`
+
+---
+
+## Done
+
+The finalizing skill now offers four merge strategies instead of only "Create PR". No code files changed — this is a skill-documentation update only.
+
+To verify: read `skills/finalizing/SKILL.md` and confirm it contains all four options with correct commands.

package/docs/plans/completed/2026-04-11-workspace-setup-design.md

@@ -0,0 +1,28 @@
+# Workspace Setup: Move Branch Creation to Brainstorming
+
+## Problem
+
+Brainstorming commits the design doc to whatever branch you're on (usually `main`), polluting it. If the idea is scrapped, you have to revert the commit. The implementation branch created later by writing-plans starts from a point after the design commit, which is messy.
+
+## Design
+
+Move branch/worktree creation from writing-plans into brainstorming. The design doc lands on the feature branch from the start, keeping `main` clean.
+
+## Changes
+
+### brainstorming/SKILL.md
+
+Step 5 changes from writing + committing the design doc on the current branch to:
+
+1. Create a feature branch (`git checkout -b <feature-name>`) or worktree (`git worktree add ../<repo>-<feature-name> -b <feature-name>`) for larger features
+2. Write the design doc to `docs/plans/YYYY-MM-DD-<topic>-design.md`
+3. Single commit on the new branch with the design doc
+
+Feature name is derived from the topic slug in the design doc filename.
+
+### writing-plans/SKILL.md
+
+- Remove step 2 ("Set up workspace") entirely
+- Step 1 expands to verify the feature branch/worktree context created by brainstorming
+- Steps renumber: 1→2→3 becomes 1→2
+- Fallback path (no design doc, brainstorming was skipped) still creates a branch itself so writing-plans works standalone

package/docs/plans/completed/2026-04-11-workspace-setup-implementation.md

@@ -0,0 +1,57 @@
+# Workspace Setup: Implementation Plan
+
+## Tasks
+
+### Task 1: Update brainstorming/SKILL.md — add workspace setup to step 5
+
+**Scenario:** Trivial (docs)
+
+Replace step 5 with workspace creation + design doc commit.
+
+**File:** `skills/brainstorming/SKILL.md`
+
+Replace:
+
+```
+5. **Write the design doc** — save to `docs/plans/YYYY-MM-DD-<topic>-design.md` and commit.
+```
+
+With:
+
+```
+5. **Set up workspace & write the design doc** — create a branch for this work. For larger features, use a git worktree for isolation:
+   ```
+   git worktree add ../<repo>-<feature-name> -b <feature-name>
+   ```
+   Save the design doc to `docs/plans/YYYY-MM-DD-<topic>-design.md` and commit on the new branch.
+```
+
+**Commit:** `refactor(brainstorming): move workspace setup into step 5`
+
+### Task 2: Update writing-plans/SKILL.md — remove step 2, expand step 1
+
+**Scenario:** Trivial (docs)
+
+Remove step 2 ("Set up workspace") entirely. Expand step 1 to verify the feature branch context. Renumber step 3 → 2.
+
+**File:** `skills/writing-plans/SKILL.md`
+
+Replace:
+
+```
+1. **Check for a design doc** — look for `docs/plans/*-design.md`. If one exists, use it as the basis for the plan. If none exists, ask the user to describe what they want to build, read relevant code, and create the plan directly.
+2. **Set up workspace** — create a branch for this work. For larger features, use a git worktree for isolation:
+   ```
+   git worktree add ../<repo>-<feature-name> -b <feature-name>
+   ```
+3. **Write the implementation plan** — break the design into tasks. Save to `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
+```
+
+With:
+
+```
+1. **Check for a design doc & workspace** — look for `docs/plans/*-design.md`. If one exists, use it as the basis for the plan. Verify you're on the feature branch (or in its worktree) created during brainstorming. If no design doc exists, ask the user to describe what they want to build, read relevant code, create a branch, and create the plan directly.
+2. **Write the implementation plan** — break the design into tasks. Save to `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
+```
+
+**Commit:** `refactor(writing-plans): remove workspace setup, verify branch context`

package/docs/workflow-phases.md

@@ -1,71 +1,57 @@
 # Workflow Phases
 
-`pi-workflow-kit` tracks four global phases:
+`pi-workflow-kit` has 4 phases. You invoke each one explicitly with `/skill:`.
 
-```text
+```
 brainstorm → plan → execute → finalize
 ```
 
 ## brainstorm
 
-Primary skill: `/skill:brainstorming`
+```
+/skill:brainstorming
+```
 
-Purpose:
-- explore requirements
-- shape the design
-- produce a design artifact under `docs/plans/`
+- Explore requirements and shape the design
+- Ask questions one at a time, propose approaches
+- Produce `docs/plans/YYYY-MM-DD-<topic>-design.md`
 
-Write boundary:
-- allowed: `docs/plans/`
-- discouraged elsewhere; runtime warnings may be injected
+Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
 
 ## plan
 
-Primary skill: `/skill:writing-plans`
+```
+/skill:writing-plans
+```
 
-Purpose:
-- turn the design into a concrete implementation plan
-- define task type (`code` or `non-code`)
-- define code-task steps or non-code acceptance criteria
+- Read the design doc
+- Break into bite-sized tasks with TDD scenarios
+- Optionally set up a branch or worktree
+- Produce `docs/plans/YYYY-MM-DD-<topic>-implementation.md`
 
-Write boundary:
-- allowed: `docs/plans/`
-- discouraged elsewhere; runtime warnings may be injected
+Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
 
 ## execute
 
-Primary skill: `/skill:executing-tasks`
+```
+/skill:executing-tasks
+```
 
-Purpose:
-- initialize `plan_tracker`
-- execute tasks one at a time
-- track per-task phase and attempt counts
+- Read the implementation plan
+- Implement tasks one at a time: implement → test → fix → commit
+- Handle code review feedback by verifying criticism before implementing
 
-Per-task phases:
-- `define`
-- `approve`
-- `execute`
-- `verify`
-- `review`
-- `fix`
-- terminal states: `complete`, `blocked`
+No write restrictions. All tools available.
 
 ## finalize
 
-Primary skill: `/skill:executing-tasks`
-
-Purpose:
-- perform holistic review
-- prepare PR / push / cleanup
-- archive planning docs
-- update README / CHANGELOG / other documentation when needed
-
-## Detection signals
+```
+/skill:finalizing
+```
 
-The workflow monitor uses a few practical signals:
+- Archive plan docs to `docs/plans/completed/`
+- Update CHANGELOG, README if needed
+- Create PR
+- Clean up worktree if one was used
 
-- skill invocations such as `/skill:brainstorming` or `/skill:writing-plans`
-- writes to `docs/plans/*-design.md` and `docs/plans/*-implementation.md`
-- `plan_tracker` initialization to enter execute
-- all tracked tasks reaching terminal state to mark execute complete
-- boundary-prompt acceptance to enter finalize
+No write restrictions. All tools available.

package/extensions/workflow-guard.ts

@@ -0,0 +1,67 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Workflow Guard extension.
+ *
+ * Blocks write/edit outside docs/plans/ during brainstorm and plan phases.
+ * You control phases explicitly via /skill: commands — no auto-detection,
+ * no state persistence, no prompts.
+ */
+
+type Phase = "brainstorm" | "plan" | null;
+
+const SKILL_TO_PHASE: Record<string, Phase> = {
+	brainstorming: "brainstorm",
+	"writing-plans": "plan",
+};
+
+export function getCurrentPhase(): Phase {
+	return phase;
+}
+
+let phase: Phase = null;
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", () => {
+		phase = null;
+	});
+
+	pi.on("input", (event) => {
+		const text = event.text ?? "";
+		for (const [skill, p] of Object.entries(SKILL_TO_PHASE)) {
+			if (text.includes(skill)) {
+				phase = p;
+				return;
+			}
+		}
+		if (
+			text.includes("executing-tasks") ||
+			text.includes("finalizing")
+		) {
+			phase = null;
+		}
+	});
+
+	pi.on("tool_call", (event, ctx) => {
+		if (!phase) return;
+
+		if (event.toolName !== "write" && event.toolName !== "edit") return;
+
+		const filePath = (event.input as { path?: string }).path ?? "";
+		if (!filePath) return;
+
+		if (filePath.startsWith("docs/plans/")) return;
+
+		if (ctx.hasUI) {
+			ctx.ui.notify(
+				`Blocked ${event.toolName} to ${filePath} during ${phase} phase. Only docs/plans/ is writable.`,
+				"warning",
+			);
+		}
+
+		return {
+			blocked: true,
+			reason: `⚠️ ${phase.toUpperCase()} PHASE: Cannot ${event.toolName} to ${filePath}. Only docs/plans/ is writable during brainstorming and planning.`,
+		};
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "0.5.3",
+  "version": "0.7.0",
   "description": "Workflow skills and enforcement extensions for pi",
   "keywords": [
     "pi-package"
@@ -18,19 +18,15 @@
   },
   "files": [
     "extensions/",
-    "agents/",
     "skills/",
     "docs/",
     "banner.jpg",
     "LICENSE",
-    "README.md",
-    "ROADMAP.md"
+    "README.md"
   ],
   "pi": {
     "extensions": [
-      "extensions/plan-tracker.ts",
-      "extensions/workflow-monitor.ts",
-      "extensions/subagent/index.ts"
+      "extensions/workflow-guard.ts"
     ],
     "skills": [
       "skills"

package/skills/brainstorming/SKILL.md

@@ -1,78 +1,31 @@
 ---
 name: brainstorming
-description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
-allowed-tools: read bash
+description: "Use this before any creative work — creating features, building components, adding functionality, or modifying behavior. Explores intent and design before implementation."
 ---
 
-> **Related skills:** Consider `/skill:using-git-worktrees` to set up an isolated workspace, then `/skill:writing-plans` for implementation planning.
+# Brainstorming
 
-# Brainstorming Ideas Into Designs
+Read-only exploration. You may **not** edit or create any files except under `docs/plans/`.
 
-> ⚠️ **BOUNDARY — DO NOT VIOLATE**
->
-> This skill is **read-only exploration**. You MUST NOT use `edit` or `write` tools.
-> The only tools allowed are `read` and `bash` (for investigation only).
->
-> - ✅ Read code and docs: yes
-> - ✅ Write to `docs/plans/`: yes (design documents only)
-> - ❌ Edit or create any other files: **absolutely no**
->
-> If you find yourself reaching for `edit` or `write`, **stop**. Present what
-> you found as a design section and ask the user to approve it first.
+## Process
 
-## Overview
+1. **Check git state** — run `git status` and `git log --oneline -5`. If there's uncommitted work, ask the user what to do with it first.
+2. **Understand the idea** — read existing code, docs, and recent commits. Ask questions one at a time to refine the idea. Prefer multiple choice when possible.
+3. **Explore approaches** — propose 2-3 approaches with trade-offs. Lead with your recommendation.
+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.
+5. **Set up workspace & write the design doc** — create a branch for this work. For larger features, use a git worktree for isolation:
+   ```
+   git worktree add ../<repo>-<feature-name> -b <feature-name>
+   ```
+   Save the design doc to `docs/plans/YYYY-MM-DD-<topic>-design.md` and commit on the new branch.
 
-Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+## Principles
 
-Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
+- One question at a time
+- YAGNI — remove unnecessary features
+- Design for testability
+- Always explore alternatives before settling
 
-## The Process
+## After the design
 
-**Before anything else — check git state:**
-- Run `git status` and `git log --oneline -5`
-- If on a feature branch with uncommitted or unmerged work, ask the user:
-  - "You're on `<branch>` with uncommitted changes. Want to finish/merge that first, stash it, or continue here?"
-- Require exactly one of: finish prior work, stash, or explicitly continue here
-- If the topic is new, suggest creating a new branch before brainstorming
-
-**Understanding the idea:**
-- Check out the current project state first (files, docs, recent commits)
-- Check if the codebase or ecosystem already solves this before designing from scratch
-- Ask questions one at a time to refine the idea
-- Prefer multiple choice questions when possible, but open-ended is fine too
-- Only one question per message - if a topic needs more exploration, break it into multiple questions
-- Focus on understanding: purpose, constraints, success criteria
-
-**Exploring approaches:**
-- Propose 2-3 different approaches with trade-offs
-- Present options conversationally with your recommendation and reasoning
-- Lead with your recommended option and explain why
-
-**Presenting the design:**
-- Once you believe you understand what you're building, present the design
-- Break it into sections of 200-300 words
-- Ask after each section whether it looks right so far
-- Cover: architecture, components, data flow, error handling, testing
-- Be ready to go back and clarify if something doesn't make sense
-
-## After the Design
-
-**Documentation:**
-- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
-- Commit the design document to git
-- The workflow monitor automatically tracks phase transitions when you invoke skills
-
-**Implementation (if continuing):**
-- Ask: "Ready to set up for implementation?"
-- Set up isolated workspace — `/skill:using-git-worktrees` for larger work, or just create a branch for small changes
-- Use `/skill:writing-plans` to create detailed implementation plan
-
-## Key Principles
-
-- **One question at a time** - Don't overwhelm with multiple questions
-- **Multiple choice preferred** - Easier to answer than open-ended when possible
-- **YAGNI ruthlessly** - Remove unnecessary features from all designs
-- **Design for testability** - Favor approaches with clear boundaries that are easy to verify with TDD
-- **Explore alternatives** - Always propose 2-3 approaches before settling
-- **Incremental validation** - Present design in sections, validate each
-- **Be flexible** - Go back and clarify when something doesn't make sense
+Ask: "Ready to plan? Run `/skill:writing-plans`"