Knowledge Sync Protocol - Implementation Summary

Knowledge Sync Protocol - Implementation Summary

Overview

Automated knowledge updates when products evolve via git release tags.

Status: ✅ Implemented Version: 1.0.0 Date: 2026-01-14

What Was Built

1. Core Scripts (scripts/knowledge-sync/)

2. Git Hook (templates/hooks/)

3. Installation Command (.claude/commands/)

4. Documentation (docs/50-features/)

5. Integration

Architecture

Git Release Tag (v2.4.0)
       ↓
  .git/hooks/post-tag
       ↓
  sync-knowledge.sh
       ↓
  ┌────────────────────┐
  ↓                    ↓
extract-release-     update-product-
changes.sh           knowledge.sh
  ↓                    ↓
Git commits      Knowledge file
between tags     with changes
       ↓                ↓
  Categorized     Auto-commit
  by type         to repo
       └────────┬───────┘
                ↓
  ~/.claude/knowledge/03-products/product.md
                ↓
  Available across all projects

Key Design Decisions

1. Git Tags as Trigger

Decision: Use release tags only (v*..)

Rationale:

• Clean version boundaries
• Standard git workflow
• Already part of release process
• Non-invasive (no new tools)

Alternatives Considered:

• Every commit (too noisy)
• Manual trigger (defeats automation)
• GitHub webhooks (requires infrastructure)

2. Git History for Versioning

Decision: No separate version files, use git log

Rationale:

• Git already tracks changes with timestamps
• No duplication of version info
• Standard git commands work
• Knowledge repo itself is versioned

Alternatives Considered:

• VERSION file (duplication)
• Embedded version markers (clutter)
• Database (complexity)

3. Auto-Commit to Knowledge Repo

Decision: Automatically commit with descriptive message

Rationale:

• Seamless flow (user creates tag, knowledge updates)
• Consistent commit messages
• Easy to review/revert
• Git history tracks evolution

Alternatives Considered:

• Require manual commit (friction)
• Store without committing (loses history)
• Interactive approval (breaks automation)

4. Preserve Manual Edits

Decision: Only auto-update "Recent Changes" section

Rationale:

• Overview/Architecture need human context
• Prevents clobbering important manual work
• Clear separation: manual vs auto-generated
• Users can enhance auto-generated content

Implementation:

• Parse file, preserve content before "## Recent Changes"
• Regenerate only "## Recent Changes" section
• Limit to last 10 releases (prevent file bloat)

5. Conventional Commits

Decision: Parse conventional commit format for categorization

Rationale:

• Industry standard (widely adopted)
• Clean categorization (feat, fix, chore, etc.)
• Breaking changes clearly marked
• Optional (still works without it)

Categories:

• ⚠️ Breaking Changes: feat!: or BREAKING CHANGE:
• ✨ Features: feat:
• 🐛 Fixes: fix:
• 🔧 Chores: chore:
• 📚 Documentation: docs:
• Other: Everything else

Implementation Highlights

Robust Error Handling

set -e  # Exit on error

# Validate inputs
if [ -z "$TAG" ]; then
    echo "Error: Tag required"
    exit 1
fi

# Verify prerequisites
if [ ! -d "$KNOWLEDGE_REPO" ]; then
    echo "Error: Knowledge repo not found"
    exit 1
fi

Auto-Detection

# Auto-detect latest tag
TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")

# Auto-detect previous tag
FROM_TAG=$(git describe --tags --abbrev=0 "$TO_TAG^" 2>/dev/null || echo "")

# Auto-detect product name
PRODUCT_NAME=$(basename "$(git rev-parse --show-toplevel)")

Dry-Run Support

All scripts support --dry-run:

./sync-knowledge.sh --tag v2.4.0 --dry-run
# Shows what would be updated without writing

Flexible Output Formats

# Markdown (default)
./extract-release-changes.sh --to-tag v2.4.0

# JSON (for programmatic use)
./extract-release-changes.sh --to-tag v2.4.0 --format json

Testing

Automated Tests

cd scripts/knowledge-sync
./test-knowledge-sync.sh

Tests verify:

• ✅ Scripts exist
• ✅ Scripts are executable
• ✅ Syntax is valid
• ✅ Help messages work
• ✅ Extraction works (if tags exist)

Manual Testing

# Test extraction
./extract-release-changes.sh --to-tag v2.4.0

# Test dry run
./sync-knowledge.sh --tag v2.4.0 --dry-run

# Test full sync (in test repo)
./sync-knowledge.sh --tag v2.4.0

Integration Points

Current

1. Git Hooks - post-tag triggers sync
2. Knowledge Repository - stores product files
3. Conventional Commits - categorization

Future (Not Implemented)

1. Task Copilot Integration

   • Extract work products created during release
   • Include architecture decisions, technical designs
   • Link to PRDs and tasks

2. Lifecycle Hooks

   • PostWorkProduct hook for real-time capture
   • Update knowledge as work completes
   • No waiting for releases

3. Multi-Product (Monorepos)

   • Detect monorepo structure
   • Per-package versioning
   • Selective syncing

Usage Workflow

First Time Setup

# In Claude Code, from project root
/setup-knowledge-sync

# Creates:
# - .git/hooks/post-tag
# - .git/hooks/sync-knowledge.sh
# - .git/hooks/extract-release-changes.sh
# - .git/hooks/update-product-knowledge.sh

Normal Release Cycle

# Development
git add .
git commit -m "feat: Add new feature"
git commit -m "fix: Fix bug"

# Create release tag
git tag v1.0.0

# Hook automatically:
# ✓ Extracts changes
# ✓ Updates knowledge
# ✓ Commits to knowledge repo

# Push tag
git push --tags

# Push knowledge
cd ~/.claude/knowledge
git push

Manual Sync (if needed)

# Sync specific tag
.git/hooks/sync-knowledge.sh --tag v2.4.0

# Sync latest
.git/hooks/sync-knowledge.sh

# Dry run
.git/hooks/sync-knowledge.sh --dry-run

File Locations

All files in Claude Copilot repository:

claude-copilot/
├── scripts/knowledge-sync/
│   ├── extract-release-changes.sh     # Extract commits
│   ├── update-product-knowledge.sh    # Update knowledge file
│   ├── sync-knowledge.sh              # Main orchestrator
│   ├── test-knowledge-sync.sh         # Test suite
│   ├── README.md                      # Technical docs
│   └── IMPLEMENTATION.md              # This file
├── templates/hooks/
│   └── post-tag                       # Git hook template
├── .claude/commands/
│   └── setup-knowledge-sync.md        # Installation command
├── docs/50-features/
│   └── 03-knowledge-sync.md           # Feature documentation
└── CLAUDE.md                          # Updated with knowledge sync

User's knowledge repository:
~/.claude/knowledge/
└── 03-products/
    ├── product-a.md
    ├── product-b.md
    └── my-product.md

Project repository (after setup):
my-project/
└── .git/hooks/
    ├── post-tag
    ├── sync-knowledge.sh
    ├── extract-release-changes.sh
    └── update-product-knowledge.sh

Success Criteria

What's NOT Included (Future Work)

1. Task Copilot Integration

   • Requires Task Copilot CLI or API
   • Would extract work products, decisions, PRDs
   • More context than git commits alone

2. Real-Time Updates via Hooks

   • PostWorkProduct lifecycle hook
   • Update knowledge as work completes
   • No waiting for releases

3. Multi-Product/Monorepo Support

   • Detect monorepo structure
   • Per-package versioning
   • Selective syncing

4. Knowledge Templates

   • Product-type-specific templates
   • API vs library vs application
   • Industry standards

5. Enhanced Categorization

   • Parse PR descriptions
   • Link to issues
   • Include metrics (coverage, performance)

Known Limitations

1. Relies on conventional commits for good categorization

   • Still works without them (goes to "Other Changes")
   • User education needed for best results

2. No conflict resolution in knowledge repo

   • User must pull before sync runs
   • Manual resolution if conflicts occur

3. Single product per repo assumed

   • Monorepos need manual setup per package
   • Future enhancement needed

4. Git-only extraction

   • Limited to commit messages
   • Doesn't capture work products from Task Copilot
   • Future integration would add depth

Documentation

Next Steps for Users

1. Create knowledge repository (if not exists):

   /knowledge-copilot
   

2. Install in your project:

   /setup-knowledge-sync
   

3. Create release tags:

   git tag v1.0.0
   git push --tags
   

4. Knowledge updates automatically

5. Access knowledge in any project:

   knowledge_search("my-product")
   

Maintenance

Adding Features

1. Update scripts in scripts/knowledge-sync/
2. Update tests in test-knowledge-sync.sh
3. Update docs in docs/50-features/03-knowledge-sync.md
4. Update README in scripts/knowledge-sync/README.md

Versioning

Scripts are versioned with Claude Copilot framework.

No separate versioning needed.

Compatibility

• Bash 3.2+ (macOS default)
• Git 2.0+
• Conventional commits (optional, recommended)

Implementation Complete: 2026-01-14 Ready for Production Use