syncing-framework-docs
Skill4 starsChanged 3 months agoApache-2.0View on GitHub
Checklist for keeping downstream docs (FRAMEWORK_SPECIFICATION, presentation HTMLs) in sync when framework-defining files change. Use when editing .claude/agents, .claude/rules, .claude/commands, CLAUDE.md, PHILOSOPHY.md, or the project version — and during /review and /ship of framework changes.
In this repository25 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- adr-writingSkill
- authoring-goal-contractsSkill
- collaborating-asyncSkill
- committing-changesSkill
- cross-agent-dispatchSkill
- documenting-decisionsSkill
- feature-status-registrySkill
- grill-meSkill
- grill-yourselfSkill
- handling-micro-fixesSkill
- multi-instance-dispatchSkill
- notifying-the-developerSkill
- orchestrating-goal-loopsSkill
- orchestrating-lean-dispatchSkill
- performance-playbookSkill
- python-project-patternsSkill
- recovering-from-failuresSkill
- running-build-checkpointsSkill
- searching-prior-artSkill
- security-checklistSkill
- selecting-review-gatesSkill
- severity-calibrationSkill
- testing-playbookSkill
- wrapping-up-sessionsSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 23
When the trigger fires, review and update these three artifacts:
- Very specific: line 49
During
/review: When reviewing framework changes, verify that affected sync points have been updated.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Framework Documentation Sync
Ensures downstream documentation artifacts stay in sync when the framework evolves. Prevents the recurring problem of framework version bumps leaving specs and presentations stale.
Trigger
This rule activates when any change touches framework-defining files:
.claude/agents/— agent definitions (count, roles, model tiers).claude/rules/— auto-loaded standards (count, new rules).claude/commands/— slash commands (count, new commands)CLAUDE.md— project constitutionPHILOSOPHY.md— framework philosophypyproject.toml— project version
Documentation Artifacts to Sync
When the trigger fires, review and update these three artifacts:
| Artifact | Path | Purpose |
| Framework Specification | docs/FRAMEWORK_SPECIFICATION.md | Authoritative full specification |
| Framework Presentation | docs/diviner-dojo-framework-presentation.html | Presentation deck for stakeholders |
| How-to-Use Presentation | docs/how-to-use-presentation.html | Developer onboarding walkthrough |
Sync Points
This table maps framework elements to the specific locations in each artifact that reference them. When an element changes, check every listed location.
| Framework Element | Specification | Presentation HTML | How-to-Use HTML |
| Version number | Frontmatter version, title, executive summary, footer | <title>, version badge, footer | Footer |
| Agent count | Section 5 heading, roster table, implementation status | Slide 5 heading, directory tree | Stats card |
| Agent model tiers | Roster table, model-tier table, directory listing | Slide 5 agent cards (badge + tier class) | — |
| Leadership hierarchy | Section 5 leadership subsection | Slide 5 heading and agent cards | — |
| Rule count | Implementation status, directory listing | Directory tree slide | — |
| Command count | Section 6, implementation status | — | Stats card, cheat sheet |
| Collaboration modes | Section 4 | Slide 6 | — |
| Hook count | Section 7, implementation status | Slide 8 | — |
| Principles | Section 2 | Slide 3 | — |
Enforcement
- During
/review: When reviewing framework changes, verify that affected sync points have been updated. Flag stale documentation as an advisory finding. - During
/ship: The ship workflow checks for FRAMEWORK-type changes and verifies documentation sync before release. - Steward gate: The Steward evaluates framework evolution proposals. Documentation sync is part of the completeness check.
What This Rule Does NOT Cover
- Content accuracy of the documentation (that's the author's responsibility)
- CLAUDE.md updates (covered by the
documenting-decisionsskill) - ADR creation for architectural changes (covered by the
selecting-review-gatesskill)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.