@hung319/opencode-hive 1.3.1

package/skills/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: dispatching-parallel-agents
+description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
+---
+
+# Dispatching Parallel Agents
+
+## Overview
+
+When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
+
+**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
+
+## Prerequisite: Check Runnable Tasks
+
+Before dispatching, use `hive_status()` to get the **runnable** list — tasks whose dependencies are all satisfied.
+
+**Only dispatch tasks that are runnable.** Never start tasks with unmet dependencies.
+
+Only `done` satisfies dependencies (not `blocked`, `failed`, `partial`, `cancelled`).
+
+**Ask the operator first:**
+- Use `question()`: "These tasks are runnable and independent: [list]. Execute in parallel?"
+- Record the decision with `hive_context_write({ name: "execution-decisions", content: "..." })`
+- Proceed only after operator approval
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Multiple failures?" [shape=diamond];
+    "Are they independent?" [shape=diamond];
+    "Single agent investigates all" [shape=box];
+    "One agent per problem domain" [shape=box];
+    "Can they work in parallel?" [shape=diamond];
+    "Sequential agents" [shape=box];
+    "Parallel dispatch" [shape=box];
+
+    "Multiple failures?" -> "Are they independent?" [label="yes"];
+    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
+    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
+    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
+    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
+}
+```
+
+**Use when:**
+- 3+ test files failing with different root causes
+- Multiple subsystems broken independently
+- Each problem can be understood without context from others
+- No shared state between investigations
+
+**Don't use when:**
+- Failures are related (fix one might fix others)
+- Need to understand full system state
+- Agents would interfere with each other
+
+## The Pattern
+
+### 1. Identify Independent Domains
+
+Group failures by what's broken:
+- File A tests: Tool approval flow
+- File B tests: Batch completion behavior
+- File C tests: Abort functionality
+
+Each domain is independent - fixing tool approval doesn't affect abort tests.
+
+### 2. Create Focused Agent Tasks
+
+Each agent gets:
+- **Specific scope:** One test file or subsystem
+- **Clear goal:** Make these tests pass
+- **Constraints:** Don't change other code
+- **Expected output:** Summary of what you found and fixed
+
+### 3. Dispatch in Parallel
+
+```typescript
+// Using Hive tools for parallel execution
+hive_worktree_start({ task: "01-fix-abort-tests" })
+hive_worktree_start({ task: "02-fix-batch-tests" })
+hive_worktree_start({ task: "03-fix-race-condition-tests" })
+// All three run concurrently in isolated worktrees
+```
+
+Parallelize by issuing multiple task() calls in the same assistant message.
+
+```typescript
+task({ subagent_type: 'scout-researcher', prompt: 'Investigate failure A' })
+task({ subagent_type: 'scout-researcher', prompt: 'Investigate failure B' })
+```
+
+### 4. Review and Integrate
+
+When agents return:
+- Read each summary
+- Verify fixes don't conflict
+- Run full test suite
+- Integrate all changes with `hive_merge`
+
+## Agent Prompt Structure
+
+Good agent prompts are:
+1. **Focused** - One clear problem domain
+2. **Self-contained** - All context needed to understand the problem
+3. **Specific about output** - What should the agent return?
+
+```markdown
+Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
+
+1. "should abort tool with partial output capture" - expects 'interrupted at' in message
+2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
+3. "should properly track pendingToolCount" - expects 3 results but gets 0
+
+These are timing/race condition issues. Your task:
+
+1. Read the test file and understand what each test verifies
+2. Identify root cause - timing issues or actual bugs?
+3. Fix by:
+   - Replacing arbitrary timeouts with event-based waiting
+   - Fixing bugs in abort implementation if found
+   - Adjusting test expectations if testing changed behavior
+
+Do NOT just increase timeouts - find the real issue.
+
+Return: Summary of what you found and what you fixed.
+```
+
+## Common Mistakes
+
+**❌ Too broad:** "Fix all the tests" - agent gets lost
+**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
+
+**❌ No context:** "Fix the race condition" - agent doesn't know where
+**✅ Context:** Paste the error messages and test names
+
+**❌ No constraints:** Agent might refactor everything
+**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
+
+**❌ Vague output:** "Fix it" - you don't know what changed
+**✅ Specific:** "Return summary of root cause and changes"
+
+## When NOT to Use
+
+**Related failures:** Fixing one might fix others - investigate together first
+**Need full context:** Understanding requires seeing entire system
+**Exploratory debugging:** You don't know what's broken yet
+**Shared state:** Agents would interfere (editing same files, using same resources)
+
+## Real Example from Session
+
+**Scenario:** 6 test failures across 3 files after major refactoring
+
+**Failures:**
+- agent-tool-abort.test.ts: 3 failures (timing issues)
+- batch-completion-behavior.test.ts: 2 failures (tools not executing)
+- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
+
+**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
+
+**Dispatch:**
+```
+Agent 1 → Fix agent-tool-abort.test.ts
+Agent 2 → Fix batch-completion-behavior.test.ts
+Agent 3 → Fix tool-approval-race-conditions.test.ts
+```
+
+**Results:**
+- Agent 1: Replaced timeouts with event-based waiting
+- Agent 2: Fixed event structure bug (threadId in wrong place)
+- Agent 3: Added wait for async tool execution to complete
+
+**Integration:** All fixes independent, no conflicts, full suite green
+
+**Time saved:** 3 problems solved in parallel vs sequentially
+
+## Key Benefits
+
+1. **Parallelization** - Multiple investigations happen simultaneously
+2. **Focus** - Each agent has narrow scope, less context to track
+3. **Independence** - Agents don't interfere with each other
+4. **Speed** - 3 problems solved in time of 1
+
+## Verification
+
+After agents return:
+1. **Review each summary** - Understand what changed
+2. **Check for conflicts** - Did agents edit same code?
+3. **Run full suite** - Verify all fixes work together
+4. **Spot check** - Agents can make systematic errors
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- 6 failures across 3 files
+- 3 agents dispatched in parallel
+- All investigations completed concurrently
+- All fixes integrated successfully
+- Zero conflicts between agent changes

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

@@ -0,0 +1,92 @@
+---
+name: executing-plans
+description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+---
+
+# Executing Plans
+
+## Overview
+
+Load plan, review critically, execute tasks in batches, report for review between batches.
+
+**Core principle:** Batch execution with checkpoints for architect review.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+## The Process
+
+### Step 1: Load and Review Plan
+1. Read plan file
+2. Review critically - identify any questions or concerns about the plan
+3. If concerns: Raise them with your human partner before starting
+4. If no concerns: Create TodoWrite and proceed
+
+### Step 2: Identify Runnable Tasks
+
+Use `hive_status()` to get the **runnable** list — tasks with all dependencies satisfied.
+
+Only `done` satisfies dependencies (not `blocked`, `failed`, `partial`, `cancelled`).
+
+**When 2+ tasks are runnable:**
+- **Ask the operator** via `question()`: "Multiple tasks are runnable: [list]. Run in parallel, sequential, or a specific subset?"
+- Record the decision with `hive_context_write({ name: "execution-decisions", content: "..." })` for future reference
+
+**When 1 task is runnable:** Proceed directly.
+
+### Step 3: Execute Batch
+
+For each task in the batch:
+1. Mark as in_progress via `hive_worktree_start()`
+2. Follow each step exactly (plan has bite-sized steps)
+3. Run verifications as specified
+4. Mark as completed
+
+### Step 4: Report
+When batch complete:
+- Show what was implemented
+- Show verification output
+- Say: "Ready for feedback."
+
+### Step 4.5: Post-Batch Hygienic Review
+
+After the batch report, ask the operator if they want a Hygienic code review for the batch.
+If yes, run `task({ subagent_type: "hygienic", prompt: "Review implementation changes from the latest batch." })` and apply feedback before starting the next batch.
+
+### Step 5: Continue
+Based on feedback:
+- Apply changes if needed
+- Execute next batch
+- Repeat until complete
+
+### Step 6: Complete Development
+
+After all tasks complete and verified:
+- 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
+
+**STOP executing immediately when:**
+- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
+- Plan has critical gaps preventing starting
+- You don't understand an instruction
+- Verification fails repeatedly
+
+**Ask for clarification rather than guessing.**
+
+## When to Revisit Earlier Steps
+
+**Return to Review (Step 1) when:**
+- Partner updates the plan based on your feedback
+- Fundamental approach needs rethinking
+
+**Don't force through blockers** - stop and ask.
+
+## Remember
+- Review plan critically first
+- Follow plan steps exactly
+- Don't skip verifications
+- Reference skills when plan says to
+- Between batches: just report and wait
+- Stop when blocked, don't guess