The command sends the message through the assistant, which chooses the descriptive feature name and idempotency key before invoking pi_workflow through the normal tool path. In interactive TUI mode, /workflow start without a message asks what you want to start working on. Non-interactive modes require the message in the command.

You can also 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. Each host command is terminated after three minutes so an interactive or stalled command cannot block the run indefinitely.
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 to select a run with a pending fresh-session handoff or normal-compaction continuation. /workflow resume is an alias. A run ID may be supplied directly:

/workflow continue <run-id>
/workflow resume <run-id>

Selection requires interactive TUI mode. In non-interactive modes, provide the run ID.

Stop active work

Use /workflow stop to abort an active (running or waiting) Workflow Run owned by the current parent session. If more than one is active, interactive TUI mode presents a selection list. A run can also be named directly, including in non-interactive modes:

/workflow stop <run-id>

Terminal runs and runs owned by historical parent sessions are not offered. The misspelled /worlflow alias is not supported.

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. Startup recovery leaves an idle run already waiting at Recovery under its current parent instead of letting another Pi session claim it. If that parent's process has exited, an explicit retry from a previously attached parent session may reclaim the stale lease before continuing. Retry clears prior failed-command output and reruns verification from a pending state. Once remediation completes the Implement stage, an older interrupted mutating Assignment no longer triggers duplicate remediation on later retries.

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.