sync-docs ยท diff
git:20260415.0ec9bf9 to git:20260417.0b8df3e
45 added, 94 removed. Audit A to A.
---
name: sync-docs
description: >
- Audit and synchronize project documentation. README, AGENTS.md, llms.txt, docs/,
- and fsrc markers. Use after feature changes, refactors, or when docs may be stale.
- Can be run as a scheduled agent or invoked manually.
+ Audit and synchronize project documentation. Detect staleness, fix drift, and keep
+ cross-references consistent across whatever docs the project has. Delegates file-specific
+ rules to the skills that own them. Use after feature changes, refactors, or when docs
+ may be stale. Can be run as a scheduled agent or invoked manually.
allowed-tools: Read Grep Glob Bash Edit Write
user-invocable: true
metadata:
title: Documentation Sync
category: maintenance
order: 20
---
# Documentation Sync
- Audit project documentation for consistency, staleness, and completeness. Fix issues found.
+ Audit whatever documentation the project has, fix drift, and keep cross-references consistent. This skill owns the **audit loop**, not the list of files.
## When to Use
- After implementing a new feature or significant refactor
- When docs haven't been updated in a while
- As a scheduled agent to catch drift
- Before releases to ensure docs match the code
- ## Audit Checklist
-
- ### 1. fsrc Markers
-
- Run `fsrc --verify` on all files with markers to detect drift:
-
- ```sh
- # Find all files with fsrc markers
- grep -rl 'fsrc src=' . --include='*.md' | xargs fsrc --verify
- ```
-
- If any markers are stale, run `fsrc` to update them:
-
- ```sh
- grep -rl 'fsrc src=' . --include='*.md' | xargs fsrc
- ```
+ ## Principle
- ### 2. Community Health Files
+ Do not enumerate required files here. Different projects carry different docs, and the authoritative rules for each doc type live in the skill that owns it. This skill's job is to:
- Verify standard community health files exist (see `check-project` for full list):
+ 1. Discover what docs the project actually has
+ 2. Detect drift between docs and code (and between docs and each other)
+ 3. Delegate file-specific fixes to the owning skill
+ 4. Verify cross-references agree
- | File | Check |
- |------|-------|
- | `SECURITY.md` | Exists with vulnerability reporting instructions |
- | `CODE_OF_CONDUCT.md` | Exists for public repos |
- | `CONTRIBUTING.md` | Matches current build/test commands |
- | `CHANGELOG.md` | Exists after first release (auto-generated by sr) |
+ ## Audit Loop
- ### 3. README Completeness
+ ### 1. Discover
- Check the README against `write-readme` standards:
+ Glob for documentation artifacts that exist in the repo. Do not assume any specific file is present. Common locations: repo root (`README.md`, `AGENTS.md`, `llms.txt`, community health files), `docs/`, `skills/`, language manifests.
- | Section | Required | Check |
- |---------|----------|-------|
- | Centered header | Always | Title, description, 3 links |
- | CI badge | Always | Points to valid workflow |
- | Features | Always | 3-8 bullet points |
- | Installation | Always | install.sh for CLIs, package manager for libs |
- | Quick Start | Always | Minimal path from install to first result |
- | Usage / CLI Reference | If CLI | Commands, flags, examples |
- | Configuration | If configurable | Config file format, env vars |
- | Architecture | If complex | Brief summary + link to `docs/architecture.md` |
- | Agent Skill | If skills exist | Link to `skills/` |
- | License | Always | Apache-2.0 |
+ ### 2. Detect drift
- ### 4. AGENTS.md Currency
+ Generic drift checks that apply to any project:
- Verify AGENTS.md reflects the current state:
+ **Embedded source drift.** If any file uses `fsrc` markers, run `fsrc --verify` to detect drift. Update with `fsrc` if drift is found.
- - Commands section matches actual build/test/lint commands (native tools, not stale justfile references)
- - Architecture overview matches current code structure
- - No references to deleted files, renamed modules, or removed features
+ ```sh
+ grep -rl 'fsrc src=' . | xargs fsrc --verify
+ ```
- ### 5. llms.txt
+ **Command drift.** Extract build, test, lint, and install commands referenced in docs. Confirm they still match the native tooling declared in the manifest. Stale references to a removed runner (e.g. justfile after migration to native tools) is the most common failure mode.
- Verify `llms.txt` exists and links are valid:
+ **Dead links.** Extract URLs from docs and spot-check reachability. Internal links should resolve to files that still exist.
- ```sh
- # Check all URLs in llms.txt are reachable
- grep -oP 'https?://\S+' llms.txt | xargs -I{} curl -sI {} | grep -E '^HTTP'
- ```
+ **Deleted references.** Grep docs for names of files, modules, or commands that no longer exist in the tree.
- ### 6. docs/ Directory
+ ### 3. Delegate specifics
- Check docs are current:
+ File-specific structural rules live in the owning skill. When a file looks stale or incomplete, open the relevant skill for the authoritative checklist rather than duplicating rules here:
- | File | Check |
- |------|-------|
- | `docs/architecture.md` | Matches current system design |
- | `docs/guides/*.md` | Procedures still work |
- | `docs/runbooks/*.md` | Commands and URLs are valid |
- | `docs/rfcs/*.md` | Status fields are accurate |
+ | Artifact | Owning skill |
+ |----------|--------------|
+ | `README.md` | `write-readme` |
+ | `AGENTS.md` | `configure-ai` |
+ | `llms.txt` | `create-llms-txt` |
+ | Community health files, required layout | `check-project` |
+ | Language/build-system docs | `scaffold-<lang>` |
- ### 7. Cross-Reference Consistency
+ ### 4. Cross-reference consistency
- Ensure these files agree on:
+ The same facts often appear in several docs. When they disagree, pick one source of truth and propagate. The README title/description is usually the source of truth for identity; the manifest is the source of truth for version and package name.
- - **Project name** README title, AGENTS.md identity, llms.txt title, package.json/Cargo.toml/pyproject.toml name
- - **Description** README subtitle, AGENTS.md description, llms.txt description, repo description
- - **Commands** README Quick Start, AGENTS.md commands, CONTRIBUTING.md development section
- - **Installation** README install, llms.txt install link
+ Facts to cross-check when more than one doc mentions them: project name, tagline/description, install command, quickstart command, primary build/test commands, license.
- ## Fix Strategy
+ ### 5. Fix or flag
- 1. **fsrc drift** run fsrc to update markers
- 2. **Missing sections** add them following `write-readme` conventions
- 3. **Stale commands** update to match native build system (see `scaffold-*` skills)
- 4. **Dead links** remove or update
- 5. **Description mismatch** use README as source of truth, propagate to other files
+ - Fix drift that is unambiguous (fsrc refresh, stale command names, dead internal links)
+ - Flag drift that needs judgment (architectural changes, new features without docs, description rewrites)
+ - Report what was fixed and what needs human review
## CI Integration
- Add fsrc verification to CI to catch drift early:
-
- ```yaml
- # In ci.yml, before other jobs
- embed:
- name: Verify Embedded Sources
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v4
- - uses: urmzd/fsrc@v4
- with:
- commit-dry: "true"
- commit-push: "false"
- - name: Check for drift
- run: git diff --exit-code
- ```
+ Repos that use `fsrc` should verify it in CI so drift is caught at PR time rather than by this skill. See `setup-ci` for the workflow pattern.
## Scheduled Sync
- This skill can be run on a schedule to keep docs fresh. When invoked:
+ When invoked on a schedule:
- 1. Run the full audit checklist above
- 2. Fix any fsrc drift automatically
- 3. Flag sections that need human review (architecture changes, new features without docs)
- 4. Report a summary of what was fixed and what needs attention
+ 1. Run the audit loop above against whatever the repo contains
+ 2. Auto-fix mechanical drift (fsrc, dead internal links, command renames)
+ 3. Flag structural issues for the next human review
+ 4. Emit a short summary **what was fixed / what needs attention**