@rohaquinlop/pi-subagents 0.3.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @rohaquinlop/pi-subagents
 
-A [pi](https://github.com/earendil-works/pi) extension that registers a single `subagent` tool with three agents:
+A [pi](https://github.com/earendil-works/pi) extension that registers three agent orchestration tools — `subagent`, `pipeline`, and `loop` — with three built-in agents:
 
 ## Installation
 
@@ -22,6 +22,8 @@ pi install @rohaquinlop/pi-subagents
 
 ## Usage
 
+### Subagent — Single Agent Dispatch
+
 One tool call = one subagent:
 ```json
 { "agent": "scout", "task": "Find all auth-related files in src/" }
@@ -31,6 +33,49 @@ To fan out, emit multiple `subagent` tool calls in the same assistant turn — p
 
 Each subagent runs as an isolated `pi` process with no inherited context — all context must be in the task description.
 
+### Pipeline — Sequential Agent Chains
+
+Chain 2–5 agents in sequence where each agent's output feeds as context into the next. Use `{previous}` in a step's task to inject the prior step's output.
+
+```json
+{ "tool": "pipeline", "args": { "steps": [
+  { "agent": "scout", "task": "Find all auth-related code in src/" },
+  { "agent": "worker", "task": "Based on these findings:\n{previous}\n\nImplement password reset flow." }
+]}}
+```
+
+Each step runs a separate subagent process. The pipeline stops on the first error. Per-step and total usage (tokens, cost, duration) are shown in the TUI.
+
+### Loop — Iterative Refinement
+
+Run the same agent 2–5 times, passing all prior iteration outputs as context. Optionally use a `judge` agent to stop early when quality is sufficient.
+
+**Basic (fixed iterations):**
+
+```json
+{ "tool": "loop", "args": {
+  "agent": "worker",
+  "task": "Write a comprehensive README for this project.",
+  "max_iterations": 3
+}}
+```
+
+**With judge for dynamic stopping:**
+
+```json
+{ "tool": "loop", "args": {
+  "agent": "worker",
+  "task": "Write a comprehensive README for this project.",
+  "max_iterations": 5,
+  "judge": {
+    "agent": "reviewer",
+    "criteria": "Is this README complete, well-structured, and ready for publication? Answer YES or NO."
+  }
+}}
+```
+
+The judge evaluates each iteration's output. When satisfied (YES), the loop stops early — no wasted iterations. Judge feedback is passed back to the runner agent for refinement.
+
 ## Config
 
 Optional `config.json` next to `index.ts`:
@@ -81,6 +126,14 @@ Frontmatter fields:
 
 The markdown body becomes the agent's system prompt.
 
+Agents can optionally declare a `connector` field in their frontmatter — a prompt template that wraps their output before it's passed as `{previous}` to the next agent in a pipeline:
+
+```yaml
+connector: "## Key findings from codebase exploration:\n\n{output}"
+```
+
+Connectors use single-line format with `\n` for line breaks. They can be overridden per-step via the optional `connector` field on pipeline steps.
+
 ### 2. Register agents via `globalThis.__pi_subagents`
 
 Pi loads extensions via jiti, which creates separate module instances. Direct imports from the subagents extension will reference a different `agents` array than the one the `subagent` tool uses. Use the `globalThis` bridge instead:
@@ -190,3 +243,7 @@ Matching is case-insensitive.
 └── tools/             # Extensions loaded into subagent processes
     └── safe-bash.ts   # bash with dangerous command blocking
 ```
+
+## Acknowledgements
+
+The pipeline and loop tools are conceptually inspired by [RecursiveMAS](https://arxiv.org/abs/2604.25917) — a research framework for scaling agent collaboration through iterative refinement and system-level orchestration.

package/agents/researcher.md

@@ -4,6 +4,7 @@ description: Web researcher — searches the web and synthesizes findings
 tools: web_search, web_fetch
 model: deepseek-v4-flash
 thinking: medium
+connector: "## Research findings:\n\n{output}"
 ---
 
 You are a research specialist. Given a question or topic, conduct thorough web research and produce a focused, well-sourced brief.

package/agents/scout.md

@@ -4,6 +4,7 @@ description: Fast codebase recon — explores files, finds patterns, maps archit
 tools: read, grep, find, ls
 model: deepseek-v4-flash
 thinking: medium
+connector: "## Key findings from codebase exploration:\n\n{output}"
 ---
 
 You are a scout agent. Quickly investigate a codebase and return structured findings.

package/agents/worker.md

@@ -5,6 +5,7 @@ tools: read, write, edit, safe_bash, web_search, web_fetch, subagent
 subagent_agents: scout, researcher
 model: deepseek-v4-flash
 thinking: medium
+connector: "## Implementation results:\n\n{output}"
 ---
 
 You are a worker agent. You operate in an isolated context — you have no knowledge of any prior conversation.
@@ -15,6 +16,7 @@ Guidelines:
 - Read files before editing to understand existing code
 - Make targeted edits, not wholesale rewrites
 - Use safe_bash for running commands (tests, builds, installs, etc.)
+- `safe_bash` has a 5-minute default timeout (300s). For long-running commands (builds, tests, installs), pass a larger `timeout`, e.g. `timeout: 600` for 10 minutes.
 - If something fails, diagnose and fix it
 - Report what you did and what changed when done