# Command Design Specification

Guidelines for Claude Code command files generated by command-generator.

## YAML Frontmatter

```yaml
---
name: command-name           # Required: lowercase with hyphens
description: Description     # Required: brief purpose
argument-hint: "[args]"      # Optional: argument format hint
allowed-tools: Tool1, Tool2  # Optional: restricted tool set
---
```

## Naming Conventions

| Element | Convention | Examples |
|---------|-----------|----------|
| Command name | lowercase, hyphens, 2-3 words max | `deploy`, `create-issue` |
| Group name | singular noun | `issue`, `session`, `workflow` |
| Verbs for actions | imperative | `deploy`, `create`, `analyze` |

## Path Structure

```
.claude/commands/deploy.md           # Top-level command
.claude/commands/issue/create.md     # Grouped command
~/.claude/commands/global-status.md  # User-level command
```

## Content Structure (GSD Style)

Generated commands should use XML semantic tags:

| Tag | Required | Purpose |
|-----|----------|---------|
| `<purpose>` | Yes | What the command does, when invoked, what it produces |
| `<required_reading>` | Yes | Files to read before execution (@ notation) |
| `<process>` | Yes | Container for execution steps |
| `<step name="...">` | Yes | Individual execution steps with snake_case names |
| `<error_codes>` | No | Error code table with severity and description |
| `<success_criteria>` | Yes | Checkbox list of verifiable completion conditions |

## Step Naming

- Use snake_case: `parse_input`, `validate_config`, `write_output`
- Use action verbs: `discover`, `validate`, `spawn`, `collect`, `report`
- First step gets `priority="first"` attribute

## Error Messages

```
Good: Error: GitHub issue URL required
      Usage: /issue:create <github-url>

Bad:  Error: Invalid input
```

## Scope Guidelines

| Scope | Location | Use For |
|-------|----------|---------|
| Project | `.claude/commands/` | Team workflows, project integrations |
| User | `~/.claude/commands/` | Personal tools, cross-project utilities |