Repository navigation
spec(epic): same pieces, different apps (FIX-2152) #3783
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
2d86ce4
spec(epic): same pieces, different apps (FIX-2152)
claude 5a2bc88
spec(epic): fold fsd-architect's answers into FIX-2152
claude 7483234
spec(epic): fold review round one and the architect's D3 correction (…
claude a070af5
FIX-2152: D2 takes a notice only in a session not backed by a task
claude a5261b9
FIX-2152: ER-5 fixtures use a plain marker, not issue ids (BP-006)
claude File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,157 @@ | ||
| # FIX-2152 · Same pieces, different apps: a Claude Code-style lab and a Grok Bot-style lab | ||
|
|
||
| **Spec** · [Decisions](DECISIONS.md) | ||
|
|
||
| ## Three teams, before and after | ||
|
|
||
| | A team that… | Today | After this epic | | ||
| |---|---|---| | ||
| | **evaluates Flow State** | Has to believe that Workforce is an operating system for agents. Shift Manager is the only app, and its way of working is new | Opens two apps that work the way Claude Code (in its session and threads modes) and Grok Bot do, built from the same pieces, and reads how little each app adds | | ||
| | **hardens the workforce package** | When Shift Manager breaks, can't tell a gap in the package from an open product question, because Shift Manager mixes both ways of working | Sees each break against a way of working that is already known to be right. Any glue an app needs is a gap filed against the package | | ||
| | **tells the story (GTM)** | Explains a new paradigm first | Shows two familiar apps first, with a "what this app adds" inventory for each, and then Shift Manager as what the same pieces make possible | | ||
|
|
||
| **Why now.** The one task primitive (FIX-2056) is on `main` except its closure (FIX-2087), and | ||
| worker messaging (FIX-1989) is merged. Jake approved starting specs and UI design on 2026-10-23, | ||
| and on the same day approved building the front ends before the refactors land. Only the wiring | ||
| waits. | ||
|
|
||
| ## The goal, and how we'll know it's met | ||
|
|
||
| **Two apps that copy the core layout and interaction of Claude Code and Grok Bot pass one | ||
| scripted session per way of working with a real model: Claude Code's session mode and threads | ||
| mode, and Grok Bot. App code is only configuration, React UI and a few small | ||
| flows, and every other need is a gap filed against the package.** | ||
|
|
||
| | Is it the right goal? | | | ||
| |---|---| | ||
| | **The real need** | Proof that the package's pieces reproduce ways of working people already trust, and a list of where they don't. Goal 1, validate through real usage; goal 4, keep the foundation honest | | ||
| | **Smaller, and rejected** | "The apps look right." A front end on fixtures meets it, while the package can't run either session. "One lab." Only two apps on the same pieces show that the UI and config are the only difference | | ||
| | **Not done if** | A lab carries code that is not config, UI or a small flow (its inventory has an *other* row) · a lab imports a package's internals · a gap is solved in a lab instead of in the package · a scripted step passes only on fixtures · a closure bug is open | | ||
|
|
||
| ```mermaid | ||
| 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"] | ||
| ``` | ||
|
|
||
| | How we verify | | | ||
| |---|---| | ||
| | **Goal check** | The closure issue's (FIX-2156), on one `main` commit after every other child merges | | ||
| | **Signal** | Leg a, FIX-2153's script: you ask the main session; it does part of the work; it starts 2 background tasks; one result shows in the main thread while that turn is still running; you stop the other task by asking the main session. Leg b, FIX-2154's script: you talk to worker A; A messages worker B; B's reply reaches A while you are still talking to A; the conversation stays coherent over a long session. Leg c, FIX-2157's script: you ask the main session; it starts 3 threads; one waits on you for a decision; one becomes ready for review; you resolve it. Plus each lab's inventory | | ||
| | **Anti-game** | Assert on what a person sees in the browser, and on task rows read through public task actions. Never on a lab's own state | | ||
| | **Control that must fail** | Leg a with the mid-turn notice off ([D2](DECISIONS.md#d2)): step 4 lands after the turn. Leg b with B's `sendMessage` dropped from its tools: A never hears B. Leg c with the main worker's delegates removed: no thread starts | | ||
|
|
||
| **Lead measure:** scripted steps that pass on `main` with a real model, of 14 (5, 5 and 4). **0 today.** | ||
|
|
||
| ## What's in the box | ||
|
|
||
|  | ||
|
|
||
| The fence holds the features each original app has that this epic leaves out. The arrow down | ||
| is the rule that makes the inventory honest: a need goes to the package, not into the lab. | ||
|
|
||
| **Docs:** each lab's README carries its inventory and how to run it. No `apps/docs` page in this | ||
| set; the landing page is GTM's. | ||
|
|
||
| ## The set · as of 2026-10-23 | ||
|
|
||
| The reviewed snapshot; live state is in Linear. | ||
|
|
||
| | Issue | Delivers | Blocked by | | ||
| |---|---|---| | ||
| | [FIX-2153](https://linear.app/fixpoint-labs/issue/FIX-2153) · Claude Code-style lab | Spec and UI design; the front end on fixtures now; the wiring and its scripted session after the refactor | FIX-2056 (wiring only); the gaps it files ([D1](DECISIONS.md#d1)) | | ||
| | [FIX-2157](https://linear.app/fixpoint-labs/issue/FIX-2157) · Claude Code-style lab, threads mode | A second mode of FIX-2153's app: the main session hands everything to background threads, and the right pane is a status board. Spec after FIX-2153's | FIX-2153; FIX-2056 and FIX-2058 (wiring only) | | ||
| | [FIX-2154](https://linear.app/fixpoint-labs/issue/FIX-2154) · Grok Bot-style lab | The same, second. Rides worker messaging (FIX-1989), written against FIX-2070's names | FIX-2056 (wiring only); FIX-2070, whose message row its worker-talk view reads; the gaps it files | | ||
| | [FIX-2158](https://linear.app/fixpoint-labs/issue/FIX-2158) · list a person's sessions of one worker | A list on the workforce client, and the concept line that the derived conversation is the default, not the only one ([D3](DECISIONS.md#d3)) | — | | ||
| | [FIX-2159](https://linear.app/fixpoint-labs/issue/FIX-2159) · a result reaches a running turn | A filer's running request takes a settled notice before its next model call, as a delivery mode of the one ending path ([D2](DECISIONS.md#d2)) | Jake's amendment (D2) | | ||
| | [FIX-2156](https://linear.app/fixpoint-labs/issue/FIX-2156) · closure · **required** | The QA plan, run on one `main` commit | every other child | | ||
|
|
||
| Two labs, one with two modes, two gaps known before review, and a closure. fsd-architect checked | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| both gaps against `main` and agreed their shape; each lab's spec may add more. | ||
|
|
||
| ## How the issues flow into each other | ||
|
|
||
| ```mermaid | ||
| flowchart LR | ||
| R["FIX-2056 · one task primitive · consumed"] -.-> A | ||
| M["FIX-1989 · worker messaging · consumed"] -.-> B | ||
| N["FIX-2070 · Messages · consumed"] -.-> B | ||
| G1["FIX-2158 · list a person's sessions of one worker"] -->|"the session list"| A["FIX-2153 · Claude Code-style lab"] | ||
| G1 -->|"the session list"| T | ||
| G2["FIX-2159 · a result reaches a running turn"] -->|"step 4"| A | ||
| I["FIX-2058 · one Inbox · consumed"] -.-> T | ||
| A -->|"the app, its mode switch and its task reads"| T["FIX-2157 · threads mode"] | ||
| A -->|"the inventory check and the setup pattern"| B["FIX-2154 · Grok Bot-style lab"] | ||
| A --> C["FIX-2156 · closure"] | ||
| B --> C | ||
| T --> C | ||
| ``` | ||
|
|
||
| An edge is what one issue hands the next. FIX-2153's and FIX-2154's specs and front ends start | ||
| at once; FIX-2157's spec follows FIX-2153's, and its build follows FIX-2153's session mode and | ||
| FIX-2154. FIX-2154 copies FIX-2153's setup pattern and shares no code with it | ||
| ([ER-3](DECISIONS.md#who-owns-what)). FIX-2157 is a mode of FIX-2153's app, so it shares that app's | ||
| code. | ||
|
|
||
| ## What stays as it is | ||
|
|
||
| - **The worker model.** A lab adds no kind of worker and no role. The Claude | ||
| Code-style main worker is a `manager` on the agent flow in session mode and a `coordinator` in | ||
| threads mode; each Grok Bot-style worker is an ordinary worker with one conversation | ||
| ([D3](DECISIONS.md#d3)). A background copy of the main worker is a second hired worker on the | ||
| same flow, which is configuration. | ||
| - **Skills.** A skill can't start a worker: `agents:` and `workers:` frontmatter stay refused | ||
| (`orchestration/src/skills/skill-md.ts`). A skill that "starts a worker" tells the model to | ||
| `createTask` for a named delegate, which is the package's one way to start work. | ||
| - **Shift Manager**, its shell and its Lab contract. The labs use the same launch contract | ||
| (`fsdev dev --app`) and the same theme, and change neither. | ||
| - **Core and engine.** Nothing in this set goes below the workforce and orchestration packages. | ||
|
|
||
| ## What's already here, and the debt | ||
|
|
||
| | Already here | What the set does with it | | ||
| |---|---| | ||
| | The five task tools, the waited `getTask`, `updateTask({ message })` and cancel (FIX-2056) | **Builds on.** Background tasks, stopping a task through the main session, and steering | | ||
| | Routed tasks, the coordinator flow and the task-board statuses (FIX-2083) | **Builds on.** Threads mode's threads and its *Working* and *Resolved* columns | | ||
| | `waitForUser` and the hold on questions (FIX-2058, planned: specs merged, not on `main`) | **Builds on**, once landed. Threads mode's *Waiting on you* and *Ready for review* columns; FIX-2157's wiring waits on it | | ||
| | `messageWorker` and `onWorkerMessage` (FIX-1989); `sendMessage` and `receive` (FIX-2070, planned) | **Builds on.** FIX-2154 is written against FIX-2070's names | | ||
| | The agent flow's planned turn (`board.planned`), where one worker does work and files work | **Builds on.** The main session that works and delegates | | ||
| | A worker's sessions: the derived default conversation, and any other session on its flow, which the create check already accepts (`workforce/src/workers/installation.ts`) | **Extended** by FIX-2158's list. Workstreams (FIX-1883, opened by `openWorkstream` or a coordinator) are not used: they need a project and a lead ([D3](DECISIONS.md#d3)) | | ||
| | `@flow-state-dev/design-system` and the `packages/ui` registry | **Builds on.** The labs' only theme and components | | ||
|
|
||
| | The debt | | | ||
| |---|---| | ||
| | **Adds** | Two private labs under `labs/` · one list call on the workforce client · one delivery mode on the ending path | | ||
| | **Removes** | Nothing | | ||
|
|
||
| **Net: up, by two labs and two package entries.** The labs are the evidence the epic exists to | ||
| produce. Each package entry is a gap the labs proved, and the next app gets it for nothing. | ||
|
|
||
| ## Sign off | ||
|
|
||
| **[The goal](#the-goal-and-how-well-know-its-met):** three scripts, 14 steps, with a real model, | ||
| and an inventory with no *other* row. **[The debt](#whats-already-here-and-the-debt):** up, by | ||
| two labs and two package entries. | ||
|
|
||
| 1. **[D1](DECISIONS.md#d1) · A gap that blocks a lab's script is a child of this epic and is | ||
| built here.** If wrong: the epic grows by package work that another epic should own. | ||
| 2. **[D2](DECISIONS.md#d2) · A background result reaches the main session inside its running | ||
| turn.** If wrong: step 4 of the Claude Code-style script is dropped, and the lab works | ||
| differently from the app it copies. | ||
| 3. **[D4](DECISIONS.md#d4) · Front ends are built now, on fixtures behind one adapter, and the | ||
| fixtures are deleted at wiring.** If wrong: some UI is redone when the refactor changes a | ||
| shape. | ||
|
|
||
| **Open, the owner's:** none beyond the sign-off. D2 amends rule 7 of the coordination concept, | ||
| and the merge of this PR approves it. Session-to-session messaging (FIX-2160) is filed outside | ||
| this epic for the owner to place. | ||
|
|
||
| Epic · 2 labs (one in two modes), 2 known gaps and a closure · Workforce: Shift Manager · Goal 1, validate through | ||
| real usage · Goal 4, keep the foundation honest | ||
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.