Command Creator Assistant

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>

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>

CRITICAL: Every Command Must Start with Frontmatter

---

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

Slash Command Features

Namespacing

• .claude/commands/frontend/component.md

  creates

  /component

  with description "(project:frontend)"

• ~/.claude/commands/component.md

  creates

  /component

  with description "(user)"

Arguments

All Arguments with

$ARGUMENTS

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

# 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

!

allowed-tools

Bash

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

@

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

Thinking Mode

Frontmatter Options

allowed-tools

argument-hint

description

model

disable-model-invocation

Skill

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

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>

Phase 1: Understanding Purpose

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

• 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

# 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

/.claude/commands/

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

~/.claude/commands/

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

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

Phase 5: Resource Planning

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

# Check which guides exist
ls -la /docs/

Critical: Copy Patterns from Similar Commands

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>

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>

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

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

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

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

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

/.claude/commands/validate-api.md

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

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>