Synapse Docs

This skill ensures Synapse A2A documentation stays synchronized with code changes.

When This Skill Activates

Automatic Triggers

1. Code changes in core modules - synapse/*.py, synapse/commands/*.py
2. Profile changes - synapse/profiles/*.yaml
3. Template changes - synapse/templates/.synapse/*
4. Plugin/Skill changes - plugins/synapse-a2a/**/*
5. Configuration changes - pyproject.toml (version, dependencies, entry points)

Manual Invocation

• /synapse-docs - Run full documentation check and update

Workflow

Phase 1: Detect Changes

When code is modified, identify affected documentation by consulting references/code-doc-mapping.md.

Quick Reference - Common Patterns:

Change Type	Primary Docs	Secondary Docs
CLI command	README.md, guides/usage.md	guides/references.md, CLAUDE.md
API endpoint	README.md, guides/references.md	guides/enterprise.md
Environment variable	README.md, guides/settings.md	templates/.synapse/settings.json
Profile setting	guides/profiles.md	CLAUDE.md
Skill content	plugins/*/SKILL.md	.claude/skills/, .codex/skills/

Phase 2: Propose Updates

For each affected document:

1. Read the current content
2. Identify the specific section to update
3. Propose the minimal necessary change
4. Present changes to user for approval

Update Principles:

• Maintain existing document style and tone
• Update only affected sections
• Keep README.md concise; put details in guides/
• Ensure consistency across related documents

Phase 3: Synchronize Related Files

After updating primary documents, check for required synchronization:

Skill Synchronization:

plugins/synapse-a2a/skills/ → .claude/skills/
plugins/synapse-a2a/skills/ → .codex/skills/

Template Consistency:

synapse/templates/.synapse/ should match documentation in guides/settings.md

Phase 4: Verify Consistency

Run consistency checks:

1. CLI commands - Compare README.md ↔ guides/usage.md ↔ guides/references.md
2. API endpoints - Compare README.md ↔ guides/references.md
3. Port ranges - Compare README.md ↔ guides/multi-agent-setup.md ↔ CLAUDE.md
4. Environment variables - Compare README.md ↔ guides/settings.md ↔ templates/settings.json

Document Categories

User-Facing (High Priority)

Document	Purpose	Update Frequency
README.md	First impression, quick start	Every feature change
guides/usage.md	How to use	CLI/API changes
guides/settings.md	Configuration reference	Setting changes
guides/troubleshooting.md	Problem solving	New issues discovered

Developer-Facing

Document	Purpose	Update Frequency
CLAUDE.md	Development guide for Claude Code	Architecture/test changes
guides/architecture.md	Internal design	Component changes
docs/*.md	Technical specifications	Design changes

Plugin/Skill

Document	Purpose	Update Frequency
plugins/synapse-a2a/README.md	Plugin installation	Plugin changes
plugins/*/skills/*/SKILL.md	Skill instructions	Feature changes

Reference Files

For detailed document inventory and code-to-doc mappings, consult:

• references/doc-inventory.md - Complete list of all documents and their roles
• references/code-doc-mapping.md - Source file to document relationships

Special Cases

Version Updates

When pyproject.toml version changes:

1. Update CHANGELOG.md with release notes
2. Check if README.md test badge needs updating
3. Update plugins/synapse-a2a/.claude-plugin/plugin.json version if needed

New Feature Addition

For major new features:

1. Add to README.md feature table
2. Create or update relevant guide in guides/
3. Update CLAUDE.md if development workflow affected
4. Add to guides/README.md navigation if new guide created

Deprecation

When deprecating features:

1. Mark as deprecated in relevant docs
2. Add migration guide if needed
3. Update CHANGELOG.md
4. Remove from quick start examples in README.md