opencodekit 0.4.0 → 0.6.0

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.4.0",
+  version: "0.6.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**:
 
@@ -200,6 +230,14 @@ read_session("today")                                 # Today's first session
 read_session("ses_abc123", focus="file changes")      # Specific aspect
 ```
 
+**`summarize_session`** - Generate AI summary of a session
+
+```
+summarize_session("ses_abc123")                       # Trigger AI summarization
+```
+
+Use before `read_session` to get a quick overview of what happened in a past session without loading full context.
+
 ### When to Start New Session
 
 - Completing distinct task from `bd ready`
@@ -244,35 +282,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/command/init.md

@@ -0,0 +1,176 @@
+---
+description: Initialize project for AI-assisted development (creates AGENTS.md + memory files)
+argument-hint: "[--deep] [--skip-questions]"
+agent: planner
+---
+
+# Init: $ARGUMENTS
+
+One command to onboard a project. Creates project-root AGENTS.md and populates memory files.
+
+## Options
+
+- `--deep`: Comprehensive research (~100+ tool calls). Git history, patterns, contributors.
+- `--skip-questions`: Skip upfront questions, infer from git config.
+
+Default: Standard research (~20-50 tool calls).
+
+## Phase 1: Upfront Questions
+
+Unless `--skip-questions`, ask in one message:
+
+1. **Identity**: "Which git contributor are you?" (show top 5 from `git shortlog -sn --all | head -5`)
+2. **Communication**: "Terse or detailed responses?"
+3. **Workflow**: "Auto-commit or ask-first?"
+4. **Rules**: "Any rules I should always follow?"
+
+If skipped, infer identity from `git config user.name` and `git config user.email`.
+
+## Phase 2: Detect Project
+
+### Always Check
+
+- `package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml` - tech stack
+- `README.md` - project description
+- `.github/workflows/`, `.gitlab-ci.yml` - CI/CD
+- `Makefile`, `justfile` - build commands
+- Existing rules: `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`
+
+### With --deep
+
+- `git shortlog -sn --all | head -10` - contributors
+- `git log --format="%s" -50` - commit conventions
+- `git branch -a` - branching strategy
+- Source file analysis for patterns
+
+## Phase 3: Create Project-Root AGENTS.md
+
+Create `./AGENTS.md` (project root, ~20-30 lines):
+
+```markdown
+## Build/Lint/Test Commands
+
+**Build**: [detected command]
+**Test**: [detected command, include single-test syntax]
+**Lint**: [detected command]
+
+## Code Style
+
+**Imports**: [detected pattern]
+**Formatting**: [tool used, e.g., prettier, black]
+**Types**: [strict, optional, none]
+**Naming**: [conventions detected]
+**Error Handling**: [pattern detected]
+
+## Project-Specific Rules
+
+[Include any rules from .cursorrules, copilot-instructions, or user-provided]
+```
+
+If AGENTS.md exists, improve it - don't overwrite blindly.
+
+## Phase 4: Populate Memory Files
+
+### .opencode/memory/user.md
+
+```markdown
+---
+purpose: User identity, preferences, communication style
+updated: [today]
+---
+
+# User Profile
+
+## Identity
+
+- Name: [from git/questions]
+- Git contributor: [email/username]
+
+## Preferences
+
+- Communication: [terse/detailed]
+- Workflow: [auto-commit/ask-first]
+
+## Rules
+
+[from Phase 1]
+```
+
+### .opencode/memory/project/commands.md
+
+```markdown
+---
+purpose: Build, test, lint, deploy commands
+updated: [today]
+---
+
+# Commands
+
+## Build
+
+[detected]
+
+## Test
+
+[detected, include single-test example]
+
+## Lint
+
+[detected]
+```
+
+### .opencode/memory/project/architecture.md
+
+```markdown
+---
+purpose: Key modules, directory structure
+updated: [today]
+---
+
+# Architecture
+
+## Structure
+
+[detected directory layout]
+
+## Key Modules
+
+[identified entry points, core modules]
+```
+
+### With --deep, also create:
+
+- `project/conventions.md` - from git log analysis
+- `project/gotchas.md` - from bug-fix patterns in history
+
+## Phase 5: Reflection
+
+Before finishing:
+
+1. Did you create both AGENTS.md AND memory files?
+2. Are commands accurate and tested?
+3. Any typos or unclear descriptions?
+4. Would this help your future self?
+
+Fix issues found.
+
+## Phase 6: Summary
+
+Report:
+
+- Files created/updated
+- Tech stack detected
+- Key findings
+- Suggested next steps (e.g., "Run /review-codebase to check conventions")
+
+## File Locations
+
+```
+./AGENTS.md                              # Project-specific rules (created)
+.opencode/AGENTS.md                      # Global rules (untouched)
+.opencode/memory/user.md                 # User preferences (created)
+.opencode/memory/project/commands.md     # Build commands (created)
+.opencode/memory/project/architecture.md # Structure (created)
+.opencode/memory/project/conventions.md  # Patterns (--deep only)
+.opencode/memory/project/gotchas.md      # Warnings (--deep only)
+```

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

@@ -0,0 +1,71 @@
+---
+description: Generate AI summary of a previous session for quick context
+argument-hint: "[session_reference]"
+agent: build
+---
+
+# Summarize
+
+Generate an AI summary of a previous session to quickly understand what happened without loading full context.
+
+## Phase 1: Resolve Session
+
+If no argument provided, list recent sessions:
+
+```
+list_sessions(limit=5, project="current")
+```
+
+Parse the session reference:
+
+- Empty or "last" resolves to most recent session
+- "2 ago" or "3 ago" resolves to nth most recent
+- "today" resolves to first session today
+- "ses\_..." uses the session ID directly
+
+## Phase 2: Generate Summary
+
+Trigger AI summarization using the configured compaction model:
+
+```
+summarize_session(session_id)
+```
+
+The summary is generated asynchronously and stored with the session.
+
+## Phase 3: Display Result
+
+Read the session with focus on the generated summary:
+
+```
+read_session(session_id, focus="summary")
+```
+
+Present the summary in a clear, scannable format showing what was accomplished, key decisions made, and any blockers encountered.
+
+## Output
+
+Report the session metadata (ID, timestamp, message count, token usage) followed by the AI-generated summary. Highlight key actions taken during the session.
+
+End with actionable next steps:
+
+- How to load full context if needed
+- How to resume associated work
+
+## Examples
+
+```
+/summarize                    # Summarize most recent session
+/summarize last               # Same as above
+/summarize ses_abc123         # Summarize specific session
+/summarize 2 ago              # Summarize 2nd most recent
+/summarize today              # First session today
+```
+
+## When to Use
+
+Use this command before resuming work to get a quick overview without loading full context. Helpful during handoffs to understand previous session state, for context triage to decide if a session is worth loading, or when researching across multiple past sessions to find relevant work.
+
+## Integration
+
+This command works alongside other session tools. Start with `list_sessions` to discover available sessions, use `/summarize` to quickly understand promising candidates, then load full context with `read_session` only for the most relevant session. This workflow saves context space by avoiding unnecessary full session loads.

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

@@ -1,28 +1,59 @@
-# Project Context Template
+---
+purpose: Persistent project knowledge that survives across sessions
+updated: 2024-12-21
+---
 
-Use `/setup-project` command to initialize these files.
+# Project Memory
 
-## Files Created
+This directory stores persistent project knowledge that agents use across sessions.
 
-| File             | Purpose                             |
-| ---------------- | ----------------------------------- |
-| `product.md`     | Product vision, users, features     |
-| `tech-stack.md`  | Languages, frameworks, dependencies |
-| `workflow.md`    | Branch strategy, review, deployment |
-| `conventions.md` | Coding standards, patterns          |
+## Standard Files
 
-## Integration with Beads
+| File              | Purpose                                 | Update When             |
+| ----------------- | --------------------------------------- | ----------------------- |
+| `commands.md`     | Build, test, lint, deploy commands      | Discover new command    |
+| `conventions.md`  | Code patterns, commit style, PR process | Learn team pattern      |
+| `gotchas.md`      | Footguns, edge cases, warnings          | Hit unexpected behavior |
+| `architecture.md` | Key modules, directory structure        | Map new area            |
 
-Beads can reference project context:
+## File Format
+
+Each file uses YAML frontmatter:
+
+```yaml
+---
+purpose: How this memory should influence agent behavior
+updated: YYYY-MM-DD
+---
+```
+
+## How Agents Use This
+
+- **Session start**: Agents read relevant memory files for context
+- **During work**: Agents update files when learning new information
+- **Session end**: Critical learnings persisted here survive context reset
+
+## Integration
+
+### With Commands
+
+- `/implement` - Reads conventions for code style
+- `/setup-project` - Populates these files initially
+- `/review-codebase` - Checks against conventions
+
+### With Beads
 
 ```bash
 bd new feature "Add auth" --context .opencode/memory/project/
 ```
 
-## Integration with Commands
+## Philosophy
+
+**Don't rely on implicit learning.** When agents discover:
 
-Commands automatically check:
+- Non-obvious behavior → Update `gotchas.md`
+- New commands → Update `commands.md`
+- Code patterns → Update `conventions.md`
+- Architecture insights → Update `architecture.md`
 
-- `/implement` - Reads tech-stack for implementation guidance
-- `/plan` - Reads product for feature alignment
-- `/review-codebase` - Reads conventions for compliance
+Explicit memory beats hoping the agent remembers.

package/dist/template/.opencode/memory/project/architecture.md

@@ -0,0 +1,26 @@
+---
+purpose: Key modules, directory structure, architectural decisions
+updated: 2024-12-21
+---
+
+# Project Architecture
+
+## Directory Structure
+
+<!-- Key directories and their purpose -->
+
+## Key Modules
+
+<!-- Core files/modules and what they do -->
+
+## Data Flow
+
+<!-- How data moves through the system -->
+
+## External Dependencies
+
+<!-- Critical third-party services, APIs -->
+
+## Architectural Decisions
+
+<!-- Why things are structured this way -->