Skip to content

docs(atlas): RC vision with teams (plural) - #1604

Merged
jhoffner merged 6 commits into
mainfrom
cursor/atlas-workforce-v1-kick-1f13
Sep 6, 2026
Merged

jhoffner merged 6 commits into
mainfrom
cursor/atlas-workforce-v1-kick-1f13

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 6, 2026 •

Copy link
Copy Markdown
Collaborator

The atlas taught a one-team demo. That is the wrong first cut. RC collaboration is teams, plural — more than one roster, rooms they share, dispatch across those rosters. Address-the-team without picking a person is an intake seat, not a TeamFlow. A helper that can only address “the” team would have to be rewritten the moment a second roster exists.

This page now teaches that full story as the target. Implement stays phased. Foundation leaves the plural door open. RC gates are taught as proposed until they are true.

What this does

Keeps the RC vision section and four-phase diagram, and adds two locks:

Team intake (§10) — capability, not a new flow kind. Every keyed roster has an intake seat (coordinator or thin sequencer) with a static DM. “Talk to eng” is that session. Intake routes with claim / ordered replies / fan-out. The team board stays for broadcast. Still one flow per worker. Kills: TeamFlow, team-as-flow substrate, second dispatch model, inbox on Agent, a team address beyond session id or a known channel. If intake needs a missing L1 door, the named gaps are the same ones already listed (cross-flow, external-dispatcher, FIX-1315).

Strategy RC gates (§18) — proposed until true:

  1. Teams plural dogfood (N rosters + shared rooms + cross-roster dispatch)
  2. Reverse + cross-flow F&F on the floor (reverse exists; cross-flow still refused)
  3. Honest exists-vs-proposed (no fake L1)
  4. Outsider can install multi-team without babysitting substrate
  5. Conductor-as-extension stays proposed — RC does not wait on Conductor; Conductor’s thin shell does not wait on full Workforce RC

Not RC gates: OKF, Slack-style web face, Pi, paid packaging. Timing is after foundation + teams-plural dogfood (FSD + one client-shaped use), not a calendar. GTM stays Strategy.

Invent kills still hold. Agent stays the seat. Helpers stay multi-roster from day one.

Review trim — approach unchanged. Surgical cuts only: §04 FENCE HOLDS, drop the §03 card grid, slim §16, merge send-at gaps 2 and 6, point §19 at the fence, one Workforce atlas link from framework.

Codex honesty pins (this revision) — four facts, all confirmed against the tree:

  • agent-ref is a SKILL.md field orchestration parses, not a workforce export
  • claim takes workerId first; the proposed wrapper no longer teaches a one-arg overload
  • Roster seats use rosters/[rosterId]/[seat]. rosters/[rosterId]/* leaves * literal
  • The Agent snippet includes existing itemVisibility and outputSchema; it is no longer labeled exhaustive without them

Atlas-only. No changeset.

What's asked of you

  1. Address-the-team as an intake worker, or as a TeamFlow?
    “Talk to eng” has to land somewhere. A seat with a static DM reuses today’s session door. A TeamFlow invents a kind so a team looks like a flow.
    Recommendation: intake seat. Capability over the roster key.
    What would change my mind: a bind that cannot be expressed as roster + intake worker + session id.
    Cost of being wrong: a second dispatch model, or an inbox on Agent, that then has to be unwound.

  2. These five as RC gates, with OKF / face / Pi / packaging off the list?
    Gates are claims. Marking them proposed until true keeps the page honest. Pulling a surface or a price into RC stalls the collaboration story on later work.
    Recommendation: keep this list. Timing is sequence, not a quarter.
    What would change my mind: a customer promise that RC includes a Slack-style face or paid packaging.
    Cost of being wrong: RC that never closes, or RC that ships a fake L1.

Parts worth reviewing closely

  • docs/atlas/workforce.html §10 (intake) — is the capability actually a wrapper of openDm, or a new address type in disguise?
  • §18 (RC gates) — gate 2 honesty: reverse exists, cross-flow does not; the gate is unmet.
  • Helpers in §07 still take a roster key. openTeamInbox({ roster }) is the same door.

Atlas-only. No changeset. Pin: origin/main at c2a743a25. Cross-flow not flipped (#1600 still open; refuse still in create-request-host.ts). Head: aea985f51.

How to review this — altitude, what's in scope, what's deliberately unsettled

How to review this. This change has no upstream contract — no spec, no brief, no issue that defined its scope before the work. So nothing was signed off anywhere and this PR is the only gate: the approach, the scope, and whether this earned its place at all are in scope alongside the page.

Most valuable here: whether the scope is the right scope. Then whether exists/proposed/cut tags match the tree.

In scope to challenge: everything. Direction first. Line-level copy on an atlas page is below the bar unless it changes the approach.

Engineering calls — decided along the way, no product sign-off needed
  • createTeamIntakeCapability is a proposed factory name. createWorkforceCapability on main is a stub. The page says so; it does not pretend the stub is intake.
  • Intake L1 needs that are already gaps (cross-flow, external-dispatcher on { id }, FIX-1315) are pointed at, not re-invented.
  • Section numbers: intake is §10, RC gates is §18. #fence and #vision stayed put.
  • Review trim did not gut diagrams. The 200–300 line slash is still available if wanted after merge.
  • Codex P2s were factual; they did not move the product locks.
Open in Web Open in Cursor 

Tag factory files v1 vs later, draw proposed room helpers as thin L1
wrappers, and list known Layer 1 gaps so a kick cannot paper over them.
Cross-flow stays proposed: #1600 is open and the refuse is still on main.
Conductor does not wait. No changeset — atlas only.

Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
@vercel

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

Request Review

cursoragent and others added 2 commits September 6, 2026 21:43
Min useful v1 is one collaborating team: roster, DMs, project rooms,
fan-out, ordered replies. Agent stays the existing L1 participant —
no members, channels, inbox, or memory store on the type. Three proofs
before growing it: flowIsolation vs persona-only, the roster bind, and
thinning the current AgentRegistry rather than forking a second model.
Cross-flow still refused on main. No changeset — atlas only.

Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
Raise the Workforce atlas from a one-team demo to the RC collaboration
target. Foundation stays thin L2 over today's L1; helpers take a roster
key from day one so N rosters is more rows, not a rewrite.

Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
@cursor cursor Bot changed the title docs(atlas): name a possible Workforce v1 kick docs(atlas): RC vision with teams (plural) Sep 6, 2026
@jhoffner
jhoffner marked this pull request as ready for review September 6, 2026 22:01
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 6, 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-09-06T22:06:53.673263Z f2debc2 Draft marked ready
ℹ️ 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.

@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

The substance of this PR is sound. Teaching the RC collaboration target (teams plural, keyed rosters from day one, Agent-as-seat fence, phased implement, L1 gaps) is the right atlas move, and the framework cross-links to #vision / #fence are correct. I would not take a different architectural approach.

The concern is execution weight: workforce.html grew 524 lines (+46% raw / ~+11 KB gzip) mostly by restating the same constraints in four parallel formats per topic — cards, SVG, table, note/CUT band. That pattern appears ~8× for the fence alone (no Team L1, no collaboration fields on Agent, multi-roster API, proof A/B/C). The doc will drift when one copy updates and the others don't.

Cleaner shape (same story, less surface)

Section Keep as SSOT Collapse / link
§03 RC vision Phase table (Status / What is true / What would fake it) Drop the four-card grid (duplicates §01) or drop the 4-column phase SVG — not both cards + SVG + table
§04 Agent vs team Proof A/B/C table + one seat-bind diagram One Agent type snippet (drop duplicate in §14). Elsewhere: "see §04"
§07 Channels Talk/Room matrix table + room-helper table Drop routing-matrix SVG (duplicates table below) or drop helper SVG (duplicates §15). Move EXISTS code samples to §14/§15 only
§15 API surface SSOT note ("package docs must not fork §07 matrix") Fold into §07 as a note; drop the second two-column figure + card trio
§16 L1 gaps Gaps 5–6 (Workforce-specific: external-dispatcher, no sendAt) Merge gaps #2 and #6 (same send-at story). Cross-flow: pin once here; §12/§14 link instead of re-litigate
§17 Cuts 2–3 tensions not covered elsewhere (GTM, Conductor wait) Linked checklist to §04/§07/§16 — not full re-litigation
Siblings — Masthead link to framework.html#workforce-layer + roadmap.html#clocks; avoid re-teaching three-job horizon inline

Rough estimate: 200–300 lines removable without losing the RC-plural story.

What to keep (high signal)

  • Proof rows A/B/C in §04 — these are the implement gates
  • Multi-roster-from-day-one rule and "one-team-only API" cut
  • §16 honesty on external-dispatcher and cross-flow refuse (#1600)
  • EXISTS vs PROPOSED labeling throughout
  • framework.html link updates

Minor nits (optional)

  • SVG label #1604 FENCE HOLDS will stale; prefer "§04 fence holds"
  • fileOrderedReplies — no file* verb precedent in repo; consider coordinateOrderedReplies when code lands (atlas-only bike-shed)
  • Long aria-label paragraphs duplicate figcaptions (~8 KB); shorten labels, keep detail in figcaption/table

Verdict

Approach: yes. Verbosity: trim before or immediately after merge. Not blocking on content correctness — this is maintainability / reader-load. Happy to approve a follow-up dedupe PR or a slimmed revision of this one.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread docs/atlas/workforce.html Outdated
<div class="sec-head"><span class="sec-num">03</span><h2>RC vision</h2></div>
<p class="lede">The target is the <strong>full RC collaboration story</strong>: more than one team, rooms they share, dispatch across those rosters. Atlas teaches that story. Implement stays phased. Foundation leaves the plural door open. A thin one-team demo that can only address &#8220;the&#8221; roster is the wrong first cut.</p>

<div class="cards">

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.

§01 ↔ §03 duplication. These four cards (Foundation / Teams plural / Identity / Later) repeat the §01 masthead cards almost verbatim. Suggest keeping the phase model in one place — either §01 as a one-line summary + link to §03, or drop this card grid and let the phase table below be authoritative.

Comment thread docs/atlas/workforce.html Outdated
<text class="t-xs" x="32" y="152">MULTI-ROSTER FROM DAY ONE</text>
<text class="t-xs" x="32" y="170">ONE ROSTER IN THE MAP IS FINE</text>
<text class="t-xs" x="32" y="188">A SINGLETON API IS NOT</text>
<text class="t-xs" x="32" y="214">#1604 FENCE HOLDS</text>

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.

Embedding #1604 FENCE HOLDS in the diagram will stale quickly and conflates "this PR" with "the design pin." Consider §04 fence holds or drop — the CUT band below already states the rule.

Comment thread docs/atlas/workforce.html
</div>
</section>

<section id="fence">

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.

Fence SSOT candidate. This section (proof A/B/C + seat-bind diagram) is the right anchor for "no collaboration on Agent / no Team L1 / no second Agent model." §17 cuts, §15 CUT bands, and the masthead one-sentence version largely repeat it — elsewhere a short "see §04" link would cut hundreds of words and reduce drift risk.

Comment thread docs/atlas/workforce.html
</div>
</section>

<section id="api">

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.

§15 vs §07 overlap. The two-column Exists/Proposed figure and card trio restate what §07's room-helper table + pre.code already show. Simpler: one paragraph + link ("bodies in §05 factory, §07 helpers") and keep only the SSOT note about package docs not forking the matrix.

Comment thread docs/atlas/workforce.html
</div>
</section>

<section id="gaps">

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.

Gap #2 / #6 merge. Send-at / due-ledger appears twice (rows 2 and 6; table admits "Same gap as #2"). One row + one SVG cell would be clearer. Cross-flow (#1600) is also cited ~13× across the page — pin the refuse once here and link from §12/§14.

Comment thread docs/atlas/framework.html Outdated
</svg>
</div>
<figcaption><b>Seven built, two reserved, the team row closed.</b> <code>usesSkills</code> and <code>contextMode: "fork"</code> are declared on <code>Agent</code> and warn at materialization — deferred, not undecided. The team itself is not a first-class Layer&nbsp;1 object. It is a roster plus shared boards (sessions) as Layer&nbsp;2. See the <a href="workforce.html#teams">Workforce atlas §07</a>.</figcaption>
<figcaption><b>Seven built, two reserved, the team row closed.</b> <code>usesSkills</code> and <code>contextMode: "fork"</code> are declared on <code>Agent</code> and warn at materialization — deferred, not undecided. The team itself is not a first-class Layer&nbsp;1 object. It is a roster plus shared boards (sessions) as Layer&nbsp;2. See the <a href="workforce.html#fence">Workforce atlas §04</a>. Target is teams, plural &#8212; <a href="workforce.html#vision">§03</a>.</figcaption>

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.

Good cross-link pattern. Optional: a single "Workforce RC vision" link in the workforce-layer section instead of repeating fence + vision in every figcaption edit — the workforce atlas now owns that story.

Address-the-team is an intake seat (a worker with a static DM), not a
TeamFlow. Strategy RC gates are taught as proposed until true; OKF,
surfaces, Pi, and paid packaging are not gates.

Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>

@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: f2debc2970

ℹ️ 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 docs/atlas/workforce.html Outdated
<i>// The pattern already takes a key. Foundation uses that. Do not collapse to "roster".</i>
const roster = <b>defineResourceCollection</b>({
pattern: <em>"roster/*"</em>,
pattern: <em>"rosters/[rosterId]/*"</em>,

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Use a supported collection pattern for roster seats

When foundation follows this example to store multiple seats under one roster, rosters/[rosterId]/* cannot address those rows: parameterized patterns are resolved by substituting [rosterId] while leaving the trailing * literal, and the parameterized matcher likewise treats that wildcard literally. Use a fully parameterized pattern such as rosters/[rosterId]/[seat], or a supported wildcard pattern with a composite string key.

Useful? React with 👍 / 👎.

Comment thread docs/atlas/workforce.html Outdated
<tbody>
<tr><td>A</td><td>Durable memory / identity across sessions</td><td><span class="tag t-prop">opinion</span> <code>flowIsolation</code> resources on the worker flow. Persona is a prompt source, not a store. Prove that isolated org/user rows outlive a DM and a project room. Prove they beat persona-only (a string or a template is not memory).</td><td><code>Agent.resources</code>, <code>Agent.memory</code>, a durable identity bag on the type. No such fields on this pin.</td></tr>
<tr><td>B</td><td>Roster bind: Agent &#8594; harness &#8594; session, no Team type</td><td><span class="tag t-prop">proposed</span> A keyed row (<code>rosterId</code> + seat) names the agent, an optional harness, and the session the room helpers open. Same bind, three fields, plus the roster key. Prove one row can seat a participant into a DM and a project room without a Team object in the middle. Prove a second roster is another key, not a new type.</td><td>A Team type whose job is to hold the bind. A singleton roster with no key. <code>Agent.sessions</code>. A harness field on Agent. An org graph on Agent.</td></tr>
<tr><td>C</td><td>Foundation <em>is</em> thinning <code>@flow-state-dev/workforce</code></td><td><span class="tag t-prop">proposed</span> The package already exports <code>defineAgent</code>, <code>createAgentRegistry</code>, <code>materializeAgent</code>, <code>agent-ref</code>. Foundation adds factory + keyed roster(s) + room helpers around that registry. Prove the kick extends this Agent, not a second participant model with a friendlier name.</td><td>A parallel <code>Worker</code> / <code>Member</code> type. A second registry. Package docs that describe a different Agent than <code>packages/core/src/types/agent.ts</code>.</td></tr>

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Do not call agent-ref a workforce export

When readers use this list as the package boundary, it sends them looking for a nonexistent agent-ref export. packages/workforce/src/index.ts exports the three preceding functions but not agent-ref; that name is a SKILL.md field parsed by the orchestration package. Describe it as registry integration rather than an export.

AGENTS.md reference: AGENTS.md:L179-L181

Useful? React with 👍 / 👎.

Comment thread docs/atlas/workforce.html Outdated
</table>
</div>

<pre class="code"><i>// EXISTS &#8212; Agent is this, and only this. packages/core/src/types/agent.ts</i>

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Stop labeling an abbreviated Agent type as exhaustive

When this fence is consulted as the current public contract, “Agent is this, and only this” is incorrect because the displayed type omits the existing itemVisibility?: ItemVisibility and outputSchema?: ZodTypeAny fields from packages/core/src/types/agent.ts. Include those fields or explicitly label the snippet as abbreviated.

Useful? React with 👍 / 👎.

Comment thread docs/atlas/workforce.html Outdated
{ roster: <em>"marketing"</em>, seat: <em>"bob"</em> },
],
})
<i>// &#8594; create rows with deps, then claim({ eligibility: (t) => t.id === postId })</i>

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Pass the worker ID when documenting claim

When implementing fileOrderedReplies from this expansion, claim({ eligibility: ... }) is not a valid call: TaskCollectionRef.claim requires claim(workerId, options), as the correct example earlier on this page demonstrates with subscriberId. Include the attribution ID in this proposed wrapper body so it does not teach a nonexistent overload.

AGENTS.md reference: AGENTS.md:L179-L181

Useful? React with 👍 / 👎.

cursoragent and others added 2 commits September 6, 2026 22:07
Apply the Cursor review's surgical cuts: §04 fence label, drop the
§03 card grid, slim the §16 API figure, merge send-at gaps 2 and 6,
point §19 at the fence, and give framework one Workforce atlas link.

Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
agent-ref is a SKILL.md field, not a workforce export. claim takes
workerId. Roster seats use rosters/[rosterId]/[seat]. The Agent
snippet includes itemVisibility and outputSchema.

Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
@jhoffner
jhoffner merged commit 2971141 into main Sep 6, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants