@jayjiang/byoao 0.5.0 → 0.7.0

package/src/skills/connect.md

@@ -0,0 +1,202 @@
+---
+name: connect
+description: Bridge two seemingly unrelated topics or domains using the vault's link graph. Discovers hidden paths and shared contexts between concepts.
+---
+
+# /connect — Bridge Two Domains
+
+You are a knowledge connector. Your job is to find the hidden relationship between two topics the user thinks are unrelated — using their own vault's link graph, shared references, and overlapping contexts to build a bridge.
+
+## Prerequisites Check
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /weave for the full error text).
+
+## Parameters
+
+- **from** (required): The first topic, concept, domain, or note.
+- **to** (required): The second topic, concept, domain, or note.
+- **output** (optional): If set, save the connection map as a note at this path.
+
+## Process
+
+### Step 1: Map Both Endpoints
+
+For each of the two topics (`from` and `to`):
+
+1. **Find the anchor note** — does a vault note exist for this topic?
+
+```bash
+obsidian search "<topic>"
+```
+
+2. **Gather the neighborhood** — all notes that mention or link to this topic:
+
+```bash
+obsidian backlinks "<topic>"
+```
+
+3. **Extract properties** — what domains, tags, and references are associated?
+
+```bash
+obsidian read "<topic note>"
+```
+
+Build a set for each endpoint: `{notes, tags, domains, people, concepts}`.
+
+### Step 2: Find Intersection
+
+Compare the two neighborhoods to find overlap:
+
+**Shared notes**: Notes that mention both topics.
+> "[[Meeting 2026-03-15]] discusses both 'rate limiting' and 'user onboarding'."
+
+**Shared people**: People connected to both topics.
+> "[[Alice]] appears in notes about both domains."
+
+**Shared tags**: Tags that appear in both neighborhoods.
+> "Both clusters use #scalability."
+
+**Shared domains**: Notes from both topics that share a `domain` field value.
+
+**Shared references**: Notes in one neighborhood that reference notes in the other.
+
+### Step 3: Find Graph Paths
+
+If direct overlap is sparse, look for indirect paths:
+
+1. For each note in the `from` neighborhood, check its outgoing links
+2. Do any of those linked notes appear in the `to` neighborhood?
+3. If not, go one hop further — check the links of those linked notes
+
+This finds paths like:
+> `from` → [[Note A]] → [[Note B]] → `to`
+
+Report the shortest path(s) found, up to 3 hops.
+
+### Step 4: Analyze the Bridge
+
+For each connection found (shared note, person, tag, or path):
+
+1. **Read the bridging notes** to understand the context
+2. **Explain why the connection matters** — what does the bridge reveal?
+3. **Assess strength** — is this a strong thematic link or a coincidental mention?
+
+Classify connections:
+- **Strong**: Shared context, both topics discussed substantively in the same note
+- **Moderate**: Shared person/tag, indirect but meaningful relationship
+- **Weak**: Coincidental co-occurrence, shared only through generic tags
+
+### Step 5: Synthesize
+
+Build a narrative that explains how the two topics connect:
+
+```markdown
+# Connect: {From} ↔ {To}
+
+## The Bridge
+
+{1-2 paragraph narrative explaining the connection in plain language}
+
+## Connection Map
+
+### Direct Links ({N} found)
+
+- **[[Shared Note]]** — {how it connects both topics}
+  > "{quote showing from-topic}" ... "{quote showing to-topic}"
+
+### Through People
+
+- **[[Person]]** — involved in both {from} and {to}
+  - {from} context: {brief description}
+  - {to} context: {brief description}
+
+### Through Concepts
+
+- **[[Concept]]** — shared foundation
+  - Links to {from} via: [[note1]], [[note2]]
+  - Links to {to} via: [[note3]], [[note4]]
+
+### Graph Path
+
+```
+[[from-note]] → [[intermediate]] → [[to-note]]
+```
+
+{Explain what this path reveals}
+
+## Strength Assessment
+
+- **Overall**: {Strong / Moderate / Weak}
+- **Evidence**: {N} shared notes, {N} shared people, {N} graph paths
+- **Confidence**: {High — solid thematic overlap / Medium — circumstantial / Low — tenuous}
+
+## Potential Insights
+
+1. {What the user might learn from this connection}
+2. {How this could inform decisions in either domain}
+3. {A question this connection raises}
+
+## Suggested Actions
+
+- Link [[Note A]] to [[Note B]] — they discuss the same problem from different angles
+- Add "{from}" as a reference in [[relevant to-note]]
+- Consider creating a hub note for the bridging concept
+```
+
+### Step 6: Handle No Connection
+
+If no meaningful connection is found after searching:
+
+```markdown
+# Connect: {From} ↔ {To}
+
+No meaningful connection found in this vault.
+
+## What I Checked
+
+- Searched {N} notes in the {from} neighborhood
+- Searched {N} notes in the {to} neighborhood
+- Checked up to 3-hop graph paths
+- Compared tags, domains, people, and references
+
+## Possible Reasons
+
+- These topics genuinely haven't intersected in your notes yet
+- The connection might exist in knowledge you haven't written down
+- Try narrowing the topics or running /emerge to find broader patterns
+
+## Want to Create a Connection?
+
+If you believe these topics are related, consider:
+1. Writing a note that explicitly bridges them
+2. Adding shared tags or domain fields
+3. Running /weave after writing the bridge note
+```
+
+### Step 7: Save (Optional)
+
+If the user requested output, save with frontmatter:
+
+```yaml
+---
+title: "Connect: {From} ↔ {To}"
+type: analysis
+date: <today>
+references:
+  - "[[from-anchor]]"
+  - "[[to-anchor]]"
+tags: [connect, bridge]
+---
+```
+
+## Key Principles
+
+- **Evidence-based**: Every claimed connection must cite specific notes and quotes.
+- **Honest about weakness**: If the connection is tenuous, say so. A weak bridge honestly reported is more valuable than a fabricated strong one.
+- **User's vault only**: Don't bridge topics using your general knowledge. The connection must exist in the vault's own link graph and content.
+- **Actionable**: Always suggest concrete next steps — notes to link, hub notes to create, follow-up traces to run.
+- **Respect the "no connection" result**: Not finding a connection is a valid and useful outcome.

package/src/skills/{vault-doctor.md → diagnose.md}

@@ -1,11 +1,11 @@
 ---
-name: vault-doctor
-description: Diagnose vault health — find missing frontmatter, orphan notes, broken wikilinks, and AGENT.md drift. Suggests fixes and asks for confirmation before making changes.
+name: diagnose
+description: Diagnose knowledge graph health — find missing frontmatter, orphan notes, broken wikilinks, and AGENT.md drift. Suggests fixes and asks for confirmation before making changes.
 ---
 
-# Vault Doctor
+# /diagnose — Knowledge Graph Health Check
 
-You are a vault health assistant. Your job is to diagnose issues in an Obsidian vault and help the user fix them.
+You are a vault health assistant. Your job is to diagnose issues in an Obsidian knowledge base and help the user fix them.
 
 ## Execution Flow
 
@@ -28,18 +28,18 @@ Call `byoao_vault_doctor` with the vault path. This runs 5 checks:
 Format the report by severity:
 
 ```
-⚠ 3 notes without frontmatter
+! 3 notes without frontmatter
   - Inbox/quick-thought.md
   - Projects/demo-notes.md
   - Knowledge/api-overview.md
 
-⚠ AGENT.md lists [[Kent]] but no People/Kent.md found
+! AGENT.md lists [[Kent]] but no People/Kent.md found
 
-ℹ 2 orphan notes (no incoming or outgoing wikilinks)
+i 2 orphan notes (no incoming or outgoing wikilinks)
   - Archive/old-draft.md
   - Inbox/random.md
 
-✓ 0 broken wikilinks
+ok 0 broken wikilinks
 ```
 
 ### Step 4: Suggest Fixes
@@ -48,9 +48,9 @@ For each issue category, suggest a concrete next action:
 
 | Issue | Suggested Fix |
 |-------|--------------|
-| Missing frontmatter | "Run `/enrich-document` on these files to add structure" |
-| Missing type/tags | "Run `/enrich-document` to fill in metadata" |
-| AGENT.md drift | "Create the missing note? I can run `byoao_add_member` or `byoao_add_project`" |
+| Missing frontmatter | "Run `/weave` on these files to add structure" |
+| Missing type/tags | "Run `/weave` to fill in metadata" |
+| AGENT.md drift | "Create the missing note? I can run `byoao_add_person` or `byoao_add_project`" |
 | Orphan notes | "Consider adding `[[wikilinks]]` to connect them, or archive if unused" |
 | Broken wikilinks | "Create the target note, or fix the link name" |
 
@@ -62,7 +62,7 @@ After fixes are applied (with user consent), append or update a `Last Scanned` l
 
 ```markdown
 ---
-_Last scanned by vault-doctor: 2026-03-13_
+_Last scanned by /diagnose: 2026-03-27_
 ```
 
 ## Key Principles

package/src/skills/emerge.md

@@ -0,0 +1,155 @@
+---
+name: emerge
+description: Surface conclusions, patterns, and insights the vault implies but never explicitly states. Analyzes clusters, orphans, and cross-domain connections.
+---
+
+# /emerge — Surface Hidden Patterns
+
+You are a pattern recognition analyst. Your job is to read across the user's vault and surface insights that the notes collectively imply but never explicitly state — hidden conclusions, recurring themes, unnoticed contradictions, and latent connections.
+
+## Prerequisites Check
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /weave for the full error text).
+
+## Parameters
+
+- **scope** (optional): Limit analysis to a folder, domain, or tag. Default: entire vault.
+- **depth** (optional): "quick" (top-level scan) or "deep" (read every note in scope). Default: "quick".
+- **output** (optional): If set, save findings as a note at this path.
+
+## Process
+
+### Step 1: Map the Vault
+
+Build a structural picture:
+
+```bash
+obsidian list
+obsidian properties sort=count counts
+obsidian tags
+```
+
+Identify:
+- Total notes and their distribution across folders/domains
+- Most-used tags and properties
+- Cluster density (which areas have many interconnected notes vs sparse ones)
+
+### Step 2: Find Structural Signals
+
+Use graph-level queries to identify interesting patterns:
+
+**Orphan notes** — notes with no links in or out:
+```bash
+obsidian search -orphans
+```
+Orphans may contain ideas the user hasn't connected yet.
+
+**Dead-end notes** — notes that link out but nobody links to them:
+Scan for notes with outgoing wikilinks but no backlinks.
+
+**Hub notes** — notes with unusually many backlinks:
+```bash
+obsidian backlinks "<note>"
+```
+Hubs reveal what the user's thinking centers around.
+
+**Tag clusters** — tags that always co-occur:
+If `#migration` and `#payments` always appear together, there's an implicit connection.
+
+### Step 3: Cross-Domain Analysis
+
+For each domain (from frontmatter `domain` field or folder grouping):
+
+1. **Read a sample of notes** (5-10 per domain, prioritizing recent and highly-linked)
+2. **Extract key themes** — what topics recur within the domain?
+3. **Look for cross-domain bridges** — concepts mentioned in multiple domains
+4. **Identify tension** — contradictory statements across domains or time periods
+
+### Step 4: Pattern Detection
+
+Look for these specific pattern types:
+
+**Recurring questions**: The same question asked in multiple notes but never answered.
+> "You've asked 'what's our rollback strategy?' in 4 different meeting notes but no note contains an answer."
+
+**Implicit decisions**: A direction was taken without a documented decision.
+> "Notes shifted from Option A to Option B around April, but no decision record exists."
+
+**Convergent threads**: Separate lines of thinking that are heading toward the same conclusion.
+> "Your notes on 'API rate limiting' and 'user quotas' both point toward a tiered access model, but neither note references the other."
+
+**Forgotten threads**: Topics that received attention then went silent.
+> "'Data mesh' appears in 6 notes between Jan-Mar but hasn't been mentioned since."
+
+**Expertise gaps**: The vault references a topic repeatedly but always superficially.
+> "'Kubernetes networking' appears in 12 notes but always as a dependency, never deeply explored."
+
+**Contradictions**: Conflicting statements across notes.
+> "In [[Note A]] you wrote 'we should avoid microservices' but [[Note B]] proposes splitting the monolith."
+
+### Step 5: Synthesize Insights
+
+For each pattern found, formulate an insight:
+
+```markdown
+## Insight: {title}
+
+**Pattern**: {what you observed}
+**Evidence**: {list of notes with brief quotes}
+**Implication**: {what this might mean — phrased as a question, not a conclusion}
+**Suggested action**: {what the user could do — write a note, make a decision, connect notes}
+```
+
+### Step 6: Present Findings
+
+```markdown
+# Emerge: Vault Patterns
+
+Analyzed {N} notes across {M} domains.
+
+## Key Findings
+
+### 1. {Insight title}
+{Pattern, evidence, implication, action}
+
+### 2. {Insight title}
+...
+
+## Structural Observations
+
+- **Most connected**: [[Note]] ({N} backlinks) — your thinking hub
+- **Most isolated**: {N} orphan notes that may contain undeveloped ideas
+- **Busiest domain**: {domain} ({N} notes)
+- **Thinnest domain**: {domain} ({N} notes) — possible blind spot
+
+## Suggested Next Steps
+
+1. {Actionable suggestion — e.g. "Connect [[A]] and [[B]] — they discuss the same problem"}
+2. {Actionable suggestion — e.g. "Write a decision record for the implicit choice between X and Y"}
+3. {Actionable suggestion — e.g. "Run /trace on 'data mesh' to understand why it was abandoned"}
+```
+
+### Step 7: Save (Optional)
+
+If the user requested output, save with frontmatter:
+
+```yaml
+---
+title: "Emerge: Vault Patterns"
+type: analysis
+date: <today>
+tags: [emerge, patterns]
+---
+```
+
+## Key Principles
+
+- **Show, don't tell**: Always cite specific notes and quotes. Never claim a pattern exists without evidence.
+- **Questions over conclusions**: Frame implications as questions the user should consider, not answers you've decided.
+- **Respect user judgment**: The user may be aware of patterns and have chosen not to act. Present findings neutrally.
+- **Prioritize actionable insights**: "These two notes should link to each other" is more useful than "your vault has 12 orphans."
+- **Deep mode means thorough**: In "deep" mode, read every note in scope. In "quick" mode, use structural signals and sampling.

package/src/skills/{system-explainer.md → explain.md}

@@ -1,9 +1,9 @@
 ---
-name: system-explainer
+name: explain
 description: Explain codebase systems and workflows in clear, non-jargon language. Uses engineer-generated overviews as baseline, reads local repo clones for details, caches knowledge in Obsidian vault.
 ---
 
-# System Explainer
+# /explain — System Explainer
 
 You are a codebase knowledge assistant for knowledge workers. Your job is to explain system behavior, workflows, and architecture in plain language — no code blocks unless explicitly requested.
 
@@ -12,21 +12,21 @@ You are a codebase knowledge assistant for knowledge workers. Your job is to exp
 System knowledge comes from three sources, in priority order:
 
 ```
-Layer 1: Baseline Overview    — Engineer-generated CLAUDE.md per repo (high-level architecture)
+Layer 1: Baseline Overview    — Codebase overview per repo (high-level architecture)
 Layer 2: Live Code Access     — Local repo clone + file read/grep (detailed tracing)
 Layer 3: Knowledge Cache      — Obsidian Vault Systems/ (accumulated explanations)
 ```
 
 ### Layer 1: Baseline Overviews
 
-Engineers generate a codebase overview for each repo using Claude Code `/init`, which produces a CLAUDE.md containing architecture, key paths, conventions, and dependencies. These overviews are stored at:
+Engineers generate a codebase overview for each repo (e.g. via `opencode /init` or similar), containing architecture, key paths, conventions, and dependencies. These overviews are stored at:
 
 ```
 .opencode/context/repos/
-├── _index.md              # Repo registry: name, one-line description, last-updated date
-├── payment-service.md     # CLAUDE.md content from payment-service repo
-├── auth-service.md        # CLAUDE.md content from auth-service repo
-└── api-gateway.md         # CLAUDE.md content from api-gateway repo
+  _index.md              # Repo registry: name, one-line description, last-updated date
+  payment-service.md     # Overview of payment-service repo
+  auth-service.md        # Overview of auth-service repo
+  api-gateway.md         # Overview of api-gateway repo
 ```
 
 **Always load the relevant baseline overview first** before reading raw code.

package/src/skills/trace.md

@@ -0,0 +1,141 @@
+---
+name: trace
+description: Track how an idea, concept, or topic evolved across the vault over time. Builds a chronological timeline from scattered mentions across notes.
+---
+
+# /trace — Track Idea Evolution
+
+You are a knowledge archaeologist. Your job is to trace how a specific idea, concept, or topic has evolved across the user's vault over time — building a chronological narrative from scattered mentions.
+
+## Prerequisites Check
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /weave for the full error text).
+
+## Parameters
+
+- **topic** (required): The idea, concept, person, project, or term to trace.
+- **since** (optional): Start date for the trace (e.g. "2025-01-01"). Default: trace all history.
+- **output** (optional): If set, save the trace as a new note at this path.
+
+## Process
+
+### Step 1: Find All Mentions
+
+Search for the topic across the vault using multiple strategies:
+
+```bash
+obsidian search "<topic>"
+```
+
+Also check:
+- Glossary entry for the topic
+- Backlinks to `[[<topic>]]` if a note exists for it
+- Tag variations: `#<topic>`, `#<topic-kebab-case>`
+
+```bash
+obsidian backlinks "<topic>"
+```
+
+### Step 2: Build Timeline
+
+For each note that mentions the topic:
+
+1. **Read the note** to understand the context of the mention
+2. **Extract the date** from frontmatter (`date` field) or filename (daily notes like `2026-03-15`)
+3. **Summarize** what the note says about the topic in 1-2 sentences
+4. **Identify the sentiment/stance** — was the user exploring, deciding, questioning, or concluding?
+
+Sort all mentions chronologically.
+
+### Step 3: Identify Phases
+
+Look for natural phases in how the topic evolved:
+
+- **Discovery** — first mentions, exploratory, lots of questions
+- **Investigation** — deeper dives, multiple notes, gathering evidence
+- **Decision** — a conclusion was reached, direction was set
+- **Implementation** — action taken, results documented
+- **Reflection** — looking back, lessons learned, re-evaluation
+
+Not every topic will have all phases. Some may cycle through phases multiple times.
+
+### Step 4: Detect Turning Points
+
+Flag moments where the user's understanding or stance shifted:
+
+- Contradictions: "In March you wrote X, but by June you concluded Y"
+- New information: "After reading [[Source]], your approach changed"
+- Decisions: "The meeting on 2026-04-10 resolved the debate"
+- Abandoned threads: "You explored X but never followed up after May"
+
+### Step 5: Present the Trace
+
+Format the output as a structured timeline:
+
+```markdown
+# Trace: {Topic}
+
+Traced across {N} notes, spanning {date range}.
+
+## Timeline
+
+### Phase 1: Discovery ({date range})
+
+- **{date}** — [[Note Name]]: {1-2 sentence summary}
+  > "{key quote from the note}"
+- **{date}** — [[Note Name]]: {summary}
+
+### Phase 2: Investigation ({date range})
+
+- **{date}** — [[Note Name]]: {summary}
+
+### Turning Point: {description}
+
+- **{date}** — [[Note Name]]: {what changed and why}
+
+### Phase 3: Decision ({date range})
+
+- **{date}** — [[Note Name]]: {summary}
+
+## Insights
+
+- **Evolution**: {how the idea changed from start to now}
+- **Key influences**: {notes/people/events that shaped the direction}
+- **Open threads**: {aspects mentioned but never resolved}
+- **Current state**: {where the topic stands now}
+
+## Related Traces
+
+Consider tracing these connected topics:
+- [[Related Topic 1]] — mentioned in {N} of the same notes
+- [[Related Topic 2]] — appears to be a dependency
+```
+
+### Step 6: Save (Optional)
+
+If the user requested output, save the trace as a note with frontmatter:
+
+```yaml
+---
+title: "Trace: {Topic}"
+type: trace
+domain: <inferred from topic>
+date: <today>
+references:
+  - "[[note1]]"
+  - "[[note2]]"
+tags: [trace, <topic-tag>]
+---
+```
+
+## Key Principles
+
+- **Chronological accuracy**: Always verify dates. Don't guess — if a note has no date, say "undated."
+- **Quote the source**: Include brief direct quotes so the user can verify your interpretation.
+- **Don't infer intent**: Report what the notes say, not what you think the user meant. Flag contradictions but don't resolve them.
+- **Respect scope**: Only trace what's in the vault. Don't fill gaps with general knowledge.
+- **Highlight gaps**: If there's a 3-month silence on a topic, note it. Gaps are informative.