formax-slash-command-workflow

name	formax-slash-command-workflow
description	Use when adding/modifying Formax slash commands (/permissions /agents /hooks /todos etc), especially output rendering (command sublines), overlay dismiss messages, and whether outputs are injected into the next LLM turn.

Formax slash command workflow

Goal

Use this skill when changing slash command discovery, dispatch, overlay dismissal output, or next-turn injection behavior.

Read First

• docs/contracts/slash-command-contract.md
• docs/contracts/semantics-contract.md when command behavior crosses canonical UI messages or routing
• docs/contracts/config-settings-contract.md when the change touches /config

These docs are canonical. If stable behavior changes, update them before or with code.

Code Map

1) Command discovery + dispatch

• packages/core/src/features/commands/registry.ts: command list/suggest/dispatch wiring
• packages/core/src/features/commands/CommandStore.ts: disk scanning + precedence (project overrides user)
• packages/core/src/features/semantics/core/commandRouting.ts: exact /clear / /compact and command-dispatch routing boundary

2) Command result contract (UI vs model)

• packages/core/src/features/commands/contracts.ts: UiEffect / UiMessage / ModelEffect shapes
• packages/core/src/features/commands/adapter.ts: maps command execution output → CommandResult
• packages/core/src/features/repl/controller/send/send.ts: consumed slash handling, local_async, and injected-block plumbing

3) Overlay dismissal “subline output”

• packages/core/src/features/repl/controller/ui/overlays.ts: overlay open/close + append “dismissed” sublines

4) REPL message plumbing + rendering

• packages/core/src/features/repl/controller/send/send.ts: applies UiEffect.appendMessages to Msg
• packages/core/src/screens/REPL.tsx: render msg.ui.kind === 'command_subline' as ⎿ ... (no ⏺)
• packages/core/src/screens/REPL.slashSuggestions.test.tsx: duplicate command selection / preferredSlashSpecId

High-Signal Patterns

• Pattern A: one-line overlay dismissal
  • append a single assistant Msg with ui.kind='command_subline'
  • keep copy stable unless the user explicitly requests copy changes
• Pattern B: multi-line local output
  • split output into multiple command_subline rows
  • this is UI only; model injection remains separately controlled
• Pattern C: inject-but-don't-spam
  • when a command needs to inform the model, keep UI output minimal and preserve recordForNextTurn / injected-block behavior separately

Minimal Workflow

1. Classify the change first: discovery / precedence, local UI output, next-turn injection, or overlay dismiss behavior.
2. Update the slash command contract first.
3. Preserve “show in UI” vs “inject into model context” as separate concerns; local output alone must not imply injection.
4. Use command_subline for Claude-style sublines; do not invent new message shapes.
5. Run the minimum regression set below before review.

Minimum Regression

• bun run test -- packages/core/src/features/commands/registry.test.ts packages/core/src/features/commands/CommandStore.test.ts packages/core/src/features/commands/adapter.test.ts packages/core/src/features/commands/contracts.test.ts
• bun run test -- packages/core/src/features/repl/controller/ui/overlays.test.tsx
• bun run test -- packages/core/src/features/repl/controller/send/send.test.ts packages/core/src/features/repl/useReplController.test.tsx
• bun run test -- packages/core/src/screens/REPL.slashSuggestions.test.tsx packages/core/src/screens/repl/inputHint.test.ts
• bun run type-check when command shapes or routing plumbing changes

Guardrails

• Do not add bespoke commandSubLines-style structures; use Msg.ui.kind='command_subline'.
• Do not change UI copy / spacing / colors as a side-effect of routing changes.
• Do not patch only overlay output if the real bug is discovery or dispatch precedence.
• If behavior is unclear, add or extend an Ink test first; tests are not the only spec, but they should lock the visible key path.