claude-autopilot 0.2.1__tar.gz

claude_autopilot-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]" --system
+
+      - name: Lint
+        run: |
+          uv run ruff check src/
+          uv run ruff format --check src/
+
+      - name: Test
+        run: uv run pytest tests/ -v

claude_autopilot-0.2.1/.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'overrides/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install "mkdocs>=1.6,<2" mkdocs-shadcn
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

claude_autopilot-0.2.1/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write  # Required for Trusted Publishing
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Build package
+        run: uv build
+
+      - name: Check distribution
+        run: uvx twine check dist/*
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/project/claude-autopilot/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: false

claude_autopilot-0.2.1/.gitignore

@@ -0,0 +1,35 @@
+# Autopilot local dev/orchestration state
+.dev/
+
+# MkDocs build output
+docs/site/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment variables
+.env
+.env.local

claude_autopilot-0.2.1/CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+Autopilot is an autonomous project session orchestrator for Claude Code. It reads project manifests (`.dev/sprint.md`), evaluates readiness via an LLM judge, and executes tasks sequentially through the Anthropic Agent SDK. It automates the outer loop of hobby project development — you write the plan, autopilot runs it.
+
+## Architecture
+
+Single Python package at `src/autopilot/`. Key modules:
+
+| Module | Responsibility |
+|--------|---------------|
+| `cli.py` | Argparse CLI, project discovery, fork-filtering, async entry point |
+| `orchestrator.py` | All agent pipelines: judge/worker/planner/researcher/portfolio/roadmap/ralph |
+| `manifest.py` | Parse/load/write manifests, task dependency resolution, agent config loading, runbook I/O, sprint log I/O |
+| `prompts.py` | Prompt builders for all agent roles; judge verdict parsing |
+| `agent.py` | Thin wrapper around `claude_agent_sdk.query()` — streams messages, tracks cost, names sessions |
+| `models.py` | Dataclasses: `Task`, `Manifest`, `AgentConfig`, `AgentResult`, `SprintResult` |
+| `config.py` | `AutopilotConfig` dataclass with v2 fields; `load_config()` from TOML |
+| `log.py` | Timestamped status logging |
+
+**Agent role configs** live in `src/autopilot/agents/*.md` — markdown files with YAML frontmatter defining system prompts, allowed tools, budget, and permission mode for each role: `judge`, `worker`, `planner`, `critic`, `researcher`, `portfolio`, `roadmap`, `roadmap-evaluate`, `deep-researcher`.
+
+**Bundled runbooks** live in `src/autopilot/runbooks/*.md` — markdown reference docs loaded at runtime via `load_runbook(archetype, cfg)`. The `python-cli` runbook ships with the package. Custom runbooks can be added to a project-local `runbooks/` directory (configured via `AutopilotConfig.runbooks_dir`).
+
+## Core Pipeline
+
+**`sprint`** (`orchestrator.py: execute_sprint()`): Executes an approved `.dev/sprint.md` — loops through pending tasks sequentially. Each task: spawn worker agent → verify marked done → retry on failure up to `max_task_attempts`. Pass `--auto-approve` to bypass the approval check. Pass `--resume` to reset stuck projects and retry failed tasks.
+
+**`build`** (`orchestrator.py: build_project()`): One-shot workflow: runs `plan` then `sprint`. Equivalent to `autopilot plan . && autopilot sprint --auto-approve .`. Pass `--context <file>` to seed the planner.
+
+**`plan`**: Lazily runs roadmap agent if `.dev/roadmap.md` doesn't exist, then runs the planner agent to write `.dev/sprint.md`. The critic agent always runs if its config exists, followed by a judge loop (up to 2 rounds) that evaluates the plan and revises if needed. On judge READY, sets `approved: true` in sprint.md. Pass `--context <file>` to skip lazy research and seed the planner directly.
+
+**`roadmap`**: Runs roadmap agent → writes `.dev/roadmap.md` with `goal:`, `archetype:`, and `validate:` frontmatter plus shipping steps. Uses research summary if available. The roadmap is the authoritative goal+validate artifact. Pass `--deep` to run deep research first. Pass `--topic "question"` or `--topic-file brief.md` to run topic research (writes `.dev/research/{slug}/report.md`, no roadmap written).
+
+**`ralph`** (`orchestrator.py: ralph_project()`): Outer loop: `(plan → sprint → evaluate) × N` until GOAL_MET or stuck. Requires `.dev/roadmap.md`. Each iteration calls `plan_project()` (planner + critic + judge), `execute_sprint()` (worker loop), `run_validation_hooks()`, and `evaluate_project()`. If tasks fail, appends a deferred investigation task to `roadmap.md` and stops. Loops until `goal_met=True` or `max_sprints` reached.
+
+**`portfolio`**: Runs portfolio agent across all discovered projects → writes `<scan_dir>/.dev/portfolio.md`. Requires `--scan` or explicit paths. Auto-generates `.dev/roadmap.md` for any project that lacks one before building the portfolio (uses deep research if no existing research artifacts). The portfolio agent uses `roadmap.md` as its primary input per project.
+
+## Key Patterns
+
+- **Manifest format**: YAML frontmatter + markdown checkboxes at `.dev/sprint.md`. Task metadata persisted inline: `[id: foo]`, `[depends: bar]`, `[attempts: 2]`, `[status: failed]`, `[error: ...]`.
+- **Session naming**: Every `run_agent()` call sets `extra_args={"session-name": "autopilot/{project}/{role}"}` so sessions appear distinctively in Claude Code's `/resume` history.
+- **Project discovery**: `discover_projects()` finds dirs with `.dev/sprint.md`; `discover_all_projects()` finds any project-like dir (git, package.json, pyproject.toml, etc.).
+- **Fork filtering**: In scan mode, non-owned repos are skipped by comparing git remote owner to detected user (`AUTOPILOT_GIT_USER` env → `git config autopilot.user` → `gh api user`). Use `--all` to disable.
+- **Default cwd**: When no path arg is provided, autopilot defaults to the current directory for all modes.
+
+## .dev Convention
+
+All autopilot working files within a project live under `.dev/` (which should be in `.gitignore`):
+- `.dev/sprint.md` — task manifest (`plan` output); used by `sprint` for worker loop
+- `.dev/roadmap.md` — roadmap agent output; contains `goal:`, `archetype:`, and `validate:` frontmatter; used by `sprint` as the goal + validate definition
+- `.dev/sprint-log.md` — sprint history, append-only, feeds planner context each sprint
+- `.dev/project-summary.md` — researcher agent output
+- `<scan_dir>/.dev/portfolio.md` — portfolio agent output
+
+## Development Commands
+
+```bash
+uv pip install -e .                          # Install (editable)
+autopilot sprint .                           # Execute approved sprint plan
+autopilot sprint --auto-approve .            # Execute, bypassing approval check
+autopilot sprint --resume .                  # Reset stuck projects and retry
+autopilot build .                            # Plan then execute (one-shot)
+autopilot build --context spec.md .          # Plan with context, then execute
+autopilot plan .                             # Generate/improve manifest (plan + critic + judge)
+autopilot roadmap .                          # Build shipping roadmap (goal + validate)
+autopilot roadmap --deep .                   # Deep research then build roadmap
+autopilot roadmap --topic "question" .       # Research a specific topic
+autopilot ralph .                            # Outer loop until goal met or stuck
+autopilot sprint --scan ~/Projects           # Auto-discover and process all projects
+uv run ruff check src/                      # Lint
+uv run ruff format --check src/             # Format check
+```
+
+There are no tests yet (smoke tests planned before v0.1.0 release — see `.dev/plans/01-naming.md`).
+
+## Code Style
+
+- Python 3.11+, async/await throughout
+- Ruff linter: line length 100, rules `E, F, I, N, W, UP`
+- Dataclasses (not Pydantic)
+- Type hints with `X | None` union syntax (not `Optional`)
+
+## Documentation
+
+When adding or changing features that affect CLI usage, agent roles, or the manifest format, update `README.md`. The README is the primary user-facing documentation.
+
+Release plans and post-MVP features tracked in `.dev/roadmap.md` and `.dev/plans/`.

claude_autopilot-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing to autopilot
+
+## Setup
+
+```bash
+git clone https://github.com/timainge/autopilot
+cd autopilot
+uv pip install -e ".[dev]"
+```
+
+## Adding a New Agent Role
+
+1. Create `src/autopilot/agents/<role>.md` with YAML frontmatter:
+   ```markdown
+   ---
+   name: role-name
+   description: What this agent does
+   allowed_tools:
+     - Read
+     - Write
+     - Bash
+   max_turns: 20
+   max_budget_usd: 1.00
+   permission_mode: default
+   ---
+
+   You are an expert...
+   ```
+2. Add a `build_<role>_prompt()` function in `prompts.py`
+3. Add a `<role>_project()` function in `orchestrator.py`
+4. Wire up the CLI flag in `cli.py`
+
+## Running Linter
+
+```bash
+make lint
+```
+
+## Running Tests
+
+```bash
+make test
+```
+
+## Submitting PRs
+
+- Keep changes focused; one feature per PR
+- Run `make ci` before opening a PR
+- Update `README.md` if you add CLI flags or agent roles

claude_autopilot-0.2.1/Makefile

@@ -0,0 +1,10 @@
+.PHONY: test lint ci
+
+test:
+	uv run pytest tests/ -v
+
+lint:
+	uv run ruff check src/
+	uv run ruff format --check src/
+
+ci: lint test

claude_autopilot-0.2.1/PKG-INFO

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: claude-autopilot
+Version: 0.2.1
+Summary: Autonomous project session orchestrator for Claude Code
+Project-URL: Homepage, https://github.com/timainge/autopilot
+Project-URL: Documentation, https://timainge.github.io/autopilot
+Project-URL: Repository, https://github.com/timainge/autopilot
+Project-URL: Bug Tracker, https://github.com/timainge/autopilot/issues
+Project-URL: Changelog, https://github.com/timainge/autopilot/releases
+License-Expression: MIT
+Keywords: ai,automation,claude,claude-code,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: claude-agent-sdk>=0.1.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# autopilot
+
+[![PyPI](https://img.shields.io/pypi/v/claude-autopilot)](https://pypi.org/project/claude-autopilot/)
+[![CI](https://github.com/timainge/autopilot/actions/workflows/ci.yml/badge.svg)](https://github.com/timainge/autopilot/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/claude-autopilot)](https://pypi.org/project/claude-autopilot/)
+[![Docs](https://img.shields.io/badge/docs-github--pages-blue)](https://timainge.github.io/autopilot)
+
+Autopilot is the outer loop for Claude Code. You describe what needs building; autopilot plans it, executes it task by task, and checks whether the goal was met — without you sitting there typing "continue".
+
+---
+
+## How it works
+
+Autopilot runs a three-stage cycle:
+
+```
+roadmap  →  plan  →  sprint
+  ↑                    |
+  └──── evaluate ←─────┘
+```
+
+**Roadmap** — defines the goal, the shipping target, and what "done" looks like (validation commands). Optional but makes everything downstream sharper.
+
+**Plan** — a planner agent reads the roadmap and writes `.dev/sprint.md`: a set of structured tasks. A critic reviews it, a judge approves it. No execution until the plan is approved.
+
+**Sprint** — each task in the manifest gets a fresh Claude Code session. The worker implements, commits, and marks the task done. Failed tasks retry up to a configured limit.
+
+**Ralph** is the outer loop that drives this cycle autonomously — planning a sprint, executing it, running validation, evaluating whether the goal is met, and repeating until it is.
+
+---
+
+## Install
+
+```bash
+pip install claude-autopilot
+# or
+uv pip install claude-autopilot
+```
+
+Requires a Claude API key or Claude Code subscription token:
+
+```bash
+# Option A: API key
+export ANTHROPIC_API_KEY=your-key-here
+
+# Option B: Claude Code subscription (Max/Pro)
+claude setup-token
+export CLAUDE_CODE_OAUTH_TOKEN=<token from above>
+```
+
+---
+
+## Quick start
+
+**One-shot build** — plan then execute in a single command:
+
+```bash
+autopilot build .
+autopilot build --context spec.md .   # seed the planner with a spec or TODO list
+```
+
+**Step by step** — more control:
+
+```bash
+autopilot roadmap .          # optional: build a goal + validate spec
+autopilot plan .             # write + approve the task manifest
+autopilot sprint .           # execute the approved manifest
+```
+
+**Fully autonomous loop** — keeps going until the goal is met:
+
+```bash
+autopilot roadmap .          # required for ralph: defines the goal and validate commands
+autopilot ralph .            # plan → sprint → evaluate, repeat
+```
+
+---
+
+## Commands
+
+### `roadmap`
+
+Writes `.dev/roadmap.md` — the goal, archetype, validation commands, and shipping phases. Used
+as the primary input for planning and as the termination condition for ralph.
+
+```bash
+autopilot roadmap .                          # assess the project and write a roadmap
+autopilot roadmap --deep .                   # run deep research (web + ecosystem) first
+autopilot roadmap --topic "question" .       # research a specific question → .dev/research/
+autopilot roadmap --topic-file brief.md .    # same, from a file
+```
+
+### `plan`
+
+Runs the planner → critic → judge pipeline and writes an approved `.dev/sprint.md`.
+
+```bash
+autopilot plan .                             # auto-runs roadmap first if it doesn't exist
+autopilot plan --context TODO.md .           # seed with a spec or todo list, skip research
+```
+
+The critic reviews the plan adversarially. The judge evaluates readiness: if NOT_READY, the
+planner revises once with the judge's feedback and the judge re-evaluates. When approved,
+`approved: true` is set in the manifest automatically.
+
+### `sprint`
+
+Executes the approved `.dev/sprint.md` task manifest. Each task spawns a fresh Claude Code
+session.
+
+```bash
+autopilot sprint .
+autopilot sprint --auto-approve .            # skip the approval check
+autopilot sprint --resume .                  # reset stuck projects, retry failed tasks
+```
+
+### `build`
+
+Shorthand for `plan` + `sprint --auto-approve` in one command.
+
+```bash
+autopilot build .
+autopilot build --context spec.md .
+```
+
+### `ralph`
+
+The fully autonomous outer loop. Requires `.dev/roadmap.md` (run `autopilot roadmap .` first).
+
+```bash
+autopilot ralph .
+autopilot ralph --auto-approve .
+```
+
+Each iteration: plan a sprint → execute tasks → run `validate` commands from roadmap frontmatter
+→ evaluate whether the goal is met. Stops when:
+- The evaluator returns `GOAL_MET`
+- Tasks fail (appends a deferred investigation task to `roadmap.md`)
+- `max_sprints` is reached
+
+### `portfolio`
+
+Builds a cross-project index — goal, tech stack, current state, and prioritised quick wins.
+Auto-generates `.dev/roadmap.md` for any project that lacks one before building.
+
+```bash
+autopilot portfolio --scan ~/Projects
+autopilot portfolio path/to/proj-a path/to/proj-b
+```
+
+Output: `<scan_dir>/.dev/portfolio.md`.
+
+---
+
+## Multi-project scanning
+
+Every command works with `--scan` to operate across a directory of projects:
+
+```bash
+autopilot roadmap --scan ~/Projects
+autopilot plan --scan ~/Projects
+autopilot sprint --auto-approve --scan ~/Projects
+autopilot ralph --scan ~/Projects
+```
+
+Repos you don't own are skipped by default. Autopilot compares the git remote owner against
+your username (checked in order: `AUTOPILOT_GIT_USER` env, `git config autopilot.user`, `gh`
+CLI auth). Use `--all` to include forks and clones.
+
+---
+
+## Configuration
+
+### Per-project: `autopilot.toml`
+
+```toml
+[autopilot]
+max_budget_usd = 10.0
+max_task_attempts = 3
+max_sprints = 5
+```
+
+### Global: `~/.config/autopilot/config.toml`
+
+Same format. Per-project config takes precedence.
+
+### Manifest frontmatter
+
+`.dev/sprint.md` and `.dev/roadmap.md` use YAML frontmatter for structured config:
+
+| Field | File | Default | Description |
+|-------|------|---------|-------------|
+| `name` | sprint | dir name | Project display name |
+| `approved` | sprint | false | Approval gate — must be true before sprint runs |
+| `status` | sprint | pending | pending / active / stuck / completed |
+| `max_budget_usd` | sprint | 5.0 | Budget cap per sprint |
+| `max_task_attempts` | sprint | 3 | Max retries per failed task |
+| `goal` | roadmap | — | Goal type: launch / publish / complete |
+| `archetype` | roadmap | — | Project archetype (e.g. `python-cli`) |
+| `validate` | roadmap | — | Shell commands that must pass for goal completion |
+
+Add `.dev/` to `.gitignore` — it contains orchestration state, not source code.
+
+### Task format
+
+Tasks in `.dev/sprint.md` are level-3 headings with a checkbox, a slug ID, and an optional
+body:
+
+```markdown
+### [ ] create-api-client
+
+Implement `src/client.py` with a `get()` and `post()` method using `httpx`.
+Use the base URL from `config.py`. Raise `APIError` on non-2xx responses.
+
+**Done**: `pytest tests/test_client.py` passes.
+
+---
+
+### [ ] add-retry-logic [depends: create-api-client]
+
+Add exponential backoff to the client using `tenacity`. Max 3 retries,
+starting at 1s. Log each retry attempt at WARNING level.
+
+---
+
+### [x] completed-task
+```
+
+- IDs are the heading text — must be `lowercase-with-dashes`
+- Dependencies: `[depends: task-id]` or `[depends: a, b]` inline in the heading
+- Retry metadata (`[attempts: N]`, `[status: failed]`, `[error: ...]`) is written by autopilot — don't edit manually
+
+---
+
+## Agent roles
+
+Agent configs live in `src/autopilot/agents/*.md` — YAML frontmatter + system prompt. Sessions
+appear in Claude Code's `/resume` history as `autopilot/projectname/role`.
+
+| Role | Invoked by | What it does |
+|------|-----------|--------------|
+| `planner` | `plan`, `build`, `ralph` | Writes `.dev/sprint.md` |
+| `critic` | `plan`, `build`, `ralph` | Reviews the plan adversarially |
+| `judge` | `plan`, `build`, `ralph` | Approves or rejects the plan |
+| `worker` | `sprint`, `build`, `ralph` | Executes a task, commits |
+| `roadmap` | `roadmap`, `ralph` | Writes `.dev/roadmap.md`; evaluates goal completion |
+| `researcher` | (lazy, before `plan`) | Analyses codebase → `.dev/project-summary.md` |
+| `deep-researcher` | `roadmap --deep` | Extended web research before roadmapping |
+| `portfolio` | `portfolio` | Cross-project index → `.dev/portfolio.md` |
+
+### Custom roles
+
+Drop a markdown file into `agents/` (or use `--agents-dir` to point to a custom directory):
+
+```markdown
+---
+name: reviewer
+description: Reviews completed tasks for quality
+allowed_tools: [Read, Glob, Bash, Grep]
+permission_mode: default
+max_turns: 20
+max_budget_usd: 0.50
+---
+
+You are a code reviewer. You read recently completed tasks and assess quality...
+```
+
+---
+
+## Design notes
+
+**Why the Agent SDK, not CLI pipes?**
+The SDK wraps Claude Code programmatically — same tools, proper message streaming, error
+handling. Each `query()` call is a fresh Claude Code session with clean context.
+
+**Why sequential tasks, not parallel?**
+Simpler to debug, cheaper, and avoids merge conflicts. Parallel execution via git worktrees is
+planned for a future release.
+
+**Why a human approval gate?**
+The judge evaluates readiness, but a human must explicitly set `approved: true` (or pass
+`--auto-approve`). This prevents runaway execution on half-baked plans.
+
+**Why markdown manifests?**
+The manifest doubles as project documentation. YAML frontmatter gives structured config; the
+markdown body gives context that humans and agents can both read naturally.