fix(playbooks): kebab-case names so /playbook keeps the name when text follows it

[bryantderosier]

Problem

/playbook treated everything after the command as the playbook name. "/playbook release, then make a crew" went out as "Start playbook release, then make a crew", so the agent was asked to start a playbook named "release, then make a crew". /playbook release followed by more text on the next line wasn't expanded at all. The underlying cause is that playbook names allowed spaces, so no text rule could tell where a name ends. @playbook: (#320) has the same problem.

What I changed

• packages/contracts/src/j5/playbook.ts → PLAYBOOK_NAME_PATTERN: a playbook name is now kebab-case (^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$), the same pattern AgentPersonaId already enforces. New suggestPlaybookName turns a stem like "Release Plan" into release-plan.
• apps/server/src/j5/playbooks/PlaybookStore.ts → discover: a .yaml file with any other name is still listed, with an invalid_name issue that suggests the rename, instead of being silently hidden. removeDefinition accepts any safe file stem, so a misnamed file can still be deleted from Settings. start refuses non-kebab names with a message pointing at playbook_list.
• apps/web/src/j5/playbooks/importPlaybookFile.ts → playbookImportName: Settings import converts names (Release Plan.yaml is saved as release-plan.yaml) instead of rejecting them.
• packages/client-runtime/src/j5/playbooks.ts → expandPlaybookPrompt: the word after /playbook is the name (lowercased, without trailing punctuation or .yaml), and any text after it is kept as its own paragraph ("Start playbook release." then "then make a crew"). A word that isn't a valid name leaves the message unchanged. PLAYBOOK_AUTHOR_INSTRUCTIONS now requires kebab-case names and puts the human-readable name in title.
• docs/user/playbooks.md: the naming rule, import conversion, and trailing text.

Why this shape

The first commit tried JSON-quoting names that contain spaces. I dropped that for one rule shared with personas: @playbook:release-review reads exactly like @persona:code-reviewer, and #320 needs no quoting. Nothing is lost for display, because every definition already has a title and the library, Fleet, and step board show it. I rejected a convention alone (Playbook Author suggesting hyphens) because imports and hand-saved files would still allow spaces. The client can't check names against the workspace's playbook list, since the expansion runs on web and three mobile submit paths without it, so the rule has to work on the text alone.

Invariants

• suggestPlaybookName always returns a name that matches PLAYBOOK_NAME_PATTERN, or null.
• A misnamed file never disappears: it's listed with its title and a rename hint, can't be started or renamed, and can be deleted.
• Only a message that starts with /playbook (case-insensitive, followed by whitespace or the end) is rewritten. /playbooks, /plan, and mid-sentence /playbook are untouched.

Surfaces

Surface	Decision
Entry points (chat, Settings, command palette, keybinding)	changed: the composer's /playbook expansion, the Settings library (misnamed files show the rename hint), and Settings import
Clients (web, desktop, mobile)	changed: all share expandPlaybookPrompt. The web and mobile libraries render the server's issue.message as they already do. Import is web and desktop only
Providers	unaffected: playbook_list and playbook_start return the same shapes, with a new issue code on misnamed files
Contracts (packages/contracts)	changed: PLAYBOOK_NAME_PATTERN and the new suggestPlaybookName helper, both in the J5-owned src/j5/playbook.ts
Reverse states	covered: a misnamed file can be deleted, or renamed on disk by the suggested name
Connection modes (local, remote, tunnel)	unaffected: same J5 routes and MCP tools
Upstream files / FORK.md	unaffected: only J5-owned files change
Docs	changed: docs/user/playbooks.md

Out of scope

• The @playbook: mention and its pickers (Mention a playbook with @playbook: in the composer #320).
• Renaming misnamed files automatically. The server never renames workspace files; it suggests the name.

Upgrade and data

No migration. Run history stores absolute definition paths and is unaffected. A workspace file whose name isn't kebab-case now shows as invalid until it's renamed. The only definition I know of in real use, agent-development-delivery.yaml, already matches.

Verification

• vp test run packages/contracts/src/j5/playbook.test.ts packages/client-runtime/src/j5/playbooks.test.ts apps/web/src/j5/playbooks/importPlaybookFile.test.ts apps/server/src/j5/playbooks/: 110 passed. New tests: the name pattern and suggestion; trailing text, the next-line case, and invalid words in the expansion; a misnamed file listed with a hint, refused at start, and deleted; import conversion.
• vp test run apps/web/src/j5/playbooks apps/mobile/src/j5/playbooks apps/mobile/src/features/threads/use-composer-command-menu.test.ts apps/server/src/j5/a2a/Migrations.test.ts: 49 passed.
• tsc --noEmit for packages/contracts, packages/client-runtime, apps/server, and apps/web: 0 errors. vp lint on the touched files: clean.

Review focus

• PlaybookStore.discover and removeDefinition: a misnamed file should stay visible and deletable, and never be startable.
• Whether requiring a leading letter (as persona ids do) is right for playbooks. 2026 plan.yaml imports as playbook-2026-plan.

Part of #320

Claude Opus 5.5 via J5 Code

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Repository: Jacksondr5/j5code/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 84d019bd-d415-4ba2-a1e6-5e96f184e4b0

---

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