context-sync

# context-sync

> A Claude Code skill (MIT, shimo4228) that audits and fixes project documentation roles. Detects overlap between CLAUDE.md, architecture docs, docs/adr/, and README, and staleness against the code — enforces a four-role model so every concept lives in exactly one place. File-level module maps are not stored; a hand-maintained one is reported as a finding. README findings are flagged, not edited.

Status: active, synced one way from the author's Claude Code harness (`scripts/sync-from-local.sh`); also shipped in the [akc-cycle](https://github.com/shimo4228/akc-cycle) plugin as `/akc-cycle:context-sync`, so this repository can trail the plugin between syncs.

## Core documentation

- [llms-full.txt](llms-full.txt): self-contained Q&A reference for AI agents (Project Facts, Prior Research, question-form H2 sections)
- [README.md](README.md): human-facing narrative (why it matters, the problem, the four roles, real results)
- [SKILL.md](skills/context-sync/SKILL.md): full skill specification — 5-phase workflow, four-role model, concept-level Architecture role, anti-patterns
- [context_evidence.py](skills/context-sync/scripts/context_evidence.py): standard-library Python 3.11+ evidence script run in the Freshness Check (numbers, paths, ADR index, llms.txt links); emits JSON
- [CHANGELOG.md](CHANGELOG.md): release history

## Architecture

- Four documentation roles: **Context** (how to work here — CLAUDE.md), **Architecture** (what concepts the code defines and how they relate — graph.jsonld triples, short overviews), **Decisions** (why it's this way — ADR), **External** (what the project is — README); llms.txt / llms-full.txt are detected as a fifth, AI-facing set
- 5-phase workflow: Discover → Overlap Detection → Create / Migrate → Freshness Check → Report
- Architecture is concept-level only: graph.jsonld answers "what is X / how does X relate to Y?"; "where is X implemented?" is derived from code (LSP / grep), never stored

## Standard reference

- [Agent Skill specification](https://agentskills.io/specification): the Claude Code skill format used by this repo
- [Answer.AI llms.txt standard](https://llmstxt.org/): the AI-facing documentation format this file implements

## Sibling skills

- [akc-cycle](https://github.com/shimo4228/akc-cycle): Claude Code plugin that installs context-sync with the other skills of the cycle, `adr-writer` among them (ADRs are created through `adr-writer`)
- [jsonld-knowledge-graph](https://github.com/shimo4228/jsonld-knowledge-graph): creates, extends and lints graph.jsonld; owns the concept-level Architecture boundary
- [readme-writer](https://github.com/shimo4228/readme-writer): receives context-sync's README findings; rewrites or reviews a README, with a fresh judge checking it against the code
- [llms-txt-writer](https://github.com/shimo4228/llms-txt-writer): writes AI-facing docs optimized for ChatGPT / Perplexity / Gemini citation
- [skill-comply](https://github.com/shimo4228/skill-comply): measures whether agents actually follow skill / rule definitions
- [search-first](https://github.com/shimo4228/search-first): research-before-coding workflow
- [skill-stocktake](https://github.com/shimo4228/skill-stocktake): quality audit for installed skills
- [rules-distill](https://github.com/shimo4228/rules-distill): scan installed skills, extract cross-cutting principles, and distill them into rules
- [learn-eval](https://github.com/shimo4228/learn-eval): extract reusable patterns from sessions, self-evaluate quality, and save to the right location
- [daily-research](https://github.com/shimo4228/daily-research): research feedback engine for your own repos — `claude -p` + macOS launchd writes daily reports per line