Agent Lifecycle Kit

Agent Lifecycle Kit (ALK) coordinates coding-agent work through a verifiable finish. It keeps the requested outcome, reviewed plan, execution boundaries, evidence and acceptance decisions connected while the external agent changes the project.

The provider-neutral workflow works with Codex, Claude Code, Qwen Code, Goose, OpenInterpreter, Pi, Grok Build, or another CLI. 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 start --adapter <adapter-id> --text "Draft a reviewed implementation plan"

Choose <adapter-id> from the adapter support matrix.

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

Use Quickstart, project profile init, task workflows, workflow customization and execution controls, and the Lifecycle cookbook. The planning-only and qualified frozen-task guides define launch boundaries. See System architecture, Project comparison, and Документация на русском.

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: one provider-neutral execution strategy composes risk, model class, packet size, review and resource limits.
• Usage visibility: tokens, time, and resource counters are native; monetary cost is optional and only used when a metered host reports it.
• Project-specific workflow settings: ALK can discover and validate uncommitted local defaults for a repository while the frozen plan remains authoritative.
• Read-only progress and managed sessions: host UIs can show lifecycle state, attested tokens and Git-style change counters; start accepts task text, Markdown, frozen run requests or stored ALK sessions 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 multi-model review can use any available adapter/model bindings; Codex, Claude Code and OpenCode/GLM are examples, not a required roster. Review Mesh prepares packets, imports answers, synthesizes findings and checks quorum, while the operator or host wrapper starts each model. The bundled reference-task suite measures deterministic quality, false acceptances, retries, elapsed time, and confidence-labeled token usage.

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

• Release neutrality scans bind the Git index and current revision; ignored local evidence is read through an explicit policy-limited flag. Host-supplied rules keep local paths, secrets, trust roots and signing keys out of portable artifacts.
• Host environment access uses explicit --host-env-allow; receipts store redacted metadata, and qualified local profiles provide the managed launch route.
• 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 validate portable paths, credentials, adapter scope and 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 while support levels remain evidence-driven.
• Import mappers and issue-to-spec intake normalize external workflows, agent dialects, and tickets into reviewable draft context.
• 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 support level

The adapter support level describes how much of the ALK integration is verified for a specific host. It covers the declared CLI/version, command projection, environment boundary, live conformance, resource calibration and accepted ALK lifecycle evidence. It describes the checked integration range; it is not a rating of the host model or of the external product.

Accepted lifecycle artifacts include the reviewed plan and lock, state and task receipts, validation and evidence summaries, independent plan and implementation audits, and final proof. Host launch routes add usage, resource and containment receipts for the exact adapter/version binding.

EXPERIMENTAL marks an adapter with offline checks and deterministic contract tests. VERIFIED adds bounded live host conformance, usage/resource calibration, accepted redacted evidence and lifecycle final proof for a defined host range. Each adapter page and the support matrix name the exact CLI, version and host-local binding covered by the evidence. The matrix covers Codex, Claude Code, Cursor, Gemini CLI, Goose, Grok Build, Hermes, Kimi Code, OpenCode, OpenInterpreter, Pi and Qwen Code.

Adapter installation and support-level 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 live in 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.
• All model sizes follow the same evidence gates; larger models receive the same bounded workflow with richer reasoning capacity.
• Public release claims use tracked source files and redacted evidence summaries.
• External dialect imports and retrieved episodes enrich context, while reviewed ALK artifacts remain the source of truth.
• Cross-check, Review Mesh and runner recovery receipts add evidence when a task or plan enables them; the operator chooses the review depth.

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, workflow customization and execution controls, execution strategy, CLI reference, Source of truth, Managed lifecycle runner, Managed adapter sessions, Implementation audit, Plan completeness, Public contracts, and Readiness diagnostics.
• Quality and resources: Reference-task evaluation, model routing, quality-cost learning, lifecycle cost accounting, host-local token 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, Neutrality scanning, and Release security.

Apache-2.0. See LICENSE.