Read
DESIGN.mdfirst. This document operationalizes it: what to build, in what order, by whom, with what dependencies.Stack (locked): TypeScript +
@opentui/core+@opentui/solid+ Solid.js + Bun.Plan model: streams that run in parallel, converging at named integration points where everything must land for a demoable milestone. Each stream is sized for one Claude Code agent in one focused session (~600–1500 LoC).
- Each wave is a parallel batch — agents in the same wave run concurrently, no dependency between them.
- Integration points (▶) are gates. Nothing in the next wave starts until the gate is green.
- Each stream has: Scope, Inputs (deps), Outputs (artifacts), Done when (acceptance), Suggested agent prompt seed.
- Total wall-clock estimate assumes 1 human reviewer + N parallel agents. Sequential lower bound is roughly the longest path.
Phase 0
└─ 0.1 Repo bootstrap ──┬─ 0.2 Lift opencode shell ─┐
├─ 0.3 Core types ──────────┤
└─ 0.4 Behavior harness ────┤
▼
[▶ Gate G0: shell renders +
test:behavior runs]
Phase 1 — Wave 1 (parallel)
┌─ A. ClaudeCodeLocal engine
├─ B. Worktree manager
├─ C. Task index
└─ D. Theme + keybindings ringbuffer
▼
[▶ Gate G1: orchestrator can run a task]
Phase 1 — Wave 2 (parallel)
┌─ E. Orchestrator core (glue A+B+C)
└─ F. Sidebar pane (consumes C)
▼
[▶ Gate G2: single-task chat demo]
┐
Phase 1 — Wave 3 (parallel, after G2) │
┌─ G. Chat pane │
├─ H. File tree pane │
├─ I. Diff/preview pane │
└─ J. Terminal pane │
▼ │
[▶ Gate G3: full 5-pane demo] │
│
Phase 1 — Wave 4 (sequential polish)
├─ K. Status flow + checks pane
├─ L. PR button + cmd-k task switcher
└─ M. Multi-task end-to-end QA
▼
[▶ Gate G4: Phase 1 ship]
Three streams. 0.2 and 0.3 can run parallel after 0.1 commits.
Scope: Make the repo runnable. Set up package layout, tooling, scripts.
Inputs: HANDOFF.md, DESIGN.md, opencode's package.json and tsconfig.json as templates.
Outputs:
package.json(Bun workspace),tsconfig.json,biome.json(oreslint/prettiermatching opencode)vitest.config.tsfor unit tests- Directory structure:
src/ cli/ # entry point (Commander or Bun's argv) tui/ # opentui + Solid components (lifted from opencode) engine/ # AI engine port + impls orchestrator/ # task lifecycle, worktree, index types/ # shared types test/ docs/ bun run devstarts the TUI (even if it's just an empty box — proves the build pipeline).gitignoreupdated;refs/already covered
Done when: bun install && bun run dev opens a blank opentui window without errors.
Agent prompt seed:
Bootstrap the kobe repo at
/Users/jacksonc/i/kobe. Use opencode (refs/opencode/packages/opencode/package.jsonandtsconfig.json) as a template. Create the directory structure listed in PLAN.md §0.1. Add minimal Bun-runnable entry that opens an empty opentui screen with title "kobe". Set up vitest. Don't add features; just prove the pipeline works.
Scope: Copy the relevant parts of refs/opencode/packages/opencode/src/cli/cmd/tui/ into our src/tui/, strip everything we don't need.
Inputs: Stream 0.1 done; explore agent's report on opencode in HANDOFF context (what's reusable).
Outputs:
src/tui/ui/dialog.tsx(dialog stack)src/tui/ui/dialog-confirm.tsx,dialog-alert.tsxsrc/tui/component/border.tsx,dialog-diff.tsx(rename later if ergonomic)src/tui/context/theme.tsx+theme/*.json(all themes copied)src/tui/context/sync.tsx,kv.tsx,command-palette.tsx- Stripped: vendor/auth/route code, opencode-specific commands (
appCommandscleared to[]), API client calls (everysdk.client.*removed or stubbed)
Done when: bun run dev shows an opentui window with theme applied; cmd-k opens an empty command palette dialog (proves dialog system works).
Suggested agent prompt seed:
Lift opencode's TUI shell into kobe. Source:
refs/opencode/packages/opencode/src/cli/cmd/tui/. Target:src/tui/. Copy the modules listed in DESIGN.md §7.1 (dialog system, theme, sync store, command palette, scrollbox primitives). Strip vendor/auth/route/SDK code — anything callingsdk.client.*should be removed or stubbed with TODO. Goal: opencode shell renders in our repo with no opencode-specific business logic. Don't add new features.
Scope: Define the interfaces that downstream streams will satisfy. This is the contract.
Inputs: DESIGN.md §5.2 (AIEngine), §10 (Task data model). Run in parallel with 0.2.
Outputs: src/types/:
engine.ts—AIEngineinterface,SessionHandle,EngineEvent,SpawnOpts,Messagetask.ts—Task,TaskStatus,TaskIndexworktree.ts—WorktreeInfo,WorktreeManagerinterface- Exhaustive type unions (use discriminated unions for events).
- One unit test per type asserting basic shape via tsc.
Done when: bun run typecheck is green; downstream streams can import { AIEngine } from "src/types" and start coding against it.
Suggested agent prompt seed:
Define kobe's core type contracts in
src/types/. Sources: DESIGN.md §5.2 (AIEngine port), §10 (Task data model). Also readrefs/vibe-kanban/crates/executors/for interface shape lessons. Output:engine.ts,task.ts,worktree.ts. Use discriminated unions for events. No implementations — types only. Add type-only test files asserting shape viaexpectTypeOf.
Scope: Build the infrastructure that lets every subsequent stream self-test by running the product. This is the load-bearing piece for the agent-self-validates property of HARNESS.md.
Inputs: Stream 0.1 (entry point exists). Runs in parallel with 0.2 and 0.3.
Outputs: test/behavior/:
driver.ts— exportsspawnKobe(opts)returning aKobeHandle. Built onnode-pty(or Bun's PTY equivalent if mature). Key methods:sendKeys(seq),typeText(s),capture()(returns visible screen as string),waitFor(predicate, timeoutMs),exit(). Tmux backend optional fallback if PTY proves flaky on macOS.screen.ts— ANSI-aware screen buffer parser. Strip cursor codes, normalize whitespace, return plain text. Make assertions readable (no ANSI noise intoContainfailures).fake-engine.ts—FakeAIEngine implements AIEngine. Scripted event sequences viaFakeAIEngine.script(sessionId, events[]). Deterministic. Note: needs Stream 0.3's types — coordinate with 0.3 agent (read its commit before finishing).fixtures/—repo-init.shbuilds a tiny test git repo; sampletasks.json; preset behavior scripts.example.test.ts— one passing behavior test: spawn kobe, capture, assert "kobe — booting" visible. Proves the harness works.README.md— author guide for behavior tests (50–100 lines).- Add
bun run test:behaviorscript topackage.json.
Done when:
bun run test:behaviorpasses the example test on a clean checkout.bun run test:behavior --watchworks for iteration.- Driver supports at least:
sendKeys,typeText,capture,exit, with timeouts. - README has copy-paste recipe for "write a behavior test in 5 minutes."
Agent prompt seed:
You are Stream 0.4 of the kobe Foundation Team. Read
/Users/jacksonc/i/kobe/CLAUDE.md,docs/DESIGN.md,docs/PLAN.md(your stream + dep graph), anddocs/HARNESS.md(especially the "Behavioral self-test" section — that's the contract you're building infrastructure for).Your sibling agents on this team:
- Stream 0.2 is lifting the opencode TUI shell into
src/tui/.- Stream 0.3 is defining
src/types/engine.ts,task.ts,worktree.ts. YourFakeAIEnginedepends on itsAIEngineinterface — readsrc/types/engine.tsafter 0.3 commits, before you finalizefake-engine.ts. If 0.3 isn't done when you need it, surface and pause; don't redefine the interface yourself.Build the deliverables in PLAN.md §0.4. Use
node-pty(or Bun PTY if available) as primary backend. The driver must be thin — your job is to make behavior tests easy to write, not to ship a TUI testing framework. ~400–600 LoC total.Self-validate per HARNESS.md: typecheck, lint, unit-test the driver itself (mock pty), and your example.test.ts must pass. Commit on green.
Self-check (the orchestrator runs these, no human needed):
-
bun installclean -
bun run devopens kobe with theme (Stream 0.2) -
bun run typecheckgreen -
bun run testgreen (Stream 0.3 type tests at minimum) -
bun run test:behaviorgreen (Stream 0.4 example test) - All four Phase 0 streams committed and merged to main
After G0. All four can ship without seeing each other.
Scope: Implement the AIEngine interface for local claude CLI.
Inputs: Stream 0.3 (AIEngine interface). Reference: refs/opcode/src-tauri/src/commands/claude.rs lines 147–230, 919–1014, 1173–1327; refs/opcode/src-tauri/src/claude_binary.rs.
Outputs: src/engine/claude-code-local/:
binary.ts— findclaudeon PATH/NVM/Homebrew/~/.claude/localspawn.ts— child_process spawn with stream-json flagsstream.ts— line-by-line JSONL parser → typedEngineEventAsyncIterablehistory.ts— read~/.claude/projects/<encoded-cwd>/<uuid>.jsonl, returnMessage[]index.ts— classClaudeCodeLocal implements AIEngine- Tests: spawn a
claudeprocess with--helpand assert exit; mock JSONL lines and assert event normalization.
Done when:
new ClaudeCodeLocal().spawn(cwd, "say hi", {})returns a handle that streams events ending in{ type: "done" }.readHistory(uuid)returns parsed messages.- Unit tests pass.
Agent prompt seed:
Implement
ClaudeCodeLocalsatisfying theAIEngineinterface insrc/types/engine.ts. Port the algorithm fromrefs/opcode/src-tauri/src/commands/claude.rs— Rust → TS. File layout per PLAN.md §A. Use Nodechild_process.spawnandreadline.createInterfaceover stdout. Normalize stream-json events to ourEngineEventdiscriminated union (do not leak Claude Code's raw shape upward). Tests: mock stream-json input, assert event sequence; integration test that spawns realclaude --help. ~400 LoC target.
Scope: Wrap git worktree add/remove/list and dirty-state detection.
Inputs: Stream 0.3 (WorktreeManager interface). Reference: refs/vibe-kanban/crates/worktree-manager/ (read for invariants, port nothing).
Outputs: src/orchestrator/worktree/:
manager.ts—class GitWorktreeManager implements WorktreeManager- Methods:
create(repo, branch, path),remove(path, { force }),list(repo),isDirty(path),currentBranch(path) - Use
bun.spawnor NodeexecFilefor git calls; never shell-string-concatenate. - Per task convention from DESIGN.md §11.3 (current:
~/.kobe/worktrees/<repo-key>/<slug>/for new tasks; repo-local.kobe/worktreesand legacy.claude/worktreesrecognized) - Tests: in
test/fixtures/, init a tiny repo, create + remove worktrees, assert state.
Done when: All methods green in unit tests; round-trip create→remove leaves no orphan files or branches.
Agent prompt seed:
Implement
GitWorktreeManagerpersrc/types/worktree.ts. Usegit worktreesubcommands viabun.spawn(no shell concat — pass args as array). Per DESIGN.md §11.3, default worktree root is~/.kobe/worktrees/<repo-key>/<slug>/for new tasks, with repo-local<repo>/.kobe/worktrees/<slug>/and legacy<repo>/.claude/worktrees/<slug>/recognized. Readrefs/vibe-kanban/crates/worktree-manager/for invariants on cleanup and dirty-state detection. Tests must use a real fixture repo (test/fixtures/repo-init.sh); no mocking git. ~300 LoC.
Scope: Persist the task list at ~/.kobe/tasks.json.
Inputs: Stream 0.3 (Task, TaskIndex).
Outputs: src/orchestrator/index/:
store.ts—class TaskIndexStore, methods:load(),save(),get(id),list(),create(partial),update(id, patch),archive(id)- Atomic writes (write to
tasks.json.tmp, rename) - File lock (
proper-lockfileor simple PID file) to prevent multi-process corruption - Migration field (
version: 1) for future shape changes - Tests: CRUD round-trips; concurrent-write rejection; corrupted file recovery (load with bad JSON returns empty index, doesn't crash)
Done when: All CRUD ops covered by unit tests; concurrent-write test shows lock works.
Agent prompt seed:
Implement
TaskIndexStorefor~/.kobe/tasks.jsonpersrc/types/task.tsand DESIGN.md §10. Atomic writes via tmp+rename. Use a lockfile to prevent corruption from a future second kobe instance. Includeversion: 1field. On corrupted JSON, log and start fresh (don't crash). Tests:~200 LoCof CRUD + concurrency tests. ~250 LoC impl.
Scope: Make the lifted opencode shell ours — pick default theme, register kobe keybindings.
Inputs: Stream 0.2 (shell lifted).
Outputs:
src/tui/context/theme.tsx— default theme set to one we like (proposal:nordoraurafrom opencode's set; user picks)src/tui/context/keybindings.ts— central keymap table (vi-style, configurable later). Bindings for: focus next/prev pane, open task list, command palette, quit, esc-cancel.src/tui/component/help-dialog.tsx—F1key shows current bindings- Tests: snapshot test on theme JSON shape; smoke test that
F1opens help.
Done when: kobe boots into themed UI with help dialog accessible.
Agent prompt seed:
Wire kobe's theme + keybindings on top of the lifted opencode shell. Pick
nordas default (changeable via~/.kobe/config.jsonlater — for now hardcode). Define keymap insrc/tui/context/keybindings.tsper PLAN.md §D. ImplementF1help dialog showing current bindings. ~150 LoC.
Manual check:
-
ClaudeCodeLocal.spawn()works against realclaudeCLI -
GitWorktreeManager.create()creates a worktree -
TaskIndexStore.create()persists a task - kobe boots themed with
F1help
These four are the building blocks. Wave 2 glues them.
Scope: The glue. Owns task lifecycle, dispatches to Wave-1 modules.
Inputs: Streams A, B, C.
Outputs: src/orchestrator/core.ts:
class Orchestratorwith methods:createTask({ repo, title, prompt }),runTask(id),pauseTask(id),archiveTask(id),getTask(id),subscribeEvents(id, cb)- Internally: ulid → Task; on
runTask, callWorktreeManager.create(), thenEngine.spawn(worktreePath, prompt), plumb events into a per-task event bus, updateTaskIndex.status. - Event bus: simple per-task EventEmitter; UI subscribes.
- Tests: integration test creating + running + archiving a task end-to-end with a mock engine.
Done when: Orchestrator.runTask(id) end-to-end works with ClaudeCodeLocal and a real worktree; events stream to a subscriber.
Agent prompt seed:
Implement the
Orchestratorclass insrc/orchestrator/core.ts. It composesClaudeCodeLocal(Stream A),GitWorktreeManager(Stream B),TaskIndexStore(Stream C). API per PLAN.md §E. Per-task event bus via Node EventEmitter. Status transitions:backlog → in_progresson runTask,→ doneon enginedoneevent,→ erroron engineerror. Integration test with a mock engine showing the full lifecycle. ~400 LoC.
Scope: The history pane. Render task list grouped by status, navigable.
Inputs: Stream C (TaskIndexStore — read-only here), Stream 0.2 (sidebar component reference from refs/opencode/.../routes/session/sidebar.tsx).
Outputs: src/tui/panes/sidebar/:
Sidebar.tsx— Solid component, fixed-width task rail- Status groups: Done / In review / In progress / Backlog / Canceled (collapsible)
- Cursor nav (j/k); enter selects task and emits
selectTask(id)event - Subscribe to
TaskIndexStoreupdates (poll or push) - Test: render with mock task list, assert grouping and cursor nav
Done when: Sidebar renders standalone in a test harness with sample data; cursor navigation works.
Agent prompt seed:
Build the kobe sidebar pane. Adapt
refs/opencode/packages/opencode/src/cli/cmd/tui/routes/session/sidebar.tsx. Fixed-width task rail. Group tasks by status (5 groups, collapsible). Cursor j/k nav. Read tasks fromTaskIndexStore(Stream C), poll every 1s for changes (we'll move to push later). EmitselectTask(id)via Solid signal. Standalone test harness with 9 mock tasks. ~250 LoC.
This is the first demoable milestone. Build a temporary App.tsx that wires Sidebar (F) + a placeholder chat area + Orchestrator (E). User can:
- Press
ctrl+nto create a task (prompts for title + repo) - See it in the sidebar
- Press enter to select it; chat area renders streamed events from
ClaudeCodeLocal
This is not the final UI. It's an end-to-end wiring proof.
Manual check:
- Create a task via
ctrl+n - Worktree appears on disk
- Claude Code spawns, output streams into the placeholder chat
- Task transitions backlog → in_progress → done
- Sidebar reflects status changes
After G2. The four panes that flank the chat.
Scope: Replace G2's placeholder with a proper chat composer + message renderer.
Inputs: Stream E (orchestrator events), Stream A (AIEngine.readHistory).
Outputs: src/tui/panes/chat/:
Chat.tsx— message list (assistant deltas, tool calls, tool results), composer at bottom- Streaming: assistant text appears token-by-token via engine event subscription
- History: on task switch, call
engine.readHistory(sessionId)and render past messages - Tool call rendering: collapsed by default, expand on enter
- Composer: multi-line input,
entersubmits,shift-enternewline
Done when: Switching between tasks in the sidebar swaps history; new prompts stream live.
Agent prompt seed:
Build kobe's chat pane. Reuse opencode's message rendering pattern (
refs/opencode/packages/opencode/src/cli/cmd/tui/routes/session/index.tsxlines 1064+). Subscribe toOrchestrator.subscribeEvents(taskId). On task change, fetchengine.readHistory(sessionId)and prepend. Tool calls render collapsed;enterexpands. Composer at bottom, multi-line,enterto submit. ~500 LoC.
Scope: Right-rail pane: list files in active task's worktree, mark changed files.
Inputs: Stream B (worktree path), Solid sync to active task signal.
Outputs: src/tui/panes/filetree/:
FileTree.tsx— recursive tree of worktree root,.gitignorerespected- Tabs at top:
All|Changes|Checks(Checks empty for now, fills in Wave 4) Changestab: only files withgit statusmodifications- Cursor nav,
enteremitsopenFile(path)(consumed by Diff pane)
Done when: Tree renders for active task; All/Changes toggle works; selecting a file emits the event.
Agent prompt seed:
Build kobe's file tree pane. List worktree files (respect .gitignore via
git ls-files --cached --others --exclude-standard). Three top tabs: All, Changes, Checks.All= full tree;Changes=git status --porcelainfiles;Checks= empty placeholder. Cursor nav,enteremitsopenFile(path). ~300 LoC.
Scope: Center pane content — show file content or diff when a file is selected.
Inputs: Stream B (worktree), Stream H (openFile event), refs/opencode/.../component/dialog-diff.tsx as the rendering reference (the user wrote this).
Outputs: src/tui/panes/preview/:
Preview.tsx— receives selected file path- Two modes: file view (full content, syntax-aware later — for v1 plain text) and diff view (
git diff <branch-base> -- <path>) - Mode switched via tabs (
File/Diff) - Reuses
DiffLinecomponent fromdialog-diff.tsx - Multi-tab support (each opened file = a tab)
Done when: Selecting files in the file tree opens them in the preview; diff toggle works.
Agent prompt seed:
Build kobe's preview pane. Lift the
DiffLinerendering pattern fromrefs/opencode/.../component/dialog-diff.tsx. Two modes: File (cat) and Diff (git diff vs branch base). Multi-tab — each opened file is a tab; close withx. Subscribes toopenFilefrom Stream H. ~350 LoC.
Scope: Embedded terminal scoped to active task's worktree.
Inputs: Stream B (worktree path), Stream E (active task signal).
Outputs: src/tui/panes/terminal/:
Terminal.tsx— pty wrapper (node-ptyor Bun equivalent)- Spawns
$SHELLwithcwd = worktreePath - Renders into an opentui scrollback area; key passthrough
- On task switch, kill old pty and spawn new
- Decision needed: do we keep one pty per task (multiplexed) or one pty global that follows active task? Default proposal: one pty per task, kept alive while task is in
in_progress.
Done when: Terminal in the bottom-right pane runs commands in the active task's worktree.
Agent prompt seed:
Build kobe's terminal pane using
node-pty(or Bun's spawn-with-pty if simpler). One pty per task; kept alive while task status isin_progress. Render output into an opentui scrollable box; pass keystrokes through. On task switch, swap to the new task's pty (or spawn one if none). ~400 LoC.
Wire all five panes into the final layout matching DESIGN.md §1's Conductor screenshot:
- Left: Sidebar (F)
- Center top: Preview (I) with file tabs
- Center bottom: Chat (G) composer
- Right top: File tree (H)
- Right bottom: Terminal (J) (and Setup Spotlight placeholder)
Manual check:
- Layout matches the Conductor screenshot grammar
- All five panes visible and interactive
- Focus cycles between panes (
tab/shift-tab) - Active task drives all panes consistently
Polish + the bits that need cross-pane coordination.
- Buttons / commands to transition
in_progress → in_review(e.g.rkey) doneandcanceledtransitions- Checks pane (the third tab in file tree): show test/build/lint status. v1: shells out to
bun testandbun run typecheck, parses exit codes, renders pass/fail. Per-project config later.
- Top-bar button / command to open a GitHub PR via
gh pr create. AI-generated description from session messages. cmd-ktask switcher (already lifted from opencode's command palette — wire it up to task list)
- Run 5+ concurrent tasks in different repos
- Profile memory + CPU
- Fix what's broken
- Document known issues in
docs/PHASE1-NOTES.md
- All Wave 1–4 streams committed
- DESIGN.md §11 open questions resolved or explicitly deferred
- CLAUDE.md updated with Phase 2 entry plan
- HANDOFF.md replaced or updated for next session
Shipped as @sma1lboy/kobe@0.1.0 on npm (see CHANGELOG.md
for the full feature manifest). Wave 4 polish landed via the
worktree-agent merges between 2026-05-09 morning and afternoon
plus the inline approval flows (ExitPlanMode + AskUserQuestion).
Two known regressions caught post-ship by the new approval-flow
behavior tests (composer lock not visible, AskUserQuestion crash);
tracked in test/behavior/approval-flow.test.ts test.skip notes
for follow-up.
| Wave | Parallel streams | Critical path stream | Wall-clock units (rough) |
|---|---|---|---|
| Phase 0 | 1 → 2 | 0.1 → 0.2 | 1.5 |
| Wave 1 | 4 | A (engine port) | 2.0 |
| Wave 2 | 2 | E (orchestrator) | 1.5 |
| Wave 3 | 4 | G (chat) or J (terminal) | 2.0 |
| Wave 4 | 1 | K (sequential) | 1.5 |
Total wall-clock: ~8.5 units with 4-way parallelism vs. ~14 sequential. The win compounds in Wave 1 and Wave 3 where parallelism is highest.
A "unit" is roughly one focused agent session (~half a day of human-attended work). Calibrate as we go.
Use the Agent tool with subagent_type: "general-purpose" (or Explore for read-only research streams). Pass the stream's "Agent prompt seed" as the prompt, plus:
- The full DESIGN.md (or a pointer to it).
- The stream's row from PLAN.md (this file).
- Any upstream stream's commit/files it depends on.
- The acceptance ("Done when") clause as the success contract.
Constraint: each stream agent gets one focus area. No cross-stream commits. If a stream agent finds it needs to modify a file outside its scope, it must surface and ask — not just go in.
| # | Decision | Stream | Resolution |
|---|---|---|---|
| 1 | Default theme | D | tokyonight (matches agent-deck's Tokyo Night palette; already lifted from opencode) |
| 2 | Worktree root | B | Updated 2026-06-06: ~/.kobe/worktrees/<repo-key>/<slug>/ for new kobe-created tasks; repo-local .kobe/worktrees and legacy .claude/worktrees remain recognized. Repo-local roots were retired so users do not need .gitignore entries for kobe runtime worktrees. |
| 3 | Branch naming | E | Auto kobe/<slug>-<ulid-suffix>; user can override per-task |
| 4 | Concurrency cap | E | 4 simultaneous running tasks; configurable via ~/.kobe/config.json later |
| 5 | Terminal pane | J | One pty per task, kept alive while task is in_progress, killed on archive |