Download the PHP package voku/agent-loop without Composer

Agent Loop

A governed coding-agent workflow for PHP repositories.

voku/agent-loop is the umbrella package for a local, auditable agentic-coding loop. It combines target-aware edit orchestration, task selection, working sessions, recall compilation, gated workflow orchestration, verification, deterministic review, learning capture, memory promotion, and repo setup/diagnostics behind one CLI:

Quick start

Install the package in an existing PHP project:

For an exact method-scoped change, build the semantic map, compile bounded source-backed recall, and prepare one execution bundle directly:

When the project's PHPStan semantic export needs more than its PHP default, pass an explicit bounded value such as --phpstan-memory-limit=512M to edit; the value is forwarded only to the map-building child process and recorded in the execution request.

For a surgical replacement, add repeatable --focus literals. edit records them and asks the local map/recall stack for short source windows around each match, so the external runner receives the evidence it needs without first spending tool calls rediscovering a large target method. Focus mode omits optional caller/dependency/test slices; use it only when the requested change is local to the matched expression. If a literal is not found, the complete target method is retained rather than silently omitting context.

The default stdout runner does not execute another agent. It writes request.json, prompt.md, execution.json, agent-result.json, the recall artifacts, and any runner evidence under .agent-loop/edit/<task-id>/.

agent-result.json is the answer sheet a verifier grades. The orchestrator fills in what it observed itself - the verification_plan_sha256 the edit is bound to, the changed_files diffed from a working-tree snapshot taken before the runner ran, and the commands it actually invoked with their exit codes - and seeds one empty slot per probe and checklist item from verification-plan.json, so an unanswered probe is visibly unanswered rather than missing. The agent fills those slots; it does not write the rest.

Verify it with:

That loads the plan, the verifier-owned key, the answer sheet and execution.json, refuses to grade artifacts whose bindings do not line up (exit 2), grades the probe answers against the key, resolves the checklist evidence, runs the declared objective gates, and writes verification-result.json. Gates that shell out report not_run unless --run-commands is passed, and a required gate that did not run fails the verification rather than passing it. The post-edit map is refreshed into a bundle-local copy, never the shared index. Exit codes: 0 verified, 1 failed, 2 unreadable bundle. This is not agent-loop verify, which checks cross-package consistency and drift.

It deliberately carries no expected answers, scores, verdicts or generated learnings. Those belong to the verifier: a result file that can grade itself is not evidence. changed_files_source distinguishes a genuinely empty diff (git_status_diff) from a repository the snapshot could not read (unavailable). Use --runner=command with an explicit executable and repeated --runner-arg values for a harness that consumes the compiled prompt on stdin. No shell command is constructed.

For an exact one-for-one literal replacement inside a resolved PHP method, prefer --runner=auto with both replacement literals. It selects the scoped mechanical runner, which requires exactly one match inside that method, verifies the map hash immediately before writing, runs php -l, reverts on lint failure, and records 0 model input tokens and tool calls in execution.json. Identical literals in another method are left unchanged, unlike a file-wide sed replacement. auto without replacement proof writes an escalation_required bundle and never launches a model; choose --runner=command explicitly only when PHP judgment is required.

Create the minimal local workflow structure and a clearly marked example task:

Inspect the generated card:

Plan and approve it. This example uses composer.json, which is already in a Composer project; replace it with the real file you intend to change.

Generate the bounded context for your coding agent:

After making the change, record its validation and continue through review and closure. See Your first governed task.

The goal is not to make a coding agent "remember everything".

The goal is to make it work in a controlled loop where useful context is selected, work is verified, findings are reviewed, and only approved knowledge becomes durable guidance.

Why this exists

Coding agents are useful, but they are also very good at three bad habits:

1. forgetting project-specific rules,
2. repeating old mistakes,
3. stuffing too much irrelevant context into the prompt.

agent-loop gives them a process.

Instead of asking an agent to "just fix this", you run a loop:

That last part matters.

Not every observation should become memory. Some findings are temporary, accidental, stale, or just wrong. A useful agent workflow needs both learning and forgetting.

Review accumulated guidance

Run the deterministic maintenance cycle through the unified CLI; it delegates knowledge evaluation to voku/agent-learning and keeps operator output under the ignored .agent-loop/ work area instead of project documentation:

The command validates immutable learning evidence, reports coverage gaps and a small review queue, and exits successfully when candidates need human review. Use --write-candidates only to create reviewable proposal records; it never approves, applies, retires, or rewrites durable guidance.

What agent-loop is

agent-loop is:

• a unified CLI for several focused agent packages,
• a workflow boundary around coding-agent sessions, with a gated plan/approve/start/status/report/close orchestration layer on top,
• a way to make project knowledge auditable,
• a human-in-the-loop process for promoting durable guidance,
• a local-first toolchain for agentic coding work, including its own setup diagnostics (init).

What agent-loop is not

agent-loop is not:

• an autonomous coding platform,
• an LLM provider,
• a vector database,
• a hidden memory system,
• a replacement for tests or static analysis,
• a place to dump every transcript forever.

If everything becomes memory, memory becomes landfill.

Package architecture

agent-loop delegates to specialized packages instead of rebuilding everything in one large tool.

Each dependency package has one job:

The table is the current executable surface. init scaffold creates only the local workflow directories, a small .agent-loop/init.json, and a DEMO-1 board card/task; it never writes over an existing file.

The loop

A typical workflow looks like this. The gated workflow commands are the preferred entry and exit points; the lower-level package commands they wrap stay available directly when you need finer control.

Pick the work:

Plan and approve the governed task context. Planning starts session working memory and records a candidate work brief. Approval seals that exact revision and compiles recall from it:

For exact method-scoped work, agent-loop edit now connects the semantic map and target-aware recall compiler directly. Its safe default prepares the execution bundle without launching an external agent; the generic command runner can pass prompt.md through stdin to an explicitly configured harness.

The broader governed workflow remains the preferred lifecycle for approved board work, session state, review, verification, and closure. Direct recall compile still writes artifacts for manual or harness ingestion.

For behavioral work, the optional repeatable --behavior-anchor records the real request, runtime, consumer, data, or integration seam that needs evidence. It is intentionally optional for documentation-only or static-only tasks. The compiled L2 briefing also distinguishes VERIFIED, INFERRED, ASSUMED, BLOCKED, and CONTRADICTED claims; agent confidence and peer feedback do not become evidence without a current repository, history, or safe-runtime check.

Run the deterministic blind-spot review before closing:

Verify cross-package consistency, then close the task — workflow close requires an approved current work brief, recall metadata, a blind-spot review report, and a passing agent-loop verify before it will let a task go to done:

Capture what the session discovered:

Finally, review durable memory candidates:

Human-in-the-loop by design

agent-loop deliberately keeps humans in the loop.

A coding agent may collect findings, suggest rules, and propose new guidance. But it should not silently rewrite the project's long-term memory, and it should not close its own task as done without evidence.

Durable guidance should be reviewed because project rules have consequences:

That final step needs a human decision.

The agent can notice the pattern. workflow close can require the evidence exists. The project owner decides whether it becomes a rule.

Learning vs constraints

There are different kinds of knowledge:

The most important output is often not "more memory".

It is a sharper constraint:

Hard constraints prevent repeated mistakes.

Soft notes merely hope the agent behaves. Hope is not a strategy, despite its popularity.

Forgetting is part of the system

A good agent workflow needs explicit rejection.

Some observations should not survive:

• one-off workarounds,
• stale debugging notes,
• accidental implementation details,
• failed ideas,
• project-specific exceptions that should not become general rules.

agent-loop treats this as part of governance.

Forgetting bad or irrelevant context is often more valuable than learning another vague rule.

CLI overview

Available namespaces:

Run agent-loop <namespace> help (or --help) for a namespace's own command list.

Board

Reads work items from local Markdown card files under todo/cards/*.md (one file per card), with todo/board.md holding board metadata (project prefix, done count). This works fully standalone — no tracker host, credentials, or network access required. todo/jira/ and a root TODO.md remains an optional rendered board projection when present.

Only board external-sync talks to an external issue tracker, and only when the invocation passes --provider-class=<FQCN> pointing at your own voku\AgentKanban\ExternalIssue\ExternalIssueProvider implementation (see "Programmatic usage" below) — nothing is wired in by default. Every other board command works from the local Markdown cards alone.

Edit

edit rejects missing, ambiguous, conflicted, or stale targets before it publishes an execution bundle. Missing or stale maps are rebuilt once unless --no-rebuild-map is supplied. The default runner is deliberately non-executing; --print-prompt prints the compiled prompt, while --runner=command --runner-command=... --runner-arg=... invokes one executable without a shell and stores stdout, stderr, and the exit code as evidence. Use --phpstan-memory-limit=512M (or a project-appropriate positive value) when rebuilding the semantic map needs more memory than the PHP default. Use repeatable --focus=TEXT for narrow, literal replacements; it keeps a small local source window around each match for the runner and falls back to the complete target method if no match is found. For a one-for-one literal replacement with no judgment call, prefer --runner=auto --replace-old=... --replace-new=...; it selects mechanical execution, performs no model invocation, and leaves auditable lint evidence. Without both literals, auto writes escalation_required rather than silently invoking a model; select --runner=command explicitly for that escalation.

RTK is an optional outer-shell output filter, not an edit runner. It can reduce the output an agent has to read without changing the deterministic edit route:

agent-loop init tools --refresh records whether rtk is reachable in PATH. When an agent runs PHP inside a container, invoke RTK outside the container (rtk docker compose exec …); do not assume a nested rtk test docker compose exec … preserves the container working directory. The package-owned historical replay test copies a public agent-loop parent blob to a temporary root, replays a one-line fix through auto, and compares the result with both the committed blob and a guarded Linux replacement baseline.

Map

Builds a compact generated symbol index under .agent-map/ by default. Use it to choose the smallest useful source read; it is optional and never becomes another durable memory store. Build once, then keep it current with map refresh, which re-analyses only changed or new files.

Session

Tracks per-task working memory and session plans. Use this for active work state, not durable project memory.

Recall

Compiles a scoped briefing for the current task. The recall compiler should select relevant approved guidance, not dump every note the project ever had.

Workflow

workflow plan starts or reuses a session and writes a candidate work brief; it deliberately does not compile recall from unapproved scope. workflow approve records the actor and revision, then compiles recall from that sealed brief. When a typed board card and/or map index exist, it passes their stable fact projections too. When <learning-root>/recall-documents.json exists, it also passes that explicit, Git-tracked Skill/ADR manifest; it never scans all project Markdown files. It automatically uses infra/doc/agent-learning (or the legacy learning-root) when one exists; pass --learning-root only for a different location. Its --file values become the initial approved scope unless one or more explicit --scope values are supplied. workflow approve records the actor and revision that approved that candidate. A later plan revision must be approved again.

--tag LABEL on workflow plan (repeatable) records optional relevance labels on the work brief, independent of --scope paths. Recall then selects a fact when its path scope overlaps the task's files or it shares a tag with the task, so cross-cutting learnings/documents (e.g. identity, ldap) can be found for a task whose files live under an unrelated directory, regardless of how a given project lays out its codebase.

workflow start remains available when a host deliberately needs the lower level session-plus-recall step without work-brief orchestration.

workflow status prints read-only session, recall, and review state.

workflow context is the bounded working view for an agent: it reads the approved brief, session decision/checkpoint titles, selected recall guidance, required validation, and navigation facts from the recall bundle (falling back to .agent-map/ only for legacy outputs). It never recompiles recall or a map, embeds no source body, and prints [SKIP] plus explicit omission counts when an input or budget is absent.

workflow report is the bounded handoff view: it reports the current work brief and approval, supplied changed files that fall outside approved scope, revision-bound validation evidence, recall outcome state, review state, task-associated learning counts, and any accepted risk. It is read-only and never runs git; pass each observed path with --changed-file (or use --format json for CI).

workflow close is a gated wrapper around session close. It requires an approved current work brief, passing validation evidence for its exact revision, recall metadata and explicit outcomes for selected guidance, a blind-spot review report, an explicit session learning decision, and a passing agent-loop verify before closing a task as done.

Record completion evidence through the session owner; it remains auditable but does not become durable guidance by itself:

Existing agent-loop session close remains unchanged.

Workflow commands do not approve code, do not approve durable learning, and do not call an LLM.

Accepted risk is explicit and written to disk:

Both are required: an override without a named owner is an anonymous decision, which is the thing the record exists to prevent. The record names who overrode it, why, and every gate that was failing at that moment - including which validation evidence was missing - in .agent-loop/risks/<task-id>.accepted-risk.md and a machine-readable .json beside it.

Verify

The one command that looks across board, session, recall, and learning state at once. Checks each print [OK], [SKIP], or [FAIL] and skip themselves when their inputs are absent, so the command stays meaningful for a repo that only wires up part of the stack. Pass --strict to fail instead of skip when the tasks/ or session_plan/ baseline is missing entirely. Pass --task-id=ID to scope the tasks/sessions/recall checks to one task, so an unrelated task's stale recall draft or broken task file doesn't fail the run — workflow close passes its own task id this way automatically. Package delegates, board, and the learning root stay repo-wide checks either way.

Review

Writes deterministic Markdown/JSON blind-spot reports plus an L2 review prompt under <recall-root>/<task-id>/reviews/, using task, session, and recall artifacts as prompt context. review code generates a focused L2 code-review prompt (purpose mismatch, contracts, invariants, edge cases, security, test gaps). Neither command approves code or calls an LLM itself — the generated prompt is for a human or harness to pass to a receiving LLM.

Learn

Captures and evaluates findings, proposals, and learning history.

Memory

Reports which MEMORY.md rows look ready for promotion; it never edits MEMORY.md itself. Promotion stays a manual edit by whoever owns that file.

Init

Diagnoses local setup, prints reviewed install plans (ripgrep, RTK, Caveman), validates repo-managed asset definitions, and syncs repo-managed skills/subagents/hooks into client target directories. It does not affect workflow close, does not call an LLM, and does not install remote tools.

init doctor/init status are read-only and never write files. init tools is the one exception: it probes whether rg, git, php, composer, and docker are reachable in PATH and whether an agent-map index exists, then caches the result to .agent-loop/tool-inventory.json (gitignore this path) so an agent does not have to re-probe availability at the start of every session. Re-probes automatically once the cache passes --max-age (default 3600s), or immediately with --refresh.

Installation

This installs voku/agent-kanban, voku/agent-session, voku/agent-map, voku/agent-recall-compiler, and voku/agent-learning as dependencies and exposes vendor/bin/agent-loop.

Programmatic usage

Start with the smallest useful loop — one task, one session, one compiled briefing. The high-level workflow command is preferred for creating and closing the governed task context:

The lower-level equivalent of workflow start is still available when you need direct package commands:

session start prints its own generated session id (date-prefixed, e.g. 2025-01-15-abc-123) on its first line. You don't need to capture it: session record/checkpoint/close/claim/show/brief also accept the task id you started the session with — agent-loop resolves it to the matching session id before delegating. The session id still works directly if you have it (e.g. from a list of multiple sessions for the same task). Likewise, recall compile --task ABC-123 without --output-dir writes to <recall-root>/ABC-123/ automatically (RecallOutputRoot::resolve(): paths.recall_root from .agent-loop/init.json if configured, else infra/doc/agent-learning/recall-output when that directory exists, else recall/), where agent-loop verify's recall-coverage check expects to find it; pass --output-dir explicitly only to override that default. See examples/basic-loop for this full sequence run against a tiny fake task with real captured output.

recall compile only writes files (system.md, validation-plan.md, recall-log.draft.json, meta.json) under <recall-root>/<task-id>/ (see RecallOutputRoot::resolve() above); it does not inject them into a running coding agent itself. After a successful compile, agent-loop prints a reminder of this:

Whatever drives the agent (a human, an editor integration, or voku/housekeeping) is responsible for reading system.md and validation-plan.md and feeding them into the actual prompt/context — that wiring is host-specific and out of scope for this package. agent-loop verify's recall check only confirms a briefing was compiled and is not stale; it cannot confirm anything actually read it.

Add the board once you have more than one task in flight, and the learning loop once you want findings to survive past a single session:

Exact available commands

Every command below is real and was verified against this repository's installed dependencies (composer require'd versions); none of it is aspirational. Run agent-loop <namespace> help (or --help) for a namespace's own usage.

agent-loop map: PHP symbol maps for smaller reads

map delegates to voku/agent-map. It builds and queries a compact PHP symbol index so agents can find the right files/classes/methods before reading large file ranges. It does not store source code, call an LLM, own durable learning, or replace PHPStan.

When called through agent-loop, map build and map refresh default --root and --out to the dispatcher root (<root>/.agent-map/php-symbols.json) unless the caller passes explicit values. Every command except build defaults --index to that same root-local index. All normal agent-map options still work:

Prefer directory scopes for --paths: PHPStan disables its result cache when it is handed individual files, which turns every rebuild into a cold rebuild. With directories, map refresh after an ordinary branch switch costs seconds.

Use map output to choose the smallest useful next read. Do not dump .agent-map/php-symbols.json into prompts.

agent-loop board external-sync is the only board command that needs a caller-provided ExternalIssueProvider implementation. The bare binary does not ship one because tracker clients are host-specific; every other board command works against local Markdown cards without it.

agent-loop review blindspots: deterministic review boundary

Run this after implementation validation and before closing the task. It writes deterministic Markdown/JSON reports plus an L2 blind-spot analysis prompt under <recall-root>/<task-id>/reviews/, using task, session, and recall artifacts from voku/agent-recall-compiler as prompt context. It warns when session notes do not show that review blindspots itself was checked. Review reports and generated prompts do not approve code. Review reports do not approve durable learning. The CLI does not call an LLM directly; the generated L2 prompt is for a human or harness to pass to a receiving LLM. Human review remains required.

L2 code-review prompt

Generates <recall-root>/<task-id>/reviews/<task-id>.code.prompt.md, an L2 code-review prompt focused on purpose mismatch, contracts, invariants, edge cases, security, and test gaps. This command is delegated to voku/agent-recall-compiler; agent-loop only defaults --output-dir to RecallOutputRoot::resolve()'s recall root so it fits the standard workflow. The prompt is intended for a receiving LLM or harness; the CLI itself does not call an LLM.

Learning boundary: findings are not durable memory

The workflow/review spine can generate evidence for learning, but it does not promote durable memory. Findings and learning candidates remain review inputs; only reviewed decisions become durable guidance. Use agent-loop memory review --file MEMORY.md as the human promotion boundary for repositories that maintain a MEMORY.md queue. See docs/workflow/learning-boundary.md for the detailed boundary.

agent-loop verify: the safety net

Every other namespace delegates outward and stops there. verify is the one command that looks across board, session, recall, and learning state at once and answers: is this repo's agent workflow state internally consistent?

Checks, each of which prints [OK], [SKIP], or [FAIL] and skips itself when its inputs are absent (so the command stays meaningful for a repo that only wires up part of the stack):

• package delegates — board/learn/map/recall/session classes are installed and resolve
• tasks — every *.md file under tasks/ parses (non-empty, has a heading)
• board — typed kanban board verification (delegated to voku/agent-kanban)
• sessions — every non-closed session under session_plan/ points to a known task id
• recall — every active session has a compiled briefing, and every compiled meta.json's recorded system.md/validation-plan.md hashes still match the files on disk (catches those two edited or regenerated out of band; recall-log.draft.json and feedback-assessment.draft.json are excluded from this check since they're meant to be hand-edited after compile)
• learning root — findings, proposals, and decision/outcome history validate

Run agent-loop verify --help for the override flags (--tasks-root, --sessions-root, --recall-root, --learning-root). agent-loop board:verify remains available as the narrower, board-only check this command used to be.

--strict: turn baseline skips into failures

By default, a missing input is reported as [SKIP] and does not fail the command — useful for a repo that only wires up part of the stack. Pass --strict to fail instead when tasks/ or session_plan/ is missing entirely:

tasks/ and session_plan/ are the baseline this command exists to confirm — a task to work on, and a session tracking it. The board and learning root stay skippable even under --strict: both are documented, opt-in additions on top of that baseline, not something every repo using agent-loop is expected to have set up. examples/basic-loop fails --strict before step 2 (session_plan/ doesn't exist yet), then passes it from step 5 onward — the same point where its own verify (without --strict) already passes, since by then a session and its recall briefing both exist.

What agent-loop deliberately does not do

agent-loop is not the learning engine. agent-loop is not the session store. agent-loop is not the recall compiler. agent-loop is the command surface.

Concretely, agent-loop:

• holds no working memory of its own — sessions live in voku/agent-session's files, not in this package
• makes no decisions about what counts as a durable lesson — that judgment lives in voku/agent-learning
• selects no context for a prompt — selection logic lives in voku/agent-recall-compiler
• owns no repository symbol map — map state lives in the generated .agent-map/php-symbols.json owned by voku/agent-map
• owns no board data — board state lives in whatever Markdown/Jira source voku/agent-kanban reads
• adds no scheduler, hidden state machine, or plugin lifecycle — voku/housekeeping is the runner; this is just the loop

If a feature needs new durable state, it belongs in one of the focused packages, not in agent-loop. The moment this wrapper starts hiding state of its own, it has become the second source of truth this whole stack was built to avoid.

Review boundaries and safety contracts

agent-loop coordinates the loop. It does not approve code, approve learning, or replace human review.

Concretely:

• it does not auto-commit, auto-merge, or push anything — every command it runs is the one you typed, with arguments resolved or defaulted as documented above, nothing more
• it does not approve code changes — that remains whatever review process (human or otherwise) already gates changes outside this tool
• it does not silently promote findings into durable memory. learn proposal-approve --by ACTOR <id>, proposal-reject, and proposal-mark-applied are voku/agent-learning's own human-actor gate (each requires an explicit --by actor) on the candidate → approved → applied lifecycle; agent-loop delegates to that command verbatim and adds no auto-approval path of its own
• agent-loop memory review is read-only: it reports which MEMORY.md rows look ready for promotion (see src/MemoryPromotionAnalyzer.php); it never edits MEMORY.md itself. Promotion stays a manual edit by whoever owns that file
• agent-loop verify only reports [OK]/[SKIP]/[FAIL] on existing state; it never repairs drift it finds

If a workflow needs an automated approval or auto-promotion path, that is a deliberate, separately-reviewed change to the owning package (voku/agent-learning for proposals, the host application for MEMORY.md), not something to add to this wrapper.

Programmatic use (host wiring)

Hosts that need custom integrations, for example Jira, implement their own ExternalIssueProvider and pass its class to board external-sync:

voku\AgentKanban\Cli\CliApplication instantiates --provider-class with a no-argument constructor, so your adapter should read its own configuration (base URL, token, project key) from environment variables or your own config file inside its own constructor.

The default binary does not ship a Jira client because Jira clients are host-specific.

That is intentional. The package should not pretend your company's Jira setup is universal. Software has enough lies already.

Scheduled execution

agent-loop is the workflow CLI.

If you want scheduled maintenance, use a runner such as voku/housekeeping to call selected agent-loop commands from cron or another scheduler.

Example scheduled jobs could include:

Keep scheduled jobs conservative.

Agents may suggest. Humans approve.

Suggested repository layout

A repository using agent-loop may keep agent workflow files under infra/doc/agent-learning:

Example workflow files:

The exact structure depends on the consuming packages and project conventions.

Token hygiene

agent-loop is part of a broader token-hygiene strategy.

It reduces prompt waste by making context selective:

The point is not to compress everything.

The point is to avoid loading irrelevant things in the first place.

Example: from finding to constraint

A session discovers this:

A proposal is created:

A human reviews it.

If accepted, it may become durable guidance:

If rejected, it is recorded as rejected guidance instead of being silently forgotten or accidentally rediscovered next week like a cursed treasure.

Development

Install dependencies:

Run the test suite:

Run PHPStan:

Run all CI checks:

composer ci runs:

Design principles

agent-loop follows a few boring but useful rules:

• keep packages focused,
• keep generated context reviewable,
• prefer explicit files over hidden state,
• treat durable memory as a reviewed artifact,
• reject bad learnings instead of accumulating noise,
• keep humans in control of project rules,
• make agent work verifiable.

Boring is good here.

Boring tools fail less dramatically.

License

MIT. See LICENSE.