Awesome-omni-skill sync-docs

Strategic documentation sync - review docs before implementation (pull context) OR export learnings after implementation (push to living docs). NOT bidirectional - two separate one-way operations at different phases.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/documentation/sync-docs" ~/.claude/skills/diegosouzapw-awesome-omni-skill-sync-docs && rm -rf "$T"

manifest: skills/documentation/sync-docs/SKILL.md

source content

Sync Documentation

You are executing the SpecWeave strategic documentation sync command. This handles phase-based documentation synchronization:

Review mode: Pull strategic docs for pre-implementation context
Update mode: Push implementation learnings to living docs

Note: This is NOT bidirectional sync (simultaneous two-way). It's two separate one-way operations at different project phases.

STEP 1: Parse Arguments and Detect Mode

Arguments provided: [user's arguments]

Parse the input:

Check for explicit mode:
```
review
```
,
```
update
```
, or none (auto-detect)
Check for increment ID:
```
0001
```
,
```
0002
```
, etc., or none (sync all - NEW DEFAULT)
Check for
```
--all
```
flag (explicit sync all)

DEFAULT BEHAVIOR:

No arguments → Sync all increments with spec.md (batch mode)
Specific increment ID → Sync that increment only
--all
flag → Sync all increments (explicit)

Auto-detect logic:

If no increment ID provided (NEW DEFAULT):

# Sync ALL increments with spec.md
echo "🔄 Syncing all increments..."
npx specweave sync-specs
# This will sync all non-archived increments

If increment ID provided:

# Read the increment's spec.md to check status
INCREMENT_PATH=".specweave/increments/{increment_id}"
STATUS=$(grep "^status:" "$INCREMENT_PATH/spec.md" | cut -d: -f2 | tr -d ' ')

Determine mode:

If no increment ID → BATCH SYNC MODE (sync all)

If increment ID provided:
  If status = "planned" → REVIEW MODE
  If status = "in-progress" → UPDATE MODE
  If status = "completed" → UPDATE MODE
  If status = "closed" → UPDATE MODE

If explicit mode provided → Use that mode

Output (Batch Mode):

🔄 Syncing all increments...

📚 Syncing 0040-vitest-living-docs-mock-fixes → FS-040...
   ✅ Synced 3 tasks to US-001
✅ Synced 0040 → FS-040

📚 Syncing 0041-living-docs-test-fixes → FS-041...
   ✅ Synced 2 tasks to US-001
✅ Synced 0041 → FS-041

✅ Sync complete: 15 increments synced, 0 failed

Output (Single Mode):

🔍 Detected increment: {increment_id}
📊 Status: {status}
🎯 Mode: {REVIEW or UPDATE}

Proceeding with {mode} mode...

STEP 2A: REVIEW MODE (Pre-Implementation)

Execute this if mode = REVIEW

Review Mode Purpose

Present strategic documentation to user for approval before implementation starts.

Execution Steps:

Locate increment folder:

INCREMENT_DIR=".specweave/increments/{increment_id}"

Read all strategic documentation:

# Required files
SPEC_MD="$INCREMENT_DIR/spec.md"

# Optional files
PM_ANALYSIS="$INCREMENT_DIR/pm-analysis.md"
ARCHITECTURE="$INCREMENT_DIR/architecture.md"
INFRASTRUCTURE="$INCREMENT_DIR/infrastructure.md"
SECURITY="$INCREMENT_DIR/security.md"
TEST_STRATEGY="$INCREMENT_DIR/test-strategy.md"
PLAN="$INCREMENT_DIR/plan.md"

Read related ADRs:

# Check for ADRs referenced in plan.md or architecture.md
ADR_DIR=".specweave/docs/internal/architecture/adr"

Present comprehensive summary:

═══════════════════════════════════════════════════════
📋 STRATEGIC DOCUMENTATION REVIEW
═══════════════════════════════════════════════════════

Increment: {increment_id}
Title: {title from spec.md}
Priority: {priority from spec.md}
Status: {status from spec.md}

───────────────────────────────────────────────────────
✅ PRODUCT SPECIFICATION (spec.md)
───────────────────────────────────────────────────────

[Summarize spec.md content - user stories, requirements, acceptance criteria]

{If pm-analysis.md exists:}
───────────────────────────────────────────────────────
✅ PRODUCT STRATEGY (pm-analysis.md)
───────────────────────────────────────────────────────

User Personas:
[List personas with needs and pain points]

Business Model:
[Revenue model, target metrics]

Feature Prioritization:
[P1/P2/P3 breakdown]

Success Metrics:
[Key metrics to track]

{If architecture.md exists:}
───────────────────────────────────────────────────────
✅ SYSTEM ARCHITECTURE (architecture.md)
───────────────────────────────────────────────────────

Tech Stack:
[List detected or specified tech stack]

System Design:
[Show Mermaid diagram if present, or describe architecture]

Data Models:
[List key entities and relationships]

API Design:
[List key endpoints or interfaces]

Scalability Considerations:
[Performance targets, scaling strategy]

{If ADRs referenced:}
───────────────────────────────────────────────────────
✅ ARCHITECTURE DECISIONS (ADRs)
───────────────────────────────────────────────────────

[For each ADR mentioned in plan.md:]
ADR {number}: {title}
  - Decision: {what was decided}
  - Rationale: {why}
  - Trade-offs: {consequences}

{If infrastructure.md exists:}
───────────────────────────────────────────────────────
✅ INFRASTRUCTURE (infrastructure.md)
───────────────────────────────────────────────────────

Platform: {platform choice}
Resources: {compute, storage, database specs}
Deployment: {deployment strategy}
Monitoring: {monitoring tools}
Cost Estimate: {monthly cost breakdown}

{If security.md exists:}
───────────────────────────────────────────────────────
✅ SECURITY (security.md)
───────────────────────────────────────────────────────

Authentication: {auth strategy}
Authorization: {authz strategy}
Data Protection: {encryption, GDPR compliance}
Security Testing: {security test plan}

{If test-strategy.md exists:}
───────────────────────────────────────────────────────
✅ TEST STRATEGY (test-strategy.md)
───────────────────────────────────────────────────────

Test Pyramid:
[E2E, Integration, Unit test breakdown]

Coverage Target: {target %}

Critical Paths:
[List critical user journeys to test]

{If plan.md exists:}
───────────────────────────────────────────────────────
⏱️  IMPLEMENTATION PLAN (plan.md)
───────────────────────────────────────────────────────

Total Tasks: {count}
Estimated Time: {estimate}

Phases:
[List implementation phases with task ranges]

───────────────────────────────────────────────────────
💰 COST & TIMELINE SUMMARY
───────────────────────────────────────────────────────

Infrastructure: ${monthly cost}/month
External Services: ${services cost}/month
Total Monthly: ${total}/month

Development Time: {weeks} weeks
Launch Target: {date estimate}

═══════════════════════════════════════════════════════

❓ Do you approve this plan?

Options:
  ✅ Type "approve" - Proceed with implementation
  ⚠️  Type "changes" - Request specific updates
  📋 Type "questions" - Ask clarifying questions
  🔄 Type "regenerate" - Regenerate strategic analysis

───────────────────────────────────────────────────────

Wait for user response:
- If "approve" → Say: "✅ Strategic documentation approved. Ready to proceed with
```
/do
```
  command."
- If "changes" → Ask: "What would you like to change? (architecture/features/security/infrastructure/other)"
- If "questions" → Ask: "What questions do you have?"
- If "regenerate" → Ask: "Which section should I regenerate?"

STOP HERE for review mode - Do not proceed to update mode.

STEP 2B: UPDATE MODE (Post-Implementation)

Execute this if mode = UPDATE

Update Mode Purpose

Synchronize living documentation in

.specweave/docs/

with learnings and decisions from completed or in-progress increment.

Execution Steps:

0. 🔄 SYNC LIVING SPECS (User Stories, ACs, Tasks) - CRITICAL FIRST STEP

🚨 MANDATORY: This MUST run FIRST before syncing strategic docs!

Execute the living specs sync using the TypeScript CLI:

import { syncSpecs } from './dist/src/cli/commands/sync-specs.js';

console.log('═══════════════════════════════════════════════════════');
console.log('📋 STEP 0: SYNCING LIVING SPECS');
console.log('═══════════════════════════════════════════════════════\n');
console.log('🔄 Syncing user stories, acceptance criteria, and tasks...\n');

// Call sync-specs to sync living docs structure
await syncSpecs(['{increment_id}']);

console.log('\n✅ Living specs synced successfully!');
console.log('   - User stories created/updated in .specweave/docs/internal/specs/');
console.log('   - Acceptance criteria synchronized with completion status');
console.log('   - Tasks linked to user stories\n');

What this step does:

✅ Parses increment spec.md and extracts user stories with ACs
✅ Syncs AC completion status from spec.md to user story files
✅ Updates task mappings in user story files
✅ Creates/updates feature files and README
✅ Ensures living specs are in sync BEFORE strategic docs

Output:

🎯 Target increment: {increment_id}
📁 Increment path: .specweave/increments/{increment_id}
🔄 Mode: Specs-only sync (Universal Hierarchy)

Processing...
📚 Syncing {increment_id} → {FS-XXX}...
   ✅ Synced 3 tasks to US-001
   ✅ Synced 2 tasks to US-002

✅ Synced {increment_id} → {FS-XXX}
   Created: 5 files

═══════════════════════════════════════════════════════

CRITICAL: If this step fails, STOP and report error. Do not proceed to strategic docs sync.

1. Analyze Increment Artifacts

INCREMENT_DIR=".specweave/increments/{increment_id}"

# Read all increment files
SPEC="$INCREMENT_DIR/spec.md"
PLAN="$INCREMENT_DIR/plan.md"
ARCHITECTURE="$INCREMENT_DIR/architecture.md"
SECURITY="$INCREMENT_DIR/security.md"
INFRASTRUCTURE="$INCREMENT_DIR/infrastructure.md"
REPORTS_DIR="$INCREMENT_DIR/reports"

# List all report files
REPORTS=$(ls -1 "$REPORTS_DIR"/*.md 2>/dev/null)

Extract documentation updates:

Reading increment {increment_id}...

📄 Files found:
  ✓ spec.md
  {✓ or ✗ for each optional file}
  ✓ {count} reports in reports/

🔍 Analyzing for documentation updates...

2. Identify Documentation Targets

Map increment content to living docs locations:

# Mapping rules:
spec.md (new features):
  → .specweave/docs/public/overview/features.md
  → .specweave/docs/public/guides/ (if guides section present)

spec.md (API changes):
  → .specweave/docs/public/api/ (if exists)

plan.md (architecture decisions):
  → .specweave/docs/internal/architecture/adr/NNNN-decision-name.md (create new ADR)

plan.md (tech stack changes):
  → .specweave/docs/internal/architecture/README.md

architecture.md:
  → .specweave/docs/internal/architecture/diagrams/ (extract diagrams)
  → .specweave/docs/internal/architecture/system-design.md

security.md:
  → .specweave/docs/internal/security/

infrastructure.md:
  → .specweave/docs/internal/operations/deployment.md
  → .specweave/docs/internal/operations/infrastructure.md

reports/*.md (learnings):
  → .specweave/docs/internal/delivery/guides/
  → .specweave/docs/internal/architecture/ (if architectural learnings)

test-strategy.md:
  → .specweave/docs/internal/testing/

Output:

📊 Documentation updates identified:

1. New ADR needed: {decision from plan.md}
   Target: .specweave/docs/internal/architecture/adr/NNNN-{slug}.md

2. Feature list update: {feature from spec.md}
   Target: .specweave/docs/public/overview/features.md

3. Architecture diagram update: {diagram from architecture.md}
   Target: .specweave/docs/internal/architecture/diagrams/{name}.md

{... list all updates}

Total: {count} documentation updates

3. Detect Conflicts

For each target file that already exists:

Read existing content
Read new content from increment
Compare and detect conflicts:

function detectConflict(existingContent, newContent, section) {
  // Types of conflicts:

  // 1. Addition (no conflict)
  if (!existingContent.includes(section) && newContent.includes(section)) {
    return { type: 'addition', conflict: false };
  }

  // 2. Enhancement (minor conflict - check if contradictory)
  if (existingContent.includes(section) && newContent.includes(section)) {
    // Check if new content contradicts existing
    if (isContradictory(existingContent, newContent)) {
      return { type: 'contradiction', conflict: true };
    } else {
      return { type: 'enhancement', conflict: false };
    }
  }

  // 3. Removal (conflict)
  if (existingContent.includes(section) && !newContent.includes(section)) {
    return { type: 'removal', conflict: true };
  }

  return { type: 'no_change', conflict: false };
}

Conflict detection heuristics:

Keywords that indicate contradiction: "instead of", "rather than", "changed from", "no longer", "deprecated"
Architecture decisions with different choices (PostgreSQL vs MongoDB)
Security policies with different rules
API endpoints with different signatures

Output:

🔍 Conflict detection results:

✅ No conflict: {count} additions/enhancements
⚠️  Conflicts found: {count} contradictions/removals

{If conflicts found, list them}

4. Resolve Conflicts (If Any)

For each conflict, present to user:

═══════════════════════════════════════════════════════
⚠️  CONFLICT #{n}/{total}
═══════════════════════════════════════════════════════

File: {target_file_path}
Section: {section_name}
Conflict Type: {contradiction/removal}

───────────────────────────────────────────────────────
📄 EXISTING CONTENT
───────────────────────────────────────────────────────
{show existing content with context - 5 lines before/after}

───────────────────────────────────────────────────────
🆕 NEW CONTENT (from increment {increment_id})
───────────────────────────────────────────────────────
{show new content with context}

───────────────────────────────────────────────────────
❓ How should I resolve this?
───────────────────────────────────────────────────────

A) Keep existing only
B) Replace with new only
C) Merge both (document the evolution)
D) Show me more context
E) Skip this update

{If architecture decision:}
💡 Recommendation: Option C - Create new ADR documenting the change

Your choice (A/B/C/D/E):

Wait for user input, then record decision

5. Apply Updates

For each update (non-conflicting + resolved conflicts):

If creating new file:

TARGET_FILE="{path}"
mkdir -p "$(dirname "$TARGET_FILE")"
cat > "$TARGET_FILE" <<EOF
{content}
EOF

Output:

✅ Created: {file_path}

If updating existing file:

# Backup first
cp "$TARGET_FILE" "$TARGET_FILE.backup"

# Apply update (append, replace section, or merge)
{update logic based on user choice}

Output:

✅ Updated: {file_path}

If creating new ADR:

# Get next ADR number
NEXT_ADR=$(ls -1 .specweave/docs/internal/architecture/adr/ | grep -E '^[0-9]{4}' | sort -r | head -1 | cut -d- -f1)
NEXT_ADR=$((NEXT_ADR + 1))
NEXT_ADR=$(printf "%04d" $NEXT_ADR)

ADR_FILE=".specweave/docs/internal/architecture/adr/${NEXT_ADR}-{slug}.md"

ADR Template:

# ADR-{number}: {Title}

**Status**: Accepted
**Date**: {current_date}
**Deciders**: {team}
**Supersedes**: {previous_adr if applicable}

## Context

{describe the problem/decision point from increment}

## Decision

{what was decided during implementation}

## Rationale

{why this decision was made - from plan.md or reports/}

## Consequences

### Positive
{benefits}

### Negative
{trade-offs or limitations}

## Implementation

{how it was implemented - reference increment {increment_id}}

## Related

- Increment: {increment_id}
- {other related ADRs}

Output:

✅ Created ADR: {adr_file}

6. Summary Report

═══════════════════════════════════════════════════════
✅ DOCUMENTATION SYNC COMPLETE
═══════════════════════════════════════════════════════

Increment: {increment_id} ({title})
Status: {status} → Documentation Updated

───────────────────────────────────────────────────────
📋 LIVING SPECS SYNCED (Step 0)
───────────────────────────────────────────────────────

✅ User Stories: {count} created/updated in .specweave/docs/internal/specs/
✅ Acceptance Criteria: Synchronized with completion status from spec.md
✅ Tasks: Linked to user stories with completion tracking
✅ Feature Files: Created/updated in .specweave/docs/internal/specs/{project}/

───────────────────────────────────────────────────────
📊 STRATEGIC DOCS CHANGES (Steps 1-5)
───────────────────────────────────────────────────────

Created:
  {list of new files with paths}
  Total: {count} files

Updated:
  {list of updated files with paths}
  Total: {count} files

ADRs Generated:
  {list of new ADRs}
  Total: {count} ADRs

Skipped:
  {list of skipped updates due to user choice}
  Total: {count} updates

───────────────────────────────────────────────────────
💾 BACKUPS
───────────────────────────────────────────────────────

{If any files were updated:}
Backup files created: {count}
Location: {original_file}.backup

To restore: cp {file}.backup {file}

───────────────────────────────────────────────────────
🎯 NEXT STEPS
───────────────────────────────────────────────────────

1. Review updated documentation:
   - Living specs: .specweave/docs/internal/specs/
   - Public docs: .specweave/docs/public/
   - Internal docs: .specweave/docs/internal/
   - New ADRs: .specweave/docs/internal/architecture/adr/

2. Verify living specs sync:
   - Check user story files for updated AC checkboxes
   - Verify tasks are linked correctly
   - Confirm feature files are up to date

3. (Optional) Generate Docusaurus site:
   - Use 'docusaurus' skill to publish updated docs

4. Commit changes:
   git add .specweave/docs/
   git commit -m "docs: sync from increment {increment_id}"

═══════════════════════════════════════════════════════

ALL documentation is now in sync with increment {increment_id}! 🎉
(Living specs + Strategic docs)

STEP 3: Configuration Support

Check for user configuration (optional):

If config exists, respect it. If not, use defaults shown above.

ERROR HANDLING

Error: Increment Not Found

❌ Error: Increment '{increment_id}' not found

Available increments:
  {list .specweave/increments/*/}

Usage: /sw:sync-docs [review|update] [increment_id]

Error: No Increment Files

❌ Error: Increment '{increment_id}' has no spec.md

This increment may be incomplete. Expected files:
  - spec.md (required)
  - plan.md (optional)
  - architecture.md (optional)

Cannot proceed with sync.

Error: Invalid Mode

❌ Error: Invalid mode '{mode}'

Valid modes:
  - review (pre-implementation doc review)
  - update (post-implementation doc sync)
  - [none] (auto-detect based on status)

Usage: /sw:sync-docs [review|update] [increment_id]

EXAMPLES

Example 1: Sync all increments (NEW DEFAULT)

User: /sw:sync-docs

Output:
🔄 Syncing all increments...

📚 Syncing 0040-vitest-living-docs-mock-fixes → FS-040...
   ✅ Synced 3 tasks to US-001
✅ Synced 0040 → FS-040

📚 Syncing 0041-living-docs-test-fixes → FS-041...
   ✅ Synced 2 tasks to US-001
✅ Synced 0041 → FS-041

📚 Syncing 0042-test-infrastructure-cleanup → FS-042...
   ✅ Synced 5 tasks to US-002
✅ Synced 0042 → FS-042

✅ Sync complete: 15 increments synced, 0 failed

Example 2: Sync specific increment

User: /sw:sync-docs 0042

Output:
🔍 Detected increment: 0042
📊 Status: completed
🎯 Mode: UPDATE

Proceeding with UPDATE mode...
{... executes update mode for 0042 only}

Example 3: Explicit review mode

User: /sw:sync-docs review 0003

Output:
🔍 Increment: 0003
📊 Status: planned
🎯 Mode: REVIEW

{... shows strategic documentation summary}

Example 4: Explicit update mode with increment

User: /sw:sync-docs update 0002

Output:
🔍 Increment: 0002
📊 Status: completed
🎯 Mode: UPDATE

{... executes update mode with conflict resolution}

IMPORTANT NOTES

Always show progress: Keep user informed at each step
Always ask on conflicts: Never overwrite without user approval
Always create backups: Before modifying existing files
Always provide summary: Show what changed at the end
Never skip validation: Check files exist before reading
Never assume structure: Verify .specweave/docs/ structure exists

You are now ready to execute this command. Follow the steps above precisely.