Agent Context Lifecycle

End a session with a project that the next agent can actually continue.

A portable skill for preserving decisions, reconciling related documents, and handing off unfinished work with its evidence. It helps an agent answer three questions: What is true now? Where does it belong? What still needs to happen?

Quick start · What you get · Worked example · How it works · Verification

The moment this becomes useful

You approved a different retry policy. The code changed. The architecture note still describes the old rule. Yesterday's test report says FAIL. A new session opens and has to decide what to trust.

This skill makes that transition explicit: update the current rule, reconcile its consumers, preserve the historical result, and hand over the exact remaining verification. It works at material checkpoints during the task as well as at closeout.

The useful output is a reconciled project and a precise continuation point. A handoff summary is the receipt for that work.

Quick start

Install into a project with the Skills CLI:

npx skills add Crabbb/agent-context-lifecycle --skill agent-context-lifecycle

Select your agent when prompted. Requires Node.js/npm for this installer and an agent capable of reading files and following Agent Skills. The skill itself is Markdown: no daemon, API key, database or background service. Your chosen agent still has its own access and usage requirements.

Then give the agent a concrete task:

Use agent-context-lifecycle to close out this session.
Reconcile the documents affected by our verified changes.
Preserve decisions, open questions, evidence and the exact next step.
Use the existing project context home and current write permissions.

Manual setup and explicit invocation

Copy SKILL.md, references/, agents/ and LICENSE.txt into an agent-context-lifecycle folder under your client's supported skill directory. For GitHub Copilot project skills, use .github/skills/agent-context-lifecycle/. For Codex project skills, use .agents/skills/agent-context-lifecycle/.

If discovery is unavailable, explicitly ask your file-capable agent to read the installed SKILL.md and apply it to your current task. Installation/discovery alone does not prove the client loaded it; check the reading trace or receipt. See verification and client scope.

What you get

Deliverable	What it contains	Why it matters
Current project context	Verified decisions, observations, constraints and open questions, each with sources	The next session can distinguish a decision from a guess
Reconciled documents	One authoritative home per claim; affected documents updated or explicitly pending	Architecture notes, plans and runbooks can agree with the same change
A continuation point	Completed work, pending outcomes, exact next actions and authorization boundaries	Another agent can resume the unfinished part
A delivery receipt	What was saved, found, loaded and behavior-tested, with evidence	A written file is never silently upgraded to “the agent knows it”
A private project wiki, when requested	A compact local entrypoint with useful working artifacts, outside the Git index	Working context stays separate from shipped contracts and test inputs
A migration record, when authorized	Source/destination mapping, hashes, dependency checks and recoverable backup	Relocation preserves history and required build inputs

The shape scales to the task. A small checkpoint can be a few precise lines in the existing plan. A substantial handoff can include reconciled files and linked evidence. Empty folders and duplicate ledgers are unnecessary.

See the output

Fictional example: a batch exporter now retries transient network failures twice. The repository has an accepted decision, a maintained runbook and an old test snapshot.

CHECKPOINT · Export retry policy

Decision       EXP-12 · accepted · batch export only
Primary source docs/decisions/EXP-12.md · revision 3
Current home   docs/architecture/retries.md#batch-export
Disposition    updated · written section read back

Reconciled     docs/operations/export-runbook.md
Preserved      evidence/export-run-previous.json · historical FAIL
Unaffected     docs/api/interactive-search.md · different retry contract

Open           Jitter strategy · candidate · not promoted to policy
Next action    Run the focused batch-export retry scenario
Delivery       Saved ✓ · Discoverable ✓ · Loaded pending
               Indexed N/A: direct file navigation
               Behavior pending: new scenario has not run

This is an illustrative output, not a benchmark or a claimed test result. The complete walkthrough includes the request, source facts, affected-document reasoning and replay behavior.

Choose your moment

Situation	Ask the agent	Result
Starting a substantial project	“Initialize private project context; keep delivery contracts tracked.”	An authorized local home with a usable entrypoint
A decision changes mid-task	“Reconcile the documents affected by this decision.”	Bounded impact analysis and targeted updates
Ending a session	“Checkpoint what is complete and what remains.”	Source-backed state and a concrete next action
Continuing in a new session	“Read project context, verify freshness, resume pending work.”	Current sources checked before continuing
Moving working artifacts	“Plan and perform this authorized migration with recovery.”	Copy, verify, then retire only approved files
Correcting the agent's approach	“This route already works; check only the missing behavior.”	Working baseline preserved; unnecessary investigation stopped

Skip cosmetic edits with no material knowledge change. Do not initialize a private wiki unless requested or already enabled for the project.

How it works

Illustrative workflow: the agent verifies sources, reconciles authorized changes, checks delivery and hands off the next action. Saving a file does not prove the next agent loaded it.

Inspect the text-based flow diagram

flowchart LR
    A[Material change] --> B[Open primary sources]
    B --> C[Find claim home and consumers]
    C --> D{Current and authorized?}
    D -->|Already current| E[Verified no-op]
    D -->|Write authorized| F[Minimal update and readback]
    D -->|Decision or access missing| G[Exact proposal or blocker]
    F --> H[Verify relevant delivery levels]
    E --> I[Continue pending work]
    G --> I
    H --> I

Loading

The impact search follows claims, citations, code references and supersession until relevant relationships are resolved or explicitly pending. It stays within the task's authorized scope. Historical evidence remains intact; maintained summaries carry current applicability.

A file is only the first step

State	What proves it
Saved	The exact changed content was read back
Indexed	The active index matches the source revision
Discoverable	A real lookup or entrypoint finds the current claim
Loaded	The target agent's trace or receipt shows it read that version
Behavior-verified	A relevant scenario demonstrates the expected behavior after loading

These are distinct claims, not a mandatory linear pipeline. A human reading a local document may need only saved and discoverable. An agent using retrieval may need all five. An unavailable check stays pending; an inapplicable check gets N/A with a reason.

Fits around your existing workflow

• Task plans and issue trackers: reuse their decision/finding IDs and completed/pending state.
• Repository documentation: preserve tracked contracts and inputs that CI or users need.
• Private context: default to .project-context/ only when enabled; respect an existing agreed home.
• Shared knowledge systems: optional, through their current identity, ownership and publication rules.
• Agent handoffs: carry source revisions and permissions; verify freshness in the receiving session.

The skill specifies the workflow. The host agent performs reads, searches and authorized edits. It does not install hooks, monitor your files continuously, provide cloud sync, expand the model's context window or guarantee model compliance. Git ignore prevents normal Git tracking; it is not an access-control boundary. Private history does not travel with a fresh clone.

Inspect the package

Resource	Purpose
SKILL.md	Entry point and shared rules
Context delta	One record contract and five explicit dispositions
Impact reconciliation	Follow affected claims without a whole-repository audit
Delivery verification	Evidence needed for each consumer
Private project wiki	Initialize and resume local working context
Migration safety	Recoverable relocation with dependency checks
Connected knowledge	Optional shared knowledge integration
Operational corrections	Preserve working baselines and reconcile late notifications

Trust, evidence and contribution

The package uses the Agent Skills format. Behavior depends on the host agent, permissions, source quality and the checks actually run. See verification scope for evidence and limits; no aggregate productivity or accuracy claim is made.

Diagrams and examples here are original explanatory material. The two editorial illustrations were generated with GPT Images; design notes and prompts describe their intent and limits.

Report a reproducible workflow problem through Issues. Include a sanitized scenario, expected behavior and observed result. Read contribution guidance before sharing context or traces.

MIT licensed. Install it, give your agent a real checkpoint, and inspect what the next session can actually recover.