@tianhai/pi-workflow-kit 0.5.3 → 0.7.0

package/docs/developer-usage-guide.md

@@ -1,462 +1,102 @@
 # Developer Usage Guide
 
-This guide explains how to install and use `pi-workflow-kit` as a developer building features with the Pi coding agent.
+How to install and use `pi-workflow-kit` with the Pi coding agent.
 
-## What this package gives you
+## What you get
 
-`pi-workflow-kit` combines:
-
-- **Skills** — markdown instructions the agent can invoke with `/skill:<name>`
-- **Extensions** — runtime behavior that tracks workflow state, warns about process mistakes, and adds tools such as `plan_tracker` and `subagent`
-
-The intended workflow is:
-
-```text
-brainstorm → plan → execute → finalize
-```
-
-Inside **execute**, each task follows this lifecycle:
-
-```text
-define → approve → execute → verify → review → fix
-```
+- **4 skills** that guide the agent through a structured workflow
+- **1 extension** that hard-blocks source writes during brainstorm and plan phases
 
 ## Installation
 
-### Option 1: Install from npm
+### From npm
 
 ```bash
 pi install npm:@tianhai/pi-workflow-kit
 ```
 
-Use this if you want the published package as-is.
-
-### Option 2: Install from the maintained git repo
+### From your own repo
 
 ```bash
-pi install git:github.com/yinloo-ola/pi-workflow-kit.git
+pi install git:github.com/<your-user>/pi-workflow-kit.git
 ```
 
-Use this if you want the repo version directly.
-
-### Option 3: Install from **your own maintained repo or fork**
-
-If you are maintaining your own repo, install from that repo directly:
-
-```bash
-pi install git:github.com/yinloo-ola/pi-workflow-kit.git
-```
-
-For a different fork/repo, use:
-
-```bash
-pi install git:github.com/<your-user>/<your-repo>.git
-```
-
-Examples:
-
-```bash
-pi install git:github.com/acme/pi-workflow-kit.git
-pi install git:github.com/yinloo-ola/pi-workflow-kit.git
-```
-
-This is the best option when:
-- you have customized the skills or extensions
-- you want full control over updates
-- you do not plan to track upstream releases closely
-
-### Option 4: Add your repo to Pi config
-
-Project-level `.pi/settings.json` or global `~/.pi/agent/config.json`:
-
-```json
-{
-  "packages": ["git:github.com/yinloo-ola/pi-workflow-kit.git"]
-}
-```
-
-If you prefer npm instead, you can still use:
+Or in `.pi/settings.json` / `~/.pi/agent/config.json`:
 
 ```json
 {
-  "packages": ["npm:@tianhai/pi-workflow-kit"]
+  "packages": ["git:github.com/<your-user>/pi-workflow-kit.git"]
 }
 ```
 
-After installation, Pi will load the package from whichever source you chose. If you installed from your own repo, future updates come from **your repo**, not the upstream package.
-
-## What activates automatically
-
-After installation, Pi loads:
-
-### Skills
-- `brainstorming`
-- `writing-plans`
-- `executing-tasks`
-- `test-driven-development`
-- `systematic-debugging`
-- `using-git-worktrees`
-- `dispatching-parallel-agents`
-- `receiving-code-review`
+## The workflow
 
-### Extensions
-- **workflow-monitor**
-- **plan-tracker**
-- **subagent**
+You control each phase by invoking the skill:
 
-You do not need to enable these manually.
-
-## Core commands and tools
-
-### Skill invocation
-
-Invoke skills directly in the Pi session:
-
-```text
-/skill:brainstorming
-/skill:writing-plans
-/skill:executing-tasks
-```
-
-### Workflow handoff
-
-Start a fresh session for the next phase. `/workflow-next` enforces immediate-next-only transitions and preserves prior completed workflow history (phases, artifacts, prompted flags) across the handoff:
-
-```text
-/workflow-next plan docs/plans/2026-04-09-feature-design.md
-/workflow-next execute docs/plans/2026-04-09-feature-implementation.md
-/workflow-next finalize docs/plans/2026-04-09-feature-implementation.md
-```
-
-### Plan tracking
-
-Track execution progress:
-
-```ts
-plan_tracker({
-  action: "init",
-  tasks: [
-    { name: "Implement endpoint", type: "code" },
-    { name: "Update README", type: "non-code" },
-  ],
-})
-
-plan_tracker({ action: "update", index: 0, phase: "define" })
-plan_tracker({ action: "update", index: 0, phase: "approve" })
-plan_tracker({ action: "update", index: 0, phase: "execute", attempts: 1 })
-plan_tracker({ action: "update", index: 0, phase: "verify" })
-plan_tracker({ action: "update", index: 0, phase: "review" })
-plan_tracker({ action: "update", index: 0, status: "complete" })
 ```
-
-### Subagent dispatch
-
-Use bundled agents through the `subagent` tool.
-
-Bundled agents require:
-
-```ts
-agentScope: "both"
+/skill:brainstorming  →  /skill:writing-plans  →  /skill:executing-tasks  →  /skill:finalizing
 ```
 
-Example:
+### 1. Brainstorm
 
-```ts
-subagent({
-  agent: "code-reviewer",
-  task: "Review Task 2 implementation against the plan and tests",
-  agentScope: "both",
-})
 ```
-
-## Recommended developer workflow
-
-## 1. Brainstorm
-
-Use this when you have an idea, request, or rough spec.
-
-```text
 /skill:brainstorming
 ```
 
-Expected outcome:
-- a clarified design
-- a design artifact in `docs/plans/`
-- optional worktree/branch setup
-
-Good time to use:
-- `/skill:using-git-worktrees` for larger changes or isolated work
-
-## 2. Write the implementation plan
-
-Use:
-
-```text
-/skill:writing-plans
-```
-
-The implementation plan should be saved under:
-
-```text
-docs/plans/YYYY-MM-DD-<feature>-implementation.md
-```
-
-### Plan authoring rules
-
-Each task should include:
-- a task title
-- `**Type:** code` or `**Type:** non-code`
-- exact file paths
-- concrete implementation steps
-- for code tasks: TDD steps and test commands
-- for non-code tasks: explicit acceptance criteria
+Explore the idea through collaborative dialogue. The agent reads code, asks questions one at a time, proposes 2-3 approaches, and presents the design in sections for your review.
 
-### Example task shapes
+Outcome: `docs/plans/YYYY-MM-DD-<topic>-design.md`
 
-Code task:
+### 2. Plan
 
-```md
-### Task 1: Add retry logic
-
-**Type:** code
-**TDD scenario:** New feature — full TDD cycle
-
-**Files:**
-- Modify: `src/retry.ts`
-- Test: `tests/retry.test.ts`
 ```
-
-Non-code task:
-
-```md
-### Task 2: Update docs
-
-**Type:** non-code
-
-**Files:**
-- Modify: `README.md`
-- Modify: `docs/architecture.md`
-
-**Acceptance criteria:**
-- README describes the new API accurately
-- Architecture doc reflects the new flow
-- Terminology matches the codebase
+/skill:writing-plans
 ```
 
-## 3. Execute the plan
+Read the design doc and break it into bite-sized tasks with exact file paths, complete code, and TDD scenarios. Optionally set up a branch or worktree.
 
-Use:
+Outcome: `docs/plans/YYYY-MM-DD-<topic>-implementation.md`
 
-```text
-/skill:executing-tasks
-```
+### 3. Execute
 
-At the start of execution, the agent should:
-1. read the plan
-2. extract tasks and task types
-3. initialize `plan_tracker`
-
-Example:
-
-```ts
-plan_tracker({
-  action: "init",
-  tasks: [
-    { name: "Add retry logic", type: "code" },
-    { name: "Update docs", type: "non-code" },
-  ],
-})
 ```
-
-## Per-task lifecycle during execution
-
-For each task:
-
-1. **define**
-   - code task: define/write tests
-   - non-code task: define/refine acceptance criteria
-2. **approve**
-   - human approves tests or acceptance criteria
-3. **execute**
-   - implement the task
-   - bounded retries
-4. **verify**
-   - rerun checks and report pass/fail
-5. **review**
-   - subagent review + human sign-off
-6. **fix**
-   - address review issues and re-enter verify/review
-
-### Important behavior
-
-- **Code tasks** follow TDD guidance
-- **Non-code tasks** use acceptance criteria instead of TDD
-- The plan tracker widget shows task progress in the TUI
-- When all tasks reach a terminal state, the workflow can move into **finalize**
-
-## 4. Finalize
-
-Use:
-
-```text
 /skill:executing-tasks
 ```
 
-or start a fresh finalize session with:
-
-```text
-/workflow-next finalize docs/plans/2026-04-09-feature-implementation.md
-```
-
-Finalize typically includes:
-- holistic review
-- PR preparation
-- doc updates
-- archive planning docs
-- cleanup of worktree/branch if needed
-
-## What the extensions do while you work
-
-### Workflow Monitor
-
-The workflow monitor runs in the background and helps keep the agent aligned.
-
-It can:
-- track the current global phase
-- prompt at workflow boundaries
-- warn when source is written before tests
-- warn when fixing starts without investigation after failures
-- warn on commit/push/PR creation without recent passing verification
-- remind the agent to confirm branch/worktree before the first write
+Implement the plan task-by-task. Each task: implement → run tests → fix if needed → commit.
 
-### Task Tracker
+### 4. Finalize
 
-The plan tracker stores execution state outside the prompt and shows it in the TUI.
-
-It tracks:
-- task name
-- task type
-- task status
-- task phase
-- execute attempts
-- fix attempts
-
-### Subagent
-
-The subagent extension lets the main agent delegate focused work to isolated helper agents.
-
-Bundled agents include:
-- `implementer`
-- `worker`
-- `code-reviewer`
-- `spec-reviewer`
-
-## Practical examples
-
-### Example: Start a new feature
-
-```text
-/skill:brainstorming
 ```
-
-Then:
-
-```text
-/skill:writing-plans
-```
-
-Then:
-
-```text
-/skill:executing-tasks
-```
-
-### Example: Ask for code review during execution
-
-```ts
-subagent({
-  agent: "code-reviewer",
-  task: "Review Task 3 implementation for correctness, edge cases, and test coverage",
-  agentScope: "both",
-})
-```
-
-### Example: Move to a fresh execute session
-
-```text
-/workflow-next execute docs/plans/2026-04-09-my-feature-implementation.md
+/skill:finalizing
 ```
 
-### Example: Move to a fresh finalize session
+Archive plan docs, update CHANGELOG/README, create PR, clean up worktree.
 
-```text
-/workflow-next finalize docs/plans/2026-04-09-my-feature-implementation.md
-```
+## What the extension does
 
-## Publishing your maintained package
+The `workflow-guard` extension watches `write` and `edit` tool calls:
 
-If you publish the maintained fork to npm, the package name is:
+- **During brainstorm and plan**: blocks writes outside `docs/plans/`. The agent can read code and use bash, but cannot modify source files.
+- **During execute and finalize**: no restrictions. All tools available.
 
-```text
-@tianhai/pi-workflow-kit
-```
+No configuration needed. It activates automatically after install.
 
-Typical release flow:
+## TDD guidance
 
-```bash
-npm run check
-npm version patch
-git push origin main --follow-tags
-```
+The plan labels each task with a TDD scenario:
 
-Then users install with:
+| Scenario | When | Rule |
+|----------|------|------|
+| New feature | Adding new behavior | Write failing test → implement → pass |
+| Modifying tested code | Changing existing behavior | Run existing tests first → modify → verify |
+| Trivial | Config, docs, naming | Use judgment |
 
-```bash
-pi install npm:@tianhai/pi-workflow-kit
-```
+This is guidance in the skill instructions, not runtime enforcement.
 
-## Best practices for developers
+## Tips
 
-- Start with `brainstorming` for anything non-trivial
-- Use `writing-plans` before touching code for multi-step work
+- Start with brainstorming for anything non-trivial
+- Use writing-plans before touching code for multi-step work
 - Put all plan artifacts under `docs/plans/`
-- Always include task `Type:` in implementation plans
-- Use `code` for implementation/test work and `non-code` for docs/process tasks
-- Let `plan_tracker` reflect the real lifecycle instead of keeping state only in chat
-- Use `subagent(..., agentScope: "both")` when you want bundled agents
-- Treat workflow monitor warnings as signals to correct process, not as noise
-- Use `/workflow-next` when handing off between sequential workflow phases
-
-## Common mistakes to avoid
-
-- Starting execution without an implementation plan
-- Initializing `plan_tracker` with task names only when your plan contains non-code tasks
-- Forgetting `agentScope: "both"` for bundled subagents
-- Treating verify/review as global phases instead of per-task steps inside execute
-- Writing files outside `docs/plans/` during brainstorm/plan unless you intentionally advance phases
-- Claiming work is done without running verification checks
-
-## Migration note
-
-If you previously installed `@yinlootan/pi-superpowers-plus`, replace it with `@tianhai/pi-workflow-kit`:
-
-```json
-{
-  "packages": ["npm:@tianhai/pi-workflow-kit"]
-}
-```
-
-The rebrand keeps runtime names stable, so existing usage still centers on:
-- `plan_tracker`
-- `workflow_reference`
-- `/workflow-next`
-- `/workflow-reset`
-- the existing skill names
-
-## Where to look next
-
-- `README.md`
-- `docs/oversight-model.md`
-- `docs/workflow-phases.md`
-- `skills/writing-plans/SKILL.md`
-- `skills/executing-tasks/SKILL.md`
+- During execute, the agent handles code review feedback by verifying criticism before implementing

package/docs/oversight-model.md

@@ -1,49 +1,28 @@
 # Oversight Model
 
-`pi-workflow-kit` combines **skills** and **extensions**.
+`pi-workflow-kit` combines **skills** and **one extension**.
 
 ## Skills
 
-Skills teach the agent the intended workflow:
+Skills teach the agent the workflow. There are 4:
 
-- `brainstorming`
-- `writing-plans`
-- `executing-tasks`
-- supporting skills such as TDD, debugging, worktrees, and review handling
+- **brainstorming** — explore ideas, produce a design doc
+- **writing-plans** — break design into TDD tasks
+- **executing-tasks** — implement tasks, handle code review
+- **finalizing** — archive docs, create PR
 
 They explain *what* to do and *when* to do it.
 
-## Extensions
+## Extension
 
-Extensions observe runtime behavior and add lightweight enforcement:
+The `workflow-guard` extension enforces one rule:
 
-- **workflow-monitor** tracks workflow phase, injects TDD/debug/verification warnings, and prompts at phase boundaries
-- **plan-tracker** stores per-task execution state, including task type, phase, and attempt counts
-- **subagent** runs isolated helper agents for implementation and review work
+> During brainstorm and plan phases, `write` and `edit` are **hard-blocked** outside `docs/plans/`.
 
-## Enforcement style
-
-The package is intentionally **warning-first**.
-
-- TDD violations are injected into tool results as warnings
-- Debug guardrails escalate after repeated failing cycles
-- Verification checks warn on `git commit`, `git push`, and `gh pr create` when passing tests have not been run recently
-- During brainstorm and plan, writes outside `docs/plans/` trigger process warnings and may escalate to an interactive stop in the TUI
-
-In interactive sessions, repeated violations can trigger a human decision prompt.
+The agent can still use `read` and `bash` for investigation. It literally cannot call `write` or `edit` on source files — the tools are blocked at the extension level.
 
-## Workflow model
-
-Global workflow phases:
-
-```text
-brainstorm → plan → execute → finalize
-```
-
-Inside **execute**, each task follows the per-task lifecycle tracked by `plan_tracker`:
+## Enforcement style
 
-```text
-define → approve → execute → verify → review → fix
-```
+Hard block for write boundaries. No warnings, no escalation, no prompts. Either the tool call is allowed or it's blocked.
 
-This keeps global workflow tracking simple while still reflecting the real per-task feedback loop.
+TDD, debugging, and code review are guidance in the skill instructions, not runtime-enforced.

package/docs/plans/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-checkpoint-review-gates-design.md

@@ -0,0 +1,50 @@
+# 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.
+```