opencodekit 0.16.15 → 0.16.18

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

@@ -1,310 +1,99 @@
 ---
 description: Research a topic or bead before implementation
-argument-hint: "<bead-id> [--quick|--thorough]"
+argument-hint: "<topic-or-bead-id> [--quick|--thorough]"
 agent: scout
-subtask: true
 ---
 
 # Research: $ARGUMENTS
 
-You're gathering information before implementation. Find answers, document findings, stop when done.
+Gather information before implementation. Find answers, document findings, stop when done.
 
-> **Lifecycle context:** Ideation → Design → **Research (optional)** → Specification → Planning → Implementation → Verification
->
 > Research can happen at any phase when you need external information or codebase understanding.
 
-## Depth Levels
-
-- `--quick` (~10 tool calls): Single question, API syntax lookup
-- Default (~30 tool calls): Moderate exploration, verify patterns
-- `--thorough` (~100+ tool calls): Comprehensive analysis, new domain
-
-## Load Skills Based on Depth
-
-```typescript
-skill({ name: "development-lifecycle" }); // Phase guidance
-
-// For --thorough mode, load the deep-research skill
-if (thorough) {
-  skill({ name: "deep-research" });
-}
-
-// For npm package evaluation
-skill({ name: "v1-run" });
-
-// For source code analysis
-skill({ name: "source-code-research" });
-
-// For swarm coordination (if parallel research needed)
-skill({ name: "swarm-coordination" });
-
-// For memory context
-skill({ name: "memory-system" });
-```
-
-## Delegation Strategy
-
-### Step 1: Classify Research Task
-
-```typescript
-// Analyze if research benefits from parallelization
-const analysis = await swarm({
-  operation: "plan",
-  action: "analyze",
-  task: "Research " + $ARGUMENTS,
-  files: "<detected files or leave empty for external research>",
-});
-
-// For search-type research with multiple sources, use swarm
-if (analysis.classification.type === "search" && analysis.classification.recommended_agents > 1) {
-  console.log(`Research classified as ${analysis.classification.type}`);
-  console.log(`Recommended: ${analysis.classification.recommended_agents} parallel agents`);
-}
-```
-
-### Internal Codebase → @explore
-
-Delegate LSP exploration to the explore agent:
-
-```typescript
-task({
-  subagent_type: "explore",
-  description: "Analyze <module>",
-  prompt: `Very thorough LSP analysis of <target files>.
-
-Questions:
-1. What functions/classes are exported?
-2. What are the incoming/outgoing calls?
-3. What patterns exist in this module?
-
-Return file:line references for all findings.`,
-});
-```
-
-### External Research → @scout (this agent)
-
-Scout handles external sources (context7, grepsearch, codesearch, etc.)
-
-### Parallel Execution (Swarm Mode for Research)
-
-For comprehensive research across multiple domains, use parallel agents:
-
-```typescript
-// Option A: Simple parallel (2-3 agents)
-// Launch both in parallel
-task({ subagent_type: "explore", prompt: "LSP analysis of..." });
-context7({ operation: "resolve", libraryName: "<lib>" });
-grepsearch({ query: "<pattern>", language: "TypeScript" });
-
-// Option B: Swarm mode for complex multi-domain research
-// Use when researching 3+ different areas simultaneously
-
-// Spawn research workers (results returned when all complete)
-Task({
-  subagent_type: "explore",
-  description: "Research domain A",
-  prompt: `Research [domain A] for ${$ARGUMENTS}...
-Return: Key findings, file paths, patterns discovered`,
-});
-
-Task({
-  subagent_type: "scout",
-  description: "Research domain B",
-  prompt: `Research [domain B] for ${$ARGUMENTS}...
-Return: Documentation, code examples, best practices`,
-});
-
-// Results available immediately when all workers complete
-```
-
-## Load Context
-
-### Load Bead Details
-
-!`br show $ARGUMENTS`
-!`cat .beads/artifacts/$ARGUMENTS/prd.md`
-
-Extract questions that need answering from spec.
-
-## Check For Previous Research
-
-!`search_session({ query: "[topic keywords]" })`
-!`list_sessions({ project: "current", since: "this week", limit: 5 })`
-
-Extract the questions that need answering from the spec.
-
-## Check Memory First (Semantic Search)
-
-Before hitting external sources, search what we already know:
+## Load Skills
 
 ```typescript
-// Search past research and observations on similar topics
-memory_search({ query: "[research question/topic]", limit: 5 });
-
-// Search for related gotchas and learnings
-memory_search({ query: "[topic keywords] gotchas", limit: 3 });
-```
-
-**If memory has high-confidence answers, you may skip external research.**
-
-Review findings for:
-
-- Previous research on this exact topic
-- Related patterns and decisions
-- Known gotchas to avoid
-
-If memory search fails (Ollama not running), continue to external sources.
-
-## Source Priority
-
-1. **Codebase patterns** (highest trust) - Delegate to @explore for LSP analysis
-2. **Official docs** (high trust) - What does the library documentation say?
-3. **v1-run** (high trust) - npm package health, vulnerabilities, comparisons
-4. **Context7** (high trust) - API usage and examples
-5. **Source code** (high trust) - Library implementation (use `source-code-research` skill)
-6. **GitHub examples** (medium trust) - Real-world patterns via codesearch/grepsearch
-7. **Web search** (lower trust) - Only if tiers 1-6 don't answer
-
-## Research
-
-### Internal Codebase → Delegate to @explore
-
-**Do NOT run LSP manually.** Delegate to the explore agent:
-
-```typescript
-task({
-  subagent_type: "explore",
-  description: "Analyze codebase patterns",
-  prompt: `Very thorough analysis of [target area].
-
-Questions:
-1. How does this project handle [pattern]?
-2. What are the existing conventions?
-3. Where are similar implementations?
-
-Return file:line references.`,
-});
+skill({ name: "beads" });
+// For --thorough mode:
+skill({ name: "deep-research" });
 ```
 
-### External Docs
+## Parse Arguments
 
-```typescript
-context7({ operation: "resolve", libraryName: "<lib>", query: "<question>" });
-context7({ operation: "query", libraryId: "<id>", topic: "<specific question>" });
-```
+| Argument         | Default  | Description                         |
+| ---------------- | -------- | ----------------------------------- |
+| Topic or bead ID | required | What to research                    |
+| `--quick`        | false    | ~10 tool calls, single question     |
+| `--thorough`     | false    | ~100+ calls, comprehensive analysis |
 
-### Source Code (When Docs Insufficient)
+Default depth: ~30 tool calls for moderate exploration.
 
-**Use the `source-code-research` skill when:**
+## Phase 1: Load Context
 
-- Documentation doesn't explain behavior clearly
-- Need to understand edge cases or internals
-- Library behaving unexpectedly
-- Evaluating library quality/fit
+If argument is a bead ID:
 
 ```bash
-# Fetch package source code
-npx opensrc <package>              # npm package
-npx opensrc <package>@<version>    # specific version
-npx opensrc pypi:<package>         # Python
-npx opensrc <owner>/<repo>         # GitHub repo
+br show $ARGUMENTS
 ```
 
-**See:** `skill({ name: "source-code-research" })` for complete workflow.
+Read PRD if it exists and extract questions that need answering.
 
-### Code Examples
+Check memory for previous research on this topic.
 
-```typescript
-codesearch({ query: "<API usage pattern>", tokensNum: 5000 });
-grepsearch({ query: "<code pattern>", language: "TypeScript" });
-```
+## Phase 2: Research
+
+### Source Priority
 
-## Validate Findings
+1. **Codebase patterns** — delegate to `explore` agent for LSP analysis
+2. **Official docs** — `context7` for API references
+3. **Source code** — `npx opensrc <package>` when docs are insufficient
+4. **GitHub examples** — `codesearch` / `grepsearch` for real-world patterns
+5. **Web search** — only if tiers 1-4 don't answer
 
-For each finding:
+### Delegation
 
-- Within spec scope?
-- Follows project constraints?
-- Uses allowed libs?
-- Matches existing codebase patterns?
+| What              | Agent                        | When                                   |
+| ----------------- | ---------------------------- | -------------------------------------- |
+| Codebase analysis | `explore`                    | Internal patterns, file structure, LSP |
+| External docs     | `scout` (this agent)         | Library APIs, best practices           |
+| Multiple domains  | Parallel `explore` + `scout` | 3+ independent questions               |
 
-**Confidence levels:**
+### Confidence Levels
 
 - **High**: Multiple authoritative sources agree, verified in codebase
 - **Medium**: Single good source, plausible but unverified
-- **Low**: Conflicting info, speculation
+- **Low**: Conflicting info, speculation — discard without corroboration
 
-Discard low-confidence findings without corroboration.
+## Phase 3: Stop When
 
-## Stop When
-
-- All spec questions answered with medium+ confidence
-- Tool budget exhausted
+- All questions answered with medium+ confidence
+- Tool budget exhausted for depth level
 - Last 5 tool calls yielded no new insights
 - Blocked and need human input
 
-## Document Findings
-
-Write `.beads/artifacts/$ARGUMENTS/research.md`:
+## Phase 4: Document
 
-```markdown
-# Research: [Title]
+Write findings to `.beads/artifacts/$ARGUMENTS/research.md` (if bead) or report directly (if topic):
 
-**Bead:** $ARGUMENTS
-**Depth:** [quick|medium|thorough]
-**Tool calls:** [N]
-
-## Questions
-
-1. [Question] → Answered (High)
-2. [Question] → Partial (Medium)
-3. [Question] → Unanswered
-
-## Key Findings
-
-### [Topic 1]
-
-**Confidence:** High
-**Sources:** `src/utils/auth.ts:42`, Context7 /vercel/next.js
-
-[Finding with code example]
-
----
-
-### [Topic 2]
-
-**Confidence:** Medium
-[Finding]
-
----
-
-## Recommendation
-
-[Approach based on findings]
-
-## Open Items
-
-- [Remaining question] - needs: [what would resolve it]
-```
+- Questions asked → answered/partial/unanswered with confidence
+- Key findings with sources (file paths, docs)
+- Recommendation based on findings
+- Open items needing resolution
 
 ## Output
 
-```
-Research: $ARGUMENTS
-
-Depth: [quick|medium|thorough]
-Tool calls: [N]
-Delegations: [@explore for codebase, @scout for external]
+Report:
 
-Questions:
-• [Q1] → Answered (High)
-• [Q2] → Partial (Medium)
+1. Depth level and tool call count
+2. Questions with answer status and confidence
+3. Key insights (bullet points)
+4. Open items remaining
+5. Next step suggestion
 
-Key insights:
-• [insight 1]
-• [insight 2]
+## Related Commands
 
-Open items: [N]
-
-Next: /plan $ARGUMENTS
-```
+| Need          | Command       |
+| ------------- | ------------- |
+| Create spec   | `/create`     |
+| Plan details  | `/plan <id>`  |
+| Start working | `/start <id>` |

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

@@ -6,187 +6,82 @@ agent: build
 
 # Resume: $ARGUMENTS
 
-You're picking up where a previous session left off. Recover context, verify state, continue work.
+Pick up where a previous session left off. Recover context, verify state, continue.
 
 ## Load Skills
 
 ```typescript
 skill({ name: "beads" });
-skill({ name: "beads-bridge" }); // For cross-session recovery
-skill({ name: "memory-system" });
 ```
 
-## Verify The Task Exists
+## Phase 1: Verify Task
 
-!`br show $ARGUMENTS`
-
-If not found, check `br list --status=all`. Maybe it was closed, or you have the wrong ID.
-
-## Check Git State
+```bash
+br show $ARGUMENTS
+```
 
-!`git branch --show-current`
-!`git rev-parse --short HEAD`
-!`git status --porcelain`
+If not found, check `br list --status=all` — it may have been closed or the ID is wrong.
 
-If you're not on the right branch:
+## Phase 2: Git State
 
 ```bash
-git checkout $ARGUMENTS 2>/dev/null || git checkout feature/$ARGUMENTS
+git branch --show-current
+git status --porcelain
 ```
 
-If there are uncommitted changes, decide: stash, commit, or discard.
-
-## Find The Handoff
+If not on the right branch, check out the feature branch. If uncommitted changes exist, ask user what to do.
 
-!`ls -t .beads/artifacts/$ARGUMENTS/handoffs/ 2>/dev/null | head -1`
+## Phase 3: Find Handoff
 
-If a handoff exists, read it:
+Check for handoff notes:
 
-!`cat .beads/artifacts/$ARGUMENTS/handoffs/[latest].md`
+```bash
+ls .beads/artifacts/$ARGUMENTS/handoffs/ 2>/dev/null
+```
 
-The handoff tells you:
+If a handoff exists, read the latest one. It tells you:
 
 - What was completed
 - Where work stopped
 - What to do next
 - Any blockers
 
-## Load Previous Session Context
-
-Search for related work:
+Also search previous sessions:
 
 ```typescript
 search_session({ query: "$ARGUMENTS" });
-list_sessions({ project: "current", limit: 5 });
-```
-
-Load the most recent relevant session:
-
-```typescript
-read_session({ session_reference: "last", project: "current" });
-```
-
-Extract from session:
-
-- Files modified
-- Decisions made
-- Where work stopped
-- Problems encountered
-
-## Load Related Memory (Semantic Search)
-
-Search for relevant observations and past work:
-
-```typescript
-// Find observations related to this bead
-memory_search({ query: "$ARGUMENTS [bead title/description]", limit: 5 });
-
-// Find similar past work
-memory_search({ query: "[bead description keywords]", limit: 3 });
 ```
 
-**Review findings** - past observations may contain:
-
-- Gotchas discovered during previous sessions
-- Decisions already made
-- Patterns that worked
-
-If memory search fails (Ollama not running), continue without it.
-
-## Load Artifacts
+## Phase 4: Load Artifacts
 
 Read all available context:
 
-!`cat .beads/artifacts/$ARGUMENTS/prd.md 2>/dev/null`
-!`cat .beads/artifacts/$ARGUMENTS/plan.md 2>/dev/null`
-!`cat .beads/artifacts/$ARGUMENTS/research.md 2>/dev/null`
-
-## Recover Swarm State (If Active)
-
-Check if there was an active swarm for this task:
-
-```typescript
-// Check for active swarm state
-const teamName = "$ARGUMENTS-swarm";
-const status = await swarm({
-  operation: "monitor",
-  action: "status",
-  team_name: teamName,
-});
-
-const stats = JSON.parse(status);
-if (stats.summary?.total_workers > 0) {
-  console.log(`✓ Found active swarm with ${stats.summary.total_workers} workers`);
-
-  // Show current progress
-  const ui = await swarm({
-    operation: "monitor",
-    action: "render_block",
-    team_name: teamName,
-  });
-  console.log(ui);
-} else {
-  console.log("No active swarm session");
-}
-
-// Sync beads to OpenCode todos for subagent visibility
-swarm({ operation: "sync", action: "push" });
-```
-
-## Check For Stale Context
-
-If handoff is more than 3 days old, things may have changed:
+- `.beads/artifacts/$ARGUMENTS/prd.md`
+- `.beads/artifacts/$ARGUMENTS/plan.md` (if exists)
+- `.beads/artifacts/$ARGUMENTS/progress.txt` (if exists)
+- `.beads/artifacts/$ARGUMENTS/research.md` (if exists)
 
-!`git log --oneline -10` # What happened since?
-!`git diff [handoff-commit]..HEAD --stat` # What files changed?
+## Phase 5: Check Staleness
 
-If significant changes occurred on main, consider rebasing:
+If handoff is more than 3 days old:
 
 ```bash
-git fetch origin
-git rebase origin/main
+git log --oneline -10
 ```
 
-## Report Status
+Check if significant changes happened on main. If so, consider rebasing. Don't blindly follow an outdated plan — verify it still makes sense.
 
-```
-Resuming: $ARGUMENTS
-
-Branch: [branch]
-Commit: [hash]
-Handoff: [date] ([age])
-
-Progress:
-- [x] [completed]
-- [x] [completed]
-- [ ] [in progress] <- resume here
-- [ ] [remaining]
-
-Next: [from handoff resume instructions]
-```
-
-## Continue Work
-
-Mark in progress if not already:
+## Phase 6: Continue
 
 ```bash
 br update $ARGUMENTS --status in_progress
 ```
 
-Then continue with implementation:
-
-| Condition               | Command                                  |
-| ----------------------- | ---------------------------------------- |
-| Swarm was restored      | Continue with `/ship $ARGUMENTS --swarm` |
-| No swarm, standard work | `/ship $ARGUMENTS`                       |
-| Need to re-plan         | `/plan $ARGUMENTS`                       |
-
-## If Context Is Too Stale
-
-If more than a week old or significant changes happened:
+Report:
 
-1. Re-read key files to refresh understanding
-2. Check if the approach in plan.md is still valid
-3. Consider running `/research $ARGUMENTS` again if external factors changed
+1. Branch and commit
+2. Handoff age
+3. Progress (completed/remaining tasks)
+4. Next action (from handoff or PRD)
 
-Don't blindly follow an outdated plan. Verify it still makes sense.
+Then continue with `/ship $ARGUMENTS` or `/plan $ARGUMENTS` as appropriate.