Spec-driven development for AI coding agents.
Shared specifications, focused tasks, independent reviews, and verified code.

Website · Documentation · CLI reference · Releases

What is Solomonar?

Solomonar is an open-source workflow for building software with AI coding agents. You agree on what the software should do, an agent builds one focused task against that agreement, separate agents review it, and a small CLI records every step in Git.

It has two parts:

• The framework: Markdown rules, skills, and agent roles that solomonar init installs into your repository under docs/solomonar/. Your agent runtime reads them. The core works with any programming language; extensions add the rules for your stack.
• The CLI: the solomonar binary. It installs, upgrades, and uninstalls the framework, adds and removes extensions, adds and removes the runtime adapters, and validates every task update against Git. It never calls a model, starts an agent, or stores review verdicts.

The name comes from Romanian folklore: a solomonar is a wizard who learns every secret from a single book and rides a dragon to command the storms. Solomonar gives your project its book (specs), its spells (skills), and its dragons (agents). Read the story behind the name.

Features

• Prototype before code. Demonstrate CLI, web, module/library, or service behavior, approve it, then extract specs and implement. Behavior changes repeat the loop; agents implement and review against agreed rules only.
• One orchestrator per task. The top-level session delegates the implementer and every reviewer, and owns the decisions it brings back to you.
• Independent, risk-based review. Security, correctness, and spec reviewers check the same committed revision in parallel. Risky changes also face an adversarial reviewer.
• Parallel tasks in isolated worktrees. Tasks start one at a time, run in parallel, and merge into main one at a time.
• A task record that cannot drift silently. State lives on a dedicated Git branch, is written only through checked CLI commands, and is compared with the real branch, worktree, and pull request on demand.
• Resume from Git, not from a conversation. You approve each task's implementation plan; every step becomes its own checkpoint commit. A new session continues the remaining steps from the plan and its commits.
• Small current docs, full history. Each finished task keeps a compact record; its final work spec stays in Git history.
• Runtime-agnostic. Claude Code, Codex, and GitHub Copilot CLI adapters point to one portable source of instructions.

Requirements

• macOS or Linux. Windows is not supported in v0.1.
• Git 2.40 or later.
• Claude Code, Codex, or GitHub Copilot CLI, to run the agent sessions.
• Optional: the GitHub CLI (gh), so task status can report pull requests and checks.
• To build from source: Go 1.27.3 or later.

The CLI needs no model-provider API key.

GitHub Copilot is supported through Copilot CLI only, not the IDE extensions or the cloud agent. Invoke /solomonar in an interactive session; prompt mode (copilot -p) cannot load the entry skill.

Installation

With Homebrew, on macOS and Linux:

brew install --cask madalinpopa/tap/solomonar

With Go:

go install github.com/madalinpopa/solomonar@latest

Prebuilt archives for macOS and Linux (amd64, arm64) are attached to each GitHub release. To build from source, see Development.

Check the installation:

solomonar version

See Install the CLI for upgrades, removal, and the JSON output.

Quick start

Initialize a project. In a terminal, solomonar init asks for the project's choices and shows the plan before it writes anything. In a script, pass the choices as flags with --yes:

mkdir ledger && cd ledger
solomonar init --git-init --runtime claude --ext go \
  --objective "Shared expenses for small groups" --yes

--ext go installs the Go rules. Without --ext, init selects extension-authoring in every project and go when a go.mod exists; add or remove extensions later with solomonar extension add|remove, and move to a newer framework with solomonar upgrade. solomonar uninstall removes the framework from a checkout again, keeping your notes, project extensions, decisions, and task history.

Make the first commit, because task worktrees branch from main. init prints the exact command for the runtimes you chose:

git add AGENTS.md CLAUDE.md .claude .solomonar docs
git commit -m "chore: initialize solomonar X.Y.Z"

Open a top-level agent session in the project and start every request with the solomonar skill:

Runtime	Example request
Claude Code	/solomonar Prototype adding a shared expense.
Codex	$solomonar Prototype adding a shared expense.
GitHub Copilot CLI	/solomonar Prototype adding a shared expense.
Any runtime	Use the solomonar skill to prototype adding a shared expense.

To install the Copilot adapter in a project with no recorded Solomonar choices, use --runtime copilot instead of --runtime claude. Follow the printed commit command: it lists individual Copilot files rather than the whole .github directory. init never changes recorded choices; in an already initialized project, change runtimes with the runtime commands:

solomonar runtime list
solomonar runtime add copilot --dry-run
solomonar runtime add copilot --yes
solomonar runtime remove copilot --yes

Each write prints the commit command for the changed adapter files. The runtime commands write no hooks or runtime settings.

With no request, the skill reports what is waiting on you and what can start next. Follow the tasks from your shell:

solomonar task show
solomonar task status W-001

Set up a project covers existing repositories and file conflicts. Run your first task follows one feature from prototype to merge.

Prototype workflow covers runnable CLI, web, module, and service examples, human approval, and the handoff into specifications and implementation.

Documentation

The website at solomonar.dev is the user documentation:

Start here	Learn the framework	Guides	Reference
Get started	How it works	Prototype workflow	CLI commands
Install the CLI	The task lifecycle	Task workflow	Project files
Set up a project	Task state	Troubleshooting
Run your first task	The story

Development

You need Go 1.27.3 or later and Task. Linters are pinned and installed into .bin/ on first use.

git clone https://github.com/madalinpopa/solomonar.git
cd solomonar
task build        # builds bin/solomonar
task check        # lint, tests with the race detector, and govulncheck, as CI runs them

Task	Purpose
task build	Build bin/solomonar.
task run -- <args>	Build and run the CLI, for example task run -- task show.
task test	Run all tests with the race detector.
task cover	Run the tests and print total coverage.
task fmt	Format the code.
task lint	Check that go.mod is tidy and run golangci-lint.
task security	Report known vulnerabilities reachable from the code.
task check	Run lint, all tests including the transcripts, and security checks.

Without Task, go build -trimpath -o bin/solomonar . and go test -race ./... work directly.

Repository layout

Path	Contents
main.go	Entry point; embeds assets/ into the binary.
internal/cli	Commands, flags, prompts, help, and output rendering.
internal/task	The task registry model, transitions, and fact checks.
internal/project	The desired-state plan for init, upgrade, and extension, the manifest, managed files, adapters, the extension catalog and store.
internal/git	The Git runner and repository discovery.
assets/framework	The framework core that init installs.
assets/extensions	The extension catalog.
assets/templates	Templates for AGENTS.md, docs/README.md, and the empty registry.
docs/	Design contracts, diagrams, and the logo.
site/	The documentation website; see site/README.md.

Contributing

Contributions are welcome. CONTRIBUTING.md covers the development setup, the documents to update with each change, commit conventions, and step-by-step guides with templates for adding framework rules, extension skills, and agents. For anything beyond a small fix, open an issue first to agree on the behavior.

The catalog holds go and the extension-authoring workflow skill, which init suggests in every project. Start it yourself: it researches, writes, and validates catalog extensions here, or project extensions in an adopting repository's docs/solomonar/extensions/<name>/, and hands off solomonar extension add <name>. The CLI, not the skill, activates an extension and tracks it in the manifest.

To report a problem, include the output of solomonar version, the command, the error code, and the relevant Git state, with secrets redacted. The troubleshooting guide lists what helps. Report security problems privately as SECURITY.md describes.

Releases

Maintainers release from main with task release:patch, task release:minor, or task release:major. The task updates framework version headers and current-build examples in the docs, site, and this README while preserving historical release and compatibility references. It commits those changes to main, then tags the commit and pushes the tag; the release workflow reruns CI, publishes the archives with GoReleaser, updates the Homebrew cask, and republishes the website.

License

Solomonar is released under the MIT License. Font and icon licenses for the website are listed in site/README.md.