Download the PHP package voku/agent-loop without Composer

Agent Loop (voku/agent-loop)

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

Coding agents are already good at changing code. The harder problem is everything around that change: remembering what was agreed, keeping the work inside the right scope, giving the agent the context it actually needs, proving the result, and carrying useful lessons into the next task.

voku/agent-loop adds that workflow around the coding agent you already use.

How it works

Agent Loop does not replace the coding agent or your normal engineering tools. It keeps the work around them durable: what was requested, what is allowed, what context matters, what has been tried, and what evidence is needed before the task is done.

The chat can disappear; the task should not.

Useful experience can feed later tasks. When a lesson becomes stable and mechanically checkable, it can become a test, static-analysis rule, or another deterministic check instead of another prompt instruction.

The goal is not maximum automation. The goal is reliable agent work with less reconstruction, less hidden state, and better evidence.

Why Agent Loop?

Install

Requirements: PHP 8.3+ and Composer.

Start a repository

Create the repository-local workflow scaffold:

Or create the tutorial board and task:

Then follow Your first governed task.

For supported coding hosts, package-owned skills and roles can be projected from the installed Composer package without downloading remote agent code:

install-assets --dry-run shows the exact managed asset changes the current project would receive without writing them. Detailed composition and host behavior live in Agent assets and host integration.

Portable assets are available for Codex, Claude Code, OpenCode, Copilot, Gemini CLI, Antigravity, and Cursor. Cursor projects the shared AGENTS.md router plus native .cursor/skills and .cursor/agents assets. Its repository shell authority policy uses a native .cursor/hooks.json beforeShellExecution guard with failClosed: true; unrelated project hooks are preserved. Cursor CLI policy and MCP authority coverage are separate and unclaimed. Cursor runtime auto-detection and live hook/read-only enforcement remain unverified, so use explicit --agent=cursor selection. Host-specific capabilities and limitations remain explicit.

The two lifecycle commands

For everyday use, the workflow stays deliberately small:

Start or resume a durable task:

For an unplanned task, enter is the front door before planning or approval. Follow the returned next_action_kind and next_action rather than inventing a sequence: command_template is model-owned work to complete from the request and repository evidence; decision_required is a genuine human-authority decision.

After implementation or another requested action:

finish reconciles current evidence and returns the next authoritative step. Repeat until the lifecycle reports completion.

You do not need to memorize the internal package order or rebuild a phase machine inside the prompt. See the lifecycle contract when you want the exact ownership model.

What makes it different?

The task survives the chat

Approved task intent and workflow state live outside the conversation. A later agent can resume from current repository evidence instead of trusting a summary of what somebody remembers happening.

The agent gets less context, but better context

agent-map can locate the relevant PHP structure and agent-recall-compiler can assemble task-specific context and prior knowledge. The agent reads what it actually needs instead of swallowing the repository.

Evidence beats confidence

Tests, static analysis, review artifacts, exact diffs, and recorded owner state remain the evidence. An agent sounding certain is not a validation strategy.

Useful experience can improve later work

agent-learning records evidence-backed observations and precedent. A useful lesson can inform a future task; repeated objective lessons can eventually become tests, PHPStan rules, fixers, typed APIs, or other deterministic constraints.

Once code or tooling owns the rule, obsolete prompt instructions can disappear again instead of accumulating forever.

Engineering judgment stays engineering judgment

agent-loop governs workflow authority and evidence. It does not turn every engineering task into “make the smallest diff”. A surgical fix can stay surgical; a broader feature or ownership correction can use the coherent solution the task actually requires.

Under the hood

You do not need to understand every package to use Agent Loop. They exist so each kind of information has one clear owner instead of one giant agent framework quietly owning everything.

Optional surfaces:

• agent-ui provides a local human control plane.
• agent-loop-runner provides an optional execution plane for isolated coding-host runs.

Boundaries

agent-loop deliberately does not:

• call an LLM by itself;
• auto-commit, auto-push, or auto-merge;
• silently invent human approval or risk acceptance;
• replace tests, PHPStan, code review, or repository-native tools;
• treat generated Map output as source evidence;
• turn every observation into durable memory;
• make hooks a correctness or security boundary;
• require one particular coding-agent provider.

The workflow is local-first and auditable through files, Git, and executable owner contracts.

Useful commands

The CLI is the executable reference. Detailed specialist commands remain available when the current task needs them; their existence does not make them mandatory workflow phases.

Capture a human Finding

Developers, product owners, and testers can record a plain evidence-backed observation without creating a Session or shaping Learning storage JSON:

The command returns an owner-created candidate Finding with validation_status=unverified. It is not active guidance and cannot be promoted directly. A named reviewer must first record a conclusion through the Learning owner:

Only that explicit validation makes the Finding eligible for the existing classification, Dream, and proposal review paths; none of those paths promote guidance automatically.

CLI namespaces

The stable command families are kept intentionally concise here; use vendor/bin/agent-loop help or <namespace> help for the executable details.

Documentation

Start here:

• Your first governed task
• Cross-package lifecycle and ownership
• Agent assets and host integration
• Learning and durable-memory boundary
• Pre-1.0 compatibility and durable-state contract

For contributors and deeper design evidence:

• Real-issue acceptance model
• First-party discipline dogfood
• Third-party mechanism mapping and notices

Development

Never report a command as passed unless it actually ran and its exit code was observed.

License

MIT. See LICENSE.