@tianhai/pi-workflow-kit 0.5.3 → 0.6.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/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.