add persisted pi workflow extension

2026-08-25 16:07:44 -04:00
parent bfb07282d6
commit c5c3316e49
46 changed files with 20642 additions and 94 deletions
@@ -0,0 +1,68 @@
+# 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`.