opencodekit 0.10.0 → 0.11.1

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

@@ -1,30 +1,368 @@
 ---
 description: Fix type errors with optional bead tracking
-argument-hint: "[bead-id]"
+argument-hint: "[bead-id] [--strict]"
+agent: build
 ---
 
 # Fix Type Errors
 
-**Load skill:** `skill({ name: "systematic-debugging" })`
+## Load Beads Skill
 
-Run `bun run typecheck` and fix all type errors.
+```typescript
+skill({ name: "beads" });
+```
+
+## Options
+
+- `--strict`: Also fix warnings and enable stricter checks
+
+## Phase 1: Load Context
+
+**Load skill:**
+
+```typescript
+skill({ name: "systematic-debugging" });
+```
+
+**Check for bead context:**
+
+```typescript
+bd_show({ id: "$ARGUMENTS" });
+```
+
+**Reserve files:**
+
+```typescript
+bd_reserve({
+  paths: ["src/**/*.ts", "src/**/*.tsx"],
+  reason: "Fixing type errors",
+  ttl: 600,
+});
+```
+
+## Phase 2: Detect Project & Run Type Check
+
+**Detect type check command:**
+
+```bash
+# Check package.json for type-check script
+grep -q "type-check\|typecheck" package.json && echo "npm run type-check"
+
+# Or use tsc directly
+npx tsc --noEmit
+```
+
+| Project Type | Type Check Command                         |
+| ------------ | ------------------------------------------ |
+| npm          | `npm run type-check` or `npx tsc --noEmit` |
+| bun          | `bun run typecheck`                        |
+| yarn         | `yarn type-check`                          |
+| pnpm         | `pnpm type-check`                          |
+
+**Capture initial error count:**
+
+```bash
+npx tsc --noEmit 2>&1 | grep -c "error TS"
+```
+
+```
+Type Check Status:
+━━━━━━━━━━━━━━━━━━
+
+Initial errors: [N]
+Files affected: [N]
+```
+
+## Phase 3: Use LSP for Semantic Analysis
+
+Get errors with full context:
+
+```typescript
+lsp_diagnostics({ filePath: "<file>", severity: "error" });
+```
+
+For each file with errors:
+
+```typescript
+lsp_hover({ filePath: "<file>", line: N, character: N }); // Understand types
+lsp_goto_definition({ filePath: "<file>", line: N, character: N }); // Find source
+```
+
+## Phase 4: Categorize Errors
+
+Group errors by pattern:
+
+| Category               | Error Pattern                       | Typical Fix                      |
+| ---------------------- | ----------------------------------- | -------------------------------- |
+| **Missing type**       | `implicitly has 'any' type`         | Add explicit type annotation     |
+| **Incorrect type**     | `Type 'X' is not assignable to 'Y'` | Fix type or add conversion       |
+| **Null/undefined**     | `possibly 'null' or 'undefined'`    | Add null check or optional chain |
+| **Property missing**   | `Property 'x' does not exist`       | Add to interface or fix typo     |
+| **Generic constraint** | `does not satisfy constraint`       | Fix generic or add constraint    |
+| **Import error**       | `Cannot find module`                | Fix import path or install dep   |
+| **Overload mismatch**  | `No overload matches this call`     | Check function signature         |
+| **Readonly violation** | `Cannot assign to 'x' (read-only)`  | Remove mutation or cast          |
+
+```
+Error Categories:
+━━━━━━━━━━━━━━━━
+
+- Missing types: [N]
+- Incorrect types: [N]
+- Null handling: [N]
+- Property errors: [N]
+- Other: [N]
+```
+
+## Phase 5: Estimate Complexity
+
+| Signals                                  | Estimate | Approach         |
+| ---------------------------------------- | -------- | ---------------- |
+| <10 errors, single category              | S (~10)  | Quick fix        |
+| 10-30 errors, few categories             | M (~30)  | Systematic       |
+| 30-100 errors, multiple categories       | L (~100) | Batch by pattern |
+| >100 errors or architectural type issues | XL       | Plan first       |
+
+## Phase 6: Fix Errors
+
+### Rules (MUST follow)
+
+- ❌ **Never** use `any` just to pass type check
+- ❌ **Never** use `// @ts-ignore` without justification
+- ❌ **Never** use `as unknown as T` pattern
+- ✅ **Prefer** proper typing over type assertions
+- ✅ **Prefer** narrowing with type guards
+- ✅ **Prefer** `unknown` over `any` when type is truly unknown
 
-## Rules
+### Common Fixes
 
-- Fix all type errors and repeat the process until there are no more type errors.
-- Do not use `any` just to pass the type check.
-- Prefer proper typing over type assertions where possible.
+**Missing type on parameter:**
 
-## Bead Integration (Optional)
+```typescript
+// Before
+function process(data) { ... }
+
+// After
+function process(data: ProcessInput): ProcessOutput { ... }
+```
+
+**Null/undefined handling:**
+
+```typescript
+// Before
+const name = user.name.toUpperCase();
+
+// After (optional chaining)
+const name = user?.name?.toUpperCase() ?? "Unknown";
+
+// After (type guard)
+if (user?.name) {
+  const name = user.name.toUpperCase();
+}
+```
 
-If a bead ID is provided (`$ARGUMENTS`), track the type fixing work:
+**Property doesn't exist:**
 
-1. **Before fixing:** Note the initial error count via `bd_msg` or notes
+```typescript
+// Before
+interface User {
+  name: string;
+}
+user.email; // Error
+
+// After - extend interface
+interface User {
+  name: string;
+  email?: string;
+}
+```
+
+**Generic constraint:**
+
+```typescript
+// Before
+function getValue<T>(obj: T, key: string) {
+  return obj[key]; // Error
+}
+
+// After
+function getValue<T extends Record<string, unknown>>(obj: T, key: keyof T) {
+  return obj[key];
+}
+```
 
-2. **After fixing:** Update with resolution summary
+### Batch Fixing Strategy
 
-If type errors reveal deeper issues requiring refactoring, create a follow-up bead:
+For many errors of same type:
 
 ```typescript
-bd_add({ title: "Refactor: <type issue summary>", type: "task", pri: 2 });
+// Use AST grep to find patterns
+ast - grep({ pattern: "function $NAME($PARAMS) {" }); // Find untyped functions
+```
+
+Fix one, then apply pattern to similar cases.
+
+## Phase 7: Iterate Until Clean
+
+```bash
+npx tsc --noEmit 2>&1
+```
+
+Repeat until:
+
+```
+Type Check: 0 errors ✓
+```
+
+**Maximum iterations:** 5 passes. If still errors after 5, reassess approach.
+
+## Phase 8: Verification
+
+**Type check passes:**
+
+```bash
+npx tsc --noEmit
+```
+
+**Tests still pass:**
+
+```bash
+npm test
+```
+
+**Lint still passes:**
+
+```bash
+npm run lint
+```
+
+```
+Verification:
+━━━━━━━━━━━━━
+
+Types: 0 errors ✓
+Tests: Passing ✓
+Lint: Passing ✓
+```
+
+## Phase 9: Track Improvement
+
+```
+Type Error Resolution:
+━━━━━━━━━━━━━━━━━━━━━━
+
+Before: [N] errors
+After: 0 errors
+Reduction: 100%
+
+By category:
+- Missing types: [N] → 0
+- Null handling: [N] → 0
+- Property errors: [N] → 0
+```
+
+## Phase 10: Document Patterns
+
+If you discovered useful type patterns:
+
+```typescript
+observation({
+  type: "pattern",
+  title: "Type pattern: [name]",
+  content: `
+## Pattern
+[Description of the type pattern]
+
+## Example
+\`\`\`typescript
+[Code showing the pattern]
+\`\`\`
+
+## When to Use
+[When this pattern applies]
+  `,
+  concepts: "typescript, types, [specific pattern]",
+  bead_id: "<bead-id>",
+});
+```
+
+Update conventions if this should be standard:
+
+```typescript
+memory -
+  update({
+    file: "project/conventions",
+    content: `
+## Type Pattern: [Name]
+
+[Pattern description and example]
+  `,
+    mode: "append",
+  });
+```
+
+## Phase 11: Handle Deep Issues
+
+If type errors reveal architectural problems:
+
+```typescript
+bd_add({
+  title: "Refactor: [type issue summary]",
+  type: "task",
+  pri: 2,
+  desc: "Type errors revealed need for: [description]",
+});
+```
+
+## Phase 12: Commit & Sync
+
+```bash
+git add <files>
+git commit -m "fix(types): resolve type errors
+
+- Fixed [N] type errors
+- Categories: [list main categories]
+- No 'any' types added
+[bead-id if applicable]"
+```
+
+```typescript
+bd_release({ _: true });
+bd_sync({ reason: "Fixed type errors" });
+```
+
+## Output
+
+```
+Type Errors Fixed
+━━━━━━━━━━━━━━━━━
+
+Estimate: [S/M/L]
+Before: [N] errors
+After: 0 errors
+
+Categories fixed:
+- Missing types: [N]
+- Null handling: [N]
+- Property errors: [N]
+
+Verification:
+- Type check: ✓
+- Tests: ✓
+- Lint: ✓
+
+'any' types added: 0 ✓
+Patterns documented: [N]
+
+Commit: [hash]
+```
+
+**Next steps:**
+
+```
+If part of larger task:
+  /implement <bead-id>
+
+If standalone:
+  /finish <bead-id>
 ```

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

@@ -1,22 +1,308 @@
 ---
 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" })
+## Load Beads Skill
 
-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
+```typescript
+skill({ name: "beads" });
+```
 
-If bead exists, update `.beads/artifacts/<bead-id>/review.md` and run `/finish`.
+## Options
+
+- `--a11y`: Include full accessibility audit
+
+## 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>
+```