Second standalone skill: tickets and the agent queue (#1748)

.the-framework/LAYOUT

@@ -1,5 +1,6 @@
 framework-dir: .the-framework
-data-branch: agents-data
+tickets-branch: tickets
+logs-branch: agents-logs
 archive-dir: agents
 events-file: events.jsonl
 meta-file: agent.json

FEATURES-SPEC.md

@@ -89,28 +89,34 @@ 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 data branch cannot reach origin (push rejected, or no remote) 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 `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
 
 ## 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)
+- 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
 - Sorting and group-by-project toggle
 - The whole filter view mirrored to the URL so it can be shared
 - 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
+- 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 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
 - Select tickets row by row (a checkbox per row) — while any are selected, the heading's queue buttons act on just the selected tickets
 - Tickets carry a GitHub issue link, so merging closes the issue
+- A claimed ticket's row names the agent holding it — its session name, opening that agent's page — when the claim names one of the project's own agents; any other holder is shown as the claim writes it
 
 ## Handoff and what lands in git
 
 - 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 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
@@ -122,7 +128,7 @@ happens while nobody is at the keyboard.
 - Empty agents publish nothing
 - Handoff panel: push / open PR / merge, as buttons
 - A withheld merge is reported with its reason
-- Agent history archived on the `agents-data` branch under per-user directories — pushed the moment a session settles
+- Agent history archived on the `agents-logs` branch under per-user directories — pushed the moment a session settles
 - Post-merge quality follow-ups queued (maintainability / security)
 - Knowledge folded back into `DECISIONS.md` / `FACTS.md` / `INSIGHTS.md` at merge
 
@@ -134,13 +140,13 @@ happens while nobody is at the keyboard.
 - Every stand-down reported with its reason ("it is a setting, not a bug"); a stand-down at the concurrency cap, or a fan-out that came out short, names the runs holding the slots
 - Concurrency cap: how many unattended agents per project
 - Fan-out planning: several agents, one ticket each
-- Cross-machine ticket claims so two agents never double-work; a claim whose agent ended with nothing to hand off is freed by the daemon
+- Cross-machine ticket claims so two agents never double-work: a claim names the agent that holds it by its id, which the daemon mints before writing the claim and starts the agent with — so the dashboard names the holder's session on the ticket's row and opens that agent's page from it; a claim whose agent ended with nothing to hand off is freed by the daemon
 - CI watch: merge a PR once its checks pass
 - CI watch: one fix agent per red head commit, max two attempts
 - Reclaim the checkout of an agent whose work is on the remote — never by publishing what a `handoff: local` agent refused to
 - An agent that committed nothing leaves no branch behind: its empty branch goes with its checkout, never pushed — and the run-id branch it started on goes too, once the branch it moved to holds everything the run-id branch did
 - A directory under `.branches/` that git does not know as a worktree is never committed, pushed, linked or deleted through — it is reported and left alone, so a leftover can never stand in for your own checkout
-- One triage at a time, across machines: a routine lock (`routines/<name>.lock.md` on the data branch) taken by the daemon before the run starts and released when it ends, whatever the ending; a held lock stands the routine down naming the machine holding it, with no agent spent; a lock left by a dead machine expires after four hours, and a daemon frees its own on boot
+- One triage at a time, across machines: a routine lock (`routines/<name>.lock.md` on the `agents-logs` branch) taken by the daemon before the run starts and released when it ends, whatever the ending; a held lock stands the routine down naming the machine holding it, with no agent spent; a lock left by a dead machine expires after four hours, and a daemon frees its own on boot
 - The agent drains its own TODO backlog, one entry per turn
 
 ## Spending
@@ -182,7 +188,7 @@ happens while nobody is at the keyboard.
 - Answer a cloud agent's question from the dashboard (typed back into claude.ai) — the same gate panel a local agent gets, multi-select and stop options included, listed with every other open question
 - Browser-bridge token setting
 - A cloud run's row follows the session's real branch and PR, with its armed draft PR opened when the session opens none
-- Another machine's runs on the shared data branch are told apart: their rows carry a glyph naming the machine that started them (the Overview's working-now card spells it out), and a run is listed once even when two checkouts share its archive
+- Another machine's runs on the shared `agents-logs` branch are told apart: their rows carry a glyph naming the machine that started them (the Overview's working-now card spells it out), and a run is listed once even when two checkouts share its archive
 
 ## Notifications
 

SPEC.md

@@ -1,9 +1,10 @@
 The Framework: autonomous AI programming. Humans make the important decisions; coding agents work the user's registered repos unattended and hand the result off as pull requests. The product never makes model calls of its own — it drives a coding-agent CLI the user already pays for (Claude Code or Codex) as a black box, on the user's own subscription.
 
-Five top-level pieces, one product:
+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/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, and the only one so far. The product depends on it; it depends on nothing of the product.
+- `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 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 skill-branches for the branch it stores everything on.
 - `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.
@@ -22,7 +23,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.
-- **Framework data on its own branch** - everything The Framework itself writes (tickets, the agent queue, agent archives) lives on the `agents-data` branch, so the default branch stays 100% code.
+- **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.
 
 ## Business logic
 
@@ -44,7 +45,7 @@ See `## User story`: the daemon keeps working while nobody is around, within the
 
 #### Business logic
 
-On a shared clock the daemon runs its background jobs: Auto PM works the agent queue down and refills it by triaging tickets and planning the ones without plans; the CI watch merges the framework's pull requests once their checks pass and starts a fix agent when checks go red; sweeps reclaim finished agents' checkouts (only what is already on the remote) and keep bookkeeping healthy, and a routine that must not run twice is guarded by a routine lock on the data branch. Each unattended start checks the quota boundary first.
+On a shared clock the daemon runs its background jobs: Auto PM works the agent queue down and refills it by triaging tickets and planning the ones without plans; the CI watch merges the framework's pull requests once their checks pass and starts a fix agent when checks go red; sweeps reclaim finished agents' checkouts (only what is already on the remote) and keep bookkeeping healthy, and a routine that must not run twice is guarded by a routine lock on the `agents-logs` branch. Each unattended start checks the quota boundary first.
 
 ## Before modifying/creating SPEC.md files
 

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/skill-branches clean && pnpm -C packages/agent-driver clean && pnpm -C packages/framework clean",
-    "test": "pnpm -C packages/skill-branches test && pnpm -C packages/agent-driver test && pnpm -C packages/framework test",
+    "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/skill-branches test && pnpm -C packages/skill-tickets 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",

packages/SPEC.md

@@ -1,12 +1,13 @@
 The deliverables The Framework ships, one directory each:
 
 - `framework/` — the product: the `framework` npm package (CLI, daemon, agent lifecycle, dashboard).
-- `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; nothing else does yet.
+- `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.
+- `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 skill-branches for the branch it keeps everything on.
 - `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 skill-branches 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 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.
 
 ## 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 data branch, 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 (the tickets and the queue are the `skill-tickets` 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.