Download the PHP package voku/agent-loop without Composer

Agent Loop (voku/agent-loop)

agent-loop is one boring CLI for coding-agent DX. It does not think, decide, or remember anything itself — it routes a stable set of commands to the packages that do.

The problem it solves

A realistic coding-agent workflow needs a board to pick work from, a session to hold working memory while a task is in progress, a compiler that selects relevant context instead of dumping everything into the prompt, and a learning loop that turns findings into durable rules without overreacting to noise. Each of those is its own focused package. Wiring them by hand means a different vendor/bin/... invocation per concern, which nobody — human or agent — keeps straight across a long session.

agent-loop exists only to remove that friction: one Composer-installed PHP CLI, one stable command vocabulary, zero shared state of its own.

Package map

Board: local Markdown first, Jira sync optional

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 Jira host, credentials, or network access required. todo/cards/*.md is the preferred local card path. todo/jira/ and root TODO.md remain supported fallback inputs: voku/agent-kanban checks todo/cards/ first, falls back to todo/jira/, and then falls back further to reading a single TODO.md at the project root (voku/agent-kanban's own fallback, not something agent-loop adds).

Only board jira-sync talks to Jira, and only once the host application constructs the Dispatcher with its own JiraIssueProvider (see "Programmatic use" below) — the bare bin/agent-loop wires none. Every other board command (summary, render, lane, next-pull, ticket, context, brief) works from the local Markdown cards alone.

agent-loop workflow: start, inspect, and close a governed task

workflow start wraps session start and recall compile.

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

workflow close is a gated wrapper around session close. It requires recall metadata, a blind-spot review report, and a passing agent-loop verify before closing a task as done.

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:

Accepted risk writes .agent-loop/risks/<task-id>.accepted-risk.md.

Requirements

Installation

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

Basic workflow

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 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/ABC-123/ automatically, 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/<task-id>/; 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 board jira-sync needs a JiraIssueProvider; it is the only board command that does. The bare binary does not wire one (Jira clients are host-specific) — see "Programmatic use" below. Every other board command works against the 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 .agent-recall/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 .agent-recall/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 recall/<task-id> so it fits the standard workflow. The prompt is intended for a receiving LLM or harness; the CLI itself does not call an LLM.

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/recall/session classes are installed and resolve
• tasks — every *.md file under tasks/ parses (non-empty, has a heading)
• board — TODO.md kanban board projection (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 recall/<task>/meta.json output hash still matches the file on disk (catches a briefing edited or regenerated out of band)
• 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. board (TODO.md) and the learning root stay skippable even under --strict: both are documented, opt-in additions on top of that baseline (see "Board: local Markdown first, Jira sync optional" above, and the learning loop in "Basic workflow"), 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 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 already have a Jira client wire it once and reuse the whole CLI:

That single wrapper replaces per-library glue scripts: every board/verify/session/recall/learn/memory command flows through it.

Auto-running it on a schedule

voku/agent-loop is the loop; voku/housekeeping is the runner. Install Housekeeping in its own checkout, point it at your target repository, and let it invoke agent-loop commands (board refinement, verification, recall, …) from cron in safe patch mode.

Development

tests/fixtures/basic-loop is a minimal end-to-end fixture (SmokeLoopTest) proving the orchestration shape: a task file exists, a session starts against it, recall compiles a briefing, learn validates the root, and agent-loop verify reports no drift — then fails on purpose once a briefing goes missing or gets edited out of band. examples/basic-loop walks through the same shape by hand, with real command output, for reading or running yourself.

License

MIT — see LICENSE.