doc-sync

name	doc-sync
description	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.
argument-hint	<completed task IDs or summary of changes made>
user-invocable	false

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):

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

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

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

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

Use Keep a Changelog 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:

# 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