command-patterns

# Command Authoring Procedure

Follow these steps to generate a command that adheres to the project's structural conventions and produces deterministic, high-quality agent behavior.

## Step 1: Validate Metadata

1. Choose a **kebab-case** name (1-64 characters, lowercase, numbers, and single hyphens only). The name becomes the filename: `.cursor/commands/<folder>/<name>.md`.
2. Determine the **folder**: `sd/` for software developers, `ai/` for AI tooling. Create new folders only when neither fits.
3. Execute the validation script:
   `python3 scripts/validate-metadata.py --name "<name>" --folder "<folder>"`
4. If the script returns an error, self-correct and re-run until successful.

## Step 2: Draft the Command

Use the template in `assets/COMMAND.template.md` as the starting point. Fill in each section following the conventions below.

### Section: Role

- One sentence, third-person: "You are a senior developer [doing X]."
- Describe the persona, not the task.

### Section: Context

- Background the agent needs before acting.
- Use tables for structured references (severity levels, artifact layers, style rules).
- Include project-specific conventions (commit style, PR template path, tool names).
- Keep under 30 lines; move large reference material to skill files or link to project docs.

### Section: Task

- One sentence stating the goal.
- Followed by a `### Steps` subsection with numbered phases.

### Section: Steps

Each step follows this pattern:

1. **Bold phase name** — One-sentence description of the phase.
   - Bullet list of specific actions.
   - Shell commands in fenced code blocks.
   - Parallel operations explicitly noted: "Run these in parallel:"
   - Conditional logic with bold keywords: "If [condition], [action]. Otherwise, [fallback]."

Apply these conventions:

| Convention | Rule |
|------------|------|
| Gathering info | Always the first step; run independent commands in parallel |
| User prompts | Use "Ask the user for:" or "Prompt the user with:" — list each option with defaults |
| Shell commands | Use fenced `bash` blocks; prefer `gh` CLI for GitHub operations |
| HEREDOC commits | Always use `cat <<'EOF'` pattern for multi-line messages |
| Verification | Always include a final verification step (`git status`, `gh pr view`, etc.) |
| Decision points | Present options to the user; never assume destructive choices |

### Section: Constraints

- Bullet list of "Do **not**" rules.
- Always include applicable safety rules from this canonical set:

| Scope | Standard constraints |
|-------|---------------------|
| Git | Do not modify `git config`; do not force-push; do not skip hooks (`--no-verify`); do not run destructive operations without confirmation |
| GitHub | Do not push to `main`/`master` directly; do not dismiss reviews programmatically |
| Files | Do not modify files outside the command's scope; do not commit secrets |
| General | Do not fabricate data; ask rather than assume when intent is unclear |

- Add command-specific constraints after the standard ones.

### Section: Output

- Always a summary table with `Field | Value` columns.
- Fields should be concise identifiers (e.g., **PR**, **Branch**, **Commit**, **Status**).
- Values use inline code for SHAs, numbers, and branch names.
- Optional: a detail table below the summary for itemized results (comments addressed, files changed, findings).

## Step 3: Review Against Checklist

1. Review the `SKILL.md` for "hallucination gaps" (points where the agent is forced to guess).
2. Verify all file paths are **relative** and use forward slashes (`/`).
3. Cross-reference the final output against `references/checklist.md`.

## Error Handling

- **Validation failure:** If `scripts/validate-metadata.py` fails, fix the flagged field and re-run.
- **Scope ambiguity:** If the command straddles consumers, prefer the primary consumer.
- **Overlapping commands:** Before creating a new command, check existing commands that already cover the workflow. Extend an existing command rather than creating a duplicate.