diff --git a/.agents/skills/logs/SKILL.md b/.agents/skills/logs/SKILL.md new file mode 100644 index 000000000..8f4d43752 --- /dev/null +++ b/.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//`: the card, `.json` — what was asked, the ticket, the branch, the pull request, how it ended, what it cost — and the diary, `.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 ] [--branch ] [--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 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 +``` + +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 ` 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. diff --git a/.agents/skills/queue/SKILL.md b/.agents/skills/queue/SKILL.md new file mode 100644 index 000000000..48ef668c0 --- /dev/null +++ b/.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 [--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 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`). diff --git a/.agents/skills/tickets/SKILL.md b/.agents/skills/tickets/SKILL.md new file mode 100644 index 000000000..b45c41d49 --- /dev/null +++ b/.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/_.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 one ticket: its text, its plan, who holds it +``` + +## Change + +``` +npx tickets put write one file under tickets/ from stdin, the whole file, creating it if new; + empty stdin writes an empty file + (npx tickets put < draft.md): a ticket or a plan +npx tickets close 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 "[](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 diff --git a/.claude/skills/logs b/.claude/skills/logs new file mode 120000 index 000000000..cda3cd58f --- /dev/null +++ b/.claude/skills/logs @@ -0,0 +1 @@ +../../.agents/skills/logs \ No newline at end of file diff --git a/.claude/skills/queue b/.claude/skills/queue new file mode 120000 index 000000000..8b8e1fb5e --- /dev/null +++ b/.claude/skills/queue @@ -0,0 +1 @@ +../../.agents/skills/queue \ No newline at end of file diff --git a/.claude/skills/tickets b/.claude/skills/tickets new file mode 120000 index 000000000..e119b4c59 --- /dev/null +++ b/.claude/skills/tickets @@ -0,0 +1 @@ +../../.agents/skills/tickets \ No newline at end of file