The queue as its own skill: @gemstack/skill-queue, command queue

FEATURES-SPEC.md

@@ -89,11 +89,11 @@ happens while nobody is at the keyboard.
 - Hottest tickets
 - Projects sidebar
 - A project whose directory was renamed or deleted leaves the sidebar on the next refresh, and comes back when the directory does; the registration is kept
-- Project errors: a project whose bookkeeping branches cannot reach origin (push rejected, or no remote) — the `tickets` branch or the `agents-logs` branch — is flagged with a red dot in the sidebar and a banner on its page, until a sync converges
+- Project errors: a project whose bookkeeping branches cannot reach origin (push rejected, or no remote) — the `agent-data` branch or the `agents-logs` branch — is flagged with a red dot in the sidebar and a banner on its page, until a sync converges
 
 ## Tickets
 
-- Tickets and the queue live on the `tickets` branch, never on a code branch; every change is one commit pushed straight to it, so what one agent writes the next one sees without waiting for a pull request (#1748)
+- Tickets and the queue live on the `agent-data` branch, never on a code branch; every change is one commit pushed straight to it, so what one agent writes the next one sees without waiting for a pull request (#1748)
 - A `tickets` link at your repository's root shows that branch's tickets from your own checkout, made only where nothing of yours sits at that path and kept out of git
 - Cross-project ticket list
 - Faceted filtering: text, priority/effort/uncertainty as buckets *or* ranges, topics, planning stage, project
@@ -102,7 +102,7 @@ happens while nobody is at the keyboard.
 - Ticket detail page
 - A plan page when a plan exists; a button to start an agent writing one when it doesn't
 - "Resume agent" on the plan page: opens the session of the agent that wrote the plan, so the conversation continues with the plan already in its context
-- Queue a ticket into the AI queue — the entry is written onto the `tickets` branch, linked to the ticket and filed under the ticket's priority
+- Queue a ticket into the AI queue — the entry is written onto the `agent-data` branch, linked to the ticket and filed under the ticket's priority
 - Queue every ticket the filters show into the AI queue, in one click from the page heading
 - Queue a plan for every unplanned ticket the filters show, from the same heading
 - A ticket whose work is done leaves the branch with its plan and its claim; a queue entry whose work is done is taken off the queue — done means deleted, never ticked off
@@ -115,8 +115,10 @@ happens while nobody is at the keyboard.
 - Every agent gets its own git worktree under `.branches/` and its own branch (`agent-<id>`), created before it starts; your checkout is never touched
 - The `branches` skill: every checkout The Framework creates carries the `@gemstack/skill-branches` package's `SKILL.md` where the agent's harness looks for skills (`.claude/skills/branches` for Claude Code, `.agents/skills/branches` for Codex), and the system prompt tells the agent to use it — that checkout is your whole workspace, name the session with the command, commit as you go, leave a clean tree, never push or open the PR yourself; an agent anywhere else (a terminal run in your checkout, an Actions runner, a cloud session) is told to branch with git itself
 - `branches` on every agent's PATH — the skill's command line: `name <name>` renames the agent's branch to `agent-<name>` and prints the name it got (suffixed when taken); `status` says whether the tree is clean and the branch on the remote; `create`, `attach`, `list`, `remove`, `prune` are the same operations the dashboard runs
-- The `tickets` skill: every checkout The Framework creates carries the `@gemstack/skill-tickets` package's `SKILL.md` beside the `branches` skill, where the agent's harness looks for skills (`.claude/skills/tickets` for Claude Code, `.agents/skills/tickets` for Codex), and the presets tell the agent to use it — the tickets and the agent queue are on the `tickets` branch, read and changed with the command, claimed before they are planned or worked; an agent anywhere else (a terminal run in your checkout, an Actions runner, a cloud session) is told instead how to do the same with git, temporarily, until the skill is committed into the repository (#1748)
-- `tickets` on every agent's PATH — the skill's command line: `list` and `show <file>` read the tickets with their plans and their holders, `queue` reads the queue in the order it is worked, `queue add <text>` puts an entry on it at a priority and linked to a ticket, `queue done <text>` takes an entry off, `put <file>` writes a ticket, a plan or the import stamp, `close <file>` removes a ticket with its plan and claim, `claim <file>` and `release <file>` are the claim; every one of them is one commit pushed to the `tickets` branch
+- The `tickets` skill: every checkout The Framework creates carries the `@gemstack/skill-tickets` package's `SKILL.md` beside the `branches` skill, where the agent's harness looks for skills (`.claude/skills/tickets` for Claude Code, `.agents/skills/tickets` for Codex), and the presets tell the agent to use it — the tickets are on the `agent-data` branch, read and changed with the command, claimed before they are planned or worked, queued as a link through the `queue` skill; an agent anywhere else (a terminal run in your checkout, an Actions runner, a cloud session) is told instead how to do the same with git, temporarily, until the skill is committed into the repository (#1748)
+- `tickets` on every agent's PATH — the skill's command line: `list` and `show <file>` read the tickets with their plans and their holders, `put <file>` writes a ticket, a plan or the import stamp, `close <file>` removes a ticket with its plan and claim, `claim <file>` and `release <file>` are the claim; every one of them is one commit pushed to the `agent-data` branch
+- The `queue` skill: every checkout The Framework creates carries the `@gemstack/skill-queue` package's `SKILL.md` beside the other two (`.claude/skills/queue`, `.agents/skills/queue`), and the presets tell the agent to use it — the agent queue is on the `agent-data` branch, read and changed with the command; an agent anywhere else gets the same git bridge as for the tickets (#1750)
+- `queue` on every agent's PATH — the skill's command line: `queue` reads the queue in the order it is worked, `queue add <text> [--priority N]` puts an entry on it in its priority section, `queue done <text>` takes an entry off; every one of them is one commit pushed to the `agent-data` branch
 - The session name is the branch: an agent is labelled by its `agent-<name>` branch, read from git after every turn — nothing to signal, nothing to record twice
 - Dependency directories shared from the parent checkout instead of reinstalled — as directories of links, so an agent's own install stays in its checkout and never rewrites or purges the parent's
 - A checkout whose work is not on the remote is kept — and a publish-nothing (`handoff: local`) agent's is kept until you publish or delete it

SPEC.md

@@ -5,7 +5,8 @@ Six top-level pieces, one product:
 - `packages/framework` — the product itself, published as the npm package `framework`: one CLI (`the-framework`) that runs a foreground daemon, the agent lifecycle it orchestrates, and the browser dashboard it serves — the product's only user interface.
 - `packages/agent-data` — a branch of the project's repository used as a file store, published as `@gemstack/agent-data`: the shared `agent-data` branch every skill keeps its files on, written through one sync → commit → push cycle that re-applies the change when the push loses a race, from a long-lived process through a persistent checkout or one-shot from any clone. A library, not a skill — read by code, never by an agent. Every skill depends on it, and so does the product; it depends on nothing.
 - `packages/skill-branches` — the git conventions and operations behind an agent's own checkout, as an API, as the `branches` command every agent the daemon starts on its machine gets on its PATH, and as the skill (`SKILL.md`) every agent's built-in system prompt carries, published as `@gemstack/skill-branches`: the first of the skills the product is being split into. The product depends on it; it depends on agent-data and on nothing of the product.
-- `packages/skill-tickets` — the project's tickets and its agent queue, on the `tickets` branch of the project's own repository, published as `@gemstack/skill-tickets`: the same three faces — an API, the `tickets` command every agent the daemon starts gets on its PATH, and the skill (`SKILL.md`) every such agent finds in its checkout — over reading tickets, writing them, claiming one so two agents never work the same, and keeping the queue. The second of the skills. The product depends on it, and it depends on agent-data for the branch it stores everything on.
+- `packages/skill-tickets` — the project's tickets, on the `agent-data` branch of the project's own repository, published as `@gemstack/skill-tickets`: the same three faces — an API, the `tickets` command every agent the daemon starts gets on its PATH, and the skill (`SKILL.md`) every such agent finds in its checkout — over reading tickets, writing them, and claiming one so two agents never work the same. The second of the skills. The product depends on it, and it depends on agent-data for the branch it stores everything on.
+- `packages/skill-queue` — the project's agent queue, on the same `agent-data` branch, published as `@gemstack/skill-queue`: the same three faces — an API, the `queue` command on every agent's PATH, and the skill (`SKILL.md`) — over reading the queue, adding an entry at a priority, and taking one off. The third of the skills. The product depends on it, and it depends on agent-data only.
 - `packages/agent-driver` — the driver seam as its own package, published as `agent-driver`: one contract for driving a coding-agent CLI as a black box — a session in a directory, one full turn per prompt, a stream of what the agent did — and the implementations for Claude Code and Codex on this device, Claude Code on a GitHub Actions runner, and a scripted fake. The product depends on it and adds the one implementation that needs the product, the hand-off to a Claude Code cloud session; it depends on nothing of the product.
 - `packages/chrome-extension` — the Claude web bridge, a companion Chrome extension: when an agent's task was handed to a Claude Code cloud session on claude.ai, it carries the question that session is parked on into the local dashboard, and types the answer picked there back into the session.
 - `packages/the-framework.ai` — the marketing website at https://the-framework.ai.
@@ -24,7 +25,7 @@ Every user-facing feature is enumerated in `FEATURES-SPEC.md`.
 - **The agent is the unit of work** - one task, in its own git worktree on its own branch, streaming everything it does as events; finished work is pushed and leaves as a pull request.
 - **Black-box driving** - the framework prompts the wrapped coding-agent CLI, lets the CLI's own loop run a full turn, and learns everything from the turn's final message: the session name the agent invented, the questions it stops to ask, and the ready-for-merge signal.
 - **Autonomy bounded by the account's own quota** - unattended work runs only while the account is under its pro-rated quota boundary; work a human asks for is never blocked, and a running agent is never interrupted over quota.
-- **Nothing bookkeeping-shaped on a code branch** - the tickets and the agent queue live on the `tickets` branch, which is the `tickets` skill's; The Framework's own records of its runs — the agent archives, the routine locks — live on the `agents-logs` branch. The default branch stays 100% code.
+- **Nothing bookkeeping-shaped on a code branch** - the tickets and the agent queue live on the `agent-data` branch, the `tickets` skill's and the `queue` skill's; The Framework's own records of its runs — the agent archives, the routine locks — live on the `agents-logs` branch. The default branch stays 100% code.
 
 ## Business logic
 

package.json

@@ -11,8 +11,8 @@
     "preview": "pnpm -C packages/framework preview",
     "dev": "pnpm -C packages/framework dev",
     "typecheck": "pnpm -C packages/framework typecheck && pnpm -C packages/the-framework.ai typecheck",
-    "clean": "pnpm -C packages/agent-data clean && pnpm -C packages/skill-branches clean && pnpm -C packages/skill-tickets clean && pnpm -C packages/agent-driver clean && pnpm -C packages/framework clean",
-    "test": "pnpm -C packages/agent-data test && pnpm -C packages/skill-branches test && pnpm -C packages/skill-tickets test && pnpm -C packages/agent-driver test && pnpm -C packages/framework test",
+    "clean": "pnpm -C packages/agent-data clean && pnpm -C packages/skill-branches clean && pnpm -C packages/skill-tickets clean && pnpm -C packages/skill-queue clean && pnpm -C packages/agent-driver clean && pnpm -C packages/framework clean",
+    "test": "pnpm -C packages/agent-data test && pnpm -C packages/skill-branches test && pnpm -C packages/skill-tickets test && pnpm -C packages/skill-queue test && pnpm -C packages/agent-driver test && pnpm -C packages/framework test",
     "========= Website": "",
     "// Develop website https://the-framework.ai locally": "",
     "website": "cd packages/the-framework.ai/ && pnpm run dev",
@@ -24,6 +24,7 @@
   "devDependencies": {
     "@gemstack/skill-branches": "workspace:*",
     "@gemstack/skill-tickets": "workspace:*",
+    "@gemstack/skill-queue": "workspace:*",
     "typescript": "^7.0.2"
   }
 }

packages/SPEC.md

@@ -3,12 +3,13 @@ The deliverables The Framework ships, one directory each:
 - `framework/` — the product: the `framework` npm package (CLI, daemon, agent lifecycle, dashboard).
 - `agent-data/` — the `@gemstack/agent-data` npm package: a branch of the project's repository used as a file store — the shared `agent-data` branch every skill keeps its files on — with the git runner and the exclude rule it is built on. A library, not a skill: read by code, never by an agent, so no `SKILL.md` and no command. Every skill depends on it; no skill depends on another (#1750).
 - `skill-branches/` — the `@gemstack/skill-branches` npm package: the git conventions and operations behind an agent's own checkout, with the skill's instructions (`SKILL.md`) and the `branches` command an agent follows them with: the first skill of the skills-plus architecture (#1725). The product depends on it, and so does the skill-tickets package; it depends on agent-data.
-- `skill-tickets/` — the `@gemstack/skill-tickets` npm package: the project's tickets and its agent queue on the `tickets` branch of its own repository, with the skill's instructions (`SKILL.md`) and the `tickets` command an agent reads, writes and claims them with: the second skill of the skills-plus architecture (#1748). The product depends on it; it depends on agent-data for the branch it keeps everything on, and on skill-branches for who an agent is.
+- `skill-tickets/` — the `@gemstack/skill-tickets` npm package: the project's tickets on the `agent-data` branch of its own repository, with the skill's instructions (`SKILL.md`) and the `tickets` command an agent reads, writes and claims them with: the second skill of the skills-plus architecture (#1748). The product depends on it; it depends on agent-data for the branch it keeps everything on.
+- `skill-queue/` — the `@gemstack/skill-queue` npm package: the project's agent queue on the `agent-data` branch of its own repository, with the skill's instructions (`SKILL.md`) and the `queue` command an agent reads and changes it with: the third skill, split out of skill-tickets (#1750). The product depends on it; it depends on agent-data only.
 - `agent-driver/` — the `agent-driver` npm package: the driver seam — start a coding-agent CLI in a directory, prompt it for one full turn, stream what it does, resume it later — with the Claude Code, Codex, GitHub Actions and fake implementations. The product depends on it and adds its own cloud-session implementation behind the same contract.
 - `chrome-extension/` — the Claude web bridge, a companion Chrome extension that connects Claude Code cloud sessions on claude.ai back to the local dashboard.
 - `the-framework.ai/` — the marketing website.
 
-The product depends on the agent-data, skill-branches, skill-tickets and agent-driver packages in code; the extension and the website depend on the product only in what they present. See the root `SPEC.md` for how they relate as a product.
+The product depends on the agent-data, skill-branches, skill-tickets, skill-queue and agent-driver packages in code; the extension and the website depend on the product only in what they present. See the root `SPEC.md` for how they relate as a product.
 
 ## Before modifying/creating SPEC.md files
 

packages/framework/SPEC.md

@@ -2,7 +2,7 @@ The product: the `framework` npm package. One CLI, `the-framework`, runs a foreg
 
 How the package's pieces relate:
 
-- `src/` — everything that runs in Node: the CLI, the daemon, the agent lifecycle (checkouts through the `skill-branches` package, gates, handoff), the drivers (the agent-driver package's, plus the product's own hand-off to a Claude Code cloud session), the `agents-logs` branch its own records live on (a branch used as a file store through the `@gemstack/agent-data` package; the tickets and the queue are the `skill-tickets` package's), autonomy (Auto PM, sweeps, CI watch), and the server side of the dashboard.
+- `src/` — everything that runs in Node: the CLI, the daemon, the agent lifecycle (checkouts through the `skill-branches` package, gates, handoff), the drivers (the agent-driver package's, plus the product's own hand-off to a Claude Code cloud session), the `agents-logs` branch its own records live on (a branch used as a file store through the `@gemstack/agent-data` package; the tickets are the `skill-tickets` package's and the queue the `skill-queue` package's), autonomy (Auto PM, sweeps, CI watch), and the server side of the dashboard.
 - `dashboard/` — the browser app the daemon serves: a single-page app that is a pure projection of the files the daemon writes, reading over `POST /_rpc/<name>` and a live event stream, and steering agents back through the same daemon.
 - `prompts/` — every prompt The Framework sends an agent, as markdown: the built-in system prompt, the protocols agents answer through, and the presets. The markdown is the only source of truth for agent-facing text.
 - `scripts/` — the build steps that compile the prompts into importable strings and run the package's test suites.

packages/framework/dashboard/components/AiQueue.tsx

@@ -30,13 +30,13 @@ import { StartAgentButton } from './StartAgentButton.js'
 
 /**
  * The prompt the play button starts an agent with: the drain preset's vocabulary (work one entry
- * through the `tickets` skill, then take it off the queue; do not start any other entry) narrowed
+ * through the `queue` skill, then take it off the queue; do not start any other entry) narrowed
  * from "the FIRST open entry" to the one entry the row shows. The raw `TODO_AGENTS.md` line, not
  * the pretty label: the agent must name exactly this entry to take it off, and the line's link is
  * how it opens the ticket (#1164). Exported so the test asserts against this and not a copy.
  */
 export function workOnEntryPrompt(entry: string): string {
-  return `Use the \`tickets\` skill: work on this one open queue entry only, and when the work is done and published run \`tickets queue done "<the entry>"\`. Do not start any other entry. The entry:\n\n${entry}`
+  return `Use the \`queue\` skill: work on this one open queue entry only, and when the work is done and published run \`queue done "<the entry>"\`. Do not start any other entry. The entry:\n\n${entry}`
 }
 
 /** How many agents the fan-out button starts until its count says otherwise. */