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