synapse-docs

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

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

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 |

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

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