/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"