{"id":50725932,"url":"https://github.com/usulpro/epic-loop","last_synced_at":"2026-06-10T04:01:38.612Z","repository":{"id":359980908,"uuid":"1247639038","full_name":"usulpro/epic-loop","owner":"usulpro","description":"Codex skill that runs long autonomous coding sessions via techlead/engineer role split and durable epic state.","archived":false,"fork":false,"pushed_at":"2026-05-24T11:52:01.000Z","size":2125,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T13:24:47.213Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/usulpro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-23T15:29:00.000Z","updated_at":"2026-05-24T11:52:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/usulpro/epic-loop","commit_stats":null,"previous_names":["usulpro/epic-loop"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/usulpro/epic-loop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usulpro%2Fepic-loop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usulpro%2Fepic-loop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usulpro%2Fepic-loop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usulpro%2Fepic-loop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usulpro","download_url":"https://codeload.github.com/usulpro/epic-loop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usulpro%2Fepic-loop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34136112,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-10T04:01:37.101Z","updated_at":"2026-06-10T04:01:38.604Z","avatar_url":"https://github.com/usulpro.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# epic-loop\n\n\u003e A Codex skill for running long autonomous coding sessions without losing the plot.\n\nepic-loop splits a single Codex session into two roles — **techlead** and **engineer** — that hand off through the Codex Stop hook. The techlead plans, the engineer executes, the loop runs until the work is actually done. Epic state lives on disk, so sessions can be resumed by anyone, at any time.\n\n---\n\n## The problem\n\nLong autonomous coding sessions waste hours on human glue:\n\n- Manually prompting the agent for the next step\n- Reviewing output before deciding what comes next\n- Picking and scoping the next task\n- Writing a precise prompt to get the model to do it well\n- Repeat\n\nThese are repeatable patterns. They don't need a human in the loop — they need the right orchestration.\n\nWhen Codex shipped hooks — particularly the **Stop hook**, which can return a continuation prompt to the same session — the orchestration became possible. epic-loop is the skill that makes it usable.\n\n---\n\n## How it works\n\nA single Codex session alternates between two roles, driven by the Stop hook:\n\n```\nsingle Codex session:\n\n  techlead  ──writes prompt for──▶  engineer\n      ▲                                 │\n      └────────── Stop hook ────────────┘\n```\n\n**techlead role.** Gets a standard prompt every turn: read epic state, do the formal work (task tracking, git commits, review, doc analysis), decide what comes next, and write a precise custom prompt for the engineer's next turn. Hands off via the Stop hook.\n\n**engineer role.** Gets a focused, custom prompt for one task. Executes it. Hands back to techlead.\n\n**Single session.** Both roles run in the same Codex session — no second process, no inter-process plumbing. The Stop hook is what makes the alternation possible.\n\n**Durable epic state.** Each epic lives at `.epic-loop/epics/\u003cslug\u003e/` with its own docs, tracker, decisions, and progress logs. Sessions die, contexts compact, machines crash — the epic survives. Any developer can resume any epic in any session.\n\n---\n\n## Modes\n\n- **Implementation** — the techlead/engineer loop described above\n- **Planning** — shaping new epics: creating docs, decomposing tasks\n- **Review** — verifying completed work\n\nModes are explicit. The skill knows which mode it's in and adapts behavior accordingly.\n\n---\n\n## Why this design\n\n**Engineer focuses on one task at a time.** Engineer turns are scoped and clean. The engineer doesn't know about the loop, the tracker, or epic-loop internals — it just executes the prompt it received.\n\n**The loop won't stop until the work is done.** A stop criterion is set up front. Until it fires, the Stop hook keeps the session going.\n\n**Survives context compaction.** Long task lists run cleanly through compaction because each engineer turn gets a freshly composed, scoped prompt — not accumulated session history.\n\n**Resumable.** Epics commit to git. Documentation, prompts, and progress are part of the repo. A new developer can pick up an in-flight epic in a new session without context loss.\n\n**Flexible.** Any process you can describe as a sequence of tracked tasks can run through epic-loop. Long task lists work especially well.\n\n---\n\n## Requirements\n\n- Codex with hooks support\n- Node.js (skill scripts are `.mjs`)\n- A project where you want to run long autonomous coding sessions\n\n---\n\n## Installation\n\nepic-loop is a project-local Codex skill. Drop the skill into `.agents/skills/epic-loop/` in your project, then set up the project-local hooks:\n\n```bash\n# Check technical readiness\nnode .agents/skills/epic-loop/scripts/doctor.mjs\n\n# Install project-local Codex hooks\nnode .agents/skills/epic-loop/scripts/install-hooks.mjs\n\n# Bind the current session to an epic\nnode .agents/skills/epic-loop/scripts/bind-session.mjs \\\n  --current --slug \"\u003cepic-slug\u003e\" --mode implementation\n```\n\nUnbound sessions are silent no-ops — epic-loop only activates for sessions explicitly bound to an epic.\n\n---\n\n## Epic structure\n\nEach epic at `.epic-loop/epics/\u003cslug\u003e/` contains:\n\n```\nstate-of-epic.md        # human-facing current state\ntracker.md              # task list and status\nimplementation-log.md   # what happened, in human-readable form\ndecision-log.md         # decisions and rationale\nrisk-register.md        # known risks\ndocs/                   # epic-scoped documentation\n.runtime/               # machine state and debug traces (hidden from role context)\n```\n\nHuman-facing artifacts and machine runtime are separated by design. Roles read the former; the latter exists for debugging and replay without polluting prompt context.\n\n---\n\n## Useful commands\n\n```bash\n# List local epics\nnode .agents/skills/epic-loop/scripts/list-epics.mjs\n\n# Compact role-facing state for the current epic\nnode .agents/skills/epic-loop/scripts/role-summary.mjs --slug \"\u003cepic-slug\u003e\"\n\n# Inspect runtime/debug state\nnode .agents/skills/epic-loop/scripts/debug.mjs\n```\n\n---\n\n## Status\n\nExperimental and actively used. The skill is the product; the rest of this repository (a Next.js app) is a fixture used to test the skill against a realistic codebase with real builds, hooks, linting, and long-running sessions.\n\nIf you're reading the source, the skill lives at `.agents/skills/epic-loop/`.\n\n---\n\n## Related\n\n- [`codex-bee`](https://github.com/usulpro/codex-bee) — earlier work on long-running Codex sessions; epic-loop is the next iteration, built around the Stop hook rather than a session wrapper.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusulpro%2Fepic-loop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusulpro%2Fepic-loop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusulpro%2Fepic-loop/lists"}