codehava-agent-kit 1.0.1 → 2.0.0

package/templates/.agent/skills/writing-skills/examples.md

@@ -0,0 +1,282 @@
+# Skill Templates & Examples
+
+Complete, copy-paste templates for each skill type.
+
+---
+
+## Template: Technique Skill
+
+For how-to guides that teach a specific method.
+
+```markdown
+---
+name: technique-name
+description: >-
+  Use when [specific symptom].
+metadata:
+  category: technique
+  triggers: error-text, symptom, tool-name
+---
+
+# Technique Name
+
+## Overview
+
+[1-2 sentence core principle]
+
+## When to Use
+
+- [Symptom A]
+- [Symptom B]
+- [Error message text]
+
+**NOT for:**
+- [When to avoid]
+
+## The Problem
+
+```javascript
+// Bad example
+function badCode() {
+  // problematic pattern
+}
+```
+
+## The Solution
+
+```javascript
+// Good example
+function goodCode() {
+  // improved pattern
+}
+```
+
+## Step-by-Step
+
+1. [First step]
+2. [Second step]
+3. [Final step]
+
+## Quick Reference
+
+| Scenario | Approach |
+|----------|----------|
+| Case A | Solution A |
+| Case B | Solution B |
+
+## Common Mistakes
+
+**Mistake 1:** [Description]
+- Wrong: `bad code`
+- Right: `good code`
+```
+
+---
+
+## Template: Reference Skill
+
+For documentation, APIs, and lookup tables.
+
+```markdown
+---
+name: reference-name
+description: >-
+  Use when working with [domain].
+metadata:
+  category: reference
+  triggers: tool, api, specific-terms
+---
+
+# Reference Name
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `cmd1` | Does X |
+| `cmd2` | Does Y |
+
+## Common Patterns
+
+**Pattern A:**
+```bash
+example command
+```
+
+**Pattern B:**
+```bash
+another example
+```
+
+## Detailed Docs
+
+For more options, run `--help` or see:
+- patterns.md
+- [examples.md](examples.md)
+```
+
+---
+
+## Template: Discipline Skill
+
+For rules that agents must follow. Requires anti-rationalization techniques.
+
+```markdown
+---
+name: discipline-name
+description: >-
+  Use when [BEFORE violation].
+metadata:
+  category: discipline
+  triggers: new feature, code change, implementation
+---
+
+# Rule Name
+
+## Iron Law
+
+**[SINGLE SENTENCE ABSOLUTE RULE]**
+
+Violating the letter IS violating the spirit.
+
+## The Rule
+
+1. ALWAYS [step 1]
+2. NEVER [step 2]
+3. [Step 3]
+
+## Violations
+
+[Action before rule]? **Delete it. Start over.**
+
+**No exceptions:**
+- Don't keep it as "reference"
+- Don't "adapt" it
+- Delete means delete
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple" | Simple code breaks. Rule takes 30 seconds. |
+| "I'll do it after" | After = never. Do it now. |
+| "Spirit not ritual" | The ritual IS the spirit. |
+
+## Red Flags - STOP
+
+- [Flag 1]
+- [Flag 2]
+- "This is different because..."
+
+**All mean:** Delete. Start over.
+
+## Valid Exceptions
+
+- [Exception 1]
+- [Exception 2]
+
+**Everything else:** Follow the rule.
+```
+
+---
+
+## Template: Pattern Skill
+
+For mental models and design patterns.
+
+```markdown
+---
+name: pattern-name
+description: >-
+  Use when [recognizable symptom].
+metadata:
+  category: pattern
+  triggers: complexity, hard-to-follow, nested
+---
+
+# Pattern Name
+
+## The Pattern
+
+[1-2 sentence core idea]
+
+## Recognition Signs
+
+- [Sign that pattern applies]
+- [Another sign]
+- [Code smell]
+
+## Before
+
+```typescript
+// Complex/problematic
+function before() {
+  // nested, confusing
+}
+```
+
+## After
+
+```typescript
+// Clean/improved
+function after() {
+  // flat, clear
+}
+```
+
+## When NOT to Use
+
+- [Over-engineering case]
+- [Simple case that doesn't need it]
+
+## Impact
+
+**Before:** [Problem metric]
+**After:** [Improved metric]
+```
+
+---
+
+## Real Example: Condition-Based Waiting
+
+```yaml
+---
+name: condition-based-waiting
+description: >-
+  Use when tests have race conditions or timing dependencies.
+metadata:
+  category: technique
+  triggers: flaky tests, timeout, race condition, sleep, setTimeout
+---
+```
+
+```markdown
+# Condition-Based Waiting
+
+## Overview
+
+Replace `sleep(ms)` with `waitFor(() => condition)`.
+
+## When to Use
+
+- Tests pass sometimes, fail other times
+- Tests use `sleep()` or `setTimeout()`
+- "Works on my machine"
+
+## The Fix
+
+```typescript
+// ❌ Bad
+await sleep(2000);
+expect(element).toBeVisible();
+
+// ✅ Good
+await waitFor(() => element.isVisible(), { timeout: 5000 });
+expect(element).toBeVisible();
+```
+
+## Impact
+
+- Flaky tests: 15/100 → 0/100
+- Speed: 40% faster (no over-waiting)
+```

package/templates/.agent/skills/writing-skills/gotchas.md

@@ -0,0 +1,197 @@
+---
+description: Common pitfalls and tribal knowledge for skill creation.
+metadata:
+  tags: [gotchas, troubleshooting, mistakes]
+---
+
+# Skill Writing Gotchas
+
+Tribal knowledge to avoid common mistakes.
+
+## YAML Frontmatter
+
+### Invalid Syntax
+
+```yaml
+# ❌ BAD: Mixed list and map
+metadata:
+  references: 
+  triggers: a, b, c
+  - item1
+  - item2
+
+# ✅ GOOD: Consistent structure
+metadata:
+  triggers: a, b, c
+  references:
+    - item1
+    - item2
+```
+
+### Multiline Description
+
+```yaml
+# ❌ BAD: Line breaks create parsing errors
+description: Use when creating skills.
+  Also for updating.
+
+# ✅ GOOD: Use YAML multiline syntax
+description: >-
+  Use when creating or updating skills.
+  Triggers: new skill, update skill
+```
+
+## Naming
+
+### Directory Must Match `name` Field
+
+```
+# ❌ BAD
+directory: my-skill/
+name: mySkill  # Mismatch!
+
+# ✅ GOOD
+directory: my-skill/
+name: my-skill  # Exact match
+```
+
+### SKILL.md Must Be ALL CAPS
+
+```
+# ❌ BAD
+skill.md
+Skill.md
+
+# ✅ GOOD
+SKILL.md
+```
+
+## Discovery
+
+### Description = Triggers, NOT Workflow
+
+```yaml
+# ❌ BAD: Agent reads this and skips the full skill
+description: Analyzes code, finds bugs, suggests fixes
+
+# ✅ GOOD: Agent reads full skill to understand workflow
+description: Use when debugging errors or reviewing code quality
+```
+
+### Pre-Violation Triggers for Discipline Skills
+
+```yaml
+# ❌ BAD: Triggers AFTER violation
+description: Use when you forgot to write tests
+
+# ✅ GOOD: Triggers BEFORE violation
+description: Use when implementing any feature, before writing code
+```
+
+## Token Efficiency
+
+### Skill Loaded Every Conversation = Token Drain
+
+- Frequently-loaded skills: <200 words
+- All others: <500 words
+- Move details to `references/` files
+
+### Don't Duplicate CLI Help
+
+```markdown
+# ❌ BAD: 50 lines documenting all flags
+
+# ✅ GOOD: One line
+Run `mytool --help` for all options.
+```
+
+## Anti-Rationalization (Discipline Skills Only)
+
+### Agents Are Smart at Finding Loopholes
+
+```markdown
+# ❌ BAD: Trust agents will "get the spirit"
+Write test before code.
+
+# ✅ GOOD: Close every loophole explicitly
+Write test before code.
+
+**No exceptions:**
+- Don't keep code as "reference"
+- Don't "adapt" existing code
+- Delete means delete
+```
+
+### Build Rationalization Table
+
+Every excuse from baseline testing goes in the table:
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests-after prove nothing immediately. |
+
+## Cross-References
+
+### Keep References One Level Deep
+
+```markdown
+# ❌ BAD: Nested chain (A → B → C)
+See [patterns.md] → which links to [advanced.md] → which links to [deep.md]
+
+# ✅ GOOD: Flat (A → B, A → C)
+See [patterns.md] and [advanced.md]
+```
+
+### Never Force-Load with @
+
+```markdown
+# ❌ BAD: Burns context immediately
+@skills/my-skill/SKILL.md
+
+# ✅ GOOD: Agent loads when needed
+See [my-skill] for details.
+```
+
+## OpenCode Integration
+
+### Correct Skill Directory
+
+```bash
+# ❌ BAD: Old singular path
+~/.config/opencode/skill/my-skill/
+
+# ✅ GOOD: Plural path
+~/.config/opencode/skills/my-skill/
+```
+
+### Skill Cross-Reference Syntax
+
+```markdown
+# ❌ BAD: File path (fragile)
+See /home/user/.config/opencode/skills/my-skill/SKILL.md
+
+# ✅ GOOD: Skill protocol
+See my-skill
+```
+
+## Tier Selection
+
+### Don't Overthink Tier Choice
+
+```markdown
+# ❌ BAD: Starting with Tier 3 "just in case"
+# Result: Wasted effort, empty reference files
+
+# ✅ GOOD: Start with Tier 1, upgrade when needed
+# Can always add references/ later
+```
+
+### Signals You Need to Upgrade
+
+| Signal | Action |
+|--------|--------|
+| SKILL.md > 200 lines | → Tier 2 |
+| 3+ related sub-topics | → Tier 2 |
+| 10+ products/services | → Tier 3 |
+| "I need X" vs "I want Y" | → Tier 3 decision trees |

package/templates/.agent/skills/writing-skills/graphviz-conventions.dot

@@ -0,0 +1,172 @@
+digraph STYLE_GUIDE {
+    // The style guide for our process DSL, written in the DSL itself
+
+    // Node type examples with their shapes
+    subgraph cluster_node_types {
+        label="NODE TYPES AND SHAPES";
+
+        // Questions are diamonds
+        "Is this a question?" [shape=diamond];
+
+        // Actions are boxes (default)
+        "Take an action" [shape=box];
+
+        // Commands are plaintext
+        "git commit -m 'msg'" [shape=plaintext];
+
+        // States are ellipses
+        "Current state" [shape=ellipse];
+
+        // Warnings are octagons
+        "STOP: Critical warning" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+        // Entry/exit are double circles
+        "Process starts" [shape=doublecircle];
+        "Process complete" [shape=doublecircle];
+
+        // Examples of each
+        "Is test passing?" [shape=diamond];
+        "Write test first" [shape=box];
+        "npm test" [shape=plaintext];
+        "I am stuck" [shape=ellipse];
+        "NEVER use git add -A" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+    }
+
+    // Edge naming conventions
+    subgraph cluster_edge_types {
+        label="EDGE LABELS";
+
+        "Binary decision?" [shape=diamond];
+        "Yes path" [shape=box];
+        "No path" [shape=box];
+
+        "Binary decision?" -> "Yes path" [label="yes"];
+        "Binary decision?" -> "No path" [label="no"];
+
+        "Multiple choice?" [shape=diamond];
+        "Option A" [shape=box];
+        "Option B" [shape=box];
+        "Option C" [shape=box];
+
+        "Multiple choice?" -> "Option A" [label="condition A"];
+        "Multiple choice?" -> "Option B" [label="condition B"];
+        "Multiple choice?" -> "Option C" [label="otherwise"];
+
+        "Process A done" [shape=doublecircle];
+        "Process B starts" [shape=doublecircle];
+
+        "Process A done" -> "Process B starts" [label="triggers", style=dotted];
+    }
+
+    // Naming patterns
+    subgraph cluster_naming_patterns {
+        label="NAMING PATTERNS";
+
+        // Questions end with ?
+        "Should I do X?";
+        "Can this be Y?";
+        "Is Z true?";
+        "Have I done W?";
+
+        // Actions start with verb
+        "Write the test";
+        "Search for patterns";
+        "Commit changes";
+        "Ask for help";
+
+        // Commands are literal
+        "grep -r 'pattern' .";
+        "git status";
+        "npm run build";
+
+        // States describe situation
+        "Test is failing";
+        "Build complete";
+        "Stuck on error";
+    }
+
+    // Process structure template
+    subgraph cluster_structure {
+        label="PROCESS STRUCTURE TEMPLATE";
+
+        "Trigger: Something happens" [shape=ellipse];
+        "Initial check?" [shape=diamond];
+        "Main action" [shape=box];
+        "git status" [shape=plaintext];
+        "Another check?" [shape=diamond];
+        "Alternative action" [shape=box];
+        "STOP: Don't do this" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+        "Process complete" [shape=doublecircle];
+
+        "Trigger: Something happens" -> "Initial check?";
+        "Initial check?" -> "Main action" [label="yes"];
+        "Initial check?" -> "Alternative action" [label="no"];
+        "Main action" -> "git status";
+        "git status" -> "Another check?";
+        "Another check?" -> "Process complete" [label="ok"];
+        "Another check?" -> "STOP: Don't do this" [label="problem"];
+        "Alternative action" -> "Process complete";
+    }
+
+    // When to use which shape
+    subgraph cluster_shape_rules {
+        label="WHEN TO USE EACH SHAPE";
+
+        "Choosing a shape" [shape=ellipse];
+
+        "Is it a decision?" [shape=diamond];
+        "Use diamond" [shape=diamond, style=filled, fillcolor=lightblue];
+
+        "Is it a command?" [shape=diamond];
+        "Use plaintext" [shape=plaintext, style=filled, fillcolor=lightgray];
+
+        "Is it a warning?" [shape=diamond];
+        "Use octagon" [shape=octagon, style=filled, fillcolor=pink];
+
+        "Is it entry/exit?" [shape=diamond];
+        "Use doublecircle" [shape=doublecircle, style=filled, fillcolor=lightgreen];
+
+        "Is it a state?" [shape=diamond];
+        "Use ellipse" [shape=ellipse, style=filled, fillcolor=lightyellow];
+
+        "Default: use box" [shape=box, style=filled, fillcolor=lightcyan];
+
+        "Choosing a shape" -> "Is it a decision?";
+        "Is it a decision?" -> "Use diamond" [label="yes"];
+        "Is it a decision?" -> "Is it a command?" [label="no"];
+        "Is it a command?" -> "Use plaintext" [label="yes"];
+        "Is it a command?" -> "Is it a warning?" [label="no"];
+        "Is it a warning?" -> "Use octagon" [label="yes"];
+        "Is it a warning?" -> "Is it entry/exit?" [label="no"];
+        "Is it entry/exit?" -> "Use doublecircle" [label="yes"];
+        "Is it entry/exit?" -> "Is it a state?" [label="no"];
+        "Is it a state?" -> "Use ellipse" [label="yes"];
+        "Is it a state?" -> "Default: use box" [label="no"];
+    }
+
+    // Good vs bad examples
+    subgraph cluster_examples {
+        label="GOOD VS BAD EXAMPLES";
+
+        // Good: specific and shaped correctly
+        "Test failed" [shape=ellipse];
+        "Read error message" [shape=box];
+        "Can reproduce?" [shape=diamond];
+        "git diff HEAD~1" [shape=plaintext];
+        "NEVER ignore errors" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+        "Test failed" -> "Read error message";
+        "Read error message" -> "Can reproduce?";
+        "Can reproduce?" -> "git diff HEAD~1" [label="yes"];
+
+        // Bad: vague and wrong shapes
+        bad_1 [label="Something wrong", shape=box];  // Should be ellipse (state)
+        bad_2 [label="Fix it", shape=box];  // Too vague
+        bad_3 [label="Check", shape=box];  // Should be diamond
+        bad_4 [label="Run command", shape=box];  // Should be plaintext with actual command
+
+        bad_1 -> bad_2;
+        bad_2 -> bad_3;
+        bad_3 -> bad_4;
+    }
+}