Doc Sync
- 21 installs
- 22 repo stars
- Updated May 28, 2026
- acedergren/agentic-tools
doc-sync is a Claude Code skill that audits or fixes drift between project documentation and the actual codebase.
About
doc-sync is a Claude Code skill that audits or fixes drift between project documentation and the actual codebase. It detects stale architecture diagrams, wrong file paths, outdated test counts, and undocumented structural changes, classifying drift into structural, path rot, count, and roadmap lag. By default it reports only; passing 'fix' applies targeted repairs and commits. Developers use it to keep docs, CLAUDE.md, and roadmaps in sync with the code.
- Audits project docs against codebase reality to detect drift
- Detects stale architecture diagrams, wrong file paths, outdated test counts, and undocumented changes
- Report-only by default; pass 'fix' to apply targeted repairs and commit
Doc Sync by the numbers
- 21 all-time installs (skills.sh)
- Ranked #1,001 of 1,879 Documentation skills by installs in the Skillselion catalog
- Data as of Jul 28, 2026 (Skillselion catalog sync)
doc-sync capabilities & compatibility
- Capabilities
- doc drift audit · documentation sync · path validation · doc repair
- Use cases
- documentation · code review
- Pricing
- Free
What doc-sync says it does
Audit project docs against codebase reality. Report drift or fix it.
Never update a doc based on what the code *should* look like — only sync to what it *actually* is now.
npx skills add https://github.com/acedergren/agentic-tools --skill doc-syncAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 21 |
|---|---|
| repo stars | ★ 22 |
| Last updated | May 28, 2026 |
| Repository | acedergren/agentic-tools ↗ |
What it does
Audit or fix drift between project docs and the codebase, detecting stale paths, counts, diagrams, and roadmap lag.
Who is it for?
Detecting and fixing stale docs, wrong file paths, outdated counts, and roadmap lag against the real codebase.
Skip if: Authoring new documentation or rewriting prose; it only syncs docs to what the code actually is.
When should I use this skill?
You want to audit or fix drift between project documentation and the actual codebase.
What you get
A drift report (or applied fixes) aligning docs, CLAUDE.md, and roadmaps with the codebase reality.
- Doc-drift report grouped by severity
- Targeted doc fixes committed (fix mode)
By the numbers
- 4 drift types: structural, path rot, count, roadmap lag
- ships 2 scripts: list-doc-targets.sh, check-doc-paths.js
Files
Documentation Sync Audit
Audit project docs against codebase reality. Report drift or fix it.
NEVER
- Never update a doc based on what the code should look like — only sync to what it actually is now.
- Never fix docs for a section you didn't audit — partial fixes create false confidence.
- Never mark a roadmap item complete based on code presence alone — check git log for the deliberate completion commit.
- Never skip auditing CLAUDE.md / agent instructions — stale agent instructions cause cascading errors in future sessions.
Drift Classification: What Actually Goes Stale
Most doc-code drift falls into four categories with different detection approaches:
| Drift Type | Detection Signal | False Positive Risk |
|---|---|---|
| Structural drift | Directory tree, plugin/middleware chain order | Low — filesystem is ground truth |
| Path rot | File paths in docs that no longer exist | Low — use check-doc-paths.js |
| Count drift | Test counts, permission counts, route counts | Medium — recount from actual files |
| Roadmap lag | Completed work not reflected in docs | High — confirm git log intent |
Decision: Audit vs Fix
$ARGUMENTS= empty oraudit→ report only, no edits$ARGUMENTS=fix→ report then apply targeted edits, commit
When fixing: edit the minimum to correct drift. Don't rewrite prose, restructure sections, or add new content — this is sync, not authoring.
What to Audit
Architecture docs — plugin/middleware chain order, route module list, monorepo package list, directory structure tree.
Security docs — security plugins listed vs what's registered, permission counts, any security-related commits since last doc update (git log --oneline --since="$(git log -1 --format=%ai docs/SECURITY.md)" -- src/).
Test docs — actual test file count vs documented count, pass/fail counts (run suite to get current numbers).
Roadmap/changelog — git log for completed work not reflected in any phase. Flag commits with feat: or fix: prefixes that postdate the last roadmap update.
CLAUDE.md / agent instructions — naming conventions match actual patterns, documented file paths exist, anti-patterns section is current.
Scripts
bash scripts/list-doc-targets.sh
node scripts/check-doc-paths.js README.md docs/ARCHITECTURE.mdReport Format
| Doc | Section | Issue | Severity |
|-----|---------|-------|----------|Severity: Critical (broken paths, missing security docs), Warning (stale counts, missing routes), Info (minor wording drift, outdated roadmap phases).
Commit (fix mode only)
docs: sync documentation with codebase [doc-sync]#!/usr/bin/env node
import { existsSync, readFileSync } from 'node:fs';
import { resolve, dirname } from 'node:path';
const files = process.argv.slice(2);
if (files.length === 0) {
console.error('Usage: node scripts/check-doc-paths.js <doc-file> [doc-file...]');
process.exit(1);
}
const virtualTargets = new Set([
'.claude/skills/',
'.claude/agents/',
'.claude/hooks/',
'.claude/skills',
'.claude/agents',
'.claude/hooks',
]);
const pathRegex = /`((?:apps|packages|docs|scripts|infrastructure|claude|\.claude|README\.md|AGENTS\.md|CLAUDE\.md)[^`:#]*)`/g;
let failures = 0;
for (const file of files) {
const abs = resolve(file);
const base = dirname(abs);
const text = readFileSync(abs, 'utf8');
const seen = new Set();
let match;
while ((match = pathRegex.exec(text)) !== null) {
const candidate = match[1].replace(/^\.\//, '');
if (seen.has(candidate)) continue;
seen.add(candidate);
if (virtualTargets.has(candidate)) continue;
const local = resolve(base, candidate);
const repo = resolve(process.cwd(), candidate);
const ok = existsSync(local) || existsSync(repo);
if (!ok) {
console.log(`MISSING\t${file}\t${candidate}`);
failures += 1;
}
}
}
if (failures === 0) {
console.log('All referenced paths found.');
}
#!/usr/bin/env bash
set -euo pipefail
find docs .claude/reference . -maxdepth 2 -name '*.md' 2>/dev/null | sort
Related skills
Lark MarkdownInstantly turn any markdown file into clean, formatted Lark/Figma-compatible documents without manual reformatting.488k
Lark DocCreate, read, update, summarize, rewrite and manage Feishu/Lark cloud documents directly from agent workflows.401k16.1kLark WikiCreate, organize, query, and manage documents, spaces, and members inside Lark (Feishu) knowledge bases directly from AI agent workflows.397k16.1k
Domain ModelingBuild and sharpen a project's domain model: pin down domain terminology in a glossary and record architectural decisions as ADRs.318k202k
Opensource Guide CoachGet expert, attribution-safe guidance on launching and sustaining an open-source project.270k71Readme I18nMaintain consistent, updatable language selector blocks across every README variant in a multilingual repository.270k71FAQ
Does doc-sync edit my docs automatically?
Only if you pass 'fix'. By default it is report-only; 'fix' applies targeted edits to correct drift and commits.
What kinds of drift does it detect?
Structural drift, path rot, count drift (test/permission/route counts), and roadmap lag, each with a different detection approach.