You are going to read the public documentation of a real, running AI agent fleet and report what it actually is. Two public surfaces, no auth on either:

- https://docs.utopiamodels.ai — the wiki, the written argument for how the fleet is built
- https://utopiamodels.ai — the OCC, its live cockpit, and the counterpart that either confirms the prose or contradicts it

Do not edit, create, or delete any file on my machine. This is a read-and-report task from start to finish.

## Step 1 — establish you can reach it, and derive the reading list

Run this first:

    curl -s https://docs.utopiamodels.ai/llms.txt | head -3

You should get a line reading `# The fleet` followed by a bulleted entry for `/docs`. If you get empty output or a non-zero exit, curl is not reaching the host from this machine. Try `python3 -c "import urllib.request; r=urllib.request.urlopen('https://docs.utopiamodels.ai/llms.txt',timeout=20); print(r.status, len(r.read()))"`, which should print `200 1506`, or fall back to wget, or use whatever web-fetch tool you have. Tell me which one worked before continuing, because everything below depends on it.

Now derive the page list rather than trusting one I typed:

    curl -s https://docs.utopiamodels.ai/llms.txt | grep -oE '\(/[a-z/-]+\)' | tr -d '()' | sed 's|^|https://docs.utopiamodels.ai|;s|$|.md|'

That emits seven URLs: the six documentation sections plus the live page. Deriving them from the index means this instruction survives the site adding a page, so use the output rather than a list from memory.

Every path on this wiki has a raw markdown twin at the same path with `.md` appended. Fetch those, not the rendered HTML. A `.md` path under `/docs/` that does not exist returns a zero-byte 404, so a wrong guess there costs you nothing and puts no error page into your context.

## Step 2 — read the seven pages in parallel

Dispatch subagents, one per URL, running concurrently. Sequential fetching wastes the main advantage you have here.

Give each subagent the same reporting contract, because the synthesis depends on comparing like with like:

1. The claims the page makes, as claims, not as a summary of its prose.
2. Which of those claims are backed by something checkable — a command written out, a status code, a file path, a dated measurement — and which are asserted with nothing behind them. Quote the evidence where it exists.
3. Any statement that contradicts another page, or that contradicts itself.
4. Numbers, verbatim, with their units and their dates.

Use the seven URLs as the pipeline emitted them rather than reconstructing paths by hand, since five of the six sections live under `/docs/` and only the overview sits at the top level. By subject they are: the overview, architecture, operations, surfaces, work, and decisions. Match each subject to its URL from the output above.

The seventh is the live page. Tell its subagent that it is generated at request time and stores nothing, so it is the only page whose numbers describe now rather than a moment when someone wrote them down. Its own header states `store: none — no snapshot file, no cache, no revalidate window.` Two fetches a second apart show its `generated:` stamp advancing, which you can check directly.

If you would rather spend one fetch than seven, `curl -s https://docs.utopiamodels.ai/llms-full.txt` returns all six static pages concatenated in about 81 KB. It excludes the live page, so fetch that separately either way.

## Step 3 — check the prose against the live surfaces

The wiki argues that this fleet publishes measurements rather than descriptions. Test that claim rather than accepting it.

Agent run-state, the highest-signal line available to you:

    curl -s https://docs.utopiamodels.ai/live.md | grep -E '^\| (agent|agent-sf|win|nova|cloud|dust) \('

You get one table row per agent, splitting what the registry says exists from whether that agent can currently take a turn. Read the two columns as separate facts, because the page's argument is that they are. If the grep returns nothing the table shape has changed, so fetch the live page whole and find the section headed `Can each agent actually run?`.

Board state, from the OCC rather than the wiki:

    curl -s https://utopiamodels.ai/v1/board | python3 -c "
    import json,sys
    d=json.load(sys.stdin)
    if not d.get('ok'):
        print('board unavailable:', d.get('error') or 'unknown'); sys.exit(0)
    print('generated:', d.get('generatedAt'))
    print('counts:', d.get('counts'), 'lanes:', d.get('byLane'), 'items:', len(d.get('items') or []))
    "

This is the only public JSON endpoint on the OCC and needs no jq, since you may not have it. If `python3` is missing, `curl -s https://utopiamodels.ai/v1/board | head -c 400` shows you the same fields by eye.

Read the `ok` field before anything else, because it separates three outcomes that look similar and mean different things.

A JSON decode error means the endpoint returned HTML rather than JSON. Treat that as unreachable, not as an empty board.

A response where `ok` is false and `error` carries a message is the endpoint telling you its upstream read failed. A value like `github graphql 403` means the OCC could not read the board from GitHub at all, so the item list is empty for that reason and no other. Re-run it a few seconds later. This endpoint does flip between healthy and refused, so a second attempt is worth making — but if the same error persists, report it as what you measured, with the error string quoted and the number of attempts you made. Do not record it as an empty board, and do not describe the fleet's work queue from the wiki's account of it when this endpoint could not confirm a single item.

A response where `ok` is true, `generatedAt` is present and the item list is populated is the healthy shape. Only then are the counts worth quoting.

The parser uses `.get()` throughout for exactly this reason: indexing directly into the counts crashes on the unhealthy shapes, and a traceback tells you less than the error string does.

Then look for the correlation. When the board endpoint degrades, the live page prints a line beginning `ERROR:` in its own board section, stating that the upstream returned no timestamp so its age cannot be stated honestly. An `ERROR:` line on that page is data the page chose to publish about itself, not a failed fetch on your end. Whether a documentation site reports its own broken upstream in place of quietly showing a stale number is a design decision you should judge, and you can observe it directly.

One caution on the OCC. `https://utopiamodels.ai` is a client-rendered application, so fetching the root with curl gives you the shell and a few loading strings rather than the live sections. Use `/v1/board` for data. If you have a browser tool the rendered page is worth a look; if you do not, say you could not see it.

## Step 3b — find the ceiling on what you can prove

Fetch the section of the live page headed `What this page cannot reach — and the command that can`:

    curl -s https://docs.utopiamodels.ai/live.md | sed -n '/What this page cannot reach/,/How this page is produced/p'

It lists facts a public page cannot establish, each paired with the command that would settle it and the box that command runs on. Those commands reach private infrastructure, so you cannot run them, and that is the point of reading the section: it draws the line between what you have verified and what you are taking on trust.

The sharpest example is stated there directly. Whether an agent account exists and whether that agent can complete a turn are different questions, and the page refuses to source the second from the first. Carry that distinction into your synthesis. Where you can only confirm that something exists, say so, rather than reporting it as working.

## Step 4 — synthesize, in your own voice

Not a page-by-page summary. I can read the pages. Give me:

- The architecture in one paragraph, at the level of what runs where and what carries state between runs.
- How one unit of work travels from an idea to a merged pull request, naming every mechanism it passes through. Where the pages leave a gap in that chain, name the gap rather than bridging it with a plausible guess.
- What this fleet deliberately does not have. For each absence, what it buys and what it costs. The decisions page argues these were chosen rather than missing; say whether you find the argument carried by evidence.
- Where claims are measured versus asserted. Give me the two or three you would want evidence for before believing them, and say what evidence would settle each.
- Any disagreement you found between pages, or between a page and what you measured in step 3. Report it plainly. A wiki that publishes its own drift is making a claim, and disagreements you find are the test of it. If the board endpoint returned an error rather than data, say so in its own line, quote the error, and state which parts of your synthesis you could not check against it.
- The one thing you did not expect.

Where a number you measured differs from a number a page states, give both and note the gap.

You are going to study a real, running AI agent fleet, then compare it against my setup and tell me what is worth taking. Read this whole prompt before you start.

## What you will do, in order

1. Read the public wiki of another fleet. No writes.
2. Fan subagents across my repo and my agent configuration to measure what I actually have. Read-only.
3. Write one ranked integration plan to the terminal.

You will not create, edit, move, or delete any file of mine at any point in this session, including config, dotfiles, and anything under `.claude/`. If you conclude a change is worth making, describe it and stop. I will make it myself or tell you to. The reason is that a plan I can read and reject costs me two minutes; a change you made while I was reading costs me a bisect.

Work through step 1 and step 2 in parallel — they touch nothing in common.

## Step 1 — read the other fleet

Start here, because it tells you what exists rather than making you guess:

~~~
curl -s https://docs.utopiamodels.ai/llms.txt | head -3
~~~

That is a public wiki, no auth, CORS open, no user-agent needed. If curl is missing or the output is empty, fall back to `python3 -c "import urllib.request;print(urllib.request.urlopen('https://docs.utopiamodels.ai/llms.txt',timeout=20).read().decode())"`, or wget, or your own fetch tool. If all of those fail the machine has no outbound network and you should say so and go straight to step 2 — the comparison is weaker but the audit of my setup still stands on its own.

Derive the page list from the index rather than hardcoding it, so this prompt does not rot as the wiki grows:

~~~
curl -s https://docs.utopiamodels.ai/llms.txt | grep -oE '\(/[a-z/-]+\)' | tr -d '()' \
  | sed 's|^|https://docs.utopiamodels.ai|;s|$|.md|'
~~~

That emits seven URLs. Every rendered page has a raw markdown twin at the same path with `.md` appended; fetch those, not the HTML. A wrong `.md` path under `/docs/` returns a zero-byte 404, so a mistake costs you nothing and puts no HTML error page into your context.

Dispatch one subagent per URL, running concurrently. Give each the same brief: return the claims its page makes, which of those claims are backed by a command or a dated measurement rather than asserted, and any claim that contradicts another page.

Include the live page in that fan-out. It is generated at request time and stores nothing, so it is the only page whose numbers are current. It reports failure per section — a line beginning `ERROR:` inside it is that page honestly reporting an upstream it could not reach, not a broken fetch on your end. Treat it as data.

Two commands worth running yourself rather than delegating, because they are the fastest evidence that any of this is real:

~~~
curl -s https://docs.utopiamodels.ai/live.md | grep -E '^\| (agent|agent-sf|win|nova|cloud|dust) \('
curl -s https://utopiamodels.ai/v1/board | python3 -c "
import json,sys
d=json.load(sys.stdin)
if not d.get('ok'):
    print('board unavailable:', d.get('error') or 'unknown'); sys.exit(0)
print(d.get('generatedAt'), d.get('counts'), d.get('byLane'))
"
~~~

The first returns one row per agent, splitting registry existence from whether that agent can currently take a turn. At the time this prompt was written one of them read `CANNOT RUN` with `resetsAt=null`, meaning nothing recovers it on a timer. The second is the live board, no auth and no jq required. It branches on `ok` because this endpoint degrades rather than failing: when its upstream read is refused it still returns valid JSON with `ok` false and an error string, and a fleet with no work and a fleet that cannot see its work are different claims. If the parser raises a JSON decode error instead, the endpoint returned HTML, which means an outage — treat it as unreachable.

`https://utopiamodels.ai` is the command center itself, but it is a client-rendered app, so curl returns a loading skeleton. Use the two endpoints above for state and ignore the root URL unless you have a browser tool.

What you are looking for in step 1 is not features. It is the shape of the decisions: what that fleet deliberately does not have, and what each absence buys and costs. Their wiki argues that most agent infrastructure is supervision machinery whose only job is keeping a resident process honest, and that deleting the resident process deletes the machinery. Judge that argument on their evidence.

## Step 2 — measure my setup

Dispatch subagents in parallel, one per area below. Each one reports what it measured, with the command or the file path that produced the number. A subagent that reports an impression instead of a measurement should be sent back. Each subagent is read-only and writes no files, the same constraint that binds you.

Commands below suppress their own error output, so a thing that does not exist on my machine yields nothing on stdout and a non-zero exit status. Read the empty output as a finding; do not read the exit code as a tool failure and retry.

**Instruction surface.** How much prose is loaded into every session before I type anything.

~~~
find . -maxdepth 4 -name 'CLAUDE.md' -not -path '*/node_modules/*' -exec wc -c {} +
ls -la ~/.claude/ 2>/dev/null
find ~/.claude/rules ~/.claude/skills ~/.claude/agents -maxdepth 2 2>/dev/null | head -50
~~~

Report total auto-loaded bytes. This is charged on every turn of every session.

**Automation that runs without me.**

~~~
python3 - <<'PY'
import json,os
p=os.path.expanduser('~/.claude/settings.json')
if not os.path.exists(p):
    print('ABSENT: no ~/.claude/settings.json'); raise SystemExit
try:
    h=json.load(open(p)).get('hooks',{})
    print(json.dumps(h,indent=1)[:3000] if h else 'PRESENT, NO HOOKS CONFIGURED')
except Exception as e:
    print('MALFORMED:',e)
PY
ls .claude/settings.json .claude/settings.local.json .mcp.json 2>/dev/null
ls .github/workflows/ 2>/dev/null
~~~

For each hook and each workflow, report what triggers it, and whether it blocks or merely warns. A blocking check that fires on a convention rather than on an invariant is a finding. The settings reader prints which case it hit, because an absent config and a corrupt one are different findings and they otherwise produce the same silence.

**What is actually maintained.** Documentation rots silently; churn tells you which files are alive.

~~~
git log --since='90 days ago' --name-only --pretty=format: -- '*.md' | grep -v '^$' | sort | uniq -c | sort -rn | head -20
git ls-files '*.md' | wc -l
~~~

A markdown file with zero commits in ninety days that is nonetheless auto-loaded into every session is dead weight being paid for continuously.

**How work is tracked.** Count the places a task can live: issue tracker, a TODO file, a plan file, a project board, comments. Run `git ls-files | grep -iE 'todo|backlog|roadmap|tasks?\.md'` for file-based trackers. For a hosted one, run `gh issue list --limit 5` if `command -v gh` finds it and it is authenticated; if it is missing, run `git remote -v` and report that the tracker could not be inspected from this machine rather than concluding there is none. Two trackers cannot both be true, and the failure is silent — one of them just stops being read.

**How agent work reaches the repo today.** Whether anything runs without me starting it, and whether it supervises itself.

~~~
crontab -l 2>/dev/null; ls ~/.config/systemd/user/*.service 2>/dev/null
ps -eo comm= | grep -iE 'claude|agent|watch|daemon' | sort -u
~~~

A resident process is the expensive kind of infrastructure, because most of what surrounds it exists only to keep it honest.

**Where state lives.** Any tracked file that caches a fact another system owns.

~~~
git ls-files | grep -iE '(generated|snapshot|manifest|cache|index|state|status)\.(json|ya?ml|md)$'
~~~

Each hit is a place that can silently disagree with reality, and the disagreement is never announced.

## Step 3 — the plan

Write it to the terminal. No files.

Rank every recommendation by leverage, highest first. For each one, five lines:

- **The change** — stated concretely enough that I could do it without asking you a follow-up question.
- **The evidence** — the measurement from step 2 that makes this worth doing on my setup specifically, not in general.
- **What it deletes** — the file, the hook, the workflow, the tracker, the process that stops existing. If a recommendation adds without deleting, say so plainly, because that is the expensive kind.
- **The cost** — what this makes harder, slower, or riskier. Every one of these has a cost and a recommendation without one is unfinished.
- **How I would know it worked** — a command I can run, with the output that means success.

Order them so an early item unblocks later ones, and say which item is a prerequisite for which.

Weight deletions above additions. A fleet that runs on a GitHub board, systemd, and git is not impressive because of what it built; it is fast because of what it refused to build, and every mechanism it did not add is one it never has to keep honest. Apply the same standard to my setup. If the honest answer for a section is that my current approach is better than theirs, say that and move on — I am not looking for a migration, I am looking for the delta that is worth paying for.

Two things to call out explicitly, because they are where this kind of comparison usually goes wrong:

Name any pattern of theirs that only works because of something they have and I do not — a dedicated server, several agent accounts, a monorepo, a particular org plan tier. Their dispatch model puts a run on a separate box under a separate account; if I have one machine and one account, the mechanism does not transfer even though the principle behind it might. Say which half transfers.

Separate what their documentation claims from what their live endpoints show. Where those two disagree, the disagreement is the more useful lesson, and their own wiki publishes several of them rather than hiding them.

Close with the single highest-leverage change I could make this week, in one sentence, and the command that would tell me it worked.

## If you run out of room

This is a large task: seven pages of theirs, six areas of mine, then a synthesis. If you are running low on context before step 3, stop fanning out and write the plan from what you have — say at the top which areas you did not get to and what command would cover them next time. A ranked plan over partial evidence, with the gaps named, is worth more to me than a complete audit you had no room to conclude.

Scaffold me a knowledge base — one that an AI agent working in my repo actually reads, on the patterns of a real running fleet documented at https://docs.utopiamodels.ai. You will write files into my repo. Read this whole prompt before your first write.

## What you are going to do, before you do it

1. Learn the pattern from the reference wiki (read-only, external).
2. Read my repo and derive what my knowledge base should contain, from my code and my history.
3. Show me a one-screen file manifest and wait for my go-ahead — asked with the `AskUserQuestion` tool, not in prose.
4. Write the files, populated from my context.
5. Run the checks below and paste the real output.

Nothing in step 4 happens before I answer step 3.

## Step 1 — learn the pattern

Run this to get the reference index and derive every page it lists as raw markdown:

    curl -s https://docs.utopiamodels.ai/llms.txt | grep -oE '\(/[a-z/-]+\)' | tr -d '()' \
      | sed 's|^|https://docs.utopiamodels.ai|;s|$|.md|'

That emits seven URLs. Dispatch subagents to fetch them in parallel — one page each. Fetch the `.md` twins, not the rendered HTML. If `curl` is missing, substitute:

    python3 -c "import urllib.request;print(urllib.request.urlopen('https://docs.utopiamodels.ai/llms.txt',timeout=20).read().decode())"

If the whole host is unreachable from my machine, say so in one line and continue from the patterns described in this prompt — they are stated below in enough detail to build from without the wiki.

Two pages matter most for this job: the work page (how work and its briefs are structured) and the decisions page (how decisions are recorded, superseded and killed). A missing `.md` path under `/docs/` returns a zero-byte 404, so a wrong guess costs you nothing and pollutes nothing.

## The four patterns you are implementing

**Portfolio-first.** Knowledge is organised by the thing it is about, not by document type. A folder per portfolio — per product, per service, per business line — each holding its own `CLAUDE.md`, its specs, and its decisions. A top-level `docs/architecture/` next to a top-level `docs/runbooks/` splits every subject in half and guarantees that reading one gives you a partial answer. Subject folders keep a subject whole.

**Doctrine that auto-loads.** A small set of behavioral files that the agent harness reads at the start of every session, with no one remembering to point at them. In Claude Code that is `CLAUDE.md` at the repo root plus one per portfolio directory. The discipline is size, because this text is prepended to every session forever: a rule earns a place only if it changes what the agent does on most turns. Everything rarer goes in a reference file read on demand. The reference fleet caps the always-loaded set a worker agent sees at 30,000 bytes, and the script that generates that set refuses to emit one which breaches the cap — a ceiling something enforces, rather than an intention.

**Decision records with a lifecycle.** A record states what was chosen, what it replaced, why, and what it cost. Once accepted it is immutable — you do not edit an accepted record to reflect a change of mind. You write a new record that supersedes it, and you edit the old record's `Superseded-by` header in the same commit that adds the new one. A record that was silently invalidated is worse than no record, because it reads as current and is not. And a decision is not reopened by disagreement; it is reopened by new information, named in the superseding record.

The test for when to skip a record is the part that is learned expensively. The reference corpus reached 93 records with 86 of them written in a single month, which is a corpus nobody reads and therefore a corpus that stops being consulted before a decision — the exact failure it exists to prevent. Write a record only when one of these is true: the choice is expensive to reverse, or a future reader will otherwise re-litigate it. If neither holds, the reasoning belongs in the pull request body or the work item, and no record is written. Put that test at the top of the decision template so it is read before each one is written, not after the corpus is already unreadable.

**One tracker.** Whatever holds work state — an issue tracker, a board, a `plan.md` of checkboxes — there is exactly one, and the knowledge base points at it rather than mirroring it. Point at the tracker; store the durable why here.

## Step 2 — read my repo, and populate from my context

Dispatch subagents to run these in parallel and report what they measured, with the command behind each finding. Five of these read git history. If this is not a git repository, say so in one line, skip them, and derive portfolios and decisions from the file tree and any existing design docs instead — you will have fewer records, which is the correct outcome rather than a reason to invent them.

    ls -la && cat README* 2>/dev/null | head -40
    git log --oneline -30
    git log --format='%s' -400 | cut -c1-40 | sort | uniq -c | sort -rn | head -20
    find . -not -path '*/node_modules/*' -not -path '*/.git/*' \
      \( -name 'CLAUDE.md' -o -name '.cursorrules' -o -name 'AGENTS.md' -o -name '*.mdc' \) | head -30
    find . -maxdepth 3 -type d \( -name 'docs' -o -name 'doc' \) -not -path '*/node_modules/*'
    git log --format='%H %s' -300 | grep -iE 'revert|instead of|replaced|migrat|switch' | head -30

The last one is the highest-value command in this list. Reverts and "replaced X with Y" messages are where decisions already happened without being recorded, and they are the only source of decision records that will be true rather than invented. Cite the commit hash this command printed. If you did not read a hash for a decision, that decision is not evidenced and does not become a record. Also read whatever design docs, ADRs, RFCs or pinned issues already exist — a knowledge base that ignores them creates a second tracker on day one.

Derive my portfolios from what the repo actually contains: top-level packages, deployable services, distinct product surfaces. If the repo is a single service, there is one portfolio and the structure is flatter — say that rather than inventing three folders to fill a template.

Do not write generic content. Every file you produce names my paths, my commands, my services. A file that would read identically in someone else's repo is a file that buys nothing and costs tokens on every session that loads it, so cut it.

## Step 3 — show me the manifest, then stop

Print a table: each file path, one line on what it holds, and whether it is auto-loaded doctrine or read-on-demand reference. Under it, name in one line each: my portfolios as you derived them, my one tracker, and the two or three decisions you found in my git history that are worth recording. Then ask me to confirm or correct with the `AskUserQuestion` tool, and wait. Options, not an open question: "write it as listed" first and marked RECOMMENDED, then the ways I am likely to want it changed. A question asked in prose carries no options and therefore no recommendation, and the recommendation is what lets me accept the default and still end up with something durable. Flag anything you would overwrite; prefer a suffixed new file over clobbering something I wrote.

## Step 4 — write it

The shape, adjusted to what you actually found:

- `CLAUDE.md` at the root — what this repo is, how to run and test it, the tracker, and a pointer to the portfolio files. Kept under about 4 KB, because it loads every session.
- `<portfolio>/CLAUDE.md` per portfolio — what it owns, how to run it, its boundaries, its gotchas.
- `docs/decisions/TEMPLATE.md` — the skip test first, then Status / Date / Context / Decision / Consequences / Superseded-by. Superseded-by present and empty on a new record, so the field exists to fill.
- `docs/decisions/NNN-*.md` — the records you derived from my history, written as the decisions they were, with the commit hash as evidence. Two or three real ones beat ten invented ones.
- `docs/reference/` — the read-on-demand tail. Things true but rarely needed.

Write dates as concrete ISO dates, not "today". Write paths and commands literally — "the deploy script" is not a path and helps nobody.

## Step 5 — check it, and paste the real output

    find . -maxdepth 2 -name 'CLAUDE.md' -not -path '*/node_modules/*' -exec wc -c {} +
    ls -R docs/decisions docs/reference 2>/dev/null
    grep -rn 'Superseded-by' docs/decisions/ | head
    git status --short

The first is the one that matters: it is the token bill on every future session. One line means one portfolio, which is a valid result — the number to read is the byte count, not the row count. If the root `CLAUDE.md` is over roughly 6 KB, cut it rather than defending it, and move what you cut into `docs/reference/`. Then grade yourself out loud on one question per file: does this change what an agent working here does? Name the files where the answer was no and delete them.

Do not commit. Leave everything staged as working-tree changes so I can read the diff.

## If you run out of room

This finishes in one paste on a normal repo. If my repo is large enough that step 2 does not fit, stop after step 3, write the manifest to `docs/KB-PLAN.md`, and tell me to start a fresh session pointing at that file. A half-written knowledge base is worse than a manifest, because the half that exists reads as complete.

For live context on the reference fleet as you work — what it is running right now, including the parts that are broken — fetch https://docs.utopiamodels.ai/live.md. It is generated per request and stores nothing, so an `ERROR:` line inside it is a real upstream failure being reported honestly, not a failed fetch on your end. The fleet's cockpit is at https://utopiamodels.ai, and its board state is one fetch away:

    curl -s https://utopiamodels.ai/v1/board | python3 -c "
    import json,sys
    d=json.load(sys.stdin)
    print(d.get('generatedAt'), d.get('counts')) if d.get('ok') else print('board unavailable:', d.get('error'))
    "

You are going to build me a working agent fleet, modelled on a real one that is running and publicly documented. A fleet here means: several agents that execute work unattended on a machine that is always on, a single queue they draw from, and a record of what happened that survives every process exiting.

Part of the job cannot be finished in this session, and knowing which part changes the order you do the rest in.

## What you can finish today, and what you cannot

Everything that lives in a repository — the scripts, the runner, the queue client, the agent definitions, the install steps, the docs — you can write and test in this session.

What you cannot do is anything that needs me: creating accounts, paying for subscriptions, putting an SSH key on a machine I own, deciding which machine stays on. You will hand me a checklist for those at the end. Do not try to work around them, do not stub them with fake credentials, and do not report the fleet as running when the parts that make it run are still on my checklist.

## Step 1 — Study the reference fleet

The fleet is documented at https://docs.utopiamodels.ai and its live cockpit is at https://utopiamodels.ai. Start with the index:

    curl -s https://docs.utopiamodels.ai/llms.txt | head -3

You should see `# The fleet` and a bulleted list. If that command prints nothing or exits non-zero, the site is unreachable from this machine; try `python3 -c "import urllib.request;print(urllib.request.urlopen('https://docs.utopiamodels.ai/llms.txt',timeout=20).read().decode())"` or `wget -qO- https://docs.utopiamodels.ai/llms.txt` before concluding it is down.

Derive the page list from the index rather than hardcoding URLs, so this stays correct as the wiki grows:

    curl -s https://docs.utopiamodels.ai/llms.txt | grep -oE '\(/[a-z/-]+\)' | tr -d '()' | sed 's|^|https://docs.utopiamodels.ai|;s|$|.md|'

That emits seven URLs. Every documentation path has a raw markdown twin at the same path plus `.md`, a fraction of the size of the rendered page with the same prose. A mistyped `.md` path under `/docs/` returns an empty 404 rather than an HTML error page, so a wrong guess costs you nothing.

Dispatch subagents to read those pages in parallel. The three that matter most for building are the architecture page (hosts, agents, the dispatch runtime), the work page (how a unit of work travels from filed to merged), and the operations page (the runbooks, including the literal dispatch and scheduler commands).

Then read the live surface, which is generated per request and stores nothing:

    curl -s https://docs.utopiamodels.ai/live.md | grep -E '^\| (agent|agent-sf|win|nova|cloud|dust) \('

You get one table row per agent, split into what the registry says exists and what can actually run. At the time this was written one agent read `CANNOT RUN — resetsAt=null — NOTHING brings this back on a timer. It needs a human.` That is the reference fleet publishing its own broken part. Build the same distinction into what you scaffold, because an agent's account existing is not the same claim as that agent being able to take a turn, and conflating them is how a fleet looks healthy while shipping nothing.

For the queue shape, one fetch gives you real board state without needing `jq`:

    curl -s https://utopiamodels.ai/v1/board | python3 -c "
    import json,sys
    d=json.load(sys.stdin)
    if not d.get('ok'):
        print('board unavailable:', d.get('error') or 'unknown'); sys.exit(0)
    print('open:', len(d.get('items') or []), '· lanes:', d.get('byLane'), '· status:', d.get('byStatus'))
    "

A healthy response prints one line of counts keyed by lane and by status. This endpoint reads a project board at request time and stores nothing, so it degrades rather than fails: when the upstream read is refused it still returns valid JSON with `ok` false and an error string. That is why the command branches on `ok` before reading anything else — an intermittent refusal would otherwise render as an empty board, and a fleet with no work and a fleet that cannot see its work are different claims. Build that same distinction into the status command you write in step 3. If the parser raises a JSON decode error instead, the endpoint served HTML, which means an outage; treat it as unreachable.

Note the lane keys. In that fleet a lane names which machine runs the work, not what kind of work it is — routing by subject matter idles healthy agents behind a busy one. Work on a lane no scheduler reaches is undispatchable no matter how idle the fleet is, so a large open count against zero dispatchable looks like a capacity problem and is actually a routing one. Carry that meaning across.

## Step 2 — Learn my machine before you write anything

Run these and tell me the answers, because they decide which variant of the scaffold you build:

    uname -s; command -v git gh claude docker python3 2>/dev/null
    gh auth status >/dev/null 2>&1 && echo "gh: authenticated" || echo "gh: not authenticated"
    systemctl --user show-environment >/dev/null 2>&1 && echo "systemd user scope: usable" || echo "systemd user scope: unavailable"

The systemd answer is the fork that matters. The reference fleet starts each run as a transient systemd unit, which gives it process isolation, a log, and a failure hook for free. If that check says unavailable — macOS, a container, a machine without a user session bus — build the launchd variant on macOS or a supervised loop elsewhere, and say plainly in the docs you write which variant this is and what it gives up. Do not emit systemd units onto a machine that cannot run them.

Also look at what I already have, with subagents in parallel: my repository layout, any `CLAUDE.md` or `.claude/` directories, how I currently run agents if I do, and where my notes and docs live. Have each subagent report what it measured and the path or command behind it. If I already have a queue — a project board, a tracker, a task list — plan to use it rather than adding a second one. Two queues cannot both be authoritative, and the reference fleet's entire design rests on there being exactly one.

## Step 3 — Tell me the plan, then build

Before writing a single file, tell me: which directory you will create, every file you will add, anything existing you would change or delete, and the one-line reason for each. Wait for me to answer. After that you have my go-ahead for the whole list and should build it without checking in again.

Build these pieces:

A **dispatch script** that takes an agent name and a work item id, and starts a run. Starting the run is the assignment — there is no separate "assign" step and no state file recording who owns what, because a file recording that would drift from reality within a day. Before launching, it should refuse to start a second run for a work item that already has one live, and refuse an agent whose account is known to be blocked. Both refusals exit non-zero and print why.

A **runner** that is what actually executes on the agent's side. It should update itself from the repository first, re-check that the work item is still open before doing anything expensive, post a start marker before the first thing that can fail, run the agent, and post a terminal marker with a link to whatever it produced from an exit trap so the marker gets posted even on a crash. Make the terminal marker derive from real evidence — a merged change, a created artifact — rather than from the exit code. A run that exits zero having produced nothing should say so.

A **scheduler** that periodically reads the queue and starts runs for anything unstarted. Give it explicit caps on concurrent runs per agent and fleet-wide, and write the measurement that justifies each number in a comment beside it. A cap chosen out of caution silently becomes the system's capacity and never announces itself. Give it a kill switch that needs no code edit — the presence of a file the scheduler checks before each cycle is enough, and it should be stoppable without editing or redeploying anything.

A **queue client** over whatever tracker step 2 found. If it is GitHub, `gh issue list --json` is enough and you should not add a library. What a fleet needs from a queue is small: list open items with their lane and status, read one, comment on one, close one.

**Agent definitions** — one directory or file per agent, holding its instructions and what it is allowed to touch. Keep the count low to start. Two agents exercise every mechanism a fleet has; ten agents just multiply anything you got wrong.

A **status command** that answers "what is this fleet doing right now" by reading the queue and the process table live, computing nothing from a stored file. Have it print, for each agent, existence and ability-to-run as two separate columns, the way the reference live page does.

A **README** stating what runs where, the literal command for each operation, and which machine each command must be run from. A command that works from one machine and silently fails from another is the most common defect in this class of system.

Now verify what can be verified without my accounts. Run the dispatch script against a fake work item and show me it refuses cleanly. Run the scheduler with its caps set to zero and show me it explains why it started nothing. Run the status command and show me the output. Syntax-check every shell script you wrote — `bash -n` on each — and show me it passes. Do not tell me the fleet works; show me the commands and their output, and be explicit that these prove the scripts run, not that the fleet ships work, which cannot be true until my checklist is done.

## Step 4 — What I have to do myself, and what each unlocks

End with this as a section, written into the README as well as told to me. For each item: what to do, roughly how long, and what stops being broken once it is done. Cover at least these, adjusted to what step 2 found:

- **An always-on machine.** Nothing about this design works on a laptop that sleeps, because the scheduler has to fire on a timer whether or not I am at the keyboard. Until this exists, runs only happen when I start them by hand. Tell me the cheapest thing that would work given what I already own.
- **An account per agent, each with its own subscription.** Agents run in parallel only because they draw on separate quotas; sharing one account across several agents means one busy agent stalls the rest. Until this is done, the fleet is one agent with extra directories.
- **SSH access from wherever I dispatch to the machine that runs.** Until this is done, dispatch works locally and not remotely.
- **The queue itself** — the project board or tracker, with the fields your queue client reads. Name the exact fields and their allowed values. Until this exists the scheduler has nothing to read.
- **Credential storage.** Name what you chose and what I have to create. Until this is done, secrets live in files where they should not be, and no agent should be started.
- **A failure notification path**, so a run that fails at 3am is visible without me looking. Until this is done, silence and success look identical.

Order that list so the earliest items unblock the later ones, and mark which ones I can skip to get a reduced fleet running today. Close with the single highest-leverage item, in one sentence.