Skip to content

docs: name worker sessions with an imperative sentence#3

Merged
LeTuR merged 1 commit into
mainfrom
docs/session-naming
Jul 9, 2026
Merged

docs: name worker sessions with an imperative sentence#3
LeTuR merged 1 commit into
mainfrom
docs/session-naming

Conversation

@LeTuR

@LeTuR LeTuR commented Jul 9, 2026

Copy link
Copy Markdown
Contributor

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:

Run exec automations off the TUI thread     good
Document the customization surface          good
thurbox-automation-nonblocking              bad — a kebab slug, reads as an id
Fix stuff                                   bad — says nothing

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 runs reads as the work. The repo prefix was pure waste —
the session already carries the repo in its cwd, and the run log has a column
for it.

Spaces are verified to round-trip. A throwaway session confirmed that
session create --name 'Probe sentence casing' succeeds, session get --json
returns "name": "Probe sentence casing" intact, and
message 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 --name are 1–64 chars, no slashes,
no leading ..

Because the name is a mailbox address, the --to / --for examples are now
quoted: an unquoted spaced name is split by the shell and mails somewhere else.
The branch stays kebab-case and keeps its slashes (--worktree-branch
fix/automation-exec-nonblocking) — the branch is not the name.

Changed

  • .claude/skills/thurbox-session/SKILL.md — new Naming a session
    subsection under §1; --name flag row corrected; session create examples
    (single- and multi-repo) now demonstrate the convention; mailbox addresses
    quoted.
  • orchestration/runs/_TEMPLATE.md — sentence-case example in the session table
    and timeline.
  • orchestration/playbooks/{_TEMPLATE,ship-feature,cross-repo-sweep}.md — name
    guidance updated. cross-repo-sweep keeps the repo in the name (as the
    object of the sentence, bare, no owner — --name takes no slashes), since a
    sweep runs one goal N times and identical mailbox addresses are ambiguous.
  • README.md — the "seventh appearance of fleet" paragraph described the old
    fleet-<slug> convention; reworded. Mailbox examples quoted.

The fleet session, agent, and extension are untouched — that name is the
deliberate six-place coupling the README's "Customizing" section describes, and
it is not what this PR is about.

Gates

shellcheck scripts/*.sh passes; git diff --stat shows .md files only.

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.
@LeTuR
LeTuR merged commit f618c5e into main Jul 9, 2026
4 checks passed
@LeTuR
LeTuR deleted the docs/session-naming branch July 9, 2026 19:46
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.

1 participant