@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/deep-research/SKILL.md

@@ -0,0 +1,384 @@
+---
+name: deep-research
+description: >
+  Use when analyzing unfamiliar code, implementing complex features, or entering thorough research mode.
+  Provides structured LSP exploration (all 9 operations), memory-first protocol, and confidence-scored findings.
+  Integrates with scout agent deep mode and research command --thorough flag.
+version: 1.0.0
+tags: [research, workflow]
+dependencies: []
+---
+
+# Deep Research - Comprehensive Code Understanding
+
+## When to Use
+
+- **Complex implementation**: Feature touches 3+ files or unfamiliar modules
+- **Thorough mode**: `/research <topic> --thorough` or scout deep mode
+- **Pre-edit understanding**: Before modifying code you don't fully understand
+- **Architecture exploration**: Understanding how systems connect
+- **Debugging**: Tracing behavior through multiple layers
+
+## When NOT to Use
+
+- Quick syntax lookup (use quick mode instead)
+- Well-understood code with obvious changes
+- Time-constrained fixes (accept lower confidence)
+
+## Core Protocol
+
+### Phase 1: Memory First (Skip External If Found)
+
+```typescript
+// Search past research on this topic
+memory_search({ query: "<topic keywords>", limit: 5 });
+
+// Check for related observations
+memory_search({ query: "<topic> gotchas patterns", limit: 3 });
+
+// Load relevant project context
+memory_read({ file: "project/architecture" });
+memory_read({ file: "project/gotchas" });
+```
+
+**Stop condition**: If memory returns high-confidence findings on this exact topic, synthesize and skip to documentation. Only proceed to exploration if:
+
+- No relevant memory found
+- Memory findings are outdated or incomplete
+- Question requires fresh analysis
+
+### Phase 2: LSP Exploration (Delegate to Explore Agent)
+
+**Delegate to explore agent** for comprehensive LSP analysis instead of manual operations:
+
+```typescript
+task({
+  subagent_type: "explore",
+  description: "LSP analysis of <target>",
+  prompt: `Very thorough LSP analysis of <symbol/module>.
+
+Target files:
+- src/path/to/file.ts
+- src/related/module.ts
+
+Questions to answer:
+1. What is the type signature of <symbol>?
+2. What calls this function? (incoming calls)
+3. What does this function call? (outgoing calls)
+4. Where is this symbol referenced across the codebase?
+5. Are there interface implementations to consider?
+
+Return structured findings with file:line references.`,
+});
+```
+
+The explore agent will run:
+
+- `documentSymbol` - File structure overview
+- `goToDefinition` - Symbol definitions
+- `findReferences` - All usages across codebase
+- `hover` - Type info and documentation
+- `workspaceSymbol` - Workspace-wide search
+- Call hierarchy (incoming/outgoing calls)
+
+**When to run LSP manually instead:**
+
+- Single symbol lookup (quick mode)
+- Explore agent unavailable
+- Need specific operation only
+
+### Phase 3: Pattern Discovery
+
+```typescript
+// Find similar patterns in codebase (use project's file extension: *.ts, *.py, *.rs, *.go, *.java, etc.)
+grep({ pattern: "<relevant pattern>", include: "*.<ext>" });
+
+// Locate related files
+glob({ pattern: "src/**/*<topic>*" });
+
+// Check tests for usage examples (adapt glob to project conventions)
+// JS/TS: **/*.test.ts, **/*.spec.ts  |  Python: **/test_*.py  |  Rust: **/tests/**
+// Go: **/*_test.go  |  Java: **/src/test/**/*.java
+glob({ pattern: "**/*test*" });
+grep({ pattern: "<function name>", include: "*test*" });
+```
+
+### Phase 4: External Research (If Needed)
+
+Only if internal exploration doesn't answer the question:
+
+```typescript
+// Official docs
+context7({ operation: "resolve", libraryName: "<lib>" });
+context7({ operation: "query", libraryId: "<id>", topic: "<specific question>" });
+
+// Real-world patterns (adapt language parameter to project)
+codesearch({ query: "<API usage pattern>", tokensNum: 5000 });
+grepsearch({ query: "<code pattern>", language: "<project language>" });
+```
+
+## Confidence Levels
+
+Score every finding:
+
+| Level      | Criteria                                   | Action               |
+| ---------- | ------------------------------------------ | -------------------- |
+| **High**   | LSP confirmed + tests exist + docs match   | Proceed confidently  |
+| **Medium** | LSP confirmed but untested or undocumented | Proceed with caution |
+| **Low**    | Inference only, no LSP/test confirmation   | Verify before using  |
+| **None**   | Speculation without evidence               | Discard              |
+
+## Stop Conditions
+
+Stop research when ANY of these are true:
+
+- All questions answered with Medium+ confidence
+- Tool budget exhausted (~100 calls for thorough)
+- Last 5 tool calls yielded no new insights
+- Blocked and need human input
+
+## Tool Budget Guidelines
+
+| Mode     | Tool Calls | Use Case                           |
+| -------- | ---------- | ---------------------------------- |
+| Quick    | ~10        | Single question, syntax lookup     |
+| Default  | ~30        | Moderate exploration               |
+| Thorough | ~100+      | Comprehensive analysis, new domain |
+
+Track your tool count and stop at budget.
+
+## Output Template
+
+Document findings in structured format:
+
+```markdown
+# Deep Research: [Topic]
+
+**Mode:** thorough
+**Tool calls:** [N]
+**Duration:** [time]
+
+## Questions Addressed
+
+1. [Q1] → Answered (High confidence)
+2. [Q2] → Partial (Medium confidence)
+3. [Q3] → Unanswered (needs: [what would resolve])
+
+## LSP Findings
+
+### Symbol: [name]
+
+**Location:** `src/path/file.ts:42`
+**Type:** [type signature from hover]
+
+**Callers (incoming):**
+
+- `src/a.ts:10` - [context]
+- `src/b.ts:25` - [context]
+
+**Dependencies (outgoing):**
+
+- `src/utils.ts:15` - [what it calls]
+
+**References:** [N] usages across [M] files
+
+---
+
+## Pattern Analysis
+
+### Pattern 1: [Name]
+
+**Files:** `src/a.ts`, `src/b.ts`
+**Confidence:** High
+**Evidence:** [LSP + grep findings]
+
+[Description of pattern]
+
+---
+
+## Key Findings
+
+### [Finding 1]
+
+**Confidence:** High
+**Sources:** LSP goToDefinition, findReferences
+**Evidence:** `src/file.ts:42-56`
+
+[Finding with code evidence]
+
+---
+
+## Recommendations
+
+Based on LSP analysis:
+
+1. [Recommendation 1] - because [LSP evidence]
+2. [Recommendation 2] - because [pattern found]
+
+## Open Items
+
+- [Remaining question] - needs: [specific tool/info]
+```
+
+## Integration Points
+
+### Scout Agent Deep Mode
+
+When scout enters deep mode, load this skill:
+
+```typescript
+skill({ name: "deep-research" });
+```
+
+Scout then follows the protocol for external + internal analysis.
+
+### Research Command --thorough
+
+When `/research <topic> --thorough` is invoked:
+
+```typescript
+skill({ name: "deep-research" });
+// Follow full protocol with ~100 tool budget
+```
+
+### Pre-Edit Verification
+
+Before any complex edit:
+
+```typescript
+skill({ name: "deep-research" });
+// Run Phase 2 (LSP) on all symbols being modified
+// Proceed only when all 9 operations complete
+```
+
+## Workflow Example
+
+**Scenario:** Understanding authentication middleware before adding rate limiting.
+
+```typescript
+// Phase 1: Memory check
+memory_search({ query: "authentication middleware rate limiting" });
+memory_read({ file: "project/architecture" });
+
+// Phase 2: Delegate LSP exploration to explore agent
+task({
+  subagent_type: "explore",
+  description: "Analyze auth middleware",
+  prompt: `Very thorough LSP analysis of authentication middleware.
+
+Target: src/middleware/auth.ts
+
+Questions:
+1. What functions are exported from auth.ts?
+2. What calls the auth middleware? (incoming calls)
+3. What does it depend on? (outgoing calls)
+4. Are there existing rate limiting patterns?
+
+Return file:line references for all findings.`,
+});
+
+// Phase 3: Pattern discovery (parallel with Phase 2)
+grep({ pattern: "middleware", include: "*.<ext>" });
+grep({ pattern: "rateLimit", include: "*.<ext>" });
+glob({ pattern: "src/middleware/*" });
+
+// Phase 4: External (if patterns unclear)
+context7({ operation: "resolve", libraryName: "express" });
+context7({ operation: "query", libraryId: "/expressjs/express", topic: "middleware" });
+
+// Document findings
+write({
+  filePath: ".beads/artifacts/<id>/research.md",
+  content: "# Deep Research: Auth Middleware...",
+});
+```
+
+## Anti-Patterns
+
+### DON'T: Skip LSP Exploration
+
+```typescript
+// Bad: Reading file without LSP analysis
+read({ filePath: "src/auth.ts" });
+// Then immediately editing...
+
+// Good: Delegate to explore agent first
+task({
+  subagent_type: "explore",
+  description: "Analyze auth.ts",
+  prompt: "Very thorough LSP analysis of src/auth.ts...",
+});
+// Then edit with understanding
+```
+
+### DON'T: Ignore Memory
+
+```typescript
+// Bad: Jumping straight to exploration
+grep({ pattern: "auth", include: "*.ts" });
+
+// Good: Check memory first
+memory_search({ query: "authentication patterns" });
+// Only explore if memory doesn't answer
+```
+
+### DON'T: Mix Confidence Levels
+
+```typescript
+// Bad: Treating speculation as fact
+"This function definitely handles X"; // Without LSP verification
+
+// Good: Explicit confidence
+"Based on LSP findReferences (High confidence): This function is called from...";
+"Inference (Low confidence): This might also handle X, needs verification";
+```
+
+### DON'T: Exceed Budget Without Stopping
+
+```typescript
+// Bad: 150 tool calls on thorough mode
+// Keep going indefinitely...
+
+// Good: Track and stop
+// Tool call 95: Still finding new insights, continue
+// Tool call 100: Stopping at budget, documenting partial findings
+```
+
+## Success Criteria
+
+Research is complete when:
+
+- [ ] Memory checked before exploration
+- [ ] All 9 LSP operations run on target symbols
+- [ ] Confidence scores assigned to all findings
+- [ ] Tool budget respected
+- [ ] Findings documented with evidence
+- [ ] Open items listed with resolution paths
+
+## Quick Reference
+
+```
+PROTOCOL:
+1. Memory first → skip if found
+2. Delegate LSP to @explore (very thorough)
+3. Patterns → grep + glob (parallel)
+4. External → only if needed
+
+DELEGATION:
+task({ subagent_type: "explore", prompt: "Very thorough LSP analysis..." })
+
+CONFIDENCE:
+High = LSP + tests + docs
+Medium = LSP only
+Low = inference
+None = discard
+
+BUDGET:
+quick ~10 | default ~30 | thorough ~100
+
+STOP WHEN:
+- Questions answered (Medium+)
+- Budget exhausted
+- 5 calls with no new insights
+- Blocked on human input
+```

package/dist/template/.opencode/skill/defense-in-depth/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: defense-in-depth
+description: Use when invalid data causes failures deep in execution, requiring validation at multiple system layers - validates at every layer data passes through to make bugs structurally impossible
+version: 1.0.0
+tags: [code-quality, debugging]
+dependencies: []
+---
+
+# Defense-in-Depth Validation
+
+> **Replaces** single-layer validation where bad data propagates silently until it causes cryptic failures deep in execution
+
+## When to Use
+
+- A bug is caused by invalid data flowing through multiple layers
+- One validation check is insufficient because data crosses boundaries
+
+## When NOT to Use
+
+- Simple, single-layer validation at an obvious entry point is enough
+- The issue is unrelated to invalid data or boundary checks
+
+## Common Rationalizations
+
+| Rationalization                                  | Rebuttal                                                                                                  |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| "One validation at the entry point is enough"    | Different code paths, refactors, and mocks all bypass a single gate — each layer catches what others miss |
+| "This adds too much boilerplate"                 | Each validation is 2-3 lines. The bug it prevents costs hours of debugging                                |
+| "The caller already validates this"              | You don't control the caller. New callers won't know your assumptions                                     |
+| "Tests will catch it"                            | Tests run after the fact. Validation prevents the bug from existing                                       |
+| "This is an internal function, input is trusted" | Internal functions get called from new paths during refactors. Trust no input                             |
+
+## Anti-Patterns
+
+| Anti-Pattern                                             | Why It Fails                                  | Instead                                                      |
+| -------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------ |
+| Validating only at the entry point (trusting downstream) | Alternate paths and refactors bypass one gate | Add independent checks at each boundary                      |
+| Duplicating identical validation at every layer          | Creates noise without improving safety        | Tailor each layer to boundary-specific invariants            |
+| Catching and swallowing errors silently                  | Hides failures and delays detection           | Raise explicit errors with actionable context                |
+| Mixing validation with business logic                    | Makes behavior hard to reason about and test  | Keep validation checks explicit and separate from core logic |
+
+## Overview
+
+When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.
+
+**Core principle:** Validate at EVERY layer data passes through. Make the bug structurally impossible.
+
+## Why Multiple Layers
+
+Single validation: "We fixed the bug"
+Multiple layers: "We made the bug impossible"
+
+Different layers catch different cases:
+
+- Entry validation catches most bugs
+- Business logic catches edge cases
+- Environment guards prevent context-specific dangers
+- Debug logging helps when other layers fail
+
+## The Four Layers
+
+### Layer 1: Entry Point Validation
+
+**Purpose:** Reject obviously invalid input at API boundary
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === "") {
+    throw new Error("workingDirectory cannot be empty");
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
+  }
+  // ... proceed
+}
+```
+
+### Layer 2: Business Logic Validation
+
+**Purpose:** Ensure data makes sense for this operation
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error("projectDir required for workspace initialization");
+  }
+  // ... proceed
+}
+```
+
+### Layer 3: Environment Guards
+
+**Purpose:** Prevent dangerous operations in specific contexts
+
+```typescript
+async function gitInit(directory: string) {
+  // In tests, refuse git init outside temp directories
+  if (process.env.NODE_ENV === "test") {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(`Refusing git init outside temp dir during tests: ${directory}`);
+    }
+  }
+  // ... proceed
+}
+```
+
+### Layer 4: Debug Instrumentation
+
+**Purpose:** Capture context for forensics
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug("About to git init", {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // ... proceed
+}
+```
+
+## Applying the Pattern
+
+When you find a bug:
+
+1. **Trace the data flow** - Where does bad value originate? Where used?
+2. **Map all checkpoints** - List every point data passes through
+3. **Add validation at each layer** - Entry, business, environment, debug
+4. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
+
+## Example from Session
+
+Bug: Empty `projectDir` caused `git init` in source code
+
+**Data flow:**
+
+1. Test setup → empty string
+2. `Project.create(name, '')`
+3. `WorkspaceManager.createWorkspace('')`
+4. `git init` runs in `process.cwd()`
+
+**Four layers added:**
+
+- Layer 1: `Project.create()` validates not empty/exists/writable
+- Layer 2: `WorkspaceManager` validates projectDir not empty
+- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
+- Layer 4: Stack trace logging before git init
+
+**Result:** All 1847 tests passed, bug impossible to reproduce
+
+## Key Insight
+
+All four layers were necessary. During testing, each layer caught bugs the others missed:
+
+- Different code paths bypassed entry validation
+- Mocks bypassed business logic checks
+- Edge cases on different platforms needed environment guards
+- Debug logging identified structural misuse
+
+**Don't stop at one validation point.** Add checks at every layer.
+
+## Verification
+
+- Test with invalid input at each layer boundary — each should reject independently.
+- Remove one validation layer — the next layer should still catch the error.
+
+## See Also
+
+- **structured-edit** - Reliable read/verify/edit workflow when changing validation code across layers