Skip to content

bestdeejay-design/agent-skills / skills/long-running-agent-workflow

long-running-agent-workflow

Verified

Structured protocol for AI agents working across many context windows: a .lra/ directory with an atomic feature list (id/priority/acceptance criteria/status) and a session progress log, plus a session protocol (read context → pick ONE feature → implement → test → checkpoint) and recovery from broken states. Based on Anthropic research on long-running agents. Triggers: 'lra', 'checkpoint', 'feature list', 'long running', 'продолжи работу', 'долгая сессия', 'план фич', 'статус проекта'.

Long-Running Agent (LRA) Workflow

Load this skill when you are about to work on a large project that will span multiple sessions / context windows and you need continuity, atomic handoffs, and recovery from broken states.

The skill gives you a tiny CLI (scripts/lra_cli.py) that maintains a .lra/ directory: a machine-readable feature-list.json (atomic features with acceptance criteria and status) and a human/agent-readable progress.txt (session log). The protocol turns "one big vague task" into a sequence of small, fully-tested, check-pointed features.


Overview — the problem

AI agents working across many context windows hit three failure modes:

  • Context amnesia — each new session has no memory of prior work.
  • One-shot tendency — trying to do too much at once, leaving half-done features.
  • Incomplete features — work spans sessions with no clear acceptance gate, so "done" is never verified.

LRA fixes this with: structured init, one atomic feature per session, an explicit test gate before done, and a checkpoint after every feature so the next session can recover.


When to use

  • Long, multi-session projects (hours/days, many context windows).
  • Any task where you might lose context between runs.
  • Triggers: lra, checkpoint, feature list, long running, продолжи работу над проектом, долгая сессия, план фич, статус проекта.

If the task is small and finishes in one session, you do not need this skill — just do the work.


Prerequisites

  • A git repository (so checkpoints can be committed and recovered).
  • Python 3 on PATH (the CLI is pure stdlib, no dependencies).
  • Run the CLI from the project root (it creates/reads .lra/ there).

Instructions

Phase 1 — Init

python3 scripts/lra_cli.py init "Short project description"

Creates .lra/feature-list.json ({"project": ..., "features": [], "created": <date>}) and .lra/progress.txt with a header. Refuses (exit 1) if .lra/ already exists, so you never clobber an in-progress project.

Phase 2 — Plan features

Add atomic, testable features. Each gets an id (f1, f2, …), a name, a priority (high/medium/low), and criteria (acceptance criteria).

python3 scripts/lra_cli.py add "User registration endpoint" --priority high \
  --criteria "POST /api/auth/register accepts email+password; validates email; hashes password; returns JWT"

Rule: a feature must be completable in one session and have concrete acceptance criteria. "Build the user system" is too big — split it.

Phase 3 — Session protocol (repeat every session)

  1. Read context — status and read .lra/progress.txt to see where you are.
  2. Pick ONE feature — the highest-priority todo (or wip you abandoned).
  3. Implement it.
  4. Test it against its acceptance criteria (unit + integration + manual).
  5. Mark done — mark f<N> done only after verification passes.
  6. Checkpoint — checkpoint "Implemented X and Y; tests green".
python3 scripts/lra_cli.py mark f1 done
python3 scripts/lra_cli.py checkpoint "User registration: endpoint + validation + tests"

Phase 4 — Checkpoint / recover

  • checkpoint "<message>" appends a timestamped line to progress.txt. Always checkpoint at the end of a session, even for partial work.
  • recover prints the last 10 progress lines plus a summary of wip features — use it at the start of a session or after a broken state to see what was in flight.

Phase 5 — Status

status prints a table of all features (id, name, priority, status) sorted todo → wip → done, so you always know the current state at a glance.


Best practices

  • One feature per session. Finish it fully (code + tests) before moving on.
  • Always leave the codebase working. No broken builds, no failing tests at a checkpoint.
  • Commit after each feature. A checkpoint is a clean git state the next session can trust.
  • Update feature-list.json before closing the session — mark status, add notes, add newly discovered sub-features with add.
  • Atomic features only. Small, testable, single-purpose.

Constraints and warnings

  • Never start a feature without acceptance criteria. If none exist, write them first via add --criteria.
  • Never skip tests. A feature is not done until its criteria are verified end-to-end.
  • Don't mark done without verification. Marking done on unverified work poisons the next session's context.
  • Don't clobber .lra/. init refuses if it exists; recover from the log instead of recreating.

Files

  • SKILL.md — this file
  • skill.json — manifest
  • scripts/lra_cli.py — the stdlib CLI (init, add, mark, checkpoint, status, recover)
  • references/lra-workflow.md — full reference: .lra/ file structure, JSON schemas, a worked example, the session checklist, and troubleshooting

Installation

# For opencode
cp -r skills/long-running-agent-workflow ~/.config/opencode/skills/

# For other agents: copy the folder to your skills directory; requires Python 3.

Key principle: leave the codebase in a testable, working state at the end of every session. The next session (and the next agent) picks up from the last checkpoint, not from amnesia.

Boundaries

  • Do not use for a short, single-turn task that does not need resumable state.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall