Perpetuum
Run long-lived scheduled agent work in a git worktree with documented metadata and human escalation queues.
Overview
Perpetuum is a journey-wide agent skill that structures scheduled multi-cycle agent work in git worktrees with metadata and human-reviewed escalations before merging.
Install
npx skills add https://github.com/zc277584121/perpetuum --skill perpetuumWhat is this skill?
- Task metadata block: worktree path, branch, merge target, schedule trigger, expected cadence
- Human-owned escalation queue: open questions with options; human moves items to Resolved
- Designed for schedule-driven cycles (example basis: adversarial-testing)
- Explicit parent repo and started-from SHA lineage for safe parallel agent work
- Agent surfaces trade-offs; humans edit decisions in place as the control signal
- Example cadence: ~40 min per cycle, ~20 cycles, ~2 days end-to-end
- Trigger type documented: schedule
Adoption & trust: 1 installs on skills.sh.
What problem does it solve?
Long-running agent tasks lose context, bypass git safety, or make irreversible calls because there is no shared template for cycles and human decisions.
Who is it for?
Indie builders running schedule-triggered agent loops (testing, hardening, refactors) who want explicit human gates on ambiguous choices.
Skip if: One-off prompts, serverless cron without a repo, or teams that forbid worktrees and autonomous multi-hour agent runs.
When should I use this skill?
User starts a long-running scheduled agent task in a worktree and needs metadata plus escalation workflow.
What do I get? / Deliverables
You get a documented worktree task with open escalations resolved by you and a merge-ready branch once cycles complete.
- Filled task metadata section for the run
- Open and Resolved escalation log with human decisions
- Branch-ready diff after completed cycles
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Bootstrap a worktree task with branch, parent repo path, and schedule trigger before enabling nightly agent cycles.
Run adversarial-testing cycles until escalations about API semantics are human-resolved.
Soak-test a feature branch over ~20 cycles while logging open questions without auto-merging.
Keep a low-frequency scheduled agent on a fix branch with explicit merge target and resolved escalation history.
How it compares
Workflow meta-skill for sustained agent runs—not a CI job definition or a single-shot debugging checklist.
Common Questions / FAQ
Who is perpetuum for?
Solo and indie builders orchestrating recurring agent cycles in a real git worktree who need written metadata and a human-owned escalation log.
When should I use perpetuum?
During Build when standing up agent tooling, in Validate for long adversarial or prototype runs, in Ship for soak testing, or in Operate when iterating on production fixes on a schedule.
Is perpetuum safe to install?
It implies git write access and autonomous edits in an isolated worktree; review the Security Audits panel on this page and keep merge targets protected until you review diffs.
SKILL.md
READMESKILL.md - Perpetuum
# Task metadata > Filled in once during setup. Reference only — perpetuum does not > rely on these fields at runtime, but humans and future agents will. - **task name**: <TASK_NAME> - **created**: <YYYY-MM-DD> - **worktree path**: <absolute path of this worktree> - **branch**: <current git branch> - **started from**: <branch>@<sha> - **parent repo**: <absolute path of parent repo, same as worktree path if no worktree used> - **merge target**: <branch the user intends to merge to, or "n/a"> - **trigger type**: schedule - **example basis**: adversarial-testing - **expected cadence**: every ~40 min, ~20 cycles total, ~2 days end-to-end # Escalations > Questions the agent surfaces for human judgment. Each item has > context + the specific question + 2–3 options with trade-offs. > > When you're ready to answer, edit the item in place to add your > decision, then move it to `## Resolved`. The agent does NOT move items > here — moving is the human's signal of "I've decided". ## Open <!-- Example (delete when you have real ones): ### (cycle 3-abc1234) off-by-one between two CLI subcommands **Context:** Subcommand A reports line ranges as `[start, end]` 1-based inclusive. Subcommand B accepts `--range start:end` as 0-based half-open. Feeding A's output directly into B silently drops the first line. This is the kind of papercut that erodes user trust without ever producing a hard error. **Question:** Align on which convention? This is a public-contract decision affecting any consumer of the CLI's structured output. **Options:** - **A (recommended):** Standardize on 1-based inclusive across both commands. Smallest change for tooling consumers, matches common shell tools (head, tail, sed). Documented breaking change. - **B:** Standardize on 0-based half-open. Matches array semantics in most languages. Larger blast radius for existing users. - **C:** Leave both, document the off-by-one. Cheapest but most surprising. --> ## Resolved <!-- Human moves answered items here with their decision. --> # Inbox > Write your instructions / nudges / context under "## Pending". The agent > reads this at the start of every cycle and moves processed items to > "## Processed". Plain natural language works; the verbs below are > shorthand the agent recognizes. > Recommended verbs (any one works, mix freely): > `SKIP:` `PRIORITIZE:` `ADD:` `STOP:` `DIRECTION:` `NOTE:` ## Pending <!-- Example items (delete these and write your own): - SKIP: postgres backend swap — I'm not going to support PG, drop those tests - PRIORITIZE: PR #123 just landed, look at it before backlog - ADD: a dimension — behavior under network partition (kill milvus mid-add) - NOTE: I'm OOO tomorrow, don't escalate anything I'd want to discuss --> ## Processed <!-- Agent moves processed items here with a one-line note on how they were applied to the plan. --> # Plan > Agent-maintained state machine. Users should **avoid editing this > directly** — route changes through `inbox.md`. The system won't crash > if you edit, but format drift may confuse the next cycle. ## Pending <!-- New items appended by prompts/1_explore.md each cycle. Format: - [ ] [<dimension>/<sub>] short description --> ## Done <!-- Completed items moved here by prompts/2_execute.md. Format: - [x] (cycle <id>) [<dimension>] short title - operation: ... - observed: ... - status: PASS | [FIXED] commit:abc1234 | [FAILED] reason | [BLOCKED] reason --> # Task: plan this cycle's exploration (do not execute) You can use any API keys / credentials available in `~/.bashrc` during later test phases. They are available to the inner agent too. Walk through these steps **and only these steps**: 1. Read the test history file (`.perpetuum/<task>/plan.md`) to know what was tested before and what fixes were already made. 2. Check the inbox (`.perpetuum/<task>/inbox.md`): - For each item in `## Pending`, decide how to act (SKIP / PRIORITIZE / ADD / STOP / DIRECTION / NOTE — treat pla