The Architect

The Architect: Autonomous Development Lifecycle Layer for Agentic AI Coding Tools

The Story

I spent three months observing AI coding agents fail quietly, not catastrophically. Agents would write a couple of files, declare success, and exit, leaving broken test suites behind. Others repeatedly rewrote the same function across retries without passing context, or simply token-burned endlessly when stuck, especially overnight. I was building agentic systems for production—where babysitting each run was impossible. The tools were good at writing code; they were bad at finishing jobs.

So I built The Architect. An open-source, provider-agnostic autonomous development lifecycle layer that wraps your AI coding CLI. It adds the missing parts: planning, completion verification, retry intelligence, quality review, and persistent memory. Compatible with Claude Code CLI, Codex CLI, and OpenCode CLI. Available on PyPI. Build 10042 marks the number of autonomous operations it took to stabilise the system.

The Pain: You Are the Orchestration Layer

Working directly with AI coding agents on multi-task goals means endless babysitting. Write a goal, start the agent. Twenty minutes later, it rewrites the same function multiple times for no obvious reason. You kill it, adjust context, rerun. It exits clean, but tests fail. Completion is an hallucination you must catch manually. By task seven you're tired. By task nine, you ship with known bugs because you need sleep.

Active supervision: 3-4 hours for 10 tasks. Most of this is watching, not thinking. You’re not architecting—you’re playing firefighter.

This is the orchestration problem: AI solves coding but nobody solved managing the process reliably.

The Four Gaps

• Completion isn’t verified. Agents say "task complete" with no proof. Exit code 0 means nothing—hallucinated success is routine.
• Retries have no memory. Retried tasks start cold, repeating past mistakes because prior context isn’t carried over.
• No stuck detection. Agents stuck on the same problem burn tokens endlessly without intervention triggers.
• Context resets every session. Every new run loses all decisions, constraints, and lessons from past attempts.

The Fake Solutions

Before The Architect, I tried better prompts. They helped temporarily but broke as goals or models changed. More expensive models hallucinate less but don’t remove supervision overhead. The core issue remains: you can’t hand off control without losing control. You either pay attention or pay for chaos.

The Solution

The Architect is the handoff mechanism. You define architecture, goals, and scope. It executes and handles every failure mode that would otherwise require you.

Provider-Agnostic Architecture

• Claude Code CLI — Anthropic’s official agentic coding tool
• Codex CLI — OpenAI’s terminal coding agent
• OpenCode CLI — Open-source multi-provider alternative

No vendor lock-in. Switch providers anytime. Use different providers for planning or execution. The orchestration layer remains consistent.

Mechanism 1: Autonomous Planning

The architect agent reads your goal, detects project structure automatically, and digests ARCHITECT.md plus any `--context` files. It decomposes the goal into numbered task files in a `tasks/` directory. Each task is self-contained, with explicit goals and sub-tasks—enough detail that the build agent can execute independently.

Scope controls task size: simple scope yields 15-20 narrow, focused tasks — good for smaller models with limited context. complex scope creates 3-5 broad tasks for powerful frontier models.

Mechanism 2: Multi-Signal Completion Detection

Decision rules: Two or more signals positive → task done. Promise tag alone suffices. Exit code alone is ignored. Any “stuck” signals (“I’m stuck”, “I can’t proceed”) override completion and mark failure.

Mechanism 3: Circuit Breaker

Retries can’t handle persistent failure patterns. Circuit breaker tracks three counters saved to disk:

• No-progress: Agent wrote zero files for 3 attempts → circuit trips.
• Same-error: Identical bash error fingerprints 3 times → trips circuit.
• Token decline: Attempt 3 uses less than 40% of tokens of attempt 1; combined with other counters → trips circuit.

When tripped, recovery actions are chosen: WAIT, REPLAN (rewrite failing task), or COOLDOWN_WAIT (pause due to rate limits). Circuit state persists across restarts, ensuring safe recovery.

Mechanism 4: Retry with Context Carry

Failed tasks retry (default 3 attempts, 30 in persistent mode). On each retry, previous attempt’s context is summarised and injected. The build agent knows exactly what was tried, what files changed, and test failures. It won’t repeat errors blindly.

Retry models let you fallback between providers, escalating on retries. Failures for one provider may succeed on another.

Mechanism 5: Retrospective Reviewer

After execution, a separate reviewer agent audits tasks. It reads all plans, code, PROGRESS.md, and runs your test suite. If issues are found, it creates fix-up tasks prefixed R01, which cycle through the same pipeline.

In persistent mode, two review rounds run. Reviewer can’t overwrite tasks or PROGRESS.md, only append fixes. Silence means clean work.

Mechanism 6: ARCHITECT.md — Persistent Project Intelligence

This structured file accumulates project memory, read by every session and agent:

• Project Structure: Repo type, languages, frameworks, dependencies, test & lint commands, dependency graph. Freshly written on planning.
• Permanent Decisions: Append-only record of architectural choices.
• Known Constraints: Issues discovered during tasks, appended.
• Lessons Learned: Failures, pitfalls, best practices discovered over time.
• Best Practices: Recorded coding standards and patterns.
• Planning History: Auto-appended each plan.

After 50+ builds on The Architect itself, the file captured 23 decisions and 11 lessons, none manually added. Agents build project memory as they build the project.

Production Codebases

Production codebases are complex. AI agents see code but not reasoning behind decisions. The Architect mitigates this:

• ARCHITECT.md captures decisions and constraints.
• The planner runs on frontier models with full context.
• Scope isolates tasks to reduce risk.
• You define architecture, agent follows.

Local GPU Models

Large local models have theoretical large context windows, but real working context fills fast. The Architect inverts typical use:

• Frontier model handles full planning and retrospective analysis.
• Local smaller model executes scoped tasks, one at a time, in clean context windows.

This mixed-model approach lets models with 30k token context do meaningful production work.

Overnight Safety

Safe unattended runs include token budgets and cooldowns:

[architect]
persistent = true
token_budget_per_hour = 500000

The system handles retries, rate limits, cooldown waits, circuit trips, replans, reviewer rounds, and resumes from crashes — all autonomously.

Dog-Fooding The Architect

The Architect runs itself. When the circuit breaker caught a repeated FileExistsError in its own build at task T47, it tripped and triggered a targeted replan. This found and fixed a bug in its own lock file. The next morning's logs revealed the self-correcting power of the orchestration layer.

Honest Limits

• Doesn’t write better code than your underlying AI. Raises the floor, not the ceiling.
• Poorly specified goals produce vague tasks. Garbage in, garbage out applies fully.
• The retrospective reviewer aids quality but is no substitute for engineering judgement and architectural oversight.
• Token counts unavailable with Claude Code; prefer OpenCode or Codex for token tracking.
• Free open models run slower—3x wall-clock time for 10 tasks compared to Claude Sonnet.

Getting Started

Install with Python 3.11+ and an AI coding CLI (Claude Code, Codex, or OpenCode):

• pip install the-architect
• architect init
• architect --plan --goal "add Stripe payment integration"
• architect

That’s it. The Architect plans, executes, retries, reviews, and reports unattended.

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