The Architect: Autonomous Development Lifecycle for Agentic AI Coding Tools
The Story
I spent three months watching AI coding agents fail the same way. Not catastrophically — quietly. An agent would write two files, declare success, exit code 0, and leave you with a broken test suite. Another would rewrite the same function three times across retries because it never remembered earlier attempts. Some just sat there token-burning at 11pm while you slept.
I was building agentic systems for production where babysitting every run is impossible. These tools were good at writing code. They were bad at finishing it.
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. It’s provider-agnostic, working with Claude Code CLI, Codex CLI, and OpenCode CLI. Available on PyPI, The Architect shipped itself. Build 10042 marks how many autonomous operations it took to stabilise it.
The Pain: You Are the Orchestration Layer
Using AI coding agents directly is a babysitting nightmare. You write a goal, start the agent, watch it rewrite a function repeatedly with no explanation, kill and retry with more context, then check failing tests after a supposedly successful run. This repeats task after task until exhaustion — with errors shipping because you had to sleep.
Active supervision: 3-4 hours for a 10-task goal. Most of that is watching, not thinking. You are not designing architecture, you are stopping stuck loops. This is the orchestration problem: coding tools solve code generation; nobody solves orchestration.
The Four Gaps
- Completion isn't verified. Agents declare "done" but exit code 0 or “task complete” means nothing without proof.
- Retries have no memory. Each retry starts cold, repeating previous mistakes.
- No stuck detection. Blocked agents burn tokens endlessly; no auto-recovery.
- Context resets every session. No persistent memory of decisions or prior failures.
The Fake Solutions
Better prompts help briefly but decay as the codebase and models evolve. More expensive models hallucinate less yet still fail to recover autonomously and require supervision. The real issue is handing off control without losing it. Either you watch or chaos reigns.
The Solution
The Architect is the handoff mechanism. You define architecture, goal, scope. The Architect executes, handling failure modes that normally demand your intervention.
Provider-Agnostic Architecture
The Architect works transparently with your existing AI coding CLIs:
- Claude Code CLI: Anthropic's agentic coding tool
- Codex CLI: OpenAI's terminal-based coding agent
- OpenCode CLI: Open-source multi-provider alternative
No vendor lock-in. Switch providers between attempts or use different providers for planning and execution. The orchestration layer stays constant.
Mechanism 1: Autonomous Planning
The Architect decomposes your goal into numbered, well-scoped task files automatically. It reads your goal, project structure (auto-detected), ARCHITECT.md, and any context files. It generates structured task files in tasks/ with clear goals, context, and subtasks. No vague instructions. Each task is self-contained and executable without further input.
Scope controls task size: simple scope creates 15-20 narrow tasks, complex scope creates 3-5 broad tasks. Choose based on your model's capability.
Mechanism 2: Multi-Signal Completion Detection
| Signal | How it works | Strength |
|---|---|---|
| Promise tag | Agent outputs <promise>TXX_COMPLETE</promise> | Strong |
| PROGRESS.md | Task marked Done in progress file | Moderate |
| Clean exit | Provider CLI exited with code 0 | Weak |
| Progress signal | Text contains "all tests pass", "task is done" | Weak |
Decision rules: Two or more signals positive → Done. Promise tag alone → Done. Exit code alone → Not done (providers exit 0 on timeout). Override: if agent signals stuck (“I’m stuck”), that overrides all completion claims.
Mechanism 3: Circuit Breaker
Retry handles model failures. The circuit breaker handles repeated failure patterns. It tracks three counters, persisted to disk:
- No-progress: three consecutive runs with zero files written trip the circuit.
- Same-error: three runs with the same canonical bash error trip the circuit.
- Token decline: attempt 3 uses <40% of attempt 1 tokens, combined with other counters, trips the circuit.
When tripped, it triggers recovery: WAIT (let model rotation handle), REPLAN (rewrite the failing task), or COOLDOWN_WAIT (pause on rate limits). Circuit state persists across restarts.
Mechanism 4: Retry with Context Carry
On failure, tasks retry up to 3 times by default. Each retry includes a context summary of prior attempts: files written/read, commands run, test failures. This avoids repeating mistakes and ensures progress.
Retries can switch providers to escape stuck states, escalating through fallback models.
Mechanism 5: Retrospective Reviewer
An auditor agent runs after all tasks, distinct from the builder, reading PROGRESS.md, planned tasks, and code written. It runs your test suite and creates fix-up tasks for any issues found. Retrospective rounds ensure high-quality output while preserving existing work integrity.
Mechanism 6: ARCHITECT.md — Persistent Project Intelligence
This append-only file accumulates knowledge across sessions:
- Project structure and dependencies, refreshed every plan
- Permanent decisions made by agents
- Known constraints discovered during builds
- Lessons learned from past failures
- Best practices
- Planning history logs
Each planning session reads this file first, informing task decomposition with historical and contextual intelligence.
Production Codebases
Production code is complex; agents don’t understand reasoning behind code decisions. The Architect mitigates this by capturing decisions in ARCHITECT.md, using frontier models for full-context planning, isolating tasks by scope, and keeping you in control of architecture.
Local GPU Models
Large local model context windows are misleading; real tasks must fit tight contexts. The Architect uses frontier models for planning and review while local smaller models execute scoped tasks within manageable windows.
This mixed approach enables practical, scalable autonomous coding on typical hardware.
Overnight Safety
Set token budgets and persistent modes to safely automate overnight runs with The Architect. It handles retries, rate limits, stuck loops, and resumes gracefully after interruptions.
Dog-Food
The Architect was built using itself. For example, it caught a circuit breaker triggering on its own lock file task failure, triggering a targeted replanning. I found this in the logs next morning.
Honest Limits
- Does not write better code than your model — it ensures the model finishes correctly.
- Bad goals create bad tasks — clear, structured goals are essential.
- Retrospective review is a quality gate, not a full code audit.
- Token counting unavailable on Claude Code; use OpenCode or Codex if needed.
- Free OpenRouter models are slower; suited for non-urgent work.
Getting Started
Install The Architect from PyPI:
pip install the-architect
Requires Python 3.11+ and at least one supported AI coding CLI: Claude Code, Codex, or OpenCode.
Quickstart commands:
- architect init
- architect --plan --goal "add Stripe payment integration"
- architect
The Architect handles planning, execution, retries, review, and reporting unattended.
Full documentation: github.com/iNetanel/the-architect