Repository navigation
docs(atlas): RC vision with teams (plural) - #1604
Conversation
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>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
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>
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. |
There was a problem hiding this comment.
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-dispatcherand cross-flow refuse (#1600) - EXISTS vs PROPOSED labeling throughout
framework.htmllink updates
Minor nits (optional)
- SVG label
#1604 FENCE HOLDSwill stale; prefer "§04 fence holds" fileOrderedReplies— nofile*verb precedent in repo; considercoordinateOrderedReplieswhen code lands (atlas-only bike-shed)- Long
aria-labelparagraphs 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.
Sent by Cursor Automation: Review For Best Approach
| <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 “the” roster is the wrong first cut.</p> | ||
|
|
||
| <div class="cards"> |
There was a problem hiding this comment.
§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.
| <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> |
There was a problem hiding this comment.
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.
| </div> | ||
| </section> | ||
|
|
||
| <section id="fence"> |
There was a problem hiding this comment.
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.
| </div> | ||
| </section> | ||
|
|
||
| <section id="api"> |
There was a problem hiding this comment.
§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.
| </div> | ||
| </section> | ||
|
|
||
| <section id="gaps"> |
| </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 1 object. It is a roster plus shared boards (sessions) as Layer 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 1 object. It is a roster plus shared boards (sessions) as Layer 2. See the <a href="workforce.html#fence">Workforce atlas §04</a>. Target is teams, plural — <a href="workforce.html#vision">§03</a>.</figcaption> |
There was a problem hiding this comment.
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>
There was a problem hiding this comment.
💡 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".
| <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>, |
There was a problem hiding this comment.
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 👍 / 👎.
| <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 → harness → 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> |
There was a problem hiding this comment.
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 👍 / 👎.
| </table> | ||
| </div> | ||
|
|
||
| <pre class="code"><i>// EXISTS — Agent is this, and only this. packages/core/src/types/agent.ts</i> |
There was a problem hiding this comment.
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 👍 / 👎.
| { roster: <em>"marketing"</em>, seat: <em>"bob"</em> }, | ||
| ], | ||
| }) | ||
| <i>// → create rows with deps, then claim({ eligibility: (t) => t.id === postId })</i> |
There was a problem hiding this comment.
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 👍 / 👎.
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>


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:
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-refis a SKILL.md field orchestration parses, not a workforce exportclaimtakesworkerIdfirst; the proposed wrapper no longer teaches a one-arg overloadrosters/[rosterId]/[seat].rosters/[rosterId]/*leaves*literalitemVisibilityandoutputSchema; it is no longer labeled exhaustive without themAtlas-only. No changeset.
What's asked of you
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.
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 ofopenDm, or a new address type in disguise?openTeamInbox({ roster })is the same door.Atlas-only. No changeset. Pin:
origin/mainatc2a743a25. Cross-flow not flipped (#1600 still open; refuse still increate-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
createTeamIntakeCapabilityis a proposed factory name.createWorkforceCapabilityon main is a stub. The page says so; it does not pretend the stub is intake.external-dispatcheron{ id }, FIX-1315) are pointed at, not re-invented.#fenceand#visionstayed put.