architect-loop - GitLite

KO | EN

gitlite — search

#hacktoberfest #react #go #rust #linux #nodejs #macos #awesome #cli #vue #pytorch #security #ios #open-source

architect-loop

(★ 624)

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

파일 탐색기

최종 버전 다운로드 (.zip)

- architect-fast-flow.svg
- architect-flow.svg
- research-flow.svg
- - docs-finish.md
  - skill-guards.md
  - skill-text.md
  - trigger-evals.md
- - trigger-prompts.md
- - architect-fast.md
  - ground-scripts.md
  - judge-narrowing-and-scout.md
  - multi-run.md
  - review-fanout.md
  - scout-retirement.md
  - script-hardening.md
  - skill-hygiene.md
  - skill-library.md
- - SKILL.md
- - check-runner.ps1
  - check-runner.sh
  - dispatch.md
  - ffcheck.ps1
  - ffcheck.sh
  - ground.ps1
  - ground.sh
  - kill-job.ps1
  - kill-job.sh
  - loop.md
  - postflight.ps1
  - postflight.sh
  - preflight.ps1
  - preflight.sh
  - research.md
  - run-job.ps1
  - run-job.sh
  - SKILL.md
  - status.ps1
  - status.sh
  - sweep-deferred.ps1
  - sweep-deferred.sh
  - tracker.md
  - trigger-eval.ps1
  - trigger-eval.sh
  - watchdog.ps1
  - watchdog.sh
- - SKILL.md
- - SKILL.md
  - tactics.md
- - DEEPENING.md
  - DESIGN-IT-TWICE.md
  - SKILL.md
- - SKILL.md
  - TEST-STEWARDSHIP.md
- - SKILL.md
- - SKILL.md
- - mocking.md
  - SKILL.md
  - tests.md
- - SKILL.md
- - SKILL.md
- validate_skills.py
.gitattributes
.gitignore
CONTEXT.md
DESIGN.md
install.ps1
install.sh
LICENSE
README.md

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/DanMcInerney/architect-loop

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd architect-loop

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. 공식 설치 스크립트

쉬움 추천

사전 준비물

Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다.

npm i -g @openai/codex@latest # optional builder backend

npm 레지스트리에 배포된 패키지를 전역으로 설치합니다. 소스 클론이 필요 없습니다.

✅ 설치 후 새 터미널을 열고, 프로그램의 버전 확인 명령(예: --version)으로 정상 설치됐는지 확인하세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# architect-loop

**An autonomous software factory for Codex and Claude: one orchestrator,
fresh-context strategist and builder agents, deterministic gates,
and a single shipping PR or local finish record — no approval gates,
timed rulings all the way down.**

## Usage

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

- `/architect-research` explores a topic and writes an answer-first report.
- `/architect-fast` ships a small, bounded change through the light lane.
- `/architect` runs the full multi-hour factory. State the goal, then let it work.

## Installation

```bash
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 Changed Recently

- The loop is now a small stage-skill library: `codebase-design`, `to-spec`,
  `adversarial-review`, `to-issues`, `frozen-checks`, `tdd`,
  `final-review`, and `integrate`.
- Run identity is pinned by `docs/runs/<run>/manifest.md`; status commands
  take a run slug and no longer discover "the current run" by scanning issues.
- GitHub and markdown tracker modes share the same state machine. Markdown
  issues live in `docs/issues/<run>/` and need no GitHub remote.
- The closing `final-review` is read-only. It returns `REVIEW: GREEN` or a
  review spec plus fix issues; fix issues build through the same builder wave.
- CLI jobs now run through `run-job.ps1|.sh`, which owns heartbeat, exit truth,
  stdout events, stderr logs, sandbox temp/cache redirects, and kill scope.
- The watchdog is typed evidence only. It detects stalls, repeated commands,
  blocked tool calls, orphaned wrappers, failed exits, and legacy unwrapped jobs;
  the orchestrator still decides.
- `kill-job.ps1|.sh` is the explicit reaping action for stuck wrapped jobs.
- The check-runner preserves head, tail, and pytest summaries, and can emit
  progress events for killed or interrupted RUN items.
- Postflight can defer locked worktree cleanup; `sweep-deferred.ps1|.sh <run>`
  clears run-scoped debris before final close.

## Design

The current session is the **orchestrator**. It grounds the repo, dispatches
fresh agents, rules on typed evidence, owns commits, and posts the digest. A
configurable **strategist** subagent handles full-lane design and review work;
fresh **builders** implement exactly one issue each in isolated worktrees and
report raw evidence only. See [DESIGN.md](DESIGN.md) for the evidence trail and
[CONTEXT.md](CONTEXT.md) for the vocabulary.

### /architect

![architect flow](https://raw.githubusercontent.com/DanMcInerney/architect-loop/main/assets/architect-flow.svg)

- Intake feeds the goal straight to a fresh strategist that drafts the spec;
  open questions become timed rulings that auto-default into recorded
  assumptions. There is no human approval gate anywhere — the human steers
  by editing the spec, commenting rulings, or `docs/STOP`.
- One fresh harden strategist attacks the draft, folds surviving findings
  into a revised spec, decomposes it into file-disjoint vertical-slice
  issues, drafts frozen checks, and stress-tests its own decomposition.
- The orchestrator publishes the spec and issues to the tracker and owns the
  freeze commit. Checks freeze in git before any builder exists.
- The run manifest pins the tracking issue, tracker mode, factory branch, and
  spec path; every issue carries a run marker.
- Builders run in fresh worktrees. They must state execution conflicts before
  coding, must not commit, and must end with one raw `STATUS:` line.
- Wrapped CLI jobs write `job.meta.json`, `job.heartbeat`, `job.exit.json`,
  `events.jsonl`, and `stderr.log`; exit truth outranks terminal-looking report
  text. Postflight refuses to merge CLI job work without that wrapper exit
  truth — unwrapped work cannot merge.
- The OS sandbox is deliberately weak (`danger-full-access`): builders may
  use the network and the wider filesystem. The real boundaries are the
  postflight touch-set audit, the never-commit ban, and read-only frozen
  checks.
- The watchdog reports typed evidence only. It never kills, nudges, or grades.
  Stuck jobs are reaped with `kill-job.ps1|.sh` and respawned from durable issue
  context.
- The check-runner grades frozen RUN items with fixed expectations. Postflight
  audits touched files, merges green jobs, and records deferred cleanup if a
  worktree cannot be removed immediately.
- At finish the orchestrator runs the closing test pass — builder-built
  suites plus every frozen RUN item — and feeds the raw output into the
  final review: one fresh, read-only strategist pass over the whole run.
  Findings become fix issues and draft checks for a fix wave; zero findings
  short-circuit to integrate.
- `integrate` is a builder-model stage whose first step is the docs pass. It
  consumes the change-context digest, updates product docs, verifies the closing
  state, sweeps deferred cleanup, and prepares the PR or markdown finish record.

### /architect-fast

![architect-fast flow](https://raw.githubusercontent.com/DanMcInerney/architect-loop/main/assets/architect-fast-flow.svg)

- Same front door and tracker semantics as `/architect`, but capped at at most
  three builder issues and roughly 400 changed lines.
- No strategist subagents, no adversarial review, no frozen checks, no
  per-issue check-runner, and no watchdog script. Issue-body acceptance
  criteria, builder-run tests, and the closing builder review carry the gate.
- Each job records its dispatch-head SHA; that SHA is the postflight diff base
  in place of a freeze SHA.
- One per-wave timed fallback wake replaces watchdog monitoring.
- After all issues merge, the orchestrator runs the full test suite and hands
  the output to one fresh builder subagent that reviews code, cohesion, and
  tests, records its findings as one fix issue, and fixes them in its
  worktree; the orchestrator merges, records the verdict and diffstat, then
  dispatches `integrate`.
- If the work exceeds the size ceiling, the lane stops and recommends
  `/architect`.

### /architect-research

![research flow](https://raw.githubusercontent.com/DanMcInerney/architect-loop/main/assets/research-flow.svg)

- A scout maps brainstorm-scale topics before lanes are designed; quick
  fact-finds skip the scout.
- The orchestrator designs research lanes along the topic's real fault lines.
- Researchers gather in parallel under hard budgets and return compact findings
  tied to numbered sources.
- The draft is marked SUPPORTED / THIN / EMPTY. Thin or empty sections trigger
  up to two targeted gap rounds.
- Verification checks load-bearing claims against raw sources, including
  falsification searches, before one author writes the report.

## Config

Optional config lives at `.architect/config` or `~/.architect/config` (repo
wins; unknown keys warn and do not fail).

```ini
strategist = claude/best       # Fable-class design/review subagents
builders = codex/best          # GPT-5.5 xhigh builders; Fast pins when available
tracker = markdown             # local issue files; omit for GitHub mode
when broad ambiguous refactor -> codex/best:xhigh  # optional builder route
```

Role strings are `<cli>/<model-spec>[:<effort>]`, with `<cli>` `claude` or
`codex`. `best` and `tier-down` resolve per family. The orchestrator is always
the session you opened, never a config key.

Default full-lane routing uses `claude/best` for strategist stages and
`codex/best` for builders. If a configured CLI is missing, the loop records the
substitution on the tracker instead of silently changing behavior. Codex
builders under ChatGPT auth use Fast-mode pins when available; API-key auth
drops those pins with a recorded substitution.

### Tracker Modes

`tracker = github` needs a GitHub remote, authenticated `gh >= 2.94.0`, and push
access. Sub-issues use native parent and blocked-by edges.

`tracker = markdown` needs only a git repo. Issues are git-tracked markdown
files in `docs/issues/<run>/`, with the same parent/blocker semantics, comments,
states, and status tree. The run finishes with a ready factory branch and merge
instructions instead of an auto-opened PR unless the in-session human directs
otherwise.

### Run Artifacts

Versioned run inputs live under `docs/spec/`, `docs/checks/<run>/`, and, in
markdown mode, `docs/issues/<run>/`.

Local run bookkeeping is gitignored: manifests under `docs/runs/<run>/`, job
reports and check evidence under `docs/jobs/<run>/`, wrapper files under
`.architect/jobs/<run>/`, builder worktrees under `.architect/wt/<run>/`, and
temporary sandbox/cache paths under `.architect/tmp/`.

Status is scripted. By default it renders the README-style workflow map with
live stage glyphs and builder cards; pass `--compact` / `-Compact` for the
legacy line tree:

```bash
skills/architect/status.sh <run> [--compact]
```

```powershell
skills\architect\status.ps1 <run> [-Compact]
```

Stage-only progress that cannot be inferred from tracker or job artifacts can
be recorded in local `docs/runs/<run>/status-events.jsonl` breadcrumbs.

An empty `docs/STOP` file halts every run at the next dispatch boundary. An
empty `docs/runs/<run>/STOP` halts only that run.

## Validation

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

The validator checks skill trigger hygiene, sibling-file pointers, README and
DESIGN links, fenced code blocks, runner contracts, wrapper/watchdog fixtures,
and the shipped architectural invariants.

## License

MIT