perpetuum

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

perpetuum

A persistent three-layer "explore → execute → escalate" loop on top of

cc-use

. Designed for tasks whose value grows with how many findings or improvements an agent can produce over hours or days.

This file is a router. Every mechanism below has a one-paragraph summary here; details live in

references/

. Read the relevant reference when the user's intent matches the corresponding section.

基于

cc-use

构建的持久化三层「探索→执行→升级」循环。专为那些Agent在数小时或数天内产生的发现或改进越多，价值就越高的任务设计。

此文件是一个路由文件。以下每种机制都在此处有一段摘要；详细内容请查看

references/

目录。当用户的需求与对应部分匹配时，阅读相关参考文档。

When to invoke this skill

何时调用此技能

The user wants to start a new persistent loop on a project (bug hunting, style distillation, PR/issue triage, observability scanning, etc.)
The user wants to inspect, pause, resume, stop, or nudge an already-running loop
The user wants to answer an escalation the loop has surfaced
The user wants to run multiple loops in parallel on the same project via git worktree

If the user's intent isn't clear from "use perpetuum" alone, ask before doing anything.

用户希望在项目上启动一个新的持久化循环（例如Bug排查、风格提炼、PR/问题分类、可观测性扫描等）
用户希望检查、暂停、恢复、停止或调整已在运行的循环
用户希望响应循环提出的升级请求
用户希望通过git worktree在同一项目上并行运行多个循环

如果仅通过“使用perpetuum”无法明确用户的意图，请先询问再执行操作。

Route by intent

按意图路由

User wants to…	Read
Start a new task	`references/setup.md` + skim `examples/`
See current status	`references/status.md`
Pause / resume / stop / kill	`references/control.md`
Push an instruction / answer an escalation	`references/feedback.md`
Parallel lines via git worktree	`references/worktree.md`
Write or adjust `trigger.sh`	`references/trigger.md`
Understand the design rationale	`references/design.md`

用户需求	阅读文档
启动新任务	`references/setup.md` + 浏览 `examples/`
查看当前状态	`references/status.md`
暂停 / 恢复 / 停止 / 终止	`references/control.md`
发送指令 / 响应升级请求	`references/feedback.md`
通过git worktree实现并行任务	`references/worktree.md`
编写或调整 `trigger.sh`	`references/trigger.md`
理解设计原理	`references/design.md`

How it works (architecture in one screen)

工作原理（架构概览）

Layer 4   you + host agent     monitor + relay (optional)
   ↓
Layer 3   trigger.sh           heartbeat: paste prompts, wait for done
   ↓                                       flags, sleep, loop
Layer 2   middle agent (tmux)  judge + dispatch, two prompts:
   ↕                                       1_explore.md  (plan)
                                           2_execute.md  (dispatch + judge)
Layer 1   inner agent          fresh context per dispatch — has no
   (cc-use)                    memory of previous cycles, cannot
                               rubber-stamp known behavior

The split between Layer 1 (producer, fresh context) and Layer 2 (judge, persistent context) is the GAN-like discriminator / generator separation that prevents the self-certifying problem of

/goal

or Ralph Loop. Layer 1 reports back to Layer 2; Layer 2 commits, fixes, or escalates.

Layer 4   you + host agent     监控 + 中继（可选）
   ↓
Layer 3   trigger.sh           心跳：粘贴提示词，等待完成
   ↕                                       标记、休眠、循环
Layer 2   middle agent (tmux)  判断 + 调度，包含两个提示词：
   ↕                                       1_explore.md （规划）
                                           2_execute.md （调度 + 判断）
Layer 1   inner agent          每次调度使用全新上下文 —— 不
   (cc-use)                    保留之前循环的记忆，无法
                               机械重复已知行为

Layer 1（生产者，全新上下文）与Layer 2（判断者，持久化上下文）的分离，是类似GAN的「判别器/生成器分离」设计，避免了

/goal

或Ralph Loop存在的自我验证问题。Layer 1向Layer 2汇报结果；Layer 2负责提交、修复或升级任务。

Mechanisms (one paragraph each)

核心机制（各机制摘要）

Each mechanism is summarized here; for the full procedure see the linked reference.

Ratchet (monotonic progress). Every accepted finding becomes a local
```
git commit
```
; every reject is a
```
git reset
```
. The branch is monotonically improving — borrowed from Karpathy's AutoResearch pattern, but for tasks without a scalar metric. Details in
```
references/design.md
```
.
Exploration vs exploitation split. Two prompts per cycle.
```
prompts/1_explore.md
```
is divergent (list dimensions, sample broadly, populate the backlog).
```
prompts/2_execute.md
```
is convergent (work through the backlog, commit or escalate). Lexically-sorted files mean you can drop a
```
3_reflect.md
```
in to add a reflection phase without touching code. Details in
```
references/trigger.md
```
.
Async human escalation.
```
escalations.md
```
is the channel for ambiguous decisions the agent can't make alone. Agent writes Open items with A/B/C options; human writes answers in Resolved. New cycles run while questions sit unanswered — the loop never blocks on the human. Details in
```
references/feedback.md
```
.
Inbox (human → agent push).
```
inbox.md
```
is where the user nudges the agent: SKIP, PRIORITIZE, ADD, STOP, DIRECTION, NOTE, or plain natural language. Read at every cycle's explore phase. Details in
```
references/feedback.md
```
.
Trigger abstraction. Three trigger types —
```
schedule
```
(every N minutes),
```
conditional
```
(poll an external state like
```
gh pr list
```
),
```
webhook
```
(event-driven). Same Layer 2 and Layer 1; only Layer 3 differs. Default in examples is
```
schedule
```
with a 2-minute interval — see cost note below. Details in
```
references/trigger.md
```
.
Control signals.
```
touch .paused
```
/
```
rm .paused
```
to pause and resume;
```
touch .stop_after_current
```
to gracefully stop after the current cycle;
```
pkill -f trigger.sh
```
+
```
tmux kill-session
```
for hard stop. File-level signals, no new protocol. Details in
```
references/control.md
```
.
Parallel lines via git worktree. For several perpetuum tasks on the same project, use
```
git worktree add
```
so each task gets its own branch and directory.
```
_meta.md
```
records the worktree metadata. Details in
```
references/worktree.md
```
.
File-as-contract.
```
plan.md
```
is agent-maintained (humans should route changes through
```
inbox.md
```
);
```
inbox.md
```
is human-write;
```
escalations.md
```
is bidirectional with the "agent writes Open, human writes Resolved" convention. Nothing is enforced at the filesystem level — it's a convention, not a lock. Details in
```
references/feedback.md
```
.

每个机制在此处有简要概述；完整流程请查看关联的参考文档。

棘轮机制（单调进度）。每个被接受的发现都会成为本地
```
git commit
```
；每个被拒绝的结果都会执行
```
git reset
```
。分支会持续优化——借鉴了Karpathy的AutoResearch模式，但适用于没有标量指标的任务。详情请查看
```
references/design.md
```
。
探索与利用分离。每个循环包含两个提示词。
```
prompts/1_explore.md
```
用于发散性思考（列出维度、广泛采样、填充待办列表）。
```
prompts/2_execute.md
```
用于收敛性执行（处理待办列表、提交或升级任务）。按字典序排序的文件意味着你可以添加
```
3_reflect.md
```
来增加反思阶段，无需修改代码。详情请查看
```
references/trigger.md
```
。
异步人工升级。
```
escalations.md
```
是Agent无法独立做出模糊决策时的沟通渠道。Agent会在Open项中写入带有A/B/C选项的问题；人类在Resolved项中写入答案。即使问题未被回答，新循环仍会继续运行——循环永远不会因等待人类而阻塞。详情请查看
```
references/feedback.md
```
。
收件箱（人类→Agent推送）。
```
inbox.md
```
是用户向Agent发送调整指令的地方：SKIP（跳过）、PRIORITIZE（优先处理）、ADD（添加）、STOP（停止）、DIRECTION（调整方向）、NOTE（备注），或是自然语言指令。每个循环的探索阶段都会读取此文件。详情请查看
```
references/feedback.md
```
。
触发器抽象。三种触发器类型——
```
schedule
```
（每隔N分钟）、
```
conditional
```
（轮询外部状态，如
```
gh pr list
```
）、
```
webhook
```
（事件驱动）。Layer 2和Layer 1保持不变；仅Layer 3不同。示例中的默认设置是间隔2分钟的
```
schedule
```
触发器——请查看下方的成本说明。详情请查看
```
references/trigger.md
```
。
控制信号。执行
```
touch .paused
```
/
```
rm .paused
```
来暂停和恢复；执行
```
touch .stop_after_current
```
来在当前循环结束后优雅停止；执行
```
pkill -f trigger.sh
```
+
```
tmux kill-session
```
来强制停止。基于文件的信号，无需新协议。详情请查看
```
references/control.md
```
。
通过git worktree实现并行任务。如需在同一项目上运行多个perpetuum任务，使用
```
git worktree add
```
为每个任务创建独立的分支和目录。
```
_meta.md
```
记录worktree元数据。详情请查看
```
references/worktree.md
```
。
文件即契约。
```
plan.md
```
由Agent维护（人类应通过
```
inbox.md
```
提交修改请求）；
```
inbox.md
```
由人类编写；
```
escalations.md
```
是双向沟通渠道，遵循“Agent编写Open项，人类编写Resolved项”的约定。文件系统层面不做强制约束——这是一种约定，而非锁机制。详情请查看
```
references/feedback.md
```
。

Task layout

任务目录结构

When a task is initialized:

<project-or-worktree>/
└── .perpetuum/
    └── <task-name>/
        ├── _meta.md             worktree/branch metadata
        ├── trigger.sh           per-task; adjusted during setup
        ├── prompts/
        │   ├── 1_explore.md     prompt 1: plan
        │   └── 2_execute.md     prompt 2: dispatch + judge + record
        ├── plan.md              agent-maintained state machine
        ├── inbox.md             human → agent
        ├── escalations.md       agent ↔ human
        ├── trigger.log
        └── state/
            └── .cycle_done_*    per-cycle sync flags (transient)

Any file matching

prompts/[0-9]+(\.[0-9]+)?_*.md

is fed to Layer 2 in lexical order, one per cycle phase. Default is 2 (

prompts/1_explore.md

prompts/2_execute.md

); add

prompts/3_reflect.md

for a reflection phase,

prompts/1.5_check.md

to insert a step between, etc.

Keeping prompts in a subdirectory separates editable templates from runtime state (

plan.md

inbox.md

escalations.md

) — users can edit the

prompts/

dir freely without mixing prompt edits and state edits.

初始化任务后，目录结构如下：

<project-or-worktree>/
└── .perpetuum/
    └── <task-name>/
        ├── _meta.md             worktree/分支元数据
        ├── trigger.sh           任务专属脚本；设置过程中可调整
        ├── prompts/
        │   ├── 1_explore.md     提示词1：规划
        │   └── 2_execute.md     提示词2：调度 + 判断 + 记录
        ├── plan.md              Agent维护的状态机
        ├── inbox.md             人类 → Agent
        ├── escalations.md       Agent ↔ 人类
        ├── trigger.log
        └── state/
            └── .cycle_done_*    循环同步标记（临时文件）

所有匹配

prompts/[0-9]+(\.[0-9]+)?_*.md

格式的文件都会按字典序依次传递给Layer 2，每个文件对应一个循环阶段。默认包含2个文件（

prompts/1_explore.md

、

prompts/2_execute.md

）；可添加

prompts/3_reflect.md

来增加反思阶段，或添加

prompts/1.5_check.md

来在两个阶段之间插入新步骤。

将提示词放在子目录中，可将可编辑模板与运行时状态（

plan.md

inbox.md

escalations.md

）分离——用户可自由编辑

prompts/

目录，无需混淆提示词编辑和状态编辑。

What the state files actually look like

状态文件示例

Use these as templates when you generate or judge file content. Match the structure; render the content in the user's language per the language rule below.

plan.md

— agent-maintained:

markdown

undefined

生成或判断文件内容时，请以此为模板。匹配结构；根据下方的语言规则，使用用户的语言生成内容。

plan.md

—— Agent维护：

markdown

undefined

Pending

[auth] test expired token refresh
[parse] malformed XML input

[auth] test expired token refresh
[parse] malformed XML input

Done

(cycle 3) [auth] login flow
- operation: cli login --user x
- observed: 200 + valid JWT
- status: PASS
(cycle 5) [parse] xss in error envelope
- status: [FIXED] commit:abc1234


`inbox.md` — user writes; agent reads and absorbs every cycle:

```markdown

(cycle 3) [auth] login flow
- operation: cli login --user x
- observed: 200 + valid JWT
- status: PASS
(cycle 5) [parse] xss in error envelope
- status: [FIXED] commit:abc1234


`inbox.md` —— 用户编写；Agent每个循环都会读取并处理：

```markdown

Pending

SKIP: postgres backend, not shipping
PRIORITIZE: PR #123 first
NOTE: I'm OOO Friday, no urgent escalations

SKIP: postgres backend, not shipping
PRIORITIZE: PR #123 first
NOTE: I'm OOO Friday, no urgent escalations

Processed

(cycle 6) SKIP applied — removed 4 postgres items from plan.md


`escalations.md` — agent writes `## Open` items; user fills
`## Resolved`:

```markdown

(cycle 6) SKIP applied — removed 4 postgres items from plan.md


`escalations.md` —— Agent编写`## Open`项；用户填写`## Resolved`项：

```markdown

Open

(cycle 4) off-by-one in --range flag

A: 1-based inclusive (matches head/tail/sed) B: 0-based half-open (matches array semantics in most languages) C: leave both, document the discrepancy

Resolved

undefined

undefined

Setting up a new task

设置新任务

Setup is the longest interaction this skill has with the user. Don't rush it — a mis-launched perpetuum task wastes hours and tokens. Walk the user through the steps below. Detail for each step lives in

references/setup.md

; this section is the overview.

设置是此技能与用户交互最长的环节。请勿仓促操作——错误启动的perpetuum任务会浪费数小时时间和token。请引导用户完成以下步骤。每个步骤的详细说明请查看

references/setup.md

；本部分为概述。

1. Prerequisites — confirm both are present

1. 前置条件——确认两项均已满足

These are the only two things the skill depends on. Don't proceed if either is missing.

cc-use
skill must be available in whichever skill environment the current host agent uses. Layer 2 of perpetuum dispatches every unit of work to a fresh inner agent via
```
cc-use
```
. Without it, there is no Layer 1.
Install it the same way perpetuum was installed:
bash
```
npx skills add zc277584121/cc-use --all -g
```
After installing, the user may need to reload skills before the current agent can see it. The exact command varies by host agent — Claude Code has
```
/reload-skills
```
; other agents may need a TUI restart. Follow that agent's docs.
tmux
must be installed locally. Verify with
```
tmux -V
```
. The middle agent (Layer 2) lives in a persistent tmux session for the duration of the task.

cc-use

is missing, ask the user whether to install it. If

tmux

is missing, point them to their package manager and stop — perpetuum cannot run without it.

这是此技能仅有的两个依赖项。如果缺少任何一项，请不要继续。

cc-use
技能必须在当前宿主Agent使用的技能环境中可用。perpetuum的Layer 2会通过
```
cc-use
```
将每个工作单元调度给全新的内部Agent。没有它，就无法运行Layer 1。
按照安装perpetuum的方式安装它：
bash
```
npx skills add zc277584121/cc-use --all -g
```
安装完成后，用户可能需要重新加载技能，当前Agent才能识别它。具体命令因宿主Agent而异——Claude Code使用
```
/reload-skills
```
；其他Agent可能需要重启TUI。请遵循对应Agent的文档。
**
```
tmux
```
**必须已在本地安装。通过
```
tmux -V
```
验证。中间Agent（Layer 2）会在任务持续期间运行在持久化的tmux会话中。

如果缺少

cc-use

，请询问用户是否要安装它。如果缺少

tmux

，请引导用户通过包管理器安装，然后停止操作——perpetuum无法在没有tmux的情况下运行。

2. Suitability gate — judge fit with the user

2. 适用性评估——判断任务是否适配

Not every task fits this architecture. A bad fit wastes the user's tokens. Don't skip this step.

Strong fit: "find more of X" / "converge toward Y" / "watch for Z" tasks. Dimensional structure. Per-finding independence.
Poor fit: one-shot tasks; strongly linear builds; tasks needing synchronous human decisions; tasks shorter than ~30 minutes total.

If the task is borderline, reshape it with the user (e.g. turn "refactor X" into "scan X module-by-module and surface one smell per module"), or recommend a non-perpetuum approach (single agent run, one-off

cc-use

dispatch). Full questionnaire in

references/setup.md

并非所有任务都适合此架构。适配性差的任务会浪费用户的token。请勿跳过此步骤。

高度适配：“查找更多X” / “向Y收敛” / “监控Z”类任务。具有维度结构，每个发现相互独立。
适配性差：一次性任务；强线性构建任务；需要同步人工决策的任务；总时长短于约30分钟的任务。

如果任务处于边界情况，请与用户一起调整任务形式（例如将“重构X”改为“逐个模块扫描X，每个模块发现一个问题”），或推荐非perpetuum方案（单次Agent运行、一次性

cc-use

调度）。完整问卷请查看

references/setup.md

。

3. Pick an example and create the task directory

3. 选择示例并创建任务目录

Look at

examples/

for the closest task shape and copy that directory's contents to

<project>/.perpetuum/<task-name>/

. Then customize:

```
prompts/1_explore.md
```
— replace generic dimension hints with this project's actual axes; use the user's language
```
prompts/2_execute.md
```
— set the
```
--project
```
absolute path; adjust commit-style and classification policy to the project
```
trigger.sh
```
— set
```
MIDDLE_SESSION
```
to something unique, adjust
```
MAX_ITER
```
, decide trigger type (schedule / conditional / webhook). The script also reads an
```
AGENT_CMD
```
env var: default is Claude Code, but users on Codex / Cursor / etc. can override before launch (e.g.
```
AGENT_CMD="codex --dangerously-bypass-approvals-and-sandbox"
```
or the safer
```
AGENT_CMD="codex --full-auto"
```
). Mention this explicitly to non-Claude-Code users.
```
_meta.md
```
— fill in worktree path, branch, parent repo, merge target
Leave
```
plan.md
```
,
```
inbox.md
```
,
```
escalations.md
```
empty (their skeletons are already in the example)
```
chmod +x trigger.sh
```

For parallel tasks on the same project, set up via

git worktree

first — see

references/worktree.md

在

examples/

中找到最匹配的任务类型，将该目录的内容复制到

<project>/.perpetuum/<task-name>/

。然后进行自定义：

```
prompts/1_explore.md
```
—— 将通用维度提示替换为项目的实际维度；使用用户的语言
```
prompts/2_execute.md
```
—— 设置
```
--project
```
绝对路径；根据项目调整提交风格和分类策略
```
trigger.sh
```
—— 将
```
MIDDLE_SESSION
```
设置为唯一值，调整
```
MAX_ITER
```
，选择触发器类型（schedule / conditional / webhook）。脚本还会读取
```
AGENT_CMD
```
环境变量：默认是Claude Code，但使用Codex / Cursor等工具的用户可在启动前覆盖此变量（例如
```
AGENT_CMD="codex --dangerously-bypass-approvals-and-sandbox"
```
或更安全的
```
AGENT_CMD="codex --full-auto"
```
）。请明确告知非Claude Code用户此选项。
```
_meta.md
```
—— 填写worktree路径、分支、父仓库、合并目标
保留
```
plan.md
```
、
```
inbox.md
```
、
```
escalations.md
```
为空（示例中已包含它们的框架）
```
chmod +x trigger.sh
```

如需在同一项目上运行并行任务，请先通过

git worktree

设置——请查看

references/worktree.md

。

4. Cost / cadence confirmation — say this out loud

4. 成本/频率确认——明确告知用户

The default

SLEEP_BETWEEN_CYCLES

in schedule-type examples is 2 minutes, intended for full throttle. With

MAX_ITER=20

, the loop burns through all 20 cycles in a few hours; each cycle costs O(a few inner-agent dispatches via

cc-use

Before launching, ask the user:

Do they have token budget for ~MAX_ITER cycles at this cadence?
Are they on a usage-based plan (cost matters) or a flat plan (rate limits matter)?
Will they babysit the first few cycles, or launch and walk away?

If they hesitate: bump

SLEEP_BETWEEN_CYCLES

(1800 = 30 min, 3600 = 1 hour), reduce

MAX_ITER

, or switch to the

conditional

trigger pattern (only fires when there's real new work).

Don't skip this step. A "$X overnight" surprise is the easiest way to make the user pull the plug on perpetuum forever.

示例中schedule类型触发器的默认

SLEEP_BETWEEN_CYCLES

为2分钟，旨在全速运行。如果

MAX_ITER=20

，循环会在数小时内完成所有20个周期；每个周期的成本约为几次通过

cc-use

调度内部Agent的费用。

启动前，请询问用户：

他们是否有足够的token预算来支持此频率下的约MAX_ITER个周期？
他们使用的是按使用量付费的方案（成本重要）还是固定套餐（速率限制重要）？
他们会监控前几个周期，还是启动后就离开？

如果用户有顾虑：增加

SLEEP_BETWEEN_CYCLES

（1800=30分钟，3600=1小时）、减少

MAX_ITER

，或切换到

conditional

触发器模式（仅当有实际新工作时才触发）。

请勿跳过此步骤。“一夜之间花费X美元”的意外情况会让用户彻底放弃perpetuum。

5. Optional first-cycle trial

5. 可选的首次循环试用

For first-time users, suggest a trial with

MAX_ITER=1

bash

sed -i.bak 's/^MAX_ITER=.*/MAX_ITER=1/' .perpetuum/<task>/trigger.sh
.perpetuum/<task>/trigger.sh        # foreground, watch one cycle
mv .perpetuum/<task>/trigger.sh.bak .perpetuum/<task>/trigger.sh

Inspect

plan.md

escalations.md

, and

git log

after the trial. Adjust prompts if anything went sideways before running 20 cycles.

对于首次使用的用户，建议进行

MAX_ITER=1

的试用：

bash

sed -i.bak 's/^MAX_ITER=.*/MAX_ITER=1/' .perpetuum/<task>/trigger.sh
.perpetuum/<task>/trigger.sh        # 前台运行，观察一个循环
mv .perpetuum/<task>/trigger.sh.bak .perpetuum/<task>/trigger.sh

试用结束后，检查

plan.md

、

escalations.md

和

git log

。如果出现问题，请调整提示词，再运行20个周期。

6. Suggest

.gitignore

and launch

6. 建议添加到

.gitignore

并启动

bash

echo '.perpetuum/' >> <project>/.gitignore   # unless the user wants state in git
nohup .perpetuum/<task>/trigger.sh > /dev/null 2>&1 &

Or hand the launch command to the user to start when they're ready.

bash

echo '.perpetuum/' >> <project>/.gitignore   # 除非用户希望将状态存入git
nohup .perpetuum/<task>/trigger.sh > /dev/null 2>&1 &

或者将启动命令交给用户，让他们在准备好后自行启动。

Known Codex compatibility quirks (already handled)

已知的Codex兼容性问题（已处理）

For Codex CLI users, two tmux/TUI quirks are handled by the default

trigger.sh

. No user action needed; documented here so you know what the extra send-key lines are for:

Codex tmux "Enter doesn't commit" bug (openai/codex#12645).
```
send_prompt
```
uses the same five-step sequence cc-use uses (
```
C-u
```
→
```
paste-buffer -d
```
→
```
Enter
```
→
```
C-m
```
→
```
Enter
```
).
"Create a plan?" popup on complex prompts. Codex pops this on long planning-style prompts (our
```
1_explore.md
```
triggers it).
```
send_prompt
```
detects Codex via
```
$AGENT_CMD
```
and sends
```
Escape
```
after paste to dismiss it.

The execute prompts in

examples/

instruct the middle agent to escalate any cc-use failure rather than work around it locally — surface it as a blocked-on-environment item in

escalations.md

and stop the cycle, do not fake a fresh inner context within your own conversation.

对于Codex CLI用户，默认的

trigger.sh

已处理两个tmux/TUI问题。无需用户操作；此处记录是为了让你了解额外的send-key行的作用：

Codex tmux“回车不提交”Bug (openai/codex#12645)。
```
send_prompt
```
使用与cc-use相同的五步序列（
```
C-u
```
→
```
paste-buffer -d
```
→
```
Enter
```
→
```
C-m
```
→
```
Enter
```
）。
复杂提示词弹出“创建计划？”窗口。当提示词较长且涉及规划时（我们的
```
1_explore.md
```
会触发此问题），Codex会弹出此窗口。
```
send_prompt
```
会通过
```
$AGENT_CMD
```
检测Codex，并在粘贴后发送
```
Escape
```
来关闭窗口。

示例中的执行提示词会指示中间Agent升级任何cc-use失败，而非在本地解决——将其作为

escalations.md

中依赖环境的阻塞项提出，并停止循环，不要在对话中伪造全新的内部上下文。

Core invariants (do not violate)

核心不变量（请勿违反）

These are the things that keep the loop honest. Don't weaken them when adjusting prompts or scripts:

Every accepted finding becomes a local
```
git commit
```
.
```
plan.md
```
is agent-maintained; humans route changes through
```
inbox.md
```
.
Layer 1 always runs in fresh context (per
```
cc-use
```
delegate, not a reused inner session within a cycle).
Layer 2's prompts are atomic and lexically ordered; don't fuse them.
Sync uses
```
.cycle_done_*
```
flag + tmux silence fallback + total timeout — all three are needed; don't drop one.

这些是保持循环可靠性的关键。调整提示词或脚本时，请不要削弱它们：

每个被接受的发现都会成为本地
```
git commit
```
。
```
plan.md
```
由Agent维护；人类应通过
```
inbox.md
```
提交修改请求。
Layer 1始终在全新上下文中运行（通过
```
cc-use
```
委托，而非在循环中重用内部会话）。
Layer 2的提示词是原子性的，按字典序排序；请勿合并它们。
同步使用
```
.cycle_done_*
```
标记 + tmux静默 fallback + 总超时——三者缺一不可；请勿省略任何一个。

After-setup briefing

设置后说明

After launching, walk the user through these in their language. The user just handed a coding agent the keys to their codebase; they need to know how to drive.

How a cycle runs. Trigger fires → middle agent reads
```
plan.md
```
/
```
inbox.md
```
→ pastes prompt 1 to plan, then prompt 2 to dispatch via
```
cc-use
```
→ judges each result → commits, escalates, or records. Then sleep, repeat. The whole thing keeps going across cycles, restarts, and your absence.
What they can edit, and how.
- ```
inbox.md
```
  — yes, anytime, write a one-liner under
```
## Pending
```
- ```
escalations.md
```
  — yes, write answers in
```
## Resolved
```
- ```
prompts/1_explore.md
```
  /
```
prompts/2_execute.md
```
  — yes, the next cycle picks up edits
- ```
trigger.sh
```
  — yes for cadence /
```
MAX_ITER
```
- ```
plan.md
```
  — avoid, agent-owned; route changes through
```
inbox.md
```
- ```
_meta.md
```
  — static after setup

Talk to you or edit files — both work. They can say things in natural language to the host agent and you translate to file operations; or they can edit files directly in their editor. Make both paths explicit; some users prefer one, some the other.

Translation table for common natural-language requests (English phrasings shown — map equivalent intent in any user language to the same operation):

User intent	You do
"pause" / "stop for now" / "hold on"	`touch .perpetuum/<task>/.paused`
"resume" / "keep going" / "start again"	`rm .perpetuum/<task>/.paused`
"stop gracefully" / "finish this cycle and stop"	`touch .perpetuum/<task>/.stop_after_current`
"kill it" / "force stop" / "just stop"	`pkill -f trigger.sh ; tmux kill-session -t middle-<task>`
"skip X" / "don't bother with X"	append `SKIP: X` to `inbox.md` `## Pending`
"prioritize Y" / "Y first"	append `PRIORITIZE: Y` to `inbox.md`
"add a test/scan for Z"	append `ADD: Z` to `inbox.md`
"change direction to W"	append `DIRECTION: W` to `inbox.md`
"for question X, pick option A"	edit the matching `escalations.md` Open item, add the answer, move to `## Resolved`
"what's the status?" / "what's it doing?"	tail `trigger.log` + summarize `plan.md` Pending/Done counts + list any unresolved escalations

Reset the cost expectation. Reiterate what
```
SLEEP_BETWEEN_CYCLES
```
and
```
MAX_ITER
```
are set to and what that implies for spend over the next N hours. The cost conversation in step 4 happened before they knew the system; remind them now.

Don't skip the briefing. A user who doesn't know they can pause and edit

inbox.md

will

pkill

the loop in panic the first time they want to change anything.

启动后，请用用户的语言引导他们了解以下内容。用户刚刚将代码库的控制权交给了编码Agent；他们需要知道如何操作。

循环运行流程。触发器触发 → 中间Agent读取
```
plan.md
```
/
```
inbox.md
```
→ 粘贴提示词1进行规划，然后粘贴提示词2通过
```
cc-use
```
调度 → 判断每个结果 → 提交、升级或记录。之后进入休眠，重复此过程。整个循环会持续运行，跨越多个周期、重启，甚至在你不在场时也能继续。
可编辑内容及方式
- ```
inbox.md
```
  —— 是，随时可编辑，在
```
## Pending
```
  下添加单行指令
- ```
escalations.md
```
  —— 是，在
```
## Resolved
```
  中写入答案
- ```
prompts/1_explore.md
```
  /
```
prompts/2_execute.md
```
  —— 是，下一个循环会应用修改
- ```
trigger.sh
```
  —— 是，可调整频率 /
```
MAX_ITER
```
- ```
plan.md
```
  —— 请勿编辑，由Agent维护；请通过
```
inbox.md
```
  提交修改请求
- ```
_meta.md
```
  —— 设置后为静态文件

与你对话或直接编辑文件——两种方式都可行。用户可以用自然语言向宿主Agent发送请求，由你转换为文件操作；也可以直接在编辑器中编辑文件。请明确告知用户两种方式；有些用户偏好其中一种。

常见自然语言请求的转换表（显示英文表述——将任何用户语言中的等效意图映射到相同操作）：

用户意图	你需要执行的操作
"暂停" / "先停一下" / "等一等"	`touch .perpetuum/<task>/.paused`
"恢复" / "继续" / "重新开始"	`rm .perpetuum/<task>/.paused`
"优雅停止" / "完成当前循环后停止"	`touch .perpetuum/<task>/.stop_after_current`
"终止它" / "强制停止" / "立刻停止"	`pkill -f trigger.sh ; tmux kill-session -t middle-<task>`
"跳过X" / "不用管X"	在 `inbox.md` 的 `## Pending` 中添加 `SKIP: X`
"优先处理Y" / "先做Y"	在 `inbox.md` 中添加 `PRIORITIZE: Y`
"添加对Z的测试/扫描"	在 `inbox.md` 中添加 `ADD: Z`
"调整方向为W"	在 `inbox.md` 中添加 `DIRECTION: W`
"对于问题X，选择选项A"	编辑 `escalations.md` 中对应的Open项，添加答案，移至 `## Resolved`
"状态如何？" / "它在做什么？"	查看 `trigger.log` 末尾 + 总结 `plan.md` 中Pending/Done的数量 + 列出未解决的升级请求

重新确认成本预期。再次强调
```
SLEEP_BETWEEN_CYCLES
```
和
```
MAX_ITER
```
的设置，以及这意味着未来N小时内的花费。步骤4中的成本对话是在用户了解系统之前进行的；现在请提醒他们。

请勿跳过此说明环节。不知道可以暂停和编辑

inbox.md

的用户，在第一次想要更改内容时会惊慌地执行

pkill

终止循环。

Language rule

语言规则

The markdown files this skill generates (

plan.md

inbox.md

escalations.md

, the two prompt files, and any text written into them at runtime) are for the user to read.

If the user speaks any non-English language and doesn't explicitly ask for another, generate all human-facing content (prompts, plan items, escalation entries, status messages) in that language.

Boundary: this rule applies only to perpetuum's own files and to the perpetuum ↔ human interaction. It does not apply to the project's own code, code comments, commit messages, documentation, or anything the inner agent produces as part of the actual task work — those follow the project's existing conventions.

File names, config keys, shell variables, and scripts are always English (cross-language stable).

此技能生成的markdown文件（

plan.md

、

inbox.md

、

escalations.md

、两个提示词文件，以及运行时写入这些文件的任何文本）供用户阅读。

如果用户使用非英语语言，且未明确要求使用其他语言，请使用该语言生成所有面向人类的内容（提示词、计划项、升级请求、状态消息）。

边界：此规则仅适用于perpetuum自身的文件以及perpetuum与人类的交互。它不适用于项目自身的代码、代码注释、提交信息、文档，或是内部Agent作为实际任务工作的一部分生成的任何内容——这些内容遵循项目现有的约定。

文件名、配置键、shell变量和脚本始终使用英文（跨语言稳定）。

perpetuum

Original

Translation

perpetuum

perpetuum

When to invoke this skill

何时调用此技能

Route by intent

按意图路由

How it works (architecture in one screen)

工作原理（架构概览）

Mechanisms (one paragraph each)

核心机制（各机制摘要）

Task layout

任务目录结构

What the state files actually look like

状态文件示例

Pending

Pending

Done

Done

Pending

Pending

Processed

Processed

Open

Open

(cycle 4) off-by-one in --range flag

(cycle 4) off-by-one in --range flag

Resolved

Resolved

Setting up a new task

设置新任务

1. Prerequisites — confirm both are present

1. 前置条件——确认两项均已满足

2. Suitability gate — judge fit with the user

2. 适用性评估——判断任务是否适配

3. Pick an example and create the task directory

3. 选择示例并创建任务目录

4. Cost / cadence confirmation — say this out loud

4. 成本/频率确认——明确告知用户

5. Optional first-cycle trial

5. 可选的首次循环试用

6. Suggest .gitignore and launch

6. 建议添加到.gitignore并启动

Known Codex compatibility quirks (already handled)

已知的Codex兼容性问题（已处理）

Core invariants (do not violate)

核心不变量（请勿违反）

After-setup briefing

设置后说明

Language rule

语言规则

6. Suggest
`.gitignore`
and launch

6. 建议添加到
`.gitignore`
并启动