DanMcInerney/architect-loop

architect‑loop – an autonomous LLM‑driven software‑factory

What it is – architect-loop is a command‑line orchestrator that lets you run a fully‑automated development pipeline powered by large‑language‑model agents (Claude for design/review, Codex for code generation). It can take a high‑level product request, break it into isolated issues, have separate “builder” agents implement each issue in a fresh Git worktree, run tests, and finally produce a single PR (or a local finish record) without any human approval gates.

How it works

• Orchestrator – the session you start (/architect, /architect‑fast or /architect‑research) is the master process. It creates a strategist sub‑agent that drafts a spec, then spawns builder agents that each handle one issue.
• Typed evidence & watchdog – every builder runs inside a wrapped CLI job that writes JSON meta files, heart‑beats and exit status. The watchdog only records typed evidence; it never kills jobs – stuck jobs are reaped manually with kill-job.
• Tracker – state can be stored either on GitHub (via issues/PRs) or locally in markdown files under docs/issues/<run>/. All run metadata lives under docs/runs/<run>/.
• Deterministic gates – frozen checks are committed before any builder runs; final review is a read‑only strategist pass that either integrates or creates fix‑issues.
• Fast lane – /architect‑fast limits the run to ≤3 builder issues and ~400 changed lines, skipping strategist stages and frozen checks for quick, bounded changes.
• Research lane – /architect‑research performs a structured literature‑style investigation, producing a source‑cited report.

Key commands

/architect-research <topic>   # topic‑level research, answer‑first report
/architect <hours+ request>   # full multi‑hour factory run
/architect-fast <small change># quick bounded change lane

Run‑time helpers include run-job.sh|ps1, kill-job, status.sh|ps1, and sweep‑deferred for cleanup.

Installation

git clone https://github.com/DanMcInerney/architect-loop
cd architect-loop && ./install.sh        # Windows: .\install.ps1
npm i -g @openai/codex@latest            # optional builder backend

The installer copies the skills/ directory to the appropriate Claude and Codex skill locations; --project installs the skills into the current repo instead of the user profile.

Configuration (optional, ~/.architect/config or .architect/config)

strategist = claude/best       # design/review agent
builders   = codex/best        # code‑generation agent
tracker    = markdown          # or github

The config lets you swap model families, pin effort levels, or change the tracker mode.

Validation & testing

uv run --no-project python tests/validate_skills.py

The validator checks that skill definitions, wrappers, and contracts conform to the project’s architectural invariants.

License – MIT.

---

Bottom line – architect-loop is a self‑contained, LLM‑orchestrated development framework that automates the whole spec‑to‑PR cycle, with both a full‑feature lane and a lightweight fast lane, and supports either GitHub or pure‑markdown issue tracking.