olliecrow/loopy

Loopy

Multi-agent collaboration

• Default to using subagents when they are likely to improve speed, quality, confidence, or keep the main context clean.
• Use subagents to widen coverage, dig deeper on one thread, get a fresh second opinion, or keep the main thread clean while side work runs.
• Split work into clear packets with owners, inputs, acceptance checks, and a synthesis step when parallelizing.
• Keep the main agent focused on synthesis, unblockers, and the next critical-path step; let subagents handle bounded side work that can run in parallel.
• Use single-agent execution only when scope is small or coordination overhead outweighs gains.

Proactive autonomy and knowledge compounding

• Be proactive: immediately take the next highest-value in-scope action when it is clear.
• Default to autonomous execution: do not pause for confirmation between normal in-scope steps.
• Request user input only when absolutely necessary: ambiguous recipe/project selection, material risk tradeoffs, missing required data/access, or destructive/irreversible actions outside policy.
• If blocked by command/tool/env failures, attempt high-confidence fallbacks autonomously before escalating (for example rg -> find/grep, python -> python3, alternate repo-native scripts).
• When the workflow uses plan/, ensure required plan directories exist before reading/writing them (create when edits are allowed; otherwise use an in-memory fallback and call it out).
• Treat transient external failures (network/SSH/remote APIs/timeouts) as retryable by default: run bounded retries with backoff and capture failure evidence before concluding blocked.
• On repeated invocations for the same objective, resume from prior findings/artifacts and prioritize net-new progress over rerunning identical work unless verification requires reruns.
• Drive work to complete outcomes with verification, not partial handoffs.
• Treat iterative execution as the default for non-trivial work; run adaptive loop passes. Example loops (adapt as needed, not rigid): issue-resolution investigate -> plan -> fix -> verify -> battletest -> organise-docs -> git-commit -> re-review; cleanup scan -> prioritize -> clean -> verify -> re-scan; docs audit -> update -> verify -> re-audit.
• Keep looping until actual completion criteria are met: no actionable in-scope next step remains, verification is green, and confidence is high.
• Run organise-docs frequently during execution to capture durable decisions and learnings, not only at the end.
• Create small checkpoint commits frequently with git-commit when changes are commit-eligible, checks are green, and repo policy permits commits.
• Never squash commits; always use merge commits when integrating branches.
• Prefer simplification over added complexity: aggressively remove bloat, redundancy, and over-engineering while preserving correctness.
• When you touch code, leave the touched area in a better state than you found it: clearer, simpler, tidier, and at least as performant unless the task requires an explicit trade-off.
• Use simple, plain English in user messages, docs, notes, reports, code comments, and other explanatory writing. Avoid jargon, fancy wording, and complex phrasing. When a technical term is needed for correctness, explain it in simple words the first time. Default to short user-facing responses. Think about what the user most wants to know, and lead with that. Do not dump every detail by default. Always include important changes, blockers, verification gaps, and any important assumptions, nuances, principles, or decisions that shaped the work. Add more detail only when the user asks for it or when uncertainty or risk makes it necessary.
• Compound knowledge continuously: keep docs/ accurate and up to date, and promote durable learnings and decisions from work into docs.

Long-task checkpoint cadence

• For any non-trivial task (including long efforts), run recurring checkpoint cycles instead of waiting for a single end-of-task wrap-up.
• At each meaningful milestone with commit-eligible changes, and at least once per major phase, invoke git-commit to create a small logical checkpoint commit once relevant checks are green and repo policy permits commits.
• At the same cadence, invoke organise-docs whenever durable learnings/decisions appear, and prune stale plan/ scratch artifacts.
• If either checkpoint is blocked (for example failing checks or low-confidence documentation), resolve or record the blocker immediately and retry before expanding scope.

Interruption handoff (required for monitored runs)

• Before stopping, switching sessions, or yielding after an interruption, write a concise handoff in plan/handoffs/ or plan/current/notes.md.
• Include:
  • target repo and current branch,
  • selected recipe path,
  • launch id and launch root if launched,
  • latest launch status and latest step,
  • current classification (running, blocked, failure, success-cleaned, success-with-retained-workspace),
  • exact next step.
• On repeat invocations, resume from the latest handoff and current launch artifacts before considering any rerun.

Terminal state contract (must follow)

The skill is complete only when all of the following are true:

• Objective completion: the requested Loopy run is launched and monitored from start through terminal outcome, and the terminal launch artifacts/logs/results have been checked before declaring success.
• Workflow completion: the checkpoint prerequisite, recipe-selection step, launch step, monitoring step, and closeout step are each resolved as done, blocked, or not-applicable, with brief evidence or rationale.
• Step-level terminal completion: each numbered subtask must have explicit completion evidence (artifact, command output, or written rationale) before advancing.
• Verification completion: required checks/validations for this skill are executed, or any unavailable checks are explicitly called out with impact.
• Findings completion (where applicable): report only evidence-backed findings; if no high-confidence critical run-health issues are present, explicitly state that.
• Loop completion: no actionable in-scope next step remains under the current objective.

Terminal state examples (adapt to skill)

• done: checkpoint completed on the target repo, one clear recipe was selected, the Loopy run finished, the retained launch artifacts/logs/results still support the final story, and the terminal state was classified correctly as failure, success-cleaned, or success-with-retained-workspace.
• blocked: checkpoint could not complete, recipe selection remained ambiguous, current-branch compatibility failed, or Loopy/tool/repo prerequisites still failed after bounded retries; blocker evidence and exact unblock commands are reported.
• not-applicable: remote-delivery follow-up is intentionally skipped when the user asked only for recipe selection or preflight diagnostics.

Stop only after this terminal contract is satisfied; otherwise continue iterating.

Overview

Run loopy launch against the correct committed recipe in ~/repos/me/loopy/recipes, but only after the current project branch has been checkpointed and pushed. Prefer the bundled launcher for repeatable preflight, recipe auto-discovery, branch-compatibility checks, launch-root discovery, heartbeat monitoring, and artifact reporting. Do not stop at launch exit alone; finish only after the retained state, logs, and result artifacts have been checked and still make sense together.

The local Loopy source repo is:

~/repos/me/loopy

The canonical launcher for this skill is:

• scripts/run_loopy.py

It runs go run ./cmd/loopy validate ... and go run ./cmd/loopy launch ... from the local Loopy repo, verifies that the current target-repo branch is clean and synchronized, can auto-rank matching recipes for the current repo plus user goal, enforces the "current branch" guardrail by default, can attach to the latest matching launch instead of starting a duplicate run, discovers the new launch under ~/loopy/launches/, and monitors state/launch.json plus retained logs/ while the run is active.

Trigger phrases

Use this skill when the user asks for intents like:

• run loopy on this repo
• start a loopy run here
• launch the loopy recipe for this project
• run the existing loopy recipe from this branch
• monitor this loopy launch
• preflight loopy for the current project

Prompt templates

Use these copy-paste templates:

• [$loopy] checkpoint and push the current branch, select the matching loopy recipe for this project, then launch and monitor it from start to finish while checking retained logs, launch state, and result artifacts.
• [$loopy] preflight the current repo for loopy readiness, identify the correct recipe under ~/repos/me/loopy/recipes, and do not launch unless branch compatibility is explicit.
• [$loopy] rerun the known recipe <project/recipe.loopy.hcl> from the current branch after checkpointing, monitor it from start to finish, and summarize the launch artifacts plus final delivery result only after the retained evidence agrees.
• [$loopy] discover the best loopy recipe for this repo and goal "<goal>", then attach to the latest matching launch if one is already running; otherwise launch and monitor a new run from start to finish while checking retained logs, launch state, and result artifacts.

Skill composition

When this skill is triggered, compose other skills as needed:

• Use checkpoint first to enforce the committed, pushed, and documented branch prerequisite before any Loopy launch starts.
• Use investigate when recipe selection, branch compatibility, launch health, or retained-artifact recovery is unclear enough that direct action would rely on guesswork.
• Use organise-docs when a Loopy run surfaces durable recipe-selection rules, operating constraints, or recovery guidance worth preserving.

If there is a conflict, launch correctness wins: companion skills should support a trustworthy Loopy run, not weaken the checkpoint-first and current-branch guardrails.

Monitoring posture and intervention bar

• Be patient by default; long Codex steps, waits, or sparse log updates alone are not intervention-worthy.
• Quiet, waiting, or same-step periods are still active monitoring time when the launch is alive.
• Treat checkout activity as a first-class progress signal when retained logs are sparse: branch creation, commits, pushes, tracked file mutations, and refreshed result artifacts mean the run is still moving even if step_index has not advanced yet.
• Accept isolated quiet periods, benign retained-log noise, or a retained local workspace when the launch still shows forward progress and artifacts remain interpretable.
• Maintain a high intervention bar: intervene only when continuing is likely to:
  • waste substantial time by leaving the launch stuck with no realistic recovery path, or
  • produce misleading/invalid delivery outcomes because launch state is clearly unhealthy.

Default policy bands for one Loopy run:

• watch band: expected step execution time, sparse logs while state/launch.json still updates, benign retained-log noise, or same-step heartbeats paired with visible checkout progress.
• escalation band: repeated identical heartbeats with no new step/log movement, repeated blocking log signals that do not recover, or ambiguous recipe/branch state that could cause the launch to run from the wrong base.
• intervention band: deterministic preflight failure, current-branch mismatch, unrecoverable launch failure, corrupted launch record/logs, or sustained no-progress state with evidence that continuing will not yield a trustworthy result.

Hard-stop override (intervene earlier):

• checkpoint on the target repo did not resolve to a pushed, synchronized branch,
• recipe selection is ambiguous or the best candidate would not start from the current branch,
• required wrapper tools (go, codex) fail in a way that blocks the expected launch behavior,
• state/launch.json becomes unreadable or records terminal failure,
• the launch exits with preserved local state that requires explicit recovery before a rerun.

Behavioral guardrails (must follow)

• Always start by running the checkpoint workflow from ../checkpoint/SKILL.md on the target repo. Do not skip this because the user already "probably pushed"; verify it.
• Treat the current working repo as the target repo unless the user explicitly names another local repo.
• Identify candidate recipes from ~/repos/me/loopy/recipes using both repo association and the user's stated goal:
  • match project-level or recipe-level repo settings against the target repo's remote URL or local repo identity,
  • match recipe filename, project directory, and prompt naming against the user's requested workflow,
  • prefer the unique candidate whose explicit branch matches the current branch.
• Use the launcher discovery output to show ranked candidates and matching reasons whenever recipe selection is not already explicit.
• If no clear recipe exists, or more than one plausible recipe remains, treat the run as blocked pending explicit recipe clarification instead of guessing.
• Do not silently launch a recipe that omits branch or names a different branch when the user's intent is "from the current branch". Treat that as ambiguous unless the user explicitly approves default-branch or mismatched-branch behavior.
• Prefer monitored go run ./cmd/loopy launch ... runs through the bundled launcher instead of raw loopy launch so preflight and monitoring stay consistent.
• Verify required wrapper tools before launch: go and codex. If the selected recipe or downstream delivery path has extra prerequisites, surface the exact blocker before launch.
• On repeated invocations, prefer --attach-latest or --launch-root so the user gets continuity instead of a duplicate launch when useful retained state already exists.
• Monitor first-class artifacts continuously while the run is active:
  • ~/loopy/launches/<id>/state/launch.json,
  • retained logs/*.message.*, logs/*.stdout.jsonl, and logs/*.stderr.log,
  • the launch checkout branch, recent commits, and git status when logs stay quiet,
  • final CLI result lines including launch_id, launch_root, branch, classification, and launch_state.
• After the process exits, keep checking the terminal launch record, retained logs, and result artifacts until the final classification still makes sense.
• When the launch stalls or exits non-zero, inspect the launch root, latest state/launch.json, and newest retained logs before concluding what failed.
• On repeated invocations for the same active launch, prefer resuming from existing launch artifacts and logs instead of launching a duplicate run unless the user explicitly asks for a rerun.

Workflow

1. Checkpoint the target repo first.

• Load and follow ../checkpoint/SKILL.md.
• The target repo is the current working repo unless the user explicitly names another repo.
• Do not continue until the checkpoint cycle resolved the repo as done or blocked.

2. Preflight the target repo after checkpointing.

• Confirm repo root with git rev-parse --show-toplevel.
• Check the worktree is fully clean with git status --porcelain.
• Capture the current branch and upstream tracking branch.
• Verify ahead/behind is 0 0 with git rev-list --left-right --count HEAD...@{u}.
• Verify origin exists and resolves to the repo identity you expect to match in Loopy recipes.
• Verify required wrapper tools are available: go and codex.
• If any prerequisite fails, do not launch Loopy. Report the exact failing check and the minimal unblock command(s).

3. Select the recipe.

• Search ~/repos/me/loopy/recipes for:
  • project.loopy.hcl files whose repo matches the target repo,
  • recipe files whose names or prompt files align with the user's requested workflow,
  • recipe files whose explicit branch matches the target repo's current branch.
• Prefer the launcher discovery mode first:
  • python3 skills/loopy/scripts/run_loopy.py --target-repo "<repo-root>" --goal "<user-goal>" --discover-only
• Use the ranked candidate output and matching reasons as the primary evidence for whether recipe selection is clear.
• When no recipe matches, use the rejection diagnostics and near-miss list to explain whether the blocker is repo mismatch, branch mismatch, or simply that no recipe exists yet.
• If there is exactly one strong candidate, continue.
• If the recipe omits branch, or sets a different branch from the current branch, treat the run as blocked pending explicit approval unless the user already requested that behavior.
• If zero or multiple plausible candidates remain, treat the run as blocked pending explicit recipe clarification.

4. Validate and launch in monitored mode.

• Use python3 skills/loopy/scripts/run_loopy.py --target-repo "<repo-root>" --goal "<user-goal>" when the recipe is not explicit, or python3 skills/loopy/scripts/run_loopy.py --recipe "<project/recipe.loopy.hcl>" --target-repo "<repo-root>" when it is.
• Default flags:
  • --warmup-seconds 300
  • --warmup-poll-seconds 30
  • --poll-seconds 600
• When the user explicitly wants a non-default Loopy runtime, pass the same launch-time overrides through the wrapper:
  • --provider <provider>
  • --model <model>
  • --reasoning-effort <level>
  • --var <name=value> (repeatable)
• Use --preflight-only when the user asked for readiness/selection only.
• Use --allow-default-branch only when the user explicitly approved running from the recipe/default branch instead of the current branch.
• Use --allow-branch-mismatch only when the user explicitly approved a recipe whose explicit branch differs from the current branch.
• Use --attach-latest on repeated invocations when the same recipe may already have an active launch.
• Use --launch-root "<~/loopy/launches/...>" --monitor-only when the user gives you a specific retained launch to inspect or continue watching.

5. Monitor while it runs.

• Stream Loopy stdout/stderr to the terminal and a local monitor log when available.
• Parse and surface:
  • target repo, current branch, and selected recipe,
  • launch root as soon as the new ~/loopy/launches/<id>/ directory is discovered,
  • state/launch.json status, step_index, last_step, updated_at, heartbeat_at, current thread/profile data, workspace retained/cleaned state, and the newest blocking log signal,
  • the newest interesting retained log signal under logs/.
• Use a staged default monitoring cadence for token efficiency:
  • first 300s: heartbeat every 30s,
  • after 300s: heartbeat every 600s.
• Emit concise heartbeats only when no new output appears for the active cadence window.
• Treat quiet, waiting, or same-step periods as active monitoring time while retained evidence still shows forward movement or a live launch.
• Treat unreadable launch state, distinct blocking log signals, or repeated identical heartbeats without other progress as intervention prompts, not as informational noise.

6. Classify the terminal outcome before taking action.

• Treat these outcomes differently:
  • failure: non-zero exit, terminal state/launch.json status failed, unreadable required artifacts, or other unrecoverable launch error.
  • success-with-retained-workspace: launch completed successfully but retained workspace state still requires follow-up or inspection.
  • success-cleaned: launch completed successfully and cleaned up its workspace state.

7. Intervention workflow (mandatory sequence).

• When intervention is justified, execute this order:
  1. Diagnose the exact stuck or failure mode from stdout/stderr, state/launch.json, and the newest retained logs.
  2. Preserve evidence by recording the recipe, launch id, launch root, latest status, latest step, and monitor log path.
  3. Prefer in-place diagnosis and recovery over an immediate rerun when the launch already produced useful retained state.
  4. Stop only the affected Loopy run when in-place recovery is not possible.
  5. Clean up only launch-local artifacts if they would mislead a rerun; never mutate the user's source repo to force recovery.
  6. Implement only high-confidence, in-scope fixes to the blocking condition.
  7. Re-run the relevant preflight or smoke check before launching another Loopy pass.
  8. Relaunch once the blocker is resolved and continue monitoring from the new launch root.

8. Close out after completion.

• Before reporting success, confirm that the final launch record, retained logs, and any produced result artifacts tell a consistent story.
• Report:
  • exit code,
  • target repo and current branch,
  • selected recipe,
  • launch id and launch root when available,
  • local monitor log path when present,
  • terminal outcome classification (failure, success-with-retained-workspace, or success-cleaned),
  • latest step and final launch-record status if available.
• If the run failed, include the latest step, latest launch status, and the exact rerun or unblock command.
• If the user asked only for readiness or diagnostics, mark launch execution not-applicable.

Script

Use scripts/run_loopy.py.

Supported arguments:

• --recipe <project/recipe.loopy.hcl>: recipe path relative to the Loopy repo recipes/ directory. Optional when discovery is allowed.
• --goal <text>: short user-intent text used to rank matching recipes during auto-discovery.
• --target-repo <path>: target local repo path. Defaults to the current working directory.
• --warmup-seconds <int>: length of the active monitoring warmup window. Default 300.
• --warmup-poll-seconds <int>: heartbeat interval during warmup. Default 30.
• --poll-seconds <int>: steady-state heartbeat interval after warmup while no new output arrives. Default 600.
• --artifact-dir <path>: override local directory for monitor logs. Defaults to <repo>/plan/artifacts/loopy when available.
• --discover-only: list matching recipe candidates and exit without launching.
• --preflight-only: run repo and recipe preflight only and do not launch Loopy.
• --allow-default-branch: allow launching a recipe that omits branch, which means Loopy will use the target repo default branch instead of the current branch.
• --allow-branch-mismatch: allow launching a recipe whose explicit branch differs from the current branch.
• --attach-latest: attach to the latest matching launch instead of starting a duplicate run when one exists.
• --launch-root <path>: attach to a specific retained launch root.
• --monitor-only: only monitor an existing launch; do not start a new one.
• --loopy-repo <path>: override the local Loopy source repo. Defaults to ~/repos/me/loopy.
• --provider <provider>: optional runtime provider override passed through to both loopy validate and loopy launch.
• --model <model>: optional runtime model override passed through to both loopy validate and loopy launch.
• --reasoning-effort <level>: optional runtime reasoning-effort override passed through to both loopy validate and loopy launch.
• --var <name=value>: repeatable launch-time recipe var assignment passed through to both loopy validate and loopy launch.