Skip to content
Back to search

architect-loop

Super optimized /goal loop. Massive token savings and higher quality. Smart model designs and reviews, cheaper model builds..

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/danmcinerney--architect-loop/badge.svg)](/listings/danmcinerney--architect-loop)

HTML

<a href="/listings/danmcinerney--architect-loop"><img src="/api/listings/danmcinerney--architect-loop/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 same `skills/` tree to Claude and Codex skill locations. Use `./install.sh --project` or `.\install.ps1 -Project` to install into the current repo instead of your user profile.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 212 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. Note: orchflows now replaces this hardcoded workflow with a library that can build any kind of workflow like this with only 2 skills. https://github.com/DanMcInerney/orchflows/
  2. # architect-loop
  3. **An autonomous software factory for Codex and Claude: one orchestrator,
  4. fresh-context strategist and builder agents, deterministic gates,
  5. and a single shipping PR or local finish record — no approval gates,
  6. timed rulings all the way down.**
  7. ## Usage
  8. ```text
  9. /architect-research <topic>
  10. /architect <hours+ feature/product request>
  11. /architect-fast <small change>
  12. ```
  13. - `/architect-research` explores a topic and writes an answer-first report.
  14. - `/architect-fast` ships a small, bounded change through the light lane.
  15. - `/architect` runs the full multi-hour factory. State the goal, then let it work.
  16. ## Installation
  17. ```bash
  18. git clone https://github.com/DanMcInerney/architect-loop
  19. cd architect-loop && ./install.sh # Windows: .\install.ps1
  20. npm i -g @openai/codex@latest # optional builder backend
  21. ```
  22. The installer copies the same `skills/` tree to Claude and Codex skill
  23. locations. Use `./install.sh --project` or `.\install.ps1 -Project` to install
  24. into the current repo instead of your user profile.
  25. ## What Changed Recently
  26. - The loop is now a small stage-skill library: `codebase-design`, `to-spec`,
  27. `adversarial-review`, `to-issues`, `frozen-checks`, `tdd`,
  28. `final-review`, and `integrate`.
  29. - Run identity is pinned by `docs/runs/<run>/manifest.md`; status commands
  30. take a run slug and no longer discover "the current run" by scanning issues.
  31. - GitHub and markdown tracker modes share the same state machine. Markdown
  32. issues live in `docs/issues/<run>/` and need no GitHub remote.
  33. - The closing `final-review` is read-only. It returns `REVIEW: GREEN` or a
  34. review spec plus fix issues; fix issues build through the same builder wave.
  35. - CLI jobs now run through `run-job.ps1|.sh`, which owns heartbeat, exit truth,
  36. stdout events, stderr logs, sandbox temp/cache redirects, and kill scope.
  37. - The watchdog is typed evidence only. It detects stalls, repeated commands,
  38. blocked tool calls, orphaned wrappers, failed exits, and legacy unwrapped jobs;
  39. the orchestrator still decides.
  40. - `kill-job.ps1|.sh` is the explicit reaping action for stuck wrapped jobs.
  41. - The check-runner preserves head, tail, and pytest summaries, and can emit
  42. progress events for killed or interrupted RUN items.
  43. - Postflight can defer locked worktree cleanup; `sweep-deferred.ps1|.sh <run>`
  44. clears run-scoped debris before final close.
  45. ## Design
  46. The current session is the **orchestrator**. It grounds the repo, dispatches
  47. fresh agents, rules on typed evidence, owns commits, and posts the digest. A
  48. configurable **strategist** subagent handles full-lane design and review work;
  49. fresh **builders** implement exactly one issue each in isolated worktrees and
  50. report raw evidence only. See [DESIGN.md](DESIGN.md) for the evidence trail and
  51. [CONTEXT.md](CONTEXT.md) for the vocabulary.
  52. ### /architect
  53. ![architect flow](assets/architect-flow.svg)
  54. - Intake feeds the goal straight to a fresh strategist that drafts the spec;
  55. open questions become timed rulings that auto-default into recorded
  56. assumptions. There is no human approval gate anywhere — the human steers
  57. by editing the spec, commenting rulings, or `docs/STOP`.
  58. - One fresh harden strategist attacks the draft, folds surviving findings
  59. into a revised spec, decomposes it into file-disjoint vertical-slice
  60. issues, drafts frozen checks, and stress-tests its own decomposition.
  61. - The orchestrator publishes the spec and issues to the tracker and owns the
  62. freeze commit. Checks freeze in git before any builder exists.
  63. - The run manifest pins the tracking issue, tracker mode, factory branch, and
  64. spec path; every issue carries a run marker.
  65. - Builders run in fresh worktrees. They must state execution conflicts before
  66. coding, must not commit, and must end with one raw `STATUS:` line.
  67. - Wrapped CLI jobs write `job.meta.json`, `job.heartbeat`, `job.exit.json`,
  68. `events.jsonl`, and `stderr.log`; exit truth outranks terminal-looking report
  69. text. Postflight refuses to merge CLI job work without that wrapper exit
  70. truth — unwrapped work cannot merge.
  71. - The OS sandbox is deliberately weak (`danger-full-access`): builders may
  72. use the network and the wider filesystem. The real boundaries are the
  73. postflight touch-set audit, the never-commit ban, and read-only frozen
  74. checks.
  75. - The watchdog reports typed evidence only. It never kills, nudges, or grades.
  76. Stuck jobs are reaped with `kill-job.ps1|.sh` and respawned from durable issue
  77. context.
  78. - The check-runner grades frozen RUN items with fixed expectations. Postflight
  79. audits touched files, merges green jobs, and records deferred cleanup if a
  80. worktree cannot be removed immediately.
  81. - At finish the orchestrator runs the closing test pass — builder-built
  82. suites plus every frozen RUN item — and feeds the raw output into the
  83. final review: one fresh, read-only strategist pass over the whole run.
  84. Findings become fix issues and draft checks for a fix wave; zero findings
  85. short-circuit to integrate.
  86. - `integrate` is a builder-model stage whose first step is the docs pass. It
  87. consumes the change-context digest, updates product docs, verifies the closing
  88. state, sweeps deferred cleanup, and prepares the PR or markdown finish record.
  89. ### /architect-fast
  90. ![architect-fast flow](assets/architect-fast-flow.svg)
  91. - Same front door and tracker semantics as `/architect`, but capped at at most
  92. three builder issues and roughly 400 changed lines.
  93. - No strategist subagents, no adversarial review, no frozen checks, no
  94. per-issue check-runner, and no watchdog script. Issue-body acceptance
  95. criteria, builder-run tests, and the closing builder review carry the gate.
  96. - Each job records its dispatch-head SHA; that SHA is the postflight diff base
  97. in place of a freeze SHA.
  98. - One per-wave timed fallback wake replaces watchdog monitoring.
  99. - After all issues merge, the orchestrator runs the full test suite and hands
  100. the output to one fresh builder subagent that reviews code, cohesion, and
  101. tests, records its findings as one fix issue, and fixes them in its
  102. worktree; the orchestrator merges, records the verdict and diffstat, then
  103. dispatches `integrate`.
  104. - If the work exceeds the size ceiling, the lane stops and recommends
  105. `/architect`.
  106. ### /architect-research
  107. ![research flow](assets/research-flow.svg)
  108. - A scout maps brainstorm-scale topics before lanes are designed; quick
  109. fact-finds skip the scout.
  110. - The orchestrator designs research lanes along the topic's real fault lines.
  111. - Researchers gather in parallel under hard budgets and return compact findings
  112. tied to numbered sources.
  113. - The draft is marked SUPPORTED / THIN / EMPTY. Thin or empty sections trigger
  114. up to two targeted gap rounds.
  115. - Verification checks load-bearing claims against raw sources, including
  116. falsification searches, before one author writes the report.
  117. ## Config
  118. Optional config lives at `.architect/config` or `~/.architect/config` (repo
  119. wins; unknown keys warn and do not fail).
  120. ```ini
  121. strategist = claude/best # Fable-class design/review subagents
  122. builders = codex/best # GPT-5.5 xhigh builders; Fast pins when available
  123. tracker = markdown # local issue files; omit for GitHub mode
  124. when broad ambiguous refactor -> codex/best:xhigh # optional builder route
  125. ```
  126. Role strings are `<cli>/<model-spec>[:<effort>]`, with `<cli>` `claude` or
  127. `codex`. `best` and `tier-down` resolve per family. The orchestrator is always
  128. the session you opened, never a config key.
  129. Default full-lane routing uses `claude/best` for strategist stages and
  130. `codex/best` for builders. If a configured CLI is missing, the loop records the
  131. substitution on the tracker instead of silently changing behavior. Codex
  132. builders under ChatGPT auth use Fast-mode pins when available; API-key auth
  133. drops those pins with a recorded substitution.
  134. ### Tracker Modes
  135. `tracker = github` needs a GitHub remote, authenticated `gh >= 2.94.0`, and push
  136. access. Sub-issues use native parent and blocked-by edges.
  137. `tracker = markdown` needs only a git repo. Issues are git-tracked markdown
  138. files in `docs/issues/<run>/`, with the same parent/blocker semantics, comments,
  139. states, and status tree. The run finishes with a ready factory branch and merge
  140. instructions instead of an auto-opened PR unless the in-session human directs
  141. otherwise.
  142. ### Run Artifacts
  143. Versioned run inputs live under `docs/spec/`, `docs/checks/<run>/`, and, in
  144. markdown mode, `docs/issues/<run>/`.
  145. Local run bookkeeping is gitignored: manifests under `docs/runs/<run>/`, job
  146. reports and check evidence under `docs/jobs/<run>/`, wrapper files under
  147. `.architect/jobs/<run>/`, builder worktrees under `.architect/wt/<run>/`, and
  148. temporary sandbox/cache paths under `.architect/tmp/`.
  149. Status is scripted. By default it renders the README-style workflow map with
  150. live stage glyphs and builder cards; pass `--compact` / `-Compact` for the
  151. legacy line tree:
  152. ```bash
  153. skills/architect/status.sh <run> [--compact]
  154. ```
  155. ```powershell
  156. skills\architect\status.ps1 <run> [-Compact]
  157. ```
  158. Stage-only progress that cannot be inferred from tracker or job artifacts can
  159. be recorded in local `docs/runs/<run>/status-events.jsonl` breadcrumbs.
  160. An empty `docs/STOP` file halts every run at the next dispatch boundary. An
  161. empty `docs/runs/<run>/STOP` halts only that run.
  162. ## Validation
  163. ```bash
  164. uv run --no-project python tests/validate_skills.py
  165. ```
  166. The validator checks skill trigger hygiene, sibling-file pointers, README and
  167. DESIGN links, fenced code blocks, runner contracts, wrapper/watchdog fixtures,
  168. and the shipped architectural invariants.
  169. ## License
  170. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.