110 lines
7.4 KiB
Markdown
110 lines
7.4 KiB
Markdown
# workflow
|
|
|
|
`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 <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:
|
|
|
|
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. Approved host commands retain a three-minute timeout, internal Git commands have a 30-second timeout, and process-tree cleanup is bounded.
|
|
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.
|
|
|
|
## 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`:
|
|
|
|
```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:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
~/.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`.
|