OpenWriterControle/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