Playbook and guides

Every team has rules that live in one person’s head and get re-explained every Tuesday. The Playbook is where they go instead: short Markdown guides that people and agents read before the work starts. Brief the agent. Retire the séance.

Before you start

• You’re a member of the workspace. Everyone can read the Playbook. What else you can do depends on your role:

	Member	Admin	Owner
Read guides and propose changes	Yes	Yes	Yes
Attach or pin a guide on an issue	Yes	Yes	Yes
Publish an unprotected guide directly, review proposals		Yes	Yes
Make a guide a workspace default			Yes
Turn review protection on or off, override review once			Yes
Grant agents Playbook access			Yes

• Settings › Playbook (agent permissions, prompts and defaults) opens for Owners and Admins. Only the Owner can change what’s on it apart from the prompts.
• Agents start read-only. See Give agents more than reading.

Steps

Find the Playbook

Choose Playbook in the sidebar, or search “Playbook” in the command palette. Three tabs: Published, Proposals and Archived. Each guide shows what it applies to and its current revision, like r3.

Write a guide

1. Press Create guide.
2. Pick the Guidance source:
   • Markdown guide: the text lives in Hydrant. Up to 64 KiB.
   • Repository reference: the text stays in your repository. Hydrant keeps the repository, file path, optional branch or commit, and an HTTPS link. It never fetches or verifies the file; the agent reads it through its own repository access.
3. Give it a Guide name and write the guide.
4. Pick the Contribution:
   • Propose change: fill in What changes, and why? and press Submit proposal. Nothing changes until someone reviews it.
   • Publish directly: press Publish guide. Admins and Owners only, and never on a protected guide.

A workspace holds up to 100 guides. Archived ones still count.

Put a guide in front of the work

A guide reaches a task in one of two ways:

• Workspace default. Applies to every issue from now on. The Owner ticks Workspace default · future task context under Applicability and retirement on the guide. Up to 10 defaults. Keep them short and general; nobody reads a 40-page default.
• Issue attachment. Open an issue, choose the Guidance tab, then Attach a guide. Pick one under Choose guide and press Attach to this issue. Leave Pin revision (optional) blank to follow the latest publication, or pin an exact revision. Up to 20 guides per issue. Remove attachment takes it off.

The Guidance tab lists what applies under Attached guides, with the reason for each: workspace default, attachment following the latest, or pinned to a revision.

Review a proposal

1. Open Proposals and pick one. You’ll see the change, the reason and the discussion.
2. Under Decision, choose Publish, Request changes or Reject, write a Reason and confirm. The author can Withdraw their own proposal instead.

You can’t review your own proposal. Discussion is evidence, not approval.

Protect a guide

Some guides are too important for anyone to publish on a whim. The Owner opens Owner controls · review protection on the guide, writes a reason and presses Require review. From then on, every change is a proposal and needs a reviewer who isn’t the author. Remove protection undoes it, also with a reason.

Override review, once

When the Owner needs a protected change published and nobody else can review it, they can skip review for one publication:

1. Open the proposal and choose Publish.
2. Tick Override review for this publication, write a Reason, then tick the confirmation that names the exact proposal and revision.
3. Press Override review and publish.

Protection stays on for the next change. The Owner’s name and reason are recorded permanently. Agents can never override review, whoever granted them.

Give agents more than reading

The Owner opens Settings › Playbook and, under Agent permissions, ticks rights for each agent connection or key, then presses Save access:

• Propose changes: submit proposals. Published guidance stays unchanged until review.
• Publish unprotected guides: make changes effective without a separate reviewer. Includes proposing.
• Review protected changes: review another author’s proposal. No self-approval. Includes proposing.

An agent never has more authority than the person who granted it. An agent granted by a Member can only propose, whatever’s ticked. Assigning an issue to a named agent grants no Playbook access either.

What you should see

• After publishing: “Published. Existing task records keep their selected revisions.” The guide’s revision goes up by one and future tasks get the new text.
• When an agent starts work on an issue: it reads the guidance with get_task_context, which returns the full list of guides that apply, frozen at that moment, plus their text. Then it records what it actually received with record_task_context. Each delivery comes with an identifier that lasts an hour, and the record points to those exact revisions.
• On the issue: the Guidance tab’s Context records list each record: who, which work attempt, which revisions. Publishing a newer revision later doesn’t rewrite old records.

A receipt is not a promise

A context record is the agent’s own report of what it received. It proves delivery, not that the agent read, understood or followed it. Reading alone leaves no record.

If it goes sideways

• “No delivery recorded. Reading alone does not leave a receipt.” The agent read guidance but never recorded it. Its instructions have to tell it to; connecting the MCP server doesn’t install them. A read-only connection can’t record at all.
• “Your current Playbook permissions do not allow this action.” You, or the agent, lack the right. Check the table above, or ask the Owner for an agent grant.
• “This guide requires a proposal and another reviewer, or an explicit owner review override.” It’s protected. Submit a proposal.
• “The author cannot review this proposal. Another eligible reviewer is required.” (An agent gets “The author cannot review their own proposal. An owner may explicitly override review to publish.”) Find another Admin, or ask the Owner to override review once.
• “Reality edited first.” Someone changed the guide, proposal or settings while you were working. Your draft is kept. Compare with the current revision, then try again.
• “Result unconfirmed.” Press Retry original request. It resends the same command, so nothing happens twice.
• “This workspace has 100 guides.” Archiving keeps history but doesn’t free a slot. That’s the limit.
• An agent’s guidance delivery expired. Deliveries last an hour. The agent reads the guidance again and records the new delivery.