pstack-harness

Harness adapters

A cut-off read is no read. A return that is shortened, warns that it was cut, or that you capped with head, tail, or a line limit leaves the file or diff unread. Read the missing part before you act. This file too. On Codex, follow Read files.

Use this skill when a pstack workflow names a delegation action, worklist, question, loop, transcript, portable resource, shell command, or process inspection.

Your tool inventory and CLI help are authoritative. Never invent a tool. Report the mechanism when it affects execution or evidence. For worklists, report item state rather than the carrier.

Before executing shell commands or answering what is running, read shell commands and running processes. This applies to every action and runtime.

Select the action

Read each selected reference in full before its action. Select only the actions the next step needs. Read a link inside a reference only when its described operation applies. Do not read every reference.

Action	Required references
worklist	Worklist procedure
question	Structured questions
spawn	The Spawn a role recipe below, Delegation and isolation, and the current runtime adapter below. Read Role resolution and handoffs only for a handoff, a recovery, a trail reviewer, or a resolver that fails or prints a note, and Portable resource path contract only when PSTACK_SKILLS_ROOT is unset
role-handoff	Role resolution and handoffs
persona	Persona contract when the spawn names a persona
loop	Loops and wake-ups
transcript	Workspace transcripts and the current runtime adapter below
portable-paths	Portable resource path contract when a command uses PSTACK_SKILLS_ROOT, PSTACK_SOURCE_ROOT, or PROJECT_ROOT

Runtime adapters

When context compaction, shortened skill content, or skill restoration affects the next action, read skill retention evidence. Keep documented limits, runtime observations, and unknown behavior separate.

For spawn or transcript, read only the current runtime column for that action. Other actions need no runtime adapter.

Runtime	Spawn adapter	Transcript location
claude-code	Claude Code	Transcript location
codex	Codex	Transcript location
hermes	Hermes	Transcript location
grok	Grok Build	Transcript location
other	Other runtime	Transcript location

Resolve portable resources

Resolve only the roots that the next command needs. Keep the exact command forms in generated plans and restore the recorded roots across owners, delegates, wake-ups, and later ticks.

Preserve roles across handoffs

Read the role resolution and handoffs reference selected above before a role handoff or recovery.

Spawn a role

Every pstack spawn runs a role from the models config, such as feature or how explorer, sometimes under a persona. Keep the caller's role and panel arm count.

1. Take the role from the skill or playbook step. A step that names none uses default. A subagent_type of poteto-agent or comment-sicko names a persona, and general-purpose names none.

2. Resolve it once per task, and again after the harness or config changes. Run the resolver from the project root, or pass --project <root>, since it reads that directory's .agents/pstack-models.md. Do not read the config files to pick values.

   python3 "${PSTACK_SKILLS_ROOT:?}/setup-pstack/scripts/check-models-config.py" --resolve --harness <claude-code|codex|grok|hermes> <role>
   

   Failure signal: nonzero exit. It prints one JSON line per arm with model, effort, and source, plus notes to relay in the reply. If it fails or prints a note, or the role is trail reviewer, follow Spawn a role in roles.md. Never drop a spawn because the resolver failed. Spawn with model and effort omitted and report it.

3. Build the call from the current runtime adapter. inherit-parent in a field means omit that field.

4. For a persona, put its complete briefing at the top of the prompt, from python3 "${PSTACK_SKILLS_ROOT:?}/pstack-harness/scripts/subagents.py" brief <persona>, unless the live agent catalog lists the persona's native name.

5. Report the model and effort each arm ran on, and label a review same-model when it matches the work's model.

Universal rules

• Use named sibling skills yourself. "Call the Skill tool with architect" tells you to load the pstack skill architect and follow it. A following "follow its" or "use its" names the part of that skill the step needs, after the whole skill loads. The name is a sibling directory under the installed skills root, the directory that holds this skill's own directory. Any other pstack mention of a skill by name, such as "the leaf skill" or "the arena skill", names one the same way. On Claude Code, call the Skill tool with the bare name, such as architect. The call works when the listing shows the name only, with no description, and a name-only listing never means the skill is missing. Codex, Grok Build, Hermes, and any other harness have no tool named Skill for these skills. There, the same phrase means read <installed skills root>/<name>/SKILL.md in full, then read the files it references when its steps need them. On Codex, a $name mention in a user prompt injects that skill's SKILL.md, so do not read that file again unless the injected copy was cut. Never ask the user to type a skill that a pstack skill names. Never edit a skill's files or the listing settings to change how it loads.
• Load only skills that someone named. Never read or load a pstack skill that you found by listing or searching a skills directory, unless the user or a loaded skill named it. A skill that the harness lists with its description can still load from that description.
• Tool names in skill text describe intent, never a required tool. Task, Glob, Grep, Read, a worklist, and Cursor-era parameters like readonly name capabilities: realize each with whatever your session provides (a search tool, a shell command, a read-only brief). Capability selection follows live descriptions, not recalled names. A missing optional tool never cancels the step and needs no announcement. A subagent_type in skill text names a persona or none, and Spawn a role turns it into the concrete type.