thoth-plugin 1.2.0 → 1.2.2

package/dist/defaults/skill/_legacy/skill-generator/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: skill-generator
+description: Use when creating a new skill, editing an existing skill, or when asked to document a reusable process or technique
+---
+
+# Skill Generator
+
+You are creating or editing a skill for the Thoth knowledge system.
+
+**Core principle:** No skill without baseline failure first. Writing skills IS Test-Driven Development applied to process documentation.
+
+**Violating the letter of this process is violating the spirit of this process.**
+
+---
+
+## The Iron Law
+
+```
+NO SKILL FILE CREATED UNTIL RED PHASE SUBAGENT COMPLETES
+```
+
+If you create a SKILL.md before the RED phase subagent documents a failure, delete it. Start over.
+
+**No exceptions:**
+- Don't keep it as "draft"
+- Don't "refine it later"  
+- Don't skip because "it's simple"
+- Don't skip because "it's just a technique skill"
+- Delete means delete
+
+---
+
+## Phase 0: Setup
+
+### Step 1: Check if Skill Exists
+
+```bash
+ls -la .opencode/skill/ | grep -i "{skill-name}"
+```
+
+If exists: Read it first. You're editing, not creating.
+
+### Step 2: Classify Skill Type
+
+| Type | Purpose |
+|------|---------|
+| **Discipline** | Rules that resist rationalization (TDD, verification) |
+| **Workflow** | Multi-step process with checkpoints |
+| **Technique** | Concrete method with steps |
+| **Reference** | API docs, syntax guides |
+
+**Write down the type before proceeding.**
+
+### Step 3: Research the Domain
+
+- What tools/APIs are involved?
+- What are common mistakes?
+- What does success look like?
+
+For discipline skills, also identify:
+- What rationalizations will agents use to skip it?
+- What pressure scenarios test compliance?
+
+---
+
+## Phase 1: RED — Baseline Test (MANDATORY)
+
+**You MUST dispatch a subagent to attempt the task WITHOUT the skill.**
+
+### Dispatch Baseline Subagent
+
+```
+task(
+  subagent_type="general",
+  description="Baseline test for {skill-name}",
+  prompt="""
+You are testing baseline behavior WITHOUT a skill.
+
+**Task:** {Describe the task the skill will teach}
+
+**Context:** {Relevant context}
+
+**Instructions:** Complete the task using your best judgment. 
+Do NOT load any skills. Just complete the task as you normally would.
+
+**Report back:**
+1. What approach did you take?
+2. What formatting/tools/methods did you use?
+3. Show the exact output you produced.
+4. What assumptions did you make?
+"""
+)
+```
+
+### Document the Failure
+
+Before proceeding, write down:
+- **What the agent did wrong** (or suboptimally)
+- **What rationalizations were used** (verbatim if possible)
+- **What the skill must teach** to prevent this
+
+**GATE: Do not proceed to Phase 2 until you have documented at least one failure or suboptimal behavior.**
+
+If the baseline agent does everything perfectly, you may not need this skill.
+
+---
+
+## Phase 2: GREEN — Write Minimal Skill
+
+Address the specific failures documented in Phase 1.
+
+### Frontmatter (Required)
+
+```yaml
+---
+name: lowercase-with-hyphens
+description: Use when [specific triggers]. Third person. No workflow summary.
+triggers:
+  - phrase that activates this skill
+  - another trigger phrase
+  - variations users might say
+---
+```
+
+**Frontmatter Rules:**
+
+| Field | Purpose | Rules |
+|-------|---------|-------|
+| `name` | Skill identifier | lowercase, hyphens only |
+| `description` | Injected into system prompt for skill discovery | Start with "Use when...", third person, no workflow summary |
+| `triggers` | **Automatic skill invocation** | Phrases users say that should activate this skill |
+
+**Triggers are critical** — they teach Thoth when to use the skill automatically. Include:
+- Direct commands ("check my email")
+- Natural phrases ("what's in my inbox")
+- Variations ("email triage", "process inbox")
+
+**Description Rules:**
+- ✅ Start with "Use when..."
+- ✅ Describe triggers/symptoms only
+- ✅ Third person (injected into system prompt)
+- ❌ Never summarize the workflow
+- ❌ Never use first person
+
+### Required Sections
+
+Copy this template and fill in:
+
+```markdown
+# Skill Name
+
+**Core principle:** {one sentence}
+
+---
+
+## When to Use
+
+- {symptom or trigger}
+- {symptom or trigger}
+
+**Do NOT use when:**
+- {exclusion}
+
+---
+
+## Quick Reference
+
+| Task | Command/Action |
+|------|----------------|
+| {task} | {how} |
+
+---
+
+## Process / Pattern
+
+{Main content here}
+
+---
+
+## Common Mistakes
+
+| Mistake | Prevention |
+|---------|------------|
+| {mistake} | {fix} |
+
+---
+
+## Red Flags - STOP
+
+- {warning sign}
+- {warning sign}
+
+---
+
+## Verification Checklist
+
+- [ ] {check}
+- [ ] {check}
+```
+
+### Optional Sections (Add If Needed)
+
+- **Rationalization Table** — Required for discipline skills
+- **Examples** — One excellent example beats many mediocre ones
+- **Supporting Files** — Only for heavy reference (>100 lines)
+
+---
+
+## Phase 3: GREEN — Verify With Skill (MANDATORY)
+
+**You MUST dispatch a subagent to attempt the same task WITH the skill.**
+
+### Dispatch Skill-Guided Subagent
+
+```
+task(
+  subagent_type="general",
+  description="Skill-guided test for {skill-name}",
+  prompt="""
+You are testing a skill.
+
+**REQUIRED SKILL — Read and follow this exactly:**
+
+---
+{Paste the full skill content here}
+---
+
+**Task:** {Same task as baseline}
+
+**Context:** {Same context as baseline}
+
+**Instructions:** Follow the skill above. Complete the task.
+
+**Report back:**
+1. What approach did you take?
+2. Did you follow the skill completely?
+3. Show the exact output you produced.
+"""
+)
+```
+
+### Verify the Fix
+
+Compare baseline vs skill-guided:
+- Did the agent avoid the mistakes from Phase 1?
+- Any NEW rationalizations that bypassed the skill?
+- Any ambiguities in the skill that allowed violations?
+
+**GATE: Do not proceed until the skill-guided agent performs correctly.**
+
+If the agent still fails, revise the skill and re-test.
+
+---
+
+## Phase 4: REFACTOR — Quality Gate
+
+### Close Loopholes
+
+For each new rationalization found in Phase 3:
+1. Add explicit counter to Common Mistakes or Rationalization Table
+2. Add to Red Flags section
+3. Re-run Phase 3 if significant changes made
+
+### Format Checks
+
+- [ ] Name: lowercase, hyphens only, no special chars
+- [ ] Description: starts with "Use when...", no workflow summary
+- [ ] Description: third person, under 500 chars
+- [ ] **Triggers: list of phrases that activate this skill**
+- [ ] Has "Core principle" statement
+- [ ] Has "When to Use" section
+- [ ] Has "Quick Reference" table
+- [ ] Has "Common Mistakes" section
+- [ ] Has "Red Flags" section
+- [ ] Has "Verification Checklist"
+
+### Size Checks
+
+```bash
+wc -l .opencode/skill/{name}/SKILL.md
+```
+
+- [ ] SKILL.md under 500 lines
+- [ ] Frequently-loaded skills under 200 lines
+- [ ] Heavy reference in separate files
+
+### Functional Check
+
+- [ ] Baseline subagent documented failure (Phase 1)
+- [ ] Skill-guided subagent performed correctly (Phase 3)
+- [ ] All referenced tools/commands exist
+- [ ] No ambiguous instructions
+
+---
+
+## Rationalization Table
+
+| Excuse | Reality |
+|--------|---------|
+| "This skill is simple, doesn't need structure" | Simple skills still need discoverability. Follow the format. |
+| "I'll add sections later" | Later never comes. Add them now. |
+| "The example is self-explanatory" | Examples don't replace Quick Reference tables. |
+| "It's just a reference skill" | Reference skills still need When to Use and Common Mistakes. |
+| "I already know this domain" | Your knowledge isn't in the file. Document it. |
+| "Baseline test is overkill" | Baseline reveals what you'll skip. Do it. Subagent is mandatory. |
+| "It's just a technique skill, doesn't need baseline" | Technique skills fail too. We learned this with email-draft. Test everything. |
+| "I already know what will fail" | You're guessing. Run the subagent. Document actual behavior. |
+| "I'll test after writing" | That's not TDD. RED comes before GREEN. Delete and start over. |
+| "Description can summarize the workflow" | Claude follows descriptions instead of reading skills. Never summarize. |
+
+---
+
+## Red Flags - STOP
+
+- Creating SKILL.md before RED phase subagent completes
+- Skipping baseline test for ANY skill type
+- "I already know what will fail" without running subagent
+- Description summarizes workflow ("scans X, extracts Y, outputs Z")
+- **Missing `triggers:` in frontmatter** — skill won't be auto-invoked
+- Missing "When to Use" section
+- No Quick Reference table
+- "I'll test it later"
+- Skill over 500 lines without supporting files
+- Proceeding to Phase 4 without Phase 3 subagent verification
+
+**All of these mean: STOP. Go back to the phase you skipped.**
+
+---
+
+## Supporting Files
+
+When to create separate files:
+
+| Content | Threshold | File |
+|---------|-----------|------|
+| Heavy reference | >100 lines | `reference.md` |
+| Detailed examples | >50 lines | `examples.md` |
+| Testing protocol | Discipline skills | `testing-protocol.md` |
+
+---
+
+## Cross-Reference
+
+**Required reading:** Read `kernel/knowledge/skill-authoring-guide.md` for comprehensive best practices.
+
+This skill is a lightweight enforcement layer. The guide has the full theory and examples.
+
+---
+
+*Skill Generator v2.0 | Part of Thoth Knowledge Management System*
+
+---
+
+## Quick Reference: The Phases
+
+| Phase | Name | Action | Gate |
+|-------|------|--------|------|
+| 0 | Setup | Check exists, classify type, research domain | — |
+| 1 | RED | Dispatch subagent WITHOUT skill, document failure | Must have documented failure |
+| 2 | GREEN | Write minimal skill addressing failures | — |
+| 3 | GREEN | Dispatch subagent WITH skill, verify fix | Must pass |
+| 4 | REFACTOR | Close loopholes, quality checks | All checks pass |

package/dist/defaults/skill/_legacy/skill-generator/testing-protocol.md

@@ -0,0 +1,158 @@
+# Testing Protocol for Skills
+
+When and how to test skills before deployment.
+
+---
+
+## Testing by Skill Type
+
+| Skill Type | Testing Required | Method |
+|------------|------------------|--------|
+| **Discipline** | Mandatory | Subagent pressure test |
+| **Workflow** | Recommended | Manual walkthrough |
+| **Technique** | Recommended | Clarity check |
+| **Reference** | Optional | Retrieval test |
+
+---
+
+## Discipline Skills: Subagent Pressure Test
+
+Discipline skills enforce rules that agents will try to rationalize around. Test with a fresh agent that doesn't have the skill loaded.
+
+### Step 1: Create Pressure Scenario
+
+Combine multiple pressures:
+
+| Pressure Type | Example |
+|---------------|---------|
+| **Time** | "We need this done in 5 minutes" |
+| **Sunk cost** | "I already wrote the code, just need to add tests" |
+| **Authority** | "The user said to skip testing" |
+| **Exhaustion** | "This is the 10th file, let's just finish" |
+| **Simplicity** | "This is too simple to need the full process" |
+
+### Step 2: Run Baseline (Without Skill)
+
+Dispatch a subagent with the pressure scenario but WITHOUT the skill in context.
+
+```
+Task: "Implement feature X. We're short on time, so skip anything unnecessary."
+```
+
+Document:
+- What did the agent skip?
+- What rationalizations were used (verbatim)?
+- What rules were violated?
+
+### Step 3: Run With Skill
+
+Same scenario, but WITH the skill loaded.
+
+Document:
+- Did the agent follow the rules?
+- Any new rationalizations that bypassed the skill?
+- Any ambiguities in the skill that allowed violations?
+
+### Step 4: Close Loopholes
+
+For each new rationalization found:
+1. Add explicit counter to Rationalization Table
+2. Add to Red Flags section
+3. Re-test until bulletproof
+
+---
+
+## Workflow Skills: Manual Walkthrough
+
+### Process
+
+1. Read the skill as if you've never seen it
+2. Follow each step literally
+3. Note any ambiguities or missing information
+4. Verify all referenced tools/files exist
+
+### Checklist
+
+- [ ] Each step is actionable (not vague)
+- [ ] Order of steps is logical
+- [ ] No missing prerequisites
+- [ ] Error cases are handled
+- [ ] Verification points are clear
+
+---
+
+## Technique Skills: Clarity Check
+
+### Process
+
+1. Give the skill to a fresh context (new session)
+2. Ask: "Follow this skill to do X"
+3. Observe if the agent can complete the task
+
+### Checklist
+
+- [ ] Instructions are unambiguous
+- [ ] Examples are complete and runnable
+- [ ] Common mistakes section covers real issues
+- [ ] Quick Reference is sufficient for repeat use
+
+---
+
+## Reference Skills: Retrieval Test
+
+### Process
+
+1. Ask questions that should be answered by the skill
+2. Verify the agent finds the right information
+3. Check for gaps in coverage
+
+### Example Questions
+
+- "How do I do X?" → Should find the relevant section
+- "What's the syntax for Y?" → Should find exact syntax
+- "What are the options for Z?" → Should list all options
+
+---
+
+## When to Skip Testing
+
+**Never skip for discipline skills.**
+
+For other types, you may skip if:
+- Skill is trivial (<50 lines)
+- Skill is internal documentation only
+- Time-critical AND low-risk
+
+But document why you skipped:
+```markdown
+## Testing
+
+Skipped: Technique skill under 50 lines, low complexity.
+```
+
+---
+
+## Subagent Dispatch Template
+
+For discipline skill testing:
+
+```
+Task: [Describe the scenario with pressure]
+
+Context: You are implementing [feature]. 
+Pressure: [Time/sunk cost/authority pressure]
+
+Do NOT load any skills. Just complete the task as you normally would.
+
+Report: What steps did you take? What did you skip and why?
+```
+
+After baseline, re-run with:
+
+```
+Task: [Same scenario]
+
+REQUIRED SKILL: Use skill-generator (or the skill being tested)
+
+Report: What steps did you take? Did you follow the skill completely?
+```

package/dist/defaults/skill/_legacy/system-init/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: system-init
+description: Onboarding wizard that interviews the user to populate the Thoth knowledge base and configure the environment.
+---
+
+# System Initialization Skill
+
+You are the **Onboarding Agent**. Your goal is to interview the user to populate Thoth's "Ground Truth" knowledge base and configure the environment.
+
+## Protocol Execution
+
+### Step 0: Welcome & Explain
+
+Introduce yourself:
+> "I'm Thoth, your AI chief of staff. Before I can help you effectively, I need to learn about you. This onboarding will take about 10-15 minutes and will set up your personal knowledge base.
+>
+> I'll ask about:
+> 1. Your work identity (role, projects, stakeholders)
+> 2. Your personal life (health, relationships, values)
+> 3. Technical setup verification
+>
+> Ready to begin?"
+
+### Step 1: Work Identity (The Chief of Staff)
+
+1. **Ask**: "Who are you professionally? (Role, Title, Company/Organization)"
+
+2. **Ask**: "What are your Top 3 Active Projects right now? For each, tell me:
+   - Project name
+   - Your role in it
+   - Current status (planning/active/wrapping up)
+   - Key deadline if any"
+
+3. **Ask**: "Who are your Top 3 Key Stakeholders? (People you report to, collaborate with closely, or manage)"
+
+4. **Action**:
+   - Create `work/identity/me.md` with professional profile
+   - Create `work/projects/{project}.md` for each project using `kernel/templates/project.md`
+   - Create `work/people/{name}.md` for each stakeholder using `kernel/templates/person.md`
+   - Update `work/MASTER.md` with project overview
+
+### Step 2: Personal Identity (The Life Coach)
+
+You are now the **Biographer**. Interview the user to build the "Life Map."
+
+**Biology (Health & Energy)**
+1. **Ask**: "How do you track your health? Do you have any current health goals? (Sleep, Exercise, Nutrition)"
+2. **Action**: Create `life/areas/health.md`
+
+**Wealth (Admin & Environment)**
+3. **Ask**: "Tell me about your life infrastructure. Living situation? Pets? What are the big 'Life Admin' buckets you manage?"
+4. **Action**: Create `life/areas/admin.md`
+
+**Community (The Village)**
+5. **Ask**: "Who are the key people in your private life? (Partner, Family, Close Friends). I'll create profiles to track important moments."
+6. **Action**: Create `life/people/{name}.md` for each person
+
+**Psychology (Values & Meaning)**
+7. **Ask**: "What are your core values? What does a 'Good Life' look like for you this year?"
+8. **Action**: Create `life/identity/values.md`
+
+### Step 3: Trust Level Setup
+
+Explain the trust system:
+> "Thoth uses a trust-based permission system. You start at Level 1 (Observer mode) where I can read but not write. As we work together successfully, I'll earn higher trust levels.
+>
+> - **Level 1**: Read-only, no external actions
+> - **Level 2**: Can write to knowledge base, access email/calendar
+> - **Level 3**: Full autonomy within your defined boundaries"
+
+**Ask**: "Would you like to start at Level 1 (safest) or Level 2 (more capable)?"
+
+**Action**: Update `kernel/state/trust.md` with initial level.
+
+### Step 4: Technical Verification
+
+1. **Check**: Can we read `kernel/THOTH.md`?
+2. **Check**: Is the Google Workspace MCP responding? (Test with `google-workspace_list_calendars`)
+3. **Check**: Is Slack MCP responding? (Test with `slack_channels_list`)
+4. **Report**: List which integrations are available.
+
+### Step 5: Finalize
+
+1. **Summarize** what was created:
+   - Number of project files
+   - Number of people profiles
+   - Life areas configured
+   - Trust level set
+
+2. **Suggest Next Steps**:
+   - "Run `skill(morning-boot)` tomorrow morning to start your first daily log"
+   - "Use `skill(thought-router)` for quick capture throughout the day"
+
+3. **Output**: "System Initialization Complete. Thoth is ready to serve."
+
+---
+
+## Technical Constraints
+
+- **Conversational**: This is an interview, not a form. Be warm and curious.
+- **Incremental Saves**: Save each section as you complete it, don't wait until the end.
+- **Templates**: Use templates from `kernel/templates/` for consistency.
+- **Trust Level**: This skill can run at Level 1 (creates files in knowledge base).

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

@@ -1,13 +1,12 @@
 ---
 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:
-  - end of day
-  - close out
-  - wrap up the day
-  - evening summary
-  - what did I accomplish
-  - end my day
+triggers: 
+output: 
+type: markdown
+created: 2026-01-09
+updated: 2026-01-09
 ---
 
 # Evening Close Skill

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

@@ -1,13 +1,16 @@
 ---
 name: mail-triage
-description: Exhaustive Gmail inbox triage using the Thoth standard protocol. Drains ALL inbox items and returns an executive dashboard.
-triggers:
-  - check my email
-  - email triage
-  - process inbox
-  - what's in my inbox
-  - scan my email
-  - any important emails
+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