# Reading Guild Rules

> Reference document for Guild workflow protocol, conventions, and rules. Read-only — no side effects. Covers commit/PR conventions, label protocol, eligibility criteria, issue pickup, priority rules, execution patterns, and bundle PR rules. Use when you need to look up Guild rules or conventions. NOT a task skill — does not perform any actions.

- Skill: `ugai/reading-guild-rules` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ugai/reading-guild-rules`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ugai/reading-guild-rules/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ugai (https://skillmd.com/u/ugai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ugai/reading-guild-rules

---


# Guild Rules

Reference-only skill. Read this when you need Guild protocol details.

This repository is structured as a **Claude Code plugin** (`guild-tavern`).
When loaded via `claude --plugin-dir` or installed from a marketplace, skills
are namespaced as `/guild-tavern:<skill-name>`.

## Shared Rules Rubric

The rules in this document are the human-readable source of truth.
A machine-readable counterpart lives in `rubrics/shared-rules.yaml`, and
`tests/test_rubric_lint.py` verifies that each targeted `SKILL.md` expresses
the relevant rules. When updating rules here, keep the rubric in sync.

## Workflow

### Recommended Workflow

```text
issue-ranger          Scout the codebase → post agent:proposed issues
      ↓
  (human)             Review and add agent:ready label
      ↓
issue-raid-commander  Analyze ready queue → detect conflicts → output sprint plan
      ↓
issue-slayer × N      Implement in parallel worktrees → open PRs
      ↓
quality-finisher      Audit PRs for test coverage → push tests or post comments
      ↓
verify-sprint         Merge PR branches locally → visual check → squash merge to main
```

Run `issue-raid-commander` before spawning a slayer team to avoid merge conflicts.
For single-issue work, skip it and go straight to `issue-slayer`.

**Full pipeline shortcut**: `dispatching-guild-expedition` runs the entire
workflow above in one command — Rangers × 4, user approval gate, Commander,
then Slayers × N in parallel. Follow up with `verify-sprint` to verify and
merge the opened PRs.

### Execution Patterns

We use two primary patterns for agent work, both utilizing isolated `git worktree`s to avoid interfering with the user's working tree.

| Pattern | How it runs | Plan Approval | Use Case |
| :--- | :--- | :--- | :--- |
| **A (Standalone)** | User invokes the skill directly | **User approves** via chat | Single-issue work |
| **B (Team)** | Team Lead spawns multiple agents | **Lead approves** via message | Parallel multi-issue sprint |

## Commit & PR Conventions

- **Co-authorship trailer** — format: `Co-Authored-By: {model} ({tool}) <email>`. Use the actual model name:
  - Claude Code: `Co-Authored-By: {model} (Claude Code) <noreply@anthropic.com>`
  - GitHub Copilot: `Co-Authored-By: {model} (GitHub Copilot) <175728472+Copilot@users.noreply.github.com>`
  - Gemini CLI: `Co-Authored-By: {model} (Gemini CLI) <176961590+gemini-code-assist[bot]@users.noreply.github.com>`
  - Antigravity: `Co-Authored-By: {model} (Antigravity) <176961590+gemini-code-assist[bot]@users.noreply.github.com>`
- **Branch Naming**: `<type>/<kebab-case-description>` (e.g., `feat/add-ambient-blur`)
- **PR Title**: Conventional Commits (e.g., `feat: add ambient blur shader`)
- **PR Body**: Must include `Closes #<issue-number>`.
- **One Issue, One PR** — default policy. Each issue gets its own PR.

### Bundle PR (Exception)

Raid Commander (or a human) may group issues into a **Bundle PR** when ALL:

1. Same fix pattern (e.g., unwrap removal, lint fix, dep bump)
2. Each issue is **small** complexity
3. No file conflicts within the group
4. Total diff is reviewable as a single unit

Bundle PR rules:

- One commit per issue (`Ref #<N>` in each commit message)
- PR body lists all `Closes #<N>`
- Slayer uses a single worktree
- Raid Commander flags candidates as `bundleable` in the sprint plan;
  Slayer follows that designation (or a direct user/lead instruction)

## Labels

### `agent:ready`

Issues must have the **`agent:ready`** label before an AI agent can pick them up.
This is an opt-in guardrail — maintainers explicitly approve issues for autonomous implementation by adding this label.

### `agent:proposed`

Issues with **`agent:proposed`** were opened by the `issue-ranger` skill.
They are **not yet approved** for autonomous implementation. Agents must wait until a maintainer adds `agent:ready` before picking them up.

> **Note**: `agent:proposed` is an origin label, not a status. It stays on the issue even after `agent:ready` is added, so you can always filter AI-proposed issues with `--label agent:proposed`.

### Issue Creation Protocol

When creating new issues, an agent MUST:

1. Add the `agent:proposed` label to every issue it creates
2. Never add `agent:ready` on its own — that label is reserved for human maintainers. The only exception is when a user explicitly approves specific issues for readiness

## Eligibility Criteria

An agent may only work on an issue if **ALL** of the following are true:

1. Has the `agent:ready` label
2. Is Open
3. Is Unassigned
4. Does **NOT** have a `pending` label

## Issue Pickup Protocol

Before writing any code, an agent MUST:

1. Self-assign the issue to itself
2. Post a comment on the issue announcing that work has started

## Priority

When multiple eligible issues exist, agents favor:

1. `bug` > `enhancement`
2. `priority:p0` > `priority:p1` > `priority:p2` > `priority:p3` (no label = `p2`)
3. Lowest issue number