SpecOrca

A spec-driven, two-role orchestration CLI for software tasks. An Architect decomposes work into precise specifications; an Agent executes each spec using a swappable coding backend (mock by default).


Package	`spec_orca`
CLI	`spec-orca`
Python	>= 3.11
License	MIT

What it does

SpecOrca runs an iterative loop:

The Architect reads a project state and produces a prioritised list of specifications (small, verifiable units of work).
The Agent picks the next spec, executes it through a coding backend, and reports the result.
The loop repeats until every spec is resolved or the Architect decides to stop.

The coding backend is an interface. SpecOrca ships with deterministic mock, Claude Code, and OpenAI Codex backends, but any backend that satisfies the Backend protocol can be substituted.

Prerequisites

Python >= 3.11
(Optional) Claude Code installed and on PATH if using the default backend.

Installation

# From a local clone (editable / development)
pip install -e ".[dev]"

# Production install (once published)
pip install spec-orca

Quickstart

# Verify the install
spec-orca --version

# Show available commands
spec-orca --help

# Create a minimal spec
spec-orca init --goal "Ship a greeting"

# Validate and print ordered specs
spec-orca plan --spec spec.yaml

# Run with the mock backend (no AI, deterministic)
spec-orca run --spec spec.yaml --backend mock --max-steps 1

# Run with Claude Code (requires claude CLI on PATH)
spec-orca run --spec spec.yaml --backend claude --max-steps 1 --allow-all

# Check environment health
spec-orca doctor --spec spec.yaml --backend claude

CLI reference

$ spec-orca --help
usage: spec-orca [-h] [--version] {run,plan,doctor,init,interview} ...

SpecOrca — a spec-driven two-role orchestrator (Architect / Agent).

options:
  -h, --help  show this help message and exit
  --version   show program's version number and exit

commands:
  run          Run the orchestration loop.
  plan         Validate and print the spec plan.
  doctor       Check environment health.
  init         Scaffold a new spec YAML file.
  interview    Start an interactive interview session.

Spec format

Spec files are YAML documents with the following schema:

Field	Type	Description
`goal`	string	High-level objective for the run.
`specs`	list	Ordered list of spec objects.

Each spec object contains:

Field	Type	Required	Description
`id`	string	yes	Unique identifier for the spec.
`title`	string	yes	Short human-readable title.
`description`	string	no	Longer explanation of the work.
`acceptance_criteria`	list[string]	yes	Conditions that must be met.
`dependencies`	list[string]	no	IDs of specs that must complete first.

Example:

goal: "Ship a greeting"
specs:
  - id: "greet"
    title: "Print hello"
    description: "Create a script that prints a greeting."
    acceptance_criteria:
      - "Program prints 'hello'."
    dependencies: []

Backend notes

The default backend is mock for deterministic execution. To use Claude Code, run with --backend claude and ensure the claude executable is available. To use a different backend, implement the Backend protocol defined in the package and pass it to the orchestrator at construction time. Backend documentation will expand as the interface stabilises.

Claude Code backend

Prerequisites:

Install Claude Code.
Ensure the CLI is on PATH and responding to claude -v.

Verify the environment:

claude -v
spec-orca doctor --backend claude --spec spec.yaml

Minimal run:

spec-orca run --backend claude --spec spec.yaml --max-steps 1 --allow-all

Tool permissions:

Claude Code runs in non-interactive (-p) mode, which denies all tool use by default. You must grant permissions or the agent will not be able to read, write, or execute anything.

The quickest way to get started is --allow-all, which grants access to every standard Claude Code tool (Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, NotebookEdit):

spec-orca run --backend claude --spec spec.yaml --max-steps 3 --allow-all

For tighter control, pass an explicit allowlist instead:

spec-orca run --backend claude --spec spec.yaml \
  --claude-allowed-tools "Read(*)" \
  --claude-allowed-tools "Write(*)" \
  --claude-allowed-tools "Edit(*)" \
  --claude-disallowed-tools "Bash(*)"

You can also block specific tools with --claude-disallowed-tools or restrict to an exact set with --claude-tools.

Claude configuration precedence (highest to lowest):

CLI flags
Config file (spec-orca.toml or [tool.spec_orca] in pyproject.toml)
Environment variables (CLAUDE_CODE_*)
Defaults

Config example:

[tool.spec_orca]
claude_bin = "claude"
claude_allowed_tools = ["read:*", "write:*"]
claude_disallowed_tools = ["rm:*"]
claude_tools = ["edit", "read"]
claude_max_turns = 4
claude_max_budget_usd = 2.5
claude_timeout_seconds = 300
claude_no_session_persistence = true

Codex backend

Prerequisites:

Install the OpenAI Codex CLI and ensure codex is on PATH.
Verify the binary and doctor checks:

codex --version
spec-orca doctor --backend codex --spec spec.yaml

Minimal run:

spec-orca run --backend codex --spec spec.yaml --max-steps 1

Model and timeout options:

spec-orca run --backend codex --spec spec.yaml \
  --codex-model gpt-5-codex \
  --codex-timeout-seconds 1800

Execution notes:

SpecOrca invokes Codex as codex exec --full-auto --json "<prompt>".
--full-auto enables unattended tool execution. Use it only in trusted repos.
Codex configuration precedence (highest to lowest):
1. CLI flags (--codex-bin, --codex-model, --codex-timeout-seconds)
2. Config file (spec-orca.toml or [tool.spec_orca] in pyproject.toml)
3. Environment variables (CODEX_EXECUTABLE, CODEX_MODEL, CODEX_TIMEOUT)
4. Defaults

Interactive interview

The interview command starts a guided requirements-gathering session. An AI interviewer helps you articulate goals, constraints, and acceptance criteria through a structured conversation flow:

Scoping — the interviewer asks what you want to achieve.
Choice — you pick between an improvement analysis or your own specific path.
Follow-up — the conversation continues with clarifying questions until requirements are clear.

At the end of the session the gathered requirements are compiled into a valid spec YAML file that can be fed directly into spec-orca run.

Prerequisites:

Install the package: pip install -e . (or pip install spec-orca)
The default backend is claude, which requires Claude Code installed and on PATH (claude -v should work).

# Start an interview (uses the claude backend by default)
spec-orca interview

# Save the generated spec to a file automatically
spec-orca interview --output spec.yaml

# Use the mock backend (no AI, for testing)
spec-orca interview --backend mock

Type quit or exit (or press Ctrl+C) to end the session. If you provided --output, the spec is saved automatically; otherwise you will be prompted for a save path.

Development

See CONTRIBUTING.md for full details.

# Install with dev dependencies
pip install -e ".[dev]"

# Run all checks (format, lint, typecheck, tests)
nox

# Run individual sessions
nox -s fmt             # auto-format
nox -s lint            # ruff lint
nox -s typecheck       # mypy strict
nox -s tests           # pytest + coverage

# Install pre-commit hooks
pre-commit install

Auto-commit (opt-in)

When iterating on this repository you can let SpecOrca commit changes automatically after each successful run:

# Commit with an auto-generated message
spec-orca run --spec spec.yaml --auto-commit

# Add a Conventional Commit prefix
spec-orca run --spec spec.yaml --auto-commit --commit-prefix feat

# Multi-step run with auto-commit
spec-orca run --spec spec.yaml --max-steps 3 --auto-commit --commit-prefix chore

Behaviour:

Off by default - auto-commit only runs when --auto-commit is passed.
Only tracked files are staged (git add -u).
No commit on a clean tree - if nothing changed, the commit is skipped.
No commit on failed runs - runs that exit non-zero never auto-commit.
Commit messages are single-line, normalized, and include the prefix when provided (e.g. feat: spec-orca run: Add widgets).
The git helper lives in spec_orca/dev/git.py and does not affect the core orchestration logic.

Project layout

src/spec_orca/           # installable package
tests/                   # pytest test suite
noxfile.py               # dev task runner
pyproject.toml           # PEP 621 metadata + tool config

Documentation

ARCHITECTURE.md — system design and module map
CHANGELOG.md — release history (Keep a Changelog)
CONTRIBUTING.md — how to contribute
CODE_OF_CONDUCT.md — community standards
SECURITY.md — vulnerability reporting

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
.github/workflows		.github/workflows
assets		assets
src/spec_orca		src/spec_orca
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
noxfile.py		noxfile.py
package.json		package.json
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

SpecOrca

What it does

Prerequisites

Installation

Quickstart

CLI reference

Spec format

Backend notes

Claude Code backend

Codex backend

Interactive interview

Development

Auto-commit (opt-in)

Project layout

Documentation

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

SpecOrca

What it does

Prerequisites

Installation

Quickstart

CLI reference

Spec format

Backend notes

Claude Code backend

Codex backend

Interactive interview

Development

Auto-commit (opt-in)

Project layout

Documentation

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages