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:

1. What exact outcome is still required?
2. Which objects may change, and which must remain untouched?
3. What evidence proves success?
4. Which task is runnable now, and who owns it?
5. Did the last iteration make measurable progress?
6. Is a human decision required before continuing?
7. 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 npx for 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.