# Playbook and guides

Write guides once, attach them to issues or make them workspace defaults, review changes, and see exactly what guidance an agent received.

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](#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](/help/agents/named-agents) 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.

:::note[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.

Contact: bots@hydrant.dev