Initial commit
This commit is contained in:
Zhongwei Li
431
.claude/skills/project-docs-sync/SKILL.md
Normal file
431
.claude/skills/project-docs-sync/SKILL.md
Normal file
@@ -0,0 +1,431 @@
|
||||
---
|
||||
name: project-docs-sync
|
||||
description: Automatically synchronize project documentation when major changes occur (new tech, architecture changes, requirements shifts). Detects significant updates and propagates changes across TECH-STACK.md, ARCHITECTURE.md, and SPECIFICATIONS.md.
|
||||
---
|
||||
|
||||
# Project Documentation Sync Skill
|
||||
|
||||
**Purpose**: Keep project documentation consistent without manual syncing overhead.
|
||||
|
||||
**Trigger**: Auto-invoked by PostToolUse hook when files in `project-management/` are edited.
|
||||
|
||||
---
|
||||
|
||||
## Decision Logic: Should We Sync?
|
||||
|
||||
```python
|
||||
def should_sync(change: dict) -> tuple[bool, str]:
|
||||
"""Conservative sync decision - only on big changes."""
|
||||
|
||||
# Track last sync state
|
||||
last_sync = load_last_sync() # from .meta/last-sync.json
|
||||
|
||||
significant_changes = {
|
||||
# Technology changes
|
||||
"added_technology": True, # New language, framework, library
|
||||
"removed_technology": True, # Deprecated/removed tech
|
||||
"upgraded_major_version": True, # React 17 → 18, Python 3.10 → 3.11
|
||||
|
||||
# Architecture changes
|
||||
"added_service": True, # New microservice, component
|
||||
"removed_service": True, # Deprecated service
|
||||
"changed_data_flow": True, # New integration pattern
|
||||
"added_integration": True, # New third-party API
|
||||
|
||||
# Requirements changes
|
||||
"new_security_requirement": True,
|
||||
"new_performance_requirement": True,
|
||||
"changed_api_contract": True,
|
||||
"added_compliance_need": True,
|
||||
}
|
||||
|
||||
# Skip minor changes
|
||||
minor_changes = {
|
||||
"typo_fix": False,
|
||||
"formatting": False,
|
||||
"comment_update": False,
|
||||
"example_clarification": False,
|
||||
}
|
||||
|
||||
change_type = classify_change(change, last_sync)
|
||||
return significant_changes.get(change_type, False), change_type
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What Gets Synced (Conservative Strategy)
|
||||
|
||||
### 1. TECH-STACK.md Changed → Update ARCHITECTURE.md
|
||||
|
||||
**Triggers:**
|
||||
- Added new language/framework (e.g., added Redis)
|
||||
- Removed technology (e.g., removed MongoDB)
|
||||
- Major version upgrade (e.g., React 17 → 18)
|
||||
|
||||
**Sync Actions:**
|
||||
```markdown
|
||||
TECH-STACK.md shows:
|
||||
+ Redis 7.x (added for caching)
|
||||
|
||||
→ Update ARCHITECTURE.md:
|
||||
- Add Redis component to architecture diagram
|
||||
- Add caching layer to data flow
|
||||
- Document Redis connection pattern
|
||||
```
|
||||
|
||||
**Example Output:**
|
||||
```
|
||||
✓ Synced TECH-STACK.md → ARCHITECTURE.md
|
||||
- Added: Redis caching layer
|
||||
- Updated: Data flow diagram (added cache lookup)
|
||||
- Reason: New technology requires architectural integration
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. ARCHITECTURE.md Changed → Update SPECIFICATIONS.md
|
||||
|
||||
**Triggers:**
|
||||
- New service/component added
|
||||
- API gateway pattern introduced
|
||||
- Data model changed
|
||||
- Integration pattern modified
|
||||
|
||||
**Sync Actions:**
|
||||
```markdown
|
||||
ARCHITECTURE.md shows:
|
||||
+ API Gateway (Kong) added between clients and services
|
||||
|
||||
→ Update SPECIFICATIONS.md:
|
||||
- Add API Gateway endpoints
|
||||
- Update authentication flow
|
||||
- Add rate limiting specs
|
||||
- Update API contract examples
|
||||
```
|
||||
|
||||
**Example Output:**
|
||||
```
|
||||
✓ Synced ARCHITECTURE.md → SPECIFICATIONS.md
|
||||
- Added: API Gateway endpoint specs
|
||||
- Updated: Authentication flow (now via gateway)
|
||||
- Reason: Architectural change affects API contracts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. PROJECT-OVERVIEW.md Changed → Validate Consistency
|
||||
|
||||
**Triggers:**
|
||||
- Project scope changed
|
||||
- New requirement category added
|
||||
- Compliance requirement added
|
||||
- Target users changed
|
||||
|
||||
**Sync Actions:**
|
||||
```markdown
|
||||
PROJECT-OVERVIEW.md shows:
|
||||
+ Compliance: GDPR data privacy required
|
||||
|
||||
→ Validate across all docs:
|
||||
- Check TECH-STACK.md has encryption libraries
|
||||
- Check ARCHITECTURE.md has data privacy layer
|
||||
- Check SPECIFICATIONS.md has GDPR endpoints (data export, deletion)
|
||||
- Flag missing pieces
|
||||
```
|
||||
|
||||
**Example Output:**
|
||||
```
|
||||
⚠ Validation: PROJECT-OVERVIEW.md → ALL DOCS
|
||||
- Missing in TECH-STACK.md: No encryption library listed
|
||||
- Missing in SPECIFICATIONS.md: No GDPR data export endpoint
|
||||
- Recommendation: Add encryption lib + GDPR API specs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Change Detection Algorithm
|
||||
|
||||
```python
|
||||
def classify_change(file_path: str, diff: str, last_sync: dict) -> str:
|
||||
"""Classify change significance using diff analysis."""
|
||||
|
||||
# Parse diff
|
||||
added_lines = [line for line in diff.split('\n') if line.startswith('+')]
|
||||
removed_lines = [line for line in diff.split('\n') if line.startswith('-')]
|
||||
|
||||
# Check for technology changes
|
||||
tech_keywords = ['framework', 'library', 'language', 'database', 'cache']
|
||||
if any(kw in line.lower() for line in added_lines for kw in tech_keywords):
|
||||
if any(removed_lines): # Replacement
|
||||
return "upgraded_major_version"
|
||||
return "added_technology"
|
||||
|
||||
# Check for architecture changes
|
||||
arch_keywords = ['service', 'component', 'layer', 'gateway', 'microservice']
|
||||
if any(kw in line.lower() for line in added_lines for kw in arch_keywords):
|
||||
return "added_service"
|
||||
|
||||
# Check for requirement changes
|
||||
req_keywords = ['security', 'performance', 'compliance', 'GDPR', 'HIPAA']
|
||||
if any(kw in line.lower() for line in added_lines for kw in req_keywords):
|
||||
return "new_security_requirement"
|
||||
|
||||
# Check for API contract changes
|
||||
if 'endpoint' in diff.lower() or 'route' in diff.lower():
|
||||
return "changed_api_contract"
|
||||
|
||||
# Default: minor change (skip sync)
|
||||
if len(added_lines) < 3 and not removed_lines:
|
||||
return "typo_fix"
|
||||
|
||||
return "unknown_change"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sync State Tracking
|
||||
|
||||
**Storage**: `.meta/last-sync.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"last_sync_timestamp": "2025-10-30T14:30:00Z",
|
||||
"synced_files": {
|
||||
"project-management/TECH-STACK.md": {
|
||||
"hash": "abc123",
|
||||
"last_modified": "2025-10-30T14:00:00Z",
|
||||
"change_type": "added_technology"
|
||||
},
|
||||
"project-management/ARCHITECTURE.md": {
|
||||
"hash": "def456",
|
||||
"last_modified": "2025-10-30T14:30:00Z",
|
||||
"synced_from": "TECH-STACK.md"
|
||||
}
|
||||
},
|
||||
"pending_syncs": []
|
||||
}
|
||||
```
|
||||
|
||||
**Update Logic**:
|
||||
1. After Write/Edit to `project-management/*.md`
|
||||
2. Calculate file hash (md5 of content)
|
||||
3. Compare with last sync state
|
||||
4. If different + significant change → Trigger sync
|
||||
5. Update `.meta/last-sync.json`
|
||||
|
||||
---
|
||||
|
||||
## Sync Execution Flow
|
||||
|
||||
```
|
||||
PostToolUse Hook Fires
|
||||
↓
|
||||
File edited: project-management/TECH-STACK.md
|
||||
↓
|
||||
Load .meta/last-sync.json
|
||||
↓
|
||||
Calculate diff from last sync
|
||||
↓
|
||||
Classify change: "added_technology" (Redis)
|
||||
↓
|
||||
Decision: should_sync() → TRUE
|
||||
↓
|
||||
┌────────────────────────────────────┐
|
||||
│ Sync: TECH-STACK → ARCHITECTURE │
|
||||
│ - Read TECH-STACK.md additions │
|
||||
│ - Identify: Redis 7.x (cache) │
|
||||
│ - Update ARCHITECTURE.md: │
|
||||
│ + Add Redis component │
|
||||
│ + Update data flow │
|
||||
└────────────────────────────────────┘
|
||||
↓
|
||||
Write updated ARCHITECTURE.md
|
||||
↓
|
||||
Update .meta/last-sync.json
|
||||
↓
|
||||
Log sync action
|
||||
↓
|
||||
Output brief sync report
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sync Report Format
|
||||
|
||||
```markdown
|
||||
## Documentation Sync Report
|
||||
|
||||
**Trigger**: TECH-STACK.md modified (added Redis)
|
||||
**Timestamp**: 2025-10-30T14:30:00Z
|
||||
|
||||
---
|
||||
|
||||
### Changes Detected: 1
|
||||
|
||||
1. **[SIGNIFICANT] Added technology: Redis 7.x**
|
||||
- **Source**: project-management/TECH-STACK.md:45
|
||||
- **Purpose**: Caching layer for API responses
|
||||
|
||||
---
|
||||
|
||||
### Syncs Applied: 2
|
||||
|
||||
1. **TECH-STACK.md → ARCHITECTURE.md**
|
||||
- ✓ Added: Redis component to architecture diagram
|
||||
- ✓ Updated: Data flow (added cache lookup step)
|
||||
- ✓ File: project-management/ARCHITECTURE.md:120-135
|
||||
|
||||
2. **TECH-STACK.md → SPECIFICATIONS.md**
|
||||
- ✓ Added: Cache invalidation API endpoint
|
||||
- ✓ Updated: Response time expectations (now <100ms with cache)
|
||||
- ✓ File: project-management/SPECIFICATIONS.md:78-82
|
||||
|
||||
---
|
||||
|
||||
### Validation Checks: 2
|
||||
|
||||
✓ TECH-STACK.md consistency: OK
|
||||
✓ ARCHITECTURE.md alignment: OK
|
||||
|
||||
---
|
||||
|
||||
**Result**: Documentation synchronized successfully.
|
||||
**Next Action**: Review changes in next commit.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with PostToolUse Hook
|
||||
|
||||
**Hook Location**: `.claude/hooks/post_tool_use_format.py`
|
||||
|
||||
**Trigger Condition**:
|
||||
```python
|
||||
def should_trigger_docs_sync(file_path: str, tool_name: str) -> bool:
|
||||
"""Only trigger on project-management doc edits."""
|
||||
|
||||
if tool_name not in ["Write", "Edit"]:
|
||||
return False
|
||||
|
||||
project_docs = [
|
||||
"project-management/TECH-STACK.md",
|
||||
"project-management/ARCHITECTURE.md",
|
||||
"project-management/PROJECT-OVERVIEW.md",
|
||||
"project-management/SPECIFICATIONS.md",
|
||||
]
|
||||
|
||||
return any(doc in file_path for doc in project_docs)
|
||||
```
|
||||
|
||||
**Invocation**:
|
||||
```python
|
||||
# In PostToolUse hook
|
||||
if should_trigger_docs_sync(file_path, tool_name):
|
||||
# Load skill
|
||||
skill_result = invoke_skill("project-docs-sync", {
|
||||
"file_path": file_path,
|
||||
"change_type": classify_change(file_path, diff),
|
||||
"last_sync_state": load_last_sync()
|
||||
})
|
||||
|
||||
# Log sync action
|
||||
log_sync_action(skill_result)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sync Strategies by File Type
|
||||
|
||||
### TECH-STACK.md → ARCHITECTURE.md
|
||||
**What to sync:**
|
||||
- New databases → Add data layer component
|
||||
- New frameworks → Add to tech stack diagram
|
||||
- New APIs → Add integration points
|
||||
- Version upgrades → Update compatibility notes
|
||||
|
||||
### ARCHITECTURE.md → SPECIFICATIONS.md
|
||||
**What to sync:**
|
||||
- New services → Add service endpoints
|
||||
- New integrations → Add API contracts
|
||||
- Data model changes → Update request/response schemas
|
||||
- Security layers → Add authentication specs
|
||||
|
||||
### PROJECT-OVERVIEW.md → ALL DOCS
|
||||
**What to validate:**
|
||||
- Compliance requirements → Check encryption in TECH-STACK
|
||||
- Performance goals → Check caching in ARCHITECTURE
|
||||
- Target users → Check API design in SPECIFICATIONS
|
||||
- Scope changes → Validate alignment across all docs
|
||||
|
||||
---
|
||||
|
||||
## Conservative Sync Rules
|
||||
|
||||
**DO Sync When:**
|
||||
- ✅ New technology added (database, framework, library)
|
||||
- ✅ Service/component added or removed
|
||||
- ✅ API contract changed (new endpoint, schema change)
|
||||
- ✅ Compliance requirement added (GDPR, HIPAA)
|
||||
- ✅ Major version upgrade (breaking changes possible)
|
||||
|
||||
**DO NOT Sync When:**
|
||||
- ❌ Typo fixes (1-2 character changes)
|
||||
- ❌ Formatting changes (whitespace, markdown)
|
||||
- ❌ Comment/example clarifications
|
||||
- ❌ Documentation of existing features (no new info)
|
||||
- ❌ Minor version bumps (patch releases)
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**If sync fails:**
|
||||
1. Log error to `.meta/sync-errors.log`
|
||||
2. Add to pending syncs in `.meta/last-sync.json`
|
||||
3. Report to user with clear action items
|
||||
4. Do NOT block the write operation (non-blocking)
|
||||
|
||||
**Example Error Report:**
|
||||
```
|
||||
⚠ Documentation Sync Failed
|
||||
|
||||
**File**: project-management/TECH-STACK.md
|
||||
**Error**: Could not parse ARCHITECTURE.md (syntax error)
|
||||
**Action Required**:
|
||||
1. Fix ARCHITECTURE.md syntax error (line 45)
|
||||
2. Re-run: /lazy docs-sync
|
||||
|
||||
**Pending Syncs**: 1 (tracked in .meta/last-sync.json)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
```bash
|
||||
# Disable auto-sync (manual /lazy docs-sync only)
|
||||
export LAZYDEV_DISABLE_DOCS_SYNC=1
|
||||
|
||||
# Sync everything (even minor changes)
|
||||
export LAZYDEV_DOCS_SYNC_AGGRESSIVE=1
|
||||
|
||||
# Sync specific files only
|
||||
export LAZYDEV_DOCS_SYNC_FILES="TECH-STACK.md,ARCHITECTURE.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What This Skill Does NOT Do
|
||||
|
||||
❌ Sync code files (only project-management docs)
|
||||
❌ Generate docs from scratch (use `/lazy docs`)
|
||||
❌ Fix documentation errors (use `/lazy fix`)
|
||||
❌ Create missing docs (use `/lazy plan`)
|
||||
|
||||
✅ **DOES**: Automatically propagate significant changes across project documentation with conservative triggers.
|
||||
|
||||
---
|
||||
|
||||
**Version**: 1.0.0
|
||||
**Non-blocking**: Syncs in background, logs errors
|
||||
**Speed**: <2 seconds for typical sync
|
||||
Reference in New Issue
Block a user