bobs-workshop 0.3.2 → 3.1.0

package/src/skills/verification/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: verification
+description: Evidence-based verification methodology. SEE code working, do not just trust tests. Use when shipping code, final verification, output validation, evidence gathering. CRITICAL: Evidence before assertions.
+metadata:
+  recommended_for: bob-send
+  category: verification
+---
+
+# Evidence-Based Verification Skill
+
+## Core Philosophy
+
+> "Evidence before assertions. Always."
+
+Never claim code works without **seeing** it work. Tests passing is not enough. You must SEE the output.
+
+## When to Use
+
+Use this skill during the SEND phase or any final verification:
+- Before shipping code
+- When validating implementation works
+- When gathering evidence for review
+- When tests pass but you need runtime proof
+
+## The Three Laws
+
+1. **See it working** - Screenshots, curl responses, CLI output. Actual evidence.
+2. **Human checkpoint** - No auto-shipping. Human reviews evidence and decides.
+3. **Fallback hierarchy** - If primary method fails, try the next method down.
+
+## Project Type Detection
+
+First, detect what type of project you're verifying:
+
+| Detection Pattern | Project Type | Primary Method |
+|-------------------|--------------|----------------|
+| package.json + src/app or pages/ | Web app | Screenshot + test flows |
+| package.json + routes or controllers/ | API | Curl endpoints |
+| Cargo.toml + src/main.rs with clap | CLI | Run commands |
+| pyproject.toml + `__main__.py` | CLI | Run commands |
+| `**/lib.rs` or `setup.py` | Library | Run examples |
+| Dockerfile or docker-compose.yml | Service | Health check + logs |
+
+## Verification Methods
+
+### Web Applications
+
+```bash
+# 1. Start dev server
+npm run dev &
+SERVER_PID=$!
+
+# 2. Wait for server (max 30s)
+sleep 5  # or: until curl -s http://localhost:3000 > /dev/null
+
+# 3. Verify key pages load
+curl -s http://localhost:3000 | head -20
+
+# 4. Check for errors (if browser available, take screenshots)
+
+# 5. Cleanup
+kill $SERVER_PID
+```
+
+**Evidence to capture:**
+- Screenshots of key pages (if browser available)
+- HTML response showing expected content
+- Console errors (if any)
+
+### Browser Verification (Playwright)
+
+For web applications, use Playwright for comprehensive browser verification:
+
+**Capabilities:**
+- **Verification**: Ensure web elements are present and functional
+- **Browsing**: Navigate through web pages to gather information
+- **Web Scraping**: Extract data from websites
+- **Testing**: Run end-to-end tests
+- **Screenshots**: Capture visual evidence of web states
+
+**Usage:**
+When a task involves browser interactions, use Playwright MCP tools:
+```bash
+# Navigate to page
+playwright_browser_navigate(url="http://localhost:3000")
+
+# Take screenshot
+playwright_browser_take_screenshot(filename="homepage.png", type="png")
+
+# Interact with elements
+playwright_browser_click(ref="submit-button")
+
+# Verify element present
+playwright_browser_snapshot()
+```
+
+**Best practices:**
+- Capture screenshots before and after interactions
+- Verify console for errors
+- Test across different viewport sizes
+- Document all browser-based evidence
+
+### APIs
+
+```bash
+# 1. Start server
+npm start &
+sleep 3
+
+# 2. Test key endpoints
+curl -s -w "%{http_code}" http://localhost:3000/api/health
+curl -s -X POST http://localhost:3000/api/[endpoint] \
+  -H "Content-Type: application/json" \
+  -d '{"test": true}'
+
+# 3. Verify response shapes match spec
+```
+
+**Evidence to capture:**
+- Status codes for each endpoint
+- Response bodies (truncated if large)
+- Error responses
+
+### CLI Tools
+
+```bash
+# 1. Test help
+./cli --help
+echo "Exit code: $?"
+
+# 2. Test primary commands
+./cli [command] test-input.txt
+echo "Exit code: $?"
+
+# 3. Test error handling
+./cli [command] nonexistent.txt
+echo "Exit code: $?"  # Should be non-zero
+```
+
+**Evidence to capture:**
+- Command output (stdout)
+- Error output (stderr)
+- Exit codes
+
+### Libraries
+
+```bash
+# 1. Run tests (confirm they pass)
+npm test
+
+# 2. Run examples from documentation
+node examples/basic-usage.js
+
+# 3. Check types compile
+npm run typecheck
+```
+
+**Evidence to capture:**
+- Example output
+- Test coverage summary
+
+## Fallback Hierarchy
+
+If primary method fails, fall back in order:
+
+```
+1. Full runtime (screenshot/curl/run) ─ FAILED
+   │
+   └─► 2. Integration tests ─ FAILED
+       │
+       └─► 3. Unit tests + examples ─ FAILED
+           │
+           └─► 4. Type check + lint only ─ FAILED
+               │
+               └─► 5. Code review only (last resort)
+                   └─► Report: "Unable to verify runtime behavior"
+```
+
+**Always record:**
+- Which method was attempted
+- Why it failed
+- Which fallback was used
+
+## Timeout Handling
+
+**30-second timeout per verification method.**
+
+If method times out:
+1. Kill the process
+2. Log the timeout
+3. Try fallback method
+
+## Evidence Storage
+
+Document evidence in MANUAL Verification Logs:
+
+```markdown
+## ✅ Verification Evidence
+
+### Runtime Verification
+**Project Type**: web
+**Method Used**: curl + HTML inspection
+**Fallback Level**: Primary (no fallback needed)
+
+### Evidence Captured
+1. **Homepage**: Returns 200, contains expected title
+2. **API Health**: /api/health returns {"status": "ok"}
+3. **Login Flow**: Form renders, submits correctly
+
+### Screenshots/Output
+- [Describe what was observed]
+- [Key behaviors verified]
+
+### Result: ✅ VERIFIED
+```
+
+## Red Flags — STOP and Reassess
+
+If you're thinking any of these, you're about to violate the methodology:
+
+- "Tests pass, that's good enough" → **NO. SEE it working.**
+- "I'll verify after shipping" → **NO. Verify BEFORE ship.**
+- "The type checker caught everything" → **NO. Types don't catch runtime issues.**
+- "Screenshot failed but it probably works" → **NO. "Probably" isn't evidence.**
+- "It should work because..." → **NO. SHOW it works.**
+- "Evidence isn't necessary for this change" → **NO. Every change gets verified.**
+
+## Rationalizations to Resist
+
+| Excuse | Reality |
+|--------|---------|
+| "Tests pass" | Tests aren't enough. SEE it working. |
+| "Type checker caught everything" | Types don't catch runtime issues. |
+| "It worked before" | Prove it works NOW. |
+| "Human checkpoint is formality" | Human checkpoint is the gate. |
+| "Code review is enough" | Code review is last resort fallback. |
+| "Tests are flaky, ignore failure" | Flaky tests hide real failures. Fix or accept with caveat. |
+
+## Flaky Test Detection
+
+```
+Test fails?
+├── Re-run failed tests
+├── Pass 2nd time?
+│   └── Yes → Note flakiness, accept with caveat
+└── Fail 2nd time?
+    ├── Run isolated
+    └── Still fail? → Real failure, must fix
+```
+
+## Output Format
+
+When verification completes:
+
+```markdown
+### Verification Summary
+
+| Check | Status | Method | Notes |
+|-------|--------|--------|-------|
+| Build | ✅ | npm run build | No errors |
+| Lint | ✅ | npm run lint | 0 issues |
+| Tests | ✅ | npm test | 47/47 passed |
+| Runtime | ✅ | curl + inspect | Evidence captured |
+
+### Evidence
+- Homepage renders correctly (verified via curl)
+- API returns expected responses
+- No console errors observed
+
+### Result: ✅ ALL CHECKS PASS + EVIDENCE GATHERED
+```
+
+## Anti-Patterns
+
+**Don't do these:**
+
+- Trusting test results without seeing code run
+- Skipping output verification because "tests pass"
+- Proceeding when verification method fails without fallback
+- Modifying code after verification passes (invalidates verification)
+- Ignoring flaky test warnings
+- Auto-approving without human checkpoint
+
+---
+
+**Remember**: You are gathering EVIDENCE. The human decides if it ships. Your job is to SEE the code work and document what you observed.

package/src/tools/background-agent/cancel.ts

@@ -0,0 +1,67 @@
+import { tool } from "@opencode-ai/plugin";
+import type { PluginInput } from "@opencode-ai/plugin";
+import { BackgroundManager } from "./manager.js";
+
+const BackgroundCancelTool: any = tool({
+  description: "Cancel running background agent sessions (cleanup)",
+  args: {
+    task_id: tool.schema.string().optional()
+      .describe("Specific task ID to cancel (omit to cancel all)"),
+    all: tool.schema.boolean().optional()
+      .describe("Cancel all running tasks"),
+  },
+  async execute(args, context) {
+    const ctx = context as unknown as PluginInput & { sessionID: string };
+    const manager = BackgroundManager.getInstance(ctx);
+
+    if (!args.task_id && !args.all) {
+      return "❌ Must specify task_id OR all=true";
+    }
+
+    if (args.all) {
+      const runningTasks = manager.getRunningTasks();
+
+      if (runningTasks.length === 0) {
+        return "📭 No running tasks to cancel";
+      }
+
+      let cancelledCount = 0;
+      for (const task of runningTasks) {
+        if (task.sessionID) {
+          await ctx.client.session.delete({
+            path: { id: task.sessionID },
+          });
+          cancelledCount++;
+        }
+      }
+
+      return `🗑️ Cancelled ${cancelledCount} running tasks`;
+    }
+
+    if (args.task_id) {
+      const task = manager.getTask(args.task_id);
+
+      if (!task) {
+        return `❌ Task ${args.task_id} not found`;
+      }
+
+      if (task.status !== "running") {
+        return `⚠️ Task ${args.task_id} is ${task.status}, cannot cancel`;
+      }
+
+      if (!task.sessionID) {
+        return `❌ Task ${args.task_id} has no session`;
+      }
+
+      await ctx.client.session.delete({
+        path: { id: task.sessionID },
+      });
+
+      return `🗑️ Cancelled task ${args.task_id}`;
+    }
+
+    return "";
+  },
+});
+
+export default BackgroundCancelTool;

package/src/tools/background-agent/concurrency.ts

@@ -0,0 +1,71 @@
+/**
+ * Simple concurrency manager for background agents.
+ * Limits concurrent tasks per model/agent.
+ */
+export class ConcurrencyManager {
+  private counts: Map<string, number> = new Map();
+  private queues: Map<string, Array<() => void>> = new Map();
+  private readonly defaultLimit = 5;
+
+  getConcurrencyLimit(key: string): number {
+    return this.defaultLimit;
+  }
+
+  async acquire(key: string): Promise<void> {
+    const limit = this.getConcurrencyLimit(key);
+    if (limit === Infinity) {
+      return;
+    }
+
+    const current = this.counts.get(key) ?? 0;
+    if (current < limit) {
+      this.counts.set(key, current + 1);
+      return;
+    }
+
+    return new Promise<void>((resolve) => {
+      const queue = this.queues.get(key) ?? [];
+      queue.push(resolve);
+      this.queues.set(key, queue);
+    });
+  }
+
+  release(key: string): void {
+    const limit = this.getConcurrencyLimit(key);
+    if (limit === Infinity) {
+      return;
+    }
+
+    const queue = this.queues.get(key);
+    
+    // Try to hand off to a waiting entry
+    while (queue && queue.length > 0) {
+      const next = queue.shift()!;
+      if (next) {
+        next();
+        return;
+      }
+    }
+
+    // No handoff occurred - decrement count to free slot
+    const current = this.counts.get(key) ?? 0;
+    if (current > 0) {
+      this.counts.set(key, current - 1);
+    }
+  }
+
+  clear(): void {
+    for (const [key] of this.queues) {
+      this.cancelWaiters(key);
+    }
+    this.counts.clear();
+    this.queues.clear();
+  }
+
+  private cancelWaiters(key: string): void {
+    const queue = this.queues.get(key);
+    if (queue) {
+      this.queues.delete(key);
+    }
+  }
+}

package/src/tools/background-agent/index.ts

@@ -0,0 +1,7 @@
+export * from "./types";
+export { BackgroundManager } from "./manager";
+export { ConcurrencyManager } from "./concurrency";
+export { default as background_agent } from "./launch.js";
+export { default as list_background_tasks } from "./list.js";
+export { default as background_output } from "./output.js";
+export { default as background_cancel } from "./cancel.js";

package/src/tools/background-agent/launch.ts

@@ -0,0 +1,39 @@
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
+import type { PluginInput } from "@opencode-ai/plugin";
+import { BackgroundManager } from "./manager.js";
+import type { LaunchInput } from "./types.js";
+
+const BackgroundAgentTool: ToolDefinition = tool({
+  description: "Launch a background agent for LSP code exploration or verification",
+  args: {
+    agent: tool.schema.enum(["alice", "bob", "bob-eng", "bob-rev", "trace", "bob-send"])
+      .describe("Agent name to launch in background"),
+    prompt: tool.schema.string().describe("Prompt for the background agent"),
+    skills: tool.schema.array(tool.schema.string()).optional()
+      .describe("Skills to load from .opencode/skill/"),
+    model: tool.schema.string().optional()
+      .describe("Override model (defaults to agent's configured model)"),
+    manual_path: tool.schema.string().optional()
+      .describe("Path to MANUAL file (for bob/bob-rev agents)"),
+  },
+  async execute(args, context) {
+    const ctx = context as unknown as PluginInput & { sessionID: string };
+    const manager = BackgroundManager.getInstance(ctx);
+
+    const input: LaunchInput = {
+      description: `${args.agent} - ${args.prompt.slice(0, 50)}`,
+      prompt: args.prompt,
+      agent: args.agent,
+      parentSessionID: ctx.sessionID,
+      model: args.model,
+      skills: args.skills,
+      manual_path: args.manual_path,
+    };
+
+    const task = await manager.launch(input);
+    return `✅ Started background ${args.agent} session: ${task.id}`;
+  },
+});
+
+export default BackgroundAgentTool;
+export { BackgroundManager };

package/src/tools/background-agent/list.ts

@@ -0,0 +1,50 @@
+import { tool } from "@opencode-ai/plugin";
+import type { PluginInput } from "@opencode-ai/plugin";
+import { BackgroundManager } from "./index.js";
+
+const ListBackgroundTasksTool = tool({
+  description: "List all running background agent sessions",
+  args: {},
+  async execute(args, context) {
+    const ctx = context as unknown as PluginInput;
+    const manager = BackgroundManager.getInstance(ctx);
+
+    const tasks = manager.getAllTasks();
+
+    if (tasks.length === 0) {
+      return "📭 No background sessions running";
+    }
+
+    const output = tasks.map((t) => {
+      const statusEmoji: Record<string, string> = {
+        pending: "⏳",
+        running: "🔄",
+        completed: "✅",
+        error: "❌",
+        cancelled: "🚫",
+      };
+      const emoji = statusEmoji[t.status] || "❓";
+      const duration = t.startedAt && t.completedAt
+        ? `${Math.round((t.completedAt.getTime() - t.startedAt.getTime()) / 1000)}s`
+        : t.startedAt
+          ? `${Math.round((Date.now() - t.startedAt.getTime()) / 1000)}s (running)`
+          : "-";
+      
+      const skillInfo = t.skills && t.skills.length > 0
+        ? ` [skills: ${t.skills.join(", ")}]`
+        : "";
+
+      return `${emoji} \`${t.id}\` - ${t.description} [${t.status}] ${duration}${skillInfo}`;
+    }).join('\n');
+
+    const runningCount = tasks.filter(t => t.status === "running").length;
+    const completedCount = tasks.filter(t => t.status === "completed").length;
+    const errorCount = tasks.filter(t => t.status === "error").length;
+
+    return `🗂️ Background Sessions (${tasks.length} total):\n` +
+           `  🔄 Running: ${runningCount} | ✅ Completed: ${completedCount} | ❌ Error: ${errorCount}\n\n` +
+           `${output}`;
+  },
+});
+
+export default ListBackgroundTasksTool;