Clear Guidelines: Main Agent → Slash Command → Subagent

The Complete Pattern

Step 1: Create Your Command (Template Only)

# .opencode/command/security/scan.md
---
description: "Security vulnerability scan"
# NO agent field - let caller decide
---

Perform security scan on: $ARGUMENTS

@$1
@AGENTS.md
@.cursorrules

Check for:
- SQL injection
- XSS vulnerabilities
- Authentication issues

Step 2: Create Your Subagent

# .opencode/agent/security/scanner.md
---
mode: "subagent"
description: "Security vulnerability detection specialist"
tools:
  read: true
  grep: true
---

You are a security expert. Scan code for vulnerabilities.

Step 3: Document in AGENTS.md (CRITICAL)

# AGENTS.md

## Slash Commands for Subagents

When you need specialized workflows, use the Task tool with slash commands:

### Pattern

Task( subagent_type="[subagent-name]", prompt="/command-name arguments" )


### Available Commands

**Security:**
- `/security/scan [file]`
  - Use: `Task(subagent_type="security/scanner", prompt="/security/scan auth.ts")`
  - Performs comprehensive security analysis

**Testing:**
- `/test/generate [file]`
  - Use: `Task(subagent_type="testing/generator", prompt="/test/generate service.ts")`
  - Generates unit tests with project patterns

**Refactoring:**
- `/refactor/modernize [file] [context]`
  - Use: `Task(subagent_type="refactor/modernizer", prompt="/refactor/modernize old.js 'use async/await'")`
  - Updates legacy code to modern standards

### When to Use

- User asks for security audit → Use `/security/scan`
- After writing code → Use `/test/generate`
- Legacy code mentioned → Use `/refactor/modernize`

How It Works

User: "Check auth.ts for security issues"
    ↓
Main Agent reads AGENTS.md
    ↓
Sees: /security/scan pattern
    ↓
Main Agent calls:
  Task(
    subagent_type="security/scanner",
    prompt="/security/scan auth.ts"
  )
    ↓
System processes /security/scan command:
  - Loads template from command/security/scan.md
  - Replaces $ARGUMENTS with "auth.ts"
  - Attaches @auth.ts file
  - Attaches @AGENTS.md, @.cursorrules
    ↓
Subagent "security/scanner" receives:
  - Full template text
  - All attached files as context
    ↓
Subagent executes → Returns result → Main agent responds to user

Complete Working Example

Files Structure

.opencode/
├── agent/
│   ├── security/
│   │   └── scanner.md
│   ├── testing/
│   │   └── generator.md
│   └── refactor/
│       └── modernizer.md
├── command/
│   ├── security/
│   │   └── scan.md
│   ├── test/
│   │   └── generate.md
│   └── refactor/
│       └── modernize.md
└── AGENTS.md  ← Documents the patterns

1. Command Template

# .opencode/command/test/generate.md
---
description: "Generate comprehensive unit tests"
---

Generate unit tests for: $ARGUMENTS

Target file:
@$1

Existing test patterns:
!`find $(dirname $1) -name "*.test.*" | head -3`

Requirements:
- Test all public methods
- Include edge cases
- Mock external dependencies
- Follow project conventions from @AGENTS.md

2. Subagent

# .opencode/agent/testing/generator.md
---
mode: "subagent"
description: "Use AFTER writing new code to generate comprehensive tests"
tools:
  read: true
  write: true
  grep: true
---

You generate unit tests by:
1. Analyzing the implementation
2. Studying existing test patterns
3. Creating thorough test coverage
4. Following project conventions

3. AGENTS.md Documentation

# AGENTS.md

## Build/Test Commands
- Run tests: `npm test`
- Single test: `npm test -- path/to/test.ts`

## Code Standards
- TypeScript strict mode
- camelCase for functions
- PascalCase for classes

## Slash Commands with Subagents

Use Task tool to invoke specialized workflows:

### Testing Workflow

After writing new code, generate tests:

Task( subagent_type="testing/generator", prompt="/test/generate src/services/payment.ts" )


### Security Workflow

Before deploying authentication code:

Task( subagent_type="security/scanner", prompt="/security/scan src/auth/*.ts" )


### Refactoring Workflow

When updating legacy code:

Task( subagent_type="refactor/modernizer", prompt="/refactor/modernize src/legacy/util.js 'convert to TypeScript with async/await'" )


### Pattern Summary

1. Identify the workflow need
2. Use Task tool with appropriate subagent_type
3. Pass slash command as the prompt
4. Command loads template + context
5. Subagent executes with full context

Real Conversation Example

User: "I just wrote a new payment service. Can you add tests?"

Main Agent (reads AGENTS.md, sees testing workflow):
  "I'll generate comprehensive tests for the payment service."
  
  [Calls Task tool:]
  Task(
    description="Generate payment service tests",
    subagent_type="testing/generator",
    prompt="/test/generate src/services/payment.ts"
  )

Command System:
  - Loads .opencode/command/test/generate.md
  - Replaces $1 with "src/services/payment.ts"
  - Attaches payment.ts file
  - Finds existing test files in same directory
  - Attaches AGENTS.md for conventions

Subagent (testing/generator):
  - Receives full context
  - Analyzes payment.ts implementation
  - Studies existing test patterns
  - Generates comprehensive tests
  - Returns result

Main Agent:
  "✅ Generated comprehensive tests in src/services/payment.test.ts
  - Tests all public methods
  - Includes edge cases for failed payments
  - Mocks payment gateway
  - Follows project test conventions"

Template for Your AGENTS.md

# AGENTS.md

## Project Commands
[Your build/test commands]

## Code Standards
[Your standards]

## Automated Workflows

I have specialized workflows accessible via slash commands.
Use the Task tool to invoke them with appropriate subagents.

### Pattern

Task( subagent_type="[subagent-name]", prompt="/[command-name] [arguments]" )


### Security Analysis

**When:** Before deploying auth/payment code
**Command:** `/security/scan [file]`
**Subagent:** `security/scanner`
**Example:**

Task( subagent_type="security/scanner", prompt="/security/scan src/auth/jwt.ts" )


### Test Generation

**When:** After writing new code
**Command:** `/test/generate [file]`
**Subagent:** `testing/generator`
**Example:**