stack/docs/scratchpads/p8-010-command-registry.md

P8-010 Scratchpad — Gateway Phase 2: CommandRegistryService + CommandExecutorService

Objective

Implement gateway-side command registry system:

• CommandRegistryService — owns canonical command manifest, broadcasts on connect
• CommandExecutorService — routes command:execute socket events
• CommandsModule — NestJS wiring
• Wire into ChatGateway and AppModule
• Register core commands
• Tests for CommandRegistryService

Key Findings from Codebase

CommandDef shape (from packages/types/src/commands/index.ts)

• scope: 'core' | 'agent' | 'skill' | 'plugin' | 'admin' (NOT category)
• args?: CommandArgDef[] — array of arg defs, each with name, type, optional, values?, description?
• No aliases required (it's listed but optional-ish... wait, it IS in the interface)
• aliases: string[] — IS present

SlashCommandResultPayload requires conversationId

• The task spec shows { command, success, error } without conversationId but actual type requires it
• Must include conversationId in all return values

CommandManifest has skills: SkillCommandDef[]

• Must include skills array in manifest

userId extraction in ChatGateway

• client.data.user holds the user object (set in handleConnection)
• client.data.user.id or similar for userId

AgentModule not imported in ChatModule

• ChatGateway imports AgentService via DI
• ChatModule doesn't declare imports — AgentModule must be global or imported

Worktree branch

• Branch: feat/p8-010-command-registry
• Working in: /home/jwoltje/src/mosaic-mono-v1/.claude/worktrees/agent-ac85b3b2

Plan

1. Create apps/gateway/src/commands/command-registry.service.ts
2. Create apps/gateway/src/commands/command-executor.service.ts
3. Create apps/gateway/src/commands/commands.module.ts
4. Modify apps/gateway/src/app.module.ts — add CommandsModule
5. Modify apps/gateway/src/chat/chat.module.ts — import CommandsModule
6. Modify apps/gateway/src/chat/chat.gateway.ts — inject services, add handler, emit manifest
7. Create apps/gateway/src/commands/command-registry.service.spec.ts

Progress

• Create CommandRegistryService
• Create CommandExecutorService
• Create CommandsModule
• Update AppModule
• Update ChatModule
• Update ChatGateway
• Write tests
• Run quality gates
• Commit + push + PR

Risks

• CommandDef args shape mismatch from task spec — must use actual type
• SlashCommandResultPayload.conversationId is required — handle missing conversationId