harness

Files (13)

• SKILL.md
• openai.yaml · agents/
• amp.md · references/
• claude-code.md · references/
• codex.md · references/
• copilot-cli.md · references/
• crush.md · references/
• cursor.md · references/
• droid.md · references/
• gemini-cli.md · references/
• goose.md · references/
• opencode.md · references/
• pi.md · references/

SKILL.md (first lines)

# Harness

pstack skills are written against a small set of neutral operations. They do not name tools or paths. This skill maps the operations onto the harness you are in right now. Every other pstack skill defers here.

## Detect once per session

Run this before the first pstack operation, then keep the answer for the session. Do not re-detect per skill.

1. Environment variables first. `COPILOT_CLI=1` means GitHub Copilot CLI, adapter `copilot-cli`. `CLAUDECODE=1` means Claude Code. `OPENCODE=1` or `OPENCODE_PID` set means opencode. `AI_AGENT=pi` or `PI_CODING_AGENT=true` means pi. `CODEX_SANDBOX` set means Codex CLI, a weak signal because it only appears under sandboxing.
2. Tool fingerprints next. `AskUserQuestion` plus an `Agent` tool means Claude Code. `request_user_input` plus `update_plan` means Codex CLI. `ask_user` plus `write_todos` means Gemini CLI. A `task` tool with `subagent_type` plus `todowrite` means opencode. `AskUser` plus `TaskOutput` means Factory Droid. `delegate` plus `load` means Goose. A read-only `agent` tool plus `crush_info` means Crush. Built-in specialists named `Review`, `Search`, or `Oracle` with no markdown persona support means Amp. `AskQuestion` plus a `Task` tool means Cursor. A `task` tool plus `read_agent`, `list_agents`, and `write_agent` means GitHub Copilot CLI, adapter `copilot-cli`.
3. Still unknown after both checks: ask the user once which harness this is, then remember it.

After detection, read `references/<harness>.md` from this skill and apply it for the rest of the session.

## Neutral operations

- **ask-user(question, options).** One structured question, two to five options, free-form always allowed. Use it where a pstack skill says to ask with options.
- **todolist(items).** A tracked task list the user can see. Update it as steps complete.
- **spawn-subagent(brief, model-role, mode).** One subagent with a standalone brief. Mode is `foreground`, `background`, or `readonly`. Fan-outs spawn all subagents in one message. The model-role names a line from the model config below, or `session` for the current model. Briefs stand alone and include goal, scope, verification, and report format.
- **persona(name).** pstack ships two personas, `poteto-agent` and `comment-sicko`, as markdown files in the plugin's `agents/` directory. When the harness supports custom subagent personas, install or reference them there. Otherwise paste the persona file's full text at the top of the subagent brief.
- **discover-mcps.** List the MCP servers configured in this harness, so a skill can pick evidence sources.
- **find-transcripts.** Locate this workspace's session transcripts on disk.
- **cloud-run(brief).** Run a subagent on managed remote compute instead of this machine. Used when a skill calls for parallel isolated workers that do not need local state.

## Model roles

Skills name roles, never model ids. Roles resolve in this order:

1. `~/.config/pstack/<harness>/models`, the active harness's config written by `/setup-pstack`. Replace `<harness>` with the adapter filename without `.md`, such as `pi`, `codex`, or `claude-code`. The adapter's Config section gives the exact path. One line per role, `role: model` or a comma-separated panel list.
2. The harness mirror named in the adapter. Cursor mirrors to `~/.cursor/rules/pstack-models.mdc` so the choices inject every session.
3. The adapter's defaults.

Read only the active harness's config and mirror. Ignore the old shared file at `~/.config/pstack/models` and other harnesses' configs. If the active config is absent, use its mirror or adapter defaults, not the shared file.

A role that resolves to nothing runs on the session model. The value `inherit-parent` or `auto` also means the session model. When a multi-model panel collapses to one model because the harness cannot spawn per-subagent models, say so in the reply. The panel still runs, sequentially if it must.

Roles in use: `code`, `fast`, `judgment`, `hardest`, plus the panel roles `how explorer`, `how explainer`, `why investigators`, `why synthesizer`, `reflect tooling`, `reflect judgment`, `arena runners`, `arena cross-judge pool`, `swarm workers`, `architect runners`, `interrogate reviewers`. Legacy config lines naming playbooks, like `bug-fix` or `feature, refactoring`, map onto the matching role as the adapter notes.

## Fallback policy

A missing capability never skips a step. Substitute the fallback and note it in the reply.

- No subagents: do the work in the main thread, sequentially, and keep raw outputs out of the context window where the skill said to.
- No per-subagent models: the session model plays every role. Panels become sequential passes with the same briefs.
- No structured ask-user: ask in plain text and list the options as a markdown list.
- No todo tool: keep a markdown checklist in the reply and update it in place.
- No MCP discovery: name which evidence sources you could not query and proceed with the rest.
- No transcripts: state the limit, then rebuild context from git history and the shared record.
- No cloud runs: use local git worktrees plus background subagents.

## Installing pstack on a harness

Cursor installs the plugin as usual with `/add-plugin pstack`. Every other harness in the adapters reads skills from `.agents/skills/` or `~/.agents/skills/` or both, so one copy covers them: clone or place this repository, then symlink each skill into the shared directory, from the repo root:

```bash
mkdir -p ~/.agents/skills && ln -sfn "$PWD"/skills/* ~/.agents/skills/
```

If the link command fails because the destination is an existing real directory, the shared directory already holds that name from another skills provider. `ln` replaces symlinks but never directories, so move or remove that copy first.

The `$PWD` prefix matters: `ln` stores the source text verbatim as the link's target, so a relative source such as plain `skills/*` resolves against the link's own directory, not yours, and ends up dangling. Only absolute operands produce working symlinks.

Keep the checkout intact. Skills reference their own files and sibling skills by relative path, so the symlinks must point into this tree rather than copying files out of it.

After installation, run [setup-pstack](../setup-pstack/SKILL.md#6-write-the-config) to choose models for pstack roles and save them in `~/.config/pstack/<harness>/models`. Step 6 adds a config-reading instruction to the user-level file named in your adapter, or writes the Cursor mirror. This makes the model choices available to later sessions across projects. Skill and persona use follows the relevant skill instructions.

From theoklitosBam7/pstack-portable, MIT.

More from theoklitosBam7/pstack-portable