From cc5276120ba5a2e152051fd5fc0c19152f5f37d9 Mon Sep 17 00:00:00 2001 From: Henry Lach Date: Sun, 17 May 2026 17:11:10 -0400 Subject: [PATCH] docs: extend intro-video visuals with pages 13-17 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds five new supporting visuals to the 'Introduction to Taskplane' video deck: 13 - Why pi? (foundation: extensible, model-agnostic, OSS) 14 - Pi capabilities (engineering surface Taskplane builds on) 15 - Getting started (install + sample batch — nine steps) 16 - Real-work playbook (spec → review → tasks → /orch-plan) 17 - Sage companion (cross-model post-batch review) Other tweaks: - _shared.css: subtitle max-width default is now 100% (drops the 820px soft cap that several pages were already overriding). - 08, 12: remove the now-redundant per-page subtitle overrides. - index.html: cards for 13-17 added, typo 'a overview' fixed, page-count subtitle bumped to 17. - 12: re-enable next arrow (now links to page 13). --- .../visuals/08-waves-lanes-worktrees.html | 4 - .../visuals/12-dashboard-visibility.html | 6 +- docs/video/visuals/13-why-pi.html | 142 +++++++++ docs/video/visuals/14-pi-capabilities.html | 152 ++++++++++ docs/video/visuals/15-how-to-get-started.html | 211 +++++++++++++ docs/video/visuals/16-real-work-playbook.html | 285 +++++++++++++++++ docs/video/visuals/17-sage-companion.html | 286 ++++++++++++++++++ docs/video/visuals/_shared.css | 3 +- docs/video/visuals/index.html | 32 +- 9 files changed, 1110 insertions(+), 11 deletions(-) create mode 100644 docs/video/visuals/13-why-pi.html create mode 100644 docs/video/visuals/14-pi-capabilities.html create mode 100644 docs/video/visuals/15-how-to-get-started.html create mode 100644 docs/video/visuals/16-real-work-playbook.html create mode 100644 docs/video/visuals/17-sage-companion.html diff --git a/docs/video/visuals/08-waves-lanes-worktrees.html b/docs/video/visuals/08-waves-lanes-worktrees.html index 83dd5baa..0e31b102 100644 --- a/docs/video/visuals/08-waves-lanes-worktrees.html +++ b/docs/video/visuals/08-waves-lanes-worktrees.html @@ -166,10 +166,6 @@ border-radius: 3px; font-size: var(--fs-sm); } - /* Let the subtitle span the full frame width instead of the shared 820px cap. */ - .subtitle { - max-width: 100%; - } diff --git a/docs/video/visuals/12-dashboard-visibility.html b/docs/video/visuals/12-dashboard-visibility.html index 08947307..7e07e878 100644 --- a/docs/video/visuals/12-dashboard-visibility.html +++ b/docs/video/visuals/12-dashboard-visibility.html @@ -197,10 +197,6 @@ color: var(--text-dim); } .footer .hl { color: var(--green); } - /* Let the subtitle span the full frame width instead of the shared 820px cap. */ - .subtitle { - max-width: 100%; - } @@ -210,7 +206,7 @@

Why a web dashboard, not a CLI

diff --git a/docs/video/visuals/13-why-pi.html b/docs/video/visuals/13-why-pi.html new file mode 100644 index 00000000..19fed426 --- /dev/null +++ b/docs/video/visuals/13-why-pi.html @@ -0,0 +1,142 @@ + + + + +V13 — Why pi + + + + +
+
+ 13 · The foundation + +
+

Why pi?

+

Taskplane runs on top of pi. Three properties made it the obvious foundation — the same three properties that let other projects (like OpenClaw) build very different agents on the same base.

+ +
+
+
01 · what won me over
+
Truly extensible
+
Build whatever you want on top of pi. The runtime that powers Taskplane is just one possible build.
+
pi is extension-first. Extensions register commands, tools, and behaviors. Nothing is hardcoded that you can't replace. The same architecture that lets OpenClaw layer its own agent on top is what lets Taskplane add an entire orchestration engine — without forking pi.
+
+ For Taskplane + /orch* commands, the review_step + wait_for_review tools, mailbox handlers, agent spawning — all live in extensions/taskplane/*. Upgrades flow through pi update with zero rewrites. +
+
+ +
+
02 · the deal-maker
+
Model agnostic
+
Anthropic, OpenAI, Bedrock, Vertex, Gemini, local Ollama — pi treats them the same. Swap any agent's model with a string.
+
Provider abstraction is built in. Models are configured per agent as provider/model-name strings. No SDK glue code, no routing layer, no fork-per-vendor. Per agent, per task, per command — different models can light up the same execution path.
+
+ For Taskplane + Cross-model reviews are non-negotiable. Worker on Opus, reviewer on GPT, merger on a third. Without pi's abstraction this means writing three SDK adapters and an in-house routing layer — and maintaining it. +
+
+ +
+
03 · the ethos match
+
Open source
+
MIT-licensed. The whole stack is inspectable. The only cost is your token bill.
+
No SaaS layer. No per-seat fees. No enterprise tier behind a paywall. You bring your own keys, your own machine, your own data. The full source for the agent runtime is right there if you want to read it, fork it, or patch it.
+
+ For Taskplane + Taskplane is also open source. The two together cost users nothing beyond tokens. A closed harness on top of an open agent framework would have defeated the point — pi shares the ethos. +
+
+
+ +
+ extensible  +  model-agnostic  +  open  ·  the right foundation for what Taskplane needed +
+
+ + diff --git a/docs/video/visuals/14-pi-capabilities.html b/docs/video/visuals/14-pi-capabilities.html new file mode 100644 index 00000000..3fa3dd6b --- /dev/null +++ b/docs/video/visuals/14-pi-capabilities.html @@ -0,0 +1,152 @@ + + + + +V14 — Pi capabilities + + + + +
+
+ 14 · The engineering surface + +
+

What pi actually gives you

+

Beyond the three big reasons in V13, here's the concrete engineering surface Taskplane builds on. Each of these is a primitive that another agent project could use just as easily.

+ +
+
+
runtime
+
Local-first execution
+
Runs in your terminal. Your keys, your machine, your filesystem. No cloud service, no telemetry pipeline, no shared backplane. The entire agent loop is observable from your own disk and your own process tree.
+
# install once, run anywhere
pi install npm:taskplane
+
+ +
+
capability packaging
+
Skills as folders
+
A "skill" is a folder with a SKILL.md manifest plus any supporting files the agent needs. pi auto-discovers them and exposes them via natural-language triggers. Taskplane's create-taskplane-task skill is one of these — totally portable.
+
# skill = folder + manifest
skills/create-taskplane-task/
  SKILL.md
+
+ +
+
extensibility
+
Custom tool registration
+
Extensions declare tools. Agents call them the same way they call read or write. Taskplane registers review_step, wait_for_review, send_agent_message, broadcast_message, and the entire orch_* family this way.
+
registerTool(
  'review_step',
  reviewStepHandler
)
+
+ +
+
control plane
+
RPC steering
+
The steer RPC injects a user-turn message into a running agent's context without killing the session. This is the primitive Taskplane's mailbox layers on top of — and what makes mid-flight course-correction possible at all.
+
# inject mid-conversation
rpc.steer(session, msg)
+
+ +
+
process model
+
Direct child processes
+
Agents run as ordinary OS subprocesses of pi. No tmux dependency, no daemon, no message broker. A process registry tracks PIDs and liveness. Worker threads keep the engine non-blocking. Standard OS primitives all the way down.
+
processRegistry
  .spawn(agent, opts)
  .track(pid)
+
+ +
+
configurability
+
Composable agent prompts
+
Every agent role is a markdown file with frontmatter — model, tools, standalone flag. Project-specific guidance composes on top of the base prompts shipped by extensions. Versionable, diff-able, reviewable.
+
# composes with base
.pi/agents/
  task-worker.md
+
+
+ +
+ For Taskplane + Every primitive on this page maps to something concrete in the orchestration system. Skills give you the task-creation entry point. Custom tools give you reviews. RPC steering gives you the mailbox. Subprocess agents give you parallel lanes. Composable prompts give you the supervisor / worker / reviewer / merger quartet without forking a thing. +
+
+ + diff --git a/docs/video/visuals/15-how-to-get-started.html b/docs/video/visuals/15-how-to-get-started.html new file mode 100644 index 00000000..c073f3f6 --- /dev/null +++ b/docs/video/visuals/15-how-to-get-started.html @@ -0,0 +1,211 @@ + + + + +V15 — Getting started: install and test + + + + +
+
+ 15 · Your first batch + +
+

Getting started: install and test

+

Nine steps from zero to a running orchestrated batch. Everything is local — your machine, your keys, your filesystem. The only ongoing cost is your model token bill.

+ +
+
+
+
01 · install
+
shell
+
+
Get Node and pi
+
Install Node (LTS or newer) however you prefer — mise, nvm, or the official installer — then install pi globally from npm. pi is the agent runtime that hosts Taskplane.
+
# Node first (any installer)
$ npm install -g @earendil-works/pi-coding-agent
+
+ +
+
+
02 · configure
+
in pi
+
+
Add a model provider
+
Launch pi and configure at least one provider (two is better) — Anthropic, OpenAI, Bedrock, Vertex, Gemini, or local Ollama. pi will prompt you for keys and save them to your user profile.
+
$ pi
/providers # add at least one, two if possible
+
+ +
+
+
03 · install
+
shell
+
+
Install Taskplane
+
Install Taskplane globally so pi can discover it as an extension. From this point on, every pi session in any project has access to /orch and the supervisor agent.
+
$ npm install -g taskplane
+
+ +
+
+
04 · project
+
shell
+
+
Make a fresh repo
+
Taskplane needs a git repository — lanes commit to branches and worktrees, so git history is the substrate. An empty new repo is the simplest starting point.
+
$ mkdir my-first-batch
$ cd my-first-batch
$ git init
+
+ +
+
+
05 · scaffold
+
shell
+
+
Initialize Taskplane
+
Drops project scaffolding: a .pi/ directory with config, the supervisor agent prompt, a sample task area, and a starter batch you can run end-to-end without writing a single task by hand.
+
$ taskplane init
+
+ +
+
+
06 · verify
+
shell
+
+
Run doctor
+
Sanity checks: pi version, Node version, Taskplane install path, providers configured, git repo health, scaffolded files present. Fix anything red before you launch a batch.
+
$ taskplane doctor
+
+ +
+
+
07 · review
+
in pi
+
+
Set a reviewer model
+
Cross-model review is Taskplane's quality gate. Pick a provider/model different from your worker (e.g. worker on Claude, reviewer on GPT). If you only have one provider, skip — you can revisit anytime.
+
$ pi
/taskplane-settings
+
+ +
+
+
08 · run
+
in pi
+
+
Launch the sample batch
+
From inside pi, kick off every task in the sample area. Taskplane discovers the DAG, plans waves, spawns lanes in parallel worktrees, runs reviews, and merges wave by wave — all autonomously.
+
/orch all
+
+ +
+
+
09 · watch
+
shell
+
+
Open the dashboard
+
In a second terminal, launch the live dashboard. Read-only view over disk: lane progress, merge agents, supervisor events, mailbox traffic. Refreshes via SSE. Cannot lie, cannot decide.
+
# new terminal, same repo
$ taskplane dashboard
+
+
+ +
+ + diff --git a/docs/video/visuals/16-real-work-playbook.html b/docs/video/visuals/16-real-work-playbook.html new file mode 100644 index 00000000..74cf0c9a --- /dev/null +++ b/docs/video/visuals/16-real-work-playbook.html @@ -0,0 +1,285 @@ + + + + +V16 — How to get started on real work + + + + +
+
+ 16 · Real work + +
+

How to get started on real work

+

Page 15 was the sample batch. Here's the playbook for your own project — where the planning matters more than the running, and the 30 minutes you spend up front decides whether the 8-hour batch produces code you'll keep.

+ +
+ +
+
+
01 · spec
+
in LLM chat
+
+
Start with a spec
+
Bring rough ideas. Walk out with structured docs.
+
Modern LLMs are excellent at turning handwavy intent into clear specifications tailored for AI coding agents. Keep specs atomic: one concern per document, organized so an agent can pull only what it needs for the task at hand — not the whole corpus on every prompt.
+
# in your favorite chat UI
"Turn these notes into spec docs for an AI coding agent."
+
+ + +
+
+
02 · review
+
different LLM
+
+
Cross-review the spec
+
A different model finds different issues. It always finds issues.
+
Hand the draft to a different LLM — if Claude wrote it, ask GPT to critique, or vice versa. Have it flag gaps, ambiguities, contradictions, and missing context. Apply its corrections. Then read it yourself; you'll catch what both models missed. Thirty minutes here saves an 8-hour batch from going sideways.
+
"Review this spec for gaps, contradictions,
and assumptions an AI coding agent would miss."
+
+ + +
+
+
03 · context
+
editor
+
+
Add supporting docs
+
Spec is "what to build". These are "how we build here".
+
Around the spec, write the project-context docs every agent will reach for. Keep each focused; agents read selectively when files are well-named and single-purpose.
+
+ tech-stack.md + coding-standards.md + architecture/ADRs + project-structure.md + test-strategy.md + glossary.md +
+
+ + +
+
+
04 · north star
+
editor
+
+
Write AGENTS.md
+
The first file every agent reads.
+
A single top-level AGENTS.md orients any agent that lands in the repo: what the project is, where major areas live, links to the docs above (relative paths!), and a "what NOT to do" section. If an agent only has time to read one file, this is it. Treat it as living documentation — update it whenever conventions shift.
+
# top of repo, alongside README.md
AGENTS.md · purpose, layout, rules, links
+
+ + +
+
★ The critical step
+
+
05 · tasks
+
in pi
+
+
Turn the spec into task packets
+
This is the step that decides whether your batch produces quality code.
+
Use the create-taskplane-task skill. It scaffolds one folder per task, each with PROMPT.md (the contract) and STATUS.md (the agent's persistent memory). The number of packets follows the spec's complexity — smaller, atomic tasks are easier to scope, review, and merge than big-bang ones. Read every generated PROMPT.md and tighten it. This is your last write-time investment before tokens get spent on code.
+
$ pi
"Create taskplane tasks from the spec in docs/spec/"
+
+ + +
+
+
06 · preview
+
in pi
+
+
Preview with /orch-plan
+
See the staging before you spend a single token on code.
+
Runs discovery and the wave planner without spawning workers. Prints the wave structure, lane assignment, dependency graph, and (for polyrepo) segment groupings. Catch ordering mistakes, lane skew, and packet-size surprises here — before they cost you the batch.
+
/orch-plan all
+
+
+ +
+ A clear, well-scoped PROMPT.md is the difference between an agent that delivers and one that drifts. Time spent here compounds across every lane in every wave. +
+
+ + diff --git a/docs/video/visuals/17-sage-companion.html b/docs/video/visuals/17-sage-companion.html new file mode 100644 index 00000000..c970725a --- /dev/null +++ b/docs/video/visuals/17-sage-companion.html @@ -0,0 +1,286 @@ + + + + +V17 — Sage: the post-batch quality gate + + + + +
+
+ 17 · The companion + +
+

Sage — the post-batch quality gate

+

Sage is a separate pi extension from Taskplane — but the two pair so well I treat them as one workflow. Per-step reviews catch problems inside a task. Sage catches problems across tasks. Every batch I ship gets a Sage pass before I merge.

+ +
+ +
+
+
01 · concept
+
advisory
+
+
A high-reasoning second opinion
+
Ad-hoc and agentic cross-model review.
+
Sage is an isolated subagent: a separate pi process running a different model, with its own context, its own tool profile, and a strict advisory mandate. It analyses and recommends — it never edits files or runs your code. You can ask for it conversationally, and pi can also decide on its own that a question warrants a second opinion.
+
# separate extension from Taskplane
pi-sage · github.com/…/pi-sage
+
+ + +
+
+
02 · install
+
shell + in pi
+
+
Install and pick a different model
+
The whole point is a model that isn't your primary.
+
One global install, then configure once. In /sage-settings, choose a model from a provider you don't use for your primary pi session — that's where the cross-model value comes from. Different family, different blind spots, different second opinion.
+
$ pi install npm:pi-sage
# then, inside pi:
/sage-settings
+
+ + +
+
+
03 · invoke
+
in pi
+
+
Two ways to summon Sage
+
Ask out loud, or let pi decide.
+
Conversational: just say "use Sage" or "get a second opinion." No slash command exists — natural language is the interface. Autonomous: pi will reach for Sage on its own when the situation warrants it.
+
+ ambiguous root-cause + risky architecture trade-off + conflicting evidence + high-impact refactor +
+
"Use Sage to check this approach."
+
+ + +
+
★ Why Taskplane users care
+
+
04 · taskplane use case
+
after every batch
+
+
Run Sage on the whole batch when it's done
+
Cross-task consistency is something per-step review simply can't see.
+
+
+ Taskplane's built-in reviewer agent reviews each step of each task as the worker writes it. That gate is excellent at what it does — catching defects, missing tests, drift from the prompt — but it sees one step at a time, in isolation. +

+ After the batch lands, a different question matters: does the whole thing hang together? Are interfaces consistent across tasks? Did lane 2's refactor leave lane 5's call site broken? Did the same concern get solved three different ways in three different lanes? Is the testing strategy coherent end-to-end? +

+ That's the gap Sage fills. Point it at the merged diff between your working branch and the orch branch (or the integration commit), and ask for a full code review. It's the quality gate I run on every Taskplane batch before I push. +
+
+
Per-step reviews verify steps.
Sage verifies the whole.
+ Typical invocation +
"Use Sage to review the diff between
develop and the orch branch."
+
+
+
+
+ +
+ Taskplane runs the batch.  Sage reviews it.  ·  separate extensions, one workflow +
+
+ + diff --git a/docs/video/visuals/_shared.css b/docs/video/visuals/_shared.css index 368a08b0..b4de4a41 100644 --- a/docs/video/visuals/_shared.css +++ b/docs/video/visuals/_shared.css @@ -199,6 +199,7 @@ h1 { color: var(--text-dim); font-size: var(--fs-subtitle); margin-bottom: var(--subtitle-mb); - max-width: calc(820px * var(--scale)); + /* Subtitle spans the full frame width — no soft cap. */ + max-width: 100%; line-height: 1.55; } diff --git a/docs/video/visuals/index.html b/docs/video/visuals/index.html index 0f222d52..c2606d43 100644 --- a/docs/video/visuals/index.html +++ b/docs/video/visuals/index.html @@ -34,6 +34,11 @@ a.card.c10 { color: var(--amber); } a.card.c11 { color: var(--blue); } a.card.c12 { color: var(--purple); } + a.card.c13 { color: var(--green); } + a.card.c14 { color: var(--amber); } + a.card.c15 { color: var(--blue); } + a.card.c16 { color: var(--purple); } + a.card.c17 { color: var(--pink); } .num { font-family: var(--mono); font-size: var(--fs-xs); @@ -82,7 +87,7 @@
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.

+

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

@@ -145,6 +150,31 @@

Visual Overview

Dashboard visibility map
A view over disk. Read-only. Cannot lie. Cannot decide.
 + +
13
+
Why pi?
+
Three reasons pi is the right foundation: extensible, model-agnostic, open source.
+ + +
14
+
Pi capabilities
+
Engineering surface Taskplane builds on: skills, tools, RPC steering, subprocess agents.
+ + +
15
+
Getting started: install and test
+
Nine steps from zero to a running batch: install pi + Taskplane, init, doctor, /orch all, dashboard.
+ + +
16
+
Real-work playbook
+
Spec → cross-LLM review → supporting docs → AGENTS.md → task packets → /orch-plan. The 30 minutes that decide your batch.
+ + +
17
+
Sage — the companion
+
Ad-hoc and agentic cross-model second opinions. The post-batch quality gate per-step reviews can't deliver.
+