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

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

@@ -0,0 +1,79 @@
+# Profiles
+
+A profile sets an agent's system prompt, model, thinking level and tools. It
+is a Markdown file with frontmatter; the body after the frontmatter is the
+profile's prompt.
+
+```markdown
+---
+description: Reviews a diff for correctness bugs.
+model: anthropic/claude-sonnet-5
+thinking: high
+tools: read, grep, find, ls, bash
+---
+
+You review code changes. Report each bug with its file, line and a failing
+scenario.
+```
+
+## Where profiles come from
+
+Profiles are looked up in three directories, from highest to lowest priority:
+
+1. `<cwd>/.pi/agents/*.md` (project), where `<cwd>` is the agent's working
+   directory
+2. `$PI_CODING_AGENT_DIR/agents/*.md`, default `~/.pi/agent/agents/` (user)
+3. `profiles/*.md` in this skill's directory (built-in)
+
+Names are matched case-insensitively. When several directories define the
+same name, the file from the highest directory is used as a whole; fields are
+never merged across files. To change one field of a built-in profile, copy the
+whole file and edit the copy. A profile with `enabled: false` hides its name,
+including lower profiles of that name.
+
+A job keeps the settings it was created with. Editing a profile affects new
+jobs only, not `resume` of an existing one.
+
+## Fields
+
+| Field | Default | Effect |
+|---|---|---|
+| `name` | file name without `.md` | Profile name. |
+| `description` | `name` | Shown by `profiles`. |
+| `model` | the caller's model | Passed to `pi --model`. |
+| `thinking` | the caller's thinking level | Passed to `pi --thinking`. |
+| `tools` | pi's default tool selection | Passed to `pi --tools`. |
+| `disallowed_tools` | none | Passed to `pi --exclude-tools`. |
+| `prompt_mode` | `append` | `append` or `replace`; see below. |
+| `enabled` | `true` | `false` hides the profile. |
+
+Unknown fields are ignored. The parser reads `key: value` lines, quoted
+strings, `true`/`false` and `[a, b]` lists, and skips comments and indented
+lines; it does not support nested YAML.
+
+## Model and thinking level
+
+For each of the two, the first value found wins: the `run` option, the profile
+field, the caller's current setting, then pi's configured default. The
+caller's settings come from the `PI_PROVIDER`, `PI_MODEL` and
+`PI_REASONING_LEVEL` variables that pi sets for the commands it runs.
+
+## Tools
+
+`tools` and `disallowed_tools` accept a comma-separated list or `[a, b]`. The
+entries are passed to pi verbatim as `--tools` and `--exclude-tools`; see pi's
+documentation of those options for the patterns they accept and which tools
+they keep.
+
+## System prompt
+
+With `prompt_mode: append`, the profile's body is passed to pi with
+`--append-system-prompt`, so it is added to the system prompt pi builds as
+usual. With `prompt_mode: replace`, the body is passed with `--system-prompt`
+and pi also gets `--no-context-files`. Any other value makes `run` fail.
+
+Every agent also receives a short block that tells it its job name, that only
+its final message is read, and that no person can approve blocked tool calls.
+This block is passed with `--append-system-prompt` in both modes, so pi does
+not load `APPEND_SYSTEM.md` files for agents; put text that agents need in a
+profile's body.

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

@@ -0,0 +1,55 @@
+# State
+
+## Locations
+
+Job directories are in
+`$XDG_STATE_HOME/pi-multi-agent/<project>/jobs/<name>/` (default
+`~/.local/state`). `<project>` is the project's directory with every character
+other than a letter or digit replaced by `-` and the leading `-` removed, so
+`/home/me/app` becomes `home-me-app`.
+
+A running job's runner listens on a Unix socket in
+`$XDG_STATE_HOME/pi-multi-agent/sockets/`, which `steer`, `abort` and `kill`
+connect to. Conversations are pi session files in
+`$PI_CODING_AGENT_DIR/multi-agent-sessions/<project>/` (default
+`~/.pi/agent/`), so they stay out of pi's `/resume` list.
+
+## Job files
+
+| File | Content |
+|---|---|
+| `job.json` | Launch settings: profile, pi arguments, cwd, parent job, depth, run mode, timeout. |
+| `prompt.txt` | Prompt of the latest run. |
+| `system-prompt.md` | The profile's prompt, when it replaces pi's system prompt. |
+| `append-prompt.md` | Text added to pi's system prompt: the profile's prompt in append mode, then the multi-agent block. |
+| `status` | Status of the latest run; final once `exit_code` exists. |
+| `lock` | Held by the job's runner for as long as it runs. The job is running exactly while this lock is held. |
+| `started_at`, `ended_at` | UTC timestamps of the latest run. |
+| `runs` | Number of runs. |
+| `exit_code` | Exit code of the latest run, written last. A run without it that is no longer running has `died`. |
+| `output.txt` | Result text of the latest run; empty if that run produced none. |
+| `model` | Model that wrote the latest message. |
+| `stderr.txt` | pi's stderr for the latest run. |
+| `progress.log` | The lines `peek` prints, across runs. |
+| `usage.json` | Token and cost totals across runs. |
+| `runner.log` | Traceback when the runner itself fails. |
+
+Starting a run clears the previous run's result, end time and model, so these
+files always describe the latest run.
+
+## Reading a conversation
+
+To read a finished job's whole conversation in interactive pi, run the
+`session_cmd` that `status` prints. Do not open it while the job is running,
+because two processes would then write the same session file.
+
+## The agent's environment
+
+An agent inherits the environment of the command that started it, plus:
+
+| Variable | Value |
+|---|---|
+| `MULTI_AGENT_JOB` | The agent's job directory. |
+| `MULTI_AGENT_DEPTH` | The agent's nesting depth; see `lifecycle.md`. |
+| `PI_MINIMAL_PERMISSION_SYSTEM_NONINTERACTIVE` | `1`, so that extension never waits for an approval. |
+| `PWD` | The agent's working directory. |

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

@@ -0,0 +1,56 @@
+# Troubleshooting
+
+## Job status
+
+- **Status `failed` with `pi exited before the run finished`.** pi stopped
+  during start-up or the run. The output holds the end of pi's stderr; the
+  whole log is in the job's `stderr.txt`. A model or tool name that pi rejects
+  causes this.
+- **Status `failed` with `the runner failed`.** The script itself hit an
+  error. The traceback is in the job's `runner.log`.
+- **Status `died`.** The runner was killed without a chance to record a
+  result. The agent's pi process exits by itself, usually within a second,
+  but commands it started can survive; look for them with `ps` if the agent
+  was running a long command. `peek` shows how far it got; `resume`
+  continues the conversation. Wait a few seconds before you `resume` a job
+  that has just died, so its old pi has exited and does not write the
+  conversation at the same time as the new one.
+- **An agent reports that a tool call needs approval.** Agents cannot ask a
+  person. Run that step yourself, or tell the user what was blocked.
+- **A job lingers after its caller is gone.** Background jobs outlive their
+  caller by design. Stop them with `kill NAME`, or `kill --all` when the user
+  asks.
+
+## Command errors
+
+- **`job is not running; use resume`.** The run has ended or is ending.
+  `resume` the job with a new prompt instead of steering it.
+- **`job NAME already exists in this project`.** `run` needs a new name.
+  `resume` the job, pick another `--name`, or `rm` the old job first.
+- **`job NAME is running` from `resume` or `rm`.** The job's runner is
+  still alive, or another command was starting the job at the same moment.
+  `wait` for it, or `kill` it first.
+- **`unknown profile: P (available: ...)`.** No enabled profile has that name
+  in the agent's working directory; the message lists the ones that exist.
+- **`--fork needs PI_SESSION_FILE`.** The command does not run inside pi, so
+  there is no conversation to copy. Drop `--fork` and write a self-contained
+  prompt.
+- **`cannot start an agent: ... MULTI_AGENT_MAX_DEPTH`.** The caller is too
+  deep in a chain of agents. Do the work directly.
+- **`the runner of job NAME is not responding`.** The runner did not answer
+  `kill` within 10 seconds, or did not exit within 20 seconds after it
+  answered. The message ends with a `pkill` command that stops that runner;
+  run it, then wait a few seconds before you `resume` the job (see `died`).
+- **`the job's working directory no longer exists`.** `resume` runs the
+  agent in the directory the job was started in. Start a new job instead.
+- **`job NAME exists in several projects`.** Run the command from the
+  directory where the job was started.
+
+## Environment
+
+- **`flock does not work on ...`.** The state directory is on a file system
+  without working file locks, such as some NFS or SMB mounts. Set
+  `XDG_STATE_HOME` to a directory on a local file system.
+- **`the socket path for this job is too long`.** The socket path under
+  `XDG_STATE_HOME` exceeds the system's limit for Unix sockets (about 100
+  bytes). Set `XDG_STATE_HOME` to a shorter path.