@amsterdamdatalabs/enact-extensions 0.1.5 → 0.1.10

package/extensions/plugin-dev/skills/command-development/references/frontmatter-reference.md

@@ -1,508 +0,0 @@
-# Command Frontmatter Reference
-
-Complete reference for YAML frontmatter fields in slash commands.
-
-## Frontmatter Overview
-
-YAML frontmatter is optional metadata at the start of command files:
-
-```markdown
----
-description: Brief description
-allowed-tools: Read, Write
-model: sonnet
-argument-hint: [arg1] [arg2]
----
-
-Command prompt content here...
-```
-
-All fields are optional. Commands work without any frontmatter.
-
-## Field Specifications
-
-### description
-
-**Type:** String
-**Required:** No
-**Default:** First line of command prompt
-**Max Length:** ~60 characters recommended for `/help` display
-
-**Purpose:** Describes what the command does, shown in `/help` output
-
-**Examples:**
-
-```yaml
-description: Review code for security issues
-```
-
-```yaml
-description: Deploy to staging environment
-```
-
-```yaml
-description: Generate API documentation
-```
-
-**Best practices:**
-
-- Keep under 60 characters for clean display
-- Start with verb (Review, Deploy, Generate)
-- Be specific about what command does
-- Avoid redundant "command" or "slash command"
-
-**Good:**
-
-- ✅ "Review PR for code quality and security"
-- ✅ "Deploy application to specified environment"
-- ✅ "Generate comprehensive API documentation"
-
-**Bad:**
-
-- ❌ "This command reviews PRs" (unnecessary "This command")
-- ❌ "Review" (too vague)
-- ❌ "A command that reviews pull requests for code quality, security issues, and best practices" (too long)
-
-### allowed-tools
-
-**Type:** Comma-separated string
-**Required:** No
-**Default:** Inherits from conversation permissions
-
-**Purpose:** Restrict or specify which tools command can use
-
-**Formats:**
-
-**Single tool:**
-
-```yaml
-allowed-tools: Read
-```
-
-**Multiple tools (comma-separated):**
-
-```yaml
-allowed-tools: Read, Write, Edit
-```
-
-```yaml
-allowed-tools: Read, Write, Bash(git:*)
-```
-
-**Tool Patterns:**
-
-**Specific tools:**
-
-```yaml
-allowed-tools: Read, Grep, Edit
-```
-
-**Bash with command filter:**
-
-```yaml
-allowed-tools: Bash(git:*)           # Only git commands
-allowed-tools: Bash(npm:*)           # Only npm commands
-allowed-tools: Bash(docker:*)        # Only docker commands
-```
-
-**All tools (not recommended):**
-
-```yaml
-allowed-tools: "*"
-```
-
-**When to use:**
-
-1. **Security:** Restrict command to safe operations
-
-   ```yaml
-   allowed-tools: Read, Grep # Read-only command
-   ```
-
-2. **Clarity:** Document required tools
-
-   ```yaml
-   allowed-tools: Bash(git:*), Read
-   ```
-
-3. **Bash execution:** Enable bash command output
-   ```yaml
-   allowed-tools: Bash(git status:*), Bash(git diff:*)
-   ```
-
-**Best practices:**
-
-- Be as restrictive as possible
-- Use command filters for Bash (e.g., `git:*` not `*`)
-- Only specify when different from conversation permissions
-- Document why specific tools are needed
-
-### model
-
-**Type:** String
-**Required:** No
-**Default:** Inherits from conversation
-**Values:**
-
-- Shorthand: `sonnet`, `opus`, `haiku`
-- Full model ID: Format is `claude-<family>-<version>-<date>` (e.g., `claude-sonnet-4-5-20250929`)
-
-Both formats are accepted. Shorthand names use the current default version of each model family.
-
-> **Note:** Anthropic releases new model versions periodically. For current model IDs, consult [Claude Models Overview](https://docs.anthropic.com/en/docs/about-claude/models). Prefer shorthand names unless you need a specific version.
-
-**Purpose:** Specify which Claude model executes the command
-
-**Examples:**
-
-```yaml
-model: haiku # Fast, efficient for simple tasks
-```
-
-```yaml
-model: sonnet # Balanced performance (default)
-```
-
-```yaml
-model: opus # Maximum capability for complex tasks
-```
-
-**When to use:**
-
-**Use `haiku` for:**
-
-- Simple, formulaic commands
-- Fast execution needed
-- Low complexity tasks
-- Frequent invocations
-
-```yaml
----
-description: Format code file
-model: haiku
----
-```
-
-**Use `sonnet` for:**
-
-- Standard commands (default)
-- Balanced speed/quality
-- Most common use cases
-
-```yaml
----
-description: Review code changes
-model: sonnet
----
-```
-
-**Use `opus` for:**
-
-- Complex analysis
-- Architectural decisions
-- Deep code understanding
-- Critical tasks
-
-```yaml
----
-description: Analyze system architecture
-model: opus
----
-```
-
-**Best practices:**
-
-- Omit unless specific need
-- Use `haiku` for speed when possible
-- Reserve `opus` for genuinely complex tasks
-- Test with different models to find right balance
-
-### argument-hint
-
-**Type:** String
-**Required:** No
-**Default:** None
-
-**Purpose:** Document expected arguments for users and autocomplete
-
-**Format:**
-
-```yaml
-argument-hint: [arg1] [arg2] [optional-arg]
-```
-
-**Examples:**
-
-**Single argument:**
-
-```yaml
-argument-hint: [pr-number]
-```
-
-**Multiple required arguments:**
-
-```yaml
-argument-hint: [environment] [version]
-```
-
-**Optional arguments:**
-
-```yaml
-argument-hint: [file-path] [options]
-```
-
-**Descriptive names:**
-
-```yaml
-argument-hint: [source-branch] [target-branch] [commit-message]
-```
-
-**Best practices:**
-
-- Use square brackets `[]` for each argument
-- Use descriptive names (not `arg1`, `arg2`)
-- Indicate optional vs required in description
-- Match order to positional arguments in command
-- Keep concise but clear
-
-**Examples by pattern:**
-
-**Simple command:**
-
-```yaml
----
-description: Fix issue by number
-argument-hint: [issue-number]
----
-Fix issue #$1...
-```
-
-**Multi-argument:**
-
-```yaml
----
-description: Deploy to environment
-argument-hint: [app-name] [environment] [version]
----
-
-Deploy $1 to $2 using version $3...
-```
-
-**With options:**
-
-```yaml
----
-description: Run tests with options
-argument-hint: [test-pattern] [options]
----
-
-Run tests matching $1 with options: $2
-```
-
-### disable-model-invocation
-
-**Type:** Boolean
-**Required:** No
-**Default:** false
-
-**Purpose:** Prevent Skill tool from programmatically invoking command
-
-**Examples:**
-
-```yaml
-disable-model-invocation: true
-```
-
-**When to use:**
-
-1. **Manual-only commands:** Commands requiring user judgment
-
-   ```yaml
-   ---
-   description: Approve deployment to production
-   disable-model-invocation: true
-   ---
-   ```
-
-2. **Destructive operations:** Commands with irreversible effects
-
-   ```yaml
-   ---
-   description: Delete all test data
-   disable-model-invocation: true
-   ---
-   ```
-
-3. **Interactive workflows:** Commands needing user input
-   ```yaml
-   ---
-   description: Walk through setup wizard
-   disable-model-invocation: true
-   ---
-   ```
-
-**Default behavior (false):**
-
-- Command available to Skill tool
-- Claude can invoke programmatically
-- Still available for manual invocation
-
-**When true:**
-
-- Command only invokable by user typing `/command`
-- Not available to Skill tool
-- Safer for sensitive operations
-
-**Best practices:**
-
-- Use sparingly (limits Claude's autonomy)
-- Document why in command comments
-- Consider if command should exist if always manual
-
-## Complete Examples
-
-### Minimal Command
-
-No frontmatter needed:
-
-```markdown
-Review this code for common issues and suggest improvements.
-```
-
-### Simple Command
-
-Just description:
-
-```markdown
----
-description: Review code for issues
----
-
-Review this code for common issues and suggest improvements.
-```
-
-### Standard Command
-
-Description and tools:
-
-```markdown
----
-description: Review Git changes
-allowed-tools: Bash(git:*), Read
----
-
-Current changes: `git diff --name-only`
-
-Review each changed file for:
-
-- Code quality
-- Potential bugs
-- Best practices
-```
-
-### Complex Command
-
-All common fields:
-
-```markdown
----
-description: Deploy application to environment
-argument-hint: [app-name] [environment] [version]
-allowed-tools: Bash(kubectl:*), Bash(helm:*), Read
-model: sonnet
----
-
-Deploy $1 to $2 environment using version $3
-
-Pre-deployment checks:
-
-- Verify $2 configuration
-- Check cluster status: `kubectl cluster-info`
-- Validate version $3 exists
-
-Proceed with deployment following deployment runbook.
-```
-
-### Manual-Only Command
-
-Restricted invocation:
-
-```markdown
----
-description: Approve production deployment
-argument-hint: [deployment-id]
-disable-model-invocation: true
-allowed-tools: Bash(gh:*)
----
-
-<!--
-MANUAL APPROVAL REQUIRED
-This command requires human judgment and cannot be automated.
--->
-
-Review deployment $1 for production approval:
-
-Deployment details: `gh api /deployments/$1`
-
-Verify:
-
-- All tests passed
-- Security scan clean
-- Stakeholder approval
-- Rollback plan ready
-
-Type "APPROVED" to confirm deployment.
-```
-
-## Validation
-
-### Common Errors
-
-**Invalid YAML syntax:**
-
-```yaml
----
-description: Missing quote
-allowed-tools: Read, Write
-model: sonnet
---- # ❌ Missing closing quote above
-```
-
-**Fix:** Validate YAML syntax
-
-**Incorrect tool specification:**
-
-```yaml
-allowed-tools: Bash # ❌ Missing command filter
-```
-
-**Fix:** Use `Bash(git:*)` format
-
-**Invalid model name:**
-
-```yaml
-model: gpt4 # ❌ Not a valid Claude model
-```
-
-**Fix:** Use shorthand (`sonnet`, `opus`, `haiku`) or full model ID (see [Claude Models Overview](https://docs.anthropic.com/en/docs/about-claude/models))
-
-### Validation Checklist
-
-Before committing command:
-
-- [ ] YAML syntax valid (no errors)
-- [ ] Description under 60 characters
-- [ ] allowed-tools uses proper format
-- [ ] model is valid value if specified
-- [ ] argument-hint matches positional arguments
-- [ ] disable-model-invocation used appropriately
-
-## Best Practices Summary
-
-1. **Start minimal:** Add frontmatter only when needed
-2. **Document arguments:** Always use argument-hint with arguments
-3. **Restrict tools:** Use most restrictive allowed-tools that works
-4. **Choose right model:** Use haiku for speed, opus for complexity
-5. **Manual-only sparingly:** Only use disable-model-invocation when necessary
-6. **Clear descriptions:** Make commands discoverable in `/help`
-7. **Test thoroughly:** Verify frontmatter works as expected