thoth-plugin 1.2.0 → 1.2.2

package/README.md

@@ -4,6 +4,22 @@
 
 Thoth is a knowledge-based life operating system that acts as your chief of staff. Unlike traditional coding assistants, Thoth is designed to **support, guide, and mentor** — not just write code.
 
+---
+
+## Ecosystem Integration
+
+Thoth is the convergence of multiple OpenCode innovations. It is built upon and integrates with:
+
+- **[OpenCode](https://github.com/opencode-ai/opencode)**: The foundational AI plugin architecture.
+- **[OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)**: The "batteries-included" framework that inspired Thoth's distribution model.
+- **[Personal-OS](https://github.com/Skeptomenos/personal-os)**: The knowledge base structure and "Circle System" methodology.
+- **[OpenProse](https://github.com/opencode-ai/open-prose)**: The declarative workflow language used for complex skills like `morning-boot`.
+- **[Vibe-Kanban](https://github.com/opencode-ai/vibe-kanban)**: Integrated task management visualization and tracking.
+
+Thoth acts as the **Root Orchestrator**, coordinating these tools into a unified "Operating System for Life".
+
+---
+
 ## Installation
 
 ### Via npm (Recommended)

package/defaults/AGENTS.md

@@ -0,0 +1,53 @@
+---
+hemisphere: null
+depth: 0
+boot_sequence: []
+---
+
+# Thoth - Life Orchestrator
+
+Welcome to Thoth, your AI chief of staff for life orchestration.
+
+## Quick Start
+
+If this is your first time using Thoth, you have two options:
+
+### Option 1: Initialize a Knowledge Base
+
+Run in your terminal:
+```bash
+npx thoth-plugin init
+```
+
+This creates a knowledge base structure at `~/thoth/` with:
+- `work/` - Professional life (projects, colleagues, career)
+- `life/` - Personal life (health, relationships, home, finance)
+- `coding/` - Technical projects and development
+- `kernel/` - System configuration and preferences
+
+### Option 2: Use Without a Knowledge Base
+
+Thoth works immediately for:
+- Running skills (`/morning-boot`, `/mail-triage`, etc.)
+- General assistance and planning
+- Ad-hoc task management
+
+## Available Skills
+
+Skills are pre-built workflows. Invoke with the skill tool:
+
+| Skill | Description |
+|-------|-------------|
+| `morning-boot` | Start your day with inbox triage and calendar review |
+| `evening-close` | End-of-day summary and overflow extraction |
+| `mail-triage` | Process Gmail inbox systematically |
+| `slack-pulse` | Scan Slack for mentions and important messages |
+| `thought-router` | Quick capture and route thoughts to the right place |
+| `post-meeting-drill` | Process meeting notes into action items |
+| `leadership-coach` | IC-to-Manager coaching for new leaders |
+
+## Learn More
+
+- Ask: "What skills are available?"
+- Ask: "Help me set up my knowledge base"
+- Ask: "Explain how Thoth works"

package/{dist/defaults/skill → defaults/skill/_legacy}/gardener/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: gardener
 description: Use when knowledge base health needs checking, broken links need fixing, orphan files need registering, or cross-references between related files are missing
+triggers:
+  - "Check knowledge base"
+  - "Run gardener"
+  - "KB health"
+  - "Fix broken links"
+  - "Check for orphan files"
 ---
 
 # Gardener Skill
@@ -58,12 +64,92 @@ The canonical frontmatter schema is defined in `kernel/config/frontmatter-schema
 
 ---
 
+## Severity Levels
+
+All issues are classified by severity to prioritize repair work:
+
+| Severity | Symbol | Meaning | Action |
+|----------|--------|---------|--------|
+| **CRITICAL** | `[C]` | Data integrity at risk, navigation broken | Fix immediately |
+| **ERROR** | `[E]` | Functionality impaired, links broken | Fix soon |
+| **WARNING** | `[W]` | Best practices violated, maintenance debt | Fix when convenient |
+| **INFO** | `[I]` | Suggestions for improvement | Optional |
+
+### Severity by Issue Type
+
+| Issue | Default Severity | Escalation Condition |
+|-------|------------------|----------------------|
+| Missing required frontmatter field | ERROR | CRITICAL if `type` missing |
+| Invalid frontmatter value | WARNING | ERROR if `status` or `priority` |
+| Broken internal link | ERROR | CRITICAL if in registry/index |
+| Missing bidirectional link | WARNING | — |
+| Orphan file (not indexed) | WARNING | ERROR if in people/ or projects/ |
+| Registry ghost (indexed but missing) | CRITICAL | — |
+| Stale _index.md (files not listed) | WARNING | ERROR if >5 files missing |
+| Frontmatter schema violation | ERROR | — |
+
+---
+
 ## Mode 1: Health Check
 
-### Step 1: Run Scan
+### Step 1: Scan All Categories
+
+Perform these checks systematically:
+
+#### 1.1 Frontmatter Validation
+
+For each `.md` file in the knowledge base:
 
-```bash
-npx tsx scripts/gardener-scan.ts --verbose
+```
+CHECK: Has frontmatter block (--- ... ---)
+CHECK: Has required fields: type, hemisphere, created, updated
+CHECK: type value is valid (person, project, task, note, reference, etc.)
+CHECK: hemisphere value matches path (work/, life/, coding/, kernel/)
+CHECK: Type-specific required fields present:
+  - person: relationship
+  - project: status
+  - task: status, priority
+CHECK: Values are valid per schema:
+  - status (project): planning|active|on-hold|completed|cancelled
+  - status (task): pending|in-progress|done|cancelled|blocked
+  - priority: P0|P1|P2|P3
+  - health: green|yellow|red
+  - relationship: manager|peer|report|stakeholder|friend|family
+```
+
+#### 1.2 Link Integrity
+
+For each `[[wikilink]]` and `[markdown](link)`:
+
+```
+CHECK: Target file exists
+CHECK: Target path is correct (not moved/renamed)
+CHECK: Bidirectional: if A links to B, does B link to A?
+```
+
+#### 1.3 Index Coverage
+
+For each `_index.md` file:
+
+```
+CHECK: All files in same directory are listed
+CHECK: All listed files actually exist (no ghosts)
+CHECK: File summaries are present and accurate
+```
+
+For `registry.md`:
+
+```
+CHECK: All hemispheres represented
+CHECK: Key entity counts are accurate
+CHECK: Last updated date is recent
+```
+
+#### 1.4 Orphan Detection
+
+```
+CHECK: Every .md file (except _index.md, registry.md) is listed in its _index.md
+CHECK: Every entity file has at least one incoming link
 ```
 
 ### Step 2: Synthesize Report
@@ -73,21 +159,34 @@ npx tsx scripts/gardener-scan.ts --verbose
 
 **Scanned**: {timestamp}
 **Total Files**: {count}
-**Overall Health**: {healthy|needs-attention|critical}
-
-### Summary
-| Category | Count | Severity |
-|----------|-------|----------|
-| Frontmatter Issues | X | warning |
-| Broken Links | X | error |
-| Orphan Files | X | warning |
-| Registry Ghosts | X | error |
-
-### Critical Issues (Top 10)
-{List with file path and issue}
+**Overall Health**: {HEALTHY|NEEDS-ATTENTION|CRITICAL}
+
+### Summary by Severity
+| Severity | Count | Categories |
+|----------|-------|------------|
+| CRITICAL | X | {list} |
+| ERROR | X | {list} |
+| WARNING | X | {list} |
+| INFO | X | {list} |
+
+### Issue Breakdown
+| Category | [C] | [E] | [W] | [I] |
+|----------|-----|-----|-----|-----|
+| Frontmatter Issues | X | X | X | X |
+| Broken Links | X | X | X | X |
+| Missing Bidirectional | — | — | X | X |
+| Orphan Files | — | X | X | — |
+| Index Staleness | — | X | X | — |
+| Registry Ghosts | X | — | — | — |
+
+### Critical Issues (Must Fix)
+{List all CRITICAL items with file path and specific issue}
+
+### Errors (Should Fix)
+{List top 10 ERROR items}
 
 ### Recommendations
-{3-5 prioritized actions}
+{3-5 prioritized actions based on findings}
 ```
 
 ---
@@ -228,6 +327,87 @@ For each approved link:
 
 ---
 
+## Bidirectional Link Verification
+
+A healthy knowledge base has bidirectional links: if A references B, B should reference A.
+
+### Detection Algorithm
+
+```
+For each file A:
+  For each outgoing link to file B:
+    Check if B has any link back to A
+    If not: flag as "Missing bidirectional: B should link to A"
+```
+
+### Severity Classification
+
+| Situation | Severity |
+|-----------|----------|
+| Person A mentions Person B, B doesn't mention A | WARNING |
+| Project links to stakeholder, stakeholder doesn't link to project | WARNING |
+| Registry/index links to file, file doesn't link back | INFO (one-way is OK) |
+| Two files in `related:` frontmatter but no body links | WARNING |
+
+### Repair Suggestion Format
+
+```markdown
+### Missing Bidirectional Links
+
+| Source | Target | Evidence | Suggested Fix |
+|--------|--------|----------|---------------|
+| work/people/alice.md | work/people/bob.md | Alice mentions Bob (line 23) | Add `[[alice]]` to bob.md Related section |
+```
+
+---
+
+## Index Staleness Detection
+
+Every directory with content files should have an `_index.md` that lists all files.
+
+### Detection Algorithm
+
+```
+For each directory with _index.md:
+  List all .md files in directory (excluding _index.md)
+  Parse _index.md for file references
+  
+  STALE if:
+    - File exists but not in _index.md (orphan)
+    - File in _index.md but doesn't exist (ghost)
+    - File count mismatch > 0
+```
+
+### Severity Classification
+
+| Situation | Severity |
+|-----------|----------|
+| 1-2 files missing from _index.md | WARNING |
+| 3-5 files missing from _index.md | WARNING |
+| >5 files missing from _index.md | ERROR |
+| Ghost entry (listed but doesn't exist) | ERROR |
+| _index.md missing entirely in content directory | ERROR |
+
+### Report Format
+
+```markdown
+### Index Staleness Report
+
+| Directory | Files | Indexed | Missing | Ghosts | Severity |
+|-----------|-------|---------|---------|--------|----------|
+| work/people/ | 15 | 12 | 3 | 0 | [W] |
+| work/projects/ | 8 | 8 | 0 | 1 | [E] |
+
+#### Missing from Index
+- work/people/new-person.md (created 2026-01-09)
+- work/people/another.md (created 2026-01-08)
+
+#### Ghost Entries (file doesn't exist)
+- work/projects/deleted-project.md (remove from _index.md)
+```
+
+---
+
 ## Red Flags - STOP
 
 - About to add 50+ links without review
@@ -280,4 +460,50 @@ Before completing cross-reference mode:
 
 ---
 
-*Gardener v3.0 | Part of Thoth Knowledge Management System*
+## Frontmatter Validation Details
+
+### Required Fields by Type
+
+| File Type | Required Fields | Optional Fields |
+|-----------|-----------------|-----------------|
+| **All files** | `type`, `hemisphere`, `created`, `updated` | `tags`, `summary`, `related` |
+| **person** | + `relationship` | `email`, `slack`, `role`, `company` |
+| **project** | + `status` | `priority`, `health`, `due`, `stakeholders` |
+| **task** | + `status`, `priority` | `due`, `project`, `assignee` |
+
+### Validation Error Examples
+
+```markdown
+### Frontmatter Validation Errors
+
+| File | Issue | Severity | Fix |
+|------|-------|----------|-----|
+| work/people/alice.md | Missing `relationship` field | [E] | Add `relationship: peer` |
+| work/projects/foo.md | Invalid status: "wip" | [E] | Change to `status: active` |
+| life/notes/random.md | Missing `type` field | [C] | Add `type: note` |
+| work/people/bob.md | hemisphere: "work" but path is life/ | [W] | Update to `hemisphere: life` |
+```
+
+### Auto-Fixable Issues
+
+The following can be auto-fixed with `/gardener fix`:
+
+| Issue | Auto-Fix Action |
+|-------|-----------------|
+| Missing `created` | Set to file creation date |
+| Missing `updated` | Set to file modification date |
+| Missing `hemisphere` | Infer from file path |
+| Incorrect `hemisphere` | Correct to match path |
+
+### Manual-Fix Required
+
+| Issue | Why Manual |
+|-------|------------|
+| Missing `type` | Cannot infer content type |
+| Missing `relationship` | Cannot guess relationship |
+| Missing `status` | Cannot guess project/task state |
+| Invalid enum value | Need user to choose correct value |
+
+---
+
+*Gardener v4.0 | Part of Thoth Knowledge Management System*

package/defaults/skill/_legacy/onboarding/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: onboarding
+description: Structured onboarding for new domains using breadth-before-depth discovery
+triggers:
+  - "Let's onboard"
+  - "New domain"
+  - "Help me set up"
+  - "Onboard my"
+  - "Learn about my"
+---
+
+# Onboarding Skill
+
+You are entering **Onboarding Mode**. Your role is to systematically learn about a new domain of Zeus's life while avoiding the depth trap.
+
+---
+
+## Philosophy
+
+1. **Breadth before depth** — Map the landscape before diving deep
+2. **Step back pattern** — After 5-10 minutes on any topic, ask "What else?"
+3. **Prevent premature action** — Focus on understanding, not doing
+4. **Structured but conversational** — Have a framework, follow Zeus's energy
+5. **Persist as you go** — Create knowledge files for important entities discovered
+
+---
+
+## Protocol
+
+### Phase 1: Orient (Start Here)
+
+Ask these questions before anything else:
+
+1. **Domain**: What domain are we onboarding? (work, life, specific project, specific area)
+2. **Goal**: What's the goal of this onboarding? (understand context, set up tracking, prepare for something)
+3. **Sources**: What systems/data sources are available? (email, calendar, documents, nothing yet)
+
+**Output**: Clear understanding of scope and available data.
+
+---
+
+### Phase 2: Scan (If Data Sources Available)
+
+If Zeus has connected email, calendar, or documents:
+
+1. Fire parallel background agents to scan:
+   ```
+   background_task(agent="general", prompt="Scan recent emails for people, projects, recurring themes...")
+   background_task(agent="general", prompt="Scan calendar for meetings, recurring events, key people...")
+   ```
+
+2. Synthesize findings:
+   - Key people mentioned
+   - Active projects/areas
+   - Recurring themes
+   - Open items/commitments
+
+**Output**: Data-driven overview of the domain landscape.
+
+---
+
+### Phase 3: Discover (Interview Mode)
+
+Ask clarifying questions about what you found (or start here if no data sources):
+
+| Area | Questions |
+|------|-----------|
+| **People** | Who are the key people? (just names for now — we'll go deeper later) |
+| **Projects/Areas** | What are the main projects or areas of focus? |
+| **Challenges** | What's the biggest challenge or pain point right now? |
+| **Success** | What does success look like? What are you optimizing for? |
+| **Gaps** | What's not working? What falls through the cracks? |
+
+**Key rule**: Collect NAMES and TOPICS first. Don't drill into any one area yet.
+
+**Output**: List of people, projects, challenges, and goals.
+
+---
+
+### Phase 4: Step Back (CRITICAL)
+
+After covering one area for 5-10 minutes, ALWAYS ask one of these:
+
+- "We've covered [X]. Before going deeper, are there other areas we should map out?"
+- "What else is on your mind that we haven't touched?"
+- "Is there anything blocking you that we should address first?"
+- "Are there other people or projects I should know about before we continue?"
+
+**NEVER** dive deep into one entity without first mapping the full landscape.
+
+**Anti-Pattern Detection**: If you've been discussing one project or person for more than 5 minutes and haven't asked about others, STOP and ask.
+
+---
+
+### Phase 5: Deepen (Only After Breadth)
+
+Once the landscape is mapped, ask Zeus which area to explore first:
+
+- "We've identified [projects A, B, C] and [people X, Y, Z]. Which would you like to detail first?"
+- "What's most urgent or important to capture deeply?"
+
+For each entity Zeus prioritizes:
+
+1. Create a knowledge file using appropriate template
+2. Capture key details, relationships, status
+3. Add to relevant `_index.md`
+4. Create bidirectional links to related entities
+
+---
+
+### Phase 6: Close
+
+Before ending the onboarding session:
+
+1. **Summarize** what was learned:
+   - Domain scope
+   - Key entities created
+   - Relationships mapped
+
+2. **Identify gaps** to fill later:
+   - "We didn't get to [X, Y, Z]. Should we schedule follow-up?"
+   - "I'm missing context on [A, B]. Can we cover that next time?"
+
+3. **Set expectations**:
+   - "I'll continue learning as we interact. Correct me when I'm wrong."
+   - "Mention new people or projects as they come up — I'll capture them."
+
+---
+
+## Anti-Pattern: The Depth Trap
+
+### WRONG
+
+```
+Zeus: "Let's onboard my work"
+Thoth: "Tell me about Project Alpha"
+Zeus: [explains Project Alpha for 20 minutes]
+Thoth: [asks more Project Alpha questions]
+[30 minutes later, deep in Project Alpha details]
+[Never asked about other projects, colleagues, goals]
+```
+
+### RIGHT
+
+```
+Zeus: "Let's onboard my work"
+Thoth: "Before we dive deep, let me understand the landscape. 
+        Who are the key people you work with?"
+Zeus: [lists 5 people]
+Thoth: "And what are the main projects or areas you're focused on?"
+Zeus: [lists 3 projects]
+Thoth: "Got it. What's your biggest challenge right now?"
+Zeus: [explains challenge]
+Thoth: "Before we go deeper on any of these, is there anything 
+        else I should know about — other projects, people, or 
+        responsibilities?"
+Zeus: [adds 2 more things]
+Thoth: "Now, which of these would you like to detail first?"
+```
+
+---
+
+## Knowledge Creation During Onboarding
+
+As you discover entities, create files:
+
+| Entity Type | Template | Location |
+|-------------|----------|----------|
+| Person (work) | `kernel/templates/person.md` | `work/people/` |
+| Person (life) | `kernel/templates/person.md` | `life/people/` |
+| Project | `kernel/templates/project.md` | `{hemisphere}/projects/` |
+| Area/Topic | Create overview file | Appropriate folder |
+
+**Rules**:
+- Check if entity already exists before creating (grep for name)
+- Add to `_index.md` immediately after creation
+- Create bidirectional links between related entities
+- Use frontmatter with appropriate type, hemisphere, tags
+
+---
+
+## Verification Checklist
+
+Before ending onboarding session:
+
+- [ ] Asked about multiple areas (people, projects, challenges, goals)
+- [ ] Used step-back pattern at least once
+- [ ] Didn't spend more than 10 minutes on any single entity before mapping others
+- [ ] Created knowledge files for key entities
+- [ ] Updated relevant `_index.md` files
+- [ ] Identified gaps for follow-up
+- [ ] Zeus knows what to expect going forward
+
+---
+
+## Quick Reference
+
+| Trigger | Action |
+|---------|--------|
+| "Let's onboard my work" | Start Phase 1 with work domain |
+| "Help me set up life tracking" | Start Phase 1 with life domain |
+| "New project: X" | Orient on project X specifically |
+| "Learn about my team" | Focus on people discovery |
+
+---
+
+*Onboarding Skill v1.0 | Part of Thoth Knowledge Management System*

package/defaults/skill/evening-close/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: evening-close
+version: 1.0.0
+description: Summarize the day, extract incomplete tasks into tomorrow's overflow, and persist daily learnings to the Knowledge Base.
+triggers: 
+output: 
+type: markdown
+created: 2026-01-09
+updated: 2026-01-09
+---
+
+# Evening Close Skill
+
+You are the **Integrity & Persistence Lead**. Your goal is to ensure that every win, decision, and observation from the day is properly archived and that tomorrow begins with total clarity.
+
+## Protocol Execution
+
+### Step 1: Audit
+
+1. **Read Daily Log**: Load today's `work/logs/YYYY-MM-DD-daily-log.md`.
+2. **Verify Progress**:
+   - Compare **Top 3 Priorities** against the **Action Log**.
+   - Identify any items marked incomplete or not mentioned in the Action Log.
+
+### Step 2: Summarize
+
+1. **Generate Executive Recap**:
+   - **Completed**: Count of actions taken.
+   - **Key Wins**: 2-3 most impactful accomplishments.
+   - **Blockers Surfaced**: Any items preventing progress.
+   - **Decisions Logged**: Summary of strategic choices.
+
+2. **Update Log**: Fill in the `## Evening Summary` section of the `daily-log.md`:
+   - Completed items
+   - Blocked items
+   - Deferred items
+   - Key Wins
+   - Key Decisions
+   - Observations
+
+### Step 3: Extract Overflow
+
+1. **Identify Incomplete Tasks**: Collect all P0/P1 items from Priorities and Pending Responses that were NOT completed.
+
+2. **Create Overflow File**: Write to `work/inbox/overflow-YYYY-MM-DD.md`:
+   ```yaml
+   ---
+   type: overflow
+   from_date: YYYY-MM-DD
+   for_date: YYYY-MM-DD (tomorrow)
+   ---
+   
+   # Overflow Tasks
+   
+   ## From [Date]
+   
+   - [ ] [P0] Task description - Reason: [why not completed]
+   - [ ] [P1] Task description - Reason: [why not completed]
+   ```
+
+### Step 4: Knowledge Persistence (The Save)
+
+Using **Smart Merge** (append-only, never overwrite), update the permanent Knowledge base:
+
+1. **People Profiles**: Extract notes about specific people and append to their `work/people/[person].md` in the `## Interaction Log` section with date stamp.
+
+2. **Project Files**: Extract decisions and append to relevant `work/projects/[project].md` in the `## Decisions` section with date stamp.
+
+3. **Chronicle Entry**: Write a single, high-fidelity sentence summarizing the day's primary outcome to `work/chronicle.md`:
+   ```
+   ## YYYY-MM-DD
+   [One sentence summary of day's state and primary outcome]
+   ```
+
+### Step 5: Weekly Maintenance (Friday Only)
+
+1. **Check Date**: Calculate `DayOfWeek` from `<omo-env>`.
+2. **If Friday**:
+   - Run system hygiene checks
+   - Review week's chronicle entries
+   - Identify patterns or recurring blockers
+   - Suggest focus areas for next week
+
+### Step 6: Finalize
+
+1. Verify all file writes were successful.
+2. Present the summary and overflow list to user in chat for final sign-off.
+3. Suggest any preparation needed for tomorrow.
+
+---
+
+## Technical Constraints
+
+- **Smart Merge**: NEVER overwrite existing context. Only append to specific sections with a date stamp.
+- **Accuracy**: Do not hallucinate outcomes. If an item status is unclear, mark it as "UNCLEAR" and ask user.
+- **Trust Level**: This skill requires Trust Level 2+ for file writes to knowledge base.
+- **Privacy**: Summarize sensitive information, don't copy verbatim.

package/defaults/skill/mail-triage/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: mail-triage
+version: 1.0.0
+description: Max emails to process
+triggers: 
+inputs: 
+- name: limit
+type: markdown
+required: false
+default: 20
+output: 
+created: 2026-01-09
+updated: 2026-01-09
+---
+
+# Mail Triage Skill
+
+You are the Lead Triage Specialist for Zeus's Chief of Staff.
+
+## Protocol Execution
+
+1.  **Read Master Instructions**: Load the full protocol from `kernel/Agents/mail-triage.md`.
+2.  **Execute**: Follow the protocol exactly as defined in the master file.
+3.  **Synthesize**: Provide the high-resolution executive report and the required raw data block.
+
+**MANDATORY**: Ensure the output includes the `## SCAN_DATA_START` and `## SCAN_DATA_END` markers as specified in the master instructions.