opencodekit 0.15.21 → 0.16.1

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

@@ -1,609 +0,0 @@
----
-description: Implement a bead - load context, delegate research, make changes, verify
-argument-hint: "<bead-id> [--parallel] [--swarm]"
-agent: build
----
-
-# Implement: $ARGUMENTS
-
-You're implementing a tracked task. Stay focused, delegate research, verify as you go, hand off if you hit limits.
-
-## Parse Arguments
-
-| Argument     | Default  | Description                               |
-| ------------ | -------- | ----------------------------------------- |
-| `<bead-id>`  | required | The bead to implement                     |
-| `--parallel` | false    | Run aggressive parallel subagent research |
-| `--swarm`    | false    | Use swarm coordination for parallel tasks |
-
-## First: Load Skills & Context
-
-```typescript
-skill({ name: "beads" });
-skill({ name: "test-driven-development" });
-skill({ name: "verification-before-completion" });
-skill({ name: "swarm-coordination" }); // For swarm mode with Kimi K2.5 PARL patterns
-skill({ name: "beads-bridge" }); // For cross-session todo persistence
-```
-
-Get the task details and check hierarchy:
-
-```bash
-bd show $ARGUMENTS
-bd dep tree $ARGUMENTS 2>/dev/null || echo "No dependencies"
-bd list --status=in_progress  # See what else is active
-```
-
-Check for messages from other agents:
-
-```bash
-bd inbox --unread -n 5
-```
-
-## Check Hierarchy Position
-
-Identify where this task sits:
-
-| Type      | Action                                      |
-| --------- | ------------------------------------------- |
-| `epic`    | Don't implement directly - work on subtasks |
-| `task`    | May implement or delegate to subtasks       |
-| `subtask` | Implement directly - this is leaf work      |
-
-**If this is an epic with subtasks:**
-
-```bash
-bd ready --json | grep -q "$ARGUMENTS"
-```
-
-→ Work on ready subtasks instead: `/implement <subtask-id>`
-
-**Or use SWARM MODE for parallel execution (recommended for 3+ subtasks):**
-
-## Swarm Mode Execution (--swarm flag or auto-detect with PARL)
-
-When the task has 3+ independent subtasks, use Kimi K2.5 PARL swarm coordination:
-
-### Step 0a: Task Analysis (Anti-Serial-Collapse)
-
-```typescript
-// 1. Analyze the actual task
-const subtasks = await getSubtasks($ARGUMENTS); // Get all subtask IDs
-const files = await getFilesForSubtasks(subtasks); // Detect relevant files
-
-const analysis = await swarm_plan({
-  operation: "analyze",
-  task: "Implement " + $ARGUMENTS + " with " + subtasks.length + " subtasks",
-  files: files.join(","),
-});
-
-// 2. Check for serial collapse
-const check = await swarm_plan({
-  operation: "check",
-  task: "Implement " + $ARGUMENTS,
-  files: String(subtasks.length),
-  recommended_agents: analysis.classification.recommended_agents,
-});
-
-if (check.serial_collapse_detected) {
-  console.log(`⚠️ Serial collapse detected: ${check.warning_signs.join(", ")}`);
-  console.log(`✓ Adjusting to ${check.suggested_agents} agents`);
-}
-
-// 3. Use classification to guide swarm setup
-const { type, recommended_agents, phases } = analysis.classification;
-console.log(`Task type: ${type}, Agents: ${recommended_agents}, Phases: ${phases.length}`);
-```
-
-### Step 1: Sync Beads to OpenCode Todos
-
-Before spawning workers, sync beads state to make it visible to subagents:
-
-```typescript
-// Push beads state to OpenCode todos
-beads_sync({ operation: "push" });
-```
-
-### Step 2: Create Delegation Packets
-
-For each parallelizable subtask:
-
-```typescript
-swarm_delegate({
-  bead_id: "<subtask-id>",
-  title: "Subtask title from bead",
-  expected_outcome: "Measurable completion criteria",
-  required_tools: "read, grep, lsp, edit, bash",
-  must_do: "LSP before edits, run project verification commands",
-  must_not_do: "No new deps, don't edit files outside scope",
-  acceptance_checks: "typecheck: npm run typecheck, lint: npm run lint, test: npm test",
-  context: "Part of epic $ARGUMENTS. See spec for requirements.",
-  write: true,
-});
-```
-
-### Step 3: Reserve File Sets
-
-Prevent conflicts between workers:
-
-```bash
-# Reserve files for each worker
-bd reserve "src/domain-a/*" --reason "swarm: subtask-1"
-bd reserve "src/domain-b/*" --reason "swarm: subtask-2"
-```
-
-### Step 4: Spawn Worker Swarm
-
-Launch all workers in parallel (multiple Task calls in one message):
-
-```typescript
-// All run simultaneously
-Task({
-  subagent_type: "general",
-  description: "Execute subtask-1",
-  prompt: `Execute bead <subtask-1>: <title>
-
-## Delegation
-Read: .beads/artifacts/<subtask-1>/delegation.md
-
-## Coordination
-Team: $ARGUMENTS-swarm
-Worker: worker-1
-
-## Protocol
-1. Read delegation packet FIRST
-2. Report START: swarm-monitor({ operation: "progress_update", team_name: "$ARGUMENTS-swarm", worker_id: "worker-<N>", phase: "<phase>", progress: 0, status: "working" })
-3. Execute following MUST DO / avoiding MUST NOT DO
-4. Report PROGRESS (every 25%): swarm-monitor({ operation: "progress_update", ...progress: 25/50/75, file: "current-file.ts" })
-5. Run ALL acceptance checks
-6. Report DONE: swarm-monitor({ operation: "progress_update", ...progress: 100, status: "completed" })
-
-Return format:
-- DONE: <summary of completed work>
-- ERROR: <issue description> (if failed)`,
-});
-
-Task({
-  subagent_type: "general",
-  description: "Execute subtask-2",
-  prompt: `Execute bead <subtask-2>: <title>
-  ...same pattern, different worker name...`,
-});
-
-Task({
-  subagent_type: "general",
-  description: "Execute subtask-3",
-  prompt: `Execute bead <subtask-3>: <title>
-  ...same pattern, different worker name...`,
-});
-// Results available when all complete
-```
-
-### Step 5: Monitor Progress (Real-time TUI)
-
-Monitor with beautiful block UI:
-
-```typescript
-// Render beautiful TUI block
-const ui = await swarm_monitor({
-  operation: "render_block",
-  team_name: "$ARGUMENTS-swarm",
-});
-console.log(ui); // Markdown block with tables, emojis, progress
-
-// Check detailed status
-const status = await swarm_monitor({
-  operation: "status",
-  team_name: "$ARGUMENTS-swarm",
-});
-const stats = JSON.parse(status).summary;
-```
-
-### Step 6: Handle Worker Results
-
-Task tool returns results when all workers complete. Parse each result:
-
-| Result Type | Detection                | Action                                 |
-| ----------- | ------------------------ | -------------------------------------- |
-| DONE        | Result contains "DONE:"  | Mark subtask complete, check progress  |
-| ERROR       | Result contains "ERROR:" | Analyze, fix locally or respawn worker |
-
-```typescript
-// Results are returned directly from Task tool
-// Each task returns its completion status
-// Example: "DONE: Implemented auth endpoint with JWT validation"
-// Example: "ERROR: TypeScript errors in user.ts line 42"
-```
-
-### Step 7: Final Verification
-
-After all workers complete:
-
-```bash
-# Full verification suite
-npm run typecheck && npm run lint && npm test
-```
-
-### Step 8: Close Epic & Cleanup
-
-```typescript
-// Clear swarm data
-await swarm_monitor({
-  operation: "clear",
-  team_name: "$ARGUMENTS-swarm",
-});
-
-// Sync completed todos back to beads
-beads_sync({ operation: "pull" });
-```
-
-```bash
-# Close the epic
-bd close $ARGUMENTS --reason "Swarm completed all subtasks: <summary>"
-```
-
-**Or execute READY subtasks sequentially (non-swarm mode):**
-
-```typescript
-// Get all READY subtasks for this epic
-// bd list --parent $ARGUMENTS --status=open --json
-
-// Fire all READY subtasks in parallel using Task tool
-// Multiple Task calls in one message run simultaneously
-Task({
-  subagent_type: "general",
-  description: "Execute subtask 1",
-  prompt: `Execute bd-subtask1: [Subtask description]
-
-    Context: Part of epic $ARGUMENTS
-
-    Requirements:
-    - Complete all work items
-    - Run verification commands
-    - Commit with bead ID in message
-    - Close the bead when done: bd close bd-subtask1 --reason "Completed: ..."`,
-});
-
-Task({
-  subagent_type: "general",
-  description: "Execute subtask 2",
-  prompt: `Execute bd-subtask2: [Subtask description]
-    ...same pattern...`,
-});
-
-// Results available immediately after all complete
-// Check newly unblocked subtasks
-bd ready  // → Next wave now READY
-```
-
-## Git State Check
-
-```bash
-git status --porcelain
-git branch --show-current
-```
-
-If dirty, ask whether to stash, commit, or continue.
-
-Create a branch if not already on one for this task:
-
-```bash
-# Get current branch (parent branch)
-PARENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
-
-# Get task title for readable branch name
-BEAD_INFO=$(bd show $ARGUMENTS --json 2>/dev/null)
-BEAD_TITLE=$(echo "$BEAD_INFO" | jq -r '.title // ""' | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | cut -c1-40)
-BEAD_TYPE=$(echo "$BEAD_INFO" | jq -r '.type // "task"')
-
-# Map bead type to branch prefix
-case "$BEAD_TYPE" in
-  "bug") PREFIX="fix" ;;
-  "feature"|"epic") PREFIX="feat" ;;
-  "refactor") PREFIX="refactor" ;;
-  *) PREFIX="feat" ;;
-esac
-
-# Create branch: <parent>/<type>/<bead-id>-<description>
-BRANCH_NAME="${PARENT_BRANCH}/${PREFIX}/$ARGUMENTS-${BEAD_TITLE}"
-git checkout -b "$BRANCH_NAME" 2>/dev/null || echo "Already on branch"
-```
-
-Mark the task in progress (if not already):
-
-```bash
-bd update $ARGUMENTS --status in_progress
-```
-
-## Load Artifacts
-
-Check what context exists:
-
-```bash
-ls .beads/artifacts/$ARGUMENTS/ 2>/dev/null || echo "No artifacts"
-```
-
-| Found         | Action                               |
-| ------------- | ------------------------------------ |
-| `plan.md`     | Follow it step by step               |
-| `spec.md`     | Implement directly from requirements |
-| `research.md` | Use findings to guide implementation |
-| Nothing       | Work from bead description           |
-
-Check for previous session work:
-
-```typescript
-search_session({ query: "$ARGUMENTS" });
-read_session({ session_reference: "last" });
-```
-
-## Load Related Memory (Semantic Search)
-
-First, get a quick codebase overview:
-
-```typescript
-// Quick overview of relevant directories
-repo - map({ path: "src", format: "compact", maxDepth: 3 });
-```
-
-Then search for relevant patterns and learnings:
-
-```typescript
-// Find similar past work
-memory -
-  search({
-    query: "[task description from bead]",
-    mode: "semantic",
-    limit: 3,
-  });
-
-// Find related gotchas and patterns
-memory -
-  search({
-    query: "[technology/domain keywords]",
-    mode: "semantic",
-    type: "observation",
-    limit: 3,
-  });
-```
-
-**Review findings before implementation.** Past observations may contain:
-
-- Gotchas to avoid (save debugging time)
-- Patterns that worked well (reuse them)
-- Decisions already made (don't re-decide)
-
-If memory search fails (Ollama not running), continue without it.
-
-## Parallel Subagent Research (if --parallel or complex task)
-
-**Delegation Pattern: Parallel Task Calls**
-
-For complex tasks, launch research subagents in parallel before diving into code.
-Multiple Task calls in a single message run simultaneously:
-
-```typescript
-// Codebase patterns - find similar implementations
-Task({
-  subagent_type: "explore",
-  description: "Find codebase patterns",
-  prompt: `For implementing $ARGUMENTS, find:
-    1. Similar patterns in this codebase (grep)
-    2. Related test files and testing patterns
-    3. Configuration or setup requirements
-    Return: File paths, code patterns, test approach`,
-});
-
-// External best practices - library docs
-Task({
-  subagent_type: "scout",
-  description: "Research best practices",
-  prompt: `Research best practices for $ARGUMENTS:
-    1. Official documentation for libraries involved
-    2. Common implementation patterns (Context7, GitHub)
-    3. Known pitfalls or gotchas
-    Return: Code examples, API usage, warnings`,
-});
-
-// Both run in parallel, results available immediately
-```
-
-**Subagent Tools:**
-| Tool | Purpose |
-| ---- | ------- |
-| `Task` | Delegate to subagent, runs in parallel when multiple calls in one message |
-
-**Subagent Rules:**
-| Agent | Use For | Can Do | Cannot Do |
-| -------- | ------------------------------ | ---------------- | ---------------- |
-| `explore`| Codebase search, patterns | Read, grep, glob | Edit, bd sync |
-| `scout` | External docs, best practices | Fetch, search | Edit, bd sync |
-| `review` | Code review, debugging | Read, analyze | Edit, bd sync |
-| `plan` | Architecture, decomposition | Read, plan | Edit, bd sync |
-
-**You (build agent) are the leader:**
-
-- Subagents return results to you
-- Only you modify files and update beads
-- Integrate subagent findings into your implementation
-
-## Estimate Your Budget
-
-Look at the task complexity and set limits:
-
-| Size   | Tool Calls | Scope                               |
-| ------ | ---------- | ----------------------------------- |
-| Small  | ~10        | Simple change, one file, clear path |
-| Medium | ~30        | Multiple files, some exploration    |
-| Large  | ~100       | Cross-cutting, needs checkpoints    |
-| XL     | Stop       | Decompose into subtasks first       |
-
-**If XL detected:**
-
-```
-This task is too large for a single session.
-Recommend: /plan $ARGUMENTS --create-beads
-```
-
-If you hit 80% of budget without finishing, create a handoff. Don't push past limits.
-
-## Lock Files Before Editing
-
-For shared files or multi-agent coordination:
-
-```bash
-bd reserve src/file-to-edit.ts --ttl 600
-```
-
-Release after completing edits:
-
-```bash
-bd release src/file-to-edit.ts
-```
-
-## Do The Work
-
-Detect project type and know your verification commands:
-
-```bash
-ls package.json Cargo.toml pyproject.toml go.mod Makefile 2>/dev/null
-```
-
-| Project | Test Command    | Lint Command                        |
-| ------- | --------------- | ----------------------------------- |
-| Node/TS | `npm test`      | `npm run lint && npm run typecheck` |
-| Rust    | `cargo test`    | `cargo clippy -- -D warnings`       |
-| Python  | `pytest`        | `ruff check . && mypy .`            |
-| Go      | `go test ./...` | `golangci-lint run`                 |
-
-**Rules while implementing:**
-
-1. **Read before edit.** Always.
-2. **Run verification** after each logical change
-3. **Delegate when stuck**: If blocked on understanding, launch `@explore` or `@scout`
-4. **Checkpoint** after significant progress: `git commit -m "WIP: $ARGUMENTS - [step]"`
-5. **Create child beads** for discovered subtasks:
-   ```bash
-   bd create "Discovered: [subtask]" -t subtask -p 2
-   bd dep add <new-id> $ARGUMENTS --type blocks
-   ```
-
-**Progress tracking** - every 10 tool calls:
-
-- Am I on track?
-- Should I checkpoint?
-- Am I approaching budget?
-- Need to delegate research?
-
-## Subtask Coordination (if parent task)
-
-If implementing a task with subtasks:
-
-```bash
-# Check which subtasks are ready
-bd ready --json | jq '.[] | select(.parent == "$ARGUMENTS")'
-
-# Work on ready subtasks in order
-# When subtask done:
-bd close <subtask-id> --reason "Completed: description"
-
-# Check if parent can close
-bd dep tree $ARGUMENTS
-```
-
-**Pattern: Complete subtasks before parent**
-
-## Before Claiming Done
-
-Verify against success criteria in the spec:
-
-```bash
-cat .beads/artifacts/$ARGUMENTS/spec.md | grep -A 20 "Success Criteria" || \
-cat .beads/artifacts/$ARGUMENTS/spec.md | grep -A 20 "Acceptance Criteria"
-```
-
-Run each verification command. All must pass. No exceptions.
-
-Run the full test suite one more time:
-
-```bash
-# Whatever your project uses
-npm test && npm run typecheck
-```
-
-## Complete
-
-If all gates pass, show what was done:
-
-```bash
-git add -A
-git status
-git diff --cached --stat
-```
-
-**Use question tool to get commit decision:**
-
-```typescript
-question({
-  questions: [
-    {
-      header: "Commit",
-      question: "Implementation Complete: $ARGUMENTS. What should I do next?",
-      options: [
-        {
-          label: "Commit changes (Recommended)",
-          description: "Git commit and bd sync",
-        },
-        {
-          label: "Show diff first",
-          description: "Review changes before committing",
-        },
-        {
-          label: "Skip commit",
-          description: "I'll review and commit manually",
-        },
-      ],
-    },
-  ],
-});
-```
-
-If user confirms:
-
-```bash
-git commit -m "$ARGUMENTS: [summary]"
-bd sync
-```
-
-Suggest next step based on hierarchy:
-
-| Situation            | Next Command                |
-| -------------------- | --------------------------- |
-| Subtask done         | `/implement <next-subtask>` |
-| All subtasks done    | `/finish <parent-task>`     |
-| Task done, no parent | `/finish $ARGUMENTS`        |
-| Need PR              | `/pr $ARGUMENTS`            |
-
-```
-Next: [recommended command]
-```
-
-If gates fail, fix them. Don't proceed with broken code.
-
-## If You Can't Finish
-
-Hit budget limit or context getting too large? Create a handoff:
-
-```
-/handoff $ARGUMENTS "Stopped at [step]. Next: [what to do]"
-```
-
-Then start a fresh session. Don't grind past diminishing returns.
-
-## Release File Locks
-
-Before ending session:
-
-```bash
-bd release --all  # Release all your locks
-```