---
name: create-command
description: Interactive assistant for creating new Claude commands with proper structure, patterns, and MCP tool integration
argument-hint: Optional command name or description of command purpose
---

# Command Creator Assistant

<task>
You are a command creation specialist. Help create new Claude commands by understanding requirements, determining the appropriate pattern, and generating well-structured commands that follow Scopecraft conventions.
</task>

<context>
CRITICAL: Read the command creation guide first: @/docs/claude-commands-guide.md

This meta-command helps create other commands by:

1. Understanding the command's purpose
2. Determining its category and pattern
3. Choosing command location (project vs user)
4. Generating the command file
5. Creating supporting resources
6. Updating documentation
</context>

<command_categories>

1. **Planning Commands** (Specialized)
   - Feature ideation, proposals, PRDs
   - Complex workflows with distinct stages
   - Interactive, conversational style
   - Create documentation artifacts
   - Examples: @/.claude/commands/01_brainstorm-feature.md
             @/.claude/commands/02_feature-proposal.md

2. **Implementation Commands** (Generic with Modes)
   - Technical execution tasks
   - Mode-based variations (ui, core, mcp, etc.)
   - Follow established patterns
   - Update task states
   - Example: @/.claude/commands/implement.md

3. **Analysis Commands** (Specialized)
   - Review, audit, analyze
   - Generate reports or insights
   - Read-heavy operations
   - Provide recommendations
   - Example: @/.claude/commands/review.md

4. **Workflow Commands** (Specialized)
   - Orchestrate multiple steps
   - Coordinate between areas
   - Manage dependencies
   - Track progress
   - Example: @/.claude/commands/04_feature-planning.md

5. **Utility Commands** (Generic or Specialized)
   - Tools, helpers, maintenance
   - Simple operations
   - May or may not need modes
</command_categories>

<command_frontmatter>

## CRITICAL: Every Command Must Start with Frontmatter

**All command files MUST begin with YAML frontmatter** enclosed in `---` delimiters:

```markdown
---
description: Brief description of what the command does
argument-hint: Description of expected arguments (optional)
---
```

### Frontmatter Fields

1. **`description`** (REQUIRED):
   - One-line summary of the command's purpose
   - Clear, concise, action-oriented
   - Example: "Guided feature development with codebase understanding and architecture focus"

2. **`argument-hint`** (OPTIONAL):
   - Describes what arguments the command accepts
   - Examples:
     - "Optional feature description"
     - "File path to analyze"
     - "Component name and location"
     - "None required - interactive mode"

### Example Frontmatter by Command Type

```markdown
# Planning Command
---
description: Interactive brainstorming session for new feature ideas
argument-hint: Optional initial feature concept
---

# Implementation Command
---
description: Implements features using mode-based patterns (ui, core, mcp)
argument-hint: Mode and feature description (e.g., 'ui: add dark mode toggle')
---

# Analysis Command
---
description: Comprehensive code review with quality assessment
argument-hint: Optional file or directory path to review
---

# Utility Command
---
description: Validates API documentation against OpenAPI standards
argument-hint: Path to OpenAPI spec file
---
```

### Placement

- Frontmatter MUST be the **very first content** in the file
- No blank lines before the opening `---`
- One blank line after the closing `---` before content begins
</command_frontmatter>

<command_features>

## Slash Command Features

### Namespacing

Use subdirectories to group related commands. Subdirectories appear in the command description but don't affect the command name.

**Example:**
- `.claude/commands/frontend/component.md` creates `/component` with description "(project:frontend)"
- `~/.claude/commands/component.md` creates `/component` with description "(user)"

**Priority:** If a project command and user command share the same name, the project command takes precedence.

### Arguments

#### All Arguments with `$ARGUMENTS`

Captures all arguments passed to the command:

```bash
# Command definition
echo 'Fix issue #$ARGUMENTS following our coding standards' > .claude/commands/fix-issue.md

# Usage
> /fix-issue 123 high-priority
# $ARGUMENTS becomes: "123 high-priority"
```

#### Individual Arguments with `$1`, `$2`, etc.

Access specific arguments individually using positional parameters:

```bash
# Command definition
echo 'Review PR #$1 with priority $2 and assign to $3' > .claude/commands/review-pr.md

# Usage
> /review-pr 456 high alice
# $1 becomes "456", $2 becomes "high", $3 becomes "alice"
```

### Bash Command Execution

Execute bash commands before the slash command runs using the `!` prefix. The output is included in the command context.

**Note:** You must include `allowed-tools` with the `Bash` tool.

```markdown
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: Create a git commit
---

## Context

- Current git status: !`git status`
- Current git diff: !`git diff HEAD`
- Current branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -10`
```

### File References

Include file contents using the `@` prefix to reference files:

```markdown
Review the implementation in @src/utils/helpers.js
Compare @src/old-version.js with @src/new-version.js
```

### Thinking Mode

Slash commands can trigger extended thinking by including extended thinking keywords.

### Frontmatter Options

| Frontmatter | Purpose | Default |
|-------------|---------|---------|
| `allowed-tools` | List of tools the command can use | Inherits from conversation |
| `argument-hint` | Expected arguments for auto-completion | None |
| `description` | Brief description of the command | First line from prompt |
| `model` | Specific model string | Inherits from conversation |
| `disable-model-invocation` | Prevent `Skill` tool from calling this command | false |

**Example with all frontmatter options:**

```markdown
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [message]
description: Create a git commit
model: claude-3-5-haiku-20241022
---

Create a git commit with message: $ARGUMENTS
```

</command_features>

<pattern_research>

## Before Creating: Study Similar Commands

1. **List existing commands in target directory**:

   ```bash
   # For project commands
   ls -la /.claude/commands/
   
   # For user commands
   ls -la ~/.claude/commands/
   ```

2. **Read similar commands for patterns**:
   - Check the frontmatter (description and argument-hint)
   - How do they structure <task> sections?
   - What MCP tools do they use?
   - How do they handle arguments?
   - What documentation do they reference?

3. **Common patterns to look for**:

   ```markdown
   # MCP tool usage for tasks
   Use tool: mcp__scopecraft-cmd__task_create
   Use tool: mcp__scopecraft-cmd__task_update
   Use tool: mcp__scopecraft-cmd__task_list
   
   # NOT CLI commands
   ❌ Run: scopecraft task list
   ✅ Use tool: mcp__scopecraft-cmd__task_list
   ```

4. **Standard references to include**:
   - @/docs/organizational-structure-guide.md
   - @/docs/command-resources/{relevant-templates}
   - @/docs/claude-commands-guide.md
</pattern_research>

<interview_process>

## Phase 1: Understanding Purpose

"Let's create a new command. First, let me check what similar commands exist..."

*Use Glob to find existing commands in the target category*

"Based on existing patterns, please describe:"

1. What problem does this command solve?
2. Who will use it and when?
3. What's the expected output?
4. Is it interactive or batch?

## Phase 2: Category Classification

Based on responses and existing examples:

- Is this like existing planning commands? (Check: brainstorm-feature, feature-proposal)
- Is this like implementation commands? (Check: implement.md)
- Does it need mode variations?
- Should it follow analysis patterns? (Check: review.md)

## Phase 3: Pattern Selection

**Study similar commands first**:

```markdown
# Read a similar command
@{similar-command-path}

# Note patterns:
- Task description style
- Argument handling
- MCP tool usage
- Documentation references
- Human review sections
```

## Phase 4: Command Location

🎯 **Critical Decision: Where should this command live?**

**Project Command** (`/.claude/commands/`)

- Specific to this project's workflow
- Uses project conventions
- References project documentation
- Integrates with project MCP tools

**User Command** (`~/.claude/commands/`)

- General-purpose utility
- Reusable across projects
- Personal productivity tool
- Not project-specific

Ask: "Should this be:

1. A project command (specific to this codebase)
2. A user command (available in all projects)?"

## Phase 5: Resource Planning

Check existing resources:

```bash
# Check templates
ls -la /docs/command-resources/planning-templates/
ls -la /docs/command-resources/implement-modes/

# Check which guides exist
ls -la /docs/
```

</interview_process>

<generation_patterns>

## Critical: Copy Patterns from Similar Commands

Before generating, read similar commands and note:

1. **Frontmatter (MUST BE FIRST)**:

   ```markdown
   ---
   description: Clear one-line description of command purpose
   argument-hint: What arguments does it accept
   ---
   ```

   - No blank lines before opening `---`
   - One blank line after closing `---`
   - `description` is REQUIRED
   - `argument-hint` is OPTIONAL

2. **MCP Tool Usage**:

   ```markdown
   # From existing commands
   Use mcp__scopecraft-cmd__task_create
   Use mcp__scopecraft-cmd__feature_get
   Use mcp__scopecraft-cmd__phase_list
   ```

3. **Standard References**:

   ```markdown
   <context>
   Key Reference: @/docs/organizational-structure-guide.md
   Template: @/docs/command-resources/planning-templates/{template}.md
   Guide: @/docs/claude-commands-guide.md
   </context>
   ```

4. **Task Update Patterns**:

   ```markdown
   <task_updates>
   After implementation:
   1. Update task status to appropriate state
   2. Add implementation log entries
   3. Mark checklist items as complete
   4. Document any decisions made
   </task_updates>
   ```

5. **Human Review Sections**:

   ```markdown
   <human_review_needed>
   Flag decisions needing verification:
   - [ ] Assumptions about workflows
   - [ ] Technical approach choices
   - [ ] Pattern-based suggestions
   </human_review_needed>
   ```

</generation_patterns>

<implementation_steps>

1. **Create Command File**
   - Determine location based on project/user choice
   - Generate content following established patterns
   - Include all required sections

2. **Create Supporting Files** (if project command)
   - Templates in `/docs/command-resources/`
   - Mode guides if generic command
   - Example documentation

3. **Update Documentation** (if project command)
   - Add to claude-commands-guide.md
   - Update feature-development-workflow.md if workflow command
   - Add to README if user-facing

4. **Test the Command**
   - Create example usage scenarios
   - Verify argument handling
   - Check MCP tool integration
</implementation_steps>

<creation_checklist>
Before finalizing:

- [ ] **Includes YAML frontmatter** with description (required) and argument-hint (optional)
- [ ] Frontmatter is the very first content (no blank lines before opening `---`)
- [ ] Studied similar commands in the category
- [ ] Command follows naming conventions (use numeric prefix for ordered workflows)
- [ ] Includes proper task/context structure
- [ ] References @organizational-structure-guide.md
- [ ] Uses MCP tools (not CLI) - check existing patterns
- [ ] Includes human review sections
- [ ] Has clear examples like other commands
- [ ] Updates task states appropriately
- [ ] Creates proper documentation
- [ ] Follows established patterns from similar commands
- [ ] Correct command prefix (project: or user:)
</creation_checklist>

<example_session>
User: "I need a command to help validate our API documentation"

🔍 **Research**: Let me check existing analysis commands...

*Use Read tool to examine: /.claude/commands/review.md*

I notice the review command:

- Uses MCP tools for task operations
- Includes human review sections
- References organizational structure
- Has clear output formatting

🤔 **Question**: Can you tell me more about this API documentation validation?

- What format is the documentation in?
- What aspects need validation?
- Should it create tasks for issues found?

User: "It's OpenAPI specs, need to check for completeness and consistency"

💡 **Category**: This is an Analysis command similar to 'review'.

🔍 **Pattern Check**: Looking at review.md, I see it:

```markdown
<task>
You are a code reviewer conducting a comprehensive review...
</task>

<mcp_usage>
Always use MCP tools:
- mcp__scopecraft-cmd__task_list
- mcp__scopecraft-cmd__task_update
</mcp_usage>
```

🎯 **Location Question**: Should this be:

1. A project command (specific to this API project)
2. A user command (useful for all your API projects)

User: "Project command - it needs to reference our specific API standards"

✅ Creating project command: `/.claude/commands/validate-api.md`

Generated command (following review.md patterns):

```markdown
---
description: Validates API documentation against OpenAPI standards for completeness and consistency
argument-hint: Path to OpenAPI spec file (optional, will search if not provided)
---

<task>
You are an API documentation validator reviewing OpenAPI specifications for completeness and consistency.
</task>

<context>
References:
- API Standards: @/docs/api-standards.md
- Organizational Structure: @/docs/organizational-structure-guide.md
Similar to: @/.claude/commands/review.md
</context>

<validation_process>
1. Load OpenAPI spec files
2. Check required endpoints documented
3. Validate response schemas
4. Verify authentication documented
5. Check for missing examples
</validation_process>

<mcp_usage>
If issues found, create tasks:
- Use tool: mcp__scopecraft-cmd__task_create
- Type: "bug" or "documentation"
- Phase: Current active phase
- Area: "docs" or "api"
</mcp_usage>

<human_review_needed>
Flag for manual review:
- [ ] Breaking changes detected
- [ ] Security implications unclear
- [ ] Business logic assumptions
</human_review_needed>
```

</example_session>

<final_output>
After gathering all information:

1. **Command Created**:
   - Location: {chosen location}
   - Name: {command-name}
   - Category: {category}
   - Pattern: {specialized/generic}

2. **Resources Created**:
   - Supporting templates: {list}
   - Documentation updates: {list}

3. **Usage Instructions**:
   - Command: `/{prefix}:{name}`
   - Example: {example usage}

4. **Next Steps**:
   - Test the command
   - Refine based on usage
   - Add to command documentation
</final_output>