Long Running

Long-Running Tasks

This skill mimics the Fable 5 long-horizon harness by enabling multi-iteration workflows with durable state, self-pacing, and iterative enforcement. It adds two core primitives: durable .loop/ state files that persist across sessions, and the unicorn-team:loop-assist GO/NO-GO gate that enforces quality and coherence at every iteration boundary.

Fable 5 gets this machinery from its harness: scheduled wakeups, context continuation, a durable workflow journal, and between-turn verification. On sonnet or opus none of that exists, so this skill reconstructs each piece from files, agents, and commands the plugin already has. The operating principle: the loop is only as durable as its state files.

When to Use

1. Fable Parity

Full per-capability detail lives in references/fable-parity.md.

2. Iteration Lifecycle

The lifecycle is: ORIENT -> EXECUTE -> VERIFY -> CHECKPOINT -> ENFORCE -> PACE.

ORIENT

• Read .loop/handoff.md to reconstruct the current goal and context.
• Parse .loop/state.json to identify the next milestone and its status.
• Confirm no conflicting state (e.g., more than one milestone marked in_progress).
• Validate that state.json is syntactically valid and contains required fields.
• Discard any assumptions derived from prior context; treat as fresh reader.

EXECUTE

• Delegate the next milestone using the following prompt template:

Agent tool -> unicorn-team:developer @ sonnet

Milestone ID: {milestone-id}
Title: {milestone-title}
Acceptance Criteria:
{acceptance-criteria}

TDD Mandate: RED -> GREEN -> REFACTOR
- Write failing test first (RED)
- Implement minimal code to pass (GREEN)
- Refactor for clarity and maintainability (REFACTOR)
- Run the FULL test suite before committing
- Commit message format: `feat({milestone-id}): <description>`
- Do not commit debug code, console.log, or temporary files
- Do not modify any files outside the scope of this milestone

VERIFY

• For high-risk milestones: invoke unicorn-team:qa-security @ sonnet for security and correctness review.
• For standard milestones: execute pytest --tb=short and ruff check directly.
• Capture and log all test output, lint warnings, and type-check results.
• Fail fast if any test fails or lint rule is violated.
• Ensure coverage metrics meet minimum thresholds if defined in state.json.

CHECKPOINT

• Increment iteration counter in .loop/state.json.
• Set current milestone status to done in milestones[].
• Commit code and state together; the commit is the checkpoint boundary.
• Append a new ## Iteration N -- <ISO date> entry to .loop/journal.md with:
  • Actions taken
  • Verification results
  • Deficiencies found
  • Next step summary
• Overwrite .loop/handoff.md with a fresh, self-contained summary including:
  • Current goal
  • Summary of completed work
  • Exact next step with acceptance criteria
  • Known risks or landmines
  • Verify commands and key file pointers

ENFORCE

• Invoke unicorn-team:loop-assist @ haiku with the following prompt template:

Agent tool -> unicorn-team:loop-assist @ haiku

Run: scripts/verify-next-run.sh
Evaluate the following checks:
E1: state.json is coherent (parses, one unambiguous next milestone, acceptance testable)
E2: regression baseline is green (full test suite passes)
E3: verification harness is in place (runner, lint, type config exist; acceptance expressible as failing tests)
E4: working tree is clean (committed, no stray files, no debug code, no unresolved task markers)
E5: handoff.md is fresh (rewritten this iteration, sufficient for fresh agent)
E6: journal.md has appended this iteration's entry
E7: stop conditions are evaluated (budget, iterations, repeated failures, user triggers)

Return exactly one of: GO, NO-GO, or STOP
Include evidence per check (e.g., "E1: two milestones marked in_progress" -> NO-GO)
Repair .loop/ artifacts yourself only when they are the sole deficiency; return
code deficiencies as a fix-list with an owner agent per item.

NO-GO handling

• loop-assist repairs .loop/ artifacts itself (state.json, journal.md, handoff.md) when they are the only deficiency, then re-runs the checks.
• loop-assist never touches code. Code deficiencies (failing tests, missing tests, uncommitted logic, debug code) come back as a fix-list.
• The orchestrator re-delegates the fix-list to unicorn-team:developer @ sonnet, then re-enforces.
• Maximum 2 remediation rounds per iteration. If the third enforcement still returns NO-GO, stop the loop and report the unresolved deficiencies.

PACE

• Consult the Pacing table to select the next interval.
• If all milestones are done, or stop conditions are met, terminate the loop.
• If NO-GO was returned, remediate and re-enforce now; do not pace until the gate returns GO or STOP.
• If waiting on external system (CI, deploy), use 60-270s.
• If no external dependency, use 1200s as default fallback.
• Never use intervals below 60s or above 1800s unless explicitly justified.

3. Pacing

Stop conditions

Evaluated at ENFORCE from state.json stop_conditions[] and budget. Canonical triggers:

• All milestones done.
• Iteration budget (budget.iterations_max) exhausted.
• Same failure occurs 3 iterations in a row.
• Any user-declared stop_conditions[] entry met.

On STOP: finalize journal + handoff, report final state, end loop. Record which stop condition fired in the final journal entry.

Worked example

• Overnight FastAPI build-out: milestones sized 50-200 lines -> /loop 20m
• Waiting on CI between milestones -> 270s
• Suite running via run_in_background -> 1200s fallback only
• No external dependencies, no CI -> 1200s default
• Manual intervention required -> use 1800s to allow human response window

4. State Files

Quickstart bash block:

skills/long-running/scripts/loop-state.sh init "Bookstore inventory REST API"
skills/long-running/scripts/loop-state.sh status
skills/long-running/scripts/loop-state.sh next
skills/long-running/scripts/loop-state.sh check

Never hand-edit state.json mid-iteration; ORIENT (read) and CHECKPOINT (write) are the only touch points. Full schemas + worked examples in references/state-format.md.

5. Resume Protocol

For a fresh session or fresh context window:

1. Read .loop/handoff.md FIRST.
2. Read .loop/state.json second.
3. Tail the last 3 entries of .loop/journal.md third.
4. Run scripts/verify-next-run.sh BEFORE doing any work.
5. If loop-assist returns NO-GO, repair state artifacts before resuming.

On NO-GO:

• Do NOT begin work on the next milestone.
• Repair only .loop/ artifacts: handoff.md, state.json, journal.md.
• Never modify source code, tests, or configuration files.
• Re-run verify-next-run.sh to confirm all checks pass before continuing.

cat .loop/handoff.md
skills/long-running/scripts/loop-state.sh status
tail -40 .loop/journal.md
skills/long-running/scripts/verify-next-run.sh

The whole resume should cost a few hundred lines of reading, not a re-derivation of history; that is what the handoff is for.

6. Background Work Discipline

• Use run_in_background for long builds or test suites.
• Check results on wake; never busy-poll.
• For harness-tracked work (completion re-invokes you), use only long fallback intervals (1200s+).
• Never poll for completion; rely on system re-invocation.
• Always log background task start and end times in journal.md.
• If background task fails, treat as NO-GO in next iteration.

7. How to Run It

# Unattended: one milestone per wake, 20-minute cadence
/loop 20m /orchestrator   # paste the cycle prompt from LOOP-PROMPT.md

8. Enforcement Contract

The mechanical half is scripts/verify-next-run.sh (exit code = number of failed checks). Full check definitions and the may-fix vs must-re-delegate table live in agents/loop-assist.md.

References

• references/fable-parity.md -- Maps Fable 5 harness features to plugin equivalents.
• references/state-format.md -- Full JSON schema and worked examples for .loop/ state files.
• scripts/loop-state.sh -- CLI tool to initialize, query, and validate .loop/ state.
• scripts/verify-next-run.sh -- Validates enforcement contract; exits with count of failed checks.
• agents/loop-assist.md -- Definition of the GO/NO-GO gate agent and its decision logic.
• LOOP-PROMPT.md -- Template for unattended loop prompts; defines context and pacing intent.
• skills/orchestrator/SKILL.md -- Routing and tiering for the agents this loop delegates to.