opencodekit 0.9.2 → 0.11.0

package/dist/template/.opencode/command/quick-build.md

@@ -1,13 +1,242 @@
 ---
-description: Quick build for trivial tasks
-argument-hint: "[task]"
+description: Quick build for trivial tasks with fast verification
+argument-hint: "<task-description> [--no-test] [--no-commit]"
 agent: build
 ---
 
 # Quick Build: $ARGUMENTS
 
-**Reject if:** ≥2 files, new deps, security risk, DB changes. Use `/create` instead.
+Fast path for trivial tasks. Skip ceremony, keep safety.
 
-**Simple edit:** Fix directly with clear comments, commit.
+## Parse Arguments
 
-**Needs structure:** Create bead with `/create`, implement, run `/finish`.
+| Argument         | Default  | Description                   |
+| ---------------- | -------- | ----------------------------- |
+| Task description | required | What to fix/change            |
+| `--no-test`      | false    | Skip test run (use sparingly) |
+| `--no-commit`    | false    | Make changes but don't commit |
+
+---
+
+## Qualification Check
+
+**This task qualifies for quick-build if ALL are true:**
+
+| Criterion                | Check                                | If False          |
+| ------------------------ | ------------------------------------ | ----------------- |
+| Single file change       | 1 file modified                      | Use `/create`     |
+| No new dependencies      | No package.json/requirements changes | Use `/create`     |
+| No database changes      | No migrations, schema changes        | Use `/create`     |
+| No security implications | No auth, secrets, permissions        | Use `/create`     |
+| Under 30 minutes         | Estimate < 30 min                    | Use `/create`     |
+| Clear scope              | Know exactly what to change          | Use `/brainstorm` |
+| Low risk                 | Won't break critical paths           | Use `/create`     |
+
+**Examples that qualify:**
+
+- Fix typo in UI text
+- Update a constant value
+- Fix off-by-one error
+- Add missing null check
+- Update documentation
+- Rename a variable
+- Fix CSS styling issue
+
+**Examples that DON'T qualify:**
+
+- Add new API endpoint (multiple files)
+- Change authentication logic (security)
+- Update database schema (DB changes)
+- Add new npm package (dependencies)
+- Refactor a module (scope unclear)
+
+---
+
+## Workflow
+
+### Step 1: Verify Scope (30 seconds)
+
+```bash
+# Check what files might be involved
+grep -r "[search-term]" src/ --include="*.{ts,tsx}" -l | head -5
+```
+
+If more than 1 file: **STOP** → Use `/create $ARGUMENTS` instead.
+
+### Step 2: Backup Current State
+
+```bash
+# Stash any existing changes
+git stash push -m "pre-quickbuild-$(date +%s)" 2>/dev/null || true
+
+# Note current commit
+git rev-parse HEAD
+```
+
+### Step 3: Make the Change
+
+```bash
+# Read the file
+read [file-path]
+
+# Make minimal, focused edit
+edit [file-path] [oldString] [newString]
+```
+
+**Edit guidelines:**
+
+- Change only what's necessary
+- Add comment if non-obvious
+- Don't refactor adjacent code
+- Don't fix unrelated issues
+
+### Step 4: Verify (unless --no-test)
+
+```bash
+# Type check
+npm run type-check || tsc --noEmit
+
+# Run relevant tests
+npm test -- --testPathPattern="[related-test]" --passWithNoTests
+
+# Lint check
+npm run lint -- [file-path]
+```
+
+**All checks must pass before committing.**
+
+### Step 5: Commit (unless --no-commit)
+
+```bash
+git add [file-path]
+git commit -m "fix: [concise description]
+
+Quick-build: [task description]"
+```
+
+**Commit message format:**
+
+- `fix:` for bug fixes
+- `chore:` for maintenance
+- `docs:` for documentation
+- `style:` for formatting
+
+---
+
+## Escape Hatch
+
+If during work you realize it's more complex:
+
+```
+⚠ Complexity detected:
+- Multiple files need changes
+- Found related issues that need fixing
+- Discovered missing test coverage
+
+Escaping to structured workflow...
+```
+
+**Action:**
+
+1. Revert uncommitted changes: `git checkout -- .`
+2. Create proper bead: `/create $ARGUMENTS`
+3. Continue with full workflow
+
+**Don't force a complex change through quick-build.**
+
+---
+
+## Time Budget
+
+| Task Type      | Max Time | Example                      |
+| -------------- | -------- | ---------------------------- |
+| Typo/text fix  | 5 min    | Fix spelling in button label |
+| Config change  | 10 min   | Update timeout value         |
+| Simple bug fix | 15 min   | Fix null check               |
+| Style fix      | 10 min   | Fix CSS alignment            |
+| Doc update     | 15 min   | Update README section        |
+
+**If approaching 30 minutes: STOP and escalate to /create.**
+
+---
+
+## Output
+
+```
+Quick Build Complete
+━━━━━━━━━━━━━━━━━━━━
+
+Task: [description]
+File: [path]
+Time: [X minutes]
+
+Changes:
+- [summary of change]
+
+Verification:
+✓ Type check passed
+✓ Tests passed (3 specs)
+✓ Lint passed
+
+Commit: [sha] "fix: [message]"
+
+Done. No bead created (trivial task).
+```
+
+---
+
+## Rollback
+
+If the quick fix causes issues:
+
+```bash
+# Revert the commit
+git revert HEAD --no-edit
+
+# Or reset to before
+git reset --hard HEAD~1
+```
+
+---
+
+## Examples
+
+```bash
+# Fix a typo
+/quick-build fix typo in login button text
+
+# Update a constant
+/quick-build change MAX_RETRIES from 3 to 5
+
+# Fix null check
+/quick-build add null check in getUserName function
+
+# CSS fix
+/quick-build fix button alignment in header
+
+# Skip tests for doc-only change
+/quick-build update README installation instructions --no-test
+```
+
+---
+
+## Anti-Patterns
+
+| Don't                       | Why                | Do Instead            |
+| --------------------------- | ------------------ | --------------------- |
+| Quick-build multiple files  | Scope creep        | Use `/create`         |
+| Skip tests for code changes | Risk of regression | Always verify         |
+| Fix "one more thing"        | Scope creep        | Separate quick-build  |
+| Force complex through       | Technical debt     | Escalate to `/create` |
+| Quick-build without reading | May miss context   | Read file first       |
+
+---
+
+## Related Commands
+
+| Need            | Command                     |
+| --------------- | --------------------------- |
+| Structured task | `/create` then `/implement` |
+| Just exploring  | Read files directly         |
+| Multiple fixes  | `/create` with sub-tasks    |
+| Need planning   | `/new-feature`              |

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

@@ -1,21 +1,445 @@
 ---
-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.
+## When to Use
 
-## Structured work (bead-based)
+| 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`    |
 
-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`
+## 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
+```