claude-workflow

A workflow layer for Pi that reproduces the useful mechanics of a Claude-Code-style coding agent — read-only planning, isolated exploration, independent verification, and a command safety gate — without modifying Pi core. It ships entirely as a Pi extension package: a prompt overlay, four commands, one delegation tool, three built-in subagents, and a tool_call safety gate, all wired through Pi's public extension APIs.

This package implements the behavior pattern of those workflows. It does not copy Claude Code source or prompt text.

The safety gate is a workflow safeguard, not a sandbox. It reduces the chance of an agent-initiated command doing damage, but it does not isolate the process. It is not a substitute for OS- or container-level isolation, and it makes no security guarantee. See Known limitations.

Requirements

• Pi (@earendil-works/pi-coding-agent) 0.80.x. The extension API contract was verified against pi commit 6d3cc89fdf8854417f1099da003a80ea848907b7 / CLI 0.80.3.
• Node.js >= 22.19.0.
• A configured model provider with a working API key. The commands that spawn subagents (/cw:explore, /cw:verify, /cw:workflow, and the cw_subagent tool) each launch a child pi process that needs a provider; without a key they return a clear configuration error.

Installation

Pi discovers a package by reading the pi manifest field from its package.json. This package declares:

"pi": {
  "extensions": ["./extensions/claude-workflow/index.ts"],
  "prompts": ["./prompts"]
}

So however you make Pi aware of the package, it loads the extension entry point and the prompt templates from that manifest. There are three ways to do that.

1. As an installed package (npm or git)

Install the package and Pi records it in your settings and loads it on every run:

# from npm (once published)
pi install npm:claude-workflow

# or straight from a git remote
pi install git:github.com/<owner>/claude-workflow

# project-local instead of user-global: add -l
pi install npm:claude-workflow -l

Pi installs the package, reads its pi manifest, and registers the extension and prompts. Remove it later with pi remove npm:claude-workflow (alias pi uninstall).

2. From a clone, loaded directly with -e

Good for development and for trying the package without adding it to your settings. Clone the repo, install dev dependencies, then point Pi at the extension entry file:

git clone <repo-url> claude-workflow
cd claude-workflow
npm install
pi -e ./extensions/claude-workflow/index.ts

-e/--extension loads a single extension for that session only; it is not persisted to settings. (Loading the entry file this way registers the extension and its bundled agents/ and prompts/, which it resolves relative to its own location.)

3. Symlinked into the agent extensions directory

Pi auto-discovers extensions placed under its agent config directory. Symlink the package (or just the extension directory) into ~/.pi/agent/extensions/ and Pi will load it on startup:

ln -s "$(pwd)/extensions/claude-workflow" ~/.pi/agent/extensions/claude-workflow

On any of these paths, confirm the extension loaded by checking that the /cw:plan, /cw:explore, /cw:verify, and /cw:workflow commands appear in Pi's command list.

Commands

/cw:plan — read-only plan mode

Toggles a read-only planning mode. On entry it snapshots your active tools, disables edit/write, restricts bash to read-only commands (the safety gate switches to a stricter policy), and injects planning instructions asking the model to investigate the code and produce a single numbered plan. It watches for the plan across turns: a clarifying-question turn keeps planning silently; a turn that contains a numbered plan offers an execute / refine / stay menu (in UI modes).

Subcommands:

| Invocation | Effect | | --- | --- | | /cw:plan | Toggle plan mode on/off. While a plan is executing, shows progress instead of toggling. | | /cw:plan execute | Execute the most recently detected plan (restores tools, leaves plan mode, enqueues the implementation prompt). Useful in non-UI modes where the menu is unavailable. | | /cw:plan end | Stop execution tracking. Steps never marked [DONE:n] are recorded as unknown. | | /cw:plan status | Show the current plan-mode state and per-step progress. | | /cw:plan help | Show the built-in help, including the tool-snapshot caveat. |

Refine is offered as an option in the interactive plan menu (it asks for an optional change note and requests a revised plan while staying in plan mode); it is a menu action rather than a /cw:plan subcommand.

Once you choose to execute, the enqueued implementation prompt asks the main agent to emit [DONE:n] on its own line after finishing plan step n; the extension parses those markers to track progress. Missing or malformed markers simply degrade the affected step to unknown — they never break tracking.

Plan state is persisted and restored on session resume/fork, so a resumed session comes back with write tools still disabled until you exit plan mode.

/cw:explore <task>

Runs an isolated, read-only explore subagent in a child pi process to do fast codebase reconnaissance for <task>. It shows you a concise report and injects that report into the conversation as a hidden context message, so the main model can use the findings on later turns without you pasting anything. The child is read-only (read/grep/find/ls plus read-only bash); the command itself does not trigger a main-model turn.

/cw:verify [scope]

Runs an isolated, read-only verifier subagent over the given scope (default: your current uncommitted changes). The verifier gathers command evidence under a read-only write policy and returns a verdict:

• PASS — the read-only checks it could run (e.g. tsc --noEmit, eslint without --fix, git diff/status/log) are sufficient evidence that the work holds.
• FAIL — a check demonstrated a concrete defect, cited with the failing command and output.
• PARTIAL — a meaningful check was blocked by the write policy or missing tooling; the blocked/missing checks are listed so you can run them yourself.

PARTIAL is the expected, normal outcome in this MVP. The verifier may not write into your project tree, so writing checks (npm test, builds, installs, snapshot updates) are blocked in-tree and reported as blocked. /cw:verify help prints this in full. Scratch scripts, when needed, are confined to the OS temp directory.

/cw:workflow <task>

Runs the MVP chain explore → planner in child processes: an exploration agent surveys the code, a planning agent turns the findings into an ordered implementation plan. In UI modes it then enqueues an implementation prompt containing that plan as a follow-up for the main agent — child processes never edit files in the MVP, so implementation happens in your main session, and you verify afterwards with /cw:verify. In modes without follow-up delivery it displays the plan and leaves continuation to you.

cw_subagent tool

A tool (not a command) the main agent calls to delegate work to the same isolated read-only child agents. Three modes, exactly one per call:

• single — { agent, task }: one agent, one task.
• parallel — { tasks: [{ agent, task }, ...] }: independent tasks run concurrently (concurrency capped at 4).
• chain — { chain: [{ agent, task }, ...] }: sequential steps where each task may reference the previous step's output via the {previous} placeholder (or has it appended automatically if the placeholder is absent).

Child agents cannot modify files or delegate further (maximum delegation depth is 1), and they return a text report. Available agents are the built-ins below.

Built-in agents

Agent definitions are Markdown files with YAML frontmatter, shipped in agents/ and resolved relative to this package (user/project agent discovery is out of scope for the MVP).

| Agent | Role | Tools | | --- | --- | --- | | explore | Fast read-only reconnaissance; reports files, symbols, findings. | read, grep, find, ls, read-only bash | | planner | Turns a task + findings into an ordered plan with risks and a critical-files list. | read, grep, find, ls (no bash, by design) | | verifier | Independently verifies work by running read-only checks; reports evidence and a PASS/FAIL/PARTIAL verdict. | read, grep, find, ls, read-only bash | | worker | Full-capability implementation agent. Shipped disabled — the MVP never lets a child process edit files. | (disabled) |

Safety gate

The extension installs a tool_call handler that classifies agent-initiated bash, edit, and write calls into three tiers:

• allow — passes through.
• confirm — prompts in UI modes; fails closed in non-UI modes (blocked with a reason rather than silently allowed or hung waiting).
• block — denied outright, with a message telling you that you can run the command yourself in your own shell if you really intend to.

It covers recursive/broad deletion, discarding uncommitted work or rewriting git state, external publication (push, PR/issue activity), writes to protected files (.env, credential files, .git/, node_modules/, lockfiles), and package installs. Plan mode applies a stricter policy (redirections, heredocs, file creation, package installs, git writes, and process kills are blocked). Child agents run under a role-specific policy: verifier children may write scratch scripts only in the OS temp directory; explore/planner/unknown roles are strictly read-only.

Known limitations

• PARTIAL is the normal /cw:verify verdict. Because writing checks (tests, builds, installs) are blocked in the project tree, the read-only verifier usually cannot produce a PASS. A PARTIAL that lists its blocked checks is honest, not a failure. PASS is reserved for cases where the allowlisted read-only checks are themselves sufficient evidence.
• Tool changes during plan mode are overwritten on exit. Plan mode snapshots your active tools on entry and restores that exact snapshot on exit. Any tool set changes you make while plan mode is active are lost when you leave it. (On session resume the snapshot is intersected with the currently registered tools, so names that no longer exist are dropped.)
• The safety gate is a workflow safeguard, not a sandbox. It constrains agent-initiated tool calls only; it does not isolate the process, does not cover everything, and makes no security guarantee. Treat it as guardrails, not containment.
• Non-UI modes fail closed. In print/JSON (non-interactive) modes there is nobody to answer a confirmation prompt, so any confirm-tier action is blocked rather than executed. Some interactive affordances (the plan action menu) also degrade to a plain notice.
• A provider API key is required for subagents. /cw:explore, /cw:verify, /cw:workflow, and cw_subagent all spawn child pi processes; without a configured model/API key they return a clear configuration error.

Development

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest

Pure logic (safety classification, plan-step and [DONE:n] parsing, state restore, verdict parsing) is covered by unit tests. Manual smoke tests use the fixtures/demo-project/ fixture — see examples/demo.md for a walkthrough of the four commands, and docs/phase5-regression.md for the end-to-end regression checklist. See docs/spec.md for the full specification and docs/plan.md for the phased plan.