spec-orca 0.1.0__tar.gz

spec_orca-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 spec-orchestrator contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spec_orca-0.1.0/PKG-INFO

@@ -0,0 +1,355 @@
+Metadata-Version: 2.4
+Name: spec-orca
+Version: 0.1.0
+Summary: SpecOrca — a spec-driven two-role orchestrator (Architect / Agent) with swappable coding backends.
+Author: SpecOrca contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dudujuju828/SpecOrca
+Project-URL: Repository, https://github.com/dudujuju828/SpecOrca
+Project-URL: Changelog, https://github.com/dudujuju828/SpecOrca/blob/master/CHANGELOG.md
+Project-URL: Issues, https://github.com/dudujuju828/SpecOrca/issues
+Keywords: orchestrator,architect,agent,cli,specorca
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: mypy>=1.13; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.0; extra == "dev"
+Requires-Dist: coverage[toml]>=7.4; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Requires-Dist: pre-commit>=4.0; extra == "dev"
+Requires-Dist: nox>=2024.4; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/specorca.png" alt="SpecOrca logo" width="200">
+</p>
+
+# SpecOrca
+
+[![CI](https://github.com/anthropics/spec-orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/anthropics/spec-orchestrator/actions/workflows/ci.yml)
+
+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](LICENSE) |
+
+## What it does
+
+SpecOrca runs an iterative loop:
+
+1. The **Architect** reads a project state and produces a prioritised list of
+   specifications (small, verifiable units of work).
+2. The **Agent** picks the next spec, executes it through a coding backend, and
+   reports the result.
+3. 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](https://docs.anthropic.com/en/docs/claude-code), and OpenAI
+Codex backends, but any backend that satisfies the `Backend` protocol can be
+substituted.
+
+## Prerequisites
+
+- Python >= 3.11
+- (Optional) [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+  installed and on `PATH` if using the default backend.
+
+## Installation
+
+```bash
+# From a local clone (editable / development)
+pip install -e ".[dev]"
+
+# Production install (once published)
+pip install spec-orca
+```
+
+## Quickstart
+
+```bash
+# 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:
+
+```yaml
+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](https://docs.anthropic.com/en/docs/claude-code).
+- Ensure the CLI is on `PATH` and responding to `claude -v`.
+
+Verify the environment:
+```bash
+claude -v
+spec-orca doctor --backend claude --spec spec.yaml
+```
+
+Minimal run:
+```bash
+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):
+
+```bash
+spec-orca run --backend claude --spec spec.yaml --max-steps 3 --allow-all
+```
+
+For tighter control, pass an explicit allowlist instead:
+
+```bash
+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):
+1) CLI flags
+2) Config file (`spec-orca.toml` or `[tool.spec_orca]` in `pyproject.toml`)
+3) Environment variables (`CLAUDE_CODE_*`)
+4) Defaults
+
+Config example:
+```toml
+[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:
+
+```bash
+codex --version
+spec-orca doctor --backend codex --spec spec.yaml
+```
+
+Minimal run:
+```bash
+spec-orca run --backend codex --spec spec.yaml --max-steps 1
+```
+
+Model and timeout options:
+```bash
+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:
+
+1. **Scoping** — the interviewer asks what you want to achieve.
+2. **Choice** — you pick between an improvement analysis or your own specific path.
+3. **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`.
+
+```bash
+# Start an interview with the mock backend
+spec-orca interview
+
+# Use a real backend for smarter follow-up questions
+spec-orca interview --backend claude
+
+# Save the generated spec to a file automatically
+spec-orca interview --backend claude --output spec.yaml
+```
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.
+
+```bash
+# 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:
+
+```bash
+# 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](ARCHITECTURE.md) — system design and module map
+- [CHANGELOG.md](CHANGELOG.md) — release history (Keep a Changelog)
+- [CONTRIBUTING.md](CONTRIBUTING.md) — how to contribute
+- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — community standards
+- [SECURITY.md](SECURITY.md) — vulnerability reporting

spec_orca-0.1.0/README.md

@@ -0,0 +1,319 @@
+<p align="center">
+  <img src="assets/specorca.png" alt="SpecOrca logo" width="200">
+</p>
+
+# SpecOrca
+
+[![CI](https://github.com/anthropics/spec-orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/anthropics/spec-orchestrator/actions/workflows/ci.yml)
+
+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](LICENSE) |
+
+## What it does
+
+SpecOrca runs an iterative loop:
+
+1. The **Architect** reads a project state and produces a prioritised list of
+   specifications (small, verifiable units of work).
+2. The **Agent** picks the next spec, executes it through a coding backend, and
+   reports the result.
+3. 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](https://docs.anthropic.com/en/docs/claude-code), and OpenAI
+Codex backends, but any backend that satisfies the `Backend` protocol can be
+substituted.
+
+## Prerequisites
+
+- Python >= 3.11
+- (Optional) [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+  installed and on `PATH` if using the default backend.
+
+## Installation
+
+```bash
+# From a local clone (editable / development)
+pip install -e ".[dev]"
+
+# Production install (once published)
+pip install spec-orca
+```
+
+## Quickstart
+
+```bash
+# 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:
+
+```yaml
+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](https://docs.anthropic.com/en/docs/claude-code).
+- Ensure the CLI is on `PATH` and responding to `claude -v`.
+
+Verify the environment:
+```bash
+claude -v
+spec-orca doctor --backend claude --spec spec.yaml
+```
+
+Minimal run:
+```bash
+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):
+
+```bash
+spec-orca run --backend claude --spec spec.yaml --max-steps 3 --allow-all
+```
+
+For tighter control, pass an explicit allowlist instead:
+
+```bash
+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):
+1) CLI flags
+2) Config file (`spec-orca.toml` or `[tool.spec_orca]` in `pyproject.toml`)
+3) Environment variables (`CLAUDE_CODE_*`)
+4) Defaults
+
+Config example:
+```toml
+[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:
+
+```bash
+codex --version
+spec-orca doctor --backend codex --spec spec.yaml
+```
+
+Minimal run:
+```bash
+spec-orca run --backend codex --spec spec.yaml --max-steps 1
+```
+
+Model and timeout options:
+```bash
+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:
+
+1. **Scoping** — the interviewer asks what you want to achieve.
+2. **Choice** — you pick between an improvement analysis or your own specific path.
+3. **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`.
+
+```bash
+# Start an interview with the mock backend
+spec-orca interview
+
+# Use a real backend for smarter follow-up questions
+spec-orca interview --backend claude
+
+# Save the generated spec to a file automatically
+spec-orca interview --backend claude --output spec.yaml
+```
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.
+
+```bash
+# 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:
+
+```bash
+# 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](ARCHITECTURE.md) — system design and module map
+- [CHANGELOG.md](CHANGELOG.md) — release history (Keep a Changelog)
+- [CONTRIBUTING.md](CONTRIBUTING.md) — how to contribute
+- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — community standards
+- [SECURITY.md](SECURITY.md) — vulnerability reporting