feat(pi-workflow): reuse standard agent profiles
This commit is contained in:
@@ -0,0 +1,3 @@
|
||||
# Reuse standard agents through workflow role overlays
|
||||
|
||||
`pi-workflow` will reuse standard `pi-interactive-subagents` definitions instead of duplicating their prompts and model settings in workflow-only agents. Explicit configuration maps standard agent names to workflow roles, while `pi-workflow` retains ownership, tool-intersection, Gate, verification, and reviewer-independence policy. The default maps `scout` to Discovery and `worker` to Implementation; bundled profiles remain fallbacks for roles without a standard mapping. This keeps one source of truth for agent identity without allowing arbitrary prompt prose or agent names to imply mutability or workflow authority.
|
||||
@@ -35,6 +35,26 @@ The managed flow is:
|
||||
|
||||
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
|
||||
|
||||
`pi-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/pi-workflow.json` or trusted `.pi/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.
|
||||
|
||||
+23
-11
@@ -11,8 +11,8 @@ The extension is based on `extensions/_workflows`, but it is a new extension rat
|
||||
|
||||
## Goals
|
||||
|
||||
- Load bundled Agent Profiles and trusted project overrides from `.pi/agents/*.md`.
|
||||
- Select agents automatically using deterministic eligibility followed by planner selection with recorded rationale.
|
||||
- Load bundled Workflow Agent Profiles plus configured standard subagent definitions from the active `pi-interactive-subagents` package, the global agent directory, and trusted project overrides.
|
||||
- Adapt standard definitions through explicit workflow role overlays, then select agents automatically using deterministic eligibility followed by planner selection with recorded rationale.
|
||||
- Pause after discovery for unresolved questions and after design for user approval.
|
||||
- Require at least three prototype candidates and explicit user acceptance for non-trivial UI or UX work.
|
||||
- Prevent an implementation agent from reviewing its own work.
|
||||
@@ -29,7 +29,7 @@ The extension is based on `extensions/_workflows`, but it is a new extension rat
|
||||
- Supporting arbitrary workflow graphs that can bypass required gates.
|
||||
- Automatically merging a completed worktree into its source branch.
|
||||
- Adding a general plugin framework for custom stages, policies, or persistence backends.
|
||||
- Supporting global Agent Profiles in the first version.
|
||||
- Inferring workflow roles or mutability from arbitrary standard-agent names or prompt prose.
|
||||
|
||||
## Language
|
||||
|
||||
@@ -170,10 +170,14 @@ After `start` creates the run lease, every subsequent state-changing parent oper
|
||||
|
||||
Profiles are loaded in this order:
|
||||
|
||||
1. Bundled profiles from `extensions/pi-workflow/agents/*.md`.
|
||||
2. Project profiles from the nearest `.pi/agents/*.md`, only when `ctx.isProjectTrusted()` is true.
|
||||
1. Bundled workflow profiles from `extensions/pi-workflow/agents/*.md`.
|
||||
2. Configured standard definitions from `${PI_CODING_AGENT_DIR:-~/.pi/agent}/extensions/pi-interactive-subagents/agents/`.
|
||||
3. Configured standard definitions from `${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents/`.
|
||||
4. Workflow profiles or configured standard definitions from the nearest `.pi/agents/*.md`, only when `ctx.isProjectTrusted()` is true.
|
||||
|
||||
Files are read in lexical order. The first duplicate within one source wins and emits a diagnostic. A project profile replaces a bundled profile with the same normalized name. Provenance and a content digest are retained. Regular files and symlinks are accepted only when their resolved paths remain inside the selected profile root.
|
||||
Standard definitions become Workflow Agent Profiles only when `standardAgents.roles` explicitly maps their name to one or more workflow roles. Their prompt, description, model, thinking level, and declared tools remain the standard definition's values; workflow policy supplies stages and still intersects tools with the audited stage allowlist. Unmapped standard definitions are ignored rather than assigned a role from their name or prose.
|
||||
|
||||
Files are read in lexical order. The first duplicate within one source wins and emits a diagnostic. Later trusted sources replace earlier definitions with the same normalized name. Provenance and a digest over both definition content and role overlay are retained. Regular files and symlinks are accepted only when their resolved paths remain inside the selected profile root. When a configured standard profile is eligible for a role, bundled profiles for that role become explicit fallbacks and are ineligible; bundled profiles continue to supply roles such as Design, Verify, and Review when no standard mapping exists.
|
||||
|
||||
Profile contents are pinned into the Workflow Run before selection. Editing a Markdown file does not change an active run.
|
||||
|
||||
@@ -263,6 +267,13 @@ Invocation values may change requested concurrency but never the safety ceiling.
|
||||
"maxAssignmentsPerRun": 128,
|
||||
"maxReviewCycles": 3,
|
||||
"analysisTools": ["read", "grep", "find", "ls"],
|
||||
"standardAgents": {
|
||||
"enabled": true,
|
||||
"roles": {
|
||||
"scout": ["discover"],
|
||||
"worker": ["implement"]
|
||||
}
|
||||
},
|
||||
"worktrees": {
|
||||
"root": ".worktrees"
|
||||
}
|
||||
@@ -495,7 +506,7 @@ Read-only analysis runs use the parent cwd and do not create worktrees. All chil
|
||||
Artifacts live under:
|
||||
|
||||
```text
|
||||
~/.pi/agent/pi-workflows/<run-id>/
|
||||
~/.pi/agent/pi-workflows/runs/<run-id>/
|
||||
```
|
||||
|
||||
Files include:
|
||||
@@ -543,7 +554,7 @@ The effective model is resolved in this order:
|
||||
|
||||
Unknown or ambiguous models fail the Assignment before execution. The effective provider, model, effort, profile digest, child session ID, and context capacity are persisted.
|
||||
|
||||
Children cannot access recursive workflow or subagent tools or `ask_user`. `pi_workflow` is added to both the shared child-tool exclusion policy and the separate Pi-subagent child exclusion list alongside the legacy `workflow` name; implementation should consolidate the duplicate list onto the shared policy when possible. Each child tool call retains the shared timeout guard, including tools registered after startup. The first-response watchdog and bounded shutdown behavior from `_workflows` are retained.
|
||||
Children cannot access recursive workflow or subagent tools or `ask_user`. Standard definitions are execution identities, not permission grants: `worker` may declare `bash` and nested subagents, but mutating workflow Assignments still receive only audited reads plus guarded `edit`/`write`, and read-only Assignments receive only audited reads. `pi_workflow` is added to both the shared child-tool exclusion policy and the separate Pi-subagent child exclusion list alongside the legacy `workflow` name; implementation should consolidate the duplicate list onto the shared policy when possible. Each child tool call retains the shared timeout guard, including tools registered after startup. The first-response watchdog and bounded shutdown behavior from `_workflows` are retained.
|
||||
|
||||
## Internal Modules
|
||||
|
||||
@@ -581,8 +592,9 @@ Implement the Workflow Run model, configuration resolution, Markdown profile loa
|
||||
|
||||
#### Phase 1 Success Criteria
|
||||
|
||||
- Trusted project profiles override bundled profiles deterministically, while untrusted project profiles are never read.
|
||||
- Profile files and symlinks resolving outside the selected bundled or trusted `.pi/agents` root are rejected.
|
||||
- Configured standard package/global/trusted-project definitions override bundled fallbacks deterministically, while untrusted project profiles are never read.
|
||||
- Standard definitions require explicit role overlays, preserve their model/prompt/tool identity, and cannot grant tools beyond the workflow stage allowlist.
|
||||
- Profile files and symlinks resolving outside the selected bundled or trusted agent roots are rejected.
|
||||
- Malformed profiles produce isolated diagnostics and cannot suppress valid profiles.
|
||||
- Profile contents, provenance, and effective model settings are pinned by digest.
|
||||
- Every profile has stage Eligibility Criteria, pre-discovery fallback is deterministic, and irrelevant profiles are excluded with recorded reasons.
|
||||
@@ -671,7 +683,7 @@ Add the dashboard integration around the Phase 4 `/workflow continue` command, p
|
||||
|
||||
## Verification Notes
|
||||
|
||||
- Test profile trust, precedence, malformed YAML isolation, and containment of regular files and symlinks.
|
||||
- Test workflow and standard-profile trust, package/global/project precedence, explicit role overlays, malformed YAML isolation, unmapped-definition omission, and containment of regular files and symlinks.
|
||||
- Test the exhaustive legal and illegal Stage/Gate transition matrix through the engine interface.
|
||||
- Test stale revision, duplicate idempotency, lease reconciliation, and notification outbox handling.
|
||||
- Test process-wide semaphore reservation races, queued cancellation, bounded session shutdown, and interrupted recovery.
|
||||
|
||||
Reference in New Issue
Block a user