thoth-plugin 1.2.3 → 1.2.5

package/README.md

@@ -151,8 +151,10 @@ Thoth includes built-in skills that trigger automatically based on your intent:
 | "start my day", "morning routine", "prepare me for the day" | morning-boot |
 | "end of day", "wrap up", "evening summary" | evening-close |
 | "check my email", "email triage" | mail-triage |
+| "process meeting notes", "drill meeting" | post-meeting-drill |
 | "check slack", "slack mentions" | slack-pulse |
 | "brain dump", "capture this" | thought-router |
+| "draft an email", "write email to" | email-draft |
 
 ### Managing Skills
 
@@ -201,7 +203,16 @@ Use the `skill-generator` skill:
 /skill-generator
 ```
 
-Skills are defined in `.opencode/skill/` with YAML frontmatter:
+Skills follow a modular architecture with three components:
+
+```
+skill-name/
+├── SKILL.md              # Workflow logic (required)
+├── skill-name-template.md   # Output template (optional)
+└── skill-name.prose      # OpenProse orchestration (optional)
+```
+
+Skills are defined with YAML frontmatter:
 
 ```yaml
 ---
@@ -210,6 +221,9 @@ description: Use when [specific triggers]. Third person.
 triggers:
   - phrase that activates this skill
   - another trigger phrase
+template: my-skill-template.md    # Optional output template
+created: 2026-01-01
+updated: 2026-01-01
 ---
 
 # My Skill
@@ -231,6 +245,8 @@ triggers:
 
 The `triggers` field enables automatic skill invocation when the user's message matches.
 
+See `docs/concepts/skill-architecture.md` for the full architecture specification.
+
 ## Sub-Agents
 
 Thoth delegates to specialized agents:

package/defaults/skill/cal-grid/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: cal-grid
+description: Map the daily calendar grid identifying meetings, deep work slots, and preparation needs.
+triggers: 
+template: cal-grid-template.md
+created: 2026-01-09
+updated: 2026-01-09
+---
+
+<!--
+ARCHITECTURE REFERENCE: docs/concepts/skill-architecture.md
+This skill can be invoked standalone OR as a subagent context template.
+-->
+
+# Calendar Grid Skill
+
+You are the Daily Grid Architect. Your mission is to scan today's calendar and produce a high-resolution grid of the day.
+
+---
+
+## Context Requirements (EXECUTE FIRST)
+
+This skill requires the user's email address for API calls.
+
+**Step 0 — Get Identity:**
+
+1. **Check if passed in context**: If you received `context.identity.email`, use it directly.
+
+2. **If not passed, invoke context-discovery skill**: Call `skill({ name: "context-discovery" })` and use the returned `email` value.
+
+3. **Store as `EMAIL`** for use in all API calls below.
+
+**If discovery fails**: Stop and report the error from context-discovery.
+
+---
+
+## When to Use
+
+- Morning boot calendar scan
+- "What's on my calendar today?"
+- "Any meetings I need to prepare for?"
+- Before planning focus time
+
+---
+
+## Tools Required
+
+| Action       | Tool                        | Parameters                                                             |
+| ------------ | --------------------------- | ---------------------------------------------------------------------- |
+| Get events   | google-workspace_get_events | `user_google_email: {EMAIL}`, `time_min`, `time_max`, `detailed: true` |
+| Write output | write                       | `work/operations/daily-log/YYYY-MM-DD/cal-grid.md`                                     |
+
+---
+
+## Execution Protocol
+
+### Phase 1: Scan Calendar
+
+```
+google-workspace_get_events(
+  user_google_email={EMAIL},
+  time_min="YYYY-MM-DDT00:00:00Z",  # Today start
+  time_max="YYYY-MM-DDT23:59:59Z",  # Today end
+  detailed=true
+)
+```
+
+Also scan tomorrow for preparation awareness:
+```
+google-workspace_get_events(
+  user_google_email={EMAIL},
+  time_min="YYYY-MM-DD+1T00:00:00Z",  # Tomorrow start
+  time_max="YYYY-MM-DD+1T23:59:59Z",  # Tomorrow end
+  detailed=true
+)
+```
+
+### Phase 2: Analyze Each Meeting
+
+For each event, determine:
+
+| Field | Analysis |
+|-------|----------|
+| **Time** | Start-end in local time |
+| **Event** | Title (clean up noise) |
+| **Attendees** | Who's attending, any VIPs? |
+| **Prep Needed** | What preparation is required? |
+| **Classification** | 1:1, Team, External, Focus, Admin |
+
+**Classification Guide:**
+
+| Type | Signal |
+|------|--------|
+| 1:1 | Two attendees, recurring |
+| Team | 3+ internal attendees |
+| External | External domain attendees |
+| Focus | Blocked time, no attendees |
+| Admin | Recurring admin tasks |
+
+### Phase 3: Identify Focus Blocks
+
+Find gaps between meetings that could be used for deep work:
+
+| Block Quality | Duration |
+|---------------|----------|
+| Deep Work | 90+ minutes |
+| Shallow Work | 30-90 minutes |
+| Buffer | <30 minutes |
+
+### Phase 4: Flag Preparation Needs
+
+For each meeting, assess:
+- Do I need to review anything beforehand?
+- Are there action items I committed to?
+- Is this a high-stakes meeting (skip-level, external)?
+
+---
+
+## Output Format
+
+**Template:** Read `cal-grid-template.md` from this skill folder.
+
+**Output path:** `work/operations/daily-log/YYYY-MM-DD/cal-grid.md`
+
+Fill the template placeholders with scan results:
+
+| Placeholder | Value |
+|-------------|-------|
+| `{{DATE}}` | Today's date (YYYY-MM-DD) |
+| `{{TIME}}` | Scan completion time (HH:MM) |
+| `{{CALENDAR_ID}}` | Calendar scanned (usually "primary") |
+| `{{MEETING_COUNT}}` | Total meetings today |
+| `{{MEETING_HOURS}}` | Total hours in meetings |
+| `{{FOCUS_HOURS}}` | Available focus time |
+| `{{COMPLEXITY}}` | Light/Medium/Heavy |
+| `{{TODAY_MEETINGS_TABLE}}` | Table rows for today's meetings |
+| `{{FOCUS_BLOCKS_TABLE}}` | Table rows for focus blocks |
+| `{{PREP_REQUIRED_TABLE}}` | Table rows for meetings needing prep |
+| `{{CONFLICTS_TABLE}}` | Table rows for conflicts (if any) |
+| `{{TOMORROW_TABLE}}` | Table rows for tomorrow preview |
+| `{{HIGH_PRIORITY_PREP}}` | Urgent prep items |
+| `{{STANDARD_PREP}}` | Standard prep items |
+| `{{DEEP_WORK_STRATEGY}}` | Recommended focus block usage |
+
+**Critical:** Output MUST include `## SCAN_DATA_START` and `## SCAN_DATA_END` markers for parsing.
+
+---
+
+## Completion Checklist
+
+- [ ] Context discovery completed (have EMAIL)
+- [ ] Today's events scanned
+- [ ] Tomorrow's events scanned for prep
+- [ ] Each meeting classified
+- [ ] Focus blocks identified
+- [ ] Preparation needs flagged
+- [ ] Output written to `work/operations/daily-log/YYYY-MM-DD/cal-grid.md`
+- [ ] SCAN_DATA markers included
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| No calendar access | Report OAuth needed, stop |
+| Empty calendar | Report "No meetings scheduled", still output focus blocks |
+| API rate limit | Wait and retry once |

package/defaults/skill/cal-grid/cal-grid-template.md

@@ -0,0 +1,106 @@
+---
+type: operations
+hemisphere: work
+created: {{DATE}}
+updated: 2026-01-09
+tags: [cal-grid, daily-log]
+summary: Calendar Grid — {{DATE}}
+---
+
+# Calendar Grid — {{DATE}}
+
+**Scan Time:** {{TIME}}  
+**Calendar:** {{CALENDAR_ID}}
+
+---
+
+## Day Summary
+
+| Metric | Value |
+|--------|-------|
+| **Total meetings** | {{MEETING_COUNT}} |
+| **Meeting hours** | {{MEETING_HOURS}} |
+| **Focus time available** | {{FOCUS_HOURS}} hours |
+| **Complexity** | {{COMPLEXITY}} |
+
+---
+
+## SCAN_DATA_START
+
+### TODAY_MEETINGS
+
+| Time | Event | Attendees | Prep | Type |
+|------|-------|-----------|------|------|
+{{TODAY_MEETINGS_TABLE}}
+
+### FOCUS_BLOCKS
+
+| Block | Duration | Quality |
+|-------|----------|---------|
+{{FOCUS_BLOCKS_TABLE}}
+
+### PREP_REQUIRED
+
+| Time | Meeting | Preparation Needed |
+|------|---------|-------------------|
+{{PREP_REQUIRED_TABLE}}
+
+### CONFLICTS
+
+| Issue | Meetings Affected | Recommendation |
+|-------|-------------------|----------------|
+{{CONFLICTS_TABLE}}
+
+### TOMORROW_PREVIEW
+
+| Time | Event | Prep Needed |
+|------|-------|-------------|
+{{TOMORROW_TABLE}}
+
+## SCAN_DATA_END
+
+---
+
+## Complexity Budget
+
+**Meeting Load: {{COMPLEXITY}}**
+
+{{#if COMPLEXITY == "Light"}}
+- 0-2 meetings scheduled
+- Capacity: 2-3 Heavy tasks, multiple Light tasks
+- Recommendation: Use today for deep work
+{{/if}}
+
+{{#if COMPLEXITY == "Medium"}}
+- 3-4 meetings scheduled
+- Capacity: 1-2 Heavy tasks, few Light tasks
+- Recommendation: Protect focus blocks aggressively
+{{/if}}
+
+{{#if COMPLEXITY == "Heavy"}}
+- 5+ meetings scheduled
+- Capacity: 1 Light task maximum
+- Recommendation: Focus on meetings, defer other work
+{{/if}}
+
+---
+
+## Preparation Alerts
+
+### High Priority
+
+{{HIGH_PRIORITY_PREP}}
+
+### Standard
+
+{{STANDARD_PREP}}
+
+---
+
+## Deep Work Strategy
+
+{{DEEP_WORK_STRATEGY}}
+
+---
+
+*Generated by cal-grid skill at {{TIME}}*

package/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/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