Historical reference, superseded for new development: This document describes the legacy workflow extension and custom engine. New feature work uses the model-invoked develop-workflow skill under ADR 0006. Retain this document only as pilot history.

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

Start a feature

Start with:

/workflow start <message>

The command sends the message through the assistant, which chooses the descriptive feature name and idempotency key before invoking 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 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 pinned to the source checkout's current HEAD. Ordinary staged, unstaged, or untracked source changes are not copied into that worktree. In TUI mode the extension shows bounded path/status evidence and requires explicit confirmation before omitting those changes. Tool, RPC, print, and JSON callers must pass allowDirtySource: true. Unmerged paths remain blocked. 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. Approved host commands retain a three-minute timeout, internal Git commands have a 30-second timeout, and process-tree cleanup is bounded.
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.

Agent selection

workflow reuses explicitly mapped standard definitions from pi-interactive-subagents before falling back to its bundled workflow profiles. By default, scout owns Discovery and worker owns Implementation; bundled profiles continue to supply Design, Prototype, Verify, and independent Review. Definitions resolve with package, global, then trusted-project precedence and are pinned into the run with their workflow role overlay.

Configure or disable mappings in ~/.pi/agent/workflow.json or trusted .pi/workflow.json:

{
  "standardAgents": {
    "enabled": true,
    "roles": {
      "scout": ["discover"],
      "worker": ["implement"]
    }
  }
}

A mapping replaces the complete inherited role map at that configuration layer. Agent names must be lowercase kebab case and roles must be workflow roles. Unmapped standard definitions are ignored. Standard definitions provide identity, instructions, model, thinking level, and requested tools, but do not widen permissions: workflow stage allowlists still remove bash, recursive subagent tools, and any other unapproved tool.

Inspect and continue

Use /workflow for the drill-down dashboard. TUI mode opens shallow popup overlays for the run list, run actions, Gates, confirmations, questions, and feedback. Plans, reports, prototype evidence, and Assignment transcripts open in a sanitized full-screen reader. Escape returns one level. RPC, print, and JSON modes remain linear and never open custom overlays.

The dashboard lists runs attached to the current session and shows persisted status, core-stage progress, Gate, plan, report, branch, and worktree information. While work is active, one line above Pi's editor tracks only the newest attached run and clears when no attached run remains active. Human-facing surfaces use the feature name as the run label. Analysis and legacy runs fall back to a request label of at most 48 characters, then to the run ID when no request exists. Duplicate labels in one available-run list receive · <run-id-prefix>, using the shortest unique prefix of at least eight characters.

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. Choosing a pending fresh-session continuation in the dashboard immediately enters the existing newSession() handoff path; it does not require a second command. Tool and RPC callers receive the explicit /workflow continue <run-id> continuation instead. Labels are presentation-only and cannot be used as lookup aliases; copyable continue and stop commands always retain the full run ID. They require no schema migration and do not change persisted paths.

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 may adopt a continuable run when its recorded owner process is dead or absent. Adoption atomically rotates the lease and Implementation Context parent IDs. A live owner or live Assignment remains fail-closed, and historical sessions remain inspection-only unless such an adoption makes one active. 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/workflows/runs/<run-id>/

Important files include immutable plan revisions, Assignment transcripts, retained prototype reports and screenshots, result.json, and the terminal Markdown report. Report headings use the readable label and include the full canonical Run ID as explicit metadata. 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 workflow.