CLAUDE.md

1# Bedrock — CLAUDE.md
2 
3Instructions for AI agents working on Obsidian vaults powered by the Bedrock plugin.
4 
5---
6 
7## What is Bedrock?
8 
9**Bedrock** is a Claude Code plugin that turns any Obsidian vault into a structured Second Brain. It provides entity management, ingestion, compression, and sync automation — all via Claude Code skills.
10 
11This is **not a codebase**. The target vault is markdown-only — no build system, no tests, no deployable artifacts. The primary consumers are humans reading in Obsidian and AI agents writing via skills.
12 
13---
14 
15## Entity Types
16 
17The vault organizes knowledge into 8 entity types, each in its own directory:
18 
19| Entity | Directory | Filename pattern | Example |
20|---|---|---|---|
21| Actors | `actors/` | `repo-name.md` | `billing-api.md` |
22| People | `people/` | `first-last.md` | `alice-smith.md` |
23| Teams | `teams/` | `squad-name.md` | `squad-payments.md` |
24| Concepts | `concepts/` | `slug.md` | `event-sourcing.md` |
25| Topics | `topics/` | `YYYY-MM-category-slug.md` | `2026-04-feature-new-checkout.md` |
26| Discussions | `discussions/` | `YYYY-MM-DD-slug.md` | `2026-04-02-daily-payments.md` |
27| Projects | `projects/` | `slug.md` | `processing-3-0.md` |
28| Fleeting | `fleeting/` | `YYYY-MM-DD-slug.md` | `2026-04-09-new-tokenization-service.md` |
29 
30Each entity type has a `_template.md` defining the required frontmatter and structure. **Always follow the template when creating new entities.**
31 
32Entity semantic definitions live in the plugin's `entities/` directory — used by `/bedrock:learn` and `/bedrock:preserve` to classify content.
33 
34---
35 
36## Writing Rules
37 
38### Language
39- **English (en-US)** for all content by default (configurable via `/bedrock:setup`)
40- Technical terms in English are accepted (PCI, API, Kafka, etc.)
41 
42### Frontmatter
43- YAML between `---` delimiters
44- **Keys always in English** (`type`, `name`, `status`, `updated_at`, `updated_by`)
45- **Values in the vault's configured language** (`description: "Billing and invoicing API"`)
46- Array references use wikilink syntax: `["[[name1]]", "[[name2]]"]`
47- Every entity must have `updated_at` (YYYY-MM-DD) and `updated_by` (person or `name@agent`)
48 
49### Wikilinks
50- Bare names only: `[[notification-service]]`, never `[[actors/notification-service]]`
51- Bidirectional links expected (see template for link table per entity type)
52- Add new links, **never remove** existing ones
53- Links to non-existent files are fine — Obsidian shows them as creation invitations
54 
55### Tags (hierarchical)
56Tags use `/` separator for multi-dimensional filtering in Obsidian graph view:
57 
58| Dimension | Prefix | Values |
59|---|---|---|
60| Type | `type/` | `actor`, `person`, `team`, `concept`, `topic`, `discussion`, `project`, `fleeting` |
61| Status | `status/` | `active`, `deprecated`, `planning`, `blocked`, `done`, `in-progress`, `open`, `completed`, `cancelled`, `raw`, `reviewing`, `promoted`, `archived` |
62| Domain | `domain/` | `payments`, `finance`, `notifications`, `checkout`, `orders`, `integrations`, `compliance`, `core`, `data`, `infra`, `marketplace`, `internal-tools`, `platform`, `security` |
63| Scope | `scope/` | `pci`, `sox`, `lgpd` (fintech), `hipaa` (health), `gdpr` (Europe), `soc2` (SaaS) |
64| Category | `category/` | `deprecation`, `bugfix`, `troubleshooting`, `rfc`, `incident`, `feature`, `compliance` |
65 
66These are examples — both domains and scopes are extensible. Add new values as your organization grows (e.g. new teams, new compliance requirements).
67 
68Rules:
69- `type/*` mandatory on all entities
70- `status/*` mandatory on actors and topics
71- `domain/*` mandatory on actors and teams
72- `scope/*` and `category/*` only when applicable
73 
74### Aliases
75- Minimum 1 alias per entity (Obsidian `aliases` field)
76- Must not duplicate the filename
77- Format: `aliases: ["Readable Name", "Acronym"]`
78 
79### Callouts
80| Callout | When | Mandatory? |
81|---|---|---|
82| `> [!warning] Deprecated` | Actor/topic with status deprecated | Yes |
83| `> [!danger] PCI Scope` | Actor with `pci: true` | Yes |
84| `> [!danger] SOX Scope` | Actor with SOX scope | Yes |
85| `> [!info]`, `> [!todo]`, `> [!bug]` | Contextual highlights | No — use sparingly |
86 
87### Filenames
88- Kebab-case, no accents, lowercase
89- Actor filenames = GitHub repository name (canonical identifier)
90 
91---
92 
93## Update Rules
94 
95| Entity | Body | Frontmatter |
96|---|---|---|
97| **Actors** | May modify and merge — new data replaces stale content | Merge new data, never delete fields |
98| **People, Teams, Concepts, Topics** | Append-only — never delete content from another agent/human | Merge new data, never delete fields |
99| **All** | Never remove existing wikilinks | Always update `updated_at` and `updated_by` |
100 
101---
102 
103## Skills
104 
105These are the Claude Code skills provided by the Bedrock plugin:
106 
107| Skill | Purpose |
108|---|---|
109| `/bedrock:ask` | Orchestrated vault reader — decomposes questions, searches graph and vault, cross-references entities |
110| `/bedrock:learn` | Ingest external sources (Confluence, Google Docs, GitHub repositories, remote URLs, and any file format supported by docling — DOCX, PPTX, XLSX, PDF, HTML, EPUB, images, and more) — extracts entities — delegates to `/bedrock:preserve` |
111| `/bedrock:preserve` | Single write point — entity detection, matching, create/update, bidirectional links, git commit |
112| `/bedrock:compress` | Vault alignment engine — fixes broken backlinks, concept fragmentation, entity miscategorization, duplicated entities, misnamed entities. Supports `--mode cron` for scheduled execution |
113| `/bedrock:healthcheck` | Read-only vault health diagnostic — checks graphify-out integrity, setup, orphan entities, dangling content, old content (>15 days). Safe to run at any frequency |
114| `/bedrock:sync` | Re-sync entities with external sources. Flags: `--people` (sync contributors), `--github` (sync PRs/activity) |
115| `/bedrock:vaults` | Manage registered vaults — list, set default (`--set-default <name>`), remove (`--remove <name>`) |
116 
117---
118 
119## Vault Resolution
120 
121Bedrock supports multiple vaults. Each vault is registered by name in a global registry
122(`vaults.json` in the plugin directory) during `/bedrock:setup`. Skills can target any
123registered vault using the `--vault <name>` flag, regardless of the current working directory.
124 
125### Registry
126 
127The vault registry lives at `<plugin_dir>/vaults.json` with this schema:
128 
129```json
130{
131  "vaults": [
132    { "name": "my-vault", "path": "/absolute/path/to/vault", "default": true },
133    { "name": "team-vault", "path": "/absolute/path/to/team-vault", "default": false }
134  ]
135}
136```
137 
138- Vault names are **kebab-case**, lowercase, unique
139- Exactly one vault is marked as `"default": true`
140- The registry is created automatically during `/bedrock:setup`
141- Manage vaults with `/bedrock:vaults` (list, set-default, remove)
142 
143### Resolution Precedence
144 
145When a skill needs to determine which vault to operate on, it follows this chain:
146 
1471. **Explicit flag** — `--vault <name>` targets the named vault from the registry
1482. **CWD detection** — if the current directory is inside a registered vault path, use that vault
1493. **Default vault** — use the vault marked as default in the registry
1504. **Error** — no vault resolved; display available vaults and ask the user to specify
151 
152This keeps full backward compatibility — users already working inside a vault directory
153don't need to change anything.
154 
155### Plugin Reinstall Note
156 
157If the Bedrock plugin is reinstalled, the `vaults.json` registry file may be lost.
158Vault data on disk is unaffected. Re-run `/bedrock:setup` inside each vault to
159re-register it.
160 
161---
162 
163## Git Workflow
164 
165Bedrock supports 3 git strategies, configured via `.bedrock/config.json` (`git.strategy` field):
166 
167| Strategy | Behavior | When to use |
168|---|---|---|
169| `commit-push` (default) | Commit + push to `main` + rebase retry (max 2 attempts) | Solo vaults, trusted contributors |
170| `commit-push-pr` | Commit to branch + push + open PR targeting `main` via `gh` CLI | Team vaults requiring review |
171| `commit-only` | Commit locally, no push | Offline or local-only vaults |
172 
173When `git.strategy` is absent from config (or `.bedrock/config.json` does not exist), all skills default to `commit-push` for backwards compatibility.
174 
175**Branch naming for `commit-push-pr`:** `vault/<YYYY-MM-DD>-<slug>` where `<slug>` is derived from the commit message (entity name, `batch-N-entities`, `compress-N-entities`, etc.). If the branch already exists, a counter is appended (e.g., `-2`).
176 
177- **Pull before write**: `git pull --rebase origin main`
178- **Commit convention**: `vault(<type>): <verb> <name> [source: <origin>]`
179 
180| Field | Values |
181|---|---|
182| `<type>` | `person`, `team`, `actor`, `concept`, `topic`, `discussion`, `project`, `note` |
183| `<verb>` | `creates`, `updates`, `links`, `compresses` |
184| `<origin>` | `memory`, `github`, `jira`, `confluence`, `gdoc`, `sheets`, `manual`, `compress` |
185 
186Examples:
187```
188vault(actor): updates billing-api [source: github]
189vault: teaches roadmap-26q1, creates 7 topics [source: confluence]
190vault: compresses 25 entities across 8 clusters [source: compress]
191```
192 
193### Error Reporting
194 
195The plugin includes a `Stop` hook (`hooks/error_reporter.py`) that auto-creates
196GitHub issues on framework errors. Disable per-vault with
197`"error_reporting": false` in `.bedrock/config.json`. Default: `true`.
198 
199---
200 
201## Zettelkasten Principles
202 
203The vault follows adapted Zettelkasten principles. Each entity type has a **role** in the knowledge graph:
204 
205| Role | Entity types | Behavior |
206|---|---|---|
207| **Permanent notes** | `actors/`, `people/`, `teams/`, `concepts/` | Consolidated, stable knowledge. Self-contained. |
208| **Bridge notes** | `topics/`, `discussions/` | Connect permanents, explaining *why* they relate. |
209| **Index notes** | `projects/` | Curation — organize reading paths (thematic MOCs). |
210| **Fleeting notes** | `fleeting/` | Inbox — raw ideas, forming concepts. Temporary by design. |
211 
212### Linking Rules
213 
2141. **Frontmatter = structural.** Arrays in frontmatter define organizational relationships (team, members, actors). Feed Dataview queries.
2152. **Body = semantic.** Wikilinks in the body must have textual context: "processes payments via [[billing-api]]", not just "[[billing-api]]".
2163. **Bridges are the connective tissue.** If two actors relate, the explanation lives in a topic or discussion — not duplicated in both.
2174. **Index notes point, they don't explain.** Projects direct the reader to bridges and permanents.
2185. **Fleeting notes are temporary.** They should be promoted (to permanent/bridge) or archived.
2196. **Provenance via `sources` field.** Every entity can record where its data came from in the `sources` frontmatter field (list of `{url, type, synced_at}`). See `entities/sources-field.md` in the plugin.
220 
221Details in `entities/*.md` (section "Zettelkasten Role" per type) within the plugin directory.
222 
223---
224 
225## Don'ts
226 
227- **Never** use flat tags (`[actor]`) — always hierarchical (`[type/actor]`)
228- **Never** use path-qualified wikilinks — `[[name]]`, not `[[dir/name]]`
229- **Never** use display names in wikilinks — `[[notification-service]]`, not `[[NotificationService]]`
230- **Never** delete content in people/teams/concepts/topics written by another agent or human
231- **Never** delete existing wikilinks or frontmatter fields
232- **Never** commit credentials, tokens, PANs, CVVs, or any sensitive data
233- **Never** log raw card data (PAN, CVV, tracks, EMV) in documentation examples
234