opencode-starterkit 1.0.1

package/baseline/skill/agent-teams/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: agent-teams
+description: >
+  Use when working with Claude Code-style agent teams for parallel research, review, competing hypotheses,
+  or any task that benefits from multiple agents working simultaneously under a lead coordinator.
+  Covers team configuration, task distribution, coordination patterns, and best practices.
+version: "1.0.0"
+license: MIT
+tags: [agent-coordination, workflow]
+dependencies: []
+---
+
+# Agent Teams - Multi-Agent Team Coordination
+
+> **Replaces** single-agent sequential work when tasks benefit from parallel research, review, or competing hypotheses
+
+## When to Use
+
+- Parallel research, review, or competing approaches that need coordination
+- Tasks benefit from shared findings and a lead coordinating teammates
+
+## When NOT to Use
+
+- Single-agent tasks or tightly coupled edits where coordination overhead is wasteful
+- Simple parallel work that can use fire-and-forget subagents instead
+
+## Overview
+
+**Agent Teams = Lead + Teammates + Shared Task List + Messaging**
+
+- **Lead agent**: Coordinates the team - distributes tasks, monitors progress, synthesizes results
+- **Teammates**: Execute tasks independently but can message each other and the lead
+- **Task list**: Shared work queue that the lead manages
+- **Messaging**: Bidirectional communication between lead and teammates
+
+## When to Use Agent Teams vs Subagents
+
+| Criteria              | Agent Teams                            | Subagents (Task tool)               |
+| --------------------- | -------------------------------------- | ----------------------------------- |
+| **Coordination**      | Lead coordinates, teammates message    | Fire-and-forget, results return     |
+| **Communication**     | Bidirectional messaging                | One-way (result only)               |
+| **Task reassignment** | Dynamic - lead can reassign            | Fixed - each subagent does its task |
+| **Context sharing**   | Shared through lead                    | Independent contexts                |
+| **Best for**          | Research, review, competing approaches | Independent implementation tasks    |
+| **Overhead**          | Higher - coordination cost             | Lower - no coordination             |
+
+### Decision Matrix
+
+```
+Need coordination between workers?  → Agent Teams
+Workers are fully independent?      → Subagents (Task tool)
+Need competing hypotheses?          → Agent Teams
+Need shared findings?               → Agent Teams
+Simple parallel execution?          → Subagents (Task tool)
+```
+
+### Parallel Skill Selection
+
+| Scenario                                    | Use This Skill              |
+| ------------------------------------------- | --------------------------- |
+| 3+ independent bug investigations           | dispatching-parallel-agents |
+| Coordinated team (research + review + impl) | agent-teams                 |
+| Large plan with dependency graph            | swarm-coordination          |
+| 2 independent tasks                         | Just use 2 Task() calls     |
+
+## When to Use
+
+- **Parallel research**: Multiple agents researching different aspects of a problem
+- **Code review**: Multiple reviewers examining different files/concerns
+- **Competing hypotheses**: Agents try different approaches, best one wins
+- **Large refactors**: Agents handle different subsystems with coordination
+- **Architecture exploration**: Agents explore different design options simultaneously
+
+## When NOT to Use
+
+- Single-agent tasks (overhead not worth it)
+- Tightly coupled work where agents would constantly block each other
+- Tasks under 3 independent units of work
+- Simple file edits with no research needed
+
+## Team Configuration Patterns
+
+### Pattern 1: Research Team
+
+```
+Lead: build agent
+├── Teammate 1 (explore): Search codebase for existing patterns
+├── Teammate 2 (scout): Research external docs and best practices
+└── Teammate 3 (review): Analyze current implementation for issues
+```
+
+**Use when**: Entering unfamiliar territory, evaluating new libraries, understanding complex systems.
+
+### Pattern 2: Review Team
+
+```
+Lead: build agent
+├── Teammate 1 (review): Security audit
+├── Teammate 2 (review): Performance review
+└── Teammate 3 (review): Architecture review
+```
+
+**Use when**: Pre-merge review of significant features, security-sensitive changes.
+
+### Pattern 3: Competing Approaches
+
+```
+Lead: build agent
+├── Teammate 1 (general): Implement approach A
+├── Teammate 2 (general): Implement approach B
+└── Teammate 3 (general): Implement approach C
+```
+
+**Use when**: Multiple valid solutions exist and you need to compare empirically.
+
+### Pattern 4: Subsystem Team
+
+```
+Lead: build agent
+├── Teammate 1 (general): Handle frontend changes
+├── Teammate 2 (general): Handle backend changes
+└── Teammate 3 (general): Handle database migrations
+```
+
+**Use when**: Large features spanning multiple subsystems with clear boundaries.
+
+## Best Practices
+
+### Task Distribution
+
+1. **5-6 tasks per teammate maximum** - More than this degrades quality
+2. **Clear boundaries** - Each teammate should own distinct files/modules
+3. **Avoid file conflicts** - Never assign the same file to multiple teammates
+4. **Include verification** - Each task should include its own verification step
+
+### Coordination
+
+1. **Lead synthesizes** - Don't let teammates make final decisions; lead integrates
+2. **Regular check-ins** - Lead should review intermediate results, not just final
+3. **Fail fast** - If a teammate hits a blocker, escalate to lead immediately
+4. **Shared conventions** - Establish naming, formatting, and style before dispatching
+
+### Communication
+
+1. **Task descriptions should be self-contained** - Teammate shouldn't need to ask clarifying questions
+2. **Include context** - What files to read, what patterns to follow, what constraints exist
+3. **Specify output format** - What should the teammate report back?
+4. **Include acceptance criteria** - How does the lead know the task is done?
+
+## Implementation with OpenCode
+
+### Using the Task Tool (Current)
+
+```typescript
+// Spawn research team
+const codebaseAnalysis = Task({
+  subagent_type: "explore",
+  description: "Analyze auth patterns",
+  prompt: `Research authentication patterns in this codebase:
+    1. Find all auth-related files
+    2. Map the auth flow
+    3. Identify potential security issues
+    Report back: file list, flow diagram, issues found`,
+});
+
+const externalResearch = Task({
+  subagent_type: "scout",
+  description: "Research JWT best practices",
+  prompt: `Research current JWT best practices:
+    1. Token rotation patterns
+    2. Refresh token security
+    3. Common vulnerabilities
+    Report back: recommended patterns with code examples`,
+});
+
+const codeReview = Task({
+  subagent_type: "review",
+  description: "Review auth security",
+  prompt: `Security review of auth implementation:
+    1. Check token storage
+    2. Verify CSRF protection
+    3. Audit session management
+    Report back: vulnerabilities found with severity ratings`,
+});
+
+// Lead synthesizes all results into unified recommendation
+```
+
+### Using Swarm Coordination (Advanced)
+
+For more structured parallel work, combine with the `swarm-coordination` skill:
+
+```typescript
+// Load swarm for structured coordination
+skill({ name: "swarm-coordination" });
+
+// Analyze and plan
+swarm({ op: "plan", task: "Implement auth overhaul across 3 subsystems" });
+
+// Create delegation packets
+swarm({
+  op: "delegate",
+  bead_id: "auth-frontend",
+  title: "Frontend auth components",
+  outcome: "All auth forms and guards updated",
+  must_do: "Follow existing component patterns, run component tests",
+  must_not: "Don't modify API contracts, don't add new dependencies",
+});
+```
+
+## Anti-Patterns
+
+### ❌ Too Many Teammates
+
+```
+Lead
+├── T1: Button component     ← Too granular
+├── T2: Input component      ← Too granular
+├── T3: Form component       ← Too granular
+├── T4: Modal component      ← Too granular
+├── T5: Toast component      ← Too granular
+├── T6: Dialog component     ← Too granular
+├── T7: Dropdown component   ← Too granular
+└── T8: Tabs component       ← Too granular
+```
+
+**Fix**: Group related work. 2-3 teammates handling related components each.
+
+### ❌ Overlapping File Ownership
+
+```
+T1: Refactor auth service     ← Both touch auth.ts!
+T2: Add new auth endpoint     ← Both touch auth.ts!
+```
+
+**Fix**: One teammate owns auth.ts changes. The other waits or works on different files.
+
+### ❌ Missing Context
+
+```
+Task({ prompt: "Fix the auth bug" })  ← Which bug? What file? What behavior?
+```
+
+**Fix**: Include file paths, error messages, expected vs actual behavior, and reproduction steps.
+
+### ❌ No Verification
+
+```
+Task({ prompt: "Implement feature X" })  ← No way to verify success
+```
+
+**Fix**: Include acceptance criteria: "Run `npm test auth`, ensure all pass. Run `npm run typecheck`."
+
+## Checklist
+
+Before dispatching a team:
+
+- [ ] Identified 3+ independent tasks (otherwise use single agent)
+- [ ] Each task has clear file ownership (no overlaps)
+- [ ] Each task has self-contained context (files, patterns, constraints)
+- [ ] Each task has acceptance criteria (verification commands)
+- [ ] Lead has a synthesis plan (how to integrate results)
+- [ ] Tasks are sized appropriately (5-6 per teammate max)
+
+## See Also
+
+- `dispatching-parallel-agents` — for independent debugging-focused parallel investigations
+- `swarm-coordination` — for dependency-aware large-plan execution

package/baseline/skill/augment-context-engine/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: augment-context-engine
+description: Semantic codebase search via Augment Context Engine MCP. Use when you need to understand code relationships, find relevant implementations, or explore unfamiliar codebases beyond keyword matching.
+version: 1.0.0
+tags: [research, context]
+dependencies: []
+---
+
+# Augment Context Engine (MCP)
+
+## When to Use
+
+- When you need semantic search to understand code relationships or find implementations beyond keyword matching.
+
+## When NOT to Use
+
+- When exact string matching or known file paths can be handled by grep/read/LSP locally.
+
+
+## Available Tools
+
+- `augment_code_search` - Semantic search across indexed GitHub repositories
+
+**Parameters:**
+
+- `repo_owner` (string, required) - GitHub org or username (e.g. `"augmentcode"`)
+- `repo_name` (string, required) - Repository name (e.g. `"test-repo"`)
+- `query` (string, required) - Natural language description of what you're looking for
+- `branch` (string, optional) - Branch to search (defaults to `"main"`)
+- `max_results` (integer, optional) - Max code snippets to return (defaults to 5)
+
+## Quick Start
+
+```
+# Search a GitHub repo for authentication code
+skill_mcp(skill_name="augment-context-engine", tool_name="augment_code_search", arguments='{"repo_owner": "myorg", "repo_name": "myapp", "query": "authentication middleware that validates JWT tokens"}')
+
+# Search a specific branch with more results
+skill_mcp(skill_name="augment-context-engine", tool_name="augment_code_search", arguments='{"repo_owner": "myorg", "repo_name": "myapp", "query": "error handling patterns", "branch": "develop", "max_results": 10}')
+```
+
+> **Tip:** Get `repo_owner` and `repo_name` from git: `git remote get-url origin`
+
+## Setup
+
+### 1. Install the Augment GitHub App
+
+Install at [github.com/apps/augmentcode](https://github.com/apps/augmentcode/installations/new) and grant access to the repos you want to index.
+
+### 2. Add the remote server
+
+The skill's `mcp.json` uses `mcp-remote` to bridge the remote API via stdio.
+
+For global access, add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "auggie": {
+      "type": "remote",
+      "url": "https://api.augmentcode.com/mcp",
+      "enabled": true
+    }
+  }
+}
+```
+
+### 3. Authenticate
+
+Sign in at [app.augmentcode.com](https://app.augmentcode.com) when prompted by `mcp-remote` on first use.
+
+## Query Tips
+
+Good queries (natural language, conceptual):
+
+- `"function that handles user authentication"`
+- `"database connection setup code"`
+- `"tests for the payment processing module"`
+
+Bad queries (use grep instead):
+
+- `"foo_bar"` — exact symbol search
+- `"TODO"` — keyword search
+- `"code that deals with everything"` — too vague
+
+## When to Use
+
+| Scenario                 | Use This              | Instead Of                 |
+| ------------------------ | --------------------- | -------------------------- |
+| Find code by meaning     | `augment_code_search` | `grep` (text only)         |
+| Understand relationships | `augment_code_search` | `@explore` agent (heavier) |
+| Unfamiliar codebase      | `augment_code_search` | Manual file exploration    |
+| Cross-repo dependencies  | `augment_code_search` | LSP references (narrower)  |
+
+## When NOT to Use
+
+- **Exact string matching** — Use `grep` instead (faster, free)
+- **Known file paths** — Use `read` directly
+- **Symbol definitions** — Use LSP `goToDefinition` (precise)
+- **Local-only work** — This searches GitHub-indexed repos, not local files
+
+## Tool Priority Integration
+
+```
+grep (text) → semantic search (meaning) → read (full file) → LSP (symbols) → edit
+```
+
+Use grep first for exact matches. Escalate to semantic search when grep results are noisy or you need conceptual understanding.
+
+## Cost
+
+- ~40-70 credits per query
+- Not free — use judiciously
+- Prefer grep for simple lookups
+
+## Resources
+
+- Docs: https://docs.augmentcode.com/context-services/mcp/overview
+- OpenCode Quickstart: https://docs.augmentcode.com/context-services/mcp/quickstart-open-code
+- GitHub App: https://github.com/apps/augmentcode/installations/new
+- Product: https://www.augmentcode.com/product/context-engine-mcp

package/baseline/skill/augment-context-engine/mcp.json

@@ -0,0 +1,6 @@
+{
+	"augment-context-engine": {
+		"command": "npx",
+		"args": ["-y", "mcp-remote", "https://api.augmentcode.com/mcp"]
+	}
+}

package/baseline/skill/beads/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: beads
+description: >
+  Multi-agent task coordination using br (beads_rust) CLI. Use when work spans multiple
+  sessions, has dependencies, needs file locking, or requires agent coordination. Covers
+  claim/reserve/done cycle, dependency management, hierarchical decomposition, and session protocols.
+version: "2.0.0"
+license: MIT
+tags: [workflow, agent-coordination]
+dependencies: []
+---
+
+# Beads Workflow - Multi-Agent Task Coordination
+
+> **Replaces** ad-hoc task tracking with sticky notes, TODO comments, or mental checklists that lose state between sessions
+## When to Use
+
+- Coordinating multi-session work with dependencies, blockers, or file locking needs
+- Running multi-agent work where tasks must persist across sessions and handoffs
+
+## When NOT to Use
+
+- Single-session, linear tasks tracked via TodoWrite
+- Quick changes with no dependencies or handoff needs
+
+## Overview
+
+**br (beads_rust) CLI** replaces the old `bd` (beads) CLI with a faster Rust implementation.
+
+**Key Distinction**:
+
+- **br CLI**: Multi-session work, dependencies, file locking, agent coordination
+- **TodoWrite**: Single-session tasks, linear execution, conversation-scoped
+
+**When to Use br vs TodoWrite**:
+
+- "Will I need this context in 2 weeks?" → **YES** = br
+- "Does this have blockers/dependencies?" → **YES** = br
+- "Multiple agents editing same codebase?" → **YES** = br
+- "Will this be done in this session?" → **YES** = TodoWrite
+
+**Decision Rule**: If resuming in 2 weeks would be hard without beads, use beads.
+
+## Essential Commands
+
+```bash
+br ready              # Show issues ready to work (no blockers)
+br list --status open # All open issues
+br show <id>          # Full issue details with dependencies
+br create --title "Fix bug" --type bug --priority 2 --description "Details here"
+br update <id> --status in_progress
+br close <id> --reason "Completed"
+br sync --flush-only  # Export to JSONL (then git add/commit manually)
+```
+
+## Hierarchy & Dependencies (Summary)
+
+- Beads supports up to 3 levels of hierarchy: Epic → Task → Subtask
+- Use hierarchy for multi-day, cross-domain, or multi-agent work
+- Dependencies unblock parallel work when parents close
+
+See: `references/HIERARCHY.md` and `references/DEPENDENCIES.md` for full details.
+
+## Session Protocol (Summary)
+
+**Start:** `br ready` → `br update <id> --status in_progress` → `br show <id>`
+
+**End:** `br close <id> --reason "..."` → `br sync --flush-only` → commit `.beads/` → restart session
+
+See: `references/SESSION_PROTOCOL.md` and `references/WORKFLOWS.md` for detailed steps and checklists.
+
+## Task Creation (Summary)
+
+Create tasks when work spans sessions, has dependencies, or is discovered mid-implementation (>2 min).
+
+```bash
+br create --title "Fix authentication bug" --priority 0 --type bug
+```
+
+See: `references/TASK_CREATION.md` for full examples and patterns.
+
+## Git Sync (Summary)
+
+`br` never runs git commands. Always `br sync --flush-only` and commit `.beads/` manually.
+
+See: `references/GIT_SYNC.md` for detailed flow and cleanup guidance.
+
+## Troubleshooting (Summary)
+
+- No ready tasks → `br list --status open`, check blockers via `br show <id>`
+- Sync failures → `br doctor`
+
+See: `references/TROUBLESHOOTING.md` for common issues and fixes.
+
+## Examples
+
+See: `references/EXAMPLES.md` for complete usage examples.
+
+## Multi-Agent Coordination (Summary)
+
+For parallel execution with multiple subagents, use the **beads-bridge** skill.
+
+See: `references/MULTI_AGENT.md` for swarm tool usage and examples.
+
+## Rules
+
+1. **Check `br ready` first** - Find unblocked work before starting
+2. **Claim before editing** - `br update <id> --status in_progress`
+3. **One task per session** - Restart after `br close`
+4. **Always sync and commit** - `br sync --flush-only` then `git add .beads/ && git commit`
+5. **Write notes for future agents** - Assume zero conversation context
+6. **Claim file paths before editing** - Use reserve to declare ownership (multi-agent only)
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+| --- | --- | --- |
+| Claiming a bead without reading its current state first (`br show`) | Misses dependencies, blockers, and prior context | Run `br show <id>` before `br update <id> --status in_progress` |
+| Closing a bead without verification evidence | Marks incomplete or broken work as done | Run verification commands and capture output before `br close` |
+| Working on blocked beads (dependencies not met) | Wastes time and causes out-of-order delivery | Use `br ready` and confirm dependencies in `br show <id>` |
+| Modifying bead state without user confirmation | Violates workflow expectations and can surprise collaborators | Ask before changing bead status, especially close/sync actions |
+| Using `br sync` without `--flush-only` (can cause conflicts) | May write unexpected state and increase sync conflict risk | Always use `br sync --flush-only` then commit `.beads/` manually |
+
+## Verification
+
+- **Before closing:** run verification commands, paste output as evidence
+- **After close:** `br show <id>` confirms `status=closed`
+- **After sync:** `git status` shows clean working tree
+
+## File Path Claiming (Summary)
+
+Claim files before editing in multi-agent work using `br reserve <id> --files "..."`.
+
+See: `references/FILE_CLAIMING.md` for the full protocol and examples.
+
+## Best Practices (Summary)
+
+- One task per session, then restart
+- File issues for work >2 minutes
+- Weekly `br doctor`, periodic `br cleanup --days 7`
+
+See: `references/BEST_PRACTICES.md` for maintenance and database health guidance.
+
+## Quick Reference
+
+```
+SESSION START:
+  br ready → br update <id> --status in_progress → br show <id>
+
+DURING WORK:
+  br create for discovered work (>2min)
+  br show <id> for context
+
+SESSION END:
+  br close <id> --reason "..." → br sync --flush-only → git add .beads/ && git commit → RESTART SESSION
+
+MAINTENANCE:
+  br doctor - weekly health check
+  br cleanup --days 7 - remove old issues
+```
+
+## References
+
+- `references/BOUNDARIES.md`
+- `references/RESUMABILITY.md`
+- `references/DEPENDENCIES.md`
+- `references/WORKFLOWS.md`
+- `references/HIERARCHY.md`
+- `references/SESSION_PROTOCOL.md`
+- `references/TASK_CREATION.md`
+- `references/GIT_SYNC.md`
+- `references/TROUBLESHOOTING.md`
+- `references/EXAMPLES.md`
+- `references/MULTI_AGENT.md`
+- `references/FILE_CLAIMING.md`
+- `references/BEST_PRACTICES.md`
+
+## See Also
+
+- `verification-before-completion`
+- `beads-bridge`

package/baseline/skill/beads/references/BEST_PRACTICES.md

@@ -0,0 +1,27 @@
+# Best Practices
+
+## Daily/Weekly Maintenance
+
+| Task         | Frequency      | Command               | Why                                            |
+| ------------ | -------------- | --------------------- | ---------------------------------------------- |
+| Health check | Weekly         | `br doctor`           | Repairs database issues, detects orphaned work |
+| Cleanup      | Every few days | `br cleanup --days 7` | Keep DB under 200-500 issues for performance   |
+
+## Key Principles
+
+1. **Plan outside Beads first** - Use planning tools, then import tasks to beads
+2. **One task per session, then restart** - Fresh context prevents confusion
+3. **File lots of issues** - Any work >2 minutes should be tracked
+4. **"Land the plane" = PUSH** - `br sync --flush-only` + git commit/push, not "ready when you are"
+5. **Include issue ID in commits** - `git commit -m "Fix bug (br-abc)"`
+
+## Database Health
+
+```bash
+# Check database size
+br list --status all --json | wc -l
+
+# Target: under 200-500 issues
+# If over, run cleanup more aggressively:
+br cleanup --days 3
+```