opencodekit 0.9.2 → 0.11.0

package/dist/template/.opencode/command/fix-ui.md

@@ -1,22 +1,302 @@
 ---
 description: Analyze and fix UI issues
-argument-hint: "[issue]"
+argument-hint: "<issue or bead-id> [--a11y]"
 agent: build
 ---
 
 # Fix UI: $ARGUMENTS
 
-skill({ name: "frontend-aesthetics" })
+## Options
 
-1. **Analyze:** Delegate to @vision for initial assessment
-   - If screenshots/videos provided, @vision describes issue in detail
-   - For large UI analysis, @vision uses Gemini CLI: `gemini -m gemini-2.5-flash` then `@[image] Analyze issue`
-2. **Research:** @vision checks design guidelines, component patterns
-   - Apply `frontend-aesthetics` criteria (typography, color, motion, backgrounds)
-3. **Fix:** Implement step by step
-   - Avoid generic AI aesthetics (Inter font, purple gradients, flat backgrounds)
-   - Use distinctive typography, cohesive themes, meaningful motion
-4. **Verify:** Screenshot/test the fix
-5. **Review:** Run tests, ensure quality
+- `--a11y`: Include full accessibility audit
 
-If bead exists, update `.beads/artifacts/<bead-id>/review.md` and run `/finish`.
+## Phase 1: Load Context
+
+**Check for bead context:**
+
+```typescript
+bd_show({ id: "$ARGUMENTS" });
+```
+
+**Load skill:**
+
+```typescript
+skill({ name: "frontend-aesthetics" });
+```
+
+**Reserve UI files:**
+
+```typescript
+bd_reserve({
+  paths: ["src/components/**", "src/styles/**"],
+  reason: "Fixing UI: $ARGUMENTS",
+  ttl: 600,
+});
+```
+
+## Phase 2: Capture Before State
+
+Take screenshot before making changes:
+
+```typescript
+// Using Playwright skill
+skill({ name: "playwright" });
+skill_mcp({
+  skill_name: "playwright",
+  tool_name: "browser_screenshot",
+  arguments: '{"name": "before-fix"}',
+});
+```
+
+Or use browser DevTools:
+
+```typescript
+skill({ name: "chrome-devtools" });
+```
+
+Save screenshot to `.beads/artifacts/<bead-id>/before.png`
+
+## Phase 3: Analyze with Vision
+
+Delegate to @vision for initial assessment:
+
+```typescript
+task({
+  subagent_type: "vision",
+  description: "Analyze UI issue",
+  prompt: `
+TASK: Analyze UI issue: $ARGUMENTS
+
+EXPECTED OUTCOME:
+- Describe the visual problem in detail
+- Identify affected components
+- Suggest fix approach
+- Check against frontend-aesthetics anti-patterns
+
+MUST DO:
+- Load the before screenshot
+- Identify specific CSS/component issues
+- Check for AI slop patterns (Inter font, purple gradients, flat backgrounds)
+- Assess color contrast and typography
+
+MUST NOT DO:
+- Don't make changes, just analyze
+- Don't suggest generic solutions
+
+CONTEXT:
+- Screenshot: .beads/artifacts/<bead-id>/before.png
+- Issue: $ARGUMENTS
+  `,
+});
+```
+
+## Phase 4: Estimate Complexity
+
+| Signals                                  | Estimate | Approach        |
+| ---------------------------------------- | -------- | --------------- |
+| Single component, CSS tweak              | S (~10)  | Quick fix       |
+| Multiple components, layout issue        | M (~30)  | Systematic fix  |
+| Cross-cutting, design system change      | L (~100) | Design review   |
+| Responsive + a11y + multiple breakpoints | XL       | Decompose first |
+
+## Phase 5: Design System Check
+
+Before fixing, verify design tokens:
+
+```bash
+# Check for design tokens/variables
+grep -r "var(--" src/styles/ | head -20
+grep -r "theme\." src/components/ | head -20
+```
+
+**Verify fix will use:**
+
+- [ ] Existing color tokens (not hardcoded colors)
+- [ ] Existing spacing scale (not arbitrary px values)
+- [ ] Existing typography scale
+- [ ] Existing breakpoints
+
+## Phase 6: Implement Fix
+
+**Anti-AI-slop checklist:**
+
+| Avoid                        | Use Instead                    |
+| ---------------------------- | ------------------------------ |
+| Inter/system-ui everywhere   | Distinctive, intentional fonts |
+| Purple/blue gradients        | Cohesive project color palette |
+| Flat, shadowless backgrounds | Subtle depth and texture       |
+| Generic rounded corners      | Consistent border-radius scale |
+| No motion                    | Meaningful, subtle animations  |
+
+**Make changes:**
+
+1. Identify affected files
+2. Make minimal, focused CSS/component changes
+3. Use existing design tokens
+4. Test in browser during development
+
+## Phase 7: Capture After State
+
+Take screenshot after changes:
+
+```typescript
+skill_mcp({
+  skill_name: "playwright",
+  tool_name: "browser_screenshot",
+  arguments: '{"name": "after-fix"}',
+});
+```
+
+Save to `.beads/artifacts/<bead-id>/after.png`
+
+## Phase 8: Verification
+
+### Visual Verification
+
+```typescript
+task({
+  subagent_type: "vision",
+  description: "Compare before/after",
+  prompt: `
+Compare these screenshots:
+- Before: .beads/artifacts/<bead-id>/before.png
+- After: .beads/artifacts/<bead-id>/after.png
+
+Verify:
+1. Issue is fixed
+2. No visual regressions
+3. Follows frontend-aesthetics principles
+4. No AI slop patterns introduced
+  `,
+});
+```
+
+### Responsive Verification
+
+Test at multiple breakpoints:
+
+| Breakpoint | Width  | Check                |
+| ---------- | ------ | -------------------- |
+| Mobile     | 375px  | Layout doesn't break |
+| Tablet     | 768px  | Spacing appropriate  |
+| Desktop    | 1280px | Full layout correct  |
+
+```typescript
+skill_mcp({
+  skill_name: "playwright",
+  tool_name: "browser_resize",
+  arguments: '{"width": 375, "height": 812}',
+});
+// Screenshot and verify
+```
+
+### Accessibility Verification (--a11y or always for M+ fixes)
+
+```typescript
+skill({ name: "accessibility-audit" });
+```
+
+Check:
+
+- [ ] Color contrast (4.5:1 for text, 3:1 for large text)
+- [ ] Keyboard navigation works
+- [ ] Focus states visible
+- [ ] Screen reader text present for icons
+- [ ] No motion for prefers-reduced-motion users
+
+### Automated Tests
+
+```bash
+npm test -- --grep "component-name"
+npm run test:visual  # If visual regression tests exist
+```
+
+```
+Verification:
+━━━━━━━━━━━━━
+
+Visual: Issue fixed ✓
+Responsive:
+  - Mobile (375px): ✓
+  - Tablet (768px): ✓
+  - Desktop (1280px): ✓
+Accessibility: [✓/⚠️ needs review]
+Tests: [✓/✗]
+```
+
+## Phase 9: Document & Observe
+
+If this revealed a UI pattern worth remembering:
+
+```typescript
+observation({
+  type: "pattern",
+  title: "[UI pattern name]",
+  content: `
+## Pattern
+[What we learned about UI implementation]
+
+## Example
+\`\`\`css
+[Code snippet]
+\`\`\`
+
+## When to Use
+[When this pattern applies]
+  `,
+  concepts: "ui, css, [component-type]",
+  files: "[affected files]",
+  bead_id: "<bead-id>",
+});
+```
+
+## Phase 10: Commit & Sync
+
+```bash
+git add <files>
+git commit -m "fix(ui): <description>
+
+- [what changed]
+- [visual improvement]
+[bead-id if applicable]"
+```
+
+```typescript
+bd_release({ _: true });
+bd_sync({ reason: "Fixed UI: $ARGUMENTS" });
+```
+
+## Output
+
+```
+UI Fixed: $ARGUMENTS
+━━━━━━━━━━━━━━━━━━━━
+
+Estimate: [S/M/L]
+Components: [list]
+
+Before: .beads/artifacts/<bead-id>/before.png
+After: .beads/artifacts/<bead-id>/after.png
+
+Verification:
+- Visual: ✓
+- Responsive: ✓
+- Accessibility: [✓/⚠️]
+- Tests: ✓
+
+Design system: Used existing tokens ✓
+AI slop check: None detected ✓
+
+Commit: [hash]
+```
+
+**Next steps:**
+
+```
+If part of larger task:
+  /implement <bead-id>
+
+If standalone fix:
+  /finish <bead-id>
+  /pr <bead-id>
+```

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

@@ -1,22 +1,269 @@
 ---
 description: Debug and fix issues
-argument-hint: "[issue]"
+argument-hint: "<issue or bead-id> [--quick]"
 agent: build
 ---
 
 # Fix: $ARGUMENTS
 
-**Simple (1-3 lines, obvious cause):** Fix directly, commit.
+## Options
 
-**Complex (unclear cause, multiple files):**
+- `--quick`: Skip deep analysis, fix directly (for obvious bugs)
 
-skill({ name: "systematic-debugging" })
+## Phase 1: Load Context
+
+**Check for bead context:**
+
+If `$ARGUMENTS` looks like a bead ID (e.g., `bd-abc123`):
+
+```typescript
+bd_show({ id: "$ARGUMENTS" });
+```
+
+Load constraints from `.beads/artifacts/<bead-id>/spec.md` if it exists.
+
+**Check for messages about this issue:**
+
+```typescript
+bd_inbox({ n: 5, unread: true, global: false });
+```
+
+## Phase 2: Parse Error Information
+
+Extract from the issue:
+
+| Field             | Extract                              |
+| ----------------- | ------------------------------------ |
+| **Error message** | Exact error text                     |
+| **Stack trace**   | Call stack with file:line references |
+| **Reproduction**  | Steps to trigger the bug             |
+| **Expected**      | What should happen                   |
+| **Actual**        | What happens instead                 |
+
+**For stack traces:**
+
+```bash
+# Find the first application code (skip node_modules, stdlib)
+grep -E "at .*(src/|lib/|app/)" <<< "[stack trace]"
+```
+
+## Phase 3: Estimate Complexity
+
+| Signals                                     | Estimate | Approach           |
+| ------------------------------------------- | -------- | ------------------ |
+| Error points to exact line, obvious fix     | S (~10)  | Quick fix          |
+| Error in known area, clear reproduction     | M (~30)  | Systematic debug   |
+| Intermittent, unclear cause, multiple files | L (~100) | Deep investigation |
+| No reproduction, architectural issue        | XL       | Research first     |
+
+```
+Fix Estimate: [S/M/L/XL]
+━━━━━━━━━━━━━━━━━━━━━━━
+
+Complexity: [description]
+Approach: [quick fix / systematic / deep investigation]
+```
+
+## Phase 4: Reserve Files
+
+```typescript
+bd_reservations({ reason: "Checking for conflicts before fix" });
+bd_reserve({
+  paths: ["<files-to-investigate>"],
+  reason: "Fixing $ARGUMENTS",
+  ttl: 600,
+});
+```
+
+## Phase 5: Investigation & Fix
+
+### Quick Fix (S estimate or --quick)
+
+1. Go directly to error location
+2. Identify obvious cause
+3. Make minimal fix
+4. Run targeted test
+5. Commit
+
+### Systematic Debug (M/L estimate)
+
+**Load skill:**
+
+```typescript
+skill({ name: "systematic-debugging" });
+```
 
 Follow four phases:
 
-1. Root cause investigation (NO fixes yet)
-2. Pattern analysis
-3. Hypothesis testing
-4. Implementation with TDD
+**1. Root Cause Investigation (NO fixes yet)**
+
+- Read error location and surrounding code
+- Trace data flow backward
+- Check recent changes: `git log -p --since="1 week ago" -- <file>`
+- Add logging/instrumentation if needed
+
+```
+Root Cause Hypothesis:
+━━━━━━━━━━━━━━━━━━━━━
+
+Cause: [what's actually wrong]
+Evidence: [how we know]
+Confidence: [High/Medium/Low]
+```
+
+**2. Pattern Analysis**
+
+- Is this a known pattern? Check gotchas.md
+- Similar bugs in history? `git log --grep="fix" --oneline`
+- Related code with same issue?
+
+**3. Hypothesis Testing**
+
+- Write a failing test that reproduces the bug
+- Verify hypothesis by checking test fails for right reason
+
+```bash
+npm test -- --grep "<bug-related-test>"
+```
+
+**4. Implementation with TDD**
+
+- Fix the code
+- Verify test now passes
+- Run full test suite for regression
+
+### Rollback Strategy
+
+Before making changes, note rollback point:
+
+```bash
+git stash  # or
+git rev-parse HEAD  # Save current commit
+```
+
+If fix makes things worse:
+
+```bash
+git checkout -- <file>  # Revert single file
+git stash pop           # Restore stashed changes
+git reset --hard <hash> # Nuclear option
+```
+
+## Phase 6: Verification
+
+**Targeted verification:**
+
+```bash
+npm test -- --grep "<related-test>"
+```
+
+**Regression check:**
+
+```bash
+npm test
+npm run lint
+npm run type-check
+```
+
+```
+Verification:
+━━━━━━━━━━━━━
+
+Bug test:  [✓ now passes]
+Full tests: [✓/✗]
+Lint:       [✓/✗]
+Types:      [✓/✗]
+```
+
+**If verification fails:** Iterate or rollback.
+
+## Phase 7: Document Root Cause
+
+Create observation for future reference:
+
+```typescript
+observation({
+  type: "bugfix",
+  title: "[Brief description of bug]",
+  content: `
+## Root Cause
+[What was actually wrong]
+
+## Fix
+[What we changed and why]
+
+## Prevention
+[How to avoid this in future]
+  `,
+  concepts: "[relevant keywords]",
+  files: "[affected files]",
+  bead_id: "<bead-id>",
+});
+```
+
+## Phase 8: Update Memory
+
+If this was a gotcha worth remembering:
+
+```typescript
+memory -
+  update({
+    file: "project/gotchas",
+    content: `
+## [Bug Title]
+
+**Symptom:** [What you see]
+**Cause:** [What's actually wrong]
+**Fix:** [How to resolve]
+**Prevention:** [How to avoid]
+  `,
+    mode: "append",
+  });
+```
+
+## Phase 9: Commit & Sync
+
+```bash
+git add <files>
+git commit -m "fix(<scope>): <description>
+
+Root cause: [brief explanation]
+[bead-id if applicable]"
+```
+
+Release locks and sync:
+
+```typescript
+bd_release({ _: true });
+bd_sync({ reason: "Fixed $ARGUMENTS" });
+```
+
+## Output
+
+```
+Fixed: $ARGUMENTS
+━━━━━━━━━━━━━━━━━
+
+Estimate: [S/M/L] (actual: [N] tool calls)
+Root cause: [brief description]
+
+Changes:
+- [file:line] - [what changed]
+
+Verification: All tests pass ✓
+Observation: Created ✓
+Gotcha: [Added to memory / Not needed]
+
+Commit: [hash]
+```
+
+**Next steps:**
+
+```
+If part of larger task:
+  /implement <bead-id>   # Continue implementation
 
-If bead exists, work within `.beads/artifacts/<bead-id>/spec.md` constraints.
+If standalone fix:
+  /finish <bead-id>      # Close the bead
+  /pr <bead-id>          # Create PR
+```