Guides

A guide gives the agent that claims a ticket a role: a reviewer, QA, security, docs, an architect, or one you or the community wrote. The agent gets the guide's instructions and a checklist it must answer before the work counts as done.

A guide is data, never code: instructions, a checklist and the checks it requires. It works the same for Claude Code, Codex or any MCP client.

#Built-in guides

Five guides ship with Teamtrail and need nothing installed:

A file in .teamtrail/guides/ with a built-in's id replaces it once you approve it. Removing that file brings the built-in back.

#Giving a ticket a guide

• A ticket asks for a guide. Each ticket has an optional guide. Agents set it with add_ticket or start_trail (guide on each ticket); you set it in the Lookout's ticket inspector (Guide). The guide must be installed and active, and made for the ticket's type.
• A trail lists its team. A trail's team is the guides its tickets use. Agents name it once with start_trail (team); after that only you change it, in Settings → Team of #n. With reviewer on the team, the review tickets Teamtrail creates at checks+review get the reviewer guide.
• Agents can pick by guide. claim_ticket and next_ticket take guides (for example ["qa"]) to take only tickets with one of those guides. Tickets without a guide are left out.

list_guides shows agents the guides they can use. Installing, approving and removing guides is yours, in the Lookout or the CLI.

#What the claiming agent gets

When a ticket has an active guide, the claim result has guide:

When the ticket asks for a guide that can't be used now (not installed, not approved, edited after approval or failing the lint), the claim has a guideWarning instead. The agent works the ticket without guide instructions, and you see the guide in Waiting on you.

Guide text never overrides Teamtrail's rules: an agent still never reviews its own work, never answers or approves for you, and never edits verification or guide files.

#The checklist

When the guide has a checklist, close_ticket, report_completion and submit_review need checklist: one answer per item.

"checklist": [
  { "item": "1", "done": true },
  { "item": "Listed what you did not test, and why", "done": false, "note": "No device lab for Android 9" }
]

item is the item's text (case and spacing don't matter) or its number. Every item needs an answer; done: false with a note counts. Teamtrail checks that each item is answered, not that the answer is true. A missing or unknown item refuses the completion with the list of what's missing.

The answers are kept in .teamtrail/.evidence/<trail>/<ticket>/checklist.json, and the ticket inspector shows them.

#Adding guides from the catalog

The public catalog is teamtrailhq/teamtrail-guides. Teamtrail reads its index.json over HTTPS; there's no server and no account.

From the CLI:

npx teamtrail@next guides search accessibility
npx teamtrail@next guides add a11y

In the Lookout: Settings → Guides → Browse guides. It shows only Verified guides by default (turn off Verified only to see all). Each guide shows its author, review history, checklist, the commands it proposes and its full instructions before you add it.

Adding a guide fetches the file, checks its sha256 against the catalog's index, runs the safety lint, shows you the whole guide and, once you approve it, copies it to .teamtrail/guides/<id>.md and pins it in .teamtrail/guides.lock.json. Commit both, and teammates get the same guide. A guide that fails the lint can't be added. The catalog's copies of built-in guides are for reading and are never added.

teamtrail guides update installs newer catalog versions. See CLI commands for every subcommand.

#What the catalog labels mean

Report this guide in the Lookout opens the catalog's report form.

#Writing your own

Start a guide for your team with:

npx teamtrail@next guides new perf

It writes .teamtrail/guides/perf.md from a template that already passes the safety lint, signed with your git name (--author <name> to sign it otherwise). Replace the placeholders with your instructions and checklist:

---
v: 1
id: perf
name: Performance
version: 1.0.0
summary: Measures before and after, on a slow phone.
handles:
  types: [task, execute]
checklist:
  - Measured before and after on the same device
author: Your Name
license: MIT
---

Measure the change on the slowest device you support, before and after, and write both numbers down.

Check it with teamtrail guides lint. Without a path it lints your project's own guides.

Then approve it in the Lookout: Settings → Guides → Write your own lists the guides your team wrote, each as Not approved yet or Approved. Agents can't use a guide until the trail lead approves it, and again after every edit. Once it's approved, give tickets the guide perf or put it on a trail's team.

guides add ./perf.md adds a guide file from elsewhere: it runs the same lint, copies the file into .teamtrail/guides/ and pins it.

To share a guide with everyone, open a pull request on the public catalog; its CONTRIBUTING.md explains the review. Write your own links to it too.

#The file format

YAML frontmatter between --- lines, then the instructions as markdown. The frontmatter uses a small YAML subset: key: value, key: [a, b], and indented lists or maps. Anything else is reported, never guessed.

The body holds the instructions, up to 8 KB. Unknown keys are errors, and keys that try to change what Teamtrail enforces (verification, level, hitl, lifecycle, tools, permissions, checks, run, status, approve, …) are refused.

A proposed check with its own timeout:

requiresChecks: [a11y]
proposedChecks:
  a11y:
    run: [npx, pa11y-ci]
    timeoutSec: 600

#The safety lint

guides lint and every install check the whole file, line by line, and name the line of each finding. Any error refuses the guide.

#Approval and pinning

• Checks only after you approve them. A guide's proposed check never runs until you approve it, from the prompt in guides add, with --approve-checks, or in Settings → Guides. Approving writes it to verification.json, the only place Teamtrail runs commands from, and records its argv's hash in the lock. If a later version changes the command, you're asked again. Without a terminal, guides add approves nothing unless you pass --approve-checks.
• Unknown programs need your acknowledgement. A proposed check that runs a program Teamtrail doesn't know says so, and its button reads I know what it runs: approve check <name>. The CLI asks about it only at a terminal; --approve-checks never approves one. A command line that itself carries or downloads code is refused.
• Approved per machine. What you approved is kept in your config folder, outside the repo. A guide a teammate added shows as approved elsewhere until you approve it on your machine, and a repo moved to another folder is asked again.
• Pinned by hash. guides.lock.json records each guide's version, sha256, source and who added it. A guide file edited after you approved it is switched off until you look at it again (Approve). The same happens when its lock entry changes outside Teamtrail, for example an agent editing the file or a teammate's change pulled with git. Its tickets get a guideWarning, and the guide shows in Waiting on you.
• Guides only add. A guide can add checks and a checklist. It can't lower the verification level, drop or reorder a check, change who decides, or let an agent review its own work. A switched-off guide keeps adding the checks its approved version required.
• Removing a guide deletes its file and lock entry. Checks you approved stay in verification.json; edit that file to drop them.

#Other catalogs

.teamtrail/guides.json adds catalogs to search, in order. The ones it lists come first, then the official one:

{
  "v": 1,
  "registries": [{ "name": "acme", "url": "https://raw.githubusercontent.com/acme/guides/main" }]
}

Each registry needs a name and an https URL (or http://localhost or http://127.0.0.1). The name teamtrail is reserved for the official catalog.

An agent can edit this file, so its catalogs are searched only once you approve it in Settings → Project → Approvals, on its own. Approving covers where guides come from, not the guides: each one is still shown whole and approved on its own. Guides from these catalogs carry their catalog's review as Verified by <host>'s catalog. Add "official": false to leave the official catalog out, or list it yourself (name teamtrail) to put it somewhere else in the order. When the file is missing, only the official catalog is used.

guides search and guides add <id> look in every catalog, in order, and guides add says which one the guide came from. An id in more than one catalog is refused until you pick one: guides add acme/perf, or --registry acme.

A catalog is a git repo with guides/<id>.md, an examples/<id>/ test example per guide, and an index.json built from them.