DevRune
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.
Ask AI about DevRune
Powered by Claude Β· Grounded in docs
I know everything about DevRune. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
βββββββ βββββββββββ ββββββββββ βββ βββββββ βββββββββββ
βββββββββββββββββββ ββββββββββββββ ββββββββ βββββββββββ
βββ βββββββββ βββ ββββββββββββββ βββββββββ βββββββββ
βββ βββββββββ ββββ βββββββββββββββ βββββββββββββββββββ
ββββββββββββββββ βββββββ βββ βββββββββββββββ ββββββββββββββ
βββββββ ββββββββ βββββ βββ βββ βββββββ βββ βββββββββββββ
One manifest, every agent.
A package manager for AI agent instructions β with Spec-Driven Development built in.
Why DevRune?
Configuring 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.
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.
- π¦ Package-manager model β sources, selection, lockfile, cache, reproducibility.
- π§ Spec-Driven Development (SDD) as first-citizen β 4-phase workflow with model routing, advisor guidance, and compaction recovery. See the SDD section.
- π€ 5 agents supported β Claude Code, OpenCode, Codex, Copilot, Factory. One source of truth, five native workspaces.
- πͺ Interactive TUI β a guided wizard for first-time setup, project-type detection, and model selection.
- π Safe updates β
devrune syncre-resolves, re-installs, and tracks drift via a state file.
Table of Contents
- Quick Start
- Supported Agents
- Spec-Driven Development (the first citizen)
- The Starter Catalog
- CLI Reference
- Manifest Format
- How It Works
- Installation
- Development
- Releases
- Community & Support
- License
π Quick Start
1. Install DevRune
curl -fsSL https://raw.githubusercontent.com/davidarce/DevRune/main/install.sh | bash
Other methods: Installation.
2. Launch the wizard
devrune init
The 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.
3. Or start from a manifest
Drop a devrune.yaml in your repo root:
schemaVersion: devrune/v1
agents: [claude, opencode]
packages:
- source: github:davidarce/devrune-starter-catalog@main
select:
skills: [git-commit, architect-advisor, unit-test-advisor]
rules: [architecture/clean-architecture, testing/mother-pattern]
mcps:
- source: github:davidarce/devrune-starter-catalog@main//mcps/engram.yaml
workflows:
- source: github:davidarce/devrune-starter-catalog@main//workflows/sdd
Then:
devrune sync
Your agents pick up the new skills, rules, MCPs, and the SDD workflow on the next turn.
π€ Supported Agents
DevRune configures all of these from a single manifest β each agent receives files in its native format, not a lowest-common-denominator abstraction.
| Agent | Workspace | Catalog File | MCP Config | Notes |
|---|---|---|---|---|
| Claude Code | .claude/ | CLAUDE.md | .mcp.json | Canonical format. Skill frontmatter is native. Hooks supported. |
| OpenCode | .opencode/ | .agents/AGENTS.md | opencode.json | Shares .agents/skills/ with Codex & Factory. Model routing. |
| Codex (OpenAI) | .codex/ | .agents/AGENTS.md | config.toml | Shares .agents/skills/. TOML MCP config. |
| GitHub Copilot | .github/ | copilot-instructions.md | .mcp.json | Generates .agent.md wrappers for @agent-name invocation. |
| Factory Droid | .factory/ | .agents/AGENTS.md | mcp.json | Shares .agents/skills/. Factory-native permissions format. |
Adding a new agent is a matter of writing an agents/{name}.yaml definition and a renderer in internal/materialize/renderers/. See Development.
π§ Spec-Driven Development (the first citizen)
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.
Instead 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.
The 4 phases
βββββββββββββββ ββββββββββββ βββββββββββββββββ βββββββββββββββ
β β Explore β βββΆ β β‘ Plan β βββΆ β β’ Implement β βββΆ β β£ Review β
β β β β β (waves) β β β
β exploration β β plan.md β β code changes β β review.md β
β .md β β β β [X] markers β β β
βββββββββββββββ ββββββββββββ βββββββββββββββββ βββββββββββββββ
Sonnet Opus Sonnet Opus
| Phase | What it does | Output |
|---|---|---|
| β Explore | Scans the codebase, curates the files that matter, surfaces ambiguities. | .sdd/{change}/exploration.md |
| β‘ Plan | Deep interview β machine-parsable task plan with batch table, dependencies, and quality gates. | .sdd/{change}/plan.md |
| β’ Implement | Executes tasks in parallel/sequential waves, fails fast, updates [X] markers per batch. | Code + updated plan.md |
| β£ Review | Diffs against the plan, flags regressions, decides commit vs. fix. | .sdd/{change}/review.md |
The Advisor Strategy (guidance loop)
During 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:
sdd-plan (Sonnet) ββ
ββ detects gap β guidance_requested
βΌ
Orchestrator ββββ launches advisors (Opus) in parallel
β architect Β· api-first Β· unit-test Β· component Β· a11y ...
βΌ
Orchestrator ββββ re-enters sdd-plan with advisor recommendations
β
βΌ
sdd-plan ββββ status: ok β crit review β implement
Each advisor returns Strengths / Issues / Recommendations and persists full guidance to engram (when available). Advisors never execute code β they only advise.
Compaction recovery
Long 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:
| Agent | Tier | Mechanism |
|---|---|---|
| Claude Code | 1a | PreCompact + SessionStart(compact) hooks in settings.json |
| Factory | 1b | PreCompact hook in settings.json |
| OpenCode | 2 | TypeScript plugin auto-loaded from .opencode/plugins/ |
| Codex / Copilot | 3 | Catalog-only recovery via REGISTRY.md instructions |
Model routing per phase
DevRune'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.
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.
Where the SDD logic lives
DevRune owns the resolver, renderers, materializer, state tracking, hooks injection, and TUI flow. devrune-starter-catalog owns the SDD skills, orchestrator, templates, hooks, and plugin β the workflow's content.
π Deep dive: the starter catalog's
workflows/sdd/directory hasORCHESTRATOR.md, the four phase skills, and shared contracts (envelope, launch-templates, advisor-templates, persistence, recovery).
π The Starter Catalog
DevRune works with any catalog that follows the directory contract (skills/, rules/, mcps/, workflows/, tools/). The devrune-starter-catalog is the curated default β it ships the SDD workflow plus:
- 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. - 11 rules β architecture (clean-arch, Beck's 4 rules), API standards, Java/Spring, React, testing patterns, microfrontends, a11y.
- 6 MCPs β Atlassian, Context7, Engram, Exa, Playwright, Ref.
- 2 developer tools β Crit (plan review), Engram (persistent memory) β auto-installed via Homebrew when the matching workflow/MCP is selected.
Fork it, trim it, extend it β it's MIT. Point DevRune at your own github:org/my-catalog and the same machinery works.
π§° CLI Reference
| Command | What it does |
|---|---|
devrune | Launches the interactive menu (Setup Β· Sync Β· Status Β· Configure Models Β· Upgrade Β· Uninstall). |
devrune init | Guided TUI wizard: agents β SDD overview β content β models β confirm β install. |
devrune sync | One-shot resolve + install. Use this after editing devrune.yaml. |
devrune resolve | Fetches packages, computes content hashes, writes devrune.lock. Network-only stage. |
devrune install | Reads devrune.lock and materializes workspace files. No network. |
devrune status | Shows installed state and whether the workspace is in sync with the lockfile. |
devrune cache clean | Drops cached package data. Flags: --packages-only, --recommend-only. |
devrune upgrade | Self-upgrades the DevRune binary to the latest release. |
devrune uninstall | Removes materialized skills, rules, MCPs, and workflows from the workspace. |
devrune version | Prints version, commit, and build date. |
Run devrune <command> --help for flags.
π Manifest Format
A minimal, idiomatic devrune.yaml:
schemaVersion: devrune/v1
agents: [claude, opencode] # which agents to configure
packages:
- source: github:davidarce/devrune-starter-catalog@main
select:
skills: [git-commit, architect-advisor]
rules: [architecture/clean-architecture]
mcps:
- source: github:davidarce/devrune-starter-catalog@main//mcps/engram.yaml
workflows:
- source: github:davidarce/devrune-starter-catalog@main//workflows/sdd
models: # optional β per-role overrides
claude:
sdd-planner: opus
sdd-implementer: sonnet
sdd-advisor: opus
install:
linkMode: copy # copy | symlink | hardlink
rulesMode: individual # per-agent: concat | individual | both
autoRecommend: true # AI-powered recommendations during init
Source refs
| Form | Example |
|---|---|
github:owner/repo@ref[//subpath] | github:davidarce/devrune-starter-catalog@main//workflows/sdd |
gitlab:owner/repo@ref[//subpath][?host=] | gitlab:team/catalog@v2?host=gitlab.example.com |
local:./path | local:./my-catalog |
Generated artifacts
| File | Purpose |
|---|---|
devrune.yaml | Your source of truth (hand-edited). |
devrune.lock | Resolved state: content hashes, parsed manifests, workflow metadata. |
.devrune/state.yaml | What was materialized. Used for drift detection and clean uninstall. |
π οΈ How It Works
DevRune runs as a three-stage pipeline:
devrune.yaml βββΊ [Resolve] βββΊ devrune.lock βββΊ [Install] βββΊ workspace
β² (hashes) βΌ (.claude/,
β β .agents/,
~/.cache/devrune/ β .github/...)
(content-addressed) β
βΌ
.devrune/state.yaml
(drift detection)
- Resolve β fetches every
source:(GitHub/GitLab/local), computes SHA-256 hashes, stores archives in a content-addressed cache (~/.cache/devrune/), and writesdevrune.lock. - 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.mdwrappers; Codex emits TOML). - State β writes
.devrune/state.yamllisting every materialized path + the lock hash.devrune statuscompares this to detect drift;devrune uninstalluses it to remove exactly what was installed.
Workflows (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.
π₯ Installation
Curl one-liner
curl -fsSL https://raw.githubusercontent.com/davidarce/DevRune/main/install.sh | bash
Pin a version:
VERSION=v0.1.27 curl -fsSL https://raw.githubusercontent.com/davidarce/DevRune/main/install.sh | bash
The 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.
go install
go install github.com/davidarce/devrune/cmd/devrune@latest
From source
git clone https://github.com/davidarce/DevRune.git
cd DevRune
make install # builds and installs to ~/.local/bin
Supported platforms
| OS | arch | Status |
|---|---|---|
| macOS | arm64 | β Supported |
| macOS | amd64 | β Supported |
| Linux | amd64 | β Supported |
| Linux | arm64 | π§ͺ Build from source |
| Windows | β | π§ͺ Use WSL2 |
π©βπ» Development
git clone https://github.com/davidarce/DevRune.git
cd DevRune
make build # builds ./devrune
make test # runs the test suite
make lint # golangci-lint
make fmt # go fmt
make install # builds + installs to ~/.local/bin
Project layout
DevRune/
βββ cmd/devrune/ # CLI entry point
βββ internal/
β βββ cli/ # cobra subcommands
β βββ tui/ # Bubble Tea + Huh wizard
β βββ resolve/ # fetch + hash + lockfile
β βββ materialize/ # rendering + workspace writes
β β βββ renderers/ # per-agent transforms
β βββ state/ # .devrune/state.yaml
β βββ model/ # manifest, workflow, agent schemas
β βββ β¦
βββ agents/ # agent definitions (claude.yaml, β¦)
βββ testdata/ # fixtures & golden files
βββ scripts/ # maintenance scripts
βββ install.sh # curl-one-liner installer
Adding an agent
- Drop an
agents/{name}.yamldescribing workspace dirs, catalog file, MCP format, link-mode constraints, and any special transforms. - Add a renderer in
internal/materialize/renderers/{name}.goimplementing theRendererinterface. - Add fixture tests under
testdata/. - Open a PR β see CONTRIBUTING.md.
Adding a workflow, skill, rule, or MCP
These live in catalogs, not in DevRune. See the devrune-starter-catalog README for the format, or fork it to start your own.
π Releases
Releases are fully automated by release-please and driven by Conventional Commits. You don't tag manually.
Flow
- Land a PR on
mainwith a Conventional Commit (feat:β minor,fix:β patch,feat!:/BREAKING CHANGE:β major after 1.0). - release-please opens (or updates) a Release PR titled
chore: release X.Y.Zwith the version bump and a generatedCHANGELOG.mddiff. - Merging that Release PR creates the
vX.Y.Ztag, publishes the GitHub Release as Latest, and triggers GoReleaser in the same workflow to upload the Darwin/Linux binaries.
Notes
- Pre-1.0 (
0.x.y):feat!:bumps minor, not major. Major is reserved for the deliberate1.0.0graduation. chore:,docs:,test:,ci:,build:,style:are excluded from the changelog. Usefeat:/fix:/refactor:/perf:for changelog-worthy work.- Tags created by
GITHUB_TOKENdon't trigger downstreamon: push: tagsworkflows, so GoReleaser is chained as a job insiderelease-please.ymlrather than living in a standalone tag-triggered workflow.
π€ Community & Support
- π Bugs & feature requests β open an issue.
- π Security disclosures β see SECURITY.md. Please don't open public issues for vulnerabilities.
- π§ Contributing β CONTRIBUTING.md covers the PR workflow.
- π Code of Conduct β CODE_OF_CONDUCT.md (Contributor Covenant).
DevRune is pre-1.0 β the surface is still evolving. Breaking changes are documented in the CHANGELOG.
π License
MIT β see LICENSE.
Copyright (c) 2026 David Arce.
