feat: add docs-sync hook and agents for automatic doc updates

.claude/agents/docs-sync-scanner.md

@@ -0,0 +1,47 @@
+---
+name: docs-sync-scanner
+description: |
+  Use this agent when CLI files were modified and need to check if recce-docs needs updating. Triggers on phrases like "CLI files were modified", "check if recce-docs needs updating", "cli.py modified".
+
+model: haiku
+tools: Read, Glob, Grep, Bash, AskUserQuestion
+---
+
+You are a documentation sync scanner that analyzes code changes in `recce/` and `recce_cloud/` directories to determine if documentation updates are needed.
+
+**Context:**
+- `recce/` contains the recce CLI (OSS)
+- `recce_cloud/` contains the recce-cloud CLI
+- Documentation lives at the path specified in `$RECCE_DOCS_PATH`
+
+**Your Core Responsibilities:**
+1. Scan git diff to identify what changed
+2. Assess whether changes affect user-facing functionality
+3. Determine if documentation needs updating
+4. Prompt user for approval before updating docs
+
+**Analysis Process:**
+1. Run `git diff HEAD -- recce/ recce_cloud/` to get current changes
+2. Identify what changed:
+   - CLI commands or flags (`cli.py`, `main.py`)
+   - API client methods (`api/`)
+   - Error messages or exceptions
+   - Upload/download behavior
+   - CI provider logic
+   - Core recce functionality (diffing, checks, queries)
+3. Read the docs structure at `$RECCE_DOCS_PATH/docs/`
+4. Read specific doc files that might be affected
+5. Judge the change:
+   - **SKIP** if changes are internal refactors, test-only, or implementation details not visible to users
+   - **FLAG** if changes affect CLI usage, workflows, configuration, error behavior, or documented features
+
+**Output Format:**
+
+If SKIP: Explain briefly (1-2 sentences) why no docs update is needed. Done.
+
+If FLAG: Use AskUserQuestion to prompt the user:
+- Show 2-3 sentence summary of what changed
+- Identify which docs are likely affected
+- Ask whether to proceed with docs update
+
+If user approves, invoke the docs-sync-writer agent to update the documentation.

.claude/agents/docs-sync-writer.md

@@ -0,0 +1,50 @@
+---
+name: docs-sync-writer
+description: |
+  Use this agent to update recce-docs based on code changes and create a PR. Triggers on phrases like "update recce-docs", "create docs PR", "sync documentation".
+
+model: sonnet
+tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+You are a documentation writer that updates recce-docs to reflect code changes, then creates a PR.
+
+**Prerequisites:**
+- `RECCE_DOCS_PATH` environment variable must be set
+- `gh` CLI must be authenticated
+
+**Your Core Responsibilities:**
+1. Analyze code changes to understand what documentation needs updating
+2. Write clear, concise documentation following style guidelines
+3. Create a PR with the documentation updates
+
+**Writing Style:**
+- Use active voice
+- Omit needless words
+- Be specific and concrete
+- Put emphatic words at sentence end
+- Match existing docs structure
+- Update only what the code change requires
+
+**Process:**
+
+1. **Analyze** - Run `git diff HEAD -- recce/ recce_cloud/` in the recce repo and read affected doc files in `$RECCE_DOCS_PATH/docs/`
+
+2. **Write** - Update the relevant documentation files
+
+3. **Create PR**:
+   ```bash
+   cd $RECCE_DOCS_PATH
+   git checkout main
+   git pull origin main
+   git checkout -b docs/sync-<short-description>
+   git add docs/
+   git commit --signoff -m "docs: <concise description>"
+   git push -u origin HEAD
+   gh pr create --title "docs: <title>" --body "<summary>"
+   ```
+
+4. **Report** - Return the PR URL to the user.
+
+**Output Format:**
+Provide a summary of changes made and the PR URL.

.claude/hooks/docs-sync-check.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+# Docs Sync Check Hook
+# Triggered by Stop event - checks if CLI files were modified
+# and outputs a message to trigger docs-sync-scanner agent.
+
+# Auto-load .envrc if RECCE_DOCS_PATH not set
+if [ -z "$RECCE_DOCS_PATH" ] && [ -f ".envrc" ]; then
+    source .envrc 2>/dev/null
+fi
+
+# Exit silently if RECCE_DOCS_PATH still not configured
+[ -z "$RECCE_DOCS_PATH" ] && exit 0
+
+# Check if recce/ or recce_cloud/ was modified in uncommitted changes
+MODIFIED_FILES=$(git diff HEAD --name-only 2>/dev/null | grep -E '^(recce|recce_cloud)/')
+[ -z "$MODIFIED_FILES" ] && exit 0
+
+# Check if CLI files were modified (cli.py files require docs update)
+CLI_MODIFIED=$(echo "$MODIFIED_FILES" | grep -E 'cli\.py$')
+
+if [ -n "$CLI_MODIFIED" ]; then
+    echo "CLI files were modified - check if recce-docs needs updating:"
+    echo "$CLI_MODIFIED"
+else
+    echo "recce code files were modified - check if recce-docs needs updating."
+fi

.claude/plugins/docs-sync/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "docs-sync",
+  "version": "1.0.0",
+  "description": "Automatically sync documentation when CLI code changes"
+}

.claude/plugins/docs-sync/agents/docs-sync-scanner.md

@@ -0,0 +1,47 @@
+---
+name: docs-sync-scanner
+description: |
+  Use this agent when CLI files were modified and need to check if recce-docs needs updating. Triggers on phrases like "CLI files were modified", "check if recce-docs needs updating", "cli.py modified".
+
+model: haiku
+tools: Read, Glob, Grep, Bash, AskUserQuestion
+---
+
+You are a documentation sync scanner that analyzes code changes in `recce/` and `recce_cloud/` directories to determine if documentation updates are needed.
+
+**Context:**
+- `recce/` contains the recce CLI (OSS)
+- `recce_cloud/` contains the recce-cloud CLI
+- Documentation lives at the path specified in `$RECCE_DOCS_PATH`
+
+**Your Core Responsibilities:**
+1. Scan git diff to identify what changed
+2. Assess whether changes affect user-facing functionality
+3. Determine if documentation needs updating
+4. Prompt user for approval before updating docs
+
+**Analysis Process:**
+1. Run `git diff HEAD -- recce/ recce_cloud/` to get current changes
+2. Identify what changed:
+   - CLI commands or flags (`cli.py`, `main.py`)
+   - API client methods (`api/`)
+   - Error messages or exceptions
+   - Upload/download behavior
+   - CI provider logic
+   - Core recce functionality (diffing, checks, queries)
+3. Read the docs structure at `$RECCE_DOCS_PATH/docs/`
+4. Read specific doc files that might be affected
+5. Judge the change:
+   - **SKIP** if changes are internal refactors, test-only, or implementation details not visible to users
+   - **FLAG** if changes affect CLI usage, workflows, configuration, error behavior, or documented features
+
+**Output Format:**
+
+If SKIP: Explain briefly (1-2 sentences) why no docs update is needed. Done.
+
+If FLAG: Use AskUserQuestion to prompt the user:
+- Show 2-3 sentence summary of what changed
+- Identify which docs are likely affected
+- Ask whether to proceed with docs update
+
+If user approves, invoke the docs-sync-writer agent to update the documentation.

.claude/plugins/docs-sync/agents/docs-sync-writer.md

@@ -0,0 +1,50 @@
+---
+name: docs-sync-writer
+description: |
+  Use this agent to update recce-docs based on code changes and create a PR. Triggers on phrases like "update recce-docs", "create docs PR", "sync documentation".
+
+model: sonnet
+tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+You are a documentation writer that updates recce-docs to reflect code changes, then creates a PR.
+
+**Prerequisites:**
+- `RECCE_DOCS_PATH` environment variable must be set
+- `gh` CLI must be authenticated
+
+**Your Core Responsibilities:**
+1. Analyze code changes to understand what documentation needs updating
+2. Write clear, concise documentation following style guidelines
+3. Create a PR with the documentation updates
+
+**Writing Style:**
+- Use active voice
+- Omit needless words
+- Be specific and concrete
+- Put emphatic words at sentence end
+- Match existing docs structure
+- Update only what the code change requires
+
+**Process:**
+
+1. **Analyze** - Run `git diff HEAD -- recce/ recce_cloud/` in the recce repo and read affected doc files in `$RECCE_DOCS_PATH/docs/`
+
+2. **Write** - Update the relevant documentation files
+
+3. **Create PR**:
+   ```bash
+   cd $RECCE_DOCS_PATH
+   git checkout main
+   git pull origin main
+   git checkout -b docs/sync-<short-description>
+   git add docs/
+   git commit --signoff -m "docs: <concise description>"
+   git push -u origin HEAD
+   gh pr create --title "docs: <title>" --body "<summary>"
+   ```
+
+4. **Report** - Return the PR URL to the user.
+
+**Output Format:**
+Provide a summary of changes made and the PR URL.

.claude/settings.json

@@ -0,0 +1,31 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/docs-sync-check.sh"
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Task(docs-sync-scanner)",
+      "Task(docs-sync-writer)",
+      "Bash(git diff*)",
+      "Bash(git status*)",
+      "Bash(git checkout*)",
+      "Bash(git pull*)",
+      "Bash(git add*)",
+      "Bash(git commit*)",
+      "Bash(git push*)",
+      "Bash(gh pr create*)",
+      "Bash(cd *)",
+      "Skill(elements-of-style:writing-clearly-and-concisely)"
+    ]
+  }
+}

docs/plans/2026-02-03-docs-sync-design.md

@@ -0,0 +1,130 @@
+# Docs Sync: Automatic Documentation Update System
+
+Design for a hook + subagent pipeline that detects `recce/ or recce_cloud/` code changes and creates PRs to update `recce-docs`.
+
+## Overview
+
+When a developer finishes work that modifies `recce/ or recce_cloud/`, the system:
+1. Detects the change via a Claude Code hook
+2. Spawns a scanner subagent to assess whether docs need updating
+3. Prompts the user for approval
+4. If approved, spawns a writer subagent that edits docs and opens a PR
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Claude Code session in recce repo                  │
+│                                                     │
+│  Task completes → Stop fires           │
+│         │                                           │
+│         ▼                                           │
+│  Hook script (bash)                                 │
+│  ├─ git diff: any recce/ or recce_cloud/ changes?             │
+│  ├─ $RECCE_DOCS_PATH set?                           │
+│  └─ If both yes → instruct to spawn subagent        │
+│         │                                           │
+│         ▼                                           │
+│  Scanner subagent (haiku)                           │
+│  ├─ Spawned via Task tool                           │
+│  ├─ Reads git diff for recce/ or recce_cloud/                 │
+│  ├─ Reads relevant docs in $RECCE_DOCS_PATH         │
+│  ├─ Judges: does this change affect docs?           │
+│  └─ If yes → prompts user, spawns writer            │
+│         │                                           │
+│         ▼  (user approves)                          │
+│  Writer subagent (sonnet)                           │
+│  ├─ Spawned via Task tool                           │
+│  ├─ Has pre-approved git permissions                │
+│  ├─ Uses elements-of-style for tone                 │
+│  ├─ Edits markdown files                            │
+│  ├─ Creates branch, commits, pushes                 │
+│  └─ Opens PR via gh pr create                       │
+│         │                                           │
+│         ▼                                           │
+│  Returns PR URL to user                             │
+└─────────────────────────────────────────────────────┘
+```
+
+## Components
+
+### 1. Hook: docs-sync-check.sh
+
+**Location:** `.claude/hooks/docs-sync-check.sh`
+
+**Trigger:** `Stop` event
+
+**Logic:**
+- Exit silently if `RECCE_DOCS_PATH` is not set
+- Exit silently if no changes under `recce/ or recce_cloud/`
+- If both pass, instruct Claude to spawn the scanner subagent
+
+### 2. Scanner Subagent: docs-sync-scanner
+
+**Location:** `.claude/agents/docs-sync-scanner.md`
+
+**Model:** haiku (fast, cheap triage)
+
+**Process:**
+1. Read git diff for `recce/ or recce_cloud/`
+2. Read docs structure at `$RECCE_DOCS_PATH/docs/`
+3. Judge: SKIP (internal changes) or FLAG (user-facing changes)
+4. If FLAG: prompt user via AskUserQuestion
+5. If approved: spawn `docs-sync-writer` subagent
+
+### 3. Writer Subagent: docs-sync-writer
+
+**Location:** `.claude/agents/docs-sync-writer.md`
+
+**Model:** sonnet (quality writing)
+
+**Pre-approved permissions:**
+- All git operations (diff, checkout, pull, add, commit, push)
+- gh pr create
+- Skill (elements-of-style)
+
+**Process:**
+1. Invoke elements-of-style skill
+2. Read code diff and affected docs
+3. Edit docs following style rules
+4. Create branch, commit with signoff, push
+5. Open PR via `gh pr create`
+6. Return PR URL
+
+## File Layout
+
+```
+recce/
+├── .claude/
+│   ├── settings.json              # hook config + permissions
+│   ├── hooks/
+│   │   └── docs-sync-check.sh     # bash gate script
+│   └── agents/
+│       ├── docs-sync-scanner.md   # haiku triage subagent
+│       └── docs-sync-writer.md    # sonnet writing subagent
+```
+
+## User Setup
+
+**One-time setup per developer:**
+1. Set `export RECCE_DOCS_PATH=/path/to/recce-docs`
+2. Ensure `gh` CLI is authenticated
+
+**What gets committed:**
+- Hook configuration in `settings.json`
+- Hook script and agent definitions
+
+**What stays local:**
+- `RECCE_DOCS_PATH` value
+
+## Design Decisions
+
+1. **Subagents over skills** — Subagents run autonomously with pre-approved permissions, reducing user prompts for routine git operations.
+
+2. **Two-stage pipeline** — Scanner (haiku) is cheap for triage; writer (sonnet) only runs when needed for quality output.
+
+3. **Pre-approved git permissions** — The writer subagent has default git/gh permissions so it can create PRs without prompting.
+
+4. **Stop hook** — Fires when Claude finishes responding, catches final state of changes.
+
+5. **Environment variable for docs path** — Simple, portable. Unset = feature disabled.