Initial commit
This commit is contained in:
Zhongwei Li
461
commands/create-command.md
Normal file
461
commands/create-command.md
Normal file
@@ -0,0 +1,461 @@
|
||||
---
|
||||
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>
|
||||
|
||||
<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>
|
||||
Reference in New Issue
Block a user