Docs/Supervisor & In-Agent Skills

Documentation

Complete guide to LoopGoal: an autonomous development loop protocol and local supervisor for AI coding agents. Keeps agents working toward user-defined goals through small, verifiable iterations.

Overview

Autonomous coding assistants frequently fail on large prompts because they attempt sweeping, unverified modifications across multiple packages simultaneously. LoopGoal eliminates hallucinations and broken states by constraining the execution model to an empirical single-improvement loop:

Observe → Select → Execute → Verify → Commit → Repeat

Empirical Inventory

Scans 100% of workspace files via git ls-files before touching code.

Verification Gate

Changes only commit if configured tests pass with exit code 0.

Zero Remote Push

Operates 100% locally. Commits are never pushed to remotes automatically.

Installation

Choose your preferred installation method. You can install in-agent skills or the native Go supervisor CLI:

Installs LoopGoal into your active AI agent environment:

npx skills add prasangapokharel/loopGoal

Supports Antigravity, Claude Code, Cursor, Codex, and OpenCode seamlessly.

Two-Layer Architecture

LoopGoal is built around a clean two-layer model that separates in-agent prompt guidance from out-of-band OS process supervision:

Layer 1: Protocol & In-Agent Skills

In-Agent Execution

Skills and instructions (SKILL.md, CLAUDE.md, .cursorrules) injected directly into agent context. Tells the agent how to reason, formulate bounded tasks, and respect project rules.

Triggered by chat slash commands: /loopgoal [goal]
Operates inside active IDE chats (Antigravity, Claude, Cursor)

Layer 2: Go CLI Supervisor

External Orchestration

A standalone Go daemon/CLI (cmd/loopgoal) that runs outside the AI agent. It invokes the agent via sub-processes, executes test verification commands, parses diffs, and manages commits.

Invoked from terminal: loopgoal run --goal "..."
Zero AI vendor lock-in; works with any CLI agent

Supported Providers & Slash Commands

LoopGoal integrates with all major AI coding agents. Click to view installation instructions for each:

Google Antigravity

Native Skill

Installed to ~/.gemini/config/skills/loopgoal/SKILL.md.

/loopgoal [your target goal]

Claude Code

Slash Command

Configured in ~/.claude/commands/loopgoal.md.

/loopgoal [your target goal]

Cursor IDE

Rule File (.mdc)

Saved to .cursor/rules/loopgoal.mdc.

@loopgoal [your target goal]

OpenAI Codex / CLI

Supervisor Adapter

Executed via Go CLI supervisor with headless flag.

loopgoal run --agent codex

The 7-Step Protocol

Every iteration strictly follows these sequential gates:

Observe & Command Audit

Discovers 100% of workspace files using git ls-files. Loads project rules (AGENTS.md) and detects test runners.

Select Bounded Task

Isolates ONE small, verifiable improvement toward the overall goal. Rejects sweeping multi-file refactors.

Execute Improvement

Agent implements only the isolated change. Modifies zero unrelated code.

Empirical Verification

Executes configured verification commands (go test, pytest, npm test). Rejects natural language claims.

Inspect Diff

Audits git diff to verify all changes strictly match the intended task.

Atomic Commit

Creates a clean local commit with iteration metadata. Zero automatic remote push.

Save State & Repeat

Updates .loopgoal/state.json and repeats if iterations remain and goal is not yet achieved.

Supervisor CLI Reference

The Go binary provides autonomous orchestration commands from your terminal:

Run Autonomous Loop

loopgoal run --goal "Add typed AuthError to middleware" --limit 5

Zero-Trust Verification (Emits Commit Token)

loopgoal verify

Executes real test harnesses and creates .loopgoal/verified.token required to unlock git commits.

Single-Target Lock (Out-of-Scope Protection)

loopgoal select internal/auth.go -objective "Add typed errors"

Restricts iteration scope to one file. Unplanned edits to outside files are automatically rejected and rolled back.

Install Git Hard-Enforcement Hooks

loopgoal hook install

Installs pre-commit (blocks unverified commits) and pre-push (blocks unauthorized remote push) hooks.

Safe Working Tree Rollback

loopgoal rollback

Discards unverified changes and restores repository to the last clean verified commit.

Model Context Protocol (MCP) Server Mode

loopgoal mcp

Exposes native MCP tools (loopgoal_select_target, loopgoal_verify, loopgoal_commit, loopgoal_rollback) to Cursor and Claude.

Scan Workspace Inventory

loopgoal scan --depth 2

Smoke Test Adapters & Verifiers

loopgoal test --smoke

Configuration Reference

Configure project goals, external agent binaries, and verification commands in .loopgoal/config.yaml:

.loopgoal/config.yaml

goal: >
  Continuously improve this project with small, safe, production-quality changes.

agent:
  command: "codex" # or "opencode", "agy", "claude"
  args:
    - "--dangerously-skip-permissions"

verify:
  - "go test ./..." # or "npm test", "pytest"

limits:
  iterations: 20
  max_retries: 3

Safety Guarantees

Zero Remote Push Lock

LoopGoal will never push commits to a remote Git repository unless explicitly authorized. All commits remain on your local working branch.

Working Tree Protection

Detects uncommitted human edits prior to iteration start. Refuses to overwrite or corrupt uncommitted developer files.