--- name: perpetuum description: > Set up, supervise, and control a persistent multi-layer "explore → execute → escalate" agent loop on a project. Use whenever a user asks to keep an agent running on a task across sessions or days — finding bugs, polishing writing, distilling a style, watching feeds, scanning for gaps, or any task whose value grows with how many findings the agent produces. Also use when the user wants to inspect, pause, resume, stop, or send a new instruction to an already-running perpetuum task. allowed-tools: - Bash - Read - Write - Edit - Glob - Grep --- # 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. **What ships here is a framework, not fixed source code.** The architecture (three layers, two prompts, three trigger families, file-as-contract, async escalation) is what's fixed and what makes the loop reliable. Everything else — the wording in `prompts/1_explore.md` and `prompts/2_execute.md`, the bash in `trigger.sh`, the classification logic the middle agent applies, even the exact structure of `plan.md` / `inbox.md` / `escalations.md` — are **templates to adapt to the user's specific task, domain, project, and language**. When you set up a new task with the user, treat the files copied from `examples/` as starting points and rewrite them to fit. Don't treat them as immutable scripts. This is what keeps a small skill flexible enough to handle adversarial testing, ML hyperparameter sweeps, PR review, migrations, and style polish without code changes. 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. ## 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. ## 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` | ## 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. ## Mechanisms (one paragraph each) Each mechanism is summarized here; for the full procedure see the linked reference. - **Ratchet (monotonic progress).** The middle agent judges each Layer-1 proposal *before* committing; rejected proposals never become commits. Accepted ones land as a local `git commit`, giving the branch a clean append-only log that doubles as the durability mechanism across sessions. Same family of idea as Karpathy's AutoResearch ratchet, with the judge slightly earlier in the loop. 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`. ## Task layout When a task is initialized: ``` / └── .perpetuum/ └── / ├── _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. ### 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 ## Pending - [ ] [auth] test expired token refresh - [ ] [parse] malformed XML input ## Done - [x] (cycle 3) [auth] login flow - operation: cli login --user x - observed: 200 + valid JWT - status: PASS - [x] (cycle 5) [parse] xss in error envelope - status: [FIXED] commit:abc1234 ``` `inbox.md` — user writes; agent reads and absorbs every cycle: ```markdown ## Pending - 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 ## 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 ``` ## 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. ### 1. Prerequisites — confirm both are present 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. If `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. ### 2. Suitability gate — judge fit with the user 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`. ### 3. Pick an example and create the task directory Look at `examples/` for the closest task shape and copy that directory's contents to `/.perpetuum//`. 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`. ### 4. Cost / cadence confirmation — say this out loud 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. ### 5. Optional first-cycle trial For first-time users, suggest a trial with `MAX_ITER=1`: ```bash sed -i.bak 's/^MAX_ITER=.*/MAX_ITER=1/' .perpetuum//trigger.sh .perpetuum//trigger.sh # foreground, watch one cycle mv .perpetuum//trigger.sh.bak .perpetuum//trigger.sh ``` Inspect `plan.md`, `escalations.md`, and `git log` after the trial. Adjust prompts if anything went sideways before running 20 cycles. ### 6. Suggest `.gitignore` and launch ```bash echo '.perpetuum/' >> /.gitignore # unless the user wants state in git nohup .perpetuum//trigger.sh > /dev/null 2>&1 & ``` Or hand the launch command to the user to start when they're ready. ## Known Codex compatibility quirks (already handled) 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: 1. **Codex tmux "Enter doesn't commit" bug** ([openai/codex#12645](https://github.com/openai/codex/issues/12645)). `send_prompt` uses the same five-step sequence cc-use uses (`C-u` → `paste-buffer -d` → `Enter` → `C-m` → `Enter`). 2. **"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. ## Core invariants (do not violate) These are the things that keep the loop honest. Don't weaken them when adjusting prompts or scripts: 1. Every accepted finding becomes a local `git commit`. 2. `plan.md` is agent-maintained; humans route changes through `inbox.md`. 3. Layer 1 always runs in fresh context (per `cc-use` delegate, not a reused inner session within a cycle). 4. Layer 2's prompts are atomic and lexically ordered; don't fuse them. 5. Sync uses `.cycle_done_*` flag + tmux silence fallback + total timeout — all three are needed; don't drop one. ## 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//.paused` | | "resume" / "keep going" / "start again" | `rm .perpetuum//.paused` | | "stop gracefully" / "finish this cycle and stop" | `touch .perpetuum//.stop_after_current` | | "kill it" / "force stop" / "just stop" | `pkill -f trigger.sh ; tmux kill-session -t middle-` | | "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. ## 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).

Perpetuum

Browse Skills by Category