---

## Creation Workflow

### Step 1: Determine Location

1. Check if in git repo: `git rev-parse --is-inside-work-tree`
2. Default: Git repo → `.claude/commands/`, No git → `~/.claude/commands/`
3. Override if user explicitly says "global" or "project"

Report chosen location before proceeding.

### Step 2: Identify Pattern

Load [references/patterns.md](references/patterns.md) and present options:

| Pattern | Structure | Use When |
|---------|-----------|----------|
| Workflow Automation | Analyze → Act → Report | Multi-step with clear sequence |
| Iterative Fixing | Run → Parse → Fix → Repeat | Fix issues until passing |
| Agent Delegation | Context → Delegate → Iterate | Complex tasks, user review |
| Simple Execution | Parse → Execute → Return | Wrapper for existing tools |

Ask: "Which pattern is closest to what you want?"

### Step 3: Gather Information

**A. Name and Purpose**
- "What should the command be called?" (kebab-case: `my-command`)
- "What does it do?" (for description field)

**B. Arguments**
- "Does it take arguments? Required or optional?"
- Required: `<placeholder>`, Optional: `[placeholder]`

**C. Workflow Steps**
- "What specific steps should it follow?"
- "What tools or commands should it use?"

**D. Constraints**
- "Any specific tools to use or avoid?"
- "Any files to read for context?"

### Step 4: Generate Command

Load [references/best-practices.md](references/best-practices.md) for:
- Template structure
- Writing style (imperative form)
- Quality checklist

Key principles:
- Use imperative form: "Run X", not "You should run X"
- Be explicit: "Run `make lint`", not "Check for errors"
- Include expected outcomes
- Define error handling
- State success criteria

### Step 5: Create File

Write the command file. Report:
- File location
- What the command does
- How to use: `/command-name [args]`

### Step 6: Test (Optional)

Suggest: "Test with `/command-name [args]`"

Iterate based on feedback.

---

## Writing Guidelines

**Imperative form (verb-first)**:
- ✅ "Run git status"
- ❌ "You should run git status"

**Specific, not vague**:
- ✅ "Run `make lint` to check for errors"
- ❌ "Check for errors"

**Include outcomes**:
- ✅ "Run `git status` - should show modified files"
- ❌ "Run git status"

**Realistic examples**:
- ✅ `git commit -m "Add OAuth2 authentication"`
- ❌ `git commit -m "foo bar"`

---

## Command Patterns Quick Reference

### Workflow Automation

---
description: Brief description for /help (required)
argument-hint: <required> or [optional] (if takes arguments)
---

# Command Title

[Instructions for agent to execute autonomously]

1. Check for .PLAN.md
2. Analyze git status/diff
3. Perform actions
4. Report results

1. Run make all-ci (max 10 iterations)
2. Parse errors by category
3. Apply targeted fixes
4. Repeat until success or stuck

1. Present context
2. Invoke subagent with Task tool
3. Iterate with user feedback
4. Save output after approval