opencode-hive 1.1.0 → 1.3.0

package/dist/skills/registry.generated.d.ts

@@ -7,7 +7,7 @@ import type { SkillDefinition } from './types.js';
 /**
  * List of builtin skill names.
  */
-export declare const BUILTIN_SKILL_NAMES: readonly ["brainstorming", "code-reviewer", "dispatching-parallel-agents", "executing-plans", "onboarding", "parallel-exploration", "systematic-debugging", "test-driven-development", "verification-before-completion", "writing-plans"];
+export declare const BUILTIN_SKILL_NAMES: readonly ["agents-md-mastery", "brainstorming", "code-reviewer", "dispatching-parallel-agents", "docker-mastery", "executing-plans", "parallel-exploration", "systematic-debugging", "test-driven-development", "verification-before-completion", "writing-plans"];
 /**
  * All builtin skill definitions.
  */

package/dist/utils/compaction-prompt.d.ts

@@ -0,0 +1 @@
+export declare function buildCompactionPrompt(): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-hive",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "OpenCode plugin for Agent Hive - from vibe coding to hive coding",
   "license": "MIT WITH Commons-Clause",

package/skills/agents-md-mastery/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: agents-md-mastery
+description: "Use when bootstrapping, updating, or reviewing AGENTS.md — teaches what makes effective agent memory, how to structure sections, signal vs noise filtering, and when to prune stale entries"
+---
+
+# AGENTS.md Mastery
+
+## Overview
+
+**AGENTS.md is pseudo-memory loaded at session start.** Every line shapes agent behavior for the entire session. Quality beats quantity. Write for agents, not humans.
+
+Unlike code comments or READMEs, AGENTS.md entries persist across all agent sessions. A bad entry misleads agents hundreds of times. A missing entry causes the same mistake repeatedly.
+
+**Core principle:** Optimize for agent comprehension and behavioral change, not human readability.
+
+## The Iron Law
+
+```
+EVERY ENTRY MUST CHANGE AGENT BEHAVIOR
+```
+
+If an entry doesn't:
+- Prevent a specific mistake
+- Enable a capability the agent would otherwise miss
+- Override a default assumption that breaks in this codebase
+
+...then it doesn't belong in AGENTS.md.
+
+**Test:** Would a fresh agent session make a mistake without this entry? If no → noise.
+
+## When to Use
+
+| Trigger | Action |
+|---------|--------|
+| New project bootstrap | Write initial AGENTS.md with build/test/style basics |
+| Feature completion | Sync new learnings via `hive_agents_md` tool |
+| Periodic review | Audit for stale/redundant entries (quarterly) |
+| Quality issues | Agent repeating mistakes? Check if AGENTS.md has the fix |
+
+## What Makes Good Agent Memory
+
+### Signal Entries (Keep)
+
+✅ **Project-specific conventions:**
+- "We use Zustand, not Redux — never add Redux"
+- "Auth lives in `/lib/auth` — never create auth elsewhere"
+- "Run `bun test` not `npm test` (we don't use npm)"
+
+✅ **Non-obvious patterns:**
+- "Use `.js` extension for local imports (ESM requirement)"
+- "Worktrees don't share `node_modules` — run `bun install` in each"
+- "SandboxConfig is in `dockerSandboxService.ts`, NOT `types.ts`"
+
+✅ **Gotchas that break builds:**
+- "Never use `ensureDirSync` — doesn't exist. Use `ensureDir` (sync despite name)"
+- "Import from `../utils/paths.js` not `./paths` (ESM strict)"
+
+### Noise Entries (Remove)
+
+❌ **Agent already knows:**
+- "This project uses TypeScript" (agent detects from files)
+- "We follow semantic versioning" (universal convention)
+- "Use descriptive variable names" (generic advice)
+
+❌ **Irrelevant metadata:**
+- "Created on January 2024"
+- "Originally written by X"
+- "License: MIT" (in LICENSE file already)
+
+❌ **Describes what code does:**
+- "FeatureService manages features" (agent can read code)
+- "The system uses git worktrees" (observable from commands)
+
+### Rule of Thumb
+
+**Signal:** Changes how agent acts  
+**Noise:** Documents what agent observes
+
+## Section Structure for Fast Comprehension
+
+Agents read AGENTS.md top-to-bottom once at session start. Put high-value info first:
+
+```markdown
+# Project Name
+
+## Build & Test Commands
+# ← Agents need this IMMEDIATELY
+bun run build
+bun run test
+bun run release:check
+
+## Code Style
+# ← Prevents syntax/import errors
+- Semicolons: Yes
+- Quotes: Single
+- Imports: Use `.js` extension
+
+## Architecture
+# ← Key directories, where things live
+packages/
+├── hive-core/      # Shared logic
+├── opencode-hive/  # Plugin
+└── vscode-hive/    # Extension
+
+## Important Patterns
+# ← How to do common tasks correctly
+Use `readText` from paths.ts, not fs.readFileSync
+
+## Gotchas & Anti-Patterns
+# ← Things that break or mislead
+NEVER use `ensureDirSync` — doesn't exist
+```
+
+**Keep total under 500 lines.** Beyond that, agents lose focus and miss critical entries.
+
+## The Sync Workflow
+
+After completing a feature, sync learnings to AGENTS.md:
+
+1. **Trigger sync:**
+   ```typescript
+   hive_agents_md({ action: 'sync', feature: 'feature-name' })
+   ```
+
+2. **Review each proposal:**
+   - Read the proposed change
+   - Ask: "Does this change agent behavior?"
+   - Check: Is this already obvious from code/files?
+
+3. **Accept signal, reject noise:**
+   - ❌ "TypeScript is used" → Agent detects this
+   - ✅ "Use `.js` extension for imports" → Prevents build failures
+
+4. **Apply approved changes:**
+   ```typescript
+   hive_agents_md({ action: 'apply' })
+   ```
+
+**Warning:** Don't auto-approve all proposals. One bad entry pollutes all future sessions.
+
+## When to Prune
+
+Remove entries when they become:
+
+**Outdated:**
+- "We use Redux" → Project migrated to Zustand
+- "Node 16 compatibility required" → Now on Node 22
+
+**Redundant:**
+- "Use single quotes" + "Strings use single quotes" → Keep one
+- Near-duplicates in different sections
+
+**Too generic:**
+- "Write clear code" → Applies to any project
+- "Test your changes" → Universal advice
+
+**Describing code:**
+- "TaskService manages tasks" → Agent can read `TaskService` class
+- "Worktrees are in `.hive/.worktrees/`" → Observable from filesystem
+
+**Proven unnecessary:**
+- Entry added 6 months ago, but agents haven't hit that issue since
+
+## Red Flags
+
+| Warning Sign | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| AGENTS.md > 800 lines | Agents lose focus, miss critical info | Prune aggressively |
+| Describes what code does | Agent can read code | Remove descriptions |
+| Missing build/test commands | First thing agents need | Add at top |
+| No gotchas section | Agents repeat past mistakes | Document failure modes |
+| Generic best practices | Doesn't change behavior | Remove or make specific |
+| Outdated patterns | Misleads agents | Prune during sync |
+
+## Anti-Patterns
+
+| Anti-Pattern | Better Approach |
+|-------------|----------------|
+| "Document everything" | Document only what changes behavior |
+| "Keep for historical record" | Version control is history |
+| "Might be useful someday" | Add when proven necessary |
+| "Explains the system" | Agents read code for that |
+| "Comprehensive reference" | AGENTS.md is a filter, not docs |
+
+## Good Examples
+
+**Build Commands (High value, agents need immediately):**
+```markdown
+## Build & Test Commands
+bun run build              # Build all packages
+bun run test               # Run all tests
+bun run release:check      # Full CI check
+```
+
+**Project-Specific Convention (Prevents mistakes):**
+```markdown
+## Code Style
+- Imports: Use `.js` extension for local imports (ESM requirement)
+- Paths: Import from `../utils/paths.js` never `./paths`
+```
+
+**Non-Obvious Gotcha (Prevents build failure):**
+```markdown
+## Important Patterns
+Use `ensureDir` from paths.ts — sync despite name
+NEVER use `ensureDirSync` (doesn't exist)
+```
+
+## Bad Examples
+
+**Generic advice (agent already knows):**
+```markdown
+## Best Practices
+- Use meaningful variable names
+- Write unit tests
+- Follow DRY principle
+```
+
+**Describes code (agent can read it):**
+```markdown
+## Architecture
+The FeatureService class manages features. It has methods
+for create, read, update, and delete operations.
+```
+
+**Irrelevant metadata:**
+```markdown
+## Project History
+Created in January 2024 by the platform team.
+Originally built for internal use.
+```
+
+## Verification
+
+Before finalizing AGENTS.md updates:
+
+- [ ] Every entry answers: "What mistake does this prevent?"
+- [ ] No generic advice that applies to all projects
+- [ ] Build/test commands are first
+- [ ] Gotchas section exists and is populated
+- [ ] Total length under 500 lines (800 absolute max)
+- [ ] No entries describing what code does
+- [ ] Fresh agent session would benefit from each entry
+
+## Summary
+
+AGENTS.md is **behavioral memory**, not documentation:
+- Write for agents, optimize for behavior change
+- Signal = prevents mistakes, Noise = describes observables
+- Sync after features, prune quarterly
+- Test: Would agent make a mistake without this entry?
+
+**Quality > quantity. Every line counts.**

package/skills/docker-mastery/SKILL.md

@@ -0,0 +1,346 @@
+---
+name: docker-mastery
+description: "Use when working with Docker containers — debugging container failures, writing Dockerfiles, docker-compose for integration tests, image optimization, or deploying containerized applications"
+---
+
+# Docker Mastery
+
+## Overview
+
+Docker is a **platform for building, shipping, and running applications**, not just isolation.
+
+Agents should think in containers: reproducible environments, declarative dependencies, isolated execution.
+
+**Core principle:** Containers are not virtual machines. They share the kernel but isolate processes, filesystems, and networks.
+
+**Violating the letter of these guidelines is violating the spirit of containerization.**
+
+## The Iron Law
+
+```
+UNDERSTAND THE CONTAINER BEFORE DEBUGGING INSIDE IT
+```
+
+Before exec'ing into a container or adding debug commands:
+1. Check the image (what's installed?)
+2. Check mounts (what host files are visible?)
+3. Check environment variables (what config is passed?)
+4. Check the Dockerfile (how was it built?)
+
+Random debugging inside containers wastes time. Context first, then debug.
+
+## When to Use
+
+Use this skill when working with:
+- **Container build failures** - Dockerfile errors, missing dependencies
+- **Test environment setup** - Reproducible test environments across machines
+- **Integration test orchestration** - Multi-service setups (DB + API + tests)
+- **Dockerfile authoring** - Writing efficient, maintainable Dockerfiles
+- **Image size optimization** - Reducing image size, layer caching
+- **Deployment** - Containerized application deployment
+- **Sandbox debugging** - Issues with Hive's Docker sandbox mode
+
+**Use this ESPECIALLY when:**
+- Tests pass locally but fail in CI (environment mismatch)
+- "Works on my machine" problems
+- Need to test against specific dependency versions
+- Multiple services must coordinate (database + API)
+- Building for production deployment
+
+## Core Concepts
+
+### Images vs Containers
+
+- **Image**: Read-only template (built from Dockerfile)
+- **Container**: Running instance of an image (ephemeral by default)
+
+```bash
+# Build once
+docker build -t myapp:latest .
+
+# Run many times
+docker run --rm myapp:latest
+docker run --rm -e DEBUG=true myapp:latest
+```
+
+**Key insight:** Changes inside containers are lost unless committed or volumes are used.
+
+### Volumes & Mounts
+
+Mount host directories into containers for persistence and code sharing:
+
+```bash
+# Mount current directory to /app in container
+docker run -v $(pwd):/app myapp:latest
+
+# Hive worktrees are mounted automatically
+# Your code edits (via Read/Write/Edit tools) affect the host
+# Container sees the same files at runtime
+```
+
+**How Hive uses this:** Worktree is mounted into container, so file tools work on host, bash commands run in container.
+
+### Multi-Stage Builds
+
+Minimize image size by using multiple FROM statements:
+
+```dockerfile
+# Build stage (large, has compilers)
+FROM node:22 AS builder
+WORKDIR /app
+COPY package.json bun.lockb ./
+RUN bun install
+COPY . .
+RUN bun run build
+
+# Runtime stage (small, production only)
+FROM node:22-slim
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+CMD ["node", "dist/index.js"]
+```
+
+**Result:** Builder tools (TypeScript, bundlers) not included in final image.
+
+### Docker Compose for Multi-Service Setups
+
+Define multiple services in `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+services:
+  db:
+    image: postgres:15
+    environment:
+      POSTGRES_PASSWORD: testpass
+    ports:
+      - "5432:5432"
+  
+  api:
+    build: .
+    environment:
+      DATABASE_URL: postgres://db:5432/testdb
+    depends_on:
+      - db
+    ports:
+      - "3000:3000"
+```
+
+Run with: `docker-compose up -d`
+Teardown with: `docker-compose down`
+
+### Network Modes
+
+- **bridge** (default): Isolated network, containers can talk to each other by name
+- **host**: Container uses host's network directly (no isolation)
+- **none**: No network access
+
+**When to use host mode:** Debugging network issues, accessing host services directly.
+
+## Common Patterns
+
+### Debug a Failing Container
+
+**Problem:** Container exits immediately, logs unclear.
+
+**Pattern:**
+1. Run interactively with shell:
+   ```bash
+   docker run -it --entrypoint sh myapp:latest
+   ```
+2. Inspect filesystem, check if dependencies exist:
+   ```bash
+   ls /app
+   which node
+   cat /etc/os-release
+   ```
+3. Run command manually to see full error:
+   ```bash
+   node dist/index.js
+   ```
+
+### Integration Tests with Docker Compose
+
+**Pattern:**
+1. Define services in `docker-compose.test.yml`
+2. Add wait logic (wait for DB to be ready)
+3. Run tests
+4. Teardown
+
+```yaml
+# docker-compose.test.yml
+services:
+  db:
+    image: postgres:15
+    environment:
+      POSTGRES_PASSWORD: test
+  test:
+    build: .
+    command: bun run test:integration
+    depends_on:
+      - db
+    environment:
+      DATABASE_URL: postgres://postgres:test@db:5432/testdb
+```
+
+```bash
+docker-compose -f docker-compose.test.yml up --abort-on-container-exit
+docker-compose -f docker-compose.test.yml down
+```
+
+### Optimize Dockerfile
+
+**Anti-pattern:**
+```dockerfile
+FROM node:22
+WORKDIR /app
+COPY . .              # Copies everything (including node_modules, .git)
+RUN bun install       # Invalidates cache on any file change
+CMD ["bun", "run", "start"]
+```
+
+**Optimized:**
+```dockerfile
+FROM node:22-slim     # Use slim variant
+WORKDIR /app
+
+# Copy dependency files first (cache layer)
+COPY package.json bun.lockb ./
+RUN bun install --production
+
+# Copy source code (changes frequently)
+COPY src ./src
+COPY tsconfig.json ./
+
+CMD ["bun", "run", "start"]
+```
+
+**Add `.dockerignore`:**
+```
+node_modules
+.git
+.env
+*.log
+dist
+.DS_Store
+```
+
+### Handle Missing Dependencies
+
+**Problem:** Command fails with "not found" in container.
+
+**Pattern:**
+1. Check if dependency is in image:
+   ```bash
+   docker run -it myapp:latest which git
+   ```
+2. If missing, add to Dockerfile:
+   ```dockerfile
+   RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+   ```
+3. Or use a richer base image (e.g., `node:22` instead of `node:22-slim`).
+
+## Hive Sandbox Integration
+
+### How Hive Wraps Commands
+
+When sandbox mode is active (`sandbox: 'docker'` in config):
+1. Hive hook intercepts bash commands before execution
+2. Wraps with `docker run --rm -v <worktree>:/workspace -w /workspace <image> sh -c "<command>"`
+3. Command runs in container, but file edits (Read/Write/Edit) still affect host
+
+**Workers are unaware** — they issue normal bash commands, Hive handles containerization.
+
+### When Host Access is Needed
+
+Some operations MUST run on host:
+- **Git operations** (commit, push, branch) — repo state is on host
+- **Host-level tools** (Docker itself, system config)
+- **Cross-worktree operations** (accessing main repo from worktree)
+
+**Pattern:** Use `HOST:` prefix to escape sandbox:
+```bash
+HOST: git status
+HOST: docker ps
+```
+
+**If you need host access frequently:** Report as blocked and ask user if sandbox should be disabled for this task.
+
+### Persistent vs Ephemeral Containers
+
+**Current (v1.2.0):** Each command runs `docker run --rm` (ephemeral). State does NOT persist.
+
+Example: `npm install lodash` in one command → not available in next command.
+
+**Workaround:** Install dependencies in Dockerfile, not at runtime.
+
+**Future:** `docker exec` will reuse containers, persisting state across commands.
+
+### Auto-Detected Images
+
+Hive detects runtime from project files:
+- `package.json` → `node:22-slim`
+- `requirements.txt` / `pyproject.toml` → `python:3.12-slim`
+- `go.mod` → `golang:1.22-slim`
+- `Cargo.toml` → `rust:1.77-slim`
+- `Dockerfile` → Builds from project Dockerfile
+- Fallback → `ubuntu:24.04`
+
+**Override:** Set `dockerImage` in config (`~/.config/opencode/agent_hive.json`).
+
+## Red Flags - STOP
+
+If you catch yourself:
+- Installing packages on host instead of in Dockerfile
+- Running `docker build` without `.dockerignore` (cache invalidation)
+- Using `latest` tag in production (non-reproducible)
+- Ignoring container exit codes (hides failures)
+- Assuming state persists between `docker run --rm` commands
+- Using absolute host paths in Dockerfile (not portable)
+- Copying secrets into image layers (leaks credentials)
+
+**ALL of these mean: STOP. Review pattern.**
+
+## Anti-Patterns
+
+| Excuse | Reality |
+|--------|---------|
+| "I'll just run it on host" | Container mismatch bugs are worse to debug later. Build happens in container anyway. |
+| "Works in my container, don't need CI" | CI uses different cache state. Always test in CI-like environment. |
+| "I'll optimize the Dockerfile later" | Later never comes. Large images slow down deployments now. |
+| "latest tag is fine for dev" | Dev should match prod. Pin versions or face surprises. |
+| "Don't need .dockerignore, COPY is fast" | Invalidates cache on every file change. Wastes minutes per build. |
+| "Install at runtime, not in image" | Ephemeral containers lose state. Slows down every command. |
+| "Skip depends_on, services start fast" | Race conditions in integration tests. Use wait-for-it or health checks. |
+
+## Verification Before Completion
+
+Before marking Docker work complete:
+
+- [ ] Container runs successfully: `docker run --rm <image> <command>` exits 0
+- [ ] Tests pass inside container (not just on host)
+- [ ] No host pollution (dependencies installed in container, not host)
+- [ ] `.dockerignore` exists if using `COPY . .`
+- [ ] Image tags are pinned (not `latest`) for production
+- [ ] Multi-stage build used if applicable (separate build/runtime)
+- [ ] Integration tests teardown properly (`docker-compose down`)
+
+**If any fail:** Don't claim success. Fix or report blocker.
+
+## Quick Reference
+
+| Task | Command Pattern |
+|------|----------------|
+| **Debug container** | `docker run -it --entrypoint sh <image>` |
+| **Run with mounts** | `docker run -v $(pwd):/app <image>` |
+| **Multi-service tests** | `docker-compose up --abort-on-container-exit` |
+| **Check image contents** | `docker run --rm <image> ls /app` |
+| **Optimize build** | Add `.dockerignore`, use multi-stage, pin versions |
+| **Escape Hive sandbox** | Prefix with `HOST:` (e.g., `HOST: git status`) |
+
+## Related Skills
+
+- **hive_skill:systematic-debugging** - When container behavior is unexpected
+- **hive_skill:test-driven-development** - Write tests that run in containers
+- **hive_skill:verification-before-completion** - Verify tests pass in container before claiming done

package/skills/executing-plans/SKILL.md

@@ -61,8 +61,8 @@ Based on feedback:
 ### Step 6: Complete Development
 
 After all tasks complete and verified:
-- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
-- **REQUIRED SUB-SKILL:** Use hive_skill:finishing-a-development-branch
+- Announce: "I'm using the verification-before-completion skill to complete this work."
+- **REQUIRED SUB-SKILL:** Use hive_skill:verification-before-completion
 - Follow that skill to verify tests, present options, execute choice
 
 ## When to Stop and Ask for Help

package/skills/test-driven-development/SKILL.md

@@ -356,7 +356,7 @@ Never fix bugs without a test.
 
 ## Testing Anti-Patterns
 
-When adding mocks or test utilities, read @testing-anti-patterns.md to avoid common pitfalls:
+When adding mocks or test utilities, avoid common pitfalls:
 - Testing mock behavior instead of real behavior
 - Adding test-only methods to production classes
 - Mocking without understanding dependencies

package/skills/writing-plans/SKILL.md

@@ -111,6 +111,12 @@ Always include **Depends on** for each task. Use `none` to enable parallel start
 **Verify**:
 - [ ] Run: `{command}` → {expected}
 - [ ] {Additional acceptance criteria}
+
+All verification MUST be agent-executable (no human intervention):
+✅ `bun test` → all pass
+✅ `curl -X POST /api/x` → 201
+❌ "User manually tests..."
+❌ "Visually confirm..."
 ````
 
 ## Remember
@@ -119,6 +125,7 @@ Always include **Depends on** for each task. Use `none` to enable parallel start
 - Exact commands with expected output
 - Reference relevant skills with @ syntax
 - DRY, YAGNI, TDD, frequent commits
+- All acceptance criteria must be agent-executable (zero human intervention)
 
 ## Execution Handoff