herdr-orchestra 0.0.0-stage → 5.0.0

package/CHANGELOG.md

@@ -0,0 +1,224 @@
+# Changelog
+
+All notable changes. Versions follow [semantic versioning](https://semver.org).
+
+## [5.0.0] - 2026-11-12
+
+### Fixed
+- **Links go to github.com again.** Some files pointed at mirror domains in place of github.com and api.github.com: the website's GitHub links (header, footer, docs header, "Star on GitHub"), the PR link `orch finish` prints, and the version lookup and source download in `install.sh` (used for `--version`, `--list` and the git-less fallback). All of them use github.com and api.github.com now.
+
+### Changed
+- **Easier to find.** The npm package has a clearer description, more search keywords (agent orchestration, multi-agent, agentic workflow, Claude Code, Codex, OpenCode) and an author. The README opens with one line on what herdr-orchestra is and the `npx herdr-orchestra@latest` command. The website has a canonical URL on every page, full Open Graph and Twitter cards (docs pages included), `robots.txt` pointing at the sitemap, and a SoftwareApplication JSON-LD block on the homepage. Page titles and a few docs titles use the words people search for, such as "Install herdr-orchestra with npx" and "What is herdr-orchestra?".
+
+## [4.11.1] - 2026-11-12
+
+### Fixed
+- **A reviewer herdr can't find no longer stalls a review in silence.** orch reaches agents by name only. When the reviewer's pane was closed and the agent came back in a new pane without its name, `orch review` failed with "agent not found", put the milestone back in the review queue and tried again every 2 minutes, with one line in `autopilot.log` and nothing else. `ORCH_MAX_LOST` counts coder failures only, so this retry never stopped, and the loud "reviewer is gone" alert fires only when the reviewer disappears in the middle of a review. Now, on the first failed review send, orch shows a desktop alert, puts a `reviewer-lost` event in the lead's queue (the lead is woken), and prints the fix: `herdr agent list`, then `herdr agent rename <pane> reviewer`. The milestone keeps waiting for review with its work kept, and the review goes out on the next loop once herdr finds the reviewer again, instead of after the 2-minute wait. After 3 failures in a row the reviewer is benched for `ORCH_UNREACHABLE_MIN` (30 min, ended early by a rename) and the lead is told once more.
+- **npm publish failures say what to do.** `npx herdr-orchestra@latest` returned E404 because the package was never published: the 4.11.0 publish stopped with EOTP (the `NPM_TOKEN` secret was a token that needs two-factor codes). The Release workflow now explains EOTP and refused tokens in plain words. The fix is a Granular Access Token with Read and write on packages and "Bypass two-factor authentication" ticked (or a Classic Automation token) saved as `NPM_TOKEN`; this release, or a by-hand re-run of the Release workflow, then publishes. A re-run skips the GitHub Release that already exists and only publishes to npm.
+
+### Changed
+- The website hero says in plain words what herdr-orchestra is: a skill you install into the coding agents you already use, plus a small `orch` command.
+
+## [4.11.0] - 2026-11-12
+
+### Added
+- **Install with npx.** `npx herdr-orchestra@latest` installs herdr-orchestra, the same way the curl script did. The npm package carries the release files and a small launcher (`npm/cli.js`) that runs the bundled `install.sh`, so install behaviour lives in one place. Every `install.sh` option works after the name: `--version v4.2.0` (downloads that release from GitHub), `--list`, `--current`, `--uninstall`, `--no-herdr-skill`. Needs Node, bash, python3 and git (no native Windows; use WSL).
+- **npm publish is part of the release.** After the GitHub Release is made, the Release workflow publishes the same version to npm (with provenance) when the `NPM_TOKEN` repository secret is set, and skips it with a warning when it is not. A version already on npm is left alone. CI and the release check that `package.json` and `VERSION` match, and CI installs from the packed tarball.
+
+### Changed
+- `install.sh` run from the npm package installs `vX.Y.Z` (not `-dev`). The README, website and install docs show npx first; the curl command stays as the way to install without Node.
+
+## [4.10.1] - 2026-11-12
+
+### Changed
+- **Releases are made by themselves.** When a merge to main carries a `VERSION` that has no release yet, the Release workflow runs the tests, tags `vX.Y.Z` on that commit and publishes the GitHub Release with its own `install.sh`. Nobody has to push a tag after merging. A tag pushed by hand still works and must match `VERSION`; a version whose tag already sits on another commit fails loudly. `scripts/release.sh` no longer tags.
+
+## [4.10.0] - 2026-11-12
+
+One installed tool is enough for a whole team. A developer with only Codex (or only Claude Code, or only OpenCode) opens one pane, and the lead builds and opens the rest from that same tool.
+
+### Added
+- **`orch team <kind> [--coders N] [--models a,b] [--no-reviewer]`**: the plan's team built from one tool. It picks coders spread over the tiers the model catalog allows for that tool (two by default: the weakest and the strongest) and a reviewer on the strongest, and prints the `Workers:` and `Reviewer:` lines. For Codex: `codex-1 (codex: gpt-6-luna)`, `codex-2 (codex: gpt-6-sol)`, `reviewer (codex: gpt-6-sol)`. It says when the tool has no allowed high-tier model. Read-only, and it works outside a repo.
+- **`orch team up [--dry-run]`**: after `orch start`, opens a herdr pane for every worker and the reviewer in the plan that herdr can't find. Each pane is split from the lead's pane, starts in the agent's folder (its worktree, or the repo), runs the tool on its plan model, and gets its plan name. Agents that already run are left alone, so it is safe to run again. It reports `WAITING` with the rename command when a new pane stops at a first-run question, and exits 3 while any agent is not ready.
+
+### Changed
+- **The plan playbook builds the team when the lead is alone.** When `herdr agent list` shows no agent pane besides the lead, the lead runs `orch team <its kind>`, writes the lines into the plan, and tells the developer how many windows will open. The run playbook runs `orch team up` when `orch start` shows a missing agent, then `orch start` again. Worktree setup no longer asks the lead to split panes by hand.
+- The reviewer can be another pane of the same tool as the coders (the playbook and README no longer point to AGY).
+
+## [4.9.0] - 2026-11-12
+
+The feature decides how many milestones a plan has. Small features no longer get split because coders are free.
+
+### Changed
+- **The lead sizes the plan to the feature.** The planning playbook no longer has a milestone budget (1–2 small, 3–4 medium, never more than 4) or the rule that split backend and frontend "even when the feature is small". The lead now writes a `## Feature breakdown` first (the real pieces of work and how they connect), starts from one milestone, and splits a piece off only when another coder can build it in parallel, other work has to build on it first, or the whole is too big for one sitting. More coders never means more milestones. Contract, scaffold and integration milestones are made only when the feature needs them.
+- **`orch sync` no longer warns above 4 milestones.** `ORCH_MAX_TASKS` is unset by default; set it to get the warning above a number of your own.
+
+### Added
+- **`Why separate:`** on a milestone: why it is its own milestone. In a plan with two or more enabled milestones, `orch sync` warns for each one without it. Plans written for 4.8 keep working (a warning, never an error); a plan with one milestone needs nothing. `orch fix` writes the line for the follow-up milestone it adds.
+
+## [4.8.0] - 2026-11-12
+
+### Added
+- **`orch fix Mn "<change>" [--to <worker>]`**: a change to something a milestone already landed, without a new planning round. It adds one small follow-up milestone to `plan.md` (depends on Mn, same Likely files, tier and review setting), already dispatched to the coder who built Mn, and starts the event manager. The check, the review and the summary apply as for any milestone. It works after ALL_DONE and during a run; the developer or the lead may run it (`--to` names another coder). The lead playbook's ALL_DONE section now tells the lead to use it when the developer asks for a change after the summary.
+
+### Changed
+- When the summary is written again (a fix after ALL_DONE), the earlier one is kept as `.orchestrate/summary.prev.md`, so the lead's notes and checklist are not lost.
+
+## [4.7.0] - 2026-11-11
+
+The lead is back in the run, without giving up the single crash-safe driver: it plans, picks a model tier for every milestone, dispatches, pauses, and is woken by events. Plans written for 4.6 keep working.
+
+### Added
+- **Event-driven lead.** With a `Lead:` line in the plan, a run works like a call stack: the lead dispatches milestones (`orch dispatch M1 M2`) and pauses; `orch autopilot` is now the **event manager**: it sends the work, watches the agents, checks, reviews and merges as before, and wakes the lead with one prompt (`orch events`) when a milestone lands, a coder asks a question, a milestone fails or is held, or new work is ready. The lead decides and pauses again. At ALL_DONE the lead is woken to finish the summary.
+- **A queue that loses nothing.** Each event is stored in `state.json` in the same write as the change that caused it. The lead is woken only when it is idle, once per batch; an unread batch is sent again after `ORCH_LEAD_REWAKE_S` (300 s), up to `ORCH_LEAD_MAX_WAKES` (3) times, and then you are told. Reading `orch events` is the acknowledgement (`--peek` looks without acknowledging). Blocking events stay open until their milestone moves on.
+- **`orch answer Mn "<text>"`**: the developer's answer goes under the milestone's "Notes from user" in `plan.md`, and the milestone goes back to the same coder with its saved work.
+- **`orch dispatch Mn... [--to <worker>] [--tier <tier>]`**: start or restart milestones. It starts the event manager when none is running (`ORCH_NO_AUTOSTART=1` turns that off). While the event manager waits for the lead or for you, it stays up and its waiting time does not count against `Budget:`.
+- **A run never stalls on the lead.** Ready milestones the lead has not dispatched after `ORCH_LEAD_WAIT_MIN` (15) start by themselves; a lead pane that is gone is reported once. `Lead mode: off` gives the 4.6 behaviour: autopilot dispatches by itself and exits 3 when it needs you.
+- **Model catalog** (`models.default.toml`, yours in `~/.config/herdr-orchestra/models.toml`): each model has a tier (small, medium, high), 1–5 ratings for reasoning, coding, architecture, instruction following, tool use, planning and speed, its context window, and the evidence for the ratings. A tier has a reasoning floor. `orch models`, `orch models show <id>`, `orch models check <id>`.
+- **Model policy.** `[policy] deny` keeps ultra-premium models (`*fable*`, `*astra*`) out of runs: `orch sync` refuses a plan that names one, and `orch agents launch` refuses to build the command.
+- **Tiers in the plan.** `Workers: claude-1 (claude: sonnet)` records the model each pane runs; milestones take `Tier:`, `Needs:` and `Model why:`. `orch sync` warns when no coder reaches a milestone's tier, when the reviewer is weaker than the work, when the lead is not on a high-tier model, and when a model is not in the catalog. `task.json` carries `tier` and `needs`.
+- **Tier-aware dispatch.** `orch pick` gives a milestone to a free coder of its tier, or a stronger one; never a weaker one while a suitable coder exists.
+- **One escalation.** A milestone out of fix or review rounds gets one fresh round on a coder with a stronger model (`orch escalate`), with the work so far, before it fails.
+- **Planned against actual.** Every attempt records its model. `summary.md` has a table of planned tier, the models that ran, and escalations; `orch report` adds per-model rows (tries, merged, first pass, moved up).
+- `orch agents launch <kind> --model <id>` and the registry key `model_flag`.
+
+### Changed
+- The lead playbooks: `orch lead plan` adds model discovery and a tier per milestone, and ends by waiting for your go; `orch lead run` is the dispatch, pause, wake, decide loop.
+- With a lead in the run, a paused, failed or held milestone no longer ends autopilot: it wakes the lead and keeps waiting (up to `ORCH_LEAD_IDLE_MAX_MIN`, 720).
+- One busy or unsuitable coder no longer blocks the dispatch of other ready milestones in the same pass.
+
+### Upgrade notes
+- A plan with a `Lead:` line now runs in `Lead mode: events`. Add `Lead mode: off` to keep driving it from a terminal only.
+- The default model ratings are starting points with their sources, not benchmarks run by this project. Check the ids against your tools, and re-rate from `orch report`.
+
+## [4.6.0] - 2026-11-11
+
+Answers the architecture review: one driver, checked state transitions, nothing red committed, bounded retries, structured contracts, and a record of what each run did. Plan format and existing commands keep working; in-flight 4.5 runs are migrated on load.
+
+### Changed
+- **Autopilot is the only driver of a run.** While `orch autopilot` runs it holds a lease (`.orchestrate/driver.lock`): a second autopilot is refused, and so is any `orch` command that would change the run from another process (`status`, `ready`, `pick`, `report` and `approve` still work). The kernel frees the lease if autopilot dies. The AI-driven scheduler loop is gone from `orch lead run`: the lead now handles what autopilot stopped on (questions, failed or held milestones, a red baseline) and finishes the summary. Recovery rules live in one place, the code.
+- **The check runs before the commit.** `orch merge` squashes the milestone, runs the check on the merged result and commits only if it passes. A milestone that passes alone but fails once merged commits nothing, and goes back to a coder as an `integration-fix` round (exit 6, counted against the 3 fix rounds). Before this, the commit landed first and the run stopped on a red branch.
+- **Every status change goes through one function** with a transition table and a per-task history. `orch set` only accepts `pending`, `paused`, `failed` and `skipped`; anything else needs `--force` and is logged. `merged` is final.
+- A conflict fix on a milestone the reviewer had already approved is reviewed again; the reviewer gets `resolution.patch` (what changed to resolve it).
+- Milestones that share a `Likely files` entry run one after the other instead of only producing a warning. `Parallel: allow` on a milestone opts out.
+- A red baseline stops autopilot with the failing lines; it no longer leaves a `baseline.txt` behind that made the next run skip the check.
+- `orch poll` returns after 5 s when no agent is working, so a short bench doesn't cost a full wait.
+
+### Added
+- **Crash safety.** A prompt is recorded before it is sent; after a crash it is confirmed with herdr or re-sent to the same agent (`orch resend`, `UNCONFIRMED` event) and never handed to a second coder. A merge is journaled: the next run finishes it if the commit had landed, or undoes the staged squash and merges again from the saved work.
+- **Bounded retries.** Attempts lost to an unreachable, vanished or rate-limited agent are counted (`orch park --lost`); at `ORCH_MAX_LOST` (4) the task fails with the reason. Three failed prompts in a row bench an agent for `ORCH_UNREACHABLE_MIN` (30).
+- **Fresh dependencies.** A worktree's setup command runs again when its lockfiles or manifests changed since its last setup (or the files in `Setup inputs:`), and the main folder gets the same before the merge check.
+- **Contracts as data** (`docs/contracts.md`): `task.json` per milestone, generated from `plan.md` (numbered acceptance criteria, allowed files, interfaces, the commits of its dependencies); `result-N.json` from coders (status, commit, the check, each criterion met or not, optional usage); `review-N.json` from the reviewer (a verdict per criterion, findings). An invalid result gets one request to rewrite it; an unmet criterion is a fix round or a blocker. The `COMMIT:` / `QUESTION:` / `BLOCKER:` line formats still work when the JSON file is missing.
+- **Scope check.** The coder's real diff is compared with `Likely files`: `Scope: warn` (default) lists strays in the summary, `Scope: strict` sends them back.
+- **Risk hold.** A milestone that deletes files, touches migrations, CI configuration or secrets files, changes dependency files it didn't list, or exceeds `ORCH_RISK_MAX_LINES` (1500) is `held` before it lands until `orch approve Mn`. `Risk hold: off` disables it.
+- **Observability.** `.orchestrate/events.jsonl` (one line per transition), per-attempt timing and check timing in state, `orch report [--json]` (time, rounds, first-pass rate, wasted work; tokens and cost only when agents report them), and the report in `summary.md`. `Budget: 3h` in the plan header stops autopilot when its running time is used up.
+- **`orch doctor [kind]`**: checks an installed agent against the real tool (version, whether each launch flag is still in its `--help`, skills, herdr detection). `orch start` warns about a launch flag that is gone. Optional registry keys `version_cmd` and `help_cmd`.
+- `tests/live/`: an opt-in smoke run with real agents, and `tests/fixtures/panes/` for captured pane text. The fixtures shipped are synthetic and labelled so; no live run has been recorded yet.
+- `state.json` carries `schema: 1` and is migrated on load. `ORCH_FAULT` is a test hook that kills orch at a named step.
+
+### Upgrade notes
+- A run that an AI lead was driving by hand should be finished with `orch autopilot`.
+- Every worktree runs its setup command once more after the upgrade (no setup fingerprint was stored before).
+- `orch sync` warns about a milestone without acceptance criteria. It is a warning, not an error, so existing plans keep running.
+
+## [4.5.0] - 2026-11-10
+
+### Changed
+- **One feature branch per run, real commits, one PR.** Planning creates nothing in git. `orch start` creates the plan's `Branch:` (now `feature/<slug>` in every example; `orch sync` warns about `orch/`), and it is the only branch a run makes. Coders work on detached worktrees, and a milestone's work in progress (under review, parked, waiting for a fix or a conflict resolution) is kept in hidden refs under `refs/orch/<branch>/Mn`, which aren't branches and are never pushed. There are no more `orch/<slug>-Mn` branches, and no `orch(Mn)` or `wip(Mn)` commits on your branch.
+- Each landed milestone is one commit whose subject is the coder's `COMMIT:` report line (what changed, e.g. `feat(api): add categories endpoint`), falling back to the milestone title, with a `Milestone: Mn` trailer.
+- Shared mode parks unfinished work into the milestone's hidden ref (`git stash`) and restores it for the next coder, so the tree is clean between milestones.
+
+### Added
+- `orch finish [--no-push]`: final check, removes the worktrees and hidden refs (and task branches left by older versions), pushes the feature branch and opens a PR into the base with `gh`, or prints the compare link. Autopilot never pushes by itself.
+- Plan header: optional `Base: <branch>` and `Commits: per-milestone | single` (`single` squashes the run into one commit at finish).
+- `orch requeue-review Mn`; `orch cooldown` accepts the reviewer and a reason (`gone` ends the bench as soon as herdr sees the agent again).
+- `orch poll` reports `ORPHAN Mn` for a task that looks in progress but whose prompt never went out.
+- In-flight runs from older versions keep their work: an existing `orch/<slug>-Mn` branch is picked up into the hidden ref.
+
+### Fixed
+- Autopilot no longer crashes in shared mode when a coder hits a rate limit or disappears (the next coder found a dirty tree).
+- Autopilot no longer crashes when the reviewer disappears (`cooldown reviewer` raised a KeyError), and the milestone now waits for review instead of being rebuilt by a coder.
+- A failed `herdr agent prompt` no longer crashes autopilot and leaves the task stuck in `coding`, which made every later run loop forever. `send`, `send-job` and `review` exit 5 and put the task back with its job kept; `send-job` no longer drops the job before it is delivered; and an orch error in one task pauses that task instead of stopping the run.
+- A GONE agent was benched for 600 minutes; it is now 10 minutes and ends as soon as the agent is back.
+- `orch set Mn pending|paused|failed` frees the coder and the reviewer like `orch park`.
+- Agent status is read from the `status` field of `herdr agent get`, so names or paths containing "working" or "blocked" are no longer misread.
+- `orch sync` frees a coder whose milestone left the plan or is no longer in progress, and drops `reviewer_busy` when the reviewer changes.
+- herdr calls time out (`ORCH_HERDR_TIMEOUT_S`, 30 s), and every command takes a lock on `.orchestrate/state.lock`, so concurrent commands can't lose updates.
+- After the integration check fails, the next autopilot run re-checks the branch and stops until it passes.
+- `Key: value` lines inside `## Global instructions` no longer override the plan header.
+- Starting on the feature branch itself no longer records the branch as its own base.
+- A mistyped task id or missing argument is a clean error, not a traceback.
+
+## [4.4.0] - 2026-11-09
+
+### Added
+- **`orch agents sync [kind...]`**: install the `orch-plan` / `orch-run` skills and slash commands into the shared dirs and every installed agent's folders. Run it after installing a new agent (Claude, Hermes, Amp, …) instead of re-running the installer; it reports `NEW` vs `ok` per agent, is idempotent, and records every written path in the uninstall manifest. Optional kind arguments restrict it to those agents.
+- `orch sync` warns when 2+ coders get a plan where every milestone waits for the one before (only one coder would work), and when 1 coder gets independent milestones in worktree mode.
+
+### Changed
+- `install.sh` now calls `orch agents sync` for the per-agent copy (one implementation); on Python < 3.11 it falls back to the shared dirs only, as in 4.2.
+- `orch agents check` and `orch agents` now point at `orch agents sync` instead of "re-run the installer" when skills are missing.
+- **The lead splits work for the team it has.** With 2+ coders, a feature that spans backend and frontend (a monorepo's `apps/api` + `apps/web`, or server + client folders) is split by side so both coders work at the same time: a small contract milestone for the shared types, then backend ∥ frontend. With 1 coder it stays one milestone after another in shared mode. The plan playbook now also maps a monorepo's apps and packages during research.
+
+### Fixed
+- The plan playbook's preflight no longer stops a lead that really is in a Herdr pane. It used to test `$HERDR_ENV` in the agent's shell tool, but Herdr's pane env doesn't reach that shell for agents whose tools run in a background process (Hermes runs every session in one gateway). The new `orch lead check` passes on `HERDR_ENV=1`, falls back to asking the herdr server (`herdr pane current`), and when it fails says how to fix it, including the Hermes `terminal.client_env_passthrough` setting.
+- `orch lead whoami` warns when `HERDR_PANE_ID` is unset, because herdr then reports the focused pane.
+
+## [4.3.1] - 2026-11-08
+
+### Fixed
+- `install.sh`: the herdr skill step no longer reads from stdin. Under `curl | bash`, npx was swallowing the rest of the installer script. It now also passes `-y` to `skills add`, and when the step fails it prints the exit code, the last lines of npx's output and a log path instead of a bare warning.
+
+## [4.3.0] - 2026-11-08
+
+### Added
+- **Any installed agent can be lead, coder or reviewer**: Claude Code, Codex, Amp, OpenCode, Hermes, Antigravity (`agy`), or any agent that runs shell commands. You pick the lead by starting the plan playbook in its pane. Universal form: "Run `orch lead plan` and follow it. Feature: …".
+- `orch lead plan` / `orch lead run` print the lead playbooks (now in `playbooks/`, versioned with `orch`). `orch lead whoami` shows the lead's pane and how to name it `lead`.
+- Agent registry: `agents.default.toml` (launch command, herdr detection, roles, skill folders, how to invoke), with overrides in `~/.config/herdr-orchestra/agents.toml`. Commands: `orch agents`, `orch agents launch <kind>`, `orch agents check`.
+- Optional `Lead: lead (<kind>)` plan header. `orch sync` rejects a lead that is also a worker or the reviewer.
+- Agents herdr can't watch (`herdr_detect = false`, or a kind missing from the registry) rely on their done file and time budget: no GONE/BLOCKED/IDLE for them, `detect:off` in `orch status`. Panes herdr doesn't recognise as agents can be addressed as `name (kind @pane:<id>)`; prompts are typed into the pane, and `orch start` reports a stale pane id.
+- Claude Code slash commands `/orch-plan`, `/orch-run` (`~/.claude/commands/`).
+- The installer puts the skills into every installed agent's skill folder, prints which agent got what and how to start the lead in it, and records everything in a manifest so `--uninstall` removes exactly what it installed.
+
+### Changed
+- `skills/` and the OpenCode commands are thin wrappers that run `orch lead plan|run`.
+- Codex's launch command is now `codex --approve-for-me` (codex-cli 0.167 no longer has `--full-auto`).
+- The agent registry needs Python 3.11+ (`tomllib`). On older Python, plans and autopilot keep working as in 4.2.
+
+## [4.2.0] - 2026-11-07
+
+### Added
+- **Review pipelining (worktree mode):** when a milestone passes its checks, it's committed to its branch and the coder is freed straight away (`orch handoff`). The coder takes the next ready milestone while the reviewer works. Review findings become a **fix job** (`orch needs-fix`) for the next free coder, preferring the one who built it. Fix and conflict jobs are dispatched before new milestones.
+- **Lead researches; coders own the how.** The planner has a research phase and writes milestones as issues: Goal, Why, Acceptance criteria, Constraints, Interfaces, Context (facts), Out of scope. Reviews report problems only (`BLOCKER: file:line — what — why`). Fix and conflict jobs describe the problem and leave the solution to the coder.
+- **Better dependency planning:** the "could B be built if A never existed?" test, a reason required for every dependency (`Depends on: M1 (what it needs)`), scaffold-first for hotspot files, contract-first for parallel milestones, integration last.
+- `orch sync` warnings: dependency without a reason; shared hotspot files (`package.json`, lockfiles, routes, `App.tsx`, `pubspec.yaml`, `go.mod`, `docker-compose.yml`…) in parallel milestones; code blocks or step-by-step "how" in a milestone; independent milestones in shared mode.
+- Curl install from the GitHub Release: `curl -fsSL https://github.com/arunnarangali/herdr-orchestra/releases/latest/download/install.sh | bash`. Each release attaches an `install.sh` that installs that version (`/releases/download/vX.Y.Z/install.sh`).
+- Installing from a git checkout at a release tag installs as that version; other commits install as `vX.Y.Z-dev`.
+- Commands: `orch handoff`, `orch needs-fix`, `orch send-job`, `orch review-ok`. `orch ready` lists `FIX` jobs first.
+
+### Changed
+- Review diffs are taken against the merge-base, and from the task branch once the coder has moved on.
+- Merge conflicts are queued as jobs for any free coder (up to 2 per milestone).
+- `orch pick` prefers the coder who last worked on the milestone.
+
+## [4.1.0] - 2026-11-07
+First release in this repository.
+
+### Added
+- `orch autopilot`: runs the whole plan with no AI in the loop. Handles dispatch, checks, fix rounds, reviews, conflicts and merges, and stops only when a human is needed (desktop notification + `.orchestrate/autopilot.log`).
+- `orch write-task`: builds worker task files from the plan, plus the reports of merged dependencies.
+- `orch nudge` and `orch version`.
+- Milestone budget: the planner targets 1–2 milestones for small features and 3–4 for medium; `orch sync` warns above 4 (`ORCH_MAX_TASKS`).
+- Context-budget rules for the AI lead: short reports, long polls, fresh-session checkpoints.
+- Curl installer with versions (`--version`, `--list`, `.orch-version` pinning, `--uninstall`).
+- End-to-end test suite with fake agents; CI and tag-driven releases.
+
+### Fixed
+- Review snapshots no longer reset the git index, which used to cancel an in-progress merge and loop forever on conflicts.
+- Re-reading the plan keeps each task's progress data: review approval, reports, conflict count.
+
+## Before this repository (kit zips)
+- **v4.0**: autopilot prototype.
+- **v3**: pool of coders (Claude + Codex), task dependencies, worktree and shared modes, the `orch` state CLI.
+- **v2**: shared skills so Amp or OpenCode can lead.
+- **v1**: single coder/reviewer playbook; done files replace herdr wait callbacks.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arun Narangali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,268 @@
-# Temporary Holding Version
+# herdr-orchestra
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Orchestrate AI coding agents as one team in [Herdr](https://herdr.dev).** A lead agent plans, coders build in parallel, a reviewer checks every diff, and you get one pull request. Works with Claude Code, Codex, OpenCode, Amp, Hermes and Antigravity.
+
+```bash
+npx herdr-orchestra@latest
+```
+
+[![npm](https://img.shields.io/npm/v/herdr-orchestra)](https://www.npmjs.com/package/herdr-orchestra) [![Website](https://img.shields.io/badge/website-herdr--orchestra.vercel.app-f5a524)](https://herdr-orchestra.vercel.app/)
+
+**Website and docs: [herdr-orchestra.vercel.app](https://herdr-orchestra.vercel.app/)** · [Install](#install) · [Quick start](https://herdr-orchestra.vercel.app/docs/quick-start/)
+
+## What is herdr-orchestra?
+
+Run a small team of AI coding agents inside [Herdr](https://herdr.dev). An AI **lead** writes the **orchestration plan**, picks the level of model each step needs, hands out the work and then pauses. A **pool of coders** builds it, in parallel git worktrees when tasks are independent, each on a model that fits its task: a small fast one for simple work, a stronger one where reasoning is the hard part. An optional **reviewer** checks every diff. A plain script, the **event manager** (`orch autopilot`), runs the **orchestration run**: it watches the agents, runs checks, merges, and wakes the lead only when something needs a decision. **Any installed agent can play any role**: Claude Code, Codex, Amp, OpenCode, Hermes, Antigravity (`agy`), or anything else that can run shell commands.
+
+```
+ you ──► lead: ORCHESTRATION PLAN  (1–4 milestones, dependencies, a model tier for each, and why)
+                    │  you read it, edit it, say go
+                    ▼
+         lead: orch dispatch M1 M2 ──► lead pauses (no AI running, nothing to pay for)
+                    │
+                    ▼        ORCHESTRATION RUN — the event manager (orch autopilot, a plain script)
+        ┌─────────── sends each milestone to a free coder on a model of its tier
+        │          code ──► checks ──► review ──► one commit on feature/<name>
+        │            ▲   fail ┘   blocker ┘   conflict ┘      (out of rounds: one go on a stronger model)
+        │
+        └── event queue ──► wakes the lead:  finished · question · failed · held · ready
+                                 │
+                 lead decides ◄──┘  dispatches what is ready, asks you when only you can answer,
+                 then pauses again  `orch answer` sends your answer back to the same coder
+                                                               ▼
+                         ALL_DONE ──► lead writes the summary ──► orch finish: push, open a PR into main
+```
+
+## Who does what
+
+| Agent | Does | Never does |
+|---|---|---|
+| **Lead** (any agent; you pick it by starting the playbook in its pane) | Researches the codebase; writes 1–4 milestones as issues (goal, why, acceptance criteria, constraints, interfaces, context facts, dependencies with reasons); gives each a model tier with the reason; dispatches the work, pauses, and is woken to decide: what to start next, a coder's question (asking you when only you can answer), a failed or held milestone, the final summary | Writes code, tells coders how to implement or fix, prompts or polls agents |
+| **Coders** (any agents: Claude, Codex, Amp, OpenCode, Hermes, AGY…) | Own the how: design, code, tests, fixing failed checks, fixing review findings, resolving conflicts | Change scope or skip acceptance criteria |
+| **Reviewer** (any spare agent, or another pane of the same tool) | Reports problems: `BLOCKER: file:line — what — why` | Edits code or prescribes fixes |
+| **Event manager** (`orch autopilot`, a script) | Sends work to coders of the right tier, watches every agent, runs checks, sends fixes and reviews, merges; queues every event and wakes the lead when it is idle | Thinks, or decides anything the lead or you should |
+
+The lead decides one technical thing: the **interfaces between milestones that run in parallel** (API shape, shared types, table columns), so two coders don't invent different versions.
+
+## Install
+
+```bash
+npx herdr-orchestra@latest
+```
+
+Requirements: [herdr](https://herdr.dev), Node (for npx), git, python3 (3.11+ for the agent registry). Node is also what installs the official herdr skill.
+
+The package is published from every GitHub Release, so `@latest` is the newest release (not the `main` branch). No Node? Use the script from the release instead: `curl -fsSL https://github.com/arunnarangali/herdr-orchestra/releases/latest/download/install.sh | bash`. Prefer git? `git clone https://github.com/arunnarangali/herdr-orchestra.git && cd herdr-orchestra && git checkout v4.11.1 && bash install.sh`
+
+It installs:
+
+| What | Where |
+|---|---|
+| `orch` CLI (scheduler + autopilot) | `~/.local/bin/orch` |
+| `orch-plan`, `orch-run` skills (read by Amp and OpenCode) | `~/.agents/skills/` |
+| `/orch-plan`, `/orch-run` OpenCode commands | `~/.config/opencode/commands/` |
+| every installed version, side by side | `~/.local/share/herdr-orchestra/` |
+
+Install once — you don't need to run the installer again when you add an agent. After installing Claude, Hermes, Amp or anything else, run:
+
+```bash
+orch agents sync
+```
+
+It finds every installed agent (binary on `PATH`), copies the `orch-plan` / `orch-run` skills and slash commands into that agent's folders, and records them so `--uninstall` still removes exactly what was installed. `orch agents` prints a hint when a new agent is missing its skills.
+
+## Versions
+
+Every release is a git tag (`v4.2.0`) with a GitHub Release that carries its own `install.sh`. Every installed version is kept side by side, so switching back is instant.
+
+```bash
+# install a specific version
+npx herdr-orchestra@4.2.0            # that npm release
+npx herdr-orchestra@latest --version v4.2.0   # or download any tag from GitHub
+
+# list versions
+npx herdr-orchestra@latest --list
+
+# pin a version for one project: commit this file, then run the installer from that folder
+echo v4.2.0 > .orch-version
+
+orch version                         # what's active now
+npx herdr-orchestra@latest --uninstall
+```
+
+Without Node, the same options work through the release script: `curl -fsSL https://github.com/arunnarangali/herdr-orchestra/releases/latest/download/install.sh | bash -s -- --list` (or `--version v4.2.0`, `--uninstall`).
+
+Version choice, first match wins: `--version` flag › `ORCH_VERSION` env › `./.orch-version` › the release the script (or npm package) came from.
+
+## Use
+
+1. **Start the team** in herdr, one pane each. `orch agents launch <kind>` prints each agent's command:
+
+   | Pane | Example command | Rename to |
+   |---|---|---|
+   | Lead | any agent, e.g. `claude` or `opencode` | `lead` (the playbook does it) |
+   | Coder (medium work) | `claude --permission-mode acceptEdits --model sonnet` | `claude-1` |
+   | Coder (small work) | `claude --permission-mode acceptEdits --model haiku` | `claude-2` |
+   | Reviewer (optional) | `claude --model opus`, `agy --mode accept-edits` or a spare agent | `reviewer` |
+
+   `orch agents launch <kind> --model <id>` prints the command with the model; `orch models` lists the models and their tiers. Use whatever your installed agents already reach.
+
+   **Only one tool installed, or just one window open?** Open only the lead and start the plan playbook. The lead sees it is alone and builds the team from its own tool: `orch team codex` picks coders and a reviewer of that tool on the models the catalog allows, spread over its tiers, and the lead writes them into the plan. When you say go, `orch team up` opens their panes next to the lead, each in its own folder and on its model, and names them. You never type either command yourself (you can: `orch team codex --coders 1`, `orch team up --dry-run`). Each pane is a separate session of the same tool, on your existing login.
+
+   ```
+   you (1 Codex pane) ──► $orch-plan add a login page
+                             lead: only me here → orch team codex
+                             Workers: codex-1 (codex: gpt-6-luna), codex-2 (codex: gpt-6-sol)
+                             Reviewer: reviewer (codex: gpt-6-sol)
+                  you ──► go
+                             orch start → orch team up → 3 more Codex panes open → the run as usual
+   ```
+
+2. **Orchestration plan:** start the plan playbook in the lead's pane (see [Choose your lead](#choose-your-lead)). The lead researches, writes `.orchestrate/plan.md` and shows you the milestones, which coder and model each one goes to, and why. Edit the plan if you like: dependencies, tier, review yes/no, your answers to open questions.
+3. **Orchestration run:** tell the lead **go** (`/orch-run`). It dispatches the milestones (`orch dispatch M1 M2`), which starts the event manager, and pauses. From here the run looks after itself:
+   - a milestone finishes → the event manager checks and merges it, then wakes the lead, which dispatches what that unlocked;
+   - a coder asks a question → the lead is woken; if the plan or the code already answers it, it answers, otherwise it asks you in its pane. `orch answer M2 "<your answer>"` writes the answer into the plan and the **same coder** carries on with its work;
+   - a risky change is **held** → you look and run `orch approve Mn`.
+
+   You can also start the event manager yourself: `orch autopilot` in a spare terminal. It is the only driver of a run: while it runs, other `orch` commands that would change the run are refused (`orch status`, `orch report`, `orch approve` and the lead's `orch events` / `orch dispatch` / `orch answer` still work).
+4. **If the lead is away** (its pane is closed, or it never reads its events): nothing is lost, the events wait in the queue. Ready work starts by itself after 15 minutes, you get a desktop notification, and `orch events --peek` shows what is open. With `Lead mode: off` in the plan header there is no lead in the run at all: `orch autopilot` dispatches by itself and stops (exit 3) when it needs you.
+5. **When it's done:** read `.orchestrate/summary.md` and test it. Want a change? Tell the lead (for example "the login button should be blue"). It runs `orch fix M1 "the login button should be blue"`: one small follow-up job goes straight to the coder who built M1, with the check and review as before, and no new plan. You can run `orch fix` yourself too. When you are happy, run `orch finish`. It re-runs the check, removes the worktrees, pushes `feature/<name>` and opens a PR into `main` (with `gh`, or prints the compare link).
+
+### Git: one branch per run, real commits, one PR
+Planning touches no git at all. `orch start` creates the plan's `Branch:` (`feature/<slug>`) and that is the only branch a run makes: coders work on detached worktrees, and a milestone's work in progress (under review, parked, waiting for a fix) lives in hidden refs under `refs/orch/`, which `git branch` doesn't list and `git push` doesn't send. Each milestone lands as **one commit whose message says what changed** (the coder's `COMMIT:` line, e.g. `feat(api): add categories endpoint`, with a `Milestone: M2` trailer). `Commits: single` in the plan header squashes the run into one commit at finish.
+
+A good feature request: Feature · Why · Must · Must not · Already decided · Done when · Mode (`shared` or `worktree`).
+
+### Models and tiers
+The lead does not pick a model by its name. It reads the catalog (`orch models`), which rates each model 1–5 on **reasoning, coding, architecture, instruction following, tool use, planning and speed**, records its context window, and says where each rating comes from. Each model serves one tier, and a model needs enough reasoning for its tier: coding skill alone never makes a model `high`.
+
+| Tier | For | Examples from the default catalog |
+|---|---|---|
+| **small** | classification, renames, docs, config, mechanical edits | `haiku`, `gpt-6-luna`, `qwen3.6-35b-a3b` |
+| **medium** | normal implementation, tests, debugging inside one module | `sonnet`, `gpt-6-sol`, `qwen3.8-27b` |
+| **high** | the lead itself, contracts and architecture, cross-module refactors, auth / payments / schema, escalations | `opus`, `deepseek-v4-pro`, `glm-5.3` |
+
+In the plan, each coder carries the model its pane runs, and each milestone says what it needs:
+
+```
+Workers: claude-1 (claude: sonnet), claude-2 (claude: haiku)
+
+## [x] M2: Import endpoint
+Tier: medium
+Needs: coding, tool-use
+Model why: one module, a clear contract, an existing endpoint to copy; no design decisions.
+```
+
+- **Dispatch follows the tier.** A milestone goes to a free coder of its tier, or a stronger one when none is free; never to a weaker one while a suitable coder exists.
+- **One escalation.** A milestone that runs out of fix or review rounds gets one fresh round on a stronger model, with the work so far, before it fails.
+- **Policy.** Ultra-premium models (`*fable*`, `*astra*`) are kept out of runs: `orch sync` refuses a plan that names one. Everything else your agents reach is allowed, open-weight models included. Edit `[policy] deny` to change the list.
+- **Checked against reality.** `summary.md` has a table of planned tier against the model that really did each milestone, and `orch report` shows first-pass rate and escalations per model. When a model does worse than its rating, lower the rating.
+- **Yours to change.** Add or re-rate models in `~/.config/herdr-orchestra/models.toml` (merged over `models.default.toml`). The default ratings are starting points with their sources, not benchmarks run by this project. A model that is not in the catalog still works; it just has no tier.
+
+### Choose your lead
+The agent whose pane you start the plan playbook in becomes the lead. It names its pane `lead` and writes `Lead: lead (<kind>)` into the plan; it never codes or reviews in its own run (`orch sync` rejects that). Give it a high-tier model: planning and coordination are reasoning work. Another pane of the same kind as a coder is fine.
+
+| Lead | Start it with |
+|---|---|
+| Claude Code | `/orch-plan <feature>` |
+| OpenCode | `/orch-plan <feature>` |
+| Codex | `$orch-plan <feature>` or "use the orch-plan skill: <feature>" |
+| Amp | "use the orch-plan skill: <feature>" |
+| Hermes | "use the orch-plan skill: <feature>" |
+| Antigravity (`agy`) | "use the orch-plan skill: <feature>" |
+| **any agent** | "Run `orch lead plan` and follow it. Feature: <feature>" |
+
+The skills and slash commands are thin wrappers: the playbooks themselves live in `orch` (`orch lead plan`, `orch lead run`), so every agent follows the same, versioned instructions.
+
+### Agent registry
+`orch agents` shows every known kind: installed or not, roles, whether herdr can watch it, and its launch command. Defaults ship in `agents.default.toml`; add or fix kinds in `~/.config/herdr-orchestra/agents.toml` (merged key by key):
+
+```toml
+[claude]
+launch = "claude --permission-mode acceptEdits"
+model_flag = "--model"        # what `orch agents launch claude --model <id>` appends
+
+[myagent]                     # a new kind
+binary = "myagent"
+launch = "myagent --auto-approve"
+herdr_detect = false          # herdr can't tell its idle/working/blocked state
+roles = ["coder"]
+skills_dirs = ["~/.myagent/skills"]
+```
+
+`orch doctor [kind]` checks an installed agent against the real tool (version, whether the launch flags still exist in its `--help`, skills, herdr detection). `orch agents launch <kind>` prints the command · `orch team <kind>` / `orch team up` build and open a whole team from one tool · `orch agents sync` installs the skills for every installed agent (run it after adding a new one) · `orch agents check` confirms the skills are installed for every installed agent. The installer copies the skills into each installed agent's folders (`~/.claude/skills`, `~/.codex/skills`, `~/.agents/skills`, `~/.hermes/skills`, `~/.gemini/config/skills`) plus Claude Code and OpenCode slash commands.
+
+### Agents herdr can't watch
+For a kind with `herdr_detect = false` (or one missing from the registry, which `orch sync` warns about), `orch` relies only on the **done file and the time budget**: it never reports GONE, BLOCKED or IDLE for it, treats it as free whenever it has no task, and `orch status` marks it `detect:off`. If herdr doesn't recognise the pane as an agent at all, address it by pane id: `Workers: hermes-1 (hermes @pane:w1:p3)`. `orch` then types prompts into that pane, and `orch start` reports a `STALE pane` when the id has changed (`herdr pane list` shows the current ids).
+
+### Milestones fit the feature
+There is no target number. The lead first writes a `## Feature breakdown` (the real pieces of work and how they connect), starts from **one** milestone, and splits a piece off only when that buys something: another coder can build it in parallel, other work has to build on it first, or the whole is too big for one sitting. More coders never means more milestones: a one-field change that touches API and UI is one milestone, even with five coders. In a plan with two or more milestones, each one carries `Why separate: <reason>`, and `orch sync` warns when it is missing. A feature made of several loosely connected parts is better as separate runs. Set `ORCH_MAX_TASKS` if you want a hard warning above a number of your own.
+
+### Dependencies decide parallelism
+For each pair, ask: *"Could B be built and pass its checks if A never existed?"* No → `Depends on: A (what B needs)`. Yes → they can run in parallel.
+- **Contract first:** parallel milestones that must fit together depend on a milestone that defines the interface.
+- **Scaffold first:** edits to shared hotspot files (routes, nav, `package.json`/lockfile, global store, shared types) go in one small first milestone; only it adds packages.
+- **Integration last.**
+
+```
+Frontend:   M1 scaffold (route, nav, packages, types) → M2 component A ∥ M3 component B → M4 wire-up
+Full stack: M1 contract (API + types) → M2 backend ∥ M3 UI → M4 integration
+```
+`orch sync` warns about dependencies without a reason, hotspot files in parallel milestones, "how" written into a milestone, and independent milestones left in shared mode.
+
+### Review pipelining (worktree mode)
+When a milestone passes its checks it's saved to its hidden ref and the coder is **freed immediately**, so it takes the next ready milestone while the reviewer works. Blockers come back as a **fix job** for the next free coder (preferring the one who built it); fix jobs go before new milestones.
+
+### Modes
+- **worktree**: each coder works in `../<repo>-wt/<name>`, independent tasks run in parallel, and each task is squash-merged when it passes checks and review. Start each coder inside its own worktree.
+- **shared**: everyone works in your folder, one milestone at a time. Two agents in one folder would overwrite each other's files and mix their changes, so this is only safe sequentially. Use it when every milestone depends on the previous one.
+
+### What the event manager handles by itself
+| Situation | Behaviour |
+|---|---|
+| Checks fail | sends the last 60 lines back to the coder, up to 3 rounds |
+| Out of fix or review rounds | one fresh round on a coder with a stronger model, if the team has one; then failed, and the lead is woken |
+| The lead is busy, gone, or not reading | events wait in the queue; it is woken once per batch when idle, again after 5 min (3 times), then you are told; ready work starts by itself after 15 min |
+| Reviewer blockers | queued as a problem-only fix job for the next free coder, up to 2 rounds |
+| Merge conflict | the same coder merges the feature branch and resolves it, up to 2 rounds; if the milestone was already approved, the reviewer sees the resolution before it lands |
+| Passes alone, fails once merged | the check runs on the merged result **before** the commit; a failure commits nothing and goes back to a coder as a fix round |
+| A coder hits a usage limit | benches it for 60 min; the other coder continues, with the work so far (also in shared mode) |
+| An agent disappears | coder: its task moves on with the work so far; reviewer: only the review waits. Either is used again as soon as it's back |
+| A prompt can't be delivered | the task goes back in the queue (its job kept) and that agent is retried after 2 min; 3 in a row bench it for 30 min |
+| Attempts keep getting lost (unreachable, gone, rate-limited) | after 4 (`ORCH_MAX_LOST`) the task fails with the history instead of looping |
+| Autopilot is killed mid-step | the next run confirms or re-sends an unconfirmed prompt to the same agent, and finishes or undoes a half-done merge |
+| Lockfiles changed since a folder was set up | the setup command runs again there (and in your main folder before the merge check) |
+| Risky change (deleted file, migration, CI config, secrets file, unlisted dependency change, very large diff) | the milestone is **held** until you run `orch approve Mn`; the rest keeps going |
+| A coder changes files outside its `Likely files` | listed in the summary (`Scope: strict` sends it back instead) |
+| An orch step fails for one task | that task is paused with the error; the others keep running |
+| The final check fails on the branch | stops; the next run re-checks and carries on once it passes |
+| Permission prompt | desktop alert, other tasks keep running |
+| Agent stops early | nudged once, then parked |
+| Worker writes `QUESTION:` | that task and its dependents wait, the lead is woken to answer or ask you; everything else continues |
+
+### Contracts and reports
+`plan.md` stays the file you edit. From it `orch` generates a `task.json` for each milestone (numbered acceptance criteria `AC1…`, allowed files, interfaces, the commits of its dependencies). Coders answer with a `result-N.json` (status, commit message, files changed, the check they ran, each criterion met or not), and the reviewer with a `review-N.json` (a verdict per criterion plus findings). The old line formats (`COMMIT:`, `QUESTION:`, `BLOCKER:`) still work as a fallback. The shapes are in [docs/contracts.md](docs/contracts.md).
+
+Every status change is written to `.orchestrate/events.jsonl`, and `orch report [--json]` shows time per milestone, fix/review/conflict rounds, first-pass rate and wasted work, plus how each model did. Tokens and cost appear only when an agent reports `usage` in its result file.
+
+Optional plan header lines: `Lead mode: events | off` (default `events` when the plan has a `Lead:` line) · `Scope: warn | strict` · `Risk hold: on | off` · `Budget: 3h` (autopilot stops when its running time is used up) · `Setup inputs: <globs>` (which files mean "run setup again"; default: lockfiles and manifests). Per milestone: `Why separate` (why it is its own milestone; needed when the plan has more than one) · `Tier`, `Needs`, `Model why` (see [Models and tiers](#models-and-tiers)) · `Parallel: allow` lets it run next to a milestone that shares its `Likely files`.
+
+### Commands
+`orch status` · `orch report` · `orch approve Mn` · `orch models [show|check <id>]` · `orch events [--peek]` · `orch dispatch Mn... [--to <worker>] [--tier <tier>]` · `orch answer Mn "<answer>"` · `orch fix Mn "<change>" [--to <worker>]` · `orch doctor [kind]` · `orch ready` · `orch autopilot` · `orch lead plan|run|check|whoami` · `orch agents [launch <kind> [--model <id>]|sync|check]` · `orch handoff Mn` · `orch needs-fix Mn` · `orch set M3 pending` · `orch park M2 paused "why"` · `orch cooldown claude-1 60` · `orch cleanup` · `orch finish [--no-push]` · `orch version` · `orch` (full help)
+
+Tunables: `ORCH_CODER_BUDGET_MIN` (45) · `ORCH_REVIEW_BUDGET_MIN` (15) · `ORCH_CHECK_TIMEOUT_MIN` (30) · `ORCH_COOLDOWN_MIN` (60) · `ORCH_MAX_TASKS` (unset: no limit) · `ORCH_GONE_COOLDOWN_MIN` (10) · `ORCH_SEND_RETRY_S` (120) · `ORCH_HERDR_TIMEOUT_S` (30) · `ORCH_MAX_LOST` (4) · `ORCH_UNREACHABLE_MIN` (30) · `ORCH_CONFIRM_S` (30) · `ORCH_RISK_MAX_LINES` (1500) · `ORCH_LEAD_WAIT_MIN` (15: ready work the lead hasn't dispatched starts by itself) · `ORCH_LEAD_REWAKE_S` (300) · `ORCH_LEAD_MAX_WAKES` (3) · `ORCH_LEAD_IDLE_MAX_MIN` (720: how long the event manager waits for an answer) · `ORCH_NO_AUTOSTART=1` (the lead's commands never start the event manager)
+
+## Develop and release
+
+```bash
+bash tests/run.sh          # end-to-end tests with fake agents (no AI, no network)
+bash tests/live/run.sh claude codex   # opt-in: one tiny real run per agent kind (needs herdr and the agents; uses their credits)
+bash install.sh            # install your checkout (vX.Y.Z at a tag, vX.Y.Z-dev otherwise)
+```
+
+Releases are made by themselves. A PR that bumps `VERSION` and adds its `## [X.Y.Z]` section to `CHANGELOG.md` is released when it is merged: the Release workflow runs the tests, tags `vX.Y.Z` on main and publishes the GitHub Release with its own `install.sh`. Nobody pushes a tag. The same workflow publishes to npm with the `NPM_TOKEN` secret, which must be a Granular Access Token with Read and write on packages and "Bypass two-factor authentication" ticked (or a Classic Automation token); a token that asks for two-factor codes fails with EOTP. After fixing the secret, run the Release workflow again by hand: it skips the existing GitHub Release and only publishes to npm. (`bash scripts/release.sh X.Y.Z` still bumps VERSION and checks the CHANGELOG for you; a tag pushed by hand still works, and must match VERSION.)
+
+Semantic versioning: **major** for breaking changes to the plan format or commands, **minor** for new features, **patch** for fixes.
+
+## License
+MIT

package/VERSION

@@ -0,0 +1 @@
+5.0.0