bestdeejay-design/agent-skills / skills/long-running-agent-workflow
long-running-agent-workflow
VerifiedStructured 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', 'продолжи работу', 'долгая сессия', 'план фич', 'статус проекта'.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.5 KB |
| references/lra-workflow.md | markdown | 5.8 KB |
| scripts/lra_cli.py | script | 8.1 KB |
| skill.json | config | 1.4 KB |
references/lra-workflow.md
View on GitHub# LRA Workflow — Reference
Full reference for the Long-Running Agent (LRA) workflow skill. The skill
`SKILL.md` is the quick-start; this file is the deep dive: file structure,
JSON schemas, a worked example, the session checklist, and troubleshooting.
---
## 1. `.lra/` file structure
```
.lra/
├── feature-list.json # machine-readable: all features + status
└── progress.txt # human/agent-readable session log
```
Both live at the **project root** (the directory where you run `lra_cli.py`).
The CLI refuses to `init` if `.lra/` already exists, so an in-progress project
is never clobbered.
---
## 2. JSON schemas
### `feature-list.json`
```json
{
"project": "Chat app with auth and history",
"features": [
{
"id": "f1",
"name": "User registration endpoint",
"priority": "high",
"criteria": "POST /api/auth/register accepts email+password; validates email; hashes password; returns JWT",
"status": "todo",
"added": "2026-08-14"
}
],
"created": "2026-08-14"
}
```
| Field | Type | Notes |
|---|---|---|
| `project` | string | Short project description (from `init`) |
| `features` | array | Ordered list of features |
| `created` | string | ISO date (`YYYY-MM-DD`) |
| `features[].id` | string | `f<N>`, auto-assigned, monotonic |
| `features[].name` | string | Feature name; must be unique (case-insensitive) |
| `features[].priority` | enum | `high` \| `medium` \| `low` |
| `features[].criteria` | string | Acceptance criteria — the verification gate |
| `features[].status` | enum | `todo` \| `wip` \| `done` |
| `features[].added` | string | ISO date the feature was added |
### `progress.txt`
```
# Long-Running Agent Progress Log
# Project: Chat app with auth and history
# Created: 2026-08-14
[2026-08-14T14:05:00] Initialized project
[2026-08-14T15:30:00] Implemented user registration: endpoint + validation + tests
```
Each `checkpoint` appends one timestamped line (`[ISO-time] message`).
---
## 3. Worked example
```bash
# --- Session 1: initialize ---
python3 scripts/lra_cli.py init "Chat app with auth and message history"
python3 scripts/lra_cli.py add "User registration endpoint" --priority high \
--criteria "POST /api/auth/register; validates email; hashes password; returns JWT"
python3 scripts/lra_cli.py add "User login endpoint" --priority high \
--criteria "POST /api/auth/login; verifies credentials; returns JWT; 401 on bad creds"
python3 scripts/lra_cli.py add "Message creation endpoint" --priority medium \
--criteria "POST /api/messages; persists message; returns created entity"
python3 scripts/lra_cli.py status
# ID NAME PRIORITY STATUS
# f1 User registration endpoint high todo
# f2 User login endpoint high todo
# f3 Message creation endpoint medium todo
# Implement f1, run its tests, then:
python3 scripts/lra_cli.py mark f1 done
python3 scripts/lra_cli.py checkpoint "User registration: endpoint + validation + tests"
# --- Session 2: recover context, continue ---
python3 scripts/lra_cli.py recover
# shows last 10 progress lines + wip features (none yet)
python3 scripts/lra_cli.py status
# f1 ... done ; f2/f3 ... todo
# Implement f2, test, mark, checkpoint.
python3 scripts/lra_cli.py mark f2 done
python3 scripts/lra_cli.py checkpoint "User login + JWT generation"
# --- Session 3: discovered a sub-feature mid-work ---
python3 scripts/lra_cli.py add "Rate limiting for message endpoints" --priority medium \
--criteria "Limit messages per user per minute; 429 when exceeded"
# f4 added; it will surface in the next session's status.
```
---
## 4. Session checklist
Run this loop every session:
- [ ] `recover` (or `status`) — read where the last session left off.
- [ ] Pick **one** feature: highest-priority `todo`, or an abandoned `wip`.
- [ ] Confirm it has **acceptance criteria**; if not, `add --criteria` first.
- [ ] Implement the feature.
- [ ] Test against the criteria (unit + integration + manual).
- [ ] `mark f<N> done` **only after** tests pass.
- [ ] `checkpoint "<what was done>"` — append to the log.
- [ ] Commit the working tree (a clean git state the next session can trust).
- [ ] Update `feature-list.json` notes / add discovered sub-features.
---
## 5. Troubleshooting
### `.lra/` already exists
`init` exits 1. You don't need to re-init — just `status` / `recover` and
continue. Only `init` a fresh project once.
### Stale `.lra/` (features don't match reality)
Edit `feature-list.json` directly (it's plain JSON) or use `add` / `mark`.
Never delete `.lra/` to "fix" it — you'd lose history. Prefer `recover` to
read the log and reconcile.
### Conflicting feature ids
IDs are auto-assigned as `f<N>` from the max existing numeric suffix, so they
never collide as long as you use `add`. If you hand-edit the file and create a
duplicate id, `mark`/`status` will still work but `recover` summaries may be
ambiguous — keep ids unique.
### Lost progress / broken state
1. `recover` — read the last 10 log lines and the `wip` summary.
2. `git log --oneline -10` and `git status` to see code state.
3. Fix or `git revert`/`git reset --soft` to a known-good commit.
4. Re-run tests, then `checkpoint` with a note about the recovery.
### Duplicate feature name
`add` rejects a name that already exists (case-insensitive). Rename or split
the feature instead of duplicating.
---
## 6. Design notes
- **Statuses are `todo` / `wip` / `done`** — three states keep the model
simple. `wip` marks a feature started but not verified; `done` is only set
after the acceptance criteria pass.
- **One feature per session** is the core discipline: it bounds context usage
and guarantees each handoff is a complete, tested unit.
- Based on Anthropic's research on effective harnesses for long-running agents
(continuity, atomic units of work, clean checkpoints).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |