Turn a vague large requirement into "a verified string of local commits". Humans intervene at only four points: the grill dialogue (adjudicating the design), the sign-off at the three exit gates (intent review / spec signing / plan confirmation), and manually executing one command when the runner ignition is blocked by permissions. Everything else is automatic.
The pipeline layering references Anthropic's "The AI-native SDLC playbook", but the gates are not prose reminders—they are the exit codes of devloop gate <stage> .
Evolution roadmap: see ROADMAP.md。Pipeline methodology and compilation prompts: see references/pipeline.md。
Control-plane kernel (call first)
The coordinating agent firstuses the executable CLI to check status/next step, then reads the long procedures. Unified entry point:
<path-to-skill>/scripts/devloop doctor
<path-to-skill>/scripts/devloop init --id <id> --title <标题>
<path-to-skill>/scripts/devloop gate intent --file .devloop/<id>/intent.md
<path-to-skill>/scripts/devloop gate spec --file .devloop/<id>/spec.md --intent .devloop/<id>/intent.md
<path-to-skill>/scripts/devloop gate plan --file .devloop/<id>/plan.md --spec .devloop/<id>/spec.md
<path-to-skill>/scripts/devloop gate goal --file .devloop/<id>/next-goal.md --spec .devloop/<id>/spec.md --plan .devloop/<id>/plan.md
<path-to-skill>/scripts/devloop next --dir .devloop/<id>
<path-to-skill>/scripts/devloop stage can --from intent --to spec
<path-to-skill>/scripts/devloop detect-host
<path-to-skill>/scripts/devloop detect-scheduler
<path-to-skill>/scripts/devloop attempt new
<path-to-skill>/scripts/devloop lock acquire --run-dir .devloop/<id>/run --phase impl
<path-to-skill>/scripts/devloop state can --from reviewing --to done
<path-to-skill>/scripts/devloop review-packet --devloop-dir .devloop/<id>
<path-to-skill>/scripts/devloop cleanup-sessions --orca-cli orca --worktree id:<repoId>::<path> --keep <live_handles>
Whenever you ask "what should I do now", run devloop next --dir .devloop/<id>, which will run the three gates in sequence and return stage= / action=; when a gate fails, it brings out each fail=。
Full contract:references/control-plane.md. Gate self-test:<path-to-skill>/scripts/devloop run-tests。
Hard execution contract
The order of this skill cannot be rearranged:
- grill → intent.md: first dig deep into the intent, conclusionwrite back while chattingliving document.
- Gate A:
gate intentall green + human review signs "pass". - intent.md → spec.md: compile into an actionable spec,eliminate process records。
- Gate B:
gate spec --intentall green + sign "pass". - spec.md → plan.md: compile into an overall solution execution plan (sliced roadmap + requirement traceability).
- Gate C:
gate plan --specall green + confirmation records complete. - loop small cycle:
host 解析 → 哨兵调度裁决 → goal 编译 → 门禁 D(gate goal)→ impl runner → 跨工具验收 reviewer, slice by slice serially. - Final summary: only after the acceptance reviewer reports that everything is complete can you proceed to the final summary report.
Prohibitions:
- No skipping levels。
devloop stage canwill rejectintent → plan. The only exception: if the user has already provided a mature SPEC/design document, you may start from stage 2 (still must go through gates B/C), and record the reason and document source in progress.md. - No bypassing human gates. The "reviewer / signer / confirmer" in the three gates are filled in byhumans, and the model must not sign on their behalf, nor fill in and pass on its own.
- No failing to recompile after upstream drift. If intent is changed, spec must be recompiled; if spec is changed, plan must be recompiled—
shabinding validation will block it, so don't change the binding values to fudge past it. - No inline implementation of slice code in the main session. The main session only does grill, compilation orchestration, host resolution, runner ignition, inspection, verification, and reporting; business code changes must be completed by the impl runner on the host(tmux session or Orca agent terminal). If host ignition fails, record it as
paused(待点火)and notify the user,do notautomatically degrade to inline implementation; if Orca detection fails, you may downgrade tohost=tmux, but still must not inline. - No igniting with a goal that has not passed gate D。
gate goalif the exit code is non-zero, fix the goal first;GOAL_SHA256is the common anchor for the impl report and reviewer acceptance, and changing the goal midway will cause the three-party hashes to mismatch. - Do not treat the runner's self-reported completion as completion. After impl exits, you must delegateacceptance reviewer(by default, an agent tool differentfrom impl) to perform adversarial checks; without the acceptance reviewer's "all complete" conclusion, you cannot set the next slice to open, nor proceed to the final summary.
- Do not let same-tool self-checks masquerade as adversarial acceptance by default. When
--reviewer=is not explicitly specified, you must select a tool different from--implaccording to the default pairing table below.Any same-tool acceptance must first obtain explicit user authorization, and record the confirmation in plan.md and write the authorization text/reason in progress.md; "only one tool left" only triggers a query, and does not automatically grant an exemption. - Do not let next-goal.md conflict with plan.md. A goal is merely an expansion of one line of the plan; it must not add requirements or change slice status; in case of conflict, plan.md prevails (see the boundary table at
references/pipeline.md)。
Optional dependencies (open-source installation)
This skill has zero required external dependencies: the interview algorithm for phase 1 is already inlined,templates/ has provided the complete on-disk structure. The following skills are purely enhancements; when missing, take the degraded path, which does not block startup,nodependency check is needed before startup.
| Phase | Recommended skill / tool | Purpose | Installation (example) | Degradation when missing |
|---|---|---|---|---|
| Phase 4 | qiaomu-goal-meta-skill(MIT) |
Polish the slice wording to be sharper | npx skills add joeseesun/qiaomu-goal-meta-skill |
Follow templates/next-goal.md 's seven-field sentence pattern; the effect is equivalent |
| host=orca | orca-cli skill + local orca CLI |
worktree / terminal fan-out impl·reviewer | The Orca app comes with a CLI; within the session ORCA skills get orca-cli |
degrade host=tmux + scripts/launch-runner-template.sh |
With grill-me / grilling installed, it can be used directly, equivalent to the inline algorithm. The interview algorithm for phase 1 (design tree / frontier / rounds) is adapted from mattpocock/skills 's grilling(MIT)。
Process overview
阶段 1 grill 意图识别 → .devloop/<id>/intent.md(活文档,边聊边回写)
── 门禁 A:devloop gate intent + 人工审阅签字 ──
阶段 2 编译设计规格 → .devloop/<id>/spec.md(消除过程性记录,R<n> 需求表)
── 门禁 B:devloop gate spec --intent + 签署 ──
阶段 3 编译执行计划 → .devloop/<id>/plan.md(切片 roadmap + 需求追溯 R→F)
── 门禁 C:devloop gate plan --spec + 确认记录 ──
阶段 4 loop 小周期 → 0 解析 host → 0.5 哨兵调度 → 1 goal 编译 → 2 impl runner → 3 跨工具 reviewer
收尾 最终汇总汇报 → 全部切片验收通过后,progress.md 收官条目,loop 结束
| host | Isolated execution area | impl | reviewer |
|---|---|---|---|
tmux(default) |
git worktree + launch-runner.sh |
tmux session running headless CLI | tmux/headless separate process |
orca(automatic in the Orca environment) |
orca worktree create |
Within the same worktree terminal create --command <agent> |
same worktree another agent terminal |
Core artifacts (all in .devloop/<id>/,<id> in the form 0042-add-rate-limit):
| File | Role |
|---|---|
intent.md |
Phase 1 living document: questions / expectations / impact scope / constraints / numbered decisions I-<n> / open questions / human review |
spec.md |
Phase 2 specification: target end state / R<n> requirements table / design / concerns and conflicts / sign-off (bound to intent_sha256) |
plan.md |
Phase 3 plan:loop single source of truth—requirement traceability R→F / confirmation records / slice roadmap / unified DoD (bound to spec_sha256) |
next-goal.md |
The current slice's self-contained goal (the only input for the impl runner; includes attempt and hash binding) |
progress.md |
Pipeline status + inspection log + host/worktree/handle records |
run/launch-runner.sh |
Only host=tmux: impl launcher (see scripts/launch-runner-template.sh) |
run/<impl>-<slice>.log |
impl log (tmux: stream-json; orca: terminal read summary is also acceptable) |
run/<impl>-<slice>-report.md |
Per-slice delivery report (written by impl) |
run/<impl>-<slice>-acceptance-prompt.md |
Acceptance prompt (written by the main session, the reviewer's only input) |
run/<reviewer>-<slice>-acceptance.log |
reviewer run log / summary |
run/<impl>-<slice>-acceptance.md |
Per-slice acceptance report (written by reviewer, all complete/incomplete/BLOCKED + impl/reviewer header) |
Phase 1: grill intent identification → intent.md
Write to disk first, then start talking:
<path-to-skill>/scripts/devloop init --id <id> --title <标题>
# → .devloop/<id>/{intent.md, progress.md, run/}
Thenrelentlessly interview the user until both sides reach the same understanding of "what to do". The interview algorithm and the living-document discipline are one thing, not two:
-
Build the design tree, compute the frontier: model what needs clarification as a decision tree—the answer to one decision unlocks or rewrites the decisions downstream of it;frontier = all decisions whose prerequisites are settled and that can be asked right now.
-
Ask the entire frontier in one round: number each question, andgive your recommended answer. This format is the interaction contract shown to the user; keep it as-is:
❓ **Q1** - **<问题标题>**:<问题正文> ➡️ <你推荐的答案> -
Verifying facts is your job, never the user's job: what the existing implementation looks like, whether some interface is depended on elsewhere, what the repo's existing conventions are—dispatch subagents to grep / read code, and leave only the trade-offs that truly need a human decision to the user.
-
Write back to intent.md on the spot after the user answers, don't save it up to record at the end: append settled rulings to the
## 裁决记录numbered list (I-1/I-2…, the spec requirements table's "source" column will reference these numbers); problem statements / expected results / scope of impact / constraints overturned by answersrewrite in place, don't pile up a "revision note" at the end of the document—leave the process trail to git and progress.md; what still can't be answered this round goes into## 未决问题's- [ ]。 -
Recompute the frontier and start the next round; when the frontier is empty, the interview is over—this is the same thing as the gate's
I-openq(## 未决问题no unchecked- [ ])said two ways, the gate is the machine criterion for "whether the interview has truly converged". After convergence,## 未决问题write as a single line- 无。
Coverage: allarchitecture boundaries, write scope, acceptance criteria, credentials/manual input, execution depthquestions that affect these must have a ruling.
If the repo root has CONTEXT.md, follow its terminology during the interview, point out conflicts on the spot and write back to ## 裁决记录. If this task itself is changing the domain model and domain-modeling skill is installed, you may separately invoke it to maintain the glossary and ADRs—its artifacts are at the repo root (CONTEXT.md / docs/adr/), do not overwrite devloop's .devloop/<id>/ , and they don't enter the devloop gate.
Gate A: intent exit
<path-to-skill>/scripts/devloop gate intent --file .devloop/<id>/intent.md
On failure, backfill item by item per fail= ,do notfor the checklist. references/pipeline.md。
## 人工审阅 isa human gate: the reviewer must have actually read the full intent text, the model may not sign on their behalf. When the conclusion is "send back", return to grill and do not proceed. When the gate passes, stdout's sha256= is the value to be written into intent_sha256: in the next phase.
Stage 2: intent.md → spec.md (compilation)
Dispatch a compilation subagent; for the prompt see references/pipeline.md "Stage 2" (a design prompt adapted from the playbook, retaining the two key points "load organizational standards + explicitly expose policy conflicts"). Key points:
- Structure follows
templates/spec.md(devloop init --id <id> --stage speccan land the skeleton). - Eliminate process records: no adjudication history, open questions, Q&A rounds, or grill conversation traces may appear. Intent adjudications appear only as
I-<n>in the "Source" column of the requirements table. - One stable ID per requirement
R<n>,Acceptance criteria must be executable(runnable commands / greppable assertions / observable metrics). ## 关注点与冲突It is better to write "none" than to hide a real policy conflict—this is the most valuable output of this stage for downstream.- Header writes
intent_sha256: <门禁 A 输出的 sha256>。 - The subagent only writes spec.md; it does not modify business code and does not commit.
Gate B: spec exit
<path-to-skill>/scripts/devloop gate spec --file .devloop/<id>/spec.md --intent .devloop/<id>/intent.md
S-procedural* The check is the machine criterion for "eliminate process records";S-bind it blocks silent drift where intent was changed but spec was not recompiled.## 签署记录 Signed off by a human.
Stage 3: spec.md → plan.md (compilation)
Dispatch a compilation subagent; for the prompt see references/pipeline.md "Stage 3". Key points:
- Structure follows
templates/plan.md. Header writesspec_sha256: <门禁 B 输出的 sha256>。 - Requirements traceability tablegives the
R<n> → F<n>mapping; every R must be covered by at least one slice. - Slice granularity: one slice ≈ the amount that can be completed in one unattended session (15–60 minutes of runner time, a dozen or two file changes). Too large will hit context/rate limits; too small wastes ignition overhead.
- Between slicesdependencies are one-way(later slices depend only on earlier slices' commits); cycles are forbidden.
- Slices involving external credentials/manual input go last and are marked
paused(原因); when reached, notify the user instead of forcing a run. - Status words are fixed:
open(at most one)/done (commit, 门禁数字)/pending/paused(原因)。 - Write clearly the "uniform DoD per slice": gate commands + all-green criteria, commit message prefix, report path, BLOCKED stop conditions.
Gate C: plan exit + user confirmation
<path-to-skill>/scripts/devloop gate plan --file .devloop/<id>/plan.md --spec .devloop/<id>/spec.md
After all gates are greenyou must ask the user to confirm whether to enter the loop, and write the conclusion into ## 确认记录: confirmer / confirmation time / confirmation scope / allowed --impl and --reviewer(may write "use default pairing") / --host(may write "auto-detect") / permission authorization / source_worktree / base_sha / plan_sha256 / control-plane policy / conclusion on entering the loop.
Silence, default assumptions, and the model's own judgment do not count as confirmation. Without a confirmation record, no runner may be created.
.devloop lifecycle and execution-area handoff
grill may first write .devloop/<id>/in the current checkout, but before entering the execution worktree the following handoff must be completed; do not assume uncommitted files will appear automatically:
- Record in the confirmed plan
source_worktree, the execution area's lockedbase_shaand the original file'splan_sha256。 - After creating the target worktree, the coordinator uses
cp -a <source>/.devloop/<id> <target>/.devloop/or an equivalentrsyncto migrate it in; recompute and verifyplan_sha256; if inconsistent, pause. - If the implementation depends on dirty, uncommitted business changes in the source checkout, pause and let the user explicitly choose: commit first, generate a patch and import it explicitly, or switch to the current checkout. Silently discarding, speculative copying, or starting from the wrong base is prohibited.
.devloop/is the control-plane; by default it is recommended to commit it together with the feature branch so that intent/spec/plan/report/acceptance are auditable. If the plan chooses not to commit, then the allowed control-plane dirty paths for each slice must be listed, and impl staging must use only a path allowlist, to avoid unboundedgit add -A。- At wrap-up, first confirm that
.devloop/has been committed with the branch or separately archived with the location recorded; only after obtaining the user's confirmation of archiving and cleanup isworktree rm。
Phase 4: loop micro-cycle
Before entering Phase 4, first run devloop gate plan and check the confirmation record; if missing, return to Phase 3 and do not create a runner.
0. Resolve the execution host (mandatory when entering the loop)
The sole authoritative entry point: run the script inside the skill, consume its stdout, and do not hand-write detection logic.
<path-to-skill>/scripts/devloop detect-host # 自动(推荐)
<path-to-skill>/scripts/devloop detect-host --force orca # 用户指定 --host=orca|tmux 时
<path-to-skill>/scripts/devloop detect-host --prefer orca # 仅偏好,不可用时允许降级
<path-to-skill>/scripts/devloop detect-host --json # 机器可读
Script output key=value(or --json), at minimum read these fields:
| Field | Meaning |
|---|---|
host |
orca or tmux — adopt directly, do not reason further |
reason |
Decision explanation, write to progress.md |
orca_cli |
Executable name/path used by subsequent Orca commands (mandatory when host=orca) |
orca_status |
ok / fail / missing / skip |
tmux_available |
0/1 |
orca_worktree_id |
The current worktree injected by the environment (may be empty) |
Priority (already built into the script; the agent only needs to pass parameters):
- User
--host=/ environment variableDEVLOOP_HOST/ script--force: strict selection; if unavailable, exit non-zero, do not downgrade. - Script
--prefer: prefer the target host; if unavailable, downgrading is allowed and recorded inreason. - Automatic: Orca signal + CLI
statushealthy →orca, otherwise preference-based downgradetmux。--force tmuxmust not detect or call Orca at all.
| Exit code | Meaning |
|---|---|
| 0 | The selected host can run |
| 1 | Cannot run (e.g. force orca but the CLI is down, or tmux is not in PATH) → record in progress paused/downgrade explanation,must not inline the implementation |
| 2 | Parameter error |
Write host、orca_cli(if any),reason, and impl/reviewer verbatim into the plan confirmation record and the progress startup line.
host=orca For the worktree/terminal fan-out steps when references/orca-host.md(only after the host has been determined to be orcaread it again, to avoid needlessly burning tokens).
0.5 Resolve sentinel scheduling (mandatory when entering the loop)
After the host is determined and before creating the sentinel,mustrun scheduling detection. The coordinator (main session harness) and impl/reviewer are not the same thing: in Orca it is very common to use omp as the coordinator, and omp does not have /loop。
<path-to-skill>/scripts/devloop detect-scheduler
<path-to-skill>/scripts/devloop detect-scheduler --json
| Field | Meaning |
|---|---|
coordinator |
claude-code / codex / grok / omp / pi / unknown |
loop_supported |
1 only then can /loopbe used; only claude-code / codex / grok |
orca_env |
1 = currently in Orca |
scheduler |
loop / orca-automation / cron / ask — adopt directly, do not reason further |
reason |
write to progress.md |
| Exit code | Meaning |
|---|---|
| 0 | Scheduling has been decided (loop / orca-automation / cron) |
| 1 | scheduler=ask: must stop and ask the user |
| 2 | parameter error |
Press scheduler= to execute (changing the verdict yourself is forbidden):
loop: the current coordinator supports/loop, directly create one every 10 minutes/loop(avoid on-the-hour minutes).orca-automation: the coordinator does not have/loop, but the person is in Orca.automaticuse Orca automations as the sentinel, andinform the user: the current coordinator is<coordinator>, does not support/loop, has switched to Orca automation, no need to change agent. Do not ask again "cron or change person", and do not create another crontab.ORCA automations create --name devloop-<id>-sentinel --trigger "<避开整点的 10 分钟 cron>" --workspace active --reuse-session --prompt "<tick prompt>" --json--reuse-sessionsend back to the current coordinator session;--providertakeORCA automations create --helpas authoritative, do not open a second coordinator.- write the automation id into the progress / plan confirmation record.
ask: does not support/loop, and is not in Orca either. Tell the user the current coordinator does not support/loop, please choose: local cronjob / launchd, or switch to claude-code / codex / grok and re-enter the loop. Before choosing, record in progresspaused(待选哨兵调度), do not create cron, do not fire.- Only after the user has chosen in writing, use
--force loop|cron|orca-automation。--force loopatloop_supported=0will stillask。
isolated execution area
- host=tmux:
git worktree add, branchfeat/devloop-<id>-<slug>。 - host=orca:
ORCA worktree create --name devloop-<id>-<slug> ...(prefer--parent-worktree active),one devloop one Orca worktree; impl and reviewer share this checkout(do not open another parallel worktree for the reviewer, which would make the impl commit invisible). plan must recordsetup=run|skip|inherit。
After completing the lifecycle handoff, immediately run in the execution worktree git config remote.origin.pushurl no_push(or an equivalent invalid push URL) to hard-disable push, and verify the configuration takes effect..devloop/<id>/ Place inside the worktree and follow the branch according to the plan's control-plane policy;never push。
For detailed Orca commands and fan-out steps see references/orca-host.md; before operating, should ORCA skills get orca-cli verify the current CLI syntax.
Sentinel (scheduled patrol)
Only at detect-scheduler after giving scheduler=loop|orca-automation|cron create the sentinel. Interval 10 minutes, choose a minute that avoids the hour. Most timers are session-level: when the coordinator exits, the loop stops. Each tick first use devloop lock acquire --run-dir .devloop/<id>/run --phase <compile|impl|review|advance> to grab the phase lock; if not grabbed, exit, the lock owner releases it at the end, to avoid duplicate fan-out of reviewer / duplicate advancement.
The scheduled task's prompt requires each time:
- One command summary:
- tmux: session liveness, log line count,
tail -c 2000、git log --oneline -3、devloop next --dir .devloop/<id> - orca:
terminal list/terminal read, whether the report file appears,git log --oneline -3(in the execution worktree path),devloop next --dir .devloop/<id>; and immediately do the session cleanup in step 6 below
- tmux: session liveness, log line count,
- Stall determination: runner/agent still present but logs or files show no progress → record "suspected stall ×N", 2 consecutive timesproactively notify the user。
- to
progress.mdpatrol tableappend a line(time/slice/host/scheduler/runner status/commit count/key points). - impl complete (the current attempt's reports are complete and the slice is still open) → enter small cycle 3 cross-tool reviewer.
- After the loop wraps up, delete this scheduled task.
- When host=orca, each tick must clean up completed sessions(See below). Orca subtasks leave behind independent terminal/session instances; if they are not closed, they will keep occupying memory.
The completion sentinel must not merely check that a fixed-path file exists. The current artifact must satisfy:attempt_id is consistent with this round;goal_sha256 is consistent with the current goal; the mtime of the report/acceptance is later than this round's goal and archive action; the report's base_sha、head_sha is verifiable. Before re-opening a slice, the previous round's report/acceptance must be moved into run/archive/<attempt_id>/(devloop attempt archive), or switch to a new artifact path containing the attempt.
host=orca: clean up completed sessions
On every tick, and after the artifacts of impl / reviewer / compiler have been consumed by this round, run:
<path-to-skill>/scripts/devloop cleanup-sessions \
--orca-cli <detect-host 给出的 orca_cli> \
--worktree id:<repoId>::<path> \
--keep <coordinator_handle>,<current_impl_handle>,<current_review_handle> \
--title-prefix devloop-<id>- \
--also-close <progress 里已结束的旧 handle>
Rules:
--keepkeep only the coordinator itself, the currently still-live impl, and the currently still-live reviewer.- The script will close:
worktree psinstate=donethe agent terminal, leftover tabs whose title containsdevloop-<id>-, and--also-close。 - Forbidden
terminal stop --worktree(it will stop the entire worktree). - Forbidden without user confirmation
worktree rm。 - After closing, write
closed=to progress; if the handle is invalid, just record it once and do not retry a double close.
Small cycle 1: goal compilation
Each time a slice is ignited, generate a non-reusable attempt_id(devloop attempt new), then delegate the goal compilation sub-agent:
- Input: the original text of the
R<n>covered by this slice in spec.md + that slice's line in plan.md and the unified DoD + relevant rulingsI-<n>+ the previous slice's report + current code anchors. - Structural contract: the output must conform to
templates/next-goal.md(self-contained next-goal.md). - Tool goal instruction section: fill in according to
templates/next-goal.md's seven-field sentence pattern - goal / verification / constraints / boundaries / iteration strategy / completion conditions / pause conditions. The sentence pattern is already inlined,does not depend on an external skill; ifqiaomu-goal-meta-skillis installed, you can use it to polish the wording and then write it into that section as-is.The remaining sections are always completed according to the template。 - Responsibility boundary: the goal is an expansion of one line of the plan - it may only reference
R<n>, and must not add new requirements; it may only read slice state, and must not write or advance it; the unified DoD is copied as-is and may only be appended to, not deleted from. In case of conflict, plan.md prevails. If you find that "this slice's scope as written in the plan cannot be done", writeBLOCKEDin the goal and return to stage 3 to fix the plan,must notchange the scope on your own. - ⚠️ The write path must explicitly write the absolute path to the worktree's
.devloop/<id>/next-goal.md. Hard-learned lesson: an agent once wrote to the main repository, causing the runner to read an old goal and exit in confusion. In the prompt, write out the target path verbatim and require the agent to self-check after writing. - The goal compilation agent only writes next-goal.md, and does not modify business code, commit, or ignite.
- At the top of next-goal.md, record
attempt_id、spec_sha256、plan_sha256、goal_sha256、base_sha, at compile timehead_sha; the impl report and acceptance must write back the same set of binding fields as well as their respective generation-timehead_sha。
See references/goal-template.mdfor details. The completion criterion isgate D exit code is 0, not the sub-agent self-reporting completion:
<path-to-skill>/scripts/devloop gate goal --file <worktree>/.devloop/<id>/next-goal.md \
--spec .devloop/<id>/spec.md --plan .devloop/<id>/plan.md
It validates the eight required subsections, the completeness of the seven fields, the non-emptiness of the nine header fields,GOAL_SHA256 self-validation, and that there is no drift in spec/plan. However, the gate must not ignite.
Small cycle 2: impl runner implementation
The runner's only task input is .devloop/<id>/next-goal.md(tool goal instruction + phase prompt); it must be consumed as-is and must not depend on the main session context.
host=tmux
On first entry into small cycle 2, copy from scripts/launch-runner-template.sh to .devloop/<id>/run/launch-runner.sh, and modify the five configuration points according to the template comments (including DEVLOOP_ID, worktree absolute path, impl name, agent, impl command line):
- Absolute path: a new tmux session does not inherit the shell; write PATH/cwd explicitly.
- Do not use interactive aliases: an agent alias containing
readwill hang an unattended session. - stream-json log tee to disk: the sentinel relies on line count and tail to judge progress.
- Permission flags must be changed: by default use the tool's minimum permissions (for Codex,
--sandbox workspace-write); thebypassPermissions/ danger examples in the template can only be enabled when the plan has recorded explicit user authorization.
Ignition:
tmux new-session -d -s devloop-<id>-<slice> 'sh <worktree>/.devloop/<id>/run/launch-runner.sh <slice>'
# 或先 chmod +x,再直接执行 launcher
When blocked by permissions, record "pending ignition" in progress, and give the user the complete command executable with ! ; it can be retried on the next tick.
One tmux session per slice (devloop-<id>-<slice>). Only one impl runs at a time.
host=orca (fan out impl agent)
For details see references/orca-host.md. Summary:
- Ensure the Orca worktree already exists, record
worktree.id=<repoId>::<path>。 - fan out in that worktree impl terminal (agent mapping:
claude-code→claude,codex→codex,grok→grok):
ORCA terminal create --worktree id:<repoId>::<path> --title devloop-<id>-<slice>-impl-<attempt> --command <impl_command_with_plan_authorized_permissions> --json
ORCA terminal wait --terminal <impl_handle> --for tui-idle --timeout-ms 60000 --json
ORCA terminal send --terminal <impl_handle> --text "Read and execute <ABS>/.devloop/<id>/next-goal.md; write report to <ABS>/.devloop/<id>/run/<impl>-<slice>-report.md; local commit only; never push; do not edit plan.md status." --enter --json
- Completion determination follows the attempt sentinel protocol: do not just check whether a fixed path exists; verify the report's
attempt_id/goal_sha256/base_sha/head_sha, mtime, and commit; do not rely only on the agent's verbal account. - progress record
impl_handle; for the create response, preferagentTerminalHandle, compatible withstartupTerminal.handle. When the handle is invalid, useterminal listto re-fetch by worktree + full title + command; double-sending is prohibited. - Optional:
worktree set --workspace-status in-progress/--comment "…"。
impl and reviewer options
The user can use --impl= / --reviewer= / --host=. When unspecified:
- host: use the
devloop detect-hostoutput as authoritative (do not infer manually) - impl default:
claude-code - reviewer default: an agent different from impl (see the pairing table)
| Tool | Orca agent id | host=tmux startup core (impl reads next-goal; reviewer reads acceptance-prompt) |
|---|---|---|
claude-code |
claude |
claude -p --permission-mode default --verbose --output-format stream-json < <input>; can only be changed after the plan records authorization bypassPermissions |
codex |
codex |
codex exec --sandbox workspace-write - < <input>;--full-auto is a deprecated alias, with risks of permission expansion and future removal |
grok |
grok |
grok --prompt-file <input> --output-format streaming-json; danger/bypass mode can only be added after the plan records authorization |
The goal / acceptance prompt content is independent of the host—the artifact is self-contained.
Default reviewer pairing (forcibly applied when--reviewer is unspecified)
| impl | Default reviewer (by priority, take the first one on this machine that isinstalled and executable) |
|---|---|
claude-code |
codex → grok |
codex |
claude-code → grok |
grok |
claude-code → codex |
Parsing rules:
- User explicitly
--reviewer=X: use X; ifX == impl,warnand ask the user for explicit authorization; without authorization, do not start acceptance with the same tool. - User unspecified: select a tool different from impl according to the table above.
- None of the candidates is available or only one tool remains: inform the user and ask whether to authorize the same tool;must notsilently accept with the same tool.
- Write the final
host/impl/reviewerinto the plan confirmation record and progress.
Small cycle 3: cross-tool adversarial acceptance (reviewer)
After impl completes, must start reviewer(default ≠ impl). The main sessionmust notdeclare "all complete" based solely on its own read-through of the diff in place of the reviewer.
Before starting
- Parse
impl/reviewer/host。 - verify that impl has exited/is idle, freeze its terminal; record the current HEAD. The main session writes a self-contained acceptance prompt to the worktree absolute path:
.devloop/<id>/run/<impl>-<slice>-acceptance-prompt.md(including the original slice text, the coveredR<n>acceptance criteria, paths, git range, gates, acceptance report output path,attempt_id/goal_sha256/base_sha/ pending verificationhead_sha, adversarial checklist, and one of three conclusions). - Start the reviewer according to host:
host=tmux — headless / tmux session, log tee to run/<reviewer>-<slice>-acceptance.log:
| reviewer | command skeleton |
|---|---|
claude-code |
claude -p --permission-mode default --verbose --output-format stream-json < "$PROMPT"; bypass only with recorded authorization |
codex |
codex exec --sandbox workspace-write - < "$PROMPT"(only the acceptance path is allowed) |
grok |
grok --prompt-file "$PROMPT" --output-format streaming-json; danger/bypass only with recorded authorization |
host=orca — same worktree then fan out the reviewer terminal (use the mapping table for agent id):
ORCA terminal create --worktree id:<repoId>::<path> --title devloop-<id>-<slice>-review-<attempt> --command <reviewer_command_with_plan_authorized_permissions> --json
ORCA terminal wait --terminal <review_handle> --for tui-idle --timeout-ms 60000 --json
ORCA terminal send --terminal <review_handle> --text "Execute acceptance prompt at <ABS>/...-acceptance-prompt.md; write ONLY <ABS>/...-acceptance.md (impl=/reviewer= header; 全部完成|未完成|BLOCKED). No code changes, no commit, no plan.md status edits." --enter --json
Completion determination: acceptance must be published via atomic rename, and attempt/hash/mtime/conclusion must all be valid; the current HEAD must equal the acceptance's reviewed head_sha. Optional workspace-status in-review。
Adversarial checklist (write into the prompt; the reviewer must provide evidence for each item)
- Whether the acceptance checklist in next-goal.md is satisfied item by item.
- Whether the acceptance criteria of the spec requirement
R<n>covered by this slice are satisfied reproducibly, clause by clause. - Whether the runner report exists, whether it includes gate numbers, change list, deviation notes, and whether there are no unhandled BLOCKED items.
- Whether the commit was actually produced, and whether the commit scope covers only this slice.
- Whether the relevant gates actually ran and there is no regression; gate numbers must be traceable from logs or reports.
- Whether the roadmap status was not advanced arbitrarily by the runner.
- (Adversarial escalation) Actively look for: missed boundaries, paths not covered by tests, conflicts with spec decisions, fake gates (report numbers inconsistent with logs).
Acceptance output
The reviewer writes .devloop/<id>/run/<impl>-<slice>-acceptance.md(note at the file header impl= / reviewer= / attempt_id= / goal_sha256= / base_sha= / reviewed head_sha=), and the conclusion can only be:
全部完成: the main session sets this slice todone (commit, 数字); if there are still pending slices, set the next slice toopenand return to small cycle 1.未完成: point out the gaps; when auto-fix is possible, keep this slice atopen, and re-enter small cycle 1 to compile a fix goal.BLOCKED: clearly state the human decisions/credentials/external conditions needed, set this slice topaused(原因)and notify the user.
The reviewer only writes the acceptance report and (optionally) reruns gates read-only;does not modify business code, does not commit, does not advance the roadmap. Compare the worktree diff before and after review; if any reviewer-added diff appears outside the allowed acceptance paths, it is always judged BLOCKED. Reports/acceptance should first write a temporary file in the same directory, then after it is fully flushed to disk, atomic rename it to the sentinel path, to avoid tick reading a half-written file. State advancement is still executed by the main session based on the acceptance conclusion; before advancing, use devloop state can --from reviewing --to done to validate, and verify again that the current HEAD equals reviewed head_sha。
wrap-up
After the last piece is done:
- Confirm every piece has an impl runner report and a reviewer acceptance report, and the conclusion of the last acceptance report is
全部完成; the acceptance report header should stateimpl/reviewer/ attempt/hash/SHA binding (and host if applicable). - Requirements closure check: every
R<n>in spec.md can find a covering slice in the plan's requirements traceability table, and that slice has beendone. If any R is unaccounted for, it is not wrapped up. - Adversarial full verification (still prefer a different reviewer from impl, or the main session performs a second check on the reviewer report): all slices committed, final gate numbers, reports complete, acceptance reports complete.
- In
progress.mdwrite the closing entry (pipeline status table completed + summary table of each slice's commit/test count/host/impl/reviewer/cost). - If the project has a global progress document (such as
docs/STATUS.md, changelog, kb progress), add onebriefclosing record — per-tick logs stay in.devloop/<id>/progress.md, do not pollute the global document. - Delete the sentinel scheduled task; when host=orca, first run
cleanup-sessions(--keepagain, keeping only the coordinator), thenworktree set --workspace-status completedand update the comment. - Commit or archive
.devloop/according to the plan's control-plane policy, record the archive location; notify the user that the loop has ended + the manual acceptance checklist (if any).Without confirming the archive and without the user's explicit consent, do notworktree rm。
Common failure reference table
| Symptom | Cause | Handling |
|---|---|---|
gate intent is stuck at I-openq |
grill has not converged, and there are still unchecked unresolved questions | Go back to grill and adjudicate item by item; for those genuinely not to be done, write the downgrade into "non-goals" |
gate spec reports S-procedural |
the spec still contains adjudication history/Q&A form | Recompile the spec; keep procedural content only in intent.md |
gate spec / gate plan reports *-bind drift |
Upstream was changed but downstream was not recompiled | Recompile downstream, do not hand-edit the binding values to paper over it |
gate plan reports P-trace |
the requirements traceability table is missing the R→F mapping | Add the mapping; if an R has nowhere to go, the slices were split wrong, go back to stage 3 |
gate plan reports P-open |
the number of open slices is not exactly 1 | Fix the roadmap status column |
| The gate passed but the model signed off itself | Violates the human gate | Void that sign-off, send it back for human review; record it in progress |
| runner exited, no report, uncommitted changes present | API rate limit / session timeout | Restart impl (tmux or orca terminal), resume and pick up the changes |
| runner exits immediately, logs show confusion | next-goal.md is stale slice content | goal wrote the wrong path — check whether it wrote into the main repo; fix and restart |
| Auto-ignition was blocked by permissions | Security classification temporarily unavailable | Mark as "pending ignition", give the user ! command; retry on the next tick |
| Log/terminal shows no progress for two consecutive ticks | runner is stuck | tmux: kill the corresponding session; orca: first verify handle/title, then terminal close --terminal <handle> and create to fan out again;ProhibitedDefault to terminal stop --worktree; if multiple times, split into slices |
| Report contains BLOCKED | Semantic ambiguity / gate not passed / missing credentials | Read the report to locate: for matters you can decide yourself, compile and fix the goal; for matters requiring human input, set paused and notify |
| A requirement appears in the goal that is not in the plan | Goal compilation out of bounds | Void that goal and recompile; if the out-of-bounds content is truly necessary, go back to stage 2/3 through the gate |
| Interview diverges and cannot be wrapped up | frontier was not built correctly; issues were not layered by dependency | Go back and fill in the design tree; adjudicate each open issue one by one, or downgrade it into "non-goals" |
| Acceptance was directly approved by the main session | Cross-tool reviewer was not started | Write the acceptance-prompt and start the reviewer according to host; for the same tool, written user confirmation is required |
| reviewer CLI / agent does not exist | None of the pairing candidates are installed | Inform about the missing item; do not silently use the same tool |
| Orca was detected but worktree/terminal failed | CLI is old / app is not ready | ORCA open + skills get orca-cli; rerun detect-host, if it fails then tmux |
| reviewer cannot see the impl commit | A second worktree was mistakenly opened | Force the same worktree.id; discard the parallel tree and rerun acceptance |
terminal_handle_stale |
Orca restarted or handle expired | terminal list to get a new handle, and only send to the new handle |
| agent guesses the host itself and it does not match the script | detect script was not run | Use the script stdout as authoritative; rerun and overwrite plan/progress |
The coordinator is omp and not in Orca, yet tries to create cron / pretends /loop |
Did not run detect-scheduler or treats ask as cron |
Stop and ask the user: switch to claude-code / codex / grok, or explicitly authorize cronjob; do not ignite without a choice |
Coordinator has no /loop and is in Orca, yet asks the user or creates crontab |
Should automatically use Orca automation | Follow the script scheduler=orca-automation to create automation and inform the user, do not ask again |
| Orca memory keeps growing, terminals accumulate more and more | Completed impl/review sessions were not closed | Run devloop cleanup-sessionsevery tick; only keep the current live handle |
Reference
references/pipeline.md— Four-stage pipeline methodology + four gate checklists + compilation prompts(required reading for stages 1–3)references/control-plane.md—devloopCLI contract and two state machinesreferences/goal-template.md— dispatch manual for the goal compilation sub-agentreferences/orca-host.md— when host=orca, the orca-cli worktree / impl·reviewer fan-out manual (read only after host is determined to be orca)templates/intent.md·templates/spec.md·templates/plan.md·templates/next-goal.md·templates/progress.md— on-disk structure for each stage (devloop inituse)scripts/gate.sh— the sole entry point for the four pre-exit gates(intent / spec / plan / goal)scripts/detect-runtime-host.sh— the sole entry point for host detection(must run when entering the loop)scripts/detect-loop-scheduler.sh— the sole entry point for sentinel scheduling detection(/loop→ Orca automation → ask again)scripts/cleanup-orca-sessions.sh— clean up completed terminal/session when host=orcascripts/launch-runner-template.sh— impl runner launcher template when host=tmux