Command Creator Assistant

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:

---
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

# 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:

# 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:

# 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.

---
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:

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

Example with all frontmatter options:

---
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:

# 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:

# 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:

<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):

---
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>