Skip to content

spec(epic): out of the box, shift-manager:dev develops Shift Manager and FSD (FIX-1903) - #3164

Merged
jhoffner merged 2 commits into
mainfrom
claude/project-thread-k7msfx
Oct 12, 2026
Merged

jhoffner merged 2 commits into
mainfrom
claude/project-thread-k7msfx

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 12, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

A team that… Today After this epic
opens pnpm shift-manager:dev to work on FSD Finds three demo projects on a scratch repository. A coding run is a script Finds FSD and Shift Manager. A coding agent works an item in a worktree of their checkout
wants the coder to read the Linear issue Pastes the issue in. A run has no Linear The project has Linear as an MCP server, and each coding run for it gets it
runs one item on each project at once Can't point either project at their checkout Gets two worktrees and two branches in one checkout
maintains the DevTeam goal checks DevTeam is the dev Lab and the goal Lab No change. DevTeam stays the goal Lab, served by --config

Goal: on a fresh open of pnpm shift-manager:dev, with no config edited, a person picks an item on FSD or on Shift Manager, and a coding agent works it in a worktree of their checkout, with Linear available to it.

flowchart LR
  O["fresh store · pnpm shift-manager:dev as shipped"] --> A["leg a · an FSD item, named by its Linear id"]
  O --> B["leg b · a Shift Manager item, at the same time"]
  A -->|"worktree of the checkout · answer names the issue title"| P["PASS · the goal is met"]
  B -->|"its own worktree and branch · both settle"| P
  C["control · Linear removed from the project"] -.-> A
  A -.->|"under the control"| F["must FAIL · no title"]
Loading

The person gives only the issue id, so the title can only come from Linear. The closure issue FIX-1919 runs this check. With Linear removed, leg a must fail.

What's in the box: the dev profile with FSD and Shift Manager, worktrees from your checkout, MCP servers as a project setting; DevTeam and the hand-over tools unchanged; not built: an issue picker, push and pull request, per-person Linear sign-in, MCP for workers that don't code

The box is one profile and two settings that a host acts on. The fence keeps this a dev setup.

Why now. A project can name its repository, and two runs on one project commit side by side. Both are done. The people who build Shift Manager do not use it yet, so checks find its gaps, not use.

The set: three issues and a closure. FIX-1906 the local checkout, FIX-1904 the dev profile, FIX-1905 project MCP settings, FIX-1919 the closure. As of 2026-10-12: all four in Backlog. The spec records that snapshot and links to live state.

The path: specs side by side, FIX-1906's spec proving a fresh worktree builds; then FIX-1906, FIX-1904 and FIX-1905 build in a chain, FIX-1905 as one PR; the closure run last

Builds are a chain, and nothing builds on a worktree until FIX-1906 has proved one builds.

Who owns what: seven rules by four issues, each rule with exactly one owner

Each rule has one owner. Two owners would be a seam; none would be a gap.

Sign off

Three issues and a closure, now · D1

D1: three issues and a closure, chosen, beside four with MCP delivery split out and two with FIX-1906 folded into FIX-1904. Decides it: what each piece waits on

It comes down to what each piece waits on: nothing waits on FIX-1875, and FIX-1906, which carries the kill line, proves a worktree builds before the rest builds on it. If wrong: one spec more than needed.

A coding run reads its project's MCP servers, by host alias, when it starts · D4

D4 trade-off figure (the blob view renders it)

It comes down to which runs get them: a run started from Inbox does not go through a coordinator. A row names a host-approved alias only, never a URL or a variable. If wrong: a worker that does not code never gets Linear.

Open · keep the goal, a real agent on a fresh open, or relax it for the script? · Q1

Open: keep the goal, a real coding agent by default, recommended, beside relaxing it with the script by default. Decides it: whether a fresh open meets the goal as written

The goal needs a real agent, so the script means rewriting the goal. I recommend keeping it: Claude Code by default, refusing to start without a credential. Merging accepts that unless you say otherwise. If wrong: one line changes.

What would change my mind on Q1: most opens are for screen work, where an agent is not wanted. Reasoning and what lost: DECISIONS.md.

Reviewers · look here

  • D3: the server cuts branches in your own checkout. The row keeps a remote, and the host maps it to the checkout, only for the project ids its config names. The other option, a host clone, needs no code but hides the branch. Is a conductor/… branch in your checkout acceptable?
  • D2: a second profile. DevTeam stays the goal Lab, because five goal checks serve its config. The cost is two profiles that can drift.

Not here: the approach of a single issue. Those are the spec PRs.

Spec · Decisions · Rules · Plan · Docs · Evolution
· Linear FIX-1903 · Project: Workforce: Shift Manager · merges after human approval and required checks

How to review this — an epic-spec, not an implementation plan

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.

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.
  • A cross-cutting decision in DECISIONS.md — shared surface, naming, sequencing, contracts.
  • A rule in BUSINESS-RULES.md with no owner, or two.
  • A missing issue the objective implies, or one in the set that doesn't serve it.
  • Shared promises and publication ownership in DOCS.md; missing or misleading
    predecessor treatment in conditional EVOLUTION.md.

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_01MJsSFWmTXycBXJU4s96Pk1


Generated by Claude Code

… Manager and FSD

The retained epic spec: a dev profile of its own with FSD and Shift Manager
projects (D2), worktrees cut from the person's own checkout while the row keeps
naming a remote (D3), and project MCP servers read when a coding run starts,
so delivery waits on no hand-over tool (D4, D1). Closure FIX-1919 filed.
Open: Q1, whether a fresh open runs a real coding agent.

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

linear-code Bot commented Oct 12, 2026

Copy link
Copy Markdown

FIX-1903

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 12, 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-12T18:10:57.849406Z 228e6af 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.

@jhoffner jhoffner self-assigned this Oct 12, 2026

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

Verdict: The core approach looks right for the stated goal. D2 (separate dev profile), D3 (remote row + host maps to your checkout), and D4 (MCP from the coding run’s project at start, not handOff / dispatchTask) are well argued against the simpler-looking alternatives, and they line up with projectWorkspace() and FIX-1762 BR-5. I would not collapse this into “edit DevTeam” or “put file:// on the row” without breaking goal checks or the review-in-checkout story.

What follows is where the packaging still feels heavier than the outcome, and what I’d simplify before or during child specs — not a request to reopen D1–D4 unless you disagree on the merits.

Issue split and PR shape

  • Three platform children + closure is coherent, but the spec already asks “whether three is really two.” Consider folding FIX-1906 into FIX-1904 as one “default dev Lab” child (host remote→checkout mapping + profile + CLI defaults). You keep FIX-1905 as the only cross-cutting platform issue. That removes one ownership matrix, one “consumes vs builds” seam, and one spec lifecycle for roughly the same code.
  • FIX-1905 as two stacked PRs partially reintroduces the settings/delivery split D1 rejected at the issue level. If parallel mechanism work during FIX-1906 is not critical, a single FIX-1905 PR after FIX-1904 (row + harness pass-through + Linear rows) may be simpler than PR1 ∥ 1906 + PR2 on 1904.

Before implementation locks in cost

  • Kill line (worktree can build/test): The epic assumes a fresh worktree in this monorepo is viable, but EVOLUTION says no end-state POC. FIX-1906’s child spec should name a dependency strategy (pnpm store sharing, symlink from primary checkout, or explicit “acceptable first-run latency”) — this dominates run latency more than MCP or mapping.
  • ER-4 / parallel git: Two worktrees on one mapped checkout is the right goal check; child tests should spell out git lock / concurrency expectations, not only “two places.”
  • MCP at run start (D4): Reuse createMcpManager / MCPServerConfig (@flow-state-dev/tools/mcp, kitchen-sink lib/mcp.ts as template) at the workforce→harness boundary; avoid a second MCP stack on the coder flow. ER-5 requires read at start; lazy connect on first tool call is still compatible and worth stating in FIX-1905 so missing LINEAR_MCP_API_KEY does not pay full spawn cost every run.
  • ER-7 vs closure: “Run still runs” without Linear is consistent with leg-a failing the title check, but implementers may read ER-7 as success-shaped. One sentence tying missing credential → leg a must FAIL would reduce ambiguity.

Spec maintainability

  • Figure / diagram duplication: path mermaid + path.svg + decision tree + eight per-decision SVGs + ownership figure largely restate tables (similar feedback on other epic specs). I’d keep end-state.svg and one path graphic; drop or consolidate D1–D4 SVGs unless you need them for an external audience.
  • Decided in review: “Nothing yet” followed by six binding bullets is easy to miss. Promote to numbered ERs or drop the “Nothing yet” header so children do not re-litigate layer boundary, LINEAR_MCP_API_KEY, shared projects, etc.

Gate

  • Q1 is the only open sign-off item. The recommendation matches the goal text; closing it at epic approval (even as “accepted recommendation”) would unblock FIX-1904’s spec without changing cost much (“one line in one profile”). If you intentionally want the PO to answer at the gate, that’s fine — just know FIX-1904’s coder default stays conditional until then.

Skipped (would need product call, not simplify nit)

  • Dropping FIX-1919 or merging all children into one mega-issue — trades review/ER clarity for fewer Linear tickets.
  • Hardcoding Linear only on the dev harness (no project mcpServers) — fights ER-5 and the “project carries the tracker” story.

Approval: Directionally approve for merge; child specs are where I’d apply the split/PR and worktree/MCP reuse notes above.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/epics/FIX-1903/SPEC.md Resolved
Comment thread specs/epics/FIX-1903/SPEC.md Resolved
Comment thread specs/epics/FIX-1903/SPEC.md Resolved
Comment thread specs/epics/FIX-1903/PLAN.md Resolved
Comment thread specs/epics/FIX-1903/DECISIONS.md Resolved
Comment thread specs/epics/FIX-1903/BUSINESS-RULES.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: 228e6af367

ℹ️ 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-1903/DOCS.md Resolved
Comment thread specs/epics/FIX-1903/DECISIONS.md Resolved
Comment thread specs/epics/FIX-1903/DECISIONS.md Resolved
Comment thread specs/epics/FIX-1903/DOCS.md Resolved
- D1: FIX-1906 stays separate and proves a fresh worktree builds first;
  FIX-1905 ships as one PR after FIX-1904; D1 figure gains the fold option
- D3/ER-13: the remote-to-checkout mapping is operator host config bound to
  project ids, never resolved from a row's remote alone
- D4/ER-14/ER-6: rows select a host-approved MCP alias; URL and credential
  variable live in host config
- ER-7: a missing LINEAR_MCP_API_KEY fails the closure's leg a
- Q1 reframed as keep or relax the goal; merging accepts the recommendation
- Handover bullets promoted to ER-15/ER-16 (no picker, "worker"); rules
  renumbered; DOCS no longer promises checking out a retained run branch
- Path figure: chain with the build proof first; one FIX-1905 PR

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MJsSFWmTXycBXJU4s96Pk1
@jhoffner
jhoffner merged commit be18f48 into main Oct 12, 2026
15 checks passed
@vercel

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

Request Review

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