{"id":"0777a708-7790-42dd-a8b2-233e061d34fd","slug":"devrune","kind":"mcp","name":"DevRune","summary":"DevRune is a Go CLI tool that configures AI development agents by resolving, fetching, and materializing packages of skills, rules, MCP server definitions, and **workflows** into developer workspaces.","owner":"davidarce","repoUrl":"https://github.com/davidarce/DevRune","license":"MIT","licenseTier":"permissive","trust":"community","stars":8,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-03-22T19:52:39.000Z","addedAt":"2026-10-21T17:03:00.107Z","logoUrl":"https://avatars.githubusercontent.com/u/13999850?u=919e4ee74567f4acafe874b220e58f1f01b8e98b&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra"],"tags":[],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T22:28:29.994Z","sample":false,"url":"https://conduits.dev/tools/devrune","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<p align=\"center\">\n  <img src=\"https://img.shields.io/badge/Go-1.26+-00ADD8?style=flat&logo=go&logoColor=white\" alt=\"Go 1.26+\">\n  <img src=\"https://img.shields.io/github/v/release/davidarce/DevRune?style=flat&color=8B5CF6\" alt=\"Release\">\n  <img src=\"https://img.shields.io/github/actions/workflow/status/davidarce/DevRune/ci.yml?label=CI&style=flat\" alt=\"CI\">\n  <img src=\"https://img.shields.io/github/license/davidarce/DevRune?style=flat&color=gray\" alt=\"License\">\n</p>\n\n<p align=\"center\">\n\n```\n██████╗ ███████╗██╗   ██╗██████╗ ██╗   ██╗███╗   ██╗███████╗\n██╔══██╗██╔════╝██║   ██║██╔══██╗██║   ██║████╗  ██║██╔════╝\n██║  ██║█████╗  ██║   ██║██████╔╝██║   ██║██╔██╗ ██║█████╗\n██║  ██║██╔══╝  ╚██╗ ██╔╝██╔══██╗██║   ██║██║╚██╗██║██╔══╝\n██████╔╝███████╗ ╚████╔╝ ██║  ██║╚██████╔╝██║ ╚████║███████╗\n╚═════╝ ╚══════╝  ╚═══╝  ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚══════╝\n```\n\n</p>\n\n<p align=\"center\">\n  <strong>One manifest, every agent.</strong>\n  <br>\n  <em>A package manager for AI agent instructions — with <a href=\"#-spec-driven-development-the-first-citizen\">Spec-Driven Development</a> built in.</em>\n</p>\n\n---\n\n## Why DevRune?\n\nConfiguring AI development agents used to mean juggling `.claude/`, `.agents/`, `.codex/`, `.github/`, and `.factory/` by hand — copying skill files, deduplicating rules, wiring MCP servers, hoping every agent sees the same context.\n\n**DevRune makes that a solved problem.** You declare what you want in a single `devrune.yaml`; DevRune resolves it, locks it, and materializes the right files into each agent's native format.\n\n- 📦 **Package-manager model** — sources, selection, lockfile, cache, reproducibility.\n- 🧠 **Spec-Driven Development (SDD) as first-citizen** — 4-phase workflow with model routing, advisor guidance, and compaction recovery. See [the SDD section](#-spec-driven-development-the-first-citizen).\n- 🤖 **5 agents supported** — Claude Code, OpenCode, Codex, Copilot, Factory. One source of truth, five native workspaces.\n- 🪄 **Interactive TUI** — a guided wizard for first-time setup, project-type detection, and model selection.\n- 🔄 **Safe updates** — `devrune sync` re-resolves, re-installs, and tracks drift via a state file.\n\n---\n\n## Table of Contents\n\n- [Quick Start](#-quick-start)\n- [Supported Agents](#-supported-agents)\n- [Spec-Driven Development (the first citizen)](#-spec-driven-development-the-first-citizen)\n- [The Starter Catalog](#-the-starter-catalog)\n- [CLI Reference](#-cli-reference)\n- [Manifest Format](#-manifest-format)\n- [How It Works](#-how-it-works)\n- [Installation](#-installation)\n- [Development](#-development)\n- [Releases](#-releases)\n- [Community & Support](#-community--support)\n- [License](#-license)\n\n---\n\n## 🚀 Quick Start\n\n### 1. Install DevRune\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/davidarce/DevRune/main/install.sh | bash\n```\n\nOther methods: [Installation](#-installation).\n\n### 2. Launch the wizard\n\n```bash\ndevrune init\n```\n\nThe TUI walks you through **agents → SDD overview → content → model selection → confirm**. It detects your project tech stack and pre-selects the relevant advisors and rules.\n\n### 3. Or start from a manifest\n\nDrop a `devrune.yaml` in your repo root:\n\n```yaml\nschemaVersion: devrune/v1\n\nagents: [claude, opencode]\n\npackages:\n  - source: github:davidarce/devrune-starter-catalog@main\n    select:\n      skills: [git-commit, architect-advisor, unit-test-advisor]\n      rules: [architecture/clean-architecture, testing/mother-pattern]\n\nmcps:\n  - source: github:davidarce/devrune-starter-catalog@main//mcps/engram.yaml\n\nworkflows:\n  - source: github:davidarce/devrune-starter-catalog@main//workflows/sdd\n```\n\nThen:\n\n```bash\ndevrune sync\n```\n\nYour agents pick up the new skills, rules, MCPs, and the SDD workflow on the next turn.\n\n---\n\n## 🤖 Supported Agents\n\nDevRune configures all of these from a single manifest — each agent receives files in its **native format**, not a lowest-common-denominator abstraction.\n\n| Agent               | Workspace            | Catalog File              | MCP Config        | Notes                                                          |\n|---------------------|----------------------|---------------------------|-------------------|----------------------------------------------------------------|\n| **Claude Code**     | `.claude/`           | `CLAUDE.md`               | `.mcp.json`       | Canonical format. Skill frontmatter is native. Hooks supported. |\n| **OpenCode**        | `.opencode/`         | `.agents/AGENTS.md`       | `opencode.json`   | Shares `.agents/skills/` with Codex & Factory. Model routing.   |\n| **Codex (OpenAI)**  | `.codex/`            | `.agents/AGENTS.md`       | `config.toml`     | Shares `.agents/skills/`. TOML MCP config.                     |\n| **GitHub Copilot**  | `.github/`           | `copilot-instructions.md` | `.mcp.json`       | Generates `.agent.md` wrappers for `@agent-name` invocation.   |\n| **Factory Droid**   | `.factory/`          | `.agents/AGENTS.md`       | `mcp.json`        | Shares `.agents/skills/`. Factory-native permissions format.   |\n\nAdding a new agent is a matter of writing an `agents/{name}.yaml` definition and a renderer in `internal/materialize/renderers/`. See [Development](#-development).\n\n---\n\n## 🧠 Spec-Driven Development (the first citizen)\n\n> **SDD is how DevRune thinks about building software.** It's not a template you opt into; it's the flagship workflow installed and orchestrated natively.\n\nInstead of yolo-coding, SDD breaks a change into **four disciplined phases** — each with its own sub-agent, model, and artifacts — and hands orchestration to a dedicated coordinator. You keep control; the agents stay on the rails.\n\n### The 4 phases\n\n```\n┌─────────────┐     ┌──────────┐     ┌───────────────┐     ┌─────────────┐\n│ ① Explore   │ ──▶ │ ② Plan   │ ──▶ │ ③ Implement   │ ──▶ │ ④ Review    │\n│             │     │          │     │   (waves)     │     │             │\n│ exploration │     │ plan.md  │     │ code changes  │     │ review.md   │\n│    .md      │     │          │     │ [X] markers   │     │             │\n└─────────────┘     └──────────┘     └───────────────┘     └─────────────┘\n   Sonnet             Opus             Sonnet                 Opus\n```\n\n| Phase          | What it does                                                                                     | Output                          |\n|----------------|--------------------------------------------------------------------------------------------------|---------------------------------|\n| **① Explore**  | Scans the codebase, curates the files that matter, surfaces ambiguities.                         | `.sdd/{change}/exploration.md`  |\n| **② Plan**     | Deep interview → machine-parsable task plan with batch table, dependencies, and quality gates.    | `.sdd/{change}/plan.md`         |\n| **③ Implement**| Executes tasks in parallel/sequential waves, fails fast, updates `[X]` markers per batch.         | Code + updated `plan.md`        |\n| **④ Review**   | Diffs against the plan, flags regressions, decides commit vs. fix.                                | `.sdd/{change}/review.md`       |\n\n### The Advisor Strategy (guidance loop)\n\nDuring Plan, the planner (Sonnet) identifies when a domain specialist is needed and returns a **`guidance_requested`** envelope. The orchestrator launches advisor sub-agents (Opus) in parallel:\n\n```\nsdd-plan (Sonnet) ─┐\n                   ├─ detects gap → guidance_requested\n                   ▼\nOrchestrator ──── launches advisors (Opus) in parallel\n                   │       architect · api-first · unit-test · component · a11y ...\n                   ▼\nOrchestrator ──── re-enters sdd-plan with advisor recommendations\n                   │\n                   ▼\nsdd-plan ──── status: ok → crit review → implement\n```\n\nEach advisor returns **Strengths / Issues / Recommendations** and persists full guidance to engram (when available). **Advisors never execute code** — they only advise.\n\n### Compaction recovery\n\nLong SDD sessions survive context compaction. DevRune installs per-agent hooks that preserve `.sdd/{change}/state.yaml` and re-inject a CRITICAL recovery prompt on session restart:\n\n| Agent             | Tier | Mechanism                                                          |\n|-------------------|:----:|--------------------------------------------------------------------|\n| Claude Code       | 1a   | `PreCompact` + `SessionStart(compact)` hooks in `settings.json`    |\n| Factory           | 1b   | `PreCompact` hook in `settings.json`                               |\n| OpenCode          | 2    | TypeScript plugin auto-loaded from `.opencode/plugins/`             |\n| Codex / Copilot   | 3    | Catalog-only recovery via `REGISTRY.md` instructions               |\n\n### Model routing per phase\n\nDevRune's TUI offers a **SDD Phase Models** step where you pick a model for each role (Explore, Plan, Implement, Review, Advisor) per agent. Pick Opus where depth matters; Sonnet where speed does. Reconfigurable anytime via `devrune` main menu → `Configure Models`.\n\n**GitHub Copilot tier constraint** — Copilot sub-agents cannot use a model with a higher cost tier than the orchestrator (VS Code enforces this). The TUI enforces this at selection time: pick the orchestrator model first and the phase cards automatically filter to only show models within that tier. The orchestrator model is written to the `.agent.md` frontmatter so VS Code picks it up directly.\n\n### Where the SDD logic lives\n\n**DevRune** owns the resolver, renderers, materializer, state tracking, hooks injection, and TUI flow.\n**[devrune-starter-catalog](https://github.com/davidarce/devrune-starter-catalog)** owns the SDD skills, orchestrator, templates, hooks, and plugin — the workflow's *content*.\n\n> 📖 Deep dive: the starter catalog's [`workflows/sdd/`](https://github.com/davidarce/devrune-starter-catalog/tree/main/workflows/sdd) directory has `ORCHESTRATOR.md`, the four phase skills, and shared contracts (envelope, launch-templates, advisor-templates, persistence, recovery).\n\n---\n\n## 📚 The Starter Catalog\n\nDevRune works with **any catalog** that follows the directory contract (`skills/`, `rules/`, `mcps/`, `workflows/`, `tools/`). The **[devrune-starter-catalog](https://github.com/davidarce/devrune-starter-catalog)** is the curated default — it ships the SDD workflow plus:\n\n- **11 skills** — 7 advisors (architect, api-first, unit-test, integration-test, component, frontend-test, a11y), `git-commit`, `git-pull-request`, `review-pr`, `arch-flow-explorer`.\n- **11 rules** — architecture (clean-arch, Beck's 4 rules), API standards, Java/Spring, React, testing patterns, microfrontends, a11y.\n- **6 MCPs** — Atlassian, Context7, Engram, Exa, Playwright, Ref.\n- **2 developer tools** — Crit (plan review), Engram (persistent memory) — auto-installed via Homebrew when the matching workflow/MCP is selected.\n\nFork it, trim it, extend it — it's MIT. Point DevRune at your own `github:org/my-catalog` and the same machinery works.\n\n---\n\n## 🧰 CLI Reference\n\n| Command                | What it does                                                                                         |\n|------------------------|------------------------------------------------------------------------------------------------------|\n| `devrune`              | Launches the interactive menu (Setup · Sync · Status · Configure Models · Upgrade · Uninstall).     |\n| `devrune init`         | Guided TUI wizard: agents → SDD overview → content → models → confirm → install.                     |\n| `devrune sync`         | One-shot `resolve` + `install`. Use this after editing `devrune.yaml`.                               |\n| `devrune resolve`      | Fetches packages, computes content hashes, writes `devrune.lock`. Network-only stage.                |\n| `devrune install`      | Reads `devrune.lock` and materializes workspace files. No network.                                   |\n| `devrune status`       | Shows installed state and whether the workspace is in sync with the lockfile.                        |\n| `devrune cache clean`  | Drops cached package data. Flags: `--packages-only`, `--recommend-only`.                             |\n| `devrune upgrade`      | Self-upgrades the DevRune binary to the latest release.                                              |\n| `devrune uninstall`    | Removes materialized skills, rules, MCPs, and workflows from the workspace.                          |\n| `devrune version`      | Prints version, commit, and build date.                                                              |\n\nRun `devrune <command> --help` for flags.\n\n---\n\n## 📝 Manifest Format\n\nA minimal, idiomatic `devrune.yaml`:\n\n```yaml\nschemaVersion: devrune/v1\n\nagents: [claude, opencode]               # which agents to configure\n\npackages:\n  - source: github:davidarce/devrune-starter-catalog@main\n    select:\n      skills: [git-commit, architect-advisor]\n      rules:  [architecture/clean-architecture]\n\nmcps:\n  - source: github:davidarce/devrune-starter-catalog@main//mcps/engram.yaml\n\nworkflows:\n  - source: github:davidarce/devrune-starter-catalog@main//workflows/sdd\n    models:                              # optional — per-role overrides\n      claude:\n        sdd-planner: opus\n        sdd-implementer: sonnet\n        sdd-advisor:   opus\n\ninstall:\n  linkMode: copy                         # copy | symlink | hardlink\n  rulesMode: individual                  # per-agent: concat | individual | both\n  autoRecommend: true                    # AI-powered recommendations during init\n```\n\n### Source refs\n\n| Form                                       | Example                                                                  |\n|--------------------------------------------|--------------------------------------------------------------------------|\n| `github:owner/repo@ref[//subpath]`         | `github:davidarce/devrune-starter-catalog@main//workflows/sdd`           |\n| `gitlab:owner/repo@ref[//subpath][?host=]` | `gitlab:team/catalog@v2?host=gitlab.example.com`                         |\n| `local:./path`                             | `local:./my-catalog`                                                     |\n\n### Generated artifacts\n\n| File                   | Purpose                                                                           |\n|------------------------|-----------------------------------------------------------------------------------|\n| `devrune.yaml`         | Your source of truth (hand-edited).                                               |\n| `devrune.lock`         | Resolved state: content hashes, parsed manifests, workflow metadata.              |\n| `.devrune/state.yaml`  | What was materialized. Used for drift detection and clean uninstall.              |\n\n---\n\n## 🛠️ How It Works\n\nDevRune runs as a three-stage pipeline:\n\n```\ndevrune.yaml  ──► [Resolve]  ──► devrune.lock  ──► [Install]  ──► workspace\n                      ▲              (hashes)          ▼           (.claude/,\n                      │                                │            .agents/,\n                  ~/.cache/devrune/                    │            .github/...)\n                   (content-addressed)                 │\n                                                       ▼\n                                              .devrune/state.yaml\n                                               (drift detection)\n```\n\n1. **Resolve** — fetches every `source:` (GitHub/GitLab/local), computes SHA-256 hashes, stores archives in a content-addressed cache (`~/.cache/devrune/`), and writes `devrune.lock`.\n2. **Install** — reads the lock, runs agent-specific **renderers** that know how each agent's files must look (Claude keeps native frontmatter; OpenCode transforms it; Copilot generates `.agent.md` wrappers; Codex emits TOML).\n3. **State** — writes `.devrune/state.yaml` listing every materialized path + the lock hash. `devrune status` compares this to detect drift; `devrune uninstall` uses it to remove exactly what was installed.\n\nWorkflows (like SDD) get special treatment: DevRune resolves the `workflow.yaml`, installs the phase skills, renders the orchestrator per agent, deep-merges hook JSON into settings, appends `.gitignore` entries, and registers the workflow in each agent's catalog file.\n\n---\n\n## 📥 Installation\n\n### Curl one-liner\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/davidarce/DevRune/main/install.sh | bash\n```\n\nPin a version:\n\n```bash\nVERSION=v0.1.27 curl -fsSL https://raw.githubusercontent.com/davidarce/DevRune/main/install.sh | bash\n```\n\nThe script detects your platform (`darwin-arm64`, `darwin-amd64`, `linux-amd64`), downloads the release tarball, and installs to `~/.local/bin` (override with `INSTALL_DIR`). It warns if another `devrune` is shadowing it on `PATH`.\n\n### go install\n\n```bash\ngo install github.com/davidarce/devrune/cmd/devrune@latest\n```\n\n### From source\n\n```bash\ngit clone https://github.com/davidarce/DevRune.git\ncd DevRune\nmake install          # builds and installs to ~/.local/bin\n```\n\n### Supported platforms\n\n| OS        | arch    | Status                         |\n|-----------|---------|--------------------------------|\n| macOS     | arm64   | ✅ Supported                    |\n| macOS     | amd64   | ✅ Supported                    |\n| Linux     | amd64   | ✅ Supported                    |\n| Linux     | arm64   | 🧪 Build from source            |\n| Windows   | —       | 🧪 Use WSL2                    |\n\n---\n\n## 👩‍💻 Development\n\n```bash\ngit clone https://github.com/davidarce/DevRune.git\ncd DevRune\n\nmake build     # builds ./devrune\nmake test      # runs the test suite\nmake lint      # golangci-lint\nmake fmt       # go fmt\nmake install   # builds + installs to ~/.local/bin\n```\n\n### Project layout\n\n```\nDevRune/\n├── cmd/devrune/              # CLI entry point\n├── internal/\n│   ├── cli/                  # cobra subcommands\n│   ├── tui/                  # Bubble Tea + Huh wizard\n│   ├── resolve/              # fetch + hash + lockfile\n│   ├── materialize/          # rendering + workspace writes\n│   │   └── renderers/        # per-agent transforms\n│   ├── state/                # .devrune/state.yaml\n│   ├── model/                # manifest, workflow, agent schemas\n│   └── …\n├── agents/                   # agent definitions (claude.yaml, …)\n├── testdata/                 # fixtures & golden files\n├── scripts/                  # maintenance scripts\n└── install.sh                # curl-one-liner installer\n```\n\n### Adding an agent\n\n1. Drop an `agents/{name}.yaml` describing workspace dirs, catalog file, MCP format, link-mode constraints, and any special transforms.\n2. Add a renderer in `internal/materialize/renderers/{name}.go` implementing the `Renderer` interface.\n3. Add fixture tests under `testdata/`.\n4. Open a PR — see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n### Adding a workflow, skill, rule, or MCP\n\nThese live in **catalogs**, not in DevRune. See the [devrune-starter-catalog README](https://github.com/davidarce/devrune-starter-catalog) for the format, or fork it to start your own.\n\n---\n\n## 🚀 Releases\n\nReleases are fully automated by [release-please](https://github.com/googleapis/release-please) and driven by [Conventional Commits](https://www.conventionalcommits.org/). You don't tag manually.\n\n**Flow**\n\n1. Land a PR on `main` with a Conventional Commit (`feat:` → minor, `fix:` → patch, `feat!:` / `BREAKING CHANGE:` → major after 1.0).\n2. release-please opens (or updates) a Release PR titled `chore: release X.Y.Z` with the version bump and a generated `CHANGELOG.md` diff.\n3. Merging that Release PR creates the `vX.Y.Z` tag, publishes the GitHub Release as **Latest**, and triggers GoReleaser in the same workflow to upload the Darwin/Linux binaries.\n\n**Notes**\n\n- Pre-1.0 (`0.x.y`): `feat!:` bumps minor, not major. Major is reserved for the deliberate `1.0.0` graduation.\n- `chore:`, `docs:`, `test:`, `ci:`, `build:`, `style:` are excluded from the changelog. Use `feat:` / `fix:` / `refactor:` / `perf:` for changelog-worthy work.\n- Tags created by `GITHUB_TOKEN` don't trigger downstream `on: push: tags` workflows, so GoReleaser is chained as a job inside `release-please.yml` rather than living in a standalone tag-triggered workflow.\n\n---\n\n## 🤝 Community & Support\n\n- 🐛 **Bugs & feature requests** — [open an issue](https://github.com/davidarce/DevRune/issues).\n- 🔐 **Security disclosures** — see [SECURITY.md](SECURITY.md). Please don't open public issues for vulnerabilities.\n- 🧭 **Contributing** — [CONTRIBUTING.md](CONTRIBUTING.md) covers the PR workflow.\n- 📜 **Code of Conduct** — [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) (Contributor Covenant).\n\nDevRune is pre-1.0 — the surface is still evolving. Breaking changes are documented in the [CHANGELOG](CHANGELOG.md).\n\n---\n\n## 📄 License\n\nMIT — see [LICENSE](LICENSE).\n\nCopyright (c) 2026 David Arce.\n"}