# Long Run

> >

- **Type:** Skill
- **Install:** `agentstack add skill-reidworks-io-reidworks-skills-long-run`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [reidworks-io](https://agentstack.voostack.com/s/reidworks-io)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [reidworks-io](https://github.com/reidworks-io)
- **Source:** https://github.com/reidworks-io/reidworks-skills/tree/main/plugins/reidworks-core/skills/long-run
- **Website:** https://reidworks-io.github.io/reidworks-skills/

## Install

```sh
agentstack add skill-reidworks-io-reidworks-skills-long-run
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Long Run — autonomous multi-agent build orchestrator

Distilled from a working pattern (weekend SDK + monorepo build, 14+ milestones, file-based
state, `/loop`-driven). Build the harness; the user owns the kickoff.

## Operating model

- **One orchestrator, many workers.** A `/loop` cycle re-fires every N minutes. Each cycle the
  orchestrator picks the next eligible milestone, spawns a worker via the Agent tool, runs
  gates, merges (or files a block), updates state, exits the turn.
- **State on disk, not in conversation.** Everything that matters across cycles lives in
  `.agents/STATE.md`, `.agents/DIGEST.md`, `.agents/BLOCKED.md`. The orchestrator is stateless
  between cycles and reconstructs from these files every time.
- **Git is the source of truth.** Workers branch, commit, open PRs, squash-merge. The diff is
  the artifact. No deployments, no force pushes.
- **Roadmap is gospel.** Never invent milestones; only execute them.
- **One repo, one prototype.** App, docs, marketing, tests, screenshots all colocated so a
  single PR can update related surfaces atomically.

## Hard prerequisites

Do not proceed to scaffolding until ALL are true. If any is missing, engage the user.

1. **Git repository.** `test -d .git`.
2. **Detailed roadmap** at `.agents/ROADMAP.md` (or equivalent) with explicit per-milestone:
   - `id` (e.g. `M0`, `P2.1`)
   - dependencies (other milestone ids)
   - contract (exact allowed-paths whitelist)
   - DoD (verifiable bullets, not "make it good")
   - model + subagent type
3. **Source-of-truth docs in repo** for the surfaces in scope:
   - `DESIGN.md` if UI work is in scope
   - `VOICE.md` if user-facing copy is in scope
   - architecture doc if SDK/library work is in scope
4. **Quality gates wired up.** A single command that runs typecheck + lint + test + build.
   Workers must pass it before merge.
5. **Deny-list** in `.claude/settings.local.json` blocking deploy commands and force-push.
6. **`.agents/STOP`** convention as kill switch.

## Phase 1 — Pre-flight audit

Run the audit. Report each as ✓ or ✗.

```bash
echo "--- long-run pre-flight ---"
test -d .git && echo "✓ git repo" || echo "✗ not a git repo"
git remote -v | grep -q . && echo "✓ git remote configured" || echo "⚠ no git remote (PR flow falls back to local squash-merge)"
for f in .agents/ROADMAP.md .agents/orchestrator-prompt.md .agents/STATE.md .agents/DIGEST.md .agents/BLOCKED.md; do
  test -f "$f" && echo "✓ $f" || echo "✗ $f"
done
test -f .claude/settings.local.json && grep -q '"deny"' .claude/settings.local.json && echo "✓ deny list" || echo "✗ no deny list"
test -f DESIGN.md && echo "• DESIGN.md present" || echo "• DESIGN.md absent (required if UI in scope)"
test -f VOICE.md && echo "• VOICE.md present" || echo "• VOICE.md absent (required if copy in scope)"
```

If the audit fails on git, stop entirely. If it fails only on harness files, that's expected —
Phase 3 scaffolds them. If the roadmap is missing, jump to Phase 2.

## Phase 2 — Roadmap engagement (only if missing or incomplete)

**Do not auto-generate the roadmap.** It encodes the user's product decisions and the orchestrator
treats it as gospel — generating it without user buy-in poisons the entire run.

Ask the user:

> A long-running orchestrator needs a detailed milestone plan before kickoff. What do you have?
> - A) I have a roadmap doc — let me point you at it
> - B) I have a high-level idea but no milestone plan
> - C) I haven't thought through the project yet

**If A:** ask the path, read it, audit against the per-milestone schema (id, deps, contract,
DoD, model). For each missing field, ask the user to fill it in OR offer to draft a candidate
they review. Do not silently fill gaps.

**If B or C:** stop the skill. Tell the user:

> A long-running build needs an approved spec. Brainstorm the problem first (e.g. via
> `/office-hours` or your team's equivalent), then lock in architecture (e.g. via
> `/plan-eng-review`), then come back. Generating a plan unprompted would burn cycles on
> the wrong work — that call belongs upstream.

When extending a partial spec into per-milestone contracts, for each milestone confirm:

- id + human title
- dependencies (which milestones must finish first)
- allowed-paths whitelist — exact globs the worker may touch (drives the contract-violation check)
- DoD bullets — verifiable, concrete (tests pass, file exists, screenshot committed, coverage ≥ N%)
- which surfaces this touches (sdk / app / docs / marketing) — drives colocation expectations
- model + subagent_type

Rule of thumb: if a one-line shell test cannot verify the DoD, it's not concrete enough.

## Phase 3 — Scaffold the harness (only after the roadmap is locked)

Read the templates bundled with this skill at `references/templates/` and write them into the
repo, substituting `{{placeholders}}` interactively:

- `references/templates/orchestrator-prompt.md` → `.agents/orchestrator-prompt.md`
- `references/templates/STATE.md` → `.agents/STATE.md`
- `references/templates/DIGEST.md` → `.agents/DIGEST.md`
- `references/templates/BLOCKED.md` → `.agents/BLOCKED.md`
- `references/templates/settings.local.json` → `.claude/settings.local.json` (merge if exists)
- `references/templates/ROADMAP-skeleton.md` → starting point if the user is hand-authoring

Required substitutions in the orchestrator prompt (ask the user, don't guess):

- `{{project-name}}`
- `{{gate-command}}` — single shell command that runs typecheck + lint + test + build for the
  whole project (e.g. `pnpm turbo run typecheck lint test build --concurrency=1`)
- `{{source-of-truth-docs}}` — list of docs the orchestrator reads each cycle (DESIGN.md,
  VOICE.md, architecture doc, etc.)
- `{{merge-strategy}}` — `gh pr create + gh pr merge --squash` (default, requires remote) OR
  `local squash-merge to main` (no remote)
- `{{notification-block}}` — paste the Slack block from `references/templates/notify-slack.md`
  if the user wants notifications; otherwise replace with "skip notification".
- `{{rate-limit-policy}}` — default is "write to BLOCKED.md, end turn, next /loop fire retries"

Add to `.gitignore`:

```
.agents/STOP
```

Commit the harness:

```bash
git add .agents/ .claude/settings.local.json .gitignore
git commit -m "chore: scaffold long-run orchestrator harness"
```

## Phase 4 — Asset colocation check

The prototype's app, docs, marketing, tests, and screenshots must live in this repo so they
evolve together. Audit the layout:

```bash
ls -d apps/* packages/* docs/ marketing/ 2>/dev/null
find . -maxdepth 3 -name 'DESIGN.md' -o -name 'VOICE.md' -o -name '*-architecture.md' 2>/dev/null | grep -v node_modules
```

Common shapes that work:

- **Monorepo (SDK + apps):** `packages//`, `apps//`, top-level `DESIGN.md` /
  `VOICE.md` / architecture doc, `.agents/screenshots//`.
- **Single app:** `src/`, `docs/`, optional `marketing/`, `tests/`, `.agents/screenshots//`.

If the user keeps assets elsewhere (Notion docs, Webflow marketing, Figma-only design), flag this:

> The orchestrator can only update files in this repo. {{asset}} lives outside it, so the build
> can't keep it in sync. Bring it into the repo (even as a stub) or accept that {{asset}}
> will drift.

## Phase 5 — Safety rails

Walk through each. Confirm before kickoff.

1. **Third-party API spend caps.** Any runtime API key used by the demo (Anthropic, OpenAI,
   etc.) should be a dedicated key with a hard workspace spend cap. Workers cannot exceed
   what the key allows.
2. **Pre-push hook** at `.git/hooks/pre-push` running the full gate command. Optional but
   recommended — catches regressions before they hit the remote.
3. **Mac wake-lock.** In a separate terminal: `caffeinate -dimsu &`. If the machine sleeps,
   `/loop` dies silently and hours of cycles are lost. **Do not swap `/loop` for `launchd`,
   `cron`, or a remote routine "for resilience"** — you lose live visibility and headless
   `claude -p` has known toolchain traps (see Known traps #1, #4).
4. **Kill switch test.**
   ```bash
   touch .agents/STOP && ls .agents/STOP && rm .agents/STOP
   ```
5. **Notification channel** (if configured) — confirm the orchestrator can reach it before kickoff.

## Phase 6 — Kickoff

Tell the user — do not run this yourself:

```
/loop 45m act as the orchestrator per .agents/orchestrator-prompt.md
```

Default interval: **45 minutes** (balances Anthropic rate-limit recovery against forward
progress). 60 minutes is also fine for smaller cycles. Avoid /`, which is awkward
to follow with `jq` and easy to miss when a worker turn goes sideways. You can't
catch a bad turn until after it lands on `main`.

**The fix:** Run the orchestrator in an *attended* `/loop` in your interactive
terminal. Use `caffeinate` for the wake-lock. Accept that if the session dies
(laptop sleeps without caffeinate, terminal closes), the cycle dies — that's the
trade. The visibility is worth it.

**If you genuinely need unattended overnight:** wrap `claude -p` in `launchd`,
but verify the MCP toolchain works headless first (Trap 4) and accept that
you'll be reading `DIGEST.md` + JSONL after the fact rather than watching live.

### Trap 2 — Bookkeeping carried across cycles

**What goes wrong:** Cycle N updates `STATE.md` or `DIGEST.md` but doesn't commit
before spawning the worker. Cycle N+1 inherits the dirty working tree. A
`git stash` somewhere — to give the worker a clean checkout — drops uncommitted
bookkeeping into a dangling stash. Hours later, "where did cycle 19's `DIGEST`
entry go?" becomes real archeology.

**The fix:** The `orchestrator-prompt.md` template now requires the orchestrator
to **commit `STATE.md` / `DIGEST.md` atomically at every meaningful checkpoint**
(dispatch, worker return, gates pass, block), not at end-of-cycle. This makes
recovery from a crashed cycle trivial: the next cycle just reads the committed
state. Push them directly to `main` as `chore: orchestrator cycle N — `
(see Trap 5 — the "never push to main" rule is carved out for bookkeeping).

### Trap 3 — BLOCKED entries without a decision tree

**What goes wrong:** A worker reports an issue, the orchestrator dumps a
paragraph to `BLOCKED.md`, the cycle ends. When the human comes back —
potentially days later — they have to re-derive: what specifically failed,
what was already tried, what are the realistic options, what does each cost?
Context decay turns a 10-minute decision into an afternoon.

**The fix:** The `BLOCKED.md` template now requires every entry to carry four
parts: **symptom** (exact failure), **what was tried** (one attempted fix and
why it didn't work), **options forward** (2–3 paths with cost / risk /
reversibility), and **recommended path** (the orchestrator's pick + reasoning).
If the orchestrator can't fill all four, the entry should say so explicitly —
that itself is information.

### Trap 4 — Headless MCP tool surprises

**What goes wrong:** Interactive Claude sessions auto-resolve a wide range of
MCP tools (Slack, Linear, Notion, etc.). `claude -p` in headless / `launchd` /
remote-routine contexts often ships with a narrower default toolset; deferred
MCP tools need an explicit `ToolSearch` round-trip to load. A Slack
notification step that "works in dev" silently no-ops in production.

**The fix:** If notifications matter, test them from a *non-interactive* Claude
session (`claude -p "use the Slack MCP to send a test message"`) before
kickoff. The `notify-slack.md` template now flags this. If the headless path
doesn't load the tool, either add an explicit `ToolSearch` step to the
orchestrator-prompt or treat `DIGEST.md` as the only reliable heartbeat and
drop the notification.

### Trap 5 — "Never push to main" is too broad

**What goes wrong:** A blanket "never push to main" rule is correct for
milestone code (which flows through PR + squash merge) but wrong for
orchestrator bookkeeping. `STATE.md` and `DIGEST.md` updates fire every cycle;
routing them through PRs is bureaucratic theater, and not pushing them means
cross-machine continuity breaks.

**The fix:** The `orchestrator-prompt.md` template now carves out an exception:
> Never push *code* to `main`. `STATE.md`, `DIGEST.md`, and `BLOCKED.md` updates
> may be pushed directly to `main` as `chore: orchestrator cycle N — `.

---

## Completion

Report status using one of:

- **DONE** — harness scaffolded, roadmap locked, safety rails confirmed, kickoff command in the user's hands.
- **DONE_WITH_CONCERNS** — kickoff is possible but specific risks were flagged (list them).
- **BLOCKED** — missing roadmap, no git, or a fundamental gap that needs human work first.
- **NEEDS_CONTEXT** — waiting on user input.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [reidworks-io](https://github.com/reidworks-io)
- **Source:** [reidworks-io/reidworks-skills](https://github.com/reidworks-io/reidworks-skills)
- **License:** MIT
- **Homepage:** https://reidworks-io.github.io/reidworks-skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-reidworks-io-reidworks-skills-long-run
- Seller: https://agentstack.voostack.com/s/reidworks-io
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.