iurykrieger/claude-bedrock/sync

/bedrock:sync — Vault Synchronization

Plugin Paths

Entity definitions and templates are in the plugin directory, not in the vault root. Use the "Base directory for this skill" provided at invocation to resolve paths:

• Entity definitions: <base_dir>/../../entities/
• Templates: <base_dir>/../../templates/{type}/_template.md
• Plugin CLAUDE.md: <base_dir>/../../CLAUDE.md (already injected automatically into context)

Where <base_dir> is the path provided in "Base directory for this skill".

Vault Resolution

Resolve which vault to sync. This skill can be invoked from any directory.

Step 1 — Parse `--vault` flag: Check if the input arguments include --vault <name>. If found, extract the vault name and remove it from the arguments before parsing --people or --github.

Step 2 — Resolve vault path:

1. If `--vault <name>` was provided:

Read the vault registry at <base_dir>/../../vaults.json. Find the entry matching the name. If not found: error — "Vault <name> is not registered. Run /bedrock:vaults to see available vaults." If found: set VAULT_PATH to the entry's path value. Store the resolved vault name as VAULT_NAME.

1. If no `--vault` flag — CWD detection:

Read <base_dir>/../../vaults.json. Check if the current working directory is inside any registered vault path (CWD starts with a registered vault's absolute path). If multiple match, use the longest path (most specific). If found: set VAULT_PATH to the matching vault's path. Store its name as VAULT_NAME.

1. If CWD detection fails — default vault:

From the registry, find the vault with "default": true. If found: set VAULT_PATH to the default vault's path. Store its name as VAULT_NAME.

1. If no resolution:

Error — "No vault resolved. Available vaults:" followed by the registry listing. "Use --vault <name> to specify, or run /bedrock:setup to register a vault."

Step 3 — Validate vault path:

test -d "<VAULT_PATH>" && echo "exists" || echo "missing"

If missing: error — "Vault path <VAULT_PATH> does not exist on disk. Run /bedrock:setup to re-register."

Step 4 — Read vault config:

cat <VAULT_PATH>/.bedrock/config.json 2>/dev/null

Extract language, git.strategy, and other relevant fields for use in later phases.

From this point forward, ALL vault file operations use `<VAULT_PATH>` as the root.

• Entity directories: <VAULT_PATH>/actors/, <VAULT_PATH>/people/, etc.
• Git operations: git -C <VAULT_PATH> <command>
• When delegating to /bedrock:preserve, pass --vault <VAULT_NAME>

Overview

This skill synchronizes the vault with external sources. It operates in three modes:

Routing

Analyze the argument passed by the user:

1. If argument contains --people → go to Mode: Sync People (below)
2. If argument contains --github → go to Mode: Sync GitHub (below)
3. Otherwise → go to Mode: Sync Sources (default) (below)

Note: If no argument is passed, or the argument does not contain recognized flags,

execute the default mode (Sync Sources).

Mode: Sync Sources (default)

Overview

This skill scans the sources field of all vault entities, deduplicates by URL, fetches updated content from each external source, compares with existing entities in the vault (incremental diff), and delegates all changes to /bedrock:preserve for centralized writing.

/bedrock:sync does NOT write entities directly — all entity writing goes through /bedrock:preserve. After re-sync, /bedrock:preserve updates synced_at in the sources field of affected entities.

/bedrock:sync does NOT ingest new sources — for that, use /bedrock:learn.

You are an execution agent. Follow the phases below in order, without skipping steps.

Phase 0 — Synchronize the Vault

Execute:

git -C <VAULT_PATH> pull --rebase origin main

If the pull fails:

• No remote configured: warn "No remote configured. Working locally." and proceed.
• Pull conflict: git -C <VAULT_PATH> rebase --abort and warn the user. Do NOT proceed without resolving.
• Otherwise: proceed.

Phase 1 — Collect Syncable Sources

Provenance is recorded in the sources field of each entity's frontmatter. Scan all entities to collect unique URLs.

1. Use Grep to find entities with a non-empty sources field:

`` Grep pattern "^sources:" in directories: actors/, people/, teams/, topics/, discussions/, projects/, fleeting/ ``

1. For each file found, use Read to extract the sources field from the YAML frontmatter.

Each entry has: {url, type, synced_at}

1. Build URL → entities map:

Deduplicate by URL. For each unique URL, record all entities that reference it: `` { "https://mycompany.atlassian.net/...": { type: "confluence", synced_at: "2026-04-09", entities: ["actors/billing-api.md", "topics/2026-04-feature-x.md"] }, "https://github.com/acme-corp/billing-api": { type: "github-repo", synced_at: "2026-04-10", entities: ["actors/billing-api.md"] } } ``

1. Filter syncable sources:

• Keep only URLs with type in (confluence, gdoc, github-repo, markdown)
• Ignore URLs with type = csv or manual (log: "URL X ignored — non-syncable type")

1. Store the list of syncable URLs with their entity maps

Report: "Phase 1: N entities with sources, M unique URLs found, K syncable, J ignored (non-syncable type)."

Phase 2 — Re-read Sources

For each syncable source, fetch updated content:

2.1 Confluence

For sources with source_type: confluence:

1. Read the internal fetcher at <base_dir>/../confluence-to-markdown/SKILL.md
2. Follow its instructions to parse the URL, choose layer (MCP → API → browser), and extract content
3. The fetcher returns Markdown content and page title

2.2 Google Docs

For sources with source_type: gdoc:

1. Read the internal fetcher at <base_dir>/../gdoc-to-markdown/SKILL.md
2. Follow its instructions to parse the URL, detect document type, choose layer (MCP → API/public export → browser), and extract content
3. The fetcher returns Markdown content and document metadata

2.3 GitHub Repository

For sources with source_type: github-repo:

1. Extract owner/repo from the URL (path segments after github.com/)
2. Use GitHub MCP directly (NOT via subagent — MCP permissions are not inherited):

• mcp__plugin_github_github__get_file_contents → read the repo's README.md
• mcp__plugin_github_github__list_commits → last 10 commits
• mcp__plugin_github_github__list_pull_requests → last 5 PRs (state=all, sort=updated)

1. Compile everything into a single markdown text

Best-effort: If any MCP call fails, continue with what was obtained. Do NOT block the sync.

2.4 Local Markdown

For sources with source_type: markdown:

1. Extract the path from the url field
2. Use Read to read the file directly
3. If the file does not exist: log and skip

2.5 Error handling

• If reading a source fails (MCP unavailable, broken URL, missing file):
• Log the error: "Source X failed — reason"
• Continue with remaining sources
• Do NOT abort the entire execution for one source

Report: "Phase 2: N sources read successfully, M failed (list)."

Phase 3 — Incremental Diff + Entity Extraction

3.1 Load entity definitions

Use Read to read ALL entity definition files from the plugin (see "Plugin Paths" section): <base_dir>/../../entities/*.md These files define what each entity type is, when to create, and how to distinguish them. Internalize these definitions — you will use them to classify content.

3.2 Catalog existing entities

Use Glob to list all files in each entity directory (excluding _template.md):

• <VAULT_PATH>/actors/*.md
• <VAULT_PATH>/people/*.md
• <VAULT_PATH>/teams/*.md
• <VAULT_PATH>/topics/*.md
• <VAULT_PATH>/discussions/*.md
• <VAULT_PATH>/projects/*.md
• <VAULT_PATH>/fleeting/*.md

For each file found:

• Extract the filename without extension (e.g.: billing-api)
• Use Read to extract the name (or title) and aliases fields from the YAML frontmatter
• Store: {filename, name, aliases, type} for matching

3.3 Analyze content and detect changes

For each source successfully read in Phase 2:

1. Identify entities mentioned in the updated content:

• For each entity cataloged in Phase 3.2, check if the filename, name, or alias appears in the content
• Match rules:
• Normalize for comparison: lowercase, no accents, no hyphens
• Partial match acceptable for compound names (e.g.: "billing api" matches "billing-api")
• Do NOT match substrings of 3 letters or fewer (e.g.: "api" does NOT match "billing-api")
• Do NOT match generic words (e.g.: "company", "service", "system")

1. Compare with the source's `entities_generated`:

• Entity in content AND already in vault → candidate for update (if there is new info in the content)
• Entity in content but NOT in vault → candidate for create
• Entity in entities_generated but NOT in updated content → keep (do not delete)

1. Classify new entities:

• For create candidates, consult the entity definitions:
• "When to create" section → positive criteria
• "When NOT to create" section → exclusion criteria
• "How to distinguish from other types" section → disambiguation

> Projects: project is a valid type in extraction. When classifying new entities, > pay special attention to signals of initiatives with closed scope (deadline, deliverables, > focal points). Consult entities/project.md for creation criteria. An excerpt that > mentions migration with a deadline and responsible person is probably a project, not a topic.

1. Record for each detected entity:

• Type (actor, person, team, topic, discussion, project)
• Canonical name (filename or suggested slug)
• Action: create or update
• Extracted info: excerpt of the content where it appears
• Source of origin: source slug

Report: "Phase 3: N entities detected (P creates, Q updates) across M sources."

Phase 4 — Consolidated Confirmation

REQUIRED: Before creating/updating any entity, present a SINGLE list with all changes from ALL sources:

## Sync — Proposed Changes
 
| # | Source | Type | Name | Action | Info |
|---|---|---|---|---|---|
| 1 | roadmap-26q1 | topic | 2026-04-feature-x | create | New topic mentioned |
| 2 | eventos-cobranca | actor | webhook-receiver | update | Description updated |
| ... | ... | ... | ... | ... | ... |
 
Total: N creates, M updates across P sources.
Confirm? (yes/no/adjust)

• yes: proceed to Phase 5
• no: abort with "Sync cancelled. No entities modified."
• adjust: ask what to adjust, modify list, re-present

If no changes detected in any source:

• Report: "No changes detected in any source. Vault is already up to date."
• Skip to Phase 6 (update last_synced anyway)

Do NOT proceed without explicit user confirmation.

Phase 5 — Delegate to /bedrock:preserve

5.1 Compile structured list

Build the entity list in the format accepted by /bedrock:preserve: