Commands Manager

Commands Manager - Branch of JARVIS-06

Build and improve commands following the commands-management policy.

Policy Source

Primary policy: JARVIS-06 → .claude/skills/commands-management/SKILL.md

This branch executes the policy defined by JARVIS-06. Always sync with Primary before major operations.

Quick Decision Tree

Task Received
    │
    ├── Create new command? ─────────────> Workflow 1: Build
    │   └── What type?
    │       ├── Simple action ───────────> Single-phase command
    │       ├── Complex workflow ────────> Multi-phase command
    │       └── Skill invocation ────────> Skill-invoking command
    │
    ├── Adapt marketplace command? ──────> Workflow 3: Adapt
    │
    ├── Fix existing command? ───────────> Workflow 2: Improve
    │
    └── Validate command? ───────────────> Validation Checklist

Command Overview

Slash commands are frequently-used prompts defined as Markdown files that Claude executes during interactive sessions.

Key concepts:

• Markdown file format for commands
• YAML frontmatter for configuration
• Dynamic arguments ($ARGUMENTS, $1, $2)
• File references (@$1, @file.txt)
• Bash execution for context (!command)
• Commands are instructions FOR Claude, not messages TO user

Critical: Commands are Instructions FOR Claude

Commands are written for agent consumption, not human consumption.

When a user invokes /command-name, the command content becomes Claude's instructions.

Correct (instructions for Claude):

Review this code for security vulnerabilities including:
- SQL injection
- XSS attacks
- Authentication issues

Provide specific line numbers and severity ratings.

Incorrect (messages to user):

This command will review your code for security issues.
You'll receive a report with vulnerability details.

Always use the first approach - tell Claude what to do.

Command Locations

Command Types

Workflow 1: Build New Command

Step 1: Define Command Purpose

Answer these questions:

• What task does this command automate?
• What arguments does it need (if any)?
• What tools should it use?
• Does it need multiple phases?
• Should it invoke a skill?
• Does it need bash execution for context?

Step 2: Write Frontmatter

---
description: Brief description for /help (<60 chars)
argument-hint: [file-path] [options]
allowed-tools: Read, Write, Edit, Bash(git:*)
model: inherit
---

Frontmatter fields:

Step 3: Write Command Body

Single-Phase Template:

---
description: [What it does in <60 chars]
argument-hint: [expected-args]
allowed-tools: Read, Write, Edit
---

[Action verb] the [target] to [achieve goal]:

1. [First step with specific action]
2. [Second step]
3. [Third step]

Report [expected output format].

Multi-Phase Template:

---
description: [What it does]
argument-hint: [args]
---

## Phase 1: Analysis

Analyze [target] for [criteria]:

1. [Analysis step 1]
2. [Analysis step 2]

Document findings before proceeding.

## Phase 2: Implementation

Based on Phase 1 findings, implement [changes]:

1. [Implementation step 1]
2. [Implementation step 2]

## Phase 3: Verification

Verify implementation:

1. [Verification step 1]
2. [Verification step 2]

Report completion status with summary.

Skill-Invoking Template:

---
description: [What it does]
disable-model-invocation: true
---

Invoke the [skill-name] skill to [purpose].

Follow the skill's workflow for [specific task].

Report results following skill's output format.

Step 4: Use Arguments Correctly

Examples:

# Using $ARGUMENTS (all args)
---
description: Create PR with given title
argument-hint: [title]
---

Create a pull request with title: $ARGUMENTS

# Using positional args
---
description: Compare two files
argument-hint: [file1] [file2]
---

Compare the contents of @$1 with @$2

# Using @$1 for file content
---
description: Review code file
argument-hint: [file-path]
---

Review the following code for issues:

@$1

Provide feedback on quality and suggestions.

Step 5: Add Bash Execution (if needed)

Use ! backticks to execute bash and include output:

---
description: Review changed files
allowed-tools: Read, Bash(git:*)
---

Files changed: !`git diff --name-only`

Review each file for:
1. Code quality and style
2. Potential bugs or issues
3. Test coverage

Provide specific feedback for each file.

Bash execution patterns:

# Get git status
Current branch: !`git branch --show-current`

# Run tests
Test results: !`npm test 2>&1`

# Check environment
Node version: !`node --version`

Note: Requires Bash in allowed-tools with appropriate pattern.

Step 6: Save and Validate

Save to: commands/[command-name].md

Run validation checklist.

Workflow 2: Improve Existing Command

Step 1: Analyze Current State

# Read command file
cat commands/[name].md

# Check for common issues:
# - Written as message TO user?
# - Missing description?
# - No argument-hint when needed?
# - Missing output format?

Step 2: Gap Analysis

Step 3: Apply Fixes

Converting message to instructions:

Before (wrong):

This command will analyze your code and find bugs.
You'll receive a report when it's done.

After (correct):

Analyze the code for bugs and issues:

1. Search for common error patterns
2. Check for security vulnerabilities
3. Identify performance issues

Report findings with severity levels and fix suggestions.

Adding output format:

Report results as:
- Summary: [1-2 sentences]
- Findings: [Bulleted list]
- Recommendations: [Action items]

Converting to multi-phase:

## Phase 1: Discovery
[Analysis steps]

## Phase 2: Action
[Implementation steps]

## Phase 3: Verification
[Check steps]

Fixing bash execution:

Wrong:

`git status`

Correct:

!`git status`

Step 4: Validate

Run full validation checklist.

Workflow 3: Adapt Marketplace Command

When taking a command from wshobson-agents, obra-superpowers, or similar:

Step 1: Read Original Command

cat marketplace-plugin/commands/[command].md

Note:

• Frontmatter structure
• Phase structure (if multi-phase)
• Argument handling
• Tool restrictions
• Bash execution patterns

Step 2: Identify JARVIS Fit

Step 3: Adapt Frontmatter

Original:

---
description: Review code for issues
---

Adapted for JARVIS:

---
description: Review code following JARVIS standards
argument-hint: [file-path]
allowed-tools: Read, Grep, Glob
---

Step 4: Adapt Body

Add JARVIS-specific context:

Review the code following JARVIS ecosystem standards:

1. Check compliance with Primary Skill patterns
2. Verify MCP tool usage follows category guidelines
3. Ensure 4-plugin architecture is respected
4. Validate CLAUDE.md references are current

Report findings with JARVIS-specific recommendations.

Add category-specific instructions:

For this category (JARVIS-XX), additionally check:
- [Category-specific check 1]
- [Category-specific check 2]

Step 5: Validate Adaptation

Run full validation checklist.

Plugin Command Features

CLAUDE_PLUGIN_ROOT Variable

Plugin commands can reference plugin files portably:

---
description: Analyze using plugin script
allowed-tools: Bash(node:*)
---

Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`

Review results and report findings.

Common patterns:

# Execute plugin script
!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`

# Load plugin configuration
@${CLAUDE_PLUGIN_ROOT}/config/settings.json

# Use plugin template
@${CLAUDE_PLUGIN_ROOT}/templates/report.md

# Access plugin resources
@${CLAUDE_PLUGIN_ROOT}/docs/reference.md

Plugin Command Organization

plugin-name/
├── commands/
│   ├── foo.md              # /foo (plugin:plugin-name)
│   ├── bar.md              # /bar (plugin:plugin-name)
│   └── utils/
│       └── helper.md       # /helper (plugin:plugin-name:utils)
└── plugin.json

Subdirectories create namespaces shown in /help.

Integration with Plugin Components

Agent integration:

---
description: Deep code review
argument-hint: [file-path]
---

Initiate comprehensive review of @$1 using the code-reviewer agent.

The agent will analyze:
- Code structure
- Security issues
- Performance
- Best practices

Skill integration:

---
description: Document API with standards
argument-hint: [api-file]
---

Document API in @$1 following plugin standards.

Use the api-docs-standards skill to ensure:
- Complete endpoint documentation
- Consistent formatting
- Example quality

Multi-component workflow:

---
description: Comprehensive review workflow
argument-hint: [file]
allowed-tools: Bash(node:*), Read
---

Target: @$1

Phase 1 - Static Analysis:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`

Phase 2 - Deep Review:
Launch code-reviewer agent for detailed analysis.

Phase 3 - Standards Check:
Use coding-standards skill for validation.

Phase 4 - Report:
Template: @${CLAUDE_PLUGIN_ROOT}/templates/review.md

Compile findings into report following template.

Validation Patterns

Argument Validation

---
description: Deploy with validation
argument-hint: [environment]
---

Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"`

If $1 is valid environment:
  Deploy to $1
Otherwise:
  Explain valid environments: dev, staging, prod
  Show usage: /deploy [environment]

File Existence Checks

---
description: Process configuration
argument-hint: [config-file]
---

Check file exists: !`test -f $1 && echo "EXISTS" || echo "MISSING"`

If file exists:
  Process configuration: @$1
Otherwise:
  Explain where to place config file
  Provide example configuration

Plugin Resource Validation

---
description: Run plugin analyzer
allowed-tools: Bash(test:*)
---

Validate plugin setup:
- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "OK" || echo "MISSING"`
- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "OK" || echo "MISSING"`

If all checks pass, run analysis.
Otherwise, report missing components.

Validation Checklist

Structure

• File in commands/ directory with .md extension
• Filename is lowercase with hyphens
• Valid YAML frontmatter between --- markers

Frontmatter

• description present and under 60 characters
• argument-hint present if command takes arguments
• allowed-tools present if tool restriction needed
• model valid if specified (sonnet/opus/haiku/inherit)

Body Content

• Written as instructions FOR Claude (imperative)
• Does NOT use "I will", "This command will", "You'll get"
• Uses action verbs: "Analyze", "Create", "Review", "Check"
• Has numbered steps for procedures
• Has "Report..." section defining output format

Arguments (if applicable)

• $ARGUMENTS used correctly for all args
• $1, $2, $3 used correctly for positional args
• @$1 used correctly for file content inclusion
• argument-hint matches actual usage

Bash Execution (if applicable)

• Uses ! backticks syntax (!command)
• allowed-tools includes Bash with appropriate pattern
• Commands are safe and tested
• Error output handled (2>&1 if needed)

Multi-Phase (if applicable)

• Phases clearly marked with ## headers
• Each phase has distinct purpose
• Phases build on each other logically
• Final phase includes verification

Plugin Commands (if applicable)

• Uses ${CLAUDE_PLUGIN_ROOT} for plugin paths
• No hardcoded absolute paths
• Resources exist in plugin

Command Examples

Example 1: Simple Review Command

---
description: Review file for code quality
argument-hint: [file-path]
allowed-tools: Read, Grep
---

Review @$1 for code quality issues:

1. Check for code style violations
2. Identify potential bugs
3. Look for performance issues
4. Verify error handling

Report findings with:
- Issue: [description]
- Severity: [high/medium/low]
- Suggestion: [fix recommendation]

Example 2: Multi-Phase Deployment Command

---
description: Deploy category to production
argument-hint: [category-number]
allowed-tools: Read, Bash(git:*), Bash(gcloud:*)
---

## Phase 1: Pre-Deployment Checks

Verify JARVIS-$1 is ready for deployment:

1. Check all tests pass
2. Verify CLAUDE.md is up to date
3. Confirm Primary Skill has no TODOs
4. Validate mcp.json configuration

Document any issues before proceeding.

## Phase 2: Deployment

Deploy JARVIS-$1:

1. Tag the release with version
2. Push to production branch
3. Deploy MCP server if applicable
4. Update BigQuery tables if needed

## Phase 3: Verification

Verify deployment success:

1. Test MCP tools are responding
2. Verify category loads correctly
3. Check logs for errors

Report deployment status with:
- Version deployed
- Components updated
- Any issues encountered

Example 3: Skill-Invoking Command

---
description: Improve category following dev cycle
argument-hint: [category-number]
disable-model-invocation: true
---

Invoke the category-optimizer skill for JARVIS-$1.

Follow the skill's self-improvement cycle:

1. Analyze current CLAUDE.md
2. Review settings.json
3. Check Primary Skill completeness
4. Apply improvements

Report all changes made following the skill's output format.

Example 4: Plugin Command with Bash

---
description: Run full analysis pipeline
argument-hint: [target-file]
allowed-tools: Read, Bash(node:*)
---

Target: @$1

Run analysis pipeline:

Step 1 - Lint:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`

Step 2 - Type Check:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/typecheck.js $1`

Step 3 - Security Scan:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/security.js $1`

Compile all findings and provide summary with:
- Total issues found
- Issues by severity
- Recommended fixes

Troubleshooting

Common Issues & Fixes

Best Practices

DO:

• ✅ Write instructions FOR Claude
• ✅ Use imperative verbs (Analyze, Create, Review)
• ✅ Include numbered steps for procedures
• ✅ Define output format with "Report..."
• ✅ Add argument-hint when taking arguments
• ✅ Use appropriate tool restrictions
• ✅ Test commands before deployment

DON'T:

• ❌ Write messages TO user ("This will...")
• ❌ Use vague instructions ("Check the code")
• ❌ Skip output format definition
• ❌ Forget argument-hint for arg-taking commands
• ❌ Use Bash(*) when specific pattern works
• ❌ Hardcode paths in plugin commands
• ❌ Skip validation

When to Use This Skill

• User asks to create a new slash command
• User asks to adapt a marketplace command
• User asks to validate command structure
• User asks to fix command that's not working
• User asks about command arguments or bash execution
• DEV-Manager detects command issues during improvement cycle
• Regular improvement cycle (~6 sessions)

Sync Protocol

Before executing any workflow:

1. Read JARVIS-06's commands-management SKILL.md
2. Check for policy updates
3. Apply current policy, not cached knowledge