@jayjiang/byoao 1.1.2 → 2.0.1

package/src/skills/connect/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: connect
+description: >
+  Bridges two topics using the link graph, shared people, tags, domains, and conceptual
+  overlap. Use when the user asks "what's the relationship between X and Y", "connect A
+  to B", "how are these related", "find connections between", "what do X and Y have in
+  common", or wants to understand how two topics, people, or concepts relate across notes.
+---
+
+# /connect — Bridge Two Topics
+
+You are a connector. Your job is to find and explain the relationship between two topics using the vault's knowledge graph — shared entities, overlapping concepts, common sources, and structural connections.
+
+## Prerequisites Check
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
+
+## Parameters
+
+- **from** (required): First topic or page name.
+- **to** (required): Second topic or page name.
+- **depth** (optional): `direct` (only direct connections) or `expanded` (include indirect paths via intermediate pages). Default: `expanded`.
+
+## Process
+
+### Step 1: Locate Both Topics
+
+```bash
+obsidian search "<from>"
+obsidian search "<to>"
+```
+
+If `INDEX.base` exists, read it to spot compiled pages for either topic.
+
+Read any existing agent pages in `entities/`, `concepts/`, `comparisons/`, and `queries/`:
+
+```bash
+obsidian read file="entities/<from>.md"  # if exists
+obsidian read file="concepts/<from>.md"  # if exists
+obsidian read file="comparisons/<from>.md"  # if exists
+obsidian read file="queries/<from>.md"  # if exists
+obsidian read file="entities/<to>.md"    # if exists
+obsidian read file="concepts/<to>.md"    # if exists
+obsidian read file="comparisons/<to>.md"  # if exists
+obsidian read file="queries/<to>.md"    # if exists
+```
+
+### Step 2: Map Each Topic's Connections
+
+For each topic:
+
+```bash
+obsidian backlinks "<from>"
+obsidian backlinks "<to>"
+```
+
+Read the pages that link to each topic. Build a connection map:
+- Direct wikilinks (both topics link to the same page, or the same page links to both)
+- Shared tags (use `SCHEMA.md` for taxonomy context when classifying)
+- Shared domain
+- Shared source notes (both topics were extracted from the same user note)
+- Shared people/entities mentioned in both topics' pages
+
+### Step 3: Find Direct Connections
+
+Check if there's already a direct relationship:
+- Does the `from` page wikilink to `to` (or vice versa)?
+- Is there a `comparisons/` page that covers both?
+- Do they share a `sources` entry in frontmatter?
+
+### Step 4: Find Indirect Paths (Expanded Mode)
+
+If no direct connection exists, search for intermediate pages:
+
+1. Find all pages that link to `from`
+2. For each of those, check if they link to `to`
+3. If yes: `from` → `intermediate` → `to` is a connection path
+4. Report the shortest path(s) and explain the relationship
+
+Also check:
+- Shared tag clusters (both topics use tags that co-occur frequently)
+- Shared domain context (both are about the same domain but different aspects)
+- Temporal overlap (both topics emerged around the same time)
+
+### Step 5: Present the Connection
+
+```markdown
+# Connection: [[{from}]] ↔ [[{to}]]
+
+## Direct Relationship
+{Yes/No} — {explain the direct connection if it exists}
+
+## Connection Paths
+{If indirect paths exist, show them:}
+
+1. [[{from}]] → [[{intermediate}]] → [[{to}]]
+   - Path explanation: {how they connect through this intermediate}
+
+## Shared Context
+- **Shared tags**: {tag1}, {tag2}
+- **Shared domain**: {domain}
+- **Shared sources**: [[source-note-1]], [[source-note-2]]
+- **Shared entities**: [[entity-1]], [[entity-2]]
+
+## Relationship Type
+{Classify the relationship:}
+- **Dependency**: {from} depends on {to} (or vice versa)
+- **Sibling**: Both are aspects of a larger concept
+- **Contrast**: They represent opposing approaches
+- **Evolution**: {to} evolved from {from} over time
+- **Parallel**: Independent topics that happen to share context
+
+## Why This Connection Matters
+{2-3 sentences on what this relationship reveals and why it's worth knowing}
+```
+
+## Key Principles
+
+- **Graph over guesswork.** Base connections on actual wikilinks, shared tags, and shared sources — not inferred relationships.
+- **Multiple paths.** There may be several ways two topics connect — show the most meaningful ones, not just the shortest.
+- **Explain, don't just list.** The value is in the *explanation* of why the connection matters, not just the path itself.
+- **Obsidian is first workbench.** All note operations go through Obsidian CLI.

package/src/skills/cook/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: cook
+description: >
+  The core knowledge compilation skill. Reads raw notes and external sources, then
+  distills them into structured, cross-referenced knowledge pages in entities/, concepts/,
+  comparisons/, and queries/. Use this skill whenever the user mentions compiling notes,
+  digesting material, updating the knowledge base, running a cook cycle, or says anything
+  like "process my notes", "compile this", "add this to the wiki", "what's new in my notes",
+  or "update knowledge pages". Also activate when the user pastes external content and wants
+  it integrated into the knowledge base.
+---
+
+# /cook — Knowledge Compilation
+
+You are a knowledge compiler. Your job is to read raw material (user notes, external sources)
+and distill it into structured, cross-referenced knowledge pages.
+
+## Prerequisites Check
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
+
+## Parameters
+
+- **target** (optional): What to cook. Default: incremental (new/modified notes since last cook).
+  - `--all` or `full`: Read all user notes in the vault
+  - `"Topic Name"`: Read notes matching this keyword
+  - `path/to/note.md`: Read a specific note
+  - `<URL>`: Fetch external article and digest it
+
+## Input Scope
+
+### Incremental Mode (default)
+
+When user runs `/cook` with no arguments:
+1. Read `log.md` for last cook timestamp
+2. Scan for `.md` files outside agent directories with `modified` date after that timestamp
+3. Include any unprocessed files
+
+### Full Mode
+
+When user runs `/cook --all`:
+- Read all user notes in the vault (exclude `entities/`, `concepts/`, `comparisons/`, `queries/`)
+- Re-evaluate all entities and concepts
+
+### Targeted Mode
+
+When user runs `/cook "Feature A"` or `/cook path/to/note.md`:
+- Read only the specified notes or notes matching the keyword
+
+### External URL
+
+When user provides a URL:
+1. Fetch content using WebFetch or Obsidian Web Clipper
+2. Save as a user note in the vault (ask the user where to save, or use a sensible default like the vault root with a descriptive filename: `<slug>.md`)
+3. Add frontmatter: `title`, `source_url`, `fetched` date
+4. Process normally — the saved note becomes raw material for /cook
+
+**Note:** No dedicated `raw/` directory. External material is saved as regular user notes, consistent with the brownfield principle.
+
+## Processing Pipeline
+
+### Step 1: Read & Parse
+- Read all target notes
+- Extract frontmatter, content, wikilinks
+- Identify entities (named things), concepts (abstract ideas), decisions, contradictions
+
+### Step 2: Match Against Existing Pages
+- Check `INDEX.base` or scan `entities/`, `concepts/` for existing pages
+- Determine: create new vs. update existing
+
+### Step 3: Create/Update Pages
+- **New entities:** Create in `entities/<name>.md`
+- **New concepts:** Create in `concepts/<name>.md`
+- **Updates:** Add new information, bump `updated` date
+- **Contradictions:** Follow Update Policy
+
+**Create page thresholds:**
+- Appears in 2+ notes, OR is central subject of one note
+- Do NOT create for: passing mentions, minor details, out-of-domain topics
+
+### Step 4: Cross-Reference
+- Ensure every new/updated page has at least 2 outbound wikilinks
+- Check existing pages link back where relevant
+
+### Step 5: Update Navigation
+- `INDEX.base` auto-updates via Obsidian Base query
+- Append entry to `log.md`
+
+### Step 6: Report
+Present structured summary (see Output Report Format below).
+
+## Contradiction Handling
+
+### Detection
+- Compare claims across notes about the same entity/concept
+- Check dates — newer claims may supersede older
+- Look for explicit contradictions (e.g., "we changed from X to Y")
+
+### Resolution Workflow
+1. Note both positions with dates and source references
+2. Mark in frontmatter: `contradictions: [page-name]`
+3. Report to user with specific sources
+4. Offer to create a comparison page
+5. User decides
+
+### Update Policy
+- Newer sources generally supersede older
+- If both positions still valid (e.g., A/B testing), note both
+- Never silently overwrite — always flag for review
+
+## Output Report Format
+
+```
+Cook complete. Here's what changed:
+
+New knowledge:
+• [[feature-a]] — Response time monitoring feature
+• [[response-time-metrics]] — Why median replaced avg
+
+Updated:
+• [[zhang-san]] — Added Feature A assignment
+
+Contradiction found:
+⚠ PRD says avg(response_time) > baseline, but experiment notes say median
+  Sources: Projects/Feature-A-PRD.md vs Daily/2026-04-05.md
+  Want me to create a comparison page?
+
+Log: 1 entry added to log.md
+```
+
+**Design principles:**
+- Natural language, no technical jargon
+- Structured for quick scanning
+- Actionable (asks for decisions on contradictions)
+- Wikilinks for easy navigation
+
+## Auto-Trigger Behavior
+
+The Agent should automatically run `/cook` after:
+- Writing a note (brief report: "Cooked 1 note. Updated [[x]], created [[y]].")
+- User drops new files into the vault
+
+**When NOT to auto-trigger:**
+- Rapid-fire note creation (batch and cook once at the end)
+- `/cook` was already run in the last 5 minutes
+
+## Agent Page Identification
+
+Agent pages are identified by directory:
+| Location | Ownership |
+|----------|-----------|
+| `entities/**/*.md` | Agent |
+| `concepts/**/*.md` | Agent |
+| `comparisons/**/*.md` | Agent |
+| `queries/**/*.md` | Agent |
+| All other `.md` | User (read-only during /cook) |
+
+No `owner` frontmatter field needed.
+
+## Key Principles
+
+- **Evidence-based**: Every knowledge page cites its sources
+- **Never modify user notes**: User notes are read-only during /cook
+- **Thresholds matter**: 2+ mentions or central subject to create a page
+- **Split at 200 lines**: Break large pages into sub-topics
+- **Flag contradictions**: Never silently overwrite

package/src/skills/diagnose/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: diagnose
+description: >
+  Vault health check at the structural level. Checks frontmatter coverage, orphan notes,
+  broken links, AGENTS.md and SCHEMA.md drift, v2 agent directories, and overall vault
+  configuration. Broader than /health (which focuses on agent pages) — /diagnose checks
+  the entire vault including user notes. Use when the user says "check my vault", "is
+  everything set up correctly", "vault health", "diagnose issues", or wants a full
+  structural audit beyond just agent pages.
+---
+
+# /diagnose — Vault Diagnosis
+
+You are a vault doctor. Your job is to check the overall health of the vault — structure, frontmatter coverage, configuration, and consistency across both user notes and agent pages.
+
+## Prerequisites Check
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
+
+## Parameters
+
+- **focus** (optional): Specific area to check — `frontmatter`, `links`, `structure`, `config`, or `all`. Default: `all`.
+
+## Process
+
+### Step 1: Frontmatter Coverage
+
+```bash
+obsidian properties sort=count counts
+```
+
+Report:
+- Total notes with frontmatter vs. without
+- Most common missing fields
+- Notes with invalid frontmatter (bad dates, unknown types, etc.)
+- Tag usage: how many unique tags, how many notes per tag
+
+### Step 2: Broken Wikilinks
+
+Scan for wikilinks that point to non-existent files:
+
+```bash
+obsidian search "\[\[.*\]\]"
+```
+
+For each wikilink found, check if the target file exists. Report broken links with:
+- Source file where the broken link appears
+- Target link that doesn't resolve
+- Suggested fix (create the missing file or remove the link)
+
+### Step 3: Orphan Detection
+
+Find notes with no inbound wikilinks:
+
+```bash
+obsidian backlinks "note-name"
+```
+
+For both user notes and agent pages, identify orphans. Note that newly created notes are expected to be orphans temporarily.
+
+### Step 4: AGENTS.md, SCHEMA.md, and v2 layout
+
+Check if `AGENTS.md` accurately reflects the current vault state:
+- Does it reference directories that no longer exist?
+- Does it miss directories that were added?
+- Are the skill references still valid?
+- Is the navigation advice still accurate?
+
+Check `SCHEMA.md`:
+- Tag taxonomy and domain sections match how tags are actually used
+- Agent directory table matches `entities/`, `concepts/`, `comparisons/`, `queries/`
+- Frontmatter expectations align with v2 `type: entity | concept | comparison | query`
+
+Verify the v2 agent directories exist and are usable: `entities/`, `concepts/`, `comparisons/`, `queries/` (note if any are missing or empty when the vault should have compiled knowledge).
+
+### Step 5: Configuration Check
+
+Verify vault configuration:
+- `.obsidian/` directory exists and is valid
+- `.opencode/` directory has current skill definitions
+- `SCHEMA.md` exists and has a defined tag taxonomy
+- `log.md` exists and has recent entries
+- `INDEX.base` exists for compiled knowledge discovery
+
+### Step 6: Present Diagnosis
+
+```markdown
+# Vault Diagnosis
+
+Scanned {N} notes, {M} agent pages, {K} user notes.
+
+---
+
+## Frontmatter Coverage
+- Notes with frontmatter: X/Y (Z%)
+- Most common missing: {list fields}
+- Unique tags: {N} (top 5: {list})
+
+## Broken Wikilinks
+- {N} broken links found:
+  - [[target]] in [[source]] → file not found
+
+## Orphan Notes
+- {N} notes with no inbound links:
+  - [[note-name]] — consider linking from [[suggested-source]]
+
+## AGENTS.md / SCHEMA.md / layout
+- AGENTS.md: {Up to date / Needs update} — {details if outdated}
+- SCHEMA.md: {Up to date / Needs update / Missing} — {taxonomy vs usage}
+- Agent dirs (`entities/`, `concepts/`, `comparisons/`, `queries/`): {OK / Missing / Issues}
+
+## Configuration
+- .obsidian/: {OK / Missing / Issues}
+- .opencode/: {OK / Missing / Issues}
+- log.md: {OK / Missing / {N} entries, last: {date}}
+- INDEX.base: {OK / Missing / Needs update}
+
+## Overall Health
+**Score**: {Good / Fair / Needs attention}
+
+{2-3 sentence summary of the vault's overall health and the top 2-3 issues to address}
+```
+
+## Key Principles
+
+- **Comprehensive but prioritized.** Check everything, but surface the most important issues first.
+- **Actionable findings.** Every issue should come with a suggested fix.
+- **Non-destructive by default.** Report issues, don't fix them automatically.
+- **Whole vault, not just agent pages.** Unlike /health which focuses on agent-maintained directories, /diagnose checks the entire vault.
+- **Obsidian is first workbench.** All note operations go through Obsidian CLI.

package/src/skills/drift/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: drift
+description: >
+  Intention-vs-action gap analysis over time. Compares what the user said they would do
+  with what actually happened. Use when the user asks "am I following through on X",
+  "how has Y changed since the plan", "did I stick to the decision", "compare plan vs
+  reality", "what drifted", or wants to check if actions match stated intentions.
+---
+
+# /drift — Intention vs. Action
+
+You are an accountability mirror. Your job is to compare what the user said they would do with what actually happened — finding gaps between intentions and actions, plan vs. reality, and the slow drift of priorities over time.
+
+## Prerequisites Check
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
+
+## Parameters
+
+- **topic** (optional): Specific plan, goal, or intention to track. Default: scan all recent intentions.
+- **window** (optional): Time window to analyze (e.g., "30d", "3m", "all"). Default: "30d".
+
+## Process
+
+### Step 1: Find Stated Intentions
+
+Search for places where the user expressed intentions:
+
+```bash
+obsidian search "should" OR "need to" OR "will" OR "plan to" OR "going to" OR "decided to"
+obsidian search "goal" OR "objective" OR "target" OR "priority"
+```
+
+Also check:
+- Daily notes for intention statements
+- Agent pages in `entities/` and `concepts/` for documented decisions, owners, or plans
+- Pages with `status: draft` that represent in-progress intentions
+- `log.md` as the chronological spine: cook cycles, reported changes, and stated purposes tied to dates
+
+### Step 2: Find Actual Actions
+
+Search for evidence of what actually happened:
+
+```bash
+obsidian search "completed" OR "done" OR "shipped" OR "implemented" OR "finished"
+obsidian search "changed" OR "switched" OR "pivoted" OR "abandoned"
+```
+
+Check:
+- Recent daily notes for actual activities
+- Agent pages in `entities/` and `concepts/` for current state and decision descriptions
+- `log.md` entries since the intention was stated
+- Updated frontmatter dates and `status` changes
+- New pages created vs. pages left in draft
+
+### Step 3: Compare Intentions to Actions
+
+For each intention found:
+
+1. **Followed through** — Evidence shows the action was taken as planned
+2. **Partially followed** — Some action was taken but not fully
+3. **Deferred** — Still planned but not yet acted on
+4. **Diverged** — Action was taken but in a different direction
+5. **Abandoned** — No evidence of any action
+
+### Step 4: Identify Drift Patterns
+
+Look for systematic patterns:
+
+- **Priority drift**: The user said X was top priority, but most time went to Y
+- **Scope drift**: A small intention grew into a much larger effort (or shrank)
+- **Direction drift**: The approach changed from the original plan
+- **Timeline drift**: Things took significantly longer (or shorter) than expected
+- **Attention drift**: An intense focus faded and wasn't replaced by anything
+
+### Step 5: Present the Drift Report
+
+```markdown
+# Drift Report: {topic or "Recent Intentions"}
+
+Analyzed {N} notes from {start date} to {end date}.
+
+---
+
+## Followed Through ✅
+- **{intention}** — {what was done, evidence from [[note]]}
+
+## Partially Followed ⚡
+- **{intention}** — {what was done vs. what was planned, gap evidence from [[note]]}
+
+## Deferred ⏳
+- **{intention}** — {stated on [[date]] in [[note]], no action found since}
+
+## Diverged ↩
+- **{intention}** — {original plan from [[note A]], actual outcome from [[note B]]}
+
+## Abandoned ❌
+- **{intention}** — {stated on [[date]], zero evidence of action}
+
+---
+
+## Drift Patterns
+
+### Priority Drift
+{Evidence that stated priorities don't match actual time allocation}
+
+### Direction Drift
+{Evidence that the approach changed from the original plan}
+
+## Overall Assessment
+{2-3 sentences: Is the user generally following through on intentions? Where is the biggest gap? Is the drift a problem or a healthy adaptation?}
+```
+
+## Key Principles
+
+- **Factual, not judgmental.** Report the gap between intention and action without moralizing. The user decides if it matters.
+- **Evidence-based.** Every drift claim must cite specific notes showing both the intention and the actual outcome.
+- **Drift isn't always bad.** Sometimes changing direction is the right call. Flag the drift; let the user judge.
+- **Obsidian is first workbench.** All note operations go through Obsidian CLI.

package/src/skills/health/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: health
+description: >
+  Scan agent-maintained directories for health issues: orphan pages, broken wikilinks,
+  stale content, frontmatter violations, tag taxonomy drift, oversized pages. Use this
+  skill whenever the user wants to audit knowledge base quality, check for broken links,
+  find stale or orphan pages, or says anything like "check my wiki", "are there any issues",
+  "audit the knowledge base", "find broken links", or "what needs fixing".
+---
+
+# /health — Knowledge Health Check
+
+Scan the four agent-maintained directories (`entities/`, `concepts/`, `comparisons/`, `queries/`)
+for structural issues.
+
+## Prerequisites Check
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
+
+## Scan Categories
+
+### 1. Orphan Pages
+Pages with no inbound wikilinks from any other note (user notes or agent pages).
+- Severity: **warning** for new pages (< 7 days old), **info** for older
+
+### 2. Broken Wikilinks
+Wikilinks in agent pages that point to non-existent targets.
+- Severity: **warning**
+
+### 3. Stale Content
+Pages where `updated` date is > 90 days behind the most recent source note's date.
+- Severity: **info**
+
+### 4. Frontmatter Violations
+Pages missing required fields (`title`, `date`, `created`, `updated`, `type`, `tags`, `sources`).
+- Severity: **warning** for missing required fields
+
+### 5. Tag Taxonomy Drift
+Tags used in agent pages that are not defined in `SCHEMA.md`.
+- Severity: **info**
+
+### 6. Oversized Pages
+Pages exceeding ~200 lines — candidates for splitting.
+- Severity: **info**
+
+## Report Format
+
+Group findings by severity:
+
+```
+Health check complete. Found 3 issues:
+
+Warnings (2):
+• [[broken-link-page]] — broken wikilink to [[nonexistent]]
+• [[orphan-page]] — no inbound links (created 30 days ago)
+
+Info (1):
+• [[large-concept]] — 340 lines, consider splitting into sub-topics
+```
+
+Offer concrete fixes for each issue. Ask before making changes.