feat: context-updater agent, token budget compliance, headless mode docs

.claude/agents/context-updater.md

@@ -0,0 +1,98 @@
+---
+name: context-updater
+description: "Automatically updates stale AI context files (CLAUDE.md, AGENTS.md, llms.txt, etc.) after structural project changes. Launch when hooks detect context drift, when a commit guard blocks, or before session end. Do NOT launch during debugging, mid-task coding, or for trivial changes."
+tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Write
+  - Edit
+---
+
+# Context Updater Agent
+
+You are an autonomous agent that updates AI context files after structural project changes. You apply the Signal Gate principle — only include what agents cannot discover by reading source code.
+
+## When You Are Launched
+
+You are typically launched by Claude Code in response to:
+- A **Stop hook** reporting context drift before session end
+- A **commit guard** blocking a commit due to missing context updates
+- A **PostToolUse hook** reporting structural file changes after the primary task is complete
+
+## Workflow
+
+### Step 1: Detect What Changed
+
+```bash
+# Find structural files with uncommitted changes
+git status --porcelain | grep -E '(commands/.*\.md|\.claude/skills/.*/SKILL\.md|\.claude/agents/.*\.md|\.claude/rules/.*\.md|package\.json|pyproject\.toml|Cargo\.toml|go\.mod|tsconfig.*\.json|wrangler\.toml|vitest\.config|jest\.config|eslint\.config|biome\.json|\.claude-plugin/plugin\.json)'
+```
+
+### Step 2: Identify Affected Context Files
+
+| Structural Change | Context Files to Update |
+|-------------------|------------------------|
+| `commands/*.md` added/removed/modified | AGENTS.md, CLAUDE.md, llms.txt |
+| `.claude/skills/*/SKILL.md` added/removed/modified | AGENTS.md, CLAUDE.md, llms.txt |
+| `.claude/agents/*.md` added/removed/modified | AGENTS.md |
+| `.claude/rules/*.md` added/removed/modified | CLAUDE.md, AGENTS.md |
+| `package.json`, `pyproject.toml`, config files | All context files (commands may have changed) |
+
+### Step 3: Read Current State
+
+For each affected context file that exists on disk:
+1. Read the current content
+2. Compare against the actual project state (count skills, commands, agents, rules)
+3. Identify specific sections that need updating (counts, tables, listings)
+
+### Step 4: Apply Surgical Edits
+
+Use **Edit** (not Write) to update only the affected sections. Preserve all human-authored content.
+
+- Update counts (e.g., "3 skills" → "4 skills")
+- Update tables (add/remove rows for new/deleted components)
+- Update command listings
+- Fix stale file path references
+
+### Step 5: Verify Quality
+
+After editing, verify:
+1. **Line budgets**: CLAUDE.md <80, AGENTS.md <120, others <60
+2. **Path accuracy**: Every backtick-quoted path in context files exists on disk
+3. **Consistency**: Commands, counts, and conventions match across all context files
+
+```bash
+# Quick line count check
+wc -l CLAUDE.md AGENTS.md 2>/dev/null
+```
+
+### Step 6: Report
+
+Report what was updated in this format:
+```
+Context files updated:
+  AGENTS.md — added skill "pdf-processing" to table, updated count 3→4
+  CLAUDE.md — updated skill count in modification guide
+  llms.txt — added skill reference
+```
+
+## Signal Gate Rules
+
+**Include** in context files: conventions, commands, hard constraints, security rules, environment quirks.
+
+**Exclude** from context files: directory listings, file trees, dependency lists, architecture overviews, framework conventions.
+
+## Loop Prevention
+
+- If you detect a `.git/.context-updater-running` flag file, exit immediately — another instance is already running
+- Create `.git/.context-updater-running` at start, remove it when done
+- If context files were modified more recently than structural files, skip — already up to date
+
+## Scope Limits
+
+- Only update context files that already exist. Do not create new ones (use `/contextdocs:ai-context init` for that)
+- Only update sections affected by the structural change. Do not rewrite entire files
+- Do not update MEMORY.md — that is Claude's auto-memory, not a context file
+- Do not run full codebase analysis — that is the `ai-context` skill's job. You do targeted, incremental patching

.claude/hooks/context-commit-guard.sh

@@ -75,7 +75,7 @@ done <<< "$STAGED_FILES"
 
 # Block commit if structural changes without context updates
 if [ "$HAS_CONTEXT" = false ]; then
-  echo "COMMIT BLOCKED: Structural files (commands, skills, rules, or config) are staged but no AI context docs (CLAUDE.md, AGENTS.md, llms.txt, etc.) were updated. Update and stage the relevant context files before committing. Run /contextdocs:ai-context audit to check what needs updating, or /contextdocs:ai-context to regenerate." >&2
+  echo "COMMIT BLOCKED: Structural files (commands, skills, rules, or config) are staged but no AI context docs (CLAUDE.md, AGENTS.md, llms.txt, etc.) were updated. Launch the context-updater agent (defined in .claude/agents/context-updater.md) to update context files, then stage them and retry the commit." >&2
   exit 2
 fi
 

.claude/hooks/context-drift-check.sh

@@ -88,7 +88,7 @@ if [ ${#ISSUES[@]} -gt 0 ]; then
   for I in "${ISSUES[@]}"; do
     MSG="$MSG\n$I"
   done
-  MSG="$MSG\nRun /contextdocs:ai-context audit to check, or /contextdocs:ai-context to regenerate."
+  MSG="$MSG\nLaunch the context-updater agent to fix these issues, or run /contextdocs:ai-context audit for a full check."
 
   # Escape for JSON
   MSG_JSON=$(printf '%s' "$MSG" | sed 's/"/\\"/g')

.claude/hooks/context-guard-stop.sh

@@ -76,12 +76,23 @@ while IFS= read -r FILE; do
   esac
 done <<< "$CHANGED_FILES"
 
-# If structural changes exist without context updates, nudge
+# Collect which structural files changed for the agent
+STRUCTURAL_LIST=""
+while IFS= read -r FILE; do
+  case "$FILE" in
+    .claude/hooks/*|.claude/rules/context-quality.md|.claude/settings.json) continue ;;
+    commands/*.md|.claude/skills/*/SKILL.md|.agents/skills/*/SKILL.md|.claude/agents/*.md|.agents/agents/*.md|.claude/rules/*.md|package.json|pyproject.toml|Cargo.toml|go.mod|tsconfig*.json|wrangler.toml|vitest.config*|jest.config*|eslint.config*|biome.json|.claude-plugin/plugin.json)
+      STRUCTURAL_LIST="$STRUCTURAL_LIST\n  - $FILE"
+      ;;
+  esac
+done <<< "$CHANGED_FILES"
+
+# If structural changes exist without context updates, instruct agent launch
 if [ "$HAS_CONTEXT" = false ]; then
-  cat << 'EOF'
+  cat << EOF
 {
   "decision": "block",
-  "reason": "CONTEXT DOC NUDGE: You modified structural files (commands, skills, rules, or config) but no AI context files (CLAUDE.md, AGENTS.md, llms.txt, etc.) were updated. Consider updating relevant context docs before finishing. Run /contextdocs:ai-context audit to check what needs updating, or /contextdocs:ai-context to regenerate. If context docs genuinely don't need changes, you can finish — this is advisory only."
+  "reason": "CONTEXT DRIFT DETECTED — structural files changed this session without context file updates:\\n$STRUCTURAL_LIST\\n\\nAffected context files likely include: AGENTS.md, CLAUDE.md, llms.txt\\n\\nACTION REQUIRED: Launch the context-updater agent (defined in .claude/agents/context-updater.md) to update these files before ending the session. The agent will apply surgical edits to only the affected sections. If context docs genuinely don't need changes, you can finish — this is advisory only."
 }
 EOF
   exit 0

.claude/hooks/context-structural-change.sh

@@ -70,7 +70,7 @@ if [ -n "$MSG" ]; then
 {
   "hookSpecificOutput": {
     "hookEventName": "PostToolUse",
-    "additionalContext": "CONTEXT REMINDER: $MSG_JSON Run /contextdocs:ai-context audit to check."
+    "additionalContext": "CONTEXT REMINDER: $MSG_JSON When your current task is complete, launch the context-updater agent to apply these updates automatically."
   }
 }
 EOF

.claude/rules/context-awareness.md

@@ -1,22 +1,33 @@
 # Context Awareness
 
-When working on a project with ContextDocs installed, recognise moments when AI context files may need attention and suggest the appropriate command. This is advisory — never block work, just surface the right tool at the right time.
+Recognise when AI context files may need attention and suggest the appropriate command. Advisory only — never block work.
 
 ## Context Trigger Map
 
-| You Notice | Suggest | Why |
-|-----------|---------|-----|
-| Structural files changed (skills, commands, agents, rules, config) | `/contextdocs:ai-context audit` | AI context files may reference stale paths or counts |
-| New dependency or framework added | `/contextdocs:ai-context` | Context files should reflect the current tech stack |
-| MEMORY.md contains repeated project conventions or stable patterns | `/contextdocs:ai-context promote` | Promote stable auto-memory insights to CLAUDE.md where the whole team benefits |
-| Test runner, linter, or formatter changed | `/contextdocs:ai-context update` | Commands in context files may reference outdated tooling |
-| Source files renamed or moved | `/contextdocs:context-verify` | Context files may reference stale paths |
-| Project going public or onboarding new contributors | `/contextdocs:ai-context init` | Bootstrap context files so every AI tool understands the project from day one |
-| Pre-release or version bump | `/contextdocs:context-verify` | Verify context files are current before shipping |
+| You Notice | Suggest |
+|-----------|---------|
+| Structural files changed (skills, commands, agents, rules, config) | `/contextdocs:ai-context audit` |
+| New dependency or framework added | `/contextdocs:ai-context` |
+| MEMORY.md contains stable patterns | `/contextdocs:ai-context promote` |
+| Test runner, linter, or formatter changed | `/contextdocs:ai-context update` |
+| Source files renamed or moved | `/contextdocs:context-verify` |
+| Project going public or onboarding contributors | `/contextdocs:ai-context init` |
+| Pre-release or version bump | `/contextdocs:context-verify` |
+
+## Autonomous Actions (Claude Code Only)
+
+When Context Guard hooks are installed, act on these triggers without waiting for user instruction:
+
+| Trigger | Action |
+|---------|--------|
+| Stop hook reports context drift | Launch `context-updater` agent before ending session |
+| Commit guard blocks a commit | Launch `context-updater` agent, stage files, retry commit |
+| PostToolUse reports structural change AND current task is complete | Launch `context-updater` agent before reporting completion |
+
+The agent (`.claude/agents/context-updater.md`) applies surgical edits, not full regeneration. Do not launch during debugging, mid-task, or for trivial changes.
 
 ## When NOT to Suggest
 
-- During debugging, testing, or CI troubleshooting — stay focused on the immediate problem
-- When the user is mid-flow on a complex coding task — wait for a natural pause
-- When the same suggestion was already made this session — don't repeat
-- For trivial code changes (typos, formatting) that don't affect context files
+- During debugging, testing, or CI troubleshooting
+- Mid-flow on a complex coding task — wait for a natural pause
+- Same suggestion already made this session

.claude/rules/context-quality.md

@@ -4,45 +4,24 @@ When generating or updating AI context files (CLAUDE.md, AGENTS.md, GEMINI.md, .
 
 ## Cross-File Consistency
 
-All context files for a project must agree on:
+All context files must agree on: language/framework version, key commands (test, build, lint, deploy), directory structure, naming conventions, and critical rules. When updating one, check and update others.
 
-- Language and framework version
-- Key commands (test, build, lint, deploy)
-- Directory structure and key file paths
-- Naming conventions and coding standards
-- Critical rules and constraints
+## Path and Command Verification
 
-When updating one context file, check if the same information appears in others and update them too.
-
-## Path Verification
-
-Every file path mentioned in a context file must exist on disk. Before writing a context file, verify referenced paths:
-
-```bash
-test -f "path/to/file" || echo "WARN: path does not exist"
-```
-
-Never reference deleted files, renamed modules, or moved directories without checking first.
+Every file path in a context file must exist on disk. Every command must be runnable — verify against `package.json` scripts, `Makefile` targets, or `pyproject.toml` scripts before writing.
 
 ## Version Accuracy
 
-Context files must reference the correct:
-
-- Language runtime version (from `.nvmrc`, `engines`, `requires-python`, `go.mod`)
-- Framework version (from `package.json`, `pyproject.toml`)
-- Test runner (jest vs vitest vs pytest vs go test)
-- Linter/formatter (eslint vs biome, ruff vs flake8)
-
-## Command Accuracy
-
-Every command listed in a context file (test, build, lint, deploy) must be runnable. Verify against `package.json` scripts, `Makefile` targets, or `pyproject.toml` scripts before writing.
+Reference correct language runtime (from `.nvmrc`, `engines`, `requires-python`, `go.mod`), framework version (from manifests), test runner, and linter/formatter.
 
 ## Sync Points
 
 When project structure, dependencies, commands, or conventions change, update all context files that reference the affected content. Load the `ai-context` skill for the full sync matrix.
 
 ## Tool Compatibility
 
-Not all context files work in all tools. Key distinctions: `AGENTS.md` works in Claude Code, OpenCode, Codex CLI, and Gemini CLI. `CLAUDE.md` works in Claude Code and OpenCode. `.cursorrules`, `.windsurfrules`, `.clinerules`, `GEMINI.md`, and `.github/copilot-instructions.md` are tool-specific. `.claude/rules/*.md` and hooks are Claude Code only. `MEMORY.md` is auto-written by Claude — not user-authored, not version-controlled. For GitLab/Bitbucket projects, generate only tool-agnostic context files.
+`AGENTS.md`: Claude Code, OpenCode, Codex CLI, Gemini CLI. `CLAUDE.md`: Claude Code, OpenCode. `.cursorrules`, `.windsurfrules`, `.clinerules`, `GEMINI.md`, `copilot-instructions.md`: tool-specific. `.claude/rules/*.md` and hooks: Claude Code only. `MEMORY.md`: auto-written by Claude, not version-controlled.
+
+## Aggregate Context Load
 
-For context file size guidance and the Signal Gate principle, load the `ai-context` skill.
+Thresholds per tool: <5,000 tokens healthy, 5,000–10,000 warning, >10,000 needs refactoring. Use `context-verify` to check. See context-verify skill for per-tool load paths and detailed reporting.