Architect-loop: staged software delivery with Codex and Claude

Architect-loop is an open-source workflow for taking a software goal through specification, implementation, checks, review, and a recorded finish. Its central idea is to separate judgment from editing: a fresh strategist shapes the work, builders handle isolated issues, deterministic checks provide evidence, and a final review decides whether the result is ready to integrate.

The project is not a magic prompt and it is not a claim that one model should own a production repository. It is a repository-level factory with explicit stages, run manifests, issue records, worktrees, wrappers, and postflight audits. The official architect-loop repository is the source for the commands, stage names, tracker modes, and design described here.

What architect-loop actually provides

The project exposes three entry points:

/architect-research <topic>
/architect <hours+ feature/product request>
/architect-fast <small change>

/architect-research maps a topic and produces an answer-first report. /architect-fast handles a small bounded change through a lighter lane. /architect runs the full multi-hour factory for a broader product or feature request.

The full lane is organized around stage skills including codebase-design, to-spec, adversarial-review, to-issues, frozen-checks, tdd, final-review, and integrate. The repository describes the default model routing as a strategist using Claude and builders using Codex, but the durable design is the separation of roles and evidence. A configured CLI that is missing is recorded as a substitution rather than silently changing the run.

That distinction matters for production builders. You can change the model or command-line client without throwing away the specification, issue decomposition, checks, and run record.

Why the workflow starts with a fresh strategist

The intake stage sends the goal to a fresh strategist that drafts the specification. Open questions become timed rulings that default into recorded assumptions if nobody resolves them. The design then goes through a hardening pass that attacks the draft, folds surviving findings into a revised specification, decomposes the work into file-disjoint vertical-slice issues, drafts frozen checks, and stress-tests the decomposition.

This is useful when the request is larger than a single edit. A prompt such as “add team billing” hides questions about states, permissions, retries, persistence, user-visible errors, and rollout. A specification makes those decisions inspectable before builders start editing.

A practical intake request should name the outcome and the boundary:

/architect 4h add team billing with an owner-only plan change flow

Constraints:
- inspect the existing account and payment flows first
- preserve the current response shapes where possible
- identify unresolved product decisions as rulings
- produce acceptance checks for authorization, retries, and duplicate requests
- do not edit application files until the specification and issue split exist

The exact product request is yours; the important part is that the factory has enough information to expose ambiguity rather than bury it inside a large diff.

How frozen checks control the build

Architect-loop publishes the specification and issues to a tracker, then freezes checks in git before any builder exists. A frozen check is an expectation that later work must satisfy. It is deliberately separate from the builder’s report.

For a billing change, a check might assert that a request from a non-owner cannot change the plan, that a repeated provider event does not create a second entitlement, and that a failed provider call leaves the account in a known state. The project’s implementation can vary, but the check should describe an observable result.

A useful check record is small and testable:

RUN: owner-plan-change
WHEN: an authenticated member without owner permission submits a plan change
EXPECT: the request is rejected and the account plan is unchanged
EVIDENCE: focused test output plus the final diff

The factory’s check runner preserves the head, tail, and test summaries and can emit progress for killed or interrupted run items. The final review receives the closing test pass, including builder-built suites and frozen run items. That gives a reviewer more than a green-looking terminal message.

The takeaway is straightforward: tests tell you what happened in the cases they cover; frozen checks tell the workflow what must not be forgotten.

Why builders use fresh worktrees

Each builder receives a fresh worktree and one issue. Builders must state execution conflicts before coding, must not commit, and must end with one raw STATUS: line. The orchestrator owns the commits and the postflight merge decision.

File-disjoint issues reduce accidental overlap. They do not make conflicts impossible: shared configuration, generated outputs, and hidden runtime coupling can still create them. The value is that a conflict has a visible owner and a smaller touch-set to inspect.

The repository records the dispatch-head SHA for each job. In the full lane, the freeze SHA becomes the diff base; in the fast lane, the dispatch head serves that role. Postflight audits touched files before merging. This is a better boundary than trusting a builder to summarize every file it changed.

A builder issue should therefore be narrow:

Issue: add idempotency handling to the payment-event consumer
Allowed areas: server/events/payment.ts, server/events/payment.test.ts
Acceptance:
- duplicate event IDs do not create duplicate entitlements
- malformed events return the existing structured error
- focused tests cover first delivery and replay
- no migration or unrelated route changes

The issue body is not a substitute for the frozen checks, but it gives the builder a clear slice and limits the review surface.

What the wrapper and watchdog add

Long-running command-line work needs reliable exit truth. Architect-loop’s run-job.ps1|.sh wrapper owns heartbeat, exit status, stdout events, stderr logs, sandbox temporary paths, and kill scope. It writes artifacts including job.meta.json, job.heartbeat, job.exit.json, events.jsonl, and stderr.log.

That solves a common agent problem: a terminal-looking “done” message is not proof that the process exited successfully. Postflight refuses to merge command-line work without wrapper exit truth. The watchdog reports typed evidence such as stalls, repeated commands, blocked tool calls, orphaned wrappers, and failed exits. It does not kill, nudge, or grade the job; the orchestrator decides what to do.

This separation is important. Monitoring should report facts. A policy layer should decide whether to retry, stop, or open a fix issue. Mixing those responsibilities makes a stuck process harder to diagnose.

For a bounded fast change, the project intentionally removes some machinery. The fast lane allows at most three builder issues and roughly 400 changed lines. It has no strategist subagents, adversarial review, frozen checks, per-issue check runner, or watchdog script. Its issue acceptance criteria, builder tests, and closing review carry the gate. If the work exceeds that size ceiling, it recommends the full lane.

How final review becomes a shipping decision

After builders finish, the orchestrator runs the full closing test pass and sends the raw output to a fresh, read-only final reviewer. The reviewer returns either REVIEW: GREEN or a review specification plus fix issues. Fix issues use the same builder wave rather than receiving a special bypass.

The final review is intentionally read-only. It cannot quietly modify the work it is judging. If no findings remain, the workflow proceeds to integration. The integrate stage begins with a documentation pass, updates product docs, verifies the closing state, sweeps deferred worktree cleanup, and prepares either a pull request or a Markdown finish record depending on tracker mode.

This gives the end of the run a useful shape:

implementation evidence -> closing checks -> read-only review -> fix wave or GREEN -> integrate

A reviewer should still inspect the diff and the product behavior. The factory records evidence; it does not remove human responsibility for deciding whether the product requirement was correct.

GitHub mode versus Markdown mode

Architect-loop supports GitHub and Markdown tracker modes. GitHub mode requires a remote, authenticated gh version 2.94.0 or later, and push access. Sub-issues use native parent and blocked-by edges.

Markdown mode needs only a git repository. Issues live in docs/issues/<run>/ and carry the same parent, blocker, comment, and state relationships without requiring a GitHub remote. A Markdown run ends with a ready factory branch and merge instructions instead of an automatically opened pull request unless the in-session human directs otherwise.

The run manifest pins the tracking issue, tracker mode, factory branch, and specification path. This prevents a status command from guessing which run is “current” by scanning unrelated issues. Status takes a run slug, and local bookkeeping lives in run-scoped directories such as docs/runs/<run>/ and docs/jobs/<run>/.

For a small team, Markdown mode is a useful way to retain the process without adding a remote dependency. For a team already operating through GitHub issues and reviews, GitHub mode keeps the work closer to the existing collaboration surface.

What to borrow if you do not install it

You do not need the entire factory to adopt its strongest ideas. Start with five habits:

1. Ask for a repository-grounded specification before a multi-file edit.
2. Split work into file-disjoint vertical slices.
3. Freeze the acceptance checks before implementation.
4. Require raw command evidence and a real exit status.
5. Run a fresh read-only review before integration.

Keep the durable artifacts in your repository. A short plan, issue list, check set, and final diff are useful to the next engineer whether the previous change was made by a human, Cursor, Claude Code, or Codex.

That is also the practical connection to OTF: its paid full-stack kits provide owned application code with CLAUDE.md, .cursorrules, and 20+ tested AI prompts, giving an agent a known starting point rather than an empty project. AI provider portability covers the related model-boundary decision, and LLM observability covers tracing the calls and outcomes once the workflow reaches production.

Architect-loop is best understood as a staged evidence system for agent-assisted software delivery. Its fresh strategists, isolated builders, frozen checks, wrapped jobs, typed watchdog reports, and read-only final review address different failure modes. You can run the full factory, choose the fast lane, or borrow the five habits. The durable result is the same: fewer invisible assumptions between a feature request and a shipping decision.

Sources

• architect-loop repository — DanMcInerney
• architect-loop DESIGN.md
• architect-loop CONTEXT.md

For an owned application starting point that agents can extend, browse OTF templates.