diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..d8141ba32b --- /dev/null +++ b/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 `` blocks for reliable triggering diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..ed57e1774f --- /dev/null +++ b/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) diff --git a/plugins/README.md b/plugins/README.md index cf4a21ecc5..d8f6bc5f08 100644 --- a/plugins/README.md +++ b/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
**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
**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
**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 | diff --git a/plugins/agent-session-commit/.claude-plugin/plugin.json b/plugins/agent-session-commit/.claude-plugin/plugin.json new file mode 100644 index 0000000000..7580f25ad8 --- /dev/null +++ b/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"] +} diff --git a/plugins/agent-session-commit/README.md b/plugins/agent-session-commit/README.md new file mode 100644 index 0000000000..7ba4074bf7 --- /dev/null +++ b/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. diff --git a/plugins/agent-session-commit/commands/session-commit.md b/plugins/agent-session-commit/commands/session-commit.md new file mode 100644 index 0000000000..11bf45893b --- /dev/null +++ b/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 diff --git a/plugins/agent-session-commit/hooks/hooks.json b/plugins/agent-session-commit/hooks/hooks.json new file mode 100644 index 0000000000..db9520f0ab --- /dev/null +++ b/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'" + } + ] + } + ] + } +}