opencodekit 0.12.2 → 0.12.3

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

@@ -1,451 +1,150 @@
 ---
-description: End-to-end research-driven implementation workflow
-argument-hint: "<bead-id> | <topic> [--quick] [--tdd]"
+description: Research and implement in one workflow
+argument-hint: "<bead-id> [--quick] [--tdd]"
 agent: build
 ---
 
 # Research & Implement: $ARGUMENTS
 
-Complete workflow that combines research, planning, and implementation into a single guided process.
+End-to-end workflow: research → plan → implement → verify.
 
-## Load Beads Skill
+Use this for features with unknowns. For simple changes, use `/fix` or `/implement` directly.
 
-```typescript
-skill({ name: "beads" });
-```
-
-## 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
+## Phase 1: Context
 
-```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}");
-}
+```bash
+bd show $ARGUMENTS
+cat .beads/artifacts/$ARGUMENTS/spec.md
 ```
 
-### Check Prerequisites
-
-```typescript
-bd_init({ _: true, team: "project", role: "builder" });
-bd_inbox({ n: 5, unread: true, global: true }); // Check for blockers
-```
+If no spec exists: "Run `/create $ARGUMENTS` first."
 
-## Phase 2: Research Phase
+## Phase 2: Research
 
-### Scope Definition
+Define what you need to learn:
 
 ```
-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]
+Questions:
+1. [Key question]
+2. [Key question]
+3. [Key question]
 ```
 
-### Research Sources
+Research using:
 
 ```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"],
-});
-```
+// Codebase patterns
+ast - grep({ pattern: "<pattern>" });
+grep({ pattern: "<pattern>", include: "*.ts" });
 
-### Synthesize Findings
+// External docs
+context7_resolve_library_id({ libraryName: "<lib>", query: "<question>" });
 
+// Real examples
+codesearch({ query: "<pattern>", tokensNum: 5000 });
 ```
-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]
+Synthesize:
 
-Recommended Approach:
-[Summary of approach based on research]
 ```
+Findings:
+• [Key insight 1]
+• [Key insight 2]
 
-### Save Research (if bead)
-
-```typescript
-if (beadId) {
-  write({
-    filePath: `.beads/artifacts/${beadId}/research.md`,
-    content: researchFindings,
-  });
-}
+Recommended approach: [summary]
 ```
 
-## Phase 3: Planning Phase
+Save to `.beads/artifacts/$ARGUMENTS/research.md`.
 
-### Generate Implementation Plan
+## Phase 3: Plan
 
-Based on research, create actionable plan:
+Create implementation plan:
 
 ```markdown
-# Implementation Plan: $ARGUMENTS
+# Plan: $ARGUMENTS
 
 ## Approach
 
-[1-2 sentence summary]
+[1-2 sentences]
 
 ## 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
+1. [Step] - verify: `[command]`
+2. [Step] - verify: `[command]`
+3. [Step] - verify: `[command]`
 
-For each step in the plan:
+## Files
 
+- `src/foo.ts` - [change]
+- `src/bar.ts` - [change]
 ```
-IMPLEMENTING: Step [X.Y]
-━━━━━━━━━━━━━━━━━━━━━━━
 
-Action: [step description]
+Save to `.beads/artifacts/$ARGUMENTS/plan.md`.
 
-[Execute the step]
+## Phase 4: Implement
 
-Verification:
-- [ ] Code compiles
-- [ ] Tests pass
-- [ ] Matches research findings
+Mark in progress:
 
-Progress: [X/Y] steps complete
+```bash
+bd update $ARGUMENTS --status in_progress
 ```
 
-### TDD Cycle (if --tdd flag or complex logic)
+If `--tdd` flag:
 
 ```
 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
+Otherwise, implement step by step from plan. Checkpoint after significant progress:
 
 ```bash
-npm test
-# or
-pytest tests/ -v
+git commit -m "WIP: $ARGUMENTS - [step]"
 ```
 
-### 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
-```
+## Phase 5: Verify
 
-### Update Review Document
+Run all gates:
 
-```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
-    `,
-  });
-}
+```bash
+npm test
+npm run type-check
+npm run lint
 ```
 
-## Phase 6: Completion
+Verify against research requirements and plan steps.
 
-### If Bead-Based
+## Phase 6: Complete
 
 ```bash
-/finish $ARGUMENTS
+git add -A
+git commit -m "$ARGUMENTS: [summary]"
 ```
 
-This will:
+```typescript
+bd_sync({ reason: "Sync research and implementation" });
+```
 
-- Run final verification
-- Create PR if needed
-- Close the bead
+```
+Done: $ARGUMENTS
 
-### If Ad-Hoc
+Research: .beads/artifacts/$ARGUMENTS/research.md
+Plan: .beads/artifacts/$ARGUMENTS/plan.md
+Changes: [files]
+Tests: Pass
 
-```bash
-/commit "feat: [description]"
+Next: /finish $ARGUMENTS
 ```
 
 ## Quick Mode (--quick)
 
-For smaller tasks, compress the workflow:
-
-```
-QUICK MODE
-━━━━━━━━━━
+For smaller tasks:
 
 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
-```
+Time budget: 30 minutes. If exceeding, convert to full workflow.