Skip to content

docs: give Shift Manager's repository profiles their own page - #3441

Merged
jhoffner merged 3 commits into
mainfrom
claude/project-thread-elhs1q
Oct 22, 2026
Merged

jhoffner merged 3 commits into
mainfrom
claude/project-thread-elhs1q

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

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 fsd dev 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 for devteam.

What this does

  • New page Shift Manager › From a checkout (shift-manager/from-a-checkout.md). It holds the fsd and devteam profiles in the order you use them: before you start, start it, then the fsd profile (asking for work, reviewing a run, giving runs Linear), then devteam. The overview keeps a two-line pointer to it.
  • The README's "Working on Shift Manager itself" section follows the same order with run-in headings, and its devteam wall of text is split into paragraphs.
  • The docs editor's findings are fixed: "the Lab's own user" now says who that is; "FSD holds the connection" on the projects page, which read as the example project named FSD, now says "the server"; and the "Three parties…" preamble, "today", "still" and a hard-to-parse sentence about memory recording are gone.
  • shift-coordinator.md's link to the devteam profile points at the new page.

No facts were changed. Two README-only details (the fsd config path, and that Storefront's workstreams are feature and release, 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.
  • One sentence was cut from the site page: "Workers it hires onto the built-in agent flow get none" (memory). Nothing on that page explains hiring or the agent flow. The sentence is still true; restore it with a link if you want it.
Moved, merged, cut

Verification

  • pnpm --filter @flow-state-dev/docs build: exit 0, no broken-link or broken-Markdown-link warnings.
  • docs-editor ran over the five pages and returned REVISE; every finding was applied except the agent flow line, which was cut. No uses of "seat".
  • No changeset: docs-site and README prose only (BP-022).

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

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
@jhoffner jhoffner self-assigned this Oct 14, 2026
@vercel

vercel Bot commented Oct 14, 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 21, 2026 10:21pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 21, 2026 10:21pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 21, 2026 10:21pm UTC

Request Review

@jhoffner
jhoffner marked this pull request as ready for review October 21, 2026 22:15

@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

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.

Open in Web View Automation 

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

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 / 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.)

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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.

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.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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.

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.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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

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.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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

Comment thread apps/docs/sidebars.ts
type: "category",
label: "Shift Manager",
items: ["shift-manager/overview", "shift-manager/settings"],
items: ["shift-manager/overview", "shift-manager/settings", "shift-manager/from-a-checkout"],

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.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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

@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.

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.

Open in Web View Automation 

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
@jhoffner
jhoffner merged commit dc6c217 into main Oct 22, 2026
18 checks passed
jhoffner pushed a commit that referenced this pull request Oct 22, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A
jhoffner pushed a commit that referenced this pull request Oct 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants