pi-workflow

pi-workflow plans and implements feature work through persisted human Gates, isolated Git worktrees, focused verification, and independent review.

Start a feature

Ask the assistant to use pi_workflow with:

action: "start"
workflow: { mode: "feature" } (or omit workflow)
A descriptive lowercase kebab-case featureName
The feature request
A unique idempotency key

The extension creates feature/<feature-name> in an exclusive worktree. Existing branch names are rejected rather than silently renamed.

The managed flow is:

Discover repository facts and ask unresolved Questions.
Design the implementation and explicitly approve the plan and UI-impact classification.
For non-trivial UI, review three browser-validated candidates and accept one revision or request refinement.
Choose a fresh plan-seeded session, compacted current session, or unchanged current context.
Implement with guarded file ownership.
Remove prototype-only behavior.
Run plan-approved verification commands and focused tests.
Complete independent specification and standards review.

The assistant must inspect the current run before each state-changing call and obtain the user's explicit Gate Decision. It must not infer approval.

Inspect and continue

Use /workflow for the focused-card dashboard. It lists runs attached to the current session and shows persisted status, progress, Gate, plan, report, branch, and worktree information.

Use:

/workflow continue <run-id>

only when the dashboard or pi_workflow reports a pending fresh-session handoff or normal-compaction continuation.

Script modes

A feature run may include one restricted read-only script at a closed insertion point:

before-design
after-design
before-review

An analysis run uses action: "start" with workflow: { mode: "analysis-script", source, args? } and does not create a worktree or feature Gates. Scripts expose only stage, assign, parallel, and immutable args. Their Assignment tools are the intersection of the configured analysis allowlist, the selected Markdown profile, and active parent tools.

Recovery

Interrupted work opens a Recovery Gate with retry, inspect, and abort choices. Completed Assignments and Decisions remain persisted. Potentially mutating interrupted Assignments are preserved and are not replayed automatically; an explicit retry creates newly fenced work where policy permits it.

Artifacts

Run state and bounded artifacts are stored under:

~/.pi/agent/pi-workflows/runs/<run-id>/

Important files include immutable plan revisions, Assignment transcripts, retained prototype reports and screenshots, result.json, and the terminal Markdown report. Completed worktrees remain available for manual inspection and integration.

Reload after exposure

Repository-managed extension links are controlled through config/pi-links.json. Run /reload after the managed link is synchronized so Pi discovers pi-workflow.

3.0 KiB Raw Blame History