Introducing a new way to review your PRs.

Read the announcement

affaan-m / ecc

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

View on GitHub

30 documents · Updated Nov 20, 2026

docs / work-items-loops-and-epics

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 actionResult
list / showInspect current local work state
upsertAdd or update a work record from a source
claimAssign an agent or human and start the item
closeMark the item complete with a terminal status
sync-githubRefresh 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.

SurfaceScopeMain source
/epic-syncEpic coordination stateGitHub issue bodies and labels
/epic-unblockBlocked epicsDeclared dependency issue state
work-items.js sync-githubGeneral local queueOpen 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

TriggerConsequenceGuard
Two actors claim an epic at the same timeBoth may pass the read-then-write check and claim the same issueSerialize claim calls outside the coordination action
A dependency is missing from the issue list or outside the scan limitValidation cannot prove the epic is readyUse a complete issue scope and resolve warnings before publishing
Review approval is absent when review is requiredPublication is rejected even if dependencies are closedRun /epic-review and confirm the approved state
A GitHub sync limit excludes open recordsRecords outside the result can appear stale and be closed locallySet --limit to cover the repository's open issues and pull requests
GitHub sync cannot run or returns invalid dataThe local queue is not refreshedCheck the GitHub command and its JSON response before acting on the queue
A loop has an overdue wake or stale Bash resultThe session may be parked or wedged while work appears activeInspect loop-status and follow its recommended intervention
--exit-code is combined with unbounded watch modeThe status process cannot finish with a meaningful exitSet --watch-count for bounded watchdog runs
A session file is missing or malformedResume cannot restore reliable contextSave a complete new session record and treat missing references as warnings
A session alias points to a removed or unreadable sessionAlias-based load and info actions cannot find the saved contextCheck the target session and recreate the alias when needed

Key files

FileWhy to read it
commands/epic-decompose.mdEntry point for turning an epic body into tracked tasks and dependencies
commands/epic-claim.mdEntry point for assigning an epic and starting its coordination state
commands/epic-sync.mdEntry point for reconciling GitHub epic state with local snapshots
commands/epic-validate.mdEntry point for the dependency and readiness gate
commands/epic-publish.mdEntry point for the validated publication step
scripts/github-coordination.jsCommand router for all epic coordination actions
scripts/…/actions.jsLifecycle rules for claim, sync, validate, review, unblock, and publish
scripts/…/state.jsShared epic state, labels, dependency checks, and local status mapping
scripts/…/store.jsBoundary that projects GitHub epics into local work items
scripts/work-items.jsGeneral local queue for work records, claims, closure, and GitHub imports
scripts/…/work-item-mutations.jsShared claim and lane rules for command-line and control-pane use
commands/loop-start.mdLoop patterns, modes, and startup safety gates
commands/loop-status.mdOperator-facing loop health signals and intervention controls
scripts/loop-status.jsTranscript analysis, status payloads, watch mode, and snapshots
commands/save-session.mdSession handoff record and its required context
commands/resume-session.mdSession lookup and read-only continuation briefing
commands/sessions.mdSession listing, lookup, aliases, and operator context for parallel work
scripts/session-inspect.jsUnified inspection surface for plans, sessions, and skill loops