[Plugin] Add agent-session-commit plugin to incrementally iterate on AGENTS.md

AGENTS.md

@@ -0,0 +1,97 @@
+# AGENTS.md
+
+This file provides guidance to AI coding assistants when working with code in this repository.
+
+## Repository Overview
+
+This is the official Claude Code repository - an agentic coding tool CLI that lives in the terminal. The repository contains:
+- Official Claude Code plugins in `plugins/`
+- GitHub automation workflows in `.github/workflows/`
+- Issue management scripts in `scripts/`
+- Example hooks in `examples/hooks/`
+
+## Plugin Architecture
+
+Plugins extend Claude Code with custom commands, agents, skills, and hooks. Each plugin follows this structure:
+
+```
+plugin-name/
+├── .claude-plugin/
+│   └── plugin.json          # Plugin metadata (name, description, version, author)
+├── commands/                 # Slash commands (markdown with YAML frontmatter)
+├── agents/                   # Specialized subagents (markdown with YAML frontmatter)
+├── skills/                   # Agent skills with progressive disclosure
+│   └── skill-name/
+│       ├── SKILL.md         # Core skill documentation
+│       ├── references/      # Detailed reference docs
+│       ├── examples/        # Working examples
+│       └── scripts/         # Utility scripts
+├── hooks/                    # Event handlers (PreToolUse, PostToolUse, Stop, etc.)
+└── README.md
+```
+
+### Key Plugin Concepts
+
+- **Commands**: Slash commands defined in markdown with `allowed-tools` frontmatter for permissions
+- **Agents**: Autonomous subagents with specific tools and system prompts
+- **Skills**: Auto-triggered context loaded when Claude detects relevant phrases
+- **Hooks**: Event-driven automation (PreToolUse, PostToolUse, SessionStart, Stop, etc.)
+- **`${CLAUDE_PLUGIN_ROOT}`**: Variable for portable paths within plugins
+
+## Available Plugins
+
+| Plugin | Purpose |
+|--------|---------|
+| `code-review` | Automated PR review with confidence-based scoring |
+| `plugin-dev` | Toolkit for developing plugins (7 skills, 3 agents) |
+| `feature-dev` | Structured 7-phase feature development workflow |
+| `commit-commands` | Git workflow automation (`/commit`, `/commit-push-pr`) |
+| `hookify` | Create custom hooks from conversation patterns |
+| `agent-sdk-dev` | Agent SDK project setup and verification |
+| `pr-review-toolkit` | Comprehensive PR review agents |
+| `security-guidance` | Security pattern detection hook |
+| `agent-session-commit` | Capture session learnings to AGENTS.md |
+
+## Project-Level Commands
+
+Commands in `.claude/commands/` are available project-wide:
+
+- `/oncall-triage` - Identify critical issues needing oncall attention
+- `/dedupe` - Find duplicate GitHub issues
+- `/commit-push-pr` - Commit, push, and create PR in one step
+
+## GitHub Automation
+
+The repository uses Claude Code for GitHub automation:
+
+- **`@claude` mentions**: Trigger Claude on issues/PRs via `.github/workflows/claude.yml`
+- **Issue triage**: Auto-labeling critical issues with `oncall-triage.yml`
+- **Duplicate detection**: Cross-reference issues with `claude-dedupe-issues.yml`
+- **Auto-close duplicates**: Scripts in `scripts/` manage duplicate issue lifecycle
+
+## Development Environment
+
+### Dev Container
+A sandboxed development environment is available via `.devcontainer/`:
+- Pre-configured with Claude Code, ESLint, Prettier, GitLens
+- Uses zsh with command history persistence
+- Includes firewall initialization for network isolation
+
+### VS Code Extensions
+Recommended extensions in `.vscode/extensions.json`:
+- ESLint, Prettier, Remote Containers, GitLens
+
+## Hook Development
+
+Example hook script in `examples/hooks/bash_command_validator_example.py`:
+- Validates bash commands before execution
+- Exit code 0: Allow, Exit code 1: Show warning, Exit code 2: Block with message to Claude
+- Hook input is JSON on stdin with `tool_name` and `tool_input`
+
+## When Contributing Plugins
+
+1. Follow the standard plugin structure with `.claude-plugin/plugin.json`
+2. Define `allowed-tools` in command frontmatter for security
+3. Use `${CLAUDE_PLUGIN_ROOT}` for portable paths
+4. Include comprehensive README.md with usage examples
+5. For agents, use description with `<example>` blocks for reliable triggering

CLAUDE.md

@@ -0,0 +1,13 @@
+# CLAUDE.md
+
+⚠️ This file is intentionally minimal.
+
+**Authoritative project instructions live in `AGENTS.md`.**
+
+You must:
+
+1. Open and follow `AGENTS.md` before doing any work.
+2. Treat `AGENTS.md` as the single source of truth for all operations.
+3. Update `AGENTS.md` (not this file) when guidelines/architecture/standards change.
+
+➡️ Read now: [AGENTS.md](./AGENTS.md)

plugins/README.md

@@ -13,6 +13,7 @@ Learn more in the [official plugins documentation](https://docs.claude.com/en/do
 | Name | Description | Contents |
 |------|-------------|----------|
 | [agent-sdk-dev](./agent-sdk-dev/) | Development kit for working with the Claude Agent SDK | **Command:** `/new-sdk-app` - Interactive setup for new Agent SDK projects<br>**Agents:** `agent-sdk-verifier-py`, `agent-sdk-verifier-ts` - Validate SDK applications against best practices |
+| [agent-session-commit](./agent-session-commit/) | Capture session learnings to AGENTS.md for cross-tool AI interoperability | **Command:** `/session-commit` - Manually trigger session learning capture<br>**Hook:** Stop - Prompts to capture learnings at session end |
 | [claude-opus-4-5-migration](./claude-opus-4-5-migration/) | Migrate code and prompts from Sonnet 4.x and Opus 4.1 to Opus 4.5 | **Skill:** `claude-opus-4-5-migration` - Automated migration of model strings, beta headers, and prompt adjustments |
 | [code-review](./code-review/) | Automated PR code review using multiple specialized agents with confidence-based scoring to filter false positives | **Command:** `/code-review` - Automated PR review workflow<br>**Agents:** 5 parallel Sonnet agents for CLAUDE.md compliance, bug detection, historical context, PR history, and code comments |
 | [commit-commands](./commit-commands/) | Git workflow automation for committing, pushing, and creating pull requests | **Commands:** `/commit`, `/commit-push-pr`, `/clean_gone` - Streamlined git operations |

plugins/agent-session-commit/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "agent-session-commit",
+  "version": "0.1.0",
+  "description": "Capture session learnings to AGENTS.md for cross-tool AI interoperability",
+  "author": {
+    "name": "Daniel Olshansky",
+    "url": "https://github.com/olshansky"
+  },
+  "repository": "https://github.com/anthropics/claude-code",
+  "license": "MIT",
+  "keywords": ["agents", "claude-md", "session", "learnings", "interoperability"]
+}

plugins/agent-session-commit/README.md

@@ -0,0 +1,69 @@
+# Agent Session Commit
+
+Capture session learnings to `AGENTS.md` for cross-tool AI interoperability.
+
+## Overview
+
+This plugin helps you build a knowledge base that works across AI coding assistants (Claude Code, Cursor, Windsurf, etc.) by:
+
+- **Prompting at session end** to capture valuable learnings
+- **Updating AGENTS.md** with patterns, preferences, and project insights
+- **Initializing AGENTS.md** if it doesn't exist (like `/init` but for AGENTS.md)
+- **Keeping CLAUDE.md minimal** as a pointer to the authoritative AGENTS.md
+
+## Why AGENTS.md?
+
+`AGENTS.md` is an emerging standard for AI-readable project documentation that works across different AI tools. By consolidating your project knowledge in `AGENTS.md`, you get consistent behavior whether using Claude Code, Cursor, Windsurf, or other AI assistants.
+
+`CLAUDE.md` is kept minimal, pointing to `AGENTS.md` as the single source of truth.
+
+## Features
+
+### Stop Hook (Automatic)
+
+When Claude finishes a task, you'll be asked:
+
+> "Would you like to capture learnings from this session to update your AGENTS.md?"
+
+If you agree, Claude will:
+1. Check if AGENTS.md exists (create if missing)
+2. Analyze the session for patterns, preferences, decisions
+3. Propose specific additions to AGENTS.md
+4. Ensure CLAUDE.md exists with pointer content
+
+### `/session-commit` Command (Manual)
+
+Trigger the capture process anytime during a session:
+
+```
+/session-commit
+```
+
+Use this when you want to save learnings mid-session or before exiting.
+
+## What Gets Captured
+
+- **Coding patterns**: Style preferences, naming conventions
+- **Architecture decisions**: Why things are structured a certain way
+- **Gotchas**: Pitfalls discovered during development
+- **Project conventions**: How this codebase does things
+- **Debugging insights**: What to check when things break
+- **Workflow preferences**: How you like to work
+
+## Important: Ctrl+C Behavior
+
+**Note:** The Stop hook triggers when Claude decides a task is complete, NOT on Ctrl+C.
+
+- Hard interrupts (Ctrl+C) may bypass the hook entirely
+- For guaranteed capture, use `/session-commit` before exiting
+- The Stop hook works for normal "task complete" endings
+
+## Installation
+
+The plugin is included in the Claude Code plugins repository. Enable it in your Claude Code settings.
+
+## Configuration
+
+No configuration required. The plugin works out of the box.
+
+To skip the end-of-session prompt, simply decline when asked.

plugins/agent-session-commit/commands/session-commit.md

@@ -0,0 +1,83 @@
+---
+description: Capture learnings from the current session and update AGENTS.md
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - LS
+---
+
+# Session Commit
+
+Analyze the current conversation to extract valuable learnings and update the project's AGENTS.md file.
+
+## Instructions
+
+### Step 1: Check for AGENTS.md
+
+First, check if `AGENTS.md` exists in the project root.
+
+**If AGENTS.md is missing**, initialize it:
+1. Analyze the project structure (package.json, pyproject.toml, Cargo.toml, etc.)
+2. Create `AGENTS.md` with:
+   - Project name and brief description
+   - Key directories and their purposes
+   - Tech stack and dependencies
+   - Any patterns you've observed during this session
+   - Development workflow (build, test, lint commands)
+
+**If AGENTS.md exists**, read it to understand current content.
+
+### Step 2: Analyze Session Learnings
+
+Review the conversation for:
+- Coding patterns and preferences discovered
+- Architecture decisions made
+- Gotchas or pitfalls encountered
+- Project conventions established
+- Debugging insights
+- Workflow preferences
+
+### Step 3: Propose Updates
+
+Present specific additions/updates to the user:
+- Group by category (patterns, conventions, architecture, etc.)
+- Be concise - capture actionable guidance, not verbose explanations
+- Format as bullet points
+- Focus on learnings that help ANY AI assistant, not just Claude
+
+### Step 4: Apply Changes
+
+After user approval:
+- Update AGENTS.md with the approved content
+- Merge with existing content appropriately
+
+### Step 5: Ensure CLAUDE.md Exists
+
+Check if `CLAUDE.md` exists. If missing or different, create/update it with:
+
+```markdown
+# CLAUDE.md
+
+⚠️ This file is intentionally minimal.
+
+**Authoritative project instructions live in `AGENTS.md`.**
+
+You must:
+
+1. Open and follow `AGENTS.md` before doing any work.
+2. Treat `AGENTS.md` as the single source of truth for all operations.
+3. Update `AGENTS.md` (not this file) when guidelines/architecture/standards change.
+
+➡️ Read now: [AGENTS.md](./AGENTS.md)
+```
+
+## Tips
+
+- If no meaningful learnings in this session, say so - don't force updates
+- Prefer bullet points over paragraphs in AGENTS.md
+- Include specific file paths when referencing project structure
+- Avoid duplicating information already in AGENTS.md

plugins/agent-session-commit/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "description": "Occasional tip about /session-commit at session end",
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c '[ $((RANDOM % 5)) -eq 0 ] && echo \"💡 Tip: Run /session-commit to capture session learnings to AGENTS.md\" >&2; exit 0'"
+          }
+        ]
+      }
+    ]
+  }
+}