Work items, loops, and epics
This system turns large GitHub issues into trackable epics, keeps their state visible in a local work queue, and supports repeated agent delivery across loops and sessions. GitHub remains the source for epic coordination, while local state and session records help operators claim work, resume context, detect stalls, and move validated work toward publication. See Orchestration and autonomous workflows for the parent model, Workflow execution and worktrees for execution isolation, Coordination inventory and goals for work planning, and GitHub coordination and policy for shared GitHub rules.
System model
Epic coordination
An epic is a GitHub issue that groups a larger unit of work into tasks and dependencies. The coordination commands add a machine-readable coordination block to that issue, align labels with its state, and write an audit comment so the work has one shared record.
The epic flow uses the issue body as the canonical record. A local SQLite entry acts as a projection for status views and operator tools. The default policy requires validation and review before publication, and it treats the epic as the branch unit rather than creating branches for each child task.
flowchart LR
A[GitHub epic issue] --> B[Coordination block]
A --> C[Tasks and dependency references]
B --> D[Labels and audit comments]
B --> E[Local work-item projection]
E --> F[Operator queue and status views]
References: scripts/…/actions.js• L46-80 scripts/…/state.js• L14-35 scripts/…/policy.js• L23-47 scripts/…/store.js• L14-47
Local work-item queue
A work item is a local record for a unit of work from GitHub, Linear, a handoff, or a manual roadmap entry. The scripts/work-items.js command provides a common queue for listing, inspecting, creating or updating, closing, claiming, and importing open GitHub issues and pull requests.
Claiming is just-in-time pickup. Without an ID, the command selects the highest-priority unassigned open item. It records the owner and optional owner kind, then moves the item to running; an explicit ID lets an operator claim a known item. The same claim rules are shared with the control pane so command-line and interactive claims have the same meaning.
GitHub synchronization gives imported issues and pull requests stable local identities. Open pull requests become review work, while draft or merge-blocked pull requests become blocked work. The sync also closes older imported records that are no longer present in the selected open-item result.
| Queue action | Result |
|---|---|
list / show | Inspect current local work state |
upsert | Add or update a work record from a source |
claim | Assign an agent or human and start the item |
close | Mark the item complete with a terminal status |
sync-github | Refresh open GitHub issues and pull requests and close stale imported records |
References: scripts/work-items.js• L29-59 scripts/work-items.js• L179-237 scripts/work-items.js• L241-315 scripts/work-items.js• L411-515 scripts/…/work-item-mutations.js• L35-83
Loop and session delivery
A loop is a managed series of delivery iterations. A session is the saved working context that lets an engineer or agent continue after a stop or handoff. Loop commands manage the run pattern and health; session commands preserve and restore the context needed for the next iteration.
The delivery model separates active work from its evidence. A loop starts with a pattern, mode, test check, hook check, and explicit stop condition. Session files preserve the work summary and current state. session-inspect can inspect orchestration plans, named sessions, Claude history, or skill-loop observations through a single inspection surface.
References: commands/loop-start.md• L5-30 commands/save-session.md• L5-16 commands/resume-session.md• L5-15 scripts/session-inspect.js• L13-36
Epic lifecycle
Decomposition and claiming
Decomposition turns the checklist and issue references in an epic body into tracked tasks and dependencies. Claiming then gives the epic an owner and coordination status so later work has a clear actor and a visible starting point.
When an engineer runs /epic-decompose, the system reconciles the task list without creating task branches. /epic-claim marks the GitHub issue as claimed, updates its coordination labels and local projection, and adds an audit comment. The claim operation requires an open issue that is not already claimed.
sequenceDiagram
participant O as Operator
participant G as GitHub epic
participant C as Coordination service
participant L as Local state
O->>C: decompose epic
C->>G: read tasks and references
C->>G: write coordination state and audit
O->>C: claim epic
C->>G: verify open and claimable
C->>G: write owner and labels
C->>L: save epic projection
References: commands/epic-decompose.md• L5-18 commands/epic-claim.md• L5-20 scripts/…/actions.js• L46-80 scripts/…/actions.js• L252-290
Synchronization and unblocking
Synchronization reconciles the issue body, coordination state, labels, and local snapshot. It is the recovery path when GitHub and local views may have drifted. /epic-sync scans issues and refreshes each epic projection; scripts/work-items.js sync-github serves the broader local queue by importing open GitHub issues and pull requests.
The general queue sync reads both open pull requests and open issues for one repository. It upserts the current records, keeps source details for later views, and closes stale records created by that sync surface. Its result is limited by the requested GitHub page size, so operators must use a scope that covers the open work they expect to reconcile.
Unblocking is a dependency sweep. /epic-unblock checks blocked epics against their declared issue references and moves an epic to ready only when all listed dependencies are closed. It updates the same GitHub and local records as other coordination actions.
| Surface | Scope | Main source |
|---|---|---|
/epic-sync | Epic coordination state | GitHub issue bodies and labels |
/epic-unblock | Blocked epics | Declared dependency issue state |
work-items.js sync-github | General local queue | Open GitHub issues and pull requests |
References: commands/epic-sync.md• L5-18 commands/epic-unblock.md• L5-19 scripts/…/actions.js• L83-127 scripts/…/actions.js• L293-343 scripts/work-items.js• L269-315
Validation, review, and publication
Validation is the readiness gate for an epic. It checks that coordination state can be read and that declared dependencies are closed; a passing result moves the epic toward ready. Review is a separate state so approval is not confused with dependency readiness.
Publication re-runs validation and also requires review approval under the default policy. Only then does /epic-publish write the final coordination state, labels, audit comment, and local snapshot. /epic-review records requested, approved, or changes-requested review outcomes and keeps those outcomes visible in both systems.
flowchart TD
A[Claimed epic] --> B[Validate dependencies]
B -->|Not ready| C[Remain blocked or pending]
B -->|Ready| D[Review outcome]
D -->|Changes requested| C
D -->|Approved| E[Publish]
E --> F[Published GitHub state and local snapshot]
References: commands/epic-validate.md• L5-20 commands/epic-review.md• L5-19 commands/epic-publish.md• L5-18 scripts/…/actions.js• L130-216 scripts/…/actions.js• L219-250
Continuous loop operations
Loop patterns and safety gates
/loop-start creates the operating plan for an autonomous delivery run. The operator selects a pattern such as sequential, continuous pull request, RFC dependency graph, or infinite, then chooses safe or fast mode. Safe mode keeps strict gates and checkpoints; fast mode reduces gates for speed.
Before the first iteration, the command checks repository state, branch strategy, test status, hook availability, and a stop condition. The loop operator also expects an evaluation baseline, a rollback path, and worktree isolation before running autonomous work.
References: commands/loop-start.md• L5-30 agents/loop-operator.md• L18-37
Loop status and intervention
loop-status observes local Claude transcript JSONL files to show whether active sessions are healthy or need attention. It detects overdue scheduled wakes, stale Bash calls without matching results, and transcript parse errors; it does not control or time out the underlying session.
The command can inspect recent transcripts, one transcript, or a different home directory. Watch mode emits repeated status frames. A write directory creates an index and per-session snapshots for another terminal or watchdog. With --exit-code, attention signals return 2 and scan errors return 1, which lets an external process choose whether to continue, pause, or stop.
References: commands/loop-status.md• L5-19 commands/loop-status.md• L33-72 scripts/loop-status.js• L385-399 scripts/loop-status.js• L529-573 scripts/loop-status.js• L745-799
Review convergence
/santa-loop is an adversarial review loop for code or other task output. It runs two independent reviewers against a shared rubric and allows publication only when both return PASS, called NICE by the command. A failed round becomes NAUGHTY; the operator fixes the findings, commits the fixes, and starts a fresh review round, with escalation after three rounds.
This loop complements epic validation rather than replacing it. Epic validation checks coordination readiness and dependencies, while the review loop checks the quality and safety of the output before a push.
References: commands/santa-loop.md• L5-12 commands/santa-loop.md• L31-64 commands/santa-loop.md• L108-143
Session-oriented delivery
Session history
The /sessions command gives an operator a way to find and inspect saved work context. It lists sessions with project, branch, worktree, and recency data; loads a session by ID or alias; shows session details; and manages aliases for work that needs repeated access.
Session history is useful when several loops or worktrees run at once. The session record carries enough context to distinguish parallel work and to locate the right continuation point without treating an old session as current work. The command reads current records from ~/.claude/session-data/ and supports legacy reads from ~/.claude/sessions/; aliases are separate names that point to session records.
Use /sessions info when an operator needs a compact view of a session's branch, worktree, recency, and content counts. Use /sessions load when the full saved context is needed. This keeps session selection and session content access separate while allowing aliases for repeated access.
References: commands/sessions.md• L5-19 commands/sessions.md• L60-69 commands/sessions.md• L136-143 commands/sessions.md• L208-290 commands/sessions.md• L292-339 scripts/…/session-manager.js• L1-9
Session save and resume
/save-session creates a new dated handoff record at the end of a work period or before a context limit. It captures the goal, confirmed results, failed approaches, open questions, file state, decisions, blockers, and the exact next step. /resume-session reads the most recent or selected record and presents a briefing without changing the historical file or starting work automatically.
The save and resume pair keeps delivery state separate from the code change itself. This allows a later loop iteration to recover the reason for a choice and the next action, even when the original session or terminal is gone.
References: commands/save-session.md• L7-16 commands/save-session.md• L50-64 commands/resume-session.md• L7-15 commands/resume-session.md• L26-39 commands/resume-session.md• L50-92
Session inspection
session-inspect provides a common read surface for plan files, named coordination sessions, Claude history, and skill improvement loops. It can list available adapters and can write the inspection result to a JSON file for another tool or handoff.
Use it when the question is about the shape or health of a session target rather than about changing epic state. This keeps session observation separate from the commands that mutate GitHub coordination or local work ownership.
References: scripts/session-inspect.js• L13-36 scripts/session-inspect.js• L66-97 scripts/session-inspect.js• L100-135
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the coordination schema, issue-body marker, state-to-label mapping, and local epic projection aligned. A change in one can leave GitHub labels or local status silently stale.
- Keep dependency parsing and dependency validation aligned. A new issue-reference or task format must still produce the dependency set used by validation and unblocking.
- Keep the two GitHub sync surfaces distinct. Epic sync owns coordination blocks; work-item sync owns the general issue and pull-request queue.
- Keep GitHub work-item identity, source metadata, status mapping, and stale-record rules aligned. A change in one can create duplicate records or close active work.
- Keep claim rules shared between the CLI and control pane. Divergent owner, status, or terminal-state rules can cause duplicate pickup.
- Keep loop status output, snapshot schemas, and exit-code meanings compatible with watchdogs and sibling terminals.
- Keep save and resume session formats compatible with the session manager and with branch/worktree metadata used to distinguish parallel work.
- Keep session lookup, alias resolution, and legacy storage reads compatible. A change in one can make a saved session or its operator alias appear missing.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Two actors claim an epic at the same time | Both may pass the read-then-write check and claim the same issue | Serialize claim calls outside the coordination action |
| A dependency is missing from the issue list or outside the scan limit | Validation cannot prove the epic is ready | Use a complete issue scope and resolve warnings before publishing |
| Review approval is absent when review is required | Publication is rejected even if dependencies are closed | Run /epic-review and confirm the approved state |
| A GitHub sync limit excludes open records | Records outside the result can appear stale and be closed locally | Set --limit to cover the repository's open issues and pull requests |
| GitHub sync cannot run or returns invalid data | The local queue is not refreshed | Check the GitHub command and its JSON response before acting on the queue |
| A loop has an overdue wake or stale Bash result | The session may be parked or wedged while work appears active | Inspect loop-status and follow its recommended intervention |
--exit-code is combined with unbounded watch mode | The status process cannot finish with a meaningful exit | Set --watch-count for bounded watchdog runs |
| A session file is missing or malformed | Resume cannot restore reliable context | Save a complete new session record and treat missing references as warnings |
| A session alias points to a removed or unreadable session | Alias-based load and info actions cannot find the saved context | Check the target session and recreate the alias when needed |
Key files
| File | Why to read it |
|---|---|
| commands/epic-decompose.md | Entry point for turning an epic body into tracked tasks and dependencies |
| commands/epic-claim.md | Entry point for assigning an epic and starting its coordination state |
| commands/epic-sync.md | Entry point for reconciling GitHub epic state with local snapshots |
| commands/epic-validate.md | Entry point for the dependency and readiness gate |
| commands/epic-publish.md | Entry point for the validated publication step |
| scripts/github-coordination.js | Command router for all epic coordination actions |
| scripts/…/actions.js | Lifecycle rules for claim, sync, validate, review, unblock, and publish |
| scripts/…/state.js | Shared epic state, labels, dependency checks, and local status mapping |
| scripts/…/store.js | Boundary that projects GitHub epics into local work items |
| scripts/work-items.js | General local queue for work records, claims, closure, and GitHub imports |
| scripts/…/work-item-mutations.js | Shared claim and lane rules for command-line and control-pane use |
| commands/loop-start.md | Loop patterns, modes, and startup safety gates |
| commands/loop-status.md | Operator-facing loop health signals and intervention controls |
| scripts/loop-status.js | Transcript analysis, status payloads, watch mode, and snapshots |
| commands/save-session.md | Session handoff record and its required context |
| commands/resume-session.md | Session lookup and read-only continuation briefing |
| commands/sessions.md | Session listing, lookup, aliases, and operator context for parallel work |
| scripts/session-inspect.js | Unified inspection surface for plans, sessions, and skill loops |