git:20260811.65ccd62 to git:20261009.07652cf

<!-- GENERATED FILE — DO NOT EDIT DIRECTLY.

Produced by defaults/scripts/generate-agents-md.sh from the

`agents-md:include` marker ranges in defaults/.loom/CLAUDE.md. To change

this file, edit those ranges in the source and re-run the generator;

CI (scripts/check-agents-md-sync.sh) fails if this file is stale.

Attribution: seeded by the gpeyton/loom fork's PR #8 (AGENTS.md codegen),

ported to single-source generation for issue #4479 (epic #4167). -->

# Loom Orchestration - Repository Guide (AGENTS.md)

This repository uses **Loom** for AI-powered development orchestration.

**Installation Date**: 2026-08-10

> **Dual-runtime status**: this file is the runtime-neutral instruction anchor

> read by AGENTS.md-aware runtimes (OpenAI Codex CLI and others — see

> https://agents.md). Claude Code additionally reads the richer `.loom/CLAUDE.md`

> sibling as its primary format; the content below is a strict subset extracted

> from that same source, so the two files cannot diverge. Anything marked

> **Claude Code only today** (see the end of this file) is not yet portable to

> other runtimes — perform the equivalent `gh` / `git` / `./.loom/scripts/*`

> steps directly instead.

## What is Loom?

Loom is a CLI + daemon for AI-powered development orchestration. It coordinates

AI development workers using git worktrees and a forge (GitHub or Gitea) as the

coordination layer, via manual roles, continuous autonomous orchestration (the

Rust `loom-daemon` binary), and a local tmux agent pool.

**Loom Repository**: https://github.com/rjwalters/loom

> **Forge note**: The `gh` commands shown below are for GitHub. For Gitea

> repositories, Loom's scripts handle API calls internally — the label-based

> workflow is identical regardless of forge.

## Orchestration Architecture

Loom decomposes development into three coordination tiers, with the forge

(GitHub / Gitea) as the shared state.

| Tier | Entry point | Purpose | Mode |

|------|-------------|---------|------|

| Tier 3 | Human | Oversight — approve proposals, handle edge cases | Observer |

| Tier 2 | `loom-daemon` (MCP) + tmux agent pool | Multi-issue dispatch + scheduled support roles | Continuous |

| Tier 1 | `/loom:sweep <issue>` | Single-issue lifecycle (Curator → Merge) | Per-issue |

| Tier 0 | `/loom:builder`, `/loom:judge`, etc. | Task execution — single focused work units | Per-task |

## Label-Based Workflow

Agents coordinate through labels. See `.github/labels.yml` for full definitions.

**Issue Lifecycle**:

```

(created) → loom:triage → loom:curating → loom:curated → loom:issue → loom:building → (closed)

↑ filer ↑ Curator ↑ Curator ↑ human ↑ Builder

```

**PR Lifecycle**:

```

(created) → loom:review-requested → loom:pr → (merged)

↑ Builder ↑ Judge ↑ Champion or human

```

**Proposal Lifecycle**:

```

(created) → loom:architect/loom:hermit/loom:auditor → (evaluated) → loom:issue

↑ Architect/Hermit/Auditor ↑ Champion ↑ Ready for Builder

```

**Epic Lifecycle**: `loom:epic` → phased `loom:architect` + `loom:epic-phase`

child issues.

### REST vs GraphQL for forge queries

### Issues Are Suggestions (Role Autonomy)

Filed issues are the *input queue*, not mandates. Curator, Builder, and Judge

may **close** or **rescope** an issue — with a stated rationale — when building

it is not the best outcome. Comment the rationale before closing; rescope

instead of closing when the core is worth keeping (drop back to

`loom:triage`/`loom:curated`, removing `loom:issue`, so it isn't re-dispatched

with a stale scope). Never close an issue that encodes a pending human

decision — route it to `loom:blocked` or `loom:operator-only` instead.

## Git Worktree Workflow

Loom uses git worktrees to isolate agent work. **Issue Worktrees**

- Always use `./.loom/scripts/worktree.sh <issue-number>` (writes a

`.loom-managed` sentinel that authorizes cleanup). **Never run `git worktree`

directly** — the helper prevents nested worktrees; use `./.loom/scripts/worktree.sh

remove <issue-number>` to remove one worktree on demand, or `loom-clean` for

the bulk stale-cleanup path.

- Loom-managed worktrees are auto-removed when their PR merges; user-provisioned

worktrees are never touched — set `LOOM_PRESERVE_WORKTREE=1` to disable

cleanup for a session.

### Merging PRs

**Never use `gh pr merge`** — always use `./.loom/scripts/merge-pr.sh <PR_NUMBER>`

merge` attempts a local checkout that fails when the PR branch is linked to a

worktree; the script merges via the forge API directly and handles worktree

cleanup automatically. A `PreToolUse` hook redirects `gh pr merge` calls to

this script.

## Claude Code only today

The coordination mechanics above (labels, worktrees, the sweep lifecycle,

`merge-pr.sh`) are runtime-neutral — any worker that can run `gh` and `git`

participates. These dispatch surfaces are Claude-Code-specific for now:

- **Slash commands** (`/loom:sweep`, `/loom:builder`, `/loom:judge`, …) are

defined under `.claude/commands/loom/`. A non-Claude runtime cannot invoke

them by name; it performs the equivalent steps directly (claim the issue,

create the worktree, implement, open the PR).

- **MCP tools** (`mcp__loom__dispatch_sweep`, `mcp__loom__list_sweeps`, …) are

reachable only through Claude Code's MCP integration.

- **`PreToolUse` guard hooks** and the **`.loom/tokens/` multi-account token

pool** guard Claude tool calls and rotate Claude Code credentials — they do

not apply to other runtimes.

For the full Claude-Code-oriented guide (daemon MCP surface, configuration,

token pool, troubleshooting) see `.loom/CLAUDE.md`.

---

**Generated by Loom Installation Process**

Last updated: 2026-08-10