Repository navigation
docs: give Shift Manager's repository profiles their own page - #3441
Conversation
The Shift Manager overview carried the fsd and devteam profile setup inline. Move it to shift-manager/from-a-checkout.md, ordered as a reader runs it, and break the README's same section into readable parts. Small prose fixes from the docs editor on the projects page. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fn5XgbC5LFjAkiiyEPuqjp
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
There was a problem hiding this comment.
Simplify review
Verdict: The docs-site split is the right shape — same pattern as settings.md and DevTool (consumer overview + focused siblings, explicit sidebars.ts entry). Trimming overview.md to a stub helps npm-only readers who land on Shift Manager first.
Where the approach stops halfway: The PR adds a third full copy of the checkout/profile runbook. from-a-checkout.md and packages/shift-manager/README.md are already diverging (README still has AGENTS.md/CLAUDE.md, fsd-projects.mts, reviewer worker, teams/devteam/ + goals/devforce-lab/ links; the new page omits or shortens several of those). Docusaurus has no shared partial/include pattern in this repo, so two prose bodies = ongoing drift unless you pick one canonical surface.
Cleaner alternative (repo precedent): @flow-state-dev/devtool keeps a short README and links to https://flow-state.dev/docs/devtool/.... I'd treat from-a-checkout.md as canonical and replace the long README subsection with a few lines + that URL (keep only commands that must work from the npm tarball if you care about offline readers). Simpler than this PR's net +63 lines across six files.
Even simpler (if README must own contributors): Skip the new page — stub overview.md and link to packages/shift-manager/README.md#... on GitHub. Worse for site nav/discoverability, but one source of truth.
Nits (non-blocking): Align naming (From a checkout / clone / Working on Shift Manager); consider sidebar order overview → from-a-checkout → settings for monorepo traffic; fenced code blocks in README for the --config invocations.
Unrelated but good: workforce/projects.md FSD→"the server" and remotes.allow tightening fit the outsider rule.
Performance: N/A (static docs).
Happy to approve a follow-up that dedupes README ↔ site; for this PR I'd merge if you're intentionally maintaining both copies for now — otherwise I'd slim README before merge.
Sent by Cursor Automation: Review For Best Approach
| @@ -41,37 +41,45 @@ If the Lab fails to start after a save, the error prints and Shift Manager waits | |||
|
|
|||
| ### Working on Shift Manager itself | |||
There was a problem hiding this comment.
Simplify / reuse: This section is still a full parallel of from-a-checkout.md after the extraction. The repo's lighter pattern is devtool: short README + link to the published doc. Consider replacing most of this with 2–3 sentences and https://flow-state.dev/docs/shift-manager/from-a-checkout so profile tweaks land in one place. (If npm-offline readers need more, keep commands here and link for semantics.)
There was a problem hiding this comment.
Agreed. The merge from main showed the drift already: both copies needed the same fetch-pin and default-model edits. In 9b61626 the site page is the canonical copy, and this README section is down to the two commands, the config paths, the repo-only links and a link to the site page, following the devtool pattern.
Generated by Claude Code
|
|
||
| ### Asking for work | ||
|
|
||
| Ask the Shift Coordinator for work on either project, and say which one, for example "on Shift Manager, make the empty Inbox say who to ask". A coding agent picks it up in a fresh worktree of your checkout, on a branch of its own. |
There was a problem hiding this comment.
Drift risk: README's "Asking for work" still says coding runs follow AGENTS.md and CLAUDE.md; this page doesn't. Either add the same line here (one sentence) or drop it from README intentionally — otherwise the two copies will disagree quickly.
There was a problem hiding this comment.
Fixed in 9b61626. The page now says runs work to AGENTS.md and CLAUDE.md, and the README no longer keeps its own copy of this section.
Generated by Claude Code
|
|
||
| ## The `fsd` profile | ||
|
|
||
| The profile is at `packages/shift-manager/teams/devteam/fsd.fsdev.config.mts`. The Lab has two projects from the start. **FSD** is the framework packages, and **Shift Manager** is this app. Both are shared with everyone in the Lab, and both point at this repository. Inbox is empty until a worker asks you something. |
There was a problem hiding this comment.
README still points contributors at teams/devteam/fsd-projects.mts for projects/MCP wiring; this page doesn't. Worth a sentence or a link to teams/devteam/README.md so docs readers aren't under-informed.
There was a problem hiding this comment.
Fixed in 9b61626. The page names fsd-projects.mts as where the projects and their MCP servers are defined, and the devteam section links to the teams/devteam README.
Generated by Claude Code
| @@ -0,0 +1,87 @@ | |||
| --- | |||
| title: Working on Shift Manager | |||
| sidebar_label: From a checkout | |||
There was a problem hiding this comment.
Naming: Three labels for one page today — file from-a-checkout, sidebar "From a checkout", title/H1 "Working on Shift Manager", overview link "Working on Shift Manager" under "From a clone…". Not wrong, but aligning H1/title/sidebar/link text would match settings.md / DevTool and reduce grep friction.
There was a problem hiding this comment.
I've partly aligned them: the overview's link and the README's link now both say "From a checkout", matching the sidebar. The title stays "Working on Shift Manager". The sidebar label can't repeat the category name, and the title says what the page is for better than the label does.
Generated by Claude Code
| type: "category", | ||
| label: "Shift Manager", | ||
| items: ["shift-manager/overview", "shift-manager/settings"], | ||
| items: ["shift-manager/overview", "shift-manager/settings", "shift-manager/from-a-checkout"], |
There was a problem hiding this comment.
Optional: for flow-state-dev contributors, from-a-checkout before settings might match how often people need repo profiles vs per-user Linear keys. Consumer-first order is also defensible — just a traffic guess.
There was a problem hiding this comment.
Leaving this as it is. The docs site is for people using the package, so Settings, which every Lab user sees, comes before the page that only applies to this repository.
Generated by Claude Code
Resolve the Shift Manager overview and README conflicts by keeping the moved profile sections, and carry main's new facts into them: fetch failure starts from local main, remote/upstream pins, a run's trust in your checkout, and the default model for workers that name none. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fn5XgbC5LFjAkiiyEPuqjp
There was a problem hiding this comment.
Code Snob — already tight. No POC.
Head dfea29a3ff36fa75700132f7698a07eb8d5abb0a. I read apps/docs/docs/shift-manager/from-a-checkout.md, the pointer and the --dev section in apps/docs/docs/shift-manager/overview.md, packages/shift-manager/README.md (the “Working on Shift Manager itself” section, against the pre-change copy), the MCP and remotes.allow sentences in apps/docs/docs/workforce/projects.md, the profile link in apps/docs/docs/workforce/shift-coordinator.md, and the one new entry in apps/docs/sidebars.ts.
A rewrite does not shrink this contract. The new page is the overview section in run order. The words it adds are the headings that make that order, the two README facts this PR records carrying over (the fsd config path, and Storefront’s feature and release workstreams), and the sentence that says who the Lab’s owner is. The README keeps its own copy, in that same order, with the devteam wall broken into paragraphs. projects.md already dropped the “Three parties…” preamble and “today”; the two renames name the server and remotes.allow in the sentence that follows. The coordinator edit is the new anchor. The sidebar edit is one entry.
Fold nothing. There is no POC.
Sent by Cursor Automation: Code Snob
Make the docs site's From a checkout page canonical and cut the README's copy of it to the commands, the config paths and a link, so the two can't drift. Carry the README-only facts onto the page: runs work to AGENTS.md and CLAUDE.md, where the fsd projects are defined, the project coordinator, and when delegated requests aren't recorded in memory. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fn5XgbC5LFjAkiiyEPuqjp
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A


Requested by Jake · project thread
Epic-wrap docs pass for FIX-1903 (Shift Manager works FSD and Shift Manager out of the box). No upstream contract: this is an editorial pass over the docs the epic's PRs touched (#3185, #3189, #3194, #3205, #3261, #3308, #3299, #3317, #3367).
The problem
Each PR added its piece of the
fsddev profile (worktrees, upstream fetch, Linear keys, Claude Code sign-in) to the published Shift Manager overview, one paragraph at a time. The result was about 35 lines of repository-only setup sitting between "Run it" and "What you see". Someone who installed Shift Manager from npm had to scroll through instructions for profiles their package doesn't include, and a contributor had to read the steps out of order: the prerequisites (sign in to Claude Code) came after how to ask for work. The README's copy of that section had the same order and one ten-sentence paragraph fordevteam.What this does
shift-manager/from-a-checkout.md). It holds thefsdanddevteamprofiles in the order you use them: before you start, start it, then thefsdprofile (asking for work, reviewing a run, giving runs Linear), thendevteam. The overview keeps a two-line pointer to it.devteamwall of text is split into paragraphs.shift-coordinator.md's link to thedevteamprofile points at the new page.No facts were changed. Two README-only details (the
fsdconfig path, and that Storefront's workstreams arefeatureandrelease, opened by the Lab's second user) were carried onto the site page so the two say the same thing.What's asked of you
Read the new page once as a reader would. Is "From a checkout" under Shift Manager the right home, or should repository setup live in contributor docs instead?
Where to look closely
from-a-checkout.md, under "Giving runs Linear": the Lab's owner is described as "the user Shift Manager opens as on your machine". That's taken from the profile's config (devtool: true, projects created as the Lab's owner), not from a run.agentflow get none" (memory). Nothing on that page explains hiring or theagentflow. The sentence is still true; restore it with a link if you want it.Moved, merged, cut
devteamprofile" →from-a-checkout.md.from-a-checkout.md. The package README keeps its own copy, as the package's entry point in the repository.agent-flow memory sentence above.packages/shift-manager/teams/devteam/README.md(touched by FIX-1904 (1/2): fsd profile, Claude Code by default, start-time account probe #3189/FIX-1904 (2/2): fsd is the default, and its runs work in worktrees of your checkout #3194/fix(shift-manager): the fsd profile's coders read its own brief and commit style, not DevTeam's demo (FIX-1971) #3317) is an internal evidence doc that uses design-review language ("D-12", "on purpose"). It's out of scope for user docs and left as is.Verification
pnpm --filter @flow-state-dev/docs build: exit 0, no broken-link or broken-Markdown-link warnings.docs-editorran over the five pages and returned REVISE; every finding was applied except theagentflow line, which was cut. No uses of "seat".Open follow-ups from the epic (not in this PR)
FIX-1955, FIX-1934, FIX-1969, plus two checks only Jake's machine can run: the FIX-1904 V1 row with a claude.ai subscription OAuth sign-in, and a confirming run of leg c.
🤖 Generated with Claude Code
https://claude.ai/code/session_01Fn5XgbC5LFjAkiiyEPuqjp
Generated by Claude Code