diff --git a/docs/video/introduction-to-taskplane-storyboard.md b/docs/video/introduction-to-taskplane-storyboard.md new file mode 100644 index 00000000..098d8129 --- /dev/null +++ b/docs/video/introduction-to-taskplane-storyboard.md @@ -0,0 +1,367 @@ +# Introduction to Taskplane — YouTube Storyboard + +**Target runtime:** 20–25 minutes +**Audience:** AI-coding practitioners (Claude Code / Cursor / Aider users — already comfortable with worktrees, agent loops, context windows) +**Tone:** Personal-builder narrative, first-person, opinions front and center +**Visual style:** Dark IDE-aesthetic HTML/CSS panels, monospace, green/amber accents — live in `docs/video/visuals/` + +--- + +## How to read this document + +Each scene is a numbered section with five fields: + +- **Runtime:** wall-clock target and cumulative time +- **On camera:** what the viewer sees of you (talking head, screen, both) +- **B-roll / capture:** what to record or screen-cap during this beat +- **Visual cue:** which HTML/CSS visual to cut to (see `docs/video/visuals/`) +- **Talking points:** the beats — *not* a full script. You'll improvise around them. + +Pickup lines in *italics* are suggested verbatim openings/closings for that scene. Use them or replace them; they're there to mark transitions cleanly. + +--- + +# ACT 1 — The "Why" (≈ 5:30) + +## Scene 1 · Cold open · 0:00 – 0:30 (~0:30) + +- **On camera:** You. Tight shot. No B-roll. +- **B-roll / capture:** — +- **Visual cue:** none — pure talking head, optional title card at 0:25 +- **Talking points:** + - Hook on the punchline first. Something like: *"I wrote a million lines of code with AI before I built this. Most of that million was wasted. This is what I built once I figured out why."* + - Name the artifact: Taskplane. One sentence: a deterministic orchestration system for multi-agent AI coding. + - Promise the payoff: by the end you'll know what it does, why it's different, and the specific design choices I'd defend. + +## Scene 2 · Origin story · 0:30 – 3:30 (~3:00) + +- **On camera:** You, opening; cut between talking head and B-roll throughout. +- **B-roll / capture:** Three vignettes: + 1. A messy vibe-coding session — paste a wall of code, agent rewriting it, files scattered. ~30s. + 2. A Ralph Wiggum loop in a single terminal — same prompt over and over, agent grinding. ~30s. + 3. A parallel Ralph orchestrator — multiple panes, agents stepping on each other (conflicts, dirty git status, the loud failure modes). ~30s. +- **Visual cue:** **V1 — Origin timeline** (`visuals/01-origin-timeline.html`) — cut to it at the 1:00 mark and let it stay on screen while you narrate the three stages. +- **Talking points:** + - *"I didn't set out to build an orchestration system. I set out to write code faster. Taskplane is the residue of about a million lines of getting that wrong."* + - **Stage 1 — Vibe coding.** Fast feedback, low ceiling. You can ship a prototype in an afternoon and a brownfield codebase in a coma in a week. + - **Stage 2 — The Ralph Wiggum loop.** One prompt, run it forever, let the agent grind. Massive unlock for green-field. Falls over the moment the work needs continuity across context windows or your codebase is bigger than the model's working memory. + - **Stage 3 — Parallel Ralph.** Just run more loops. Sounds obvious. The collisions, dirty worktrees, and silent overwrites taught me the lessons that became Taskplane's invariants. + - **The thread:** every stage failed in a way that produced a design rule. Worktrees came from collisions. STATUS.md came from context loss. Cross-model reviews came from worker-confidence problems. The merge agent came from "git can't merge intent." + - Land the transition: *"I'll show you each of those design rules. But first — what is Taskplane actually trying to solve?"* + +## Scene 3 · The problem statement · 3:30 – 4:45 (~1:15) + +- **On camera:** Talking head, slow cut to visual. +- **B-roll / capture:** — +- **Visual cue:** **V2 — Light factory vs dark factory** (`visuals/02-light-factory-vs-dark.html`). Show it ≈4:00 and hold. +- **Talking points:** + - The honest problem: agents at scale don't fail because the model is dumb. They fail because the **harness** around them is non-deterministic. + - Three failure modes I kept hitting: + 1. **Context loss** mid-task — work disappears, agent restarts, half-done state on disk. + 2. **Silent collisions** — two agents both "completed" their work, one overwrote the other. + 3. **No operator visibility** — by the time you noticed, $8 was on fire and nobody could tell you what went wrong. + - Taskplane's claim: you can keep the autonomy *and* get back the determinism. You don't have to choose. + - Light factory vs dark factory framing: dark factory hides the work; light factory shows you everything happening on the floor. This is the philosophical anchor for the rest of the video. + +## Scene 4 · What makes Taskplane different · 4:45 – 5:30 (~0:45) + +- **On camera:** Talking head with V2 still on screen, then a brief cut to V3 preview. +- **B-roll / capture:** — +- **Visual cue:** linger on **V2**, then teaser-cut to **V3 — Agent quartet** (`visuals/03-agent-quartet.html`) at 5:15. +- **Talking points:** + - Three differentiators in one breath: + 1. **Deterministic orchestration** with file-backed state (resumable, inspectable, recoverable). + 2. **Verbose-by-design task packets** (PROMPT.md / STATUS.md) — I'd rather you read what the agent is going to do than trust a black box. + 3. **Cross-model reviews baked in** — different model writes the code than reviews it. + - Tease the agenda: *"We're going to walk through how Taskplane thinks, how it runs, and how you watch it run. Let's start with the four agents."* + +--- + +# ACT 2 — How Taskplane thinks (≈ 7:30) + +## Scene 5 · The minimalist agent quartet · 5:30 – 7:00 (~1:30) + +- **On camera:** Full visual on screen, you narrating over it. +- **B-roll / capture:** Briefly show `.pi/agents/*.md` in an editor to make it concrete — supervisor.md, task-worker.md, task-reviewer.md, task-merger.md. +- **Visual cue:** **V3 — Agent quartet** (`visuals/03-agent-quartet.html`). Hold for the full scene. +- **Talking points:** + - Taskplane has **exactly four agent roles**. Not seven, not twelve. Adding agents adds coordination overhead; if I can't justify why an agent exists, it doesn't exist. + - **Supervisor** — the conversational operator-in-the-loop. Monitors batch progress, reads agent replies, can steer or override. Doesn't write code. + - **Worker** — implements the steps in PROMPT.md. One worker per lane. Owns checkpoint discipline. + - **Reviewer** — independent quality gate. Reads plans and code, emits `APPROVE` / `REVISE` / `RETHINK`. Persistent across a task so it remembers earlier reviews. + - **Merger** — the LLM that combines lane branches into the orch branch. Reads conflict markers, resolves semantically, runs verification. + - The discipline: **clear separation of concerns**. Workers optimize for progress, reviewers for correctness, mergers for integration, supervisor for control. They don't bleed. + - Closing line: *"Four roles, four prompts, four jobs. That's it."* + +## Scene 6 · The create-taskplane-task skill (verbose by design) · 7:00 – 9:30 (~2:30) + +- **On camera:** Talking head opening, then mostly screen capture. +- **B-roll / capture:** + - Live demo or pre-recorded: ask the skill to create a real task. Walk through the generated PROMPT.md showing Mission / Dependencies / File Scope / Steps / Do NOT / Amendments. + - Show the matching STATUS.md with checkboxes. + - Show the file tree: PROMPT.md, STATUS.md, .reviews/, .DONE absent (yet). +- **Visual cue:** **V4 — Anatomy of a task packet** (`visuals/04-task-packet-anatomy.html`). Use as a structural overlay while screen-capping the real file. +- **Talking points:** + - This is the **most opinionated piece** of Taskplane and I want to defend it explicitly. + - Every task is a packet of two files: **PROMPT.md** (the contract) and **STATUS.md** (the memory). + - The skill enforces a complexity rubric — blast radius, novelty, security, reversibility — which scores into a review level (0–3) and a size (S/M/L/XL). XL must split. + - **The verbosity is the point.** I want you to read what the agent is about to do. I want: + - explicit `## File Scope` so the orchestrator can compute lane affinity safely + - explicit `## Dependencies` so the wave planner can build a real DAG + - explicit `## Do NOT` guardrails so the worker has friction against shortcuts + - explicit step granularity so a worker can resume mid-task without re-deriving intent + - **The contrast — the "dark factory" alternative:** a single sentence prompt and a model that "just figures it out." Faster to write, impossible to debug, impossible to audit, impossible to resume. + - The trade-off is real: it takes longer to author a packet. The payoff is that every other part of the system — wave planning, lane affinity, reviews, merges, resume — becomes deterministic. You're paying for clarity once so that ten downstream decisions become mechanical. + - The honest cost: this style requires you to *think* about a task before you launch it. That's a feature, not a bug. + +## Scene 7 · Determinism in orchestration · 9:30 – 10:30 (~1:00) + +- **On camera:** Mostly visual, talking head bookends. +- **B-roll / capture:** Show `.pi/batch-state.json` in an editor. Highlight `schemaVersion`, wave plan, per-lane records. Show `.pi/supervisor/events.jsonl` scrolling. +- **Visual cue:** **V5 — Determinism vs autonomy** (`visuals/05-determinism-spectrum.html`). Cut to it at ≈ 9:45. +- **Talking points:** + - Where Taskplane sits on the determinism / autonomy spectrum is deliberate. + - **The non-deterministic bits** — the LLM calls themselves, the reviewer verdicts, the merge resolutions. You can't make these deterministic without giving up the model's value. + - **Everything around them is.** Dependency resolution is a real DAG. Wave assignment is topological sort. Lane assignment is affinity-first by file scope. Branch names are templated. State is checkpointed atomically. Events are append-only JSONL. + - The principle: *push every decision you can to a deterministic file or rule, so the only randomness left is the model's actual thinking.* + - Concrete payoffs: resume works. Two runs of the same batch produce the same waves. Debugging is reading files, not interrogating a process. + +## Scene 8 · Cross-model reviews · 10:30 – 12:00 (~1:30) + +- **On camera:** Visual primary; brief screen capture of agent config. +- **B-roll / capture:** Open `.pi/agents/task-worker.md` and `.pi/agents/task-reviewer.md`. Highlight the `model:` lines — worker on one model, reviewer on a different model. Then a dashboard shot of a review row firing under an active task. +- **Visual cue:** **V6 — Cross-model review flow** (`visuals/06-cross-model-review.html`). +- **Talking points:** + - *"If Opus is the worker, GPT is the reviewer. Different brain reading the work. Different blind spots."* + - Why this matters: same-model review is closer to confirmation bias than review. Models that write a certain way tend to *evaluate* that way too. Putting a different family on the other side is the cheapest possible defense. + - **Reviews are not optional** — they're a level you set per-task (0 = none for trivial; 1 = plan; 2 = plan + code; 3 = full). The skill scores you into the right level so you don't default to "0 because it's faster." + - **Two flavors of review:** + 1. **Plan review** — fires before the worker writes any code. Catches design problems early when the cost to redirect is one prompt, not a refactor. + 2. **Code review** — fires after a step's commits. Reviewer sees only that step's diff (baseline SHA), not the cumulative noise. + - **Persistent reviewer context** — same reviewer across all reviews for a task, so it remembers what it flagged in Step 2 when it looks at Step 4. Costly to spawn, cheap to keep alive. + - Verdicts are file artifacts in `.reviews/`. APPROVE / REVISE / RETHINK. REVISE is addressed inline — the worker still has its full context and just goes back and fixes it. + +## Scene 9 · File-based mail · 12:00 – 13:00 (~1:00) + +- **On camera:** Heavy visual; tail with talking head. +- **B-roll / capture:** Show `.pi/mailbox/{batchId}/{session}/inbox`, `outbox`, `ack`, and `_broadcast`. Drop a `send_agent_message` call and show the file appear, then move to `ack`. +- **Visual cue:** **V7 — Mailbox protocol** (`visuals/07-mailbox-protocol.html`). +- **Talking points:** + - Real problem this solves: the supervisor needs to talk to a *running* agent without killing it. Stdin injection is platform-specific and one-way. Tmux send-keys is brittle. Sockets aren't portable. + - **The answer is a directory.** Inbox, outbox, ack, batch-scoped, session-scoped. The supervisor writes a JSON message file; the agent's RPC wrapper sees it, injects it as a user turn; the agent replies into the outbox. + - Why files: zero dependencies, cross-platform, survives crashes, **human-debuggable**. You can `cat` a mailbox to know exactly what the supervisor told an agent. + - Same pattern already runs the rest of the system: `.DONE`, `.review-signal-*`, `lane-state-*.json`, `merge-request-*.txt`. The mailbox just extends a proven idiom. + +--- + +# ACT 3 — How Taskplane runs (≈ 8:30) + +## Scene 10 · Worktrees and parallelization · 13:00 – 14:30 (~1:30) + +- **On camera:** Heavy visual; bookend talking head. +- **B-roll / capture:** Terminal: `git worktree list` during a batch. Show `.worktrees/{batchId}/lane-1/`, `lane-2/`, `merge/`. File explorer side-by-side showing two lanes with different files. +- **Visual cue:** **V8 — Waves, lanes, worktrees** (`visuals/08-waves-lanes-worktrees.html`). +- **Talking points:** + - The unit of isolation is a **git worktree**. Each lane gets its own working directory pinned to its own branch, sharing the same `.git` history. + - Why worktrees and not just "more directories": + - shared object store — cheap + - real branches — auditable + - clean parallelism — no agent can clobber another's files + - failure preservation — a failed lane's worktree stays around for forensics + - **Three concepts, three jobs:** + - **Wave** — a dependency-safe batch. Topological sort over the task DAG. Wave 2 doesn't start until Wave 1's merge completes. + - **Lane** — a parallel execution slot within a wave. Capped by `max_lanes`. A lane runs one worker at a time; multiple tasks on the same lane run **serially**. + - **Worktree** — the lane's actual checkout. + - **Affinity-first lane assignment** is the under-loved feature. Tasks that share `## File Scope` entries get collapsed onto the same lane so they execute in sequence in a shared worktree. That converts a future merge conflict into a no-op fast-forward. The verbosity in PROMPT.md is what makes this safe. + +## Scene 11 · The branching / merging strategy · 14:30 – 16:30 (~2:00) + +- **On camera:** Visual primary throughout; screen-cap interleaved. +- **B-roll / capture:** `git log --graph --oneline --all` during a multi-wave batch. Show the orch branch, the lane branches fanning off and merging back. Then `/orch-integrate` and the fast-forward of `main`. +- **Visual cue:** **V9 — Branching lifecycle** (`visuals/09-branching-lifecycle.html`). +- **Talking points:** + - **Your working branch is sacred.** Taskplane never touches it during a batch. + - The flow: + 1. `/orch` creates `orch/{operatorId}-{batchId}` from your current branch. + 2. Each lane gets `task/{op}-lane-{N}-{batchId}` off the orch branch. + 3. Workers commit to lane branches. + 4. When a wave finishes, lane branches **merge into the orch branch** (not into your working branch). + 5. Next wave starts from the post-merge orch branch state. This is critical: Wave 2 sees Wave 1's combined output, not just one lane's view. + 6. When all waves complete, `/orch-integrate` brings the orch branch back to your working branch (fast-forward, merge commit, or PR — your call). + - **Why this matters:** + - You can keep working in your checkout while a batch runs. + - If a batch dies on Wave 3, your working branch is still clean. Restart, retry, or walk away. + - Integration is an explicit, reviewable step. No surprise merges. + +## Scene 12 · The LLM merge agent · 16:30 – 18:00 (~1:30) + +- **On camera:** Visual + screen capture. +- **B-roll / capture:** Walk through a real conflict resolution from a prior batch (or stage one): + 1. `git merge` halts with a conflict marker + 2. The merge agent reads PROMPT.md for both lanes + 3. Resolves semantically, commits, runs verify command + 4. Result JSON written, engine picks it up +- **Visual cue:** **V10 — Semantic merge vs git merge** (`visuals/10-semantic-merge.html`). +- **Talking points:** + - Plain `git merge` does textual 3-way. It can't tell you that Worker A adding validation and Worker B adding a parameter are **complementary** changes — it just sees overlapping regions and gives up. + - Taskplane's merge agent is a **full LLM with read/write/edit/bash**. It: + 1. Reads conflict markers + 2. Reads both sides' PROMPT.md to understand intent + 3. Edits the file to combine the changes semantically + 4. Commits + 5. Runs your `merge.verify` command (typically the test suite) + 6. If verify fails, it can iterate on the merge before reporting failure + - **Merge health monitor** runs in the background — every 2 minutes, checks PID liveness + activity. Stale at 10 min, stuck at 20 min. It **emits events but never kills autonomously**. The supervisor (you, or the autonomous one) decides. + - This is the piece that makes genuine parallelism safe. Without it, you'd either serialize everything (slow) or hope file scopes don't overlap (fragile). + +## Scene 13 · Polyrepo: the hard problem · 18:00 – 21:00 (~3:00) + +- **On camera:** Heavy visual; periodic screen-cap. +- **B-roll / capture:** + - Show a workspace folder with `taskplane-pointer.json` at the root and 3 sibling repos (`shared-libs/`, `api-service/`, `web-client/`). + - Open a real multi-repo PROMPT.md showing `#### Segment: shared-libs` markers in each step. + - Show `.pi/batch-state.json` with `segments[]` array, `packetRepoId`, `activeSegmentId`. +- **Visual cue:** **V11 — Polyrepo segments + packet home** (`visuals/11-polyrepo-segments.html`). +- **Talking points:** + - **Monorepo is the easy case.** One git history, one set of worktrees, one merge target. Taskplane runs single-repo mode and most of what we just talked about applies cleanly. + - **Polyrepo is the hard case** because: + 1. Three independent git histories that need to advance *coherently*. + 2. A single task's code changes might span multiple repos. + 3. The task's PROMPT.md / STATUS.md / .DONE need a single source of truth — they can't be duplicated across repos. + 4. Each repo's worktree, branch, and merge has to be tracked independently. + 5. Failures need to be repo-scoped so unrelated work keeps moving. + - **Taskplane's answers:** + - **Workspace mode** kicks in when `taskplane-pointer.json` is present. No silent fallback to repo mode. + - **A packet home repo** is declared in config (`routing.taskPacketRepo`). All packet files (PROMPT.md / STATUS.md / .DONE / .reviews) live there. No ambiguity. + - **Tasks decompose into segments** — one segment per repo. A task spanning three repos has three segments. + - **Segment markers in PROMPT.md** (`#### Segment: `) tell the worker which repo to write to. The skill generates these explicitly — no inference. + - **A segment DAG** controls intra-task ordering: shared-libs first, then API, then web-client. Optional explicit `## Segment DAG` block, with deterministic inference as fallback. + - **The orch branch is created per-repo.** `/orch-integrate` loops over every repo with an orch branch. + - The point: polyrepo isn't bolted on. The persistence schema (v4) treats segments as first-class. The lane runner uses `ExecutionUnit.packet` paths instead of inferring from cwd. Every place that touches "the repo" knows it might be one of many. + +## Scene 14 · Segmentation in action · 21:00 – 22:00 (~1:00) + +- **On camera:** Visual + screen capture together. +- **B-roll / capture:** Walk one real multi-repo task through: + 1. Skill generates PROMPT.md with segments for `shared-libs`, `api-service`, `web-client` + 2. Planner builds segment DAG + 3. Lane runs Segment A (shared-libs), commits in shared-libs worktree + 4. Same lane picks up Segment B (api-service), commits in api-service worktree + 5. STATUS.md updates land in the packet home repo throughout +- **Visual cue:** keep **V11** on screen; optionally overlay STATUS.md updates. +- **Talking points:** + - One task. One STATUS.md. Multiple worktrees. Sequential segments inside the task; parallel tasks across the wave. + - The worker keeps full task context across segments — it can *read* across all repos at any time for planning. It can only *write* into the active segment repo and the packet home repo. + - **Dynamic segment expansion** (post-MVP) lets a worker say "I need to touch a 4th repo I didn't anticipate" — engine validates, supervisor approves, DAG mutates. + - The headline: polyrepo work is no longer "run three sequential single-repo batches and pray." It's one coherent task with one memory. + +--- + +# ACT 4 — The operator's view (≈ 2:30) + +## Scene 15 · Why a web dashboard (not CLI) · 22:00 – 23:30 (~1:30) + +- **On camera:** Screen-cap heavy. Open the dashboard during a live batch. +- **B-roll / capture:** + - `taskplane dashboard` → `http://localhost:8099` + - Show wave/lane progress bars, the active worker row with token count + cost, a reviewer sub-row firing under a task, merge telemetry, batch history. + - Brief cut to a `tmux`-style pile of panes for contrast. +- **Visual cue:** **V12 — Dashboard visibility map** (`visuals/12-dashboard-visibility.html`). +- **Talking points:** + - I get asked this a lot: *"Why not a CLI dashboard? You're a CLI guy."* + - Two reasons. + 1. **The data is structured.** Lane state, reviewer state, merge state, supervisor actions, batch history. CLIs are good at one stream. Dashboards are good at many. + 2. **The audience is mid-glance.** When I'm running a batch I'm not staring at it. I check every few minutes. A browser tab updates over SSE while I work; a tmux pane needs my attention to render. + - The dashboard is **read-only** by design. Control happens through the supervisor agent or `/orch` commands. The dashboard never lies because it never decides. + - One file per source: `.pi/batch-state.json`, `.pi/lane-state-*.json`, `.pi/supervisor/events.jsonl`, `.reviews/`. The dashboard is a view over disk, not a process you trust. + +## Scene 16 · The right balance of visibility (light factory) · 23:30 – 24:30 (~1:00) + +- **On camera:** Talking head primary; brief recall of V2. +- **B-roll / capture:** — +- **Visual cue:** brief recall of **V2 — Light factory vs dark factory**, then back to talking head for the close. +- **Talking points:** + - Bring it home: the *visibility* spectrum. + - **Too dark:** "Tell the agent what to do, come back tomorrow." Cheap until it isn't. + - **Too bright:** every keystroke streams to your terminal, you babysit the agent. + - **The middle (light factory):** + - The plan is on disk (PROMPT.md) + - The progress is on disk (STATUS.md) + - The decisions are on disk (`.reviews/`, mailbox, events.jsonl) + - The control surface is asymmetric — you can step in at any boundary (steer via mailbox, pause via `/orch-pause`, retry a task, force a merge) but you don't *have* to. + - This is the rule I'd defend hardest: **autonomy is fine, but it must be inspectable autonomy.** If you can't audit what an agent did from disk after the fact, you've built a dark factory. + +## Scene 17 · Close · 24:30 – 25:00 (~0:30) + +- **On camera:** Talking head, tight shot. +- **B-roll / capture:** — +- **Visual cue:** Title card / repo link / dashboard URL. +- **Talking points:** + - One-line recap: *"Four agents. Verbose packets. Deterministic orchestration. Cross-model reviews. Worktree isolation. Semantic merges. Packet-home polyrepo. A dashboard that doesn't lie."* + - What to do next: install, run `taskplane init`, run the first orchestration tutorial, watch the dashboard. + - Where to find it: GitHub link, npm package, docs. + - Sign-off — your usual outro. + +--- + +# Extras / cutting-room + +These are agenda items you didn't list but I think are worth a beat. Drop in where you have room or save for a Part 2. + +1. **The persistent-context worker loop** — one worker per task, not one worker per step. Single context across all steps. Iteration only on context overflow. Massive cost reduction vs. fresh-spawn-per-step. Worth a 60-second beat in Scene 6 or as a chapter marker. +2. **Quality gate** (post-`.DONE` cross-model review with PASS / NEEDS_FIXES verdict + remediation loop). Mentionable in Scene 8 as a "third tier of review." +3. **Resilience tier** — supervisor exit interception (worker exits without progress → supervisor gets the last message + can re-steer up to 2× before failing the task). One-line in Scene 9. +4. **The skill is open-ended on STATUS.md hydration** — outcome-level checkboxes preferred over micro-checklists; the `⚠️ Hydrate` marker for discovery-dependent steps. Optional 30-second clip in Scene 6 if you want to defend the "no micro-script" stance. +5. **Doctor / init / templates** — quick CLI demo of `taskplane init` and `taskplane doctor`. Good cold-open candidate for a follow-up "getting started" video. +6. **Why pi (not Claude Code / etc. directly)** — pi gives Taskplane the multi-model abstraction it needs for cross-model reviews. Worth a 30s sidebar in Scene 8 if you want to head off the FAQ. +7. **Self-doc loop** — the `selfDocTargets` config that lets agents log discoveries into project docs over time. A nice tease for a future video. + +--- + +# Visuals manifest + +All visuals are standalone HTML files in `docs/video/visuals/`. Each is dark-IDE-styled, monospace, with green/amber accents. They're written to be: + +- **Reusable** — drop into a blog post, a slide, or a website unchanged +- **Recordable** — open in a browser, OBS scene-capture the window +- **Editable** — single file each, all CSS inline, no external assets + +| # | File | Used in scene(s) | Purpose | +| --- | ----------------------------------- | ---------------- | -------------------------------------------------------------------- | +| V1 | `01-origin-timeline.html` | 2 | Vibe → Ralph → Parallel Ralph → Taskplane progression | +| V2 | `02-light-factory-vs-dark.html` | 3, 16 | Side-by-side philosophy framing | +| V3 | `03-agent-quartet.html` | 4, 5 | Four agent roles with one-line responsibilities | +| V4 | `04-task-packet-anatomy.html` | 6 | Annotated PROMPT.md + STATUS.md structure | +| V5 | `05-determinism-spectrum.html` | 7 | What Taskplane forces deterministic vs leaves to the model | +| V6 | `06-cross-model-review.html` | 8 | Worker model → Reviewer model handoff with verdicts | +| V7 | `07-mailbox-protocol.html` | 9 | Supervisor ↔ inbox/outbox ↔ agent file flow | +| V8 | `08-waves-lanes-worktrees.html` | 10 | Wave → Lane → Worktree hierarchy | +| V9 | `09-branching-lifecycle.html` | 11 | Working branch → orch branch → lane branches → merge → integrate | +| V10 | `10-semantic-merge.html` | 12 | git merge conflict vs LLM semantic resolution | +| V11 | `11-polyrepo-segments.html` | 13, 14 | Three repos, segments per repo, packet home, segment DAG | +| V12 | `12-dashboard-visibility.html` | 15 | What the dashboard exposes from disk | + +--- + +# Pacing summary + +| Act | Window | Length | Cumulative | +| --- | -------------- | ------- | ---------- | +| 1 | 0:00 – 5:30 | 5:30 | 5:30 | +| 2 | 5:30 – 13:00 | 7:30 | 13:00 | +| 3 | 13:00 – 21:30 | 8:30 | 21:30 | +| 4 | 21:30 – 25:00 | 3:30 | 25:00 | + +Total: 25:00. Trim Scene 14 or Scene 16 to land closer to 22 minutes if needed; both are designed to absorb cuts without breaking the throughline. + +--- + +# Open questions for the next iteration + +Things I'd like your decision on before we move from storyboard → script: + +1. **Live demo or pre-recorded screen captures?** Live is more authentic, pre-recorded is cleaner. I'd suggest pre-recorded for Scenes 6, 11, 12, 13–15 and live for Scene 2's B-roll vignettes. +2. **Real client name on screen?** Some of the dashboard / status / mailbox captures will show real task IDs (TP-xxx). Are any of those sensitive, or all fair game? +3. **One million lines — should we cite the source?** A subtle on-screen badge would land the claim harder. Up to you whether to be specific or keep it as a round figure. +4. **Music?** Doesn't change the storyboard but does change the pacing of Scenes 2 and 17. If there's a bed I should write to, tell me now. +5. **Companion blog post?** This storyboard reads like a longform article with a couple of pivots. Would be cheap to spin out as a Medium piece that links back to the video. diff --git a/docs/video/visuals/01-origin-timeline.html b/docs/video/visuals/01-origin-timeline.html new file mode 100644 index 00000000..ff06a112 --- /dev/null +++ b/docs/video/visuals/01-origin-timeline.html @@ -0,0 +1,159 @@ + + + + +V1 — Origin timeline + + + + +
+
+ 1 · Origin + +
+

The road to Taskplane

+

A million lines of AI-generated code. Three failed harnesses. Each failure produced a design rule.

+ +
+
+
01
+
+
Vibe coding
+
stage one · chat-driven
+
Paste, regenerate, accept. Fast for greenfield prototypes. Falls apart the moment the codebase outgrows the model's working memory.
+
lesson → A working memory must live outside the model.
+
+
+ +
+
02
+
+
Ralph Wiggum loop
+
stage two · single agent, single prompt
+
One prompt, run it forever. The agent grinds. Beautiful for narrow problems. Drops context across iterations and can't survive long-running work.
+
lesson → State must be on disk. STATUS.md was born here.
+
+
+ +
+
03
+
+
Parallel Ralph
+
stage three · many agents, one repo
+
More loops, more throughput — and a cascade of silent collisions. Two agents both "complete." One overwrites the other. Git stops being a safety net.
+
lesson → Worktrees. Lanes. A real DAG. And a merge that understands intent.
+
+
+ +
+
04
+
+
Taskplane
+
today · deterministic orchestration
+
Four agents. Verbose packets. File-backed state. Worktree isolation. Cross-model reviews. Semantic merges. A web-based dashboard to drive observability.
+
rule → Autonomy is fine. Inspectable autonomy is the goal.
+
+
+
+ +
+ vibe → ralph → parallel ralph → taskplane · ~1M lines of AI-generated code along the way +
+
+ + diff --git a/docs/video/visuals/02-light-factory-vs-dark.html b/docs/video/visuals/02-light-factory-vs-dark.html new file mode 100644 index 00000000..d95f27e9 --- /dev/null +++ b/docs/video/visuals/02-light-factory-vs-dark.html @@ -0,0 +1,143 @@ + + + + +V2 — Light factory vs dark factory + + + + +
+
+ 2 · Philosophy + +
+

Light factory vs dark factory

+

Two ways to run autonomous agents but the light factory model gives you the visibility you need to steer effectively.

+ +
+
+
Dark factory
+
"Just trust the agent"
+
Single opaque prompt. Agent decides everything. You see the receipts only when it's over.
+
    +
  • ✕
    One-line prompts. No file scope, no dependencies, no guardrails.
    • +
  • ✕
    In-memory state. Crash = lose the work and the plan.
    • +
  • ✕
    Shared working directory. Silent collisions. Last writer wins.
    • +
  • ✕
    No review surface. Same model writes, same model evaluates. Confirmation bias.
    • +
  • ✕
    Black-box telemetry. Spinner spinning. $8 burning. No clue why.
    • +
+
visibility → 0 · recoverability → 0 · operator clarity → 0
+
+ +
+
Light factory · Taskplane
+
"Show the work"
+
The plan is on disk. The progress is on disk. The decisions are on disk. The orchestration is deterministic around the model's randomness.
+
    +
  • ✓
    Verbose task packets. PROMPT.md + STATUS.md. What, why, and where to write.
    • +
  • ✓
    File-backed state. .DONE, STATUS.md, batch-state.json. Resume from any crash.
    • +
  • ✓
    Worktree isolation. Every lane is its own checkout. No collisions, ever.
    • +
  • ✓
    Cross-model reviews. Different family on the other side. Independent quality gate.
    • +
  • ✓
    Dashboard reads disk. SSE-streamed truth. Cannot lie. Doesn't decide.
    • +
+
visibility → full · recoverability → atomic · operator clarity → first-class
+
+
+ +
+ autonomy is fine — inspectable autonomy is the goal +
+
+ + diff --git a/docs/video/visuals/03-agent-quartet.html b/docs/video/visuals/03-agent-quartet.html new file mode 100644 index 00000000..bdf96fb6 --- /dev/null +++ b/docs/video/visuals/03-agent-quartet.html @@ -0,0 +1,195 @@ + + + + +V3 — Agent quartet + + + + +
+
+ 3 · Roster + +
+

The agent quartet

+

Four roles. Four prompts. Four jobs. No more agents than the work demands — and no less.

+ +
+
+
+
supervisor
+
control
+
+
The conversational operator-in-the-loop. Watches the batch, talks to agents, never writes code.
+
Owns
+
    +
  • batch progress + recovery
    • +
  • steering via mailbox
    • +
  • orch_* tool calls
    • +
  • failure triage
    • +
+
model → your session model
+
+ +
+
+
worker
+
execute
+
+
Implements the steps in PROMPT.md. One per lane. Owns checkpoint discipline and STATUS.md.
+
Owns
+
    +
  • step-by-step execution
    • +
  • commits at step boundary
    • +
  • review_step calls
    • +
  • .DONE on completion
    • +
+
model → e.g. claude-opus
+
+ +
+
+
reviewer
+
verify
+
+
Independent quality gate. Reads plans and code. Persistent across a task — remembers what it flagged earlier.
+
Owns
+
    +
  • plan + code reviews
    • +
  • APPROVE / REVISE / RETHINK
    • +
  • cross-step memory
    • +
  • verdicts on disk in .reviews/
    • +
+
model → different family (e.g. gpt-5)
+
+ +
+
+
merger
+
integrate
+
+
LLM that combines lane branches into the orch branch. Reads conflict markers. Resolves semantically. Runs verify.
+
Owns
+
    +
  • git merge --no-ff per lane
    • +
  • semantic conflict resolution
    • +
  • post-merge verification
    • +
  • result.json reporting
    • +
+
model → capable code model
+
+
+ +
+ supervisor → spawns worker per lane → worker calls reviewer at step boundaries → wave completes → merger combines lanes → next wave +
+
+ + diff --git a/docs/video/visuals/04-task-packet-anatomy.html b/docs/video/visuals/04-task-packet-anatomy.html new file mode 100644 index 00000000..971fff17 --- /dev/null +++ b/docs/video/visuals/04-task-packet-anatomy.html @@ -0,0 +1,191 @@ + + + + +V4 — Anatomy of a task packet + + + + +
+
+ 4 · The contract + +
+

Anatomy of a Taskplane task packet

+

Two files. The plan and the memory. Verbose by design — the verbosity is what makes wave planning, lane affinity, and resume deterministic.

+ +
+
+
## Mission
+
What and why. The worker starts with no memory of the conversation that created the task. Mission is the brief.
+
+
+
## Dependencies
+
Machine-parsed. Feeds the wave DAG. **Task:** patterns and **External:** entries — strict format on purpose.
+
+
+
## File Scope
+
Feeds lane affinity. Two tasks that share files land on the same lane and run serially. Verbosity here prevents merge conflicts later.
+
+
+
### Step N
+
Outcome-level checkboxes. Each step has a commit boundary. Plan + code reviews fire at the step level when review level ≥ 1.
+
+
+
## Do NOT
+
Explicit guardrails. Workers shortcut when given room. Naming the off-limits surface area reduces that pull.
+
+
+
STATUS.md
+
The memory. Iteration count, current step, checkboxes, discoveries, review history. Survives crashes. Drives resume.
+
+
+ +
+
+
PROMPT.mdthe contract · immutable
+
+
1# TP-201 · Add repo-aware fields to schema
+
2.
+
3## Mission
+
4Add repoId + packetRepo to PersistedTaskRecord
+
5so resume can reconstruct segment frontier...
+
6.
+
7## Dependencies
+
8- **Task:** TP-081 (segment graph)
+
9- **None** for external
+
10.
+
11## File Scope
+
12- extensions/taskplane/types.ts
+
13- extensions/taskplane/persistence.ts
+
14.
+
15## Review Level: 2
+
16## Size: M
+
17.
+
18### Step 1: Add fields to types.ts
+
19- [ ] add repoId, packetRepo to PersistedTaskRecord
+
+
+ +
+
STATUS.mdthe memory · checkpoint log
+
+
1# TP-201 · STATUS
+
2.
+
3Current Step: 2
+
4Iteration: 1
+
5Reviews fired: 1 / max 8
+
6.
+
7### Step 1: Add fields ✓
+
8- [x] add repoId, packetRepo
+
9- [x] update schema version
+
10commit 9af2c1 · plan APPROVE · code APPROVE
+
11.
+
12### Step 2: Migration ⏵
+
13- [x] add v3→v4 upconverter
+
14- [ ] cover idempotent re-run
+
15awaiting plan review for step 2
+
16.
+
17### Step 3: Tests
+
18- [ ] add schema-v4-migration.test.ts
+
19.
+
+
+
+ +
+ + diff --git a/docs/video/visuals/05-determinism-spectrum.html b/docs/video/visuals/05-determinism-spectrum.html new file mode 100644 index 00000000..2dedb5f8 --- /dev/null +++ b/docs/video/visuals/05-determinism-spectrum.html @@ -0,0 +1,189 @@ + + + + +V5 — Determinism spectrum + + + + +
+
+ 5 · Design philosophy + +
+

Where Taskplane sits on the determinism spectrum

+

Push every decision you can to a deterministic file or rule, so the only randomness left is the model's actual thinking.

+ +
+
+ Fully deterministic + Fully autonomous +
+
+
+
TP
+
Taskplane
+
deterministic harness · autonomous calls
+
+
+
+ +
+
+
Forced deterministic
+
Everything around the LLM call. File-backed, rule-based, repeatable across runs.
+
    +
  • DAG resolutionKahn-style topological sort
    • +
  • Wave assignmentstable by task ID
    • +
  • Lane affinityfile-scope overlap → same lane
    • +
  • Branch namesorch/{op}-{batch} · task/{op}-lane-N-{batch}
    • +
  • State writesatomic temp → rename
    • +
  • Event logappend-only events.jsonl
    • +
  • Segment DAGexplicit ## Segment DAG or inferred chain for polyrepo support
    • +
  • Mailbox addressingbatch-scoped, session-scoped paths
    • +
+
+ +
+
Left to the model
+
The bits you can't make deterministic without giving up the value. Bounded by the harness.
+
    +
  • Worker implementationcode generation within step
    • +
  • Reviewer verdictsAPPROVE / REVISE / RETHINK
    • +
  • Merge resolutionssemantic conflict combining
    • +
  • Plan generationhow to approach a step
    • +
  • Supervisor steeringwhen / what to inject
    • +
  • Discovery hydrationcheckbox expansion at runtime
    • +
  • Verify-then-fixtest failures post-merge
    • +
  • Exit interceptionsupervisor re-steer up to 2×
    • +
+
+
+ +
+ Two runs of the same batch produce the same waves, the same lanes, the same branch names —
+ only the contents of the model's tokens differ. +
+
+ + diff --git a/docs/video/visuals/06-cross-model-review.html b/docs/video/visuals/06-cross-model-review.html new file mode 100644 index 00000000..1f2d7878 --- /dev/null +++ b/docs/video/visuals/06-cross-model-review.html @@ -0,0 +1,271 @@ + + + + +V6 — Cross-model review flow + + + + +
+
+ 6 · The independent gate + +
+

Cross-model reviews

+

What one model writes, another model reviews. Cross model reviews drive exceptional outcomes — different blind spots, different priors. The cheapest review you'll ever buy.

+ +
+
+
worker
+
implements steps
+
model: claude
+
    +
  • read PROMPT.md + STATUS.md
    • +
  • plan the step
    • +
  • → call review_step(plan)
    • +
  • implement on review.APPROVE
    • +
  • commit at step boundary
    • +
  • → call review_step(code)
    • +
  • address REVISE inline
    • +
+
+ +
+
+
request
+
+
+
+
verdict
+
+
+
+ +
+
reviewer
+
persistent · cross-step memory
+
model: gpt
+
    +
  • wait_for_review (tool, not bash)
    • +
  • read request-R00N.md
    • +
  • read code at baseline SHA only
    • +
  • cross-check earlier findings
    • +
  • write .reviews/R00N-{type}-stepN.md
    • +
  • emit verdict
    • +
  • wait_for_review again
    • +
+
+
+ +
Verdict surface
+
+
+
APPROVE
+
Continue to next step. Implementation commits stand.
+
+
+
REVISE
+
Worker reads feedback, fixes inline, recommits. Same context, no spawn.
+
+
+
RETHINK
+
Plan-level concern. Worker reconsiders the approach before more code.
+
+
+
UNAVAILABLE
+
Reviewer crashed / timed out. Worker proceeds cautiously. Logged for the operator.
+
+
+ +
+ review levels per task → 0 none · 1 plan · 2 plan + code · 3 plan + code + test +
step 0 (preflight) and the final step (docs) always skip +
+ +
+ + diff --git a/docs/video/visuals/07-mailbox-protocol.html b/docs/video/visuals/07-mailbox-protocol.html new file mode 100644 index 00000000..1f0672d2 --- /dev/null +++ b/docs/video/visuals/07-mailbox-protocol.html @@ -0,0 +1,214 @@ + + + + +V7 — Mailbox protocol + + + + +
+
+ 7 · Steering + +
+

The file-based mailbox

+

The supervisor and a running agent share a mailbox directory. Files in, files out, audit trail in the middle. Zero deps, cross-platform, survives crashes.

+ +
+
+
supervisor
+
writes inbox
+
send_agent_message · broadcast_message · read_agent_replies
+
+ +
+
.pi/mailbox/{batchId}/{session}/
+
+
inbox/
+
supervisor → agent "call review_step(plan) first"
+
+
+
ack/
+
processed moved on agent next turn
+
+
+
outbox/
+
agent → supervisor "blocked: missing repo config"
+
+
+
_broadcast/
+
supervisor → all "wrap up — context budget tight"
+
+
+ +
+
agent
+
reads inbox
+
rpc-wrapper injects messages via the steer command at turn boundaries
+
+
+ +
+
.pi/mailbox/ # batch-scoped root — stale msgs structurally impossible
+
└── 20260514T103207/ # {batchId}
+
├── orch-henrylach-lane-1/
+
│ ├── inbox/ 1774744971303-a7f2c.msg.json
+
│ ├── ack/ 1774744928110-91ce4.msg.json
+
│ └── outbox/ 1774744961200-ad21e.msg.json
+
├── orch-henrylach-lane-2/ …
+
└── _broadcast/
+
└── inbox/ 1774744990001-b04f7.msg.json # checked by every agent
+
+ +
+
+
reliable
+
batch-scoped paths, atomic moves to ack, no message ever lost or misdelivered.
+
+
+
debuggable
+
cat the inbox. you can see exactly what the supervisor told an agent and when.
+
+
+
bidirectional
+
agents reply into outbox/ — the engine polls and surfaces alerts to the supervisor.
+
+
+
portable
+
windows, macOS, linux — same protocol. no sockets, no named pipes, no daemon.
+
+
+
+ + diff --git a/docs/video/visuals/08-waves-lanes-worktrees.html b/docs/video/visuals/08-waves-lanes-worktrees.html new file mode 100644 index 00000000..83dd5baa --- /dev/null +++ b/docs/video/visuals/08-waves-lanes-worktrees.html @@ -0,0 +1,312 @@ + + + + +V8 — Waves, lanes, worktrees + + + + +
+
+ 8 · Execution hierarchy + +
+

Batch, waves, lanes, worktrees, tasks

+

A batch runs waves in series. Each wave runs lanes in parallel. Each lane runs tasks in series in its own git worktree. That's the whole shape.

+ +
+ wave + lane + worktree + task +
+ +
+
+
batch · orch/{username}-20260514T103207
+
10 tasks · 3 waves · max_lanes=3
+
+ +
+
+
Wave 1 · no unmet dependencies · parallel across lanes
+
+
+
lane-1
+
.worktrees/{batch}/lane-1/
+
+ TP-201→ + TP-202→ + TP-203 +
+
affinity-first · shared file scope · serial in shared worktree
+
+
+
lane-2
+
.worktrees/{batch}/lane-2/
+
+ TP-210 +
+
independent file scope · runs in parallel
+
+
+
lane-3
+
.worktrees/{batch}/lane-3/
+
+ TP-215 +
+
independent file scope · runs in parallel
+
+
+
lane branches → merge worktree → orch branch · LLM merger runs verify
+
+ +
+
Wave 2 · deps satisfied by wave 1 · parallel across lanes
+
+
+
lane-1
+
.worktrees/{batch}/lane-1/
+
+ TP-204→ + TP-205 +
+
sees wave 1's merged orch state
+
+
+
lane-2
+
.worktrees/{batch}/lane-2/
+
+ TP-220 +
+
parallel
+
+
+
lane-3
+
.worktrees/{batch}/lane-3/
+
+ TP-225 +
+
parallel
+
+
+
lane branches → merge worktree → orch branch
+
+ +
+
Wave 3 · final · serial when only one task remains
+
+
+
lane-1
+
.worktrees/{batch}/lane-1/
+
+ TP-230 +
+
depends on TP-220 + TP-225
+
+
+
lane-2 · idle
+
—
+
+
nothing assigned this wave
+
+
+
lane-3 · idle
+
—
+
+
nothing assigned this wave
+
+
+
all waves merged into orch branch · ready for /orch-integrate for final merge or PR to working branch
+
+
+
+ +
+
+
Waves are serial
+
Wave N+1 starts only after wave N's merge into the orch branch completes. The next wave always sees integrated state.
+
+
+
Lanes are parallel
+
Up to max_lanes within a wave. Each lane is one subprocess worker against one worktree against one branch.
+
+
+
Tasks share lanes when scopes overlap
+
Affinity-first assignment. Overlapping ## File Scope entries collapse onto the same lane and run serially.
+
+
+
+ + diff --git a/docs/video/visuals/09-branching-lifecycle.html b/docs/video/visuals/09-branching-lifecycle.html new file mode 100644 index 00000000..fad1ecb4 --- /dev/null +++ b/docs/video/visuals/09-branching-lifecycle.html @@ -0,0 +1,263 @@ + + + + +V9 — Branching lifecycle + + + + +
+
+ 9 · Git topology + +
+

How Taskplane uses branches

+

Your working branch stays untouched for the whole batch. Lanes commit to lane branches. Lane branches merge into the orch branch wave by wave. Only /orch-integrate brings the orch branch home.

+ +
+
+
develop → your working branch
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + develop + orch/... + lane-1 + lane-2 + + + wave 1 + wave 2 + wave 3 + /orch-integrate + + + + + + + +
+ develop (your branch, untouched during batch) + orch branch (created by /orch) + lane branches (workers commit here) + merge / integrate commits +
+
+ +
+
+
1
+
/orch creates orch branch
+
orch/{op}-{batchId} forks from your current branch. Working branch is now frozen for the duration.
+
+
+
2
+
lanes fork from orch
+
One task/{op}-lane-N-{batchId} per lane. Workers commit here in worktrees.
+
+
+
3
+
wave merge
+
After each wave, a merge agent combines lane branches back into orch. Next wave sees the previous wave's merged changes.
+
+
+
4
+
all waves complete
+
Orch branch now holds the full batch result. Your working branch is still untouched.
+
+
+
5
+
/orch-integrate
+
Fast-forward, merge commit, or open a PR. Your choice. Always an explicit step.
+
+
+ +
+ your working branch is sacred — never touched until /orch-integrate +
+
+ + diff --git a/docs/video/visuals/10-semantic-merge.html b/docs/video/visuals/10-semantic-merge.html new file mode 100644 index 00000000..8d444572 --- /dev/null +++ b/docs/video/visuals/10-semantic-merge.html @@ -0,0 +1,212 @@ + + + + +V10 — Semantic merge vs git merge + + + + +
+
+ 10 · The merge agent + +
+

Semantic merge vs git merge

+

Plain git merge sees text. The Taskplane merge agent reads task intent, understands the diff, and resolves conflicts as a developer would. With a verify step.

+ +
+
+
git merge · 3-way text
+
conflict markers, no resolution
+
Worker A added validation. Worker B added an options parameter. Both touched the same region. Git stops.
+ 
function process(data, options) {
+<<<<<<< HEAD
+  validate(data);
+  return transform(data);
+=======
+  return transform(data, options);
+>>>>>>> task/lane-2
+}
+// neither side complete · build is broken
+// merge halts · operator must fix by hand
+
verdict → fail · waits for human · cannot proceed
+
+ +
+
Taskplane merge · LLM with read/write/edit/bash
+
reads intent, combines correctly
+
The merger reads both lanes' PROMPT.md, sees A wanted validation and B wanted options, and combines them. Then runs the test suite.
+ 
function process(data, options) {
+  validate(data);
+  return transform(data, options);
+}
+// both changes preserved · semantics intact
+// git add + commit + run verify command
+$ node --test tests/*.test.ts
+  ✓ 3,587 tests passed
+
verdict → succeeded · 2 conflicts resolved · tests green
+
+
+ +
+
merge agent lifecycle
+
+
+
1
+
request
+
Engine writes merge-request file with branches + task IDs + verify command.
+
+
+
2
+
spawn in merge worktree
+
Agent lives in .worktrees/{batch}/merge/. Full tool access.
+
+
+
3
+
merge per lane
+
git merge → if conflict, read PROMPT.md, resolve in code, git add + commit.
+
+
+
4
+
verify
+
Run the configured verify command (typically the test suite). Iterate on failures.
+
+
+
5
+
result.json
+
Engine polls. Counters update. Next wave provisions.
+
+
+
+ +
+ merge health monitor polls every 2 min · stale at 10 · stuck at 20 · emits events, never kills autonomously +
+
+ + diff --git a/docs/video/visuals/11-polyrepo-segments.html b/docs/video/visuals/11-polyrepo-segments.html new file mode 100644 index 00000000..33546a09 --- /dev/null +++ b/docs/video/visuals/11-polyrepo-segments.html @@ -0,0 +1,284 @@ + + + + +V11 — Polyrepo segments + + + + +
+
+ 11 · The hard case + +
+

Polyrepo: tasks decompose into segments

+

One task. Three repos. A segment per repo. A segment DAG to order them. One packet home for the task's memory. Every other piece — worktrees, branches, merges — happens independently per repo.

+ +
+
+
workspace · ~/dev/tp-test-workspace/ · taskplane-pointer.json
+
workspace mode · 3 repos · routing.taskPacketRepo = shared-libs
+
+ +
+
+
shared-libs packet home
+
../shared-libs · main
+
Segments owned
+ TP-302::shared-libs +
Code touched
+
packages/utils/string.ts
packages/types/api.ts
+
Packet files
+
PROMPT.md · STATUS.md · .DONE · .reviews/
+
+ +
+
api-service
+
../api-service · main
+
Segments owned
+ TP-302::api-service +
Code touched
+
src/handlers/users.ts
src/schemas/user.ts
+
Packet files
+
— writes flow back to packet home
+
+ +
+
web-client
+
../web-client · main
+
Segments owned
+ TP-302::web-client +
Code touched
+
src/api/client.ts
src/components/Profile.tsx
+
Packet files
+
— writes flow back to packet home
+
+
+
+ +
+
Segment DAG · task TP-302 · intra-task ordering
+
+
+
segment 1
+
shared-libs
+
+
→
+
+
segment 2
+
api-service
+
+
→
+
+
segment 3
+
web-client
+
+
+
+ +
+
+
Packet authority
+
STATUS.md, .DONE, .reviews/ are always written to the packet home repo. No splits, no inference.
+
+
+
Segment isolation
+
Workers read across all repos for planning. They write only to the active segment repo + the packet home.
+
+
+
Per-repo orch branches
+
An orch/… branch is created in every repo with work. /orch-integrate loops over all of them.
+
+
+
+ + diff --git a/docs/video/visuals/12-dashboard-visibility.html b/docs/video/visuals/12-dashboard-visibility.html new file mode 100644 index 00000000..08947307 --- /dev/null +++ b/docs/video/visuals/12-dashboard-visibility.html @@ -0,0 +1,256 @@ + + + + +V12 — Dashboard visibility map + + + + +
+
+ 12 · The operator's view + +
+

Why a web dashboard, not a CLI

+

The dashboard is a view over disk — every panel maps to a file the engine already writes. It reads, it never decides. It cannot lie.

+ +
+
+ Taskplane dashboard — batch 20260515T095750 mid-wave-2: lane status, merge agents, agent sessions +
+ +
+
+
Data sources (read-only)
+
    +
  • batch state
    • +
  • lane snapshots
    • +
  • events
    • +
  • actions
    • +
  • history
    • +
  • reviews
    • +
  • status
    • +
  • mailbox
    • +
+
+ +
+
Why not a CLI
+
    +
  • structured data — many sources, many shapes; a dashboard fans them out, a CLI flattens them.
    • +
  • mid-glance ergonomics — SSE pushes truth into a tab; the tab updates while you're somewhere else.
    • +
  • read-only by design — control lives in /orch and the supervisor agent; the dashboard never decides.
    • +
  • file-backed truth — every panel maps to a file. If it disagrees, the file wins.
    • +
+
+
+
+ +
+ one tab. all the truth. no babysitting required. +
+
+ + diff --git a/docs/video/visuals/_shared.css b/docs/video/visuals/_shared.css new file mode 100644 index 00000000..368a08b0 --- /dev/null +++ b/docs/video/visuals/_shared.css @@ -0,0 +1,204 @@ +/* ============================================================================ + Taskplane intro video · shared visual stylesheet + ---------------------------------------------------------------------------- + Edit this file to make universal changes to every visual at once. + Each per-visual HTML file imports this file and adds its own + layout/component styles inline. + + Sections: + 1. Design tokens (colors, fonts, type scale, spacing) + 1a. Global scale knob (single value resizes text + page padding) + 1b. Surfaces + text + 1c. Accents + 1d. Fonts + 1e. Type scale (size ladder + semantic aliases) + 1f. Page padding / frame width + 1g. Radii + 2. Reset (box-sizing, margin/padding zeroing) + 3. Base (body, html backgrounds) + 4. Frame (centered container) + 5. Typography (.eyebrow, h1, .subtitle) + ============================================================================ */ + + +/* ---------------------------------------------------------------------------- + 1. Design tokens + ---------------------------------------------------------------------------- */ +:root { + + /* ----- 1a. Scale knob ---------------------------------------------------- + One number to enlarge or shrink everything controlled by shared.css. + Per-file hardcoded paddings/gaps are NOT affected — text gets bigger + while containers keep their original geometry. That's usually what you + want for "fill the screen" output: text dominates and reads on mobile. + + --scale: 1 → IDE-density (matches original storyboard preview) + --scale: 1.5 → 16:9 video-ready · mobile-readable on YouTube (default) + --scale: 1.75 → larger still; some dense visuals (V8, V12) may exceed + 1080p height — scroll or zoom Chrome out to compensate + --scale: 2 → poster / thumbnail capture + -------------------------------------------------------------------------- */ + --scale: 1.5; + + + /* ----- 1b. Surfaces + text ----------------------------------------------- */ + --bg: #0d1117; + --surface: #161b22; + --surface-2: #1c2128; + --border: #30363d; + + --text: #e6edf3; /* primary — high contrast */ + --text-dim: #c9d1d9; /* secondary — was #8b949e, bumped for mobile/video */ + --text-faint: #a3aeb8; /* tertiary — was #6e7681, bumped for mobile/video */ + + + /* ----- 1c. Accents ------------------------------------------------------- */ + --green: #7ee787; + --amber: #f0b35e; + --blue: #79c0ff; + --red: #ff7b72; + --purple: #d2a8ff; + --pink: #ff9bb8; + + + /* ----- 1d. Fonts --------------------------------------------------------- */ + --mono: 'JetBrains Mono', 'Fira Code', Menlo, Consolas, monospace; + --sans: 'Inter', -apple-system, system-ui, sans-serif; + + + /* ----- 1e. Type scale --------------------------------------------------- + The base values (9px, 10px, 11px, …) are the "natural" sizes. They get + multiplied by --scale at runtime, so the ratios are preserved. Tweak a + base value to drift just that rung without affecting the rest. + -------------------------------------------------------------------------- */ + + /* size ladder */ + --fs-3xs: calc( 9px * var(--scale)); /* tiny badges (home-badge) */ + --fs-2xs: calc(10px * var(--scale)); /* micro labels, table headers */ + --fs-xs: calc(11px * var(--scale)); /* tags, lane labels, panel labels */ + --fs-sm: calc(12px * var(--scale)); /* small body, code, file lines */ + --fs-md: calc(13px * var(--scale)); /* default body, eyebrow */ + --fs-lg: calc(14px * var(--scale)); /* descriptions, taglines */ + --fs-xl: calc(16px * var(--scale)); /* subtitle, marker pins */ + --fs-2xl: calc(18px * var(--scale)); /* medium card titles, agent names */ + --fs-3xl: calc(20px * var(--scale)); /* large numeric values, panel titles */ + --fs-4xl: calc(22px * var(--scale)); /* hero inline names, actor names */ + --fs-5xl: calc(26px * var(--scale)); /* hero display titles inside cards */ + --fs-6xl: calc(36px * var(--scale)); /* page h1 */ + --fs-icon: calc(24px * var(--scale)); /* large icon glyphs (DAG arrows) */ + + /* semantic aliases (used by base styles below) */ + --fs-h1: var(--fs-6xl); + --fs-eyebrow: var(--fs-md); + --fs-subtitle: var(--fs-xl); + + + /* ----- 1f. Page padding / frame width ------------------------------------ */ + --page-pad-y: calc(32px * var(--scale)); /* top/bottom body padding */ + --page-pad-x: calc(40px * var(--scale)); /* left/right body padding */ + --frame-max: 1820px; /* hard cap on content width (16:9 ≈ 1920) */ + --subtitle-mb: calc(28px * var(--scale)); /* space below h1 subtitle */ + + + /* ----- 1g. Radii --------------------------------------------------------- */ + --r-sm: 4px; + --r-md: 6px; + --r-lg: 8px; + --r-xl: 10px; + --r-2xl: 12px; +} + + +/* ---------------------------------------------------------------------------- + 2. Reset + ---------------------------------------------------------------------------- */ +*, +*::before, +*::after { + box-sizing: border-box; + margin: 0; + padding: 0; +} + + +/* ---------------------------------------------------------------------------- + 3. Base + ---------------------------------------------------------------------------- */ +html, +body { + background: var(--bg); + color: var(--text); + font-family: var(--sans); +} + +body { + min-height: 100vh; + padding: var(--page-pad-y) var(--page-pad-x); +} + + +/* ---------------------------------------------------------------------------- + 4. Frame + ---------------------------------------------------------------------------- */ +.frame { + max-width: var(--frame-max); + margin: 0 auto; +} + + +/* ---------------------------------------------------------------------------- + 5. Typography + ---------------------------------------------------------------------------- */ +.eyebrow { + font-family: var(--mono); + color: var(--green); + font-size: var(--fs-eyebrow); + letter-spacing: 0.12em; + text-transform: uppercase; + margin-bottom: 12px; + /* Allow a per-page nav (.page-nav) to sit at the right edge of the eyebrow. + With one child the title still aligns left as before. */ + display: flex; + align-items: center; + justify-content: space-between; + gap: 16px; +} + +/* Subtle per-page navigation: prev / index / next. Placed inside .eyebrow. */ +.page-nav { + display: inline-flex; + align-items: center; + gap: 14px; + letter-spacing: normal; + text-transform: none; + font-size: var(--fs-lg); + line-height: 1; +} +.page-nav a, +.page-nav span { + color: var(--text-faint); + text-decoration: none; + transition: color 0.15s ease; +} +.page-nav a:hover { + color: var(--green); +} +.page-nav .disabled { + opacity: 0.3; + cursor: default; +} + +h1 { + font-size: var(--fs-h1); + font-weight: 600; + letter-spacing: -0.01em; + margin-bottom: 8px; +} + +.subtitle { + color: var(--text-dim); + font-size: var(--fs-subtitle); + margin-bottom: var(--subtitle-mb); + max-width: calc(820px * var(--scale)); + line-height: 1.55; +} diff --git a/docs/video/visuals/dashboard-screenshot.png b/docs/video/visuals/dashboard-screenshot.png new file mode 100644 index 00000000..55fa138e Binary files /dev/null and b/docs/video/visuals/dashboard-screenshot.png differ diff --git a/docs/video/visuals/index.html b/docs/video/visuals/index.html new file mode 100644 index 00000000..0f222d52 --- /dev/null +++ b/docs/video/visuals/index.html @@ -0,0 +1,151 @@ + + + + +Taskplane intro video · visuals index + + + + +
+
Introduction to Taskplane
+

Visual Overview

+

These 12 pages provide a overview of how Taskplane dramatically improves AI agent coding outcomes for long-running multi-task orchestration.

+ +
+ +
1
+
Origin timeline
+
Vibe → Ralph → Parallel Ralph → Taskplane. The ~1M lines of lessons.
+ + +
2
+
Light factory vs dark factory
+
Two-panel philosophy framing. Visibility is the differentiator.
+ + +
3
+
The agent quartet
+
Supervisor · worker · reviewer · merger. One row, four jobs.
+ + +
4
+
Anatomy of a task packet
+
PROMPT.md + STATUS.md side by side with annotated callouts.
+ + +
5
+
Determinism spectrum
+
What Taskplane forces deterministic vs what it leaves to the model.
+ + +
6
+
Cross-model review flow
+
Opus writes · GPT reads · APPROVE / REVISE / RETHINK / UNAVAILABLE.
+ + +
7
+
Mailbox protocol
+
Inbox · outbox · ack · _broadcast. Supervisor steers via files.
+ + +
8
+
Waves, lanes, worktrees
+
Execution hierarchy with affinity-first lane assignment shown.
+ + +
9
+
Branching lifecycle
+
Working branch → orch branch → lane branches → merge → integrate.
+ + +
10
+
Semantic merge vs git merge
+
Side-by-side: conflict markers vs LLM-resolved combined intent.
+ + +
11
+
Polyrepo segments
+
Three repos, segment DAG, packet home repo, write isolation.
+ + +
12
+
Dashboard visibility map
+
A view over disk. Read-only. Cannot lie. Cannot decide.
+ +
+
+ +