1 +#
Ultra Planned Work Visibility Implementation Plan 3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Show all workflow phases immediately and keep queued, pending, conditional, running, done, dropped, and skipped states accurate throughout execution.
7 +**Architecture:** Extend Ultra's progress stream with workflow-plan and phase-transition events while retaining existing agent events. The reducer owns planned phase records and queued agent rows; both UI surfaces render one ordered ledger from that state.
9 +**Tech Stack:** TypeScript, TypeBox, Pi TUI, Vitest, Mise
13 +**Phase:** Single-plan implementation
17 +##
Task 1: Add Planned Progress State 21 +- Modify: `extensions/ultra/__tests__/progress.test.ts`
22 +- Modify: `extensions/ultra/progress.ts`
24 +- [ ] **Step 1: Write failing reducer tests**
28 +- a `plan` event seeds every phase in specification order;
29 +- known agent ids become `queued` rows;
30 +- `agents-pending` and `condition-pending` phases create no fake agent rows;
31 +- a `phase` event replaces a pending phase with exact queued agent ids;
32 +- a skipped phase removes provisional rows;
33 +- agent `start` changes queued to running;
34 +- all counts derive from current rows and phase statuses.
36 +Use this event shape:
39 +const plan
: UltraProgressEvent = {
42 + { phase:
"research", status:
"resolved", agentIds: [
"research#0"] },
43 + { phase:
"verify", status:
"agents-pending", agentIds: [] },
44 + { phase:
"publish", status:
"condition-pending", agentIds: [] },
49 +Expected seeded state:
52 +expect(state.
rows).
toEqual([
53 + expect.
objectContaining({ agentId:
"research#0", status:
"queued" }),
55 +expect(state).
toMatchObject({
64 +- [ ] **Step 2: Run progress tests and verify RED**
69 +mise run test -- extensions/ultra/__tests__/progress.test.ts
72 +Expected: TypeScript/runtime failures because plan events, planned phase records, queued status, and new counts do not exist.
74 +- [ ] **Step 3: Implement the progress model**
76 +Split the event contract into this union:
79 +export type AgentProgressKind = "start" | "action" | "delta" | "end";
81 +export interface AgentProgressEvent {
84 + kind
: AgentProgressKind;
86 + toolCallId
?: string;
94 + thinkingLevel
?: ThinkingLevel;
97 + controls
?: AgentControls;
100 +export type PhasePlanStatus = 103 + | "condition-pending" 107 +export interface PlannedPhase {
109 + status
: PhasePlanStatus;
110 + agentIds
: readonly string[];
113 +export type UltraProgressEvent = 114 + | AgentProgressEvent 115 + | { kind
: "plan"; phases
: readonly PlannedPhase[] }
116 + | ({ kind
: "phase" }
& PlannedPhase);
119 +Extend `AgentStatus` with `queued`.
120 +Replace `ReducerState.phases: readonly string[]` with `readonly PlannedPhase[]`.
121 +Add `queued`, `running`, and `later` numeric fields.
123 +Handle `plan` before agent logic by cloning phase records and seeding one queued row per `agentId`.
124 +Handle `phase` by replacing the matching phase, retaining matching agent rows, adding missing queued rows, and removing rows no longer planned for that phase.
125 +Keep agent-event fallback behavior by creating a resolved phase record when an agent event arrives without a prior plan.
126 +Recompute all six counts after every event.
127 +Only phase events update `state.phase`; initial plan seeding must not select the final phase.
129 +Update `mapSessionEvent()` to return `AgentProgressEvent | null`.
130 +Guard transcript and row helpers so they accept only agent events.
132 +- [ ] **Step 4: Run progress tests and verify GREEN**
134 +Run the Task 1 test command again.
135 +Expected: all progress tests pass.
137 +##
Task 2: Emit Plans And Exact Phase Transitions 141 +- Modify: `extensions/ultra/__tests__/engine.test.ts`
142 +- Modify: `extensions/ultra/engine.ts`
144 +- [ ] **Step 1: Write failing engine tests**
146 +Add one test with unconditional single, literal fan-out, dynamic fan-out, and conditional phases.
147 +Capture `onProgress` and assert the first event is:
153 + { phase:
"one", status:
"resolved", agentIds: [
"one#0"] },
154 + { phase:
"literal", status:
"resolved", agentIds: [
"literal#0",
"literal#1"] },
155 + { phase:
"dynamic", status:
"agents-pending", agentIds: [] },
156 + { phase:
"conditional", status:
"condition-pending", agentIds: [] },
161 +Add assertions that:
163 +- each enabled phase emits `resolved` before its first agent `start`;
164 +- false `when` emits `skipped` and no agent starts;
165 +- every settled phase emits `done`;
166 +- empty fan-out emits resolved/done with no agent ids;
167 +- cancellation emits dropped ends for every resolved but unlaunched agent.
169 +- [ ] **Step 2: Run engine tests and verify RED**
174 +mise run test -- extensions/ultra/__tests__/engine.test.ts
177 +Expected: failures because the engine emits only agent events.
179 +- [ ] **Step 3: Implement planning emissions**
181 +Add a pure initial planner:
184 +function planPhases(spec
: WorkflowSpec)
: PlannedPhase[] {
185 + return spec.phases.
map((phase)
=> {
186 + if (phase.when
!== undefined) {
187 + return { phase: phase.
id, status:
"condition-pending", agentIds: [] };
189 + if (phase.kind
=== "single") {
192 + status:
"resolved",
193 + agentIds: [
`${phase.id}#0`],
196 + if (
Array.
isArray(phase.over)) {
199 + status:
"resolved",
200 + agentIds: phase.over.
map((_, index)
=> `${phase.id}#${index}`),
203 + return { phase: phase.
id, status:
"agents-pending", agentIds: [] };
208 +Emit `{ kind: "plan", phases: planPhases(spec) }` before entering the phase loop.
209 +Emit `skipped` immediately when `when` resolves false.
210 +After `phaseItems()` resolves, emit `resolved` with exact ids before calling `mapWithConcurrency()`.
211 +During slot normalization, emit dropped end events with text `aborted` for `isAborted(slot)` entries.
212 +Emit phase `done` after storing phase results.
214 +Update `makeForwarder()` to wrap controls only when `event.kind` is an agent kind and controls exist.
215 +Do not alter result counts, interpolation, or journal behavior.
217 +- [ ] **Step 4: Run engine tests and verify GREEN**
219 +Run the Task 2 test command again.
220 +Expected: all engine tests pass.
222 +##
Task 3: Render The Icon-Led Ledger 226 +- Modify: `extensions/ultra/__tests__/ui.test.ts`
227 +- Modify: `extensions/ultra/ui.ts`
229 +- [ ] **Step 1: Write failing tool and overlay tests**
231 +Add tests for the accepted visual vocabulary:
234 +expect(output).
toContain(
"");
235 +expect(output).
toContain(
"");
236 +expect(output).
toContain(
"");
237 +expect(output).
toContain(
"");
238 +expect(output).
toContain(
"");
239 +expect(output).
toContain(
"");
242 +Also assert textual labels remain present.
243 +Verify expanded rows follow specification phase order, pending/skipped placeholders are visible, collapsed output contains counts but no ids/actions, and overlay focus navigation skips phase placeholders.
245 +- [ ] **Step 2: Run UI tests and verify RED**
250 +mise run test -- extensions/ultra/__tests__/ui.test.ts
253 +Expected: failures because only running/done/dropped agent rows render.
255 +- [ ] **Step 3: Implement ordered display rows and icons**
257 +Use verified glyph constants:
260 +const STATUS_ICON
: Record<
AgentStatus,
string>
= {
267 +const PHASE_ICON
= {
268 + "agents-pending":
"",
269 + "condition-pending":
"",
274 +Build a pure ordered display list from `state.phases`:
276 +- pending and skipped phases contribute one non-agent display row;
277 +- resolved/done phases contribute their agent rows;
278 +- done phases with no agents contribute `done · no agents`;
279 +- orphan fallback agent rows append last.
281 +Render labels and explanations exactly:
283 +- `agents not planned yet` / `earlier results determine which agents are needed`;
284 +- `conditional` / `earlier results determine whether this phase runs`;
286 +- queued current-phase agents: `waiting for concurrency slot`;
287 +- queued later agents: `starts when phase begins`.
289 +Change `phaseCounter()` to read planned phase records.
290 +Extend `summaryLine()` with active, queued, and later counts while keeping done/dropped counts.
292 +Use the ordered display list in tool and overlay renderers.
293 +Overlay focus remains indexed by `state.rows`, and only matching agent display rows receive the focus marker.
294 +Plan and phase events trigger rendering; phase/end events bypass throttling.
296 +Harden `asReducerState()` so old `phases: string[]` details fall back to an empty board.
298 +- [ ] **Step 4: Run UI tests and verify GREEN**
300 +Run the Task 3 test command again.
301 +Expected: all UI tests pass.
303 +##
Task 4: Wire Serializable Plan Events 307 +- Modify: `extensions/ultra/__tests__/wire.test.ts`
308 +- Modify: `extensions/ultra/__tests__/harness.test.ts`
309 +- Modify: `extensions/ultra/wire.ts`
310 +- Modify: `extensions/ultra/README.md`
312 +- [ ] **Step 1: Write failing sink and harness tests**
314 +Update sink tests to send a plan event first and assert the first `onUpdate.details` already contains every phase and known queued agent.
315 +Update harness expectations so the expanded workflow tool result contains queued or planning rows before completion.
317 +- [ ] **Step 2: Run wire and harness tests and verify RED**
322 +mise run test -- extensions/ultra/__tests__/wire.test.ts extensions/ultra/__tests__/harness.test.ts
325 +Expected: failures because the sink assumes every event has controls and the old summary lacks planned counts.
327 +- [ ] **Step 3: Update sink serialization and docs**
329 +In `makeToolProgressSink()`, strip controls only from agent events:
332 +const safe
= "agentId" in event ? {
...event, controls:
undefined }
: event;
333 +state
= reduceProgress(state, safe);
336 +Update `summarize()` with done, active, queued, later, and dropped counts.
337 +Document planned ledger states and icon labels in `README.md`.
339 +- [ ] **Step 4: Run wire and harness tests and verify GREEN**
341 +Run the Task 4 test command again.
342 +Expected: both files pass.
344 +##
Task 5: Verify And Commit 348 +- Verify: `extensions/ultra/**`
350 +- [ ] **Step 1: Run focused verification**
353 +mise run test -- extensions/ultra
358 +Expected: all Ultra tests, formatting, lint, typecheck, skill checks, and static extension checks pass.
360 +- [ ] **Step 2: Inspect scope**
363 +git diff --check -- extensions/ultra
364 +git diff --stat -- extensions/ultra
367 +Expected: no whitespace errors and no files outside `extensions/ultra` in the implementation diff.
369 +- [ ] **Step 3: Commit implementation**
372 +git add extensions/ultra
373 +git commit -m "feat(ultra): show planned workflow agents"
376 +Preserve all unrelated dirty work.