# pi-workflow `pi-workflow` plans and implements feature work through persisted human Gates, isolated Git worktrees, focused verification, and independent review. ## Start a feature Start with: ```text /workflow start ``` 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/` in an exclusive worktree. Existing branch names are rejected rather than silently renamed. The managed flow is: 1. Discover repository facts and ask unresolved Questions. 2. Design the implementation and explicitly approve the plan and UI-impact classification. 3. For non-trivial UI, review three browser-validated candidates and accept one revision or request refinement. 4. Choose a fresh plan-seeded session, compacted current session, or unchanged current context. 5. Implement with guarded file ownership. 6. Remove prototype-only behavior. 7. Run plan-approved verification commands and focused tests. 8. 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: ```text /workflow continue /workflow resume ``` 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: ```text /workflow stop ``` 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. ## Artifacts Run state and bounded artifacts are stored under: ```text ~/.pi/agent/pi-workflows/runs// ``` 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`.