pi-subagents 0.17.3 → 0.17.4

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [0.17.4] - 2026-04-22
+
+### Added
+- Bundled a `pi-subagents` skill that teaches agents how to use builtin subagents, slash-command vs tool workflows, management-mode agent creation/editing, fork/intercom coordination, clarify mode, worktrees, async status inspection, and chain templating.
+
+### Changed
+- Tightened the builtin `oracle` prompt so intercom-enabled forked reviews now prefer concise conversational handoffs during the review and send a short final recommendation via `pi-intercom` before returning the full structured result.
+- Tightened `oracle-executor` so it explicitly frames itself as the single writer thread and escalates gaps in the approved direction instead of silently patching around them.
+
 ## [0.17.3] - 2026-04-22
 
 ### Added

package/agents/oracle-executor.md

@@ -12,6 +12,8 @@ defaultProgress: true
 
 You are `oracle-executor`: a high-context implementation subagent.
 
+You are the single writer thread. Your job is to execute approved direction, not to make new architectural or product decisions.
+
 You are invoked after the main agent has already decided on a direction, often based on advice from `oracle`. You are allowed to act, but you are not the owner of product or architecture decisions. The main agent remains the final decision authority.
 
 If runtime bridge instructions are present, use them as the source of truth for which orchestrator session to contact and how to coordinate. Use `intercom({ action: "ask", ... })` when a new decision is needed to continue safely. Use `intercom({ action: "send", ... })` for concise progress or completion handoffs when that extra coordination is helpful.
@@ -32,6 +34,7 @@ Working rules:
 - Do not add speculative scaffolding or future-proofing unless explicitly required.
 - Use `bash` for inspection, validation, and relevant tests.
 - Escalate uncertainty to the main agent with `intercom` when needed.
+- If the implementation reveals a gap in the approved direction, pause and escalate via `intercom` rather than silently patching around it with an implicit decision.
 - If implementation reveals an unapproved product or architecture choice, pause and ask via `intercom` instead of deciding it yourself.
 - If you send a completion handoff through `intercom`, keep it short and still return the full structured task result normally.
 - Keep `progress.md` accurate when asked to maintain it.

package/agents/oracle.md

@@ -17,7 +17,7 @@ Before you do anything else, reconstruct the key inherited decisions, constraint
 
 If you need clarification from the main agent, use `intercom`. If runtime bridge instructions are present, use them as the source of truth for which orchestrator session to contact and how to phrase coordination.
 
-Use `intercom({ action: "ask", ... })` when you need a real decision or clarification. Use `intercom({ action: "send", ... })` only for brief progress or handoff messages when that extra coordination is actually useful. Keep intercom traffic tight and purposeful. Do not narrate your whole review through intercom.
+Use `intercom({ action: "ask", ... })` when you need a real decision or clarification. Use `intercom({ action: "send", ... })` for concise conversational handoffs during the review and for a short final recommendation before you return your full result. Keep intercom traffic tight and purposeful. Do not narrate your whole review through intercom, but do treat `intercom` as the preferred path for back-and-forth with the orchestrator when bridge instructions are available.
 
 Core responsibilities:
 - reconstruct inherited decisions, constraints, and open questions from the context
@@ -26,6 +26,8 @@ Core responsibilities:
 - call out when a proposed move conflicts with an earlier decision or constraint
 - protect consistency over novelty; prefer the path that honors existing decisions unless the context clearly supports a pivot
 - when you do recommend a pivot, explain exactly which prior assumption or decision should be revised and why
+- exploit your clean forked context to spot things the main agent may have missed due to context rot, accumulated reasoning, or errors in the original instruction
+- look beyond the explicit question and suggest guidance based on the overall agent trajectory, even when not directly asked
 
 What you do not do by default:
 - do not edit files or write code
@@ -38,6 +40,8 @@ Working rules:
 - Use `bash` only for inspection, verification, or read-only analysis.
 - If information is missing and it matters, ask the main agent via `intercom` instead of guessing.
 - If the answer depends on a decision the main agent has not made yet, stop and ask via `intercom` before continuing.
+- When bridge instructions are present, send concise intercom messages when a recommendation, concern, or question would benefit from immediate discussion instead of waiting silently until the final return.
+- Before returning your full structured result, send a short intercom handoff summarizing the recommended next move when bridge instructions are present.
 - Prefer narrow, specific corrections to the current path over rewriting the whole plan.
 
 Your output should follow this shape. If no executor handoff is warranted, say so plainly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.17.3",
+  "version": "0.17.4",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -30,6 +30,7 @@
     "!*.test.ts",
     "*.mjs",
     "agents/",
+    "skills/**/*",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -44,6 +45,9 @@
     "extensions": [
       "./index.ts",
       "./notify.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "peerDependencies": {

package/skills/pi-subagents/SKILL.md

@@ -0,0 +1,426 @@
+---
+name: pi-subagents
+description: |
+  Delegate work to builtin or custom subagents with single-agent, chain,
+  parallel, async, forked-context, and intercom-coordinated workflows. Use
+  for advisory review, implementation handoffs, and multi-step tasks where a
+  single agent should stay in control while other agents contribute context,
+  planning, or execution.
+---
+
+# Pi Subagents
+
+Use this skill when you need to launch a specialized subagent, compose multiple
+agents into a workflow, or create/edit agents and chains on demand.
+
+## When to Use
+
+- **Advisory review**: fork to `oracle` or `reviewer` for a branched review thread
+- **Implementation handoff**: have `oracle` advise, then `oracle-executor` or `worker` implement
+- **Recon and planning**: use `scout` or `context-builder`, then `planner`
+- **Parallel exploration**: run multiple non-conflicting tasks concurrently
+- **Long-running work**: launch async/background runs and inspect them later
+- **Agent authoring**: create, update, or override agents and chains for a project
+
+## Tool vs Slash Commands
+
+Agents can use the `subagent(...)` and `subagent_status(...)` tools directly.
+Humans often use the slash-command layer instead:
+
+- `/run` — launch a single agent
+- `/chain` — launch a chain of steps
+- `/parallel` — launch top-level parallel tasks
+- `/agents` — open the agents manager TUI
+- `/subagents-status` — inspect active/recent async runs
+
+Prefer the tool when you are writing agent logic. Prefer the slash commands when
+you are guiding a human through an interactive flow.
+
+## Builtin Agents
+
+Builtin agents load at the lowest priority. Project agents override user agents,
+and user/project agents override builtins with the same name.
+
+| Agent | Purpose | Model | Typical output / role |
+|-------|---------|-------|------------------------|
+| `scout` | Fast codebase recon | `openai-codex/gpt-5.4-mini` | Writes `context.md` handoff material |
+| `planner` | Creates implementation plans | `openai-codex/gpt-5.4` | Writes `plan.md` |
+| `worker` | General implementation | `openai-codex/gpt-5.4` | Edits code directly |
+| `reviewer` | Review-and-fix specialist | `openai-codex/gpt-5.3-codex:high` | Can edit/fix reviewed code |
+| `context-builder` | Requirements/codebase handoff builder | `openai-codex/gpt-5.4` | Writes structured context files |
+| `researcher` | Web research brief generator | `openai-codex/gpt-5.4` | Writes `research.md` |
+| `delegate` | Lightweight generic delegate | inherits parent model | No fixed output; generic delegated work |
+| `oracle` | Decision-consistency advisory review | `openai-codex/gpt-5.4:high` | Advisory review, intercom coordination |
+| `oracle-executor` | Implementation after approval | `openai-codex/gpt-5.3-codex:high` | Single-writer implementation after approval |
+
+Override builtin defaults via settings before copying full agent files when a
+small tweak is enough.
+
+Settings locations:
+- User scope: `~/.pi/agent/settings.json`
+- Project scope: `.pi/settings.json`
+
+Useful override fields: `model`, `fallbackModels`, `thinking`,
+`systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `disabled`,
+`skills`, `tools`, and `systemPrompt`.
+
+## Discovery and Scope Rules
+
+Agent files can live in:
+- `~/.pi/agent/agents/*.md` — user scope
+- `.pi/agents/*.md` — canonical project scope
+- legacy `.agents/*.md` — still read for compatibility, but `.pi/agents/` wins on conflicts
+
+Chains live in:
+- `~/.pi/agent/agents/*.chain.md`
+- `.pi/agents/*.chain.md`
+- legacy `.agents/*.chain.md`
+
+Precedence is:
+1. project scope
+2. user scope
+3. builtin agents
+
+## Running Subagents
+
+### Single agent
+
+```typescript
+subagent({
+  agent: "oracle",
+  task: "Review my current direction and challenge assumptions."
+})
+```
+
+### Forked context
+
+```typescript
+subagent({
+  agent: "oracle",
+  task: "Review my current direction and challenge assumptions.",
+  context: "fork"
+})
+```
+
+`context: "fork"` creates a branched child session from the current persisted
+parent session. It does **not** create a fresh minimal review context or filter
+history down to only the relevant parts. Use it when you want a separate review
+or execution thread that can still reference the parent session history.
+
+### Parallel execution
+
+```typescript
+subagent({
+  tasks: [
+    { agent: "scout", task: "Explore the auth module" },
+    { agent: "reviewer", task: "Review the API client" }
+  ]
+})
+```
+
+### Chain execution
+
+```typescript
+subagent({
+  chain: [
+    { agent: "scout", task: "Map the auth flow and summarize key files" },
+    { agent: "planner", task: "Create an implementation plan from {previous}" },
+    { agent: "worker", task: "Implement the approved plan based on {previous}" }
+  ]
+})
+```
+
+Chain steps can use templated variables such as `{task}`, `{previous}`, and
+`{chain_dir}`. This is the main way to pass structured summaries between steps
+without forcing each step to rediscover everything.
+
+### Async/background
+
+```typescript
+subagent({
+  agent: "worker",
+  task: "Run the full test suite",
+  async: true
+})
+```
+
+Inspect async runs with the `subagent_status(...)` tool or the
+`/subagents-status` slash command.
+
+## Clarify TUI
+
+Single and parallel runs support a clarification TUI when you want to preview or
+edit parameters before launch:
+
+```typescript
+subagent({
+  agent: "worker",
+  task: "Implement feature X",
+  clarify: true
+})
+```
+
+Chains default to clarify mode unless you explicitly set `clarify: false`.
+For programmatic background launches, use `clarify: false, async: true`.
+
+## Worktree Isolation
+
+When multiple agents might write concurrently, use worktrees instead of letting
+them share one filesystem view.
+
+```typescript
+subagent({
+  tasks: [
+    { agent: "worker", task: "Implement feature A" },
+    { agent: "worker", task: "Implement feature B" }
+  ],
+  worktree: true
+})
+```
+
+`worktree: true` gives each parallel task its own git worktree branched from
+HEAD. This requires a clean git state and is mainly for intentionally parallel
+write workflows. If you want one writer thread and several advisory agents,
+prefer a single-writer pattern instead.
+
+## The Oracle Workflow
+
+The intended oracle loop is:
+1. the main agent forks to `oracle`
+2. `oracle` reviews direction, drift, assumptions, and risks
+3. `oracle` can coordinate back to the orchestrator via `intercom`
+4. the main agent decides what direction to approve
+5. only then should `oracle-executor` implement
+
+```typescript
+// Advisory review in a branched thread
+subagent({
+  agent: "oracle",
+  task: "Review my current direction, challenge assumptions, and propose the best next move.",
+  context: "fork"
+})
+
+// Implementation only after explicit approval
+subagent({
+  agent: "oracle-executor",
+  task: "Implement the approved approach: ...",
+  context: "fork"
+})
+```
+
+`oracle` is not a fresh-context reviewer in the Cognition article sense. It is
+a forked advisory thread that inherits the parent session history and uses that
+history as a baseline contract.
+
+## Subagent + Intercom Coordination
+
+When `pi-intercom` is installed and enabled, delegated runs can coordinate with
+the orchestrator through the intercom bridge.
+
+### Subagent asks the orchestrator
+
+```typescript
+intercom({
+  action: "ask",
+  to: "orchestrator",
+  message: "Should I optimize for readability or performance here?"
+})
+```
+
+### Orchestrator replies
+
+```typescript
+intercom({ action: "reply", message: "Optimize for readability." })
+```
+
+Or inspect unresolved asks first:
+
+```typescript
+intercom({ action: "pending" })
+```
+
+Use `intercom` when:
+- a subagent is blocked on a decision
+- an advisory agent wants to send a concise handoff mid-flight
+- a detached or async child needs to coordinate without waiting for normal tool return flow
+
+## Management Mode
+
+The `subagent(...)` tool also supports management actions.
+
+### List available agents and chains
+
+```typescript
+subagent({ action: "list" })
+```
+
+### Create an agent
+
+```typescript
+subagent({
+  action: "create",
+  config: {
+    name: "my-agent",
+    description: "Project-specific implementation helper",
+    systemPrompt: "Your system prompt here.",
+    systemPromptMode: "replace",
+    model: "openai-codex/gpt-5.4",
+    tools: "read,grep,find,ls,bash"
+  }
+})
+```
+
+### Update an agent
+
+```typescript
+subagent({
+  action: "update",
+  agent: "my-agent",
+  config: {
+    thinking: "high"
+  }
+})
+```
+
+### Delete an agent
+
+```typescript
+subagent({ action: "delete", agent: "my-agent" })
+```
+
+Use management actions when the system needs to create or edit subagents on
+demand without dropping into raw file editing.
+
+## Creating and Editing Agents by File
+
+A minimal agent file looks like this:
+
+```markdown
+---
+name: my-agent
+description: What this agent does
+model: openai-codex/gpt-5.4
+thinking: high
+tools: read, grep, find, ls, bash
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+---
+
+Your system prompt here.
+```
+
+That is only a starting point. Common optional fields include:
+- `defaultProgress`
+- `defaultReads`
+- `output`
+- `fallbackModels`
+- `maxSubagentDepth`
+
+For many customizations, builtin overrides in settings are lower-friction than
+copying a full builtin file.
+
+## Prompt Template Integration
+
+If `pi-prompt-template-model` is installed, prompt templates can delegate into
+`pi-subagents`. This is useful when a slash command should always run through a
+particular agent or with forked context.
+
+## Important Constraints
+
+- **Forking requires a persisted parent session.** If the current session does not
+  have a persisted session file, forked runs fail.
+- **Forked runs inherit parent history.** They are branched threads, not fresh
+  filtered contexts.
+- **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked
+  unless configured otherwise.
+- **Intercom asks are blocking.** A session can only maintain one pending outbound
+  ask wait state at a time.
+- **Keep conversational authority clear.** Advisory subagents should not silently
+  become second decision-makers.
+
+## Best Practices
+
+### Keep writes single-threaded by default
+
+A strong pattern is one main decision-maker plus advisory/research/review
+subagents around it. Use `oracle` for advice and `oracle-executor` or `worker`
+for the actual write path.
+
+### Use fork for branched advisory or execution threads
+
+Forked runs are useful when the child should reason in a separate thread while
+still inheriting the parent’s accumulated context.
+
+### Prefer narrow tasks
+
+Give subagents specific tasks rather than vague mandates.
+`Review auth.ts for null-check gaps` works better than `Review everything`.
+
+### Escalate decisions upward
+
+If a subagent encounters an unapproved product, architecture, or scope choice,
+it should coordinate back via `intercom` instead of deciding alone.
+
+### Name sessions meaningfully
+
+Use `/name` so intercom targeting stays stable.
+
+## Common Workflows
+
+### Recon → Plan → Implement
+
+```typescript
+subagent({
+  chain: [
+    { agent: "scout", task: "Map the auth flow and summarize relevant files" },
+    { agent: "planner", task: "Plan the migration from {previous}" },
+    { agent: "worker", task: "Implement the approved plan from {previous}" }
+  ]
+})
+```
+
+### Review loop
+
+```typescript
+subagent({ agent: "worker", task: "Add retry logic to the API client." })
+subagent({
+  agent: "reviewer",
+  task: "Review the retry logic implementation. Look for edge cases and race conditions.",
+  context: "fork"
+})
+```
+
+### Parallel non-conflicting analysis
+
+```typescript
+subagent({
+  tasks: [
+    { agent: "scout", task: "Audit frontend auth flow" },
+    { agent: "researcher", task: "Research current retry/backoff best practices" }
+  ]
+})
+```
+
+## Error Handling
+
+**"Unknown agent"**
+```typescript
+subagent({ action: "list" })
+// Check available agents and chains, then confirm scope/precedence.
+```
+
+**"Max subagent depth exceeded"**
+```typescript
+// Flatten the workflow or raise maxSubagentDepth in config.
+```
+
+**"Session manager did not return a session file"**
+```typescript
+// Persist the current session before using context: "fork".
+```
+
+**Intercom "Already waiting for a reply"**
+```typescript
+// Resolve the current outbound ask before starting another one.
+```