LoopPilot

English | 简体中文

LoopPilot is a host-native, runtime-free execution-control Skill for AI agents. It guides an agent to plan, execute, verify, adapt, and stop with evidence while staying within the user's authorization.

Install · Use · Protocol · Documentation · Contributing

Use it for checked multi-step work: implementation, diagnosis, research, writing, and recovery. It reuses the host's own planning, tools, and task state.

Current RC Status

Item	Current recorded status
Development candidate	v1.0.0-rc1 — NOT_RELEASE_READY
Designated Reference Host	Codex, fixed for this RC under the Option B successor
Formal acceptance	NOT_RUN; Gate 4 remains UNMET
Host compatibility	Every host remains explicitly unverified

The candidate decision and latest preflight record the evidence and blockers. Component versions and installation checks have been observed; trusted actual provider/model/endpoint identity, formal loading and Hash B binding, complete isolation, and independent behavior review remain unresolved. Repository tests and independent facts review do not establish Host Acceptance. The RC checklist retains the release gates.

What It Is

LoopPilot is a behavioral specification for an AI agent that already has some combination of context, planning, tools, and task state. It tells that agent to:

1. clarify the real Goal and success criteria;
2. reuse the native Plan instead of creating a second planner;
3. choose and execute the highest-value safe action;
4. verify the real result;
5. adapt only when evidence changes the best path; and
6. stop with an accurate outcome and remaining gaps.

The Skill is a Markdown protocol with no runtime dependency. The repository also includes installers and maintenance validators; these do not provide an independent agent runtime, framework, scheduler, memory service, backend, or fixed integration API.

Why It Is Not a Retry Prompt

A retry prompt usually repeats an operation until a count or timeout. LoopPilot requires every iteration to produce measurable progress, new evidence, a new blocker, or a justified Plan change. An unchanged failed action cannot be repeated merely to keep the loop running.

LoopPilot also distinguishes a recoverable failure from a missing prerequisite, unavailable verification, and diminishing returns. It may change strategy or stop; persistence is not mechanical repetition.

Why It Does Not Replace the Host Planner

LoopPilot treats the host's Goal, Plan, Todo, Memory, tools, and task status as the source of truth when they exist. It updates that state instead of maintaining a parallel Plan. A host with no planning feature may use a minimal task-local Plan, but LoopPilot does not define a universal planner or assume private Goal and Plan APIs.

See host capability levels for prompt-only, planning and tool, and persistent hosts.

One Useful Iteration

The following pseudocode expresses the concept:

while useful_safe_work_remains:
    inspect_goal_and_native_plan()
    action = select_next_unblocked_action()
    result = execute(action)
    evidence = verify(result)
    update_native_plan(result, evidence)

These names are illustrative. They are not functions a host must implement. The actual host may represent the same behavior with conversation context, a task list, tool calls, or persistent state.

A useful iteration changes the task state through progress, evidence, a blocker, or an evidence-backed Plan change. Reflection or status narration without one of those results does not justify another iteration.

When It Activates

Activate for multiple dependent steps whose outcome must be checked, diagnosis or recovery of a failed attempt, or explicit invocation. Checked multi-step non-coding work includes research, writing, analysis, planning deliverables, and information organization. Tools or file edits alone are not triggers. Product Risk sets review, validation, and evidence depth; Coordination Necessity determines Full Loop, not whether the work is coding. The Supervisor owns the mode decision.

The managed lp shortcut is the only short-trigger owner and reads the same installed SKILL.md as /loop-pilot; it never falls back to a repository-local body. See installation and alias binding.

LoopPilot should not implicitly activate for a factual answer, one-sentence rewrite, casual conversation, brainstorming-only request, or advice-only request. Explicit invocation still applies its safety and honesty rules, but does not justify an unnecessary multi-stage Plan.

Lifecycle and Outcomes

The lifecycle is a conceptual vocabulary, not a required state machine.

flowchart LR
    INTAKE --> GOAL_READY
    GOAL_READY --> PLAN_READY
    PLAN_READY --> EXECUTING
    EXECUTING --> VERIFYING
    VERIFYING --> COMPLETED
    VERIFYING --> REPLANNING
    REPLANNING --> PLAN_READY
    INTAKE --> BLOCKED
    GOAL_READY --> BLOCKED
    PLAN_READY --> BLOCKED
    EXECUTING --> BLOCKED
    VERIFYING --> BLOCKED
    REPLANNING --> BLOCKED

Loading

A run reports one primary outcome:

• Completed: the full Goal is satisfied and verified.
• Partially Completed: valuable work exists, but known gaps remain.
• Blocked: a missing prerequisite prevents the next useful action.
• Budget Stop: a resource limit or diminishing return ends the run.

Partially Completed and Budget Stop are report classifications; a host does not need to add them as persisted lifecycle states. See the lifecycle model and safety and stopping.

Minimal Use

Use LoopPilot to update the project configuration, verify the build, and continue
until the acceptance criteria pass or a meaningful stop condition is reached.

Expected behavior:

Goal: update configuration without breaking the build.
Native Plan: inspect -> edit -> build -> inspect diff.
Evidence: actual file contents, command status, and relevant checks.
Stop: Completed, Partially Completed, Blocked, or Budget Stop with remaining gaps.

Shared State and Multi-Agent Handoff

AGENTS.md gives Agents and hosts that load it the same stable instruction priority, verification discipline, safety rules, and authority boundaries. Dynamic task state is kept separate under the optional .looppilot/ protocol, so old task details do not turn into permanent repository rules.

The host-native Goal, Plan, Todo, task state, or memory remains authoritative. Shared files contain only the minimum facts, evidence, blockers, decisions, and next-action summary needed for another Agent or resumed session. They do not store a second complete Plan, complete conversations, tool-call logs, credentials, or private chain-of-thought.

flowchart TD
    USER["User instruction"] --> NATIVE["Host-native Goal / Plan"]
    NATIVE --> LOOP["LoopPilot execution"]
    LOOP --> EVIDENCE["Observed evidence"]
    LOOP --> SHARED["Compact shared state"]
    EVIDENCE --> NEXT["Next agent or resumed session"]
    SHARED --> NEXT

Loading

When unfinished complex work needs durable continuity, the Agent MAY update .looppilot/STATE.md and .looppilot/HANDOFF.md after a material event. The receiving Agent MUST re-check the current user instruction, working tree, native Plan, and tool state. The handoff transfers context, not authority. Simple one-step tasks SHOULD skip shared-state updates entirely.

See AGENTS.md for repository-wide rules, .looppilot/README.md for the protocol, and SKILL.md for LoopPilot's execution behavior.

Supervised Multi-Agent Delegation

LoopPilot can describe supervised delegation when the host already supports multiple Agents, delegated sessions, or equivalent task assignment. It does not automatically create Agents or provide a scheduler, concurrency runtime, file isolation, locking, cancellation service, or merge engine.

One Supervisor remains accountable for the parent Goal. Workers handle only contracted subtasks, an independent Reviewer checks scope and evidence, and one Supervisor or Integrator owns the final combined result. approved means a subtask passed review; it is not integrated until the reviewed work is combined and parent-level checks pass.

Simple tasks are completed directly rather than split for ceremony. Parallel work requires non-overlapping scope or suggestion-only tasks followed by one Integrator edit. Delegation never transfers authority beyond the explicit Task Contract and latest user instruction.

See the coordination design, inactive delegation summary, and Task Contract protocol. Real multi-Agent creation, Reviewer independence, concurrency isolation, and named-host behavior remain unverified.

For complex delegated work, the Supervisor first decides whether current external facts are necessary. It prepares a traceable Research Brief only when local evidence is not sufficient, and selects only Skills the host has actually confirmed are available. The minimum relevant Skill set and fallback are recorded in the Task Contract; assignment never expands authority or installs anything.

Submitted tasks pass through separate Standards and Spec reviews. Both must pass and required evidence must be observed before approved. The parent Checklist remains unchecked until the Integrator combines the work and verifies the parent result. It stores stable deliverables, concise evidence, context pressure, and one Resume Point rather than duplicating the native Plan.

Context pressure is classified as unknown, normal, elevated, high, or critical. High or critical pressure triggers state persistence and a controlled budget stop before forced interruption; no exact token balance is assumed. Real network research, installed-Skill discovery, token signals, independent Reviewers, and budget-stop recovery remain host capabilities and are not verified by this repository's static tests.

Loop Engineering Foundation

LoopPilot now defines the first-stage architecture for a Project made of bounded Loops. A Loop is a cohesive change set that can be independently implemented, integrated, reviewed, accepted, committed when authorized, and resumed from persisted state. The model connects Tasks, Worker Deliveries, Integration Records, Review Reports, Findings, three-layer acceptance, Loop Closure, and Checkpoints.

The existing shared-state protocol remains Lightweight Mode. Full Loop Mode is a documented migration target for multi-Loop or cross-context delivery whose coordination needs require it; it is not an implemented runtime or a claim of host compatibility.

Start with the Loop Engineering model, the Project Engineering Context, pattern-selection rules, the Project Closure target, and the Full Loop migration plan.

Full Loop Contracts and Ledgers

Phase 2 adds inactive Full Loop templates for a Project Loop Map, Loop Contract, Task Ledger, and Finding Ledger. The Loop Map owns Loop status; the two Ledgers own Task and Finding status. Detailed artifacts and Checklists remain projections or evidence, and only a closed Loop may be checked.

Lightweight Mode remains unchanged for small work. These templates and validators are static protocol structure, not a workflow runtime or evidence of real-host behavior. See Full Loop contracts and Ledgers.

Full Loop Delivery, Review, and Closure

Phase 3 adds six inactive templates for Worker Delivery, Integration Record, Review Report, Finding Detail, Rework Task, and Loop Closure. Task-level Readiness gates a Delivery into integration; Loop-level Spec and Standards reviews judge the unified outcome. Findings enter the Finding Ledger before scoped rework, Reviewer reverification precedes closure, and Loop Closure projects closed only through the Loop Map after all acceptance layers and Barriers pass.

This remains a static protocol: it does not schedule Agents, mutate Ledgers, integrate Git work, infer severity, create commits, or recover a Checkpoint. See the Phase 3 delivery protocol.

Full Loop Checkpoint and Context Recovery

Phase 4 adds three inactive templates: Checkpoint, Context Compaction Manifest, and Resume Validation Report. CHECKPOINT.md is the only recovery authority; it records a verified repository boundary, unfinished work, current permissions, evidence to revalidate, and one exact Resume Point. The Manifest selects minimal context, and the Resume Report compares the record with current instructions, Git, Ledgers, artifacts, tools, Skills, and authority before continuation.

At high context pressure the Supervisor stabilizes the smallest safe verifiable unit and prepares recovery state. At critical pressure new work stops after state is persisted. These static contracts do not count tokens, compact context, create Checkpoints, start sessions, transfer Agents, reset Git, or execute recovery. See the Phase 4 recovery protocol.

Project Closure and Final Delivery

Phase 5 adds four inactive templates for Cross-Loop Validation, Project Acceptance, Release Readiness, and the Final Delivery Report. Closed mandatory Loops are only inputs: the integrated Project outcome still requires Goal-to-Evidence Mapping, Project Spec and Standards Review, Functional/Engineering/Delivery Acceptance, Project Finding routing through remediation Loops, an honest release relationship, a Final Checkpoint, and a user-readable report.

PROJECT.md remains the only Project status authority. Readiness does not grant tag, release, deploy, migrate, rollback, or traffic-change authority, and acceptance does not imply release execution or user acknowledgement. These templates and their validator are static protocol checks, not a Project Closure or release runtime. See the Phase 5 protocol.

Final Protocol Calibration and Feature Freeze

Phase 11 makes each lifecycle fact single-authority, treats supporting copies as derived projections, and requires a finite lifecycle consistency snapshot before a new Full Loop Closure becomes ready. Exact comparisons run through the public validator; semantic contradiction remains independent Reviewer judgment. Legacy Closures without the new section receive migration guidance rather than an unconditional failure.

The v1 core protocol is feature frozen after Phase 11. Before the Release Candidate, work is limited to bug, compatibility, security, documentation, host-adapter, trigger-tuning, and validator-correctness fixes. No new role, mode, Ledger, lifecycle subsystem, Barrier, or acceptance model is added. See final protocol calibration, lifecycle authority and derived projections and v1 migration.

Cross-Host Acceptance Preparation

The Cross-Host Acceptance procedure defines how a host, host version, model, and loading-mode combination earns an evidence-backed verdict on eight protocol dimensions, and which conditions gate the v1.0 Release Candidate. Verdicts come from observed Host Acceptance Records that reference real evaluation runs; the public validator checks record structure and verdict constraints. Defining the procedure verifies no host: every combination remains unverified until an observed accepted record supports a narrower verdict. The bounded Option B successor lets each applicable future RC select exactly one Reference from Claude Code and Codex before formal acceptance. This candidate selects Codex, retains unknown runtime identity, and is NOT_RELEASE_READY with Gate 4 unmet. Historical Claude Code preparation notes live in evaluations/claude-code.

Evidence-Calibrated Protocol Selection

Phase 7 synthesizes four bounded, read-only MMGH experiments into documentation labels and proportional defaults. The Supervisor selects Lightweight, Full Loop, or No Implementation before implementation; the Integrator records the decision. Lightweight targets four to seven Governance Artifacts as a provisional heuristic and escalates when risk or scope outgrows its contract. Tool, Agent, and host failures are Execution Infrastructure Incidents unless evidence proves a Product or Protocol Finding. Specialist Reviewers are loaded by risk, and Project Finalization is not loaded for an ordinary single change.

See evidence synthesis, mode selection, load profiles, and the MMGH evidence boundary.

Second Evidence-Backed Calibration

Phase 9 incorporates bounded Final-Assignment evidence. Product Risk sets review, validation, and evidence depth; Coordination Necessity decides whether Full Loop is needed. Lightweight may use risk-matched specialists without becoming a third mode. The calibration adds red-baseline attribution, Verification Surface inventory, verifiable Worker claims, delegation fallback, and separate product, governance, and evaluation artifact accounting. EXP-006 comparative scoring remains unverified where the committed control archive is incomplete.

See Phase 9 calibration, baseline evidence, coordination necessity, and Final-Assignment evidence.

Example Applications

• Programming: revise an implementation after a failing test, then run relevant checks and inspect the diff. See the coding trace.
• Research: investigate conflicting sources and expose unresolved uncertainty. See the research trace.
• Writing: compare a draft with its brief, revise a missed requirement, and stop when all requested checks pass. See the writing trace.

Every example is an illustrative trace. It does not claim real commands, searches, or external actions.

Install or Copy

LoopPilot has no runtime dependency for Skill users. Distribution-001 provides stateful installers that preserve the complete repository-relative payload:

.\install.ps1 -Destination "$HOME\.codex\skills\loop-pilot"

./install.sh --destination "$HOME/.codex/skills/loop-pilot"

The destination may instead be supplied through LOOPPILOT_INSTALL_DIR. Without an explicit destination, the scripts use a single detectable Claude Code or Codex skills directory and stop if detection is absent or ambiguous. Directory detection does not establish host compatibility; every host remains unverified until an accepted Host Acceptance Record exists.

Use update.ps1 or update.sh from the new source package to upgrade. Use uninstall.ps1 or uninstall.sh to remove only state-recorded, unmodified managed files. Local modifications, unrelated files, and backups are preserved by default. See the installation and distribution guide for layout, ownership, conflict, backup, upgrade, and uninstall behavior. Observed packaging checks are recorded separately in installation validation.

Manual copying remains possible: copy or clone the repository, expose SKILL.md through the host's documented Skill or instruction mechanism, and preserve its relative supporting files.

Repository maintainers can install the isolated development dependency and run the repeatable checks described in validation.

The installation CI matrix checks Windows PowerShell 5.1/7 and Git Bash, Ubuntu Bash/PowerShell 7, and macOS system Bash 3.2/PowerShell 7. Job artifacts record actual platform/architecture, shell versions, native lifecycle logs and receipt hashes. Coverage applies only to each successful recorded packaging run; it does not establish AI-host behavior. See platform maintenance verification.

Safety and Progress

LoopPilot interprets authority narrowly. Commit, push, publish, deploy, message sending, destructive changes, credential exposure, and irreversible operations require their own explicit authorization. Permission for one does not imply another.

For long tasks, the agent should communicate the Goal and next action, then update the user only after material results, blockers, or Plan changes. Routine tool narration and promises of future asynchronous work are outside the contract.

Compatibility Boundary

LoopPilot describes capability levels, not certified product integrations. Evidence quality and persistence depend on the host's actual tools and state. A prompt-only host cannot claim background execution, durable recovery, or direct verification it does not possess. A qualified Host Acceptance Record must bind any compatibility verdict to the exact observed host, version, model, and loading combination.

Validation Status

This section separates what the repository implements, what has actually been observed, and what remains unverified. The three are not interchangeable.

Implemented

Present in the repository and exercised by static checks:

• Protocol rules in SKILL.md, AGENTS.md, and the docs/ protocol documents, through Phase 11 lifecycle authority and the v1 feature freeze.
• Validators under scripts/, entered through python scripts/validate.py.
• Inactive templates under .looppilot/ and evaluations/templates/.

Implemented means the rule, validator, or template exists and passes the repository's own checks. It does not mean an agent follows it.

Observed

Recorded from bounded experiments, each scoped to its own project and archive:

• MMGH EXP-001 to EXP-004 informed Phase 7 mode selection.
• Final-Assignment EXP-005 informed Phase 8-A. EXP-006 arm execution was observed; its dynamic holdout is partially unverified and the inspected control archive lacks final comparative scoring.
• EXP-008 and EXP-009 are attributed to their supplied archived reports.
• GamePulse EXP-010 reported a verified partial delivery whose final Full Loop behavioral acceptance failed.

Observed means it happened in a specific recorded run. It does not generalize to another project, host, or model.

Unverified

No evidence in this repository supports any of the following:

• Actual host behavior. Every host, including this RC's designated Codex Reference, is unverified because no qualified RC-bound accepted Host Acceptance Record exists. Earlier Claude Code preparation and historical records retain their original scope and verdicts.
• Production reliability, longitudinal governance behavior, release, and deployment.
• Automatic agent compliance, including implicit activation accuracy, automatic mode selection, automatic Loop decomposition, dynamic Reviewer selection, multi-Agent creation, Checkpoint recovery, and Project Closure execution.
• Phase 11 behavior: it is statically implemented and behaviorally unverified.

The repository-level checks below have been exercised with pinned tools:

• Skill frontmatter and repository YAML parse with PyYAML 6.0.3, including duplicate mapping-key rejection and required metadata checks.
• Markdown relative links, code fences, final newlines, trailing whitespace, and the declared Skill word range pass the static validator.
• All repository Mermaid diagrams, including Loop objects, mode selection, barriers, delegation, and Project Closure, render to non-empty SVG files with Mermaid CLI 11.16.0.

These are syntax and repository-structure checks, not behavioral compatibility evidence. The evaluation templates prepare that future work without claiming results, and the v1.0 RC checklist tracks what must be observed before a development candidate can qualify for release.

Current Limitations

• No independent runtime, planner, tool layer, memory, scheduler, or recovery service is included.
• Prompt-only hosts have weak state continuity and may require user-attributed evidence.
• The lifecycle and pseudocode are conceptual, not executable interfaces.
• Every host remains explicitly unverified. Claude Code, Codex, Gemini CLI, GitHub Copilot, and every other host have no accepted Host Acceptance Record, so this repository claims no compatibility with any of them. A host moves off this list only through an observed Host Acceptance Record, and its verdict then covers only that exact host, host version, model, and loading mode. For v1.0.0-rc1, Codex is the designated Reference; Claude Code, Gemini CLI, GitHub Copilot, and other hosts remain Candidates with their disclosure duties.
• Real concurrent scheduling, runtime permission isolation, distributed locking, automatic merging, and cross-session delegated recovery are not implemented.
• Automatic-trigger accuracy and behavioral reliability still require observed real-host traces and rubric scoring.

Roadmap

• Run Cross-Host Acceptance with the defined procedure and close the v1.0 RC checklist before qualifying the development candidate for release.
• Record reproducible evaluation traces without turning examples into fake evidence.
• Add narrowly scoped host notes only when an adapter and tests support them.
• Refine false-positive activation and unnecessary-loop cases.

Repository Guide

The source-only documentation index groups current use, protocol support, acceptance preparation, and historical material. The archive index maps the five reports moved from the repository root; these indexes are repository references and are not copied by the installer.

• 简体中文 README: Chinese introduction, usage, and evidence boundaries.

• SKILL.md: executable instructions.

• Lifecycle: conceptual states and transitions.

• Host capabilities: adaptation boundaries.

• AGENTS.md: stable repository-level Agent instructions.

• Shared-state protocol: optional continuity and handoff.

• Safety and stopping: authority and outcomes.

• Multi-Agent coordination: supervised delegation, review, conflict, and integration protocol.

• Design rationale: design tradeoffs.

• Lifecycle authority and projections: Phase 11 authority, derived snapshot, and Closure consistency rules.

• Final protocol calibration: Phase 11 evidence classification, calibration table, and bounded conclusion.

• v1 migration: backward-compatible adoption guidance.

• Cross-Host Acceptance: per-host acceptance procedure, verdicts, and the Release Candidate checklist.

• v1.0 RC checklist: Release Candidate gates and their required evidence. The checklist is not acceptance.

• Current candidate decision and RC1 preflight: current recorded facts, unmet prerequisites, and safe next steps.

• Validation: repeatable maintenance checks and their boundary.

• Full Loop Contracts and Ledgers: Phase 2 templates, state enums, completion projection, and authority rules.

• Full Loop Delivery, Review, and Closure: Phase 3 evidence, review, rework, and closure contracts.

• Full Loop Checkpoint and Context Recovery: Phase 4 pressure, Budget Stop, compaction, Checkpoint, and resume-validation contracts.

• Project Closure and Final Delivery: Phase 5 cross-Loop evidence, Project acceptance, release readiness, final recovery, and recipient-facing delivery reporting.

• Examples: illustrative traces.

• Behavioral scenarios: counterexamples and evaluation cases.

• Evaluation rubric: 0-to-3 scoring.

• Evaluation preparation: future trace and score templates.

• CONTRIBUTING.md: contribution requirements.

• CHANGELOG.md: notable changes.

License

LoopPilot is available under the MIT License. Copyright 2026 Tutict.