loop — how it works

A value-ranked, auditable, pausable coding-agent loop. Agents: Codex or Claude Code (per role) · macOS only.

把一次性的 coding-agent prompt 变成「portfolio intake → verification → PM review → 白天执行 → 晚间复盘」的闭环。这页讲清：什么时候触发、触发后它自己干什么。

📄 README  ·  🤖 AGENTS.md  ·  ⚙️ examples

1 · Triggers 什么时候开始

① portfolio onboarding
First run asks for the portfolio registry once, then runs CTO catch-up profiles for each project. 首次建立项目组合并理解每个项目。
loop portfolio init · add · intake
② morning review + approval
Every morning verifies the full portfolio, ranks product and readiness value, then waits for explicit approval. 每天早上确认 portfolio，并把 readiness work 也按价值排序。
loop morning · approve
③ day loop / run-now
Approved projects start now, then run hourly until budget, stop condition, pause, or stop. 已批准项目先跑一轮，然后每小时推进。
loop start-day · run-now · stop

2 · One cycle, step by step 触发后它自己干这些

1
planner agent
Reads the approved daily-focus + PM review + last scorecard + bounded memory, then proposes value-scored candidates.
读早上批准的 focus 和反馈 → 产出按价值打分的候选 → candidates.json + issue 文件
2
gates checks
Candidates must pass every gate, or the cycle stops and waits for you. 过不了闸 → waiting_for_human 或 no-op。
value line · ≥ threshold do-nothing · no forced work blocked category risk envelope higher-value blocker
3
worker Codex / Claude
Runs on the role's provider (Codex or Claude Code); creates the GitHub issue, then edits code in an isolated worktree — confined to that worktree, only the issue's Allowed Files.
按角色用 Codex 或 Claude;先建 issue,再在隔离 worktree 里改代码,被关在 worktree 内、只能动白名单文件
4
verify + scan fail-closed
Trusted verification commands run under sandbox-exec (network denied, secret dirs denied), then an allowlist + secret-leak scan. 验证沙箱化 + 防泄露扫描。
sandbox-exec network denied secret-leak scan
5
reviewer agent
Must emit REVIEW_STATUS: pass | fail | needs_human. Only pass proceeds.
独立 reviewer 把关，只有 pass 才往下走
6
PR + merge automatic
On pass, the engine opens a PR and runs gh pr merge --delete-branch into the pilot branch — no human gate here.
reviewer 通过 = 自动开 PR 并合并，中间没有人工复核
7
summary + memory automatic
Writes the cycle-summary, distills bounded memory, optional Linear milestone — all automatic. The full digest report (loop-engine/reports/<project>/latest.md) is refreshed separately by loop digest (see Evening).
自动:写 cycle-summary + 沉淀 memory +（可选）Linear。完整 digest 报告由 loop digest 单独刷新(见晚上)
Default cap / 默认限流： only the top-ranked auto-runnable task runs per cycle (max_tasks_per_cycle = 1) to avoid same-cycle PR conflicts; the rest go to deferred-candidates.md. 一轮只做最高价值的一件事。

3 · Daily rhythm 每日节奏：早晨设方向 · 晚上看复盘

🌅 Morning — set focus, then trigger
① loop morning — shows Portfolio Registry Verification + Portfolio Readiness boards, then writes pm-reviews/latest.md and a value-ranked plan.
② loop approve <project> — writes .loop/daily-focus/latest.md; use --approve-medium for the whole day's bounded medium-risk envelope.
③ If the highest-value work is readiness, use loop approve <project> --init-loop instead of starting execution.
④ loop start-day — starts only approved executable projects; first cycle runs immediately, then hourly.
早上先确认完整 portfolio，再按价值排序；未 ready 的高价值项目可以先做 intake / contract / init。
🌙 Evening — recap, then score
① loop evening pauses active loops (or named projects).
② It refreshes digests: what merged, before/after, approval queue → loop-engine/reports/<project>/latest.md.
③ It writes loop-engine/evening-scorecards/latest.md and a daily report; tomorrow's PM review reads them.
晚上统一暂停、出复盘和 scorecard，喂给明天。

4 · What runs automatically vs. waits 什么自动跑、什么必须等人

Low-risk → auto
tests, docs, CLI/digest wording, deterministic parsing, small observability/refactors. Runs unattended after gates pass. 过闸后自动跑。
Medium-risk → supervised
visible UI, small product-surface or schema changes, bounded loop-init readiness. Needs a same-day approved envelope; the first execution is supervised by start-day or run-now --supervised. 要早上预批 envelope + 监督首跑。
High-risk → never auto
credentials, auth, launchd/cron, publishing/deploy, destructive ops, broker credentials, live orders, real-money movement, live trading config flips, broad rewrites. Always manual. Trading read-only analysis is not high-risk by default, but trading auto-run is default-deny except clearly read-only/backtest/data-quality review. 永远人工；trading 只读分析不是默认高风险，但自动执行默认拒绝非只读工作。
loop · value-first, fail-closed, pausable  ·  every claim here maps to loop-engine/bin/loopctl.py
本图为人而作（visual for humans）· 机读操作契约见 AGENTS.md