pi-multi-agent-skill 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Milan Glacier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# pi-multi-agent-skill
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A minimal, lightweight multi-agent skill and CLI for [pi](https://pi.dev). It
+needs no extension and adds no tools. Your agent starts other agents, runs
+them in parallel or in the background, and waits for, steers, stops or
+resumes them. Any harness or agent that has a shell can use it.
+
+It aims to be minimal while keeping subagents as useful as an extension and
+tool based approach. A subagent extension adds its tool definitions to every
+request, while this skill adds only a few dozen tokens of description to your
+agent's context until it decides to delegate.
+
+## Install
+
+Install the skill as a pi package from npm:
+
+```bash
+pi install npm:pi-multi-agent-skill
+```
+
+Or install directly from GitHub:
+
+```bash
+pi install git:github.com/milanglacier/pi-multi-agent-skill
+```
+
+You can also install the skill with the open skills CLI:
+
+```bash
+npx skills install milanglacier/pi-multi-agent-skill --global --agent pi
+```
+
+The CLI copies the skill to `~/.agents/skills/multi-agent`, which pi reads.
+You can also link it into pi's skills directory yourself:
+
+```bash
+ln -s "$PWD/skills/multi-agent" ~/.pi/agent/skills/multi-agent
+```
+
+Requirements: pi and Python 3.9 or later. Nothing else to install.
+
+Agents run `pi` by default. To run another build of pi, such as pi-bolt, set
+`PI_MULTI_AGENT_PI_BIN` in the environment that starts it. Your agent's shell
+inherits the variable, and so do the agents it starts:
+
+```bash
+alias pi-bolt='PI_MULTI_AGENT_PI_BIN=pi-bolt pi-bolt'
+```
+
+## Features
+
+- **Small token cost.** A subagent extension adds its tool definitions to
+  every request, whether or not your agent delegates anything. With this
+  skill, your agent's context holds only the skill's description, a few
+  dozen tokens, until it decides to delegate. Then it loads SKILL.md, which
+  is about 1.2K tokens and is all it needs for a fully working multi-agent
+  setup. The details of each command stay in separate references that it
+  reads only when needed.
+- **Everything a subagent tool does, without the tool.** Your agent gets the
+  same controls a dedicated extension would give it: start agents, wait for
+  them, `steer` one with a correction, `abort` it and keep what it has so
+  far, `resume` a finished job with a follow-up task, and see what each job
+  is doing. You can run the same commands yourself from a terminal.
+- **Foreground agents.** Run a quick question and wait for the answer. A
+  foreground agent is tied to the command that started it: press Esc, cancel
+  the tool call or close the session, and the agent and the commands it was
+  running stop with it, at every level of nesting.
+- **Parallel and background agents.** Start several jobs at once and collect
+  their results later. A background job is independent of your session: it
+  keeps running after the session that started it ends, until it finishes
+  or times out, and you can collect its result from a later session.
+- **Your full pi setup.** Each agent loads the same extensions, MCP servers,
+  skills and settings as an interactive pi, and uses your model unless its
+  profile picks another.
+- **Profiles.** They work as in other subagent tools: each one sets an
+  agent's system prompt, model, thinking level and tools.
+- **Fork your conversation.** `--fork` hands the agent everything you have
+  discussed so far, for tasks that need that context.
+- **Works outside pi.** Claude Code, Codex or any other agent with a shell
+  can run the same commands to delegate work to pi agents.
+
+## Non-goals
+
+These are deliberate non-goals, to keep the skill small and free of bloat.
+Each is better as a separate extension or skill that you pick to match your
+own workflow. This follows the minimalism of pi itself and the Unix
+philosophy: do one thing well and compose.
+
+- **Memory.** Agents do not share or keep memory between jobs. Use a memory
+  extension, or have agents write handoff notes.
+- **Scheduling.** There are no cron-style or recurring agents. Use cron,
+  `systemd` timers or a scheduler extension to run the commands.
+- **Worktrees.** Agents are not isolated in git worktrees. Just prompt the
+  agent to use a worktree.
+- **Dynamic workflows.** There is no scripting layer for orchestration such
+  as pipelines, parallel fan-out with gates, or phases. Your agent can
+  already start, wait for and chain jobs with plain commands. For
+  deterministic scripts, use an extension such as
+  [pi-dynamic-workflow](https://github.com/milanglacier/pi-dynamic-workflow).
+
+## Usage
+
+Your agent drives the skill on its own, but the commands also work by hand:
+
+```bash
+multi_agent.py run --profile Explore "Where is the retry policy defined?"
+multi_agent.py run --background --name review "Review the error handling in src/server/"
+multi_agent.py wait review --timeout 120
+multi_agent.py steer review "Skip generated files"
+multi_agent.py resume review "Now check the client side"
+multi_agent.py list
+```
+
+See [`skills/multi-agent/references/`](skills/multi-agent/references/) for
+every command and option, how jobs start and stop, the profile format, where
+state is kept and troubleshooting.
+
+## Profiles
+
+A profile is a Markdown file with frontmatter that sets an agent's system
+prompt, model, thinking level and tools. `--profile NAME` selects one;
+`multi_agent.py profiles` lists the available ones.
+
+```markdown
+---
+model: anthropic/claude-sonnet-5
+thinking: high
+tools: read, grep, find
+---
+You review code changes and report bugs.
+```
+
+Profiles are looked up in `<cwd>/.pi/agents/*.md`, then
+`$PI_CODING_AGENT_DIR/agents/*.md` (`~/.pi/agent/agents/` by default); when
+names collide, the local profile wins. Two profiles are built in:
+`general-purpose` (the default) and `Explore`, a read-only search agent.
+Supported fields are `name`, `description`, `model`, `thinking`, `tools`,
+`disallowed_tools`, `prompt_mode` and `enabled`. Fields do not merge across
+files, so a local profile replaces the profile it overrides as a whole and
+must supply the entire profile; `enabled: false` is the exception and hides
+the name on its own. Unknown fields are ignored, and nested YAML is not
+supported. See
+[`references/profiles.md`](skills/multi-agent/references/profiles.md) for the
+field details.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "pi-multi-agent-skill",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "A minimal multi-agent skill+cli for pi. It adds no extension or tools, so it uses only a few dozen tokens of the context window until the main agent delegates, yet it gives the same controls as a subagent extension. Background agents keep running after the session closes, and any later session can collect their results.",
+  "license": "MIT",
+  "author": "Milan Glacier",
+  "homepage": "https://github.com/milanglacier/pi-multi-agent-skill#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/milanglacier/pi-multi-agent-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/milanglacier/pi-multi-agent-skill/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "agent-skill",
+    "multi-agent"
+  ],
+  "files": [
+    "skills/multi-agent/SKILL.md",
+    "skills/multi-agent/profiles/*.md",
+    "skills/multi-agent/references/*.md",
+    "skills/multi-agent/scripts/*.py",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/skills/multi-agent/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: multi-agent
+description: Start other pi agents and delegate work to them. Use it when a task benefits from a multi-agent workflow, such as splitting work across agents, running it in parallel or in the background, or keeping a side task out of your own context.
+---
+
+# Multi-agent
+
+This skill starts other agents and manages each one as a named job. An agent
+does not see your conversation unless you start it with `--fork`, and you see
+only its final message.
+
+`SKILL_DIR` below is the directory that contains this SKILL.md. Every command
+has the form:
+
+```bash
+python3 "$SKILL_DIR/scripts/multi_agent.py" <command> ...
+```
+
+## Pick a profile
+
+A profile sets an agent's system prompt, model, thinking level and tools. Run
+this once per session to see the available profiles:
+
+```bash
+python3 "$SKILL_DIR/scripts/multi_agent.py" profiles
+```
+
+There are two built-in profiles. `general-purpose` (the default) has your
+tools and settings. `Explore` is a read-only search agent. Pass a profile
+with `--profile NAME`.
+
+## Run an agent
+
+For a short single task, run it in the foreground. The command blocks until
+the agent finishes and prints its result:
+
+```bash
+python3 "$SKILL_DIR/scripts/multi_agent.py" run --profile Explore "Where is the retry policy for HTTP calls defined?"
+```
+
+Pass a prompt longer than one line through `-` and a heredoc:
+
+```bash
+python3 "$SKILL_DIR/scripts/multi_agent.py" run --name auth-review - <<'EOF'
+Read src/auth/ and list every place that ...
+EOF
+```
+
+Write prompts that are self-contained: give the goal, the relevant paths and
+what the answer should contain. When the task builds on your conversation so
+far, add `--fork` instead: the agent starts from a copy of it.
+
+For a long task, or several tasks in parallel:
+
+- If your harness has a tool that runs a shell command in the background, run
+  the foreground `run` command with it. The job then stops when your session
+  ends. The command prints `multi-agent: started job NAME` first; use that
+  name for `steer` and `abort`. If the tool can wake you on each output line,
+  turn that off and wait for the command to exit. If the tool has its own
+  timeout, see "Timeouts" below.
+- Otherwise, or when the work must continue after your session ends, add
+  `--background`. The command prints the job name and returns at once. A
+  background job runs until it finishes or reaches its timeout (one hour by
+  default). Tell the user the job's name.
+- Never put the command in the background with `&`; use `--background`.
+
+Run only as many jobs at once as the task needs.
+
+## Timeouts
+
+- A foreground `run` or `resume` has no timeout unless you pass
+  `--timeout S`. It stops when the agent finishes or when the command ends,
+  for example when your tool call is cancelled or your session ends.
+- A `--background` job stops after one hour unless you pass `--timeout S`.
+  `--timeout 0` removes the limit.
+- When a background tool of your harness runs the foreground command and the
+  tool has its own timeout, pass a shorter `--timeout`, leaving a grace
+  period so the job stops the agent and records its result before the tool
+  kills it. If you disable the tool's timeout instead, the job runs until
+  the agent finishes or your session ends.
+
+## Wait for a result
+
+```bash
+python3 "$SKILL_DIR/scripts/multi_agent.py" wait NAME --timeout 120
+```
+
+Exit code 2 means the job is still running; run the same command again in a
+new tool call. Wait for one job per tool call and do not chain several `wait`
+commands in one call: a message that steers you arrives only after your
+current tool call returns.
+
+The output is the agent's final message followed by a `--- multi-agent ---`
+footer. The footer is for you. Report the agent's findings to the user in your
+own words.
+
+Exit code 0 means the job ended with status `done`; 1 means it ended another
+way (`failed`, `aborted`, `timeout`, `killed`, `died`), and the output says
+why.
+
+## Correct or continue a job
+
+```bash
+python3 "$SKILL_DIR/scripts/multi_agent.py" steer NAME "Skip the tests directory"
+python3 "$SKILL_DIR/scripts/multi_agent.py" abort NAME
+python3 "$SKILL_DIR/scripts/multi_agent.py" kill NAME
+python3 "$SKILL_DIR/scripts/multi_agent.py" resume NAME "Now check the callers too"
+```
+
+- `steer` adds a message that the agent reads before its next step.
+- `abort` stops the agent and keeps its last message as the result.
+- `kill` stops a job that does not respond to `abort`.
+- `resume` continues a finished job's conversation with a new prompt.
+
+`kill --all` stops every running job of the current project. Use it only when
+the user asks.
+
+## Inspect jobs
+
+```bash
+python3 "$SKILL_DIR/scripts/multi_agent.py" list
+python3 "$SKILL_DIR/scripts/multi_agent.py" status NAME
+python3 "$SKILL_DIR/scripts/multi_agent.py" peek NAME
+```
+
+`peek` shows the job's recent tool calls.
+
+## References
+
+The `references/` directory next to this file has the details. Read a file
+only when you need it:
+
+- `commands.md`: every command and option, output formats and exit codes.
+- `lifecycle.md`: statuses, how a run stops, foreground and background
+  lifetime, timeouts, dialogs and nesting.
+- `profiles.md`: writing a profile, where profiles are looked up, and how the
+  model, tools and system prompt are chosen.
+- `state.md`: where jobs and conversations are stored, and the agent's
+  environment.
+- `troubleshooting.md`: error messages and what to do about them.

package/skills/multi-agent/profiles/Explore.md

@@ -0,0 +1,34 @@
+---
+description: "Fast read-only search agent for locating code. Use it to find files by pattern (eg. \"src/components/**/*.tsx\"), grep for symbols or keywords (eg. \"API endpoints\"), or answer \"where is X defined / which files reference Y.\" Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis — it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: \"quick\" for a single targeted lookup, \"medium\" for moderate exploration, or \"very thorough\" to search across multiple locations and naming conventions."
+tools: read, bash, grep, find, ls
+prompt_mode: replace
+---
+
+# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools.
+
+You are STRICTLY PROHIBITED from:
+- Creating new files
+- Modifying existing files
+- Deleting files
+- Moving or copying files
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find, cat, head, tail.
+
+# Tool Usage
+- Use the find tool for file pattern matching (NOT the bash find command)
+- Use the grep tool for content search (NOT bash grep/rg command)
+- Use the read tool for reading files (NOT bash cat/head/tail)
+- Use Bash ONLY for read-only operations
+- Make independent tool calls in parallel for efficiency
+- Adapt search approach based on thoroughness level specified
+
+# Output
+- Use absolute file paths in all references
+- Report findings as regular messages
+- Do not use emojis
+- Be thorough and precise

package/skills/multi-agent/profiles/general-purpose.md

@@ -0,0 +1,3 @@
+---
+description: General-purpose agent for research, broad searches and multi-step tasks. It has the caller's tools and settings.
+---

package/skills/multi-agent/references/commands.md

@@ -0,0 +1,218 @@
+# Commands
+
+Every command runs as `python3 "$SKILL_DIR/scripts/multi_agent.py" <command>`.
+A PROMPT or MESSAGE of `-` is read from stdin, without its trailing newlines.
+An empty prompt or message is a usage error. `--help` prints a usage summary.
+
+| Command | What it does |
+|---|---|
+| `run [options] (PROMPT \| -)` | Start a new job. |
+| `resume NAME [--background] [--timeout S] (PROMPT \| -)` | Start a new run of a finished job, in the same conversation. |
+| `wait NAME [--timeout S]` | Block until the job is no longer running, then print its result. |
+| `result NAME` | Print the result of a job that is not running. |
+| `steer NAME (MESSAGE \| -)` | Give a running agent a message to read before its next step. |
+| `abort NAME` | Ask a running agent to stop, keeping its last message as the result. |
+| `kill NAME` / `kill --all` | Stop one job, or every running job of the current project. |
+| `status NAME` | Print the job's settings and state. |
+| `peek NAME [-n N]` | Print the last N lines (default 20) of the job's progress log. |
+| `list [--all]` | List the jobs of the current project. |
+| `profiles` | List the available profiles. |
+| `rm NAME` / `rm --all` | Delete one job that is not running, or every such job of the current project, with their conversations. |
+
+## Projects and job names
+
+A job belongs to the project of the directory where `run` was called. `run`,
+`list`, `kill --all` and `rm --all` work on the current directory's project only.
+
+The other commands look for NAME in the current project first. If the project
+has no job of that name, they search every project and use the job when
+exactly one project has it, so they also work from another directory. When
+several projects have a job of that name, the command fails and lists them;
+run it from the job's project.
+
+## run
+
+| Option | Meaning |
+|---|---|
+| `--profile P` | Profile name, matched case-insensitively. Default `general-purpose`. |
+| `--name N` | Job name. Default: the profile name in lowercase, `-`, and 4 hex digits, such as `explore-3f9a`. |
+| `--background` | Return as soon as the job has started. |
+| `--timeout S` | Wall-clock limit for the run in seconds. Default 3600 for a background run and no limit for a foreground run. `0` means no limit. |
+| `--fork` | Start the agent from a copy of the caller's conversation. |
+| `--model M` | Model pattern passed to `pi --model`. |
+| `--thinking L` | Thinking level passed to `pi --thinking`. |
+| `--cwd DIR` | Working directory for the agent, relative to the current directory. Default: the current directory. |
+
+A job name contains letters, digits, `.`, `_` and `-`, starts and ends with a
+letter or digit, and has at most 64 characters. `run` refuses a name that
+already exists in the project and reports its status and age. Pick another
+`--name`. Use `resume` or `rm` only for a job you started or the user asked
+about.
+
+`--cwd` changes where the agent works and where project profiles are looked
+up (`DIR/.pi/agents/`). The job still belongs to the current directory's
+project.
+
+`--fork` copies the conversation in `$PI_SESSION_FILE`, which pi sets for the
+commands it runs. It fails when that variable is unset or the file does not
+exist. Only the job's first run starts from the copy; later runs continue the
+job's own conversation.
+
+When `--model` and `--thinking` are omitted, the profile and then the caller's
+settings decide; see `profiles.md`.
+
+A foreground `run` writes `multi-agent: started job NAME` to stderr as soon as
+the job starts, then blocks and prints the result when the run ends. If the
+command receives SIGINT, SIGTERM or SIGHUP, the job stops with status `killed`
+and the command still prints the result. A second signal ends the command at
+once.
+
+A background `run` prints the following and exits with code 0. `timeout_s`
+is `none` when the run has no limit.
+
+```
+job: explore-3f9a
+status: running
+timeout_s: 3600
+```
+
+## resume
+
+`resume` starts a new run of a job that is not running. The agent continues
+the job's conversation, with the profile, model, thinking level, tools, system
+prompt and working directory that the job was created with. Editing the
+profile afterwards does not change an existing job.
+
+Only `--background` and `--timeout` can be given. They apply to the new run
+alone and have the same defaults as for `run`, so a resumed run does not
+inherit the previous run's timeout. Output is the same as for `run`.
+
+The job's status, result and duration always describe its latest run. If the
+job has no saved conversation, for example because pi failed during start-up,
+`resume` prints a note to stderr and the agent starts a new conversation.
+
+## wait and result
+
+`wait` blocks until the job is no longer running and prints its result.
+Without `--timeout` it waits as long as the job runs. When `--timeout`
+expires first, it prints the following and exits with code 2; the
+`last_progress` line is missing when the progress log is empty.
+
+```
+job: explore-3f9a
+status: running
+waited_s: 120
+last_progress: 14:02:11 grep retry policy
+```
+
+`result` prints the result of a job that is not running and fails with `job
+NAME is still running; use wait` otherwise.
+
+`run` in the foreground, `wait` and `result` print the result as the agent's
+final message followed by a footer:
+
+```
+<final assistant text>
+
+--- multi-agent ---
+name: explore-3f9a
+status: done
+profile: Explore
+model: anthropic/claude-sonnet-5
+duration_s: 84
+```
+
+The text is `(no output)` when the run produced none. For a `failed` run it
+ends with an `error:` line. `model` is the model that wrote the latest
+message, or the requested model when none did, or `(pi default)` when no
+model was requested. `duration_s` covers the latest run. `lifecycle.md`
+explains what the text holds for each status.
+
+## steer
+
+`steer` sends a message to the running agent, which reads it before its next
+step. It prints `job: NAME` and `steer: queued` once pi has accepted the
+message, and the message appears in the progress log. It fails with `job is
+not running; use resume` when the run has ended or is ending.
+
+## abort
+
+`abort` asks the agent to stop and prints `job: NAME` and `abort: requested`
+without waiting for it. Steering messages that the agent has not read yet are
+discarded. The run ends with status `aborted`; use `wait` to get the result.
+`abort` fails with `job is not running; use resume` when the run has ended or
+is ending.
+
+## kill
+
+`kill NAME` stops the run at once and returns after the job's runner has
+exited, which takes at most about 20 seconds. It prints the job name and the
+status the run ended with:
+
+```
+job: explore-3f9a
+status: killed
+```
+
+When the run had already ended, or was ending on its own, `kill` changes
+nothing, prints that status followed by `(not running)`, and exits with code
+0.
+
+`kill --all` stops every running job of the current project in parallel and
+prints one such block per job. For a job it could not stop, the block has an
+`error:` line instead of the status, and the command exits with code 1. With
+no running job it prints `no running jobs in this project`.
+
+## status
+
+`status` prints `key: value` lines: `name`, `status`, `mode` (`foreground` or
+`background`), `profile`, `model`, `parent`, `cwd`, `started_at`, `ended_at`,
+`runs`, `exit_code`, `output_file`, `session_file` and `session_cmd`. A `-`
+marks a missing value. Timestamps are UTC and describe the latest run.
+
+`session_cmd` opens the job's conversation in interactive pi. While the job
+runs, `status` adds a `note:` line as a reminder not to open it yet, because
+two processes would then write the same conversation file.
+
+## peek
+
+`peek` prints the last N lines of the job's progress log, which spans all of
+its runs. Each line starts with the local time. The log records each run's
+start and end, every tool call with a short excerpt of its main argument,
+retries, compactions, cancelled dialogs (`denied:`), steering messages, abort
+requests and timeouts. It does not hold the agent's text; read that with
+`wait` or `result`.
+
+## list
+
+`list` prints a table with the columns `NAME`, `STATUS`, `MODE`, `PARENT` and
+`AGE`, oldest first. It shows running jobs and jobs that ended in the last 24
+hours; `--all` shows every job of the project. `AGE` is the time since the
+run started for a running job and since it ended otherwise. `PARENT` is the
+job that started this one, or `-`.
+
+## profiles
+
+`profiles` lists each enabled profile with its description and source file.
+It looks up project profiles in the current directory.
+
+## rm
+
+`rm NAME` deletes a job that is not running: its state directory and its
+conversation file. It prints `removed: NAME` and fails with `job NAME is
+running; kill it first` while the job runs.
+
+`rm --all` deletes every job of the current project that is not running,
+with its conversation, and leaves running jobs alone.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | The job ended with status `done`, or the command succeeded. |
+| 1 | The job ended with another status, or the command failed. |
+| 2 | `wait` timed out and the job is still running. |
+| 64 | Usage error, such as an unknown option or a missing prompt. |
+
+The job's status decides the exit code of a foreground `run` or `resume`, of
+`wait` and of `result`. The other commands exit with 0 when they succeed.