raphael-loop
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseRaphaelLoop
RaphaelLoop
Treat the user's complete request as one goal. Preserve its objective, constraints, exclusions, approval boundaries, and stop conditions across every iteration.
Use this flow:
text
Goal -> Contract -> Baseline -> Task DAG -> Bounded work -> Independent verification -> Checkpoint -> Terminal decisionDo not start an open-ended loop. Convert ambiguous persistence such as “keep going,” “make it good,” or “until done” into observable predicates and finite limits first.
将用户的完整请求视为一个目标。在每次迭代中保留其目标、约束、排除项、审批边界和终止条件。
使用以下流程:
text
Goal -> Contract -> Baseline -> Task DAG -> Bounded work -> Independent verification -> Checkpoint -> Terminal decision不要启动无限制循环。首先将“继续进行”“做得更好”或“直到完成”这类模糊的持续性要求转换为可观察的判定条件和有限限制。
1. Admit or decline the loop
1. 接受或拒绝循环
Start RaphaelLoop only when all of these are true:
- The goal can be evaluated by a repeatable command, query, inspection, or measurable artifact.
- Work can be split into increments that fit within one iteration.
- Scope, prohibited changes, and approval boundaries are known.
- At least one finite iteration, time, token, cost, or deadline limit exists.
Use a disclosed default limit of 10 iterations only when the goal, scope, verifier, and approval boundary are already valid. Route one-step work to a normal task instead of creating loop state.
Decline the loop when success depends entirely on taste, required evidence is unavailable, continuous monitoring has no finite boundary, or the requested automation would perform unapproved irreversible actions.
仅当满足以下所有条件时才启动RaphaelLoop:
- 目标可通过可重复的命令、查询、检查或可衡量的工件进行评估。
- 工作可拆分为适合单次迭代的增量任务。
- 范围、禁止变更内容和审批边界已知。
- 存在至少一个有限的迭代次数、时间、token、成本或截止期限限制。
仅当目标、范围、验证器和审批边界均有效时,才使用公开的默认限制——10次迭代。将单步工作路由至常规任务,而非创建循环状态。
当成功完全取决于主观偏好、所需证据不可用、持续监控无有限边界,或请求的自动化将执行未获批准的不可逆操作时,拒绝启动循环。
2. Select one host protocol
2. 选择一个宿主协议
Identify the current host and keep it fixed for the goal:
| Host | Skill location | Agent destination | Bundled protocol |
|---|---|---|---|
| Codex | | | |
| Claude Code | | | |
Resolve from the absolute path of this loaded ; do not assume the consumer project's working directory contains RaphaelLoop scripts. The host role health check is required before Agent dispatch in or . Skip it for read-only and unless the user explicitly asks to audit host registration:
SKILL_DIRSKILL.mdrunresumedesignauditbash
bash "$SKILL_DIR/scripts/install-agents.sh" --harness <codex-or-claude> --checkInterpret exit codes exactly:
- : continue.
0 - : run the installer with
10, report every host-level target, obtain explicit approval, then run it without--dry-runand check again. Stop as--dry-runif approval is unavailable.blocked - : correct the host argument or ask one focused question if the host cannot be identified.
2 - : run
3, explain which host-level files would be backed up or replaced, and obtain explicit approval before refreshing them. Check again after refresh; otherwise stop before dispatch.--dry-run - : report an invalid bundled Agent set and stop.
4
The installer must use only files inside this Skill. Do not download an Agent catalog or substitute remote instructions.
Treat bundled Agent files as a separate host-level lifecycle from the Skill directory. A Skills CLI update or removal does not refresh or remove them automatically.
- For a requested refresh, run , obtain explicit approval for the reported targets, run the installer, and finish with
--dry-run.--check - Before removing the Skill, run , report the exact managed files, obtain explicit approval, then run
--uninstall --dry-run. Tell the user to remove the Skill with their package manager only after this succeeds.--uninstall - If uninstall returns , do not delete or overwrite anything. The files differ from the current manifest; require review or an approved refresh first.
3 - Never remove backup directories automatically.
识别当前宿主并为该目标保持固定:
| 宿主 | Skill 位置 | Agent 目标路径 | 捆绑协议 |
|---|---|---|---|
| Codex | | | |
| Claude Code | | | |
从已加载的的绝对路径解析;不要假设消费者项目的工作目录包含RaphaelLoop脚本。在或中调度Agent前,必须进行宿主角色健康检查。对于只读的和模式,除非用户明确要求审核宿主注册,否则跳过此检查:
SKILL.mdSKILL_DIRrunresumedesignauditbash
bash "$SKILL_DIR/scripts/install-agents.sh" --harness <codex-or-claude> --check严格解释退出代码:
- :继续执行。
0 - :使用
10运行安装程序,报告每个宿主级目标,获取明确批准后,不带--dry-run重新运行并再次检查。若无法获得批准,则标记为--dry-run并停止。blocked - :修正宿主参数,若无法识别宿主则提出一个聚焦问题。
2 - :运行
3,说明哪些宿主级文件将被备份或替换,在刷新前获取明确批准。刷新后再次检查;否则在调度前停止。--dry-run - :报告无效的捆绑Agent集并停止。
4
安装程序必须仅使用此Skill内的文件。不得下载Agent目录或替换为远程指令。
将捆绑Agent文件视为与Skill目录分离的宿主级生命周期。Skills CLI的更新或移除不会自动刷新或删除这些文件。
- 若请求刷新,运行,获取对报告目标的明确批准,运行安装程序,最后执行
--dry-run。--check - 在移除Skill前,运行,报告确切的受管文件,获取明确批准后,运行
--uninstall --dry-run。仅在此操作成功后,告知用户使用包管理器移除Skill。--uninstall - 若卸载返回,请勿删除或覆盖任何内容。文件与当前清单不符;需先进行审核或获得批准的刷新。
3 - 切勿自动删除备份目录。
3. Select one operating mode
3. 选择一种运行模式
Choose exactly one mode before loading or mutating loop state:
| Mode | Use when | Allowed behavior |
|---|---|---|
| The user needs a governed loop definition before execution. | Inspect read-only context, compile and validate a contract, explain risks; do not initialize state or change the project. |
| The user authorizes implementation toward the contract. | Initialize or resume state, claim work, implement, verify, checkpoint, recover, and decide. |
| A prior loop was interrupted or compacted. | Load state, run an integrity audit, preserve counters and verified tasks, then continue only from the runnable frontier. |
| The user needs a review of a contract, loop state, or evidence. | Run |
Infer only when the request clearly authorizes changes. Use for planning requests and for review requests. A status request remains read-only. Do not turn an audit into implementation.
rundesignaudit在加载或修改循环状态前,精确选择一种模式:
| 模式 | 使用场景 | 允许行为 |
|---|---|---|
| 用户需要在执行前获得受管控的循环定义。 | 检查只读上下文,编译并验证合约,解释风险;不初始化状态或修改项目。 |
| 用户授权朝着合约目标进行实现工作。 | 初始化或恢复状态,认领工作,执行实现,验证,创建checkpoint,恢复,并做出决策。 |
| 先前的循环被中断或压缩。 | 加载状态,运行完整性审核,保留计数器和已验证任务,仅从可运行的前沿继续执行。 |
| 用户需要审核合约、循环状态或证据。 | 运行 |
仅当请求明确授权变更时,才推断使用模式。规划请求使用模式,审核请求使用模式。状态请求保持只读。不得将审核转为实现工作。
rundesignaudit4. Compile the executable goal contract
4. 编译可执行的目标合约
Create a JSON contract using examples/runtime-contract.json, then validate it before changing the project. Load references/runtime.md when constructing fields or operating the kernel.
text
schema_version, goal_id, objective, success_mode,
scope.allowed, scope.prohibited,
predicates[id, kind, command[], timeout_seconds, runs, required_passes],
limits[max_iterations, max_minutes, max_tokens, max_cost, max_recoveries, max_stalls],
approval_gates,
tasks[id, deliverable, depends_on, scope, predicate_ids, rollback_plan, side_effects]Require an objective, scope, at least one predicate, fixed verifier argument arrays, a finite value for every limit, and a predicate-linked acyclic task graph. Ask one question that removes the largest blocking ambiguity when any required field cannot be derived safely.
Do not accept subjective predicates such as , , or . A count-only request succeeds after the requested count; report quality metrics separately instead of inventing a quality claim.
looks goodproduction readykeep improvingVerifier commands must be arrays, never shell strings. Side effects require a declared approval gate and idempotency key, but the runtime never executes them. In , run ; this validates without creating consumer state.
designpython3 "$SKILL_DIR/scripts/raphael_loop.py" validate --contract /absolute/contract.json使用examples/runtime-contract.json创建JSON合约,然后在修改项目前进行验证。构建字段或运行内核时,加载references/runtime.md。
text
schema_version, goal_id, objective, success_mode,
scope.allowed, scope.prohibited,
predicates[id, kind, command[], timeout_seconds, runs, required_passes],
limits[max_iterations, max_minutes, max_tokens, max_cost, max_recoveries, max_stalls],
approval_gates,
tasks[id, deliverable, depends_on, scope, predicate_ids, rollback_plan, side_effects]要求包含目标、范围、至少一个判定条件、固定的验证器参数数组、每个限制的有限值,以及与判定条件关联的无环任务图。当任何必填字段无法安全推导时,提出一个能消除最大阻塞歧义的问题。
不接受“看起来不错”“可用于生产”或“持续改进”这类主观判定条件。仅计数的请求在达到请求次数后即成功;单独报告质量指标,而非主观臆断质量达标。
验证器命令必须为数组,而非shell字符串。副作用需要声明的审批门和幂等键,但运行时从不执行它们。在模式下,运行;此操作仅验证合约,不创建消费者状态。
designpython3 "$SKILL_DIR/scripts/raphael_loop.py" validate --contract /absolute/contract.json5. Initialize recoverable runtime state
5. 初始化可恢复的运行时状态
Use the bundled zero-dependency Python kernel for every mechanical transition. Resolve it from the loaded Skill, not the consumer working directory:
bash
RAPHAEL_RUNTIME="$SKILL_DIR/scripts/raphael_loop.py"
python3 "$RAPHAEL_RUNTIME" init --contract /absolute/contract.json --project /absolute/projectStore active state at inside the consumer project. Add to that project's ignore rules when appropriate. Do not hand-edit runtime state, counters, leases, evidence, hashes, or checkpoint snapshots.
.raphael-loop/<goal-id>/state.json.raphael-loop/The state records:
text
contract and hash; project root and baseline fingerprint;
status; task DAG; ownership leases; evidence ledger;
iteration, time, token, cost, recovery, and stall usage;
failure signatures; last verified checkpoint; transition eventsinitresumed: trueresumeIn , run and before claiming work. In , use or only. The runtime captures a project fingerprint and writes a checkpoint only after fresh verification so resumed work can distinguish delivery claims from accepted evidence.
resumeaudit --statestatusauditaudit --contractaudit --state使用捆绑的零依赖Python内核处理所有机械转换。从已加载的Skill解析内核路径,而非消费者工作目录:
bash
RAPHAEL_RUNTIME="$SKILL_DIR/scripts/raphael_loop.py"
python3 "$RAPHAEL_RUNTIME" init --contract /absolute/contract.json --project /absolute/project将活动状态存储在消费者项目内的中。适当时将添加到该项目的忽略规则中。请勿手动编辑运行时状态、计数器、租约、证据、哈希或checkpoint快照。
.raphael-loop/<goal-id>/state.json.raphael-loop/状态记录包含:
text
合约及哈希;项目根目录和基线指纹;
状态;任务DAG;所有权租约;证据台账;
迭代、时间、token、成本、恢复和停滞的使用情况;
失败签名;最后一次验证的checkpoint;转换事件仅当合约哈希匹配时,才会恢复现有状态。若返回,则在认领工作前执行审核。切勿重置预算使用情况或重复已验证的任务。合约发生实质性变更时,需要新的目标ID或明确停用旧状态。
initresumed: trueresume在模式下,认领工作前运行和。在模式下,仅使用或。运行时仅在完成新验证后才捕获项目指纹并写入checkpoint,以便恢复的工作能区分交付声明与已接受的证据。
resumeaudit --statestatusauditaudit --contractaudit --state6. Build the minimum task DAG
6. 构建最小任务DAG
Work backward from the predicates:
- Add a baseline task for each verifier.
- Derive the smallest deliverables that can change a failing predicate.
- Connect real dependencies and expose the runnable frontier.
- Split oversized work into independently verifiable vertical increments.
- Use bounded read-only investigation tasks for unknowns.
- Delete tasks that do not affect a predicate or remove a blocking dependency.
Every task must include:
text
id, deliverable, dependencies, acceptance, allowed_scope,
capability, risk, status, owner, evidenceUse only , , , , , or as task status. Move a task to only after its acceptance check passes.
pendingrunnableactiveverifiedfailedblockedverified从判定条件倒推:
- 为每个验证器添加基线任务。
- 推导能改变失败判定条件的最小交付物。
- 连接实际依赖关系并暴露可运行的前沿任务。
- 将过大的工作拆分为可独立验证的垂直增量任务。
- 对未知内容使用有界的只读调查任务。
- 删除不影响判定条件或无法消除阻塞依赖的任务。
每个任务必须包含:
text
id, deliverable, dependencies, acceptance, allowed_scope,
capability, risk, status, owner, evidence仅使用、、、、或作为任务状态。仅当验收检查通过后,才将任务标记为。
pendingrunnableactiveverifiedfailedblockedverified7. Route the built-in roles
7. 路由内置角色
Use these protocol-equivalent roles:
| Role | Responsibility |
|---|---|
| Maintain contract, limits, checkpoints, progress, and terminal decision. |
| Produce the minimum predicate-linked task DAG. |
| Assign runnable work with exclusive ownership. |
| Deliver one bounded task packet. |
| Independently evaluate the declared acceptance checks. |
| Turn a stable failure signature into one new recovery action or a stop recommendation. |
Prefer a host-provided specialist when its description directly matches the required capability. Use when no specialist exists. Always retain and an independent .
loop-workerloop-controllerloop-verifierSend every assigned Agent a compact packet containing:
text
contract summary, task id, current evidence, exclusive responsibility,
allowed scope, dependencies, acceptance command, expected return, prohibitionsRequire each Agent to return , changes or findings, , and . Do not send unrelated conversation history.
statusevidencerisksThe Controller is the only role that requests terminal ; the Orchestrator requests ; the Worker reports a bounded outcome through ; the Verifier requests ; and Recovery requests . Agents may propose transitions, but they must not simulate successful kernel output or edit state directly.
decideclaimrecordverifyretryRun at most three workers concurrently and preserve one host slot for the root. Parallelize only tasks with disjoint files, external objects, dependencies, and mutable state. Sequence shared ownership and integration work.
使用以下协议等效角色:
| 角色 | 职责 |
|---|---|
| 维护合约、限制、checkpoint、进度和最终决策。 |
| 生成与判定条件关联的最小任务DAG。 |
| 分配可运行的工作并赋予专属所有权。 |
| 交付一个有界任务包。 |
| 独立评估声明的验收检查。 |
| 将稳定的失败签名转换为一个新的恢复操作或停止建议。 |
当宿主提供的专家角色描述直接匹配所需能力时,优先使用该角色。若无专家角色,则使用。始终保留和独立的。
loop-workerloop-controllerloop-verifier向每个分配的Agent发送一个紧凑数据包,包含:
text
合约摘要、任务ID、当前证据、专属职责、
允许范围、依赖关系、验收命令、预期返回值、禁止事项要求每个Agent返回、变更或发现结果、和。请勿发送无关的对话历史。
statusevidencerisks只有Controller角色可请求最终;Orchestrator请求;Worker通过报告有界结果;Verifier请求;Recovery请求。Agent可提议转换,但不得模拟成功的内核输出或直接编辑状态。
decideclaimrecordverifyretry最多同时运行三个worker,并为根节点保留一个宿主插槽。仅对文件、外部对象、依赖关系和可变状态互不相交的任务进行并行处理。对共享所有权和集成工作进行序列化处理。
8. Execute one bounded iteration
8. 执行一次有界迭代
At each loop boundary:
- Refresh cancellation, limits, and predicate evidence.
- Apply terminal rules before spending another iteration.
- Select the smallest critical-path increment from the runnable frontier.
- Assign the minimum capable, non-conflicting Agent set.
- Let the root integrate results and resolve ownership conflicts.
- Ask to run the predeclared checks independently.
loop-verifier - Update the DAG, progress vector, failure signature, and checkpoint.
- Apply terminal rules again.
For the executable transitions, use:
bash
python3 "$RAPHAEL_RUNTIME" claim --state "$STATE" --task "$TASK" --owner "$OWNER"
python3 "$RAPHAEL_RUNTIME" record --state "$STATE" --task "$TASK" --owner "$OWNER" --outcome progress
python3 "$RAPHAEL_RUNTIME" verify --state "$STATE" --predicate "$PREDICATE"
python3 "$RAPHAEL_RUNTIME" checkpoint --state "$STATE" --task "$TASK" --owner "$OWNER"
python3 "$RAPHAEL_RUNTIME" decide --state "$STATE"The root performs project edits through normal host tools between and . The kernel only governs state and declared verifiers. A checkpoint rejects evidence when any project file changes after verification.
claimrecordCount one iteration from task selection through verification and checkpoint. Do not count a pure status check, approval wait, or recovery-state load as a new iteration.
Define measurable progress as at least one of:
- A success-predicate metric improves.
- A task passes its acceptance check.
- A blocking dependency is removed and independently verified.
Do not count elapsed time, code volume, Agent output, replanning, or unverified completion claims as progress.
在每个循环边界:
- 刷新取消指令、限制和判定条件证据。
- 在消耗下一次迭代前应用终止规则。
- 从可运行的前沿任务中选择最小的关键路径增量任务。
- 分配能力匹配且无冲突的最小Agent集合。
- 让根节点整合结果并解决所有权冲突。
- 请求独立运行预先声明的检查。
loop-verifier - 更新DAG、进度向量、失败签名和checkpoint。
- 再次应用终止规则。
对于可执行的转换,使用:
bash
python3 "$RAPHAEL_RUNTIME" claim --state "$STATE" --task "$TASK" --owner "$OWNER"
python3 "$RAPHAEL_RUNTIME" record --state "$STATE" --task "$TASK" --owner "$OWNER" --outcome progress
python3 "$RAPHAEL_RUNTIME" verify --state "$STATE" --predicate "$PREDICATE"
python3 "$RAPHAEL_RUNTIME" checkpoint --state "$STATE" --task "$TASK" --owner "$OWNER"
python3 "$RAPHAEL_RUNTIME" decide --state "$STATE"根节点在和之间通过常规宿主工具执行项目编辑。内核仅管控状态和已声明的验证器。当验证后任何项目文件发生变更时,checkpoint会拒绝该证据。
claimrecord从任务选择到验证和checkpoint完成,计为一次迭代。纯状态检查、等待审批或加载恢复状态不计入新迭代。
可衡量的进度定义为至少满足以下一项:
- 成功判定条件的指标有所改善。
- 任务通过其验收检查。
- 阻塞依赖被移除并经过独立验证。
请勿将耗时、代码量、Agent输出、重新规划或未经验证的完成声明计为进度。
9. Recover without retry loops
9. 无重试循环的恢复
Normalize a failure signature as:
text
<verifier-name> + <exit-code-or-result> + <error-class>On the first occurrence, preserve the raw evidence and assign one targeted hypothesis. If the same signature returns after recovery and no new actionable evidence or alternative critical-path task exists, stop as .
loop-recoveryblockedRecord the recovery boundary with . The first matching signature permits one new action; its second matching occurrence blocks the task. The runtime records but never performs a rollback or side effect.
python3 "$RAPHAEL_RUNTIME" retry ...Stop as after two completed iterations leave the progress vector unchanged. Switch to a different runnable critical-path task once when evidence supports it; do not hide a stall with unrelated work.
blockedResume a blocked goal only after new evidence, permission, user input, or environment state changes the blocking condition. Preserve prior history and start a new recovery audit.
将失败签名标准化为:
text
<verifier-name> + <exit-code-or-result> + <error-class>首次出现时,保留原始证据并为分配一个针对性假设。若恢复后仍返回相同签名,且无新的可操作证据或替代关键路径任务,则标记为并停止。
loop-recoveryblocked使用记录恢复边界。首次匹配签名允许一个新操作;第二次匹配则阻塞该任务。运行时记录但从不执行回滚或副作用。
python3 "$RAPHAEL_RUNTIME" retry ...若两次完整迭代后进度向量未发生变化,则标记为并停止。当证据支持时,切换到不同的可运行关键路径任务一次;请勿用无关工作掩盖停滞。
blocked仅当新证据、权限、用户输入或环境状态改变阻塞条件后,才恢复被阻塞的目标。保留先前历史并启动新的恢复审核。
10. Apply deterministic terminal priority
10. 应用确定性终止优先级
Use this exact priority:
text
cancelled > succeeded > exhausted > blocked- : the user cancels or replaces the goal.
cancelled - : the contract's
succeededorallpredicate combination is true in fresh independent evidence.any - : a finite limit is reached before success.
exhausted - : the stall or repeated-failure rule is met, or a required permission, input, tool, or dependency remains unavailable.
blocked
When success and a limit are reached in the same verified checkpoint, use . Treat an unavailable, failed, or stale verifier as , never as success.
succeededunknownStop immediately after a terminal decision. Do not add optional cleanup or unrelated improvements after the goal ends.
使用以下精确优先级:
text
cancelled > succeeded > exhausted > blocked- :用户取消或替换目标。
cancelled - :合约的
succeeded或all判定条件组合在最新的独立证据中成立。any - :在成功前达到有限限制。
exhausted - :满足停滞或重复失败规则,或所需权限、输入、工具或依赖仍不可用。
blocked
若在同一验证checkpoint中同时达到成功和限制条件,则标记为。将不可用、失败或过期的验证器视为,而非成功。
succeededunknown做出最终决策后立即停止。目标结束后,请勿添加可选清理或无关改进工作。
11. Preserve authority and evidence
11. 保留权限和证据
- Never expand the user's authorization because the work is iterative.
- Require approval for publishing, payment, deletion, production writes, permission elevation, and other irreversible effects.
- Preserve user-owned changes and declare file or object ownership before concurrent work.
- Never weaken tests, thresholds, or verifiers to make a predicate pass unless changing them is explicitly the goal.
- Never let the producer be the only verifier of its deliverable.
- Never describe or
blockedas success.exhausted - Never execute a verifier through a shell or substitute an undeclared command at runtime.
- Treat verifier commands as trusted code with inherited host authority. Use reviewed project-local checks; the runtime kernel is not a sandbox and cannot guarantee cleanup of deliberately detached descendants.
- Treat evidence logs as potentially sensitive local artifacts; do not print credentials from verifier commands.
End with a terminal report containing the terminal state and reason, host, iterations and budget used, roles used, every predicate and its latest evidence, changed artifacts, validation results, remaining DAG or blocker when unfinished, and state-file path.
- 切勿因工作是迭代式的而扩大用户的授权范围。
- 发布、支付、删除、生产环境写入、权限提升及其他不可逆操作均需获得批准。
- 保留用户所有的变更,并在并发工作前声明文件或对象所有权。
- 除非明确将修改测试、阈值或验证器作为目标,否则切勿弱化它们以让判定条件通过。
- 切勿让生产者成为其交付物的唯一验证者。
- 切勿将或
blocked描述为成功。exhausted - 切勿通过shell执行验证器,或在运行时替换未声明的命令。
- 将验证器命令视为具有继承宿主权限的可信代码。使用经过审核的项目本地检查;运行时内核并非沙箱,无法保证清理故意分离的子进程。
- 将证据日志视为潜在敏感的本地工件;请勿打印验证器命令中的凭据。
最终生成一份终端报告,包含终端状态及原因、宿主、已使用的迭代次数和预算、使用的角色、每个判定条件及其最新证据、已变更的工件、验证结果、未完成时剩余的DAG或阻塞点,以及状态文件路径。
12. Load examples only when needed
12. 仅在需要时加载示例
- Runtime contract: examples/runtime-contract.json
- Test-repair loop: examples/repair-failing-tests.md
- Performance loop: examples/improve-performance.md
- Cross-layer delivery loop: examples/deliver-cross-layer-feature.md
- 运行时合约:examples/runtime-contract.json
- 测试修复循环:examples/repair-failing-tests.md
- 性能优化循环:examples/improve-performance.md
- 跨层交付循环:examples/deliver-cross-layer-feature.md