{
  "feature": "slash-commands",
  "version": "1.0.0",
  "description": "Register and execute text commands with a / prefix in chat messages",
  "category": "integration",
  "tags": [
    "commands",
    "chat",
    "extensibility",
    "shortcuts",
    "integration"
  ],
  "actors": [
    {
      "id": "user",
      "name": "User",
      "type": "human",
      "description": "Any authenticated user who types slash commands in a chat message"
    },
    {
      "id": "platform",
      "name": "Platform",
      "type": "system",
      "description": "The chat platform that parses messages and dispatches command execution"
    },
    {
      "id": "command_handler",
      "name": "Command Handler",
      "type": "system",
      "description": "The registered callback or extension that executes the command logic"
    }
  ],
  "fields": [
    {
      "name": "command",
      "type": "text",
      "required": true,
      "label": "Command Name"
    },
    {
      "name": "params",
      "type": "text",
      "required": false,
      "label": "Command Parameters"
    },
    {
      "name": "room_id",
      "type": "text",
      "required": true,
      "label": "Room ID"
    },
    {
      "name": "user_id",
      "type": "text",
      "required": true,
      "label": "User ID"
    },
    {
      "name": "description",
      "type": "text",
      "required": true,
      "label": "Description"
    },
    {
      "name": "params_example",
      "type": "text",
      "required": false,
      "label": "Parameters Example"
    },
    {
      "name": "permission",
      "type": "text",
      "required": false,
      "label": "Required Permission"
    },
    {
      "name": "provides_preview",
      "type": "boolean",
      "required": false,
      "label": "Provides Preview"
    }
  ],
  "rules": {
    "general": [
      "Command names must be unique across the platform; registering a duplicate command replaces or errors depending on configuration",
      "Command names are lowercased and must contain only alphanumeric characters and hyphens",
      "Command execution is triggered only when the full message starts with /, followed by a registered command name",
      "Commands with a required permission are hidden from users who lack that permission",
      "If provides_preview is true, the platform calls the previewer function as the user types and shows up to 10 preview items",
      "Selecting a preview item triggers executePreviewItem instead of the main executor",
      "Command callbacks receive read-only access to the platform data; mutations go through the modify accessor",
      "Commands may send ephemeral messages back to the invoking user without posting to the room",
      "Unrecognized command names should surface a help hint rather than silently fail",
      "Extensions and apps may register, enable, or disable commands dynamically at runtime"
    ]
  },
  "outcomes": {
    "command_executed": {
      "priority": 10,
      "given": [
        "user sends a message starting with / followed by a registered command name",
        "user has the required permission for the command (if any)"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "slash_command.executed",
          "payload": [
            "command",
            "params",
            "room_id",
            "user_id"
          ]
        }
      ],
      "result": "Command handler is invoked with the command name, params, room context, and user context"
    },
    "preview_shown": {
      "priority": 8,
      "given": [
        "user is typing a command whose provides_preview is true",
        "user has not yet submitted the message"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "slash_command.preview_requested",
          "payload": [
            "command",
            "params",
            "room_id",
            "user_id"
          ]
        }
      ],
      "result": "Platform calls the previewer and displays up to 10 inline preview items to the user"
    },
    "preview_item_selected": {
      "priority": 9,
      "given": [
        "preview was shown",
        "user selects one of the preview items"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "slash_command.preview_item_selected",
          "payload": [
            "command",
            "params",
            "room_id",
            "user_id"
          ]
        }
      ],
      "result": "Platform calls executePreviewItem with the selected item instead of the main executor"
    },
    "permission_denied": {
      "priority": 2,
      "error": "SLASH_COMMAND_PERMISSION_DENIED",
      "given": [
        "user sends a message starting with / followed by a registered command name",
        "command requires a permission the user does not hold"
      ],
      "then": [],
      "result": "Command is not displayed to the user and execution is rejected"
    },
    "command_not_found": {
      "priority": 1,
      "error": "SLASH_COMMAND_NOT_FOUND",
      "given": [
        "user sends a message starting with / followed by a name that is not a registered command"
      ],
      "then": [],
      "result": "Platform surfaces a help message or ignores the unknown command"
    },
    "command_disabled": {
      "priority": 3,
      "error": "SLASH_COMMAND_DISABLED",
      "given": [
        "user invokes a command that is currently disabled by an extension or admin"
      ],
      "then": [],
      "result": "Execution is blocked and an informational message may be shown to the user"
    }
  },
  "errors": [
    {
      "code": "SLASH_COMMAND_NOT_FOUND",
      "status": 404,
      "message": "The command you entered was not found. Type /help to see available commands."
    },
    {
      "code": "SLASH_COMMAND_PERMISSION_DENIED",
      "status": 403,
      "message": "You do not have permission to use this command."
    },
    {
      "code": "SLASH_COMMAND_DISABLED",
      "status": 400,
      "message": "This command is currently disabled."
    }
  ],
  "events": [
    {
      "name": "slash_command.executed",
      "description": "Fires when a registered slash command is successfully dispatched to its handler",
      "payload": [
        "command",
        "params",
        "room_id",
        "user_id"
      ]
    },
    {
      "name": "slash_command.preview_requested",
      "description": "Fires when the platform requests inline preview results while a user is typing a command",
      "payload": [
        "command",
        "params",
        "room_id",
        "user_id"
      ]
    },
    {
      "name": "slash_command.preview_item_selected",
      "description": "Fires when a user selects one of the inline preview items",
      "payload": [
        "command",
        "params",
        "room_id",
        "user_id"
      ]
    },
    {
      "name": "slash_command.registered",
      "description": "Fires when a new slash command is registered by a handler or extension",
      "payload": [
        "command",
        "description",
        "permission"
      ]
    },
    {
      "name": "slash_command.unregistered",
      "description": "Fires when a slash command is removed or disabled",
      "payload": [
        "command"
      ]
    }
  ],
  "related": [
    {
      "feature": "bot-plugin-framework",
      "type": "recommended",
      "reason": "Extensions and bots use the plugin framework to register slash commands dynamically"
    },
    {
      "feature": "role-based-access-control",
      "type": "optional",
      "reason": "Permission-gated commands rely on RBAC to determine access"
    }
  ],
  "extensions": {
    "source": {
      "repo": "https://github.com/RocketChat/Rocket.Chat",
      "project": "Open-source team communication platform",
      "tech_stack": "TypeScript, Meteor, React, MongoDB",
      "files_traced": 6
    }
  },
  "agi": {
    "goals": [
      {
        "id": "extensible_command_dispatch",
        "description": "Parse, authorise, and dispatch slash commands from chat messages to registered handlers with permission enforcement and preview support",
        "success_metrics": [
          {
            "metric": "permission_enforcement_rate",
            "target": "100%",
            "measurement": "Permission-gated commands hidden from and rejected for unauthorised users / total attempts"
          }
        ]
      }
    ],
    "autonomy": {
      "level": "supervised",
      "human_checkpoints": [
        "before registering a system-level slash command that affects all users"
      ]
    },
    "verification": {
      "invariants": [
        "command names must be unique across the platform",
        "permission-required commands are hidden from users who lack the permission",
        "unrecognised commands surface a help hint rather than silently failing"
      ],
      "acceptance_tests": [
        {
          "scenario": "permission-gated command rejected",
          "given": "user without required permission types a permission-gated command",
          "when": "message is submitted",
          "expect": "SLASH_COMMAND_PERMISSION_DENIED and command not displayed to the user"
        },
        {
          "scenario": "preview shown while typing",
          "given": "command has provides_preview true and user is still typing",
          "when": "user types the command",
          "expect": "up to 10 inline preview items displayed"
        }
      ]
    },
    "capabilities": [
      {
        "id": "command_registration",
        "description": "Register and unregister slash commands dynamically by extensions and bots"
      },
      {
        "id": "inline_preview_dispatch",
        "description": "Call command preview functions while user types and display results inline"
      }
    ],
    "tradeoffs": [
      {
        "prefer": "discoverability",
        "over": "strict_failure",
        "reason": "unknown commands show a help hint rather than an error to guide users to available commands"
      }
    ]
  }
}