opencodekit 0.21.9 → 0.22.0

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

@@ -1,10 +1,9 @@
 ---
-description: External research specialist for library docs and patterns
+description: External research specialist for library docs, dependency source, and patterns
 mode: subagent
 temperature: 0.2
 steps: 30
 tools:
-  memory-update: false
   observation: false
   todowrite: false
   question: false
@@ -32,40 +31,46 @@ You are OpenCode, the best coding agent on the planet.
 
 # Scout Agent
 
-**Purpose**: Knowledge seeker — you find the signal in the noise of external information.
+**Purpose**: Knowledge seeker — you find the signal in the noise of external information. You inspect dependency source, compare local code against upstream, and return evidence-backed findings.
 
 > _"Good research doesn't dump facts; it creates actionable clarity."_
 
 ## Identity
 
-You are a read-only research agent. You output concise recommendations backed by verifiable sources only.
+You are a read-only research agent. You output concise recommendations backed by verifiable sources only. Do not modify the user's workspace.
 
 ## Task
 
-Find trustworthy external references quickly and return concise, cited guidance.
+Find trustworthy external references quickly and return concise, cited guidance — starting with the direct answer, then the evidence.
 
 ## Success Criteria
 
+- **Lead with the answer** — state the finding first, then the evidence
 - Answer the research question with the smallest set of authoritative sources that supports the recommendation
 - Lock factual claims to retrieved sources; do not rely on model memory for current facts, APIs, specs, or release status
 - Separate verified facts from assumptions, estimates, and lower-confidence context
 - State source conflicts explicitly and prefer higher-ranked sources
 - Stop when more searching is unlikely to change the recommendation
+- If a repository or resource is inaccessible, say so explicitly and continue with whatever evidence is still available
 
 ## Rules
 
 - Never modify project files
 - Never invent URLs; only use verified links
-- Cite every non-trivial claim
+- Cite every non-trivial claim with exact file paths and line references when available
 - Prefer high-signal synthesis over long dumps
 - **Never refer to tools by name** — say "I'm going to search for..." not "I'll use the websearch tool"
+- When reading a cloned repo, note that findings reflect the default clone state unless the caller specifies a branch/commit
 
 ## When to Use Scout
 
+- Inspecting dependency repositories or library source code
+- Comparing local code against upstream implementations
 - Finding library docs, API references, or framework patterns
 - Comparing alternatives or evaluating package options
 - Researching external integrations before implementation
 - Getting latest ecosystem info, release notes, or migration guides
+- Explaining how a library or framework works by reading its source
 
 ## When NOT to Use Scout
 
@@ -107,10 +112,19 @@ If lower-ranked sources conflict with higher-ranked sources, follow higher-ranke
 1. Check memory first:
 
    ```typescript
-   memory-search({ query: "<topic keywords>", limit: 3 });
+   memory - search({ query: "<topic keywords>", limit: 3 });
    ```
 
-2. If memory is insufficient, choose tools by need:
+2. If memory is insufficient, choose the primary approach by task type:
+
+   **Task involves a GitHub repo or dependency source code:**
+   - Use `grepsearch` or `codesearch` for targeted code search across public repos (no clone needed)
+   - Use `webclaw` scrape on `raw.githubusercontent.com` URLs to read specific files directly
+   - For deep inspection: `git clone <url> /tmp/<name>` via bash, then use glob/grep/read on the cloned path
+   - Use official docs only as a supplement when source alone is insufficient
+   - If multiple repos are relevant, inspect each before drawing conclusions
+
+   **Task involves docs, APIs, or ecosystem research:**
    | Need | Tool |
    |------|------|
    | docs/API | `context7`, `codesearch` |
@@ -124,19 +138,23 @@ If lower-ranked sources conflict with higher-ranked sources, follow higher-ranke
    **Web content priority:** Always try `webclaw` tools first for URL extraction. They handle 403s, bot protection, and produce 67% fewer tokens than raw HTML. Fall back to `webfetch` only if webclaw is unavailable.
 
 3. Run independent calls in parallel
-4. Return concise recommendations with sources
+4. Return findings: direct answer first, then evidence organized by repo/source
 
 ## Examples
 
-| Good                                                                 | Bad                                        |
-| -------------------------------------------------------------------- | ------------------------------------------ |
-| "Use pattern X; cited docs + 2 production examples with permalinks." | "Best practice is Y" with no source links. |
+| Good                                                                             | Bad                                        |
+| -------------------------------------------------------------------------------- | ------------------------------------------ |
+| "The function is at `lib/auth.ts:42`. It validates JWT via RS256." + source link | "Best practice is Y" with no source links. |
+| "Use pattern X; cited docs + 2 production examples with permalinks."             | Dumping raw file contents without analysis |
+| "Repo was inaccessible; continuing with official docs found at [url]..."         | Blocking on inaccessible resource silently |
 
 ## Output
 
-- Summary (2-5 bullets)
-- Recommended approach
-- Sources
-- Risks/tradeoffs
+**Structure every response in this order:**
+
+1. **Direct answer** — the finding or recommendation, upfront
+2. **Evidence** — organized by repo or source, with file:line references
+3. **Sources** — verified URLs or paths
+4. **Risks/tradeoffs** — if relevant
 
 **IMPORTANT:** Only your final message is returned to the main agent. Make it comprehensive and self-contained — include all key findings, not just a summary of what you explored.

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

@@ -8,7 +8,6 @@ tools:
   write: false
   bash: false
   task: false
-  memory-update: false
   observation: false
   todowrite: false
 ---

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

@@ -0,0 +1,48 @@
+---
+description: Reduce ambiguity before planning or implementation
+argument-hint: "<request or bead-id> [--quick|--deep]"
+agent: build
+---
+
+# Clarify: $ARGUMENTS
+
+Reduce ambiguity before planning or implementation. Use when the request is real but still fuzzy.
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "brainstorming" });
+```
+
+## Parse Arguments
+
+| Argument | Default | Description |
+|---|---|---|
+| `<request or bead-id>` | required | Freeform request text or existing bead ID |
+| `--quick` | false | Minimize to 1-3 high-leverage questions |
+| `--deep` | false | Cover non-goals, risks, interfaces, success criteria |
+
+**Mode rules:** Default → make next command obvious. `--quick` → 1-3 questions. `--deep` → exhaustive. `--deep` wins if both appear.
+
+## When to Use / Not Use
+
+**Use:** Request is fuzzy, scope unclear, multiple interpretations of "done," `/plan` would be premature because main decision is unresolved.  
+**Skip:** Request is specific enough to plan directly, task is mechanical, ambiguity is only about codebase facts you can inspect.
+
+## Core Rules
+
+- **Inspect first, ask second** — never ask for codebase facts you can discover directly
+- **One question at a time** — each must reduce a real ambiguity
+- **Prefer structured choices** (multiple choice, yes/no)
+- **Surface non-goals explicitly** — what should *not* change is as important as what should
+- **Stop once the next command is obvious**
+
+## Process
+
+1. Read request, identify unknowns blocking execution
+2. If bead ID: `br show $ID`, inspect artifacts
+3. If freeform text: search memory, check existing patterns
+4. Ask questions one at a time, resolve before next
+5. Surface non-goals and constraints
+6. Recommend next command: `/plan`, `/create`, `/ship`, or `/design`

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

@@ -0,0 +1,53 @@
+---
+description: Create a well-structured conventional commit from staged or unstaged changes
+argument-hint: "[--all] [--amend] [message override]"
+agent: build
+---
+
+# Commit: $ARGUMENTS
+
+Create a well-structured conventional commit from current changes.
+
+## Load Skills
+
+```typescript
+skill({ name: "verification-before-completion" });
+```
+
+## Process
+
+### Phase 1: Inspect Changes
+
+```bash
+git status --short
+git diff --cached --stat   # if staged
+git diff --stat            # if unstaged
+```
+
+### Phase 2: Review Diffs
+
+Read each changed file. Look for:
+- Debug code, console.log, TODOs that should be resolved
+- Accidental changes outside scope
+- Missing error handling or edge cases
+
+### Phase 3: Construct Commit
+
+Format: `type(scope): description`
+
+Types: `feat` (feature), `fix` (bug), `test` (test-only), `refactor` (no behavior change), `chore` (config/tooling), `docs`, `style`, `perf`.
+
+### Phase 4: Commit
+
+```bash
+git add <files>    # stage specific files — never git add .
+git commit -m "type(scope): description
+
+- bullet points of key changes"
+```
+
+### Phase 5: Verify
+
+```bash
+git log --oneline -3
+```

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

@@ -32,10 +32,10 @@ skill({ name: "ux-quality-gates" }); // IA, forms, recovery, loading, usability
 
 ## Phase 1: Detect Existing Design System
 
-```typescript
-tilth_tilth_files({ pattern: "**/tailwind.config.{js,ts,mjs}" });
-tilth_tilth_files({ pattern: "**/globals.css" });
-tilth_tilth_files({ pattern: "**/components.json" }); // shadcn
+```bash
+srcwalk files "**/tailwind.config.{js,ts,mjs}"
+srcwalk files "**/globals.css"
+srcwalk files "**/components.json"  # shadcn
 ```
 
 Read what exists. Don't design in a vacuum — build on the project's current system.

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

@@ -0,0 +1,56 @@
+---
+description: Debug and fix a bug or failing test
+argument-hint: "<description of bug or error>"
+agent: build
+---
+
+# Fix: $ARGUMENTS
+
+Systematically debug and fix the reported issue.
+
+## Load Skills
+
+```typescript
+skill({ name: "systematic-debugging" });
+skill({ name: "root-cause-tracing" });
+skill({ name: "verification-before-completion" });
+```
+
+## Process
+
+### Phase 1: Reproduce
+
+```bash
+# Reproduce the issue with the exact steps or command
+```
+
+### Phase 2: Isolate
+
+- Search for the error message or symptom in the codebase
+- Trace the execution path to find the root cause
+- Read the 2-4 most relevant files
+- Distinguish symptom from root cause
+
+### Phase 3: Fix
+
+- Apply the minimal fix for the root cause
+- Do not add speculative guards, tolerant readers, or defensive copies
+- Prefer making the bad state impossible over handling all bad states
+
+### Phase 4: Verify
+
+```bash
+npm run typecheck
+npm run lint
+npm test            # or vitest relevant test
+```
+
+If verification fails twice on the same approach, escalate with learnings.
+
+## Output
+
+Report:
+1. Root cause (with file:line)
+2. Fix applied
+3. Verification results
+4. What else was considered and rejected

package/dist/template/.opencode/command/improve-architecture.md

@@ -0,0 +1,55 @@
+---
+description: Proactive architecture health check — find shallow modules, propose deep-module redesigns
+argument-hint: "[path|module|'all'] [--scope surface|deep]"
+agent: review
+---
+
+# Improve Architecture: $ARGUMENTS
+
+Proactive architecture health check. Find shallow modules and propose deep-module redesigns.
+
+## Load Skills
+
+```typescript
+skill({ name: "deep-module-design" });
+skill({ name: "verification-before-completion" });
+```
+
+## Architecture Check
+
+Apply Ousterhout's deep module principles:
+- **Small interface** — does this module expose more than it should?
+- **Information hiding** — are implementation details leaking?
+- **Pull complexity downward** — are callers doing work the module should own?
+
+## Process
+
+### Phase 1: Scan
+
+If path given, focus on that directory. If `all`, scan the full project.
+
+For each module, assess:
+- Lines of interface vs lines of implementation
+- Number of callers and how they use it
+- What knowledge is embedded but not encapsulated
+- What would break if the module were redesigned
+
+### Phase 2: Propose
+
+For each finding:
+
+| Module | Issue | Proposed Redesign | Effort | Risk |
+|---|---|---|---|---|
+| path/to/module | Shallow interface exposing internals | Encapsulate behind 3 functions | M | Low |
+
+### Phase 3: Prioritize
+
+Rank proposals by impact/effort ratio. Recommend top 1-3 changes worth making.
+
+## Output
+
+Report:
+1. Modules reviewed
+2. Findings (current issue, proposed redesign, effort, risk)
+3. Top recommendations
+4. Quick wins (S-effort changes)

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

@@ -1,31 +1,49 @@
 ---
-description: Initialize core project setup (AGENTS.md + tech-stack detection only)
-argument-hint: "[--deep]"
+description: Initialize project setup — AGENTS.md, planning context, user profile, and tech stack
+argument-hint: "[--deep] [--context|--user|--all]"
 agent: build
 ---
 
 # Init: $ARGUMENTS
 
-Core project setup. Creates AGENTS.md and detects tech stack. Run once per project.
+Initialize project setup. Run once per project. Supports three modes via argument flags.
 
-> **Next steps:** `/init-user` for personalization, `/init-context` for GSD planning workflow
+> **Next step for fresh projects:** `/plan` to create first implementation plan.  
+> **Next step for brownfield:** `/review-codebase` for deep codebase analysis.
 
 ## Load Skills
 
 ```typescript
 skill({ name: "index-knowledge" });
+skill({ name: "context-initialization" });
+skill({ name: "brainstorming" });
+skill({ name: "verification-before-completion" });
+skill({ name: "swarm-coordination" }); // For --brownfield analysis
 ```
 
-## Options
+## Parse Arguments
 
-| Argument | Default | Description                               |
-| -------- | ------- | ----------------------------------------- |
-| `--deep` | false   | Comprehensive research (~100+ tool calls) |
+| Argument | Default | Description |
+|---|---|---|
+| `--deep` | false | Comprehensive research for AGENTS.md (~100+ tool calls) |
+| `--context` | false | Init planning context (roadmap, state) |
+| `--user` | false | Init user profile |
+| `--all` | false | Full init: AGENTS.md + context + user profile |
 
-## Phase 1: Detect Project
+**Mode rules:**
+- No flags (default): Core project setup — AGENTS.md + tech stack only
+- `--context`: Planning context (roadmap.md, state.md)
+- `--user`: User profile (user.md)
+- `--all`: Everything
+- `--deep` applies to AGENTS.md generation only
 
-Detect and validate:
+---
+
+## Mode 1: Core Setup (Default)
 
+### Phase 1: Detect Project
+
+Detect and validate:
 - Package manager and dependencies (with versions)
 - Build, test, lint, dev commands — **validate each actually works**
 - CI/CD configuration
@@ -34,82 +52,84 @@ Detect and validate:
 
 With `--deep`: Also analyze git history, source patterns, subsystem candidates.
 
-## Phase 2: Preview Detection
+### Phase 2: Preview Detection
 
-After detecting project, show summary and ask for confirmation:
+Show detected summary and ask for confirmation before writing.
 
-```typescript
-question({
-  questions: [
-    {
-      header: "Preview",
-      question: `Detected: ${detectedTechStack}. Create AGENTS.md?`,
-      options: [
-        { label: "Yes, create it (Recommended)" },
-        { label: "Show me what you'll write first" },
-        { label: "Cancel" },
-      ],
-    },
-  ],
-});
-```
+### Phase 3: Create AGENTS.md
+
+Create `./AGENTS.md` — target <60 lines (max 150). Follow `index-knowledge` format:
+- Tech stack with versions, file structure, validated commands
+- Code example from actual codebase
+- Testing conventions, boundaries, gotchas
+
+**Principles:** Examples > explanations. Pointers > copies. If AGENTS.md exists, improve it — don't overwrite blindly.
 
-**If "Show me":** Display detected values without writing files, then ask again.
+### Phase 4: Create tech-stack.md
 
-## Phase 3: Create AGENTS.md
+Write detected values to `.opencode/memory/project/tech-stack.md`. Persist with memory update.
 
-Create `./AGENTS.md` — **target <60 lines** (max 150). Follow the `index-knowledge` skill format:
+---
+
+## Mode 2: Planning Context (`--context`)
+
+Initialize project planning context with roadmap and state files.
 
-- Tech stack with versions
-- File structure
-- Commands (validated)
-- Code example from actual codebase (5-10 lines)
-- Testing conventions
-- Boundaries (always/ask-first/never)
-- Gotchas
+### Phase 1: Discovery
 
-**Principles**: Examples > explanations. Pointers > copies. If AGENTS.md exists, improve it — don't overwrite blindly.
+If `--brownfield` (detected from existing codebase), run parallel codebase analysis:
+- `explore` for architecture patterns
+- `explore` for data flow
+- `explore` for domain boundaries
 
-## Phase 4: Create tech-stack.md
+If greenfield, skip to requirements gathering.
 
-From template `.opencode/memory/_templates/tech-stack.md`:
+### Phase 2: Requirements Gathering
 
-Read the template from `.opencode/memory/_templates/tech-stack.md` and write it to `.opencode/memory/project/tech-stack.md`.
+Ask questions to define:
+- Project vision and goals (1-2 sentences each)
+- Target users and their needs
+- Core features (what must exist)
+- Technical constraints
+- Success criteria
 
-Fill detected values:
+### Phase 3: Create Files
 
-- Framework, language, runtime
-- Styling, components, design system
-- Database, ORM, state management
-- Testing tools
-- Verification commands
+- `.opencode/memory/project/roadmap.md` — vision, goals, user personas, feature roadmap, constraints, success criteria
+- `.opencode/memory/project/state.md` — current status, active decisions, known issues, next priorities
+- Update `.opencode/opencode.json` instructions to include roadmap.md and state.md
+
+---
 
-## Phase 5: Subsystems (--deep only)
+## Mode 3: User Profile (`--user`)
 
-Identify candidates for nested AGENTS.md:
+Create personalized user profile at `.opencode/memory/project/user.md`.
 
-- `packages/*/` in monorepos
-- `frontend/` vs `backend/` directories
-- Significantly different subsystem patterns
+### Phase 1: Gather Preferences
 
-Ask user before creating nested files.
+Ask questions about:
+- **Identity**: Name, role, experience level
+- **Communication**: Verbosity preference, feedback style, update frequency
+- **Workflow**: Branch strategy, commit style, review expectations, test expectations
+- **Technical**: Preferred tools, avoided patterns, dev environment
 
-## Phase 6: Verify and Report
+### Phase 2: Create user.md
 
-Verify:
+Write to `.opencode/memory/project/user.md` with the captured preferences.
 
-- [ ] AGENTS.md is <60 lines (or justified)
-- [ ] Commands validated and work
-- [ ] Boundaries include Never rules
-- [ ] Code example from actual codebase
-- [ ] tech-stack.md created
+### Phase 3: Update opencode.json
+
+Ensure user.md is in `instructions[]` as one of the 4 auto-injected files (user.md, tech-stack.md, project.md, git-context.md).
+
+> **Warning:** Do not add more files to `instructions[]` unless essential. Per-prompt injection of too many files causes session OOM. Use `memory-search({ file: "..." })` for on-demand access.
+
+---
 
-Output:
+## Output
 
-1. Files created (with line counts)
-2. Tech stack detected
-3. Commands validated (yes/no)
-4. Suggested next steps:
-   - `/init-user` — Create user profile
-   - `/init-context` — Set up GSD planning workflow
-   - `/review-codebase` — Deep codebase analysis
+Report what was created:
+1. AGENTS.md (if core setup ran)
+2. tech-stack.md (if core setup ran)
+3. roadmap.md + state.md (if `--context`)
+4. user.md (if `--user`)
+5. Recommended next command: `/plan`, `/review-codebase`, or `/resume`

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

@@ -0,0 +1,66 @@
+---
+description: Refactor code for clarity, performance, or maintainability
+argument-hint: "<file or path> [--scope minimal|moderate|aggressive]"
+agent: build
+---
+
+# Refactor: $ARGUMENTS
+
+Improve code quality without changing external behavior.
+
+## Load Skills
+
+```typescript
+skill({ name: "code-simplification" });
+skill({ name: "verification-before-completion" });
+```
+
+## Parse Arguments
+
+| Argument | Default | Description |
+|---|---|---|
+| `<file or path>` | required | File or directory to refactor |
+| `--scope` | minimal | `minimal` (rename/restructure), `moderate` (extract modules), `aggressive` (redesign) |
+
+## When to Refactor
+
+- Module has grown beyond its original purpose
+- Tests are hard to write because of tight coupling
+- Similar logic appears in multiple places
+- Files have crossed 300+ lines with unclear boundaries
+
+## Process
+
+### Phase 1: Assess
+
+1. Read all files in scope
+2. Identify: duplication, shallow interfaces, unclear naming, mixed concerns
+3. Plan the refactor — show plan if >3 files would change
+
+### Phase 2: Lock Behavior
+
+- If the module has tests, they must still pass after refactor
+- If no tests exist, run existing verification (typecheck, lint)
+- No behavior changes in a refactor — external API must be preserved
+
+### Phase 3: Execute
+
+- One change at a time, verify after each
+- Prefer small commits with clear messages
+- `refactor(scope): what changed`
+
+### Phase 4: Verify
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+```
+
+## Output
+
+Report:
+1. What changed and why
+2. Files modified
+3. Verification results
+4. What was left for future refactors

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

@@ -38,7 +38,7 @@ skill({ name: "verification-gates" });
 | `explore`            | Finding patterns in codebase, prior art |
 | `scout`              | External research, best practices       |
 | `lsp`                | Finding symbol definitions, references  |
-| `tilth_tilth_search` | Finding code patterns                   |
+| `srcwalk find`       | Finding code patterns                   |
 | `codesearch`         | Real-world usage examples               |
 
 ## Phase 1: Gather Context

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

@@ -48,7 +48,7 @@ skill({ name: "reflection-checkpoints" }); // Mid-point + completion checks duri
 | `explore`            | Finding patterns in codebase, prior art   |
 | `scout`              | External research, best practices         |
 | `lsp`                | Finding symbol definitions, references    |
-| `tilth_tilth_search` | Finding code patterns                     |
+| `srcwalk find`       | Finding code patterns                     |
 | `task`               | Spawning subagents for parallel execution |
 
 ## Phase 1: Guards