Use when user asks to "update docs", "sync documentation", "fix outdated docs", "update changelog", "docs are stale", or after completing code changes that might affect documentation.
Synchronizes documentation with code changes, updates changelogs, and flags outdated examples.
npx claudepluginhub agent-sh/sync-docs[report|apply] [--scope=recent|all|before-pr] [path]Sync documentation with actual code state. Finds docs that reference changed files, updates CHANGELOG, and flags outdated examples.
/sync-docs command (you are here)
|
v
sync-docs-agent (sonnet)
|-- Invoke sync-docs skill
|-- Return structured results
|
v
Command processes results
|-- If apply mode + fixes: spawn simple-fixer
|-- Present final results
Parse from $ARGUMENTS:
report (default) or apply--scope=recent (default): Files changed since last commit to main--scope=all: Scan all docs against all code--scope=before-pr: Files in current branch (for /next-task integration)path: Specific file or directoryconst args = '$ARGUMENTS'.split(' ').filter(Boolean);
const mode = args.includes('apply') ? 'apply' : 'report';
const scopeArg = args.find(a => a.startsWith('--scope='));
const scope = scopeArg ? scopeArg.split('=')[1] : 'recent';
const pathArg = args.find(a => !a.startsWith('--') && a !== 'report' && a !== 'apply');
const agentOutput = await Task({
subagent_type: "sync-docs:sync-docs-agent",
model: "sonnet",
prompt: `Sync documentation with code state.
Mode: ${mode}
Scope: ${scope}
${pathArg ? `Path: ${pathArg}` : ''}
Execute the sync-docs skill and return structured results.`
});
Parse the structured JSON from between === SYNC_DOCS_RESULT === markers:
// Helper to extract JSON result from agent output
function parseSyncDocsResult(output) {
const match = output.match(/=== SYNC_DOCS_RESULT ===[\s\S]*?({[\s\S]*?})[\s\S]*?=== END_RESULT ===/);
if (!match) {
throw new Error('No SYNC_DOCS_RESULT found in agent output');
}
return JSON.parse(match[1]);
}
const result = parseSyncDocsResult(agentOutput);
// result now contains: { mode, scope, validation, discovery, issues, fixes, changelog, summary }
If mode is apply and fixes array is non-empty:
if (mode === 'apply' && result.fixes.length > 0) {
await Task({
subagent_type: "next-task:simple-fixer",
model: "haiku",
prompt: `Apply these documentation fixes:
${JSON.stringify(result.fixes, null, 2)}
Use the Edit tool to apply each fix. Commit message: "docs: sync documentation with code changes"`
});
}
## Documentation Sync ${mode === 'apply' ? 'Applied' : 'Report'}
### Scope
- Mode: ${mode}
- Scope: ${scope}
- Changed files analyzed: ${result.discovery.changedFilesCount}
- Related docs found: ${result.discovery.relatedDocsCount}
### Validation Results
**Count/Version Validation**
${result.validation.counts.status === 'ok' ? '[OK] Counts and versions aligned' : `[WARN] ${result.validation.counts.summary.issueCount} issues found`}
**Cross-Platform Validation**
${result.validation.crossPlatform.status === 'ok' ? '[OK] Cross-platform docs valid' : `[WARN] ${result.validation.crossPlatform.summary.issueCount} issues found`}
### Documentation Issues
${result.issues.length === 0 ? '[OK] No documentation issues detected' :
result.issues.map(i => `- **${i.doc}:${i.line || '?'}** (${i.severity}): ${i.suggestion || i.type}`).join('\n')}
### CHANGELOG Status
${result.changelog.status === 'ok' ? '[OK] All changes documented' :
`[WARN] ${result.changelog.undocumented.length} commits may need entries:\n${result.changelog.undocumented.map(c => ` - ${c}`).join('\n')}`}
${mode === 'apply' && result.fixes.length > 0 ? `
### Fixes Applied
${result.fixes.map(f => `- **${f.file}**: ${f.type}`).join('\n')}
` : ''}
${mode === 'report' && result.fixes.length > 0 ? `
## Do Next
- [ ] Run \`/sync-docs apply\` to fix ${result.fixes.length} auto-fixable issues
- [ ] Review flagged items manually
` : ''}
# Check what docs might need updates (safe, no changes)
/sync-docs
# Check docs related to specific path
/sync-docs report src/auth/
# Apply safe fixes
/sync-docs apply
# Full codebase scan
/sync-docs report --scope=all
# For PR preparation
/sync-docs apply --scope=before-pr
This command is also used by /next-task Phase 11:
// Phase 11 invocation
await Task({
subagent_type: "sync-docs:sync-docs-agent",
prompt: "Sync docs for PR. Mode: apply, Scope: before-pr"
});
/sync-docsUse when user asks to "update docs", "sync documentation", "fix outdated docs", "update changelog", "docs are stale", or after completing code changes that might affect documentation.