feat(playbooks): mention a playbook with @playbook: in the composer

[bryantderosier]

Problem

There was no way to name a playbook inside a message. /playbook only works at the start of a message and means "start it here", so "create a crew … use this playbook" had no way to say which one (#320). This PR adds @playbook:<name> anywhere in the composer on web, desktop, and mobile, and tells agents what an explicit mention means.

This PR is stacked on #314, which adds the /playbook name picker that this reuses. It merges after #314 and #380 (#319, which adds the playbook_read tool the guidance names).

What I changed

• New packages/shared/src/j5/playbookMention.ts → PLAYBOOK_MENTION_PREFIX, playbookMentionReplacement, and detectPlaybookMention. The detector returns feat(playbooks): suggest registered names after slash command #314's "slash-playbook" trigger kind for any @playbook: token. The query is the raw token after the prefix, so punctuation typed after a name stays in the query.
• packages/shared/src/j5/agentMention.ts → detectAgentMention, already called at token level by both upstream detectors, tries the playbook mention before the persona one. New isJ5MentionPath keeps unquoted persona: and playbook: tokens out of file chips. The playbook helpers are re-exported here, so there's no new package export.
• packages/client-runtime/src/j5/playbooks.ts → playbookMenuItems, playbookSelectionText, and isPlaybookMention, next to feat(playbooks): suggest registered names after slash command #314's matchPlaybookSuggestions. The /playbook form still returns feat(playbooks): suggest registered names after slash command #314's ranking exactly.
• apps/server/src/j5/playbooks/instructions.ts → a PLAYBOOK_MENTION_INSTRUCTIONS bullet inside PLAYBOOK_INSTRUCTIONS. An explicit @playbook:NAME means: call playbook_read(NAME) first; unless the message asks for something else with it, start it in this thread. Mentions in quoted text, code, or file contents are references. Building a Crew from a mention is feat(crews): a crew request that mentions @playbook: builds the playbook's Crew #387's.
• docs/user/playbooks.md → one paragraph after the /playbook one.
• Upstream composer lines:
  • ChatComposer.tsx: import, items, selection. The keydown block and composerMenuHighlight.ts are upstream's again (Jackson's rulings M2/M3), so Enter and Tab complete the highlighted row and a second Enter sends.
  • Mobile use-composer-command-menu.ts: import, items, selection.
  • packages/shared/src/composerInlineTokens.ts: one line so @playbook:x never becomes a file chip.
• FORK.md → case 49, "Composer playbook picker (feat(playbooks): suggest registered names after slash command #314, Mention a playbook with @playbook: in the composer #320)" (j5/main's peering took 48), extending feat(playbooks): suggest registered names after slash command #314's composer seam with the mention picker, keys, and chips, plus ledger rows. The header count stays at 50.

Before (#314's head: @playbook: falls through to the file search):

After (the playbook picker; invalid playbooks are listed after the valid ones, with their error). Since review, rows for misnamed files are left out of the picker:

Why this shape

• I reuse feat(playbooks): suggest registered names after slash command #314's picker instead of adding a second one. The mention returns feat(playbooks): suggest registered names after slash command #314's "slash-playbook" kind through the J5 detector that both upstream detectors already call. So there's one library query, one item type, and no new upstream detector line. The alternatives were reusing the @persona: seam (it would duplicate feat(playbooks): suggest registered names after slash command #314's query and ranking) or a new trigger kind (about 12 upstream lines instead of about 6).
• Invalid playbooks show with their error, in the mention picker only. An invalid definition with a valid name is still insertable, because the agent can help fix the file. A misnamed file (non-kebab stem) is left out, since @playbook:Release Notes isn't a valid mention and the composer menus have no disabled state; its rename hint shows in Settings. feat(playbooks): suggest registered names after slash command #314's /playbook picker keeps hiding invalid entries.
• Docs only in docs/user/playbooks.md. The upstream docs/user/composer.md doesn't document @persona: either, so I left it alone.

Invariants

• The /playbook command form keeps feat(playbooks): suggest registered names after slash command #314's items and ranking. Enter and Tab complete the highlighted row like every composer menu, including a bare /playbook or an exact name, and a second Enter sends. A bare /playbook is still sendable with the send button.
• The mention picker never lists a row it can't insert.
• The mention query is the raw token after @playbook:, so picking a row never removes text the user typed after it.
• @playbook: text is always plain editable text, never a file chip, on web and mobile.
• The mention and /playbook share one library query per composer, including new-thread drafts (feat(playbooks): suggest registered names after slash command #314's project and thread inputs).

Surfaces

Surface	Decision
Entry points (chat, Settings, command palette, keybinding)	changed: the composer, including new-thread drafts; no Settings, palette, or keybinding surface
Clients (web, desktop, mobile)	changed: web and desktop ChatComposer, mobile command menu
Providers	changed: the guidance reaches every provider through the shared instructions; the mention itself is plain text
Contracts (packages/contracts)	unaffected
Reverse states	the mention is ordinary text; delete it to remove it; nothing is persisted
Connection modes (local, remote, tunnel)	unaffected: #314's authenticated library route
Upstream files / FORK.md	changed: the composer lines above, recorded in FORK.md case 49 together with #314's seam
Docs	changed: docs/user/playbooks.md

Out of scope

• Building a Crew from a mention ("Create a crew … use @playbook:name" builds a playbook-shaped Crew #323) and recording the playbook on a Crew (A Crew proposal records the playbook it follows #321).
• Suggesting @playbook: from a bare @.

Upgrade and data

None. No contracts, migrations, or persisted state.

Verification

• vp test run packages/shared/src/j5/playbookMention.test.ts packages/shared/src/j5/agentMention.test.ts packages/client-runtime/src/j5/playbooks.test.ts apps/mobile/src/features/threads/use-composer-command-menu.test.ts apps/web/src/composer-logic.test.ts apps/web/src/components/chat/composerMenuHighlight.test.ts apps/server/src/provider/T3OrchestrationInstructions.test.ts packages/shared/src/j5/playbookTrigger.test.ts apps/mobile/src/j5/upstreamSeams.test.ts: 194 tests pass. composerMenuHighlight.ts and its test match upstream again.
• New tests cover:
  • detection, including trailing punctuation staying in the query;
  • @persona: detection unchanged;
  • no file chip for @playbook:;
  • web's separate detector;
  • mention-mode ordering with invalid entries;
  • misnamed files left out of the mention picker;
  • a bare @playbook: offers rows, so Enter completes the first instead of sending;
  • /playbook deb still completing as before.
• vp exec tsc --noEmit -p . in packages/shared, packages/client-runtime, apps/web, apps/mobile, and apps/server: clean. vp lint on the touched files: 0 errors. The 45 warnings in ChatComposer.tsx and use-composer-command-menu.ts are the same set as on feat(playbooks): suggest registered names after slash command #314's head.
• Screenshots come from isolated dev servers with sample playbooks (two valid, one broken definition, one misnamed file). Web only; I didn't run mobile.

Review focus

• The selection change in ChatComposer.tsx and resolveComposerCommandSelection. The keydown block should now match upstream exactly.
• FORK.md case 49: whether it describes feat(playbooks): suggest registered names after slash command #314's seam and this PR's additions accurately.

Closes #320 (stacked on #314)

Claude Opus 5.5 via J5 Code (crew: planner, builder, and two reviewers on Claude and Codex)

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Choose registered playbooks from composer suggestions using /playbook , or reference one by name with @playbook:.
  • Playbook suggestions show loading, errors, and empty results; selection inserts the playbook into your message.
  • Playbook commands are available at the start of a message. Press Enter on a bare /playbook command to send it without selecting a suggestion.

• Documentation

  • Updated playbook guidance with instructions for both selection methods.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Advanced

Run ID: c367e32a-f993-4c07-98d6-4cbe14147c0c

📥 Commits

Reviewing files that changed from the base of the PR and between e1d7af7 and f00a915.

📒 Files selected for processing (28)

• FORK.md
• apps/mobile/src/features/threads/ComposerCommandPopover.tsx
• apps/mobile/src/features/threads/NewTaskDraftScreen.tsx
• apps/mobile/src/features/threads/ThreadComposer.tsx
• apps/mobile/src/features/threads/ThreadDetailScreen.tsx
• apps/mobile/src/features/threads/use-composer-command-menu.test.ts
• apps/mobile/src/features/threads/use-composer-command-menu.ts
• apps/mobile/src/j5/upstreamSeams.test.ts
• apps/server/src/j5/playbooks/instructions.ts
• apps/web/src/components/ChatView.tsx
• apps/web/src/components/chat/ChatComposer.tsx
• apps/web/src/components/chat/ComposerCommandMenu.tsx
• apps/web/src/components/chat/composerMenuHighlight.test.ts
• apps/web/src/components/chat/composerMenuHighlight.ts
• apps/web/src/composer-logic.test.ts
• apps/web/src/composer-logic.ts
• docs/user/playbooks.md
• packages/client-runtime/src/j5/playbooks.test.ts
• packages/client-runtime/src/j5/playbooks.ts
• packages/shared/package.json
• packages/shared/src/composerInlineTokens.ts
• packages/shared/src/composerTrigger.ts
• packages/shared/src/j5/agentMention.test.ts
• packages/shared/src/j5/agentMention.ts
• packages/shared/src/j5/playbookMention.test.ts
• packages/shared/src/j5/playbookMention.ts
• packages/shared/src/j5/playbookTrigger.test.ts
• packages/shared/src/j5/playbookTrigger.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds /playbook suggestions and @playbook: mentions to web and mobile composers. Shared detection and client-runtime helpers support trigger recognition, suggestion selection, and completion. Server instructions and user documentation describe playbook mention handling.

Changes

Playbook composer

Layer / File(s)	Summary
Shared playbook trigger and mention detection packages/shared/package.json, packages/shared/src/j5/*, packages/shared/src/composerTrigger.ts, packages/shared/src/composerInlineTokens.ts	Shared code detects /playbook and @playbook: triggers, formats mention replacements, and excludes playbook paths from unquoted inline file tokens.
Playbook suggestion and completion rules packages/client-runtime/src/j5/playbooks.ts, packages/client-runtime/src/j5/playbooks.test.ts	The runtime ranks suggestions, creates menu items for slash commands and mentions, and defines keyboard completion behavior.
Web composer trigger, picker, and selection apps/web/src/composer-logic.ts, apps/web/src/composer-logic.test.ts, apps/web/src/components/ChatView.tsx, apps/web/src/components/chat/ChatComposer.tsx, apps/web/src/components/chat/ComposerCommandMenu.tsx, apps/web/src/components/chat/composerMenuHighlight.ts, apps/web/src/components/chat/composerMenuHighlight.test.ts	The web composer queries playbooks for the selected project, displays picker states, and inserts selection text. A bare /playbook command does not automatically highlight the first item.
Mobile composer trigger, picker, and selection apps/mobile/src/features/threads/ComposerCommandPopover.tsx, apps/mobile/src/features/threads/NewTaskDraftScreen.tsx, apps/mobile/src/features/threads/ThreadComposer.tsx, apps/mobile/src/features/threads/ThreadDetailScreen.tsx, apps/mobile/src/features/threads/use-composer-command-menu.ts, apps/mobile/src/features/threads/use-composer-command-menu.test.ts, apps/mobile/src/j5/upstreamSeams.test.ts	The mobile composer passes project and server-thread context to the command-menu hook, which queries and displays playbook suggestions. The command popover also supports empty playbook results.
Playbook mention instructions and usage apps/server/src/j5/playbooks/instructions.ts, docs/user/playbooks.md	Server instructions describe handling explicit playbook mentions. User documentation describes playbook selection and starting through /playbook and @playbook:.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  actor User
  participant ChatComposer
  participant detectComposerTrigger
  participant PlaybookLibraryQuery
  participant playbookMenuItems
  participant ComposerCommandMenu
  User->>ChatComposer: Type a slash-playbook query
  ChatComposer->>detectComposerTrigger: Detect the current composer trigger
  detectComposerTrigger-->>ChatComposer: Return trigger kind and query
  ChatComposer->>PlaybookLibraryQuery: Load playbooks for the selected project
  ChatComposer->>playbookMenuItems: Build suggestions from query results
  playbookMenuItems-->>ComposerCommandMenu: Return playbook menu items
  User->>ComposerCommandMenu: Select a playbook
  ComposerCommandMenu->>ChatComposer: Apply playbook selection text

Loading

Merge Risk: 🔵 Low · up to f00a9

Mergeable with a bounded follow-up: drafts targeting another worktree can show the project root’s playbooks instead. Users can enter known playbook names manually.

Security Architecture Review

Security architecture risk: 🔵 Low · up to f00a9

Existing access and ownership checks limit playbook execution. However, drafts can discover playbooks from a different worktree than the one used for execution, and the required read-first operation is unavailable in this revision. These are bounded risks; no privilege escalation was established.

Retained concerns

• Medium · architecture · inferred: A draft targeting a non-default worktree discovers playbooks from the project root because its library request carries no draft-workspace identity. Selection inserts only the playbook name, while playbook_start resolves the invoking thread's worktree. If the worktrees contain different definitions under that name, the agent can receive instructions different from the definition represented by the picker. Exposure is bounded to the selected project and existing agent authority; no authorization bypass was established. Whether this mismatch already existed in prerequisite #314 is unresolved.

Security review details

Security Blast Radius

• inferred — The demonstrated execution scope is an orchestration-capable invocation's owner thread and resolved workspace. A misleading playbook definition could influence that agent's subsequent work under its existing authority, but this review did not establish additional credentials, cross-tenant reach, or privilege escalation. The unavailable read operation prevents a complete exposure assessment of the read-first path.

Security Findings and Attack Paths

• inferred — The supported conditional path is definition substitution across worktrees: a draft discovers a project-root name, inserts that name into the message, and later starts the same name in its thread worktree. Different definitions can therefore change the instructions the agent receives. Exploitation would require control over a relevant definition and execution of the mention; neither malicious content nor an authorization bypass was demonstrated.

Trust Boundaries and Controls

• observed — Tool-side authority remains separate from mention interpretation: orchestration capability is required, run access checks owner-thread equality, and workspace selection comes from the invocation's thread. The inspected denial tests cover missing capability and cross-owner access; they do not establish authorization or availability of playbook_read.
• observed — The quoted-text, code, and file-content exception is expressed in agent-facing guidance. The inspected mention path did not establish a provenance-aware runtime gate or enforced read-before-start ordering. This is a control limitation, not evidence that an attacker successfully bypassed the exception.

Resilience and Maintainability Implications

• observed — Recovery is owner-scoped: current retrieves persisted progress, cancellation remains available when definitions are invalid, and stale or terminal transitions are rejected. These safeguards govern tool operations; they do not bind a prior read result or picker selection to the live definition consumed at start.

Hardening Proposals

• proposed — Carry a server-validated draft-workspace identity through discovery and preserve that identity when resolving the selected name. If read-before-start is intended as a safety guarantee, make read failure stop the transition and bind the subsequent start to the same workspace and definition identity.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR implements the shared @playbook: detector, web/mobile picker flow, workspace query inputs, invalid-definition rows, server guidance, documentation, seam coverage, and tests required by #320. …	Update @playbook: detection and replacement-range handling so trailing punctuation is excluded from the playbook name and remains in the message. Add or update tests for comma, period, and other required trailing punctuation cases. Keep i…
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 25 files. (2 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Out of Scope Changes check	✅ Passed	The changed composer logic, shared helpers, picker behavior, invalid-playbook presentation, tests, server instructions, documentation, and upstream seam support the objectives in #320. The /playbook…
Title check	✅ Passed	The title clearly identifies the primary change: adding @playbook: mentions in the composer.
Description check	✅ Passed	The description explains the problem, implementation, UI behavior, upstream impact, testing, documentation, scope, and model/harness. It includes screenshots and verification details, although it uses…

Full details: Linked Issues check

Explanation

The PR implements the shared @playbook: detector, web/mobile picker flow, workspace query inputs, invalid-definition rows, server guidance, documentation, seam coverage, and tests required by #320. The PR does not satisfy the trailing-punctuation rule in #320. detectPlaybookMention returns the full suffix as query, and the tests explicitly require review, and review. to remain in the query. Therefore, a mention followed by punctuation does not identify the kebab-case name review for picker matching. The deferred Crew behavior is not assessed as missing because the PR and #320 assign it to #387.

Resolution

Update @playbook: detection and replacement-range handling so trailing punctuation is excluded from the playbook name and remains in the message. Add or update tests for comma, period, and other required trailing punctuation cases. Keep invalid names and file-chip exclusion covered.

Full details: Docstring Coverage

Explanation

Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 25 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch j5/playbook-mention

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

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

[Jacksondr5]

[Review panel: Opus 5.5, Sonnet 5.5, Sol 6.1]

Three findings are inline. Reusing #314's picker through detectAgentMention is the right minimal shape, and the panel's live passes found the picker, plain @ file and thread mentions, and single-agent delivery all working.

Noted, not a finding: this PR conflicts with #380 in instructions.ts and docs/user/playbooks.md, and relies on #380 for playbook_read.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
j5-code	Ready	Preview	Sep 30, 2026 5:24pm UTC

[Jacksondr5]

[Coordinator-relayed: Jackson's decisions, checked by Review panel: Opus 5.5]

Jackson ruled on the panel's two open decisions. Both remove behavior #314 brought to j5/main. This PR already rewrites those lines, so the panel recommends removing both here rather than in a follow-up.

M2: drop "bare /playbook + Enter sends the list request"

With it gone, Enter on a bare /playbook completes the first row, like every other composer menu. Remove:

• packages/client-runtime/src/j5/playbooks.ts:339-343: isBarePlaybookCommand, and its test at playbooks.test.ts:584-593.
• ChatComposer.tsx:
  • the import at line 60;
  • the comment and composerMenuAutoHighlight at 2781-2782;
  • autoHighlight: composerMenuAutoHighlight at 2789 and 3414;
  • the composerMenuAutoHighlight deps at 2795 and 3425;
  • the keydown default at 4422-4426, back to upstream's activeComposerMenuItemRef.current ?? currentItems[0].
• Upstream apps/web/src/components/chat/composerMenuHighlight.ts:6-7,21: revert to upstream, so line 21 reads return input.items[0]?.id ?? null;. Also delete the "leaves nothing active without a highlight when auto-highlight is off" test at composerMenuHighlight.test.ts:19-35. Nothing else uses this option; the autoHighlight props in ComposerCommandMenu.tsx and elsewhere belong to upstream's Command component.
• FORK.md:
  • drop the ledger rows for composerMenuHighlight.ts and composerMenuHighlight.test.ts;
  • in case 49 "Keys", drop the autoHighlight sentence, the bare-list clause, and the isBarePlaybookCommand sentence;
  • in "Rebase checks", drop composerMenuHighlight.test.ts.
• Keep expandPlaybookPrompt's list branch. A bare /playbook is still sendable with the send button (and on mobile), or when no playbook matches, so the docs/user/playbooks.md:50 wording stays true.

M3: drop "Enter sends an exact name instead of completing"

Follow upstream: Enter and Tab always complete the highlighted item, and a second Enter sends. Remove:

• packages/client-runtime/src/j5/playbooks.ts:259-274: shouldCompleteComposerMenuSelection, and its test table at playbooks.test.ts:595-618.
• ChatComposer.tsx: the import at line 64, and the condition at 4435-4437, back to upstream's if ((key === "Enter" || key === "Tab") && selectedItem) {.
• FORK.md case 49 "Keys": drop the "Enter sends … an exact name (shouldCompleteComposerMenuSelection, J5)" clause.

After both, the keydown block in ChatComposer.tsx matches upstream again, and composerMenuHighlight.ts leaves the ledger.

No change on mobile. Its popover has no Enter handling for this, and #314's slash-playbook popover visibility is unaffected.

[bryantderosier]

@Jacksondr5 applied both rulings in this PR:

• M2 (de4cc82): a bare /playbook plus Enter now completes the first row like every other composer menu. isBarePlaybookCommand, the autoHighlight option and its test are gone, and composerMenuHighlight.ts and its test match upstream again. expandPlaybookPrompt's list branch stays, so a bare /playbook is still sendable with the send button or on mobile, and the docs line holds.
• M3 (1b76353): Enter and Tab always complete the highlighted row, and a second Enter sends. shouldCompleteComposerMenuSelection and its test table are gone.

The ChatComposer.tsx keydown block is upstream's again, and FORK.md case 49 "Keys" and "Rebase checks" are trimmed to match. Mobile didn't import either helper, so nothing changed there. A bare @playbook: still never sends: it offers rows, so Enter picks one, and there's a test for that.