plan-progress

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Plan, Status, Step, Task } from '../types'
5
6const PANE = 'plan-progress'
7const TOOL = 'mcp__plan-progress__plan'
8const PLAN_TOOL = 'mcp__ccd_turn__update_plan'
9const WRAP_TOOL = 'mcp__ccd_turn__wrap_up'
10
11const EMPTY: Plan = { title: '', steps: [] }
12
13const plan = atom({ plugin: 'plan-progress', key: 'plan' } as const, EMPTY)
14const turn = atom({ plugin: 'plan-progress', key: 'turn' } as const, [])
15const open = atom({ plugin: 'plan-progress', key: 'open' } as const, {})
16const isDismissed = atom({ plugin: 'plan-progress', key: 'isDismissed' } as const, false)
17const isBriefed = atom({ plugin: 'plan-progress', key: 'isBriefed' } as const, false)
18
19const MARK: Record<Status, { glyph: string; color: string }> = {
20  pending: { glyph: '○', color: 'inactive' },
21  active: { glyph: '●', color: 'claude' },
22  done: { glyph: '✓', color: 'success' },
23  blocked: { glyph: '!', color: 'warning' },
24}
25
26// Bar fills: the master plan's in green, every step, task and turn bar in blue.
27const MASTER_FILL = 'success'
28const PART_FILL = 'suggestion'
29
30const BOX: Record<Status, string> ={ pending: ' ', active: '~', done: 'x', blocked: '!' }
31
32// ---------- model ----------
33
34function toStatus(raw: unknown): Status {
35  if (raw === 'completed' || raw === 'done') return 'done'
36  if (raw === 'in_progress' || raw === 'active') return 'active'
37  if (raw === 'blocked') return 'blocked'
38  return 'pending'
39}
40
41function clamp(raw: number): number {
42  return Math.round(Math.min(100, Math.max(0, raw)))
43}
44
45/** Progress belongs to an item in progress; any other status carries none. */
46function setStatus<T extends Task>(item: T, status: Status): T {
47  const { progress, ...rest } = item
48  return (status === 'active' && progress !== undefined ? { ...rest, status, progress } : { ...rest, status }) as T
49}
50
51/** A reported 0-100: full marks the item done, anything less puts it in progress. */
52function setProgress<T extends Task>(item: T, raw: number): T {
53  if (!Number.isFinite(raw)) return item
54  const progress = clamp(raw)
55  return progress === 100 ? setStatus(item, 'done') : { ...item, status: 'active', progress }
56}
57
58/** A step with tasks follows them: all done is done, any started is in progress. Blocked stays. */
59function settle(step: Step): Step {
60  if (step.status === 'blocked' || step.tasks.length === 0) return step
61  if (step.tasks.every(t => t.status === 'done')) return setStatus(step, 'done')
62  if (step.tasks.some(t => t.status !== 'pending')) return setStatus(step, 'active')
63  return step
64}
65
66function share(item: Task): number {
67  if (item.status === 'done') return 1
68  return item.status === 'active' ? (item.progress ?? 0) / 100 : 0
69}
70
71function stepShare(step: Step): number {
72  if (step.status === 'done' || step.tasks.length === 0) return share(step)
73  return step.tasks.reduce((sum, t) => sum + share(t), 0) / step.tasks.length
74}
75
76/** Steps weigh by their task count, so a ten-task step counts more than a one-line one. */
77function overall(p: Plan): number {
78  const weight = (s: Step) => Math.max(1, s.tasks.length)
79  const total = p.steps.reduce((sum, s) => sum + weight(s), 0)
80  return total === 0 ? 0 : p.steps.reduce((sum, s) => sum + stepShare(s) * weight(s), 0) / total
81}
82
83function pct(fraction: number): number {
84  return Math.round(fraction * 100)
85}
86
87function bar(fraction: number, width: number): [string, string] {
88  const filled = Math.round(Math.min(1, Math.max(0, fraction)) * width)
89  return ['━'.repeat(filled), '━'.repeat(width - filled)]
90}
91
92type RawTask = { text?: unknown; status?: unknown; progress?: unknown }
93type RawStep = RawTask & { note?: unknown; tasks?: unknown }
94
95function mintTask(raw: RawTask): Task | undefined {
96  if (typeof raw?.text !== 'string' || raw.text.trim() === '') return undefined
97  const task: Task = { id: crypto.randomUUID(), text: raw.text.trim(), status: toStatus(raw.status) }
98  return typeof raw.progress === 'number' ? setProgress(task, raw.progress) : task
99}
100
101function mintStep(raw: RawStep): Step | undefined {
102  const head = mintTask(raw)
103  if (head === undefined) return undefined
104  const tasks = (Array.isArray(raw.tasks) ? (raw.tasks as RawTask[]) : [])
105    .map(mintTask)
106    .filter((t): t is Task => t !== undefined)
107  const note = typeof raw.note === 'string' && raw.note.trim() ? raw.note.trim() : undefined
108  return { ...head, tasks, ...(note ? { note } : {}) }
109}
110
111type Update = { step?: unknown; task?: unknown; status?: unknown; progress?: unknown; note?: unknown; text?: unknown }
112
113function applyUpdate<T extends Task & { note?: string }>(item: T, u: Update): T {
114  let next = item
115  if (typeof u.text === 'string' && u.text.trim()) next = { ...next, text: u.text.trim() }
116  if (u.status !== undefined) next = setStatus(next, toStatus(u.status))
117  if (typeof u.progress === 'number') next = setProgress(next, u.progress)
118  if (typeof u.note === 'string') {
119    const { note: _drop, ...rest } = next
120    next = (u.note.trim() ? { ...rest, note: u.note.trim() } : rest) as T
121  }
122  return next
123}
124
125function applyUpdates(p: Plan, updates: Update[]): Plan {
126  const steps = [...p.steps]
127  for (const u of updates) {
128    const at = typeof u?.step === 'number' ? u.step - 1 : -1
129    const step = steps[at]
130    if (step === undefined) continue
131    if (typeof u.task === 'number') {
132      const ti = u.task - 1
133      if (step.tasks[ti] === undefined) continue
134      const tasks = step.tasks.map((one, i) => (i === ti ? applyUpdate(one, u) : one))
135      steps[at] = settle({ ...step, tasks })
136    } else {
137      steps[at] = applyUpdate(step, u)
138    }
139  }
140  return { ...p, steps }
141}
142
143function summary(p: Plan): string {
144  if (p.steps.length === 0) return 'The plan is empty.'
145  const lines = [`Plan${p.title ? `: ${p.title}` : ''} (${pct(overall(p))}% done)`]
146  p.steps.forEach((s, i) => {
147    const count = s.tasks.length ? ` (${s.tasks.filter(t => t.status === 'done').length}/${s.tasks.length})` : ''
148    lines.push(`${i + 1}. [${BOX[s.status]}] ${s.text} ${pct(stepShare(s))}%${count}${s.note ? ` — ${s.note}` : ''}`)
149    s.tasks.forEach((t, j) => {
150      const progress = t.status === 'active' && t.progress !== undefined ? ` (${t.progress}%)` : ''
151      lines.push(`   ${j + 1}. [${BOX[t.status]}] ${t.text}${progress}`)
152    })
153  })
154  return lines.join('\n')
155}
156
157function age(iso: string | undefined): string {
158  const then = iso ? Date.parse(iso) : NaN
159  if (!Number.isFinite(then)) return ''
160  const mins = Math.max(0, Math.round((Date.now() - then) / 60000))
161  if (mins < 1) return 'updated just now'
162  if (mins < 60) return `updated ${mins}m ago`
163  if (mins < 60 * 24) return `updated ${Math.round(mins / 60)}h ago`
164  return `updated ${Math.round(mins / 60 / 24)}d ago`
165}
166
167type Now = { step: Step; task?: Task; fraction?: number; done?: number; total?: number }
168
169/**
170 * The plan as drawn: the item in progress with no reported progress takes the
171 * share of the agent's turn list that is done. Stored data stays as reported.
172 * shortcut: assumes the turn list is about the task in progress, upgrade if the agent names the task it works on
173 */
174function live(p: Plan, turnList: Task[]): { view: Plan; now?: Now } {
175  const at = p.steps.findIndex(s => s.status === 'active')
176  const step = p.steps[at]
177  if (step === undefined) return { view: p }
178  const done = turnList.filter(t => t.status === 'done').length
179  const total = turnList.length
180  const fromTurn = total > 0 ? Math.min(99, Math.round((done / total) * 100)) : undefined
181  const fill = <T extends Task>(item: T): T =>
182    item.progress === undefined && fromTurn !== undefined ? { ...item, progress: fromTurn } : item
183  const ti = step.tasks.findIndex(t => t.status === 'active')
184  const task = step.tasks[ti]
185  const nextStep: Step =
186    task !== undefined
187      ? { ...step, tasks: step.tasks.map((t, i) => (i === ti ? fill(t) : t)) }
188      : step.tasks.length === 0
189        ? fill(step)
190        : step
191  const view = { ...p, steps: p.steps.map((s, i) => (i === at ? nextStep : s)) }
192  const item = task !== undefined ? nextStep.tasks[ti] : step.tasks.length === 0 ? nextStep : undefined
193  const fraction = item?.progress !== undefined ? item.progress / 100 : undefined
194  return {
195    view,
196    now: { step: nextStep, task: task !== undefined ? nextStep.tasks[ti] : undefined, fraction, ...(total ? { done, total } : {}) },
197  }
198}
199
200// ---------- engine ----------
201
202/** shortcut: one plan per project root, upgrade to named plans if a repo needs two at once */
203async function storeKey($: EngineInterface): Promise<string> {
204  return `plan:${await $.session.root()}`
205}
206
207async function paintStatus($: EngineInterface, stored: Plan) {
208  const { view, now } = live(stored, await read($, turn))
209  const where = now ? (now.task ?? now.step).text.slice(0, 40) : ''
210  const part = now?.fraction !== undefined ? ` ${pct(now.fraction)}%` : ''
211  $.ui.status(view.steps.length === 0 ? undefined : `Plan ${pct(overall(view))}%${where ? ` · ${where}${part}` : ''}`)
212}
213
214async function setPlan($: EngineInterface, change: (prev: Plan) => Plan) {
215  const prev = await read($, plan)
216  const next = { ...change(prev), updatedAt: new Date().toISOString() }
217  await update($, plan, () => next)
218  if (next.steps.length === 0) await $.store.delete(await storeKey($))
219  else await $.store.set(await storeKey($), next)
220  await paintStatus($, next)
221  if (prev.steps.length === 0 && next.steps.length > 0 && !(await read($, isDismissed))) {
222    $.ui.open({ id: PANE, title: 'Plan' }).catch(() => undefined)
223  }
224}
225
226function withStatus(items: Task[], at: number, status: Status): Task[] {
227  return items.map((item, i) => (i === at ? setStatus(item, status) : item))
228}
229
230/** The desktop app's advance / done / start steps, applied to the turn list. */
231function applyPlanSteps(items: Task[], e: Record<string, unknown>): Task[] {
232  if (Array.isArray(e.done)) {
233    for (const n of e.done) if (typeof n === 'number') items = withStatus(items, n - 1, 'done')
234  }
235  if (e.advance === true) {
236    const current = items.findIndex(t => t.status === 'active')
237    if (current >= 0) items = withStatus(items, current, 'done')
238    const nextPending = items.findIndex((t, i) => i > current && t.status === 'pending')
239    if (nextPending >= 0) items = withStatus(items, nextPending, 'active')
240  }
241  if (typeof e.start === 'number') {
242    items = items.map(t => (t.status === 'active' ? setStatus(t, 'pending') : t))
243    items = withStatus(items, e.start - 1, 'active')
244  }
245  return items
246}
247
248const TOOL_DESCRIPTION = [
249  'The master plan the person sees in their Plan pane: steps with subtasks and their progress,',
250  'kept for this project across sessions. Call with no arguments to read it back.',
251  '`steps` replaces the whole plan, each step with its `tasks`. `updates` changes one step, or one of its tasks,',
252  'by 1-based `step` and `task`: `status`, `progress` (0-100; 100 marks it done), `note` (why a step is blocked, what is open).',
253  'Take statuses from evidence (merged PRs, branches, files on main), not from checkboxes in a plan doc.',
254  'Your own update_plan list already shows under the step in progress; use this tool for the plan itself,',
255  'and update it as you finish its tasks.',
256].join(' ')
257
258const STATUS_ENUM = ['pending', 'active', 'done', 'blocked']
259const TASK_SCHEMA = {
260  type: 'object',
261  properties: {
262    text: { type: 'string' },
263    status: { type: 'string', enum: STATUS_ENUM },
264    progress: { type: 'number', minimum: 0, maximum: 100 },
265  },
266  required: ['text'],
267}
268
269function buildPrompt(request: string): string {
270  return [
271    `Lay out the master plan for this in my Plan pane: ${request}`,
272    '',
273    'Read what it points at first (specs, implementation plans, PRs, branches, tickets). Make one step per',
274    'slice, phase or milestone, each with its tasks. Take each status from evidence (merged PRs, branches,',
275    'what is on main), not from checkboxes in the docs; mark a step `blocked` with a `note` when something',
276    `must happen before it can start. Then call ${TOOL} once with a short \`title\`, an optional \`note\``,
277    '(the critical path, in one line) and the whole plan as `steps`. Only lay out the plan; do not start the work.',
278  ].join('\n')
279}
280
281const REFRESH_PROMPT = [
282  `Bring the plan in my Plan pane up to date. Read it back with ${TOOL}, check each open step and task`,
283  'against the repo (merged PRs, branches, what is on main), and send the changes as `updates`.',
284  'Only update the plan; do not start the work.',
285].join(' ')
286
287const SUBCOMMANDS = new Set(['show', 'hide', 'clear', 'refresh'])
288
289/** Sends a prompt as the person's, once the hook that asked has returned. */
290function ask($: EngineInterface, text: string) {
291  $.clock.after(0, () => void $.prompt.submit({ text, asUser: true }).catch(() => undefined))
292}
293
294export const register: Register = on => {
295  on('session.start', async ($, e, next) => {
296    await $.command.register({
297      name: 'plan-progress',
298      description: 'Show the Plan pane, or lay out a master plan from a spec, plan, PR or goal',
299      argumentHint: '[<request>|refresh|hide|clear]',
300    })
301    await $.tool.register({
302      name: 'plan',
303      description: TOOL_DESCRIPTION,
304      isDeferred: false,
305      inputSchema: {
306        type: 'object',
307        properties: {
308          title: { type: 'string', description: 'Title shown above the plan.' },
309          note: { type: 'string', description: 'One line under the title, such as the critical path.' },
310          steps: {
311            type: 'array',
312            description: 'Replaces the whole plan.',
313            items: {
314              ...TASK_SCHEMA,
315              properties: {
316                ...TASK_SCHEMA.properties,
317                note: { type: 'string' },
318                tasks: { type: 'array', items: TASK_SCHEMA },
319              },
320            },
321          },
322          updates: {
323            type: 'array',
324            description: 'Changes by 1-based position: a step, or a task of it when `task` is given.',
325            items: {
326              type: 'object',
327              properties: {
328                step: { type: 'number' },
329                task: { type: 'number' },
330                text: { type: 'string' },
331                status: { type: 'string', enum: STATUS_ENUM },
332                progress: { type: 'number', minimum: 0, maximum: 100 },
333                note: { type: 'string', description: 'Empty string removes it.' },
334              },
335              required: ['step'],
336            },
337          },
338          clear: { type: 'boolean', description: 'Empties the plan.' },
339        },
340      },
341    })
342
343    const stored = (await $.store.get(await storeKey($))) as Plan | undefined
344    if (stored && Array.isArray(stored.steps)) await update($, plan, () => stored)
345    const current = await read($, plan)
346    await paintStatus($, current)
347    if (current.steps.length > 0 && !(await read($, isDismissed))) {
348      $.ui.open({ id: PANE, title: 'Plan' }).catch(() => undefined)
349    }
350
351    return next(e)
352  })
353
354  on('tool.call', { tool: TOOL }, async ($, e) => {
355    const args = e as Record<string, unknown>
356    const isRead = ['title', 'note', 'steps', 'updates', 'clear'].every(k => args[k] === undefined)
357    if (!isRead) {
358      await setPlan($, prev => {
359        let p: Plan = args.clear === true ? EMPTY : prev
360        if (typeof args.title === 'string' && args.title.trim()) p = { ...p, title: args.title.trim() }
361        if (typeof args.note === 'string') p = { ...p, note: args.note.trim() || undefined }
362        if (Array.isArray(args.steps)) {
363          p = { ...p, steps: (args.steps as RawStep[]).map(mintStep).filter((s): s is Step => s !== undefined) }
364        }
365        if (Array.isArray(args.updates)) p = applyUpdates(p, args.updates as Update[])
366        return p
367      })
368    }
369    return { result: summary(await read($, plan)) }
370  })
371
372  // The agent's own task list becomes the turn list under the step in progress.
373  on('tool.call', { tool: PLAN_TOOL }, async ($, e, next) => {
374    const ran = await next(e)
375    if (ran.deny !== undefined || ran.isError === true) return ran
376    const args = e as Record<string, unknown>
377    await update($, turn, prev => {
378      let items = prev ?? []
379      if (Array.isArray(args.items)) {
380        items = (args.items as { content?: unknown; text?: unknown; status?: unknown }[])
381          .map(one => mintTask({ text: one?.content ?? one?.text, status: one?.status }))
382          .filter((t): t is Task => t !== undefined)
383      }
384      return applyPlanSteps(items, args)
385    })
386    await paintStatus($, await read($, plan))
387    return ran
388  })
389
390  on('tool.call', { tool: 'TodoWrite' }, async ($, e, next) => {
391    const ran = await next(e)
392    if (ran.deny !== undefined || ran.isError === true) return ran
393    await update($, turn, () =>
394      e.todos.map(todo => mintTask({ text: todo.content, status: todo.status })).filter((t): t is Task => t !== undefined),
395    )
396    await paintStatus($, await read($, plan))
397    return ran
398  })
399
400  on('tool.call', { tool: WRAP_TOOL }, async ($, e, next) => {
401    const ran = await next(e)
402    await update($, turn, prev => (prev ?? []).map(t => (t.status === 'active' ? setStatus(t, 'done') : t)))
403    await paintStatus($, await read($, plan))
404    return ran
405  })
406
407  // A plan kept from an earlier session: tell the agent once that it is there to keep current.
408  on('prompt.submit', async ($, e, next) => {
409    if (e.command !== undefined || e.isMeta === true || (await read($, isBriefed))) return next(e)
410    const p = await read($, plan)
411    if (p.steps.length === 0) return next(e)
412    await update($, isBriefed, () => true)
413    const note = [
414      `The person's Plan pane holds this project's master plan. When your work finishes or starts one of its`,
415      `tasks, report it with ${TOOL} \`updates\`.`,
416      summary(p),
417    ].join('\n')
418    return next({ ...e, context: [...(e.context ?? []), note] })
419  })
420
421  on('ui.close', async ($, e, next) => {
422    if (e.id === PANE && e.origin.kind === 'person') await update($, isDismissed, () => true)
423    return next(e)
424  })
425
426  on('command.run', { command: 'plan-progress' }, async ($, e) => {
427    const [verb = 'show'] = e.args.trim().split(/\s+/).filter(Boolean)
428
429    if (verb === 'hide') {
430      await update($, isDismissed, () => true)
431      await $.ui.close({ id: PANE })
432      return { text: 'Plan pane hidden. /plan-progress brings it back.' }
433    }
434    if (verb === 'clear') {
435      await update($, plan, () => EMPTY)
436      await update($, open, () => ({}))
437      await $.store.delete(await storeKey($))
438      await paintStatus($, EMPTY)
439      return { text: 'Plan cleared for this project.' }
440    }
441
442    await update($, isDismissed, () => false)
443    const opened = await $.ui.open({ id: PANE, title: 'Plan' })
444    const where = opened.isPlaced ? '' : ' (no surface placed the pane right now)'
445
446    // A command.run hook holds the turn, so the prompt goes once it has returned.
447    if (verb === 'refresh') {
448      ask($, REFRESH_PROMPT)
449      return { text: `Bringing the plan up to date${where}.` }
450    }
451    if (!SUBCOMMANDS.has(verb)) {
452      ask($, buildPrompt(e.args.trim()))
453      return { text: `Laying out the plan${where}.` }
454    }
455    return { text: `${summary(await read($, plan))}${where}` }
456  })
457
458  // One row above the prompt: the plan and what is in progress. Press it to open the pane.
459  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
460    const stored = await read($, plan)
461    if (e.props.hasSurvey || stored.steps.length === 0) return next(e)
462    const { Box, Text, Button } = $.ui.resolve(e)
463    const { view, now } = live(stored, await read($, turn))
464    const whole = overall(view)
465    const where = now ? (now.task ? `${now.step.text} › ${now.task.text}` : now.step.text) : `${view.steps.filter(s => s.status === 'done').length} of ${view.steps.length} steps`
466    const [filled, rest] = bar(now?.fraction ?? whole, 8)
467    const tail = now?.fraction !== undefined ? `${pct(now.fraction)}%` : ''
468    return (
469      <Box flexDirection="row" justifyContent="space-between" gap="sm">
470        <Box flexShrink={1}>
471          <Button
472            key="plan-band"
473            plain
474            onPress={async () => {
475              await update($, isDismissed, () => false)
476              await $.ui.open({ id: PANE, title: 'Plan' })
477            }}
478          >
479            <Text wrap="truncate-end">
480              <Text weight="semibold">Plan {pct(whole)}%</Text>
481              <Text dimColor> · </Text>
482              <Text>{where}</Text>
483            </Text>
484          </Button>
485        </Box>
486        <Text mono tabular>
487          <Text color={now ? PART_FILL : MASTER_FILL}>{filled}</Text>
488          <Text color="subtle">{rest}</Text>
489          {tail ? ` ${tail.padStart(4)}` : ''}
490        </Text>
491      </Box>
492    )
493  })
494
495  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
496    const els = $.ui.resolve(e)
497    const { Box, Text, Button } = els
498    const Input = 'Input' in els ? els.Input : undefined
499    const stored = await read($, plan)
500    const turnList = await read($, turn)
501    const expanded = await read($, open)
502    const { view: p, now } = live(stored, turnList)
503
504    const columns = e.props.bodyColumns ?? 40
505
506    const meter = (fraction: number, width: number, fill: string) => {
507      const [filled, rest] = bar(fraction, width)
508      return (
509        <Text mono>
510          <Text color={fill}>{filled}</Text>
511          <Text color="subtle">{rest}</Text>
512        </Text>
513      )
514    }
515
516    // A bar on a line of its own, as wide as the room its indent and the text after it leave.
517    const progressLine = (fraction: number, max: number, indent: number, detail?: string) => {
518      const tail = `  ${pct(fraction)}%`
519      const rest = detail ? ` · ${detail}` : ''
520      const width = Math.max(6, Math.min(max, columns - indent - tail.length - rest.length))
521      return (
522        <Text size="footnote" tabular>
523          {meter(fraction, width, PART_FILL)}
524          {tail}
525          {rest ? <Text dimColor>{rest}</Text> : ''}
526        </Text>
527      )
528    }
529
530    const nowBlock = (n: Now) => (
531      <Box key="now" flexDirection="column" marginTop="sm">
532        <Text size="caption" wrap="truncate-end">
533          <Text color="claude" weight="semibold">
534            Now
535          </Text>
536          {n.task ? <Text dimColor>{` · ${n.step.text}`}</Text> : ''}
537        </Text>
538        <Text weight="medium">{(n.task ?? n.step).text}</Text>
539        {n.fraction !== undefined &&
540          progressLine(n.fraction, 32, 0, n.total ? `${n.done} of ${n.total} this turn` : undefined)}
541      </Box>
542    )
543
544    // The task the Now block names keeps its bar there, not twice.
545    const row = (item: Task, key: string, indent: number) => (
546      <Box key={key} flexDirection="column">
547        <Text wrap="truncate-end">
548          <Text color={MARK[item.status].color}>{MARK[item.status].glyph}</Text>{' '}
549          <Text dimColor={item.status === 'done'} weight={item.status === 'active' ? 'medium' : 'regular'}>
550            {item.text}
551          </Text>
552        </Text>
553        {item.status === 'active' && item.progress !== undefined && item.id !== now?.task?.id && (
554          <Box paddingLeft={2}>{progressLine(item.progress / 100, 20, indent + 2)}</Box>
555        )}
556      </Box>
557    )
558
559    const turnRows = (indent: number) =>
560      turnList.length === 0 ? null : (
561        <Box flexDirection="column" paddingLeft={indent} marginTop="xs">
562          <Text size="caption" dimColor>
563            This turn
564          </Text>
565          {turnList.map(t => row(t, `turn-${t.id}`, indent + 4))}
566        </Box>
567      )
568
569    if (p.steps.length === 0) {
570      return (
571        <Box flexDirection="column" gap="sm">
572          <Text size="heading" weight="semibold">
573            No plan yet
574          </Text>
575          <Text dimColor size="footnote">
576            Point the agent at a spec, an implementation plan, a PR or a goal. It reads what is there, checks what
577            has landed, and lays out the steps here with their tasks. The plan stays with this project across
578            sessions.
579          </Text>
580          {Input !== undefined && (
581            <Input
582              key="request"
583              placeholder="docs/plans/autopilot, a PR link, a goal"
584              submitLabel="Lay out plan"
585              onSubmit={value => {
586                if (value.trim()) ask($, buildPrompt(value.trim()))
587              }}
588            />
589          )}
590          <Text dimColor size="caption">
591            Or run /plan-progress with the same.
592          </Text>
593          {turnRows(0)}
594        </Box>
595      )
596    }
597
598    const whole = overall(p)
599    const doneSteps = p.steps.filter(s => s.status === 'done').length
600    const allTasks = p.steps.flatMap(s => s.tasks)
601    const doneTasks = allTasks.filter(t => t.status === 'done').length
602    const hasActive = p.steps.some(s => s.status === 'active')
603    const facts = [
604      `${doneSteps} of ${p.steps.length} steps`,
605      allTasks.length ? `${doneTasks} of ${allTasks.length} tasks` : '',
606      age(p.updatedAt),
607    ].filter(Boolean)
608
609    const toggle = (step: Step, isOpen: boolean) =>
610      update($, open, prev => ({ ...(prev ?? {}), [step.id]: !isOpen }))
611
612    return (
613      <Box flexDirection="column" gap="md">
614        <Box flexDirection="column" gap="xs">
615          <Box flexDirection="row" justifyContent="space-between" gap="sm">
616            <Box flexShrink={1}>
617              <Text size="heading" weight="semibold" wrap="truncate-end">
618                {p.title || 'Plan'}
619              </Text>
620            </Box>
621            <Text size="heading" weight="semibold" tabular>
622              {pct(whole)}%
623            </Text>
624          </Box>
625          {meter(whole, Math.max(8, Math.min(56, columns - 2)), MASTER_FILL)}
626          <Text size="footnote" dimColor tabular>
627            {facts.join(' · ')}
628          </Text>
629          {p.note && (
630            <Text size="footnote" dimColor>
631              {p.note}
632            </Text>
633          )}
634          {now && nowBlock(now)}
635        </Box>
636
637        <Box flexDirection="column" gap="xs">
638          {p.steps.map(step => {
639            const hasBody = step.tasks.length > 0 || step.note !== undefined || (step.status === 'active' && turnList.length > 0)
640            const isOpen = hasBody && (expanded[step.id] ?? (step.status === 'active' || step.status === 'blocked'))
641            const fraction = stepShare(step)
642            const count = step.tasks.length
643              ? `${step.tasks.filter(t => t.status === 'done').length}/${step.tasks.length}`
644              : ''
645            // The step in progress puts its numbers on the bar below; any other shows its count.
646            const isActive = step.status === 'active'
647            const tally = isActive ? '' : count
648            const label = (
649              <Text wrap="truncate-end">
650                <Text dimColor>{hasBody ? (isOpen ? '▾' : '▸') : ' '}</Text>{' '}
651                <Text color={MARK[step.status].color}>{MARK[step.status].glyph}</Text>{' '}
652                <Text dimColor={step.status === 'done'} weight={step.status === 'active' ? 'semibold' : 'regular'}>
653                  {step.text}
654                </Text>
655              </Text>
656            )
657            return (
658              <Box key={`step-${step.id}`} flexDirection="column">
659                <Box flexDirection="row" justifyContent="space-between" gap="sm">
660                  <Box flexShrink={1}>
661                    {hasBody ? (
662                      <Button key={`toggle-${step.id}`} plain onPress={() => toggle(step, isOpen)}>
663                        {label}
664                      </Button>
665                    ) : (
666                      label
667                    )}
668                  </Box>
669                  {tally !== '' && (
670                    <Text size="footnote" tabular dimColor>
671                      {tally}
672                    </Text>
673                  )}
674                </Box>
675                {isActive && (
676                  <Box paddingLeft={4}>
677                    {progressLine(
678                      fraction,
679                      40,
680                      4,
681                      step.tasks.length
682                        ? `${step.tasks.filter(t => t.status === 'done').length} of ${step.tasks.length} tasks`
683                        : undefined,
684                    )}
685                  </Box>
686                )}
687                {isOpen && (
688                  <Box flexDirection="column" paddingLeft={4} marginTop={isActive ? 'xs' : undefined}>
689                    {step.note !== undefined && (
690                      <Text
691                        size="footnote"
692                        color={step.status === 'blocked' ? 'warning' : undefined}
693                        dimColor={step.status !== 'blocked'}
694                      >
695                        {step.note}
696                      </Text>
697                    )}
698                    {step.tasks.map(t => row(t, `task-${t.id}`, 4))}
699                    {step.status === 'active' && turnRows(0)}
700                  </Box>
701                )}
702              </Box>
703            )
704          })}
705        </Box>
706
707        {!hasActive && turnRows(0)}
708
709        <Box flexDirection="row">
710          <Button key="refresh" plain dimColor label="Check against the repo" onPress={() => ask($, REFRESH_PROMPT)} />
711        </Box>
712      </Box>
713    )
714  })
715}
716

1export type Status = 'pending' | 'active' | 'done' | 'blocked'
2
3/** `progress` is 0-100, reported by the agent; only an item in progress carries one. */
4export type Task = { id: string; text: string; status: Status; progress?: number }
5
6export type Step = Task & { note?: string; tasks: Task[] }
7
8export type Plan = { title: string; note?: string; steps: Step[]; updatedAt?: string }
9
10declare module 'claude-code' {
11  interface PluginState {
12    'plan-progress': {
13      plan: Plan
14      /** The agent's own task list for the turn, shown under the step in progress. */
15      turn: Task[]
16      /** Expanded or collapsed per step id; a step absent here is open while in progress. */
17      open: Record<string, boolean>
18      isDismissed: boolean
19      isBriefed: boolean
20    }
21  }
22}
23