pi-workflow-kit

Stop AI agents from rushing to code. Enforce a structured brainstorm→plan→execute→verify→finalize workflow with TDD discipline.

AI coding agents tend to skip design and jump straight into implementation, producing over-engineered or misaligned code. pi-workflow-kit solves this by hard-blocking write operations during brainstorm and planning phases — the agent literally cannot modify your source files until you approve the design.

pi package. Zero configuration required.

Install

pi install npm:@tianhai/pi-workflow-kit

No setup needed — skills and guards activate automatically after install.

Want to try before committing?

pi -e npm:@tianhai/pi-workflow-kit

What You Get

🛡️ Workflow Guard (extension)

Enforces phase-appropriate tool access — not just guidelines, but hard blocks:

| Phase | write / edit | bash | |-------|:-:|:-:| | Brainstorm / Plan / Verify | 🔒 Blocked outside docs/plans/ | 🔒 Read-only only (grep, find, cat, git status, curl…) | | Execute / Finalize | ✅ Full access | ✅ Full access |

The agent can read code and discuss design with you during brainstorm/plan, but it physically cannot modify source files or run mutating commands.

🧠 7 Workflow Skills

Guide the agent through a disciplined development process:

brainstorm → plan → [design-review?] → execute → [verify?] → finalize ↕ diagnose (anytime)

For multi-feature designs, the plan→execute loop repeats per feature.

| Phase | Trigger | What Happens | |-------|---------|--------------| | Brainstorm | /skill:pwk-brainstorming | Explore approaches, debate tradeoffs, produce a design doc with a Features table | | Design Review | /skill:pwk-design-review | Audit plan and design for production risks (security, scalability, fault tolerance) | | Plan | /skill:pwk-writing-plans | Plan one feature at a time from the Features table — bite-sized TDD tasks with acceptance criteria | | Execute | /skill:pwk-executing-tasks | Implement tasks one-by-one with TDD discipline and pre-commit checkpoint review gates | | Verify | /skill:pwk-verify | Three expert review passes (security, optimization, traceability) on implemented code | | Finalize | /skill:pwk-finalizing | Archive plan docs, update README/CHANGELOG, create PR | | Diagnose | /skill:pwk-diagnose | 6-phase debugging loop: reproduce → hypothesize → instrument → fix → verify |

The Workflow in Detail

Phase Control

You control each phase — the agent never advances on its own. Invoke a skill to move forward:

/skill:pwk-brainstorming → discuss and design (names features) /skill:pwk-writing-plans → plan next feature from the Features table /skill:pwk-design-review → audit for production risks (on demand) /skill:pwk-executing-tasks → implement with TDD /skill:pwk-verify → review code for security, optimization, and traceability /skill:pwk-finalizing → ship it

Feature-Based Planning

Design docs include a ## Features table that tracks each feature's status:

| # | Feature | Status | Notes | |---|---------|--------|-------| | 1 | User signup | ✅ done | | | 2 | Email verification | 🔄 planned | Plan: docs/plans/...-email-verification-implementation.md | | 3 | Password reset | ⬜ pending | |

This enables incremental development — plan and execute one feature at a time, then loop back for the next.

TDD Three-Scenario Model

Each task is labeled with its TDD scenario during planning:

| 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 |

Lessons Learned

A persistent rules file (docs/lessons.md) helps the agent learn from repeat mistakes across sessions. When the agent catches itself making the same error — like forgetting to run make lint — it writes a rule immediately. Future sessions (even after /new) pick it up automatically.

brainstorm → reads lessons (design context)
plan        → reads lessons (task breakdown)
execute     → reads lessons per task, writes new ones on repeat mistakes
finalize    → reviews and retires stale rules

Rules are simple imperative bullets:

• After completing each task, run make lint && make fmt before committing
• Never import testify in this project
• Always check for existing test helpers before writing new ones

No configuration needed — the file is created automatically when the first lesson is written.

Checkpoint Review Gates

Optionally label tasks with a checkpoint to pause for human review. At each checkpoint the agent stops and waits for your feedback — you can approve, ask for changes, or send it back to rethink. Only when you're satisfied does it move on to the next task.

| Checkpoint | When to Use | What Happens | |---|---|---| | (none) | Trivial tasks, well-understood changes | Auto-advance, no pause | | checkpoint: test | Test design matters | Agent writes the failing test, then pauses for your review. Verify the test covers the right cases before the agent implements. | | checkpoint: done | Implementation review matters | Agent implements and passes tests, then pauses for your review. Verify the implementation is correct before committing. |

Quick Start

# Install
pi install npm:@tianhai/pi-workflow-kit

# Start a new feature
> /skill:pwk-brainstorming
> I want to add OAuth2 login to our API

# (agent explores approaches, writes design doc with Features table)
# (write/edit are blocked — your code is safe)

> /skill:pwk-writing-plans

# (agent picks next feature, breaks into TDD tasks)
# (triggers design review for non-trivial features)
> /skill:pwk-executing-tasks

# (agent implements with TDD, cognitive persona shifts, all tools unlocked)
> /skill:pwk-verify

# (agent runs security, optimization, and traceability reviews on implemented code)
> /skill:pwk-finalizing

# (agent archives docs, curates lessons, creates PR)

Why?

• AI agents skip design. Left unchecked, they jump to code and over-engineer. This forces a think-first workflow.
• TDD needs structure. The three-scenario model gives the agent clear rules for when to write tests first.
• You stay in control. Checkpoint review gates let you approve test designs and implementations before the agent commits.
• Enforced, not suggested. Hard blocks mean the agent can't ignore the rules — not even accidentally.

Project

pi-workflow-kit/
├── extensions/
│   └── workflow-guard.ts      # Write blocker during brainstorm/plan/verify
├── skills/
│   ├── pwk-brainstorming/SKILL.md
│   ├── pwk-design-review/SKILL.md
│   ├── pwk-writing-plans/SKILL.md
│   ├── pwk-executing-tasks/SKILL.md
│   ├── pwk-verify/SKILL.md
│   ├── pwk-finalizing/SKILL.md
│   └── pwk-diagnose/SKILL.md
├── tests/
│   └── workflow-guard.test.ts
├── package.json
└── README.md

Development

npm test

License

MIT