Session Commit

Analyze the current coding session, propose improvements to AGENTS.md, and apply approved changes.

Workflow

1. Read the current AGENTS.md and build a mental map of existing sections.
2. If the repo documents a validation or repair command for instruction files, run it before proposing edits.
3. Extract only durable learnings from the current session.
4. Propose changes using the format in references/change-proposal-format.md.
5. Wait for explicit user approval before applying any edits.
6. 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

If CLAUDE.md, CODEX.md, or GEMINI.md are missing or empty, create symlinks that point to 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.