AutoDev

Live smoke tests (requires claude CLI logged in)

AUTODEV_LIVE=1 uv run pytest tests/ -k live -v

Development setup

```bash git clone https://github.com/mohamedameen/autodev cd autodev uv sync

Quick start

Install once, opt in per project, then describe what you want built.

pip install ai-autodev

cd /your/project
autodev init

In your AI coding agent, invoke the /autodev skill with your feature request:

/autodev Build a REST API with user registration, login, and JWT auth.

AutoDev shells out to your AI coding agent (Claude Code or Cursor) via subprocess for every dispatch — no API keys to wire up, no embedded session state machine. The /autodev slash command is a thin dispatch layer that runs autodev plan / autodev execute for you.

---

Examples

• examples/subtract/ — smoke test: add a subtract(a, b) function to a tiny repo
• examples/jwt_auth/ — realistic spec: build JWT authentication end-to-end

---

Configuration

.autodev/config.json is a versioned, strict pydantic schema (AutodevConfig). Model defaults are platform-aware — Claude Code uses model aliases (opus/sonnet/haiku) that resolve to the latest version, while Cursor uses explicit models with auto for intelligent selection and automatic fallback on rate limits. Each agent has a configurable max_turns — the number of turns the agent gets per invocation (tool-heavy roles like developer get more turns; text-only tournament roles get 1).

Regenerate the defaults with:

uv run python -c "from config.defaults import default_config; print(default_config('claude_code').model_dump_json(indent=2))"

<details> <summary>Full default configuration (Claude Code platform)</summary>

{
  "schema_version": "1.0.0",
  "platform": "auto",
  "agents": {
    "architect": {
      "model": "opus",
      "disabled": false,
      "max_turns": 5,
      "effort": null
    },
    "explorer": {
      "model": "haiku",
      "disabled": false,
      "max_turns": 3,
      "effort": null
    },
    "domain_expert": {
      "model": "sonnet",
      "disabled": false,
      "max_turns": 3,
      "effort": null
    },
    "developer": {
      "model": "sonnet",
      "disabled": false,
      "max_turns": 10,
      "effort": null
    },
    "reviewer": {
      "model": "sonnet",
      "disabled": false,
      "max_turns": 3,
      "effort": null
    },
    "test_engineer": {
      "model": "sonnet",
      "disabled": false,
      "max_turns": 5,
      "effort": null
    },
    "critic_sounding_board": {
      "model": "sonnet",
      "disabled": false,
      "max_turns": 3,
      "effort": null
    },
    "critic_drift_verifier": {
      "model": "sonnet",
      "disabled": false,
      "max_turns": 3,
      "effort": null
    },
    "docs": {
      "model": "sonnet",
      "disabled": false,
      "max_turns": 3,
      "effort": null
    },
    "designer": {
      "model": "sonnet",
      "disabled": false,
      "max_turns": 3,
      "effort": null
    },
    "critic_t": {
      "model": "sonnet",
      "disabled": false,
      "max_turns": 1,
      "effort": null
    },
    "architect_b": {
      "model": "sonnet",
      "disabled": false,
      "max_turns": 5,
      "effort": null
    },
    "synthesizer": {
      "model": "sonnet",
      "disabled": false,
      "max_turns": 1,
      "effort": null
    },
    "judge": {
      "model": "sonnet",
      "disabled": false,
      "max_turns": 1,
      "effort": null
    }
  },
  "tournaments": {
    "plan": {
      "enabled": true,
      "num_judges": 5,
      "convergence_k": 2,
      "max_rounds": 15,
      "score_stability_window": 4,
      "score_stability_max_delta": 2,
      "winner_stability_window": 3,
      "max_plan_lines_growth_ratio": 1.5,
      "complex_plan_num_judges_override": 7,
      "num_branches": 3,
      "branches": null,
      "promotion_grade_enabled": false,
      "holdout_evaluation_enabled": false,
      "drift_verifier_enabled": true,
      "explorer_enabled": false,
      "voting_strategy": "borda",
      "judge_roles": null,
      "judge_role_weights": null,
      "plateau_detection_enabled": false,
      "plateau_window": 4,
      "cross_family_plateau_enabled": false,
      "cross_family_plateau_window": 10
    },
    "impl": {
      "enabled": true,
      "num_judges": 1,
      "convergence_k": 1,
      "max_rounds": 3,
      "score_stability_window": 2,
      "score_stability_max_delta": 1,
      "winner_stability_window": 2,
      "max_plan_lines_growth_ratio": null,
      "complex_plan_num_judges_override": null,
      "num_branches": 1,
      "branches": null,
      "promotion_grade_enabled": false,
      "holdout_evaluation_enabled": false,
      "drift_verifier_enabled": true,
      "explorer_enabled": false,
      "voting_strategy": "borda",
      "judge_roles": null,
      "judge_role_weights": null,
      "plateau_detection_enabled": false,
      "plateau_window": 4,
      "cross_family_plateau_enabled": false,
      "cross_family_plateau_window": 10
    },
    "phase_review": {
      "enabled": true,
      "num_judges": 3,
      "convergence_k": 1,
      "max_rounds": 2,
      "score_stability_window": null,
      "score_stability_max_delta": null,
      "winner_stability_window": null,
      "max_plan_lines_growth_ratio": null,
      "complex_plan_num_judges_override": null,
      "num_branches": 1,
      "branches": null,
      "promotion_grade_enabled": false,
      "holdout_evaluation_enabled": false,
      "drift_verifier_enabled": true,
      "explorer_enabled": false,
      "voting_strategy": "borda",
      "judge_roles": null,
      "judge_role_weights": null,
      "plateau_detection_enabled": false,
      "plateau_window": 4,
      "cross_family_plateau_enabled": false,
      "cross_family_plateau_window": 10
    },
    "max_parallel_subprocesses": null,
    "execute_max_parallel_tasks": null,
    "auto_disable_for_models": [
      "opus"
    ]
  },
  "qa_gates": {
    "syntax_check": true,
    "lint": true,
    "build_check": true,
    "test_runner": true,
    "secretscan": true,
    "secretscan_baseline_enabled": false,
    "secretscan_per_extension_thresholds": null,
    "sast_scan": false,
    "mutation_test": false,
    "mutation_test_enabled": false,
    "mutation_test_threshold": 0.7
  },
  "qa_retry_limit": 3,
  "user_complexity": "medium",
  "guardrails": {
    "max_invocations_per_task": 60,
    "max_tool_calls_per_task": 60,
    "max_duration_s_per_task": 900,
    "max_diff_bytes": 5242880,
    "cost_budget_usd_per_plan": null
  },
  "task_overrides": {
    "huge_repo_multipliers": null
  },
  "prm": {
    "strategy": "rules",
    "ml_threshold": 0.7,
    "ml_min_events": 3
  },
  "plateau_detector": {
    "strategy": "rules",
    "regression_window": 10,
    "plateau_slope_threshold": 0.1
  },
  "hive": {
    "enabled": true,
    "path": "~/.local/share/autodev/shared-learnings.jsonl"
  },
  "knowledge": {
    "enabled": true,
    "swarm_max_entries": 100,
    "hive_max_entries": 200,
    "dedup_threshold": 0.6,
    "max_inject_count": 5,
    "hive_enabled": true,
    "promotion_min_confirmations": 3,
    "promotion_min_confidence": 0.7,
    "denylist_roles": [
      "explorer",
      "judge",
      "critic_t",
      "architect_b",
      "synthesizer"
    ],
    "lane_aware_injection_enabled": true,
    "decay_curves": null
  },
  "hallucination_guard": true,
  "repeated_hypothesis_threshold": 0.6,
  "web_search_enabled": false,
  "worktree_sparse_checkout_enabled": false,
  "worktree_pool_enabled": false,
  "cross_phase_parallelism_enabled": false,
  "speculative_execution_enabled": false
}

</details>

Note: On Cursor, architect and architect_b default to opus with automatic fallback to auto when rate limited. Roles like explorer, developer, test_engineer default to auto for intelligent model selection.

---

CLI reference

---

Plugins via `entry_points`

```python

pyproject.toml of your plugin package

[project.entry-points."autodev.plugins"] my_gate = "my_package.gates:MyCustomGate" # QAGatePlugin my_judge = "my_package.judges:MyJudge" # JudgeProviderPlugin my_agent = "my_package.agents:MyAgentSpec" # AgentExtensionPlugin ```

Install the wheel, run autodev doctor — your plugin is live. The registry validates against the QAGatePlugin, JudgeProviderPlugin, and AgentExtensionPlugin protocols; invalid plugins are skipped with a warning (no hard fail).

Integration tests (mocked adapters)

uv run pytest tests/integration/ -v

How it compares

---

3. Mandatory QA gates

Every diff runs through syntax check, lint, build, test runner, and secret scan before it can leave the FSM as tested. A failure feeds structured feedback back to the developer with bounded retry. Mutation testing (opt-in, mutation_test_enabled) and per-repo secret-scan baselines (secretscan_baseline_enabled) are also available.

Reviewer never wastes time on a diff that doesn't compile or fails its own tests.

QA gates + guardrails

Five standard gates run on every developer diff, in order. All are default-on:

Failures feed structured feedback back to the developer; qa_retry_limit (default 3) bounds the retry loop. After exhaustion, escalation goes to critic_sounding_board for a pre-abort sanity check.

Opt-in extras: - Mutation testing (mutation_test_enabled, mutation_test_threshold=0.7): runs mutmut on developer diffs as a promotion gate. The Stage-1/2 pipeline (v0.19.0) filters equivalent mutants statically and via LLM judge, surfacing real survivors as a kill_rate signal that feeds promotion grading. - Per-repo secretscan baseline (secretscan_baseline_enabled): pre-existing-secret allowlist with per-extension entropy thresholds. Refresh with autodev secretscan baseline. - Hallucination guard (default-on, hallucination_guard=true): AST-based check for invented identifiers in Python, TypeScript, JavaScript, and C++. - Drift verifier (default-on, drift_verifier_enabled=true): plan-vs-reality cross-check before phase_complete. - Extended-scope editor expansion (Task.extended_scope): a task may widen its allowed edit set when justified; the architect marks Extended-Scope: { ... } blocks. Sync validation runs by default; the critic-review path (extended_scope_critic.py) is opt-in.

Guardrails (per-task hard caps, all default-on): - max_invocations_per_task: 60 - max_tool_calls_per_task: 60 - max_duration_s_per_task: 900 - max_diff_bytes: 5_242_880 - cost_budget_usd_per_plan: null (set to enforce a per-plan circuit breaker)

See docs/design_documentation/qa_gates_design.md, docs/design_documentation/guardrails_design.md, and docs/design_documentation/extended_scope.md.

---