@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/incremental-implementation/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: incremental-implementation
+description: Use when implementing features or fixes to enforce thin vertical slices with verify-after-each — prevents large, untested changes by requiring working code at every step
+version: 1.0.0
+tags: [workflow, implementation, code-quality]
+dependencies: [test-driven-development, verification-before-completion]
+---
+
+# Incremental Implementation
+
+> **Replaces** big-bang implementations where everything is built at once and tested at the end — enforces thin vertical slices with verification after each step
+
+## When to Use
+
+- Implementing any feature that touches more than 2 files
+- Working from a plan or spec with multiple tasks
+- Building something where partial progress should be demonstrable
+
+## When NOT to Use
+
+- One-line fixes or trivial changes
+- Pure refactors with no behavior change (use code-simplification instead)
+- Exploratory prototyping where you need to experiment freely
+
+## Common Rationalizations
+
+| Rationalization                                   | Rebuttal                                                                                                            |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| "I'll build everything first and test at the end" | End-to-end testing after 500 lines of changes makes failures impossible to isolate                                  |
+| "This feature can't be split into slices"         | Every feature can be sliced — you're confusing "the UI needs all parts" with "the code must be written all at once" |
+| "Committing partial work creates noise"           | Partial working commits are rollback points. One giant commit is a rollback cliff                                   |
+| "It's faster to write it all at once"             | It feels faster until the first bug takes 2 hours to locate in a 400-line diff                                      |
+| "The slices are too small to be meaningful"       | If a slice compiles, passes tests, and moves toward the goal, it's meaningful                                       |
+| "I need to see the whole picture first"           | Read the plan first, then implement slice by slice. Understanding ≠ building all at once                            |
+
+## Overview
+
+Large implementations fail because errors compound. When you write 500 lines before running anything, each line can introduce a bug that interacts with bugs from other lines. Thin vertical slices keep the error surface small.
+
+**Core principle:** Working code at every step. Never be more than one slice away from a green build.
+
+## The Cycle
+
+```
+FOR each slice:
+  1. IMPLEMENT — Write the minimal code for this slice (1-3 files max)
+  2. VERIFY — Run typecheck + lint + relevant tests
+  3. COMMIT — Create a checkpoint with descriptive message
+  4. NEXT — Move to the next slice
+
+IF verify fails:
+  Fix within the current slice before moving on
+  Do NOT proceed to the next slice with broken code
+```
+
+## Slicing Strategies
+
+### Vertical Slice (Preferred)
+
+Each slice delivers one thin path through the full stack:
+
+```
+Slice 1: API endpoint returns hardcoded data → test passes
+Slice 2: API endpoint reads from database → test passes
+Slice 3: UI calls API and renders data → test passes
+Slice 4: Add validation and error handling → test passes
+```
+
+### Contract-First
+
+Define interfaces first, then implement behind them:
+
+```
+Slice 1: Define types/interfaces → compiles
+Slice 2: Implement with stubs → tests pass (with mocked data)
+Slice 3: Replace stubs with real implementation → tests pass
+```
+
+### Risk-First
+
+Implement the hardest or most uncertain part first:
+
+```
+Slice 1: The tricky algorithm or integration → tests pass
+Slice 2: The straightforward plumbing → tests pass
+Slice 3: The UI/presentation layer → tests pass
+```
+
+## Implementation Rules
+
+### 1. Simplicity First
+
+Default to the simplest viable solution for each slice.
+
+```
+❌ "Let me add a factory pattern for extensibility"
+✅ "Direct function call works. Refactor to pattern IF a second use case appears"
+```
+
+### 2. Scope Discipline
+
+Each slice does ONE thing. If you notice something else that needs fixing:
+
+```
+NOTICED BUT NOT TOUCHING: [description of unrelated improvement]
+```
+
+Log it and continue with the current slice.
+
+### 3. One Compilable Step at a Time
+
+Never leave the codebase in a state where typecheck fails between slices.
+
+```
+❌ Add 5 function signatures, then implement all 5
+✅ Add and implement function 1, verify, then function 2
+```
+
+### 4. Keep Tests Green
+
+If existing tests break from your change, fix them in the same slice — not in a "fix tests" slice later.
+
+### 5. Feature Flags for Incomplete Features
+
+If a slice can't be hidden behind existing abstractions:
+
+```typescript
+// Temporary gate — remove when feature is complete
+if (process.env.ENABLE_NEW_FEATURE) {
+  // new code path
+} else {
+  // existing behavior
+}
+```
+
+### 6. Rollback-Friendly
+
+Each committed slice should be independently revertable without breaking the build.
+
+## Slice Size Guide
+
+| Slice Size    | Signal                                     |
+| ------------- | ------------------------------------------ |
+| 1-30 lines    | Ideal — easy to review and verify          |
+| 30-100 lines  | Acceptable — still isolatable              |
+| 100-200 lines | Too large — find a split point             |
+| 200+ lines    | Stop. You're doing big-bang implementation |
+
+## Red Flags — STOP
+
+If you catch yourself:
+
+- Writing more than 100 lines without running verification
+- Saying "I'll test this after I finish the next part"
+- Having 3+ files with uncommitted changes
+- Building a complex abstraction before the simple version works
+- Skipping verification because "this slice is trivial"
+
+**STOP.** Verify what you have. Commit if it passes. Then continue.
+
+## Verification
+
+After each slice:
+
+```bash
+# Minimum verification (must pass)
+npm run typecheck   # or equivalent
+npm run lint        # or equivalent
+
+# If slice changes behavior
+npm test            # relevant test files
+```
+
+After all slices complete:
+
+```bash
+# Full verification
+npm run typecheck && npm run lint && npm test
+```
+
+## Integration with Other Skills
+
+- **test-driven-development** — Write the test for each slice FIRST (RED), then implement (GREEN)
+- **verification-before-completion** — Run full gates after the final slice
+- **code-simplification** — Refactor AFTER all slices pass, not during implementation
+- **systematic-debugging** — If a slice fails verification, debug systematically instead of guessing
+
+## See Also
+
+- **writing-plans** — Creates the plan that this skill executes slice-by-slice
+- **executing-plans** — Orchestrates parallel execution of independent slices

package/dist/template/.opencode/skill/index-knowledge/SKILL.md

@@ -0,0 +1,413 @@
+---
+name: index-knowledge
+description: Use when generating or refreshing AGENTS.md knowledge bases for a codebase. MUST load before creating hierarchical documentation or complexity-scored subdirectory guides.
+version: 1.0.0
+tags: [documentation, workflow]
+dependencies: []
+---
+
+# index-knowledge
+
+## When to Use
+
+- When you need to generate or update hierarchical AGENTS.md documentation for a codebase.
+
+## When NOT to Use
+
+- When only a single small directory needs a manual note instead of a full knowledge hierarchy.
+
+
+## Usage
+
+```
+/index-knowledge                  # Update mode (default)
+/index-knowledge --create-new     # Delete all → regenerate from scratch
+/index-knowledge --max-depth=2    # Limit directory depth (default: 5)
+```
+
+## Load Skills
+
+```typescript
+skill({ name: "memory-system" }); // Search for existing patterns
+skill({ name: "deep-research" }); // For thorough LSP exploration
+```
+
+## Check Memory First
+
+```typescript
+memory_search({ query: "AGENTS.md conventions patterns", limit: 3 });
+```
+
+---
+
+## Workflow (High-Level)
+
+1. **Discovery + Analysis** (concurrent)
+   - Launch parallel explore agents (multiple Task calls in one message)
+   - Main session: bash structure + LSP codemap + read existing AGENTS.md
+2. **Score & Decide** - Determine AGENTS.md locations from merged findings
+3. **Generate** - Root first, then subdirs in parallel
+4. **Review** - Deduplicate, trim, validate
+
+<critical>
+**TodoWrite ALL phases. Mark in_progress → completed in real-time.**
+  
+```typescript
+todowrite({ todos: [
+  { id: "discovery", content: "Fire explore agents + LSP codemap + read existing", status: "pending", priority: "high" },
+  { id: "scoring", content: "Score directories, determine locations", status: "pending", priority: "high" },
+  { id: "generate", content: "Generate AGENTS.md files (root + subdirs)", status: "pending", priority: "high" },
+  { id: "review", content: "Deduplicate, validate, trim", status: "pending", priority: "medium" }
+]});
+```
+</critical>
+
+---
+
+## Phase 1: Discovery + Analysis (Concurrent)
+
+**Mark "discovery" as in_progress.**
+
+### Launch Parallel Explore Agents
+
+Multiple Task calls in a single message execute in parallel. Results return directly.
+
+```
+// All Task calls in ONE message = parallel execution
+
+Task(
+  description="project structure",
+  subagent_type="explore",
+  prompt="Project structure: PREDICT standard patterns for detected language → REPORT deviations only"
+)
+
+Task(
+  description="entry points",
+  subagent_type="explore",
+  prompt="Entry points: FIND main files → REPORT non-standard organization"
+)
+
+Task(
+  description="conventions",
+  subagent_type="explore",
+  prompt="Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig) → REPORT project-specific rules"
+)
+
+Task(
+  description="anti-patterns",
+  subagent_type="explore",
+  prompt="Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments → LIST forbidden patterns"
+)
+
+Task(
+  description="build/ci",
+  subagent_type="explore",
+  prompt="Build/CI: FIND .github/workflows, Makefile → REPORT non-standard patterns"
+)
+
+Task(
+  description="test patterns",
+  subagent_type="explore",
+  prompt="Test patterns: FIND test configs, test structure → REPORT unique conventions"
+)
+```
+
+<dynamic-agents>
+**DYNAMIC AGENT SPAWNING**: After bash analysis, spawn ADDITIONAL explore agents based on project scale:
+
+| Factor                       | Threshold | Additional Agents          |
+| ---------------------------- | --------- | -------------------------- |
+| **Total files**              | >100      | +1 per 100 files           |
+| **Total lines**              | >10k      | +1 per 10k lines           |
+| **Directory depth**          | ≥4        | +2 for deep exploration    |
+| **Large files (>500 lines)** | >10 files | +1 for complexity hotspots |
+| **Monorepo**                 | detected  | +1 per package/workspace   |
+| **Multiple languages**       | >1        | +1 per language            |
+
+```bash
+# Measure project scale first
+total_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)
+total_lines=$(find . -type f \( -name "*.ts" -o -name "*.py" -o -name "*.go" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')
+large_files=$(find . -type f \( -name "*.ts" -o -name "*.py" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {count++} END {print count+0}')
+max_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1)
+```
+
+Example spawning (all in ONE message for parallel execution):
+
+```
+// 500 files, 50k lines, depth 6, 15 large files → spawn additional agents
+Task(
+  description="large files",
+  subagent_type="explore",
+  prompt="Large file analysis: FIND files >500 lines, REPORT complexity hotspots"
+)
+
+Task(
+  description="deep modules",
+  subagent_type="explore",
+  prompt="Deep modules at depth 4+: FIND hidden patterns, internal conventions"
+)
+
+Task(
+  description="cross-cutting",
+  subagent_type="explore",
+  prompt="Cross-cutting concerns: FIND shared utilities across directories"
+)
+// ... more based on calculation
+```
+
+</dynamic-agents>
+
+### Main Session: Concurrent Analysis
+
+**While Task agents execute**, main session does:
+
+#### 1. Bash Structural Analysis
+
+```bash
+# Directory depth + file counts
+find . -type d -not -path '*/\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c
+
+# Files per directory (top 30)
+find . -type f -not -path '*/\.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30
+
+# Code concentration by extension
+find . -type f \( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.go" -o -name "*.rs" \) -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20
+
+# Existing AGENTS.md / CLAUDE.md
+find . -type f \( -name "AGENTS.md" -o -name "CLAUDE.md" \) -not -path '*/node_modules/*' 2>/dev/null
+```
+
+#### 2. Read Existing AGENTS.md
+
+```
+For each existing file found:
+  Read(filePath=file)
+  Extract: key insights, conventions, anti-patterns
+  Store in EXISTING_AGENTS map
+```
+
+If `--create-new`: Read all existing first (preserve context) → then delete all → regenerate.
+
+#### 3. LSP Codemap (if available)
+
+```
+lsp_servers()  # Check availability
+
+# Entry points (parallel)
+lsp_document_symbols(filePath="src/index.ts")
+lsp_document_symbols(filePath="main.py")
+
+# Key symbols (parallel)
+lsp_workspace_symbols(filePath=".", query="class")
+lsp_workspace_symbols(filePath=".", query="interface")
+lsp_workspace_symbols(filePath=".", query="function")
+
+# Centrality for top exports
+lsp_find_references(filePath="...", line=X, character=Y)
+```
+
+**LSP Fallback**: If unavailable, rely on explore agents + AST-grep.
+
+**Merge: bash + LSP + existing + Task agent results. Mark "discovery" as completed.**
+
+---
+
+## Phase 2: Scoring & Location Decision
+
+**Mark "scoring" as in_progress.**
+
+### Scoring Matrix
+
+| Factor               | Weight | High Threshold           | Source  |
+| -------------------- | ------ | ------------------------ | ------- |
+| File count           | 3x     | >20                      | bash    |
+| Subdir count         | 2x     | >5                       | bash    |
+| Code ratio           | 2x     | >70%                     | bash    |
+| Unique patterns      | 1x     | Has own config           | explore |
+| Module boundary      | 2x     | Has index.ts/**init**.py | bash    |
+| Symbol density       | 2x     | >30 symbols              | LSP     |
+| Export count         | 2x     | >10 exports              | LSP     |
+| Reference centrality | 3x     | >20 refs                 | LSP     |
+
+### Decision Rules
+
+| Score        | Action                    |
+| ------------ | ------------------------- |
+| **Root (.)** | ALWAYS create             |
+| **>15**      | Create AGENTS.md          |
+| **8-15**     | Create if distinct domain |
+| **<8**       | Skip (parent covers)      |
+
+### Output
+
+```
+AGENTS_LOCATIONS = [
+  { path: ".", type: "root" },
+  { path: "src/hooks", score: 18, reason: "high complexity" },
+  { path: "src/api", score: 12, reason: "distinct domain" }
+]
+```
+
+**Mark "scoring" as completed.**
+
+---
+
+## Phase 3: Generate AGENTS.md
+
+**Mark "generate" as in_progress.**
+
+### Root AGENTS.md (Full Treatment)
+
+```markdown
+# PROJECT KNOWLEDGE BASE
+
+**Generated:** {TIMESTAMP}
+**Commit:** {SHORT_SHA}
+**Branch:** {BRANCH}
+
+## OVERVIEW
+
+{1-2 sentences: what + core stack}
+
+## STRUCTURE
+
+\`\`\`
+{root}/
+├── {dir}/ # {non-obvious purpose only}
+└── {entry}
+\`\`\`
+
+## WHERE TO LOOK
+
+| Task | Location | Notes |
+| ---- | -------- | ----- |
+
+## CODE MAP
+
+{From LSP - skip if unavailable or project <10 files}
+
+| Symbol | Type | Location | Refs | Role |
+
+## CONVENTIONS
+
+{ONLY deviations from standard}
+
+## ANTI-PATTERNS (THIS PROJECT)
+
+{Explicitly forbidden here}
+
+## UNIQUE STYLES
+
+{Project-specific}
+
+## COMMANDS
+
+\`\`\`bash
+{dev/test/build}
+\`\`\`
+
+## NOTES
+
+{Gotchas}
+```
+
+**Quality gates**: 50-150 lines, no generic advice, no obvious info.
+
+### Subdirectory AGENTS.md (Parallel)
+
+Launch general agents for each location in ONE message (parallel execution):
+
+```
+// All in single message = parallel
+Task(
+  description="AGENTS.md for src/hooks",
+  subagent_type="general",
+  prompt="Generate AGENTS.md for: src/hooks
+    - Reason: high complexity
+    - 30-80 lines max
+    - NEVER repeat parent content
+    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS
+    - Write directly to src/hooks/AGENTS.md"
+)
+
+Task(
+  description="AGENTS.md for src/api",
+  subagent_type="general",
+  prompt="Generate AGENTS.md for: src/api
+    - Reason: distinct domain
+    - 30-80 lines max
+    - NEVER repeat parent content
+    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS
+    - Write directly to src/api/AGENTS.md"
+)
+// ... one Task per AGENTS_LOCATIONS entry
+```
+
+**Results return directly. Mark "generate" as completed.**
+
+---
+
+## Phase 4: Review & Deduplicate
+
+**Mark "review" as in_progress.**
+
+For each generated file:
+
+- Remove generic advice
+- Remove parent duplicates
+- Trim to size limits
+- Verify telegraphic style
+
+**Mark "review" as completed.**
+
+---
+
+## Final Report
+
+```
+=== index-knowledge Complete ===
+
+Mode: {update | create-new}
+
+Files:
+  ✓ ./AGENTS.md (root, {N} lines)
+  ✓ ./src/hooks/AGENTS.md ({N} lines)
+
+Dirs Analyzed: {N}
+AGENTS.md Created: {N}
+AGENTS.md Updated: {N}
+
+Hierarchy:
+  ./AGENTS.md
+  └── src/hooks/AGENTS.md
+```
+
+---
+
+## Anti-Patterns
+
+- **Static agent count**: MUST vary agents based on project size/depth
+- **Sequential execution**: MUST parallel (multiple Task calls in one message)
+- **Ignoring existing**: ALWAYS read existing first, even with --create-new
+- **Over-documenting**: Not every dir needs AGENTS.md
+- **Redundancy**: Child never repeats parent
+- **Generic content**: Remove anything that applies to ALL projects
+- **Verbose style**: Telegraphic or die
+- **Skipping memory**: ALWAYS search memory for existing patterns before starting
+
+---
+
+## Record Findings
+
+After completion, save significant discoveries:
+
+```typescript
+observation({
+  type: "pattern",
+  title: "AGENTS.md patterns for [project]",
+  narrative: "[Key conventions, anti-patterns, structure decisions]",
+  concepts: "AGENTS.md, documentation, codebase, knowledge",
+  confidence: "high",
+});
+```