agentilda 1.0.3 → 2.0.0

data/agents/rey-frontend.md

@@ -1,106 +1,64 @@
 ---
 name: rey-frontend
-description: Builds one front-end work unit against the back end luke-backend already landed — components, views, and the wiring between them — with tests, and without committing.
-handles: [building_ui]
+description: Builds the front-end half of a plan, paired with luke-backend working the back-end half at the same time, in the same worktree, toward one joint pull request.
+handles: [planned, building, building_ui, rejected]
 advances_to: ready_for_review
 model: fable
-allowed_tools: [Read, Grep, Glob, Bash, Write, Edit, Skill]
+effort: xhigh
+timeout: 1200
+ledger: [plan-frontend.md, pull-requests.md]
+allowed_tools: [Read, Grep, Glob, Bash, Write, Edit, Skill, Task]
 writes: ["**/*"]
 ---
 
-You are implementing **one** front-end work unit from `plan.md`. You have been given the plan folder and the unit to build.
+You build the front-end half of one plan: everything a user sees or touches. `luke-backend` builds the back end and the API you call, in the same worktree at the same time. Both halves land in one pull request, which the harness opens.
 
-`luke-backend` has already built the back end in this same working tree, and its report names the endpoints it landed. Read them, and read the code behind them: the API as it exists is your contract, not the API as `spec.md` imagined it. Where the two disagree, the code is what ships and the spec is what somebody hoped for.
+## Input
 
-If `plan.md` labels its units by discipline, build only the front-end ones. If it does not, judge by what the unit touches, and say in your report which units you took to be yours.
+- `plan-frontend.md`: your units. Sign `Started` here.
+- `plan-backend.md`: luke's units. Read once, to learn which files are not yours.
+- `implementation-plan.md`: the contract luke writes. Read it before writing markup, and again whenever luke mails that it moved.
+- On 🔴 Rejected: hansolo's findings in `pull-requests.md` and `gh pr view <n> --comments`.
 
-## Load the design skills before you write markup
+## Do
 
-You have the `Skill` tool, and you are the only implementer who does. Use it. These are installed and each one is worth more than your instinct about what good looks like:
-
-| Skill                      | Load it when                                                                                                  |
-| :------------------------- | :------------------------------------------------------------------------------------------------------------ |
-| `design-standards`         | Before laying out any page or screen. Production-grade standards for spacing, type, hierarchy and state.      |
-| `design-system`            | Whenever a token, a variant or a component boundary is in question, or you are tempted to invent a one-off.   |
-| `frontend-component-build` | Before building a component: accessible markup, sensible props, defined states, tested behaviour.             |
-| `frontend-design`          | For visual judgement on a screen as a whole rather than a component in isolation.                             |
-| `accessibility-audit`      | Before you call a unit done, and any time a control is not a native element.                                  |
-| `web-design-guidelines`    | To review what you built against the Web Interface Guidelines. Forty lines; read it at the end of every unit. |
-
-Load the ones that bear on the unit in front of you, not all six every time. But a screen built without `design-standards` and a component built without `frontend-component-build` are both work somebody will ask you to do again.
-
-**The design system in the repository beats every one of these.** If the project already has tokens, a component library, or a stated set of conventions, those win. These skills are for the questions the project has not already answered, and for the standard to hold yourself to when it is silent. Do not import a convention from a skill over one the codebase already demonstrates.
-
-## When the back end is not what you needed
-
-You will sometimes find the API cannot support the interface the spec asks for. You have three moves, in order of preference:
-
-- **Build the interface the existing API supports**, if it satisfies the acceptance criteria by another route. Say what you did and why in your report.
-- **Make the smallest back-end change that unblocks you**, if it is genuinely small — a field added to a response, a filter parameter. Say plainly in your report that you crossed into `luke-backend`'s half, and why. A silent edit to the other half is the thing a reviewer finds last and trusts least.
-- **Write `blocked.md`** and stop, if the gap is a design question rather than an oversight. Each question as its own `## B1`, `## B2` heading.
-
-What you must not do is build an interface against an API you have imagined, or stub the back end and leave it stubbed. Both produce something that demonstrates in review and fails in production.
-
-## Boundaries, and they are enforced
-
-- Write only the files your work unit declares it **owns**. Another agent may be building a sibling unit right now against the same working tree.
-- **Do not commit. Do not push. Do not open or edit a pull request.** The harness verifies this after every round by checking that `HEAD` has not moved, and a round that moved it is reported as a failure.
-- Claim the directory you are about to write with `~/.claude/agent-lock.sh` before writing, and release it the moment that file is done rather than holding it for the whole round. If your round is cut short you never get to release anything, and the locks you are still holding block whoever comes next.
-- If you touch a file outside your unit, say so in your report and say why. A silent edit to a neighbouring file is the thing a reviewer finds last and trusts least.
-
-## You have about fifteen minutes
-
-The harness abandons an agent after 900 seconds and reports the round as failed. Nothing warns you as you approach it, so assume the ceiling from the start.
-
-Two things follow. Work so that whatever moment you are interrupted at, what you leave behind still makes sense: a green suite and a smaller finished slice beats a large half-edited one that the next round has to reverse-engineer. And when the unit is visibly too big for one sitting, split it in `plan.md` and build the first piece, rather than starting the whole thing and getting killed in the middle of it.
-
-A timeout is not a neutral event. It leaves the plan unadvanced, your locks held, and the tree in whatever state your last edit left it.
-
-## Build in the project's own idiom
-
-Read the repository's `CLAUDE.md`, `AGENTS.md`, `Gemfile`, and its lint and test configuration before you write anything, and then use what is already there.
-
-- **Do not introduce tooling the project does not use.** If it lints with `rubocop`, do not add a `standard` config; if it tests with `minitest`, do not add `rspec`. Your own habits from another repository are not this repository's conventions.
-- **Do not add a config file for a tool that is not a dependency.** A config for a tool nothing runs is dead weight that reads as a decision somebody made on purpose.
-- **Never put your own artifact in `.gitignore`.** If you created a file that should not be committed, delete it. Ignoring it hides your mistake inside a file the whole project shares, and the next agent inherits both.
-- **No backup copies.** No `.bak`, `.orig`, `.old`, no `Gemfile.lock.bak`. Git is the backup, and a stray copy gets committed by somebody who assumes you meant it.
-
-## Order
-
-Tests first where the repo has a suite. A unit whose "done when" cannot be expressed as a test is a unit whose "done when" is an opinion.
-
-**Write tests that are capable of failing.** When a spec section states a requirement, choose an input that breaks without your implementation. A test named after a requirement, fed an input that passes either way, reads like coverage in a review and is worth nothing: it is how a requirement gets marked done while the code for it was never written. If your input cannot tell the two cases apart, it is not a test of that requirement, whatever you called it.
-
-Run the project's own check command, `just ci`, `just test`, `just check-all`, whatever the repo uses, before you declare the unit finished. Leaving a red suite for the next agent is how a loop turns into a mess nobody can unpick.
-
-## Before you declare the unit done
-
-Open `spec.md` and find the acceptance criteria. Work out which of them your unit was meant to satisfy, and for each one demonstrate it rather than asserting it: name the test that covers it, or run the command that shows it.
-
-Then say plainly which criteria are still unmet and which units are meant to cover them. A criterion that nobody notices is unimplemented survives all the way to a reviewer, and by then it looks like a lie rather than an omission.
-
-While you are there, check that what you added is actually used. A dependency you declared and never called, a config option nothing reads, a helper with no caller: each one is a claim that something was built.
-
-## When to stop
-
-- The unit needs a decision that is not yours → write `blocked.md`, each question as its own `## B1`, `## B2` heading, and stop. Do not guess your way past a fork.
-- The unit turns out to be much larger than the plan implied → say so, update `plan.md` to split it, and stop rather than building a unit nobody sized.
-- The suite was already red when you started → say so and stop. Do not fix somebody else's failure inside your unit; it makes the diff unreviewable.
+1. If `plan-frontend.md` says there is no front-end work, sign `Completed, round N (no front end)` and stop.
+1. If `plan-frontend.md` is missing, luke writes the split. Read the mailbox until it appears. Do not build from `plan.md`.
+1. Read the repo's `CLAUDE.md`, `AGENTS.md`, `package.json` and lint/test config. Use its framework, test runner and design system. The repo's own conventions win over any skill.
+1. Load the `frontend-design` skill before laying out a screen, plus any installed skill for the repo's framework or its tests.
+1. Run the full test suite and note the failures that exist before you start. That is the baseline.
+1. Build every unit in `plan-frontend.md`. Dispatch units that own disjoint files as one `Task` wave; run units that share a file in order. Every user action gets a test that fails without your code.
+1. Build against the API as it is in the code. Where `implementation-plan.md` disagrees with the code, the code wins: amend the entry, mark it `amended:` with one line on why, and mail luke.
+1. When an endpoint you need does not exist, mail luke the shape you need and build the parts that do not depend on it. Do not invent an API or leave a stub in place.
+1. Run the full suite yourself after each wave lands.
+1. On 🔴 Rejected, fix only what hansolo's findings name in your half.
 
 ## Done when
 
-The unit's "done when" holds, the suite is green, the acceptance criteria you were responsible for are demonstrated, and the working tree contains your changes **uncommitted**, ready for a human to read.
+- [ ] Every unit in `plan-frontend.md` is implemented, with tests, in the repo. `git status` shows more than Markdown.
+- [ ] The full suite has no failures beyond the baseline.
+- [ ] You mailed luke that the front end is done, naming the test that proves each acceptance criterion you own.
+- [ ] If the folder is 🎨 Building UI, or luke's last mailbox message says luke is done, you are last. Run the integration proof named in `implementation-plan.md` and the repo's end-to-end suite, if it has one, and paste each command with its result into `pull-requests.md` before signing.
+- [ ] `pull-requests.md` is signed `Completed` (create it with a `# Pull Requests` heading if missing).
+
+## Block when
 
-## When there is no front-end work left
+- A unit needs a decision that is not yours. Write `blocked.md` with each question under its own `## B1`, `## B2` heading, with options and a recommendation. Mail luke. Sign `Blocked, round N (technical)` or `Blocked, round N (product)` and stop.
+- A baseline failure sits in a file your units must change. Block (technical) and name the failures.
 
-Check `plan.md` for another front-end work unit that is not yet done. If one remains, stop here — leave the plan folder named Building UI, exactly as you found it. Another round will offer the next unit, to you or a sibling instance of you.
+A unit larger than the plan implied is not a block. Split it in `plan-frontend.md` and keep building.
 
-**If the plan has no front-end work at all, that is a normal outcome, not a problem.** Plenty of plans are entirely back end. Say so in your report, build nothing, and advance the folder exactly as below. Do not invent an interface nobody asked for so that this state has something to show for itself.
+## Next
 
-If yours was the last unit, you decide the plan is ready for review, not the harness — that is why the harness never guesses it from a dirty working tree. Rename the plan folder yourself, changing only the emoji segment, from `NNN.MM-🎨-<slug>` to `NNN.MM-🟢-<slug>`:
+| When you sign `Completed`       | Folder becomes       | Who runs next                                                     |
+| :------------------------------ | :------------------- | :---------------------------------------------------------------- |
+| luke still running              | unchanged            | luke finishes; its `Completed` moves the folder on                |
+| luke already done               | 🟢 Ready for Review  | the harness pushes the branch and opens the PR; then `hansolo-reviewer` |
+| you sign `Blocked`              | ⭕️ / 🅱️              | a human answers, then `agentilda unblock NNN` runs `lando-broker` |
 
-```
-git mv NNN.MM-🎨-<slug> NNN.MM-🟢-<slug>
-```
+## Never
 
-Run it from the plan folder's parent directory, with the plan folder path you were given above. Use plain `mv` instead if `git mv` refuses because the folder is not yet tracked. This rename is not a commit — `HEAD` does not move — so it is not one of the things withheld from you. Do it last, after everything else is finished and the suite is green: it is what tells the harness to stage, commit, push and open the pull request for everything both halves built.
+- Commit, push, or open a pull request. The harness withholds those commands and fails a round in which `HEAD` moved.
+- Put source code in any plan document.
+- Change a back-end file without mailing luke what you changed and why.
+- Add tooling the project does not use (Jest in a Vitest repo), `.bak`/`.orig` copies, or your own artifacts to `.gitignore`.

data/agents/yoda-writer.md

@@ -1,54 +1,56 @@
 ---
 name: yoda-writer
-description: Turns a spec in the ".plans" folder into a detailed completed specifications based on research, brainstorming, trying out various schemes and ideas.
+description: Turns a researched spec.md into a complete specification and leaves a blank plan.md for the planner.
 handles: [researched, retroactive]
-advances_to: planned
-model: fable
+advances_to: ready_for_planning
+model: sonnet
+effort: xhigh
+timeout: 900
+ledger: [spec.md]
 allowed_tools: [Read, Grep, Glob, Bash, Write, Edit, Task, Skill, WebSearch, WebFetch]
-writes: [spec.md, blocked.md]
+writes: [spec.md, plan.md, blocked.md]
 ---
 
-You are writing or rewriting the actual innovative part of the `spec.md` file for a single plan folder. You are basing this on two pillars that should already be there for you:
+You finish `spec.md` for one plan folder so that `palpatine-planner` can split it into work units without asking anything.
 
-- Introduction Section
-- Deep Research Section produced by `leah-researcher`
+## Input
 
-Before drafting, invoke the `superpowers:brainstorming` skill (via the Skill tool) to explore more than one way to frame the problem before committing to one. Use any other skill you find useful in describing a problem in such a way that the next agent, `palpatine-planner`, will be able to break it down into a `plan.md` with clear tasks, non-overlapping, such that they can be written by different sub-agents and then joined into a cohesive implementation plan, that `luke-backend` and `rey-frontend` can then read and without any additional context (unless one of them decides it needs it) be able to implement this idea, feature, story, whatever this is. They build in that order, back end first, so a unit that needs both should say which half it means.
+`spec.md` with a problem statement at the top and a `## Research` chapter from `leah-researcher`. Read the project's README, its other `.plans` folders, and the code the feature touches before writing.
 
-Read the surrounding project first — its README, its existing `.plans` entries, and the code the feature will touch. A specification written without reading the codebase describes a system that does not exist.
+## Do
 
-## What the final `spec.md` document should contain
+1. Frame the problem at least two ways. Pick one and say in one line why.
+1. Tighten the problem statement if the research changed it. Do not edit `## Research`.
+1. Write these sections, in this order:
+   1. **Goal.** One paragraph: what becomes possible that is not possible now.
+   1. **Non-Goals.** At least three. If you cannot name three, you have not found the boundary.
+   1. **In scope.** Statements a reviewer can check. "Handles errors" is not one.
+   1. **Out of scope.** Each with its reason.
+   1. **Back end / front end.** For each in-scope item, which half builds it. `luke-backend` and `rey-frontend` build them as a pair.
+   1. **Open questions.** Everything you had to assume, including leah's unsettled list.
+   1. **Risks to planning or execution.**
+   1. **Conclusion.** What will exist when this ships, in a few sentences.
+1. Anchor every fact to the research, a `file:line`, or a command's output. A sentence you cannot anchor is an assumption: move it to open questions.
 
-1. **Problem Statement**. This is the problem we are trying to solve and was originally written when the folder swas created. With your writing super skills it may be prudent to rewrite this section, with the precision, ideation and gravitas.
-1. **Research**. This should be already prefilled for you by @leah-researcher, and should not reqiure any editing or rewrite. If anything, it should contain food for thought and ideas to consider as goals or non-goals, as well ass a plethora of external references, available and behind a paywall, open source or commons license, or licensed in another way (we document all licensing details in the file docs/markdown/licensing-details.md relative to the root of the repository —> if it doesn't exist, then create it).
-
-What follows is your job to write:
-
-1. **The Goal** — one paragraph. What becomes possible that is not possible now.
-1. **Non-Goals** — the half people skip, and the half that prevents the scope argument in review. If you cannot name three, you have not understood the boundary.
-1. **In scope** — concrete, checkable statements. "Handles errors" is not one.
-1. **Out of scope** — with a reason for each, not just a list.
-1. **Open questions** — anything you had to assume.
-1. **Anything that may block planning or execution**.
-1. **Conclusion** -> a summary of the feature, that should demonstrate a clear evolution from the introduction that is at the top, to the conclusion at the bottom. A real value, solutions, and ideas must be presented clearly, in a coincise manner, ready for `palpatine-planner` to break them down into implementable tasks.
-
-## No Assumptions
-
-You will not assume anything ever. You will verify, confirm, double-check, and write facts, referencing the research or your own references and never assume anything that's not in the spec.md.
-
-## When to stop and block instead
+## Retroactive plans
 
-If answering an open question requires a decision that is not yours — a product tradeoff, a contradiction with an earlier plan, a cost commitment — **do not guess**. Write `blocked.md` instead, with each question as its own `## B1`, `## B2` heading, each carrying options and a recommendation, and say which kind of block it is:
+A folder numbered `NNN.MM` with `MM > 0` describes work that already shipped. Open with the dated provenance line from `~/.agents/skills/create-plan/references/retroactive-spec.md`, and describe what exists, not what was "decided".
 
-- an engineering or architecture decision → the folder becomes ⭕️
-- a product or priority decision → the folder becomes 🅱️
+## Done when
 
-A specification built on a guessed answer is worse than no specification, because it looks decided.
+- [ ] Every section above exists, and In scope holds no item without a check.
+- [ ] Every open question is either answered in the text or listed.
+- [ ] An empty `plan.md` exists next to `spec.md` (`touch plan.md`). Leave it blank. A heading in it tells the harness the plan is already written.
+- [ ] `spec.md` is signed `Completed`.
 
-## Retroactive plans
+## Block when
 
-If the folder's number has a non-zero decimal (`NNN.MM` where MM > 0), the work already shipped. Open the document with the dated provenance line — see `~/.agents/skills/create-plan/references/retroactive-spec.md`. Describe what exists. Do not write it as though it were decided in advance.
+An open question needs a decision that is not yours: a product tradeoff, a conflict with an earlier plan, a cost commitment. Write `blocked.md` with each question under its own `## B1`, `## B2` heading, with options and a recommendation. Sign `Blocked, round N (technical)` or `Blocked, round N (product)` and stop. A spec built on a guessed answer looks decided and is not.
 
-## Done when
+## Next
 
-You stop writing the spec when it's clear as day what we are building and what this spec specifically does not cover. A competent implementer could build this without asking you anything, and `palpatine-planner` can write a competent `plan.md` without asking any questions.
+| You sign                            | Folder becomes           | Who runs next                                                     |
+| :---------------------------------- | :----------------------- | :---------------------------------------------------------------- |
+| `Completed`, with blank `plan.md`   | 📋 Ready for Planning    | `palpatine-planner`                                               |
+| `Blocked (technical)` / `(product)` | ⭕️ / 🅱️                  | a human answers, then `agentilda unblock NNN` runs `lando-broker` |
+| nothing, or killed                  | 📋 if a blank `plan.md` exists (the harness signs for you), else unchanged | `palpatine-planner`, or nobody |

data/bin/setup

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+IFS=$'\n\t'
+# set -v
+
+command -v just>/dev/null  || brew install just
+command -v rbenv>/dev/null || brew install rbenv
+
+ruby_version="$(cat .ruby-version | tr -d '\n')"
+current_ruby_version="$(ruby -e 'puts RbConfig::CONFIG["RUBY_PROGRAM_VERSION"]')"
+
+if [[ ${ruby_version} != ${current_ruby_version} ]]; then
+  bash -c "$(curl -fsSL https://bit.ly/ruby-install-0-2-1)" -- ${ruby_version}
+else
+  echo -e "\e[0;33m[OK]\e[0m Ruby version ${ruby_version} is installed and current."
+fi
+
+rbenv versions | grep -q ${ruby_version} || {
+  echo -e "\e[1;31mCan't find ruby version ${ruby_version} after an attempted install.\e[0m"
+  exit 1
+}
+
+bundle check>/dev/null && {
+  echo -e "\e[0;33m[OK]\e[0m Gemfile dependencies are already satisfied."
+} || bundle install -j 12

data/exe/agentilda

@@ -3,109 +3,30 @@
 
 # agentilda — spec → plan → build.
 #
-#   agentilda create tax rule dsl      # the next numbered plan folder
-#   agentilda create --after 002 …     # a plan written after the fact
-#   agentilda list-plans               # every plan, its state, its PRs
-#   agentilda resync dirs              # folder emoji vs folder contents
-#   agentilda resync prs               # [NNN.MM] prefixes on PR titles
-#   agentilda docs -o context/workflow.md
-#
-# Deliverables go to STDOUT; progress goes to STDERR. Anything that writes to
-# disk or to GitHub is a dry run until you pass --commit.
+# Anything that writes to the disk or to GitHub is a dry run until you pass --commit.
 #
 # © 2026 Konstantin Gredeskoul
 
-# Resolve the bundle from this repository rather than from wherever the caller
-# happens to be standing: this is installed on PATH and run from other projects'
-# roots, where the local Gemfile knows nothing about dry-cli or finite_machine.
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
-
+# Resolve the dependencies from this repository without the bundler, thank you very much.
 module Agentilda
   PROJECT_ROOT = File.expand_path("..", __dir__)
 end
 
-begin
-  require "bundler/setup"
-rescue LoadError, StandardError => e
-  # standard:disable Style/StderrPuts -- Kernel#warn is a no-op under
-  # RUBYOPT=-W0, which agent harnesses and CI both set. This is the only
-  # thing a caller gets before exit 69, so it has to reach them regardless.
-  $stderr.puts "agentilda: could not load the bundle from #{ENV.fetch("BUNDLE_GEMFILE", nil)}"
-  $stderr.puts "  #{e.class}: #{e.message.lines.first.to_s.strip}"
-  $stderr.puts "  Run `bundle install` in #{File.dirname(ENV.fetch("BUNDLE_GEMFILE", nil))}"
-  # standard:enable Style/StderrPuts
-  exit 69
-end
-
-require_relative "../lib/agentilda"
-
-# Names dry-cli can resolve, so a leading word that is not one of these is a
-# typo and must fail rather than quietly run something else.
-KNOWN = %w[create new c list-plans status st resync docs version --version -v -h --help].freeze
-
-# Bare `agentilda` prints its help. It used to print the plan table, which
-# meant the one command that reads a tree was also the one you got by accident.
-argv = ARGV.dup
-argv = ["-h"] if argv.empty?
-
-# `run --push-pr` takes an OPTIONAL part letter: bare means "continue this
-# plan's sequence", `--push-pr C` means "use C". dry-cli has no optional-value
-# option, so the bare form is filled in here rather than made to look like a
-# mistake.
-#
-# Scoped to `run`, and to the long spelling when it is not. This rewrote every
-# `-p` in every command for a while, which quietly turned
-# `linear import TAX -p "Some Project"` into `-p auto "Some Project"` — the
-# option took "auto" and the project name became a stray argument. A global
-# rewrite of a one-letter flag will collide with the next command that wants
-# it; this one collided within the week.
-if argv.first == "run"
-  argv = argv.each_with_object([]) do |token, out|
-    out << token
-    next unless ["--push-pr", "-p"].include?(token)
-
-    following = argv[argv.index(token) + 1]
-    out << "auto" unless following&.match?(/\A[A-Z]\z/)
-  end
+if Agentilda::PROJECT_ROOT.include?("lib/ruby/gems")
+  require "rubygems"
+  gem "agentilda"
 end
 
-module ProgramBanner
-  extend Dry::CLI::Banner::ColorMethods
-
-  def self.banner
-    puts %(
-      #{yellow.bold("agentilda")}
-        #{blue("Agentic Specification-Driven Development")} #{green("v#{Agentilda::VERSION}")}
-
-        This is the key executable that facilitates Agentic Flow:
-
-        #{green.bold("spec → plan → build → review → tune/fix → approve")}
-
-        For now the final merge and deploy is manual. It also provides sync
-        of the .plans folders with Github PRs and Linear Issues. See the file
-        #{::Agentilda::PROJECT_ROOT}/context/workflow.md for the details.
+# lib/ goes first on the load path: several files `require "agentilda/..."`,
+# and without this those resolve to whichever agentilda gem is installed,
+# not to this checkout, and one class ends up defined twice.
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 
-      #{yellow.bold("GLOBAL FLAGS")}
-        -h, --help        Show this help message and exit
-        -C, --no-color    Disable color output
-
-    ).gsub(/^ {6}/, "").strip
-    puts
-  end
-end
-
-no_color = %w[--no-color -C].intersect?(argv)
-Dry::CLI::Banner.disable_color! if no_color
-# # dry-cli prints the command list for an unresolved command and exits 1, and
-# it treats a bare `--help` as exactly that. Asking for help is not a failure,
-# so the status is forced back to 0 for the help forms only.
-help = %w[-h --help help].intersect?(argv) && argv.first[0] == "-"
-ProgramBanner.banner if help
+require_relative "../lib/agentilda"
+require_relative "../lib/agentilda/launcher"
 
 begin
-  Dry::CLI.new(Agentilda::CLI).call(arguments: help ? [] : argv) || 0
+  Agentilda::Launcher.new(ARGV.dup).execute!
 rescue SystemExit => e
-  exit(help ? 0 : e.status)
+  exit(e.status)
 end
-
-exit 0

data/lib/agentilda/adoption.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+require "fileutils"
+require "parallel"
+
+require "agentilda/status"
+
 module Agentilda
   # Gives a plan folder to every pull request that has no plan to point at.
   #
@@ -185,8 +190,8 @@ module Agentilda
       pull = adoptee.pull
       github.pull_request(pull[:number].to_s)
     rescue Agentilda::Error
-      {number: pull[:number], title: pull[:title], url: pull[:url],
-       state: pull[:state] || "Unknown", body: ""}
+      { number: pull[:number], title: pull[:title], url: pull[:url],
+       state: pull[:state] || "Unknown", body: "" }
     end
   end
 end

data/lib/agentilda/agent.rb

@@ -25,112 +25,53 @@ module Agentilda
   # @!attribute [r] timeout
   #   @return [Integer, nil] seconds before this agent is abandoned; nil
   #     defers to the executor's run-wide default
-  Agent = Data.define(:name, :description, :handles, :advances_to, :model,
-    :allowed_tools, :may, :network, :timeout, :prompt, :path) do
+  # @!attribute [r] ledger
+  #   @return [Array<String>] the documents this agent signs, in the order
+  #     it reaches them; the last entry it wrote is where it stands
+  # @!attribute [r] rounds
+  #   @return [Integer] how many times it may be invoked on one plan in one
+  #     state before the plan parks; a Completed never earns another
+  # @!attribute [r] effort
+  #   @return [String, nil] passed to `claude --effort`
+  # @!attribute [r] starts_as
+  #   @return [Symbol, nil] the state the harness renames the plan into the
+  #     moment this agent is dispatched, where the topology permits it
+  # @!attribute [r] holds_at
+  #   @return [Symbol, nil] the state the plan takes when this agent completes
+  #     while its partner on the same plan is still running
+  Agent = Data.define(:name,
+    :description,
+    :handles,
+    :advances_to,
+    :model,
+    :allowed_tools,
+    :may,
+    :network,
+    :timeout,
+    :prompt,
+    :path,
+    :ledger,
+    :rounds,
+    :effort,
+    :starts_as,
+    :holds_at) do
+    def initialize(ledger: [], rounds: 1, effort: nil, starts_as: nil, holds_at: nil, **rest) = super
+
     # @return [Boolean] whether this agent changes anything on disk
     def read_only? = advances_to.nil?
 
     # @param status [Agentilda::Status]
     # @return [Boolean]
     def handles?(status) = handles.include?(status.key)
-  end
-
-  # Loads and indexes the agent definitions.
-  class Agents
-    # Where definitions live, unless told otherwise.
-    DEFAULT_DIR = File.expand_path("../../agents", __dir__)
-
-    # @param dir [String]
-    # @param roster [Array<Agentilda::Agent>, nil] a pre-selected list, used
-    #   by {#only} and {#without} to derive a narrower roster; nil (the
-    #   default) loads every definition in `dir`
-    def initialize(dir: DEFAULT_DIR, roster: nil)
-      @dir = File.expand_path(dir)
-      @all = roster
-    end
-
-    # @return [String]
-    attr_reader :dir
-
-    # @return [Array<Agentilda::Agent>] in name order
-    def all
-      @all ||= Dir.glob(File.join(dir, "*.md")).sort.filter_map { |path| parse(path) }
-    end
-
-    # @param name [String]
-    # @return [Agentilda::Agent, nil]
-    def find(name) = all.find { |a| a.name == name.to_s }
-
-    # A roster holding only the agents named — what `run --agent` hands the
-    # loop, so a restriction typed at the command line restricts assignments
-    # and not merely chaining.
-    #
-    # @param names [Array<String>]
-    # @return [Agentilda::Agents]
-    def only(*names)
-      wanted = names.flatten.map(&:to_s)
-      self.class.new(dir:, roster: all.select { |a| wanted.include?(a.name) })
-    end
-
-    # A roster without the agents named — what `run --skip` hands the loop.
-    # A plan sitting in a skipped agent's state is simply never assigned, the
-    # same way a state no agent handles is stepped around.
-    #
-    # @param names [Array<String>]
-    # @return [Agentilda::Agents]
-    def without(*names)
-      unwanted = names.flatten.map(&:to_s)
-      self.class.new(dir:, roster: all.reject { |a| unwanted.include?(a.name) })
-    end
-
-    # Every agent the query could mean. An exact name wins outright; failing
-    # that the query matches as a prefix, and failing that anywhere in the
-    # name, so `leah` finds leah-researcher and `review` finds
-    # hansolo-reviewer. A directory or a trailing `.md` is stripped first,
-    # because tab completion hands those in.
-    #
-    # @param query [String]
-    # @return [Array<Agentilda::Agent>]
-    def match(query)
-      wanted = File.basename(query.to_s, ".md")
-      exact = all.select { |a| a.name == wanted }
-      return exact unless exact.empty?
 
-      prefixed = all.select { |a| a.name.start_with?(wanted) }
-      return prefixed unless prefixed.empty?
-
-      all.select { |a| a.name.include?(wanted) }
-    end
-
-    # Every agent that will act on a plan in this state, in definition order.
-    # A read-only agent is never offered work by the loop — it has nothing to
-    # advance, so including it would make every round look productive.
+    # The word after the hyphen: `researcher`, `backend`. What the screen's
+    # agent column shows, the name being too long for it.
     #
-    # @param status [Agentilda::Status]
-    # @return [Array<Agentilda::Agent>]
-    def for_status(status) = all.select { |a| a.handles?(status) && !a.read_only? }
-
-    private
-
-    # @param path [String]
-    # @return [Agentilda::Agent, nil]
-    def parse(path)
-      meta, body = Frontmatter.split(File.read(path, encoding: "UTF-8"))
-      return nil if meta["name"].to_s.empty?
-
-      Agent.new(
-        name: meta["name"].to_s,
-        description: meta["description"].to_s,
-        handles: Array(meta["handles"]).map { |s| s.to_s.to_sym },
-        advances_to: meta["advances_to"]&.to_s&.then { |s| s.empty? ? nil : s.to_sym },
-        model: meta["model"],
-        allowed_tools: Array(meta["allowed_tools"]).map(&:to_s),
-        may: Array(meta["may"]).map { |c| c.to_s.strip.squeeze(" ") },
-        network: meta["network"] == true,
-        timeout: meta["timeout"].to_i.then { |s| s.positive? ? s : nil },
-        prompt: body.strip,
-        path: path
-      )
-    end
+    # @return [String]
+    def role = name.split("-", 2).last.to_s
   end
+
+  # More rounds than this costs tokens and buys nothing: an agent that has
+  # not finished in five tries is not going to on the sixth.
+  Agent::MAX_ROUNDS = 5
 end