Autonomous Software Evolution System

This repository contains a zero-dependency Python implementation of the PRD in AUTONOMOUS_SOFTWARE_EVOLUTION_SYSTEM_PRD.md.

The current v1 focuses on the control plane and safety model:

• repository snapshotting
• evidence-backed task generation
• bounded task selection with scoring and cooldowns
• branch locking and base-branch revalidation
• deterministic review guardrails
• baseline-aware validation
• run history and artifact storage outside the product repository
• optional external coder and pull request integrations

By default, the system is conservative. If no coder is configured, it analyzes the repository, selects a task, and then skips safely without mutating the repo.

Repository Layout

autonomous_dev/
  agents/
  orchestrator/
  repo/
ai/
  product_context.md
tests/

Important files:

• autonomous_dev/orchestrator/main.py: cycle orchestration and CLI
• autonomous_dev/repo/repo_snapshot.py: repository snapshot engine
• autonomous_dev/agents/planner_agent.py: candidate scoring and task brief generation
• autonomous_dev/agents/reviewer_agent.py: diff guardrail enforcement
• autonomous_dev/agents/tester_agent.py: baseline-aware validation

Prerequisites

• uv
• git installed and available on PATH
• a clean repository working tree before running a cycle
• at least one commit on the base branch

The orchestrator refuses to run if the repository is dirty or has no commits.

Bootstrapping With uv

Install the project environment:

UV_CACHE_DIR=/tmp/uv-cache uv sync

Run the test suite:

UV_CACHE_DIR=/tmp/uv-cache uv run python -m unittest discover -s tests -q

AI Context Files

The orchestrator expects this committed file inside the target repository:

• ai/product_context.md

CLI Usage

Show the built-in help:

UV_CACHE_DIR=/tmp/uv-cache uv run python -m autonomous_dev.orchestrator.main --help

Run an analysis-only cycle that skips safely before implementation:

UV_CACHE_DIR=/tmp/uv-cache uv run python -m autonomous_dev.orchestrator.main \
  --repo . \
  --base-branch main \
  --editable-path autonomous_dev/ \
  --editable-path tests/ \
  --editable-path ai/

Run a full cycle with commits enabled:

UV_CACHE_DIR=/tmp/uv-cache uv run python -m autonomous_dev.orchestrator.main \
  --repo . \
  --base-branch main \
  --editable-path autonomous_dev/ \
  --editable-path tests/ \
  --editable-path ai/ \
  --coder-command "/absolute/path/to/scripts/generic_coder_wrapper.py" \
  --commit

Run a full cycle with commit and pull request hooks:

UV_CACHE_DIR=/tmp/uv-cache uv run python -m autonomous_dev.orchestrator.main \
  --repo . \
  --base-branch main \
  --editable-path autonomous_dev/ \
  --editable-path tests/ \
  --editable-path ai/ \
  --coder-command "/absolute/path/to/scripts/generic_coder_wrapper.py" \
  --pr-command "/path/to/pr-wrapper" \
  --commit \
  --open-pr

External Command Integration

The built-in coder and PR integrations are intentionally generic. You provide wrapper scripts or executables, and the orchestrator passes context through environment variables.

This repository includes a generic coder wrapper at scripts/generic_coder_wrapper.py. By default it:

• reads the selected task_brief.json
• builds a bounded implementation prompt
• invokes the local codex exec CLI in the target repository

That wrapper is repo-agnostic. You can use the same file against any repository that has the required ai/ context files.

External coder command environment:

• AUTONOMOUS_DEV_REPO_PATH
• AUTONOMOUS_DEV_TASK_BRIEF_PATH
• AUTONOMOUS_DEV_RUN_PATH
• AUTONOMOUS_DEV_BASE_REF
• AUTONOMOUS_DEV_BRANCH_NAME

External PR command environment:

• AUTONOMOUS_DEV_REPO_PATH
• AUTONOMOUS_DEV_TASK_BRIEF_PATH
• AUTONOMOUS_DEV_BRANCH_NAME
• AUTONOMOUS_DEV_BASE_BRANCH

The coder command is expected to modify the repository in place. The PR command is expected to create a pull request through whatever mechanism you choose, for example gh, an internal tool, or a custom API wrapper.

Example using the included generic wrapper against another repository:

UV_CACHE_DIR=/tmp/uv-cache uv run python -m autonomous_dev.orchestrator.main \
  --repo /absolute/path/to/target-repo \
  --base-branch main \
  --editable-path app/ \
  --editable-path src/ \
  --editable-path tests/ \
  --editable-path ai/ \
  --coder-command "/Users/walterheck/Source/helixiora/internal/simple/scripts/generic_coder_wrapper.py" \
  --commit

If you want the wrapper to delegate to a different tool instead of Codex, switch it to command mode and provide a custom delegate:

AUTONOMOUS_DEV_DELEGATE_CMD="python /path/to/your_delegate.py" \
/Users/walterheck/Source/helixiora/internal/simple/scripts/generic_coder_wrapper.py --backend command

If your local uv cache directory is writable, you can omit UV_CACHE_DIR=/tmp/uv-cache. It is included above because this environment does not allow writing to the default Homebrew cache location.

Run Artifacts and History

Runtime state is stored inside this orchestrator repository by default under:

.autonomous_dev_runs/<target-repo-slug>/

Each run for a given target repository under that directory gets its own workspace with artifacts such as:

• repo_summary.json
• module_index.json
• dependency_graph.json
• analysis_report.json
• candidate_tasks.json
• task_brief.json
• implementation_result.json
• review_result.json
• validation_result.json
• cycle_outcome.json

Per-repository history is stored as JSON Lines in the runtime root.

Guardrails

The current implementation enforces these main policies:

• only one active cycle per repository and base branch
• temporary improvement branch creation by default
• no dependency manifest changes
• no edits under forbidden paths such as deployment/, terraform/, or .github/workflows/
• only allowlisted editable paths may be changed
• behavior-changing Python diffs require test changes
• diff size limits for files changed and lines changed
• validation compares the candidate against the base branch baseline when available

Current Limitations

• the analysis and planning layers are deterministic heuristics, not live model calls
• there is no built-in pull request provider; PR creation is delegated to an external command
• there is no built-in scheduler daemon; periodic execution is expected to come from cron, systemd, GitHub Actions, or another runner
• validation defaults to compileall and unittest discovery unless you extend the tester agent
• the repository under analysis must already contain committed AI context files

Suggested Next Steps

If you want to use this against a real repository, the practical next step is to write two tiny wrappers:

1. a coder wrapper that reads task_brief.json and calls your preferred coding tool
2. a PR wrapper that creates a pull request for an approved committed branch