Describe do-epic in the README's tools and setup
CI / tests (pull_request) Has been cancelled

This commit is contained in:
2026-11-19 01:28:11 +01:00
parent b25b7ec0d9
commit 027f441cae
2 changed files with 34 additions and 0 deletions
+3
View File
@@ -150,6 +150,8 @@ cd ~/code/acme-billing && ~/.claude/bin/project-config
The last line prints each setting's path once the config is complete.
`do-epic` keeps its settings per machine, not per project, in `~/.claude-projects/do-epic/`: a `config.toml` and a `repo-rule.md`, the same for every epic. The config sets `jira-url` (the site, such as `https://acme.atlassian.net`), `env-file` (the file holding `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, outside every checkout and config folder) and `repoless-model` (the model that works an item with no repo), and optionally `clone-folder` (where a missing repo is cloned, `~/code` if left out), `language` (the language of Jira text, English if left out), and `jira-finish-transition` and `jira-finish-status`, which close a finished epic as a project's config names them. `repo-rule.md` is prose that tells claude how to tell an item's repo, such as "a label that equals a repo's name names that repo", and may not be blank. do-epic records the answer as a `repo:<name>` label on the issue, and asks you where the rule leaves it unclear. Each repo an epic changes has a project config of its own, as in the rest of this section, and a missing checkout is cloned. `do-epic` fails and names each setting or file it lacks.
A project runs on the routing ladder this setup ships, `bin/model_routing/routing-ladder.json`: the rungs, least competent first, each a model at an effort, that loop-claude routes workers, subagents and reviews to. To run one project on other rungs, as when an outage or a client's account leaves it fewer models, copy that file to `~/.claude-projects/<key>/routing-ladder.json` and cut or change its rungs. Keep one model for each family, such as opus: Claude Code launches a subagent by its family's name. The project's file replaces the shipped ladder whole. loop-claude reads it as each cycle starts, and `subagent-rung` and rule-hook each time they run. The loop never commits it, so commit it in the folder's repo yourself only where it should last. Set the project's models to ones its ladder holds, for example with `LOOP_CLAUDE_WORKER_MODEL` and `LOOP_CLAUDE_JUDGE_MODEL`. A model off the ladder is not routed: every worker runs on that model, at the effort Claude Code's `settings.json` gives. Each cycle of a project on a ladder of its own says so on stderr, naming the file, and says where the worker's model is off it. `loop-claude --help` shows the file's shape.
## Update
@@ -183,6 +185,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `command-patterns [<version>] [--calls <file>]` prints a table of the shell command patterns a release's archived chunks ran, such as `tea pr create`, for an audit of the release, and with `--calls <file>` saves each call as a JSON line; `command-patterns --help` states the columns and the line's keys.
- `compress-archives` gzips each transcript in loop-claude's archive and each file in the review folders 30 days after it last changed, keeping all of them; Install's crontab line runs it daily.
- `deploy-release [--cut] [<checkout>]` moves `~/.claude`, or the checkout named, to the newest release, as Update says; with `--cut`, run in the development clone, it first cuts the next release, as Release says.
- `do-epic <EPIC-KEY>` runs the chunks of one Jira epic whose items span repos, or have none, each in its own window of the tmux session `epic-<EPIC-KEY>`, on the same cycle, judge and interrupt as loop-claude. The epic's description is its record: goals, audience, scoring and decisions. do-epic ranks the epic's items by the epic's goals, then code health, then each repo's goals, starts as many chunks as the epic's `**Max parallel chunks:** 2` line and each repo's `parallel-chunks` allow, parks a chunk whose pull request waits on a gate, and closes the epic only once you confirm every goal. Install → "Set up a project" says how to set it up; `do-epic --help` states the flags and the contract.
- `judge-replay <model> [--offline]` replays loop-claude's judge on archived verdicts of the projects run on the model. It prints what each rung a review climbs to misses, and the lowest rung below those that returns every verdict, as each candidate above it does. With `--offline` it doesn't call a judge: it counts what a "?" rule, a decision table and a classifier trained on the archive decide of each verdict's kind from the worker's final message, and how many interrupts each misses. `judge-replay --help` states both replays.
- `larv-review <command>` holds larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's round count and the opening of its round commit's title, the scoring run's trigger and setup; the comprehension history's format, its latest places and its count of how often seats agree; and each reviewer's prompt header. `larv-review --help` states them. `settings.json` → `hooks` runs `larv-review reviewer-context` as each subagent starts. A reviewer under `agents/` whose frontmatter has `omitClaudeMd: true` starts without `CLAUDE.md`, and the command hands it that file's "Shared goal", "Prose" and "Vocabulary" sections.
- `loop-claude <task>` runs a project's next chunks, each in its own tmux window, cycle after cycle; `loop-claude --help` states its contract.
+31
View File
@@ -2927,3 +2927,34 @@ Read most (opens and searches):
- `bin/do_epic/epic_record.py` 1
- `bin/loop_claude/project/premises.py` 1
- `bin/loop_claude/project/records.py` 1
## Reading cost, chunk d77b99fcaa22, finished 2026-11-18T23:16:50Z
112582 new input tokens before the first commit.
Read most (opens and searches):
- `bin/do_epic/main.py` 7
- `bin/forge/pulls.py` 4
- `bin/chunk_pr/approval.py` 3
- `bin/chunk_pr/main.py` 3
- `bin/do_epic/scheduler.py` 3
- `rules/todo-items.md` 3
- `README.md` 2
- `bin/agent_cycle/tmux.py` 1
- `bin/do_epic/chunk_prompt.py` 1
- `docs/decisions.md` 1
## Reading cost, chunk 12edf0c9126c, finished 2026-11-19T00:27:34Z
96788 new input tokens before the first commit.
Read most (opens and searches):
- `bin/do_epic/main.py` 4
- `rules/todo-items.md` 3
- `bin/do_epic/backend/protocol.py` 1
- `bin/do_epic/chunk_prompt.py` 1
- `bin/do_epic/scheduler.py` 1
- `bin/plan_store/jira_epic.py` 1
- `bin/release_plan/release_standing.py` 1