@cat-factory/app 0.31.0 → 0.32.0

package/app/stores/brainstorm.ts

@@ -0,0 +1,210 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import type {
+  BrainstormSession,
+  BrainstormStage,
+  ResolveBrainstormExceededChoice,
+  ReviewItemStatus,
+} from '~/types/brainstorm'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+/**
+ * Brainstorm (structured-dialogue) state. On the pipeline path a brainstorm runs as an opt-in
+ * gate step: the run parks while the human picks / steers / dismisses the proposed options, then
+ * asks to incorporate. Incorporation + the re-run run ASYNCHRONOUSLY in the durable driver — the
+ * call returns at once (status `incorporating`) and the user goes back to the board; they are
+ * summoned again (a notification) only if the re-run yields options or hits the cap. The store is
+ * patched both from call responses and from live `brainstorm` stream events (see `upsert`).
+ *
+ * A block may have one live session per STAGE (`requirements` / `architecture`), so the cache is
+ * keyed by `${blockId}:${stage}`. `available` mirrors the backend's opt-in gate (a 503 hides the
+ * UI). Per-workspace; nothing is persisted client-side.
+ */
+export const useBrainstormStore = defineStore('brainstorm', () => {
+  const api = useApi()
+  const workspace = useWorkspaceStore()
+
+  const key = (blockId: string, stage: BrainstormStage) => `${blockId}:${stage}`
+
+  /** null = unknown (not probed), true/false = feature on/off. */
+  const available = ref<boolean | null>(null)
+  /** The current session per `${blockId}:${stage}` (null = fetched, none exists). */
+  const sessions = ref<Record<string, BrainstormSession | null>>({})
+  /** `${blockId}:${stage}` keys whose agent is currently running (run / re-run). */
+  const running = ref<Set<string>>(new Set())
+  /** Session ids currently incorporating their picks. */
+  const incorporating = ref<Set<string>>(new Set())
+  /** `${blockId}:${stage}` keys whose current session is being fetched (the initial `load`). */
+  const loadingByKey = ref<Set<string>>(new Set())
+  const inFlight = new Map<string, Promise<void>>()
+
+  function sessionFor(blockId: string, stage: BrainstormStage): BrainstormSession | null {
+    return sessions.value[key(blockId, stage)] ?? null
+  }
+  /** The async background stage a session is in, or null (so the board can show "working"). */
+  function backgroundStage(
+    blockId: string,
+    stage: BrainstormStage,
+  ): 'incorporating' | 'reviewing' | null {
+    const status = sessions.value[key(blockId, stage)]?.status
+    return status === 'incorporating' || status === 'reviewing' ? status : null
+  }
+  function isRunning(blockId: string, stage: BrainstormStage): boolean {
+    return running.value.has(key(blockId, stage))
+  }
+  function isLoading(blockId: string, stage: BrainstormStage): boolean {
+    return loadingByKey.value.has(key(blockId, stage))
+  }
+  function isIncorporating(sessionId: string): boolean {
+    return incorporating.value.has(sessionId)
+  }
+
+  /** Options still needing a human (status `open`). */
+  function openCount(session: BrainstormSession): number {
+    return session.items.filter((i) => i.status === 'open').length
+  }
+  /** Options the human chose (a reply recorded), which the companion folds in. */
+  function answeredCount(session: BrainstormSession): number {
+    return session.items.filter((i) => i.status === 'answered' || i.status === 'resolved').length
+  }
+  /** Every option is settled (chosen or dismissed) — none still open. */
+  function allSettled(session: BrainstormSession): boolean {
+    return openCount(session) === 0
+  }
+  /** Incorporation is possible: all options settled AND at least one was chosen. */
+  function canIncorporate(session: BrainstormSession): boolean {
+    return allSettled(session) && answeredCount(session) > 0
+  }
+  /** Proceed (skip the companion) is possible: all options settled but none chosen. */
+  function canProceed(session: BrainstormSession): boolean {
+    return allSettled(session) && answeredCount(session) === 0
+  }
+
+  function store(session: BrainstormSession) {
+    sessions.value = { ...sessions.value, [key(session.blockId, session.stage)]: session }
+  }
+
+  function withFlag(set: typeof running, k: string, on: boolean) {
+    const next = new Set(set.value)
+    if (on) next.add(k)
+    else next.delete(k)
+    set.value = next
+  }
+
+  /** Fetch the current session for a block + stage (probing the feature's availability). */
+  async function load(blockId: string, stage: BrainstormStage) {
+    if (!workspace.workspaceId) return
+    const k = key(blockId, stage)
+    const pending = inFlight.get(k)
+    if (pending) return pending
+    const promise = (async () => {
+      withFlag(loadingByKey, k, true)
+      try {
+        const session = await api.getBrainstorm(workspace.requireId(), blockId, stage)
+        available.value = true
+        sessions.value = { ...sessions.value, [k]: session }
+      } catch {
+        available.value = false
+      } finally {
+        withFlag(loadingByKey, k, false)
+        inFlight.delete(k)
+      }
+    })()
+    inFlight.set(k, promise)
+    return promise
+  }
+
+  /** Record a human's choice on one option. */
+  async function reply(session: BrainstormSession, itemId: string, text: string) {
+    store(await api.replyBrainstormItem(workspace.requireId(), session.id, itemId, text))
+  }
+
+  /** Set an option's status (dismiss / reopen). */
+  async function setItemStatus(
+    session: BrainstormSession,
+    itemId: string,
+    status: ReviewItemStatus,
+  ) {
+    store(await api.setBrainstormItemStatus(workspace.requireId(), session.id, itemId, status))
+  }
+
+  /**
+   * Ask the driver to incorporate the picks ASYNCHRONOUSLY. Optional `feedback` is the "do it
+   * differently" direction when redoing a merge. Returns at once with the `incorporating`
+   * session (the fold + re-run happen in the background).
+   */
+  async function incorporate(session: BrainstormSession, feedback?: string) {
+    withFlag(incorporating, session.id, true)
+    try {
+      const updated = await api.incorporateBrainstorm(
+        workspace.requireId(),
+        session.blockId,
+        session.stage,
+        feedback,
+      )
+      store(updated)
+      return updated
+    } finally {
+      withFlag(incorporating, session.id, false)
+    }
+  }
+
+  /** Re-run the brainstorm against the converged direction (one more pass; may converge/advance). */
+  async function reReview(blockId: string, stage: BrainstormStage): Promise<BrainstormSession> {
+    withFlag(running, key(blockId, stage), true)
+    try {
+      const updated = await api.reReviewBrainstorm(workspace.requireId(), blockId, stage)
+      store(updated)
+      return updated
+    } finally {
+      withFlag(running, key(blockId, stage), false)
+    }
+  }
+
+  /** Proceed: settle the brainstorm and advance the parked run. */
+  async function proceed(blockId: string, stage: BrainstormStage): Promise<BrainstormSession> {
+    const updated = await api.proceedBrainstorm(workspace.requireId(), blockId, stage)
+    store(updated)
+    return updated
+  }
+
+  /** Resolve a capped session: extra-round / proceed / stop-reset. */
+  async function resolveExceeded(
+    blockId: string,
+    stage: BrainstormStage,
+    choice: ResolveBrainstormExceededChoice,
+  ): Promise<BrainstormSession> {
+    const updated = await api.resolveBrainstormExceeded(
+      workspace.requireId(),
+      blockId,
+      stage,
+      choice,
+    )
+    store(updated)
+    return updated
+  }
+
+  return {
+    available,
+    sessions,
+    sessionFor,
+    backgroundStage,
+    isRunning,
+    isLoading,
+    isIncorporating,
+    openCount,
+    answeredCount,
+    allSettled,
+    canIncorporate,
+    canProceed,
+    load,
+    reply,
+    setItemStatus,
+    incorporate,
+    reReview,
+    proceed,
+    resolveExceeded,
+    // Patch the cache from a live `brainstorm` stream event.
+    upsert: store,
+  }
+})

package/app/stores/followUps.ts

@@ -0,0 +1,73 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import { useApi } from '~/composables/useApi'
+import { useWorkspaceStore } from '~/stores/workspace'
+import { useExecutionStore } from '~/stores/execution'
+
+/**
+ * The Follow-up companion action surface. The live item state lives on the run's Coder step
+ * (`step.followUps`) and is kept fresh by the execution stream, so the window reads items
+ * straight off the execution store — this store only wraps the decide actions (file / send
+ * back / answer / dismiss) and tracks which item is mid-action so the window can disable its
+ * buttons. The returned state is also pushed back into the execution store so the UI updates
+ * immediately even before the stream echoes the change.
+ */
+export const useFollowUpsStore = defineStore('followUps', () => {
+  const api = useApi()
+  const workspace = useWorkspaceStore()
+  const execution = useExecutionStore()
+
+  /** Item ids with an action in flight (drives per-row spinners / disabled buttons). */
+  const acting = ref<Set<string>>(new Set())
+  /** The last error message from an action, surfaced inline; cleared on the next action. */
+  const error = ref<string | null>(null)
+
+  function isActing(itemId: string): boolean {
+    return acting.value.has(itemId)
+  }
+
+  function mark(itemId: string, on: boolean) {
+    const next = new Set(acting.value)
+    if (on) next.add(itemId)
+    else next.delete(itemId)
+    acting.value = next
+  }
+
+  /** Run one decide action, reflecting the returned state onto the run's Coder step. */
+  async function act(
+    executionId: string,
+    itemId: string,
+    call: (ws: string) => Promise<unknown>,
+  ): Promise<void> {
+    error.value = null
+    mark(itemId, true)
+    try {
+      const state = await call(workspace.requireId())
+      // Reflect the authoritative state immediately (the stream will also echo it).
+      const instance = execution.getInstance(executionId)
+      const step = instance?.steps.find((s) => s.followUps?.enabled)
+      if (step && state && typeof state === 'object') {
+        step.followUps = state as typeof step.followUps
+      }
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Action failed'
+      throw e
+    } finally {
+      mark(itemId, false)
+    }
+  }
+
+  const fileItem = (executionId: string, itemId: string) =>
+    act(executionId, itemId, (ws) => api.fileFollowUp(ws, executionId, itemId))
+
+  const queueItem = (executionId: string, itemId: string) =>
+    act(executionId, itemId, (ws) => api.queueFollowUp(ws, executionId, itemId))
+
+  const answerItem = (executionId: string, itemId: string, answer: string) =>
+    act(executionId, itemId, (ws) => api.answerFollowUp(ws, executionId, itemId, answer))
+
+  const dismissItem = (executionId: string, itemId: string) =>
+    act(executionId, itemId, (ws) => api.dismissFollowUp(ws, executionId, itemId))
+
+  return { acting, error, isActing, fileItem, queueItem, answerItem, dismissItem }
+})

package/app/stores/pipelines.ts

@@ -48,6 +48,11 @@ export const usePipelinesStore = defineStore('pipelines', () => {
   const draftConsensus = ref<(ConsensusStepConfig | null)[]>([])
   /** Per-step estimate gating, kept index-aligned with `draft` (null ⇒ always run). */
   const draftGating = ref<(StepGating | null)[]>([])
+  /**
+   * Per-step Follow-up companion toggle, kept index-aligned with `draft`. Only meaningful on
+   * a `coder` step; `false` disables the companion there (default/true ⇒ enabled).
+   */
+  const draftFollowUps = ref<(boolean | null)[]>([])
   /** Organizational labels for the pipeline being assembled/edited. */
   const draftLabels = ref<string[]>([])
   const draftName = ref('New pipeline')
@@ -71,6 +76,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftThresholds.value.splice(index, 0, null)
     draftConsensus.value.splice(index, 0, null)
     draftGating.value.splice(index, 0, null)
+    draftFollowUps.value.splice(index, 0, null)
   }
 
   function addToDraft(kind: AgentKind) {
@@ -84,6 +90,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftThresholds.value.splice(index, 1)
     draftConsensus.value.splice(index, 1)
     draftGating.value.splice(index, 1)
+    draftFollowUps.value.splice(index, 1)
   }
 
   function moveInDraft(from: number, to: number) {
@@ -100,6 +107,8 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftConsensus.value.splice(to, 0, cons ?? null)
     const [gat] = draftGating.value.splice(from, 1)
     draftGating.value.splice(to, 0, gat ?? null)
+    const [fu] = draftFollowUps.value.splice(from, 1)
+    draftFollowUps.value.splice(to, 0, fu ?? null)
   }
 
   /** Whether the producer step at `index` currently has its companion attached after it. */
@@ -174,6 +183,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftThresholds.value = reorder(draftThresholds.value)
     draftConsensus.value = reorder(draftConsensus.value)
     draftGating.value = reorder(draftGating.value)
+    draftFollowUps.value = reorder(draftFollowUps.value)
   }
 
   /** Toggle the consensus mechanism on the draft step at `index` (default config / off). */
@@ -191,6 +201,12 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftGates.value[index] = !draftGates.value[index]
   }
 
+  /** Toggle the Follow-up companion on the draft (coder) step at `index` (default on → off). */
+  function toggleDraftFollowUps(index: number) {
+    // Default (null/true) is enabled, so the first toggle disables it (false); toggle back to null.
+    draftFollowUps.value[index] = draftFollowUps.value[index] === false ? null : false
+  }
+
   /** Enable/disable the draft step at `index` without removing it. */
   function toggleDraftEnabled(index: number) {
     draftEnabled.value[index] = draftEnabled.value[index] === false
@@ -203,6 +219,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftThresholds.value = []
     draftConsensus.value = []
     draftGating.value = []
+    draftFollowUps.value = []
     draftLabels.value = []
     draftName.value = 'New pipeline'
     editingId.value = null
@@ -216,6 +233,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftThresholds.value = pipeline.agentKinds.map((_, i) => pipeline.thresholds?.[i] ?? null)
     draftConsensus.value = pipeline.agentKinds.map((_, i) => pipeline.consensus?.[i] ?? null)
     draftGating.value = pipeline.agentKinds.map((_, i) => pipeline.gating?.[i] ?? null)
+    draftFollowUps.value = pipeline.agentKinds.map((_, i) => pipeline.followUps?.[i] ?? null)
     draftLabels.value = [...(pipeline.labels ?? [])]
     draftName.value = pipeline.name
     editingId.value = pipeline.id
@@ -240,6 +258,11 @@ export const usePipelinesStore = defineStore('pipelines', () => {
         : {}),
       // Only send gating when at least one step has gating enabled.
       ...(draftGating.value.some((g) => g?.enabled) ? { gating: [...draftGating.value] } : {}),
+      // Only send followUps when at least one step disables it (default is on, so only the
+      // explicit `false` opt-outs are worth persisting).
+      ...(draftFollowUps.value.some((f) => f === false)
+        ? { followUps: [...draftFollowUps.value] }
+        : {}),
       // Only send labels when there are any.
       ...(draftLabels.value.length ? { labels: [...draftLabels.value] } : {}),
     }
@@ -297,6 +320,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftThresholds,
     draftConsensus,
     draftGating,
+    draftFollowUps,
     draftLabels,
     draftName,
     editingId,
@@ -311,6 +335,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     toggleCompanion,
     toggleDraftGating,
     toggleDraftGate,
+    toggleDraftFollowUps,
     toggleDraftEnabled,
     toggleDraftConsensus,
     setDraftConsensus,

package/app/stores/ui.ts

@@ -135,6 +135,10 @@ export const useUiStore = defineStore('ui', () => {
     blockId: string
     instanceId: string | null
     stepIndex: number | null
+    // The brainstorm dialogue stage, set only when `view === 'brainstorm'` (its two agent
+    // kinds share one window). Derived from the step's agent kind on the pipeline path, or
+    // passed explicitly on an off-path open.
+    stage?: 'requirements' | 'architecture'
   } | null>(null)
 
   // Agent step-detail overlay: which pipeline step (a run instance + step index)
@@ -233,7 +237,20 @@ export const useUiStore = defineStore('ui', () => {
         ? agentKindMeta(step.agentKind).resultView
         : undefined
     if (view && instance) {
-      resultView.value = { view, blockId: instance.blockId, instanceId, stepIndex }
+      // The brainstorm window is shared by both stages; carry which one from the step's kind.
+      const stage =
+        view === 'brainstorm'
+          ? step?.agentKind === 'architecture-brainstorm'
+            ? 'architecture'
+            : 'requirements'
+          : undefined
+      resultView.value = {
+        view,
+        blockId: instance.blockId,
+        instanceId,
+        stepIndex,
+        ...(stage ? { stage } : {}),
+      }
       return
     }
     stepDetail.value = { instanceId, stepIndex }
@@ -456,10 +473,41 @@ export const useUiStore = defineStore('ui', () => {
   function openClarityReview(blockId: string) {
     resultView.value = { view: 'clarity-review', blockId, instanceId: null, stepIndex: null }
   }
+  function openBrainstorm(blockId: string, stage: 'requirements' | 'architecture') {
+    resultView.value = { view: 'brainstorm', blockId, instanceId: null, stepIndex: null, stage }
+  }
   // Open the service-spec window for a service frame (the inspector's "View Requirements").
   function openServiceSpec(blockId: string) {
     resultView.value = { view: 'service-spec', blockId, instanceId: null, stepIndex: null }
   }
+  // Open the Follow-up companion window for a run's Coder step (the blinking chip + the
+  // `followup_pending` notification). Resolves the Coder step index from the run when not
+  // given, so callers that only know the run can still open it.
+  function openFollowUps(instanceId: string, stepIndex: number | null = null) {
+    const execution = useExecutionStore()
+    const instance = execution.getInstance(instanceId)
+    if (!instance) return
+    // A pipeline may carry more than one follow-up-enabled Coder step, so don't blindly pick
+    // the first when no index is given: prefer the step that still has undecided items (the
+    // one the run is parked on), else the current step, else the first enabled one.
+    const resolveIdx = () => {
+      const pending = instance.steps.findIndex(
+        (s) => s.followUps?.enabled && s.followUps.items.some((i) => i.status === 'pending'),
+      )
+      if (pending >= 0) return pending
+      const current = instance.steps[instance.currentStep]
+      if (current?.followUps?.enabled) return instance.currentStep
+      return instance.steps.findIndex((s) => s.followUps?.enabled)
+    }
+    const idx = stepIndex ?? resolveIdx()
+    if (idx < 0) return
+    resultView.value = {
+      view: 'follow-ups',
+      blockId: instance.blockId,
+      instanceId,
+      stepIndex: idx,
+    }
+  }
   function closeResultView() {
     resultView.value = null
   }
@@ -594,7 +642,9 @@ export const useUiStore = defineStore('ui', () => {
     resetAiOnboarding,
     openRequirementReview,
     openClarityReview,
+    openBrainstorm,
     openServiceSpec,
+    openFollowUps,
     closeRequirementReview,
     openStepDetail,
     closeStepDetail,

package/app/types/brainstorm.ts

@@ -0,0 +1,55 @@
+// Brainstorm (structured-dialogue) wire types. Mirror of `@cat-factory/contracts`'
+// brainstorm.ts, kept in sync by hand like the rest of `~/types/*` (the SPA does not import
+// the backend package directly).
+//
+// A brainstorm agent runs a structured dialogue: it PROPOSES options with explicit
+// trade-offs (raised as review items), a human picks / steers / dismisses, and the picks are
+// folded into ONE converged direction. There are two stages (`requirements`, `architecture`)
+// served by one engine; a block may have one live session per stage.
+//
+// Structurally identical to a requirements review (the items share the same shape), so the
+// per-item types are reused from `~/types/requirements`; only the `stage` discriminator and
+// the converged document (`convergedDirection`) differ.
+
+import type {
+  RequirementReviewItem,
+  ReviewItemCategory,
+  ReviewItemSeverity,
+  ReviewItemStatus,
+} from '~/types/requirements'
+
+export type { ReviewItemCategory, ReviewItemSeverity, ReviewItemStatus }
+
+/** Which dialogue a brainstorm session drives. */
+export type BrainstormStage = 'requirements' | 'architecture'
+
+/** A brainstorm option is the same shape as a requirements-review item. */
+export type BrainstormItem = RequirementReviewItem
+
+/** Lifecycle of a brainstorm session — identical to the requirements review lifecycle. */
+export type BrainstormStatus =
+  | 'ready'
+  | 'incorporating'
+  | 'reviewing'
+  | 'merged'
+  | 'exceeded'
+  | 'incorporated'
+
+/** How a human resolves a session that hit its iteration cap. */
+export type ResolveBrainstormExceededChoice = 'extra-round' | 'proceed' | 'stop-reset'
+
+export interface BrainstormSession {
+  id: string
+  blockId: string
+  stage: BrainstormStage
+  status: BrainstormStatus
+  items: BrainstormItem[]
+  model: string | null
+  convergedDirection: string | null
+  /** Agent passes run so far (initial pass is 1; each re-run adds one). */
+  iteration: number
+  /** The agent-pass budget (from the task's merge preset; an extra round bumps it). */
+  maxIterations: number
+  createdAt: number
+  updatedAt: number
+}

package/app/types/domain.ts

@@ -20,6 +20,7 @@ import type { Notification } from './notifications'
 import type { RequirementReview } from './requirements'
 import type { ConsensusSession, ConsensusStepConfig, StepGating, TaskEstimate } from './consensus'
 import type { ClarityReview } from './clarity'
+import type { BrainstormSession } from './brainstorm'
 import type { MergeThresholdPreset } from './merge'
 import type { ModelPreset } from './model-presets'
 import type { PipelineSchedule } from './recurring'
@@ -256,6 +257,11 @@ export interface TestReport {
 /** The kinds of agents available in the agent palette. */
 export type AgentKind =
   | 'requirements-review'
+  // Brainstorm (structured-dialogue) gates: propose options with trade-offs and let the human
+  // converge. `requirements-brainstorm` runs before the requirements review; `architecture-
+  // brainstorm` before the architect. Both open the shared brainstorm window.
+  | 'requirements-brainstorm'
+  | 'architecture-brainstorm'
   | 'architect'
   | 'researcher'
   | 'coder'
@@ -390,6 +396,12 @@ export interface Pipeline {
    * always run. Used to make a companion conditional on the task estimate.
    */
   gating?: (StepGating | null)[]
+  /**
+   * Per-step Follow-up companion toggle, parallel to `agentKinds`: governs whether a `coder`
+   * step runs the future-looking Follow-up companion. `followUps[i] === false` disables it;
+   * `null`/`true`/absent ⇒ enabled (a Coder step gets it by default). Ignored on non-coder steps.
+   */
+  followUps?: (boolean | null)[]
   /** Free-form organizational labels for the library (filter/search). */
   labels?: string[]
   /** True when archived: kept but hidden from the default library view. */
@@ -583,6 +595,7 @@ export type WorkspaceEvent =
   | { type: 'requirements'; review: RequirementReview; at: number }
   | { type: 'consensus'; session: ConsensusSession; at: number }
   | { type: 'clarity'; review: ClarityReview; at: number }
+  | { type: 'brainstorm'; session: BrainstormSession; at: number }
   | { type: 'kaizen'; grading: KaizenGrading; at: number }
 
 /** Level-of-detail buckets driven by the canvas zoom level. Shallow → deep:

package/app/types/execution.ts

@@ -382,6 +382,47 @@ export interface PipelineStep {
    * Mirrors `runEnvironmentSchema`.
    */
   environment?: RunEnvironment | null
+  /**
+   * Live Follow-up companion state when this (coder) step has the future-looking companion
+   * enabled: the forward-looking items the Coder streamed (loose ends / side-tasks /
+   * questions) and the send-back loop budget. The chip blinks while any item is `pending`;
+   * the gate holds the pipeline until every item is decided. Mirrors `followUpsStepStateSchema`.
+   */
+  followUps?: FollowUpsStepState | null
+}
+
+/** What a streamed item is: a forward-looking follow-up or a clarifying question. */
+export type FollowUpItemKind = 'follow_up' | 'question'
+
+/** Lifecycle of a single follow-up / question item (mirrors `followUpItemStatusSchema`). */
+export type FollowUpItemStatus = 'pending' | 'filed' | 'queued' | 'answered' | 'dismissed'
+
+/** One forward-looking item the Coder surfaced (mirrors `followUpItemSchema`). */
+export interface FollowUpItem {
+  id: string
+  kind: FollowUpItemKind
+  title: string
+  detail: string
+  suggestedAction?: string | null
+  status: FollowUpItemStatus
+  /** The human's answer to a `question` item, or null while unanswered / not a question. */
+  answer?: string | null
+  /** Canonical external id of the filed ticket (e.g. "owner/repo#123"), when `filed`. */
+  ticketExternalId?: string | null
+  /** URL of the filed ticket, when `filed`. */
+  ticketUrl?: string | null
+  /** True once a queued / answered item was folded into a Coder loop-back. */
+  sentToCoder?: boolean
+  createdAt: number
+  updatedAt: number
+}
+
+/** Live Follow-up companion state on the Coder step (mirrors `followUpsStepStateSchema`). */
+export interface FollowUpsStepState {
+  enabled: boolean
+  items: FollowUpItem[]
+  loops?: number
+  maxLoops?: number
 }
 
 /** One failing CI check the gate's precheck saw (mirrors `gateFailingCheckSchema`). */

package/app/types/notifications.ts

@@ -15,6 +15,7 @@ export type NotificationType =
   | 'release_regression'
   | 'decision_required'
   | 'human_test_ready'
+  | 'followup_pending'
 export type NotificationStatus = 'open' | 'acted' | 'dismissed'
 
 /** The on-call agent's recommendation on a `release_regression`. */

package/app/utils/catalog.spec.ts

@@ -14,6 +14,8 @@ import {
 const AGENT_KINDS: AgentKind[] = [
   'requirements-review',
   'clarity-review',
+  'requirements-brainstorm',
+  'architecture-brainstorm',
   'bug-investigator',
   'task-estimator',
   'architect',