Session Commit

AGENTS.md

Available scripts

• scripts/preflight.sh

  - Checks whether required instruction files exist and optionally repairs missing files.

Workflow

1. Run preflight checks:

bash scripts/preflight.sh

1. If preflight fails and user approves repairs, run:

bash scripts/preflight.sh --fix

1. Read the current

   AGENTS.md

   and build a mental map of existing sections.
2. Extract only durable learnings from the current session.
3. Propose changes using the format in

   references/change-proposal-format.md

   .
4. Wait for explicit user approval before applying any edits.
5. Apply approved changes and merge with existing content.

What to capture

• Coding patterns and conventions established in the session
• Architecture decisions and reasoning that should persist
• Debugging playbooks and recurring gotchas
• Workflow preferences that improve future sessions

Guardrails

• Do not capture transient implementation details that will age quickly.
• Prefer updating existing sections before creating new headings.
• Use concise bullet points rather than long paragraphs.
• Keep guidance tool-agnostic unless behavior differs by tool.
• If no meaningful learning occurred, report that and stop.

Pointer file behavior

CLAUDE.md

CODEX.md

GEMINI.md

AGENTS.md

Output contract

• Proposal stage: output only proposed changes with explicit add/modify/remove counts.
• Apply stage: update

  AGENTS.md

  only after explicit approval.
• Completion stage: summarize what changed and where.