Summary

This repository provides a research-backed framework for orchestrating AI agents in a software development loop. It addresses the challenge of robust AI-driven planning, implementation, and review by separating roles: Claude Fable acts as the architect for planning and review, while GPT-5.5 Codex serves as the builder for implementation and research. The system leverages the repository itself as memory, offering a structured approach to AI-assisted coding for engineers and researchers seeking automated development workflows.

How It Works

The core architecture employs two Claude Code skills to create a repository-centered loop. The architect (Claude Fable) defines specifications and acceptance gates before any code is written, breaking down tasks into lanes and committing gates to docs/gates/. Builders (GPT-5.5 Codex) operate in parallel, isolated worktrees, must "argue with the spec," build only their assigned files, and report raw results without direct commit access. Fable then judges the output by executing gate commands, comparing diffs against the spec's intent, and merging passing lanes. The repository's Git history and specific documentation files (docs/gates/, docs/lanes/, docs/HANDOFF.md) serve as the sole memory. An integrated research loop (/architect-research) uses Codex for topic scouting, followed by Fable designing topic-specific lanes for parallel, budget-constrained Codex researchers, culminating in a verified, decision-oriented report.

Quick Start & Requirements

• Primary install:

  git clone https://github.com/DanMcInerney/architect-loop
  cd architect-loop && ./install.sh
  # Windows: .\install.ps1
  

• Prerequisites:
  • npm installed.
  • npm i -g @openai/codex@latest (Codex CLI >= 0.133).
  • Claude Code subscription (any paid plan).
  • Codex CLI signed into a ChatGPT plan.
• Resource Footprint: Installation is approximately 30 seconds. Builder/researcher runs consume ChatGPT plan quotas (5-hour and weekly limits); Fable sessions are brief.
• Relevant Files: DESIGN.md, skills/architect/SKILL.md, skills/architect-research/lanes.md.

Highlighted Details

• Agent Interaction: Builders are required to verbally challenge the specification before coding, with silent compliance flagged as a defect.
• Review Rigor: Fable's integration process involves executing gate commands and assessing diffs against the original spec intent, not solely relying on passing tests.
• Research Design: Research lanes are dynamically designed per topic post-scout, rather than adhering to a fixed taxonomy, mirroring production deep-research systems.
• Supervision: Built-in liveness checks, stall triage, and explicit timeouts are applied to all long-running commands.

Maintenance & Community

No specific details regarding maintainers, community channels (e.g., Discord/Slack), or roadmaps are provided in the README. The origin notes inspiration from an X post by @jumperz.

Licensing & Compatibility

• License: MIT.
• Compatibility: The MIT license is permissive, allowing for commercial use and integration within closed-source projects without significant restrictions.

Limitations & Caveats

Adoption requires existing subscriptions to Claude Code and ChatGPT plans, with usage drawing directly from paid plan quotas which may represent a significant portion of weekly limits for extensive runs. The system's effectiveness is inherently tied to the performance and interpretation capabilities of the underlying AI models. Reliance on the repository's Git history and specific documentation files as the sole memory mechanism necessitates careful management.