Architecture

Loop Factory has three layers.

1. Portable Factory

loop-factory CLI owns state transitions:

inbox spec -> prompt -> active spec -> review -> archive
                         \-> backprop prompt -> specs/docs update

State is file-based:

• factory/specs/inbox/: new work
• factory/specs/active/: dispatched work
• factory/specs/archive/: accepted work
• factory/prompts/: generated agent prompts
• factory/runs/: run manifests
• factory/reviews/: accepted review records

Spec creation includes a grill gate. Before dispatch, use grill-me style questioning one question at a time, then record decisions under # Grill Gate.

Built-in loops live in code as a small catalog and render prompts through loop-factory loops prompt <loop-id>. Each loop includes a trigger mode, iteration cap, check command, exit condition, and first step. This keeps loop control deterministic while agents handle implementation and verification.

2. Native Adapters

Codex adapter:

• .agents/skills/loop-factory
• .agents/skills/backpropagate-specs
• .agents/skills/review-and-archive
• .codex/agents/spec-implementer.toml
• .codex/agents/spec-reviewer.toml
• .codex/hooks.json

Claude adapter:

• .claude/skills/loop-factory
• .claude/skills/backpropagate-specs
• .claude/skills/review-and-archive
• .claude/agents/spec-implementer.md
• .claude/agents/spec-reviewer.md
• .claude/loop.md
• .claude/settings.json

3. CI Adapter

GitHub Actions provide non-interactive review:

• loop-factory.yml: validates Python CLI and spec queue
• codex-review.yml: optional Codex review action for pull requests

State Rules

• Only humans or explicit CLI commands move specs from inbox to active.
• Only accepted review moves active specs to archive.
• Failed review leaves spec active.
• Backprop can update specs/docs but must not change product intent silently.
• Generated prompt files are artifacts, not source of truth.

Agent Selection

Use one agent when:

• task is sequential
• same files will be edited
• risk is high and needs tight control

Use subagents when:

• independent research can run in parallel
• review should be context-isolated
• implementation and test-writing can be split by path

Use Claude dynamic workflows when:

• orchestration itself should be reusable code
• dozens of workers are useful
• intermediate results should stay out of context

Use Codex GitHub Action when:

• repeatable review belongs in CI
• task needs repository checkout but not local desktop state