architecture-guard

Doc Sync

Detect and resolve documentation drift without front-loading a full repository audit. Treat standard Claude Code Sonnet context as the baseline.

Triggers

Users may say:

• "doc sync"
• "sync docs"
• "fix doc drift"
• "reconcile docs"
• "update docs to match code"
• "update code to match docs"
• "check for documentation drift"

Parameters

direction is required:

• code-to-docs: update docs to match code
• docs-to-code: identify code gaps against docs
• full: bidirectional reconciliation with human review for conflicts

Options:

• --dry-run: report only, no file edits
• --scope <path>: limit the audit to a subtree or file group
• --incremental: start from changed files since the last sync, then current git changed files if no last-run record exists
• --parallel N: cap concurrent auditors; default 2, maximum 4

Artifact root resolution

Treat every .aiwg/... path below as a logical artifact path. Before reading or writing sync state, working evidence, or reports, run aiwg artifacts path from the active workspace and use the returned absolute directory as AIWG_ARTIFACT_ROOT. Never write these payloads to a literal project-local .aiwg/ when AIWG_ARTIFACTS_PATH or .aiwg-location redirects the corpus.

Context Budget Rules

• Start with git status --short, git diff --name-only, and git diff --cached --name-only.
• If no --scope or --incremental is supplied, derive a candidate scope from changed files and ask before expanding to the full repo.
• Use inventories (rg --files, find, git path lists) before reading file bodies.
• Dispatch auditors only for domains implicated by the scoped files.
• Each auditor returns at most 10 findings and 600 words to the parent context. Detailed evidence goes under $AIWG_ARTIFACT_ROOT/working/doc-sync/.
• Do not preload other skills into auditor agents.
• For combined doc-sync, blog, and commit requests, keep blog/release coverage as one scoped lane and return a handoff summary for commit-and-push.

Workflow

1. Parse direction and options.
2. Build the cheap scope inventory from git path lists.
3. Select relevant lanes only: CLI/API docs, provider docs, skill/agent catalogs, README/changelog/release/blog material, or config/schema docs.
4. Run bounded auditors for selected lanes only.
5. Write $AIWG_ARTIFACT_ROOT/reports/doc-sync-{timestamp}.md with scope, findings, auto-fixable items, human-review items, and changed files.
6. If not --dry-run, apply high-confidence fixes only.
7. Validate modified files with targeted checks.
8. Record $AIWG_ARTIFACT_ROOT/reports/doc-sync-last-run.json.
9. Return report path, files changed, validation commands, and remaining review items.

Output Contract

Return:

• report path
• scope audited
• files changed
• validation commands run
• remaining human-review items
• recommended handoff skill, if any