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.

ALK provides a verifiable finish for external-agent work with proportionate control. It adds only the checks and evidence needed for the task; most of the time remains for research, implementation and product verification.

Quick start

Start with install ALK and make the first run.

It includes macOS, Linux and Windows instructions, Python 3.11-3.14, PyPI installation with python -m pip install agent-lifecycle-kit==1.80.0, and common agent-lifecycle version errors.

For a quick start, run:

git clone https://github.com/avksp/agent-lifecycle-kit.git
cd agent-lifecycle-kit
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
agent-lifecycle version
agent-lifecycle diagnose --no-install-plans

Choose <adapter-id> from the adapter support matrix and pass a task from a file:

agent-lifecycle start --adapter <adapter-id> --file task.md

• Then choose a suitable scenario in how ALK works for different tasks.
• The boundaries of planning-only launch and frozen-task launch through a verified profile are documented in the reference. Shipped planning profiles remain candidates with safe failure until the corresponding profile is verified.
• The system architecture page explains how the project is organized, and project comparison shows how it differs from similar tools.
• Multiple-agent boundaries, workflow configuration, model choice, prompts, timeouts and retries are described in workflow customization and execution controls.
• Create a local project profile with agent-lifecycle project profile init; see project workflow profile.
• For long sessions, use context checkpoints and compaction recovery. They preserve a bounded local continuation package without changing plan authority.

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, resource counters and structured execution records without sensitive data 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, or apply a built-in workflow preset for a common route, while the frozen plan remains authoritative.
• Reproducible Python maintenance: pinned development-only Ruff, mypy and coverage checks, a non-growing quality ratchet, stable redacted CLI errors, installed package resources, an explicit documented Python API, and bounded performance controls that preserve security and evidence rules.
• Optional adapter lifecycle control: operation-level GUIDANCE_ONLY, OBSERVED and ENFORCED declarations remain separate from general adapter support; bundled adapters currently publish GUIDANCE_ONLY with NO_RECOMMENDATION, and managed launch remains WRAPPER_ONLY. See optional adapter lifecycle control.
• Project principles and plan deltas keep long-running work understandable: principles provide bounded defaults, while a digest-bound delta shows which plan authority changed and whether review and a new lock are required. CI also checks an acyclic module/package graph, layer direction and source-size limits; adapter inspection uses bounded literal profiles and fails closed without executing adapter code.
• Read-only progress and managed sessions preserve review/freeze boundaries; host UIs show lifecycle state and counters, start accepts task text, Markdown, frozen requests or stored sessions, and plan verify only checks plan data.

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; the operator or host wrapper starts each model. The reference-task suite validates or compares execution setups only after enough quality evidence; insufficient data produces NO_RECOMMENDATION.

Routing and resource control

• Compact context profiles, small-model packets and local quality-cost learning help choose a safe mode; audit optimization compares quality, time, tokens and resources after holdout evidence and requires operator approval.
• 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 verified 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.
• The portable Agent Plugins package exposes the maintained ALK skills tree; see portable Agent Plugins. After a client-owned installation, client qualification checks discovery without claiming lifecycle proof.
• 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.

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.

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, Русская документация, Install, Quickstart, Beginner and advanced workflows, Commands by task, Research workflow, Lifecycle task scenarios, 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, Plan verification, Research evidence, Source of truth, Managed lifecycle runner, Managed adapter sessions, Portable Agent Plugins, Plugin publication, Implementation audit, Plan completeness, Public contracts, and Readiness diagnostics.
• Quality and resources: Reference-task evaluation, model routing, quality-cost learning, performance and resource budgets, lifecycle cost accounting, host-local token accounting, process execution observability, Usage export, and Evidence integrity.
• Profiles and operations: Project workflow presets, Project workflow profile, 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.