opencodekit 0.9.2 → 0.11.0

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

@@ -1,52 +1,324 @@
 ---
-description: Analyze Github Actions logs and fix issues with bead tracking
-argument-hint: "[github-actions-url]"
+description: Analyze GitHub Actions logs and fix issues with bead tracking
+argument-hint: "<github-actions-url or run-id>"
+agent: build
 ---
 
-**Load skill:** `skill({ name: "systematic-debugging" })`
+# Fix CI: $ARGUMENTS
 
-For deep tracing: `skill({ name: "root-cause-tracing" })`
+## Phase 1: Load Skills & Create Bead
 
-## Github Actions URL
+**Load skills:**
 
-<url>$ARGUMENTS</url>
-
-## Create Bug Bead
+```typescript
+skill({ name: "systematic-debugging" });
+skill({ name: "root-cause-tracing" });
+```
 
-CI failures are P0 bugs. Create a bead to track:
+**CI failures are P0 bugs.** Create bead immediately:
 
 ```typescript
 bd_add({
-  title: "Fix CI: <failure summary>",
-  type: "task",
+  title: "Fix CI: [failure summary]",
+  type: "bug",
   pri: 0,
-  tags: ["bug"],
+  tags: ["ci", "bug"],
+});
+```
+
+**Reserve workflow files:**
+
+```typescript
+bd_reserve({
+  paths: [".github/workflows/**", "package.json", "tsconfig.json"],
+  reason: "Fixing CI: $ARGUMENTS",
+  ttl: 600,
+});
+```
+
+## Phase 2: Fetch CI Logs
+
+**From URL:**
+
+```bash
+# Extract run ID from URL
+# https://github.com/owner/repo/actions/runs/12345678
+gh run view 12345678 --log-failed
+```
+
+**From run ID:**
+
+```bash
+gh run view $ARGUMENTS --log-failed
+```
+
+**List recent failed runs:**
+
+```bash
+gh run list --status=failure --limit=5
+```
+
+**Get full logs:**
+
+```bash
+gh run view $ARGUMENTS --log > /tmp/ci-log.txt
+```
+
+## Phase 3: Extract Errors
+
+Parse the CI log for errors:
+
+```bash
+# Find error lines
+grep -i "error\|failed\|exception" /tmp/ci-log.txt | head -30
+
+# Find the failing step
+gh run view $ARGUMENTS --json jobs --jq '.jobs[] | select(.conclusion=="failure") | {name, steps: [.steps[] | select(.conclusion=="failure")]}'
+```
+
+**Extract key information:**
+
+| Field             | Extract                        |
+| ----------------- | ------------------------------ |
+| **Failing job**   | Which job failed               |
+| **Failing step**  | Which step in the job          |
+| **Error message** | Exact error text               |
+| **Exit code**     | Process exit code if available |
+| **Context**       | Lines before/after error       |
+
+```
+CI Failure Analysis:
+━━━━━━━━━━━━━━━━━━━━
+
+Job: [job name]
+Step: [step name]
+Error: [error message]
+
+Context:
+[relevant log lines]
+```
+
+## Phase 4: Identify Failure Pattern
+
+Common CI failure patterns:
+
+| Pattern                  | Symptoms                           | Typical Fix                         |
+| ------------------------ | ---------------------------------- | ----------------------------------- |
+| **Dependency issue**     | "module not found", npm/yarn error | Update lockfile, check versions     |
+| **Environment mismatch** | Works locally, fails in CI         | Check Node/Python version, env vars |
+| **Test flakiness**       | Intermittent failures              | Add retries, fix race conditions    |
+| **Build timeout**        | Job cancelled after N minutes      | Optimize build, increase timeout    |
+| **Type error**           | TypeScript compilation failed      | Fix type errors locally first       |
+| **Lint error**           | ESLint/Prettier failures           | Run lint locally, fix issues        |
+| **Secret missing**       | "secret not found"                 | Check repository secrets config     |
+| **Permission denied**    | GITHUB_TOKEN issues                | Check workflow permissions          |
+| **Cache issue**          | Stale cache causing failures       | Clear cache, update cache key       |
+| **Docker issue**         | Image pull/build failures          | Check Dockerfile, registry auth     |
+
+## Phase 5: Estimate Complexity
+
+| Signals                             | Estimate | Approach           |
+| ----------------------------------- | -------- | ------------------ |
+| Single config change, obvious fix   | S (~10)  | Quick fix          |
+| Dependency update, env var fix      | M (~30)  | Systematic         |
+| Flaky tests, race conditions        | L (~100) | Deep investigation |
+| Workflow restructure, cross-cutting | XL       | Plan first         |
+
+## Phase 6: Reproduce Locally (if possible)
+
+Try to reproduce the failure locally:
+
+```bash
+# Run the same commands as CI
+npm ci
+npm run build
+npm test
+npm run lint
+```
+
+If it passes locally but fails in CI:
+
+```bash
+# Check for environment differences
+node --version    # Compare to CI
+npm --version     # Compare to CI
+cat .nvmrc        # If exists
+```
+
+## Phase 7: Fix
+
+**For complex fixes (≥3 phases):**
+
+```typescript
+task({
+  subagent_type: "planner",
+  description: "Plan CI fix",
+  prompt: "Create implementation plan for fixing CI: [failure description]",
+});
+```
+
+Save plan to `.beads/artifacts/<bead-id>/spec.md`
+
+**Common fixes:**
+
+```bash
+# Dependency issues
+rm -rf node_modules package-lock.json
+npm install
+
+# Type errors
+npm run type-check  # Fix locally first
+
+# Lint errors
+npm run lint -- --fix
+
+# Cache issues (add to workflow)
+# - uses: actions/cache@v3
+#   with:
+#     key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+```
+
+## Phase 8: Verify Locally
+
+Before pushing:
+
+```bash
+npm run build
+npm test
+npm run lint
+npm run type-check
+```
+
+All must pass locally.
+
+## Phase 9: Push & Re-trigger CI
+
+```bash
+git add <files>
+git commit -m "fix(ci): <description>
+
+Root cause: [what was wrong]
+<bead-id>"
+
+git push
+```
+
+**Re-trigger CI:**
+
+```bash
+gh workflow run <workflow-name>
+# or
+gh run rerun $ARGUMENTS --failed
+```
+
+**Watch CI status:**
+
+```bash
+gh run watch
+```
+
+```
+CI Verification:
+━━━━━━━━━━━━━━━━
+
+Run ID: [new run id]
+Status: [pending/success/failure]
+URL: [run url]
+```
+
+## Phase 10: Handle Results
+
+**If CI passes:**
+
+```typescript
+observation({
+  type: "bugfix",
+  title: "CI fix: [summary]",
+  content: `
+## Root Cause
+[What was actually wrong]
+
+## Fix
+[What we changed]
+
+## Prevention
+[How to avoid in future]
+  `,
+  concepts: "ci, github-actions, [specific issue]",
+  bead_id: "<bead-id>",
 });
+
+bd_done({ id: "<bead-id>", msg: "CI fixed: [summary]" });
 ```
 
-Save the bead ID for tracking. Add the CI run reference via `bd_msg` or notes.
+**If CI still fails:**
 
-## Workflow
+Iterate:
 
-1. **Analyze:** Use `build` agent to read the GitHub Actions logs, analyze and find the root causes of the issues.
+1. Fetch new logs
+2. Identify new/remaining error
+3. Fix and push again
+4. Maximum 3 iterations before escalating
 
-2. **Plan:** For complex CI/CD problems (≥3 phases), delegate to `planner` agent to create a detailed implementation plan. Save plan to `.beads/artifacts/<bead-id>/spec.md`.
+**If fix makes things worse:**
 
-3. **Fix:** Use `build` agent to implement the fixes step by step.
+```bash
+git revert HEAD
+git push
+```
 
-4. **Verify:** Use `review` agent to run tests, ensure quality and security, then report back.
+Then reassess approach.
 
-5. **Iterate:** If there are issues or failed tests, `build` agent will fix them and repeat the process until all tests pass.
+## Phase 11: Update Memory
 
-## Close Bead
+If this was a recurring CI issue:
 
-Once CI passes:
+```typescript
+memory -
+  update({
+    file: "project/gotchas",
+    content: `
+## CI: [Issue Title]
+
+**Symptom:** [What you see in CI logs]
+**Cause:** [Root cause]
+**Fix:** [How to resolve]
+**Prevention:** [Config to prevent recurrence]
+  `,
+    mode: "append",
+  });
+```
+
+## Phase 12: Sync & Report
 
 ```typescript
-bd_done({ id: "<bead-id>", msg: "CI fixed: <summary of fix>" });
+bd_release({ _: true });
+bd_sync({ reason: "Fixed CI: $ARGUMENTS" });
+```
+
+```
+CI Fixed: $ARGUMENTS
+━━━━━━━━━━━━━━━━━━━━
+
+Estimate: [S/M/L]
+Root cause: [brief description]
+Pattern: [which common pattern]
+
+Changes:
+- [file] - [change]
+
+CI Run: [new run URL]
+Status: Passed ✓
+
+Observation: Created ✓
+Gotcha: [Added/Not needed]
+
+Commit: [hash]
 ```
 
 ## Notes
 
-- If `gh` command is not available, instruct the user to install and authorize GitHub CLI first.
-- If the fix reveals systemic issues, create related beads for follow-up work.
+- If `gh` CLI is not available: `brew install gh && gh auth login`
+- If fix reveals systemic issues, create follow-up beads
+- For flaky tests, consider adding retry logic or fixing race conditions
+- Check if same failure happened before: `gh run list --status=failure --limit=20`

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

@@ -1,30 +1,362 @@
 ---
 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" })`
+## Options
 
-Run `bun run typecheck` and fix all type errors.
+- `--strict`: Also fix warnings and enable stricter checks
 
-## Rules
+## Phase 1: Load Context
 
-- 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.
+**Load skill:**
 
-## Bead Integration (Optional)
+```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
 
-If a bead ID is provided (`$ARGUMENTS`), track the type fixing work:
+Group errors by pattern:
 
-1. **Before fixing:** Note the initial error count via `bd_msg` or notes
+| 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          |
 
-2. **After fixing:** Update with resolution summary
+```
+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
+
+### Common Fixes
 
-If type errors reveal deeper issues requiring refactoring, create a follow-up bead:
+**Missing type on parameter:**
 
 ```typescript
-bd_add({ title: "Refactor: <type issue summary>", type: "task", pri: 2 });
+// 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();
+}
+```
+
+**Property doesn't exist:**
+
+```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];
+}
+```
+
+### Batch Fixing Strategy
+
+For many errors of same type:
+
+```typescript
+// 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>
 ```