Lifecycle

Give coding agents the project context they need to make proportionate changes. A small lifecycle.yaml tells them whether they are exploring an idea, building the first release, changing an operational system, or maintaining fragile code.

Lifecycle is an Agent Plugins package for project owners and teams using coding agents. It provides two portable skills and a Codex hook that loads project context automatically.

stage: production
notes: Serving operational users; deployment rollback is available.

With this declaration, an agent considers affected users, contracts, data and recovery when planning a change. It can still add features and refactor. Changing the profile does not grant deployment permissions or require compatibility for every existing interface.

Start with Codex

You need Git, Python 3.10 or later available as python3 in a POSIX execution environment, and a Codex client supporting Agent Plugins and local command hooks. The hook uses only Python's standard library; no package installation is needed to run it. The declaration must be a regular UTF-8 file of at most 16 KiB; symlinks are not supported.

1. Register and install the plugin using the Codex CLI:

   codex plugin marketplace add guilhem/lifecycle
   codex plugin add lifecycle@lifecycle
   

2. In Codex, open /hooks, review and trust the Lifecycle hook. Start a new session in your project after enabling it. In the desktop app, restart the app if the plugin has not appeared. Changed hook definitions require a new trust review.

3. Create lifecycle.yaml at your project's Git root using one of the profiles below. For a project that has not entered operational use:

   stage: development
   notes: Building the first operational release; previews use test data.
   

   Alternatively, ask the agent: Use the lifecycle skill to initialize this repository's lifecycle and integrate its existing agent instructions.

4. Start or resume a session and ask: Read lifecycle.yaml and explain how its profile affects this task. The agent should identify the declared profile and its practical consequences. The hook itself does not post routine chat messages or change files.

The hook reloads context at startup, resume, clear, fork and after compaction. From a subdirectory or linked worktree, it reads that Git root's declaration. Outside Git, it checks the working directory only. Repositories without a declaration stay quiet; unreadable files produce a nonblocking diagnostic.

Codex's current documentation restricts bundled-hook distribution to manual installation rather than the public plugin directory. This repository supplies that installation route. See the official packaging guidance and hook trust instructions.

Choose a profile

One profile describes the whole repository. Add short notes when operational obligations or known constraints need clarification.

These are profiles, not a sequence. Old code is not automatically legacy and new code is not automatically safe to discard. Production covers services, installed applications, libraries, firmware and self-hosted software. Existing users and valuable data still matter in every profile, including retired.

The authoritative profile reference defines implementation, validation and delivery implications. Copyable examples cover all six profiles.

Propose changes when reality changes

flowchart LR
    A[Project declaration] --> B[Agent adapts its work]
    B --> C[Major change observed]
    C --> D[Evidence and proposed YAML diff]
    D --> E[User authorizes update]
    E --> A

The lifecycle-update skill proposes a transition after actual first production delivery, a maintenance decision, retirement, or demonstrated resolution of documented fragility. It explains the evidence and how the new profile changes the agent's approach.

A tag, green CI run, deployment command or successful preview does not by itself prove production delivery. The skill distinguishes verified events from reported ones and waits for authorization before editing. It then applies the new profile to the current work. No scheduler, polling or transition history is involved.

Use other agents or work without hooks

Install both directories from skills/ together in your agent's supported skills location. They use the Agent Skills format; the update skill refers to the shared profile definitions in its sibling skill directory.

Add this instruction to your existing AGENTS.md, or your agent's equivalent:

Before relevant planning, implementation, review or delivery decisions, read root lifecycle.yaml and apply the installed lifecycle skill. After concrete evidence of a major project change, use lifecycle-update to propose an update. Do not change the declaration without authorization.

If your agent does not discover skills, include resolvable local paths to both SKILL.md files in that instruction. Preserve existing project guidance.

The standard root manifest packages the skills. Codex-only hook configuration lives under extensions.com.openai, with its files in com.openai/. Other clients can ignore that extension and still use the skills. See client extensions.

Validate declarations and contribute

The JSON Schema accepts a required stage and optional string notes; other fields are rejected. Use one YAML document with unique string keys. The hook supplies text to the agent; it does not parse or certify the declaration.

For deterministic validation, clone the repository and install the development dependencies in an isolated environment:

git clone https://github.com/guilhem/lifecycle.git
cd lifecycle
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python scripts/validate.py lifecycle.yaml examples/*.yaml
.venv/bin/python -m unittest discover -s tests -v

To validate another project's declaration, pass its path to scripts/validate.py. Valid files print valid; any invalid file makes the command exit with status 1. CI also validates the plugin manifest against the official Agent Plugins schema. Local tests exercise the hook protocol, root discovery, worktrees, read failures and safety bounds; they do not establish that hooks have been trusted or executed inside an installed Codex session.

Licensed under MIT.