opencodekit 0.2.7 → 0.3.0

package/README.md

@@ -82,10 +82,16 @@ build (Primary Orchestrator - 70% of work)
   ├→ @orchestrator (Multi-agent coordination)
   └→ @general (Fallback)
 
+Background Plugins:
+  • enforcer (TODO completion enforcement)
+  • compactor (Context usage warnings at 70/85/95%)
+  • truncator (Dynamic output truncation)
+
 Supporting:
   • 24 Skills (loaded via commands: 8 core, 7 stack, 9 specialized)
   • 45+ Commands (workflow shortcuts, includes /handoff)
   • 5 MCP Services (context7, exa, gkg, gh_grep, figma*) + augment-context-engine
+  • Custom Tools (memory-*, observation, ast-grep)
   • Beads task tracking (`bd` CLI for multi-session workflows)
   • Manual Handoffs (clean phase transitions)
 ```
@@ -227,6 +233,8 @@ You've successfully set up OpenCodeKit when:
 - ✅ Delegation is clear (build → specialized subagents)
 - ✅ `/handoff` creates portable bundles (.opencode/memory/handoffs/)
 - ✅ MCP services configured (6 total: 5 enabled, 1 optional)
+- ✅ Background plugins active (enforcer, compactor, truncator)
+- ✅ Custom tools available (memory-\*, observation, ast-grep)
 - ✅ Environment variables set (.opencode/.env with API keys)
 
 ---
@@ -235,13 +243,13 @@ You've successfully set up OpenCodeKit when:
 
 - [OpenCode Docs](https://opencode.ai/docs/)
 - [Multi-Agent Pattern](https://github.com/disler/opencode-hooks-multi-agent-observability)
-- [Handoff Workflow Guide](.opencode/INTEGRATION_OVERVIEW.md)
+- [Handoff Workflow Guide](.opencode/command/handoff.md)
 - [MCP Services Setup](.opencode/README.md)
 
 ## 📚 Documentation
 
 - **CLI Tool**: [CLI.md](./CLI.md) - `ock` command reference (init, setup, agent, skill)
-- **Architecture Guide**: `.opencode/INTEGRATION_OVERVIEW.md` - Two-layer system (Memory + Backlog + Git)
+- **Architecture Guide**: `.opencode/AGENTS.md` - Global rules and tool priority
 - **MCP Services Setup**: `.opencode/README.md` - Complete environment setup
 - **Handoff Bundles**: `.opencode/command/handoff.md` - Clean phase transitions
 - **Custom Commands**: `.opencode/command/` - All 45+ workflow commands
@@ -252,9 +260,9 @@ You've successfully set up OpenCodeKit when:
 
 ---
 
-**OpenCodeKit v2.0**  
-**Architecture**: Two-layer (Memory + Backlog + Git)  
-**New**: Manual handoff workflow + 6 MCP services + 24 skills system + semantic memory search  
+**OpenCodeKit v0.3.0**  
+**Architecture**: Two-layer (Memory + Beads + Git)  
+**New in v0.3.0**: Background plugins (enforcer, compactor, truncator) + ast-grep semantic code tool  
 **Ready for**: Daily production use
 
 Enjoy your streamlined agent system with clean phase transitions! 🚀

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.2.7",
+  version: "0.3.0",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   type: "module",
   repository: {

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

@@ -63,32 +63,44 @@
 
 ## Tool Priority
 
-**GKG tools → Built-in tools**
+**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        | `grep`, `glob`                    | Pattern matching, file discovery |
-| 2        | `read`, `edit`, `write`           | File operations                  |
+| 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                    |
 
 **Rule**: Always `read` before `edit` to verify content.
 
-## Research Tools
+### AST-Grep Usage
+
+Semantic code operations - smarter than regex:
+
+```bash
+# Search patterns
+ast-grep pattern="console.log($$$)"                    # Find all console.log
+ast-grep pattern="async function $NAME($$$) { $$$ }"   # Find async functions
+ast-grep pattern="const [$S, $SET] = useState($$$)"    # Find React hooks
+
+# Replace (dry run by default)
+ast-grep pattern="oldFunc($$$)" rewrite="newFunc($$$)" dryRun=true
+ast-grep pattern="fetch($URL)" rewrite="await fetch($URL)" dryRun=false
+```
 
-| Tool                                        | Use For                                                | Performance Notes                  |
-| ------------------------------------------- | ------------------------------------------------------ | ---------------------------------- |
-| `augment-context-engine_codebase-retrieval` | Codebase understanding, architecture analysis          | ~74s avg, 200K context, 67% CCEval |
-| `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                   |
+**Pattern syntax**: `$NAME` = single node, `$$$` = zero or more nodes
 
-**Augment Context Engine Best Practices**:
+## Research Tools
 
-- **When to use**: Complex queries like "How does authentication work?", "What's the architecture?", "Where is X implemented?"
-- **When NOT to use**: Simple lookups ("find function foo"), specific file reads, known symbol references
+| 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     |
 
 ## Error Handling
 
@@ -149,6 +161,22 @@ memory-search(query: "session", type: "handoffs")
 
 - Task tracking uses Beads (`bd` CLI)
 
+## Active Plugins
+
+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        |
+
+**Compactor thresholds**:
+
+- 70% - Gentle reminder, still plenty of room
+- 85% - Consider pruning or summarizing
+- 95% - Critical: prune immediately or start new session
+
 ## Session Management
 
 **Philosophy**: Short sessions (<150k tokens) beat long bloated ones. Agents get worse with too much context. Cost is exponential.

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

@@ -38,12 +38,12 @@ opencode
 ├── README.md              # This file
 ├── opencode.json          # OpenCode configuration
 ├── AGENTS.md              # Global agent rules
-├── INTEGRATION_OVERVIEW.md  # Architecture docs
 │
 ├── agent/                 # Custom agents (5 total)
 ├── command/               # Custom commands (26 workflows)
 ├── superpowers/skills/    # Domain expertise (16 skills)
-├── tool/                  # Custom MCP tools
+├── tool/                  # Custom MCP tools (memory-*, observation, ast-grep)
+├── plugin/                # Background plugins (enforcer, compactor, truncator)
 └── memory/                # Persistent context
 ```
 
@@ -135,7 +135,55 @@ Memory (Permanent)     → Beads (Multi-session)    → Git (Audit Trail)
 **Beads:** Multi-session tasks with spec/research/plan/review artifacts  
 **Git:** Automatic execution history
 
-**See:** `INTEGRATION_OVERVIEW.md` for complete architecture
+**See:** `AGENTS.md` for global rules and tool priority
+
+---
+
+## Active Plugins (Background)
+
+Plugins run automatically in every session:
+
+| 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        |
+
+**Compactor thresholds**:
+
+- 70% - Gentle reminder, still plenty of room
+- 85% - Consider pruning or summarizing
+- 95% - Critical: prune immediately or start new session
+
+---
+
+## Custom Tools
+
+| Tool              | Purpose                                  |
+| ----------------- | ---------------------------------------- |
+| **memory-read**   | Load previous context, templates         |
+| **memory-update** | Save learnings, handoffs                 |
+| **memory-search** | Search across all memory files           |
+| **observation**   | Create structured observations           |
+| **ast-grep**      | Semantic code search/replace (AST-based) |
+
+### AST-Grep Usage
+
+Semantic code operations - smarter than regex:
+
+```bash
+# Search patterns
+ast-grep pattern="console.log($$$)"                    # Find all console.log
+ast-grep pattern="async function $NAME($$$) { $$$ }"   # Find async functions
+ast-grep pattern="const [$S, $SET] = useState($$$)"    # Find React hooks
+
+# Replace (dry run by default)
+ast-grep pattern="oldFunc($$$)" rewrite="newFunc($$$)" dryRun=true
+```
+
+**Pattern syntax**: `$NAME` = single node, `$$$` = zero or more nodes
+
+**Requires**: `brew install ast-grep` or `cargo install ast-grep --locked`
 
 ---
 
@@ -208,6 +256,23 @@ Result: Dashboard with shadcn/ui
 
 ## Troubleshooting
 
+**"Notifications not working" (WSL/Windows):**
+
+If running OpenCode in WSL, notifications require additional setup:
+
+```bash
+# 1. Install dependencies
+sudo apt install -y libnotify-bin dunst
+
+# 2. Start dunst (run each time you open WSL terminal)
+dunst >/dev/null 2>&1 &
+
+# 3. Or add to ~/.bashrc for auto-start:
+if ! pgrep -x dunst >/dev/null; then
+  dunst >/dev/null 2>&1 &
+fi
+```
+
 **"API key not found":**
 
 - Check .env location (.opencode/.env or ~/.config/opencode/.env)
@@ -260,10 +325,11 @@ Result: Dashboard with shadcn/ui
 - **Context7 API:** https://context7.com
 - **Exa API:** https://exa.ai
 - **Skills Documentation:** `superpowers/skills/`
-- **Architecture Guide:** `INTEGRATION_OVERVIEW.md`
+- **Architecture Guide:** `AGENTS.md`
 
 ---
 
-**OpenCodeKit Template v2.2**  
+**OpenCodeKit v0.3.0**  
 **Architecture:** Two-Layer (Memory + Beads + Git)  
-**Last Updated:** December 4, 2025
+**New in v0.3.0:** Background plugins (enforcer, compactor, truncator) + ast-grep tool  
+**Last Updated:** December 17, 2025

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

@@ -15,10 +15,13 @@ tools:
   websearch: true
   codesearch: true
   gkg*: true
+  ast-grep*: true
   context7*: true
   gh_grep*: true
   memory-read: true
   memory-update: true
+  memory-search: true
+  observation: true
 ---
 
 # Build Agent
@@ -44,8 +47,9 @@ Primary orchestrator. Execute-first. Autonomous task completion until resolved.
 ## Tool Priority
 
 1. **GKG tools** for code search (definitions, references, repo map)
-2. **Built-in tools** for pattern matching (grep, glob, read)
-3. **Bash** for running tests, builds, commands
+2. **AST-Grep** for semantic code search/replace
+3. **Built-in tools** for pattern matching (grep, glob, read)
+4. **Bash** for running tests, builds, commands
 
 ## Anti-Hallucination
 

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

@@ -14,11 +14,14 @@ tools:
   webfetch: true
   websearch: true
   gkg*: true
+  ast-grep*: true
   context7*: true
   gh_grep*: true
   codesearch: true
   memory-read: true
   memory-update: true
+  memory-search: true
+  observation: true
 ---
 
 # Rush Agent
@@ -42,14 +45,15 @@ Fast execute-first agent. Speed over depth. Delegate anything complex.
 
 ## Tool Priority
 
-**GKG tools FIRST for code search, then built-in tools.**
+**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             |
-| `grep`                            | Text strings, config values |
-| `glob`                            | Find files by pattern       |
+| 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        |
 
 ## Pre-Action Checks
 

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

@@ -1,11 +1,13 @@
 ---
-description: Brainstorm ideas into designs
+description: Brainstorm and explore ideas with code
 argument-hint: "[topic]"
-agent: review
+agent: build
 ---
 
 # Brainstorm: $ARGUMENTS
 
 use_skill("brainstorming")
 
-Follow the skill exactly. If bead exists, use `.beads/artifacts/<bead-id>/spec.md` as constraints.
+Follow the skill for ideation, then explore the codebase to validate feasibility. Create quick prototypes or code spikes if helpful.
+
+If bead exists, use `.beads/artifacts/<bead-id>/spec.md` as constraints.

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

@@ -1,15 +1,17 @@
 ---
-description: Design with brainstorming
+description: UI/UX visual design and aesthetics
 argument-hint: "[topic or task-id]"
 agent: designer
 ---
 
 # Design: $ARGUMENTS
 
-use_skill("brainstorming")
+use_skill("frontend-aesthetics")
 
-**Quick design:** Follow skill, apply YAGNI ruthlessly.
+Focus on visual design: typography, color, spacing, layout, accessibility. Avoid AI slop aesthetics.
 
-**Full design:** After brainstorming, save to `.opencode/memory/research/YYYY-MM-DD-$ARGUMENTS-design.md`
+**Quick design:** Provide actionable design recommendations.
+
+**Full design:** Save to `.opencode/memory/research/YYYY-MM-DD-$ARGUMENTS-design.md`
 
 If bead exists, design within `.beads/artifacts/<bead-id>/spec.md` constraints.

package/dist/template/.opencode/dcp.jsonc

@@ -1,43 +1,43 @@
 {
-	// Enable or disable the plugin
-	"enabled": true,
-	// Enable debug logging to ~/.config/opencode/logs/dcp/
-	"debug": false,
-	// Show toast when plugin updates are available
-	"showUpdateToasts": true,
-	// Summary display: "off", "minimal", or "detailed"
-	// Note: "detailed" may cause issues with extended thinking models
-	"pruningSummary": "off",
-	"strategies": {
-		// Deduplication runs automatically on every request
-		"deduplication": {
-			"enabled": true,
-			"protectedTools": []
-		},
-		// Exposes prune tool to the LLM for manual context management
-		"pruneTool": {
-			"enabled": true,
-			"protectedTools": [
-				"task",
-				"todowrite",
-				"todoread",
-				"prune",
-				"batch",
-				"write",
-				"edit"
-			],
-			// Nudge the AI to prune periodically
-			"nudge": {
-				"enabled": true,
-				"frequency": 10
-			}
-		},
-		// LLM-based semantic analysis on idle (legacy, resource intensive)
-		"onIdle": {
-			"enabled": false,
-			"showModelErrorToasts": true,
-			"strictModelSelection": false,
-			"protectedTools": []
-		}
-	}
+  // Enable or disable the plugin
+  "enabled": true,
+  // Enable debug logging to ~/.config/opencode/logs/dcp/
+  "debug": false,
+  // Show toast when plugin updates are available
+  "showUpdateToasts": true,
+  // Summary display: "off", "minimal", or "detailed"
+  // Note: "detailed" may cause issues with extended thinking models
+  "pruningSummary": "off",
+  "strategies": {
+    // Deduplication runs automatically on every request
+    "deduplication": {
+      "enabled": true,
+      "protectedTools": [],
+    },
+    // Exposes prune tool to the LLM for manual context management
+    "pruneTool": {
+      "enabled": true,
+      "protectedTools": [
+        "task",
+        "todowrite",
+        "todoread",
+        "prune",
+        "batch",
+        "write",
+        "edit",
+      ],
+      // Nudge the AI to prune periodically
+      "nudge": {
+        "enabled": true,
+        "frequency": 10,
+      },
+    },
+    // LLM-based semantic analysis on idle (legacy, resource intensive)
+    "onIdle": {
+      "enabled": false,
+      "showModelErrorToasts": true,
+      "strictModelSelection": true,
+      "protectedTools": [],
+    },
+  },
 }