pstack-pi

Files (2)

• SKILL.md
• runtime.md · references/

SKILL.md (first lines)

# pstack on Pi

`poteto-mode` is the sole router. It selects the playbook, canonical role, step order, and lifecycle protocol. This adapter translates those choices to Pi-compatible runtimes. It never selects a playbook, repeats the playbook index, or changes a playbook gate.

While this skill is active, its role map is the specific pstack execution contract. Generic host instructions remain valid outside pstack work.

## Canonical role map

Use the live host's configured names. This reference mapping targets OMP, a
Pi-based runtime; other hosts must substitute their own names through the runtime
contract.

| Canonical role | Pi/OMP agent | Contract |
|---|---|---|
| `explorer` | `scout` | Read-only repository reconnaissance, trace reduction, narrow audits. |
| `watcher` | `scout` | Observe one exact generation or external-state transition, then terminate. |
| `planner` | `designer` | Technical planning, architecture, decomposition, sequencing, and non-visual design candidates. |
| `designer` | `designer` | Visual, interaction, and product-design candidates. |
| `reviewer` | `reviewer` | Independent code, protocol, behavioral, or security review. |
| `researcher` | `librarian` | Source-verified external library, framework, API, protocol, or version research. |
| `synthesizer` | `reviewer` | Cross-report synthesis, adjudication, and advisory judgment over frozen evidence. |
| `implementer` | `task` | Bounded implementation or test changes with explicit write ownership. |
| `owner` | `task` | One coupled multi-step implementation session retained through IRC follow-ups. |
| `mechanical` | `sonic` | Fully specified low-judgment edits. Ambiguity returns to the root. |

The reference OMP roster is closed:

```text
scout
designer
reviewer
security-reviewer
librarian
task
sonic
```

A canonically routed task item's `agent` value must be one of those bundled names. Canonical role labels and model aliases are not agent names.

`poteto-agent` and `comment-sicko` are custom compatibility agents for direct named seams in imported skills. A direct compatibility call may use that custom agent name; ordinary canonical routing never does.

### Planning distinction

The imported warning about a built-in planning subagent describes a source-host mechanism that bypassed the skill contract. This Pi-compatible package has no bundled `plan` agent. Canonical `planner` work uses `designer` with a technical-planning brief and does not pass source-host subagent fields.

### Security review

Use `security-reviewer` for an independent security lane. Keep it read-only and separate from ordinary code review when both are required. A later `reviewer` session may synthesize frozen reports; it does not replace the primary security review.

## Task contract

The root coordinator performs every `task` call through the host task facility. A child never calls `task`, starts another child, or asks the user directly. Put `Do not call task or start subagents` under `FORBIDDEN` in every child brief.

Children start without the parent conversation. Every prompt must stand alone. They receive the configured workspace, context files, skills, and approved plan resources supplied by the host.

### One task

When the flat schema is active:

```json
{
  "name": "parser-overflow-worker",
  "agent": "task",
  "task": "GOAL\n...\n\nROLE\n...\n\nSCOPE\n...\n\nCONTEXT\n...\n\nACCEPTANCE\n...\n\nVERIFY\n...\n\nTIMEBOX\n...\n\nFORBIDDEN\n...\n\nREPORT\n...\n\nSTANDING\n...",
  "isolated": true
}
```

When batch mode is active, use a one-item `tasks[]` call instead of inventing a per-call batch switch.

Use `isolated: true` for a writer that needs a dedicated worktree. Read the returned isolation metadata and verify the patch, branch, or applied change the host reports. Use a non-isolated session for a long-lived owner that must accept follow-ups in the same workspace.

### Batched panel

Use one batch call for independent participants:

```json
{
  "context": "Shared immutable repository, base SHA, artifacts, constraints, and verification context.",
  "tasks": [
    {
      "name": "candidate-a",
      "agent": "designer",
      "task": "Standalone brief for architecture candidate A.",
      "isolated": false
    },
    {
      "name": "candidate-b",
      "agent": "designer",
      "task": "Standalone brief for architecture candidate B.",
      "isolated": false
    }
  ]
}
```

Each `name` is unique. `context` contains common immutable material. Each item still names its exact role, slice, acceptance criteria, verification, forbidden work, and report contract.

Start every participant in one batch before consuming any verdict. Separate writers with isolated workspaces or disjoint output paths. Freeze candidate artifacts before starting reviewers. Freeze reviewer reports before starting a separate synthesizer session.

### Background completion and follow-ups

Background task results arrive through the host's async result delivery. Record the returned job and agent identifiers. The preview may be truncated.

- Read the full result from `agent://<id>`.
- Read the session transcript from `history://<id>` when the report is incomplete, ambiguous, or suspicious.
- Use `hub` with `op: "jobs"` to inspect jobs and `op: "wait"` with `ids` to wait for specific job IDs.
- Use `hub` with `op: "list"` to inspect peers and `op: "send"` with `to` for one in-scope correction, answer, authorization, or next coupled phase.
- Use `hub` with `op: "cancel"` and exact job `ids` for stale, superseded, or scope-breaching work.
- A follow-up to a parked session revives the same session when the host reports that capability.
- Never steer a reviewer toward a preferred conclusion.
- Use only operations exposed by the live `hub` schema. Do not invent lifecycle operations.
- Ignore duplicate terminal deliveries and reject stale artifact generations.

A task result is evidence, not completion. The root inspects the artifact and runs verification.

## Brief shape

A dispatch is forbidden until its brief contains:

From shrimpwtf/oh-my-pstack, MIT.

More from shrimpwtf/oh-my-pstack