codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/writing-skills/references/standards/README.md

@@ -0,0 +1,152 @@
+---
+description: Standards and naming rules for creating agent skills.
+metadata:
+  tags: [standards, naming, yaml, structure]
+---
+
+# Skill Development Guide
+
+Comprehensive reference for creating effective agent skills.
+
+## Directory Structure
+
+```
+~/.config/opencode/skills/
+  {skill-name}/           # kebab-case, matches `name` field
+    SKILL.md              # Required: main skill definition
+    references/           # Optional: supporting documentation
+      README.md           # Sub-topic entry point
+      *.md                # Additional files
+```
+
+**Project-local alternative:**
+```
+.agent/skills/{skill-name}/SKILL.md
+```
+
+## Naming Rules
+
+| Element | Rule | Example |
+|---------|------|---------|
+| Directory | kebab-case, 1-64 chars | `react-best-practices` |
+| `SKILL.md` | ALL CAPS, exact filename | `SKILL.md` (not `skill.md`) |
+| `name` field | Must match directory name | `name: react-best-practices` |
+
+## SKILL.md Structure
+
+```markdown
+---
+name: {skill-name}
+description: >-
+  Use when [trigger condition].
+metadata:
+  category: technique
+  triggers: keyword1, keyword2, error-text
+---
+
+# Skill Title
+
+Brief description of what this skill does.
+
+## When to Use
+
+- Symptom or situation A
+- Symptom or situation B
+
+## How It Works
+
+Step-by-step instructions or reference content.
+
+## Examples
+
+Concrete usage examples.
+
+## Common Mistakes
+
+What to avoid and why.
+```
+
+## Description Best Practices
+
+The `description` field is critical for skill discovery:
+
+```yaml
+# ❌ BAD: Workflow summary (agent skips reading full skill)
+description: Analyzes code, finds bugs, suggests fixes
+
+# ✅ GOOD: Trigger conditions only
+description: Use when debugging errors or reviewing code quality.
+metadata:
+  triggers: bug, error, code review
+```
+
+**Rules:**
+- Start with "Use when..."
+- Put triggers under `metadata.triggers`
+- Keep under 500 characters
+- Use third person (not "I" or "You")
+
+## Context Efficiency
+
+Skills load into context on-demand. Optimize for token usage:
+
+| Guideline | Reason |
+|-----------|--------|
+| Keep SKILL.md < 500 lines | Reduces context consumption |
+| Put details in supporting files | Agent reads only what's needed |
+| Use tables for reference data | More compact than prose |
+| Link to `--help` for CLI tools | Avoids duplicating docs |
+
+## Supporting Files
+
+For complex skills, use additional files:
+
+```
+my-skill/
+  SKILL.md              # Overview + navigation
+  patterns.md           # Detailed patterns
+  examples.md           # Code examples
+  troubleshooting.md    # Common issues
+```
+
+**Supporting file frontmatter is required** (for any `.md` besides `SKILL.md`):
+
+```markdown
+---
+description: >-
+  Short summary used for search and retrieval.
+metadata:
+  tags: [pattern, troubleshooting, api]
+  source: internal
+---
+```
+
+This frontmatter helps the LLM locate the right file when referenced from `SKILL.md`.
+
+Reference from SKILL.md:
+```markdown
+## Detailed Reference
+
+- Patterns - Common usage patterns
+- Examples - Code samples
+```
+
+## Skill Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| **Reference** | Documentation, APIs | `bigquery-analysis` |
+| **Technique** | How-to guides | `condition-based-waiting` |
+| **Pattern** | Mental models | `flatten-with-flags` |
+| **Discipline** | Rules to enforce | `test-driven-development` |
+
+## Verification Checklist
+
+Before deploying:
+
+- [ ] `name` matches directory name?
+- [ ] `SKILL.md` is ALL CAPS?
+- [ ] Description starts with "Use when..."?
+- [ ] Triggers listed under metadata?
+- [ ] Under 500 lines?
+- [ ] Tested with real scenarios?

package/templates/.agent/skills/writing-skills/references/standards/metadata-standard.md

@@ -0,0 +1,65 @@
+# SKILL.md Metadata Standard
+
+Official frontmatter fields recognized by OpenCode.
+
+## Required Fields
+
+```yaml
+---
+name: skill-name
+description: >-
+  Use when [trigger condition].
+metadata:
+  triggers: keyword1, keyword2, error-message
+---
+```
+
+| Field | Rules |
+|-------|-------|
+| `name` | 1-64 chars, lowercase, hyphens only, must match directory name |
+| `description` | 1-1024 chars, should describe when to use |
+
+## Optional Fields
+
+```yaml
+---
+name: skill-name
+description: Purpose and triggers.
+metadata:
+  license: MIT
+  compatibility: opencode
+  author: "your-name"
+  version: "1.0.0"
+  category: "reference"
+  tags: "tag1, tag2"
+---
+```
+
+| Field | Purpose |
+|-------|---------|
+| `license` | License identifier (e.g., MIT, Apache-2.0) |
+| `compatibility` | Tool compatibility marker |
+| `metadata` | String-to-string map for custom key-values |
+
+## Name Validation
+
+```regex
+^[a-z0-9]+(-[a-z0-9]+)*$
+```
+
+**Valid**: `my-skill`, `git-release`, `tdd`  
+**Invalid**: `My-Skill`, `my_skill`, `-my-skill`, `my--skill`
+
+## Common Metadata Keys
+
+Use these conventions for consistency across skills:
+
+| Key | Example | Purpose |
+|-----|---------|---------|
+| `author` | `"your-name"` | Skill creator |
+| `version` | `"1.0.0"` | Semantic version |
+| `category` | `"reference"` | Type: reference, technique, discipline, pattern |
+| `tags` | `"react, hooks"` | Searchable keywords |
+
+> [!IMPORTANT]
+> Any field not listed here is **ignored** by OpenCode's skill loader.

package/templates/.agent/skills/writing-skills/references/templates/discipline.md

@@ -0,0 +1,54 @@
+---
+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.

package/templates/.agent/skills/writing-skills/references/templates/pattern.md

@@ -0,0 +1,48 @@
+---
+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]

package/templates/.agent/skills/writing-skills/references/templates/reference.md

@@ -0,0 +1,35 @@
+---
+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

package/templates/.agent/skills/writing-skills/references/templates/technique.md

@@ -0,0 +1,59 @@
+---
+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`

package/templates/.agent/skills/writing-skills/references/templates/tier-3-platform.md

@@ -0,0 +1,19 @@
+# Platform Name Skill
+
+Template for complex Tier 3 skills.
+
+## Structure
+
+```
+skill/
+├── SKILL.md            # Dispatcher
+├── commands/
+│   └── skill.md        # Orchestrator
+└── references/
+    └── topic/
+        ├── README.md   # Overview
+        ├── api.md      # API Reference
+        ├── config.md   # Configuration
+        ├── patterns.md # Recipes
+        └── gotchas.md  # Critical Errors
+```

package/templates/.agent/skills/writing-skills/references/testing/README.md

@@ -0,0 +1,204 @@
+# Testing Guide - TDD for Skills
+
+Complete methodology for testing skills using RED-GREEN-REFACTOR cycle.
+
+## Testing All Skill Types
+
+Different skill types need different test approaches.
+
+### Discipline-Enforcing Skills (rules/requirements)
+
+**Examples**: TDD, verification-before-completion, designing-before-coding
+
+**Test with**:
+
+- Academic questions: Do they understand the rules?
+- Pressure scenarios: Do they comply under stress?
+- Multiple pressures combined: time + sunk cost + exhaustion
+- Identify rationalizations and add explicit counters
+
+**Success criteria**: Agent follows rule under maximum pressure
+
+### Technique Skills (how-to guides)
+
+**Examples**: condition-based-waiting, root-cause-tracing, defensive-programming
+
+**Test with**:
+
+- Application scenarios: Can they apply the technique correctly?
+- Variation scenarios: Do they handle edge cases?
+- Missing information tests: Do instructions have gaps?
+
+**Success criteria**: Agent successfully applies technique to new scenario
+
+### Pattern Skills (mental models)
+
+**Examples**: reducing-complexity, information-hiding concepts
+
+**Test with**:
+
+- Recognition scenarios: Do they recognize when pattern applies?
+- Application scenarios: Can they use the mental model?
+- Counter-examples: Do they know when NOT to apply?
+
+**Success criteria**: Agent correctly identifies when/how to apply pattern
+
+### Reference Skills (documentation/APIs)
+
+**Examples**: API documentation, command references, library guides
+
+**Test with**:
+
+- Retrieval scenarios: Can they find the right information?
+- Application scenarios: Can they use what they found correctly?
+- Gap testing: Are common use cases covered?
+
+**Success criteria**: Agent finds and correctly applies reference information
+
+## Pressure Types for Testing
+
+### Time Pressure
+
+"You have 5 minutes to complete this task"
+
+### Sunk Cost Pressure
+
+"You already spent 2 hours on this, just finish it quickly"
+
+### Authority Pressure
+
+"The senior developer said to skip tests for this quick bug fix"
+
+### Exhaustion Pressure
+
+"This is the 10th task today, let's wrap it up"
+
+## RED Phase: Baseline Testing
+
+**Goal**: Watch the agent fail WITHOUT the skill.
+
+**Steps**:
+
+1. Design pressure scenario (combine 2-3 pressures)
+2. Give agent the task WITHOUT the skill loaded
+3. Document EXACT behavior:
+   - What rationalization did they use?
+   - Which pressure triggered the violation?
+   - How did they justify the shortcut?
+
+**Critical**: Copy exact quotes. You'll need them for GREEN phase.
+
+**Example Baseline**:
+
+```
+Scenario: Implement feature under time pressure
+Pressure: "You have 10 minutes"
+Agent response: "Since we're short on time, I'll implement the feature first
+and add tests after. Testing later achieves the same goal."
+```
+
+## GREEN Phase: Minimal Implementation
+
+**Goal**: Write skill that addresses SPECIFIC baseline failures.
+
+**Steps**:
+
+1. Review baseline rationalizations
+2. Write skill sections that counter THOSE EXACT arguments
+3. Re-run scenario WITH skill
+4. Agent should now comply
+
+**Bad (too general)**:
+
+```markdown
+## Testing
+
+Always write tests.
+```
+
+**Good (addresses specific rationalization)**:
+
+```markdown
+## Common Rationalizations
+
+| Excuse                              | Reality                                                                 |
+| ----------------------------------- | ----------------------------------------------------------------------- |
+| "Testing after achieves same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+| "Too simple to test"                | Simple code breaks. Test takes 30 seconds.                              |
+```
+
+## REFACTOR Phase: Loophole Closing
+
+**Goal**: Find and plug new rationalizations.
+
+**Steps**:
+
+1. Agent found new workaround? Document it.
+2. Add explicit counter to skill
+3. Re-test same scenario
+4. Repeat until bulletproof
+
+**Pattern**:
+
+```markdown
+## Red Flags - STOP and Start Over
+
+- Code before test
+- "I already manually tested it"
+- "Tests after achieve the same purpose"
+- "It's about spirit not ritual"
+- "This is different because..."
+
+**All of these mean**: Delete code. Start over with TDD.
+```
+
+## Complete Test Checklist
+
+Before deploying a skill:
+
+**Baseline (RED)**:
+
+- [ ] Designed 3+ pressure scenarios
+- [ ] Ran scenarios WITHOUT skill
+- [ ] Documented verbatim agent responses
+- [ ] Identified pattern in rationalizations
+
+**Implementation (GREEN)**:
+
+- [ ] Skill addresses SPECIFIC baseline failures
+- [ ] Re-ran scenarios WITH skill
+- [ ] Agent complied in all scenarios
+- [ ] No hand-waving or generic advice
+
+**Bulletproofing (REFACTOR)**:
+
+- [ ] Tested with combined pressures
+- [ ] Found and documented new rationalizations
+- [ ] Added explicit counters
+- [ ] Re-tested until no more loopholes
+- [ ] Created "Red Flags" section
+
+## Common Testing Mistakes
+
+| Mistake                        | Fix                                                       |
+| ------------------------------ | --------------------------------------------------------- |
+| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. |
+| "Skill is obviously clear"     | Clear to you ≠ clear to agents. Test it.                  |
+| "Testing is overkill"          | Untested skills have issues. Always.                      |
+| "Academic review is enough"    | Reading ≠ using. Test application scenarios.              |
+
+## Meta-Testing
+
+**Test the test**: If agent passes too easily, your test is weak.
+
+**Good test indicators**:
+
+- Agent fails WITHOUT skill (proves skill is needed)
+- Agent p asses WITH skill (proves skill works)
+- Multiple pressures needed to trigger failure (proves realistic)
+
+**Bad test indicators**:
+
+- Agent passes even without skill (test is irrelevant)
+- Agent fails even with skill (skill is unclear)
+- Single obvious scenario (test is too simple)

package/templates/.agent/skills/writing-skills/references/tier-1-simple/README.md

@@ -0,0 +1,75 @@
+---
+description: When to use Tier 1 (Simple) skill architecture.
+metadata:
+  tags: [tier-1, simple, single-file]
+---
+
+# Tier 1: Simple Skills
+
+Single-file skills for focused, specific purposes.
+
+## When to Use
+
+- **Single concept**: One technique, one pattern, one reference
+- **Under 200 lines**: Can fit comfortably in one file
+- **No complex decision logic**: User knows exactly what they need
+- **Frequently loaded**: Needs minimal token footprint
+
+## Structure
+
+```
+my-skill/
+└── SKILL.md          # Everything in one file
+```
+
+## Example
+
+```yaml
+---
+name: flatten-with-flags
+description: Use when simplifying deeply nested conditionals.
+metadata:
+  category: pattern
+  triggers: nested if, complex conditionals, early return
+---
+
+# Flatten with Flags
+
+## When to Use
+- Code has 3+ levels of nesting
+- Conditions are hard to follow
+
+## The Pattern
+Replace nested conditions with early returns and flag variables.
+
+## Before
+```javascript
+function process(data) {
+  if (data) {
+    if (data.valid) {
+      if (data.ready) {
+        return doWork(data);
+      }
+    }
+  }
+  return null;
+}
+```
+
+## After
+```javascript
+function process(data) {
+  if (!data) return null;
+  if (!data.valid) return null;
+  if (!data.ready) return null;
+  return doWork(data);
+}
+```
+```
+
+## Checklist
+
+- [ ] Fits in <200 lines
+- [ ] Single focused purpose
+- [ ] No need for `references/` directory
+- [ ] Description uses "Use when..." pattern