context-capsule

The whole job: reconcile, write the capsule, confirm it, then stop.

A capsule is a small markdown file with YAML frontmatter. A fresh session reads three fields from it and continues. It is state for the next session, not a transcript of this one.

Steps

1. Reconcile from live state. Look at what is actually true now: git status, git log -n 5, the files you changed, any task list. Budget: 2 to 4 reads. Record what happened, not what was said. A capsule that restates the conversation instead of the repo state is the failure this skill exists to prevent.

2. Write it with the helper, which stamps the date, validates the fields and writes into the configured capsule directory:

   node "${CLAUDE_PLUGIN_ROOT}/scripts/capsule-lib.mjs" write \
     --objective "<what this work is for, one sentence>" \
     --waiting-on "<concrete items, owners, gates a fresh session must know>" \
     --next-action "<the one next step, specific enough to act on cold>" \
     --slug "<short-topic>" \
     --dir '${user_config.capsuleDir}'
   

   Run it from the project directory (do not cd elsewhere) and keep the --dir line exactly as written, single quotes included (they stop the shell expanding the placeholder when the option is unset). A configured path that itself contains a single quote is not supported. It carries the configured capsule directory. If the directory option is not set, that value is empty or still reads ${user_config.capsuleDir} literally; then drop the --dir line and the helper uses the project default.

   Optional: --body-file <path> with your own body sections (see Format).

3. Confirm. The helper prints the path it wrote. Run node "${CLAUDE_PLUGIN_ROOT}/scripts/capsule-lib.mjs" validate <that path> and expect VALID. If it prints INVALID, fix the fields and write again.

4. Stop. Tell the user the capsule path in one line. If they asked for /refresh, tell them to run /clear next.

Field rules

• objective, waiting_on, next_valid_action are required and must be non-empty. waiting_on is the resume contract: write it so a fresh session can act from it alone.
• next_valid_action must be a real action, not "resume the session" or "re-read the state". The helper refuses ceremony text.
• Do not paste secrets, tokens or credentials into a capsule. It is a plain file in the project.

Format

Frontmatter fields: id, parent_capsule_id, status: active, objective, waiting_on, resume_trigger, expires, trigger, next_valid_action, success_criteria, tags, created_at (ISO-8601 with offset), resolved_at. Body sections: Done (don't redo), Historical-Errors -> Resolutions, Historical-Rejected-Approaches, Files-Read / Files-Modified, Operating-Facts, Pending-Gates, Claimed-Rows. The format is compatible with the full aigent-os install.

Lifecycle

active then resumed (set automatically by the SessionStart hook when a /clear loads it) then done. Never edit status by hand. Capsules older than 14 days (plugin option maxAgeDays, or the CONTEXT_CAPSULE_MAX_AGE_DAYS env var, to change) are refused at resume with a message, not loaded.

When not to capsule

Mid-thought (finish the thought first), or a trivial session a fresh start can rebuild from the repo.