69 lines
3.0 KiB
Markdown
69 lines
3.0 KiB
Markdown
# 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:
|
|
|
|
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:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
~/.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`.
|