dotfiles/pi/extensions/subagent/README.md

pi subagent scaffold

Foundation for a global pi subagent extension with parallel and chained delegation.

What this includes

• index.ts — main subagent tool and /subagents command
• agents.ts — agent discovery and manifest parsing
• agents/ — starter bundled agents:
  • scout → zai/glm-5.1
  • planner → openai-codex/gpt-5.4:xhigh
  • implementer → openai-codex/gpt-5.3-codex
  • reviewer → openai-codex/gpt-5.4:xhigh
  • librarian → zai/glm-5.1 + exa_search / exa_code
• prompts/ — starter prompt templates:
  • /implement
  • /scout-and-plan
  • /implement-and-review
  • /parallel-scout
  • /research

Discovery model

This extension supports three agent sources:

• bundled — agents shipped in this directory (./agents)
• user — ~/.pi/agent/agents
• project — nearest .pi/agents from the current working directory upward

Scope values:

• global — bundled + user
• project — project only
• both — bundled + user + project

Precedence when names collide:

1. bundled
2. user
3. project

So project-local agents override user/global ones, and user/global agents override bundled defaults.

Parallel safety

Parallel mode is intentionally conservative.

• agents with parallelSafe: true can run in parallel
• agents with parallelSafe: false are blocked in parallel mode

The bundled implementer is marked serial-only.

Agent manifest format

Each agent is a markdown file with YAML frontmatter:

---
name: planner
description: Creates implementation plans
model: anthropic/claude-sonnet-4-5
tools: read, grep, find, ls
parallelSafe: true
role: planner
tags: planning, design
---

System prompt goes here.

Notes:

• model accepts normal pi --model values, including provider/id and optional :thinking
• the current scaffold intentionally uses built-in pi providers (openai-codex, zai), so no custom provider extension is required yet
• tools should usually be explicit to avoid recursive delegation
• parallelSafe defaults to false if omitted

Install globally from this repo

Recommended runtime target:

mkdir -p ~/.pi/agent/extensions
ln -sfn /Users/rasyidanakbar/Development/dotfiles/pi/extensions/subagent ~/.pi/agent/extensions/subagent

Then start pi and run:

/reload

Because prompts and bundled agents live inside the extension directory, a single directory symlink is enough.

Usage examples

Single agent:

Use subagent planner to propose a plan for refactoring auth

Parallel:

Use subagent with two tasks in parallel: scout auth flow, librarian find similar patterns

Chain:

Use subagent chain: scout -> planner -> implementer

Prompt templates:

/implement add request validation to the API
/scout-and-plan refactor auth to support oauth
/implement-and-review add pagination to the endpoint
/parallel-scout investigate session handling
/research evaluate the best pattern for background job retries in this codebase

Good next steps

1. add parallel_then_reduce
2. add budget / timeout controls
3. add a custom index_search tool for librarian workflows
4. wire the whole pi/extensions/ directory into Home Manager so ~/.pi/agent/extensions/ is managed automatically
5. pair librarian with the separate pi/extensions/exa-tools extension for web/docs/code retrieval