Set up a project

solomonar init installs the framework into one repository. It copies the rules, skills, and agent roles, writes small adapter files for your agent runtime, and creates the task registry. This page uses a new project called ledger; the same steps work in an existing repository.

Preview the plan

Start in an empty directory. --git-init creates the Git repository for you; inside an existing repository it is ignored.

mkdir ledger && cd ledger
solomonar init --git-init --runtime claude --runtime codex \
  --objective "Shared expenses for small groups" --dry-run

--dry-run prints every file init would write and writes nothing:

Plan
  git        init -b main
  create     docs/solomonar/agents/adversarial-reviewer.md
  create     docs/solomonar/agents/correctness-reviewer.md
  ...
  create     .codex/agents/spec-reviewer.toml
  create     .solomonar/manifest.json
  registry   create refs/heads/workflow-state with an empty state.json
Would initialize solomonar 0.1.0 in /work/ledger
  39 files created

Choose runtimes with --runtime claude, --runtime codex, both, or --runtime none. Without the flag, init selects each runtime whose executable it finds on your PATH.

Initialize

Run the same command with --yes instead of --dry-run. In a script or an agent's shell, init refuses to write without --yes.

solomonar init --git-init --runtime claude --runtime codex \
  --objective "Shared expenses for small groups" --yes

Initialized solomonar 0.1.0 in /work/ledger
  39 files created
  registry  refs/heads/workflow-state @ d769ccf0e2985d73a01b442fb0556fb8854de1fe

Next:
  1. First commit required before task worktrees:
       git add AGENTS.md CLAUDE.md .claude .agents .codex .solomonar docs && git commit -m "chore: initialize solomonar 0.1.0"
  2. Start a top-level session in /work/ledger with your selected outcome:
       Claude Code: /solomonar Explore the next useful flow.
       Codex:       $solomonar Explore the next useful flow.
       Portable:    Use the solomonar skill to explore the next useful flow.
warning: no remote "origin"; the registry stays local

The warning is expected in a new repository. Once you add an origin remote, the CLI publishes the registry there after each task update.

Make the first commit

Task worktrees branch from main, so main needs a commit. Run the command from step 1 of the output:

git add AGENTS.md CLAUDE.md .claude .agents .codex .solomonar docs
git commit -m "chore: initialize solomonar 0.1.0"

What init created

The adapter files are short stubs that point to docs/solomonar/. The real instructions live in one place, whatever runtime you use. The configuration reference lists every file and who owns it.

Open docs/README.md and fill in the mission and intended users. Agents read it at the start of each task.

In an existing repository

Run init from anywhere inside the repository; it writes at the worktree root. Your files are safe:

• An existing AGENTS.md is adopted: the framework section goes on top and your content moves under ## Project notes. Pass --overwrite AGENTS.md to replace it instead.
• An existing CLAUDE.md is never changed. If it lacks an @AGENTS.md line, init tells you to add one.
• An existing docs/README.md is left alone.
• Any other file that differs from what init would write stops the run with a conflict. Choose per file with --keep <path> or --overwrite <path>.

If the repository already has an application, agents discover its build and test commands from your scripts and manifests. You do not need to describe them up front.

Running init again

init is safe to repeat. With the same choices and unchanged files, it does nothing:

Already initialized with solomonar 0.1.0; nothing to do.

It never changes a recorded choice, such as the runtimes. Those will change through the planned runtime and extension commands. Extensions cannot be chosen at init yet; --ext none is the only accepted value today.

Next

The project is ready. Run your first task.