@jayjiang/byoao 1.1.2 → 2.0.0

package/src/skills/organize.md

@@ -1,206 +1,107 @@
 ---
 name: organize
-description: Reorganize vault directory structure using Obsidian CLI's move command, which safely updates all backlinks. Analyzes enriched frontmatter (type, domain) to propose a logical folder layout. Use when the user says "organize my vault", "reorganize files", "clean up folders", "restructure", or after running /weave on a messy vault.
+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, or clean up the vault structure.
 ---
 
-# /organize — Vault Directory Reorganization
+# /organize — Directory Organization
 
-You are a vault organizer. Your job is to analyze the current directory structure, propose a logical reorganization based on enriched frontmatter metadata, and execute moves safely using Obsidian CLI — which automatically updates all backlinks and wikilinks.
+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
 
-**Before doing anything else:**
-
-1. Verify Obsidian CLI is available:
-
 ```bash
 obsidian --version
 ```
 
-If this fails, STOP and display:
-
-```
-Obsidian CLI is not available. Please ensure:
-1. Obsidian is running
-2. This vault is open in Obsidian
-3. CLI is enabled: Settings → General → Advanced → Command-line interface
-```
-
-2. Check that files have frontmatter (specifically `type`). Run:
-
-```bash
-obsidian properties sort=count counts
-```
-
-If `type` property has very low coverage (< 30% of notes), STOP and suggest:
-
-```
-Most files lack a `type` property — /organize needs frontmatter to
-decide where files belong. Run /weave first to enrich your notes,
-then come back to /organize.
-```
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
 
 ## Parameters
 
-- **scope** (optional): `all` (default) or a specific directory path to reorganize
-- **dry-run** (optional): If set, show proposed changes without executing
-- **aggressive** (optional): Also suggest consolidating existing directory structures (e.g., merge year-based sprint folders into `Sprints/`)
-
-## File Exclusion Rules
-
-Never move or suggest moving:
-
-| Pattern | Reason |
-|---------|--------|
-| `AGENTS.md` | BYOAO-managed root file |
-| `INDEX.base` | Knowledge graph index — do not move |
-| `Start Here.md` | BYOAO onboarding file |
-| `.obsidian/`, `.git/`, `.byoao/` | System directories |
-| `.opencode/`, `.cursor/`, `.claude/` | Tool config directories |
-| `.env`, `credentials.*`, `*.key` | Sensitive files |
+- **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: Analyze Current Structure
-
-Build a complete picture of the vault:
+### Step 1: Scan Current Structure
 
 ```bash
 obsidian list
 ```
 
-Then read frontmatter for every file to build a map of `path → {type, domain, project, tags}`. Use batch reading:
+Build a picture of:
+- Current directory structure
+- Notes in each directory
+- Notes that seem misplaced based on their frontmatter
 
-```bash
-obsidian read "<note name>"
-```
-
-Categorize every file into one of:
-- **Has type** — can be auto-organized based on the mapping table
-- **No type but in coherent directory** — already organized, leave in place
-- **No type and in root/flat dir** — suggest running `/weave` first
-
-### Step 2: Build Reorganization Map
+### Step 2: Check Agent Pages
 
-For each file with a `type` property, determine if it should move based on this mapping:
+Agent pages should live in their designated directories:
 
-| `type` | Target Directory | Notes |
-|--------|-----------------|-------|
-| `daily` | `Daily/` | |
-| `meeting` | Project folder if `project` field exists, else `Meetings/` | Group by project when possible |
-| `feature` | `Projects/<project>/` | Use `project` frontmatter field |
-| `project` | `Projects/` | Top-level project notes |
-| `sprint-handoff` | `Sprints/` | |
-| `reference` | `Knowledge/` or user's preferred reference location | General reference material |
-| `person` | `People/` | |
-| `investigation` | Project folder if `project` field exists, else `Knowledge/` | |
-| `idea` | `Knowledge/` | |
-| `decision` | Project folder if `project` field exists, else `Knowledge/` | |
+| `type` frontmatter | Expected directory |
+|-------------------|-------------------|
+| `entity` | `entities/` |
+| `concept` | `concepts/` |
+| `comparison` | `comparisons/` |
+| `query` | `queries/` |
 
-**Smart rules — when NOT to move:**
+For each agent page, check:
+- Does its current directory match its `type`?
+- If not, suggest a move
 
-1. **Already in the right place** — if a `type: meeting` file is already in `Meetings/` or inside a project folder, skip it
-2. **Part of a coherent group** — if a file sits in `2025 Sprint/Sprint22/JIRA ticket/` alongside related files, the entire group is already organized even if the parent folder name doesn't match BYOAO conventions. Do NOT break up coherent groups
-3. **Deep nesting** — if a file is 3+ levels deep in a project-specific directory, it's likely intentionally placed. Leave it unless the user explicitly asks to flatten
-4. **Name collisions** — if moving a file would create a name collision in the target directory, flag it and skip
+### Step 3: Check User Notes
 
-**When `aggressive` mode is enabled**, also suggest structural consolidation:
-- Multiple year/sprint directories (e.g., `2025 Sprint/`, `2026 Sprint/`) → merge under `Sprints/2025/`, `Sprints/2026/`
-- Scattered documentation directories → consolidate under `Knowledge/`
-- This is a larger operation — always present as a separate approval step
+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:
 
-### Step 3: Present Plan
+- 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)
 
-Group proposed moves by category and show a clear summary:
-
-```
-/organize analysis complete.
+### Step 4: Check Naming Conventions
 
-## Files to move (23 of 504)
+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`)
 
-### Root files → proper directories
-  HANDOVER-2026-03-04.md → Knowledge/Handovers/HANDOVER-2026-03-04.md
-  HANDOVER-2026-03-02.md → Knowledge/Handovers/HANDOVER-2026-03-02.md
-  BigQuery_Syntax_Guide.md → Knowledge/BigQuery_Syntax_Guide.md
+Flag any naming violations.
 
-### Meeting notes → Meetings/
-  standup-2026-03-15.md → Meetings/standup-2026-03-15.md
+### Step 5: Suggest Moves
 
-### Reference docs → Knowledge/
-  API_Overview.md → Knowledge/API_Overview.md
+For each misplaced file:
 
-## New directories to create
-  Knowledge/Handovers/
-  Meetings/
-
-## Files staying in place: 481
-  (Already in coherent directory structures)
-
-## Files without `type` (cannot auto-organize): 12
-  Run /weave on these first, then re-run /organize.
-
-Options:
-  1. Approve all moves
-  2. Review one-by-one
-  3. Skip — make no changes
 ```
+Move: entities/wrong-place.md → concepts/wrong-place.md
+  Reason: type=concept but currently in entities/
 
-Wait for user response before proceeding.
+Move: Projects/random-notes.md → Projects/feature-a/
+  Reason: Content is about Feature A, should be grouped with other Feature A notes
+```
 
-### Step 4: Execute Moves
+### Step 6: Apply Moves (If Confirmed)
 
-For each approved move, use `obsidian move`:
+Use Obsidian CLI to rename/move files:
 
 ```bash
-obsidian move file="HANDOVER-2026-03-04" to="Knowledge/Handovers/"
+obsidian rename file="old-path.md" new_name="new-path.md"
 ```
 
-**Execution rules:**
+Always show the full plan before applying. Never move files silently.
 
-- Create target directories first if they don't exist:
-  ```bash
-  mkdir -p "<vault path>/<target directory>"
-  ```
-- Execute moves one at a time and verify each succeeds
-- If a move fails (name collision, file locked, etc.), log the error and continue with remaining moves
-- Report progress every 10 moves: "Moved 10/23 files..."
+### Step 7: Update Wikilinks
 
-**Why `obsidian move` instead of `mv`:**
+After moving files, check that all wikilinks to the moved files are still valid:
 
-`obsidian move` tells Obsidian to perform the move internally. Obsidian automatically updates **all wikilinks and backlinks** across the entire vault that reference the moved file. Using file system `mv` would leave broken links.
-
-### Step 5: Verify
-
-After all moves complete:
-
-1. Get the updated file list:
-   ```bash
-   obsidian list
-   ```
-
-2. Check for broken links:
-   ```bash
-   byoao_graph_health
-   ```
-
-3. Report results:
-
-```
-/organize complete:
-  - Moved: 23 files
-  - Skipped: 0 (errors)
-  - New directories created: 2
-  - Broken links after moves: 0
-  - Files still without `type`: 12 (run /weave to fix)
+```bash
+obsidian backlinks "moved-file"
 ```
 
-If any broken links are found, report them and suggest fixes.
+Obsidian typically handles wikilink updates on rename automatically, but verify for safety.
 
-## Important Guidelines
+## Key Principles
 
-- **Conservative by default**: Only suggest moves where the benefit is clear. A file that's "good enough" where it is should stay
-- **Never break coherent groups**: If files are organized together in a project directory, don't scatter them even if their `type` would suggest different target directories
-- **User approval is mandatory**: Never move files without explicit confirmation
-- **`obsidian move` only**: Never use file system `mv`, `cp`, or rename commands for vault files — only `obsidian move` and `obsidian rename` preserve link integrity
-- **Idempotent**: Running /organize twice should not propose moves for files that were already correctly placed in the first run
-- **Reversible**: If the user wants to undo, they can run `/organize` again with manual adjustments, or restore from git history
+- **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.md

@@ -0,0 +1,63 @@
+---
+name: prep
+description: >
+  Shared prerequisites check — verifies Obsidian CLI is available and displays a correct
+  error message with installation guidance. Referenced by all skills via "(see /prep)".
+---
+
+# /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.md

@@ -1,11 +1,14 @@
 ---
 name: trace
-description: Track how an idea, concept, or topic evolved across the vault over time. Builds a chronological timeline from scattered mentions. Use when the user asks "how did X evolve", "what's the history of", "when did we start thinking about", "trace this idea", or wants to understand the arc of a concept.
+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", or wants to understand how an idea changed over time.
 ---
 
-# /trace — Track Idea Evolution
+# /trace — Chronological Timeline
 
-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.
+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
 
@@ -13,144 +16,126 @@ You are a knowledge archaeologist. Your job is to trace how a specific idea, con
 obsidian --version
 ```
 
-If this fails, STOP and display the Obsidian CLI availability message (see /weave for the full error text).
-
-## Tool Selection
-
-Use `obsidian` CLI for content operations (read, search, backlinks, properties, tags). Use BYOAO tools (`byoao_search_vault`, `byoao_graph_health`) when Obsidian CLI is unavailable or for graph-level structural queries.
+If this fails, STOP and display the Obsidian CLI availability message (see /prep).
 
 ## 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.
+- **topic** (required): The idea, decision, or concept to trace.
+- **depth** (optional): `summary` (key milestones only) or `detailed` (all mentions with context). Default: `summary`.
 
 ## Process
 
-### Sampling Strategy
-
-If a 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: Find All Mentions
+### Step 1: Locate All Mentions
 
-Search for the topic across the vault using multiple strategies:
+Search for the topic across all notes:
 
 ```bash
 obsidian search "<topic>"
+obsidian tags "<topic>"
 ```
 
-Also check:
-- `INDEX.base` if it exists, for domain and note_type classification
-- Backlinks to `[[<topic>]]` if a note exists for it
-- Tag variations: `#<topic>`, `#<topic-kebab-case>`
+Also search agent-maintained pages under `entities/`, `concepts/`, `comparisons/`, and `queries/`:
 
 ```bash
-obsidian backlinks "<topic>"
+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 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?
+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
 
-Sort all mentions chronologically.
+### Step 3: Detect Phases
 
-### Step 3: Identify Phases
+Group the timeline into phases:
 
-Look for natural phases in how the topic evolved:
+- **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)
 
-- **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
+A topic may skip phases, cycle back, or have multiple parallel tracks.
 
-Not every topic will have all phases. Some may cycle through phases multiple times.
+### Step 4: Identify Turning Points
 
-### Step 4: Detect Turning Points
+Highlight moments where the trajectory changed:
 
-Flag moments where the user's understanding or stance shifted:
+- "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
 
-- 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: Find Contradictions
 
-### Step 5: Present the Trace
+Compare statements across time:
 
-Format the output as a structured timeline:
+- "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?
 
-```markdown
-# Trace: {Topic}
+Flag genuine contradictions. Note the dates, sources, and nature of the conflict.
 
-Traced across {N} notes, spanning {date range}.
+### Step 6: Present Timeline
 
-## Timeline
+```markdown
+# Timeline: {topic}
 
-### Phase 1: Discovery ({date range})
+Traced across {N} notes spanning {start date} to {end date}.
 
-- **{date}** — [[Note Name]]: {1-2 sentence summary}
-  > "{key quote from the note}"
-- **{date}** — [[Note Name]]: {summary}
+---
 
-### Phase 2: Investigation ({date range})
+## Phase 1: {Phase Name} ({date range})
 
-- **{date}** — [[Note Name]]: {summary}
+**What was happening**: {brief context}
 
-### Turning Point: {description}
+- **{date}** — [[Note A]]: {what happened / what was decided}
+- **{date}** — [[Note B]]: {what changed / what was added}
 
-- **{date}** — [[Note Name]]: {what changed and why}
+**Key insight**: {what this phase reveals}
 
-### Phase 3: Decision ({date range})
+---
 
-- **{date}** — [[Note Name]]: {summary}
+## Phase 2: {Phase Name} ({date range})
+...
 
-## 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}
+## Turning Points
 
-## Related Traces
+1. **{date}**: {what changed and why it mattered} — [[source note]]
 
-Consider tracing these connected topics:
-- [[Related Topic 1]] — mentioned in {N} of the same notes
-- [[Related Topic 2]] — appears to be a dependency
-```
+## Contradictions Found
 
-### Step 6: Save (Optional)
+- ⚠ [[Note A]] says X, but [[Note B]] says Y — {resolution if known}
 
-At the end of your trace, ask:
+## Current State
 
-> "Would you like me to save this as a note?"
+{Where things stand now — the most recent position on this topic}
 
-If the user confirms, save the trace with frontmatter:
+## Unanswered Questions
 
-```yaml
----
-title: "Trace: {Topic}"
-note_type: literature
-type: reference
-domain: <inferred from topic>
-date: <today>
-references:
-  - "[[note1]]"
-  - "[[note2]]"
-tags: [trace, <topic-tag>]
----
+{What the vault doesn't tell us about this topic's evolution}
 ```
 
-Use `obsidian create` to save. Ask the user where they'd like it saved.
-
 ## 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.
+- **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.