opencodekit 0.10.0 → 0.11.1

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

@@ -1,22 +1,275 @@
 ---
 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.
+## Load Beads Skill
 
-**Complex (unclear cause, multiple files):**
+```typescript
+skill({ name: "beads" });
+```
 
-skill({ name: "systematic-debugging" })
+## Options
+
+- `--quick`: Skip deep analysis, fix directly (for obvious bugs)
+
+## 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
+```

package/dist/template/.opencode/command/generate-diagram.md

@@ -1,48 +1,349 @@
 ---
-description: Generate technical diagrams, flowcharts, wireframes
-argument-hint: "<description> [type: flowchart|wireframe|architecture|erd|sequence]"
+description: Generate technical diagrams, flowcharts, and visual documentation
+argument-hint: "<description> [--type=<type>] [--style=<style>] [--format=<format>] [--from-code]"
 agent: vision
 model: proxypal/gemini-3-flash-preview
 ---
 
 # Generate Diagram: $ARGUMENTS
 
-Generate technical diagrams and visual documentation.
+Generate technical diagrams and visual documentation with Mermaid code output.
 
-## Instructions
+## Parse Arguments
 
-Parse from `$ARGUMENTS`:
+| Argument      | Default   | Options                         |
+| ------------- | --------- | ------------------------------- |
+| Description   | required  | What the diagram shows          |
+| `--type`      | flowchart | See diagram types below         |
+| `--style`     | clean     | clean, sketch, formal, colorful |
+| `--format`    | both      | png, svg, mermaid, both         |
+| `--size`      | medium    | simple, medium, complex         |
+| `--from-code` | false     | Analyze codebase to generate    |
+| `--colors`    | default   | Brand colors or preset          |
 
-- Diagram description
-- Type (default: flowchart)
+---
+
+## Diagram Types
+
+| Type           | Description                              | Best For                |
+| -------------- | ---------------------------------------- | ----------------------- |
+| `flowchart`    | Process flows, decision trees            | Workflows, algorithms   |
+| `sequence`     | Interaction sequences, API calls         | System interactions     |
+| `architecture` | System components, infrastructure        | High-level design       |
+| `erd`          | Entity relationship diagrams             | Database design         |
+| `class`        | Class diagrams, inheritance              | OOP design              |
+| `state`        | State machines, transitions              | UI states, workflows    |
+| `mindmap`      | Hierarchical concepts                    | Brainstorming, planning |
+| `gantt`        | Timeline, project schedule               | Project planning        |
+| `wireframe`    | UI layouts, screen mockups               | UX design               |
+| `network`      | Network topology                         | Infrastructure          |
+| `c4`           | C4 model (context, container, component) | Architecture docs       |
+
+---
+
+## Workflow: AI vs Mermaid-First
+
+### Use AI Generation When:
+
+- Creating wireframes or visual mockups
+- Need artistic/sketch style
+- Complex visual that Mermaid can't express
+
+### Use Mermaid-First When:
+
+- Technical diagrams (flowchart, sequence, erd, class)
+- Need precise control over structure
+- Will iterate on the diagram
+- Need version-controlled diagrams
+
+**Recommendation:** For technical diagrams, this command generates Mermaid code that you can edit and render.
+
+---
+
+## Mermaid Syntax Reference
+
+### Flowchart
+
+```mermaid
+flowchart TD
+    A[Start] --> B{Decision?}
+    B -->|Yes| C[Action 1]
+    B -->|No| D[Action 2]
+    C --> E[End]
+    D --> E
+```
+
+**Shapes:** `[Rectangle]` `(Rounded)` `{Diamond}` `([Stadium])` `[[Subroutine]]`
+**Directions:** `TD` (top-down), `LR` (left-right), `BT`, `RL`
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant A as API
+    participant D as Database
+
+    U->>A: POST /login
+    A->>D: Query user
+    D-->>A: User data
+    A-->>U: JWT token
+```
+
+**Arrows:** `->>` (solid), `-->>` (dashed), `-x` (cross), `-)` (async)
+
+### Entity Relationship
 
-## Types
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ LINE_ITEM : contains
+    PRODUCT ||--o{ LINE_ITEM : includes
 
-- **flowchart**: Process flows, decision trees
-- **wireframe**: UI layouts, screen mockups
-- **architecture**: System architecture, components
-- **erd**: Entity relationship diagrams
-- **sequence**: Interaction sequences
+    USER {
+        int id PK
+        string email
+        string name
+    }
+```
 
-## Output Formats
+**Cardinality:** `||` (one), `o{` (zero or more), `|{` (one or more)
 
-Generate both:
+### Class Diagram
 
-1. Visual image (PNG)
-2. Mermaid/PlantUML code equivalent
+```mermaid
+classDiagram
+    class User {
+        +String email
+        +String name
+        +login()
+        +logout()
+    }
+    class Admin {
+        +deleteUser()
+    }
+    User <|-- Admin
+```
 
-## Process
+**Relationships:** `<|--` (inheritance), `*--` (composition), `o--` (aggregation)
+
+### State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Loading : fetch
+    Loading --> Success : resolve
+    Loading --> Error : reject
+    Success --> Idle : reset
+    Error --> Idle : retry
+```
+
+### Gantt Chart
+
+```mermaid
+gantt
+    title Project Timeline
+    dateFormat YYYY-MM-DD
+    section Phase 1
+    Design     :a1, 2024-01-01, 2w
+    Development :a2, after a1, 4w
+    section Phase 2
+    Testing    :a3, after a2, 2w
+```
+
+### Mindmap
+
+```mermaid
+mindmap
+  root((Project))
+    Frontend
+      React
+      Tailwind
+    Backend
+      Node.js
+      PostgreSQL
+    DevOps
+      Docker
+      AWS
+```
+
+---
+
+## Style Options
+
+| Style      | Description             | Use Case                     |
+| ---------- | ----------------------- | ---------------------------- |
+| `clean`    | Minimal, professional   | Documentation, presentations |
+| `sketch`   | Hand-drawn appearance   | Informal, brainstorming      |
+| `formal`   | Box borders, structured | Enterprise, technical docs   |
+| `colorful` | Vibrant, color-coded    | Marketing, education         |
+
+---
+
+## Codebase Integration (--from-code)
+
+Analyze actual code to generate diagrams:
+
+```bash
+# Generate architecture from imports
+/generate-diagram system architecture --from-code --type=architecture
+
+# Generate ERD from models
+/generate-diagram database schema --from-code --type=erd
+
+# Generate class diagram from TypeScript
+/generate-diagram class relationships --from-code --type=class
+```
+
+**How it works:**
+
+1. Scans relevant source files
+2. Extracts structure (classes, functions, imports)
+3. Generates Mermaid code representing actual codebase
+4. Renders as diagram
+
+---
 
-1. Parse the description into structural elements
-2. Create clean, professional diagram
-3. Use consistent styling
-4. Include legend if complex
+## Examples by Type
+
+### Flowchart
+
+```bash
+# User authentication flow
+/generate-diagram user login process with email verification --type=flowchart
+
+# Algorithm
+/generate-diagram binary search algorithm --type=flowchart --style=clean
+```
+
+### Sequence Diagram
+
+```bash
+# API flow
+/generate-diagram OAuth2 authentication flow between client, auth server, and resource server --type=sequence
+
+# Microservice communication
+/generate-diagram order processing across payment, inventory, and shipping services --type=sequence
+```
+
+### Architecture
+
+```bash
+# System overview
+/generate-diagram e-commerce platform with React frontend, Node API, and PostgreSQL --type=architecture
+
+# Cloud infrastructure
+/generate-diagram AWS deployment with ECS, RDS, and CloudFront --type=architecture --style=formal
+```
+
+### ERD
+
+```bash
+# Database schema
+/generate-diagram user management system with users, roles, and permissions --type=erd
+
+# E-commerce
+/generate-diagram product catalog with categories, variants, and inventory --type=erd
+```
+
+### State Diagram
+
+```bash
+# UI states
+/generate-diagram form submission states from idle to loading to success or error --type=state
+
+# Order lifecycle
+/generate-diagram order status from pending through processing, shipped, delivered --type=state
+```
+
+---
+
+## Size/Complexity Guidance
+
+| Size      | Elements   | Description                  |
+| --------- | ---------- | ---------------------------- |
+| `simple`  | 3-5 nodes  | Quick sketch, single concept |
+| `medium`  | 6-12 nodes | Standard documentation       |
+| `complex` | 13+ nodes  | Comprehensive system view    |
+
+**Tip:** Start simple, iterate to add detail.
+
+---
 
 ## Output
 
-Save to `.opencode/memory/design/diagrams/`:
+### File Structure
+
+```
+.opencode/memory/design/diagrams/[name]/
+├── diagram.png           # Rendered image
+├── diagram.svg           # Vector version
+├── diagram.mmd           # Mermaid source code
+└── README.md             # Usage notes
+```
+
+### Inline Output
+
+```markdown
+## Generated Diagram
+
+**Type:** sequence
+**Description:** User authentication flow
+
+### Mermaid Code
+
+\`\`\`mermaid
+sequenceDiagram
+User->>Auth: Login request
+Auth->>DB: Validate credentials
+DB-->>Auth: User data
+Auth-->>User: JWT token
+\`\`\`
+
+### Rendered
+
+[PNG/SVG image displayed]
+
+### Usage
+
+- Embed in GitHub markdown (supports Mermaid natively)
+- Use Mermaid Live Editor for modifications
+- Export to PNG/SVG for presentations
+```
+
+---
+
+## Rendering Options
+
+| Platform     | Mermaid Support      |
+| ------------ | -------------------- |
+| GitHub       | Native in markdown   |
+| GitLab       | Native in markdown   |
+| Notion       | Via code block       |
+| Confluence   | Via plugin           |
+| VS Code      | Via extension        |
+| Mermaid Live | https://mermaid.live |
+
+---
+
+## Limitations
+
+| Limitation          | Workaround                                          |
+| ------------------- | --------------------------------------------------- |
+| Very large diagrams | Break into multiple smaller diagrams                |
+| Custom icons        | Use external tool, embed as image                   |
+| Precise positioning | Mermaid auto-layouts; use external tool for control |
+| Complex styling     | Basic theming only; export SVG for advanced styling |
+| Wireframes          | AI-generated image better than Mermaid              |
+
+---
 
-- Diagram image
-- Mermaid code file (.mmd)
+## Related Commands
 
-Report files and display the Mermaid code inline.
+| Need                 | Command            |
+| -------------------- | ------------------ |
+| Analyze mockup       | `/analyze-mockup`  |
+| Generate image       | `/generate-image`  |
+| Review architecture  | `/review-codebase` |
+| Create documentation | `/summarize`       |