opencodekit 0.3.3 → 0.5.0

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.3.3",
+  version: "0.5.0",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   type: "module",
   repository: {
@@ -2605,6 +2605,15 @@ async function editMCP(configPath) {
     await addMCPServer(configPath, config);
     return;
   }
+  console.log();
+  console.log(import_picocolors7.default.bold("  MCP Servers"));
+  for (const [name, server] of Object.entries(config.mcp)) {
+    const status = server.enabled === false ? import_picocolors7.default.red("off") : import_picocolors7.default.green("on");
+    const type = server.type === "remote" ? import_picocolors7.default.dim("remote") : import_picocolors7.default.dim("local");
+    const endpoint = server.type === "remote" ? import_picocolors7.default.dim(` → ${server.url}`) : import_picocolors7.default.dim(` → ${(server.command || []).join(" ")}`);
+    console.log(`    ${status} ${name} ${type}${endpoint}`);
+  }
+  console.log();
   const action = await ie({
     message: "MCP Servers",
     options: [

package/dist/template/.opencode/AGENTS.md

@@ -15,22 +15,38 @@
 
 **Check before any tool call. Delegate if task involves search or research.**
 
-| Task Type         | Delegate To | Trigger Words                                        |
-| ----------------- | ----------- | ---------------------------------------------------- |
-| Code search       | @explore    | find, where is, search, how does X work, locate      |
-| External research | @scout      | research, compare, docs for, API for, best practices |
-| Code review/debug | @review     | review, audit, debug, why broken, root cause         |
-| Architecture      | @planner    | design, architect, plan, structure, phases           |
-| UI/UX design      | @vision     | mockup, UI review, accessibility, aesthetics, visual |
+- **@explore** - Code search: find, where is, search, how does X work, locate
+- **@scout** - External research: research, compare, docs for, API for, best practices
+- **@review** - Code review/debug: review, audit, debug, why broken, root cause
+- **@planner** - Architecture: design, architect, plan, structure, phases
+- **@vision** - UI/UX design: mockup, UI review, accessibility, aesthetics, visual
 
 **Execute directly**: Single-file edits, explicit commands, answering from loaded context.
 
+### Research Depth Levels
+
+Specify depth when delegating to control tool call budget:
+
+- **quick** (~5-10 calls) - Simple lookup, single answer, API syntax
+- **medium** (~20-50 calls) - Moderate exploration, verify across files
+- **thorough** (~100+ calls) - Comprehensive analysis, dependency mapping
+
+**Examples**:
+
+```
+@explore (quick): Where is the auth middleware?
+@explore (thorough): How does the entire auth system work?
+@scout (quick): Syntax for React useEffect cleanup
+@scout (thorough): How do production apps handle auth refresh tokens?
+```
+
 ## Anti-Hallucination
 
 - **Major features**: Check task exists (`bd show <id>`)
 - **Bug fixes/edits**: Proceed directly; document clearly
 - **Before commit**: Close task with reason (`bd close <id> --reason "..."`)
 - **Find work**: Use `bd ready` for unblocked tasks
+- **URLs**: Never generate or guess URLs. Only use URLs from user input, tool results, or verified documentation.
 
 ## Universal Standards
 
@@ -65,14 +81,10 @@
 
 **GKG tools → AST tools → Built-in tools**
 
-| Priority | Tools                             | Use For                            |
-| -------- | --------------------------------- | ---------------------------------- |
-| 1        | `gkg_search_codebase_definitions` | Find symbols by name               |
-| 1        | `gkg_get_references`              | Find all usages                    |
-| 1        | `gkg_repo_map`                    | API-level overview                 |
-| 2        | `ast-grep`                        | Semantic code search/replace (AST) |
-| 3        | `grep`, `glob`                    | Pattern matching, file discovery   |
-| 3        | `read`, `edit`, `write`           | File operations                    |
+1. `gkg_search_codebase_definitions`, `gkg_get_references`, `gkg_repo_map` - Find symbols, usages, API overview
+2. `ast-grep` - Semantic code search/replace (AST-based)
+3. `grep`, `glob` - Pattern matching, file discovery
+4. `read`, `edit`, `write` - File operations
 
 **Rule**: Always `read` before `edit` to verify content.
 
@@ -95,18 +107,17 @@ ast-grep pattern="fetch($URL)" rewrite="await fetch($URL)" dryRun=false
 
 ## Research Tools
 
-| Tool         | Use For                                                | Performance Notes    |
-| ------------ | ------------------------------------------------------ | -------------------- |
-| `context7`   | Library docs (try first)                               | Fast, external APIs  |
-| `websearch`  | Docs not in Context7, recent releases, troubleshooting | General web search   |
-| `codesearch` | Real implementation patterns from GitHub               | Public repo examples |
-| `webfetch`   | Specific URL user provided                             | Direct URL fetch     |
+- **context7** - Library docs (try first). Fast, external APIs.
+- **websearch** - Docs not in Context7, recent releases, troubleshooting.
+- **codesearch** - Real implementation patterns from GitHub.
+- **webfetch** - Specific URL user provided.
 
 ## Error Handling
 
 - **Transient** (network, timeout): Retry 2x with backoff
 - **Rate limit**: Stop, report to user
 - **Logic error**: Change strategy, don't repeat
+- **Blocked by hook/CI**: Analyze error message, adjust approach, retry once. If still blocked, ask user to check hooks/config.
 
 ## Memory System
 
@@ -116,16 +127,37 @@ ast-grep pattern="fetch($URL)" rewrite="await fetch($URL)" dryRun=false
   handoffs/       # Phase transitions
   research/       # Research findings
   observations/   # Structured observations
+  project/        # Persistent project knowledge
+    commands.md       # Build, test, lint, deploy commands
+    conventions.md    # Code patterns, commit style, PR process
+    gotchas.md        # Footguns, edge cases, "don't forget this"
+    architecture.md   # Key modules, directory structure
+  user.md         # Identity, preferences, communication style
 ```
 
+### Standard Memory Blocks
+
+- **project/commands.md** - Build/test/lint commands. Update when discovering new command.
+- **project/conventions.md** - Code patterns, style. Update when learning team pattern.
+- **project/gotchas.md** - Footguns, warnings. Update when hitting unexpected behavior.
+- **project/architecture.md** - Key modules, structure. Update when mapping new area.
+- **user.md** - Preferences, workflow. Update when learning user preference.
+
+### Explicit Memory Updates
+
+Don't rely on implicit learning. Explicitly persist:
+
+- Non-obvious project behavior → `project/gotchas.md`
+- User preferences discovered → `user.md`
+- New build/test commands → `project/commands.md`
+- Code patterns to follow → `project/conventions.md`
+
 ### Memory Tools
 
-| Tool            | Use For                          |
-| --------------- | -------------------------------- |
-| `memory-read`   | Load previous context, templates |
-| `memory-update` | Save learnings, handoffs         |
-| `memory-search` | Search across all memory files   |
-| `observation`   | Create structured observations   |
+- **memory-read** - Load previous context, templates
+- **memory-update** - Save learnings, handoffs
+- **memory-search** - Search across all memory files
+- **observation** - Create structured observations
 
 ### Observations
 
@@ -165,11 +197,9 @@ memory-search(query: "session", type: "handoffs")
 
 Plugins run automatically in the background:
 
-| Plugin        | What it does                                                |
-| ------------- | ----------------------------------------------------------- |
-| **enforcer**  | OS notification when session idles with incomplete TODOs    |
-| **compactor** | Warns at 70%, 85%, 95% context usage - prevents rushed work |
-| **truncator** | Dynamic output truncation based on context remaining        |
+- **enforcer** - OS notification when session idles with incomplete TODOs
+- **compactor** - Warns at 70%, 85%, 95% context usage - prevents rushed work
+- **truncator** - Dynamic output truncation based on context remaining
 
 **Compactor thresholds**:
 
@@ -244,35 +274,28 @@ Use all three:
 
 Use `find_skills` → `use_skill` when:
 
-| Situation                  | Skill                               |
-| -------------------------- | ----------------------------------- |
-| Creating something new     | `brainstorming`                     |
-| Bug or unexpected behavior | `systematic-debugging`              |
-| Implementing feature       | `test-driven-development`           |
-| Before commit/done         | `verification-before-completion`    |
-| Complex multi-step work    | `writing-plans` → `executing-plans` |
-| Finished implementation    | `requesting-code-review`            |
-| Building UI                | `frontend-aesthetics`               |
-| UI/UX with images          | `ui-ux-research`                    |
-| Large codebase research    | `gemini-large-context`              |
+- Creating something new → `brainstorming`
+- Bug or unexpected behavior → `systematic-debugging`
+- Implementing feature → `test-driven-development`
+- Before commit/done → `verification-before-completion`
+- Complex multi-step work → `writing-plans` → `executing-plans`
+- Finished implementation → `requesting-code-review`
+- Building UI → `frontend-aesthetics`
+- UI/UX with images → `ui-ux-research`
+- Large codebase research → `gemini-large-context`
 
 Skip for simple questions, quick edits, or conversations.
 
-## Gemini CLI (Large Context)
+### Progressive Skill Loading
 
-Use when analysis needs >100KB context or image analysis.
+Skills consume context. Manage them actively:
 
-```bash
-# Codebase analysis
-gemini -p "@src/ [your question]"
-
-# Image analysis (interactive)
-gemini
-@mockup.png Analyze this UI design
-```
+1. **Load on-demand**: Only load skills when starting relevant work
+2. **Read linked files lazily**: Don't load all skill references immediately—read only when needed
+3. **Unload after completion**: When task completes, skill context is no longer needed
+4. **One skill at a time**: Avoid loading multiple skills unless task requires it
 
-**Default**: `gemini-2.5-pro` (1M tokens)
-**Fast**: `gemini-2.5-flash` with `-m gemini-2.5-flash`
+**IMPORTANT**: Always unload irrelevant skills to free context space. Loaded skills that aren't actively needed are context debt.
 
 ## Core Constraints
 

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

@@ -78,3 +78,23 @@ Before claiming completion:
 - Code review/debugging → @review
 - Architecture planning → @planner
 - UI/UX analysis, mockups → @vision
+
+### Delegation Prompt Structure
+
+When delegating, include ALL 7 sections:
+
+1. **TASK**: Atomic, specific goal (one action per delegation)
+2. **EXPECTED OUTCOME**: Concrete deliverables with success criteria
+3. **REQUIRED SKILLS**: Which skill to invoke (if any)
+4. **REQUIRED TOOLS**: Explicit tool whitelist (prevents sprawl)
+5. **MUST DO**: Exhaustive requirements - leave NOTHING implicit
+6. **MUST NOT DO**: Forbidden actions - anticipate rogue behavior
+7. **CONTEXT**: File paths, existing patterns, constraints
+
+After delegation completes, VERIFY:
+
+- Did result match expected outcome?
+- Were MUST DO / MUST NOT DO followed?
+- Evidence provided (not just "done")?
+
+Vague prompts = wasted tokens. Be exhaustive.

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

@@ -47,13 +47,9 @@ Fast execute-first agent. Speed over depth. Delegate anything complex.
 
 **GKG tools FIRST, then AST-Grep, then built-in tools.**
 
-| Tool                              | Use For                      |
-| --------------------------------- | ---------------------------- |
-| `gkg_search_codebase_definitions` | Find symbols by name         |
-| `gkg_get_references`              | Find all usages              |
-| `ast-grep`                        | Semantic code search/replace |
-| `grep`                            | Text strings, config values  |
-| `glob`                            | Find files by pattern        |
+1. `gkg_search_codebase_definitions`, `gkg_get_references` - Find symbols, usages
+2. `ast-grep` - Semantic code search/replace
+3. `grep`, `glob` - Text search, file patterns
 
 ## Pre-Action Checks
 
@@ -69,15 +65,31 @@ Before mutations (edit, write, delete):
 - **Rate limits**: Stop, report to user
 - **Logic errors**: Change strategy, don't repeat
 
-## Delegation Rules
+## Delegation
 
-| Task Type               | Delegate To |
-| ----------------------- | ----------- |
-| Codebase search         | @explore    |
-| Library docs, patterns  | @scout      |
-| Code review, debugging  | @review     |
-| Architecture, 3+ phases | @planner    |
-| UI/UX, mockups, visuals | @vision     |
+- Codebase search → @explore
+- Library docs, patterns → @scout
+- Code review, debugging → @review
+- Architecture, 3+ phases → @planner
+- UI/UX, mockups, visuals → @vision
+
+### Delegation Prompt Structure
+
+When delegating, include ALL 7 sections:
+
+1. **TASK**: Atomic, specific goal (one action per delegation)
+2. **EXPECTED OUTCOME**: Concrete deliverables with success criteria
+3. **REQUIRED SKILLS**: Which skill to invoke (if any)
+4. **REQUIRED TOOLS**: Explicit tool whitelist (prevents sprawl)
+5. **MUST DO**: Exhaustive requirements - leave NOTHING implicit
+6. **MUST NOT DO**: Forbidden actions - anticipate rogue behavior
+7. **CONTEXT**: File paths, existing patterns, constraints
+
+After delegation completes, VERIFY:
+
+- Did result match expected outcome?
+- Were MUST DO / MUST NOT DO followed?
+- Evidence provided (not just "done")?
 
 ## Execute Directly
 

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

@@ -30,96 +30,131 @@ Visual content specialist for multimodal analysis: images, mockups, PDFs, diagra
 
 ## Strengths
 
-- Image and screenshot analysis via Gemini CLI
+- Image and screenshot analysis
 - PDF and document extraction
 - Diagram interpretation (architecture, flowcharts, ERDs)
 - Design system audit and consistency review
 - Accessibility assessment (WCAG compliance)
 - Anti-AI-slop aesthetic recommendations
 
-## Guidelines
+## Analysis Modes
 
-- Use `gemini` CLI with `-m gemini-2.5-flash` for all visual analysis
-- Apply `frontend-aesthetics` skill to avoid generic AI aesthetics
-- Apply `ui-ux-research` skill for systematic design analysis
-- Read-only role: analyze and recommend, don't implement
-- Delegate implementation to @build agent
+### Quick Analysis
 
-## Gemini CLI Usage
+Fast visual assessment for simple queries.
 
-**Always use gemini-2.5-flash model:**
+**Use when:** Single image, specific question, time-sensitive
+**Skill:** `visual-analysis` (quick mode)
 
-### Image Analysis (Mockups, Screenshots)
-
-```bash
-gemini -m gemini-2.5-flash
-@mockup.png Analyze this UI design for:
-1. Typography choices and hierarchy
-2. Color palette and contrast
-3. Spacing and layout consistency
-4. Accessibility concerns
 ```
-
-### PDF/Document Analysis
-
-```bash
-gemini -m gemini-2.5-flash
-@document.pdf Extract key information and summarize
+Analyze image → Extract key observations → Provide focused answer
 ```
 
-### Diagram Interpretation
+### Deep Audit
 
-```bash
-gemini -m gemini-2.5-flash
-@architecture.png Explain this system architecture diagram
-```
+Comprehensive analysis with actionable recommendations.
+
+**Use when:** Design review, accessibility audit, system consistency check
+**Skills:** Combine multiple skills based on task:
 
-### Codebase-Wide Design Audit
+| Task            | Primary Skill         | Supporting Skills     |
+| --------------- | --------------------- | --------------------- |
+| UI/UX Review    | `ui-ux-research`      | `frontend-aesthetics` |
+| Accessibility   | `accessibility-audit` | `visual-analysis`     |
+| Design System   | `design-system-audit` | `frontend-aesthetics` |
+| Mockup Analysis | `mockup-to-code`      | `visual-analysis`     |
 
-```bash
-gemini -m gemini-2.5-flash -p "@src/components/ Audit design system consistency"
+```
+Load skill(s) → Systematic analysis → Structured findings → Recommendations
 ```
 
-## Design Principles
+## Responsibilities
 
-### Avoid AI Slop
+### DO
 
-- Inter/Roboto as primary fonts
-- Purple/blue gradients everywhere
-- Flat white backgrounds with no texture
-- Stock illustration style
-- Cookie-cutter card layouts
+- Load appropriate skill before analysis (`use_skill`)
+- Follow skill workflows systematically
+- Provide structured output (Summary → Findings → Recommendations)
+- Reference specific elements with coordinates/descriptions
+- Cite WCAG criteria for accessibility issues
+- Suggest concrete fixes, not vague improvements
 
-### Recommend Instead
+### DON'T
 
-- Distinctive typography (GT Walsheim, Söhne, custom fonts)
-- Purposeful color with texture and depth
-- Meaningful animations and transitions
-- Layout variety and visual hierarchy
+- Embed CLI commands in responses (use skills/commands instead)
+- Implement changes directly (delegate to @build)
+- Make assumptions about intent without clarifying
+- Skip skill loading for complex tasks
+- Provide generic "looks good" assessments
 
-## Accessibility Checklist
+## Skill Selection Guide
 
-- [ ] Color contrast meets WCAG AA (4.5:1 for text)
-- [ ] Focus indicators visible
-- [ ] Touch targets >= 44px
-- [ ] Motion respects prefers-reduced-motion
-- [ ] Keyboard navigation works
+| User Request                  | Load This Skill       |
+| ----------------------------- | --------------------- |
+| "Review this mockup"          | `visual-analysis`     |
+| "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` |
+| "Deep UI/UX analysis"         | `ui-ux-research`      |
 
 ## Tool Priority
 
-1. **Gemini CLI** (`-m gemini-2.5-flash`) for image, PDF, and codebase analysis
-2. **Read/Glob** for component and style inspection
-3. **Webfetch/Websearch** for design inspiration
+1. **Skills** (`use_skill`) - Load appropriate skill for the task
+2. **Read/Glob** - Inspect existing components and styles
+3. **GKG tools** - Find design-related code definitions
+4. **Webfetch/Websearch** - Design inspiration and references
+5. **Context7** - UI library documentation
 
 ## Output Format
 
-1. **Summary**: Overall assessment (1-2 sentences)
-2. **Findings**: Specific observations with details
-3. **Recommendations**: Actionable next steps
-4. **References**: Links to patterns if relevant
+All analyses should follow this structure:
+
+```markdown
+## Summary
+
+[1-2 sentence overall assessment]
+
+## Findings
+
+### [Category 1]
+
+- Observation with specific detail
+- Another observation
+
+### [Category 2]
+
+- Observation
+
+## Recommendations
+
+1. [Actionable fix] - Priority: High/Medium/Low
+2. [Another fix] - Priority: ...
+
+## References
+
+- [Link or pattern reference if relevant]
+```
 
 ## Delegation
 
-- Implementation work → @build
-- External library research → @scout
-- Code review after changes → @review
+| Need                  | Delegate To |
+| --------------------- | ----------- |
+| Implement changes     | @build      |
+| Research UI libraries | @scout      |
+| Review implementation | @review     |
+| Plan large redesign   | @planner    |
+
+## Anti-Patterns to Flag
+
+When reviewing designs, actively identify these AI-slop patterns:
+
+- Inter/Roboto as primary fonts without justification
+- Purple/blue gradient overuse
+- Flat white backgrounds lacking texture
+- Generic stock illustration style
+- Cookie-cutter card layouts with no hierarchy
+- Excessive rounded corners on everything
+- Glassmorphism without purpose
+
+**Alternative directions** are covered in `frontend-aesthetics` skill.

package/dist/template/.opencode/command/accessibility-check.md

@@ -0,0 +1,66 @@
+---
+description: WCAG accessibility audit
+argument-hint: "<image-or-component-path> [level: A|AA|AAA]"
+agent: vision
+model: proxypal/gemini-3-flash-preview
+---
+
+# Accessibility Check: $ARGUMENTS
+
+use_skill("accessibility-audit")
+
+Perform WCAG accessibility audit.
+
+## Instructions
+
+Parse path and WCAG level from `$ARGUMENTS` (default: AA).
+
+Determine input type:
+
+- **Image/screenshot**: Visual accessibility analysis
+- **Component path**: Code accessibility patterns
+
+## Visual Analysis
+
+Check:
+
+1. **Color contrast** - Text/background ratios (AA: 4.5:1 normal, 3:1 large)
+2. **Touch targets** - Interactive elements ≥44x44px
+3. **Visual information** - Color-only cues, missing labels
+4. **Content structure** - Heading hierarchy, reading order
+5. **Interactive states** - Focus indicators, hover states
+
+## Code Analysis
+
+Search for:
+
+- Missing alt text on images
+- Click handlers on non-interactive elements
+- Form inputs without labels
+- Missing ARIA attributes
+
+## Output
+
+```markdown
+## Accessibility Audit
+
+**WCAG Level:** [level]
+
+### Critical Issues
+
+- [ ] Issue + WCAG ref + fix
+
+### Major Issues
+
+- [ ] Issue + WCAG ref + fix
+
+### Minor Issues
+
+- [ ] Issue + WCAG ref + fix
+
+### Passed
+
+- ✓ What passed
+```
+
+Include code fix snippets for each issue.

package/dist/template/.opencode/command/analyze-mockup.md

@@ -0,0 +1,43 @@
+---
+description: Analyze UI mockup or screenshot
+argument-hint: "<image-path> [focus: layout|colors|components|all]"
+agent: vision
+model: proxypal/gemini-3-flash-preview
+---
+
+# Analyze Mockup: $ARGUMENTS
+
+use_skill("visual-analysis")
+
+Analyze the provided UI mockup or screenshot.
+
+## Instructions
+
+Load the image from the path in `$ARGUMENTS`.
+
+Determine focus area (default: all):
+
+- **layout**: Grid, hierarchy, spacing, responsive considerations
+- **colors**: Extract palette with hex values, suggest semantic naming
+- **components**: Identify UI elements, variants, reusability
+- **all**: Comprehensive analysis covering everything
+
+## Output Format
+
+```markdown
+## Summary
+
+[1-2 sentence overview]
+
+## Findings
+
+[Structured analysis based on focus area]
+
+## Implementation Notes
+
+- Technical considerations
+- Component library suggestions
+- CSS/Tailwind starting point
+```
+
+Suggest follow-up commands if relevant.

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

@@ -0,0 +1,53 @@
+---
+description: Audit design system from screenshots or codebase
+argument-hint: "<screenshots-path|codebase> [output: tokens|report|both]"
+agent: vision
+model: proxypal/gemini-3-pro-preview
+---
+
+# Design Audit: $ARGUMENTS
+
+use_skill("design-system-audit")
+
+Perform a comprehensive design system audit.
+
+## Instructions
+
+Determine source type from `$ARGUMENTS`:
+
+- **Screenshots path**: Analyze images for visual inventory
+- **"codebase"**: Analyze code for design tokens and patterns
+
+Output format (default: both):
+
+- **tokens**: JSON design tokens
+- **report**: Markdown audit report
+- **both**: Both formats
+
+## For Screenshots
+
+Analyze all images and extract:
+
+1. Color palette (group by primary, secondary, neutral, semantic)
+2. Typography scale (families, sizes, weights)
+3. Spacing patterns
+4. Component variants
+5. Inconsistencies to consolidate
+
+## For Codebase
+
+Search for:
+
+- Hardcoded colors and values
+- Tailwind config
+- CSS custom properties
+- Design token files
+
+## Output
+
+Provide design tokens JSON and/or audit report with:
+
+- Executive summary with metrics
+- Findings by category
+- Prioritized recommendations
+- Consistency score