/create-command

name: create-command
description: Create slash commands with brainstorming and best practices
usage: /create-command [command-description] [--skip-brainstorm] [--plugin <name>]

Create Command

Creates new slash commands through a structured workflow: **iron-law → brainstorm → design → scaffold → validate**. Uses Socratic questioning to refine rough ideas into well-designed commands before generating any files.

**Important**: This workflow enforces the Iron Law. You cannot create command files without first creating and running failing tests. See [Iron Law Interlock](../shared-modules/iron-law-interlock.md).

When To Use

Use this command when you need to:

• Creating a new slash command from scratch
• Need guided brainstorming for command design
• Want structured workflow for command development

When NOT To Use

Avoid this command if:

• Creating skills - use /create-skill instead
• Creating hooks - use /create-hook instead
• Modifying existing commands - edit directly

Usage

# Start with brainstorming (recommended)
/create-command "run all tests and show coverage report"

# Skip brainstorming if design is clear
/create-command test-coverage --skip-brainstorm

# Create in specific plugin
/create-command "analyze git history" --plugin sanctum

What is a Slash Command?

Slash commands are shortcuts that expand into prompts Claude follows. They're stored as `.md` files in `commands/` and referenced in `plugin.json`.

**Simple command example:**

---
description: Run tests with coverage
---

Run all tests with pytest and display a coverage report. Focus on files changed in the current branch.

**Command with arguments:**

---
description: Review specific PR
usage: /review-pr <pr-number> [--focus security|performance|all]
---

Review pull request #$ARGUMENTS using the code review skill. Focus on ${focus:-all} aspects.

Workflow

Phase 0: Iron Law Interlock (Blocking)

**This phase is required and cannot be skipped.**

Before any file creation, satisfy the Iron Law interlock:

Step 1: Create Test File FIRST

# Determine test location based on target plugin
tests/unit/test_${command_name}_command.py

Step 2: Write Structural Validation Tests

"""Tests for ${command_name} command structure and validation.

Written BEFORE implementation per Iron Law.
"""
import json
from pathlib import Path
import pytest

class Test${CommandName}Command:
    """Test /${command_name} command structure."""

    @pytest.fixture
    def command_file_path(self) -> Path:
        return Path(__file__).parents[2] / "commands" / "${command_name}.md"

    @pytest.fixture
    def plugin_json_path(self) -> Path:
        return Path(__file__).parents[2] / ".claude-plugin" / "plugin.json"

    def test_should_exist_when_command_file_path_resolved(
        self, command_file_path: Path
    ) -> None:
        """Command file must exist."""
        assert command_file_path.exists()

    def test_should_have_frontmatter_when_parsing_content(
        self, command_file_path: Path
    ) -> None:
        """Command must have valid frontmatter."""
        content = command_file_path.read_text()
        assert content.startswith("---")
        assert "description:" in content

    def test_should_be_registered_in_plugin_json(
        self, plugin_json_path: Path
    ) -> None:
        """Command must be registered in plugin.json."""
        plugin = json.loads(plugin_json_path.read_text())
        commands = plugin.get("commands", [])
        assert any("${command_name}.md" in cmd for cmd in commands)

Step 3: Run Tests - Capture RED State

pytest tests/unit/test_${command_name}_command.py -v

**Expected output (RED):**

FAILED test_should_exist_when_command_file_path_resolved - FileNotFoundError
FAILED test_should_have_frontmatter_when_parsing_content - FileNotFoundError
FAILED test_should_be_registered_in_plugin_json - AssertionError

Step 4: Capture Evidence

**Iron Law Checkpoint**: Creating command `${command_name}`.

[E1] Command: pytest tests/unit/test_${command_name}_command.py -v
Output: 3 FAILED (file does not exist)
Status: RED - Interlock satisfied

**Self-Check**:
- [x] Test file created BEFORE implementation
- [x] Failure evidence captured
- [x] Tests drive the implementation

Step 5: Create TodoWrite Items

proof:iron-law-red - Test failure captured for ${command_name}
proof:iron-law-interlock-satisfied - Proceeding to design phase

**Only after completing Phase 0 may you proceed to Phase 1.**

---

Phase 1: Brainstorming (Default)

Before creating any files, refine the command concept through collaborative dialogue.

**Invoke the brainstorming skill:**

Use superpowers:brainstorming to refine this command idea before scaffolding.

The brainstorming phase will:

1. **Understand the purpose** - One question at a time:

• What task does this command automate?
• How often will it be used? (daily, weekly, occasionally)
• What's the expected output? (action, report, interactive)
• Who is the target user?

2. **Explore the interface**:

• What arguments/options are needed?
• Should this be interactive or fire-and-forget?
• Are there variants that should be separate commands?
• What's a good, memorable name?

3. **Design the implementation**:

• Simple prompt expansion vs. skill invocation?
• Does it need an agent for complex tasks?
• What existing skills/commands can it use?
• What tools will Claude need to use?

4. **Validate the design** - Present in sections:

• Command signature and description
• Prompt content
• Integration with skills/agents
• Example usage

5. **Document the design**:

• Write to `docs/plans/YYYY-MM-DD-<command-name>-design.md`
• Commit the design document

**Skip brainstorming** with `--skip-brainstorm` only when:

• You have a written design document already
• The command is a tr