Agent Lifecycle Kit

Agent Lifecycle Kit (ALK) gives coding agents one delivery workflow from request to verified result. It turns a user task into a reviewed specification, an approved plan, bounded implementation work, review, and final proof, so agents finish the job instead of stopping at a patch.

The workflow is provider-neutral. Codex, Claude Code, Qwen Code, Goose, OpenInterpreter, Pi, Grok Build, or another CLI can follow the same lifecycle, while provider commands, model choice, and secret handling stay in adapters or host-local profiles.

Quick start

From a source checkout:

python -m pip install -e .
agent-lifecycle version
agent-lifecycle diagnose --no-install-plans
agent-lifecycle adapter validate --descriptor adapters/codex/adapter.descriptor.json

The official PyPI package supports Python 3.11-3.14. Install the exact release with python -m pip install agent-lifecycle-kit==1.51.0.

For a short walkthrough, use Quickstart and the Lifecycle cookbook. For structure and positioning, see System architecture and Project comparison. Russian documentation starts at Документация на русском.

What it gives you

• A finish-oriented lifecycle: plan, execute, review, and prove the result.
• One process for different CLIs: adapter-specific commands stay outside the core, and new adapters can be added without changing lifecycle schemas.
• Small-model friendly packets: compact context, clear next actions, and deterministic checks for local or cheaper models.
• Quality without overengineering: optional profiles turn on only when risk or task type requires them.
• Usage visibility: tokens, time, and resource counters are native; monetary cost is optional and only used when a metered host reports it.
• Read-only progress and managed sessions: host UIs can show lifecycle state, attested tokens and Git-style change counters; adapter task start accepts task text, Markdown or frozen run requests while preserving review/freeze boundaries.

Feature areas

Plan and execute

• Reviewed specification and plan flow before implementation starts.
• Deterministic task packets for splitting work across agents.
• Execution records capture completion checks, blockers, retries, and final proof; missing required evidence fails the step.
• Ready-made task templates cover bug fixes, idea-to-PR flow, PR review, merge-conflict repair, and release-readiness work.

Quality and proof

• Implementation audits compare results with the frozen plan and acceptance evidence.
• For explicit bug and regression repair, the optional Bug Forensics profile records reproduction, fingerprint, failure class, hypotheses, minimal patch, regression proof, and reusable recipes.
• Optional proof-integrity evidence for high-risk final proofs: stable findings, root-cause digests, fix-impact receipts, and hash chains.
• Cross-checks and runtime-policy receipts are opt-in controls; plans can require proof for an external system update before acceptance.
• Optional Review Mesh covers leader-draft review, parallel research synthesis and audit panels. The advisor can suggest a mode; review-mesh prepare creates local reviewer packets; opted-in plans can require assignment/result/synthesis/quorum receipts, but ALK core does not start hosts.

Routing and resource control

• Compact context profiles, small-model packets, objective snapshots, and local quality-cost learning help choose the lightest safe mode.
• Phase resource measurements reuse the usage export envelope for tokens, duration, and resource counters without mandatory monetary accounting.
• Usage/session exports include tokens, resources, receipt digests, and optional host-reported cost_usd.

Security and containment

• Neutrality filters use host-supplied deny rules to keep local paths, secrets, trust roots, and signing keys out of portable artifacts.
• Host env files require explicit --host-env-allow; receipts store redacted metadata, and generic descriptor-driven native launch is blocked before process creation.
• Imports, diagnostics, and usage exports redact local paths and common secret markers before validation.
• Sandbox receipts separate runtime filesystem, network, process, and environment containment from git write-scope.
• Release security gates reject leaked local paths, credentials, and unsupported adapter or production claims.

Adapters and interop

• Adapter contracts keep host-specific projections separate from lifecycle schemas.
• New CLI hosts start as adapters: descriptor, command projection, environment boundary, and verification evidence live outside the lifecycle core.
• Adapter capability checks and progress bridge support compare live receipts and display lifecycle state without automatic maturity changes.
• Import mappers and issue-to-spec intake treat external workflows, agent dialects, and tickets as untrusted draft inputs.
• Lightweight episode retrieval over receipt/session summaries keeps digest provenance and explicit chainVerified or chainUnchecked state.

Operations

• Runner recovery receipts cover attempt snapshot, restore, abandon, selected attempt, worker lease, and heartbeat state.
• Read-only diagnostics, event feeds, managed lifecycle steps, progress watch receipts, and change summaries inspect checkout and workflow state without model calls.

Daily flow

Spec -> frozen plan -> bounded work -> implementation audit -> final proof. Core commands cover specification, plan, workflow, audit, adapters, imports, metrics, policy, diagnostics, runner state, and adapter task intake. See CLI reference and Source of truth.

Adapter maturity

EXPERIMENTAL means offline checks exist; bounded live host conformance and usage/resource calibration are still required before VERIFIED. The verified claim is host-specific and also requires accepted redacted evidence and lifecycle final proof for the tested host range. New hosts can be added as adapters first and promoted only for the exact CLI/version/provider binding that has evidence. Monetary accounting is required only for metered modes.

Adapter installation and maturity details live in Adapter install and Adapter support matrix.

Contract map

The public lifecycle surface is schema-backed. Full stable schema ids, compatibility rules, runner recovery, cross-check, Review Mesh, Bug Forensics and usage export details are listed in Public contracts.

Design boundaries

• The core stays provider-neutral. Concrete host commands and model bindings belong to adapters or host-local profiles.
• New CLIs are integrated through adapters: descriptor, command projection, environment boundary, and verification evidence. The lifecycle schemas remain stable while host support grows.
• Small models get compact packets, deterministic checks, and explicit next-action lists instead of long narrative state.
• Larger models keep the same gates; better reasoning does not bypass evidence.
• Public release claims are limited to tracked source files and redacted evidence summaries.
• External dialect imports and retrieved episodes are context aids only; they do not replace reviewed ALK source-of-truth artifacts.
• Optional cross-check, Review Mesh and runner recovery receipts add evidence only when a task or plan requests them; they are not default multi-model execution.

Documentation

• Start: English documentation, Русская документация, Quickstart, Lifecycle cookbook, and Code review workflows.
• Planning and adapters: Issue to specification drafts, Adapter install, and Adapter support matrix.
• Reference: System architecture, CLI reference, Source of truth, Managed lifecycle runner, Managed adapter sessions, Implementation audit, Plan completeness, Public contracts, and Readiness diagnostics.
• Quality and resources: Small-model packets, model routing, adaptive policy, quality-cost learning, lifecycle cost accounting, Usage export, and Evidence integrity.
• Profiles and operations: Read-only status views, Adapter progress bridge, Sandbox boundaries, Import mappers, Episode retrieval, Runner recovery, Cross-check profile, Review Mesh, Bug Forensics profile, and Bug Forensics context budget.
• Release assets: Task templates and Release security.

Apache-2.0. See LICENSE.