Sync Governance

Synchronise policies, guardrails, and external ADRs from Confluence to the vault.

Usage

/sync-governance                    # Incremental sync (changes since last sync)
/sync-governance --full             # Full sync (re-fetch everything)
/sync-governance --check            # Check for updates without syncing
/sync-governance --type policies    # Sync only policies
/sync-governance --type guardrails  # Sync only guardrails
/sync-governance --type adrs        # Sync only external ADRs

Overview

This skill pulls governance content from Confluence into the vault for:

• Offline access during architecture work
• Cross-referencing with local ADRs and projects
• AI-assisted analysis when creating new designs
• Version tracking to detect policy changes

Prerequisites

1. Atlassian MCP plugin connected and authenticated
2. .claude/sync/manifest.json exists (created on first run)
3. +Sync/ folder structure exists

Source Configuration

The manifest defines what to sync from Confluence:

Source	Confluence Query	Local Path
Policies	label = 'governance-policy'	+Sync/Policies/
Guardrails	label = 'governance-guardrail' OR pages in guardrail directories	+Sync/Guardrails/
Organisational ADRs	label = 'Approved_Architecture_ADR' OR label = 'Approved_Technology_Guardrail'	+Sync/Org-ADRs/

Key Confluence Spaces

Space	Key	Content
YourOrg Architecture and Engineering	BAAandE	ADR Process, Guardrails Directory
YourOrg Digital Operating Model	BDOC	Guardrail Templates, Governance
BC3 Framework	BC3	Delivery Guardrails, Templates
DataPlatform/Integration	IO	Data Product Guardrails

Key Source Pages

Page	ID	Purpose
Directory of Architecture Guardrails	65405808	Master list of architecture guardrails
Directory of Technology Guardrails	65405938	Master list of technology guardrails
How an ADR becomes a Guardrail	65415886	Process documentation
Guardrail - Template	73040191	Template for creating guardrails

Workflow

Step 1: Initialise

Read .claude/sync/manifest.json
If not exists:
  Create +Sync/ folder structure
  Create initial manifest with default sources

Step 2: Query for Updates

For each source in manifest, use Atlassian MCP:

// Example: Find all architecture guardrails
searchConfluenceUsingCql(
  cloudId: "c1f0e5f8-ba19-4251-8d78-db300e0715bf",
  cql: "label = 'Approved_Architecture_Guardrail' AND type = 'page'",
  limit: 100
)

// Example: Find pages in guardrails directory
getConfluencePageDescendants(
  cloudId: "c1f0e5f8-ba19-4251-8d78-db300e0715bf",
  pageId: "65405808"  // Directory of Architecture Guardrails
)

Step 3: Compare Versions

For each page returned:

• Check if page ID exists in manifest.pages
• Compare Confluence version number to stored version
• Categorise as: new, updated, or unchanged

Step 4: Fetch Changed Content

For each new/updated page:

getConfluencePage(
  cloudId: "c1f0e5f8-ba19-4251-8d78-db300e0715bf",
  pageId: "<page-id>",
  contentFormat: "markdown"
)

Step 5: Convert to Vault Format

Create note with appropriate frontmatter based on content type:

Policy Note:

---
type: Policy
title: <page title>
source: confluence
sourceSpace: <space key>
sourcePageId: "<page id>"
sourceVersion: <version number>
sourceUrl: <confluence URL>
lastSynced: <ISO timestamp>
owner: <from page metadata or content>
status: active
effectiveDate: <if found in content>
reviewDate: <if found in content>
readOnly: true
tags: [policy, synced, <derived tags>]
---

> [!warning] Read-Only Sync
> This content is synced from Confluence. Do not edit locally.
> Source: [<title>](<url>) | Version: <version> | Synced: <date>

<converted markdown content>

Guardrail Note:

---
type: Guardrail
title: <page title>
source: confluence
sourceSpace: <space key>
sourcePageId: "<page id>"
sourceVersion: <version number>
sourceUrl: <confluence URL>
lastSynced: <ISO timestamp>
owner: <from content>
scope: <derived from content: aws | azure | data | security | integration | delivery>
status: active
readOnly: true
tags: [guardrail, synced, <derived tags>]
---

Organisational ADR Note (synced from Confluence):

---
type: Adr
title: <page title>
status: <mirrors Confluence status: proposed | accepted | deprecated>
adrType: Architecture_ADR | Technology_ADR

# Source/Provenance (synced)
source: confluence
sourcePageId: "<page id>"
sourceSpace: <space key>
sourceUrl: <confluence URL>
sourceVersion: <version number>

# Sync metadata
lastSynced: <ISO timestamp>
readOnly: true

# Authority (derived from scope/labels)
authority: team | organizational      # Based on whether it's a guardrail or team decision

# Standard ADR fields
deciders: []
approvers: []
stakeholders: []
relatedTo: []
dependsOn: []

# Quality
confidence: high                      # Published ADRs are authoritative
freshness: current
verified: true

tags: [adr, synced, <derived tags>]
---

Step 6: Write Files and Update Manifest

1. Write markdown file to appropriate +Sync/ subfolder
2. Update manifest.pages entry with:
   • New version number
   • Sync timestamp
   • Local file path
   • Content hash (for change detection)
3. Update manifest.lastFullSync timestamp
4. Update manifest.stats counters

Step 7: Handle Deletions (Optional)

Pages in manifest but not returned from Confluence:

• Mark local file with status: archived in frontmatter
• Add archivedReason: "Removed from Confluence"
• Move to +Sync/_archived/ or leave in place with warning

Step 8: Generate Summary

Output sync results:

## Governance Sync Complete

**Synced at:** 2026-01-11 10:30
**Duration:** 45 seconds

| Type | New | Updated | Unchanged | Archived |
|------|-----|---------|-----------|----------|
| Policies | 0 | 1 | 8 | 0 |
| Guardrails | 2 | 0 | 15 | 0 |
| Organisational ADRs | 1 | 3 | 42 | 1 |

### Changes Detected

**Updated:**
- 📋 Policy - SAS1 Integration Standards (v2 → v3)
  - [View in Confluence](https://...)

**New:**
- 🚧 Guardrail - GR5 AI Model Governance
- 🚧 Guardrail - GR6 Third Party Data Sharing
- 📐 External ADR - Bedrock Model Selection

**Archived:**
- 📐 ~~External ADR - Legacy API Pattern~~ (removed from Confluence)

### Action Required
- Review updated Policy - SAS1 for impact on current projects

Scheduling Integration

With Daily Note

The /daily skill can check sync freshness:

## In /daily skill, add section:

### Governance Freshness Check

Read manifest.lastFullSync
If older than 24 hours:
  Display: "⚠️ Governance content last synced X hours ago"
  Offer: "Run /sync-governance to update"

Staleness Check Before ADR Creation

The /adr skill should check freshness:

## Before creating ADR:

If manifest.lastFullSync > 24 hours:
  Warn: "Governance policies may be stale. Sync first?"

Manifest Schema

.claude/sync/manifest.json:

{
  "version": "1.0",
  "lastFullSync": "2026-01-11T06:00:00Z",
  "cloudId": "c1f0e5f8-ba19-4251-8d78-db300e0715bf",
  "sources": [
    {
      "name": "Architecture Guardrails",
      "type": "guardrails",
      "method": "descendants",
      "rootPageId": "65405808",
      "localPath": "+Sync/Guardrails/Architecture/",
      "filenamePattern": "Guardrail - {title}.md"
    },
    {
      "name": "Technology Guardrails",
      "type": "guardrails",
      "method": "descendants",
      "rootPageId": "65405938",
      "localPath": "+Sync/Guardrails/Technology/",
      "filenamePattern": "Guardrail - {title}.md"
    },
    {
      "name": "Approved ADRs",
      "type": "adrs",
      "method": "label",
      "cql": "label = 'Approved_Architecture_ADR' AND type = 'page'",
      "localPath": "+Sync/Org-ADRs/",
      "filenamePattern": "ADR - {title}.md"
    }
  ],
  "pages": {
    "65415886": {
      "title": "How an ADR becomes a Guardrail",
      "space": "BAAandE",
      "version": 12,
      "type": "process",
      "localFile": "+Sync/Process/Process - How an ADR becomes a Guardrail.md",
      "lastSynced": "2026-01-11T06:00:00Z",
      "hash": "abc123def456"
    }
  },
  "stats": {
    "totalPolicies": 12,
    "totalGuardrails": 23,
    "totalAdrs": 45,
    "lastChangeDetected": "2026-01-10T14:30:00Z"
  }
}

First Run Setup

On first run when no manifest exists:

1. Create folder structure:

   +Sync/
   ├── Policies/
   ├── Guardrails/
   │   ├── Architecture/
   │   └── Technology/
   ├── Org-ADRs/
   ├── Process/
   └── _archived/
   

2. Create initial manifest.json with organization-specific sources

3. Perform full sync

4. Report initial inventory

Error Handling

Error	Action
Atlassian auth failure	Prompt to re-authenticate
Page not accessible	Skip and log warning
Rate limit hit	Pause and retry with backoff
Malformed content	Skip page, log error
Write failure	Abort sync, preserve manifest

Related

• [[Incubator - Architecture as Code]]
• [[Incubator Note - Using Atlassian MCP for Policies]]
• [[Incubator - How to Develop a Guardrail]]
• [[Page - How an ADR becomes a Guardrail]] (synced from Confluence)