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>

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"

description: Interactive brainstorming session for new feature ideas argument-hint: Optional initial feature concept

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

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

description: Validates API documentation against OpenAPI standards argument-hint: Path to OpenAPI spec file

undefined

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

• .claude/commands/frontend/component.md

  creates

  /component

  with description "(project:frontend)"

• ~/.claude/commands/component.md

  creates

  /component

  with description "(user)"

/fix-issue 123 high-priority

/review-pr 456 high alice

• Current git status: !

  git status

• Current git diff: !

  git diff HEAD

• Current branch: !

  git branch --show-current

• Recent commits: !

  git log --oneline -10

undefined

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>

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?

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

• Task description style
• Argument handling
• MCP tool usage
• Documentation references
• Human review sections

undefined

/.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)?"

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>