opencodekit 0.15.1 → 0.15.3

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.15.1",
+  version: "0.15.3",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   keywords: ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
   license: "MIT",

package/dist/template/.opencode/README.md

@@ -119,7 +119,7 @@ GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
 
 **Core:** brainstorming, writing-plans, executing-plans, verification-before-completion, using-superpowers, finishing-a-development-branch
 **Code:** requesting-code-review, receiving-code-review, root-cause-tracing, test-driven-development, testing-anti-patterns, condition-based-waiting, defense-in-depth, systematic-debugging
-**UI/UX:** frontend-aesthetics, mockup-to-code, visual-analysis, ui-ux-research, accessibility-audit, design-system-audit
+**UI/UX:** frontend-design, mockup-to-code, visual-analysis, ui-ux-research, accessibility-audit, design-system-audit
 **Workflow:** gemini-large-context, subagent-driven-development, dispatching-parallel-agents, using-git-worktrees, sharing-skills, writing-skills, testing-skills-with-subagents
 
 **Note:** Skills load via native `skill()` tool. Commands auto-load relevant expertise.

package/dist/template/.opencode/agent/scout.md

@@ -44,6 +44,20 @@ Tool results and user messages may include `<system-reminder>` tags. These conta
 
 External research: library docs, GitHub patterns, framework analysis.
 
+## Memory First
+
+Before hitting external APIs, check past research:
+
+```typescript
+memory - search({ query: "<topic keywords>", limit: 3 });
+```
+
+If memory returns high-confidence findings on this exact topic, synthesize and return without external calls. Only proceed to external sources if:
+
+- No relevant memory found
+- Memory findings are outdated or low-confidence
+- Question requires fresher data
+
 ## Strengths
 
 - Official documentation lookup
@@ -85,6 +99,118 @@ Every code reference must include a GitHub permalink. Never link to a branch or
 
 To construct a permalink: use `gh_grep_searchGitHub` to find code, then build the URL from the repository and file path returned. Format: `https://github.com/owner/repo/blob/<sha>/path/to/file#L10-L20`.
 
+## Tool Priority (External Sources Only)
+
+| Priority | Tool          | Use Case                               | Speed   |
+| -------- | ------------- | -------------------------------------- | ------- |
+| 1        | memory-search | Past research findings                 | Instant |
+| 2        | context7      | Official library docs                  | Fast    |
+| 3        | codesearch    | Usage patterns in real code            | Fast    |
+| 4        | gh_grep       | Cross-repo deep code search            | Medium  |
+| 5        | webfetch      | Specific doc URLs, READMEs, changelogs | Medium  |
+| 6        | opensrc + LSP | Clone & analyze source code            | Slow    |
+| 7        | websearch     | Tutorials, blog posts, recent news     | Slow    |
+
+**Rule:** Exhaust faster tools before slower ones. Run tools in parallel when independent.
+
+## webfetch Usage
+
+Use `webfetch` for specific external URLs when you have a known target:
+
+```typescript
+// GitHub raw files
+webfetch({
+  url: "https://raw.githubusercontent.com/owner/repo/main/README.md",
+  format: "markdown",
+});
+
+// Documentation pages
+webfetch({ url: "https://zod.dev/docs/guides/async", format: "markdown" });
+
+// Release notes
+webfetch({ url: "https://github.com/colinhacks/zod/releases", format: "markdown" });
+
+// API references
+webfetch({ url: "https://docs.example.com/api/authentication", format: "markdown" });
+```
+
+**When to use:**
+
+- User provides a specific URL
+- context7 returns a doc link worth fetching
+- Need CHANGELOG or release notes
+- GitHub README has details not in context7
+
+## Source Code Deep Dive
+
+When documentation is insufficient, analyze actual source code.
+
+### Step 1: Load the Skill
+
+```typescript
+skill({ name: "source-code-research" });
+```
+
+### Step 2: Clone the Package
+
+```bash
+npx opensrc <package>           # npm (auto-detects version)
+npx opensrc <package>@<version> # specific version
+npx opensrc pypi:<package>      # Python
+npx opensrc <owner>/<repo>      # GitHub repo
+```
+
+### Step 3: Navigate with LSP
+
+After cloning, source lands in `opensrc/repos/github.com/<owner>/<repo>/`. Use LSP:
+
+```typescript
+// Get file structure
+lsp({
+  operation: "documentSymbol",
+  filePath: "opensrc/repos/.../src/index.ts",
+  line: 1,
+  character: 1,
+});
+
+// Jump to definition
+lsp({
+  operation: "goToDefinition",
+  filePath: "opensrc/repos/.../src/types.ts",
+  line: 42,
+  character: 10,
+});
+
+// Find all usages
+lsp({
+  operation: "findReferences",
+  filePath: "opensrc/repos/.../src/core.ts",
+  line: 100,
+  character: 5,
+});
+```
+
+### Step 4: Search Within Clone
+
+```typescript
+// Find specific patterns
+grep({ pattern: "async.*refine", path: "opensrc/", include: "*.ts" });
+
+// Check tests for usage examples
+glob({ pattern: "opensrc/**/test/**/*.ts" });
+glob({ pattern: "opensrc/**/*.test.ts" });
+```
+
+### Step 5: Construct Permalinks
+
+Build GitHub permalinks from cloned code:
+
+```
+https://github.com/<owner>/<repo>/blob/<sha>/path/to/file.ts#L42-L56
+```
+
+Get SHA from `opensrc/sources.json` or the cloned repo.
+
 ## Guidelines
 
 Cite sources with links. No emojis. Explain what the code does, why it's designed that way, and how to use it.
@@ -93,10 +219,40 @@ Compare implementations across repositories when doing deep research. Note which
 
 ## When Things Fail
 
-If context7 doesn't find the library, clone the repo directly and read the source plus README.
+### Fallback Chain
+
+```
+context7 fails → try codesearch for patterns
+codesearch empty → try gh_grep with broader query
+gh_grep empty → webfetch specific doc URLs if known
+still stuck → opensrc clone + LSP analysis
+last resort → websearch for tutorials/blogs
+```
+
+### Specific Failures
+
+**context7 doesn't find library:**
+
+1. Try `codesearch({ query: "<library> <function> example" })`
+2. Try `gh_grep_searchGitHub({ query: "import.*from.*<library>" })`
+3. Clone with `npx opensrc <library>` and read source
+
+**gh_grep returns nothing:**
+
+- Broaden query: search concepts, not exact function names
+- Try different language filters
+- Search for error messages or config patterns
+
+**opensrc clone fails:**
+
+- Check if package exists on npm/pypi/crates
+- Try GitHub URL directly: `npx opensrc owner/repo`
+- Fall back to `webfetch` on raw GitHub files
 
-If gh_grep returns nothing, broaden your query. Search for concepts instead of exact function names.
+**API rate limits:**
 
-If you hit API rate limits, work from already-cloned repos in the temp directory.
+- Work from already-cloned repos in `opensrc/`
+- Use `memory-search` to find cached findings
+- Reduce parallel calls, go sequential
 
 If you're uncertain, say so explicitly. Propose a hypothesis but flag it as unverified.

package/dist/template/.opencode/agent/vision.md

@@ -65,9 +65,9 @@ Comprehensive analysis with actionable recommendations.
 **Use when:** Design review, accessibility audit, system consistency check
 **Skills:** Combine multiple skills based on task:
 
-- **UI/UX Review**: Primary `ui-ux-research`, supporting `frontend-aesthetics`
+- **UI/UX Review**: Primary `ui-ux-research`, supporting `frontend-design`
 - **Accessibility**: Primary `accessibility-audit`, supporting `visual-analysis`
-- **Design System**: Primary `design-system-audit`, supporting `frontend-aesthetics`
+- **Design System**: Primary `design-system-audit`, supporting `frontend-design`
 - **Mockup Analysis**: Primary `mockup-to-code`, supporting `visual-analysis`
 
 ```
@@ -99,7 +99,7 @@ Load skill(s) → Systematic analysis → Structured findings → Recommendation
 - "Check accessibility" → `accessibility-audit`
 - "Audit our design system" → `design-system-audit`
 - "Convert this design to code" → `mockup-to-code`
-- "Is this too AI-looking?" → `frontend-aesthetics`
+- "Is this too AI-looking?" → `frontend-design`
 - "Deep UI/UX analysis" → `ui-ux-research`
 
 ## Output Format
@@ -144,4 +144,4 @@ When reviewing designs, actively identify these AI-slop patterns:
 - Excessive rounded corners on everything
 - Glassmorphism without purpose
 
-**Alternative directions** are covered in `frontend-aesthetics` skill.
+**Alternative directions** are covered in `frontend-design` skill.

package/dist/template/.opencode/command/agent-browser.md

@@ -0,0 +1,21 @@
+---
+description: Automate browser tasks (scraping, form filling, web interaction)
+argument-hint: "[what you want to do in the browser]"
+agent: general
+---
+
+# Agent Browser: $ARGUMENTS
+
+Automate browser tasks using agent-browser CLI.
+
+## Load Skill
+
+```typescript
+skill({ name: "agent-browser" });
+```
+
+Then follow the skill instructions to help with browser automation.
+
+<user-request>
+$ARGUMENTS
+</user-request>

package/dist/template/.opencode/command/complete-next-task.md

@@ -0,0 +1,77 @@
+---
+description: Complete the next incomplete PRD task for a bead
+argument-hint: "<bead-id>"
+agent: build
+---
+
+# Complete Next Task: $ARGUMENTS
+
+Complete one task from a bead PRD task list.
+
+This command is **Beads-native**:
+
+- PRD: `.beads/artifacts/<bead-id>/prd.md`
+- Tasks: `.beads/artifacts/<bead-id>/prd.json`
+- Progress: `.beads/artifacts/<bead-id>/progress.txt`
+
+## Preconditions
+
+- A bead exists: `bd show $ARGUMENTS`
+- PRD task list exists:
+
+```bash
+ls ".beads/artifacts/$ARGUMENTS/prd.json"
+```
+
+If missing:
+
+- Create PRD: `.beads/artifacts/$ARGUMENTS/prd.md` (use `skill({ name: "prd" })`)
+- Convert: `skill({ name: "prd-task" })`
+
+## Process
+
+### 1) Get Bearings
+
+- Read `.beads/artifacts/$ARGUMENTS/progress.txt` (create if missing)
+- Read `.beads/artifacts/$ARGUMENTS/prd.json`
+- Pick the next task with `passes: false`
+
+### 2) Implement the Task
+
+Implement only what’s needed to satisfy the verification steps.
+
+### 3) Run Feedback Loops (Required)
+
+Run what applies to the repo:
+
+- tests
+- lint
+- typecheck
+
+Do not commit if any fail.
+
+### 4) Update PRD JSON
+
+Set that task’s `passes` to `true`.
+
+### 5) Update Progress Log
+
+Append a short entry to `.beads/artifacts/$ARGUMENTS/progress.txt`:
+
+```markdown
+## Task - <task.id>
+
+- What was implemented
+- Files changed
+- Learnings / patterns
+```
+
+### 6) Commit (Ask First)
+
+Show staged changes and ask user before committing.
+
+## Completion
+
+If all tasks have `passes: true`, report that the PRD is complete and recommend:
+
+- `/finish $ARGUMENTS`

package/dist/template/.opencode/command/create.md

@@ -60,7 +60,9 @@ bd create "[title]" -t epic -p 1
 
 ## Create Spec
 
-Write `.beads/artifacts/<bead-id>/spec.md`:
+Write `.beads/artifacts/<bead-id>/spec.md`.
+
+Treat `spec.md` as a **short task card** (one screen): goal + success criteria + constraints. Put the detailed plan and task breakdown in `prd.md`.
 
 ```markdown
 # [Title]
@@ -84,9 +86,16 @@ Write `.beads/artifacts/<bead-id>/spec.md`:
 **Must:** [required]
 **Never:** [forbidden]
 
+## PRD (Optional)
+
+If this task has a PRD, keep details there:
+
+- `.beads/artifacts/<bead-id>/prd.md`
+- `.beads/artifacts/<bead-id>/prd.json` (generated)
+
 ## Notes
 
-[context if needed]
+[only brief context here; details belong in prd.md]
 ```
 
 ## If Epic: Create Subtasks
@@ -104,6 +113,30 @@ Visualize:
 
 !`bd dep tree bd-[epic]`
 
+## Optional: Create a PRD (Recommended for features)
+
+If the work is more than a small one-off change, create a PRD alongside the spec.
+
+- Template: `.opencode/memory/_templates/prd.md`
+- Output: `.beads/artifacts/<bead-id>/prd.md`
+
+```typescript
+skill({ name: "prd" });
+```
+
+Write the PRD so it includes a `## Tasks` section (each `### ... [category]` with `**Verification:**` bullets).
+
+After PRD is written, convert it to executable tasks:
+
+```typescript
+skill({ name: "prd-task" });
+```
+
+This generates:
+
+- `.beads/artifacts/<bead-id>/prd.json`
+- `.beads/artifacts/<bead-id>/progress.txt`
+
 ## Sync
 
 ```bash
@@ -119,7 +152,9 @@ Type: [task/bug/feature/epic]
 Priority: [0-4]
 Spec: .beads/artifacts/bd-[id]/spec.md
 
-Next: /implement bd-[id]
+Next:
+- `/start bd-[id]` (recommended)
+- or `/implement bd-[id]` (direct implementation)
 ```
 
 If epic with subtasks:

package/dist/template/.opencode/command/design-audit.md

@@ -474,7 +474,7 @@ Save outputs to:
 
 | Need                   | Skill                 |
 | ---------------------- | --------------------- |
-| Aesthetic improvements | `frontend-aesthetics` |
+| Aesthetic improvements | `frontend-design` |
 | Implement from mockup  | `mockup-to-code`      |
 | Accessibility audit    | `accessibility-audit` |
 | Visual analysis        | `visual-analysis`     |

package/dist/template/.opencode/command/design.md

@@ -55,7 +55,7 @@ read({ filePath: "src/styles/globals.css" });
 
 ## Phase 2: Aesthetic Direction (DECISION GATE)
 
-skill({ name: "frontend-aesthetics" })
+skill({ name: "frontend-design" })
 
 **BEFORE any design work, you MUST state:**
 

package/dist/template/.opencode/command/finish.md

@@ -76,6 +76,14 @@ Read the spec and check each criterion:
 
 For each success criterion listed, run its verification. All must pass. If something's missing, go back and implement it.
 
+## If PRD Tasks Exist
+
+If `.beads/artifacts/$ARGUMENTS/prd.json` exists:
+
+- Ensure every task has `passes: true`
+- If tasks remain incomplete, do NOT close the bead yet
+- Continue with: `/complete-next-task $ARGUMENTS`
+
 ## Review Changes (Ask Before Commit)
 
 Show what would be committed:

package/dist/template/.opencode/command/frontend-design.md

@@ -0,0 +1,21 @@
+---
+description: Create distinctive, production-grade frontend interfaces
+argument-hint: "[component/page description]"
+agent: build
+---
+
+# Frontend Design: $ARGUMENTS
+
+Create UI components, pages, or applications with React, Tailwind CSS v4, shadcn/ui, and Motion.
+
+## Load Skill
+
+```typescript
+skill({ name: "frontend-design" });
+```
+
+Then follow the skill instructions to create the interface.
+
+<user-request>
+$ARGUMENTS
+</user-request>

package/dist/template/.opencode/command/index-knowledge.md

@@ -0,0 +1,25 @@
+---
+description: Generate hierarchical AGENTS.md knowledge base
+argument-hint: "[optional focus or notes]"
+agent: plan
+---
+
+# Index Knowledge: $ARGUMENTS
+
+Generate or refresh hierarchical `AGENTS.md` files for this codebase.
+
+## Load Skill
+
+```typescript
+skill({ name: "index-knowledge" });
+```
+
+Then follow the skill workflow to:
+
+- Analyze the repo structure
+- Identify subsystem boundaries
+- Generate/refresh `AGENTS.md` files (root + nested where appropriate)
+
+<user-request>
+$ARGUMENTS
+</user-request>

package/dist/template/.opencode/command/init.md

@@ -140,6 +140,12 @@ Detected subsystems that may benefit from nested AGENTS.md:
 Create nested AGENTS.md files? (y/n)
 ```
 
+### Optional Follow-Up: Index Knowledge
+
+If the repo is large or keeps changing (monorepos especially), generate/refresh hierarchical `AGENTS.md` using:
+
+- `/index-knowledge`
+
 ## Phase 5: Populate Memory Files
 
 ### .opencode/memory/user.md

package/dist/template/.opencode/command/opensrc.md

@@ -0,0 +1,58 @@
+---
+description: Clone a repo and enhance with AGENTS.md knowledge base
+---
+
+Clone a repository using opensrc and generate hierarchical AGENTS.md documentation.
+
+## Workflow
+
+### Step 1: Load opensrc skill
+
+```
+skill({ name: 'opensrc' })
+```
+
+### Step 2: Clone the repository
+
+```bash
+npx opensrc <repo>
+```
+
+Where `<repo>` is extracted from the user request (supports `owner/repo`, `github:owner/repo`, full URL, etc.)
+
+### Step 3: Navigate to cloned repo
+
+After clone completes, cd into the repo:
+
+```bash
+cd opensrc/repos/github.com/<owner>/<repo>/
+```
+
+Parse owner/repo from the input or from `opensrc/sources.json` after clone.
+
+### Step 4: Load index-knowledge skill
+
+```
+skill({ name: 'index-knowledge' })
+```
+
+Execute in **update mode** (default) - modify existing AGENTS.md + create new where warranted.
+
+### Step 5: Report completion
+
+```
+=== opensrc Complete ===
+
+Repository: <owner>/<repo>
+Location: opensrc/repos/github.com/<owner>/<repo>/
+
+AGENTS.md files generated:
+  ✓ ./AGENTS.md (root)
+  ✓ ./src/... (if applicable)
+
+The repository is now enhanced with agent context.
+```
+
+<user-request>
+$ARGUMENTS
+</user-request>

package/dist/template/.opencode/command/skill-create.md

@@ -19,13 +19,13 @@ Skills are process instructions that:
 
 ## Prerequisites
 
-Load the skill-writing skill first:
+Load the skill-creator skill first:
 
 ```typescript
-skill({ name: "writing-skills" });
+skill({ name: "skill-creator" });
 ```
 
-This provides the TDD framework for skill creation.
+This provides the framework for skill creation.
 
 ## Phase 1: Define the Problem
 

package/dist/template/.opencode/command/skill-optimize.md

@@ -10,10 +10,10 @@ Improve an existing skill to be more effective, concise, and resistant to agent
 
 ## Prerequisites
 
-Load the skill-writing methodology:
+Load the skill-creator skill:
 
 ```typescript
-skill({ name: "writing-skills" });
+skill({ name: "skill-creator" });
 ```
 
 ## Phase 1: Locate and Load Current Skill

package/dist/template/.opencode/command/start.md

@@ -206,6 +206,9 @@ Task({
 Look for:
 
 - `spec.md` - Requirements and constraints
+- `prd.md` - PRD (optional, recommended for features)
+- `prd.json` - PRD tasks (generated from prd.md)
+- `progress.txt` - PRD execution progress (append-only)
 - `research.md` - Previous research
 - `plan.md` - Implementation plan
 - `handoffs/` - Previous session handoffs
@@ -250,6 +253,11 @@ memory -
 
 If memory search fails (Ollama not running), continue without it.
 
+## PRD Tasks (If Present)
+
+- If `.beads/artifacts/$ARGUMENTS/prd.json` exists: next is `/complete-next-task $ARGUMENTS`.
+- If `.beads/artifacts/$ARGUMENTS/prd.md` exists but `prd.json` does not: generate tasks with `prd-task` (see `/create` for the full PRD workflow).
+
 ## Determine Next Step
 
 Based on task type and what exists:
@@ -264,12 +272,13 @@ Based on task type and what exists:
 
 ### For Tasks/Subtasks (leaf work)
 
-| Artifacts Found       | Next Command            |
-| --------------------- | ----------------------- |
-| Nothing               | `/research $ARGUMENTS`  |
-| Only spec.md          | `/plan $ARGUMENTS`      |
-| spec.md + research.md | `/plan $ARGUMENTS`      |
-| plan.md exists        | `/implement $ARGUMENTS` |
+| Artifacts Found       | Next Command                     |
+| --------------------- | -------------------------------- |
+| Nothing               | `/research $ARGUMENTS`           |
+| Only spec.md          | `/plan $ARGUMENTS`               |
+| spec.md + research.md | `/plan $ARGUMENTS`               |
+| plan.md exists        | `/implement $ARGUMENTS`          |
+| prd.json exists       | `/complete-next-task $ARGUMENTS` |
 
 ## Output
 

package/dist/template/.opencode/command/ui-review.md

@@ -17,7 +17,7 @@ skill({ name: "beads" }); // Session protocol
 ```
 
 ```typescript
-skill({ name: "frontend-aesthetics" });
+skill({ name: "frontend-design" });
 skill({ name: "visual-analysis" });
 skill({ name: "accessibility-audit" });
 ```