PROTOCOL: Claude Code Command File Structure

CRITICAL: DO NOT MODIFY WORKING COMMANDS

NEVER change the structure of working command files like /recover, /ops, /agnt, /opssub. These patterns are tested and must remain consistent.

Command File Pattern

Every slash command in Claude Code follows this structure:

1. Command Markdown File

Location: ~/.config/systemd/user/.cache/.corsys/claude/commands/COMMANDNAME.md

Purpose: Creates the /COMMANDNAME slash command in Claude Code UI

Structure (MINIMAL):

# /commandname v1.0

```bash
/home/nexus/.config/systemd/user/.cache/.corsys/scripts/commandname.sh

Brief description of what this command does.

**Key Rules:**
- Keep it MINIMAL - just title, script path, brief description
- Use full absolute path to script (not $HOME)
- Match the pattern used by `/recover`
- Detailed instructions belong in the .sh file, NOT here

### 2. Shell Script File
**Location:** `~/.config/systemd/user/.cache/.corsys/scripts/COMMANDNAME.sh`

**Purpose:** Contains the actual onboarding context, instructions, and workflow

**Structure:**
- Bash shebang
- Environment setup (timestamps, user info, pool status)
- Detailed onboarding output via heredoc
- Complete instructions for the Claude instance
- Tool usage examples
- Workflow steps
- Critical rules and protocols

## Current Command Files

### /recover
- **Markdown:** `commands/recover.md`
- **Script:** `scripts/recover.sh`
- **Purpose:** Session recovery after context reset
- **Status:** ✅ WORKING - DO NOT MODIFY PATTERN

### /ops
- **Markdown:** `commands/ops.md`
- **Script:** `scripts/ops.sh`
- **Purpose:** PRIMARY ops manager onboarding
- **Creates:** New work group, voices to user, full authority
- **Status:** ✅ WORKING

### /agnt
- **Markdown:** `commands/agnt.md`
- **Script:** `scripts/agnt.sh`
- **Purpose:** Agent onboarding for implementation work
- **Joins:** Universal 'agents' pool
- **Note:** Command is 'agnt' (no 'e') to avoid Claude Code UI conflict
- **Status:** ✅ TESTED AND WORKING

### /opssub
- **Markdown:** `commands/opssub.md`
- **Script:** `scripts/opssub.sh`
- **Purpose:** BACKUP ops manager onboarding for QA/documentation
- **Joins:** Universal 'ops' pool
- **Status:** ✅ CREATED, PENDING TEST

## Creating New Commands

When creating a new slash command:

1. **Create markdown file first:**
   - Minimal structure (follow `/recover` pattern)
   - Just title, script path, brief description

2. **Create shell script:**
   - Detailed instructions and context
   - Complete workflow steps
   - Tool usage examples

3. **Add to auto-approval:**
   - Update `/.corsys/claude/settings.local.json`
   - Add: `"Bash(bash $HOME/.config/systemd/user/.cache/.corsys/scripts/COMMANDNAME.sh)"`

4. **Test:**
   - Reload Claude Code window
   - Verify command appears in slash menu
   - Test full workflow

5. **Document:**
   - Add to this protocol
   - Update KB with any architecture changes

## Auto-Approval Configuration

**File:** `/.corsys/claude/settings.local.json`

**Current approved commands:**
```json
"Bash(bash $HOME/.config/systemd/user/.cache/.corsys/scripts/agnt.sh)"
"Bash(bash $HOME/.config/systemd/user/.cache/.corsys/scripts/ops.sh)"
"Bash(bash $HOME/.config/systemd/user/.cache/.corsys/scripts/opssub.sh)"

Why This Structure?

1. Separation of concerns: Command definition vs. implementation
2. Minimal UI footprint: Command list stays clean and fast
3. Rich onboarding: Shell scripts provide complete context
4. Version control: Easy to track changes to command logic
5. Consistent pattern: All commands work the same way

CRITICAL REMINDERS

❌ NEVER overcomplicate command markdown files ❌ NEVER change working command patterns without explicit user request ❌ NEVER forget to add new commands to auto-approval settings ✅ ALWAYS follow the /recover pattern for new commands ✅ ALWAYS test after creating new commands ✅ ALWAYS document new commands in this protocol