Maintenance Capsule

Maintenance Capsule

Build the smallest repository-local project kernel that lets a fresh agent recover the project's identity, verify current reality, and continue from the right place without freezing the implementation.

Standardize what must be remembered, not how every project must be built. The capsule is a navigation and decision layer; the repository, Git state, tests, deployed behavior, and other current sources remain the operational truth.

Choose a mode

• init: The repository has no capsule. Inspect it and create the minimum useful capsule.
• audit: A capsule or project instructions exist. Find duplication, stale facts, contradictions, and implementation-level overconstraint; remove what does not change decisions.
• refresh: The project goal, architecture, or stable baseline changed. Update the capsule to describe the new truth instead of appending history.
• resume: Work continues in a new window, model, person, or stage. Read the capsule, reconcile it with current reality, identify the current stage and next minimal action, then continue or report discrepancies before changing files.

Infer the mode from the request and repository. Do not ask when the evidence makes the choice clear.

Inspect before writing

Read the real repository first:

1. Check Git status and preserve unrelated user changes.
2. Read existing repository instructions, README, primary entry points, tests, and deployment configuration.
3. Inspect current outputs or interfaces when user-visible correctness matters.
4. Identify the source of truth for facts that can drift.
5. Distinguish enduring intent from temporary state and implementation detail.

Do not create a capsule from the user's prompt alone when the repository can answer the question.

Apply the narrow waist

Keep five cross-environment invariants:

1. Goal: What outcome must the project create, and for whom?
2. Boundaries: What truths, non-goals, safety limits, or identity must not be lost?
3. Evidence: What observable checks prove improvement or regression?
4. Stable baseline: What accepted artifact, version, or live target is the comparison or rollback point?
5. Current handoff: What stage is active, what is unfinished or unverified, and what is the next minimal action?

Leave implementation choices open unless a specific path is required for safety, compatibility, or deterministic correctness.

Do not confuse the stable baseline with work in progress. A baseline is accepted evidence; current handoff state may be incomplete, uncertain, or blocked.

Create the minimum capsule

Default to one file:

GOAL.md

Add only when earned by the project:

AGENTS.md              # repository-local rules that change agent behavior
HANDOFF.md             # handoff state too large or volatile for GOAL.md
observable baseline    # evidence with real comparison value

GOAL.md

Keep it concise and decision-bearing. Include:

• one-sentence project goal;
• 3–5 success criteria;
• the smallest set of narrow-waist boundaries;
• an upgrade method that changes one primary variable per iteration;
• project-specific acceptance evidence;
• the current stable baseline, if one exists;
• a short current handoff: stage, completed state, unfinished or unverified items, blockers, and next minimal action.

Treat GOAL.md as the project's identity card plus a short baton. Keep the handoff section compact and replace stale state instead of appending a diary. If it becomes longer than roughly 10–20 lines, changes much more frequently than project identity, or contains substantial temporary detail, move it to HANDOFF.md and leave a pointer in GOAL.md.

For comparisons, use improved / unchanged / regressed + evidence. Avoid numeric scores without a calibrated scale. Require critical identity and engineering quality not to regress, and require at least one evidenced improvement before release.

AGENTS.md

Create or retain repository AGENTS.md only when local rules materially change decisions or protect the project. Host-wide rules alone are sufficient otherwise.

Keep repository instructions shorter than the goal document. When needed, it should:

• tell agents to read GOAL.md and inspect current reality first;
• protect source-of-truth and safety constraints;
• require scoped changes and real verification;
• preserve the user's commit, push, deployment, and destructive-action boundaries.

Point to GOAL.md; do not duplicate it. Prefer 4–7 rules.

HANDOFF.md

Create HANDOFF.md only when the short baton no longer fits cleanly in GOAL.md. Keep only operational continuation state:

• current stage and last verified result;
• unfinished and explicitly unverified work;
• blockers or external dependencies;
• next minimal action;
• temporary safety warnings needed by the next agent.

Do not duplicate project identity, enduring boundaries, history, or general process rules. Replace resolved state and use Git or decision records for history.

Observable baseline

Choose evidence by project type:

• UI: one approved screenshot or rendered artifact;
• API: contract tests and representative HTTP responses;
• CLI: golden commands and outputs;
• data pipeline: audit report or small golden dataset;
• library: public API tests;
• documentation: representative reader questions and expected answers.

Reuse verified artifacts when available. Do not manufacture a baseline merely to satisfy the structure. Add multiple baselines only when each protects a materially different risk.

Audit by deletion

For every capsule statement, ask:

• Does it change a future decision?
• Is it enduring rather than temporary?
• Is it already enforced by code, tests, or Git?
• Does it duplicate another rule?
• Does it protect an outcome, or merely freeze an implementation?

Delete or merge statements that fail these tests. Do not add repository rules, directory blueprints, separate handoff files, changelogs, or process checklists by default. Add them only when project complexity creates a demonstrated decision, safety, verification, or recovery need.

When existing files would be semantically overwritten, present the intended diff before editing unless the user explicitly authorized direct execution.

Refresh without accumulation

After a milestone:

1. Re-check the repository and external source of truth.
2. Replace stale current-state facts; do not preserve them as history in the capsule.
3. Update the baseline only after the new result is accepted.
4. Refresh the short handoff after a meaningful phase boundary; split or merge HANDOFF.md according to its current size and volatility.
5. Keep project history in Git, releases, or dedicated decision records—not in GOAL.md or HANDOFF.md.
6. Re-run the deletion audit and validation.

Resume without archaeology

For resume mode:

1. Read GOAL.md, then optional repository AGENTS.md and HANDOFF.md.
2. Check the minimum real state needed to validate the handoff: Git status, relevant entry points, tests, outputs, or external source of truth.
3. State the recovered goal, active stage, discrepancies, and next minimal action.
4. If capsule and reality conflict, treat reality as evidence and pause before changing project identity, boundaries, or accepted baseline.
5. Continue under the existing acceptance standard; do not rebuild project context from scratch unless the capsule demonstrably fails.

Completion check

Before handing off:

• verify a fresh agent can identify the goal, boundaries, evidence, stable baseline, current stage, and next minimal action;
• verify continuation does not require a full-repository archaeology pass or repeated background questions;
• confirm implementation freedom remains explicit;
• run relevant project validation;
• show the capsule diff and what was removed;
• do not commit, push, deploy, tag, or overwrite existing files beyond the user's authorization.