pstack-harness

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Harness adapters

Harness 适配器

pstack skills describe delegation abstractly: "spawn a subagent on model X", "launch N in parallel in one message", "readonly", "AskQuestion". Each is an intent, not a tool name. Satisfy the intent with whatever your session actually provides — your live tool inventory and your CLI's own help are the authority, not this file. Never invent a tool, and say in your reply which mechanism you used.

pstack技能以抽象方式描述委托逻辑：“基于模型X生成子代理”、“在一条消息中并行启动N个任务分支”、“只读模式”、“AskQuestion”。这些均为意图描述，而非工具名称。请使用当前会话实际提供的能力来满足这些意图——你的实时工具库和CLI自带帮助文档是权威依据，而非本文档。切勿虚构工具，且需在回复中说明你使用的实现机制。

The primitives

核心原语

Spawn a subagent. In order of preference:

Your harness's native subagent or delegation tool, whatever it is called.
No such tool → invoke your own CLI non-interactively as a subprocess (its help names the command and flags), one invocation per arm, run concurrently in background shells, each arm's report collected from stdout or a file path named in its brief.
No subprocesses either → run the arms sequentially inline, one at a time, each writing its report to a file before the next starts, then synthesize. Keep the configured arm count.

Each writer gets its own git worktree, whichever mechanism spawns it.

Set an arm's model. Pass the model through whatever the spawn mechanism accepts — a tool parameter, a CLI flag. Only pass a value this session has confirmed the mechanism accepts; anything unconfirmed or rejected means

inherit-parent

: omit the model and let the arm run on the session model.

Set an arm's effort. Every role resolves to a model and a reasoning effort (see The models config below). Pass the effort through the spawn mechanism when it has a field or flag for it. When it has none, or the harness rejects the value, the effort alone becomes

inherit-parent

: keep the model, keep the arm, and say in the reply that the effort was inherited. An effort problem never drops a model or an arm.

Parallelism. Real where the mechanism allows it (independent tool calls in one message, concurrent subprocesses); otherwise sequential with the same arm count.

Read-only. Use an enforcing option if the spawn mechanism has one; otherwise state it plainly in the brief ("read-only: do not edit or write files").

Structured questions (
AskQuestion
). Your harness's structured-question tool if it has one; otherwise ask in plain chat.

Open a todolist. Harnesses name this tool inconsistently, so resolve it by looking, never by recall. Claude Code calls it

TodoWrite

, Codex calls it

update_plan

, Hermes ships it as the

todo

toolset. Search your inventory by the exact names above and by shape, a tool that tracks a plan or a task list, not by the literal word "todo" alone;

update_plan

is the name that gets missed. Some harnesses defer tool schemas, so a tool absent from the visible inventory may still be loadable through a tool-search facility. Query that facility both ways before you conclude there is none, because a name lookup finds what a shape query misses and the reverse. Only a look that came up empty licenses the fallback: a scratch

TODO.md

in your worktree or working directory when you can write files, otherwise a checklist in your reply updated as items land. Missing the tool never cancels the practice: the full plan stated up front, one item in progress at a time, skips marked with a reason, nothing silently dropped. Name the mechanism you used in your reply.

Loops and wake-ups. Your harness's loop or scheduling facility; otherwise a re-invoking wrapper (script, cron, CI).

Transcripts. Every harness keeps this workspace's session record somewhere — log files under its data directory, or a database with an export command. Locate yours before reading, and stay inside the current workspace's sessions; other projects' transcripts are private.

生成子代理，优先级如下：

使用harness原生的子代理或委托工具（无论其名称为何）。
若无此类工具 → 以非交互方式将自身CLI作为子进程调用（其帮助文档会说明命令和参数），每个任务分支对应一次调用，在后台shell中并发运行，从stdout或任务简介中指定的文件路径收集每个分支的报告。
若也无法使用子进程 → 按顺序逐个运行任务分支，每个分支完成后将报告写入文件，再进行结果合成。保持配置的任务分支数量不变。

无论采用哪种生成机制，每个执行单元都会获得独立的git工作树。

设置任务分支的模型：通过生成机制支持的方式传递模型参数——可以是工具参数或CLI标志。仅传递当前会话已确认机制支持的值；若值未确认或被拒绝，则使用

inherit-parent

：不指定模型，让任务分支使用会话默认模型。

设置任务分支的推理力度：每个角色都会解析为一个模型和对应的推理力度（见下方模型配置）。当生成机制有对应字段或标志时，传递推理力度参数。若没有对应字段，或harness拒绝该值，则仅推理力度采用

inherit-parent

：保留模型和任务分支，并在回复中说明推理力度已继承。推理力度问题绝不会丢弃模型或任务分支。

并行处理：若机制支持则实现真正的并行（一条消息中的独立工具调用、并发子进程）；否则按顺序执行，但保持任务分支数量不变。

只读模式：若生成机制有强制只读的选项则使用该选项；否则在任务简介中明确说明（“只读模式：请勿编辑或写入文件”）。

结构化问题（AskQuestion）：若harness有结构化问题工具则使用该工具；否则以普通聊天形式提问。

打开任务清单：不同harness对该工具的命名不一致，因此需通过查找确认，而非仅凭记忆。Claude Code称其为

TodoWrite

，Codex称其为

update_plan

，Hermes则以

todo

工具集形式提供。请通过上述精确名称或工具形态（用于跟踪计划或任务列表的工具）搜索你的工具库，不要仅搜索字面意义的“todo”；

update_plan

是最容易被遗漏的名称。部分harness会延迟加载工具 schema，因此可见工具库中不存在的工具可能仍可通过工具搜索功能加载。请同时通过名称和形态查询该功能，再判定是否不存在——名称查找和形态查询可互补遗漏。只有当确实未找到时，才可使用 fallback 方案：若可写入文件，则在工作树或工作目录中创建临时

TODO.md

；否则在回复中使用清单，并随任务进展更新。即使缺少工具，也必须执行该操作：提前明确完整计划，一次处理一个任务项，跳过的项需标注原因，不得静默丢弃任务。需在回复中说明你使用的机制。

循环与唤醒：使用harness的循环或调度功能；否则使用重新调用的包装器（脚本、cron、CI）。

会话记录：每个harness都会在某处保存当前工作区的会话记录——可能是数据目录下的日志文件，或是带有导出命令的数据库。请先定位你的会话记录位置，且仅访问当前工作区的会话；其他项目的会话记录为私有内容。

Hints for known harnesses

已知harness的提示信息

Observed circa 2026-09. Treat as starting points, not contracts — verify against your live session before relying on any of them, and prefer what you find over what is written here.

harness	spawn	todolist	effort	transcripts
Claude Code	`Task` tool (custom agents from `.claude/agents/` spawn by name); `model` takes short aliases	`TodoWrite` . Absent from some builds and permission modes, and it is not always in the deferred-tool list either, so an empty look here is real and the fallback applies	no per-call field; only the `effort` frontmatter key of a custom agent file. A subagent inherits the session effort ( `--effort` , `effortLevel` ), so the effort is `inherit-parent` here	JSONL under `~/.claude/projects/<slug>/` , `<slug>` = workspace path with `/` → `-`
Codex	`spawn_agent` (the multi-agent feature, stable in 0.152) takes a model and a reasoning effort per spawn; custom roles live in `~/.codex/agents/.md` or `.codex/agents/.md` with `model` and `model_reasoning_effort` ; `codex exec` is the subprocess route	`update_plan` . No "todo" in the name, so a keyword scan misses it	the reasoning-effort field on `spawn_agent` ; `-c model_reasoning_effort=<value>` on `codex exec` . A model set without an effort gets that model's default effort (medium on the GPT-5.6 family), not the parent's, so always pass one	JSONL under `~/.codex/sessions/` by date
Hermes	a delegation toolset when enabled; `hermes -z` for one-shot subprocess runs	the `todo` toolset, listed as "Task Planning" and enabled by default. Confirm with `hermes tools list` , then read the tool's live schema for the call shape	`--reasoning <value>` on `hermes -z` ; config `agent.reasoning_effort` and per-model `agent.reasoning_overrides` . Whether the delegation toolset takes an effort field is unverified: check its schema in session	SQLite store; `hermes sessions` subcommands list and export

信息采集于2026年9月左右。仅作为参考起点，而非正式约定——在依赖任何信息前，请先验证当前会话的实际情况，优先使用你找到的实时信息，而非本文档内容。

harness	生成子代理方式	任务清单工具	推理力度设置	会话记录存储
Claude Code	`Task` 工具（通过名称调用 `.claude/agents/` 中的自定义Agent）； `model` 参数支持短别名	`TodoWrite` 。部分版本和权限模式下可能缺失，且不一定在延迟加载工具列表中，若未找到则需使用 fallback 方案	无单次调用字段；仅支持自定义Agent文件的 `effort` 前置键。子代理会继承会话的推理力度（ `--effort` 、 `effortLevel` ），因此此处推理力度为 `inherit-parent`	JSONL格式文件存储于 `~/.claude/projects/<slug>/` ， `<slug>` 为工作区路径将 `/` 替换为 `-` 后的字符串
Codex	`spawn_agent` （多Agent功能，在0.152版本中稳定）支持为每个生成的Agent指定模型和推理力度；自定义角色存储于 `~/.codex/agents/.md` 或 `.codex/agents/.md` ，包含 `model` 和 `model_reasoning_effort` 参数； `codex exec` 是子进程调用方式	`update_plan` 。名称中不含“todo”，因此关键词扫描易遗漏	`spawn_agent` 的推理力度字段； `codex exec` 的 `-c model_reasoning_effort=<value>` 参数。若仅设置模型未指定推理力度，则使用该模型的默认推理力度（GPT-5.6系列默认为medium），而非父进程的推理力度，因此请务必传递推理力度参数	JSONL格式文件按日期存储于 `~/.codex/sessions/`
Hermes	启用后会提供委托工具集； `hermes -z` 用于单次子进程运行	`todo` 工具集，显示为“Task Planning”，默认启用。请通过 `hermes tools list` 确认，然后查看该工具的实时schema了解调用格式	`hermes -z` 的 `--reasoning <value>` 参数；配置项 `agent.reasoning_effort` 和每个模型的 `agent.reasoning_overrides` 。委托工具集是否支持推理力度字段尚未验证：请在会话中查看其schema	SQLite存储；通过 `hermes sessions` 子命令列出和导出会话记录

Universal rules

通用规则

Panels degrade by model, never by count. A four-model panel in a one-model harness is still four arms (parallel or sequential), each with a genuinely different brief; the configured list length sets the count.
Named sibling skills are files. When a pstack skill says "the architect skill" or "read the leaf skill", it names a sibling directory under the same installed skills root. Most pstack skills are gated against model invocation, so they appear in no tool inventory and their descriptions are not in context — that never means missing. Read the named skill's SKILL.md (and any files it references) directly and follow it; record that you applied it by file read. Never edit a skill's gating to make it invocable.
Tool names in skill text describe intent, never a required tool.
```
Task
```
,
```
Glob
```
,
```
Grep
```
,
```
Read
```
, a todolist, and Cursor-era parameters like
```
readonly
```
,
```
environment: "cloud"
```
, and
```
is_background
```
name capabilities: realize each with whatever your session provides (a search tool, a shell command, a read-only brief, worktree isolation, background execution). A missing tool never cancels the step — find the equivalent, and never report a step blocked on a tool name.
Config: roles resolve to a model and an effort per The models config below. A value the current harness cannot use is
```
inherit-parent
```
for that field only.
Honesty: never report parallel arms that actually ran sequentially; name the mechanism used.
No improvised models: every spawn resolves through a named role. A spawn whose skill names no role resolves through the
```
default
```
line, then
```
inherit-parent
```
. Never pick a model that neither the config nor the skill's inline default names, and say which role the model came from.

任务分支按模型降级，绝不减少数量：在仅支持单模型的harness中，四模型面板仍会保留四个任务分支（并行或顺序执行），每个分支使用完全不同的任务简介；配置的列表长度决定任务分支数量。
命名的同级技能为文件：当pstack技能提及“架构师技能”或“阅读leaf技能”时，指的是同一已安装技能根目录下的同级目录。大多数pstack技能会限制模型调用，因此不会出现在工具库中，其描述也不会在上下文里——但这绝不意味着不存在。请直接读取指定技能的SKILL.md（及其引用的任何文件）并遵循其要求；记录你通过读取文件应用了该技能。切勿修改技能的限制设置使其可被调用。
技能文本中的工具名称描述意图，而非强制要求的工具：
```
Task
```
、
```
Glob
```
、
```
Grep
```
、
```
Read
```
、任务清单，以及Cursor时代的参数如
```
readonly
```
、
```
environment: "cloud"
```
、
```
is_background
```
均为能力描述：请使用当前会话提供的任何方式实现（搜索工具、shell命令、只读任务简介、工作树隔离、后台执行）。缺少工具绝不意味着步骤取消——请找到等效方案，切勿报告因工具名称缺失导致步骤受阻。
配置：角色会根据下方模型配置解析为模型和推理力度。若当前harness无法使用某值，则仅该字段采用
```
inherit-parent
```
。
诚实性：切勿报告实际为顺序执行的并行任务分支；需说明你使用的机制。
禁止即兴选择模型：每个生成操作都需通过命名角色解析。若技能未指定角色，则通过
```
default
```
行解析，再使用
```
inherit-parent
```
。切勿选择配置或技能内置默认值未提及的模型，并需说明模型来自哪个角色。

The models config

模型配置

~/.agents/pstack-models.md

(user) and

.agents/pstack-models.md

(workspace) map each role to a model and a reasoning effort.

setup-pstack

writes and lints the file; its shipped default is

examples/pstack-models.md

next to that skill.

Grammar.

role: entry

, or

role, role: entry

to bind several roles at once. Panel roles (

how critics

arena runners

arena cross-judge pool

architect runners

interrogate reviewers

) take a comma list, one arm per entry. An entry is

model

model@effort

. Efforts are

none

low

medium

high

xhigh

max

;

ultra

is Codex's Pro mode and is valid only on

gpt-5.6-sol

inherit-parent

and

auto

, with or without

@effort

, run the arm on the parent chat model. A

## codex

## claude-code

, or

## hermes

header starts a section whose lines apply to that harness only; lines above any header apply everywhere. Two roles are special.

trail reviewer

is the show-me-your-work reviewer; when it resolves to the model that did the work, show-me-your-work steps down one tier so the review stays cross-model.

default

is the entry for any spawn whose skill names no role; it ships as

inherit-parent

Precedence. Resolve the model and the effort of a role separately, taking the first level that has a value:

workspace file, this harness's section
workspace file, flat lines
user file, this harness's section
user file, flat lines
the skill's inline default for the model; the effort policy below for the effort
the
```
default
```
line, searched through levels 1 to 4, for a spawn whose skill names no role or whose role has no inline default
```
inherit-parent
```
: the value is
```
inherit-parent
```
or
```
auto
```
, the harness has no way to set that field, or the harness rejected the value

A section never leaks into another harness. A workspace flat line beats a user harness line, so the old rule "workspace wins per role" still holds.

Codex alias translation. On Codex, a Claude alias that reaches step 7 translates instead of inheriting:

alias	Codex entry	why
`fable`	`gpt-5.6-sol@max`	Sol at max is the Fable-parity tier
`opus`	`gpt-5.6-sol@xhigh`	Sol at high or xhigh matches Opus
`sonnet`	`gpt-5.6-terra@high`	Terra is the balanced, mini-like tier, Sonnet's role
`haiku`	`gpt-5.6-luna@high`	Luna is the high-throughput, nano-like tier; the floor keeps it at high

The translated effort belongs to the alias and stands unless the entry wrote its own

@effort

. Hermes has no translation table yet; an alias there is

inherit-parent

, as before.

Effort policy. When no

@effort

is written: floor

high

for every role.

xhigh

for hardest tasks, judgment and prose, bug-fix, perf-issue, hillclimb, how explainer, how critics, why synthesizer, reflect judgment, divergent and synthesizer, arena cross-judge pool, architect runners, and trail reviewer. Nothing in this policy produces

max

ultra

; those come only from an explicit

@max

@ultra

on a line, from the Codex translation of

fable

, or from an explicit escalation in the task. Effort never changes an arm count or a model choice.

~/.agents/pstack-models.md

（用户级）和

.agents/pstack-models.md

（工作区级）将每个角色映射到模型和推理力度。

setup-pstack

负责写入和校验该文件；其默认模板为该技能旁的

examples/pstack-models.md

。

语法：

role: entry

，或

role, role: entry

将多个角色绑定到同一配置。面板角色（

how critics

、

arena runners

、

arena cross-judge pool

、

architect runners

、

interrogate reviewers

）接受逗号分隔的列表，每个条目对应一个任务分支。条目格式为

model

或

model@effort

。推理力度可选值为

none

、

low

、

medium

、

high

、

xhigh

、

max

；

ultra

是Codex的Pro模式，仅在

gpt-5.6-sol

上有效。

inherit-parent

和

auto

（可带或不带

@effort

）表示任务分支使用父聊天模型。

## codex

、

## claude-code

或

## hermes

标题开头的部分仅适用于对应harness；标题上方的行适用于所有harness。有两个特殊角色：

trail reviewer

是“展示工作过程”的审核者；当它解析为执行任务的模型时，“展示工作过程”步骤会降级一级，确保审核使用跨模型。

default

是技能未指定角色时的默认配置；默认值为

inherit-parent

。

优先级：分别解析角色的模型和推理力度，采用第一个有有效值的层级：

工作区文件，当前harness专属部分
工作区文件，通用行
用户文件，当前harness专属部分
用户文件，通用行
技能内置的模型默认值；推理力度采用下方的推理力度策略
```
default
```
行，按层级1至4搜索，适用于技能未指定角色或角色无内置默认值的生成操作
```
inherit-parent
```
：值为
```
inherit-parent
```
或
```
auto
```
、harness无法设置该字段，或harness拒绝该值

专属部分绝不会影响其他harness。工作区通用行优先级高于用户harness专属行，因此旧规则“工作区配置按角色优先”仍然有效。

Codex别名转换：在Codex中，若Claude别名到达步骤7，会进行转换而非继承：

别名	Codex配置	原因
`fable`	`gpt-5.6-sol@max`	Sol模型max力度与Fable性能相当
`opus`	`gpt-5.6-sol@xhigh`	Sol模型high或xhigh力度匹配Opus
`sonnet`	`gpt-5.6-terra@high`	Terra是平衡型mini级模型，对应Sonnet的定位
`haiku`	`gpt-5.6-luna@high`	Luna是高吞吐量nano级模型；最低力度设为high

转换后的推理力度属于别名本身，除非条目自身指定了

@effort

。Hermes目前无转换表；别名在Hermes中会采用

inherit-parent

，与之前一致。

推理力度策略：当未指定

@effort

时：所有角色默认最低为

high

。对于最复杂的任务（判断与文案、bug修复、性能问题、爬坡优化、how类解释、how类评审、why类合成、反思判断、发散与合成、竞技场交叉评审池、架构师执行单元、trail reviewer），使用

xhigh

。本策略不会生成

max

或

ultra

；这些值仅来自条目中明确的

@max

或

@ultra

、Codex对

fable

的转换，或任务中的明确升级。推理力度绝不会改变任务分支数量或模型选择。",