# Pi Dispatch

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-jakubgajski-pi-dispatch-skill-pi-dispatch`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jakubgajski](https://agentstack.voostack.com/s/jakubgajski)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jakubgajski](https://github.com/jakubgajski)
- **Source:** https://github.com/jakubgajski/pi-dispatch-skill/tree/master/pi_dispatch

## Install

```sh
agentstack add skill-jakubgajski-pi-dispatch-skill-pi-dispatch
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Pi-Dispatch Skill

Describes how to delegate coding plans to orchestrated teams of pi agents. Claude's role: write JSON → run script → read JSON.

**Path convention:** `{{SKILL_DIR}}` = the directory containing this SKILL.md. Resolve it from the file path you used to read this skill. All paths below are relative to `{{SKILL_DIR}}`.

## When to Use

Use `pi-dispatch` for any pi agent work. Use the native `Agent` tool for Claude subagents (sonnet/opus/haiku).

## Config

`{{SKILL_DIR}}/config.json` — edit `pi_models` to swap models, `default_timeout_minutes` for global default.

```json
{
  "provider": "openrouter",
  "default_timeout_minutes": 5,
  "task_routing": {
    "hard": { "pi_tier": "hard" },
    "moderate": { "pi_tier": "hard" },
    "easy": { "pi_tier": "easy" },
    "mechanical": { "pi_tier": "easy" },
    "verification": { "pi_tier": "easy" }
  },
  "pi_models": {
    "hard": ["xiaomi/mimo-v2.5-pro", "z-ai/glm-5.1"],
    "easy": [
      "qwen/qwen3.6-plus",
      "deepseek/deepseek-v4-pro",
      "z-ai/glm-5-turbo"
    ]
  }
}
```

## Step 1 — Write the dispatch JSON

Write to `.pi_agent_dispatch/.json`:

```json
{
  "spawned_at": "2026-05-02T10:00:00",
  "task": "one-line description",
  "agents": [
    {
      "id": "research",
      "task_type": "easy",
      "timeout_minutes": 10,
      "depends": [],
      "prompt": "Full self-contained prompt. End with: \"Output a concise summary of changes made.\"\nUse relative paths — pi runs inside the worktree."
    },
    {
      "id": "implement",
      "task_type": "hard",
      "depends": ["research"],
      "prompt": "..."
    },
    {
      "id": "tests",
      "task_type": "easy",
      "depends": ["implement"],
      "prompt": "..."
    },
    {
      "id": "docs",
      "task_type": "mechanical",
      "depends": ["implement"],
      "prompt": "..."
    },
    {
      "id": "special",
      "pi_model": "xiaomi/mimo-v2.5-pro",
      "depends": ["tests", "docs"],
      "prompt": "..."
    }
  ]
}
```

**Field reference:**

| Field             | Required                       | Notes                                                            |
| ----------------- | ------------------------------ | ---------------------------------------------------------------- |
| `id`              | yes                            | unique within file                                               |
| `task_type`       | yes unless `pi_model` explicit | key from `config.json:task_routing`                              |
| `pi_model`        | no                             | explicit model; overrides tier; no retry on failure              |
| `timeout_minutes` | no                             | per-agent; default = `config.default_timeout_minutes`            |
| `provider`        | no                             | per-agent; default = `config.provider` (e.g. `openrouter`)       |
| `depends`         | no                             | list of agent ids; missing = `[]`                                |
| `prompt`          | yes                            | self-contained; end with summary instruction; use relative paths |

**Prompt Writing Guidelines:**

When writing the prompt for a subagent, avoid writing the exact expected content (e.g., the exact code or output). Instead, write a compressed version that preserves the meaning anchors for the subagent to figure out the rest. Choose the approach that is likely to yield the most concise and effective prompt for the task.

Use one of the following strategies or a combination of them:

1. **Goal and Constraint Description**: Describe the goal of the task and the constraints (e.g., function signature, style, output format). The subagent will figure out the exact content.
2. **Requirements List**: Write a list of requirements that the expected result must satisfy. The subagent will produce a result that meets all requirements.
3. **Step-by-step Outcomes**: Break the task into steps and describe the expected outcome of each step in a high-level way.
4. **Test‑First Specification**: Create executable tests (or verification scripts) in the proper location following repository conventions. Provide a brief prompt that includes design and business context, points the subagent to the test file(s), and specifies the exact command to run them. The subagent’s goal is to make all tests pass.

Remember to end every prompt with an explicit summary instruction.

**Authoring rules:**

- Two agents that touch the same file MUST be sequenced via `depends`. Parallel = disjoint file scope.
- Every prompt must end with an explicit summary instruction. That summary becomes the `output` field in JSON.
- Use relative paths only — pi is spawned inside the worktree.

## Step 2 — Run the Orchestrator

```bash
python {{SKILL_DIR}}/orchestrate.py .pi_agent_dispatch/.json
```

## Step 3 — Read Output

**Success (`status: complete`):** all changes are merged into your working branch. Read per-agent `output` summaries. `attempt: 2` means a retry was needed.

**Failure (`status: conflict_paused`):** integration branch is preserved; working branch is untouched. Read `failure_reason`:

- `merge conflict` → fix `depends` in JSON, then **continue** (not re-run):

  ```bash
  python {{SKILL_DIR}}/orchestrate.py --continue .pi_agent_dispatch/-state.json
  # or with a fixed dispatch file:
  python {{SKILL_DIR}}/orchestrate.py --continue .pi_agent_dispatch/-state.json --json-override .pi_agent_dispatch/.json
  ```

  Already-merged agents are skipped; only the failed/pending agents re-run from the preserved integration branch.

  **Tool-generated files cause spurious conflicts.** IDE indexes, language-server caches, linter caches, and similar tools often write files to the repo directory when they run. Each parallel agent generates its own version of these files, producing conflicts that look like `depends` errors but aren't. The fix is repo-level: add those paths to `.gitignore` before running the dispatch. Common offenders: `.idea/`, `.vscode/`, `.pi-lens/`, `*.pyc`, coverage reports, any tool that writes a cache keyed on file paths or timestamps. Run `git status` inside a worktree after a failed dispatch to see what unexpected files appeared.

- `non-zero exit` after retry → diagnose from agent `output`.

**Inspecting diffs after success:**

```bash
git diff ..HEAD          # everything from this dispatch
git show                      # one agent's changes
git diff ..  # what one agent added vs previous
```

## Crash Recovery

```bash
python {{SKILL_DIR}}/orchestrate.py --cleanup .pi_agent_dispatch/-state.json
```

Removes worktrees, deletes agent branches, reverts integration branch.

## Pi CLI Reference (condensed)

```bash
# One-shot (what orchestrate.py does internally):
pi --provider openrouter --model  --no-session -p "prompt"

# Read-only audit:
pi --tools read,grep,find,ls -p "Review this"

# Continue session:
pi -c "Follow up"

# No session saved:
pi --no-session -p "one-off"
```

**Models by tier:**

Described in `config.json`

Default provider is configured in `config.json`. Override per-agent with the `provider` field in dispatch JSON.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jakubgajski](https://github.com/jakubgajski)
- **Source:** [jakubgajski/pi-dispatch-skill](https://github.com/jakubgajski/pi-dispatch-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jakubgajski-pi-dispatch-skill-pi-dispatch
- Seller: https://agentstack.voostack.com/s/jakubgajski
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.