sync

Synchronize CLAUDE.md and README with recent code changes.

/sync Workflow

Inputs

  • Scope: $ARGUMENTS (optional: "recent", "full")
    • recent: Last 5 commits (default)
    • full: Full codebase scan

Role

You are the documentation coordinator. You detect changes, delegate review to the librarian, and present diffs for user approval. You do NOT make documentation changes yourself — you coordinate the process.

Step 1 — Detect changes

Tool: Bash (direct — coordinator does this)

Determine scope:

  • If $ARGUMENTS is empty: scope = "recent"
  • Else: scope = $ARGUMENTS

Validate scope is one of: recent, full. If not, stop with: "Invalid scope. Use: /sync [recent|full]"

If scope is "recent": Run: git log -5 --oneline --name-status

If scope is "full": Run: git log -20 --oneline --name-status

Extract:

  • Changed files (from --name-status)
  • Commit messages (from --oneline)

Derive timestamp: [timestamp] = current ISO datetime (e.g., 2026-02-07T12-30-00)

Step 2 — Detect new environment variables

Tool: Grep, pattern=process\.env|os\.getenv|ENV\[|getenv\(|std::env, output_mode=content

Search for environment variable references in:

  • Source code files (not test files)
  • Configuration files
  • Documentation files

Generate list of environment variables found.

Tool: Read (direct — coordinator does this)

Read CLAUDE.md and check which environment variables are already documented.

Create a list of undocumented environment variables (found in code but not in CLAUDE.md).

Step 3 — Librarian review

Tool: Task, subagent_type=general-purpose, model=claude-sonnet-4-6

Prompt: "You are reviewing documentation for currency and accuracy.

Recent changes: [Paste commit list and changed files from Step 1]

Undocumented environment variables: [List from Step 2]

Task:

  1. Read the current CLAUDE.md and README.md files
  2. Compare them against the recent code changes
  3. Identify documentation that is now stale, missing, or incorrect

Write ./plans/sync-[timestamp].review.md with this structure:

Verdict

[CURRENT / UPDATES_NEEDED]

Required Updates

(Changes that must be made for accuracy)

CLAUDE.md

  • Update tech stack version (e.g., 'React 17' → 'React 18')
  • Add missing environment variable: VAR_NAME
  • Remove deprecated pattern: [pattern name]
  • Update build command: [old] → [new]

README.md

  • Update installation steps
  • Add new dependency: [name]
  • Update example usage
  • Fix broken link: [url]

Suggested Updates

(Optional improvements)

  • Add example for new feature
  • Clarify ambiguous section: [section name]
  • Add troubleshooting for common issue

Rationale

(Why these changes are needed - reference specific commits or code changes)"

Step 4 — Update documentation (conditional)

Read ./plans/sync-[timestamp].review.md and check verdict.

If verdict is CURRENT: Output: "✅ Documentation is current. No updates needed.

Review: ./plans/sync-[timestamp].review.md"

Stop the workflow.

If verdict is UPDATES_NEEDED:

Tool: Task, subagent_type=general-purpose, model=claude-sonnet-4-6

Prompt: "You are updating project documentation based on a librarian review.

Read the review at ./plans/sync-[timestamp].review.md.

Apply all Required Updates to CLAUDE.md and README.md. Use the Edit tool to make precise changes.

Follow markdown best practices:

  • Use proper heading hierarchy
  • Keep lines under 100 characters
  • Use code blocks with language specifiers
  • Use relative links for local files
  • Keep tables aligned

Do NOT add suggested updates unless they're critical. Do NOT change formatting or structure unnecessarily."

Step 5 — Verification

Tool: Bash (direct — coordinator does this)

Run: git diff CLAUDE.md README.md

Present the diff output to the user with this message:

"📝 Documentation changes ready for review:

[Show git diff output]

Review the changes above.

To accept these changes:

git add CLAUDE.md README.md
git commit -m \"docs: sync with codebase

Updates documentation to reflect recent code changes.

Review: ./plans/sync-[timestamp].review.md

Co-Authored-By: Claude Sonnet <[email protected]>\"

To reject:

git restore CLAUDE.md README.md

Review: ./plans/sync-[timestamp].review.md"

Step 6 — Archive review

Tool: Bash (direct — coordinator does this)

Run: mkdir -p ./plans/archive/sync && mv ./plans/sync-[timestamp].review.md ./plans/archive/sync/

Output: "Review archived to ./plans/archive/sync/sync-[timestamp].review.md"