sdd-pipeline

1// sdd-live — what is happening in an SDD project, live, inside Claude Code.
2//
3// - Above the prompt: the SDD phase, the delivery in course, requirements proven, the gate; then what runs now (the
4//   SDD skill, how many agents work and on what).
5// - /sdd opens a pane: Now (skill and stage), Agents (each subagent: what it was asked, its type, how long, its last
6//   action and its recent ones, how it ended), Project (requirements with their warnings in plain words), Journal,
7//   and the customer page's link.
8// - Toasts when an agent finishes and when the phase, the proven count or the gate changes.
9//
10// Agents are followed from the engine's own events: `agent.spawn` (what it was asked, its id), `tool.call` carrying
11// that id (what it does), `turn.complete` carrying it (how it ended), and `$.agent.list()` for the status of the
12// ones still alive. The project comes from `sdd status build --no-out` (read-only), refreshed when the session
13// starts, after each main turn and after an SDD skill or a commit.
14import { atom, read, update } from 'claude-code'
15import type { Register } from 'claude-code'
16
17import type { Agent, Now, Snapshot } from '../../types/sdd-live'
18
19const PANE = 'sdd-live'
20const snap = atom({ plugin: 'sdd-pipeline', key: 'snap' } as const, null)
21const error = atom({ plugin: 'sdd-pipeline', key: 'error' } as const, null)
22const target = atom({ plugin: 'sdd-pipeline', key: 'target' } as const, null)
23const isHidden = atom({ plugin: 'sdd-pipeline', key: 'isHidden' } as const, false)
24const agents = atom({ plugin: 'sdd-pipeline', key: 'agents' } as const, [])
25const now = atom({ plugin: 'sdd-pipeline', key: 'now' } as const, { skill: null, skillAt: null, last: null, lastAt: null })
26
27const PHASE: Record<string, string> = {
28  understand: 'Entender', agree: 'Acordar', design: 'Diseñar', plan: 'Planificar',
29  build: 'Construir', verify: 'Comprobar', deliver: 'Entregar', done: 'Entregado',
30}
31const STATUS: Record<string, string> = {
32  pending: 'Pendiente', building: 'En construcción', shown: 'Demostrado', failing: 'No cumple',
33  deferred: 'Aplazado', deprecated: 'Retirado',
34}
35const WARN: Record<string, string> = {
36  unshown: 'falta captura', weakened: 'prueba sin el texto exacto', challenge: 'revisor encontró un problema',
37  stale: 'evidencia antigua', failing: 'prueba falla',
38}
39const GATE: Record<number, string> = { 0: 'gate ok', 1: 'gate: no cumplido', 2: 'gate: evidencia antigua', 3: 'gate ok con aplazados', 4: 'gate: hallazgo abierto' }
40const COLOR: Record<string, string> = { shown: 'success', building: 'suggestion', failing: 'error', deferred: 'remember', pending: 'subtle', deprecated: 'subtle' }
41/** The SDD skills by the stage a person recognises. */
42const SKILL: Record<string, string> = {
43  'sdd-requirements-engineer': 'Requisitos', 'sdd-specifications-engineer': 'Especificaciones', 'sdd-spec-auditor': 'Auditoría de specs',
44  'sdd-test-planner': 'Plan de pruebas', 'sdd-plan-architect': 'Plan de entregas', 'sdd-task-generator': 'Tareas',
45  'sdd-task-implementer': 'Construcción', 'sdd-acceptance': 'Aceptación', 'sdd-gap-detector': 'Huecos spec/código',
46  'sdd-req-change': 'Cambio de requisitos', 'sdd-tech-designer': 'Diseño técnico', 'sdd-ux-designer': 'Diseño UX',
47  'sdd-security-auditor': 'Auditoría de seguridad', 'sdd-orchestrator': 'Orquestador', 'sdd-lead': 'Lead multisesión',
48  'sdd-setup': 'Puesta en marcha', 'sdd-pipeline-status': 'Estado del pipeline', 'sdd-reverse-engineer': 'Ingeniería inversa',
49  'sdd-reconcile': 'Reconciliar specs', 'sdd-import': 'Importar', 'sdd-session-summary': 'Resumen de sesión',
50}
51const LIVE = new Set(['pending', 'running', 'waiting'])
52const AGENT_ICON: Record<string, string> = { running: '▶', pending: '…', waiting: '⏸', idle: '·', completed: '✓', failed: '✗', killed: '■' }
53const AGENT_COLOR: Record<string, string> = { running: 'claude', pending: 'subtle', waiting: 'warning', idle: 'subtle', completed: 'success', failed: 'error', killed: 'subtle' }
54
55/** The skill's short name: `sdd-pipeline:sdd-acceptance` → `sdd-acceptance`. */
56function skillName(skill: string): string {
57  return String(skill).split(':').pop() || String(skill)
58}
59function base(p: unknown): string {
60  return String(p ?? '').split('/').filter(Boolean).pop() || String(p ?? '')
61}
62function clip(s: unknown, n: number): string {
63  const t = String(s ?? '').replace(/\s+/g, ' ').trim()
64  return t.length > n ? `${t.slice(0, n - 1)}…` : t
65}
66/** One line for what a tool call does, in the words a person reads in a log. */
67function describe(e: any): string {
68  switch (e.tool) {
69    case 'Bash': return `$ ${clip(e.command, 70)}`
70    case 'Read': return `lee ${base(e.file_path)}`
71    case 'Edit': case 'MultiEdit': return `edita ${base(e.file_path)}`
72    case 'Write': return `escribe ${base(e.file_path)}`
73    case 'Grep': return `busca «${clip(e.pattern, 40)}»`
74    case 'Glob': return `lista ${clip(e.pattern, 40)}`
75    case 'Skill': return `skill ${skillName(e.skill)}`
76    case 'Agent': case 'Task': return `lanza agente «${clip(e.description, 40)}»`
77    case 'WebFetch': return `consulta ${clip(e.url, 50)}`
78    case 'WebSearch': return `busca en la web «${clip(e.query, 40)}»`
79    default: return String(e.tool)
80  }
81}
82function ago(ms: number): string {
83  const s = Math.max(0, Math.round(ms / 1000))
84  if (s < 60) return `${s}s`
85  const m = Math.floor(s / 60)
86  return m < 60 ? `${m}m${String(s % 60).padStart(2, '0')}s` : `${Math.floor(m / 60)}h${String(m % 60).padStart(2, '0')}m`
87}
88
89/** The sdd.mjs this view runs: the plugin's own when shipped inside sdd-pipeline, else $SDD_PLUGIN_ROOT's, else the
90 * newest installed sdd-pipeline in the plugin cache (a release ranks above its own pre-release). */
91async function cli($: any): Promise<string | null> {
92  const own = `${$.plugin.root}/scripts/sdd.mjs`
93  if (await $.fs.exists(own)) return own
94  const env = await $.env.get('SDD_PLUGIN_ROOT')
95  if (env && (await $.fs.exists(`${env}/scripts/sdd.mjs`))) return `${env}/scripts/sdd.mjs`
96  const home = await $.env.get('HOME')
97  const cache = `${home}/.claude/plugins/cache/noelserdna/sdd-pipeline`
98  if (!(await $.fs.exists(cache))) return null
99  const versions = (await $.fs.list(cache)).filter((x: any) => x.kind === 'dir' && /^\d+\.\d+\.\d+/.test(x.name)).map((x: any) => x.name)
100  const key = (v: string) => { const [core = '', pre] = v.split('-', 2); return [...core.split('.').map(n => Number(n) || 0), pre ? 0 : 1] }
101  versions.sort((a: string, b: string) => { const x = key(a), y = key(b); for (let i = 0; i < 4; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (y[i] ?? 0) - (x[i] ?? 0); return 0 })
102  return versions.length ? `${cache}/${versions[0]}/scripts/sdd.mjs` : null
103}
104
105/** Rebuilds the project snapshot (read-only); a folder with no SDD project leaves it null. */
106async function refresh($: any, quiet = true) {
107  const root = (await read($, target)) || (await $.session.cwd())
108  const isSdd = (await $.fs.exists(`${root}/pipeline-state.json`)) || (await $.fs.exists(`${root}/requirements/REQUIREMENTS.md`))
109  if (!isSdd) { await update($, snap, () => null); await update($, error, () => null); await status($); return }
110  const sdd = await cli($)
111  if (!sdd) { await update($, error, () => 'no encuentro el plugin sdd-pipeline'); return }
112  const run = await $.process.run(['node', sdd, 'status', 'build', '--no-out'], { cwd: root, timeoutMs: 60000 })
113  if (run.exitCode !== 0) { await update($, error, () => (run.stderr || run.stdout).split('\n')[0].slice(0, 200)); return }
114  let d: any
115  try { d = JSON.parse(run.stdout) } catch { await update($, error, () => 'salida de sdd status build ilegible'); return }
116  const active = (d.requirements || []).filter((r: any) => r.status !== 'deprecated')
117  const s: Snapshot = {
118    root,
119    name: d.project?.name || base(root),
120    phase: d.where?.phase || 'understand',
121    now: d.where?.now || '',
122    next: d.where?.next ?? null,
123    ask: (d.where?.needFromYou || []).map((a: any) => a.text),
124    fase: d.where?.fase ? `entrega ${d.where.fase.n}/${d.where.fase.of}` : null,
125    shown: active.filter((r: any) => r.status === 'shown').length,
126    total: active.length,
127    gate: d.technical?.gate?.code ?? null,
128    reqs: active.map((r: any) => ({ id: r.id, title: r.title, plain: r.plain, status: r.status, fase: r.fase,
129      warnings: [...new Set<string>((r.warnings || []).map((w: any) => w.code))] })),
130    journal: (d.journal || []).slice(-8).reverse().map((j: any) => ({ at: j.at, kind: j.kind, text: j.text })),
131    url: d.page?.url ?? null,
132    at: await $.clock.now(),
133  }
134  const before = await read($, snap)
135  await update($, snap, () => s)
136  await update($, error, () => null)
137  await status($)
138  if (!quiet && before && before.root === s.root) {
139    if (before.phase !== s.phase) $.ui.toast(`SDD: ahora ${PHASE[s.phase] || s.phase} — ${s.now}`)
140    else if (before.shown !== s.shown) $.ui.toast(`SDD: ${s.shown} de ${s.total} requisitos demostrados`)
141    else if (before.gate !== s.gate && s.gate !== null) $.ui.toast(`SDD: ${GATE[s.gate] || 'gate ' + s.gate}`)
142  }
143}
144
145/** The status line: the phase and the agents at work. */
146async function status($: any) {
147  const s = await read($, snap)
148  const live = (await read($, agents)).filter(a => LIVE.has(a.status)).length
149  const parts = [s ? `SDD ${PHASE[s.phase] || s.phase} · ${s.shown}/${s.total}` : null, live ? `${live} agente${live === 1 ? '' : 's'}` : null].filter(Boolean)
150  $.ui.status(parts.length ? parts.join(' · ') : undefined)
151}
152
153/** Records one agent's change; the list keeps the newest 40. */
154async function touch($: any, id: string, change: (a: Agent) => Agent, create?: () => Agent) {
155  await update($, agents, list => {
156    const i = list.findIndex(a => a.id === id)
157    if (i === -1) return create ? [create(), ...list].slice(0, 40) : list
158    const next = [...list]
159    next[i] = change(next[i] as Agent)
160    return next
161  })
162}
163
164/** Reconciles the statuses with the engine's own list (an agent stopped, killed or left waiting). */
165async function poll($: any) {
166  const mine = await read($, agents)
167  if (!mine.some(a => LIVE.has(a.status))) return
168  let rows: any[] = []
169  try { rows = await $.agent.list() } catch { return }
170  const at = await $.clock.now()
171  for (const r of rows) {
172    const known = mine.find(a => a.id === r.id)
173    if (known && known.status !== r.status) {
174      await touch($, r.id, a => ({ ...a, status: r.status, endedAt: LIVE.has(r.status) ? null : (a.endedAt ?? at) }))
175    }
176  }
177  await status($)
178}
179
180export const register: Register = on => {
181  on('session.start', async ($, e, next) => {
182    await $.command.register({ name: 'sdd', description: 'Panel en vivo del proyecto SDD: etapa, agentes en marcha, requisitos y diario', argumentHint: '[ruta del proyecto | refresh | off | clear]' })
183    const started = await next(e)
184    void refresh($).catch(() => {})
185    $.clock.every(5000, () => { void poll($).catch(() => {}) })
186    return started
187  })
188
189  on('agent.spawn', async ($, e, next) => {
190    const r: any = await next(e)
191    if (r && r.agentId) {
192      const at = await $.clock.now()
193      const ev: any = e
194      await touch($, r.agentId, a => a, () => ({
195        id: r.agentId, description: clip(ev.description || ev.subagentType, 80), type: String(ev.subagentType || 'agent'),
196        workflow: ev.workflow?.runId ?? null, parent: ev.parentAgentId ?? null, status: 'running',
197        startedAt: at, endedAt: null, last: null, lastAt: null, actions: 0, recent: [],
198      }))
199      await status($)
200    }
201    return r
202  }).catch(($, e, next) => next(e)) // an observer: whatever fails here, the agent starts
203
204  on('tool.call', async ($, e, next) => {
205    const ev: any = e
206    const line = describe(ev)
207    const at = await $.clock.now()
208    if (ev.agentId) {
209      await touch($, ev.agentId, a => ({ ...a, status: 'running', last: line, lastAt: at, actions: a.actions + 1, recent: [line, ...a.recent].slice(0, 6) }))
210    } else {
211      await update($, now, n => ({ ...n, last: line, lastAt: at }))
212      if (ev.tool === 'Skill' && /(^|:)sdd-/.test(String(ev.skill))) await update($, now, n => ({ ...n, skill: skillName(ev.skill), skillAt: at }))
213    }
214    const ran = await next(e)
215    // a commit or an SDD skill changes the project: refresh it once the call is done
216    if (!ev.agentId && ((ev.tool === 'Bash' && /\bgit (commit|merge|tag)\b|\bsdd(\.mjs)? (accept|journal|status|route)\b/.test(String(ev.command))) || ev.tool === 'Skill')) {
217      void refresh($, false).catch(() => {})
218    }
219    return ran
220  }).catch(($, e, next) => next(e)) // an observer: whatever fails here, the call runs
221
222  on('skill.prompt', async ($, e, next) => {
223    const name = skillName((e as any).skill)
224    if (name.startsWith('sdd-')) { const at = await $.clock.now(); await update($, now, n => ({ ...n, skill: name, skillAt: at })) }
225    return next(e)
226  })
227
228  on('turn.complete', async ($, e, next) => {
229    const done: any = await next(e)
230    const ev: any = e
231    if (ev.agentId) {
232      const at = await $.clock.now()
233      const list = await read($, agents)
234      const a = list.find(x => x.id === ev.agentId)
235      if (a && LIVE.has(a.status)) {
236        const ended = ev.isAborted ? 'killed' : 'completed'
237        await touch($, ev.agentId, x => ({ ...x, status: ended, endedAt: at }))
238        $.ui.toast(`${ended === 'completed' ? '✓' : '■'} Agente «${clip(a.description, 50)}» ${ended === 'completed' ? 'terminó' : 'se detuvo'} en ${ago(at - a.startedAt)}`)
239        await status($)
240      }
241    } else {
242      void refresh($, false).catch(() => {})
243    }
244    return done
245  })
246
247  on('command.run', { command: 'sdd' }, async ($, e) => {
248    const arg = ((e as any).args || '').trim()
249    if (arg === 'off') { await update($, target, () => null); await refresh($); return { text: 'sdd-live: vuelve a seguir el directorio de la sesión.' } }
250    if (arg === 'clear') { await update($, agents, list => list.filter(a => LIVE.has(a.status))); await status($); return { text: 'sdd-live: agentes terminados borrados de la lista.' } }
251    if (arg && arg !== 'refresh') {
252      if (!(await $.fs.exists(arg))) return { text: `sdd-live: no existe ${arg}` }
253      await update($, target, () => arg)
254    }
255    await update($, isHidden, () => false)
256    await refresh($)
257    const s = await read($, snap)
258    await $.ui.open({ id: PANE, title: s ? `SDD · ${s.name}` : 'SDD · agentes' })
259    const live = (await read($, agents)).filter(a => LIVE.has(a.status)).length
260    return { text: s ? `Panel SDD de ${s.name} abierto (${live} agente${live === 1 ? '' : 's'} en marcha).` : ((await read($, error)) || `Este directorio no tiene un proyecto SDD; el panel muestra solo los agentes (${live} en marcha).`) }
261  })
262
263  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
264    const s = await read($, snap)
265    const list = await read($, agents)
266    const live = list.filter(a => LIVE.has(a.status))
267    const n: Now = await read($, now)
268    if ((!s && live.length === 0) || e.props.hasSurvey || (await read($, isHidden))) return next(e)
269    const { Box, Text, Button } = $.ui.resolve(e)
270    const t = await $.clock.now()
271    const gate = s && s.gate !== null ? GATE[s.gate] : null
272    const first = live[0]
273    return (
274      <Box flexDirection="column">
275        <Box>
276          <Text bold>SDD </Text>
277          {s && <Text color="claude">{PHASE[s.phase] || s.phase}</Text>}
278          {s && s.fase && <Text dimColor> · {s.fase}</Text>}
279          {s && <Text dimColor> · {s.shown}/{s.total} demostrados</Text>}
280          {gate && <Text color={s!.gate === 0 || s!.gate === 3 ? 'success' : 'warning'}> · {gate}</Text>}
281          {n.skill && <Text dimColor> · {SKILL[n.skill] || n.skill}</Text>}
282          {live.length > 0 && <Text color="claude"> · {live.length} agente{live.length === 1 ? '' : 's'}</Text>}
283          <Text> </Text>
284          <Button key="hide" label="Ocultar" plain onPress={() => update($, isHidden, () => true)} />
285        </Box>
286        {first && (
287          <Text dimColor wrap="truncate-end">
288            ▶ {first.description}{first.last ? ` — ${first.last}` : ''} ({ago(t - first.startedAt)}){live.length > 1 ? ` · y ${live.length - 1} más (/sdd)` : ''}
289          </Text>
290        )}
291        {!first && s && s.ask.length > 0 && <Text color="warning" wrap="truncate-end">Necesitamos del cliente: {s.ask[0]}</Text>}
292        {!first && s && s.ask.length === 0 && s.now && <Text dimColor wrap="truncate-end">{s.now}</Text>}
293      </Box>
294    )
295  })
296
297  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
298    const { Box, Text, Button } = $.ui.resolve(e)
299    const s = await read($, snap)
300    const err = await read($, error)
301    const list = await read($, agents)
302    const n: Now = await read($, now)
303    const t = await $.clock.now()
304    const live = list.filter(a => LIVE.has(a.status))
305    const ended = list.filter(a => !LIVE.has(a.status)).slice(0, 6)
306    const rows = Math.max(12, e.viewport?.rows ?? 30)
307    const reqRoom = Math.max(3, rows - 18 - live.length * 3 - ended.length)
308    const reqs = s ? [...s.reqs].sort((a, b) => (b.warnings.length - a.warnings.length) || a.id.localeCompare(b.id)).slice(0, reqRoom) : []
309    return (
310      <Box flexDirection="column">
311        <Text bold>Ahora</Text>
312        {s ? <Text wrap="wrap">{PHASE[s.phase] || s.phase}{s.fase ? ` · ${s.fase}` : ''} · {s.shown}/{s.total} demostrados — {s.now}</Text>
313           : <Text dimColor wrap="wrap">{err || 'Sin proyecto SDD en este directorio (/sdd <ruta> para seguir otro).'}</Text>}
314        {n.skill && <Text wrap="truncate-end">Skill: <Text color="claude">{SKILL[n.skill] || n.skill}</Text><Text dimColor> ({n.skill}, desde hace {ago(t - (n.skillAt ?? t))})</Text></Text>}
315        {n.last && <Text dimColor wrap="truncate-end">Conversación principal: {n.last} (hace {ago(t - (n.lastAt ?? t))})</Text>}
316        {s && s.ask.map(a => <Text color="warning" wrap="wrap">Del cliente: {a}</Text>)}
317        <Text> </Text>
318        <Text bold>Agentes {live.length ? `(${live.length} en marcha)` : ''}</Text>
319        {list.length === 0 && <Text dimColor>Ningún agente lanzado en esta sesión.</Text>}
320        {live.map(a => (
321          <Box flexDirection="column">
322            <Text wrap="truncate-end"><Text color={AGENT_COLOR[a.status] || 'text'}>{AGENT_ICON[a.status] || '?'} </Text><Text bold>{a.description}</Text><Text dimColor> · {a.type}{a.workflow ? ' · workflow' : ''} · {ago(t - a.startedAt)} · {a.actions} acciones</Text></Text>
323            <Text dimColor wrap="truncate-end">   {a.last ? `ahora: ${a.last} (hace ${ago(t - (a.lastAt ?? t))})` : 'arrancando…'}</Text>
324            {a.recent.length > 1 && <Text dimColor wrap="truncate-end">   antes: {a.recent.slice(1, 4).join(' · ')}</Text>}
325          </Box>
326        ))}
327        {ended.map(a => (
328          <Text dimColor wrap="truncate-end"><Text color={AGENT_COLOR[a.status] || 'subtle'}>{AGENT_ICON[a.status] || '·'} </Text>{a.description} · {a.type} · {ago((a.endedAt ?? t) - a.startedAt)} · {a.actions} acciones</Text>
329        ))}
330        {s && <Text> </Text>}
331        {s && <Text bold>Requisitos</Text>}
332        {reqs.map(r => (
333          <Box flexDirection="column">
334            <Text wrap="truncate-end">
335              <Text color={COLOR[r.status] || 'text'}>{STATUS[r.status] || r.status}</Text>
336              <Text dimColor> {r.id} </Text>
337              {r.plain || r.title}
338            </Text>
339            {r.warnings.length > 0 && <Text color="warning" wrap="truncate-end">   ⚠ {r.warnings.map(w => WARN[w] || w).join(' · ')}</Text>}
340          </Box>
341        ))}
342        {s && s.journal.length > 0 && <Text> </Text>}
343        {s && s.journal.length > 0 && <Text bold>Diario</Text>}
344        {s && s.journal.slice(0, 4).map(j => <Text wrap="truncate-end"><Text dimColor>{j.at.slice(0, 10)} </Text>{j.text}</Text>)}
345        <Text> </Text>
346        {s && (s.url ? <Text dimColor wrap="truncate-end">Página del cliente: {s.url}</Text> : <Text dimColor>Sin página del cliente publicada todavía.</Text>)}
347        <Box>
348          <Button key="refresh" label="Actualizar" onPress={() => refresh($, false)} />
349          <Text> </Text>
350          <Button key="clear" label="Limpiar terminados" onPress={() => update($, agents, l => l.filter(a => LIVE.has(a.status)))} />
351        </Box>
352      </Box>
353    )
354  })
355}
356

1export type Req = { id: string; title: string; plain: string | null; status: string; warnings: string[]; fase: number | null }
2export type Entry = { at: string; kind: string; text: string }
3/** The SDD project as `sdd status build --no-out` describes it (contract sdd-status-v1, cut to what the views draw). */
4export type Snapshot = {
5  root: string
6  name: string
7  phase: string
8  now: string
9  next: string | null
10  ask: string[]
11  fase: string | null
12  shown: number
13  total: number
14  gate: number | null
15  reqs: Req[]
16  journal: Entry[]
17  url: string | null
18  at: number
19}
20/** One subagent of this session: what it was asked, what it is doing now and how it ended. */
21export type Agent = {
22  id: string
23  description: string
24  type: string
25  workflow: string | null
26  parent: string | null
27  status: string
28  startedAt: number
29  endedAt: number | null
30  last: string | null
31  lastAt: number | null
32  actions: number
33  recent: string[]
34}
35/** What is running in the main conversation: the SDD skill in course and the main loop's last action. */
36export type Now = { skill: string | null; skillAt: number | null; last: string | null; lastAt: number | null }
37
38declare module 'claude-code' {
39  interface PluginState {
40    'sdd-pipeline': {
41      snap: Snapshot | null
42      error: string | null
43      target: string | null
44      isHidden: boolean
45      agents: Agent[]
46      now: Now
47    }
48  }
49}
50