Vibekanban

Vibekanban

What it is

Vibekanban is the visual UX layer on top of the jobcard system — not a separate tool. It emerges from three components working together:

1. Quick Look — .jobcard bundles render as dark playing-card UI in Finder
2. Zellij — 7-pane pipeline layout + pane-per-card focus navigation
3. bop CLI — control plane (inspect, poker, status, logs)

Quick Look Extension

macos/bop/ — Swift/SwiftUI QL extension. Key file: PreviewViewController.swift.

QL Sandbox Lessons (hard-won)

• Extension MUST be sandboxed (com.apple.security.app-sandbox = true)
• MACH_O_TYPE = mh_execute (NOT mh_bundle)
• ENABLE_DEBUG_DYLIB = NO
• GENERATE_INFOPLIST_FILE = YES auto-qualifies class name
• Sandboxed QL CANNOT shell out — use changes.json for file listing
• NSFileCoordinator fallback for reading files in sandbox
• Register: lsregister -f ~/Applications/JobCardHost.app && pluginkit -a

Card Anatomy (top→bottom)

[glyph 44pt] [title bold] [P2 badge]
[label pills — colored by kind]
[progress bar]
[subtask dots ●○○○]
──────────────────────
[Spec]──[Plan]──[Code]──[QA]   ← stage pipeline
[acceptance criteria]
[clock 22h ago]   [⬛ Attach]  [● Stop]
                   ^running+session  ^running

Attach Button (green)

Appears when stages[current_stage].status == "running" AND zellij_session is set. Opens bop://card/<id>/session → host app routes to zellij attach <session>.

Stop Button (coral)

Appears when stages[current_stage].status == "running".

URL Scheme (bop://)

Host app (macos/JobCardHost/) registers bop:// URL scheme in Info.plist.

Routed in JobCardHostApp.swift via .onOpenURL.

Logs Tab

QL preview includes a Logs tab with live-tail link. Clicking opens terminal with colorized log output via bop logs <id>.

Glyph System

See unicode-glyphs skill for full reference.

suit  = team       ♠=CLI  ♥=Arch  ♦=Quality  ♣=Platform
rank  = priority   Ace=P1  Queen=P2  Jack=P3  5=P4
🃏    = wildcard / needs breakdown (joker — U+1F0CF)
🂿    = RED JOKER — DO NOT USE, renders as ◆ (silent misread)

Glyph is set at creation or via bop poker consensus. Never change mid-flight.

Card Back / Reveal Convention

• 🂠 (U+1F0A0) in filename or UI means unrevealed estimate/card-back state.
• Consensus reveal flips filename prefix to the chosen face card (example 🂻-feat-auth.jobcard).
• Keep meta.id stable (feat-auth) while filename glyph changes.

Contrast Rule (Playing Card Fonts)

• Playing-card glyphs visually assume a dark backdrop at larger sizes.
• Keep QL card canvas dark; for light host surfaces, wrap glyph in a dark chip/panel.
• There is no reliable "reverse font" Unicode variant for card backs/faces; do inversion at the view layer (background/foreground swap), not by changing codepoint.

Zellij Integration

7-Pane Layout (layouts/bop.kdl)

┌──────────┬──────────────────┬──────────────────┐
│  BOARD   │  SPEC            │  QA              │
│  watch   │  what to build   │  did it work?    │
│  status  ├──────────────────┼──────────────────┤
│          │  STDOUT          │  STDERR          │
│          │  agent output    │  agent errors    │
├──────────┴──────────────────┴──────────────────┤
│  INSPECTOR — bop inspect <id>                  │
├─────────────────────────────────────────────────┤
│  SHELL — bop commands (focus/retry/approve)    │
└─────────────────────────────────────────────────┘

Launch: zellij --layout layouts/bop.kdl

bop_focus.zsh — Card Navigator

Navigate all Zellij panes to focus on a specific card:

scripts/bop_focus.zsh <card-id>       # populate all panes for card
scripts/bop_focus.zsh --auto          # sweep all panes via zellij action write-chars

Uses zellij action write-chars to send commands into named panes.

bop_bop.zsh — Session Bootstrap

Goal→card→Zellij session in one command:

scripts/bop_bop.zsh "add auth to the API"
# Creates card: bop-add-auth-to-the-api
# Writes goal to spec.md
# Starts/attaches Zellij session: bop-bop-add-auth-to-the-api
# Runs dispatcher inside session

Budget-aware: reads stage_budgets from template meta.json.

Meta Fields for Zellij

{
  "zellij_session": "bop-feat-auth",  // session name
  "zellij_pane": "3"                  // pane ID within session
}

Set by dispatcher on spawn. Used by QL Attach button and bop_focus.

Display Tiers (by running card count)

• 0–5 cards: per-card pane with glyph in title
• 6–20: team-level pane
• 21+: status bar only

Log Colorization

bop logs <id> outputs tailspin-style colorized logs:

• Timestamps → dim
• ERROR/WARN → red/yellow
• File paths → cyan
• Numbers → magenta

Implemented in colorize_log_line() in main.rs. Detects TTY for auto-disable.

Label Pill Colors

Thumbnail Pipeline (macOS)

• Preview image: <card>.jobcard/QuickLook/Thumbnail.png
• Renderer: scripts/render_card_thumbnail.swift <meta.json> <out.png>
• Dispatcher/merge-gate refresh on state transitions
• Also refresh after poker-driven filename glyph rename (🂠 → face card)
• Batch: scripts/macos_cards_maintenance.zsh [--compress]

Finder Icon Coloring

Cards show their stage as icon color in Finder:

Driven by scripts/set_card_icon.swift. The bop icons FSEvents watcher auto-triggers icon updates on state transitions. Bundled into the bop factory lifecycle.

changes.json (merge-gate artifact)

Written at merge time. QL reads this instead of shelling out to git.

{
  "branch": "job/feat-auth",
  "files_changed": [
    {"path": "src/auth.rs", "status": "added"},
    {"path": "src/main.rs", "status": "modified"}
  ],
  "stats": {"files_changed": 2, "insertions": 145, "deletions": 12}
}

Stage Display Names

Never use .capitalized — "QA" → "Qa". Use lookup:

let stageOrder = [("spec","Spec"),("plan","Plan"),("implement","Code"),("qa","QA")]

Render Test (no QL daemon)

swift scripts/render_card_thumbnail.swift <meta.json> <out.png>