Overview
Agent Loop Engine is a self-correcting development loop framework. It turns a fuzzy requirement into a structured, verifiable, iterative process: Project Detect (status detection) → Scaffold (scaffold generation, optional) → Grill-Me (requirements clarification) → Loop Manifest (contract) → Iterate (implement → review → verify) → Completion.
Core principle: Every iteration must be verified before it counts. No verification, no progress.
Violating the letter of this rule is violating the spirit of this rule.
When to Use
digraph when_to_use {
"Has a clear requirement?" [shape=diamond];
"Needs iterative refinement?" [shape=diamond];
"Has verifiable success criteria?" [shape=diamond];
"agent-loop-engine" [shape=box];
"Use regular development" [shape=box];
"Start with grill-me first" [shape=box];
"Has a clear requirement?" -> "Needs iterative refinement?" [label="yes"];
"Has a clear requirement?" -> "Use regular development" [label="yes - no loop needed"];
"Needs iterative refinement?" -> "Has verifiable success criteria?" [label="yes"];
"Has verifiable success criteria?" -> "agent-loop-engine" [label="yes"];
"Has verifiable success criteria?" -> "Start with grill-me first" [label="no - clarify first"];
}
Use when:
- Implementing a feature that needs iterative improvement against a measurable signal
- Bug fixing where the root cause is unclear and needs systematic investigation
- Refactoring with a regression test gate
- Any task where "done" means "verifiably done"
Don't use when:
- One-shot, throwaway code
- Configuration changes with no behavioral effect
- The task is already clear and can be done in one pass
Directory Structure
loop-engine/
├── SKILL.md # 主技能文件 (本文件)
├── CLAUDE.md # 循环章程
├── ARCHITECTURE.md # 架构心智模型
├── .claude-plugin/
│ └── plugin.json # Claude Code 插件清单
├── .codex-plugin/
│ └── plugin.json # Codex 插件清单
├── hooks/
│ ├── hooks.json # 钩子注册 (Claude Code)
│ ├── hooks-cursor.json # 钩子注册 (Cursor)
│ ├── run-hook.cmd # 跨平台钩子执行器
│ ├── session-start # 会话启动 → 注入技能上下文
│ ├── pre_completion_hook.py # 完成前门禁 → 强制回归测试
│ └── post_tool_edit_hook.py # 编辑后门禁 → 快速失败
├── roles/
│ ├── grill-me.md # 需求澄清子智能体
│ ├── implementer.md # 实现子智能体
│ └── reviewer.md # 审查子智能体
├── schemas/
│ └── loop-manifest.schema.json # Manifest 验证 schema
├── shturl # 全局时序共享日志（核心记忆，仅追加）
├── ship-change.js # 统一代码交付流水线（6阶段: Setup→Implement→Simplify→Review→Verify→PR）
├── domains/ # 多 Loop 业务域目录
│ └── {loop-name}/ # 单个业务循环独立目录
│ ├── LOOP_CONTRACT.md # 当前循环合约、目标、停止规则
│ ├── STATE.md # 循环独立运行状态快照
│ └── artifacts/ # signal/doc 任务与文档产物
└── skills/ # 子技能目录
├── pr/
│ └── SKILL.md # PR 验证技能
└── new-loop/
└── SKILL.md # 新建 Loop 脚手架技能
The Loop
digraph agent_loop_engine {
rankdir=TB;
node [shape=box, style=rounded];
start [label="START", shape=ellipse, style=filled, fillcolor="#d4edda"];
detect [label="Phase 0: Project Detect\n项目状态检测", style=filled, fillcolor="#e8daef"];
scaffold [label="Phase 0.5: Scaffold\n项目脚手架生成\n(仅首次/空项目)", style=filled, fillcolor="#d5f5e3"];
grill [label="Phase 1: Grill-Me\n需求澄清 → 验收标准", style=filled, fillcolor="#ffeeba"];
manifest [label="loop_manifest.md\n(验收标准契约)", shape=note, style=filled, fillcolor="#e2e3e5"];
loop [label="Phase 2: Loop Iteration\n(循环迭代)", style=filled, fillcolor="#cce5ff"];
subgraph cluster_iteration {
label="每次迭代";
task [label="1. 分派任务工单\n(task brief)"];
impl [label="2. Implementer 执行\n(TDD + 自测)"];
review [label="3. Reviewer 审查\n(Spec + Quality)"];
verdict [label="审查通过?", shape=diamond];
fix [label="4. 修复子智能体\n修复问题"];
}
verify [label="Phase 3: Pre-Completion Hook\n强制回归测试", style=filled, fillcolor="#f8d7da"];
test_pass [label="测试通过?", shape=diamond];
terminate [label="Phase 4: 检查终止条件\n(首次/增量模式)", style=filled, fillcolor="#d1ecf1"];
done [label="DONE", shape=ellipse, style=filled, fillcolor="#d4edda"];
post_edit [label="Post-Tool-Edit Hook\n(每次编辑后快速测试)", style=filled, fillcolor="#fff3cd", shape=note];
start -> detect;
detect -> scaffold [label="未初始化"];
detect -> grill [label="已初始化"];
scaffold -> grill;
grill -> manifest;
manifest -> loop;
loop -> task;
task -> impl;
impl -> post_edit [style=dashed, label="每次编辑触发"];
post_edit -> impl [style=dashed, label="失败则回退"];
impl -> review;
review -> verdict;
verdict -> fix [label="不通过"];
fix -> review;
verdict -> verify [label="通过"];
verify -> test_pass;
test_pass -> terminate [label="通过"];
test_pass -> fix [label="不通过"];
terminate -> done [label="满足条件"];
terminate -> loop [label="继续迭代"];
}
Core Loop Pseudocode
The full pseudocode has been moved to references/loop-pseudocode.md for readability. Read it when you need the detailed execution flow.
High-level summary:
function AgentLoopEngine(user_input):
// Phase 0: Project Detect (项目状态检测)
project_state = detect_project_state()
if not initialized: ProjectScaffold.generate()
// Phase 1: Grill-Me (需求澄清)
mode = detect_loop_mode(project_state) // first-run | incremental
manifest = GrillMe.clarify(user_input, mode) // → loop_manifest.md
// Phase 2: Loop Iteration (循环迭代)
while not should_terminate(iteration, no_progress, manifest, mode):
dispatch_subagent("implementer.md") // 实现
dispatch_subagent("reviewer.md") // 审查
run_pre_completion_hook() // 回归测试
classify_failure() → recoverable / unrecoverable / needs_human
evaluate_progress(manifest.feedback_signal)
// Phase 3: 完成
return generate_completion_report()
Grill-Me Interface Contract
Input
{
"user_input": "string — 用户的原始需求描述",
"context": {
"project_type": "code | content | service",
"existing_tests": "bool — 是否有现有测试套件",
"constraints": ["string — 已知约束列表"]
}
}
Output
Grill-Me produces loop_manifest.md, written in the following format:
# Loop Manifest: <loop-name>
## 需求描述
<用户原始需求简述>
## 验收标准
### P0 - 必须满足
- [ ] AC1: <可验证的描述> | 验证: <命令/观测>
### P1 - 应该满足
- [ ] AC2: <可验证的描述> | 验证: <命令/观测>
## 终止条件
- 最大迭代次数: <N>
- 最大无进展轮数: <M>
- 超时: <T>s
## 审批门
- 需要审批: <操作列表>
- 自动允许: <操作列表>
Return value
{
"status": "clarified | rejected",
"manifest_path": "loops/<loop-name>/loop_manifest.md",
"acceptance_criteria": [
{
"id": "AC1",
"priority": "P0",
"description": "用户登录后显示仪表盘",
"verification": "pytest tests/test_dashboard.py -x"
}
],
"termination": {
"max_iterations": 10,
"max_no_progress": 3,
"timeout_seconds": 300
}
}
Hook System
Hook Registration (hooks.json)
Hooks are registered to the Agent runtime via hooks.json . The system supports three hook events:
{
"hooks": {
"SessionStart": [
{
"matcher": "startup|clear|compact",
"hooks": [{
"type": "command",
"command": "run-hook.cmd session-start",
"async": false
}]
}
],
"PreCompletion": [
{
"matcher": ".*",
"hooks": [{
"type": "command",
"command": "python pre_completion_hook.py <loop_dir> [test_command]",
"async": false
}]
}
],
"PostToolEdit": [
{
"matcher": "edit_file|write_file",
"hooks": [{
"type": "command",
"command": "python post_tool_edit_hook.py <edited_file> [test_command]",
"async": true
}]
}
]
}
}
Hook 1: SessionStart — session start hook
| Property | Value |
|---|---|
| Trigger timing | When the Agent session starts, is cleared, or compacts |
| Execution mode | Synchronous (async: false) |
| Function | Inject skill context into the Agent system prompt |
| Timeout | 5s |
| Return value | JSON-formatted additionalContext or additional_context |
{
"additionalContext": "<EXTREMELY_IMPORTANT>\nYou have the Agent Loop Engine loaded.\n...\n</EXTREMELY_IMPORTANT>"
}
Hook 2: PreCompletion — mandatory regression test hook before completion
| Property | Value |
|---|---|
| Trigger timing | Before the Agent claims "completion", after all files have been generated |
| Execution mode | Synchronous (async: false) — blocks until the test completes |
| Function | Mandatory run regression tests to prevent unverified code from being marked as complete |
| Timeout | 120s (configurable) |
| Failure handling | Automatically roll back state, append a fix task to the iteration queue |
Return value convention:
{
"success": bool, # 测试是否通过
"output": str, # 测试标准输出/错误 (截断至 2000 字符)
"fix_task": str|None, # 失败时追加的修复任务描述
"duration_ms": int # 测试执行耗时（毫秒）
}
Execution flow:
Agent 宣称"完成"
│
▼
┌──────────────────────────────┐
│ PreCompletion Hook 触发 │
│ 1. 检测项目类型 (pytest/ │
│ npm test/cargo test) │
│ 2. 运行完整测试套件 │
└──────────────┬───────────────┘
│
┌───────┴───────┐
▼ ▼
┌────────┐ ┌──────────────┐
│ 通过 │ │ 不通过 │
└───┬────┘ └──────┬───────┘
│ │
▼ ▼
允许完成 追加修复任务
回退到迭代状态
Hook 3: PostToolEdit — fast-fail hook after editing
| Property | Value |
|---|---|
| Trigger timing | Every time the Agent performs edit_file/write_file on a core code file |
| Execution mode | Asynchronous (async: true) — runs in the background, does not block the Agent |
| Function | Automatically run fast unit tests to achieve fast fail (Fast Fail) |
| Timeout | 30s |
| Failure handling | Recommend rolling back the change and logging the issue |
Return value convention:
{
"success": bool, # 测试是否通过
"output": str, # 测试输出 (截断至 1000 字符)
"should_revert": bool, # 是否建议回退
"duration_ms": int # 测试执行耗时（毫秒）
}
Core file matching rules (CORE_FILE_PATTERNS):
CORE_FILE_PATTERNS = [
r"tools/.*\.py$", # 工具脚本
r"hooks/.*\.py$", # 钩子脚本
r"SKILL\.md$", # 技能文件
r"roles/.*\.md$", # 角色文件
r"schemas/.*\.json$", # Schema 文件
]
Execution flow:
Agent 执行 edit_file/write_file
│
▼
┌──────────────────────────────────┐
│ PostToolEdit Hook 触发 │
│ 1. 检查是否核心文件 │
│ 2. 推断相关测试文件 │
│ 3. 运行 pytest -x -q (30s 超时) │
└──────────────┬───────────────────┘
│
┌───────┴───────┐
▼ ▼
┌────────┐ ┌──────────────┐
│ 通过 │ │ 不通过 │
└───┬────┘ └──────┬───────┘
│ │
▼ ▼
继续工作 建议回退修改
记录失败日志
Orchestration — orchestration design
Sub-agent scheduling
Loop Orchestrator (主 Agent)
│
├── Grill-Me Subagent (需求澄清阶段)
│ ├── 输入: 用户原始需求
│ └── 输出: loop_manifest.md
│
├── Implementer Subagent (每次迭代)
│ ├── 输入: task brief + 上下文
│ ├── 工具: TDD, 文件编辑, 测试运行
│ └── 输出: task report + 代码变更
│
├── Reviewer Subagent (每次实现后)
│ ├── 输入: diff + task brief + task report
│ ├── 权限: 只读 (read-only)
│ └── 输出: review report (Spec + Quality)
│
└── Fix Subagent (审查不通过时)
├── 输入: review findings + 代码
└── 输出: 修复后的代码 + 验证
State transitions
┌──────────────────────────────────────────────────────────────────────────┐
│ Loop Orchestrator │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ IDLE │───▶│ CLARIFY │───▶│ ITERATE │───▶│ VERIFY │ │
│ │ (等待输入)│ │ (需求澄清) │ │ (迭代实现) │ │ (验证门禁) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ REVIEW │ │ COMPLETE │ │
│ │ (审查) │ │ (完成) │ │
│ └────┬─────┘ └──────────┘ │
│ │ │
│ ┌────────┴────────┐ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ FIX │ │ PAUSED │ │
│ │ (修复循环) │ │ (等待人工) │ │
│ └──────────┘ └────┬─────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ITERATE │ │ ITERATE │ │
│ │(重试) │ │(人工确认后)│ │
│ └──────────┘ └──────────┘ │
│ │
│ ┌─────────────┐ 不可恢复错误 │
│ │ TERMINATED │◄─────────────────────── │
│ │ (强制终止) │ │
│ └─────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
Failure routing (Residual Routing)
On each verification failure, determine routing via classify_failure() :
验证失败
│
▼
classify_failure(错误类型, manifest.residual_routing)
│
├── recoverable ──→ 修复 → 重试 (最多 max_recovery_attempts 次)
│
├── unrecoverable ──→ 写入 shturl → TERMINATED (强制终止)
│
└── needs_human ──→ 写入 shturl → PAUSED (等待人工确认)
│
▼
人工确认后 → ITERATE (继续)
Termination condition check
At the end of each iteration, check the following conditions:
- Acceptance criteria met — all P0 acceptance criteria have passed ✅
- Maximum iterations — reached
manifest.termination.max_iterations❌ - No-progress rounds — consecutive
manifest.termination.max_no_progress_roundsrounds with no improvement ❌ - Timeout — exceeded
manifest.termination.timeout_seconds❌
If any condition is met, the Loop terminates.
Verification Gates — gate system
Three-layer verification defense line
Refer to the ship-change design of the Loop Engineer Template:
┌──────────────────────────────────────────────────────────────┐
│ 三层校验防线 │
│ │
│ 第一层: Post-Tool-Edit Hook (快速失败) │
│ 触发: 每次编辑核心文件 │
│ 检查: 快速单元测试 (仅修改部分) │
│ 超时: 30s │
│ │
│ 第二层: Reviewer (代码审查) │
│ 触发: 每次迭代实现完成后 │
│ 检查: Spec Compliance + Code Quality │
│ 权限: 只读 │
│ │
│ 第三层: Pre-Completion Hook (回归测试) │
│ 触发: Agent 宣称完成前 │
│ 检查: 完整回归测试套件 │
│ 超时: 120s │
│ 失败: 回退状态 + 追加修复任务 │
└──────────────────────────────────────────────────────────────┘
Gate violation handling
| Violation type | Detection method | Handling method |
|---|---|---|
| Test fails after edit | PostToolEdit Hook | Recommend rollback, record failure |
| Review not passed | Reviewer | Dispatch fix sub-agent, re-review |
| Test fails before completion | PreCompletion Hook | Roll back state, append fix task |
| Claiming completion without verification | PreCompletion Hook (intercept) | Force run tests, block if not passed |
Red Flags — STOP
- Skip Grill-Me and go straight to implementation
- Start Loop without defined acceptance criteria
- Continue moving forward despite review not passing
- Claim "done" despite test failure
- Skip Pre-Completion Hook
- Ignore failure warnings from Post-Tool-Edit Hook
- Modify too many files in one iteration
- Continue iterating after exceeding termination condition
All of these mean: Stop and reassess.
Common Rationalizations
| Excuse | Reality |
|---|---|
| "The requirements are already clear" | Write it down, turn it into verifiable acceptance criteria |
| "Do it first, verify later" | Verification is proof, not an after-the-fact check |
| "Tests are too slow" | Slow because there are many tests, which means more tests are needed |
| "Review wastes time" | Review finds problems earlier than tests |
| "Just change one line of code" | One line of code can also cause a regression |
| "This iteration is the last one" | The termination condition has the final say, not you |
| "The user can't wait" | Unverified code is worse than waiting |
Integration
Reference documents:
ARCHITECTURE.md— System architecture overview, component relationships, and data flow. Read this first to understand the overall design.references/loop-pseudocode.md— Full pseudocode for the loop execution flow.
Required sub-skills:
- Roles: grill-me.md — Requirements clarification subagent
- Roles: implementer.md — Implementation subagent (TDD)
- Roles: reviewer.md — Code review subagent (Spec + Quality)
Sub-skills (in skills/):
- skills:pr — PR validation, called after all iterations are complete
- skills:new-loop — Loop scaffold generation, called when starting a new loop
Hooks (auto-registered):
hooks/pre_completion_hook.cjs— Pre-completion regression gatehooks/post_tool_edit_hook.cjs— Post-edit fast-fail gate
Status & Limitations
Non-goals (deliberate scope, not missing features):
- Not a fully-autonomous agent. This is a human-supervised loop framework. Critical decisions (approval gates, irreversible actions) require human confirmation.
- Not a model or runtime. Bring your own host (Claude Code, Codex CLI, Cursor, etc.). The skill defines the process; your host executes it.
- Not an MCP server. This skill orchestrates agent behavior via Markdown + subagents, not via the MCP protocol.
- Not a CI/CD pipeline.
ship-change.jsis a development workflow helper, not a replacement for GitHub Actions, Jenkins, etc. - Not domain-exhaustive. For a very custom workflow, fork a loop and adapt it — that's what the skill structure is for.
Limitations:
- Non-deterministic. Loop output depends on the underlying model. Treat every iteration's output as a draft to verify, not a final result to trust. Workaround: verification gates catch regressions before they propagate.
- No correctness guarantee. A loop can be confidently wrong across multiple iterations. Workaround: every iteration gates on a real signal (test results, metrics); keep a human in the loop for critical decisions.
- Host-dependent subagent isolation. Real, isolated subagent execution is verified only on Claude Code. On other hosts (Codex CLI, Cursor), multi-role loops run inline — functionally correct but serial. See Compatibility section.
- Cost & latency. Each iteration makes multiple model calls (Implementer + Reviewer). Start with a low iteration budget.
- Requires test framework. The verification gates depend on a working test suite. Without tests, the gates are no-ops.
Compatibility
Agent Loop Engine uses subagent dispatch for multi-role execution (Grill-Me, Implementer, Reviewer, Fix). Subagent isolation is host-dependent:
| Host | Skills | Subagent Dispatch | Notes |
|---|---|---|---|
| Claude Code | ✅ | ✅ Real, isolated, parallel | Verified — native subagent support |
| Claude Agent SDK | ✅ | ✅ | SDK-level agent spawning |
| Codex CLI | ✅ | ➖ Inline (serial) | Roles run inline, functionally correct |
| Cursor | ✅ | ➖ Inline (serial) | Composer agent, no subagent spawning |
| Hermes / Antigravity | ✅ | ➖ Inline (serial) | Reported working |
| Pi | ✅ | ➖ Inline (serial) | Skills load, subagents run as subtasks |
| OpenClaw | ✅ | ➖ Inline (serial) | Reported working |
Key takeaway: On Claude Code, all multi-role features run with full isolation. On other hosts, roles execute inline — the logic is the same, but they run serially and share context. The skill is fully functional everywhere; only the performance characteristics differ.
Off Claude Code, don't rely on parallel subagent isolation. Always verify results independently.
Verification Checklist
Before marking a loop complete:
- Grill-Me completed: acceptance criteria defined in
loop_manifest.md - All P0 criteria verified passing
- Pre-Completion Hook ran: regression tests pass
- Review completed: Spec Compliance ✅ + Code Quality ✅
- No open Critical/Important findings
- Termination conditions met (not exceeded)
- Post-Tool-Edit Hooks reported no failures
- Progress ledger complete and accurate
Final Rule
No loop iteration without verification.
No completion claim without passing the Pre-Completion gate.
This is non-negotiable.