Agent Lifecycle Kit

Русская версия

Agent Lifecycle Kit is a provider-neutral workflow distribution for turning a
software request into a reviewed SDD specification, a frozen agent-ready plan,
controlled implementation, independent implementation audit, and reproducible
final verdict.

It is distributed as one repository with one semantic core and native host
projections for Codex, Claude Code, Cursor, Hermes, and OpenCode.

Current status

v0.5.0 is the current source release. It adds the release-0-5 execution
gates: acceptance checklist validation against the frozen manifest, neutral
adapter event stream validation, task-acceptance write-scope enforcement,
per-attempt baseline reconciliation, external-action parking, final completion
signals, and live Claude Code adapter evidence.

Adapter maturity is host-specific. Claude Code is VERIFIED for Claude Code
2.1.220 in the current source tree after the local release-0-5 live
conformance, live calibration, and full lifecycle proof. Codex, Cursor, Hermes,
and OpenCode remain EXPERIMENTAL until each host has matching live evidence.
Public directory publication still depends on each host marketplace review
process.

What the kit does

The complete lifecycle is:

request
  -> clarification when required
  -> SDD specification
  -> independent specification review and refinement
  -> production-ready agent plan
  -> independent plan review and refinement
  -> immutable freeze
  -> task packet compilation
  -> authorized implementation
  -> controller-owned validation and independent review per task
  -> remediation or contract change when required
  -> final audit, terminal review, and reproducible completion proof

The lifecycle has five canonical skills:

• agent-first-planning
• audit-agent-plan
• agent-plan-to-workers
• agent-workflow-orchestrator
• audit-plan-implementation

The skills are thin entry points. Specifications, plans, locks, task packets,
run state, evidence, budgets, and audit semantics are owned by the shared
deterministic core rather than reimplemented in each host adapter.

Compact context mode

Small-context hosts are supported through a deterministic context profile, not
through prompt-only truncation. The bundled
profiles/small-context-profile.v1.json defines 4k-strict, 8k, 16k, 32k, and
64k windows, reserves output space, limits the active packet and state summary,
limits evidence/tool-output summaries and recent verbatim user turns, and
forbids silent truncation.

If a rendered envelope does not fit, the controller must split the task,
request a larger context, or block the run. Older context and tool output are
represented by hashable summaries and evidence identities.

The conformance corpus includes a dedicated 4k-strict scenario
(S1-SMALL-CONTEXT-4K-STRICT-01) in addition to the 8k baseline, so support for
sub-8k local models is verified as a separate contract path.

Live cost calibration

Synthetic replay baselines are useful for deterministic regression checks, but
they are not production-promotion evidence. Promotion requires a live,
usage-attested receipt validated against
conformance/core/live-calibration-profile.v1.json and
conformance/core/budget-targets.v1.json.

Lifecycle conformance for a promoted host is validated separately:

python tools/release/validate_live_host_conformance.py \
  --profile conformance/core/live-calibration-profile.v1.json \
  --baseline conformance/core/adapter-baseline.v1.json \
  --receipt-dir <live-host-receipts-dir> \
  --promoted-hosts codex \
  --evidence <live-host-conformance-evidence.json>

python tools/release/validate_live_calibration.py \
  --profile conformance/core/live-calibration-profile.v1.json \
  --budget-targets conformance/core/budget-targets.v1.json \
  --receipt-dir <live-calibration-receipts-dir> \
  --promoted-hosts codex \
  --evidence <live-calibration-evidence.json>

The validator rejects synthetic replay receipts, missing usage attestations,
unsupported hosts, missing required scenario/cohort coverage for that host,
quality regressions, and p95 budget overruns. A universal VERIFIED claim
requires one passing live host conformance receipt and one passing live cost
calibration receipt per host listed in the calibration profile.
See
live cost calibration.

Model routing

Model routing is a deterministic provider-neutral core capability. The core
resolves a neutral model class for each phase or task attempt; host adapters map
that class to a configured provider/runtime model outside portable artifacts.
When a task attempt has attemptModelRoute.requiresUsageReceipt=true,
workflow task-result is fail-closed until a valid host-attested usage receipt
is provided.

agent-lifecycle model profile-check --profile profiles/model-routing-profile.v1.json
agent-lifecycle model route --profile profiles/model-routing-profile.v1.json --request <model-route-request.json>
agent-lifecycle model usage-check --receipt <model-usage-receipt.json> --route-decision <model-route-decision.json> --budget-targets conformance/core/budget-targets.v1.json

Portable classes are no-model, budget, local-compact, standard-code,
local-standard-code, strong-reasoning, local-strong-review, and
specialist-review. Local-only execution is supported, but final audit,
security review, performance review, production promotion, and S2 independent
review require an explicitly calibrated review-capable local class such as
local-strong-review; local-compact cannot silently satisfy those gates.

See model routing.

Budget decisions

Budget caps are safety stops, not success criteria. When a model-backed attempt
exceeds an approved cap, the workflow enters WAITING_FOR_BUDGET_DECISION
instead of accepting the task. In manual mode an operator chooses whether to
continue, reroute, split, or abort. In auto mode the policy can reroute within a
bounded count, but critical review phases cannot silently downgrade to weaker
classes.

Budget modes are:

• metered: requires an approved USD cap.
• subscription: requires maxInvocations and a token or wall-clock cap.
• local: uses the same resource-cap rule as subscription mode.

See budget reroute policy.

Distribution layout

A universal distribution does not mean one manifest format. The same core is
projected into each host's native loading model:

The root repository is the canonical plugin root for Codex, Claude Code, and
Cursor. The older adapters/<host>/ directories remain offline conformance
projections and host-specific metadata; users should install from the root
package unless a future release explicitly publishes a materialized adapter
package.

Installation and publication

Source-mode core CLI

For local development of the current repository:

python -m pip install -e .
agent-lifecycle version
agent-lifecycle schema list
agent-lifecycle workflow status --state <path-to-run.state.json>
agent-lifecycle workflow next --state <path-to-run.state.json>
agent-lifecycle workflow task-start --state <path-to-run.state.json> --task <task-id> --operation-id <id> --expected-revision <n> --source-revision <sha> --reason "<reason>"
agent-lifecycle workflow task-result --state <path-to-run.state.json> --task <task-id> --operation-id <id> --expected-revision <n> --source-revision <sha> --result <task-result.json> --model-usage-receipt <model-usage-receipt.json> --reason "<reason>"
agent-lifecycle workflow task-accept --state <path-to-run.state.json> --task <task-id> --operation-id <id> --expected-revision <n> --review <task-review.json> --reason "<reason>"
agent-lifecycle workflow finalize --state <path-to-run.state.json> --operation-id <id> --expected-revision <n> --source-revision <sha> --final-audit <final-audit.json> --proof <final-proof.json> --reason "<reason>"
agent-lifecycle audit ownership --manifest <plan.manifest.json> --base <base-ref> --fail-on-unowned --fail-on-forbidden
agent-lifecycle tier resolve --request <tier-request.json>
agent-lifecycle specification check --specification <specification.json>
agent-lifecycle plan check --manifest <plan.manifest.json> --lock <plan.lock.json>
agent-lifecycle plan acceptance-check --manifest <plan.manifest.json> --acceptance <acceptance-criteria.md>
agent-lifecycle task compile --manifest <plan.manifest.json> --out-dir <task-packet-dir> --write
agent-lifecycle model profile-check --profile profiles/model-routing-profile.v1.json
agent-lifecycle model route --profile profiles/model-routing-profile.v1.json --request <model-route-request.json>
agent-lifecycle model usage-check --receipt <model-usage-receipt.json> --route-decision <model-route-decision.json> --budget-targets conformance/core/budget-targets.v1.json
agent-lifecycle context profile-check --profile profiles/small-context-profile.v1.json
agent-lifecycle context check --profile profiles/small-context-profile.v1.json --task-packet <task-packet.json> --summary <compact-summary.json> --target-window 4k-strict
agent-lifecycle context check --profile profiles/small-context-profile.v1.json --task-packet <task-packet.json> --summary <compact-summary.json> --target-window 8k
agent-lifecycle context render --profile profiles/small-context-profile.v1.json --task-packet <task-packet.json> --summary <compact-summary.json> --target-window 8k
agent-lifecycle adapter validate --descriptor adapters/codex/adapter.descriptor.json --baseline conformance/core/adapter-baseline.v1.json
agent-lifecycle adapter event-check --event <adapter-event-1.json> --event <adapter-event-2.json>
agent-lifecycle adapter scaffold --host synthetic-host --target /tmp/agent-lifecycle-adapter-scaffold --dry-run
agent-lifecycle-neutrality scan --scope current-tree-complete --policy policy/neutrality.policy.json --require-zero-findings

The same commands can run without installation from a checkout:

PYTHONPATH=src python -m agent_lifecycle version
PYTHONPATH=src python -m agent_lifecycle schema list
PYTHONPATH=src python -m agent_lifecycle workflow status --state <path-to-run.state.json>
PYTHONPATH=src python -m agent_lifecycle workflow next --state <path-to-run.state.json>
PYTHONPATH=src python -m agent_lifecycle workflow task-start --state <path-to-run.state.json> --task <task-id> --operation-id <id> --expected-revision <n> --source-revision <sha> --reason "<reason>"
PYTHONPATH=src python -m agent_lifecycle workflow finalize --state <path-to-run.state.json> --operation-id <id> --expected-revision <n> --source-revision <sha> --final-audit <final-audit.json> --proof <final-proof.json> --reason "<reason>"
PYTHONPATH=src python -m agent_lifecycle audit ownership --manifest <plan.manifest.json> --base <base-ref> --fail-on-unowned --fail-on-forbidden
PYTHONPATH=src python -m agent_lifecycle tier resolve --request <tier-request.json>
PYTHONPATH=src python -m agent_lifecycle specification check --specification <specification.json>
PYTHONPATH=src python -m agent_lifecycle plan check --manifest <plan.manifest.json> --lock <plan.lock.json>
PYTHONPATH=src python -m agent_lifecycle plan acceptance-check --manifest <plan.manifest.json> --acceptance <acceptance-criteria.md>
PYTHONPATH=src python -m agent_lifecycle task compile --manifest <plan.manifest.json> --out-dir <task-packet-dir> --write
PYTHONPATH=src python -m agent_lifecycle model profile-check --profile profiles/model-routing-profile.v1.json
PYTHONPATH=src python -m agent_lifecycle model route --profile profiles/model-routing-profile.v1.json --request <model-route-request.json>
PYTHONPATH=src python -m agent_lifecycle model usage-check --receipt <model-usage-receipt.json> --route-decision <model-route-decision.json> --budget-targets conformance/core/budget-targets.v1.json
PYTHONPATH=src python -m agent_lifecycle context check --profile profiles/small-context-profile.v1.json --task-packet <task-packet.json> --summary <compact-summary.json> --target-window 8k
PYTHONPATH=src python -m agent_lifecycle adapter validate --descriptor adapters/codex/adapter.descriptor.json --baseline conformance/core/adapter-baseline.v1.json
PYTHONPATH=src python -m agent_lifecycle adapter event-check --event <adapter-event-1.json> --event <adapter-event-2.json>
PYTHONPATH=src python -m agent_lifecycle adapter scaffold --host synthetic-host --target /tmp/agent-lifecycle-adapter-scaffold --dry-run
PYTHONPATH=src python -m agent_lifecycle.neutrality scan --scope current-tree-complete --policy policy/neutrality.policy.json --require-zero-findings

Implemented core CLI groups are version, schema, workflow status,
workflow next, workflow block, workflow resolve, workflow task-start,
workflow task-result, workflow task-accept, workflow finalize,
audit ownership, tier resolve, context profile-check, context check,
context render, model profile-check, model route, model usage-check,
specification check, plan check, plan acceptance-check, task compile,
adapter validate, adapter event-check, adapter scaffold, and
neutrality. Adapter scaffold is template-only and can only create
EXPERIMENTAL projection skeletons. Runtime adapter execution and conformance
lifecycle groups remain reserved and fail closed with a stable
agent-lifecycle-error.v1 response until their runtime core modules land.

context check and context render also fail closed on overflow: if the
rendered receipt status is FAIL, the CLI exits non-zero and returns
agent-lifecycle-error.v1 with code context-overflow. The receipt checks the
rendered envelope, reserved-output budget, active packet, state summary,
accepted evidence summary, optional toolOutputs, and recent verbatim
user-turn count.

workflow finalize requires --final-audit. The audit must pass with
READY_FOR_FINALIZATION, match the run's plan revision and digest, avoid
production-promotion claims, contain no unresolved MEDIUM+ findings, and carry
a valid agent-completion-signal.v1 with PASS status or an explicit
evidence-bound WAIVED signal.

workflow task-accept rechecks changed files from the committed task result
against the frozen task write scope and root write policy before accepting an
independent review. Forbidden, read-only or unowned paths fail closed with
task-ownership-violation.

Each task attempt records its own base revision at launch. A task result whose
changeSet.baselineSha differs from that attempt base is rejected unless it
contains a valid agent-baseline-reconciliation-receipt.v1.

Human-only work should be represented as workflow state, not prose completion.
Core transitions can park a run in WAITING_FOR_EXTERNAL_ACTION and resume it
only from a matching agent-external-action-receipt.v1.

Workflow transitions enforce task controllerGates for pre-launch,
post-attempt, pre-acceptance, and finalization phases. Expected receipts
are resolved from the frozen receiptPath template and must bind gate, run,
package, task, attempt, phase, operation, plan digest, source revision, PASS
verdict, freshness, dependencies, and configured attestation fields.

Tests use only the Python standard library:

PYTHONPATH=src python -m unittest discover -s tests -p 'test_*.py'

Codex

Install from the tagged source marketplace:

codex plugin marketplace add avksp/agent-lifecycle-kit --ref v0.5.0
codex plugin add agent-lifecycle-kit@agent-lifecycle-kit

You can also browse configured marketplaces with /plugins. Start a new Codex
session after installation so the bundled skills are loaded.

For public Plugins Directory publication, submit the root package as a
skills-only plugin through the OpenAI plugin submission portal. Do not claim
VERIFIED until live Codex install and lifecycle conformance evidence is
published in the support matrix.

Claude Code

Add the marketplace and install the plugin:

claude plugin marketplace add avksp/agent-lifecycle-kit
claude plugin install agent-lifecycle-kit@agent-lifecycle-kit

In an interactive Claude Code session, the equivalent slash flow is:

/plugin marketplace add avksp/agent-lifecycle-kit
/plugin install agent-lifecycle-kit@agent-lifecycle-kit
/reload-plugins

Plugin skills are namespaced by plugin name, for example
/agent-lifecycle-kit:agent-workflow-orchestrator.

Claude Code is verified for the tested 2.1.220 host range in the current source
tree. The claim is backed by release-0-5 live conformance, live
calibration, and ALK lifecycle final proof listed in the support matrix.

For inclusion in the Anthropic-managed public directory, submit the plugin for
Claude's external plugin review. The repo-level marketplace is enough for
private or community distribution, but not a public-directory approval claim.

Cursor

For local validation before submission, symlink or copy the repository into
Cursor's local plugin directory:

mkdir -p ~/.cursor/plugins/local
ln -s /path/to/agent-lifecycle-kit ~/.cursor/plugins/local/agent-lifecycle-kit

Then restart Cursor or run Developer: Reload Window. After local validation,
submit the public repository at https://cursor.com/marketplace/publish.

For Teams or Enterprise, import the GitHub repository as a team marketplace
from Dashboard -> Plugins. After public approval, install from the Cursor
Marketplace or Customize panel. If your Cursor build supports chat-based
plugin installation, use:

/add-plugin agent-lifecycle-kit

Hermes

Hermes can install the shared skills directly. To install all lifecycle skills
from the tagged release:

for skill in agent-first-planning audit-agent-plan agent-plan-to-workers agent-workflow-orchestrator audit-plan-implementation; do
  hermes skills install "https://raw.githubusercontent.com/avksp/agent-lifecycle-kit/v0.5.0/skills/${skill}/SKILL.md"
done

The root skills.sh.json provides tap/category metadata for hosts that read
skills.sh-compatible indexes. adapters/hermes/* contains experimental
registry and slash-command projection metadata. It is not a live Hermes plugin
verification claim.

OpenCode

OpenCode loads plugins and skills through separate mechanisms. For a project
install, copy the shared skills and adapter into the target project:

KIT=/path/to/agent-lifecycle-kit
mkdir -p .opencode/skills .opencode/plugins
cp -R "$KIT"/skills/* .opencode/skills/
cp "$KIT"/adapters/opencode/plugins/agent-lifecycle-kit.js .opencode/plugins/

For user-level install:

KIT=/path/to/agent-lifecycle-kit
mkdir -p ~/.config/opencode/skills ~/.config/opencode/plugins
cp -R "$KIT"/skills/* ~/.config/opencode/skills/
cp "$KIT"/adapters/opencode/plugins/agent-lifecycle-kit.js ~/.config/opencode/plugins/

The repository root also includes opencode.json for source checkout testing.
A future npm package can point to the same adapter, but no npm publication is
claimed by v0.5.0.

Usage

Ask the host to run the full lifecycle through agent-workflow-orchestrator:

Use the agent-workflow-orchestrator skill.

Task: <describe the required outcome>.

Ask only blocking clarification questions. Build and independently review an
SDD production-ready plan until it is ready to freeze. Request authorization
before implementation. Validate and independently review every task attempt.
Run the final audit and terminal review before reporting completion.

Host-specific explicit invocation may be used when available:

• Codex: select Agent Lifecycle Kit or ask Codex to use
  agent-workflow-orchestrator
• Claude Code: /agent-lifecycle-kit:agent-workflow-orchestrator
• Cursor: ask Agent to use agent-workflow-orchestrator
• Hermes: run /agent-workflow-orchestrator after installing the skill
• OpenCode: ask the agent to load agent-workflow-orchestrator through its
  native skill tool

The release support matrix is authoritative for exact namespaced syntax and
host maturity. An EXPERIMENTAL adapter projection is not a live runtime
compatibility claim.

Stage-specific skills

Use agent-first-planning when you need clarification, an SDD specification,
and a production-ready plan without starting implementation:

Use agent-first-planning to turn this request into an independently reviewable
SDD plan package. Stop before implementation.

Use audit-agent-plan for an independent findings-first review of a draft or
reopened plan:

Use audit-agent-plan to review this complete plan revision. Do not implement
or silently repair it; return stable findings and a readiness verdict.

Use agent-plan-to-workers only after a reviewed plan is frozen:

Use agent-plan-to-workers to compile this frozen plan into immutable task
packets. Do not redesign the DAG or ownership.

Use agent-workflow-orchestrator to run or resume the complete authorized
lifecycle:

Use agent-workflow-orchestrator to resume the frozen run from durable state,
enforce its budgets and approvals, and route every task through review.

Use audit-plan-implementation for a read-only task-attempt or final
implementation audit:

Use audit-plan-implementation for a findings-first audit against the frozen
plan, packet, changed files, tests, and evidence. Do not fix findings.

Execution and approval policy

The durable workflow state is independent of chat history and native goal-mode
availability. A host with native background tasks can map them through its
adapter; another host can resume the same state sequentially.

Implementation starts only from a hash-verified frozen plan and immutable task
packet set. The default flow asks for authorization before execution.
Automatic execution is allowed only when the frozen run policy and host policy
both permit it. Contract changes, authority drift, missing evidence, exhausted
budgets, or unavailable mandatory capabilities block the run.

For model-backed attempts, adapters must execute the task with the selected
attemptModelRoute or fail closed. The controller accepts the result only when
the usage receipt binds to the run, task, attempt, plan digest, source revision
and route decision digest.

SDD tier selection is proposed by planning, checked by the deterministic
tier resolve rules, independently reviewed by audit-agent-plan, and then
frozen by the controller. Manual overrides may raise the tier; lowering a tier
requires resolver and independent review agreement.

Compatibility and safety

• Core contracts do not embed provider names, model names, project paths, or
  credentials.
• The repository and all samples, fixtures, and evaluations must remain free of
  source-project information.
• Adapters may translate discovery, invocation, approvals, subagents, and host
  operations, but they may not reimplement lifecycle semantics.
• Install only trusted releases. Native plugins and hooks may execute code with
  the permissions granted by their host.
• Check the release support matrix before relying on a host adapter.

Documentation

• Russian README
• Adapter support matrix
• Modular controller architecture
• Codex plugin documentation
• Claude Code plugin documentation
• Cursor plugin documentation
• Hermes skills documentation
• OpenCode skills
• OpenCode plugins

License

Licensed under the Apache License 2.0.