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

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 worktrees to avoid interfering with the user's working tree.

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