Dashboard architecture: the plan and six questions

[suleimansh]

The dashboard for the skills architecture, from #1768. This issue is the plan and the questions. Nothing is built yet.

1. What exists. One React app inside the framework package, served by the daemon with an SPA fallback. Seven routes: the Overview, a project's launcher, a run's page, /tickets, a ticket's page, a ticket's plan, and /settings. The sidebar has Overview, Tickets, Projects and Settings as literal rows. Every skill's data reaches the browser through the framework's own RPCs, and every skill's page or card is the framework's code. Nothing in the UI, the daemon or the registry says which skills a project uses: the four skills are hard dependencies of the framework, always linked into every checkout, always on every agent's PATH.

2. What is decided. From Dashboard architecture #1768: one page per skill (/tickets for the tickets, /agents for the logs), a hook for cards on the Overview (the dashboard's / page), and modularity over UX paper cuts. From the skills round: no skill imports another, the framework is the caller, and a skill is picked per repository by committing its files.

3. The questions. I need your call on six things. Each has its options in the plan below.

   • Q1, where a skill's dashboard code lives: inside the framework, one directory per skill behind a registry; or exported by the skill package; or a sibling package per skill.
   • Q2, how the dashboard knows which skills a project picked: the committed skills directory, package.json, a setting in the daemon's registry, or the data's presence.
   • Q3, the Overview, the dashboard's / page: each skill contributes one card and the framework keeps its own, or the Overview is framework-only with the skill pages one click away.
   • Q4, the pages, and the buttons that need two skills: the ticket page's Queue button, the hot tickets' queue lane, a claim's link to its run.
   • Q5, the runs when the logs skill is not picked: the run page is the framework's while a run lives; the finished run is the logs skill's, and without it the run is gone with its worktree. No second archive.
   • Q6, the order: logs first, since the framework already reads runs only through the skill's library, or tickets first, since its pages exist.

4. Names. Today's names, skill-<x>, <x>. /agents is your name for the logs page. A rename to skills-<x> changes nothing below.

5. PR shape is my call after the answers. No FEATURES-SPEC.md, SPEC or LOGIC files: main has none since the clean slate.

---

🤖 curated · Fable 5.1 — the plan, as the agent wrote it after reading every page, route, component and RPC of the dashboard on main (5c8d41d); I read it and I stand behind the questions above.

The plan

What it is. The dashboard today is one app that knows every skill. The skills are standalone packages now, and a repository picks the ones it wants. The dashboard has to show a page, a card or a control only for the skills that repository picked, and the code has to be arranged so that one skill's page is one skill's directory. This plan says what the code does now, where each surface belongs, and what has to change, question by question.

Where every surface belongs today. Paths under packages/framework/, dashboard/ is the browser, src/ is the daemon.

surface	file	skill
the shell, routes	dashboard/App.tsx:276-377, dashboard/lib/route.ts:19,30,37	framework; tickets is a reserved word
the sidebar	dashboard/components/AgentHistory.tsx:198-215 nav rows, :233-270 the runs	framework nav; the runs are logs
the Overview, the / page	dashboard/components/DashboardPage.tsx:54-82	seven sections, see Q3
the project launcher	dashboard/components/ProjectHome.tsx:51-66	framework, plus the Docs section reading the queue file (src/dashboard/docs.ts:57)
the run page	dashboard/components/AgentView.tsx:90,97,206-224	framework live; replay from logs (:90); branch controls from branches (AgentHandoff.tsx:182-231, AgentActionsMenu.tsx:204-220, GitStatusBar.tsx:60)
the ticket pages	TicketsPage.tsx, TicketDetailPage.tsx, TicketPlanPage.tsx, TicketsPanel.tsx, TicketFilterBar.tsx, HotTickets.tsx, lib/ticket-filter.ts	tickets; queue for the Queue buttons (TicketsPage.tsx:127,145,168, TicketDetailPage.tsx:41); logs for a claim's link (TicketsPanel.tsx:162-165, TicketPlanPage.tsx:46)
the queue	AiQueue.tsx, lib/queue-entry.ts, DocsPanel.tsx	queue; no page of its own; only TicketsPage.tsx:127 calls onQueue directly
routines	RoutineWork.tsx:91,136,165	framework (auto PM)
settings, bridge, devices, Discord, quota, cloud notices, open questions, composer, presets	SettingsPage.tsx, Bridge*.tsx, DevicesSettings.tsx, DiscordDialogs.tsx, Quota.tsx, CloudAgentNotice.tsx, OpenQuestions.tsx, Composer.tsx, PresetsMenu.tsx	framework
the RPCs	src/dashboard-rpc/reads.ts, control.ts	19 of the 33 reads and 9 of the 17 controls go through a skill library; the joins are in src/dashboard/overview.ts, dashboard.ts, tickets.ts:48-55, interventions.ts
the server	src/dashboard/server.ts:224-274 one bundle dir, static.ts:43 SPA fallback, bundle.ts:20 one path	framework
the daemon	src/daemon.ts:212-250 wires the daemon's closures; src/daemon-runtime.ts:116-120 PATH, :127-131 the linked skills, marked temporary	framework

What "absent" means today. Two different things, and the plan keeps them apart:

• The package is absent. Impossible: packages/framework/package.json:50-53 depends on all four, the daemon drains the queue through @gemstack/skill-queue, claims through @gemstack/skill-tickets, records through @gemstack/skill-logs, makes checkouts through @gemstack/skill-branches. The framework is the caller; it keeps every library.
• The data is absent. This is what the UI handles already: no tickets/ on the branch gives an empty list (TicketsPage.tsx:386), no queue file gives "Nothing queued." (AiQueue.tsx:150), no runs give "No agents yet." (AgentHistory.tsx:270), a claim whose agent is not in the records is shown as written (src/dashboard/tickets.ts:53), the right rail offers a tab only when its read came back non-empty (RightRail.tsx:105-112).

So "the user did not pick the skill" is a third state that nothing knows. The one flag that exists is hasTickets (src/dashboard/dashboard.ts:17-21), the presence of a ticket file, read by the onboarding checklist alone (OnboardingChecklist.tsx:150). The sidebar's Tickets row has a prop that would hide it (AgentHistory.tsx:84-86,211), and the shell always passes it (App.tsx:420).

How a skill is picked, per the install tool. A skill package's skills are materialized as real, committed files under the repository's skills directory, .agents/skills/<name>/ by default or whichever */skills/ directories already exist, each with a source.json naming the package and version; never a link into node_modules (use-npm-skills 0.1.0, its DECISIONS.md "Materialize each skill"). The install here today: .agents/skills/logic-driven-development/ plus skills-lock.json. The four skills are not in any project's skills directory yet: the daemon links them into each checkout's .claude/skills and .agents/skills (src/daemon-runtime.ts:127-131, packages/skill-branches/src/skill-links.ts:20,59-70), git-excluded, and the project root gets none.

The join points, the reads that need two skills:

• src/dashboard/overview.ts:288-342 (buildOverview): live runs, cloud runs from the records, the queue count.
• src/dashboard/overview.ts:225-267 (buildHotTickets): tickets, the open queue entries, the live runs' tickets.
• src/dashboard/dashboard.ts:48-72 (buildDashboard): the queue once, the overview, hasTickets per project. One RPC feeds three Overview cards.
• src/dashboard/tickets.ts:48-55 (resolveHolders): a claim's holder matched against the records, named through branches.
• src/dashboard/interventions.ts:87-184: open PRs on agent-* branches, parked runs, unpushed branches from the records.
• src/dashboard-rpc/control.ts:351-382: queue a ticket, queue its plan.

---

Q1: where a skill's dashboard code lives

Story. You open packages/skill-tickets/. Today it holds the command, the library, SKILL.md and DECISIONS.md. The ticket pages, 2,200 lines, sit in packages/framework/dashboard/components/ beside the composer and the settings page, and their RPCs sit in src/dashboard-rpc/reads.ts beside the bridge's. Someone reads the tickets package to review its design, and does not find its UI. Someone reads the dashboard to remove tickets, and has to know which 12 files are the tickets'.

Options.

• A. Inside the framework, one directory per skill, behind a registry. dashboard/skills/tickets/ holds the pages, cards and client stubs; src/dashboard-skills/tickets/ holds the RPC module and the reads. One registry file lists the four entries: name, nav row, routes, Overview card. The shell, the sidebar and the Overview read the registry and nothing else. The framework's build makes one bundle as today. The skill package stays what it is.
• B. Exported by the skill package. @gemstack/skill-tickets/dashboard exports the same pages, React as an optional peer dependency; the framework's build imports the export and composes the bundle. This is the "super package": one package, the skill and its dashboard extension. The RPC side stays in the framework, since the handlers act through the daemon's context (src/dashboard/rpc-serve.ts:50-75), or moves too, behind a plugin contract for the daemon.
• C. A sibling package per skill, @gemstack/skill-tickets-dashboard. Same as B with the React code out of the agent's install.

What A costs: the skill's UI lives outside the skill's package, and a third-party skill cannot bring a page. What B costs: a CLI package that carries React code and a design system, a contract for what a page may use (the RPC transport, the shell's navigation, the UI primitives at dashboard/components/ui/), and a daemon contract if the RPCs move too. Under B and C the framework still bundles every page, because it depends on every skill: the modularity the user sees is Q2's, not the package boundary's.

🤖 recommends A now. The four pages are first-party, and the contract a page needs is exactly what building four of them behind one registry teaches. B is a directory move once that contract is known, and the registry entry becomes the export. Nothing in A is thrown away by B.

Q2: how the dashboard knows which skills a project picked

Story. You register two repositories. One picked all four skills. The other runs on Claude Code Web and picked tickets and logs only. You open the Overview. Which cards show? You open the second project's launcher: does the run page offer "Remove worktree"? Today both projects show everything, and the daemon links all four skills into both.

Options.

• A. The committed skills directory. Per project, the daemon lists <root>/.agents/skills/*/ (or whichever */skills/ directories the tool used) and keeps the names that are ours: branches, tickets, queue, logs. One read per registry poll, on ProjectSummary. A fresh clone answers the same on every machine, since the files are committed. This is the install tool's own model and the "conventions are the only glue" rule.
• B. package.json. The project depends on @gemstack/skill-tickets. Committed too, and true here today (root package.json:25-28). False for a skill installed from GitHub with the skills CLI, which writes no dependency.
• C. A setting in the daemon's registry, the-framework.json, per project, on the settings page. Per machine, not in git; two machines can disagree; the agent's checkout does not read it.
• D. The data's presence. tickets/ on the branch means tickets, as hasTickets does today. Wrong for a picked skill with no data yet, and for logs, whose data appears after the first run only.

Whatever the pick, the shell takes the union over registered projects for the sidebar rows and the Overview cards, and the project's own set for its pages and its run page's controls.

🤖 recommends A. One mechanism, the tool's, read from git. Until the four skills are materialized into a project (step 0 in Q6), the read finds none of them and the dashboard shows all four, as today: no second code path, one line saying "no skills directory means every skill".

Q3: the Overview, the dashboard's / page

Story. The Overview has seven sections in a fixed order: the onboarding checklist, usage, the Human Queue, the agents working now, the AI Queue, the routines, the hot tickets (DashboardPage.tsx:54-82). Four of the seven are a skill's. Someone who did not pick the queue sees a card saying "Nothing queued." and an onboarding step asking them to populate a queue. Someone who did not pick tickets sees "Nothing in progress, queued, or high priority."

Options.

• A. Each skill contributes one card through the registry. Logs gives the agents working now (today's Agents.tsx, fed by the live runs and the records), queue gives the AI Queue, tickets gives the hot tickets. Branches gives none: its facts already sit inside the Human Queue's unpushed rows. The framework keeps the checklist, usage, the Human Queue and the routines. A card renders only when some registered project picked its skill. The checklist's two skill steps (OnboardingChecklist.tsx:140-156) hide the same way. The composite RPC onDashboard splits: each card polls its own read, as the hot tickets already do (HotTickets.tsx:63).
• B. A framework-only Overview. Usage, the Human Queue, the agents working now, the routines. Every skill is a sidebar row and a page, nothing more. Fewer joins, one less RPC, and the at-a-glance backlog is a click away.

🤖 recommends A. The hook you asked for is the registry entry's card. The cards exist; the work is the split of onDashboard and the pick check.

Q4: the pages, and the buttons that need two skills

Story. A ticket's page has a Queue button (TicketDetailPage.tsx:41). The tickets list has two bulk actions that read the queue before writing it (TicketsPage.tsx:127-168). The hot tickets have a lane that is the queue (HotTickets.tsx:49-53). A claimed ticket links to the run that holds it (TicketsPanel.tsx:162-165), and a plan links to the run that wrote it (TicketPlanPage.tsx:46). Someone picked tickets and not the queue. What does the Queue button do?

The pages.

skill	page	today
tickets	/tickets, /{project}/tickets/{slug}, /{project}/tickets/{slug}/plan	exist, move as they are
logs	/agents	does not exist: the runs live in the sidebar (AgentHistory.tsx:233-270) and the run page. The page is the cross-project list the command prints: every run, newest first, with its ticket, branch, PR, status and cost, filters by ticket and branch, each row opening the run page
queue	/queue, or none	the AI Queue card is the whole surface today (every project's entries with a start button). A page adds room for the priority sections and the entry text; the card stays the summary
branches	none	its UI is the run page's controls: branch, dirty, PR, push, merge, remove worktree, and the launcher's git bar

The buttons. Every cross-skill control follows the same rule as the tickets SKILL.md, which says "when the repository has the queue skill": the control renders only when the project picked both skills. The Queue button, the two bulk actions and the queue lane need queue; the claim's link and the plan's row need logs; the run page's branch controls need branches. Without the second skill the button is not there, the lane is empty, the holder is shown as written. This is the behavior the empty states already have; the pick check adds the case where the data could exist but the skill was not wanted.

The joins on the daemon side stay where they are, in the framework's read modules, since the framework is the caller and may read two skills; each join already yields an empty part when one side has no data.

🤖 recommends: tickets as they are; /agents as the runs list; no queue page this round (the card is the surface, a page when someone misses it); branches without a page; the both-picked rule for every cross-skill control.

Q5: the runs when the logs skill is not picked

Story. You start an agent. Its page streams the live file from its checkout (src/store/agent-checkout.ts:46-55), the composer sends messages, the gates ask you. The run ends. The daemon records it through the logs library (src/store/agent-store.ts:921) and, once the branch is pushed, reclaims the checkout. Tomorrow you open the run: the page replays the diary (AgentView.tsx:90, src/store/agent-store.ts:1055), the sidebar lists it from the records (:866-870). Now the same day in a project that did not pick logs.

Options.

• A. Live is the framework's, finished is the logs skill's. The run page, the feed, the composer, the gates, the browser panel and the stop stay framework and read the checkout while it exists. Without logs the daemon records nothing, the finished run drops out of the list when its checkout is reclaimed (the live list reads .branches/*/.the-framework/agent.json, src/store/agent-store.ts:1028-1041), and the page says "This agent is gone" (App.tsx:341-348). The Human Queue loses its unpushed rows, which come from the records (src/dashboard/interventions.ts:167). A continue of a reclaimed run is impossible without its record, which is already true.
• B. The framework keeps a local archive as the fallback. The transient copy under .the-framework/agents/ (src/store/agent-store.ts:851) becomes the no-logs store, so finished runs survive on the machine that ran them. Two stores, two readers, the situation the logs skill just ended.

🤖 recommends A. Modularity over paper cuts: a project that did not want the logs does not get them.

Q6: the order

Story. Four skills, one registry, one pick read, one new page. Which goes first decides what the second PR inherits.

Options.

• A. Logs first. Step 0, the four skills materialized into the projects with the install tool, so the pick read has something to read; its layout is the tool's, not ours. Then the registry with the pick read and the sidebar rows hidden by pick. Then the logs entry: the /agents page, the agents card, the sidebar's recorded rows. Then tickets: the pages move under their directory, the hot tickets card, the checklist step, the both-picked buttons. Then queue: the AI Queue card, the Docs section's queue file (src/dashboard/docs.ts:57) and the rail's Docs tab as the queue's. Then branches: the run page's controls behind the pick. The framework reads runs only through the logs library since The agent logs as their own skill: @gemstack/skill-logs, command logs; agents-logs folded onto agent-data #1771, so the logs move touches no store.
• B. Tickets first. The pages exist, so the first PR is the largest move and proves the registry on the most code. Logs second.

🤖 recommends A. Your example in #1768 was /agents, and the tickets move is mechanical once the registry stands.

---

PR shape

One PR per step above, each one skill's directory plus the registry line that mounts it; the first PR carries the registry and the pick read alone. Step 0 is a cutover by hand, per project, once the skills' package layout matches the install tool's. No package is published by this work. FEATURES-SPEC.md, SPEC and LOGIC files are not touched: main has none since the clean slate.

Not in this round

A page brought by a third-party skill. Presets as skills (#1770). Routines as a skill. The skills-<x> rename. The chrome extension. The design gallery (dashboard/design/), a manual list of previews that gains a line per new card.

[suleimansh]

My picks, one per question, updated after your questions on Discord. Where they differ from the plan in the issue body, the picks win. For each: the story I used to decide, the options, what I picked.

---

Q1, where a skill's dashboard code lives

Story. The tickets skill is one package: the command and the SKILL.md. Its dashboard pages are not in it. They live inside the framework, mixed with everything else. You open the package to review the skill and see no UI. I want to remove tickets from the dashboard and have to hunt for its files.

Options.

• A. Inside the framework, one directory per skill.
• B. Exported by the skill package, React as a peer.
• C. Its own package.

👤 I picked: out of the framework first, as one package per skill. The widget leaves the framework's dashboard and ships in the skill's package with the command and the SKILL.md, on its own export path. Splitting it into its own package later is one move, if a reason shows up. The SKILL.md apart from the command is your npx auto-package-manager direction and stays as it is. Names are yours.

---

Q2, how the framework and the dashboard know a skill

Story. Someone does not like our tickets skill. They write their own, where tickets are GitHub issues instead of markdown files. They install it instead of ours. Does the framework still work? That is interchange: swap one skill for another that does the same job.

Why option A fails that. The dashboard reads the skills folder and keeps only four names: branches, tickets, queue, logs. A skill called github-tickets is invisible. And the daemon's own code calls our tickets package directly, by import, when it claims a ticket for an agent. It cannot call anyone else's. So under A a user can skip our tickets skill, but never replace it.

A picture. A phone charger. The phone does not know charger brands. It knows one plug shape, USB-C, and any charger with that plug works. Option A was a phone that accepts four chargers by brand name.

The fix, your idea from Discord: capabilities. The framework stops knowing skills at all. A routine is a prompt, "get tickets to work on". The agent reads the skills folder, finds the tickets and queue skills, and does the rest itself: queue, pick an entry, tickets claim, work. Swap our tickets skill for github-tickets and the prompt does not change; the agent reads the new SKILL.md. A missing capability is reported: the SKILL.md says "if you cannot get tickets, tell the user", and a show-error skill gives the agent the channel, the dashboard, email, whatever the user reads.

Two moments keep framework code, because no agent exists then: the checkout before the run, and the record after it. Whether those stay as two daemon calls, or move into the agent too, is open.

First an experiment. A throwaway repository, a real agent, only the two SKILL.md files in its skills folder. Four runs: the prompt with both skills, with Sonnet and with Opus; the same prompt with the queue skill removed; two agents on one queue at once; the cost of a tick that finds nothing. If the agent does it reliably, this is Q2. If not, the fallback for the daemon's side is a plug shape per job: the command the framework runs and the JSON it expects back, which any skill can fill.

👤 I picked: capabilities. The experiment ran, result in the comment below: the agent composes the skills by itself from Sonnet up, and the routine's prompt carries the rules of the job. The skills folder is still read, whoever wrote it; the four names and the four imports go. The two no-agent moments, checkout before and record after, stay framework code for now.

---

Q3, skills knowing each other

Story. Today our skills know each other. The tickets SKILL.md tells the agent about the queue command. The ticket page has a Queue button. The hot tickets card has a queue lane. A claim links to a run, which is the logs' data. Each of these is one skill knowing another exists.

In theory. Yes, it can be avoided. Someone has to know both, and that someone is the framework, the one who installed both. Never a skill.

In practice, case by case.

• The SKILL.md sentence goes. The agent learns "queue a ticket after planning it" from the framework's own prompt, which already knows both commands.
• The Queue button is not the ticket page's. The dashboard has a generic slot, actions on a link. The queue widget registers "Add to queue" for any link. The ticket page shows tickets as links. The dashboard puts the two together. Drop the queue and the button is not there.
• The claim's holder is an agent id, the framework's own concept. The dashboard turns any agent id into a link when a records widget exists. Tickets never hears of logs.
• The hot tickets card mixes three skills, so it is the framework's card, or it splits into a tickets card and a queue card.
• logs --ticket matches a field the framework wrote. A neutral name, work with a link inside, removes the last word "ticket" from the logs skill. Your call.

👤 I picked: no skill knows another. The framework is the only one that knows two, and every cross-skill feature is the dashboard composing generic pieces, links and agent ids.

---

Q4, what a skill brings to the dashboard

Story. The router has tickets as a reserved word and the sidebar has a Tickets row written by hand. A new skill with a page means editing the framework. And the run page's branch buttons, push, open PR, merge, remove worktree, are wired to our branches package.

👤 I picked: the dashboard reserves nothing; the skill defines its route, its widget, its actions. The dashboard offers slots and each widget fills what it wants: a page with a sidebar row, a card on the Overview, actions on links, on runs, on cards. Or nothing: a skill with no widget is a command and a SKILL.md, and the dashboard never mentions it. The dashboard discovers and mounts, and names no skill. The rule "show the button when both skills are picked" is gone; Q3 replaces it. Whether the queue gets a page is the queue widget's decision, not the plan's.

---

Q5, the runs when no records skill is installed

Story. I start an agent. Its page streams the live file from its checkout, the composer sends messages, the gates ask me. The run ends. Today the daemon records it through our logs package. Tomorrow the page replays the diary. Now the same day in a project with no records skill.

👤 I picked: live is the framework's, finished is the records job's, no fallback archive. The daemon writes a run through the job's plug and the finished run's page comes from the records widget. Nobody plugged in: nothing recorded, the run vanishes with its checkout, the page says it is gone.

What "nothing recorded" means: no card, no diary, no replay, no row in the sidebar once the checkout is gone. The agent's own chat transcript is untouched: the framework never kept it, Claude Code keeps it in its own folder, with or without any skill.

The screens, with the logs skill and without:

• The sidebar's runs. While an agent runs, its row is there in every project: the framework reads the running checkouts itself. After it ends and its checkout is removed, the row stays only if the skill recorded the run. Without the skill, the row is gone.
• A run's page while it runs. The feed, the message box, its questions, its browser. The framework's, the same with or without the skill.
• A run's page after it ends. With the skill, the page replays what the agent said. Without it, once the checkout is removed, the page says: no record of this agent, finished runs are kept only when a logs skill is installed. The dashboard names the capability, never our package.
• The page of all past runs, and the agents card on the Overview. The skill's widget. Without the skill, no page and no card. You named the page /agents; I prefer /logs, the skill's own name. Under Q4 the skill names its route, so it is one line either way.

**One cost for you t### Q6, the order

1. The SKILL.md files into the projects' skills folders, so there is something to discover. Each names its package and major in its own command line, npx auto-package-manager <pkg>^N <cmd>, so that is where the daemon and the dashboard learn the package.
2. The daemon half: the drain replaced by a routine prompt with the rules, the checkout before and the record after as the two framework calls, no skill imported. Proven with the logs skill's record.
3. The dashboard half: the sockets, a sidebar row, a page, an Overview card, filled by whatever skill is installed. The logs skill's page goes through first.
4. Then queue, tickets, branches, one at a time.

👤 I picked: this order, daemon first, UI after. The earlier step 1, the four jobs on paper, is gone: with capabilities there are no four jobs to write, the routine is the prompt.

daemon and the dashboard learn the package.
3. The plug in the dashboard and the daemon: discovery, the slots, calling a job by its command instead of importing our package.
4. One skill end to end, logs: the smallest proof, its framework side is already the cleanest.
5. Then queue, tickets, branches, one at a time.

👤 I picked: this order.

---

🤖 curated · Fable 5.1 — the stories are the agent's, told to me while I decided; the picks are mine. The first version of this comment, and the plan above, took the framework's four imports as fixed; your questions on Discord are what changed that.

[suleimansh]

🤖 curated · Fable 5.1

Q2, the experiment: can an agent compose the skills by itself, with no framework code knowing the skills?

Result: the agent picks and composes the skills by itself. What it needs from the prompt is the rules of the job, not the skill names.

The skills say how: how to read the queue, claim a ticket, close it. The agent learned that from the two SKILL.md files alone, in every run. What no file says is the rules of this job: one entry, not all; nobody answers, so never ask; publishing means pushing; an empty queue means stop. Without those rules the agent behaves as in a chat, lists the tickets and asks, or does everything it finds. With them in the prompt, both models do exactly the job. So a routine's prompt is the one line plus those rules, and the skills stay generic.

Sixteen plain claude -p runs on a throwaway repo. Only the tickets and queue SKILL.md in its skills folder. No daemon. Three tiny tickets, a queue of three. Sonnet and Opus. $3.69 in total.

prompt	what the agent did
get tickets to work on	listed the tickets and asked a human which one. Claimed nothing.
+ Use the skills in this repository.	Sonnet did all three entries end to end. Opus claimed all three, then stopped to ask before committing, three locks held.
+ Nobody will answer you: never ask, decide yourself. Take one queued task only, publish it by pushing to main, mark it done, then stop. If nothing is queued, say so and stop.	both models: queue → tickets claim → edit → push → tickets close → queue done → stop. One entry. No locks left.

The four situations, with the third prompt where it matters:

• Queue skill removed. The repository has the tickets skill but not the queue skill, and the agent is asked for work. The wanted answer is "there is no queue here", and stop.
  • Without any note in the skills: Opus said the queue skill is missing and stopped. Sonnet said nothing, took tickets straight from the ticket list, did the work and closed the tickets, without pushing.
  • With one sentence added to the tickets SKILL.md, "without the queue skill there is no agent queue: asked for queued work, say so and stop", Sonnet three more times. Queue SKILL.md gone but its package still installed: Sonnet found the queue command in package.json and used the queue anyway, twice. Package gone too: Sonnet said there is no queue and stopped, no claims, $0.08.
  • So the note works, but "the skill is absent" has to mean both its SKILL.md and its package are gone. With only the SKILL.md gone, the agent still finds the command.
• Two agents on one queue. The claims held. No ticket was worked twice. The second agent moved on from a refused claim by itself.
• Empty queue. With the stop sentence: both stop, $0.11 Sonnet, $0.18 Opus, under a minute. Without it: both start unqueued tickets, $0.29 and $0.49.
• One entry, full loop. $0.15 Sonnet, $0.27 Opus, about 30 seconds.

Open points:

• A stalled agent leaves its locks. Nothing lifts them.
• Two sentences in the tickets SKILL.md get in the way: "close once the work is merged" stalls Opus in a run with no merge step, and "install first" sends Sonnet to npm install before it reads anything.

Every run, commands in order, cost and time

Rig: local bare origin, agent-data with three tickets (priority 7, 5, 5) and a queue linking them. Skills folder: .agents/skills/tickets/SKILL.md, .agents/skills/queue/SKILL.md, linked from .claude/skills. Commands through node_modules. Claude Code 2.1.269, one fresh clone and origin per run, AGENT_ID per agent. Permission mode acceptEdits with an allowlist, not bypassPermissions as the framework uses; it cost Sonnet turns on npm install in two runs. P1, P2, P3 are the three prompts of the table.

(a) P1. Sonnet: tickets skill, npm install refused three times, tickets list, asked. Never read the queue. Opus: tickets list, queue, tickets show ×3, asked.

(a) P2. Sonnet: queue, tickets list, then per entry in queue order: tickets claim, edit, commit, push main, tickets close, queue done. Opus: queue, tickets list, tickets show ×3, tickets claim ×3, new branch, edits, stopped: "want me to commit and merge?", "close only once merged". Three locks held.

(b) P2, queue SKILL.md removed. Sonnet: tickets list, per ticket: claim, edit, commit locally, tickets close. Nothing pushed. Opus: tickets list, show ×3, claim ×3, edits, release ×3, said the queue skill is absent (found in git history), asked.

(c) P2, two Sonnet agents at once. Agent 2 claimed entry 1 (20:26:10). Agent 1's claim was refused ("reason":"claimed"), it claimed entries 2 and 3 (20:26:22) and edited both. Agent 2 pushed, closed, queue done (20:26:29), its claims on 2 and 3 refused, stopped. Agent 1 stopped before committing, two locks held.

(d) P2, empty queue. Sonnet: queue → [], tickets list, show ×3, then claim, branch, commit, release for all three unqueued tickets, nothing pushed. Opus: same start, branch, claim ×3, edits, stopped asking, three locks held.

(e) P3. Sonnet and Opus: queue, tickets show entry 1, tickets claim, edit, commit, push main, tickets close, queue done, stop.

(e0) P3, empty queue. Sonnet: queue → [], one tickets list, stopped. Opus: queue twice, stopped.

run	model	$	wall	turns
(a) P1	Sonnet / Opus	0.15 / 0.23	32 s / 27 s	14 / 10
(a) P2	Sonnet / Opus	0.29 / 0.37	66 s / 66 s	24 / 16
(b) queue removed	Sonnet / Opus	0.22 / 0.33	53 s / 54 s	20 / 12
(c) race, agent 1 / 2	Sonnet	0.17 / 0.19	52 s / 40 s	17 / 19
(d) empty queue, P2	Sonnet / Opus	0.29 / 0.49	69 s / 78 s	25 / 22
(e) one entry, P3	Sonnet / Opus	0.15 / 0.27	30 s / 35 s	14 / 13
(e0) empty queue, P3	Sonnet / Opus	0.11 / 0.18	35 s / 16 s	8 / 8

Transcripts: sixteen stream-json files, kept locally.

[suleimansh]

The daemon half, step 2 of Q6. Built as #1777. The picks are mine; the stories and options are the agent's. One question each, the same shape as the picks above.

---

🤖 curated · Fable 5.1

What the daemon does after this step

A tick fires. The daemon makes a checkout for an agent, starts it with one prompt, walks away. The agent reads the skills in the project, takes one queued task, works it, marks it done, stops. The daemon publishes the branch, records the run, removes the checkout. The daemon reads no queue, claims no ticket, deletes no entry, and names no skill.

Today the same job is spread over two loops that both import the tickets and queue libraries: the sweep in auto-pm.ts reads the queue, claims the ticket, pins the entry into the prompt, and deletes the entry after the run; and a second loop in todo-loop.ts drains the queue inside every build agent after its main work. Both go.

---

Q6.1 The routine's prompt

Story. The sweep starts an agent with a prompt. Today that prompt is built in code, in auto-pm.ts (pinnedDrainJob), one per queue entry. It reads, with the entry and its ticket filled in:

Work on this one open entry of the agent queue only (use the tickets skill):

• Fix the README title

Do not start any other entry, and do not take the entry off the queue — the framework does once your work lands. If the entry is no longer on the queue, stop and do nothing.

The entry's ticket, tickets/2026-09-13_readme-title.md, is already claimed for you: tickets show 2026-09-13_readme-title.md names you as its holder. Once your work is published, run tickets close 2026-09-13_readme-title.md — closed tickets leave the branch, and the claim goes with the ticket. If the ticket is not claimed, or claimed by someone else, it is not yours — stop and do nothing.

So the daemon reads the queue, picks the entry, claims the ticket, and tells the agent all three. The preset file prompts/presets/drain_queue.md ("Use the queue skill: run queue and work on the FIRST open entry only…") is never what the sweep fires; it only serves to recognise a drain started by hand from the dashboard. The experiment showed the agent needs none of this: no skill name, no entry, no claim, only the rules of the job. In the framework one rule changes: the agent must not push. It commits on its branch, and the run publishes the branch when the agent stops.

The prompt, from the experiment's third wording:

Get tickets to work on. Nobody will answer you: never ask, decide yourself. Take one queued task only. Commit your work on your branch and do not push; the run that started you publishes your branch when you stop. For you, committed counts as published: once the work is committed, close its ticket and mark the queue entry done. Before you stop, release any claim you still hold unless you closed the ticket. If nothing is queued, say so and stop.

Options for where the words live.

• A. A preset markdown in the framework, today's shape with new words.
• B. Split: the framework adds "nobody answers, stop when there is nothing to do" to every unattended start; the routine holds only the job sentences.
• C. In the queue skill's SKILL.md. The experiment argued against it: the skill says how, the prompt says the job.
• D. The shape of Replace presets in favor of skills with disable-model-invocation #1770: the routine is a skill, work-queue/SKILL.md, with disable-model-invocation: true, so only a person or the daemon fires it. Its body is the prompt above. The daemon starts the agent with /work-queue. The "/" list in the launcher shows it like any preset.

👤 I picked: D. The drain becomes a skill file, work-queue/SKILL.md, the first preset converted for #1770. The rest follow one at a time.

Where it lives: its own package, @gemstack/routines, decided while building #1777. Two kinds of skill from here:

• Capability skills (branches, tickets, queue, logs): a SKILL.md and a command. Each does one thing.
• Routine skills (work-queue, later triage, plan, update): a SKILL.md only. A job that composes capabilities.

A routine names capabilities. A capability never names another skill. So routines cannot live in the tickets or queue package. The framework depends on the routines package and fires a routine by its slash command.

Rig check after posting: three Opus runs of /work-queue, about $0.27 and 35 seconds each: claim, edit, commit, no push, close the ticket, mark the entry done, stop. No lock left. The sentence "committed counts as published" comes from those runs: without it the agent left the ticket open.

---

Q6.2 When a tick fires

Story. Auto PM is on, the queue is empty all Monday. Today that costs nothing: the sweep reads the queue file and starts no agent. After this step the daemon reads no queue. Every start that finds nothing is an empty run: $0.18 on Opus, $0.11 on Sonnet, measured. Tuesday someone on another machine queues three entries. The daemon should notice soon and drain all three.

Options.

• A. Blind every ten minutes, today's cadence. An idle day is 144 empty runs, about $26 per project.
• B. Blind every hour. About $4 per idle day, and up to an hour before Tuesday's entries are seen.
• C. The framework keeps reading the queue for free. That keeps the queue library and the name queue in the daemon.
• D. Fire when the data branch moved. The daemon already pulls agent-data every 30 seconds. It remembers the branch head. A tick fires when the head changed since the last run ended, by a commit the daemon did not write itself. Tuesday's entries move the branch, the tick fires within a minute. The agent's claim, close and done are commits too, so the branch moved during the run, and the daemon fires again as the run ends. The chain drains the queue by itself. An empty run writes nothing, and the chain stops. One heartbeat tick a day as a belt. The daemon reads git only.

👤 I picked: D. Free when idle, quick when work appears. The quota gate, the cooldown and the concurrency cap stay as they are. The rotation, which refills the queue, fires after an empty run instead of after an empty read: same meaning, no queue read.

---

Q6.3 The two calls that stay

Story. Two moments have no agent: before the run, when the checkout is made, and after it, when the run is recorded. They stay framework code.

• Checkout before. In: the project path, the agent id. Out: the worktree, the branch agent-<id>, AGENT_ID in the environment as the framework's own constant. Gone: the four skill directories on PATH and the three skill symlinks in every checkout. After step 1 the SKILL.md files are tracked in the project and npx tickets resolves from the project's own dependencies, so a checkout has the skills by being a checkout.
• Record after. In: the run's meta and event log, read from the worktree. Out: one commit on agent-data, card and diary. Unchanged, except the card's ticket field: the daemon learned it from the queue read. It goes empty. The dashboard's "implementing this ticket" lane comes back in the dashboard half from the lock file, whose holder is the agent id (Q3).

Options for what they import.

• A. Two package imports remain: the checkout from the branches package, the record write from the logs package. Everything about tickets and queue leaves the daemon.
• B. Zero imports. The checkout is plain git; the record is a write to the data branch through the shared branch library. The logs skill becomes read-only in code, as its SKILL.md already says. The branches package's library shrinks to what its command needs.
• C. A logs record and a branches checkout command the framework runs by name. Two skill names in the daemon again.

👤 I picked: A now, B at step 4 when branches is done. The PR body names the two imports that remain.

---

Q6.4 Locks a stalled agent leaves

Story. The agent claims a ticket, then stops without closing or releasing: the API dropped it, or it stopped to ask a question nobody answers, as happened three times in sixteen runs, all in prompts without the rules. The lock stays and every later agent skips that ticket. Today the daemon frees the one claim it minted itself. After this step it claims nothing.

Options.

• A. A rule in the routine: "before you stop, release any claim you still hold unless you closed the ticket". Covers a stop by choice, not a killed process.
• B. A timeout in the tickets skill. Against the skill's own design: a person may hold a ticket for days.
• C. The daemon removes lock files naming its dead agents. Complete, but the daemon reads the tickets skill's lock format again.
• D. A person. The ticket page has a Release button, the lock is visible.

👤 I picked: A plus D. C is the only complete answer and exactly the coupling this step removes; a later conscious choice, not a default.

---

Q6.5 What goes

• The drain preset, its catalog entry, and the exact-text match that recognises a hand-fired drain.
• In auto-pm.ts: the drain job, the pinned prompt, the drain mode of the decision, the drain batch and its claims, the settle half that deletes the entry and frees the claim, the "ended dry" memory. About 28 of its 105 tests.
• In daemon-services.ts: the queue read, the drain claim and release, the promote, the ticket named on the start. Four tests.
• todo-loop.ts whole, the agent-side loop, with its 13 tests. And the merge-gate belt that parses the session's own TODO file with the queue parser; its own comment says built to be deleted.
• In daemon-runtime.ts: the PATH entries, the checkout symlinks, the AGENT_ID name imported from tickets.
• In cli.ts: the ticket start option, the (fix #N) in the PR title read from the ticket, the ticket event.
• The per-tick data sync calls the tickets sync then the queue sync; it becomes one pull of agent-data through the shared branch library. The root tickets link and the queue seed move to the skills' own setup.
• The routine list on the dashboard shows /work-queue in the drain's row; Run now fires it.

What remains, said in the PR body. The rotation and its tickets imports: update tickets, triage quick, triage consensual, plan tickets. The dashboard's tickets and queue imports, and the two package dependencies, the queue one only for the dashboard. And the scheduler, auto-pm.ts, still knows the routines by name: the list, its order, which one fans out, which two take a lock.

Options for scope.

• A. The drain only in this PR. The four rotation jobs follow, one PR each, each becoming a routine skill the same way. Plan tickets last: its fan-out claims tickets in the daemon and needs its own design.
• B. Every routine now, one PR, and the daemon imports nothing from tickets.

👤 I picked: A now, then B. This PR removes the drain. After it, another round: the four rotation jobs, one PR each, until the daemon imports nothing from tickets. Not both at once: the rig tested one prompt, the four rotation prompts are untested as skills, and one diff over most of auto-pm.ts would fail all at once.

---

Q6.6 Proof

Story. Before anyone looks at the PR, the PR's own daemon runs against the throwaway repository from the experiment, with the tickets, queue and logs SKILL.md tracked and three entries queued. Nobody touches it. The daemon fires /work-queue, the agent drains one entry, the daemon publishes, records, fires again. Three runs, then one empty run, then it stops. npx logs in a fresh clone lists the four runs; npx logs show <id> prints a diary.

Options.

• A. Tests only: the trigger and the chain with fakes. Proves the code, not a real agent under the daemon with bypassPermissions, which the experiment never ran.
• B. One real run: proves the agent under the daemon and the record. Cannot show the daemon firing again on its own.
• C. Three entries: shows both. About $1.20 on Opus.

👤 I picked: C, three entries. Unit tests come with the PR in every case. The transcripts and the logs output go into the PR body.

---

Order of work. The rig check of /work-queue headless first. Then one PR: the routine skill, the trigger and chain, the removal list, the two calls trimmed, the tests. Then the three-entry proof, then the PR is shown. Follow-ups, one PR each: the four rotation jobs as folders in the routines package; then each routine declares its own trigger in its SKILL.md front matter, so the scheduler knows no names; then the scheduler becomes a package, a library the daemon wires like agent-driver, so another runner can fire routines without the dashboard; branches to zero imports at step 4.