The Architect: Autonomous Development Lifecycle for Agentic AI Coding Tools
The Story
I spent three months watching AI coding agents fail in subtle, persistent ways. Not catastrophic breakdowns, but quiet failures: an agent writing two files and declaring success without passing tests; retrying the same function multiple times without memory; burning tokens at 11pm without progress. Agents wrote code but did not finish the job. I was building production-grade agentic systems that couldn’t be babysat constantly. So I built The Architect.
The Architect is an open-source autonomous development lifecycle layer that wraps any AI coding CLI. It adds planning, completion verification, retry intelligence, quality review, and persistent memory—everything agents miss. Provider-agnostic and proven on Claude Code CLI, Codex CLI, and OpenCode CLI, The Architect shipped itself with 10,042 autonomous runs demonstrating its stabilisation.
The Pain: You Are the Orchestration Layer
Using AI coding agents directly means constant supervision. You watch as the agent endlessly retries the same fragment, kill it, adjust context, and try again. Completion claims are hallucinations—failing tests prove that. Hours spent babysitting task retries with little strategic progress.
This is the orchestration problem. AI tools solve coding. No one has solved handling failure modes, retries, progress monitoring, or stuck detection at scale.
The Four Gaps
- Completion isn't verified. Exit code or task completion claims mean nothing without evidence.
- Retries have no memory. Retry attempts start cold, repeating previous mistakes without context.
- No stuck detection. Agents burn tokens indefinitely when blocked with no automatic recovery.
- Context resets every session. Project knowledge, decisions, and lessons are lost between runs.
The Fake Solutions
- Better prompts. Tuning helps only briefly and must be constantly redone as code and models evolve.
- More expensive models. Higher quality reduces hallucinations but does not eliminate manual oversight or stuck states.
The real problem: you cannot hand off control to an AI agent without losing control, forcing either constant attention or chaos.
The Solution
The Architect is the handoff mechanism. You maintain architectural control and let it run. It detects and handles failures requiring human intervention.
Provider-Agnostic Architecture
- Claude Code CLI – Anthropic's official coding agent
- Codex CLI – OpenAI's command line coding agent
- OpenCode CLI – open-source multi-vendor alternative
Switch providers or mix planning and execution tools freely. The orchestration layer remains constant.
Mechanism 1: Autonomous Planning
The Architect agent decomposes your goal into numbered, self-contained task files inside tasks/. These tasks include goal, context, and detailed sub-tasks. You do not define tasks manually.
Task scope is configurable: simple scope splits goals into many small tasks; complex scope condenses tasks for frontier models with higher context windows.
Mechanism 2: Multi-Signal Completion Detection
Completion requires corroboration from multiple independent signals to confirm task success.
| Signal | How it Works | Strength |
|---|---|---|
| Promise tag | Agent outputs <promise>TXX_COMPLETE</promise> | Strong |
| PROGRESS.md | Task marked "Done" in progress marker file | Moderate |
| Clean exit | Provider CLI exits with code 0 | Weak |
| Progress signal | Text contains "all tests pass", "task is done" | Weak |
Decision logic: Two or more positive signals declare task done; promise tag alone suffices. Exit code alone is never enough. If the agent outputs stuck signals (“I’m stuck”), it overrides completion claims and marks failure.
Mechanism 3: Circuit Breaker
The circuit breaker detects failure patterns retry logic misses, using persisted counters:
- No-progress (no files written in 3 attempts)
- Same-error fingerprint (3 repeats of logically identical bash errors)
- Token decline (retry attempts use fewer tokens, indicating Giving Up)
When triggered, the circuit opens and selects recovery: WAIT, REPLAN (task rewrite), or COOLDOWN_WAIT (handle rate limits). State persists across restarts ensuring safe unattended runs.
Mechanism 4: Retry with Context Carry
Retries use previous attempt summaries to avoid repeating mistakes. Attempt n+1 receives detailed context of files written, tests run, and failure reasons from attempt n.
You can also configure retry models—different provider or model per attempt increasing chances of success.
Mechanism 5: Retrospective Reviewer
A separate agent audits all completed work and runs your test suite after all tasks finish. It creates fix-up tasks for any regressions or uncovered issues, feeding them back into the execution pipeline.
The reviewer only adds tasks. It never rewrites existing work or plans.
Mechanism 6: ARCHITECT.md — Persistent Project Intelligence
The heart of long-term memory and learning. ARCHITECT.md accumulates:
- Project structure (languages, frameworks, dependencies)
- Permanent architectural decisions
- Known constraints discovered during builds
- Lessons learned from past failures
- Best practices for the project
- Planning history of prior sessions
Every planning and execution reads this file, enabling context continuity and architectural stability across sessions.
Production Codebases
Unlike greenfield projects, mature codebases have accumulated decisions, constraints, and edge cases unknown to agents. The Architect handles this by preserving these in ARCHITECT.md, using frontier models for planning with full context, isolating tasks by scope, and letting you define architecture rather than relying on the AI to invent it.
Local GPU Models
Local models with large token windows still face real context window limitations. The Architect manages this by splitting work: a powerful frontier model plans with full context; a local smaller model executes narrowly scoped tasks. This mixed-model pattern enables real production work on local GPUs.
Overnight Safety
Configure The Architect to safely run unattended overnight by capping token budgets, managing cooldowns on rate limits, preserving progress state, and enabling task retries and re-planning autonomously.
Example configuration:
[architect]
persistent = true
token_budget_per_hour = 500000
Dog-Food
The Architect improved itself during development. A key bug in its own lock file was caught by its circuit breaker mechanism detecting identical retry failures, triggering replanning and fixing its implementation automatically.
Honest Limits
- It does not write better code than your AI coding tool. It raises the floor, not the ceiling.
- Poorly specified goals produce vague tasks. Clear goals remain critical.
- The retrospective reviewer is a quality gate, not a full code review.
- Token usage tracking is unavailable with Claude Code due to format limitations.
- Free models like OpenRouter are significantly slower—suitable for non-urgent work only.
Getting Started
Install The Architect from PyPI:
pip install the-architect
Requires Python 3.11+ and one or more supported AI coding CLI tools: Claude Code, Codex, or OpenCode.
Initialize your project and run:
architect init
architect --plan --goal "add Stripe payment integration"
architect
The Architect will plan, execute, retry, review, and report fully unattended.
Full documentation is available at github.com/iNetanel/the-architect.