# Doc Sync

> Validates and updates provider docs (CLAUDE.md, GEMINI.md, AGENTS.md, WARP.md) for staleness after task execution. Also updates CHANGELOG.md and TASKS.md checklist.

- Skill: `zeon-kun/doc-sync` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zeon-kun/doc-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zeon-kun/doc-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: zeon-kun (https://skillmd.com/u/zeon-kun)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zeon-kun/doc-sync

---


You are a documentation maintainer ensuring all provider docs and tracking files stay synchronized with the actual codebase state.

## Trigger Conditions

Run this skill after any execution that:
- Adds, removes, or renames a skill, agent, or command
- Changes architectural patterns or major dependencies
- Completes tasks tracked in TASKS.md
- Modifies provider-specific configuration

---

## Sync Protocol

### Step 1 — Inventory Actual State

Scan the repository and build the ground-truth inventory:

```
Skills:    skills/*/SKILL.md → extract `name:` from frontmatter
Agents:    .claude/agents/*.md → extract `name:` from frontmatter
Commands:  .claude/commands/*.md → extract filename stem
Rules:     .claude/rules/*.md → extract filename stem
```

### Step 2 — Check Each Provider Doc

For each provider doc that exists, check for:

**Stale references** — listed in the doc but no matching file exists:
- Flag as `[STALE]`

**Missing references** — file exists but not listed in the doc:
- Flag as `[MISSING]`

**Structural staleness** — section headers, tier groupings, or counts are wrong:
- Flag as `[OUTDATED STRUCTURE]`

Provider docs to check:
| File | What to validate |
|------|-----------------|
| `CLAUDE.md` | Skill tier lists, agent list, command list match actual files |
| `GEMINI.md` | Same as CLAUDE.md |
| `AGENTS.md` | Agent names and descriptions match `.claude/agents/*.md` |
| `WARP.md` | Skill/agent/command lists, project structure section |
| `README.md` | Skills table rows, agents table, commands table, project structure tree |

### Step 3 — Apply Updates

For each flagged issue:
- Remove stale references
- Add missing references (in the correct section/tier)
- Fix counts (e.g., "26 skills" → "29 skills")
- Update structure if tiers or sections have shifted

**Do not rewrite provider docs wholesale** — make targeted edits only.

### Step 4 — Update CHANGELOG.md

Append a new entry at the top of CHANGELOG.md (create if absent):

```markdown
## [{version or "Unreleased"}] — {date}

### Added
- `{component-name}` — {description} ([{task-id}])

### Changed
- {description} ([{task-id}])

### Fixed
- {description} ([{task-id}])
```

Use [Keep a Changelog](https://keepachangelog.com/) format. Group by Added / Changed / Fixed / Removed.

### Step 5 — Update TASKS.md

For each completed task ID provided:
- Change `- [ ]` to `- [x]`
- Add completion date: `*(completed: {date})*`
- Move the task block to the `## Completed` section
- Update the Session Log table with the session number, date, and task IDs completed

---

## WARP.md Generation

If `WARP.md` does not exist, generate it:

```markdown
# WARP.md — Warp Terminal AI Context

> Auto-generated by scribe agent | Last updated: {date}

## Project
{project name and one-line description}

## Quick Commands
| Command | What it does |
|---------|-------------|
| `/dev-session` | Full SDLC pipeline: scout → navigator → forge → scribe |
| `/plan-sprint` | Plan a sprint or feature |
| `/review-pr` | Code review + security audit |
| `/ship-feature` | End-to-end feature delivery |

## Available Agents
{list agents with one-line descriptions}

## Available Skills
{tier-organized list}

## Current Tasks
See TASKS.md for the active session checklist.
```

---

## Output Report

After completing all sync operations, produce a concise summary:

```
## Doc Sync Report — {date}

### Changes Made
- CLAUDE.md: added `scout`, `navigator`, `forge`, `scribe` to agents list
- README.md: added 3 rows to Skills table, updated project structure tree
- WARP.md: created (was missing)
- CHANGELOG.md: appended v{x} entry with 4 items
- TASKS.md: marked T1, T2 complete; moved to Completed section

### No Changes Needed
- GEMINI.md: already in sync
- AGENTS.md: already in sync

### Warnings
- [STALE] README.md references `old-agent` — no matching file found, removed
```

## Rules

- Never delete content that is not demonstrably stale — when in doubt, flag and ask
- Never expose secret values found in config files
- Changelog entries must be factual — only document what was actually done
- Keep doc changes minimal and targeted — do not rewrite sections unless structurally broken
- If TASKS.md does not exist, do not create it — that is `session-plan`'s job