docs: name worker sessions with an imperative sentence#3
Merged
Conversation
Worker session names read as identifiers (`fleet-ship-<slug>`, `thurbox-automation-nonblocking`) rather than as the work they stand for. Adopt an imperative summary in sentence case instead. Spaces in `--name` are verified to round-trip through `session create`, `session get --json`, and `message send --to`, so the "hyphenated, no spaces" rule in the playbook template was simply wrong. The real constraints are 1-64 chars, no slashes, no leading dot. Since a name is a mailbox address, quote it in shell examples; an unquoted spaced name is split by the shell and mails somewhere else. This does not touch the `fleet` session, agent, or extension.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Renames the convention for thurbox worker session names — no existing session
is renamed. Names go from kebab-case slugs to an imperative summary in sentence
case:
Documentation only. No script or behavior changes.
Why
A session name is the first thing an operator reads in the TUI window list and
the run log.
fleet-ship-<slug>reads as an identifier for the work;Cache the registry sync between runsreads as the work. The repo prefix was pure waste —the session already carries the repo in its
cwd, and the run log has a columnfor it.
Spaces are verified to round-trip. A throwaway session confirmed that
session create --name 'Probe sentence casing'succeeds,session get --jsonreturns
"name": "Probe sentence casing"intact, andmessage send --to 'Probe sentence casing'returns{"enqueued":true,"woke":true}.The playbook template's "hyphenated, no spaces" rule was therefore wrong, not
merely stylistic. The real constraints on
--nameare 1–64 chars, no slashes,no leading
..Because the name is a mailbox address, the
--to/--forexamples are nowquoted: an unquoted spaced name is split by the shell and mails somewhere else.
The branch stays kebab-case and keeps its slashes (
--worktree-branchfix/automation-exec-nonblocking) — the branch is not the name.Changed
.claude/skills/thurbox-session/SKILL.md— new Naming a sessionsubsection under §1;
--nameflag row corrected;session createexamples(single- and multi-repo) now demonstrate the convention; mailbox addresses
quoted.
orchestration/runs/_TEMPLATE.md— sentence-case example in the session tableand timeline.
orchestration/playbooks/{_TEMPLATE,ship-feature,cross-repo-sweep}.md— nameguidance updated.
cross-repo-sweepkeeps the repo in the name (as theobject of the sentence, bare, no owner —
--nametakes no slashes), since asweep runs one goal N times and identical mailbox addresses are ambiguous.
README.md— the "seventh appearance offleet" paragraph described the oldfleet-<slug>convention; reworded. Mailbox examples quoted.The
fleetsession, agent, and extension are untouched — that name is thedeliberate six-place coupling the README's "Customizing" section describes, and
it is not what this PR is about.
Gates
shellcheck scripts/*.shpasses;git diff --statshows.mdfiles only.