Tares

Record a check you ran on a ticket: the exact `command`, what it showed (`result`), the `commit` it ran on, and, for a test you added, `broke_test`: the test you saw fail when you broke the code it covers (then pass again once restored). One line goes into the Checks part of the ticket's working doc; the rest of the doc is untouched. Record each check after you run it, never one you did not run: the reviewer compares them with your session. Several checks you ran back to back go in one call: `more` takes the others as [{command, result, commit, broke_test}, ...].

Keep one grant: `words` are the person's own words, quoted exactly as they said them (never your summary); Tares adds today's date. `scope` is `all` (every project) or `project` (this project only, name it in `project`). Only the person's own session or the orchestrator, relaying the person verbatim, may add one.

Add one line to a doc every project shares: `doc` is `agents` (the AGENTS.md for all projects: a rule every session should follow, e.g. "always build on a branch, never commit to main") or `memory` (a fact or preference that holds across projects, e.g. "the household uses euros"). Ask the user first, and add only what holds beyond this project; a project's own rules go in its own AGENTS.md. A line already there is not added twice.

Give a ticket (T3, its id, or its Linear or GitHub identifier such as GH-12) to the station that works it, by the station's name (for example shop-build-m1). Only the orchestrator, or the person's own session, assigns. A ticket with no stage yet starts at todo.

Record an assumption you made so the work does not block: the `question` the plan did not answer, the `choice` you made, `why`, the `tickets` it touches (T3, ...), and who it `affects`. Returns its number (A1, A2, ...): tell the orchestrator that number in one line and carry on. The orchestrator confirms open assumptions with the person once per milestone. Never use this for what must go to the person directly (prod deploys, secrets, money, new contacts, deleting data).

Link a working doc (write it first with write_doc, kind `working`) to a ticket, by the ticket's Tares id, Linear identifier or GitHub identifier (GH-12). Works for tickets in Linear or GitHub too: the working doc stays in Tares.

Start every ticket here, and again after a revive: one read with where the ticket stands (stage, holder, PR, verdict), its working doc, its milestone and acceptance checks, the state of what it depends on, the project's AGENTS.md (it wins over the generic flow) and the shared one, open assumptions and desk questions on it, and where you left off (checks recorded, Codex, earlier review rounds, the crew's latest messages). `start=True` also moves a ticket that has not been started to doing, so starting a ticket is this one call; a ticket already in review, changes, blocked or merged keeps its stage.

Describe one catalog entry in full: schema (event types + typed fields, inferred from stored events), freshness, lineage, and sample records. Handles look like source:logs or trigger:error_spike. Use this to discover label names before creating a trigger or reading an unfamiliar source.

List available sources, triggers and projects.

Create an empty Tares project for a piece of work you are about to spec, and tie this session to it. `name` is the project's handle (unique on Tares); `goal` is one line saying what it is for. Then write its docs with write_doc and its tickets (write_ticket, or link_linear_project or link_github_issues when the tickets live in Linear or GitHub). Returns the project's id and name.

Create a data source so Tares starts ingesting it immediately (no restart). `config` is the connector's config (see list_connectors / discover_source); push connectors ignore `poll`. `project` is the project id the source joins (default: the default project); other projects can use it too. Returns {ok, name} or an error detail. After creating, use list_sources to watch it ingest and catalog_describe("source:<name>") to see its labels.

Create a trigger: a condition Tares evaluates continuously over one or more sources; when it trips, subscribed agents are woken with the correlated timeline. `sources` names the sources it watches (at least one). `filters` [{field, op, value}] (ops: eq, neq, in (a list), contains, gt, lt, gte, lte) narrows them. `key_field` is the entity label (default: the primary label of the first source). `condition` is {aggregate: any|avg|count|max|min|sum, field: numeric label to aggregate (omit for count), predicate: e.g. '> 1.0' / '>= 5' / '== 0', window: detection window e.g. '1m'}. `emit` is {kind: what a firing is called e.g. error_spike, context_window: timeline the woken agent receives e.g. '15m'}. `project` is the project id the trigger belongs to (default: the default project); its sources join that project. `description` (optional) says in one plain line what wakes it, phrased to follow "When", e.g. "an alert fires in the checkout service"; the project page uses it instead of the rule's own wording (at most 160 characters, one line). catalog_describe a source to confirm its labels first. Wire agents to it with subscribe().

The projects handed to the crew, oldest first: each with its repos (`path` on this machine, GitHub `name`) and the tickets and open PRs of each, the autonomy it was handed over at when stricter than the crew's, tickets done of all, and the milestone it is on. The orchestrator works from this list: a project here with no builder is one to start. Projects the person said are done are not in it (`finished` lists them apart). `releasing` lists the projects the person took back from the crew (`tares factory session <project>`) that still wait for the orchestrator to stop their builders (`holders`) and call release_project; they are no longer the crew's to work on.

Record what the person said about an assumption (A3): `state` kept or overturned (or open again), `words` the person's own words, required when overturned. Only the orchestrator, or the person's own session, may. Answering a batch on the desk does this for you.

Put a question for the person on the desk (one desk for every project; numbered D1, D2...): the question, your recommendation and why, the options, two lines of context, what it blocks (tickets, stations), whether it blocks, and who asked. For the batch of assumptions to confirm once per milestone, pass their numbers in `assumptions`. Then ask the person in your session, one item at a time, blockers first. Only the orchestrator writes the desk. A permission a station was refused: `station` its name and `command` the exact command it was refused, verbatim as it reported it; `recommendation` the grant in plain words (which station may run what, where). The person can allow it with one click in the Tares console; the crew's watch then restarts that station with the grant in its settings.

Record the person's answer to a desk item (D3). `words` is their reply exactly as they typed it in your session, never your summary: Tares checks it against what they typed and says whether it matches. A reply of one letter ("B") is passed as is: Tares maps it to that option. `choice` the option it picks. `standing` only when they said it holds from now on ("always fine for staging"); with `scope` all it holds for every project. A standing answer that matches becomes a grant. For an assumption batch: `kept` the assumptions they keep, `overturned` {A3: their words}; open a follow-up ticket for each overturned one.

The desk: open questions (or `answered`, `withdrawn`) across every project, blockers first, then oldest. Ask the first one.

Take a question off the desk when it no longer needs the person (answered by events, or no longer relevant), saying why.

Scan the local Docker environment and get a list of proposed sources (one per container's logs, plus a detected Prometheus). Each item's `config` is ready to pass to create_source.

Introspect an upstream and get a proposed source config — no commitment. Works for connectors that can introspect: e.g. prometheus given {"url": "http://..."}, or github given {"repo": "owner/name"}. The returned `proposed_config` can be passed straight to create_source. (Use list_connectors to see which connectors support discovery.)

Mark a project done, once the person said so. Ask them first on the desk ("Is <project> done? Tickets all merged, milestones checked."), record their answer with desk_answer, then call this with that item (`decision`, D<n>). Tares keeps their words, sets the project done and takes it off the crew's work list; a later hand-over opens it again. Refused while a ticket is open. Only the orchestrator may. Returns how many projects the crew still holds: with none left, ask the person on the desk whether to stop the crew (`tares factory crew down` in their terminal). A person's own session (`tares factory session`, not a crew station) passes `words` instead: what the person typed when they said it is done, copied exactly. That also finishes a project the crew never held.

The tares-factory crew's settings for every project: `autonomy` (L3-review: the person approves each merge; L4-ship: a builder merges after the reviewer's pass and green CI), `releaser` (whether the crew runs a releaser; without one a ticket ends at merged), `release_profile`, `prod_pattern` (what counts as prod), `challenger` (builders run the Codex challenger), `builders_max`, `claude_update` (whether the watch moves stations onto a new Claude Code; on unless false). Unset ones are null: ask the person, one at a time, with a recommendation. `kit.frozen` is null while the crew follows the plugin checkout, else when and by whom the person froze it (`tares factory crew freeze`): the watch then moves no station onto a newer kit. Read only here; the person freezes and unfreezes from the CLI. `idle_wake` (null or false: off): when true the factory's watch wakes you with a message when you have work and holds your liveness tick, so you arm no schedule of your own. `pace` (null or false: off): when true the watch slows the crew before the plan's limits: no new builders, a 45-minute tick, and builders wait near the 5-hour limit; its notes to you say what to do.

One of the project's docs, with its markdown body.

The instructions of one of the project's skills, as markdown.

One station with its current session and the earlier sessions that played it.

One ticket, by its Tares id, its number (T3), its Linear identifier (for example ENG-12) or its GitHub identifier (for example GH-12), with the body of its working doc, who holds it and where it stands, its pull request as GitHub has it (head, CI, the reviewer's verdict, merged), its history, and the crew's messages about it: everything you need to work on it.

Hand a specced project to the crew: Tares records it with every repo it spans, and the orchestrator picks it up from Tares on its next tick. `repos` is one {path, name} per repo: `path` the absolute folder it is checked out in on this machine, `name` its GitHub repo (owner/name), the repo that holds the plan first. A later call adds repos, never replaces them. `autonomy` only when the person wants this project stricter than the crew (L3-review: every merge waits for their yes). `repo` (one path) is the older form. Then send `crew-orchestrator` a `[TF:SHIP]` message with SendMessage so it starts now rather than on its tick. If no crew is running (list_crew shows no orchestrator working, idle or waiting), tell the person to run `tares factory crew up` first.

Join a project: Tares POSTs every firing of every trigger in the project to `url` (your agent's webhook), the triggers added later included. The body carries dispatch_id, trigger, project, key (the entity), fired_at, payload (the timeline) and run_ids (the Tares agents it woke). Returns the subscription id.

Tie the project to the GitHub repo (owner/name or URL) whose issues carrying `issue_label` are its tickets (default `tares:<project name>`). Tares then keeps its ticket list in sync (about once a minute): the GitHub milestones its issues sit in become the project's milestones, "blocked by" becomes depends_on, and status follows the issues. Uses the GitHub credentials stored on Tares (Settings, GitHub); one of them must read the repo's issues. Create and change the issues with `gh`. Returns the tickets found.

Tie the project to the Linear project its tickets live in, by the Linear project's id, URL or name. Tares then keeps its ticket list in sync with Linear (about once a minute) and runs a first sync now. Needs Linear connected on Tares (Settings). Returns the tickets found.

The project's assumptions, A1 first: the question, the choice, why, the tickets, and the state (open: not yet confirmed; kept; overturned, with the person's words). `state` narrows the list.

List the connector types you can create a source with, each with its config fields, mode (poll | push), and whether it supports discovery. Read this first to learn what you can ingest and how to configure it.

The crew as Tares sees it: one row per station (orchestrator, reviewer, releaser, builders, helpers) with its state (working, idle, waiting, quiet, ended), the project it is on, when it last spoke, the stations it started, and how many earlier sessions played it.

What the person decided on the project, newest first: the question, their words, the choice, whether it stands from now on and whether it matched what they typed (`via` "console": a permission they allowed in the console; the watch restarts that station with it). Follow them; relay them to stations by quoting the words.

The project's docs in reading order (starting prompt, spec, plan, AGENTS.md, memory, notes, working docs): id, kind, title, size, when changed. No bodies: read one with get_doc. `kind` narrows the list. Docs marked `global` (the AGENTS.md and the memory for all projects) belong to every project: read them too, they hold the user's standing rules.

The findings recorded in the project, newest first: its Tares agents' and the ones external agents recorded. `entity` and `agent` narrow them. Read them before concluding, so you build on what is known instead of repeating it.

The project's milestones in order: name, goal, acceptance checks, how many tickets and how many are done, which are ready, and whether the milestone is finished. Work one milestone at a time, in this order.

List the projects you can work in: id, name, template and status. With a project key it is the one project the key belongs to.

List the project's skills: name and description. Load one with get_skill before relying on it, only when your task matches its description.

List every configured source with its live health (status, events ingested, last error). Use it to confirm a source you created is actually ingesting.

The project's tickets in plan order: id, label (the Linear identifier such as ENG-12, the GitHub identifier such as GH-12, else T<n>), title, status (todo, in_progress, done, canceled), milestone, depends_on, the GitHub repo it changes (`repo`, owner/name, for a project that spans several), whether it is ready (all it depends on is done) or which tickets block it, the link when it lives in Linear or GitHub, and the id and title of each one's working doc. Work the ready tickets in this order. Also says where they live: `linear` is the Linear project and `github` the repo and issue label, each with when it was last synced (null when the project does not use it); with both null the tickets live in Tares. Read one with get_ticket to get its working doc.

Pick the build up where an earlier session stopped. Call it first when you are told to work on a project and a ticket is already in progress (list_tickets says so), or when told to pick up. Returns the hand-over: the ticket with its working doc, what the previous session said last and the files it touched, the builders' notes and a checklist. It takes the build over (the previous session is marked replaced) unless that session may still be open: then it says so and does nothing; ask the person, and call again with take_over=true only if they say so.

What happened in the project, newest first: each firing with the runs it woke and their findings, and the findings recorded without a firing (external agents' among them).

Read one correlated, time-ordered timeline of everything matching `selector` across all sources, or only a `project`'s sources, or only the `sources` you name. `selector` is a {label: value} conjunction, matched with strict AND, e.g. {"repo": "frontend"} or {"service": "api-server", "endpoint": "/login"}. An event matches only if it carries every named label with that value, so adding a label narrows and removing one widens. Use this to investigate any entity on the fly; once you know which sources matter, create_trigger() over them. Set `include_payload` when the one-line summaries aren't enough and you need each event's full lossless record: the return becomes JSON {timeline, events[]} where each event carries `raw`. With a project key the read covers that project only, its findings included.

The docs every project shares: the AGENTS.md for all projects (the user's standing rules) and the memory (facts and preferences that hold across projects), as markdown. Read them at the start of any work on a project and follow them; do not ask the user again for what they already say.

What the person allows the crew to do, in their own words with the date: the grants for every project, and the project's own when `project` is given. Never act on a permission that is not here or in the person's own words in your session.

Record what you concluded about an entity (a service, a repo, a customer) in the project. It lands on the entity's timeline next to the Tares agents' findings and in the project's activity, under your key's name. `finding` is markdown; `verdict` one lowercase word (for example rca or resolved); `label` the label the entity is a value of when it is not the project's usual one (for example service). `headline` is one line (at most 100 characters) saying what you found, and `next_step` what a person should do (empty when nothing needs doing): both show on the project's Overview.

Record your review of a ticket's pull request, the same verdict you post to GitHub: `head` the commit you reviewed, `verdict` pass, changes or block, `verified` what you ran and what it showed, `not_verified` what you did not cover and why, `findings` [{"severity": "P1|P2|P3", "file": "", "line": 0, "blocking": true, "text": ""}], and on a re-review `resolved` marking each earlier finding {"F1": "fixed", "F2": "open"}. A pass leaves no blocking finding open. Only the reviewer records reviews.

Kinds of finding that came back in several tickets of a repo (owner/name) in the last 30 days, with the tickets and examples. Check these first in a review.

The person took this project back from the crew (it is under `releasing` in crew_projects): call this once every builder that held its tickets has stopped, pushed what it had and written its progress, and has been retired. Tares clears the tickets' holders (stages, pull requests and working docs stay) and the person's session owns the project from then on. Then reply to the session that asked with `[TF:RELEASED]`. Only the orchestrator, or the person's own session when no orchestrator runs.