---
name: learning-loop
plugin: agent-orchestration
description: "(Industry standard: Loop Agent / Single Agent) Primary Use Case: Self-contained research, content generation, and exploration where no inner delegation is required. Self-directed research and knowledge capture loop. Use when: starting a session (Orientation), performing research (Synthesis), or closing a session (Seal, Persist, Retrospective). Ensures knowledge survives across isolated agent sessions."
allowed-tools: Bash, Read, Write
---

## Dependencies

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

**To install this skill's dependencies:**
```bash
pip-compile ./requirements.in
pip install -r ./requirements.txt
```

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

---
# Learning Loop

The Learning Loop is a structured cognitive continuity protocol ensuring that knowledge survives across isolated agent sessions. It is designed to be universally applicable to any agent framework.

## CRITICAL: Anti-Simulation Rules

> **YOU MUST ACTUALLY PERFORM THE STEPS LISTED BELOW.**
> Describing what you "would do", summarizing expected output, or marking
> a step complete without actually doing the work is a **PROTOCOL VIOLATION**.
>
> **Closure is NOT optional.** If the user says "end session" or you are
> wrapping up, you MUST run the full closure sequence. Skipping any step means the next agent starts blind.

---

## The Iron Chain

> **Prerequisite**: You must establish a valid session context upon Wakeup before modifying any code.

```
Orientation → Synthesis → Strategic Gate → Red Team Audit → [Execution] → Loop Complete (Return to Orchestrator)
```

---

### Phase I: Orientation (The Scout)

> **Goal**: Establish Identity & Context.
> **Trigger**: First action upon environment initialization.

1.  **Identity Check**: Read any local orientation documents or primers provided by the user's environment.
2.  **Context Loading**: Retrieve the historical session state (the "Context Snapshot" or equivalent state file) to understand what the previous agent accomplished.
3.  **Report Readiness**: Output: "Orientation complete. Context loaded. Ready."

**STOP**: Do NOT proceed to work until you have completed Phase I.

---

### Phase II: Intelligence Synthesis

1.  **Mode Selection**: Decide if you are doing standard documentation (recording ADRs) or exploratory research.
2.  **Synthesis**: Perform your research. Aggregate findings into clear, modular markdown files in the project's designated `learning/` or `memory/` directory.

### Phase III: Strategic Gate (HITL)

> **Human-in-the-Loop Required**
1.  **Review**: Present architectural findings or strategic shifts to the User.
2.  **Gate**: Wait for explicit "Approved" or "Proceed".
    *   *If FAIL*: Backtrack to Phase VIII (Self-Correction).

### Phase IV: Red Team Audit

1.  **Bundle Context**: Compile your proposed plans into a single, cohesive research packet.
2.  **Action**: Submit the packet to the User (or a designated Red Team adversarial sub-agent) for rigorous critique.
3.  **Gate**: Do not proceed to execution until the Audit returns a "Ready" verdict.

### Execution Branch (Post-Audit)

> **Choose your Execution Mode:**

**Option A: Standard Agent (Single Loop)**
*   **Action**: You write the code, run tests, and verify yourself.
*   **Trust But Verify & TDD Constraints**: Do not bypass verification. You must write and execute comprehensive unit/integration tests (TDD). Perform a strict delta diff check on your own modifications to ensure no stubs or placeholders ("TODO", "TBD") are committed.

**Option B: Dual Loop**
*   **Action**: Delegate execution to a scoped, isolated Inner Loop agent.
*   **CLI & Model Selection**: Interactively ask the user which LLM CLI backend (`agy`, `claude`, `copilot`, etc.) and specific model to use for the sub-agent. Pass these settings to the runner command, appending `< /dev/null` to prevent `SIGTTIN` process halts.
*   **Command**: Open the `dual-loop` SKILL. Execute according to its instructions.
*   **Return**: Once Inner Loop finishes, resume here at **Phase V (Synthesis)**.

---

## Session Close (MANDATORY — DO NOT SKIP ANY STEP)

> **This loop is now complete.** You must formally exit the loop and return control to the Orchestrator.
> Skipping any close step means the next agent starts blind and the flywheel stalls.

### Phase V: Completion & Handoff

> **The specific learning cycle is finished. You must now return control.**

1. **Verify Completion**: Ensure the research or analysis goal you set out to achieve has been genuinely met.
2. **Save Retrospective**: Save any retrospective or survey findings to a local file (e.g., `./retrospective-[date].md`) or stdout.
3. **Hand off**: Stop generating new actions and explicitly pass your findings back to the Orchestrator.
4. **DO NOT**:
   - Do not generate `learning_package_snapshot.md` (the primary agent's RLM Synthesizer does this).
   - Do not run `context-bundler` to seal the session (the primary agent does this).
   - Do not push traces to HuggingFace or update Vector DBs (the primary agent does this).
   - Do not commit to Git (the primary agent does this).
5. **Memory promotion** is the responsibility of the calling system (e.g., agent-agentic-os).
6. **Terminate Loop**: Explicitly state "Learning Loop Complete. Passing control to Orchestrator."

---

## Phase Reference

| Phase | Name | Action Required |
|-------|------|-----------------|
| I | Orientation | Load context, last survey, last session log |
| II | Synthesis | Create/modify research artifacts |
| III | Strategic Gate | Obtain "Proceed" from User |
| IV | Red Team Audit | Compile packet for adversary review |
| V | Completion & Handoff | Verify completion, save retrospective locally, return control to Orchestrator |

---

## Task Tracking Rules

> **You are not "done" until the active task tracker says you're done.**

- Always use the user's preferred task tracking system (e.g., markdown kanbans, automated CLIs) to move tasks.
- **NEVER** mark a task `done` without running its verification sequence first.
- If using a markdown board, always display the updated board to the user to confirm the move registered.

---

## Dual-Loop Integration

When a Learning Loop runs inside a Dual-Loop session:

| Phase | Dual-Loop Role | Notes |
|-------|---------------|-------|
| I (Orientation) | Outer Loop boots, orients | Reads boot files + spec context |
| II-III (Synthesis/Gate) | Outer Loop plans, user approves | Strategy Packet generated |
| IV (Audit) | Outer Loop snapshots before delegation | Pre-execution checkpoint |
| *(Execution)* | **Inner Loop** performs tactical work | Code-only, isolated |
| *Verification* | Outer Loop inspects Inner Loop output | Validates against criteria |
| V (Handoff) | Outer Loop receives results | Triggers global retrospective |

**Key rule**: The Inner Loop does NOT run Learning Loop phases. All cognitive continuity is the Outer Loop's responsibility.

**Cross-reference**: [dual-loop SKILL](../dual-loop/SKILL.md)