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.69.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

• Start with quickstart.
• 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 redacted process receipts 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 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, Commands by task, 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, 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, lifecycle cost accounting, host-local token accounting, process execution observability, 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.