littlebearapps · Nathan Schram (nathanschram) · May 6, 2026 · May 6, 2026 · May 6, 2026
diff --git a/.claude/skills/ai-context/SKILL.md b/.claude/skills/ai-context/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ai-context
-description: Generates, updates, and maintains AGENTS-first AI IDE context files with AGENTS.md as canonical shared context and thin tool-specific bridges. Use this skill when the user wants to create a CLAUDE.md, generate AGENTS.md, set up context files for a project, update or fix out-of-date context files, refresh stale CLAUDE.md or AGENTS.md, bootstrap context for a new repo, move or promote MEMORY.md patterns into CLAUDE.md, audit context for drift, or generate cursorrules, copilot instructions, clinerules, windsurfrules, or GEMINI.md. This is the right skill for updating, regenerating, or fixing context files — not just checking them. Use proactively whenever context files may need attention, even if not explicitly requested.
+description: Generates, updates, and maintains AGENTS-first AI IDE context files with AGENTS.md as canonical shared context and thin tool-specific bridges. Works across Claude Code, Codex CLI, Gemini CLI, OpenCode, Cursor, Copilot, Windsurf, and Cline. Use this skill when the user wants to create context files, generate AGENTS.md, set up CLAUDE.md or bridge files for a project, update or fix out-of-date context files, bootstrap context for a new repo, promote MEMORY.md patterns, audit context for drift, or generate cursorrules, copilot instructions, clinerules, windsurfrules, or GEMINI.md. This is the right skill for updating, regenerating, or fixing context files — not just checking them. Use proactively whenever context files may need attention, even if not explicitly requested.
 ---
 
 # AI Context File Generator
@@ -37,14 +37,14 @@ Describe the **end state** you want, not step-by-step instructions. Consider fix
 | File | Role | Purpose |
 |------|------|---------|
 | `AGENTS.md` | Canonical shared context | Shared identity, commands, conventions, constraints, security notes, and monorepo guidance |
-| `CLAUDE.md` | Thin bridge | `@AGENTS.md` import plus Claude-specific rules, key files, and workflow notes |
+| `CLAUDE.md` | Thin bridge | Claude-specific rules, key files, and workflow notes (use `@AGENTS.md` import in Claude Code) |
 | `.cursorrules` | Thin bridge | Cursor-specific rule scoping or metadata only |
 | `.github/copilot-instructions.md` | Thin bridge | Copilot-specific review and PR guidance only |
-| `.windsurfrules` | Compatibility bridge | Windsurf compatibility while AGENTS.md adoption continues |
+| `.windsurfrules` | Thin bridge | Windsurf-specific rule activation or metadata only |
 | `.clinerules` | Thin bridge | Cline-specific autonomy boundaries and commit checklist |
-| `GEMINI.md` | Compatibility bridge | Gemini-specific discovery shim while keeping AGENTS.md canonical |
+| `GEMINI.md` | Thin bridge | Gemini-specific discovery or extension notes only |
 
-**CLAUDE.md vs MEMORY.md:** CLAUDE.md contains instructions *for* Claude (shared via git). MEMORY.md contains notes *by* Claude (local only). Promote recurring MEMORY.md insights to CLAUDE.md.
+**Context file vs memory:** Context files contain instructions *for* the agent (shared via git). Memory files (MEMORY.md, agent-memory/) are notes *by* the agent (local only). Promote recurring memory insights to the appropriate context file.
 
 ## Generation Workflow
 
@@ -57,7 +57,7 @@ Describe the **end state** you want, not step-by-step instructions. Consider fix
 
 **AGENTS.md** (~120 lines): Identity, commands, non-default conventions, hard constraints, security notes, monorepo guidance. Omit Project Structure, architecture, dependency dumps, and key file tables.
 
-**CLAUDE.md** (~10-20 lines, hard max 80): `@AGENTS.md`, then only Claude-specific additions such as `.claude/rules/` references, key file pointers, or path-scoped guidance. Do not restate shared commands and conventions unless Claude-specific formatting requires it.
+**CLAUDE.md** (~10-20 lines, hard max 80): In Claude Code, use `@AGENTS.md` to import the canonical context, then add only Claude-specific additions (`.claude/rules/` references, key file pointers, path-scoped guidance). In other tools, CLAUDE.md is not used — AGENTS.md is loaded directly.
 
 **Other bridge files** (~10-20 lines each, hard max 60): reference or subset `AGENTS.md`, then add only tool-specific fields. Cline may add a `## Before Committing` checklist. `.windsurfrules` and `GEMINI.md` are compatibility bridges for now — keep them especially lean.
 
@@ -90,6 +90,14 @@ Tracks [agents.md spec](https://github.com/agentsmd/agents.md) v1.0 via `upstrea
 - Don't repeat framework docs — agents know React, Express, Django
 - Don't include secrets or session-specific state
 
-## Claude Code Reference
+## Platform Notes
 
-For advanced agent/skill frontmatter fields, variable substitution, dynamic context injection, bundled resource patterns, CLAUDE.md advanced features (@import, directory walking, claudeMdExcludes, managed policy), rules system (path-scoped rules, recursive discovery, user-level rules, symlinks), and plugin system (installation scopes, .lsp.json, output styles, plugin settings), load the companion reference: `SKILL-reference.md`
+**AGENTS.md auto-load:** Codex CLI, OpenCode, Cursor, Windsurf, Cline, and Copilot load AGENTS.md natively. Claude Code requires `@AGENTS.md` in CLAUDE.md. Gemini CLI is configurable via `context.fileName` in settings.json.
+
+**Hooks:** Context Guard hooks are available on Claude Code (12 events), Gemini CLI (11), Copilot (8, preview), Cursor (4+), Cline (3), and Codex CLI (2, experimental). See the context-guard skill for per-platform setup.
+
+**Standalone verification:** Run `bin/context-verify.sh` on any platform for 0-100 health scoring without a plugin system.
+
+## Advanced Reference (Claude Code)
+
+For agent/skill frontmatter fields, variable substitution, dynamic context injection, bundled resources, CLAUDE.md advanced features (@import, directory walking, claudeMdExcludes, managed policy), rules system (path-scoped rules, recursive discovery, symlinks), and plugin system (installation scopes, output styles, plugin settings), load the companion reference: `SKILL-reference.md`
diff --git a/.claude/skills/context-guard/SKILL.md b/.claude/skills/context-guard/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: context-guard
-description: Installs opt-in Claude Code hooks with two-tier enforcement for AI context file freshness. Use this skill when the user wants to install context hooks, set up commit guards for context files, prevent stale CLAUDE.md or AGENTS.md from being committed, detect context drift, add content filter guards for OSS files, check context guard status, or uninstall context hooks. Covers install, install strict, uninstall, and status. Claude Code only — hooks do not work in OpenCode, Codex CLI, or other tools.
+description: Installs context freshness hooks with two-tier enforcement. Full automation on Claude Code (12 hook events). Gemini CLI (11 events), Copilot (8, preview), Cursor (4+), and Cline (3) support hooks with platform-specific setup. Use this skill when the user wants to install context hooks, set up commit guards for context files, prevent stale CLAUDE.md or AGENTS.md from being committed, detect context drift, add content filter guards, check context guard status, or uninstall context hooks. Covers install, install strict, uninstall, and status.
 ---
 
 # Context Guard
@@ -9,7 +9,7 @@ description: Installs opt-in Claude Code hooks with two-tier enforcement for AI
 
 Hooks and a quality rule to keep AI context files in sync with the codebase. Prevents content filter errors on standard OSS files. Two-tier enforcement for context doc freshness.
 
-**Claude Code only.** OpenCode, Codex CLI, Cursor, Windsurf, Cline, and Gemini CLI do not support Claude Code hooks. Cross-tool features (skills, AGENTS.md) work without Context Guard.
+**Primary platform: Claude Code** (full automation, 12 hook events). Other platforms with hook support — Gemini CLI (11 events), Copilot (8, preview), Cursor (4+), Cline (3) — can use adapted hooks from `platforms/` packages (coming soon). For platforms without hooks (Codex CLI, OpenCode, Windsurf), use `bin/context-verify.sh` as a manual or CI-based alternative.
 
 ## Enforcement Tiers
 

diff --git a/.claude/skills/context-verify/SKILL.md b/.claude/skills/context-verify/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: context-verify
-description: Validates AI context file quality with 13 checks and 0-100 health scoring. Use this skill when the user wants to check context file health, validate line budgets, detect stale paths, verify AGENTS-to-bridge consistency, run a context quality audit, score context files for CI, or check for discoverable content and MEMORY.md drift. Use proactively before releases or after structural changes.
+description: Validates AI context file quality with 13 checks and 0-100 health scoring. Works on any platform — also available as a standalone CLI script (bin/context-verify.sh). Use this skill when the user wants to check context file health, validate line budgets, detect stale paths, verify AGENTS-to-bridge consistency, run a context quality audit, score context files for CI, or check for discoverable content and MEMORY.md drift. Use proactively before releases or after structural changes.
 ---
 
 # Context Verifier
@@ -39,9 +39,9 @@ Treat `AGENTS.md` as the canonical shared context. Bridge files may subset or re
 
 If a project MEMORY.md exists, check for convention-like patterns ("Always", "Never", "Use") not yet promoted to CLAUDE.md.
 
-### 6. Context Guard Status
+### 6. Context Guard Status *(Claude Code, Gemini CLI, Copilot, Cursor)*
 
-Check for hook scripts in `.claude/hooks/context-*.sh` and entries in `.claude/settings.json`.
+Check for hook scripts and registration entries. In Claude Code: `.claude/hooks/context-*.sh` and `.claude/settings.json`. Other platforms use their own hook directories.
 
 ### 7. Context Load (Aggregate Token Estimate)
 
@@ -104,6 +104,18 @@ If `.claude-plugin/plugin.json` exists, verify required fields: `name`, `version
 
 Report includes per-dimension breakdown and specific actions to reach grade A.
 
+## Standalone CLI
+
+For platforms without skill support, or for CI pipelines, use the standalone script:
+
+```bash
+bin/context-verify.sh              # Interactive report
+bin/context-verify.sh --ci         # CI mode (exit 1 below threshold)
+bin/context-verify.sh --ci --min-score 90  # Custom threshold
+```
+
+The CLI implements checks 1, 3, 5–14 automatically (bash + git). Check 2 (discoverable content) and check 4 (bridge consistency) are partially automated — full semantic analysis requires this AI-powered skill.
+
 ## CI Integration
 
-With `ci` argument, output machine-readable format and exit code 1 on failures. Accept `--min-score N` to fail the CI job below a threshold.
+With `ci` argument (skill or CLI), output machine-readable format and exit code 1 on failures. Accept `--min-score N` to fail the CI job below a threshold.
diff --git a/AGENTS.md b/AGENTS.md
@@ -19,9 +19,9 @@ Skills are loaded on-demand. Each lives at `.claude/skills/<name>/SKILL.md`. The
 
 | Skill | What It Provides |
 |-------|-----------------|
-| `ai-context` | AGENTS-first AI IDE context generation — builds canonical `AGENTS.md`, then emits thin bridges for Claude, Copilot, Cursor, Windsurf, Cline, and Gemini, with init/update/promote/audit lifecycle support |
-| `context-guard` | Context Guard hook installation — two-tier enforcement, SessionStart health check, settings.json configuration, companion reference for 17 hook events and 4 handler types, troubleshooting *(Claude Code only)* |
-| `context-verify` | Context file validation — line budgets, discoverable content detection, stale paths, @import validation, rule path-scope and symlink checks, .mcp.json validation, agent memory hygiene, plugin manifest completeness, AGENTS-to-bridge consistency, aggregate context load, and 0–100 health scoring with CI integration |
+| `ai-context` | AGENTS-first AI IDE context generation across 8 tools — builds canonical `AGENTS.md`, then emits thin bridges for Claude, Copilot, Cursor, Windsurf, Cline, and Gemini, with init/update/promote/audit lifecycle support |
+| `context-guard` | Context Guard hook installation — two-tier enforcement, SessionStart health check, settings.json configuration, companion reference for 17 hook events and 4 handler types, troubleshooting. Primary: Claude Code (12 events); cross-platform: Gemini CLI (11), Copilot (8), Cursor (4+), Cline (3) |
+| `context-verify` | Context file validation — line budgets, discoverable content detection, stale paths, @import validation, rule path-scope and symlink checks, .mcp.json validation, agent memory hygiene, plugin manifest completeness, AGENTS-to-bridge consistency, aggregate context load, and 0–100 health scoring with CI integration. Also available as standalone CLI (`bin/context-verify.sh`) |
 
 ## Workflow Commands
 
@@ -30,7 +30,7 @@ Invoke as `/contextdocs:command-name` in Claude Code, or as prompts in Codex CLI
 | Command | What It Does |
 |---------|-------------|
 | `ai-context` | Generate AGENTS-first AI context using Signal Gate — supports `all`, `claude`, `agents`, `cursor`, `copilot`, `windsurf`, `cline`, `gemini`, `init`, `update`, `promote`, `audit` |
-| `context-guard` | Install, uninstall, or check status of Context Guard hooks with tiered enforcement *(Claude Code only)* |
+| `context-guard` | Install, uninstall, or check status of Context Guard hooks with tiered enforcement — primarily Claude Code, with cross-platform hooks for Gemini CLI, Copilot, Cursor, and Cline |
 | `context-verify` | Validate context file quality — line budgets, stale paths, bridge consistency, health scoring, CI integration |
 
 ## Rules (Claude Code Only)
@@ -40,9 +40,9 @@ Invoke as `/contextdocs:command-name` in Claude Code, or as prompts in Codex CLI
 - `doc-standards.md` — documentation quality standards, 4-Question Test, Lobby Principle, banned phrases (auto-loaded, PitchDocs)
 - `docs-awareness.md` — documentation trigger map, suggests PitchDocs commands when docs-relevant work is detected (auto-loaded, PitchDocs)
 
-## Hooks (Claude Code Only)
+## Hooks
 
-7 opt-in hooks, installed via `/contextdocs:context-guard install`. Hooks reference the context-updater agent for autonomous action:
+7 opt-in hooks for Claude Code, installed via `/contextdocs:context-guard install`. Adapted hooks for Gemini CLI, Copilot, Cursor, and Cline via `platforms/` packages (coming soon). For platforms without hooks, use `bin/context-verify.sh` as a CI-based alternative.
 
 - `context-session-start.sh` — session-start context health check (advisory)
 - `context-forced-eval.sh` — keyword-gated skill evaluation on context-related prompts (advisory)