OpenAgentsControl/plugins/claude-code/commands/oac-help.md

---

name: oac:help description: Show usage guide for OpenAgents Control workflow, skills, and commands

argument-hint: [skill-name]

OpenAgents Control - Help Guide

$ARGUMENTS

🎯 Overview

OpenAgents Control (OAC) brings intelligent multi-agent orchestration to Claude Code with a 6-stage workflow for context-aware development.

🏗️ How Everything Works Together

Architecture Flow

User Request
    ↓
┌─────────────────────────────────────────────────────────────┐
│ using-oac skill (6-stage workflow)                          │
│                                                              │
│  Stage 1: Analyze & Discover                                │
│      ↓                                                       │
│      └─→ /context-discovery → context-scout subagent        │
│                                                              │
│  Stage 2: Plan & Approve                                    │
│      ↓                                                       │
│      └─→ Present plan → REQUEST USER APPROVAL               │
│                                                              │
│  Stage 3: LoadContext                                       │
│      ↓                                                       │
│      ├─→ Read discovered context files                      │
│      └─→ /external-scout (if external packages needed)      │
│                                                              │
│  Stage 4: Execute                                           │
│      ↓                                                       │
│      ├─→ Simple: Direct implementation                      │
│      └─→ Complex: /task-breakdown → task-manager subagent   │
│           ↓                                                  │
│           ├─→ /code-execution → coder-agent subagent        │
│           ├─→ /test-generation → test-engineer subagent     │
│           └─→ /code-review → code-reviewer subagent         │
│                                                              │
│  Stage 5: Validate                                          │
│      ↓                                                       │
│      └─→ Run tests, verify acceptance criteria              │
│                                                              │
│  Stage 6: Complete                                          │
│      ↓                                                       │
│      └─→ Update docs, summarize changes                     │
└─────────────────────────────────────────────────────────────┘
    ↓
Deliverables returned to user

Skill → Subagent Mapping

Skill	Invokes	Primary Tools	Purpose
/using-oac	N/A (orchestrator)	All	Main workflow orchestration through 6 stages
/context-discovery	context-scout	Read, Glob, Grep	Discover relevant context files and standards
/context-manager	context-manager	Read, Write, Glob, Bash	Manage context files, validate structure, organize
/task-breakdown	task-manager	Read, Write, Bash	Break complex features into atomic subtasks
/code-execution	coder-agent	Read, Write, Edit, Bash	Implement code following discovered standards
/test-generation	test-engineer	Read, Write, Bash	Generate comprehensive tests using TDD
/code-review	code-reviewer	Read, Grep, Bash	Perform security and quality code review
/external-scout	N/A (direct API)	WebFetch, Context7	Fetch live documentation for external packages

Configuration Hierarchy

OAC uses a layered configuration system with the following priority:

1. .oac (current directory)
   ↓ Project-specific settings
   ↓ Overrides global and built-in defaults
   ↓
2. ~/.oac (home directory)
   ↓ Personal defaults across all projects
   ↓ Overrides built-in defaults
   ↓
3. Built-in defaults (plugins/claude-code/.oac.example)
   ↓ Fallback when no custom config exists

Configuration sections:

• context.* - Context download and caching behavior
• cleanup.* - Temporary file cleanup settings
• workflow.* - Workflow automation preferences
• external_scout.* - External documentation fetching

Example: If you set workflow.auto_approve: true in ~/.oac, it applies to all projects unless a specific project's .oac overrides it.

📋 6-Stage Workflow

The OAC workflow ensures context-aware, high-quality code delivery:

Stage 1: Analyze & Discover

• Understand requirements and scope
• Invoke /context-discovery to find relevant context files
• Identify project standards, patterns, and conventions

Stage 2: Plan & Approve

• Present implementation plan
• REQUEST APPROVAL before proceeding
• Confirm approach with user

Stage 3: LoadContext

• Read all discovered context files
• Load coding standards, security patterns, naming conventions
• Pre-load context for execution stage

Stage 4: Execute

• Simple tasks: Direct implementation
• Complex tasks: Invoke /task-breakdown to decompose into subtasks
• Follow loaded standards and patterns

Stage 5: Validate

• Run tests and validation
• STOP on failure - fix before proceeding
• Verify acceptance criteria met

Stage 6: Complete

• Update documentation
• Summarize changes
• Return results

🤖 Available Subagents

OAC provides specialized subagents for different tasks:

task-manager

Break down complex features into atomic, verifiable subtasks with dependency tracking.

When to use: Complex features requiring multiple steps, parallel execution, or dependency management.

Example:

Use the task-manager subagent to break down this feature:
"Add user authentication with JWT tokens"

context-scout

Discover relevant context files, standards, and patterns for your task.

When to use: Before implementing any feature, to find coding standards, security patterns, and conventions.

Example:

Use the context-scout subagent to find:
- TypeScript coding standards
- Security patterns for authentication
- API design conventions

coder-agent

Execute coding subtasks with full context awareness and self-review.

When to use: Implementing specific features or subtasks following discovered standards.

Example:

Use the coder-agent subagent to implement:
- JWT authentication service
- Following security patterns from context

test-engineer

Generate comprehensive tests using TDD principles.

When to use: Creating tests for new features or existing code.

Example:

Use the test-engineer subagent to create tests for:
- Authentication service
- Following test standards from context

code-reviewer

Perform thorough code review with security and quality analysis.

When to use: Reviewing code changes before committing.

Example:

Use the code-reviewer subagent to review:
- Recent authentication changes
- Check security patterns and code quality

context-manager

Manage context files, discover context roots, validate structure, and organize project context.

When to use: Adding context from GitHub/worktrees, validating context files, or organizing context structure.

Example:

Use the context-manager subagent to:
- Add context from GitHub: github:acme-corp/standards
- Add context from worktree: worktree:../team-context
- Validate existing context files
- Update navigation for discoverability

🎨 Available Skills

Skills guide the main agent through specific workflows:

/using-oac

Main workflow orchestrator implementing the 6-stage process.

Auto-invoked: When you start a development task.

/context-discovery

Guide for discovering and loading relevant context files.

Usage: /context-discovery authentication feature

/task-breakdown

Guide for breaking down complex features into subtasks.

Usage: /task-breakdown user authentication system

/code-execution

Guide for executing coding tasks with context awareness.

Usage: /code-execution implement JWT service

/test-generation

Guide for generating comprehensive tests.

Usage: /test-generation authentication service

/code-review

Guide for performing thorough code reviews.

Usage: /code-review src/auth/

📝 Available Commands

/oac:setup

Download context files from GitHub repository.

Usage: /oac:setup

What it does:

• Fetches .opencode/context/ from GitHub
• Validates context structure
• Creates .context-manifest.json

/oac:plan

Plan and break down a complex feature into atomic subtasks.

Usage: /oac:plan [feature description]

Examples:

• /oac:plan user authentication system
• /oac:plan API rate limiting with Redis
• /oac:plan payment integration (PCI compliance required)

What it does:

• Analyzes feature requirements
• Discovers relevant context
• Creates task breakdown with dependencies
• Generates JSON task files in .tmp/tasks/{feature}/

/oac:add-context

Add context files from GitHub, worktrees, local files, or URLs.

Usage: /oac:add-context [source] [options]

Examples:

• /oac:add-context github:acme-corp/standards --category=team
• /oac:add-context worktree:../team-context --category=team
• /oac:add-context file:./docs/patterns/auth.md --category=custom
• /oac:add-context url:https://example.com/doc.md --category=external

Options:

• --category=<name> - Target category (default: custom)
• --priority=<level> - Priority level (critical, high, medium)
• --overwrite - Overwrite existing files
• --dry-run - Preview without making changes

What it does:

• Discovers context root location
• Fetches/copies files from source
• Validates markdown format
• Updates navigation for discoverability

/oac:help

Show this usage guide (you're reading it now!).

Usage:

• /oac:help - Show general help
• /oac:help <skill-name> - Show help for specific skill

/oac:status

Show plugin status and installed context.

Usage: /oac:status

What it shows:

• Plugin version
• Installed context version
• Available subagents and skills
• Context file count

/oac:cleanup

Clean up old temporary files with approval.

Usage: /oac:cleanup

What it does:

• Finds old session files (>7 days)
• Finds old task files (>30 days)
• Finds old external cache (>7 days)
• Requests approval before deletion

⚙️ Configuration Setup

First-Time Setup

1. Download context files (required):

   /oac:setup --core
   

   This downloads coding standards, security patterns, and conventions.

2. Create configuration (optional): ```bash

   For project-specific settings

   cp plugins/claude-code/.oac.example .oac

# For global settings cp plugins/claude-code/.oac.example ~/.oac

3. **Customize settings**:
   Edit `.oac` to configure:
   - Auto-download context updates
   - Cleanup schedules
   - Workflow preferences
   - External documentation sources

### Configuration Options

**Context settings**:
- `context.auto_download: true/false` - Auto-download context on first use
- `context.categories: core,openagents-repo` - Which context categories to load
- `context.update_check: true/false` - Check for context updates on startup
- `context.cache_days: 7` - How long to cache context before suggesting update

**Cleanup settings**:
- `cleanup.auto_prompt: true/false` - Prompt to clean old temporary files
- `cleanup.session_days: 7` - Days before session files are considered old
- `cleanup.task_days: 30` - Days before completed tasks are considered old
- `cleanup.external_days: 7` - Days before external cache is considered old

**Workflow settings**:
- `workflow.auto_approve: false` - **WARNING**: Skips approval gates (not recommended)
- `workflow.verbose: false` - Show detailed workflow progress

**External scout settings**:
- `external_scout.enabled: true/false` - Enable external documentation fetching
- `external_scout.cache_enabled: true/false` - Cache external docs locally
- `external_scout.sources: context7` - Documentation sources to use

## 🚀 Quick Start Examples

### Example 1: Simple Feature

User: "Add a login endpoint"

Claude (using-oac skill):

1. Analyze: Understand login requirements
2. Plan: Present implementation approach → REQUEST APPROVAL
3. LoadContext: Read API standards, security patterns
4. Execute: Implement endpoint directly
5. Validate: Run tests
6. Complete: Update API docs ```

Example 2: Complex Feature

User: "Build a complete authentication system"

Claude (using-oac skill):
1. Analyze: Understand auth requirements
2. Plan: Present high-level approach → REQUEST APPROVAL
3. LoadContext: Read security patterns, API standards
4. Execute: Invoke /task-breakdown
   - Subtask 1: JWT service
   - Subtask 2: Auth middleware
   - Subtask 3: Login endpoint
   - Subtask 4: Refresh token logic
5. Validate: Run integration tests
6. Complete: Update docs, summarize

Example 3: Using Subagents Directly

# Discover context first
Use the context-scout subagent to find TypeScript and security patterns.

# Break down complex task
Use the task-manager subagent to break down the authentication system.

# Implement subtask
Use the coder-agent subagent to implement JWT service following discovered patterns.

# Generate tests
Use the test-engineer subagent to create tests for the JWT service.

# Review code
Use the code-reviewer subagent to review all authentication changes.

🔑 Key Principles

Context First, Code Second

Always discover and load context before implementing. This ensures your code follows project standards.

Approval Gates

OAC requests approval before execution. This prevents unwanted changes and ensures alignment.

Atomic Tasks

Complex features are broken into 1-2 hour subtasks with clear acceptance criteria.

Self-Review

Every deliverable passes validation before completion (types, imports, anti-patterns, acceptance criteria).

No Nested Calls

In Claude Code, only the main agent can invoke subagents. Skills orchestrate the workflow, subagents execute specialized tasks.

📚 Learn More

• Installation: See INSTALL.md for setup instructions
• Quick Start: See QUICK-START.md for getting started
• Architecture: See README.md for system overview
• Context System: Explore context/ directory for standards and patterns

🆘 Troubleshooting

"Context files not found"

Run /oac:setup to download context from GitHub.

"Subagent not available"

Verify plugin installation with /oac:status.

"Approval not requested"

This is a bug - OAC should always request approval before execution. Please report.

"Nested subagent call error"

Claude Code doesn't support nested calls. Use skills to orchestrate, not subagents calling subagents.

💡 Tips

1. Start with /oac:setup - Download context files first
2. Let the workflow guide you - The using-oac skill handles orchestration
3. Use context-scout early - Discover standards before coding
4. Break down complex tasks - Use task-manager for multi-step features
5. Review before committing - Use code-reviewer for quality checks

---

Version: 1.0.0
Plugin: oac
Last Updated: 2026-02-16