neolabhq/context-engineering-kit/create-command

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

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

1. Analysis Commands (Specialized)

• Review, audit, analyze
• Generate reports or insights
• Read-heavy operations
• Provide recommendations
• Example: @/.claude/commands/review.md

1. Workflow Commands (Specialized)

• Orchestrate multiple steps
• Coordinate between areas
• Manage dependencies
• Track progress
• Example: @/.claude/commands/04_feature-planning.md

1. 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"

1. `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
---
 
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/ ```

1. 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?

1. 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 ```

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

1. 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 ``

1. 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> ``

1. 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> ```

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

1. Create Supporting Files (if project command)

• Templates in /docs/command-resources/
• Mode guides if generic command
• Example documentation

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

1. 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"