The Architect

The Architect: Autonomous Development Lifecycle for AI Coding Agents

The Story

I spent three months watching AI coding agents fail the same way. Not catastrophically — quietly. An agent that writes two files, declares success, exits code 0, leaving you with a broken test suite. An agent that rewrites the same function three times across retries because it lacks context from previous attempts. An agent that stalls at 11pm, token-burning endlessly while you sleep.

I was building agentic systems for production where babysitting every run is impossible. The tools were good at writing code. They failed at finishing the job.

So I built The Architect. An open-source, autonomous development lifecycle layer that wraps your AI coding CLI and adds what’s missing: planning, completion verification, retry intelligence, quality review, and persistent memory. Provider-agnostic — works with Claude Code CLI, Codex CLI, and OpenCode CLI. Available on PyPI. Build 10042 marks how many autonomous operations it took to stabilise this tool.

The Pain: You Are the Orchestration Layer

Using AI coding agents directly on multi-task goals looks like this:

• You write a goal and start the agent.
• Twenty minutes in, it rewrites the same function for the third time without explanation.
• You kill it, retry with adjusted context, it exits code 0 but tests fail. Completion was hallucinated.
• You manually carry context for the retry and wait.
• By task 7 you’re tired. Task 9 ships with known edge cases because it’s 1am and you need sleep.

Active supervision: 3-4 hours for a 10-task goal, mostly watching not thinking. This is orchestration failure: your AI solves coding, you solve orchestration.

The Four Gaps

• Completion isn’t verified. Agents declare done but output is partial or broken.
• Retries have no memory. Re-attempts start cold, repeating past mistakes.
• No stuck detection. Agents keep burning tokens stuck in loops unless manually stopped.
• Context resets every session. No memory of past runs, decisions, or failures.

The Fake Solutions

Better prompts help temporarily but decay as code and goals evolve.

More expensive models hallucinate less but don’t autonomously recover or replace supervision.

The problem is not capability but control. You can’t hand off without losing control.

The Solution

The Architect is your handoff mechanism. You retain architecture and goal control. The Architect handles every failure mode that would otherwise need your intervention.

Provider-Agnostic Architecture

• Claude Code CLI: Anthropic’s official coding agent.
• Codex CLI: OpenAI’s terminal-based coding agent.
• OpenCode CLI: Open-source, multi-provider alternative.

No vendor lock-in. Switch providers mid-process. The orchestration layer stays constant.

Mechanism 1: Autonomous Planning

The Architect decomposes your goal into numbered, self-contained task files in the tasks/ directory. It reads your goal, auto-detected project structure, ARCHITECT.md, and optional context files.

Task files are precise instructions: goal, context, and sub-tasks specific enough for execution without questions.

Scope controls task sizing: simple creates 15-20 narrow tasks; complex creates 3-5 broad tasks. Choose scope depending on model capabilities.

Mechanism 2: Multi-Signal Completion Detection

Decision rules: Two or more positive signals indicate completion. Promise tag alone also counts as done. Exit code alone does not. Any stuck signal like "I'm stuck" overrides completion signals to flag hallucination.

Mechanism 3: Circuit Breaker

Retries handle failures; the circuit breaker handles failure patterns with persistent counters:

• No-progress: 3 consecutive attempts with zero files written triggers circuit.
• Same-error: 3 identical bash error fingerprints (abstracted from file paths/lines) triggers circuit.
• Token decline: Attempt 3 uses <40% tokens of attempt 1 combined with other counters triggers circuit.

When tripped, it selects recovery: WAIT, REPLAN (rewrite failing task), or COOLDOWN_WAIT (due to rate limiting). State persists across restarts.

Mechanism 4: Retry with Context Carry

Failed tasks retry with up to 3 attempts by default, 30 in persistent mode. On retry, previous attempts' context is summarised and included: files written/read, bash commands run, test failures. The build agent adapts—no repeated mistakes.

Retry models allow switching providers between attempts for resilience.

Mechanism 5: Retrospective Reviewer

After all tasks, a separate reviewer (not the build agent) audits the work:

• Reads PROGRESS.md, task files, code written.
• Runs test suite, detects failures or missing edge cases.
• Generates fix-up tasks with R-prefix to run through execution.

In persistent mode, two review rounds run. Reviewer cannot modify original tasks or progress but only adds tasks or remains silent.

Mechanism 6: ARCHITECT.md — Persistent Project Intelligence

A structured file accumulating project state, continuously enhanced by every session.

• Project Structure: languages, frameworks, dependencies, test commands, graphs.
• Permanent Decisions: append-only recorded choices.
• Known Constraints: append-only, e.g. compatibility issues.
• Lessons Learned: append-only mistakes, safety checks.
• Best Practices: append-only guidelines.
• Planning History: auto-appended.

This file changes how autonomous projects scale by retaining architecture, constraints, and lessons across sessions.

Production Codebases

Production code is complex. Agents see code but not the rationale behind choices. The Architect mitigates this via:

1. ARCHITECT.md captures decisions and constraints discovered during builds.
2. Planning runs on a frontier model with full context.
3. Scope isolates tasks reducing blast radius.
4. You define architecture, agent binds execution within that set scope.

Local GPU Models

Local models have limited effective context windows when coding—files, instructions, outputs fill memory fast. The Architect uses a mixed-model pattern:

• Frontier model plans and reviews with full context.
• Local model executes scoped tasks inside reliable context limits.

This enables production-scale local execution on models with 30k token windows.

Overnight Safety

A safe unattended run configuration example:

[architect]
persistent = true
token_budget_per_hour = 500000

The system autonomously handles retries, rate limit cooldowns, stuck detection, circuit breaker trips, replanning, retrospective fixes, and state persistence across restarts.

Dog-Food

The Architect bootstrapped itself. During task T47, the circuit breaker detected a recurring FileExistsError and triggered a targeted replanning which fixed its own lock file bug overnight.

Honest Limits

• The Architect does not improve code quality beyond the underlying model’s ability. It raises the reliability floor but code quality depends on the model.
• Poorly specified goals yield vague tasks. Clear goals and structured context files remain essential.
• The retrospective review is a quality gate, not a substitute for engineering judgment or code review.
• Token tracking is unavailable with Claude Code; use OpenCode or Codex for token-based budgets.
• Free model mode is slower; expect 3x runtime versus Claude Sonnet for 10 tasks.

Getting Started

Installation

Run: pip install the-architect

Requirements: Python 3.11+, plus at least one supported AI coding CLI: Claude Code, Codex, or OpenCode.

Quickstart

• architect init
• architect --plan --goal "add Stripe payment integration"
• architect (executes planning, execution, retries, review, and reporting unattended)

Full documentation at github.com/iNetanel/the-architect.

SEO Keywords

Provider-agnostic orchestration layer for AI coding agents. Developer tooling for autonomous development. DevOps infrastructure for agentic AI. Open-source Python package. CI/CD automation with AI. Infrastructure for AI coding tools.