opencodekit 0.10.0 → 0.11.1

package/dist/template/.opencode/command/research-and-implement.md

@@ -1,21 +1,451 @@
 ---
-description: Research then implement
-argument-hint: "<bead-id> or [topic]"
+description: End-to-end research-driven implementation workflow
+argument-hint: "<bead-id> | <topic> [--quick] [--tdd]"
 agent: build
 ---
 
 # Research & Implement: $ARGUMENTS
 
-## Simple edit (no bead needed)
+Complete workflow that combines research, planning, and implementation into a single guided process.
 
-Fix directly with clear comments. Commit.
+## Load Beads Skill
 
-## Structured work (bead-based)
+```typescript
+skill({ name: "beads" });
+```
 
-1. Validate bead exists: `bd_show({ id: "$ARGUMENTS" })`
-2. Load constraints from `.beads/artifacts/$ARGUMENTS/spec.md`
-3. Research within scope: `/research $ARGUMENTS`
-4. Plan approach: `/plan $ARGUMENTS`
-5. Implement with TDD: `skill({ name: "test-driven-development" })`
-6. Complete review: `.beads/artifacts/$ARGUMENTS/review.md`
-7. Run `/finish $ARGUMENTS`
+## When to Use
+
+| Scenario                  | Use This Command           |
+| ------------------------- | -------------------------- |
+| New feature with unknowns | ✓ Yes                      |
+| Bug with unclear cause    | ✓ Yes                      |
+| Integration with new API  | ✓ Yes                      |
+| Simple code change        | ✗ No - use `/fix` directly |
+| Already have a plan       | ✗ No - use `/implement`    |
+
+## Phase 1: Parse Input and Validate
+
+### Detect Input Type
+
+```typescript
+const input = "$ARGUMENTS";
+
+if (input.startsWith("bd-")) {
+  // Bead-based workflow
+  bd_show({ id: input });
+  // Load spec for constraints
+  read({ filePath: `.beads/artifacts/${input}/spec.md` });
+} else {
+  // Ad-hoc topic - may need to create bead
+  console.log(`Topic: ${input}`);
+  console.log("Consider creating a bead for tracking: /create ${input}");
+}
+```
+
+### Check Prerequisites
+
+```typescript
+bd_init({ _: true, team: "project", role: "builder" });
+bd_inbox({ n: 5, unread: true, global: true }); // Check for blockers
+```
+
+## Phase 2: Research Phase
+
+### Scope Definition
+
+```
+RESEARCH SCOPE
+━━━━━━━━━━━━━━
+
+Topic: [from $ARGUMENTS or bead spec]
+
+Questions to Answer:
+1. [Key question 1]
+2. [Key question 2]
+3. [Key question 3]
+
+Out of Scope:
+- [Explicit exclusion 1]
+- [Explicit exclusion 2]
+```
+
+### Research Sources
+
+```typescript
+// 1. Codebase exploration
+task({
+  subagent_type: "explore",
+  description: "Explore codebase for patterns",
+  prompt: `
+    TASK: Research existing patterns for [topic]
+    
+    Search for:
+    - Similar implementations
+    - Related utilities
+    - Test patterns
+    - Configuration examples
+    
+    Return: File paths and key patterns found
+  `,
+});
+
+// 2. External documentation (if needed)
+context7_resolve_library_id({
+  libraryName: "[relevant library]",
+  query: "[specific question]",
+});
+
+// 3. Real-world examples (if needed)
+gh_grep_searchGitHub({
+  query: "[pattern to find]",
+  language: ["TypeScript"],
+});
+```
+
+### Synthesize Findings
+
+```
+RESEARCH FINDINGS
+━━━━━━━━━━━━━━━━━
+
+Key Insights:
+1. [Finding 1]
+2. [Finding 2]
+3. [Finding 3]
+
+Existing Patterns to Follow:
+- [Pattern from codebase]
+- [Convention discovered]
+
+External Best Practices:
+- [From docs/examples]
+
+Risks Identified:
+- [Risk 1]
+- [Risk 2]
+
+Recommended Approach:
+[Summary of approach based on research]
+```
+
+### Save Research (if bead)
+
+```typescript
+if (beadId) {
+  write({
+    filePath: `.beads/artifacts/${beadId}/research.md`,
+    content: researchFindings,
+  });
+}
+```
+
+## Phase 3: Planning Phase
+
+### Generate Implementation Plan
+
+Based on research, create actionable plan:
+
+```markdown
+# Implementation Plan: $ARGUMENTS
+
+## Approach
+
+[1-2 sentence summary]
+
+## Steps
+
+### Phase 1: Setup
+
+- [ ] Step 1.1: [action]
+- [ ] Step 1.2: [action]
+
+### Phase 2: Core Implementation
+
+- [ ] Step 2.1: [action]
+- [ ] Step 2.2: [action]
+- [ ] Step 2.3: [action]
+
+### Phase 3: Testing
+
+- [ ] Step 3.1: Write tests for [component]
+- [ ] Step 3.2: Run test suite
+
+### Phase 4: Verification
+
+- [ ] Step 4.1: Manual verification
+- [ ] Step 4.2: Code review prep
+
+## Files to Modify
+
+- `path/to/file1.ts` - [change description]
+- `path/to/file2.ts` - [change description]
+
+## Test Strategy
+
+[How to verify implementation]
+
+## Rollback Plan
+
+[How to revert if needed]
+```
+
+### Save Plan (if bead)
+
+```typescript
+if (beadId) {
+  write({
+    filePath: `.beads/artifacts/${beadId}/plan.md`,
+    content: implementationPlan,
+  });
+}
+```
+
+## Phase 4: Implementation Phase
+
+### Load Implementation Skill
+
+```typescript
+skill({ name: "test-driven-development" });
+```
+
+### Reserve Files
+
+```typescript
+const filesToEdit = extractFilesFromPlan(plan);
+bd_reserve({ paths: filesToEdit, ttl: 600, reason: "Implementing $ARGUMENTS" });
+```
+
+### Execute Plan Steps
+
+For each step in the plan:
+
+```
+IMPLEMENTING: Step [X.Y]
+━━━━━━━━━━━━━━━━━━━━━━━
+
+Action: [step description]
+
+[Execute the step]
+
+Verification:
+- [ ] Code compiles
+- [ ] Tests pass
+- [ ] Matches research findings
+
+Progress: [X/Y] steps complete
+```
+
+### TDD Cycle (if --tdd flag or complex logic)
+
+```
+For each component:
+
+1. RED: Write failing test
+   └── Run tests, confirm failure
+
+2. GREEN: Write minimal code to pass
+   └── Run tests, confirm passing
+
+3. REFACTOR: Clean up
+   └── Run tests, confirm still passing
+```
+
+## Phase 5: Verification Phase
+
+### Run Full Test Suite
+
+```bash
+npm test
+# or
+pytest tests/ -v
+```
+
+### Verify Against Research
+
+```
+VERIFICATION CHECKLIST
+━━━━━━━━━━━━━━━━━━━━━━
+
+Research Requirement              │ Status
+──────────────────────────────────┼────────
+[Requirement from research 1]     │ ✓ Met
+[Requirement from research 2]     │ ✓ Met
+[Best practice identified]        │ ✓ Met
+
+Plan Completion                   │ Status
+──────────────────────────────────┼────────
+Phase 1: Setup                    │ ✓ Complete
+Phase 2: Core Implementation      │ ✓ Complete
+Phase 3: Testing                  │ ✓ Complete
+Phase 4: Verification             │ ✓ Complete
+```
+
+### Update Review Document
+
+```typescript
+if (beadId) {
+  write({
+    filePath: `.beads/artifacts/${beadId}/review.md`,
+    content: `
+# Review: ${beadId}
+
+## Implementation Summary
+[What was built]
+
+## Key Decisions
+[Decisions made during implementation]
+
+## Testing
+- Tests added: [count]
+- Coverage: [if available]
+- All tests: PASSING
+
+## Known Limitations
+[Any caveats]
+
+## Ready for Review
+- [ ] Code complete
+- [ ] Tests passing
+- [ ] Documentation updated
+    `,
+  });
+}
+```
+
+## Phase 6: Completion
+
+### If Bead-Based
+
+```bash
+/finish $ARGUMENTS
+```
+
+This will:
+
+- Run final verification
+- Create PR if needed
+- Close the bead
+
+### If Ad-Hoc
+
+```bash
+/commit "feat: [description]"
+```
+
+## Quick Mode (--quick)
+
+For smaller tasks, compress the workflow:
+
+```
+QUICK MODE
+━━━━━━━━━━
+
+1. Minimal research (5 min max)
+   - Check for existing patterns
+   - Identify key constraints
+
+2. No formal plan document
+   - Mental model only
+
+3. Direct implementation
+   - Write code
+   - Add tests
+
+4. Verify and commit
+   - Run tests
+   - Commit with clear message
+
+Time budget: 30 minutes max
+If exceeding: Convert to full workflow with bead
+```
+
+## Workflow Summary
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    RESEARCH & IMPLEMENT WORKFLOW                        │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  INPUT                                                                  │
+│    │                                                                    │
+│    ├── Bead ID → Load spec, create artifacts                           │
+│    └── Topic   → Ad-hoc, consider /create first                        │
+│                                                                         │
+│  RESEARCH (15-30 min)                                                   │
+│    │                                                                    │
+│    ├── Codebase exploration                                            │
+│    ├── External documentation                                          │
+│    ├── Real-world examples                                             │
+│    └── Synthesize findings                                             │
+│                                                                         │
+│  PLANNING (10-20 min)                                                   │
+│    │                                                                    │
+│    ├── Create step-by-step plan                                        │
+│    ├── Identify files to modify                                        │
+│    └── Define test strategy                                            │
+│                                                                         │
+│  IMPLEMENTATION (variable)                                              │
+│    │                                                                    │
+│    ├── TDD cycle for each component                                    │
+│    ├── Follow plan steps                                               │
+│    └── Track progress                                                  │
+│                                                                         │
+│  VERIFICATION (10-15 min)                                              │
+│    │                                                                    │
+│    ├── Run full test suite                                             │
+│    ├── Verify against research                                         │
+│    └── Update review document                                          │
+│                                                                         │
+│  COMPLETION                                                             │
+│    │                                                                    │
+│    └── /finish or /commit                                              │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Examples
+
+```bash
+/research-and-implement bd-auth01       # Full workflow with bead
+/research-and-implement "add caching"   # Ad-hoc topic
+/research-and-implement bd-fix02 --quick  # Quick mode
+/research-and-implement bd-core03 --tdd   # Enforce TDD
+```
+
+## Error Handling
+
+### Research Stalls
+
+```
+If research is taking too long (>30 min):
+
+1. Time-box remaining research
+2. Document unknowns explicitly
+3. Plan for iterative discovery during implementation
+4. Set "research spike" tasks for deep unknowns
+```
+
+### Implementation Blocks
+
+```
+If implementation hits unexpected blocker:
+
+1. Stop implementation
+2. Add finding to research.md
+3. Revise plan if needed
+4. Create sub-task for blocker if significant
+5. Continue or defer based on impact
+```
+
+### Test Failures
+
+```
+If tests fail during verification:
+
+1. Analyze failure
+2. Check if bug or missing requirement
+3. Fix and re-run
+4. If persistent, document in review.md
+5. Decide: fix now or create follow-up task
+```