Rune

Multi-agent engineering orchestration for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).

Built on Discipline Engineering — a proof-based architecture that treats specification compliance, not just code quality, as the primary metric.

Plan, implement, review, test, and audit your codebase using coordinated Agent Teams — each teammate with its own dedicated context window.

What Is This?

Rune is a Claude Code plugin that turns a single-agent coding session into a coordinated multi-agent engineering team. It provides 116 specialized AI agents (74 core + 42 extended), 44 skills, and a 45-phase end-to-end pipeline that handles planning, implementation, code review, testing, and PR creation — all orchestrated through Claude Code's Agent Teams.

Compatibility: Requires Claude Code 2.1.81+ with Agent Teams support. macOS 12+ or Linux. See full requirements.

Why This Exists

Claude Code is powerful on its own — but a single agent has a single context window. As tasks grow in scope (reviewing a 50-file diff, planning a feature across multiple services, running a full implementation pipeline), one context window becomes the bottleneck:

• Context saturation — A single agent reviewing 40 files loses focus on file 35. Rune gives each reviewer its own full context window, so the last file gets the same attention as the first.
• Specialization over generalization — One agent trying to catch security issues, performance bugs, and naming inconsistencies simultaneously does none of them well. Rune dispatches Ward Sentinel for security, Ember Oracle for performance, and Pattern Seer for consistency — each focused on what it does best.
• Parallelism — Sequential work on 6 implementation tasks takes 6x as long. Swarm workers claim and complete tasks independently, bounded only by file-level conflicts.
• Separation of concerns — Planning, implementing, reviewing, and testing in one context creates confirmation bias (the same agent reviews code it just wrote). Rune enforces phase boundaries: different agents plan, build, and critique.

These problems are symptoms of a deeper issue: AI agents optimize for completion signals, not specification compliance. Rune's architecture is designed around the Discipline Engineering framework — five layers of decomposition, comprehension verification, proof-based completion, and anti-rationalization gates that ensure agents deliver what was specified, not just what compiles.

The trade-off is token cost — multi-agent workflows consume more tokens than a single session. Rune is designed for cases where quality, thoroughness, and coverage matter more than minimizing API usage.

<a name="token-warning"></a>

[!WARNING] Rune is token-intensive and time-intensive.

>

Each workflow spawns multiple agents, each with its own dedicated context window. This means higher token consumption and longer runtimes than single-agent usage.

>

| Workflow | Typical Duration | Why | |----------|-----------------|-----| | /rune:devise | 10–30 min | Up to 7 agents across 7 phases (brainstorm, research, synthesize, forge, review) | | /rune:appraise | 5–20 min | Up to 8 review agents analyzing your diff in parallel — scales with LOC changed | | /rune:audit | 10–30 min | Full codebase scan — same agents, broader scope | | /rune:strive | 10–30 min | Swarm workers implementing tasks in parallel | | /rune:arc | 1–2 hours | Full 45-phase pipeline (forge → plan review → work → gap analysis → code review → mend → test → ship → merge) | | /rune:arc (complex) | up to 3 hours | Large plans with multiple review-mend convergence loops |

>

/rune:arc is intentionally slow because it runs the entire software development lifecycle autonomously — planning enrichment, parallel implementation, multi-agent code review, automated fixes, 3-tier testing, and PR creation. Each phase spawns and tears down a separate agent team. The result is higher quality, but it takes time.

>

Want faster iterations? Run the steps individually instead of the full pipeline:

>

`` /rune:plan → /rune:work → /rune:review (10–30 min) (10–30 min) (5–20 min) ``

>

This gives you the same core workflow (plan → implement → review) in 25–80 minutes with manual control between steps — versus 1–3 hours for /rune:arc which adds forge enrichment, gap analysis, automated mend loops, 3-tier testing, and PR creation on top.

>

Claude Max ($200/month) or higher recommended. Use --dry-run where available to preview scope before committing.

Install

/plugin marketplace add https://github.com/vinhnxv/rune
/plugin install rune

Restart Claude Code after installation.

<details> <summary>Local development</summary>

claude --plugin-dir /path/to/rune

</details>

Setup

Rune requires Agent Teams. Enable it in .claude/settings.json or .claude/settings.local.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "includedGitignorePatterns": [
    "plans/",
    "todos/",
    "tmp/",
    "reviews/",
    ".rune/",
    ".claude/CLAUDE.local.md"
  ]
}

includedGitignorePatterns lets Claude Code read Rune's output directories that are typically gitignored.

For configuration details (hardcoded v3.x defaults, override paths) see the Configuration section below.

How It Works

Rune orchestrates multi-agent workflows where specialized AI teammates collaborate through shared task lists and file-based communication. Instead of one agent doing everything in a single context window, Rune splits work across purpose-built agents — each with its own full context window.

You ──► /rune:devise ──► Plan
                           │
         /rune:arc ◄───────┘
             │
             ├─ Forge & Validate     enrich plan, review architecture, refine
             ├─ Work                 swarm workers implement in parallel
             ├─ Gap Analysis         detect and remediate implementation gaps
             ├─ Review & Mend        multi-agent code review + auto-fix findings
             ├─ Test                 3-tier testing (unit → integration → E2E)
             ├─ Ship                 validate and create PR
             └─ Merge               rebase and merge

Workflows

Quick Start (New Users)

/rune:tarnished — The Unified Entry Point

Don't remember which command to use? /rune:tarnished is the intelligent master command that routes natural language to the correct Rune workflow. It understands both English and Vietnamese.

# Route by keyword — passes through to the right skill
/rune:tarnished plan add user authentication
/rune:tarnished work plans/my-plan.md
/rune:tarnished review
/rune:tarnished arc plans/my-plan.md
/rune:tarnished arc-quick plans/my-plan.md

# Chain workflows — multi-step with confirmation between steps
/rune:tarnished review and fix
/rune:tarnished plan then work

# Natural language — classifies intent automatically
/rune:tarnished implement the latest plan
/rune:tarnished fix the findings from the last review

# Guidance — ask Rune anything
/rune:tarnished help
/rune:tarnished what should I do next?
/rune:tarnished khi nào nên dùng audit vs review?

When run with no arguments, /rune:tarnished scans your project state (plans, reviews, git changes) and suggests the most logical next action.

Core Commands

Utilities

Workflow Details

<a name="devise"></a> /rune:devise — Planning

Transforms a feature idea into a structured plan through a multi-phase pipeline:

1. Brainstorm — structured exploration with elicitation methods
2. Research — parallel agents scan your repo, git history, echoes, and external docs
3. Solution Arena — competing approaches evaluated on weighted dimensions
4. Synthesize — consolidate findings into a plan document
5. Predictive Goldmask — risk scoring for files the plan will touch
6. Forge — topic-aware enrichment by specialist agents
7. Review — automated verification + optional technical review

/rune:devise                  # Full pipeline
/rune:devise --quick          # Skip brainstorm + forge (faster)

Output: plans/YYYY-MM-DD-{type}-{name}-plan.md

<a name="arc"></a> /rune:arc — End-to-End Pipeline

The full pipeline from plan to merged PR, with 45 phases:

Forge → Plan Review → Refinement → Verification → Semantic Verification
  → Design Extraction → Task Decomposition → Work → Storybook Verification
  → Design Verification → UX Verification → Gap Analysis
  → Gap Remediation → Goldmask Verification → Code Review (--deep)
  → Goldmask Correlation → Mend → Verify Mend → Design Iteration
  → Test → Test Coverage Critique → Pre-Ship Validation → Release Quality Check
  → Ship → Bot Review Wait → PR Comment Resolution → Merge

/rune:arc plans/my-plan.md
/rune:arc plans/my-plan.md --resume        # Resume from checkpoint
/rune:arc plans/my-plan.md --no-forge      # Skip forge enrichment
/rune:arc plans/my-plan.md --skip-freshness  # Bypass plan freshness check

Features: checkpoint-based resume, adaptive review-mend convergence loop (3 tiers: LIGHT/STANDARD/THOROUGH), diff-scoped review, co-author propagation.

How arc phases work: Arc uses Claude Code's Stop hook to drive the phase loop — when one phase finishes, the stop hook reads state from .rune/arc-phase-loop.local.md, determines the next phase, and re-injects a prompt. Each phase is literally a new Claude Code turn with its own fresh context window. This solves the context degradation problem (phase 18 gets the same quality as phase 1) but means the stop hook chain is a critical path — a bug in any hook silently breaks the pipeline. See docs/state-machine.md for the full phase graph.

<a name="strive"></a> /rune:strive — Swarm Execution

Self-organizing workers parse a plan into tasks and claim them independently:

/rune:strive plans/my-plan.md
/rune:strive plans/my-plan.md --approve    # Require human approval per task

<a name="appraise"></a> /rune:appraise — Code Review

Multi-agent review of your git diff with up to 8 specialized Ashes:

/rune:appraise                # Standard review
/rune:appraise --deep         # Multi-wave deep review (up to 18 Ashes across 3 waves)

Built-in reviewers include: Ward Sentinel (security), Pattern Seer (consistency), Flaw Hunter (logic bugs), Ember Oracle (performance), Depth Seer (missing logic), and more. Stack-aware intelligence auto-adds specialist reviewers based on your tech stack.

<a name="audit"></a> /rune:audit — Codebase Audit

Full-scope analysis of your entire codebase (not just the diff):

/rune:audit                   # Deep audit (default)
/rune:audit --standard        # Standard depth
/rune:audit --deep            # Multi-wave investigation
/rune:audit --incremental     # Stateful audit with priority scoring and coverage tracking

<a name="mend"></a> /rune:mend — Fix Findings

Parse a TOME (aggregated review findings) and dispatch parallel fixers:

/rune:mend tmp/reviews/{id}/TOME.md

<a name="forge"></a> /rune:forge — Plan Enrichment

Deepen a plan with Forge Gaze — topic-aware agent matching that selects the best specialists for each section:

/rune:forge plans/my-plan.md
/rune:forge plans/my-plan.md --exhaustive  # Lower threshold, more agents

<a name="goldmask"></a> /rune:goldmask — Impact Analysis

Three-layer analysis: Impact (what changes), Wisdom (why it was written that way), Lore (how risky the area is):

/rune:goldmask                # Analyze current diff

<a name="inspect"></a> /rune:inspect — Gap Audit

Compares a plan against its implementation across 10 quality dimensions:

/rune:inspect plans/my-plan.md
/rune:inspect plans/my-plan.md --focus "auth module"

<a name="elicit"></a> /rune:elicit — Structured Reasoning

24 curated methods for structured thinking: Tree of Thoughts, Pre-mortem Analysis, Red Team vs Blue Team, 5 Whys, ADR, and more.

/rune:elicit

Agents

116 specialized agents (74 core + 42 extended in registry):

Review Agents

Core reviewers active in every /rune:appraise and /rune:audit run. UX and design reviewers (below) are conditionally activated for frontend files. Stack specialists are additionally auto-activated based on detected tech stack:

UX & Design Reviewers (conditionally activated for frontend files):

Stack Specialists (auto-activated by detected tech stack):

Investigation Agents

Used by /rune:goldmask, /rune:inspect, and /rune:audit --deep:

Research Agents

Work Agents

Utility Agents

Testing Agents

QA Agents

Meta-QA Agents

Skills

44 skills providing background knowledge, workflow orchestration, and tool integration. Source of truth: plugins/rune/CLAUDE.md.

Configuration

Rune v3.x ships with hardcoded defaults — there is no talisman.yml config layer. See plugins/rune/references/v3-defaults.md for the full inventory of baked-in values across arc, audit, devise, gates, goldmask, inspect, integrations, misc, plan, pr_comment, process_management, review, settings, teammate_lifecycle, testing, ux, and work sections.

To deviate from a baked default, use one of the override paths documented in v3-defaults.md:

1. Per-session env vars — A subset of defaults are env-readable (${VAR:-default} patterns in scripts). Set the env var in .envrc or your shell profile.
2. Local fork of an agent definition — Custom Ashes are wired in the orchestration layer rather than configured. Place your custom agent at .claude/agents/<name>.md and update the relevant skill's summon list. See custom-ashes.md for the wiring contract.

Migration note for v2.x users: Existing .rune/talisman.yml is silently ignored in v3.x. SessionStart warns once when this file is detected. To restore prior behavior, pin to v2.x in your marketplace.json.

Architecture

rune/
├── .claude-plugin/
│   └── marketplace.json          # Marketplace registry
└── plugins/
    └── rune/                     # Main plugin
        ├── .claude-plugin/
        │   └── plugin.json       # Plugin manifest (see plugin.json for current version)
        ├── agents/               # 74 core agent definitions
        │   ├── investigation/    #   23 investigation agents
        │   ├── utility/          #   16 utility agents
        │   ├── review/           #   13 review agents
        │   ├── meta-qa/          #    9 meta-QA agents
        │   ├── research/         #    7 research agents
        │   ├── work/             #    5 work agents
        │   ├── qa/               #    1 QA verifier (parametric, manifest-driven)
        │   └── shared/           #   13 shared resources (templates, protocols)
        ├── registry/             # 42 extended agents
        ├── skills/               # 44 skills
        ├── commands/             # 11 slash commands
        ├── hooks/                # Event-driven hooks
        │   └── hooks.json
        ├── scripts/              # Hook & utility scripts (256 .sh/.py files)
        ├── .mcp.json             # MCP server config (echo-search, agent-search, context7)
        ├── CLAUDE.md             # Plugin instructions
        ├── CHANGELOG.md
        └── README.md             # Detailed component reference

State Machine Reference

Every Rune workflow is an explicit state machine with named phases, conditional gates, and error recovery tiers. See docs/state-machine.md for mermaid diagrams of all 10 workflows — useful for debugging pipeline failures, understanding phase transitions, and verifying correctness.

Key Concepts

Known Gotchas

A few things to know when working with Rune — especially if you're debugging a pipeline failure or writing custom hooks/scripts:

See the Troubleshooting guide for more operational details.

Requirements & Compatibility

Windows: Not currently supported. WSL2 with Ubuntu may work but is untested.

Resources Overview

Links

• Detailed component reference — all agents, skills, commands, hooks
• Documentation hub — start here to choose the right user guide
• GLM-5 setup guide — use GLM-5 with Rune for budget-friendly agent teams
• Rune user guide (English): arc + arc-batch — operational guide with greenfield/brownfield use cases
• Hướng dẫn Rune (Tiếng Việt): arc + arc-batch — hướng dẫn vận hành kèm use case greenfield/brownfield
• Rune planning guide (English): devise + forge + plan-review + inspect — how to write and validate plan files correctly
• Hướng dẫn planning Rune (Tiếng Việt): devise + forge + plan-review + inspect — cách lập plan và review plan đúng chuẩn
• Rune code review and audit guide (English): appraise + audit + mend — multi-agent review, codebase audit, and finding resolution
• Hướng dẫn review và audit Rune (Tiếng Việt): appraise + audit + mend — review đa agent, audit codebase, và xử lý finding
• Rune work execution guide (English): strive + goldmask — swarm implementation and impact analysis
• Hướng dẫn thực thi Rune (Tiếng Việt): strive + goldmask — implementation swarm và phân tích tác động
• Rune advanced workflows guide (English) — debug, goldmask, variant-hunt, self-audit
• Hướng dẫn workflow nâng cao Rune (Tiếng Việt) — debug, goldmask, variant-hunt, self-audit
• Rune getting started guide (English) — quick start for first-time users
• Hướng dẫn bắt đầu nhanh Rune (Tiếng Việt) — hướng dẫn nhanh cho người mới
• Thuật ngữ Rune (Tiếng Việt) — bảng giải thích thuật ngữ ngắn gọn
• Rune command reference (English) — complete slash-command catalog by workflow
• Bảng tra lệnh Rune (Tiếng Việt) — danh mục đầy đủ lệnh slash theo workflow
• Rune custom agents and extensions (English) — build custom Ashes, CLI-backed reviewers, Forge Gaze integration
• Hướng dẫn custom agent và mở rộng Rune (Tiếng Việt) — xây dựng custom Ash, CLI reviewer, tích hợp Forge Gaze
• Rune troubleshooting and optimization (English) — debug failures, reduce token cost, tune performance
• Hướng dẫn xử lý sự cố và tối ưu Rune (Tiếng Việt) — chẩn đoán lỗi, giảm token, tối ưu hiệu suất
• Rune engineering solutions (English) — 30 unique solutions across 200+ commits
• Giải pháp kỹ thuật Rune (Tiếng Việt) — 30 giải pháp đặc biệt qua hơn 200 commits
• State machine reference — mermaid diagrams of all 10 workflow state machines
• Changelog — release history

License

MIT