Skip to content

spec(epic): same pieces, different apps (FIX-2152) - #3783

Merged
jhoffner merged 5 commits into
mainfrom
claude/project-thread-h7gvq3
Oct 23, 2026
Merged

jhoffner merged 5 commits into
mainfrom
claude/project-thread-h7gvq3

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

A team that… Today After this epic
evaluates Flow State Must believe that Workforce is an operating system for agents. Shift Manager is the only app, and it works in a new way Opens two apps that work like Claude Code (session mode and threads mode) and Grok Bot. Both use the same pieces. Each app shows how little it adds
hardens the workforce package Cannot tell a gap in the package from an open product question when Shift Manager breaks Sees each break against a way of working that is known to be correct. Glue that an app needs is a gap in the package
tells the story (GTM) Must explain a new paradigm first Shows two familiar apps first, each with a "what this app adds" table. Then shows Shift Manager

Goal: two apps copy the core layout and interaction of Claude Code and Grok Bot. Each way of working passes one scripted session with a real model. App code is only configuration, React UI and a few small flows. All other needs are gaps in the package.

flowchart LR
  A["each lab · real model · durable store · a browser"] --> L1["leg a · session mode: 5 steps"]
  A --> L3["leg c · threads mode: 5 steps"]
  A --> L2["leg b · Grok Bot-style: 4 steps"]
  L1 --> T["what the person sees · thread, task pane, status board, worker list"]
  L3 --> T
  L2 --> T
  T -->|"every step · inventory has no other row"| P["PASS · the epic's goal is met"]
  C["control · notice taken only after the turn"] -.-> L1
  L1 -.->|"under the control"| F["must FAIL · step 4 lands after the turn"]
Loading

The closure issue FIX-2156 proves it on one main commit. Its control turns off the mid-turn notice, and step 4 of leg a must then fail. Why this goal and not a smaller one: SPEC.md.

What's in the box: two labs made of config, React UI and small flows, over one set of package pieces, plus two package entries the gaps add. Not built: diffs, permissions, a harness picker, landing copy

Each lab adds only its layout, its worker files and a few small flows. A need goes to the package, not into the lab.

Why now. The one task primitive (FIX-2056) is on main except its closure, and worker messaging (FIX-1989) is merged. Jake approved the specs, the UI design and the front ends on 2026-10-23. Only the wiring waits for the refactors.

The set (as of 2026-10-23, live state in Linear):

  • FIX-2153 · Claude Code-style lab, session mode. First.
  • FIX-2157 · the same app, threads mode: a coordinator and a status board. Its spec follows FIX-2153's. Its wiring also waits for FIX-2058.
  • FIX-2154 · Grok Bot-style lab. Second, and blocked by FIX-2070 (Messages).
  • FIX-2158 · gap: the workforce client lists a person's sessions of one worker.
  • FIX-2159 · gap: a running request takes a settled notice before its next model call.
  • FIX-2156 · closure · required.

fsd-architect checked the gaps and the worker-talk view against main (answer, D3 correction). Session-to-session messaging, which the correction proposed, is filed outside this epic as FIX-2160: no script needs it, and it conflicts with rule 21 (a message never addresses a raw session).

Who owns what: seven rules, each with one owner. FIX-2153 owns the five lab rules; FIX-2158 and FIX-2159 own their mechanisms

Each rule has one owner. FIX-2153 owns the lab rules because it goes first.

Sign off

The goal, at that size: three scripts, 14 steps, with a real model, and an inventory with no other row. If wrong: the labs look correct on fixtures and prove nothing about the package.

The set's debt: up, by two private labs and two package entries. The labs are the evidence. Each entry is a gap that the next app gets for nothing. If wrong: two labs that nobody maintains.

A gap that blocks a lab's script is built in this epic · D1

D1: gaps that block a script are children of this epic, chosen, beside another epic later and a workaround in the lab. Decided by whether the epic can finish on its own work

It comes down to whether the epic can finish on its own work. Gaps join in one batch when each lab's spec merges; a later one needs your sign-off. If wrong: the epic grows by package work that another epic should own.

A background result reaches the main session during its turn · D2

D2: a result is taken before the main session's next model call, chosen, beside after the turn as today. Decided by working the way Claude Code does

It comes down to working the way Claude Code does. It amends rule 7 of the coordination concept: an ending's notice gets a third destination. If wrong: step 4 of the session-mode script changes, and the lab works differently from the app it copies.

Front ends are built now, on fixtures behind one adapter · D4

D4: fixtures behind one adapter, chosen, beside waiting for the refactors and wiring to today's names. Decided by finishing the UI before the wiring

It comes down to finishing the UI first. If wrong: part of the UI is done again when a shape changes.

Decided as engineering, no sign-off: D3, a lab session is an ordinary session of the worker. Nothing enforces one conversation per worker; the derived session stays the default conversation, and FIX-2158 only lists the others.

Open: nothing beyond the sign-off. A merge of this PR approves the rule 7 amendment (D2).

Reviewers · look here

  • ER-1 (DECISIONS.md, Who owns what): do the path rules and caps catch glue, and is the manual gate the right home for the rest?
  • D2: is the transferred take/handle/ack enough to keep each ending heard once?
  • The set: is a gap that the labs will need missing? The closure must not pass while one is unbuilt.

SPEC.md · DECISIONS.md · FIX-2152 · handle agent-mailbox#46

How to review this

This is an epic-spec: the shared objective and cross-cutting decisions for a set of
issues, in a retained document set. It is not any one issue's implementation design, and it
is not a schedule.

In scope to challenge:

  • The objective and the goal in SPEC.md — is this body of work worth doing, and is the
    goal the real need at full size, or a smaller one the set could meet while the need stays
    unmet? Would the closure issue's check fail if the goal were not met?
  • Whether the set overbuilds. Each issue can earn its place while the whole is too much.
    That question can only be asked here.
  • The set's debt in SPEC.md — something the set overlaps and doesn't name, or adds and
    doesn't list.
  • A cross-cutting decision in DECISIONS.md — shared surface, naming, sequencing, contracts.
  • A rule in DECISIONS.md → Who owns what with no owner, or two.
  • A missing issue the objective implies, or one in the set that doesn't serve it.

Out of scope — owned by the individual issue specs:

  • Any single issue's approach, architecture, file layout, or test plan.
  • Anything that touches exactly one issue. It belongs on that issue's spec PR.
  • The figures, at the pixel level, and routine status movement since the dated snapshot.
  • POC production polish. End-state experiments under the owning spec's poc/
    show shape and scoping, not shippable implementation. Directional evidence, experimental
    isolation and absence of secrets/generated dependencies remain in scope.

Feedback in the second list is routed to the issue it concerns as an implementer note, not
folded in here.

Required repository checks, approvals and review-thread policy still govern merge.
Optional comments are triaged, not a reason to grind to zero or restart the design review.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KwpAiiUuq5pNkkmtNnc5pv

Epic spec for two labs built only from the workforce package plus config,
React UI and small flows: a Claude Code-style app (session and threads
modes) and a Grok Bot-style app. Sets the bar, the inventory, the gap rule,
and the closure FIX-2156.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KwpAiiUuq5pNkkmtNnc5pv
@vercel

vercel Bot commented Oct 23, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 23, 2026 9:29pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 23, 2026 9:29pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 23, 2026 9:29pm UTC

Request Review

@jhoffner jhoffner self-assigned this Oct 23, 2026
@linear-code

linear-code Bot commented Oct 23, 2026

Copy link
Copy Markdown

FIX-2152

Copy link
Copy Markdown
Collaborator Author

@codex review

Please look closely at three things. First, whether D2 (a settled notice taken before the filer's next model call, through the existing steer path) is consistent with the one-ending rule and one request per session in docs/internal/design/workforce-coordination-concept.md. Second, whether the "Already here" claims in SPEC.md match main. Third, whether ER-1's inventory bar can actually be checked.


Generated by Claude Code

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 23, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-23T21:29:47.779542Z a070af5 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (spec-level, direction only)

I read SPEC.md and DECISIONS.md and checked the code each decision cites. The file references all exist, and the direction is sound. Four points below are worth folding in before merge. The rest I'd leave to the child specs.

Fold in before merge

1. D2 reuses the steer path less directly than the spec says. DECISIONS.md says a filer's notice "can take the same path" as steer-context.ts.

  • steer-context.ts is built for an assignee's task turn. It imports currentWorkerClaim and isTaskTurn and reads steers addressed to that claim.
  • The main session is a filer's conversation turn, not a task turn. The gap issue needs a new prepare-step context entry on the conversation turn that reads settled notices.
  • The mechanism is shared, but the entry is new. That sizes the gap larger than "makes a filer's running request take its notices".
  • ER-6's "once, never both" needs an atomic claim between the mid-turn take and the deferred notice turn. task-settled.ts already has noteSeen over ctx.session.atomicState, keyed per notice, with TASK_NOTICES_STATE. Name it in ER-6 as the intended arbiter so the gap doesn't invent a second one.
  • I haven't run this. Open Q3 ("does D2 break one request per session / FIX-2077?") is a disputed behavioral claim, and the settle-claim skill exists for that. A throwaway POC for the filer-side take would settle it before D2 reaches the owner as a sign-off. That's cheaper than finding out at FIX-2153's wiring.

2. The ER-5 adapter is a fourth kind of code, so ER-1's check fails on its own design.

  • ER-1 allows only config, React UI and small flows, and the check "fails on any file that fits none of the three".
  • The adapter module (ER-5) is none of these. It is also the one file that changes at wiring.
  • After wiring it is a thin set of workforce-client calls, which is exactly the shape the inventory exists to measure.
  • Classify it explicitly, for example as "UI data layer: calls package exports only, with a line cap". Otherwise the first inventory has an other row, or the check gets a quiet exception, which is how glue gets in.

3. ER-1's bar can be gamed, and ER-3 pushes UI duplication into the labs.

  • "At most a few flows, each under 200 lines, composed only from package exports" can be met by splitting one flow into five. "Composed only from package exports" is also only checkable if the check inspects imports and block construction, not just line counts.
  • State what the check parses (imports resolve to exports maps; flow count cap). Otherwise ER-1 is a convention, not the gate the closure relies on.
  • ER-3 says "a piece of UI both need is copied". The repo already has a sharing path for that: the packages/ui registry and fsdev ui add. Copying the thread and composer components into two labs recreates the duplication the registry exists to prevent. Prefer "shared UI goes to the registry (a package gap per ER-4); only app-specific UI stays in the lab". That also makes each inventory show what the app actually adds.

4. Question whether the closure should block on FIX-2157.

  • Leg c (threads mode) is specced after FIX-2153 and builds on its app. It is the largest dependency chain: FIX-2153's session mode, FIX-2154 and FIX-2058 must all land first.
  • The core proof (the same pieces reproduce Claude Code's session mode and Grok Bot) is carried by legs a and b.
  • Suggest the closure be required for a and b, with leg c as a required-but-separable child that doesn't hold the closure if its spec shows a package gap bigger than D1's "can the epic finish on its own work" test. Otherwise D1 plus a late-arriving gap in 2157 can stall an epic whose headline proof is already met.

Noted, no change needed

  • D3: the epic's reading (several sessions of one worker is a new entry point, not a new concept) matches client.ts. It exposes only roster, findWorkerSession, ensureWorkerSession and standingRules. Defer to fsd-architect.
  • The "skills don't start workers" decision matches skill-md.ts refusing agents: and workers:.
  • Leg b's control ("drop B's sendMessage from its tools") and leg a's control are good: each must fail for the reason named.

Architecture opportunity (only because the gap issues will touch it)

The mid-turn gap (D2) and the existing steer take both read "things that arrived while the request ran" before a model call. When the gap is built, it should extend that shared take rather than add a parallel one. That keeps one place that answers "what has this running request not yet seen". I'm not recommending a refactor now. The gap issue's spec should say which side owns the shared helper.


Generated by Claude Code

D3 becomes one optional conversation key (FIX-2158), not workstreams;
D2 takes the architect's conditions (FIX-2159); FIX-2154 is blocked by
FIX-2070; D2 and D3 are concept amendments for the owner's sign-off.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KwpAiiUuq5pNkkmtNnc5pv

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify review (spec-only)

This epic is directionally sound and already matches the lean workforce epic shape (FIX-2056 / FIX-2058): SPEC + DECISIONS, ER table in decisions, coordination seams, no PLAN/BR split. The extra surface vs peers is mostly D4 (fixtures-first UI) and three decision SVGs — justified if Jake’s 2026-10-23 sequencing call stays non-negotiable.

What I would not simplify away (the spec already argues these well):

  • Two labs — Kitchen Sink / Shift Manager are the wrong product story; the GTM/evaluation table needs two familiar shells plus honest per-app inventories (ER-3 “no shared code” is painful but coherent with that goal).
  • D2 mid-turn settled notices — reusing prepareStep / steer-context is the right package seam; building a third concurrency model would be worse.
  • Threads mode (FIX-2157) — if Claude Code parity requires session + threads, a second leg is fair; folding it only helps process (fewer epic children), not product proof.

Where complexity crept in (worth trimming in a follow-up amend, not a rewrite)

  1. Same fork, many surfaces — D2, ER-6, the mid-turn gap row, Open §3, and leg-a control failure all describe one behavior. Child gap specs can own mechanics; the epic could keep D2 + one acceptance line and drop ER-6’s duplicate “deferred notice turn” prose (or make ER-6 a one-line pointer to D2).
  2. D1 + “each lab’s spec may add more” — logically unbounded epic growth. D1 already has the “epic-sized gap” escape hatch; consider adding an explicit cap at direction approval: script-blocking children filed in one batch per lab when that lab’s spec merges (everything else → project link only). That preserves D1 without surprise scope.
  3. D4 × ER-3 — two isolated adapters/fixture sets while FIX-2056/2058/2070 names move is the highest delivery risk, not a wrong call. Mitigations that don’t violate ER-3: FIX-2153 spec documents adapter layout FIX-2154 copies; shared test-only harness for anti-game waits (event-driven, not sleep loops); optional FIX-2056-style POC on settled-notice + prepareStep before wiring PRs.
  4. Open vs decided — D3/ER-7 and FIX-2154 message view (Open §4) are still architect-pending while UI starts under D4. Fine for layout mocks; adapter functions that encode D3 semantics should wait until mailbox #46 is folded, or the epic should say fixtures for those gaps are stub UI only until then.
  5. Figures — decision tree (mermaid) + d1/d2/d4 SVGs + ownership SVG largely restate the D tables. If spec-figures policy allows, one diagram (end-state or ownership) plus prose tables would cut maintenance; not blocking.

Skipped (larger product/process forks — only if you reopen the brief)

  • Package epic (D2 + D3) then lab-only epic — clearer merge order, splits narrative.
  • Defer threads to post-closure — drops leg c from the 14-step bar.
  • UI after refactors (reject D4) — contradicts approved sequencing.

Verdict

Approve for direction: two labs, two known package gaps, inventory discipline, and closure on real-model scripts are the right bar for “same pieces, different apps.” Address the duplication and D1 batching nits when child specs land; resolve Open items before wiring adapters that bet on D3/message-view semantics.

No changeset needed (spec only).

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/epics/FIX-2152/SPEC.md Resolved
Comment thread specs/epics/FIX-2152/SPEC.md Resolved
Comment thread specs/epics/FIX-2152/DECISIONS.md Resolved
Comment thread specs/epics/FIX-2152/DECISIONS.md Resolved
Comment thread specs/epics/FIX-2152/DECISIONS.md Resolved
Comment thread specs/epics/FIX-2152/DECISIONS.md Resolved
Comment thread specs/epics/FIX-2152/DECISIONS.md Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2d86ce462b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread specs/epics/FIX-2152/DECISIONS.md Resolved
Comment thread specs/epics/FIX-2152/SPEC.md Resolved
Comment thread specs/epics/FIX-2152/DECISIONS.md Resolved
Comment thread specs/epics/FIX-2152/SPEC.md Resolved
…FIX-2152)

D3 needs no model change: a lab session is an ordinary session of the
worker, and FIX-2158 only lists them. Session-to-session messaging goes
to FIX-2160, outside the epic (rule 21). ER-1 gets path rules and caps;
FIX-2058 is marked planned; D2 names the transferred notice transaction;
D1 batches gaps at each lab's spec merge.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KwpAiiUuq5pNkkmtNnc5pv

Copy link
Copy Markdown
Collaborator Author

@codex review

Second round, on 7483234. Please check that ER-1's path rules and caps can actually be checked, and that D2's transferred take/handle/ack keeps each ending heard exactly once.


Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7483234fe8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread specs/epics/FIX-2152/DECISIONS.md Resolved
Codex round 2: a take in a task-backed session would skip that task's
own ending work in the queued onTaskSettled.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KwpAiiUuq5pNkkmtNnc5pv

Copy link
Copy Markdown
Collaborator Author

@codex review

Round 3, on a070af5. The only change is in D2: a notice is taken only by a conversation request in a session that no task backs. Please check that this closes the double-handling and skipping you found, and doesn't open a new path.


Generated by Claude Code

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KwpAiiUuq5pNkkmtNnc5pv
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Swish!

Reviewed commit: a070af583f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants