The tickets, queue and logs skills are tracked files of gemstack

.agents/skills/logs/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: logs
+description: The record of every run agents made on this project — what was asked, on which ticket, where the work went, how it ended, what the agent said — where it lives, how to read it, and when to look back before you work.
+---
+
+# Agent logs
+
+Every run an agent made on this project leaves a record on the branch `agent-data`, never on a code branch; your checkout does not contain it. A run is two files under `agents/<who>/`: the card, `<id>.json` — what was asked, the ticket, the branch, the pull request, how it ended, what it cost — and the diary, `<id>.jsonl` — what the agent said along the way, its result.
+
+Read them with the `logs` command, a dependency of this repository (`@gemstack/skill-logs`), run as `npx logs`. When that fails for a missing `node_modules`, install with the lockfile's package manager (`npm install` for `package-lock.json`) and run it again. The command only reads: the program that ran an agent records its run, at its end. A refusal exits 1 with a line on stderr; a wrong command line exits 2 with the usage.
+
+## Read
+
+```
+npx logs [--ticket <file>] [--branch <name>] [--limit N]
+                                 the runs, newest first, as one JSON array of cards — the newest 20
+                                 unless --limit says otherwise; --ticket keeps the runs that worked
+                                 one ticket (its filename, or the path a queue entry links to);
+                                 --branch the runs on one branch
+npx logs show <id>               one run: its card, plus `diary`, the lines of what the agent
+                                 said, its result, how it ended, and what it cost
+```
+
+## Before you plan or work a ticket, read its runs
+
+```
+npx logs --ticket <file>
+```
+
+A ticket, or a queue entry that links one, may have been worked before. A `stopped` or `failed` run tells you what to avoid: `npx logs show <id>` for what that agent said before it ended. A `done` run with a `pr` means the work may already be there: read the pull request before doing it again. A run with no ticket is found by `--branch`, or in the list.
+
+## The card
+
+```json
+{
+  "id": "2026-09-08T18-14-30-111Z",
+  "startedAt": "2026-09-08T18:14:30.651Z",
+  "endedAt": "2026-09-08T18:15:40.433Z",
+  "status": "done",
+  "intent": "what the agent was asked to do",
+  "driver": "claude-code",
+  "model": "opus",
+  "branch": "agent-2026-09-08T18-14-30-111Z",
+  "pr": { "number": 1765, "url": "https://github.com/org/repo/pull/1765" },
+  "ticket": "tickets/2026-09-01_some-ticket.md",
+  "cost": 0.62
+}
+```
+
+`status` is `running`, `done`, `stopped` or `failed`. `cost` is in US dollars. Every field but `id`, `startedAt` and `status` is absent when unknown. The program that wrote the card may keep its own bookkeeping under one more key, `caller`; the command never prints it.
+
+## The diary
+
+One JSON object per line. Four kinds are the agent's, in the order they happened:
+
+```
+{"kind":"said","text":"…"}                       something the agent said
+{"kind":"result","text":"…"}                     the agent's final answer for a turn
+{"kind":"cost","usd":0.62}                       what a stretch of the run cost, in US dollars
+{"kind":"ended","status":"failed","detail":"…"}  how the run ended; detail when it did not end well
+```
+
+Any other kind of line is the writing program's own; `show` leaves it out.

.agents/skills/queue/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: queue
+description: Where the project's agent queue lives, how to read it and change it, and its format.
+---
+
+# The agent queue
+
+The agent queue (`TODO_AGENTS.md`) lives on the branch `agent-data`, never on a code branch; your checkout does not contain it. It lists every task agents will work on next, in the order they will be taken.
+
+Read and change it with the `queue` command, a dependency of this repository (`@gemstack/skill-queue`), run as `npx queue`. When that fails for a missing `node_modules`, install with the lockfile's package manager (`npm install` for `package-lock.json`) and run it again. Every change it makes is one commit pushed straight to the `agent-data` branch. A refusal exits 1 with a line on stderr; a wrong command line exits 2 with the usage.
+
+## Read
+
+```
+npx queue                        the open entries, in order of work, as one JSON array
+```
+
+## Change
+
+```
+npx queue add <text> [--priority N]
+                                 put an entry on the queue; --priority (0-10) places it in that
+                                 section; without it, the entry goes at the end of the file
+npx queue done <entry>           remove an entry: one quoted argument, exactly as `npx queue`
+                                 printed it; done means deleted
+```
+
+## Format
+
+```md
+## Priority 10 (critical — act immediately)
+
+...
+
+## Priority 9
+
+- [Succinct description](/link-for-more-details)
+- Or self-contained TODO item with complete description of what should be done
+
+...
+
+## Priority 0 (only if capacity)
+
+...
+```
+
+The queue lists *all* tasks AI will work on next, sorted by priority. Priority 10 is rarely used (e.g. critical production bugs) and is treated as the utmost priority. Within a priority, the first tasks have higher priority (they are the "next" tasks within that "priority queue"). A done entry is removed (`npx queue done`).

.agents/skills/tickets/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: tickets
+description: Where the project's tickets live, how to read and change them, how to claim a ticket so no two agents work the same one, how to queue one, and the formats.
+---
+
+# Tickets
+
+The tickets (`tickets/<DATE>_<SLUG>.md`, with their `.plan.md` and `.lock.md` siblings) live on the branch `agent-data`, never on a code branch. A `tickets` link at the repository root, if present, shows a possibly stale copy; never write there. The command reads fresh.
+
+Read and change them with the `tickets` command, a dependency of this repository (`@gemstack/skill-tickets`), run as `npx tickets`. When that fails for a missing `node_modules`, install with the lockfile's package manager (`npm install` for `package-lock.json`) and run it again. Every change it makes is one commit pushed straight to the `agent-data` branch. A refusal exits 1 with a line on stderr; a wrong command line exits 2 with the usage.
+
+## Read
+
+```
+npx tickets list                 every open ticket, as one JSON array: file, title, summary, priority, topics,
+                                 github, date, planned, effort, uncertainty, locked, lockedBy
+                                 (priority, topics, github, effort, uncertainty, locked, lockedBy
+                                 absent when unset)
+npx tickets show <file>          one ticket: its text, its plan, who holds it
+```
+
+## Change
+
+```
+npx tickets put <file>           write one file under tickets/ from stdin, the whole file, creating it if new;
+                                 empty stdin writes an empty file
+                                 (npx tickets put <file> < draft.md): a ticket or a plan
+npx tickets close <file>         once the work is done and published: remove the ticket with its plan
+                                 and lock; refused while someone else holds it; its queue entry, if any,
+                                 stays: `npx queue done` it
+```
+
+## Queue a ticket
+
+When the repository has the `queue` skill, a ticket goes on the agent queue as a link, its title as the label, at the ticket's own `Priority:` (5 when it has none):
+
+```
+npx queue add "[<title>](tickets/<file>)" --priority <N>
+```
+
+Once the work is done and published, `npx tickets close <file>` and `npx queue done` the entry.
+
+## Claim before you plan or work a ticket
+
+```
+npx tickets claim <file>         {"ok":true,"file":…,"holder":…} — the ticket is yours
+                                 {"ok":false,"reason":"claimed","holder":…,"file":…} — someone else's
+                                 (no holder when the lock's line does not parse): pick another; never remove
+                                 or overwrite their lock. A claim guards claim, close and release;
+                                 put overwrites whoever holds the ticket
+npx tickets release <file>       lift your own claim when the plan or the work is done, and before you
+                                 stop unless you closed it; nothing lifts it on a timeout
+```
+
+Every `<file>` above takes a ticket's filename (`2042-01-01_some-ticket.md`) or the `tickets/…` path a queue entry links to; `put` also takes that ticket's `.plan.md` name, and writes a plan for a ticket that does not exist, without complaint, invisible to `show`. You claim as `AGENT_ID` when it is set, else as your current branch (so a rename or a branch switch between claim and release changes who you are: release from the branch you claimed on, or the lock stays until a person edits the branch).
+
+## Formats
+
+### A ticket: `tickets/<DATE>_<SLUG>.md`
+
+DATE: yyyy-mm-dd. SLUG: a succinct kebab-case slug of the ticket title.
+
+```md
+Priority: 0-10 [optional, 10: critical — act immediately, 0: only if capacity]
+Topics: [list-of-topics] [optional]
+GitHub: [#42](https://github.com/org/repo/issues/42) [optional]
+
+# Ticket title
+
+## TLDR
+
+...
+
+## Why it matters
+
+...
+
+[optional: more info (any heading and format you want)]
+```
+
+`Priority:`, `Effort:` and `Uncertainty:` are bare whole numbers above the `# ` title; anything else reads as absent for queue placement and the scales, and a ticket with no readable `Priority:` queues at 5.
+
+### A claim: `tickets/<DATE>_<SLUG>.lock.md`
+
+Written by `npx tickets claim`, removed by `npx tickets release` or `npx tickets close`. One line: `CLAIMED: <holder>`.
+
+### A plan: `tickets/<DATE>_<SLUG>.plan.md`
+
+The plan for an existing ticket (`tickets/2042-01-01_some-ticket.md` → `tickets/2042-01-01_some-ticket.plan.md`).
+
+```md
+Effort: 0-10 [0: implementation is trivial, 10: implementation takes months]
+Uncertainty: 0-10 [0: implementation without meaningful alternatives, 10: highly uncertain how to implement]
+Outdated: yes [optional, only if the ticket was updated in a way that makes the plan outdated]
+
+# [Plan] Ticket title
+
+Single sentence describing this file's content.
+
+## TLDR [optional]
+
+Brief overview of this file's content.
+
+## Problems [optional]
+
+List of all significant aspects with low confidence on how to implement, with explanation why uncertain.
+
+## Solutions [optional]
+
+For each problem, list of ways to solve the problem (including meaningful shortcuts, for quicker implementation).
+
+## Considerations [optional]
+
+Exhaustive list of all significant aspects to be considered (including edge cases).
+
+## Implementation [optional]
+
+Concrete plan to implement the ticket.
+```
+
+Notes:
+- Covers both spiking (e.g. high-level research without implementation plan) and planning (e.g. concrete implementation proposal)
+- The `.plan.md` file can be modified multiple times over an extended period (e.g. a ticket requiring repeated human intervention, transitioning from spiking to concrete plan)
+- All sections are just proposals and optional: you can use any headings with any format
+- The uncertainty value:
+  - Gauges whether there are *significant* alternatives, minor variability such as syntax should be ignored
+  - Is used for evaluating whether human intervention is needed (0 => clearly no human intervention needed)
+- Example of how to gauge uncertainty and alternatives:
+  - List all aspects that need to be considered
+  - Give an uncertainty rating (0-10) to each aspect following this criteria: is there an obviously optimal way to implement it (0), or is it highly unclear whether it can be implemented in a better way (10)?
+  - Explore and suggest alternatives for each aspect with a low rating

.claude/skills/logs

@@ -0,0 +1 @@
+../../.agents/skills/logs

.claude/skills/queue

@@ -0,0 +1 @@
+../../.agents/skills/queue

.claude/skills/tickets

@@ -0,0 +1 @@
+../../.agents/skills/tickets