@tianhai/pi-workflow-kit 0.5.3 → 0.7.0

package/skills/executing-tasks/SKILL.md

@@ -1,247 +1,82 @@
 ---
 name: executing-tasks
-description: Use when you have an approved implementation plan to execute task-by-task with human gates and bounded retries
+description: "Use this to implement an approved plan task-by-task. Run after writing-plans, before finalizing."
 ---
 
 # Executing Tasks
 
-## Overview
+Implement the plan from `docs/plans/*-implementation.md` task by task.
 
-Execute an implementation plan task-by-task using a per-task lifecycle with human gates and bounded retry loops. Each task goes through: **define → approve → execute → verify → review → fix**.
+## Per-task lifecycle
 
-**Announce at start:** "I'm using the executing-tasks skill to implement the plan."
+Check each task for a `checkpoint` label and follow the appropriate flow:
 
-## Prerequisites
+### No checkpoint (auto-advance)
 
-Before starting, verify:
-- [ ] On the correct branch/worktree
-- [ ] Plan file exists at `docs/plans/YYYY-MM-DD-<name>.md`
-- [ ] Plan has been reviewed and approved
+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
 
-## Initialization
+### checkpoint: test
 
-1. Read the plan file and extract all tasks, including each task's `Type:` field
-2. Initialize plan_tracker with structured task metadata:
-   ```
-   plan_tracker({
-     action: "init",
-     tasks: [
-       { name: "Task 1 name", type: "code" },
-       { name: "Task 2 name", type: "non-code" },
-     ],
-   })
-   ```
-3. Mark the execute phase as active
+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
 
-## Per-Task Lifecycle
+### checkpoint: done
 
-For each task in the plan:
+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
 
-### 1. Define
+## TDD discipline
 
-**Code task →** Write actual test file(s) with assertions:
-- Create test files that exercise the new/modified behavior
-- Tests must be specific, deterministic, and fail before implementation
-- Include edge cases and error conditions
-- Apply TDD-specific guidance only to code tasks
+Follow the TDD scenario from the plan:
 
-**Non-code task →** Reuse and refine the plan's acceptance criteria:
-- List specific, measurable conditions
-- Each criterion must be independently verifiable
-- Treat these criteria as the basis for approval and verification
+- **New feature**: write the test first, see it fail, then implement
+- **Modifying tested code**: run existing tests before and after
+- **Trivial change**: use judgment
 
-Update plan_tracker:
-```
-plan_tracker({ action: "update", index: N, phase: "define" })
-```
-
-### 2. Approve (Human Gate)
-
-Present the test cases or acceptance criteria to the human:
-
-**For code tasks:**
-- Show the test files to be written
-- Explain what each test verifies
-- Ask: "Do these test cases cover the requirements? Approve, revise, or reject?"
-
-**For non-code tasks:**
-- Show the acceptance criteria list from the plan
-- Ask: "Do these criteria capture the intent? Approve, revise, or reject?"
-
-**No execution begins until approved.**
-
-If revised → return to Define step.
-If rejected → skip task and mark as blocked.
-
-```
-plan_tracker({ action: "update", index: N, phase: "approve" })
-```
+Don't skip tests because "it's obvious." The test is the contract.
 
-### 3. Execute (max 3 attempts)
+## Checkpoint review
 
-Implement the task following the plan's steps.
+When pausing at a checkpoint, present:
 
-For each attempt:
-1. Write/modify code as specified in the plan
-2. Run tests or verify against acceptance criteria
-3. If all pass → move to Verify
-4. If failures:
-   - Analyze the failures
-   - Fix the implementation
-   - Increment executeAttempts
-   - If executeAttempts reaches 3 → **escalate to human**
-
-```
-plan_tracker({ action: "update", index: N, phase: "execute" })
-plan_tracker({ action: "update", index: N, attempts: 1 })  // after each attempt (routes to executeAttempts based on phase)
 ```
+⏸ Paused at checkpoint: [test|done] for task [N]
 
-**Escalation on budget exhaustion:**
-> "I've attempted this task 3 times without success. Options:
-> 1. Revise the scope or approach
-> 2. Adjust the test cases / acceptance criteria
-> 3. Abandon this task and move on
-> 
-> What would you like to do?"
-
-### 4. Verify
-
-Re-run all tests or check all acceptance criteria.
-
-Report results to the human:
-- ✅ Condition 1: passed
-- ✅ Condition 2: passed
-- ❌ Condition 3: failed — [description of failure]
-
-**Does not auto-fix.** Flags failures to human for decision.
+**What was done:** [brief summary]
+**Diff:** [show relevant diff]
 
+Review and let me know how to proceed.
 ```
-plan_tracker({ action: "update", index: N, phase: "verify" })
-```
-
-If failures detected:
-> "Verification found issues. Options:
-> 1. Go back to Execute for another attempt
-> 2. Revise the tests/criteria
-> 3. Accept as-is (mark partial)
-> 
-> What would you like to do?"
-
-### 5. Review (two layers)
 
-**Layer 1 — Subagent review:**
-- Dispatch a subagent to review the implementation against the task spec
-- Subagent checks: correctness, edge cases, code quality, test coverage
-- Subagent reports findings
+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
 
-  Use `agentScope: "both"` to access the bundled `code-reviewer` agent:
-  ```
-  subagent({ agent: "code-reviewer", task: "Review implementation of task N against spec", agentScope: "both" })
-  ```
+## Receiving code review
 
-**Layer 2 — Human sign-off:**
-- Present the subagent review + test results to the human
-- Summarize what was done, what passed, any concerns
-- Ask: "Does this look good? Approve or request changes?"
+When the user shares code review feedback:
 
-```
-plan_tracker({ action: "update", index: N, phase: "review" })
-```
+1. **Verify the criticism** — read the relevant code. Is the feedback accurate?
+2. **Evaluate the suggestion** — is the proposed fix the right approach? Consider alternatives.
+3. **Implement or push back** — if valid, fix it. If not, explain why with evidence from the codebase.
+4. **Don't blindly implement** — every suggestion should be verified against the code before accepting.
 
-If issues found → move to Fix.
+## If you're stuck
 
-### 6. Fix (max 3 loops, re-enters Verify → Review)
+- Re-read the plan — you may have drifted from the spec
+- Check git log — recent commits may reveal context
+- Ask the user — it's better to clarify than to guess wrong
 
-1. Address the review feedback
-2. Re-enter Verify → Review cycle
-3. Increment fixAttempts after each fix round
-4. If fixAttempts reaches 3 → **escalate to human**
-
-```
-plan_tracker({ action: "update", index: N, phase: "fix" })
-plan_tracker({ action: "update", index: N, attempts: 1 })  // routes to fixAttempts based on phase
-```
-
-**Escalation on budget exhaustion:**
-> "I've attempted fixes 3 times. Options:
-> 1. Proceed as-is despite remaining issues
-> 2. Keep fixing (at your own risk)
-> 3. Abandon this task and move on
-> 
-> What would you like to do?"
-
-### Task Complete
-
-When both reviewers are satisfied and all conditions pass:
-
-```
-plan_tracker({ action: "update", index: N, status: "complete" })
-```
-
-Commit the task:
-```bash
-git add <relevant files>
-git commit -m "feat(task N): <description>"
-```
-
-## Escalation Rules
-
-| Event | Action |
-|-------|--------|
-| Execute 3 attempts exhausted | Escalate to human — never auto-skip |
-| Fix loop 3 attempts exhausted | Escalate to human — never auto-skip |
-| Verify fails | Flag to human — human decides next step |
-
-**No silent skipping. Consistent escalation everywhere.**
-
-## Finalize Phase
-
-After all tasks complete (or are explicitly accepted by human):
-
-### 1. Final Review
-- Dispatch subagent to review the entire implementation holistically
-- Check for integration issues, consistency across tasks, documentation gaps
-
-### 2. Create PR
-```bash
-git push origin <branch>
-gh pr create --title "feat: <feature summary>" --body "<task summary>"
-```
-
-### 3. Archive Planning Docs
-```bash
-mkdir -p docs/plans/completed
-mv docs/plans/<plan-file> docs/plans/completed/
-```
+## After all tasks
 
-### 4. Update Repo Docs
-- Update CHANGELOG with feature summary
-- Update README if API/surface changed
-- Update inline documentation as needed
-
-### 5. Update Project Documentation
-- Update README if project overview has changed
-- Update CONTRIBUTING or architecture docs if structure changed
-- Note any new patterns or conventions introduced
-
-### 6. Clean Up
-- Remove worktree if one was used
-- Mark finalize phase complete
-
-## Boundaries
-- Read code, docs, and tests: yes
-- Write tests and implementation code: yes (within current task scope)
-- Write to docs/plans/completed/: yes (during finalize)
-- Edit files outside task scope: no (unless human explicitly approves)
-
-## Remember
-- Always present test cases/criteria for human approval before executing
-- Extract each task's `Type:` from the plan and preserve it in `plan_tracker`
-- Track per-task phase and attempts in plan_tracker
-- Code tasks use TDD; non-code tasks use acceptance criteria during define, approve, and verify
-- Escalate immediately on budget exhaustion — never silently skip or continue
-- Verify does not auto-fix — always flag to human
-- Review has two layers (subagent first, then human)
-- Fix loops re-enter verify → review (max 3 fix loops)
-- Execute has separate budget (max 3 attempts)
-- Total max cycles per task: 3 execute + 3 fix = 6
+Ask: "All tasks done? Run `/skill:finalizing` to ship."

package/skills/finalizing/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: finalizing
+description: "Use this after all tasks are complete to clean up, document, and ship the work."
+---
+
+# Finalizing
+
+Ship the completed work.
+
+## Process
+
+1. **Move planning docs** — archive the design and implementation docs, then commit:
+   ```
+   mkdir -p docs/plans/completed
+   mv docs/plans/*-design.md docs/plans/completed/
+   mv docs/plans/*-implementation.md docs/plans/completed/
+   git add docs/plans/completed/ && git commit -m "chore: archive planning docs"
+   ```
+
+2. **Update documentation** — if the API or surface changed:
+   - Update README.md
+   - Update CHANGELOG.md
+   - Update any inline docs
+
+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>
+   ```

package/skills/writing-plans/SKILL.md

@@ -1,149 +1,49 @@
 ---
 name: writing-plans
-description: Use when you have a spec or requirements for a multi-step task, before touching code
+description: "Use this to break a design into an implementation plan with bite-sized TDD tasks. Works with or without a prior brainstorm."
 ---
 
-> **Related skills:** Did you `/skill:brainstorming` first? Ready to implement? Use `/skill:executing-tasks`.
-
 # Writing Plans
 
-## Overview
-
-Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
-
-Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
-
-**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
-
-**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
-
-**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>-implementation.md`
-
-## Boundaries
-- Read code and docs: yes
-- Write to docs/plans/: yes
-- Edit or create any other files: no
-
-## Bite-Sized Task Granularity
-
-**Each step is one action (2-5 minutes):**
-- "Write the failing test" - step
-- "Run it to make sure it fails" - step
-- "Implement the minimal code to make the test pass" - step
-- "Run the tests and make sure they pass" - step
-- "Commit" - step
-
-## Plan Document Header
-
-**Every plan MUST start with this header:**
-
-```markdown
-# [Feature Name] Implementation Plan
-
-> **REQUIRED SUB-SKILL:** Use the executing-tasks skill to implement this plan task-by-task.
-
-**Goal:** [One sentence describing what this builds]
-
-**Architecture:** [2-3 sentences about approach]
-
-**Tech Stack:** [Key technologies/libraries]
-
----
-```
+Read-only exploration. You may **not** edit or create any files except under `docs/plans/`.
 
-## Task Structure
+## Process
 
-Every task must declare its type explicitly so `executing-tasks` can initialize `plan_tracker` with the correct metadata.
+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`.
 
-### Code task template
+## Task format
 
-```markdown
-### Task N: [Component Name]
+Each task should be 2-5 minutes of work:
 
-**Type:** code
-**TDD scenario:** [New feature — full TDD cycle | Modifying tested code — run existing tests first | Trivial change — use judgment]
-
-**Files:**
-- Create: `exact/path/to/file.py`
-- Modify: `exact/path/to/existing.py:123-145`
-- Test: `tests/exact/path/to/test.py`
-
-**Step 1: Write the failing test**
-
-```python
-def test_specific_behavior():
-    result = function(input)
-    assert result == expected
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `pytest tests/path/test.py::test_name -v`
-Expected: FAIL with "function not defined"
-
-**Step 3: Write minimal implementation**
-
-```python
-def function(input):
-    return expected
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `pytest tests/path/test.py::test_name -v`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add tests/path/test.py src/path/file.py
-git commit -m "feat: add specific feature"
-```
-```
-
-### Non-code task template
-
-```markdown
-### Task N: [Documentation / rollout / analysis task]
-
-**Type:** non-code
-
-**Files:**
-- Modify: `README.md`
-- Modify: `docs/architecture.md`
+- Exact file paths to create/modify
+- Complete code (not "add validation")
+- Exact commands with expected output
+- `git commit` after each task
+- Optional `checkpoint: test` or `checkpoint: done` label
 
-**Acceptance criteria:**
-- Criterion 1: [Specific, observable outcome]
-- Criterion 2: [Specific, observable outcome]
-- Criterion 3: [Specific, observable outcome]
+## TDD in the plan
 
-**Implementation notes:**
-- Update the listed files only.
-- Keep terminology consistent with the rest of the repo.
-- Reference the relevant code paths or docs where useful.
+Label each task with its TDD scenario:
 
-**Verification:**
-- Review each acceptance criterion one-by-one.
-- Confirm the updated docs match the implemented behavior.
-```
+| Scenario | When | Instructions in the task |
+|---|---|---|
+| **New feature** | Adding new behavior | Write failing test → run it → implement → run it → commit |
+| **Modifying tested code** | Changing existing behavior | Run existing tests first → modify → verify they pass → commit |
+| **Trivial** | Config, docs, naming | Use judgment, commit when done |
 
-## Remember
-- Exact file paths always
-- Every task must include `**Type:** code` or `**Type:** non-code`
-- Non-code tasks must include explicit `**Acceptance criteria:**`
-- Complete code in plan (not "add validation")
-- Exact commands with expected output
-- Reference relevant skills
-- DRY, YAGNI, TDD, frequent commits
-- Order tasks so each task's dependencies are completed by earlier tasks
-- If plan exceeds ~8 tasks, consider splitting into phases with a checkpoint between them
+## Checkpoint labels
 
-## Execution Handoff
+Optionally label each task with a `checkpoint` to require human review before proceeding:
 
-After saving the plan, the workflow monitor automatically tracks phase transitions when you invoke skills.
+| 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 |
 
-Then offer execution:
+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.
 
-**"Plan complete and saved to `docs/plans/<filename>.md`. Ready to execute with `/skill:executing-tasks`."**
+## After the plan
 
-The executing-tasks skill handles the full per-task lifecycle (define → approve → execute → verify → review → fix) with human gates and bounded retry loops.
+Ask: "Ready to execute? Run `/skill:executing-tasks`"

package/ROADMAP.md

@@ -1,16 +0,0 @@
-# Roadmap
-
-Short-term priorities for `pi-workflow-kit`:
-
-- keep the simplified 4-phase workflow coherent across skills, extensions, and docs
-- improve `executing-tasks` ergonomics for real feature delivery
-- continue tightening workflow-monitor tests around phase transitions and handoffs
-- improve README and reference docs so package behavior is easy to trust
-- expand examples for non-code tasks and finalize flows
-
-Longer-term possibilities:
-
-- richer plan parsing helpers for typed task extraction
-- deeper TUI support for active-task detail
-- more bundled subagents for targeted review and maintenance tasks
-- optional reporting/export of workflow state

package/agents/code-reviewer.md

@@ -1,18 +0,0 @@
----
-name: code-reviewer
-description: "Production readiness review: quality, security, testing (read-only)"
-tools: read, bash, find, grep, ls
----
-
-You are a code quality reviewer.
-
-Review for:
-- correctness, error handling
-- maintainability
-- security and footguns
-- test coverage quality
-
-Return:
-- Strengths
-- Issues (Critical/Important/Minor)
-- Clear verdict (ready or not)

package/agents/config.ts

@@ -1,5 +0,0 @@
-/**
- * Canonical model configuration for bundled agents.
- * Change this one constant to update the default model for all bundled agents.
- */
-export const DEFAULT_MODEL = "claude-sonnet-4-5";

package/agents/implementer.md

@@ -1,26 +0,0 @@
----
-name: implementer
-description: Implement tasks via TDD and commit small changes
-tools: read, write, edit, bash, plan_tracker, workflow_reference
-extensions: ../extensions/workflow-monitor, ../extensions/plan-tracker
----
-
-You are an implementation subagent.
-
-## TDD Approach
-
-Determine which scenario applies before writing code:
-
-**New files / new features:** Full TDD. Write a failing test first, verify it fails, implement minimal code to pass, refactor.
-
-**Modifying code with existing tests:** Run existing tests first to confirm green. Make your change. Run tests again. If the change isn't covered by existing tests, add a test. If it is, you're done.
-
-**Trivial changes (typo, config, rename):** Use judgment. Run relevant tests after if they exist.
-
-**If you see a ⚠️ TDD warning:** Pause. Consider which scenario applies. If existing tests cover your change, run them and proceed. If not, write a test first.
-
-## Rules
-- Keep changes minimal and scoped to the task.
-- Run the narrowest test(s) first, then the full suite when appropriate.
-- Commit when the task's tests pass.
-- Report: what changed, tests run, files changed, any concerns.

package/agents/spec-reviewer.md

@@ -1,13 +0,0 @@
----
-name: spec-reviewer
-description: Verify implementation matches the plan/spec (read-only)
-tools: read, bash, find, grep, ls
----
-
-You are a spec compliance reviewer.
-
-Check the implementation against the provided requirements.
-- Identify missing requirements.
-- Identify scope creep / unrequested changes.
-- Point to exact files/lines and provide concrete fixes.
-Return a clear verdict: ✅ compliant / ❌ not compliant.

package/agents/worker.md

@@ -1,17 +0,0 @@
----
-name: worker
-description: General-purpose worker for isolated tasks
-tools: read, write, edit, bash, plan_tracker, workflow_reference
-extensions: ../extensions/workflow-monitor, ../extensions/plan-tracker
----
-
-You are a general-purpose subagent. Follow the task exactly.
-
-## TDD (when changing production code)
-
-- New files: write a failing test first, then implement.
-- Modifying existing code: run existing tests first, make your change, run again. Add tests if not covered.
-- Trivial changes: run relevant tests after if they exist.
-- If you see a ⚠️ TDD warning, pause and decide which scenario applies before proceeding.
-
-Prefer small, test-backed changes.