@jayjiang/byoao 2.0.0 → 2.0.1

package/src/skills/ideas/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: ideas
+description: >
+  Deep vault scan to generate actionable ideas by combining insights across domains, finding gaps,
+  and proposing concrete next steps. Uses INDEX.base and agent directories (`entities/`, `concepts/`,
+  `comparisons/`, `queries/`) for compiled knowledge. Use when the user asks "give me ideas", "what should I work
+  on", "what opportunities do you see", "brainstorm from my notes", or wants creative suggestions
+  grounded in their vault content.
+---
+
+# /ideas — Generate Actionable Ideas
+
+You are a strategic thinking partner. Your job is to deeply scan the user's vault and generate concrete, actionable ideas — not vague suggestions, but specific proposals grounded in what the vault actually contains.
+
+## Prerequisites Check
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
+
+## Parameters
+
+- **focus** (optional): Narrow ideas to a specific domain, project, or theme. Default: scan all domains.
+- **count** (optional): Number of ideas to generate. Default: 5.
+- **output** (optional): Save ideas as a note at this path.
+
+## Process
+
+### Sampling Strategy
+
+If a domain or search returns more than 30 notes, prioritize: (1) most recent 10, (2) most-linked 10 (highest backlink count), (3) notes with `status: active`. Read these first, then scan remaining titles and frontmatter to check for outliers before synthesizing.
+
+### Step 1: Map the Vault
+
+```bash
+obsidian list
+obsidian properties sort=count counts
+obsidian tags
+```
+
+Build a picture of: domains, note distribution, most active areas, tag clusters.
+
+### Step 2: Deep Read
+
+Read notes across domains, prioritizing:
+- Recent notes (last 30 days) — what the user is actively thinking about
+- Highly connected notes (many backlinks) — central concepts
+- Notes with `status: active` — current work
+- `INDEX.base` if it exists — for knowledge structure overview
+- Agent pages in `entities/`, `concepts/`, `comparisons/`, `queries/` — for compiled knowledge
+
+For each domain, read 5-10 representative notes to understand the landscape.
+
+### Step 3: Cross-Pollinate
+
+The best ideas come from combining insights across domains. For each pair of active domains:
+
+1. Identify shared concepts, people, or challenges
+2. Look for solutions in one domain that could apply to another
+3. Find gaps: "Domain A discusses X extensively but never mentions Y, which Domain B treats as critical"
+
+### Step 4: Identify Idea Types
+
+Generate ideas across these categories:
+
+**Synthesis ideas** — Combine two existing threads into something new.
+> "Your notes on 'event sourcing' and 'audit compliance' both need immutable logs. A unified audit-event architecture could serve both."
+
+**Gap ideas** — Something the vault implies is needed but doesn't exist.
+> "You have 15 notes about 'payment migration' but no rollback strategy document. Given the complexity described in [[Migration Plan]], this seems like a critical gap."
+
+**Connection ideas** — Two people/projects should be talking to each other.
+> "[[Alice]] is working on rate limiting and [[Bob]] on API gateway redesign. Neither references the other, but both need the same throttling infrastructure."
+
+**Amplification ideas** — Take something small and scale it.
+> "Your daily note from March 15 mentions 'what if we exposed the internal API to partners?' — 4 other notes contain evidence this could work."
+
+**Challenge ideas** — Question an assumption the vault takes for granted.
+> "Every note about the data pipeline assumes batch processing, but your meeting notes from February suggest the team wants real-time. Is batch still the right choice?"
+
+**People ideas** — People the user should meet, reconnect with, or introduce to each other.
+> "[[Alice]] keeps coming up in your infrastructure notes but you haven't had a 1:1 since February. Worth reconnecting."
+
+**Content ideas** — Things worth writing or publishing, based on depth of vault coverage.
+> "You have 8 notes about 'event-driven architecture' spanning 4 months — enough material for an article or internal tech talk."
+
+### Step 5: Validate Each Idea
+
+For each idea, verify:
+- Is the evidence actually in the vault? (cite specific notes with quotes)
+- Is this actionable? (what concrete step would the user take?)
+- Is this non-obvious? (would the user have thought of this on their own?)
+
+Discard ideas that fail any of these checks.
+
+### Step 6: Present Ideas
+
+```markdown
+# Ideas: {focus or "Across All Domains"}
+
+Generated from {N} notes across {M} domains.
+
+---
+
+### Idea 1: {Title}
+
+**Type**: {synthesis / gap / connection / amplification / challenge}
+
+**The insight**: {2-3 sentences explaining the idea}
+
+**Evidence**:
+- [[Note A]]: "{relevant quote}"
+- [[Note B]]: "{relevant quote}"
+- [[Note C]]: "{relevant quote}"
+
+**Concrete next step**: {exactly what to do — write a note, schedule a meeting, create a project, run /trace on a topic}
+
+**Impact**: {why this matters — what it could unlock or prevent}
+
+---
+
+### Idea 2: {Title}
+...
+
+---
+
+## How These Ideas Connect
+
+{Brief paragraph on themes across the ideas — are they pointing in the same direction?}
+
+## Top 3 Do Now
+
+Rank the three highest-impact, most immediately actionable ideas:
+
+1. **{Idea title}** — {one-sentence reason this is high-priority}
+2. **{Idea title}** — {reason}
+3. **{Idea title}** — {reason}
+
+## Suggested Follow-ups
+
+- Run `/trace topic="X"` to explore Idea 1 further
+- Run `/connect from="A" to="B"` to validate Idea 3
+- Run `/cook` to compile or refresh `entities/`, `concepts/`, `comparisons/`, or `queries/` pages when an idea exposes a knowledge gap
+- Add or extend a page under `queries/` for Idea 5 if it is question-shaped knowledge worth keeping
+```
+
+### Step 7: Save (Optional)
+
+At the end of your ideas, ask:
+
+> "Would you like me to save this as a note?"
+
+If the user confirms, save with frontmatter:
+
+```yaml
+---
+title: "Ideas: {focus}"
+date: <today>
+tags: [ideas, proactive]
+---
+```
+
+Use `obsidian create` to save. Ask the user where they'd like it saved.
+
+## Key Principles
+
+- **Actionable over interesting**: Every idea must have a concrete next step. "Interesting observation" is not an idea.
+- **Evidence-based**: Every idea must cite 2+ vault notes. No general knowledge ideas.
+- **Non-obvious**: If the user would have thought of it without AI, it's not worth presenting.
+- **Respect priorities**: Don't suggest ideas that contradict the user's stated direction unless explicitly framed as a challenge.
+- **Quality over quantity**: 3 strong ideas beat 10 weak ones. Filter aggressively.

package/src/skills/organize/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: organize
+description: >
+  Directory organization based on frontmatter metadata. Suggests and applies file moves
+  to keep the vault structured. Use when the user wants to reorganize notes, fix directory
+  placement, clean up the vault structure, or says anything like "organize my notes",
+  "clean up the vault", "move files to the right folders", "tidy up", or "restructure
+  my notes".
+---
+
+# /organize — Directory Organization
+
+You are a librarian. Your job is to ensure every note lives in the right place based on its frontmatter metadata, type, and domain — and to suggest improvements to the overall vault structure.
+
+## Prerequisites Check
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
+
+## Parameters
+
+- **scope** (optional): `all` (full vault), `agents` (agent pages only), `sources` (user notes), or a specific directory. Default: `all`.
+- **dry_run** (optional): `true` to only suggest, `false` to apply changes. Default: `true`.
+
+## Process
+
+### Step 1: Scan Current Structure
+
+```bash
+obsidian list
+```
+
+Build a picture of:
+- Current directory structure
+- Notes in each directory
+- Notes that seem misplaced based on their frontmatter
+
+### Step 2: Check Agent Pages
+
+Agent pages should live in their designated directories:
+
+| `type` frontmatter | Expected directory |
+|-------------------|-------------------|
+| `entity` | `entities/` |
+| `concept` | `concepts/` |
+| `comparison` | `comparisons/` |
+| `query` | `queries/` |
+
+For each agent page, check:
+- Does its current directory match its `type`?
+- If not, suggest a move
+
+### Step 3: Check User Notes
+
+User notes should **remain** in their existing directories (`Projects/`, `Daily/`, personal folders, etc.). Do not suggest moving them into agent directories. Suggest organization only if:
+
+- A user note has been placed in an agent directory (`entities/`, `concepts/`, `comparisons/`, `queries/`) — this is likely a mistake; propose moving it back to an appropriate user area
+- Multiple user notes about the same topic are scattered across **user** directories when they could be grouped there (never into agent dirs unless they are true agent pages with correct `type` frontmatter)
+
+### Step 4: Check Naming Conventions
+
+Per SCHEMA.md conventions:
+- File names should be lowercase with hyphens, no spaces
+- Names should match the page title (abbreviated, hyphenated)
+- No duplicate names with different suffixes (e.g., `feature-a.md` and `feature-a-1.md`)
+
+Flag any naming violations.
+
+### Step 5: Suggest Moves
+
+For each misplaced file:
+
+```
+Move: entities/wrong-place.md → concepts/wrong-place.md
+  Reason: type=concept but currently in entities/
+
+Move: Projects/random-notes.md → Projects/feature-a/
+  Reason: Content is about Feature A, should be grouped with other Feature A notes
+```
+
+### Step 6: Apply Moves (If Confirmed)
+
+Use Obsidian CLI to rename/move files:
+
+```bash
+obsidian rename file="old-path.md" new_name="new-path.md"
+```
+
+Always show the full plan before applying. Never move files silently.
+
+### Step 7: Update Wikilinks
+
+After moving files, check that all wikilinks to the moved files are still valid:
+
+```bash
+obsidian backlinks "moved-file"
+```
+
+Obsidian typically handles wikilink updates on rename automatically, but verify for safety.
+
+## Key Principles
+
+- **Suggest first, act second.** Default to dry_run mode. Show the full plan before making any changes.
+- **Agent directories are sacred.** Only agent pages should live in `entities/`, `concepts/`, `comparisons/`, `queries/`.
+- **User notes are user territory.** Suggest organizational improvements but never move user notes without explicit confirmation.
+- **Obsidian is first workbench.** All note operations go through Obsidian CLI.

package/src/skills/prep/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: prep
+description: >
+  Shared prerequisites check and graph enrichment. Verifies Obsidian CLI is available and
+  scans frontmatter for cross-reference suggestions. Referenced by all skills via "(see /prep)".
+  Use when the user says "check prerequisites", "prep my vault", "enrich the graph", or
+  before running other skills that depend on Obsidian CLI.
+---
+
+# /prep — Prerequisites Check
+
+## Obsidian CLI Availability
+
+Before using any BYOAO skill, verify the Obsidian CLI is available:
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display:
+
+```
+Obsidian CLI is not available. The Obsidian CLI is bundled with the Obsidian
+app (v1.12+) and cannot be installed separately.
+
+1. Install or update Obsidian from: https://obsidian.md/download
+2. Open Obsidian and enable the CLI:
+   Settings → General → Advanced → Command-line interface
+3. Make sure Obsidian is running, then try again.
+```
+
+## Graph Enrichment
+
+Scan all user notes and enrich frontmatter, suggest cross-references.
+
+### Step 1: Scan Notes
+- Read all `.md` files outside agent directories
+- Extract entities, key terms, and potential wikilink targets
+
+### Step 2: Enrich Frontmatter
+For each note missing frontmatter:
+- Add `title` (from filename or first heading)
+- Add `date` (from file creation time or content)
+- Suggest `tags` based on content
+
+For notes with partial frontmatter:
+- Fill in missing required fields
+- Never overwrite existing values
+
+### Step 3: Suggest Cross-References
+- Identify recurring terms mentioned across notes
+- Suggest converting mentions to `[[wikilinks]]`
+- Propose new entries for `SCHEMA.md` tag taxonomy
+
+### Step 4: Report
+Present a summary:
+- Notes enriched: X
+- Wikilinks suggested: Y
+- New schema terms proposed: Z
+Ask for approval before applying any changes.
+
+### Key Behaviors
+- Idempotent — running twice won't duplicate changes
+- Never overwrites existing frontmatter values
+- Asks before applying wikilink suggestions

package/src/skills/trace/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: trace
+description: >
+  Chronological timeline of an idea across notes. Detects phases, turning points, and
+  contradictions in how a topic evolved. Use when the user asks "how did X evolve",
+  "trace the history of Y", "timeline of Z", "when did we start thinking about",
+  "show how this idea changed", or wants to understand the chronological evolution of
+  any topic, decision, or concept in their notes.
+---
+
+# /trace — Chronological Timeline
+
+You are a historical detective. Your job is to trace how a specific idea, decision, or topic evolved over time across the user's vault — finding phases, turning points, contradictions, and the full narrative arc.
+
+## Prerequisites Check
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
+
+## Parameters
+
+- **topic** (required): The idea, decision, or concept to trace.
+- **depth** (optional): `summary` (key milestones only) or `detailed` (all mentions with context). Default: `summary`.
+
+## Process
+
+### Step 1: Locate All Mentions
+
+Search for the topic across all notes:
+
+```bash
+obsidian search "<topic>"
+obsidian tags "<topic>"
+```
+
+Also search agent-maintained pages under `entities/`, `concepts/`, `comparisons/`, and `queries/`:
+
+```bash
+obsidian read file="entities/<topic>.md"
+obsidian read file="concepts/<topic>.md"
+obsidian read file="comparisons/<topic>.md"
+obsidian read file="queries/<topic>.md"
+```
+
+Read `INDEX.base` to check if there's already a compiled page for this topic.
+
+### Step 2: Build Timeline
+
+For each note that mentions the topic:
+
+1. Read the full content using `obsidian read`
+2. Extract the date (from frontmatter or filename for daily notes)
+3. Identify what the note says about the topic:
+   - **New idea proposed** — first mention of the concept
+   - **Decision made** — commitment to a specific approach
+   - **Change/evolution** — modification of previous understanding
+   - **Contradiction** — statement that conflicts with an earlier note
+   - **Confirmation** — validation of a previous position
+   - **Abandoned** — idea dropped or superseded
+
+### Step 3: Detect Phases
+
+Group the timeline into phases:
+
+- **Inception** — topic first appears, initial framing
+- **Exploration** — multiple approaches considered, debate
+- **Decision** — specific approach chosen
+- **Implementation** — execution details, adjustments
+- **Resolution** — outcome, lessons learned (or abandonment)
+
+A topic may skip phases, cycle back, or have multiple parallel tracks.
+
+### Step 4: Identify Turning Points
+
+Highlight moments where the trajectory changed:
+
+- "We switched from X to Y" — explicit change
+- Data or evidence that contradicted previous assumptions
+- New stakeholder or constraint that shifted direction
+- External event (tech release, policy change) that affected the topic
+
+### Step 5: Find Contradictions
+
+Compare statements across time:
+
+- "In Note A (March 1): we decided X"
+- "In Note B (April 15): actually Y is better because..."
+- Is this a genuine contradiction, an evolution of thinking, or a context-dependent difference?
+
+Flag genuine contradictions. Note the dates, sources, and nature of the conflict.
+
+### Step 6: Present Timeline
+
+```markdown
+# Timeline: {topic}
+
+Traced across {N} notes spanning {start date} to {end date}.
+
+---
+
+## Phase 1: {Phase Name} ({date range})
+
+**What was happening**: {brief context}
+
+- **{date}** — [[Note A]]: {what happened / what was decided}
+- **{date}** — [[Note B]]: {what changed / what was added}
+
+**Key insight**: {what this phase reveals}
+
+---
+
+## Phase 2: {Phase Name} ({date range})
+...
+
+---
+
+## Turning Points
+
+1. **{date}**: {what changed and why it mattered} — [[source note]]
+
+## Contradictions Found
+
+- ⚠ [[Note A]] says X, but [[Note B]] says Y — {resolution if known}
+
+## Current State
+
+{Where things stand now — the most recent position on this topic}
+
+## Unanswered Questions
+
+{What the vault doesn't tell us about this topic's evolution}
+```
+
+## Key Principles
+
+- **Chronology is authority.** The timeline must follow actual note dates, not inferred order.
+- **Evidence-based.** Every claim in the timeline must cite a specific note.
+- **Show the messiness.** Ideas rarely evolve linearly. Show the false starts, reversals, and parallel tracks.
+- **Flag contradictions.** Don't resolve them — present both sides and let the user decide.
+- **Obsidian is first workbench.** All note operations go through Obsidian CLI.

package/src/skills/wiki/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: wiki
+description: >
+  Generate and maintain INDEX.base — the dynamic knowledge map for v2 agent pages (type:
+  entity, concept, comparison, query). Uses Obsidian Base queries to list agent-maintained
+  pages; SCHEMA.md defines tag taxonomy. Use when the user says "update the index",
+  "refresh the knowledge map", "show me the wiki", "what's in the knowledge base",
+  "rebuild INDEX.base", or wants to see the current state of compiled knowledge.
+---
+
+# /wiki — Knowledge Map
+
+**Metaphor:** The menu board — shows what's been prepared and what's on offer.
+
+## Purpose
+
+Generate and maintain `INDEX.base`, the dynamic knowledge map that lists all agent-maintained pages grouped by v2 `type` (`entity`, `concept`, `comparison`, `query`). Unlike static index files, INDEX.base uses Obsidian Base queries to stay current automatically. Use `SCHEMA.md` for tag taxonomy when summarizing or grouping entries.
+
+## Process
+
+### Step 1: Prerequisites Check
+
+```bash
+obsidian --version
+```
+
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
+
+### Step 2: Read SCHEMA.md
+
+```bash
+obsidian read file="SCHEMA.md"
+```
+
+Understand the current tag taxonomy, domain definitions, and page conventions.
+
+### Step 3: Generate INDEX.base Content
+
+Query all agent-maintained pages by v2 frontmatter `type` (`entity`, `concept`, `comparison`, `query`) so each page is listed under the correct section:
+
+```bash
+obsidian properties type=entity
+obsidian properties type=concept
+obsidian properties type=comparison
+obsidian properties type=query
+```
+
+For each type, compile entries with:
+- Page name (as wikilink)
+- Title from frontmatter
+- Brief summary (from content's first paragraph or definition section)
+- Tags and domain
+
+Format by section:
+
+```markdown
+# Knowledge Index
+
+## Entities
+- [[feature-a]] — Response time monitoring feature (tags: monitoring, backend)
+- [[zhang-san]] — Senior engineer on Feature A team (tags: team, engineering)
+
+## Concepts
+- [[response-time-metrics]] — Why median replaced avg for trigger calculation (tags: metrics, decisions)
+- [[search-trigger-rules]] — Search trigger rule design principles (tags: search, configuration)
+
+## Comparisons
+- [[avg-vs-median-for-trigger]] — Side-by-side analysis of avg vs median as trigger metrics (tags: metrics, decisions)
+
+## Queries
+- [[why-did-we-choose-median]] — "Why did we choose median over avg?" — detailed answer (tags: metrics, history)
+```
+
+### Step 4: Check Obsidian Base Configuration
+
+INDEX.base relies on Obsidian Base (saved search) configuration. Verify:
+
+1. The Base query covers all four agent directories
+2. The query filters by `type` frontmatter field
+3. Results are grouped by type
+
+If the Base doesn't exist or is misconfigured, guide the user to set it up:
+- Open Obsidian → Bases → Create new base
+- Name it "Knowledge Index"
+- Query: `path:entities/ OR path:concepts/ OR path:comparisons/ OR path:queries/`
+- Group by: `type`
+
+### Step 5: Present the Index
+
+Show the current INDEX.base content to the user:
+
+```markdown
+# Knowledge Index
+
+Generated on YYYY-MM-DD
+
+Total pages: N (X entities, Y concepts, Z comparisons, W queries)
+
+## By Domain
+- backend: N pages
+- frontend: M pages
+- infrastructure: K pages
+
+## Most Connected
+- [[page-name]] — N inbound links
+- [[page-name]] — M inbound links
+
+## Recently Updated
+- [[page-name]] — updated YYYY-MM-DD
+- [[page-name]] — updated YYYY-MM-DD
+```
+
+### Step 6: Suggest Gaps
+
+Based on the index, identify knowledge gaps:
+- Entity mentioned in multiple concepts but no entity page exists
+- Concept referenced in entity pages but no concept page exists
+- Domains with very few pages (under-represented areas)
+- Tags used frequently but no corresponding concept page
+
+## Key Principles
+
+- **INDEX.base is dynamic.** The Obsidian Base query keeps it current — no manual regeneration needed on every cook cycle.
+- **Summary quality.** Each entry's one-line summary should be genuinely informative, not just the page title repeated.
+- **Navigation first.** INDEX.base exists to help humans find knowledge quickly. Structure it for scanning, not completeness.
+- **Obsidian is first workbench.** All note operations go through Obsidian CLI.
+- **Agent pages only.** INDEX.base covers only `entities/`, `concepts/`, `comparisons/`, `queries/` — not user notes.