benxu001/agentic-linear-orchestration-framework

# agentic-linear-orchestration-framework A Linear-native multi-agent orchestrator for Claude Code, extracted from a real shipped project. ## What this is A working framework for using Claude Code to ship issues from a Linear backlog end-to-end with high autonomy. You drive the orchestrator session at the top; the orchestrator picks issues, spawns implementer subagents in git worktrees, spawns reviewer subagents when each PR opens, and auto-merges clean work when the issue's tier allows. You stay in the loop on judgment calls (page routes, polish, anything cross-cutting); the orchestrator handles the mechanical pipeline around them. The framework was developed in production use on [DropLog](case-studies/README.md), a personal project that has been the test bed for every rule, every gotcha, and every auto-merge decision included here. Every hard rule has a real incident behind it - see [`case-studies/`](case-studies/) for the forensics. ## 30-second mental model operator -> orchestrator picks Linear issue -> spawn implementer subagent (worktree-isolated) -> reads issue, branches, implements, verifies, pushes PR -> flips Linear In Progress -> In Review -> returns structured verdict -> spawn reviewer subagent (read-only) -> applies PR Review Standard, returns 3-bucket verdict -> orchestrator applies the auto-merge gate -> auto-merge if reviewer is clean and tier allows -> otherwise ping operator -> orchestrator logs the run for model-fitness tracking See [ARCHITECTURE.md](ARCHITECTURE.md) for the full picture. ## What you get - **Multi-agent spawn pattern** for Claude Code's subagent system, including the workaround for the project-level agent discovery limitation ([`framework/memory/subagent-spawn-pattern.md`](framework/memory/subagent-spawn-pattern.md)). - **Auto-merge gate with a tier model** that distinguishes mechanical work (auto-merge OK) from judgment calls (operator required). See [`framework/.claude/orchestration/policy.md`](framework/.claude/orchestration/policy.md) sections 3 + 5. - **Implementer + reviewer subagent specs** with full workflows, verdict formats, and escalation rules. - **Canon / memory / decisions knowledge layering** - what each surface is for and how to update it. - **Real failure-mode library** from production use: working-tree leaks, classifier blocks, silent SDK gotchas, RLS coverage misses, OAuth attribution problems - each with the incident, the rule that came out of it, and the recovery procedure. Useful whether you're a solo developer shipping a side project or part of a team looking for proven patterns to adapt. Honest scoping: the framework as shipped is written against Linear + Claude Code; adapting to other trackers or harnesses is a known-shaped piece of work - see [LIMITATIONS.md](LIMITATIONS.md) for the coupling points and where the abstractions would slot in. ## Get started The `framework/` directory is a drop-in template. To use it in a new project: 1. Copy the contents of `framework/` into your project root. 2. Edit `AGENTS.md`, `RETRIEVAL.md`, and the agent specs in `.claude/agents/` to replace placeholders like `{ISSUE_PREFIX}`, `{PROJECT_NAME}`, `{STACK}` with your specifics. 3. If you're using Linear, set up a dedicated agent OAuth user (see [case-studies/03-linear-agent-oauth/](case-studies/03-linear-agent-oauth/)) and add the four `LINEAR_AGENT_*` env vars to your project's `.env.example`. 4. Open a Claude Code session in the project root. The canon will auto-load via `CLAUDE.md`'s `@`-imports. 5. Read [ARCHITECTURE.md](ARCHITECTURE.md) for the role contracts and the auto-merge gate, then walk through one issue end-to-end to confirm the pipeline works in your environment. ## Repository layout . +-- README.md this file +-- ARCHITECTURE.md knowledge layers + roles + auto-merge gate +-- LIMITATIONS.md coupling points + honest scope +-- CHANGELOG.md +-- LICENSE MIT +-- framework/ the drop-in template | +-- AGENTS.md | +-- CLAUDE.md | +-- RETRIEVAL.md | +-- .claude/ | | +-- orchestration/ policy + decisions log + how-to | | +-- agents/ implementer + reviewer role specs | | +-- settings.json SubagentStop hook | +-- memory/ index + seed gotcha files +-- case-studies/ anonymized incidents from the originating project | +-- README.md | +-- 01-model-escalation-tracking/ | +-- 02-orchestrator-in-session-fix/ | +-- 03-linear-agent-oauth/ | +-- 04-stack-gotchas/ +-- diagrams/ Mermaid architecture + workflow + gate diagrams ## License MIT. See [LICENSE](LICENSE).