opencodekit 0.10.0 → 0.11.1

package/dist/template/.opencode/command/edit-image.md

@@ -1,40 +1,243 @@
 ---
 description: Edit image with natural language instructions
-argument-hint: "<image-path> <edit-instruction>"
+argument-hint: "<image-path> <edit-instruction> [--hd] [--preserve-size] [--compare]"
 agent: vision
 model: proxypal/gemini-3-pro-image-preview
 ---
 
 # Edit Image: $ARGUMENTS
 
-Edit an existing image using natural language.
+Edit an existing image using natural language instructions.
 
-## Instructions
+## Parse Arguments
 
-Parse from `$ARGUMENTS`:
+Extract from `$ARGUMENTS`:
 
-- Image path (first argument)
-- Edit instruction (remaining text)
+| Argument          | Required | Description                    |
+| ----------------- | -------- | ------------------------------ |
+| Image path        | Yes      | Path to source image           |
+| Edit instruction  | Yes      | Natural language edit request  |
+| `--hd`            | No       | Higher quality output (slower) |
+| `--preserve-size` | No       | Maintain original dimensions   |
+| `--compare`       | No       | Output before/after comparison |
 
-## Examples
+---
+
+## Edit Types & What Works
+
+### Works Well
+
+| Edit Type                  | Example                                   | Success Rate |
+| -------------------------- | ----------------------------------------- | ------------ |
+| **Background removal**     | "remove the background"                   | High         |
+| **Background replacement** | "replace background with beach sunset"    | High         |
+| **Color changes**          | "change the shirt to blue"                | High         |
+| **Style transfer**         | "make it look like a watercolor painting" | High         |
+| **Add elements**           | "add a hat to the person"                 | Medium-High  |
+| **Remove objects**         | "remove the car from the image"           | Medium-High  |
+| **Lighting adjustments**   | "make it look like golden hour"           | High         |
+| **Extend canvas**          | "extend the image to the right"           | Medium       |
 
-- `screenshot.png remove the background`
-- `logo.png change the color to blue`
-- `photo.jpg add a sunset sky`
-- `ui.png make the button larger`
+### Works Poorly (Set Expectations)
+
+| Edit Type                       | Why It's Hard                  | Alternative             |
+| ------------------------------- | ------------------------------ | ----------------------- |
+| **Text changes**                | AI struggles with precise text | Use image editor        |
+| **Face/hand details**           | Often distorts                 | Mask specific region    |
+| **Precise positioning**         | "Move object 50px left"        | Use coordinates in mask |
+| **Multiple simultaneous edits** | Conflicts                      | Do one edit at a time   |
+| **Preserving fine details**     | May blur/change                | Use `--preserve-size`   |
+
+---
 
 ## Process
 
-1. Load and analyze the source image
-2. Understand the edit request
-3. Apply the edit preserving unaffected areas
-4. Save to `.opencode/memory/design/edited/` with descriptive name
+1. **Load** the source image from path
+2. **Analyze** the original (note key features to preserve)
+3. **Interpret** the edit instruction
+4. **Apply** the edit, preserving unaffected areas
+5. **Save** with versioning to track iterations
+6. **Compare** if `--compare` flag set
+
+---
+
+## Common Edit Patterns
+
+### Background Operations
+
+```bash
+# Remove background (transparent)
+/edit-image photo.jpg remove the background
+
+# Replace background
+/edit-image photo.jpg replace background with a modern office
+
+# Extend/outpaint
+/edit-image landscape.jpg extend the sky upward
+```
+
+### Color & Style
+
+```bash
+# Color change
+/edit-image product.jpg change the product color to red
+
+# Style transfer
+/edit-image photo.jpg convert to anime style
+
+# Mood change
+/edit-image scene.jpg make it look like nighttime with city lights
+```
+
+### Object Manipulation
+
+```bash
+# Add object
+/edit-image room.jpg add a plant in the corner
+
+# Remove object
+/edit-image street.jpg remove the person on the left
+
+# Replace object
+/edit-image desk.jpg replace the laptop with a typewriter
+```
+
+### Enhancement
+
+```bash
+# Lighting
+/edit-image portrait.jpg add dramatic studio lighting
+
+# Quality
+/edit-image old-photo.jpg enhance and sharpen, remove grain --hd
+
+# Composition
+/edit-image product.jpg add subtle shadow underneath
+```
+
+---
 
 ## Output
 
-Report:
+### Standard Output
+
+```markdown
+## Edit Complete
+
+**Source:** `path/to/original.jpg`
+**Edit:** "remove the background"
+**Output:** `.opencode/memory/design/edited/original-v1-bg-removed.png`
+
+### Original Analysis
+
+- Dimensions: 1920x1080
+- Key elements: Person in center, office background
+- Preserved: Person, clothing, pose
+
+### Edit Applied
+
+- Background detected and removed
+- Edges refined with feathering
+- Output format: PNG (transparent)
+
+### Refinements Available
+
+- "Soften the edges more"
+- "Keep the shadow underneath"
+- "Make background white instead of transparent"
+```
+
+### Comparison Output (--compare)
+
+```markdown
+## Before/After Comparison
+
+| Aspect     | Before       | After       |
+| ---------- | ------------ | ----------- |
+| Background | Office scene | Transparent |
+| Subject    | Unchanged    | Unchanged   |
+| Dimensions | 1920x1080    | 1920x1080   |
+| File size  | 450KB        | 380KB       |
+
+**Visual diff:** Key changes highlighted in output
+```
+
+---
+
+## Version History
+
+Edits are saved with version tracking:
+
+```
+.opencode/memory/design/edited/
+├── photo-v1-bg-removed.png      # First edit
+├── photo-v2-color-change.png    # Second edit
+├── photo-v3-add-shadow.png      # Third edit
+└── photo-history.json           # Edit history
+```
+
+**History file:**
+
+```json
+{
+  "source": "photo.jpg",
+  "edits": [
+    { "v": 1, "instruction": "remove background", "timestamp": "..." },
+    { "v": 2, "instruction": "change shirt to blue", "timestamp": "..." }
+  ]
+}
+```
+
+To revert: Reference previous version as source.
+
+---
+
+## Tips for Better Results
+
+1. **Be specific**: "Add a red baseball cap" > "add a hat"
+2. **One edit at a time**: Chain simple edits for complex changes
+3. **Describe what to keep**: "Change background but keep the shadow"
+4. **Use style references**: "Make it look like a Pixar movie"
+5. **Specify format needs**: "Remove background, keep as PNG with transparency"
+
+---
+
+## Limitations
+
+- **Text editing**: AI cannot reliably modify or add text
+- **Precise geometry**: Exact pixel-level positioning not supported
+- **Faces**: May alter facial features unintentionally
+- **Hands**: Often produces artifacts
+- **Multiple subjects**: May struggle to isolate specific elements
+- **Brand logos**: May distort or refuse (safety filters)
+
+For precise edits, consider: Photoshop, GIMP, or Figma.
+
+---
+
+## Examples
+
+```bash
+# Basic edit
+/edit-image screenshot.png remove the background
+
+# High quality with comparison
+/edit-image product.jpg enhance lighting and add reflection --hd --compare
+
+# Preserve dimensions
+/edit-image banner.png change the color scheme to dark mode --preserve-size
+
+# Style transfer
+/edit-image photo.jpg convert to oil painting style --hd
+```
+
+---
+
+## Related Commands
 
-- Original image analysis
-- Edit applied
-- Output path
-- Offer refinements
+| Need               | Command           |
+| ------------------ | ----------------- |
+| Generate new image | `/generate-image` |
+| Analyze image      | `/analyze-mockup` |
+| Restore old photo  | `/restore-image`  |
+| Create icon        | `/generate-icon`  |

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

@@ -8,15 +8,21 @@ agent: build
 
 **Load skills:**
 
-- `skill({ name: "verification-before-completion" })`
-- `skill({ name: "finishing-a-development-branch" })`
+```typescript
+skill({ name: "beads" }); // Session protocol
+skill({ name: "verification-before-completion" });
+skill({ name: "finishing-a-development-branch" });
+```
 
-## Phase 1: Load Bead
+## Phase 1: Load Bead & Check Messages
 
 ```typescript
 bd_show({ id: "$ARGUMENTS" });
+bd_inbox({ n: 5, unread: true, global: false });
 ```
 
+Review any messages about this bead before proceeding.
+
 Verify status is `in-progress` or `open`.
 
 ## Phase 2: Detect Project Type
@@ -27,50 +33,24 @@ Check which project files exist to determine verification commands:
 ls package.json Cargo.toml pyproject.toml setup.py Makefile go.mod 2>/dev/null || true
 ```
 
-**Node.js/TypeScript** (`package.json` exists):
-
-- Build: `npm run build` or `bun run build`
-- Test: `npm test` or `bun test`
-- Lint: `npm run lint` or `bun run lint`
-- Type check: `npm run type-check` or `bun run type-check`
-
-**Rust** (`Cargo.toml` exists):
-
-- Build: `cargo build`
-- Test: `cargo test`
-- Lint: `cargo clippy -- -D warnings`
-
-**Python** (`pyproject.toml` or `setup.py` exists):
-
-- Test: `pytest`
-- Lint: `ruff check .` or `flake8`
-- Type check: `mypy .`
+| Project Type       | Build            | Test            | Lint                          |
+| ------------------ | ---------------- | --------------- | ----------------------------- |
+| Node.js/TypeScript | `npm run build`  | `npm test`      | `npm run lint && type-check`  |
+| Rust               | `cargo build`    | `cargo test`    | `cargo clippy -- -D warnings` |
+| Python             | -                | `pytest`        | `ruff check . && mypy .`      |
+| Go                 | `go build ./...` | `go test ./...` | `golangci-lint run`           |
+| Make-based         | `make build`     | `make test`     | `make lint`                   |
 
-**Go** (`go.mod` exists):
-
-- Build: `go build ./...`
-- Test: `go test ./...`
-- Lint: `golangci-lint run`
-
-**Make-based** (`Makefile` exists, no other markers):
-
-- Build: `make build`
-- Test: `make test`
-- Lint: `make lint`
-
-**No recognized files:** Skip automated gates, proceed to Phase 4.
-
-Check if each command actually exists before running (e.g., verify script exists in `package.json`).
+Check if each command actually exists before running.
 
 ## Phase 3: Hard Gates (MUST ALL PASS)
 
-Run detected verification commands. Skip any that don't exist for the project.
-
-Report:
+Run detected verification commands. Skip any that don't exist.
 
 ```
 Finish Gates: <bead-id>
 ━━━━━━━━━━━━━━━━━━━━━━
+
 Project: [detected type]
 
 Build:      [✓/✗/skipped]
@@ -97,13 +77,19 @@ Read spec:
 cat .beads/artifacts/<bead-id>/spec.md
 ```
 
-Check each success criterion:
+Check each success criterion with its verification command:
 
 ```
 Success Criteria:
-- [x] [Criterion 1] - verified by [how]
-- [x] [Criterion 2] - verified by [how]
-- [ ] [Criterion 3] - NOT MET: [reason]
+━━━━━━━━━━━━━━━━
+
+- [x] [Criterion 1]
+      Verify: `[command]` ✓
+- [x] [Criterion 2]
+      Verify: `[command]` ✓
+- [ ] [Criterion 3] - NOT MET
+      Verify: `[command]` ✗
+      Reason: [what failed]
 ```
 
 **If any criterion not met: STOP.**
@@ -115,7 +101,38 @@ Missing:
 - [Criterion] - [what's needed]
 ```
 
-## Phase 5: Create Review
+## Phase 5: Verify ADR (for L/XL tasks)
+
+Check if spec indicated L/XL complexity:
+
+```bash
+cat .beads/artifacts/<bead-id>/adr.md 2>/dev/null || echo "No ADR"
+```
+
+For L/XL tasks, ADR should exist documenting the design decision.
+
+If missing and was L/XL: Warn but don't block.
+
+## Phase 6: Calculate Estimation Accuracy
+
+Extract estimate from spec/plan and compare to actual:
+
+```
+Estimation Accuracy:
+━━━━━━━━━━━━━━━━━━━
+
+Estimated: [S/M/L] (~[N] tool calls)
+Actual: [N] tool calls
+Variance: [+/-N%] ([over/under]estimated)
+```
+
+**Learning signals:**
+
+- > 50% over: Task was harder than expected. Document why in review.
+- > 50% under: Task was easier. Consider if similar tasks should be estimated lower.
+- Within 20%: Good estimate. Pattern worth remembering.
+
+## Phase 7: Create Review
 
 Write `.beads/artifacts/<bead-id>/review.md`:
 
@@ -125,6 +142,16 @@ Write `.beads/artifacts/<bead-id>/review.md`:
 **Bead:** <bead-id>
 **Completed:** <date>
 
+## Estimation Accuracy
+
+| Metric    | Value                |
+| --------- | -------------------- |
+| Estimated | [S/M/L] (~[N] calls) |
+| Actual    | [N] calls            |
+| Variance  | [+/-N%]              |
+
+**Why variance?** [If significant, explain]
+
 ## Changes Made
 
 | File         | Change        |
@@ -136,13 +163,18 @@ Write `.beads/artifacts/<bead-id>/review.md`:
 
 - [Thing that went well]
 
+## What Was Difficult
+
+- [Challenge encountered and how resolved]
+
 ## What Was Skipped
 
 - [Thing intentionally not done and why]
 
-## Inconsistencies Found
+## Lessons Learned
 
-- [Any issues discovered but not fixed]
+- [Pattern worth documenting]
+- [Gotcha to remember]
 
 ## Test Coverage
 
@@ -155,7 +187,51 @@ Write `.beads/artifacts/<bead-id>/review.md`:
 - [x] [Criterion 2]
 ```
 
-## Phase 6: Final Commit
+## Phase 8: Create Observation (if notable findings)
+
+If you discovered something worth remembering:
+
+```typescript
+observation({
+  type: "learning", // or: decision, bugfix, pattern, discovery, warning
+  title: "[concise title]",
+  content: "[what was learned and why it matters]",
+  concepts: "[keywords]",
+  files: "[affected files]",
+  bead_id: "<bead-id>",
+});
+```
+
+**Create observations for:**
+
+- Patterns that should be reused
+- Gotchas that wasted time
+- Design decisions with rationale
+- Bug root causes
+
+## Phase 9: Update Memory (if applicable)
+
+If patterns or gotchas discovered:
+
+```typescript
+// For new patterns
+memory -
+  update({
+    file: "project/conventions",
+    content: "## [Pattern Name]\n\n[Description and example]",
+    mode: "append",
+  });
+
+// For gotchas
+memory -
+  update({
+    file: "project/gotchas",
+    content: "## [Gotcha Title]\n\n[What happened and how to avoid]",
+    mode: "append",
+  });
+```
+
+## Phase 10: Final Commit
 
 ```bash
 git add -A
@@ -173,27 +249,36 @@ git commit -m "<bead-id>: [summary of changes]
 Closes: <bead-id>"
 ```
 
-## Phase 7: Close Bead
+## Phase 11: Close Bead & Notify
 
-Complete the task and release any file reservations:
+Complete the task:
 
 ```typescript
 bd_done({ id: "$ARGUMENTS", msg: "Implemented: [1-liner summary]" });
 ```
 
-This closes the bead, releases file locks, and syncs with git.
+Notify dependent tasks are now unblocked:
 
-## Phase 8: Database Health Check
+```typescript
+bd_msg({
+  subj: "<bead-id> completed",
+  body: "Dependent tasks now unblocked. Summary: [1-liner]",
+  to: "all",
+  importance: "normal",
+  global: true,
+});
+```
 
-Check issue count:
+## Phase 12: Database Health Check
 
 ```typescript
 bd_ls({ status: "all", limit: 1 });
 ```
 
-**If >200 issues:** Warn about performance.
-
-**If >500 issues:** Strongly recommend cleanup with `bd_cleanup({ days: 7 })`.
+| Issue Count | Action                                       |
+| ----------- | -------------------------------------------- |
+| >200        | Warn about performance                       |
+| >500        | Strongly recommend `bd_cleanup({ days: 7 })` |
 
 ## Output
 
@@ -205,37 +290,44 @@ Gates: All passed ✓
 Criteria: All met ✓
 Commit: [commit hash]
 
+Estimation:
+- Estimated: [S/M/L] (~[N] calls)
+- Actual: [N] calls
+- Accuracy: [good/over/under]
+
 Artifacts:
 - .beads/artifacts/<bead-id>/spec.md
-- .beads/artifacts/<bead-id>/research.md
-- .beads/artifacts/<bead-id>/plan.md
 - .beads/artifacts/<bead-id>/review.md
+[- .beads/artifacts/<bead-id>/research.md]
+[- .beads/artifacts/<bead-id>/plan.md]
+[- .beads/artifacts/<bead-id>/adr.md]
 
 Branch: <bead-id>
 ```
 
-**If issue count >200:**
+**Next steps:**
 
 ```
-⚠️  Database has [count] issues. Consider running:
-    bd_cleanup({ days: 7 })
-    bd_sync()
-```
+━━━━━━━━━━━━━━━━━━━━━
 
-**Session recommendation:**
+Ready to merge:
+  /pr <bead-id>           # Create pull request
+  git checkout main && git merge <bead-id>  # Direct merge
 
+Or start fresh:
+  → Start new session for next task
+  → Previous work: read_session("last")
 ```
-━━━━━━━━━━━━━━━━━━━━━
-Task complete. For best performance:
-→ Start a fresh agent session for next task
-→ Previous work available via read_session("last")
 
-Next: Create PR or merge to main
-```
+**If issue count >200:**
 
-After calling `bd_done()`, restart your session for a fresh context. The one-task-per-session pattern keeps agents fast and focused.
+```
+⚠️  Database has [count] issues. Run:
+    bd_cleanup({ days: 7 })
+    bd_sync({ reason: "Cleanup after finish" })
+```
 
-**If work was interrupted or partially complete:**
+**If work was incomplete:**
 
 ```
 ⚠️  Work incomplete? Create handoff: