Repository navigation
spec(FIX-1770): Run Shift Manager against your own Lab with one command, with a dev mode - #2734
Conversation
…nd, with a dev mode Retained spec set: fsdev gains a generic app hook (--app, --host, --watch), @flow-state-dev/node gains two generic page options, and Shift Manager is published as a thin CLI over the hook. Includes the esm-reload POC. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Second-look and architecture review (direction only)The shape holds up. The generic hook sits in fsdev and policy plugs in as page meta, which keeps Above the bar1. S5: the supervisor may be mostly
2. S2/S6: the plan doesn't cover Vite's HMR websocket.
3. D3: PR-C holds too much (S7–S13).
Notes
Anything below the bar (names, module layout, option naming) is left to the implementer. Generated by Claude Code |
There was a problem hiding this comment.
Simplify review (spec FIX-1770)
What we're judging: Whether this spec is the smallest credible path to “install Shift Manager, one command, --dev restarts my Lab on save” without copying start.mts into every app.
Verdict: Approve direction. D1 (fsdev owns the hook, node stays generic), D2 (built pages for npm; Lab restart is what outside users need), and D3 (three PRs) hang together. The esm-reload POC correctly closes in-process reload and justifies process restart. I don't see a blocking spec incoherence.
The work is large relative to the issue title (13 surfaces, 26 BRs) but proportionate if the real deliverable is a reusable “app beside a Lab” hook, not only Shift Manager on npm. If you only cared about npm + restart, you could ship publish + node --watch first and defer --app / --host / Vite-from-source — that would be faster but would violate the layer rule and repeat start.mts for the next app.
Where complexity might be trimmed (non-blocking)
-
--watchimplementation shape — PLAN says “supervisor restarts the serving child” while the POC settles onnode --watchon the import graph. Worth one explicit sentence in PLAN (or Decided): prefer wrapping the dev entry withnode --watchand a single watch authority; avoid a second chokidar/fs.watch layer unless Vite temp-config loops force it (you already flag that at implement time). -
Dual meaning of
--dev— For installs,--dev= Lab restart + built pages; in a checkout, it also turns on Vite for Shift Manager pages (S6, BR-20–22). That’s coherent with D2 but is the densest part of PR-B and the docs table. Optional fork (product, not required): document npm--devas Lab-only and keep page HMR onpnpm devonly, deferring or narrowing S6. I’m not sure that’s better for in-repo ergonomics; flagging it in case PR-B cost matters. -
nodesurface (S1 + S2) — Two newserve()options (meta map + Connect handler) may both be necessary for Vite index + static assets. If implementers can serve checkout pages with handler-only and call a shared inject helper internally, you might ship one public option — only if it doesn’t fight the “one injection path” guardrail. -
Docs duplication — DOCS asks for site
overview.mdandpackages/shift-manager/README.md“Run it” verbatim. Fine for launch; consider “site canonical, README links” later to avoid three-way drift withcli.md. -
Implement-time perf (spec gap, not direction) — When implementing S5/S6: debounce/coalesce restarts under save bursts, one Vite server per child, cap success-path restart logging. None of this needs to block spec merge.
Alternatives considered (simpler cuts)
| Cut | Tradeoff |
|---|---|
Publish + node --watch before fsdev dev --app |
Faster npm; generic hook and “no Workforce in fsdev” slip a release |
No shift-manager bin — fsdev dev --app @flow-state-dev/shift-manager |
Fewer surfaces; weaker branded one-liner for outsiders |
| Split Lab restart vs page HMR across flags/scripts | Clearer npm story; may reintroduce two-terminal dev for SM authors unless pnpm dev bundles both |
Reuse: Implementation should mostly extend executeDevCommand / resolveDevToolAssets patterns and lift double-serve() from start.mts, not reimplement. Packed-install fixture beside serve-devtool.mjs is the right CI template.
What's asked of you: No must-fix before merge from this review. If you amend the spec before approval, the highest-leverage clarifications are (1) watch = node --watch by default and (2) whether dual --dev semantics stay as written or you narrow S6 in PR-B scope.
Sent by Cursor Automation: Review For Best Approach
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3ff093af9f
ℹ️ 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".
… override, patch changesets) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S


npx shift-manager --config ./fsdev.config.mts. Nothing to build--dev. A save restarts the Lab--devstart.mtsfsdev dev --app <package>. fsdev knows nothing about the appGoal: a person outside this repository installs Shift Manager and opens their own Lab in the browser with one command and no build. With
--dev, a saved change to the Lab shows without a manual restart.Check:
goals/shift-manager/it-runs-from-an-install/, model n/a. Controls:GOAL_CONTROL=no-page-configmust fail leg a, andGOAL_CONTROL=no-watchmust fail leg b. Why this goal and not a smaller one: SPEC.md.On the left, one lab script does all the work. On the right, fsdev does the generic work, below the framework line.
How:
fsdev dev --appserves the pages of an app, the Lab API on the same origin, and the DevTool on a second port.--watchrestarts the Lab on a change. Shift Manager publishes a small command over this hook.Sign off
The goal, at that size. If wrong: we publish a package that works only in a checkout.
fsdev owns the hook, and node gets only two generic page options · D1
It comes down to the production install: if node owns the hook, Vite and a file watcher go to all servers. If wrong: dev tools in a production host, or a hook that each app writes again.
The package ships built pages only, and --dev restarts the Lab of the user · D2
It comes down to who edits what: outside users edit their Lab, not Shift Manager. If wrong: outside users cannot change the screens without a clone of the repository.
Three PRs in sequence: the hook, then watch, then the published package · D3
It comes down to review size: one PR mixes a host change, a supervisor and a package move. If wrong: nothing installs until the third PR merges.
Open: none. D1 is the one to weigh. News, hard to reverse: this is the first npm publish of
@flow-state-dev/shift-manager. An npm name is permanent. Reasoning: DECISIONS.md. Cases: BUSINESS-RULES.md.Reviewers · look here
poc/esm-reload/). Is a page reload on each save acceptable?Not here: hosting Shift Manager as a deployed team service. The
fsdev gendependency on Workforce is a follow-up.Spec · Decisions · Rules · Plan · Docs · Evolution · Linear FIX-1770 · project Workforce: Shift Manager, no epic · builds on FIX-1662 and FIX-1649 · merges after human approval and required checks
How to review this — altitude, what's in scope, what's deliberately unsettled
This is a direction set, not an implementation. Reviewing it well means
answering one question: is this the right approach?
In scope to challenge:
SPEC.md— is the goal the real need at full size,for the people named, or a smaller goal that would let us call this done early? Would the
named check fail if the goal were not met?
docs/philosophy.md?DECISIONS.md— that's the sign-off surface.BUSINESS-RULES.mdmisses, or a rule that would invalidate the design.DOCS.mdand their fit with the rules; a missing ormisleading lineage claim in conditional
EVOLUTION.md.Out of scope — deliberately unsettled here, and owned by the implementing agent:
PLAN.mdpins on purpose.PLAN.mdleft open on purpose — it is directional by design, and a gap at thataltitude is intended, not an omission.
or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
decisions don't say is.
PLAN.mdmay include a rough pseudocode sketchshowing the shape of the proposed solution. It is knowingly incomplete, is not real code,
and is not what will ship. Review it for directional viability only. Do not report
that it lacks error handling, omits edge cases, names things that don't exist in the repo, or
wouldn't build: all of that is true on purpose.
poc/are retained,not production code. Read them for directional evidence, not production completeness.
Their isolation from production/default discovery and absence of secrets or generated
dependencies are in scope; retention is not permission to weaken repository checks.
One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.
Feedback in the second list is welcome and gets recorded verbatim in
PLAN.md → Notes from reviewfor the implementer to weigh against real code. It will not be argued with, and itwill not be folded into the design prose. Please don't re-raise it: one mention is enough.
The one exception is the sketch and the POC. Line-level feedback on either is dropped, not
recorded — there is nothing for an implementer to weigh about code that isn't shipping. Feedback
about their direction is not line-level and is treated like any other above-the-bar finding.
Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.
POC — one runnable check, throwaway
node specs/issues/FIX-1770/poc/esm-reload/probe.mjsanswers: can--devreload a Lab inside the process? No. A cache-busted import of the config keeps the old flow module, andnode --watchrestarts on an imported module only. It is throwaway evidence, not production code.🤖 Generated with Claude Code
https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S
Generated by Claude Code