opencodekit 0.15.1 → 0.15.2

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

@@ -0,0 +1,358 @@
+---
+name: index-knowledge
+description: Generate hierarchical AGENTS.md knowledge base for a codebase. Creates root + complexity-scored subdirectory documentation.
+---
+
+# index-knowledge
+
+Generate hierarchical AGENTS.md files. Root + complexity-scored subdirectories.
+
+## Usage
+
+```
+--create-new   # Read existing → remove all → regenerate from scratch
+--max-depth=2  # Limit directory depth (default: 5)
+```
+
+Default: Update mode (modify existing + create new where warranted)
+
+---
+
+## 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.**
+  
+```
+TodoWrite([
+  { 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

package/dist/template/.opencode/skill/mockup-to-code/SKILL.md

@@ -158,6 +158,6 @@ Save implementations to `.opencode/memory/design/implementations/`
 
 | Need              | Skill                 |
 | ----------------- | --------------------- |
-| Aesthetic quality | `frontend-aesthetics` |
+| Aesthetic quality | `frontend-design` |
 | Accessibility     | `accessibility-audit` |
 | Design tokens     | `design-system-audit` |

package/dist/template/.opencode/skill/opensrc/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: opensrc
+description: Fetch source code for npm, PyPI, or crates.io packages and GitHub/GitLab repos to provide AI agents with implementation context beyond types and docs. Use when needing to understand how a library works internally, debug dependency issues, or explore package implementations.
+---
+
+# opensrc
+
+CLI tool to fetch source code for packages/repos, giving AI coding agents deeper implementation context.
+
+## When to Use
+
+- Need to understand how a library/package works internally (not just its interface)
+- Debugging issues where types alone are insufficient
+- Exploring implementation patterns in dependencies
+- Agent needs to reference actual source code of a package
+
+## Quick Start
+
+```bash
+# Install globally or use npx
+npm install -g opensrc
+
+# Fetch npm package (auto-detects installed version from lockfile)
+npx opensrc zod
+
+# Fetch from other registries
+npx opensrc pypi:requests       # Python/PyPI
+npx opensrc crates:serde        # Rust/crates.io
+
+# Fetch GitHub repo directly
+npx opensrc vercel/ai           # owner/repo shorthand
+npx opensrc github:owner/repo   # explicit prefix
+npx opensrc https://github.com/colinhacks/zod  # full URL
+
+# Fetch specific version/ref
+npx opensrc zod@3.22.0
+npx opensrc owner/repo@v1.0.0
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opensrc <packages...>` | Fetch source for packages/repos |
+| `opensrc list` | List all fetched sources |
+| `opensrc remove <name>` | Remove specific source |
+| `opensrc clean` | Remove all sources |
+
+## Output Structure
+
+After fetching, sources stored in `opensrc/` directory:
+
+```
+opensrc/
+├── settings.json           # User preferences
+├── sources.json            # Index of fetched packages/repos
+└── repos/
+    └── github.com/
+        └── owner/
+            └── repo/       # Cloned source code
+```
+
+## File Modifications
+
+On first run, opensrc prompts to modify:
+- `.gitignore` - adds `opensrc/` to ignore list
+- `tsconfig.json` - excludes `opensrc/` from compilation
+- `AGENTS.md` - adds section pointing agents to source code
+
+Use `--modify` or `--modify=false` to skip prompt.
+
+## Key Behaviors
+
+1. **Version Detection** - For npm, auto-detects installed version from `node_modules`, `package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`
+2. **Repository Resolution** - Resolves package to its git repo via registry API, clones at matching tag
+3. **Monorepo Support** - Handles packages in monorepos via `repository.directory` field
+4. **Shallow Clone** - Uses `--depth 1` for efficient cloning, removes `.git` after clone
+5. **Tag Fallback** - Tries `v{version}`, `{version}`, then default branch if tag not found
+
+## Common Workflows
+
+### Fetching a Package
+
+```bash
+# Agent needs to understand zod's implementation
+npx opensrc zod
+# → Detects version from lockfile
+# → Finds repo URL from npm registry
+# → Clones at matching git tag
+# → Source available at opensrc/repos/github.com/colinhacks/zod/
+```
+
+### Updating Sources
+
+```bash
+# Re-run same command to update to currently installed version
+npx opensrc zod
+# → Checks if version changed
+# → Re-clones if needed
+```
+
+### Multiple Sources
+
+```bash
+# Fetch multiple at once
+npx opensrc react react-dom next
+npx opensrc zod pypi:pydantic vercel/ai
+```
+
+## References
+
+For detailed information:
+- [CLI Usage & Options](references/cli-usage.md) - Full command reference
+- [Architecture](references/architecture.md) - Code structure and extension
+- [Registry Support](references/registry-support.md) - npm, PyPI, crates.io details

package/dist/template/.opencode/skill/opensrc/references/architecture.md

@@ -0,0 +1,176 @@
+# opensrc Architecture
+
+## Contents
+- Directory structure
+- Core flow
+- Key modules
+- Type definitions
+- Extension points
+
+## Directory Structure
+
+```
+src/
+├── index.ts              # CLI entry, Commander setup
+├── types.ts              # Shared type definitions
+├── commands/
+│   ├── fetch.ts          # Main fetch logic
+│   ├── list.ts           # List sources
+│   ├── remove.ts         # Remove sources
+│   └── clean.ts          # Clean all sources
+└── lib/
+    ├── git.ts            # Clone, path management
+    ├── repo.ts           # Parse/resolve repo specs
+    ├── version.ts        # Detect installed versions
+    ├── agents.ts         # AGENTS.md/sources.json updates
+    ├── gitignore.ts      # .gitignore management
+    ├── tsconfig.ts       # tsconfig.json exclude
+    ├── settings.ts       # User preferences
+    ├── prompt.ts         # Interactive prompts
+    └── registries/
+        ├── index.ts      # Registry detection/routing
+        ├── npm.ts        # npm registry API
+        ├── pypi.ts       # PyPI API
+        └── crates.ts     # crates.io API
+```
+
+## Core Flow
+
+### Fetch Package
+
+1. **Parse input** - Detect registry prefix or repo format
+2. **Version detection** (npm only) - Check lockfiles/node_modules
+3. **Registry lookup** - Query API for repo URL
+4. **Clone** - Shallow clone at matching git tag
+5. **Update index** - Write to sources.json, optionally AGENTS.md
+
+### Input Type Detection
+
+```
+detectInputType(spec) → "package" | "repo"
+```
+
+- Registry prefix (`npm:`, `pypi:`, `crates:`) → package
+- Repo pattern (`owner/repo`, URL, `github:`) → repo
+- Default → package (npm)
+
+## Key Modules
+
+### registries/index.ts
+
+Routes to correct registry handler:
+
+```typescript
+parsePackageSpec(spec): PackageSpec
+resolvePackage(spec): ResolvedPackage
+detectRegistry(spec): { registry, cleanSpec }
+detectInputType(spec): "package" | "repo"
+```
+
+### git.ts
+
+Manages cloning and source storage:
+
+```typescript
+fetchSource(resolved, cwd): FetchResult
+fetchRepoSource(resolved, cwd): FetchResult
+listSources(cwd): { packages, repos }
+removePackageSource(name, cwd, registry): { removed, repoRemoved }
+```
+
+Storage structure: `opensrc/repos/{host}/{owner}/{repo}/`
+
+### version.ts
+
+Detects installed npm versions (priority order):
+1. `node_modules/{pkg}/package.json`
+2. `package-lock.json`
+3. `pnpm-lock.yaml`
+4. `yarn.lock`
+5. `package.json` (strips range prefixes)
+
+### repo.ts
+
+Parses repo specs, resolves via GitHub/GitLab API:
+
+```typescript
+parseRepoSpec(spec): RepoSpec | null
+resolveRepo(spec): ResolvedRepo
+isRepoSpec(spec): boolean
+```
+
+Supports: GitHub, GitLab, Bitbucket (GitHub/GitLab via API).
+
+## Type Definitions
+
+```typescript
+type Registry = "npm" | "pypi" | "crates"
+
+interface PackageSpec {
+  registry: Registry
+  name: string
+  version?: string
+}
+
+interface ResolvedPackage {
+  registry: Registry
+  name: string
+  version: string
+  repoUrl: string
+  repoDirectory?: string  // For monorepos
+  gitTag: string
+}
+
+interface RepoSpec {
+  host: string      // github.com, gitlab.com
+  owner: string
+  repo: string
+  ref?: string      // Branch, tag, commit
+}
+
+interface FetchResult {
+  package: string
+  version: string
+  path: string
+  success: boolean
+  error?: string
+  registry?: Registry
+}
+```
+
+## Extension Points
+
+### Adding a Registry
+
+1. Create `registries/{name}.ts`:
+   - `parse{Name}Spec(spec)` - Parse name@version
+   - `resolve{Name}Package(name, version)` - Query API, return ResolvedPackage
+
+2. Update `registries/index.ts`:
+   - Add prefix to `REGISTRY_PREFIXES`
+   - Add case to `parsePackageSpec` and `resolvePackage`
+
+3. Add to `Registry` type in `types.ts`
+
+### Registry Implementation Pattern
+
+```typescript
+// Parse spec into name/version
+export function parseSpec(spec: string): { name: string; version?: string }
+
+// Query registry API, extract repo URL
+async function fetchInfo(name: string): Promise<RegistryResponse>
+
+// Normalize git URLs (remove git+, .git suffix)
+function extractRepoUrl(info): string | null
+
+// Main resolver
+export async function resolve(name: string, version?: string): Promise<ResolvedPackage>
+```
+
+### Git Tag Resolution
+
+Clone tries tags in order:
+1. `v{version}` (most common)
+2. `{version}` (no prefix)
+3. Default branch (fallback with warning)