opencodekit 0.10.0 → 0.11.0

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

@@ -1,41 +1,251 @@
 ---
 description: Generate sequential images for visual storytelling
-argument-hint: "<story-description> [frames: N] [style: comic|realistic|sketch]"
+argument-hint: "<story-description> [--frames=<N>] [--style=<style>] [--aspect=<ratio>] [--layout=<layout>]"
 agent: vision
 model: proxypal/gemini-3-pro-image-preview
 ---
 
 # Generate Storyboard: $ARGUMENTS
 
-Generate a sequence of images telling a visual story.
+Generate a sequence of images telling a visual story with consistent characters and settings.
 
-## Instructions
+## Parse Arguments
 
-Parse from `$ARGUMENTS`:
+| Argument          | Default  | Options                          |
+| ----------------- | -------- | -------------------------------- |
+| Story description | required | Narrative or script to visualize |
+| `--frames`        | 4        | 3-12 frames                      |
+| `--style`         | sketch   | See style presets below          |
+| `--aspect`        | 16:9     | 16:9, 4:3, 1:1, 9:16             |
+| `--layout`        | grid     | grid, strip, single              |
+| `--captions`      | true     | Include scene descriptions       |
+| `--timing`        | false    | Add duration annotations         |
 
-- Story description or script
-- Number of frames (default: 4)
-- Visual style (default: sketch)
+---
+
+## Style Presets
+
+| Style        | Description                               | Best For                           |
+| ------------ | ----------------------------------------- | ---------------------------------- |
+| `sketch`     | Hand-drawn, rough lines, quick            | Pre-production, drafts             |
+| `comic`      | Bold lines, panels, dynamic               | Marketing, entertainment           |
+| `realistic`  | Photo-realistic rendering                 | Film pre-viz, client presentations |
+| `animation`  | Clean lines, flat colors                  | Animated content planning          |
+| `noir`       | High contrast, shadows, dramatic          | Thriller, drama                    |
+| `watercolor` | Soft, artistic, painterly                 | Emotional narratives               |
+| `minimalist` | Simple shapes, icons                      | UX flows, explainers               |
+| `cinematic`  | Widescreen, film grain, dramatic lighting | Video production                   |
+| `children`   | Bright colors, friendly, rounded          | Kids content                       |
+| `technical`  | Clean, annotated, precise                 | Product demos, tutorials           |
+
+---
+
+## Aspect Ratios
+
+| Ratio    | Dimensions  | Use Case                         |
+| -------- | ----------- | -------------------------------- |
+| `16:9`   | Widescreen  | Video, YouTube, presentations    |
+| `4:3`    | Traditional | Classic film, some presentations |
+| `1:1`    | Square      | Social media, Instagram          |
+| `9:16`   | Vertical    | TikTok, Stories, Reels           |
+| `2.35:1` | Anamorphic  | Cinematic widescreen             |
+
+---
+
+## Shot Types
+
+Specify shot types in your description for precise framing:
+
+| Shot                | Description                          | Emotional Effect            |
+| ------------------- | ------------------------------------ | --------------------------- |
+| `wide/establishing` | Full environment, tiny figures       | Context, scale, isolation   |
+| `medium`            | Waist up, some environment           | Conversation, action        |
+| `close-up`          | Face or object fills frame           | Emotion, detail, importance |
+| `extreme close-up`  | Eyes, hands, small detail            | Intensity, intimacy         |
+| `over-shoulder`     | Behind one character, facing another | Dialogue, connection        |
+| `bird's eye`        | Directly above                       | Overview, vulnerability     |
+| `low angle`         | Looking up at subject                | Power, dominance            |
+| `high angle`        | Looking down at subject              | Weakness, submission        |
+| `POV`               | Character's viewpoint                | Immersion, subjectivity     |
+
+**Example prompt with shots:**
+
+```
+Frame 1: Wide shot - City skyline at sunset, small figure on rooftop
+Frame 2: Medium shot - Character turns, looking worried
+Frame 3: Close-up - Phone screen showing message
+Frame 4: Over-shoulder - Character reading, city blurred behind
+```
+
+---
+
+## Panel Layouts
+
+| Layout     | Description                | Frames              |
+| ---------- | -------------------------- | ------------------- |
+| `grid`     | Even grid arrangement      | Any (auto-arranges) |
+| `strip`    | Single horizontal row      | 3-6 frames          |
+| `vertical` | Single vertical column     | 3-6 frames          |
+| `featured` | One large + smaller panels | 4-6 frames          |
+| `single`   | Individual images only     | Any                 |
+
+---
+
+## Use Cases
+
+### Video Production
+
+```bash
+# Commercial storyboard
+/generate-storyboard Product unboxing: hands open box, reveal product, show features, happy customer using it --frames=6 --style=cinematic --aspect=16:9
+
+# Music video
+/generate-storyboard Singer in empty warehouse, dancing, memories flash, reunites with loved one --frames=8 --style=noir --timing
+```
+
+### UX/Product Flows
+
+```bash
+# User journey
+/generate-storyboard User discovers app, signs up, completes first task, shares achievement --frames=4 --style=minimalist --aspect=1:1
+
+# Feature explainer
+/generate-storyboard Problem: messy desk. Solution: our app. Result: organized life --frames=3 --style=technical
+```
+
+### Marketing/Social
+
+```bash
+# Social campaign
+/generate-storyboard Day in the life with our coffee: morning routine, commute, work meeting, evening relaxation --frames=4 --style=watercolor --aspect=9:16
+
+# Brand story
+/generate-storyboard Founder's journey: garage startup, first customer, team growth, today's success --frames=6 --style=sketch
+```
+
+### Animation Planning
+
+```bash
+# Character animation
+/generate-storyboard Character walks in, sees something surprising, reacts with joy, celebrates --frames=4 --style=animation
 
-## Styles
+# Explainer video
+/generate-storyboard Complex data enters system, gets processed, outputs simple insights --frames=5 --style=minimalist
+```
 
-- **comic**: Bold lines, panels, speech bubbles
-- **realistic**: Photo-realistic scenes
-- **sketch**: Hand-drawn, rough storyboard style
+---
+
+## Maintaining Consistency
+
+### Character Consistency
+
+Include character details in your prompt:
+
+```
+Main character: Young woman, short black hair, red jacket, determined expression
+Setting: Rainy city at night, neon signs, wet streets
+```
+
+### Consistency Tips
+
+1. **Define characters first**: Age, hair, clothing, distinguishing features
+2. **Establish setting**: Time of day, weather, key environmental elements
+3. **Maintain color palette**: Specify dominant colors to carry through
+4. **Reference previous frames**: "Same character from frame 1..."
+5. **Use consistent lighting**: Define light source direction
+
+---
+
+## Transitions & Timing
+
+Use `--timing` to add duration annotations:
+
+| Transition | Symbol | Description          |
+| ---------- | ------ | -------------------- | --------------- |
+| Cut        | `→`    | Instant switch       |
+| Fade       | `~>`   | Gradual transition   |
+| Dissolve   | `<~>`  | Blend between frames |
+| Wipe       | `      | >`                   | Edge transition |
+
+**Example output with timing:**
+
+```
+Frame 1 (3s) → Frame 2 (2s) ~> Frame 3 (4s) → Frame 4 (2s)
+```
+
+---
 
-## Process
+## Captions & Dialogue
 
-1. Break story into key moments
-2. Maintain visual consistency (characters, settings)
-3. Generate each frame with clear narrative progression
-4. Number frames sequentially
+Include dialogue or narration:
+
+```bash
+/generate-storyboard Scene: coffee shop meeting
+Frame 1: "Two old friends spot each other" - wide shot, recognition
+Frame 2: "They haven't seen each other in years" - medium, approaching
+Frame 3: "Warm embrace" - close-up, emotional hug
+Frame 4: "Just like old times" - sitting, laughing, coffee cups
+```
+
+---
 
 ## Output
 
-Save to `.opencode/memory/design/storyboards/<story-name>/`:
+### File Structure
+
+```
+.opencode/memory/design/storyboards/[story-name]/
+├── frames/
+│   ├── 01-establishing.png
+│   ├── 02-introduction.png
+│   ├── 03-conflict.png
+│   └── 04-resolution.png
+├── storyboard-sheet.png      # Combined layout
+├── storyboard-sheet.pdf      # Print-ready
+└── script.md                 # Scene descriptions + timing
+```
+
+### Script Output
+
+```markdown
+# Storyboard: [Story Name]
+
+## Frame 1 - Establishing Shot
+
+**Duration:** 3 seconds
+**Shot:** Wide
+**Description:** City skyline at sunset, small figure visible on rooftop
+**Audio:** Ambient city sounds, distant traffic
+**Transition:** Cut to →
+
+## Frame 2 - Introduction
+
+**Duration:** 2 seconds
+**Shot:** Medium
+**Description:** Character turns, worried expression
+**Dialogue:** (thinking) "Where is she?"
+**Transition:** Fade to ~>
+```
+
+---
+
+## Limitations
+
+| Limitation                    | Workaround                                                 |
+| ----------------------------- | ---------------------------------------------------------- |
+| Perfect character consistency | Include detailed character description; may need touch-ups |
+| Exact pose matching           | Describe poses clearly; use reference terms                |
+| Complex action sequences      | Break into more frames                                     |
+| Text/dialogue in image        | Add text in post-processing                                |
+| Specific brand elements       | Describe style, add logos later                            |
+
+---
 
-- Individual frame images (01.png, 02.png, etc.)
-- Combined storyboard sheet
-- Scene descriptions text file
+## Related Commands
 
-Report generated sequence.
+| Need                  | Command             |
+| --------------------- | ------------------- |
+| Generate single image | `/generate-image`   |
+| Edit a frame          | `/edit-image`       |
+| Create diagram        | `/generate-diagram` |
+| Analyze reference     | `/analyze-mockup`   |

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

@@ -8,10 +8,25 @@ agent: build
 
 **Load skill:** `skill({ name: "verification-before-completion" })`
 
-## Phase 1: Gather State
+## Phase 1: Check Messages
+
+Check for any messages that might affect handoff:
+
+```typescript
+bd_inbox({ n: 5, unread: true, global: true });
+```
+
+## Phase 2: Release Locks
+
+Release any file reservations you hold:
+
+```typescript
+bd_release({ _: true });
+```
+
+## Phase 3: Gather State
 
 ```typescript
-// Bead info
 bd_show({ id: "$ARGUMENTS" });
 ```
 
@@ -26,7 +41,33 @@ git status --porcelain
 git diff --stat
 ```
 
-## Phase 2: Commit WIP (if needed)
+## Phase 4: Verify Artifacts
+
+Check what artifacts exist and are valid:
+
+```bash
+ls -la .beads/artifacts/<bead-id>/ 2>/dev/null
+```
+
+For each artifact, verify it's not empty:
+
+```bash
+wc -l .beads/artifacts/<bead-id>/spec.md 2>/dev/null
+wc -l .beads/artifacts/<bead-id>/research.md 2>/dev/null
+wc -l .beads/artifacts/<bead-id>/plan.md 2>/dev/null
+```
+
+```
+Artifact Check:
+━━━━━━━━━━━━━━
+
+- spec.md: [exists/missing] ([N] lines)
+- research.md: [exists/missing] ([N] lines)
+- plan.md: [exists/missing] ([N] lines)
+- review.md: [exists/missing] ([N] lines)
+```
+
+## Phase 5: Commit WIP (if needed)
 
 If uncommitted changes exist:
 
@@ -35,7 +76,23 @@ git add -A
 git commit -m "WIP: <bead-id> - [current step]"
 ```
 
-## Phase 3: Create Handoff
+## Phase 6: Calculate Session Stats
+
+Track estimation accuracy:
+
+```
+Session Stats:
+━━━━━━━━━━━━━━
+
+Estimate: [S/M/L] (~[N] tool calls)
+Actual: [N] tool calls
+Variance: [+/-N%]
+
+Progress: [N]% complete
+Time in session: [estimated duration]
+```
+
+## Phase 7: Create Handoff
 
 Write `.beads/artifacts/<bead-id>/handoffs/<timestamp>.md`:
 
@@ -47,15 +104,26 @@ Write `.beads/artifacts/<bead-id>/handoffs/<timestamp>.md`:
 
 ## Provenance
 
-- **Repo:** [git remote URL]
-- **Branch:** [branch name]
-- **Commit:** [commit hash]
-- **Clean:** [yes/no]
+| Field  | Value            |
+| ------ | ---------------- |
+| Repo   | [git remote URL] |
+| Branch | [branch name]    |
+| Commit | [commit hash]    |
+| Clean  | [yes/no]         |
+
+## Session Stats
+
+| Metric   | Value         |
+| -------- | ------------- |
+| Estimate | [S/M/L]       |
+| Budget   | ~[N] calls    |
+| Actual   | [N] calls     |
+| Variance | [+/-N%]       |
+| Progress | [N]% complete |
 
 ## Session Context
 
-**Current Session:** [session ID from OpenCode]
-**Token Usage:** [if available]
+**Current Session:** [session ID]
 
 Next session can load context with:
 ```
@@ -66,10 +134,12 @@ read_session("last", project="current")
 
 ## Bead State
 
-- **ID:** <bead-id>
-- **Title:** [title]
-- **Status:** [status]
-- **Priority:** [priority]
+| Field    | Value      |
+| -------- | ---------- |
+| ID       | <bead-id>  |
+| Title    | [title]    |
+| Status   | [status]   |
+| Priority | [priority] |
 
 ## Progress
 
@@ -80,7 +150,7 @@ read_session("last", project="current")
 
 ### In Progress
 
-- [ ] [Current step] - [where stopped]
+- [ ] [Current step] - [where stopped, what's next]
 
 ### Remaining
 
@@ -91,8 +161,10 @@ read_session("last", project="current")
 
 ### Key Files
 
-- `src/foo.ts:42` - [why relevant]
-- `src/bar.ts` - [why relevant]
+| File              | Relevance        |
+| ----------------- | ---------------- |
+| `src/foo.ts:42`   | [why relevant]   |
+| `src/bar.ts`      | [why relevant]   |
 
 ### Decisions Made
 
@@ -101,7 +173,22 @@ read_session("last", project="current")
 
 ### Blockers/Issues
 
-- [Issue 1] - [status]
+- [Issue 1] - [status: resolved/pending/blocked]
+
+## Lessons Learned
+
+### What Went Well
+
+- [Thing that worked smoothly]
+
+### What Was Harder Than Expected
+
+- [Challenge encountered]
+- [Why it was harder]
+
+### Patterns Discovered
+
+- [Pattern worth remembering]
 
 ## Resume Instructions
 
@@ -109,36 +196,121 @@ read_session("last", project="current")
 
 1. [First thing to do]
 2. [Second thing to do]
+3. [Third thing to do]
 
-**Recommended:** Start next session with `/resume <bead-id>` to auto-load this handoff + previous session context.
+**Recommended:** Start next session with `/resume <bead-id>`
 
 ## Artifacts
 
-- spec.md: [exists/missing]
-- research.md: [exists/missing]
-- plan.md: [exists/missing]
+| Artifact     | Status  | Lines |
+| ------------ | ------- | ----- |
+| spec.md      | [✓/✗]   | [N]   |
+| research.md  | [✓/✗]   | [N]   |
+| plan.md      | [✓/✗]   | [N]   |
+| review.md    | [✓/✗]   | [N]   |
+```
+
+## Phase 8: Create Observation (if notable learnings)
+
+If session revealed patterns or gotchas:
+
+```typescript
+observation({
+  type: "learning",
+  title: "Session learning: [topic]",
+  content: `
+## What Happened
+[Brief description]
+
+## Lesson
+[What we learned]
+
+## Application
+[When to apply this learning]
+  `,
+  concepts: "[keywords]",
+  bead_id: "<bead-id>",
+});
+```
+
+## Phase 9: Update Memory (if gotchas found)
+
+If you discovered issues worth remembering:
+
+```typescript
+memory -
+  update({
+    file: "project/gotchas",
+    content: `
+## [Gotcha Title]
+
+**Symptom:** [What you see]
+**Cause:** [Root cause]
+**Fix:** [How to resolve]
+  `,
+    mode: "append",
+  });
+```
+
+## Phase 10: Notify Blockers (if any)
+
+If there are blockers for next session:
+
+```typescript
+bd_msg({
+  subj: "Handoff: <bead-id> - Blocked",
+  body: `
+Blockers:
+- [Blocker 1]
+- [Blocker 2]
+
+Needs: [what's required to unblock]
+  `,
+  to: "all",
+  importance: "high",
+  global: true,
+});
 ```
 
-## Phase 4: Update Bead
+## Phase 11: Update Bead & Sync
 
-Add a note about the handoff via `bd_msg` or update spec with handoff reference.
+```typescript
+bd_msg({
+  subj: "Handoff created",
+  body: "Progress: [N]%\nNext: [what needs to happen]",
+  to: "all",
+  importance: "normal",
+  global: false,
+});
+
+bd_sync({ reason: "Handoff created for $ARGUMENTS" });
+```
 
 ## Output
 
 ```
 Handoff Created: <bead-id>
-━━━━━━━━━━━━━━━━━━━━━━━━
+━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Commit: [hash]
 Branch: [branch]
+Progress: [N]% complete
+
+Session Stats:
+- Estimate: [S/M/L] (~[N] calls)
+- Actual: [N] calls
+- Variance: [+/-N%]
 
+Artifacts verified: [N]/[N]
 Saved: .beads/artifacts/<bead-id>/handoffs/<timestamp>.md
 
-━━━━━━━━━━━━━━━━━━━━━━━━
-🔄 Press Ctrl+K to compact session with handoff context
-━━━━━━━━━━━━━━━━━━━━━━━━
+━━━━━━━━━━━━━━━━━━━━━━━━━━
+To continue: /resume <bead-id>
+━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-The handoff plugin will automatically inject this context into the new session.
+The handoff is saved. Start a fresh session for best performance.
 
-Alternatively, resume manually: /resume <bead-id>
+Next session will auto-load:
+- This handoff document
+- Previous session context via read_session("last")
 ```