Agent Loop (`voku/agent-loop`)

Name: agent-loop
Author: voku

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

You have work to do
        |
        v
+------------------+
|    Agent Loop    |
|                  |
| keeps the task,  |
| context and      |
| evidence coherent|
+--------+---------+
         |
         v
+------------------+
|   Coding agent   |
|                  |
| understands,     |
| changes, tests   |
+--------+---------+
         |
         v
+------------------+
|  Prove the work  |
|                  |
| tests · analysis |
| review · evidence|
+--------+---------+
         |
    +----+----+
    |         |
 not done    done
    |         |
    +-- retry |
              v
       keep useful lessons
              |
              v
       better future work

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?

Without it	With Agent Loop
A new chat means reconstructing the task	Approved task intent and progress survive the conversation
The agent decides what to do next from prose and memory	The workflow exposes the current next step
Large repositories become giant prompts	Only relevant repository context is selected
“Looks good” can quietly become “done”	Tests, analysis and review remain explicit evidence
Useful lessons disappear after one task	Proven lessons can inform later work
Instructions keep growing forever	Repeated objective lessons can become tests, static rules or other deterministic checks
Your workflow becomes tied to one model vendor	The workflow stays local and provider-independent

Install

composer require --dev voku/agent-loop

Requirements: PHP 8.3+ and Composer.

vendor/bin/agent-loop

Start a repository

Create the repository-local workflow scaffold:

vendor/bin/agent-loop init scaffold

Or create the tutorial board and task:

vendor/bin/agent-loop init scaffold --demo
vendor/bin/agent-loop board card show DEMO-1

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:

vendor/bin/agent-loop init install-assets --agent=all --dry-run
vendor/bin/agent-loop init install-assets --agent=all
vendor/bin/agent-loop init host-status --format=json

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, and Antigravity. Host-specific capabilities and limitations remain explicit.

The two lifecycle commands

For everyday use, the workflow stays deliberately small:

unplanned or existing task
  -> agent-loop enter <task-id>
  -> follow next_action_kind + next_action
  -> do the current work
  -> agent-loop finish <task-id>
  -> repeat until complete

Start or resume a durable task:

vendor/bin/agent-loop enter ABC-123 --format=json

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:

vendor/bin/agent-loop finish ABC-123 --format=json

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.

Concern	Package
Workflow and task authority	`agent-loop`
Git-native work items	`agent-kanban`
Temporary working memory and validation evidence	`agent-session`
Repository structure and code navigation	`agent-map`
Bounded task context and prompt construction material	`agent-recall-compiler`
Findings, precedent and durable learning	`agent-learning`
Reusable engineering and review skills	`agent-skills`

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

vendor/bin/agent-loop help
vendor/bin/agent-loop init doctor
vendor/bin/agent-loop init host-status --format=json
vendor/bin/agent-loop workflow status ABC-123 --format=json
vendor/bin/agent-loop map query SomeClass
vendor/bin/agent-loop verify --task-id=ABC-123

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:

vendor/bin/agent-loop learn capture \
  --task TEAM-123 \
  --by product-owner \
  --observation 'The expected approval step is not visible to a new contributor.' \
  --hypothesis 'Making that step explicit will prevent incomplete requests.' \
  --evidence 'Observed during a representative acceptance walkthrough.'

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:

vendor/bin/agent-loop learn finding-transition finding.2026-09-19.abc123 validated \
  --by reviewer \
  --conclusion 'The observation is reproducible and ready for Learning triage.'

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.

edit          governed edit preparation and execution
board         Git-native work items
session       temporary working memory and validation evidence
map           repository structure and code navigation
recall        bounded task context and outcome logging
learn         findings, proposals, constraints and learning history
verify        cross-package consistency checks
workflow      durable governed workflow orchestration
board:verify  board-only consistency checks
memory        MEMORY.md validation and review
review        deterministic review helpers
init          repository setup and managed agent assets

Documentation

Start here:

For contributors and deeper design evidence:

Development

composer install
composer test
composer phpstan
composer ci

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

License

MIT. See LICENSE.

Agent Loop (voku/agent-loop)