feat: Enhance slash command spec with Claude Code best practices

Inspiration: https://code.claude.com/docs/en/slash-commands

New frontmatter fields:
- argument-hint: Show expected arguments (e.g., [pr-number] [priority])
- allowed-tools: Restrict tools for security (e.g., Bash(git:*))
- model: Specify AI model (e.g., claude-3-5-haiku for simple tasks)
- Positional arguments: Support $1, $2, $3

Enhancements:
- Updated all 3 templates (Pure-Execution, Script-Assisted, CLI-Referenced)
- Added comprehensive frontmatter fields table
- Added argument access patterns documentation
- Maintained MetaSpec's Spec-Driven positioning
- Preserved dual-source architecture

Impact:
- Better UX (users see expected args)
- More secure (can restrict tools per command)
- Cost-optimized (lighter models for simple tasks)
- More flexible (positional arguments)
- Industry standard alignment

Author: NeilJo-GY

CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### ✨ Improvements
+
+**Enhanced slash command specification with Claude Code best practices**
+
+**Inspiration**: Adopted proven patterns from [Claude Code slash commands](https://code.claude.com/docs/en/slash-commands)
+
+**New frontmatter fields**:
+1. ✅ **`argument-hint`**: Show expected arguments in `/help` (e.g., `[pr-number] [priority]`)
+2. ✅ **`allowed-tools`**: Restrict command to specific tools for security (e.g., `Bash(git:*), FileEdit(specs/*)`)
+3. ✅ **`model`**: Specify AI model for specific commands (e.g., `claude-3-5-haiku-20241022` for simple tasks)
+4. ✅ **Positional arguments**: Support `$1`, `$2`, `$3` in addition to `$ARGUMENTS`
+
+**Enhancements**:
+- ✅ Updated all 3 slash command templates (Pure-Execution, Script-Assisted, CLI-Referenced)
+- ✅ Added comprehensive frontmatter fields table with examples
+- ✅ Added argument access patterns documentation
+- ✅ Maintained MetaSpec's unique Spec-Driven positioning
+- ✅ Preserved dual-source architecture (Protocol-Derived + Library-Selected)
+
+**Before**:
+```yaml
+---
+description: Create feature spec
+scripts:
+  sh: scripts/bash/script.sh
+---
+```
+
+**After**:
+```yaml
+---
+description: Create feature specification
+argument-hint: [feature-description]
+scripts:
+  sh: scripts/bash/script.sh --json "{ARGS}"
+  ps: scripts/powershell/script.ps1 -Json "{ARGS}"
+allowed-tools: Bash(git:*), FileEdit(specs/*)
+model: claude-3-5-sonnet-20241022
+---
+```
+
+**Impact**: 
+- ✅ **Better UX**: Users see expected arguments in `/help`
+- ✅ **More secure**: Can restrict tools per command
+- ✅ **Cost-optimized**: Can use lighter models for simple commands
+- ✅ **More flexible**: Positional arguments for structured commands
+- ✅ **Industry standard**: Aligns with Claude Code patterns
+
+**Files Changed**: `specify.md.j2`
+
+---
+
 ### 🐛 Bug Fixes
 
 **Removed hardcoded line number references**

src/metaspec/templates/meta/sdd/commands/specify.md.j2

@@ -578,6 +578,35 @@ api-toolkit lint openapi.yaml
 
 ---
 
+### 📋 Frontmatter Fields (YAML Metadata)
+
+All slash commands support frontmatter metadata (inspired by [Claude Code slash commands](https://code.claude.com/docs/en/slash-commands)):
+
+| Field | Required | Description | Example |
+|-------|----------|-------------|---------|
+| `description` | ✅ Yes | Brief description (shown in `/help`) | `"Create feature specification"` |
+| `argument-hint` | ⚠️ Recommended | Show expected arguments | `[feature-description]` or `[pr-number] [priority]` |
+| `scripts` | Optional | Cross-platform scripts | `sh: scripts/bash/script.sh`<br>`ps: scripts/powershell/script.ps1` |
+| `allowed-tools` | Optional | Restrict tools (security) | `Bash(git:*), FileEdit(specs/*)` |
+| `model` | Optional | Specify AI model | `claude-3-5-sonnet-20241022` |
+
+**Argument Access Patterns**:
+- `$ARGUMENTS` - All arguments as single string (e.g., "arg1 arg2 arg3")
+- `$1`, `$2`, `$3` - Individual positional arguments (like shell scripts)
+- `{ARGS}` - Escaped for safe script execution
+
+**Example frontmatter**:
+\```yaml
+---
+description: Review pull request with priority
+argument-hint: [pr-number] [priority] [assignee]
+allowed-tools: Bash(git:*), FileEdit(docs/*)
+model: claude-3-5-sonnet-20241022
+---
+\```
+
+---
+
 ### 🎯 Dual-Source Architecture (Composable Spec Systems)
 
 **IMPORTANT**: Slash Commands come from **TWO sources** and can be **composed**:
@@ -942,8 +971,27 @@ Based on your toolkit functions (from **Component 3, STEP 1: Define Toolkit Type
 ##### Template 1: Pure-Execution Slash Commands (Most Common)
 
 ```markdown
+---
+description: Brief description of what this command does
+argument-hint: [arg1] [arg2]  # Optional: show expected arguments
+allowed-tools: Bash(git:*), FileEdit(specs/*)  # Optional: restrict tools
+model: claude-3-5-sonnet-20241022  # Optional: specify model
+---
+
 # /{toolkit-name}.{command}
 
+## User Input
+
+\```text
+$ARGUMENTS
+\```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+**Argument Access**:
+- `$ARGUMENTS` - All arguments as single string
+- `$1`, `$2`, `$3` - Individual positional arguments
+
 ## Purpose
 [What protocol-compliant output to produce]
 
@@ -1005,14 +1053,43 @@ User can validate output independently:
 ##### Template 2: Script-Assisted Slash Commands (Spec-Kit Pattern)
 
 ```markdown
+---
+description: Brief description of what this command does
+argument-hint: [arg1] [arg2]  # Optional: show expected arguments
+scripts:
+  sh: scripts/bash/{script-name}.sh --json "{ARGS}"
+  ps: scripts/powershell/{script-name}.ps1 -Json "{ARGS}"
+allowed-tools: Bash(*), FileEdit(*)  # Scripts need broader permissions
+model: claude-3-5-sonnet-20241022  # Optional: specify model
+---
+
 # /{toolkit-name}.{command}
 
+## User Input
+
+\```text
+$ARGUMENTS
+\```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+**Argument Access**:
+- `$ARGUMENTS` - All arguments as single string
+- `$1`, `$2`, `$3` - Individual positional arguments
+- `{ARGS}` - Escaped for script execution
+
 ## Purpose
 [What to produce, with script handling setup]
 
 ## Helper Script
+
+**Cross-platform execution**:
 \```bash
-scripts/{script-name}.sh --args
+# Linux/Mac
+scripts/bash/{script-name}.sh --json "$ARGUMENTS"
+
+# Windows
+scripts/powershell/{script-name}.ps1 -Json "$ARGUMENTS"
 \```
 
 **Script Purpose**: Set up file structure, create skeleton
@@ -1056,8 +1133,25 @@ scripts/{script-name}.sh --args
 **Purpose**: Remind AI to suggest CLI validation after production
 
 ```markdown
+---
+description: Validate output against protocol specifications
+argument-hint: [file-to-validate]  # Optional: show expected arguments
+allowed-tools: Bash({toolkit-name}:validate:*)  # Only allow validation tools
+model: claude-3-5-haiku-20241022  # Can use lighter model for simple reminders
+---
+
 # /{toolkit-name}.validate
 
+## User Input
+
+\```text
+$ARGUMENTS
+\```
+
+**Argument Access**:
+- `$1` - File to validate (if provided)
+- `$ARGUMENTS` - All arguments
+
 ## Purpose
 Remind AI to suggest validation after producing content