Skip to content

LeoYeAI/agent-master-skills / skills/agent-mode-upgrades

agentic-loop-upgrade

Flagged

Enhanced agentic loop with planning, parallel execution, confidence gates, semantic error recovery, and observable state machine. Includes Mode dashboard UI for easy configuration.

# šŸš€ Agentic Loop Upgrade

[![Source](https://img.shields.io/badge/source-github.com%2Fopenclaw%2Fskill--agentic--loop--upgrade-blue)](https://github.com/openclaw/skill-agentic-loop-upgrade)
[![ClawHub](https://img.shields.io/badge/clawhub-agentic--loop--upgrade-green)](https://clawhub.com/skills/agentic-loop-upgrade)
[![License](https://img.shields.io/badge/license-MIT-lightgrey)](./LICENSE)

An enhanced agentic loop for [OpenClaw](https://github.com/openclaw/openclaw) with planning, parallel execution, confidence gates, and semantic error recovery.

![Mode Dashboard](assets/mode-dashboard.png)

## ✨ Features

| Feature | Core Loop | Enhanced Loop |
|---------|-----------|---------------|
| **Planning** | āŒ Reactive | āœ… Goal decomposition with step tracking |
| **Execution** | Sequential | āœ… Parallel (independent tools) |
| **Error Handling** | Retry-based | āœ… Semantic recovery with alternatives |
| **Confidence** | Implicit | āœ… Explicit gates for risky actions |
| **Context** | Overflow-triggered | āœ… Proactive summarization |
| **State** | Implicit | āœ… Observable FSM with checkpointing |

## šŸŽÆ What It Does

### Planning & Reflection
The agent decomposes complex goals into step-by-step plans, tracks progress across turns, and reflects after each action to assess if steps are complete.

### Parallel Execution
Independent tools execute concurrently for faster task completion. The orchestrator identifies which tools can run in parallel.

### Confidence Gates
Before risky operations (file deletions, external messages, etc.), the system assesses confidence and can pause for approval.

### Semantic Error Recovery
When tools fail, the system diagnoses the error type and attempts alternative approaches rather than simple retries.

### Observable State Machine
Explicit state tracking enables debugging, dashboards, and checkpointing for resuming interrupted tasks.

## šŸ“¦ Installation

### From ClawHub
```bash
openclaw skill install agentic-loop-upgrade
```

### Manual Installation
1. Clone/download to your skills directory:
   ```bash
   cd ~/.openclaw/skills
   git clone https://github.com/openclaw/skill-agentic-loop-upgrade agentic-loop-upgrade
   ```

2. Build the TypeScript:
   ```bash
   cd agentic-loop-upgrade/src
   npm install
   npm run build
   ```

3. Restart OpenClaw:
   ```bash
   openclaw gateway restart
   ```

## šŸš€ Quick Start

### Enable via Dashboard

1. Open OpenClaw Dashboard → **Agent** → **Mode**
2. Click **Enhanced Loop** card
3. Configure settings (or use defaults)
4. Click **Save Configuration**

### Disable

- Mode tab → Click **Core Loop** → Save
- Or delete: `~/.openclaw/agents/main/agent/enhanced-loop-config.json`

## āš™ļø Configuration

All settings are available in the Mode dashboard:

### Planning & Reflection
- **Enable Planning**: Generate execution plans before complex tasks
- **Reflection After Tools**: Assess progress after each tool execution
- **Max Plan Steps**: Maximum steps in a generated plan (2-15)

### Execution
- **Parallel Tools**: Execute independent tools concurrently
- **Max Concurrent**: Maximum parallel tool executions (1-10)
- **Confidence Gates**: Assess confidence before risky actions
- **Confidence Threshold**: Minimum confidence to proceed (30-95%)

### Context Management
- **Proactive Management**: Summarize and prune before overflow
- **Summarize After N Iterations**: Trigger summarization interval
- **Context Threshold**: Context fill level to trigger management

### Error Recovery
- **Semantic Recovery**: Diagnose errors and adapt approach
- **Max Recovery Attempts**: Maximum alternative attempts (1-5)
- **Learn From Errors**: Store successful recoveries for future use

### State Machine
- **Enable State Machine**: Track agent state transitions
- **State Logging**: Log all state transitions
- **Metrics Collection**: Collect timing metrics per state

### Orchestrator Model
Select a cost-effective model for planning/reflection calls (e.g., Claude Sonnet 4.5).

## šŸ“ File Structure

```
~/.openclaw/
ā”œā”€ā”€ agents/main/agent/
│   └── enhanced-loop-config.json    # Configuration
ā”œā”€ā”€ agent-state/                      # Persistent plan state
│   └── {sessionId}.json
└── checkpoints/                      # Checkpoint files
    └── {sessionId}/
        └── ckpt_*.json
```

## šŸ”§ For Developers

### Programmatic Usage

```typescript
import { createOrchestrator } from "@openclaw/enhanced-loop";

const orchestrator = createOrchestrator({
  sessionId: "session_123",
  planning: { enabled: true, maxPlanSteps: 7 },
  approvalGate: { enabled: true, timeoutMs: 15000 },
  retry: { enabled: true, maxAttempts: 3 },
  context: { enabled: true, thresholdTokens: 80000 },
  checkpoint: { enabled: true },
}, {
  onPlanCreated: (plan) => console.log("Plan:", plan.goal),
  onStepCompleted: (id, result) => console.log("āœ“", result),
});

await orchestrator.init();
```

### Architecture

See [SKILL.md](./SKILL.md) for full technical documentation.

## šŸ”’ Security & Trust

This skill wraps the agent runner and appends plan context to the agent's prompt. Both operations are bounded, transparent, and auditable:

| Property | Value |
|---|---|
| Outbound network | LLM provider only (inherited from host) |
| Telemetry / phone-home | āŒ None |
| Prompt modification | āœ… Additive-only (appends status text; never replaces core prompt) |
| Runner bypass | āŒ Never — original runner always called |
| Credential storage | āŒ None |
| Persistence | Local `~/.openclaw/` only |
| Enabled by default | āŒ No — requires explicit opt-in |

**Post-install verification:**
```bash
~/.openclaw/skills/agentic-loop-upgrade/scripts/verify.sh
```

See [SECURITY.md](./SECURITY.md) for the full audit document.

## āš ļø Notes

- **Token overhead**: Planning and reflection use additional tokens (configurable via orchestrator model selection)
- **Easy rollback**: One click to switch back to Core Loop
- **Checkpoints**: Long tasks can be resumed if interrupted

## šŸ“š Documentation

- [SKILL.md](./SKILL.md) - Full technical documentation
- [SECURITY.md](./SECURITY.md) - Security & trust audit document
- [INSTRUCTIONS.md](./INSTRUCTIONS.md) - Integration guide for agents
- [references/](./references/) - Component documentation

## šŸ”— Links

- [OpenClaw](https://github.com/openclaw/openclaw)
- [Source Code](https://github.com/openclaw/skill-agentic-loop-upgrade)
- [ClawHub](https://clawhub.com/skills/agentic-loop-upgrade)
- [Documentation](https://docs.openclaw.ai)
- [Discord](https://discord.com/invite/clawd)

## šŸ“„ License

MIT
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall