raphael-liu/raphael-loop
Bounded, verifiable Loop Engineering for Codex, Claude Code, and DeepSeek Harness.
catalog 简介 / catalog descriptioncatalog description：Loop Engineering
安装Install
dsh plugin --profile web add @raphael-liu/raphael-loop把 raphael-liu/raphael-loop 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
RaphaelLoop
Bounded, verifiable Loop Engineering for Codex, Claude Code, and DeepSeek Harness.
简体中文 · Architecture · Examples · Contributing · Security
RaphaelLoop turns “keep working until it is done” into a governed engineering loop: a stable goal contract, a dependency-aware task graph, explicit ownership, independent verification, recoverable checkpoints, and deterministic stop conditions.
It is an Agent Skill, not another model runtime. Codex, Claude Code, or DeepSeek Harness still performs the work with its native tools; RaphaelLoop supplies the operating protocol that keeps long-running work aligned and reviewable.
Why RaphaelLoop
AI coding is increasingly capable of executing for many turns, but more turns do not automatically produce better engineering. The difficult failures happen between turns:
- The original objective is compressed into a vague todo and gradually drifts.
- Multiple Agents edit overlapping files or repeat the same investigation.
- A producer declares success using its own incomplete evidence.
- A failing action is retried until time, tokens, or budget are exhausted.
- Human approval gates disappear inside an “autonomous” workflow.
- A restarted session cannot distinguish verified work from an Agent's claim.
A reliable loop needs more than repeated prompting. It needs a control contract that answers seven questions at every boundary:
- What exact outcome is still required?
- Which objects may change, and which must remain untouched?
- What evidence proves success?
- Which task is runnable now, and who owns it?
- Did the last iteration make measurable progress?
- Is a human decision required before continuing?
- Should the loop succeed, stop, recover, or wait?
RaphaelLoop makes those answers explicit and persists them outside the conversation.
Use cases
RaphaelLoop is a good fit for:
- repairing a reproducible set of test, build, lint, or type-check failures;
- delivering a feature across components with independent acceptance checks;
- improving a measured performance, coverage, reliability, or defect metric;
- coordinating non-conflicting specialists around a dependency graph;
- recovering a long task after context compaction or session interruption;
- stopping safely when progress stalls or a permission boundary is reached.
Use a normal single task instead when one change and one check can finish the work. Do not start a loop for open-ended brainstorming, subjective polishing without a rubric, unbounded monitoring, or unattended destructive and production actions.
How it works
Goal
-> validated contract and finite limits
-> baseline evidence
-> minimum task DAG
-> bounded worker assignments
-> independent verification
-> durable checkpoint
-> succeeded | exhausted | blocked | cancelled
The contract fixes the objective, scope, predicates, verifier commands, evidence locations, budget, and approval boundaries before the first mutation. Each iteration selects the smallest critical-path increment, assigns exclusive ownership, verifies the result, and records a checkpoint.
Activity is not progress. RaphaelLoop counts progress only when a predicate metric improves, a task passes its acceptance check, or a blocking dependency is independently removed. Two completed iterations without measurable progress stop as blocked.
Four operating modes
| Mode | Purpose | Project mutation |
|---|---|---|
design |
Compile and validate a goal contract and minimal task DAG. | No |
run |
Execute bounded work, verification, checkpoints, and terminal decisions. | Within the contract |
resume |
Audit an interrupted state and continue without resetting accepted work or budgets. | Within the existing contract |
audit |
Inspect contract, state, budgets, leases, and evidence integrity. | No |
This separates planning and review from implementation. A request to audit does not silently become a request to edit code, and a resumed task cannot erase prior resource use.
Installation
Requirements:
- Codex, Claude Code, or DeepSeek Harness with Agent/Skill support;
- Node.js with
npxfor the recommended installer; - macOS or Linux;
- Bash 3.2 or newer;
- Python 3.9 or newer for the deterministic runtime kernel and repository validation.
No project .env file or service credential is required. HOME, PATH, TMPDIR, CODEX_HOME, and CLAUDE_CONFIG_DIR are optional host or operating-system environment variables, not RaphaelLoop secrets.
Install directly from GitHub with the open Agent Skills CLI:
npx skills add https://github.com/raphael-liu/raphael-loop --skill raphael-loop
The default command is interactive and project-scoped. It discovers the nested raphael-loop package without installing repository documentation or tests. Review the selected target and installation method before confirming.
List the repository's available Skills without installing:
npx skills add https://github.com/raphael-liu/raphael-loop --list
Codex
npx skills add https://github.com/raphael-liu/raphael-loop --skill raphael-loop --global --agent codex --yes
Claude Code
npx skills add https://github.com/raphael-liu/raphael-loop --skill raphael-loop --global --agent claude-code --yes
DeepSeek Harness
The skill is published to npm as @raphael-liu/raphael-loop with the official dsh.skills declaration. Install it through the DSH plugin channel (profile bundle) or by dropping the bundle into a DSH skill root:
# Official plugin channel (profile bundle; restart dsh after install)
dsh plugin --profile web add @raphael-liu/raphael-loop
# Filesystem skill root (immediate; global or project-scoped)
npx skills add https://github.com/raphael-liu/raphael-loop --skill raphael-loop
cp -R skills/raphael-loop ~/.dsh/skills/raphael-loop # global for the current user
Unlike Codex and Claude Code, DeepSeek Harness has no host-level Agent registration: the six role prompts ship inside the Skill (agents/dsh/*.md) and dispatch through DSH's built-in subagents.
bash skills/raphael-loop/scripts/install-agents.sh --harness dsh --dry-run
bash skills/raphael-loop/scripts/install-agents.sh --harness dsh --check
The CLI installs only skills/raphael-loop/. All six Codex, Claude, and DeepSeek Harness role definitions are already inside that package; no additional Agent repository is downloaded or cloned.
On first use, RaphaelLoop resolves its installed directory and checks the selected host. If the six role definitions are not registered yet, it first previews every host-level target and asks for explicit approval. Only after approval does the bundled install-agents.sh copy the matching protocol files and verify their manifest. Existing different same-named files are preserved in a timestamped backup directory before replacement. A project-scoped Skill may therefore initialize host-level Agent definitions on first use, but never silently.
Maintainers can preview this role-registration step from a source checkout without changing the host:
bash skills/raphael-loop/scripts/install-agents.sh --harness codex --dry-run
bash skills/raphael-loop/scripts/install-agents.sh --harness claude --dry-run
bash skills/raphael-loop/scripts/install-agents.sh --harness dsh --dry-run
The Skills CLI manages the Skill directory, not the separately registered host Agent files. Update a default project installation with npx skills update raphael-loop --project, or a global installation with npx skills update raphael-loop --global. The next RaphaelLoop use checks for stale roles, previews the refresh, and asks for approval.
Before removing either scope, ask the loaded Skill to clean up its managed roles:
Use $raphael-loop to preview and uninstall its bundled role definitions.
Wait for my approval after the dry-run before removing anything.
The underlying safe sequence is --uninstall --dry-run, explicit approval, and then --uninstall. Cleanup refuses to delete modified or stale files and never removes backup directories; resolve those files manually or approve a refresh first. Then run npx skills remove raphael-loop for a project installation or npx skills remove raphael-loop --global for a global installation.
Quick start
Give the loop an objective, protected scope, objective verifiers, and finite limits:
Use $raphael-loop to repair all currently failing tests.
Allowed scope:
- Application source responsible for a baseline failure.
- Focused tests only when evidence proves the test is incorrect.
Prohibited scope:
- Public APIs, persisted formats, test thresholds, dependencies, and deployment.
Success mode: all
1. The full test command exits 0.
2. The existing lint command exits 0.
3. An independent verifier reports no unresolved P1 or P2 regression.
Limits:
- 5 iterations.
- 30 minutes.
- No production or external writes.
RaphaelLoop will normalize the contract, record the baseline, create a task DAG, route the smallest runnable increment, verify it independently, and stop at the first valid terminal condition.
For explicit control, copy the complete runtime contract, adjust its scope, predicates, limits, and tasks, then ask RaphaelLoop to run it. Verifier commands are argument arrays rather than shell strings.
Architecture
RaphaelLoop ships the same six logical roles in both host protocols:
| Role | Responsibility |
|---|---|
| Controller | Owns the contract, budget, checkpoints, progress, and terminal decision. |
| Planner | Derives the minimum predicate-linked task DAG. |
| Orchestrator | Assigns runnable tasks with exclusive ownership and safe concurrency. |
| Worker | Delivers one bounded task packet inside its declared scope. |
| Verifier | Evaluates declared checks independently from the producer. |
| Recovery | Uses a stable failure signature to choose one new action or stop. |
skills/raphael-loop/ distributable Skill boundary
SKILL.md provider-neutral loop protocol
agents/codex/*.toml Codex role definitions
agents/claude/*.md Claude Code role definitions
agents/dsh/*.md DeepSeek Harness role definitions
scripts/install-agents.sh offline host initializer
scripts/raphael_loop.py deterministic runtime kernel
references/runtime.md runtime contract and CLI reference
examples/ copy-ready goal contracts
scripts/validate.sh repository release gate
tests/ packaging and behavior checks
When the host already has a domain specialist, the orchestrator may route a matching task to it. Otherwise, the bundled Worker provides the fallback. The Controller and independent Verifier remain part of every loop.
Runtime kernel and state
Consumer-project state lives under .raphael-loop/<goal-id>/state.json, not in this repository. The zero-dependency kernel validates the contract and DAG, writes state atomically, leases overlapping scopes exclusively, executes only declared verifier argument arrays, enforces bounded flaky-check quorum, and binds evidence to a fingerprint of tracked and non-ignored untracked project files.
Only fresh independently verified work enters a checkpoint. Any fingerprinted project change after verification, including checked-out submodule content, makes that evidence stale. A canonical state hash detects out-of-band edits to counters or evidence. A resumed loop therefore does not repeat accepted tasks or mistake an interrupted Agent response for completed work. See the runtime reference for the schema and commands.
Terminal semantics
RaphaelLoop uses one fixed priority:
cancelled > succeeded > exhausted > blocked
A failed, missing, or stale verifier produces unknown, never success. Reaching a limit is reported as exhausted; lack of a safe path is reported as blocked.
Safety model
RaphaelLoop coordinates work but does not create authority.
- Publishing, payment, deletion, production writes, permission elevation, and other irreversible effects remain human-gated.
- Worker ownership is explicit before concurrent mutation.
- Tests, thresholds, and verifier commands cannot be weakened merely to pass.
- The producer cannot be the sole verifier of its deliverable.
- Existing user changes remain outside an Agent's scope unless the contract includes them.
- Repeated failures stop instead of becoming an infinite retry loop.
- The kernel uses
shell=False, finite verifier timeouts, bounded logs, atomic state writes, and hashed evidence. Verifiers still inherit host authority, so only reviewed project-local commands should be declared; the kernel is not a sandbox. - Side effects require a declared approval gate and idempotency key; the kernel records intent but never publishes, rolls back, deletes, pays, or elevates permission.
The Skill complements the host's sandbox, permissions, and review controls; it does not replace them.
Examples
- Repair failing tests
- Improve measured performance
- Deliver a cross-layer feature
- Executable runtime contract
Each example includes allowed and prohibited scope, fixed verifier commands, finite limits, a copy-ready prompt, and the required terminal report.
Troubleshooting
install-agents.sh --check uses stable exit codes:
| Exit | Meaning | Action |
|---|---|---|
0 |
Installation is healthy | Start the loop. |
2 |
Invalid or ambiguous host argument | Pass --harness codex or --harness claude. |
3 |
Installed files are missing, changed, or stale | Preview the refresh, review backups and targets, then explicitly approve or stop. |
4 |
The bundled Agent set is incomplete or invalid | Restore a complete release before installing. |
10 |
RaphaelLoop Agents are not installed | Preview exact targets and install only after explicit approval. |
Use --dry-run before installing or refreshing when the host already contains same-named Agents. Before removing the Skill, use --uninstall --dry-run; the installer deletes files only when they still match the managed manifest.
Validate a source checkout with:
bash scripts/validate.sh
Contributing
Read CONTRIBUTING.md before changing a role contract. Codex, Claude, and DeepSeek Harness definitions must remain semantically equivalent, executable behavior needs deterministic validation, and repository artifacts must remain free of credentials and private runtime state.
Security concerns belong in private vulnerability reporting; see SECURITY.md.
License
RaphaelLoop is available under the MIT License.
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…
-
titanwings/colleague-skill
将冰冷的离别化为温暖的 Skill，欢迎加入数字生命1.0！Transforming cold farewells into warm skills? It's giving rebirth era. Welcome to Digital …
-
nocobase/nocobase
NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything fr…