richfrem/dual-loop

Dependencies

This skill requires Python 3.8+ and standard library only. No external packages needed.

To install this skill's dependencies:

pip-compile ./requirements.in
pip install -r ./requirements.txt

See ../../requirements.txt for the dependency lockfile (currently empty — standard library only).

---

Dual-Loop (Inner/Outer Agent Delegation)

This skill defines the orchestration pattern for the Dual-Loop Agent Architecture. The Outer Loop (the directing agent) uses this protocol to organize work, delegate execution to an Inner Loop (the coding/tactical agent), and rigorously verify the results before merging.

This architecture is entirely framework-agnostic and can be utilized by any AI agent pairing (e.g., Antigravity directing Claude Code, or an OpenHands agent directing a specialized CLI sub-agent).

CRITICAL: Anti-Simulation Rules

YOU MUST ACTUALLY PERFORM THE VALIDATIONS LISTED BELOW. Describing what you "would do" or marking a step complete without actually doing the verification is a PROTOCOL VIOLATION.

---

Architecture Overview

flowchart LR
    subgraph Outer["Outer Loop (Strategy & Protocol)"]
        Scout[Scout & Plan] --> Spec[Define Tasks]
        Spec --> Query[Query User]
        Query --> Packet[Generate Strategy Packet]
        Verify[Verify Result] -->|Pass| Commit[Seal & Commit]
        Verify -->|Fail| Correct[Generate Correction Packet]
    end

    subgraph Inner["Inner Loop (Execution)"]
        Receive[Read Packet] --> Plan[Commit to Plan]
        Plan --> Execute[Write Code & Run Tests]
        Execute -->|No Git| Done[Signal Done]
    end

    Packet -->|Handoff| Receive
    Done -->|Completion| Verify
    Correct -->|Delta Fix| Receive

Reference: Architecture Diagram

---

The Workflow Loop

Step 1: The Plan (Outer Loop)

1. Orientation: The Outer Loop agent reads the project requirements or goals.
2. Decomposition: Break the goal down into distinct Work Packages (WPs) or sub-tasks.
3. Verification: Confirm that the tasks are atomic, testable, and do not overlap.

Step 1.5: Interactively Determine CLI and Model (Outer Loop)

Before generating the Strategy Packet or executing commands, you must interactively ask the user:

1. "Which LLM CLI backend would you like to use for the inner loop execution?"
   • Options: agy (Antigravity CLI), claude (Claude CLI), copilot (GitHub Copilot CLI), codex (OpenAI-compatible CLI), or llama (local Gemma host).
2. "Which specific model should be used?"
   • Prompt them with standard defaults or allow them to specify a custom model name (e.g., Gemini 3.5 Flash (Low)).

Once confirmed, record this configuration and use the selected CLI and model in the sub-agent delegation command.

Step 2: Prepare Execution Environment

1. Isolation: Ensure a safe workspace exists for the Inner Loop. Workspace creation (e.g., worktrees, branching, ephemeral containers) is strictly a delegated responsibility of the Orchestrator or external tooling. The Dual-Loop just receives the environment.
2. Update State: Mark the current Work Package as "In Progress" in whatever task-tracking system the project uses.

Step 3: Generate Strategy Packet (Outer Loop)

1. Write a tightly scoped markdown document (the "Strategy Packet") specifically for the Inner Loop.
2. Requirements for the Packet:
   • The exact goal.
   • A Pre-Execution Workflow Commitment Diagram (an ASCII box) mapping out the steps the Inner Loop must take.
   • Only the specific file paths the sub-agent needs to care about.
   • Strict "NO GIT" constraints (the Inner Loop must not commit).
   • If generating scripts/pipelines, instruct the Inner Loop to use the "Modular Building Blocks" architecture (split convenience CLI wrappers from core Python APIs).
   • Clear Acceptance Criteria.
3. Save the packet (e.g., handoffs/task_packet_001.md).

Step 4: Hand-off (The Bridge)

(Best Practice: Run a functional CLI heartbeat using a simple health prompt to verify end-to-end connectivity before the first hand-off).

The Outer Loop invokes the Inner Loop. To ensure stability, avoid shell process hangs in background/headless environments (which freeze when attempting to read standard input without redirection), and target the chosen LLM backend, the Outer Loop must run run_agent.py using relative pathing and passing the user's selected CLI and model. Always append < /dev/null to the command to prevent SIGTTIN halts:

# Explicitly delegate inner-loop execution with redirected stdin and chosen model
python scripts/run_agent.py \
  handoffs/task_packet_001.md \
  <target_file_to_modify> \
  handoffs/result_packet.md \
  "Execute the strategy packet instructions exactly." \
  --cli <selected_cli> \
  --model "<selected_model>" < /dev/null

If run_agent.py is unavailable, this is done by spawning a sub-process (e.g., agy -p "Read handoffs/task_packet_001.md" < /dev/null), calling an API, or asking the Human User to switch terminals.

Step 5: Execute (Inner Loop)

The Inner Loop agent:

1. Reads the packet.
2. Writes the code.
3. Runs the tests.
4. Signals "Done" when the Acceptance Criteria are met (or if it gets fundamentally stuck).

Constraint: The Inner Loop MUST NOT run version control commands.

Step 6: Verify (Outer Loop)

Once the Inner Loop signals completion, the Outer Loop must verify the results under the Trust But Verify and TDD principles:

1. No Blind Trust: Never accept the sub-agent's work without direct validation. You bear full responsibility for the stability and accuracy of the code.
2. Delta Check: Inspect the changes (e.g., via git diff or system state checks) to see exactly what files the Inner Loop altered. Ensure no unexpected files were modified, no stubs were left, and no security regressions were introduced.
3. TDD / Test Check: Run the unit and integration test suite mechanically. If new functionality was added, ensure corresponding tests exist and pass. Do not proceed without functional test validation.
4. Lint & Placeholder Scan: Validate syntax and scan the code for stub placeholders ("TODO", "TBD", "[NEEDS INPUT]"). Reject any incomplete work.

On Verification PASS:

1. The Outer Loop accepts the changes.
2. The task tracker is updated to "Done".

On Verification FAIL:

1. The Outer Loop generates a Correction Packet using the strict Severity-Stratified Output Schema:
   • 🔴 CRITICAL: The code fails to compile, tests fail, or the requested feature is entirely missing.
   • 🟡 MODERATE: The feature works, but violates project architecture, ADRs, or performance standards.
   • 🟢 MINOR: The feature works and follows architecture, but has minor naming or stylistic issues.
2. The Outer Loop loops back to Step 4, handing the Correction Packet to the Inner Loop.
3. Emit Friction Event: Every Verification FAIL should be logged to a local friction log (e.g., ./friction-log.md) for the Orchestrator to review at handoff.

Step 7: Self-Assessment Survey (MANDATORY — Outer Loop and Inner Loop)

Before handoff, both the Outer Loop and Inner Loop MUST each complete the Post-Run Self-Assessment Survey (references/memory/post_run_survey.md). Answer every section in full.

Count-Based Signals: How many times did you not know what to do next? Miss a step? Use wrong CLI syntax? Get redirected by a human? Total friction events?

Qualitative Friction: Where were you most uncertain? Which step felt ambiguous? What was the biggest source of friction? What one change would have helped most?

Improvement Recommendation: What one change should be tested before the next run? What is the target (Skill/Prompt/Script/Rule)?

Save to a local file (e.g., ./retrospective-[YYYYMMDD]-[HHMM]-[AGENT].md) or stdout.

If any single friction cause appears 3+ times this cycle, flag for Triple-Loop Retrospective Full Loop before the next cycle begins.

Step 8: Completion & Handoff

Once all Work Packages are verified and surveys saved, the Dual-Loop pattern is complete. The Outer Loop terminates and returns control to the global lifecycle manager (Orchestrator). Memory promotion is the responsibility of the calling system.

---

Task Lane Management

Throughout the process, the Outer Loop must maintain discipline over task states. If you are operating this loop, you must ensure you or the task tracker accurately reflects:

1. Backlog -> Doing (When Strategy Packet is generated)
2. Doing -> Review (When Inner Loop signals completion)
3. Review -> Done (When Outer Loop verifies and commits)
4. Review -> Doing (If verification fails and a Correction Packet is sent)

---

Workspace Isolation

Dual-Loop (Agent-Loops) does not manage workspaces. It receives an isolated directory or execution context from the Orchestrator and runs the loop inside it. Workspace creation (e.g., git worktrees, branches) is a delegated responsibility of the Orchestrator or the global system environment.

Fallback: In-Place Execution

If an isolated workspace cannot be provided:

1. The Inner Loop codes directly in the main directory.
2. The Outer Loop must log this lack of isolation in a friction log for the handoff to the Orchestrator.
3. All other constraints (no system manipulation from Inner Loop out of scope, verification gate, correction packets) still apply.

---

Fundamental Constraints

• No Protocol Crossing: The Inner Loop manages tacticals (code compilation, tests). The Outer Loop manages strategy (git, architecture decisions, human interactions).
• Isolation: Strategy Packets must be minimal. Do not send the Inner Loop thousands of lines of conversation history. Give it exactly what it needs to execute the specific Work Package.