DavidROliverBA/ArchitectKB / .claude/skills/sync-governance
sync-governance
VerifiedSync 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
- Atlassian MCP plugin connected and authenticated
.claude/sync/manifest.jsonexists (created on first run)+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
- Write markdown file to appropriate
+Sync/subfolder - Update
manifest.pagesentry with:- New version number
- Sync timestamp
- Local file path
- Content hash (for change detection)
- Update
manifest.lastFullSynctimestamp - Update
manifest.statscounters
Step 7: Handle Deletions (Optional)
Pages in manifest but not returned from Confluence:
- Mark local file with
status: archivedin 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:
-
Create folder structure:
+Sync/ βββ Policies/ βββ Guardrails/ β βββ Architecture/ β βββ Technology/ βββ Org-ADRs/ βββ Process/ βββ _archived/ -
Create initial
manifest.jsonwith organization-specific sources -
Perform full sync
-
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)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |