thoth-plugin 1.2.3 → 1.2.5

package/dist/defaults/skill/context-discovery/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: context-discovery
+description: Use when a skill needs Thoth KB context (identity, stakeholders, projects) and it hasn't been discovered yet this session. Called automatically by morning-boot and other context-dependent skills.
+triggers: 
+created: 2026-01-09
+updated: 2026-01-10
+---
+
+<!--
+ARCHITECTURE REFERENCE: docs/concepts/skill-architecture.md
+This skill is typically invoked by other skills, not directly by user.
+-->
+
+# Context Discovery
+
+**Core principle:** Find the Thoth KB and extract context needed for skills to operate, adapting to the actual file structure rather than assuming an ideal one.
+
+---
+
+## When to Use
+
+- Morning-boot or other skills need user context (email, stakeholders)
+- Running from unknown directory and need to find KB root
+- Context hasn't been discovered yet this session
+- User asks "where is my knowledge base"
+
+**Do NOT use when:**
+- Context is already cached in session
+- User explicitly provides context (email, etc.)
+- Running a skill that doesn't need KB context
+
+---
+
+## Quick Reference
+
+| Task | How |
+|------|-----|
+| Find KB root | Check config → walk up for markers → check siblings |
+| Determine hemisphere | Parse CWD path for `/work/`, `/life/`, `/coding/` |
+| Find email | Read `{hemisphere}/AGENTS.md`, extract from MCP config table |
+| Find stakeholders | Check `{hemisphere}/Stakeholders/_index.md` or `{hemisphere}/people/_index.md` |
+| Cache results | Store in `.thoth-state/context.json` for session reuse |
+
+---
+
+## Discovery Algorithm
+
+### Step 1: Check Explicit Config (Fastest)
+
+```
+Check: ~/.config/opencode/thoth.json
+Look for: { "kb_root": "/path/to/thoth-kb" }
+```
+
+If found, use this path directly. Skip walk-up.
+
+### Step 2: Walk Up for Markers
+
+Starting from CWD, check each parent directory for:
+
+| Marker | Priority | Indicates |
+|--------|----------|-----------|
+| `.opencode/thoth.json` with `"type": "thoth-kb"` | 1 (best) | Explicit KB marker |
+| `.thoth-root` file | 2 | Simple marker file |
+| `kernel/` + `work/` + `life/` directories | 3 | Structure-based detection |
+
+Stop at first match. That's the KB root.
+
+### Step 3: Check Siblings (If Walk-Up Fails)
+
+If in a development directory (like `thoth-core`), check sibling directories:
+
+```bash
+ls .. | grep -E "(thoth-kb|kb)" 
+```
+
+Look for directories containing `kernel/` or `.opencode/thoth.json`.
+
+### Step 4: Determine Hemisphere
+
+Analyze CWD path:
+
+| Path Contains | Hemisphere |
+|---------------|------------|
+| `/work/` | work |
+| `/life/` | life |
+| `/coding/` | coding |
+| `/kernel/` | kernel |
+| None of above | unknown |
+
+If hemisphere is `unknown` and KB root was found, default based on context:
+- Morning boot → default to `work`
+- Or ask user which hemisphere
+
+### Step 5: Extract Identity
+
+Read `{kb_root}/{hemisphere}/AGENTS.md` and find the MCP configuration table:
+
+```markdown
+## MCP Tool Configuration
+
+| MCP Server | Required Parameter | Value |
+|------------|-------------------|-------|
+| google-workspace | user_google_email | user@example.com |
+```
+
+Extract `user_google_email` value.
+
+**Fallback locations:**
+1. `{hemisphere}/AGENTS.md` MCP table (preferred)
+2. `{hemisphere}/digital-identity.md`
+3. `{hemisphere}/_identity.md`
+4. `kernel/config/identity.md`
+
+### Step 6: Locate Stakeholders
+
+Check in order (use first that exists):
+1. `{kb_root}/{hemisphere}/Stakeholders/_index.md`
+2. `{kb_root}/{hemisphere}/people/_index.md`
+3. `{kb_root}/{hemisphere}/Team/_index.md` (for direct reports)
+
+### Step 7: Build Context Object
+
+```json
+{
+  "kb_root": "/path/to/thoth-kb",
+  "hemisphere": "work",
+  "identity": {
+    "email": "user@example.com",
+    "source": "work/AGENTS.md"
+  },
+  "stakeholders": {
+    "path": "work/Stakeholders/_index.md",
+    "count": 32
+  },
+  "projects": {
+    "path": "work/projects/_index.md"
+  },
+  "ready": true,
+  "missing": []
+}
+```
+
+### Step 8: Cache Results
+
+Write to `.thoth-state/context.json` in KB root for session reuse.
+
+---
+
+## Output Format
+
+Return a structured context object:
+
+```
+CONTEXT DISCOVERY RESULT
+========================
+
+KB Root: /path/to/thoth-kb
+Hemisphere: work
+Source: ~/.config/opencode/thoth.json (or walk-up, or sibling)
+
+Identity:
+  Email: user@example.com
+  Timezone: Europa/Berlin (if found)
+  Source: work/AGENTS.md
+
+Stakeholders:
+  Path: work/Stakeholders/_index.md
+  Count: 32 files
+
+Projects:
+  Path: work/projects/_index.md
+
+Ready: YES
+Missing Required: (none)
+Missing Optional: [timezone]
+```
+
+If discovery fails:
+
+```
+CONTEXT DISCOVERY FAILED
+========================
+
+KB Root: NOT FOUND
+Searched:
+  - ~/.config/opencode/thoth.json: not found
+  - Walk-up from /current/path: no markers found
+  - Siblings: no thoth-kb found
+
+Action Required: Run context-onboarding to set up KB
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Prevention |
+|---------|------------|
+| Assuming fixed file paths | Always use discovery algorithm, never hardcode |
+| Not checking config file first | Config is fastest path, always check first |
+| Stopping at first `kernel/` found | Verify it's a real KB (has work/ or life/ too) |
+| Parsing AGENTS.md wrong | Look for MCP table specifically, not general content |
+| Not caching results | Always cache to `.thoth-state/context.json` |
+
+---
+
+## Red Flags - STOP
+
+- Hardcoding `/Users/username/...` paths
+- Assuming `_identity.md` exists (it often doesn't)
+- Not handling "hemisphere unknown" case
+- Returning partial results without `ready: false` flag
+- Not reporting what's missing when discovery fails
+
+---
+
+## Verification Checklist
+
+- [ ] Can find KB when running from KB root
+- [ ] Can find KB when running from hemisphere subdirectory
+- [ ] Can find KB when running from sibling directory (e.g., thoth-core)
+- [ ] Correctly extracts email from AGENTS.md MCP table
+- [ ] Reports missing files clearly when KB incomplete
+- [ ] Caches results for session reuse
+- [ ] Works for new user with no KB (reports failure, suggests onboarding)
+
+---
+
+## Integration
+
+Other skills call discovery like this:
+
+```prose
+# In morning-boot.prose
+
+# Check for cached context
+let cached = session "Read .thoth-state/context.json if exists and fresh"
+
+if **no cached context or stale**:
+  let context = do context-discovery
+  
+  if **context.ready is false**:
+    do context-onboarding
+    let context = do context-discovery  # retry
+    
+# Use context
+let email = context.identity.email
+```
+
+---
+
+*Context Discovery v1.0 | Part of Thoth Skill System*

package/dist/defaults/skill/context-discovery/discovery.prose

@@ -0,0 +1,143 @@
+# Context Discovery Test
+# Validates that AI-driven context discovery works reliably
+
+# Phase 1: Environment Discovery
+let discovery = session "Discover Thoth KB environment"
+  prompt: """
+    You are testing context discovery for Thoth skills.
+    
+    Execute these steps and report findings:
+    
+    ## Step 1: Get Current Location
+    Run `pwd` to get the current working directory.
+    
+    ## Step 2: Find KB Root
+    Walk up the directory tree looking for markers:
+    - `.thoth-root` file (preferred marker)
+    - `.opencode/` directory with thoth configuration
+    - `kernel/` directory (thoth-kb convention)
+    
+    For each parent directory up to filesystem root, check if these exist.
+    Stop when you find a marker.
+    
+    ## Step 3: Determine Hemisphere
+    Look at the CWD path:
+    - If path contains `/work/` → hemisphere is "work"
+    - If path contains `/life/` → hemisphere is "life"  
+    - If path contains `/coding/` → hemisphere is "coding"
+    - Otherwise → hemisphere is "unknown"
+    
+    ## Step 4: Locate Identity Files
+    If KB root was found, check for these files (report exists: true/false):
+    - `{root}/work/_identity.md`
+    - `{root}/life/_identity.md`
+    - `{root}/kernel/config/identity.md` (fallback)
+    
+    ## Step 5: Locate Stakeholder Files
+    Check for:
+    - `{root}/work/people/_index.md`
+    - `{root}/life/people/_index.md`
+    
+    ## Report Format
+    
+    Return a structured report:
+    
+    ```
+    DISCOVERY REPORT
+    ================
+    
+    Current Directory: /path/to/cwd
+    
+    KB Root Search:
+    - Checked: /path/to/cwd → no markers
+    - Checked: /path/to/parent → found .thoth-root
+    - KB Root: /path/to/thoth-kb (or NOT FOUND)
+    
+    Hemisphere Detection:
+    - Path analysis: contains "/work/" 
+    - Detected: work (or life, coding, unknown)
+    
+    Identity Files:
+    - work/_identity.md: EXISTS / MISSING
+    - life/_identity.md: EXISTS / MISSING
+    - kernel/config/identity.md: EXISTS / MISSING
+    - Recommended: {path to use}
+    
+    Stakeholder Files:
+    - work/people/_index.md: EXISTS / MISSING
+    - life/people/_index.md: EXISTS / MISSING
+    
+    Ready Status:
+    - Can run morning boot: YES / NO
+    - Missing required: [list of missing files]
+    - Missing optional: [list of missing files]
+    ```
+  """
+
+# Phase 2: Validate Discovery
+session "Analyze discovery results"
+  prompt: """
+    Based on the discovery results above, answer:
+    
+    1. **Discovery Reliability**: Did the walk-up algorithm successfully 
+       find the KB root? Was the hemisphere correctly inferred?
+    
+    2. **File Resolution**: Were identity and stakeholder files found 
+       where expected? Any surprises?
+    
+    3. **Readiness Assessment**: Could the morning boot skill run with 
+       the discovered context? What's missing?
+    
+    4. **Edge Cases Identified**: Any issues with the discovery approach 
+       that would need handling?
+    
+    5. **Recommendations**: Suggestions to improve the discovery pattern.
+    
+    Be specific and actionable.
+  """
+  context: discovery
+
+# Phase 3: Simulate Morning Boot Context Loading
+if **KB root was found and identity file exists**:
+  let identity = session "Load identity file"
+    prompt: """
+      Read the identity file that was discovered (the recommended one 
+      from the discovery report).
+      
+      Extract:
+      - Email address
+      - Timezone
+      - Any other identity context
+      
+      Report what you found.
+    """
+    context: discovery
+  
+  session "Validate identity is usable"
+    prompt: """
+      The identity file was loaded. Validate:
+      
+      1. Is there an email address we can use for Gmail/Calendar APIs?
+      2. Is there a timezone for scheduling context?
+      3. Is the format parseable and consistent?
+      
+      Report whether this identity context is sufficient for morning boot.
+    """
+    context: identity
+
+else:
+  session "Guide user to set up identity"
+    prompt: """
+      No usable KB root or identity file was found.
+      
+      Guide the user to set this up:
+      
+      1. Explain what's needed (a thoth-kb with identity file)
+      2. Show them the expected structure
+      3. Offer to create a starter identity file if they provide:
+         - Their email address
+         - Their timezone
+      
+      Be helpful and specific about file locations.
+    """
+    context: discovery