[design] Two-level work model — the Lead owns epics (direction), subordinates own tasks (execution)

[serge-ivo]

The model, from the owner (2026-08-07)

The leader coder owns kind of, like, epics (general direction) for each agent and remembers
that — those should be on the board. Each coder agent operates on task level.

Two levels, split by who owns what:

	Lead	Subordinate
Owns	epics — durable direction per repo	tasks — units of execution
Board holds	"FWS: finish the voice port"	"fix #36", "tree is dirty", "PR #153 needs review"
Acts via	delegate_goal	its own Pilot + engine

This is the revisit #150 explicitly left open. That ticket shipped tickets as flat, saying so
in its own words:

The Ticket (three properties — flat, no epics for now)… Deliberately no parent/epic hierarchy
for now (keep it simple — revisit only if a real need appears).

The need has appeared, from the person running four coders daily.

Why this does not contradict #322

#322 decided responsibility sits with the subordinate — "he drives the terminal", and that a
policy violation is a board item on the subordinate, not the Lead.

That still holds. The two are different levels, not competing owners:

• Direction is the Lead's and is durable — it survives across runs, sessions and days. That is
  what makes it worth remembering rather than re-stating every conversation.
• Execution is the subordinate's, including anything a policy raises. Nothing moves onto the
  Lead's board that a human would go to the subordinate to fix.

The distinction is the same one #322 draws between a policy and a goal, one level up: an epic is
standing intent; a task is a discrete unit of work; a policy is an invariant. All three are
durable, which is precisely why none of them should live only in a chat transcript.

What it fixes

Today the Lead's memory of direction is the conversation. Ask it "what should FWS be working on?"
and the honest answer is whatever it can reconstruct from subordinate_status — recent runs and
board items — which is history, not intent. Direction that exists only in a chat is lost the moment
the thread rolls over, and re-stated by the user every session. That is the same pattern as
preference:response_style living in memory before Behaviour existed (#226): a durable thing with
no proper home, kept wherever it happened to land.

It also gives delegation a reason. Right now every delegate_goal is free-standing. With epics, a
run can be attributed to the direction it serves — which is what makes progress reportable
(#310's stats become "movement against an epic" rather than "runs per day").

Design questions worth settling before building

1. Is an epic a board item, or its own thing? The board already exists on both sides and Agent work as first-class Tickets — granular, with reasoning + per-ticket conversation #150's
   ticket shape is flat by design. Adding a parent to tickets is the smaller change; a separate
   epic model is cleaner but duplicates lifecycle.
2. One epic per subordinate, or many? "General direction for each agent" reads as one active
   epic per repo, which is far simpler than a backlog and matches how the Lead is actually used.
3. Does a delegated run link back to its epic? Strongly suggest yes — otherwise the Lead can
   state direction but still cannot say whether anything moved toward it.
4. Who closes an epic? A subordinate finishing a task cannot know the epic is done. This is
   probably a human decision, or the Lead's on explicit review — not automatic.
5. How does it reach the model? Injected as context on the Lead the way settings and behaviour
   are, derived from the board rather than restated in prose — the Prompt-drift check — three agents in two days told a story about themselves their capabilities contradicted #315 lesson.

Related

• Agent work as first-class Tickets — granular, with reasoning + per-ticket conversation #150 — the flat ticket model this extends (closed; this is its stated revisit).
• [design] Standing policies — let the Lead keep repos true instead of reporting that they aren't #322 — standing policies; the ownership decision there is the foundation for this split.
• [stats] Per-agent Stats tab — declarative card schema over a closed, owner-scoped source vocabulary #310 — stats; epics are what would make "progress" measurable rather than "activity".

[serge-ivo]

Assessment: the model is right, it needs no new machinery, and the slot it wants is already in the schema — empty

Design deliverable, same treatment as #279. Short version: yes to the two-level model, no to every
piece of storage the ticket contemplates. An epic is not a ticket with a parent and not a new
record; it is one field on a relationship that already exists, in a JSON column that already exists,
made unique per subordinate by an index that already exists. Question 3 — attribution — I would
not build, because it is already derivable from data the platform writes today.

Four things I checked in the code first, because three of them change the answer.

---

1. The lower level is already complete, and the Lead already reads it

subordinate_status returns, per subordinate: board cards with the subordinate's own status and
its columnTitle (so the Lead can read a vocabulary it does not hold), loop runs with
quietForMinutes, connectivity.canWork, repo (branch / dirty / changed files / githubRepo),
and acts with ok: true | false | null — lib/connectors/supervision.ts:156-277, assembled by the
pure summarizeSubordinates (lib/subordinate-observation.ts:74).

So "subordinates own tasks" is not work. It is done. The entire gap in this ticket is on the Lead's
side, and it is one durable string per subordinate.

2. The Lead already has durable, prompt-injected storage — twice — and neither is a good home

BASE is granted unconditionally, including to an agent that declares a capabilities.tools
allowlist: toolNamesFor seeds the set with BASE and only then applies the allowlist
(agent-do-tools.ts:186-188). So the Coder Lead — which declares six tools — silently also has
write_memory, create_task, configure_board, start_work, check_work, get/set_behaviour.

Both candidate homes are already injected every turn, which means design question 5 costs nothing
whichever way this goes:

• ## Your Memory — agent-think.ts:245-259. Keyed, owner-editable via
  GET/PUT/DELETE /v1/instances/:id/memory (routes/storage.ts:397-451), source-tagged, and the
  prompt already forbids the agent overwriting a (user-set) entry.
• ## Active Tasks — agent-think.ts:271-277, from the instance DO's own task list.

Neither is right, for different reasons:

• Memory would work mechanically, but Agent Behaviour: stop character leaking into Memory; migrate preference:* and responseStyle #226 drew the line at "memory is for facts about the
  SUBJECT". Direction is not a fact about the subject, it is intent about it, and putting it there
  re-runs the argument that produced preference:response_style — a durable thing parked wherever it
  landed. The ticket says this itself.
• DO tasks are worse than they look. I filed Instance DO tasks are agent-writable, prompt-injected, and invisible to the owner #337: on an instance, create_task writes to a
  Durable-Object store with no read route and no console surface — chatRoutes (the only proxy
  for /tasks) is mounted at /v1/agents only (index.ts:141) and resolves :id against the
  agents table (routes/chat.ts:16-21), so GET /v1/agents/<instanceId>/tasks 404s. An epic there
  would be durable, prompt-injected, and invisible to the person whose direction it is.

3. "Those should be on the board" — the board is not the thing you'd be adding a parent to

board_items is an overlay, not a ticket table: PK (instance_id, user_id, job_key), columns
user_status, updated_at, title, subtitle, url (0036 + 0037). It persists only a human's status
move. The cards themselves are derived at read time from instance_runtime_tasks
(lib/board.ts:276, mirroredRuntimeTasks). There is no Ticket type anywhere — a ticket is an
untyped object literal in instance_runtime_tasks.payload (routes/instances.ts:1096-1108).

And nothing in board_items, instance_runtime_tasks, BoardItemView or WorkItem carries a
parent, child or link field. Adding one is not "the smaller change" — it lands in the payload shape,
the derived board builder, the console renderer and MCP, all four.

The decisive problem is not size, it is direction of reference. Every board table is keyed
(instance_id, user_id, …). A Lead's epic lives on the Lead's instance; the tasks it would parent
live on the subordinates'. A parent pointer would be the first cross-instance reference inside
instance-scoped storage, in a system whose marketplace invariant is that instance storage is
isolated. Every cross-instance relation today lives somewhere else on purpose: the graph
(agent_supervision), the pump (agent_connections), or the run (agent_loop_runs.delegated_by).

4. The slot already exists, has been migrated, and is read by nothing

-- migrations/0060_agent_supervision.sql
CREATE TABLE IF NOT EXISTS agent_supervision (
  id, user_id, supervisor_instance_id, subordinate_instance_id,
  enabled INTEGER NOT NULL DEFAULT 1,
  config  TEXT,                   -- JSON: label, per-edge budget defaults (#184)
  created_at, updated_at
);
CREATE UNIQUE INDEX idx_supervision_subordinate ON agent_supervision(subordinate_instance_id);

config is written at create (lib/supervision.ts:137) and parsed into SupervisionView.config
(:54). No code path reads a field out of it. It is an empty JSON column on the exact
relationship an epic describes — "this Lead's standing intent for this subordinate" — and the unique
index makes it one-per-subordinate for free.

---

Recommendation

An epic is agent_supervision.config.direction. No migration, no table, no parent pointer, no
cross-instance reference, no fifth record.

// agent_supervision.config
{ "direction": { "text": "Finish the voice port and get the suite green.",
                 "setBy": "user", "updatedAt": "2026-08-07T…" } }

That resolves the design questions as follows.

Q	Answer
1. Board item or its own thing?	Neither. A property of the supervision edge — the same shape as merge_policy on coding_repos or behaviour on an instance config.
2. One or many?	One, and it is enforced by idx_supervision_subordinate, not by application code. "General direction for each agent" is literally the primary key.
3. Does a run link back?	No new field. See below.
4. Who closes it?	The human, or the Lead on explicit review. Closing = clearing the field. The agent may never clear or overwrite a setBy: "user" direction unasked — the rule memory already has and already states in the prompt.
5. How does it reach the model?	subordinateSummaries (connectors/supervision.ts:100-150) already builds the roster from a D1 read per turn; add direction to that SELECT and it lands in list_subordinates, in subordinate_status, and in one derived ## Your Agents prompt block. Derived from the record, never restated in prose — the #315 rule.

Question 3 in full: attribution is already derivable, and I would not add a column

The ticket suspects yes. I think no, and the reason is arithmetic rather than principle.

agent_loop_runs after 0090 carries instance_id and delegated_by (indexed:
idx_agent_loop_runs_delegated_by(user_id, delegated_by, started_at DESC)). The epic is keyed by
(supervisor, subordinate). Those are the same two ids. So:

runs against the FWS direction = runs where delegated_by = <lead> and instance_id = <fws>

is a query over columns that already exist, on an index that already exists. listDelegatedRuns
(lib/agent-loop-store.ts:134) is nine-tenths of it. An epic_id column would store a fact the
join already yields.

The one thing the join cannot answer is "the direction changed on Tuesday — which runs served the
old one?" That needs direction history, which is a fifth record of what happened, and this repo
has already written down why it does not want one (lib/stats-sources.ts:11-17, "No fifth record of
what happened"). If #310 later needs movement-against-an-epic, it gets it from the join. If someone
later wants the history, that is a separate ticket that has to argue for itself.

---

What I would not build

1. A parent/child hierarchy on tickets. It crosses the instance boundary inside isolated storage,
   it touches four layers, and the hierarchy it buys is exactly one level deep with exactly one
   parent per subordinate — which is the primary key of an existing table.
2. A separate epic model with its own lifecycle, ordering, progress percentage and backlog. The
   ask is "remember what FWS is for", not a project-management product. Agent work as first-class Tickets — granular, with reasoning + per-ticket conversation #150's flat decision holds;
   this does not reverse it, it declines to extend it.
3. epic_id on agent_loop_runs. Derivable, per above.
4. Auto-closing an epic from a subordinate's completion. A delegated run records its outcome but not its consequential acts — merging to main is invisible #294's whole finding is that "completed"
   describes the objective and never what changed on the way — a subordinate cannot attest to an
   epic, and the acts legend already tells the Lead not to read completion as an all-clear.
5. Any epic on the subordinate's board. [design] Standing policies — let the Lead keep repos true instead of reporting that they aren't #322 settled that the Lead does not accumulate other
   agents' work; the mirror of that rule is that direction does not descend into the subordinate's
   queue. A subordinate receives a goal, not an epic. Anything else makes the direction a second
   place to look for the same thing.
6. An epic-aware delegate_goal argument. The tool takes exactly {instanceId, objective, maxIterations} (connectors/supervision.ts:356-364) and should keep taking exactly that. The
   supervisor and the subordinate are both already named on the call; adding a third identifier for
   the pair they form is redundant.

The one real risk, and how it is already solved

The direction is free text, it persists across sessions, and the Lead reads agent-authored
subordinate summaries every turn. If the Lead can write its own direction, a single prompt injection
in a repo file or an issue body converts into a standing instruction that survives the
conversation — strictly worse than a bad turn.

So the write rule is not a nicety, it is the security boundary, and it is one this codebase already
implements: the agent may propose; the owner sets. Concretely — setBy: "user" is immutable to
the agent (the exact rule ## Your Memory states at agent-think.ts:247-249), and an agent-written
direction is marked setBy: "agent" and rendered in the console as a proposal awaiting confirmation.
This is #279's user-requested-vs-agent-initiated split, and it does the same work here.

Scope of the actual build

• direction added to the subordinateSummaries SELECT and to SupervisionRow/SupervisionView.
• GET/PUT/DELETE on the existing supervision route for the field, owner-scoped.
• One ## Your Agents block in the Lead's prompt, derived from the roster.
• set_direction as a registry tool, scope: "write", refusing to overwrite setBy: "user".
• The console's supervision settings row gains a text field.

No migration. If that turns out to be wrong, the thing to revisit is the read path, not the schema.

Leaving this open — design-assessed, not implemented, and #337 (invisible DO tasks) is the reason
the DO-task option is off the table today.

[serge-ivo]

Shipped — the direction is a field on the edge, and only the owner writes it

0ec9dd9 (plus fb9e40b, 5c206a4), CI green. Built to the design comment above; the four claims
it rests on were re-checked at HEAD first, because several tickets this week described work already
done and two described the opposite of the truth.

Which claims held

Claim	Verdict at HEAD
agent_supervision.config is migrated, written at create, read by no code path	Held. createSupervision wrote it, toView parsed it into SupervisionView.config, and the only consumer was GET /:id/supervision, which handed the blob to a console that typed it away. No field was read from it anywhere.
idx_supervision_subordinate is UNIQUE	Held (migration 0060) — so "one direction per agent" is the primary key.
The lower level is already complete	Held. subordinate_status returns each subordinate's cards with its own columnTitle (subordinate-observation.ts:116), runs, connectivity, repo and acts. The whole gap was one string on the Lead's side.
"A parent on tickets is the smaller change" is FALSE	Held. board_items is a status overlay; cards are derived at read time by mirroredRuntimeTasks from instance_runtime_tasks, and a Ticket type does not exist anywhere in the repo.
Attribution is derivable — no epic_id	Held. agent_loop_runs carries delegated_by + instance_id, indexed together by 0090; the epic is keyed by those same two ids.

No migration. Nothing needed one.

How the direction is set, and why an agent cannot set it alone

PUT /v1/instances/:id/supervision/:sid/direction (and DELETE to clear) is the only path that
writes setBy: "user". The agent's set_direction registry tool writes through the tool runtime
and never speaks HTTP, so it can only ever produce setBy: "agent" — provenance moves agent → owner
and never back, structurally rather than by convention. nextDirection (pure, tested) refuses an
agent write over a setBy: "user" value, and parseDirection fails closed: anything that is not
exactly "user" is the agent's, so a future path that forgets to stamp provenance cannot inherit
authority by default.

An agent-written direction is also never rendered as direction. It comes back under
proposedDirection, a different key, with the legend saying it carries no authority — because three
turns later the model cannot tell its own text from its owner's, and a direction lands on every
later prompt, which is what turns one prompt injection into a standing instruction. The console
shows a proposal as one and its button reads Confirm, not Save: confirming is the owner
re-sending the text through the owner's route. Same mechanism as memory's (user-set).

It reaches the model three ways, all derived from the record per turn (#315), never restated in
prose: list_subordinates, subordinate_status, and a ## Your Agents prompt block gated on the
agent declaring a supervision tool, so only an agent that supervises somebody pays for the read.

What I did NOT build

All six from the design: no ticket parent/child hierarchy, no epic model with a lifecycle, no
epic_id on runs, no auto-close from a subordinate's completion, no epic on a subordinate's board,
no extra delegate_goal argument. Closing an epic is the owner clearing the field.

One deliberate gap

The live Coder Lead declares its tools in migration 0067, so it does not yet have
set_direction — its read path is complete (both roster tools and the prompt block), only the
proposal tool is absent. Adding it is a capabilities.tools edit through the #141 update route, no
migration and no monorepo PR, so I left that as the owner's call rather than writing a data
migration for it.

[serge-ivo]

Implemented in 0ec9dd9 — see the comment above.