#Agent Loop (voku/agent-loop)

Keep coding-agent work moving without losing the task, guessing what comes next, or calling something done without evidence.

agent-loop is a local-first PHP workflow kernel for coding agents. It gives agents and developers a shared, checkable way to run tasks: what to do, what may be touched, what evidence proves it, and how lessons learned from one task improve future tasks.

---

#The Core Philosophy: Why a Governed Workflow?

#1. Workflow Tokens Buy Handover Resilience

Running a governed workflow uses slightly more tokens upfront than throwing raw prompts into a chat. In return, the task survives the chat.

• If an agent context window runs out, the model hallucinates, or the session dies, the work is never lost.
• You can hand over the task seamlessly: start in Claude Code, hand off to OpenAI Codex, have GitHub Copilot inspect it, or let a human engineer pick up exactly where the agent stopped.
• The state, approved scope boundary, and validation evidence live as versioned artifacts in your Git repository—not inside volatile LLM conversational memory.

#2. Multi-Agent Collaboration on Kanban Tasks

Different coding agents can work on the same project at the same time on different Kanban tasks.

• agent-kanban stores task items as Git-native Markdown files (docs/kanban/*.md) with deterministic revision hashes.
• Agent A can tackle a refactoring card while Agent B works on a bugfix card.
• Because boundaries and scope whitelists are enforced per task, agents do not step on each other's toes or pollute each other's context.

#3. Findings → Learnings: Project Intelligence That Compounds

After every task run, review observations and lint diagnostics become structured findings.

• Repeated findings synthesize into corroborated proposals.
• An engineering owner approves them into durable decisions.
• Each run makes the development process better and more tailored for the specific project.

#4. Deterministic Checks Reduce Tokens Over Time

When a project learning is approved, we don't dump another 500 words into a bloated system prompt or MEMORY.md landfill. Instead, we codify it into a deterministic check:

• A custom PHPStan rule
• A php-cs-fixer configuration
• A targeted unit/regression test
• A Git pre-commit or CI check

Deterministic checks cost 0 LLM prompt tokens. Over time, system prompts shrink, models receive sharper and smaller context, and the token cost per task decreases while repository quality increases deterministically.

---

#How It Works

Most coding-agent setups fail in one of two ways:

1. They stuff rules into giant prose prompts and hope the model remembers them.
2. They let the model mark its own homework ("I ran the tests and everything is green!").

agent-loop replaces both with two simple commands that run inside your project:

vendor/bin/agent-loop enter <task-id>
vendor/bin/agent-loop finish <task-id>

You have work to do
       │
       ▼
┌──────────────┐
│  Agent Loop  │ ◄─── task, rules, boundaries, and evidence live here
└──────┬───────┘
       │  enter: here is the task, the scope, and the exact next step
       ▼
┌──────────────┐
│ Coding agent │ ◄─── works only inside the approved boundary
└──────┬───────┘
       │  finish: prove the work with tests and git status
       ▼
┌──────────────┐      not done yet
│  Agent Loop  │ ──────────────────────► tells the agent what to fix
└──────┬───────┘
       │  done
       ▼
Keep useful lessons ──► deterministic checks ──► faster, cheaper future runs

---

#Without It vs. With Agent Loop

---

#What Makes It Different

1. The task survives the chat. Chat sessions are temporary; tasks are not. agent-loop keeps the task, its scope, and its progress in the repository so any agent (or human) can pick it up.
2. Multi-agent Kanban concurrency. Different agents can work on the same project simultaneously, each assigned to a separate card on the Git-native board.
3. The agent gets less context, but better context. Instead of feeding the model the whole repository or an endless memory log, agent-map and agent-recall-compiler select only the symbols and rules relevant to the task at hand.
4. Evidence beats confidence. A model saying "done" is not evidence. agent-loop checks recorded command runs, exit codes, and git diffs before allowing a task to finish.
5. Useful experience improves later work. Real findings from past tasks can be promoted to durable rules. The next time an agent touches related code, it gets the benefit of that experience automatically.
6. Deterministic checks reduce tokens over time. Approved learnings are translated into PHPStan rules, linters, and tests. Mechanical checks run for free, keeping prompt tokens low and quality reproducible.
7. Engineering judgment stays engineering judgment. Humans approve contracts, scope expansions, policy waivers, and durable rules. The kernel enforces the boundaries; the agent does the coding; you remain in control.

---

#What Agent Loop Does NOT Do

To maintain architectural integrity, agent-loop explicitly avoids doing things that belong elsewhere:

• It does not call LLM APIs by itself. Your coding host (Claude Code, Cursor, Copilot, Codex, etc.) handles model calls. agent-loop provides the workflow harness and guardrails.
• It does not auto-commit or push without approval. Git commits and pushes remain under human control or explicit host delegation.
• It does not invent human approval. Scope changes, policy waivers, and durable guidance promotions require an explicit human decision.
• It does not replace project-native tools. It does not reinvent PHPUnit, Pest, PHPStan, or PHP-CS-Fixer; it invokes them and checks their exit codes and evidence.
• It does not create a prompt landfill. It rejects the MEMORY.md pattern where unverified notes pile up unchecked.
• It is not vendor-locked. It projects instructions and assets for Codex, Claude Code, OpenCode, Copilot, Gemini CLI, and Antigravity.

---

#CLI Overview

#The Two Canonical Front Doors

For 90% of your daily workflow, you or your agent only need these two commands:

# 1. Enter the task: returns the current state and canonical next action
vendor/bin/agent-loop enter <task-id> --format=json

# 2. Finish the task: reconciles test evidence, git status, and quality gates
vendor/bin/agent-loop finish <task-id> --format=json

#Specialist Front Doors & Diagnostic Commands

When specialized or recovery workflows are needed:

---

#The 9 Focused Packages

agent-loop is an umbrella architecture composed of focused, single-responsibility packages:

---

#Supported Coding Hosts

agent-loop projects managed instructions, skills, and settings for the major coding-agent platforms:

# Install managed assets for all supported hosts
vendor/bin/agent-loop init install-assets --agent=all

• Codex (AGENTS.md, .agent-loop/codex/)
• Claude Code (CLAUDE.md, .claude/skills/)
• OpenCode (OPENCODE.md, .opencode/)
• GitHub Copilot (.github/copilot-instructions.md)
• Gemini CLI (GEMINI.md)
• Antigravity (.agent/skills/)

---

#Requirements & Installation

• PHP 8.3 or higher
• Composer
• Git repository

Install as a development dependency:

composer require --dev voku/agent-loop

Initialize your repository:

vendor/bin/agent-loop init setup
vendor/bin/agent-loop init doctor

---

#Interactive Sandbox & Documentation App

This repository contains the interactive Vite + React documentation app and Lifecycle Simulator:

npm install
npm run dev

Visit http://localhost:3000 to explore:

• Interactive Lifecycle Simulator: Test 10 distinct scenarios (Quick Fix, Happy Path, Bounded Repair, Scope Creep Refusal, Handover, Multi-Agent Board, Learning Promotion, etc.).
• The Connected Mental Model: Trace data flow across all 9 packages.
• Claim vs Evidence Inspector: See why cryptographic Git evidence beats natural-language chat claims.
• CLI Playbook: Full input/output schema for every lifecycle command.

---

#Quality Checks

Run before committing or submitting a pull request:

npm run lint
npm run build

#License

This project is open-source software licensed under the MIT License.