docs(j5): product docs cleanup — kinds, identifiers, definitions by Jacksondr5 · Pull Request #110 · Jacksondr5/j5code

Jacksondr5 · 2026-09-05T17:11:25Z

Posted by an AI agent on Jackson's behalf

A full pass over the J5 product docs, worked with Jackson on this branch and reviewed in the worktree before each commit.

Conventions. docs/j5/process/docs.md defines five document kinds — definition, plan, research, record, runbook — each with an expected lifetime and a one-line test. Only definitions may be cited as current truth. Two identifier kinds remain: a feature's acceptance criteria ("Squadron AC5") and a plan's milestones ("A2A M5"); every letter register (D, E, X, R, SC, ST, SB, IB, TA, AR, SP, QS, FV, DV, P, J, M and the ticket series) is retired, with each definition's History mapping the old ids.

Definitions. Every feature and core doc under product/ is rewritten into the definition shape (Problem, Definition, grouped acceptance criteria, scenarios on a shared example fleet, History): Squadron, agent-to-agent communication, the agent tool surface, the substrate, inbox, thread rendering, archive flow, Fleet page and sidebar (absorbing PR #107), Roles, Crews, Memos, Playbooks, Spawning Guide, shared Squadrons, PR pane, cross-device, problems, use cases, fleet vision, principles. The glossary is an index of names with owners plus the distinctions it owns itself. Definitions never reference plans or research.

Plans, records, research, runbooks. Plans live under plans/ with status and carry all build status (the A2A plan's status table; the dogfood v0 plan's "what the current build narrows" table keyed by definition and criterion). Worklog records are date-first and marked kind: record; research is stamped as_of; runbooks moved under runbooks/ with script references repaired. README.md rewritten as the map.

Rulings recorded on the way are already tracked as issues: #111 (several open asks per person, follow-ups by Exchange id). #117 and #119 landed on main during the pass and are recorded as built. Rebased onto main and absorbs #125, #131 and #132 in definition shape.

Docs only. Zero broken links across docs/j5.

Model: Claude Fable 5.1, harness: Claude Code via J5 Code (Product seat).

🤖 Generated with Claude Code

coderabbitai · 2026-09-05T17:11:31Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Essentials

Run ID: 523ab3d0-f7ce-4e7d-8628-5d223e386cbf

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

_{Comment @coderabbitai help to get the list of available commands.}

Jacksondr5 · 2026-09-05T17:35:24Z


-## The agent organizational family
+**Two kinds of entry.** Most terms name something a product definition owns; for those the entry is an index — the term, a one-line gloss that only identifies the thing, and the definition that owns it. The gloss never states a rule or a property; if a sentence here could be argued with, it belongs in the owning definition instead. A few terms are distinctions everyone must share but that no feature builds — Subagent versus Peer Agent is the model — and for those the glossary is the owner and the entry is the full definition.


Suggested change

**Two kinds of entry.** Most terms name something a product definition owns; for those the entry is an index — the term, a one-line gloss that only identifies the thing, and the definition that owns it. The gloss never states a rule or a property; if a sentence here could be argued with, it belongs in the owning definition instead. A few terms are distinctions everyone must share but that no feature builds — Subagent versus Peer Agent is the model — and for those the glossary is the owner and the entry is the full definition.

**Two kinds of entry.** Most terms name something a product definition owns; for those the entry is an index — the term, a one-line gloss that only identifies the thing, and the definition that owns it. The gloss never states a rule or a property; if a sentence here could be argued with, it belongs in the owning definition instead. A few terms are distinctions everyone must share but that no feature builds and for those the glossary is the owner and the entry is the full definition.

Jacksondr5 · 2026-09-05T17:35:57Z


-We use a civil-nautical theme to make onboarding users to these concepts easier.
+**Casing.** A named product concept is written in Title Case — Squadron, Crew, Captain, Role, Manifest, Playbook, Memo, Exchange, Peer Agent, Subagent, Spawning Guide, Registrar — so a reader knows it is our concept and not the ordinary word. Everything else is lowercase, including fleet, agent, participant, inbox, ledger and dashboard. A surface's proper name is Title Case (Fleet page). Code identifiers keep their own spelling.


Suggested change

**Casing.** A named product concept is written in Title Case — Squadron, Crew, Captain, Role, Manifest, Playbook, Memo, Exchange, Peer Agent, Subagent, Spawning Guide, Registrar — so a reader knows it is our concept and not the ordinary word. Everything else is lowercase, including fleet, agent, participant, inbox, ledger and dashboard. A surface's proper name is Title Case (Fleet page). Code identifiers keep their own spelling.

**Casing.** A named product concept is written in Title Case — Squadron, Crew, Captain, Role, etc. — so a reader knows it is our concept and not the ordinary word. Everything else is lowercase, including fleet, agent, participant, inbox, ledger and dashboard. A surface's proper name is Title Case (Fleet page). Code identifiers keep their own spelling.

Jacksondr5 · 2026-09-05T17:36:24Z

-| **Role**     | A reusable, user-authored definition of a kind of agent: identity/prompt content, model + reasoning allowlist, skill allowlist, posture. Spawnable solo or composed into Crew definitions. Defined in `features/roles.md`. (R28)                                                                     |
-| **Manifest** | Implementation vocabulary, not a separate concept: the artifact form of a Crew definition — composes Roles into a Crew with their wiring. The user's content — git-versioned, portable, shareable by construction. (R12, R28)                                                                        |
-| **Captain**  | Derived role archetype, not a platform entity: any agent with Crews placed under it. Runs Crews, serves as tie-breaker; never a communication router. Captaincy follows placement. Defined in `features/crews.md`. (R18–R22)                                                                         |
+**Upstream's words.** T3 Code's own vocabulary — thread, turn, project, worktree, provider, session, checkpoint, projection, receipt — is defined in [upstream's glossary](../../internals/glossary.md) and is not restated here. Upstream words that upstream does not define (settled, snoozed, pinned, archived, steer, queue) are used in J5 docs with upstream's meaning; where J5 defines behavior around one of them, the entry below points at the definition that does. J5 does not write its own definition of an upstream word unless a measured confusion requires one.


Suggested change

**Upstream's words.** T3 Code's own vocabulary — thread, turn, project, worktree, provider, session, checkpoint, projection, receipt — is defined in [upstream's glossary](../../internals/glossary.md) and is not restated here. Upstream words that upstream does not define (settled, snoozed, pinned, archived, steer, queue) are used in J5 docs with upstream's meaning; where J5 defines behavior around one of them, the entry below points at the definition that does. J5 does not write its own definition of an upstream word unless a measured confusion requires one.

**Upstream's words.** T3 Code's own vocabulary is defined in [upstream's glossary](../../internals/glossary.md) and is not restated here. Upstream words that upstream does not define are used in J5 docs with upstream's meaning; where J5 defines behavior around one of them, the entry below points at the definition that does. J5 does not write its own definition of an upstream word unless a measured confusion requires one.

Jacksondr5 · 2026-09-05T17:37:18Z

+| fleet               | All of a user's agents across every connected server — the totality, never a sub-grouping          | [cross-device.md](cross-device.md)                                                        |
+| **Squadron**        | The user-created grouping of agents and their work that everything else is organized under         | [features/squadron.md](features/squadron.md)                                              |
+| **Squadron home**   | The one Squadron an agent belongs to, recorded when it is created                                  | [features/squadron.md](features/squadron.md)                                              |
+| **Registrar**       | The creation-time step that records an agent's Squadron home                                       | [features/squadron.md](features/squadron.md)                                              |


"Registrar" as a step (an action) feels grammatically incorrect

bryantderosier

Reviewed at 30187f8462dc5dcc9616e69c2e6119bf38fce59a.

The reorganization makes the documentation easier to navigate, but four documentation issues need reconciliation before these definitions can serve as a consistent source of truth:

Preserve the original historical text in the new record files; several currently contain only a notice claiming the text was retained.
Include sender retirement in the Exchange closure contract, consistent with archive and inbox behavior.
Preserve the distinction between linking a new Exchange to an earlier one and joining an open ask through regarding.
Align archive behavior with the Fleet page's requirement to retain retired ancestors of active agents.

Inline comments describe the affected cases and suggested corrections. Relative Markdown file links and whitespace checks passed; the earlier glossary feedback appears incorporated.

Review posted by Codex.

bryantderosier · 2026-09-11T01:58:13Z

+kind: record
+---
+
+> **Record.** The register R1–R35 was the definition of record for much of the product until 2026-09-08, when each ruling moved into the definition that owns it. Where each landed: R1–R2, R11, R14–R15 → [archive flow](../product/features/archive-flow.md); R3–R4, R10, R25 → [agent-to-agent communication](../product/a2a/index.md); R5, R26 → [inbox](../product/features/inbox.md); R6 (external systems as nodes) → a door recorded in [shared Squadrons](../product/features/shared-squadrons.md); R7 (cost rolls up per Squadron) → the Fleet page definition when its contract lands; R8, R23 (posture), R28 → [roles](../product/features/roles.md); R9, R29 → [shared Squadrons](../product/features/shared-squadrons.md); R12–R13, R16–R22 → [crews](../product/features/crews.md); R21 (placement) → [squadron](../product/features/squadron.md); R24 → [principles](../product/principles.md); R27 → [playbooks](../product/features/playbooks.md); R30–R35 → [memos](../product/features/memos.md). Kept unedited as the session it was.


[P2] Preserve the original text beneath the record notice

This file ends after the notice: none of the original R1–R35 register is present despite the claim that it was kept unedited. The new decision-log, communication-graph-draft, initial-backlog, and PR-pane-brief records have the same problem. Following a definition's History link therefore reaches a placeholder rather than the decisions and rationale it promises. Please retain the original bodies under the new frontmatter and retirement notices so the historical references remain useful.

bryantderosier · 2026-09-11T01:58:13Z

+6. While an Exchange is open between two agents, a further ask from the same sender to the same receiver joins it as a follow-up rather than opening a second Exchange.
+7. An agent may hold several open Exchanges with the same person at once, each shown as its own inbox item.
+8. A follow-up to an open ask to a person references that Exchange by its id, joins it, and is shown beneath the original ask in the inbox.
+9. One reply naming the Exchange closes it, together with every follow-up that joined it; the sender may withdraw its own ask; the receiver's retirement closes it with a notice to the sender; nothing else closes it.


[P2] Include sender retirement among Exchange closure causes

For an agent with an outstanding ask to a person, archiving the agent must end that outgoing Exchange and remove the inbox item (archive-flow's Definition and inbox AC11). This criterion only permits receiver retirement, replies, and explicit withdrawal, then says nothing else closes it. An implementation following this exhaustive rule would leave an archived sender's obligations open. Please include retirement of either participant and keep the notice/inbox behavior consistent with the owning definitions.

bryantderosier · 2026-09-11T01:58:13Z

+
+**Rules.** A message to the caller itself is refused. A send to a person that is not an ask is refused; a person never opens an Exchange, so there is nothing for an agent to reply to. Between agents, a further ask to a peer that already holds an open Exchange from the caller joins it as a follow-up. To a person, a further ask opens a new Exchange and a new inbox item unless it names an open one in `regarding`, in which case it joins that Exchange and is shown beneath the original ask. An ask to a person without an urgency is refused.
+
+**Errors**, each naming the actual state and the next command: the caller has no Squadron home; the recipient is not addressable (pointing at `list_participants`); the recipient is the caller (naming the caller's own id, and `schedule_task` for a future trigger to oneself); an ask without an intent; a send to a person that is not an ask (naming the legal move and the own-thread alternative); an ask to a person without urgency; an `exchange_id` or `regarding` that is unknown, already closed, or not the caller's (naming the Exchange's actual state).


[P2] Keep earlier-Exchange linkage distinct from open-ask follow-ups

The regarding input now applies only to an open ask to a person, and this error rule rejects closed targets. That removes the former R10 use: after a peer's reply closes an Exchange but leaves part of the question unanswered, open a new Exchange linked to the earlier one. The A2A Definition still describes that recovery, and the principles' "Simple tools at the frontier" case still specifies referencing the earlier Exchange with one field. Please distinguish linking a new Exchange to a closed predecessor from joining an open human ask, or explicitly reconcile the other definitions if retiring that linkage is intentional.

bryantderosier · 2026-09-11T01:58:13Z

+
+6. Every waiter on an ended Exchange receives a platform notice rendered as a muted notice line in its thread.
+7. The person's inbox items from the archived agent leave immediately, with no terminal row.
+8. The archived agent leaves the active sidebar and the Fleet page; its ledger and conversation remain readable.


[P2] Preserve Fleet placeholders for archived agents with active descendants

When a coordinator is archived while its builders remain active, Fleet page AC11 requires its row to remain as a dimmed placeholder, with the builders beneath it and no re-parenting. This criterion and the Aftermath paragraph instead say the archived agent leaves the Fleet page unconditionally. Please add the active-descendant exception and refer to the Fleet definition so archive and tree rendering can satisfy the same contract.

…identifier kinds Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…le made unambiguous Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…ic citation rewritten Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

… a record; glossary review fixes; shared example fleet Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…ommunication-graph draft to a record; A2A plan to plans/ Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…olicies, truthful-steer guard, stop wins over restart continuation; Astra delivery guidance removed Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…plied everywhere; a person receives asks only and never opens one Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…s one (repairs edits missed against the staged text) Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…drons as definitions — the design-review register dissolved into them Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…n review and backlog become records; principles' cases point at definitions by name; GitHub milestones carry the backlog Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…pane as definitions; the posted PR-pane brief kept as a record Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…ter, research stamped as_of, runbooks under runbooks/, process classified, README rewritten Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Rewrites sidebar-and-roster as the Fleet page and sidebar definition (AC1–AC26, scenarios, History mapping SB1–SB7, FV1–FV11 and DV6), moves the 2026-09-04 fleet-visibility session record to its date-first name with a pointer to the definition, re-keys the dogfood plan's narrowing table by criterion, and gives the glossary's Fleet page, Squadron scope, orphan and delivery alarm terms their owners. Supersedes PR #107. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

… cross-environment changes Rebased onto j5/main. Folds main's five doc changes into the rewritten definitions in their own shape: list_squadrons and join_squadron in the agent tools and substrate definitions and as Squadron AC14; reversible archive, unarchive and separate deletion in the archive-flow and tools definitions; the cross-environment merge (#125) as cross-device AC7–AC10 and inbox criteria, with build status in the dogfood plan. Records #126 and #127 as landed in the A2A plan. Moves the Squadron Scope section into the Definition and the plan per the conventions. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

… shape The EnvelopeFormatter test reads the send_message description out of docs/j5/product/a2a/agent-tools.md and compares it byte-for-byte with the runtime string; the docs rewrite changed the heading and label the parser looked for. Update the parser to the definition shape, drop the stale "or a reply" toward a person from the runtime string (a person never opens an ask, so there is nothing to reply to; the channel itself went in #127), and hold the definition's description to the shipped string. The regarding sentence returns with #111. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

github-actions Bot added vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. size:L 100-499 effective changed lines (test files excluded in mixed PRs). labels Sep 5, 2026

Jacksondr5 commented Sep 5, 2026

View reviewed changes

Jacksondr5 force-pushed the j5/docs-product-cleanup branch from e9d3276 to b48da1b Compare September 7, 2026 17:53

github-actions Bot added size:XXL 1,000+ effective changed lines (test files excluded in mixed PRs). and removed size:L 100-499 effective changed lines (test files excluded in mixed PRs). labels Sep 7, 2026

Jacksondr5 mentioned this pull request Sep 11, 2026

docs(j5): fleet visibility acceptance contract (FV1–FV10, DV6) #107

Closed

Jacksondr5 marked this pull request as ready for review September 11, 2026 00:58

bryantderosier reviewed Sep 11, 2026

View reviewed changes

Jacksondr5 mentioned this pull request Sep 11, 2026

docs(j5): define portable user-authored agent libraries #75

Merged

Jacksondr5 and others added 14 commits September 13, 2026 20:48

docs(j5): how the J5 docs are organized — five kinds, lifetimes, two …

83026f2

…identifier kinds Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs(j5): glossary rewritten as index + owned distinctions; casing ru…

9ca13de

…le made unambiguous Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs(j5): cite principles by name — headings un-numbered, every numer…

25f2801

…ic citation rewritten Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs(j5): Squadron rewritten as a definition; naming session moved to…

5f72611

… a record; glossary review fixes; shared example fleet Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs(j5): A2A definition, substrate and agent-tools as definitions; c…

01899e1

…ommunication-graph draft to a record; A2A plan to plans/ Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs(j5): steering after the upstream integration — two independent p…

77331d4

…olicies, truthful-steer guard, stop wins over restart continuation; Astra delivery guidance removed Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs(j5): inbox, thread rendering and archive flow as definitions; Re…

50b0328

…plied everywhere; a person receives asks only and never opens one Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs(j5): A2A definition — a person receives asks only and never open…

c2510a2

…s one (repairs edits missed against the staged text) Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs(j5): Roles, Crews, Memos, Playbooks, Spawning Guide, Shared Squa…

37d599f

…drons as definitions — the design-review register dissolved into them Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs(j5): dogfood plan consolidated under plans/; decision log, desig…

e1f3314

…n review and backlog become records; principles' cases point at definitions by name; GitHub milestones carry the backlog Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs(j5): problems, use cases, fleet vision, cross-device and the PR …

8f489ed

…pane as definitions; the posted PR-pane brief kept as a record Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs(j5): mechanical sweep — records renamed date-first with frontmat…

ad9bcea

…ter, research stamped as_of, runbooks under runbooks/, process classified, README rewritten Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Jacksondr5 force-pushed the j5/docs-product-cleanup branch from 30187f8 to 02541e6 Compare September 14, 2026 02:11

Jacksondr5 enabled auto-merge (squash) September 14, 2026 02:11

Jacksondr5 changed the title ~~docs(j5): product docs cleanup — kinds, identifiers, glossary~~ docs(j5): product docs cleanup — kinds, identifiers, definitions Sep 14, 2026

Jacksondr5 merged commit 078c2cd into j5/main Sep 14, 2026
21 checks passed

Jacksondr5 deleted the j5/docs-product-cleanup branch September 14, 2026 03:15

Navigation Menu

Repository navigation

docs(j5): product docs cleanup — kinds, identifiers, definitions - #110

docs(j5): product docs cleanup — kinds, identifiers, definitions#110
Jacksondr5 merged 15 commits into
j5/mainfrom
j5/docs-product-cleanup

Jacksondr5 commented Sep 5, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 5, 2026 •

edited

Loading

Review skipped

Uh oh!

Jacksondr5 Sep 5, 2026

Uh oh!

Jacksondr5 Sep 5, 2026

Uh oh!

Jacksondr5 Sep 5, 2026

Uh oh!

Jacksondr5 Sep 5, 2026

Uh oh!

bryantderosier left a comment

Uh oh!

bryantderosier Sep 11, 2026

Uh oh!

bryantderosier Sep 11, 2026

Uh oh!

bryantderosier Sep 11, 2026

Uh oh!

bryantderosier Sep 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## The agent organizational family
		Two kinds of entry. Most terms name something a product definition owns; for those the entry is an index — the term, a one-line gloss that only identifies the thing, and the definition that owns it. The gloss never states a rule or a property; if a sentence here could be argued with, it belongs in the owning definition instead. A few terms are distinctions everyone must share but that no feature builds — Subagent versus Peer Agent is the model — and for those the glossary is the owner and the entry is the full definition.


		We use a civil-nautical theme to make onboarding users to these concepts easier.
		Casing. A named product concept is written in Title Case — Squadron, Crew, Captain, Role, Manifest, Playbook, Memo, Exchange, Peer Agent, Subagent, Spawning Guide, Registrar — so a reader knows it is our concept and not the ordinary word. Everything else is lowercase, including fleet, agent, participant, inbox, ledger and dashboard. A surface's proper name is Title Case (Fleet page). Code identifiers keep their own spelling.


		Rules. A message to the caller itself is refused. A send to a person that is not an ask is refused; a person never opens an Exchange, so there is nothing for an agent to reply to. Between agents, a further ask to a peer that already holds an open Exchange from the caller joins it as a follow-up. To a person, a further ask opens a new Exchange and a new inbox item unless it names an open one in `regarding`, in which case it joins that Exchange and is shown beneath the original ask. An ask to a person without an urgency is refused.

		Errors, each naming the actual state and the next command: the caller has no Squadron home; the recipient is not addressable (pointing at `list_participants`); the recipient is the caller (naming the caller's own id, and `schedule_task` for a future trigger to oneself); an ask without an intent; a send to a person that is not an ask (naming the legal move and the own-thread alternative); an ask to a person without urgency; an `exchange_id` or `regarding` that is unknown, already closed, or not the caller's (naming the Exchange's actual state).

Conversation

Jacksondr5 commented Sep 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Sep 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bryantderosier left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Jacksondr5 commented Sep 5, 2026 •

edited

Loading

coderabbitai Bot commented Sep 5, 2026 •

edited

Loading