plan-build

Plan/Build workflow mode for the pi coding agent.

• Say "plan" → pi produces an implementation plan and cannot touch anything (file writes and mutating commands are hard-blocked).
• Say "build" → pi executes changes.
• Say "ok, go" after reviewing a plan → pi starts implementing it.

Works in any project, with zero configuration — just install the package.

Features

• 🔒 Enforced plan mode — in plan mode, write/edit/rename tool calls and mutating bash commands (rm, mv, > redirects, npm install, php artisan make|migrate, git commit|push, composer require, …) are blocked. Read-only inspection (ls, grep, git status/diff, php artisan route:list, …) still works so plans can be researched.
• 🔁 Sticky mode — once in plan mode, follow-ups like "what about edge cases?" stay read-only until you say build.
• ✅ Approval detection — short approval messages after a plan (ok, go, ok, build, sounds good, proceed, …) flip to build mode automatically.
• 🎛️ /plan and /build commands — switch modes explicitly mid-conversation.
• 📊 Visible mode indicator — the TUI footer status shows PLAN MODE / BUILD MODE.
• 📝 Companion skill — teaches the agent a consistent plan format (goal, steps, files, tests, risks).

Installation

Recommended: npm (gallery-listed, no pinning needed)

pi install npm:plan-build

Per-project (.pi/settings.json, shareable with your team):

cd your-project
pi install npm:plan-build -l

Git (latest or pinned tag)

pi install git:github.com/pramudya3/plan-build          # latest
pi install git:github.com/pramudya3/plan-build@v1.0.1   # pinned

Manual clone (no settings write)

git clone https://github.com/pramudya3/plan-build
pi install /path/to/plan-build
# or try it for a single run without installing:
pi -e /path/to/plan-build

Pi auto-discovers extensions/ and skills/ from the pi manifest in package.json, so no further setup is needed.

Releases & versioning

Versions are kept in sync across channels: git tag v1.0.1 = npm 1.0.1. See RELEASING.md for the release workflow.

# Update to the latest version
pi update --extensions

# Pin the git channel to a specific tag
pi install git:github.com/pramudya3/plan-build@v1.0.1

# Move an existing pin to a new tag
pi install git:github.com/pramudya3/plan-build@v1.1.0

Available tags: git ls-remote --tags https://github.com/pramudya3/plan-build.git

Note: the pi.dev gallery indexes npm packages — the npm channel (plan-build) is the gallery-eligible one; the git channel offers pinned tags.

Usage

You say	What happens
plan: add login feature	PLAN mode: structured plan, no changes allowed
what about edge cases?	Stays in PLAN mode (read-only)
ok, go / ok, build / sounds good / build	BUILD mode: executes the plan
/plan	Manually switch to PLAN mode
/build	Manually switch to BUILD mode

The mode resets to BUILD on restart.

How it works

• before_agent_start detects the mode keyword in your prompt and injects mode instructions into the system prompt.
• tool_call blocks write/edit/rename and mutating bash commands while in plan mode.
• ctx.ui.setStatus shows the current mode in the TUI footer.

Security

The extension runs with full system permissions like any pi extension — review the source before installing: extensions/plan-build.ts.

License

MIT © Nanda Rizky