singularity-forge/docs/dev/sf-runtime/command-surface.md

SF Command Surface

When to Use

This reference applies when:

• Adding or modifying SF slash commands (/mode, /tasks, /skills, etc.)
• Changing command handlers in src/resources/extensions/sf/commands/handlers/
• Updating command catalog descriptions
• Ensuring web/TUI/headless command parity
• Modifying command dispatch routing

Instructions

1. Check existing handlers — Look in commands/handlers/core.js and commands/handlers/ops.js for the pattern
2. Update catalog — Add to commands/catalog.js TOP_LEVEL_SUBCOMMANDS
3. Update help text — Add to showHelp() in commands/handlers/core.js
4. Wire dispatch — Add routing in handleCoreCommand() or handleOpsCommand()
5. Test — Verify with node --check and manual test

Verification

• Command appears in /help
• Command appears in /help all
• Handler file passes node --check
• No /sf prefix in user-facing strings

Examples

// Adding a new command
if (trimmed === "mycommand" || trimmed.startsWith("mycommand ")) {
    await handleMyCommand(trimmed.replace(/^mycommand\s*/, "").trim(), ctx);
    return true;
}