Immutable. This exact content is served forever at /api/v1/blob/d82ec2a1732be4ac.
---
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)