OAC Plugin - First-Time Setup Guide

Version: 1.0.0
Date: 2026-02-16
Audience: First-time users
Time: 5-10 minutes

🎯 What You'll Accomplish

By the end of this guide, you'll have:

✅ OAC plugin installed and verified
✅ Context files downloaded
✅ Working development workflow
✅ Understanding of the 6-stage process

No prior experience needed — just follow the steps in order.

📋 Prerequisites

Before starting, ensure you have:

Claude Code installed and working
Internet connection (for downloading context files)
A project directory to work in

🚀 Step-by-Step Setup

Step 1: Install the Plugin

Choose ONE method:

Option A: From GitHub Marketplace (Recommended)

# Add the marketplace
/plugin marketplace add darrenhinde/OpenAgentsControl

# Install the plugin
/plugin install oac

Expected output:

✓ Marketplace added: darrenhinde/OpenAgentsControl
✓ Plugin installed: oac
✓ Location: ~/.claude/plugins/cache/oac/

Option B: Local Development

# Navigate to the repo
cd /path/to/OpenAgentsControl

# Start Claude with the plugin
claude --plugin-dir ./plugins/claude-code

Expected output:

✓ Loading plugin from: ./plugins/claude-code
✓ Plugin loaded: oac

Step 2: Verify Installation

Run the status command to check everything is working:

/oac:status

Expected output:

OAC Plugin Status
=================

Plugin Version: 1.0.0
Status: ✅ Installed

Components:
- Subagents: 6 available
  ✓ task-manager
  ✓ context-scout
  ✓ external-scout
  ✓ coder-agent
  ✓ test-engineer
  ✓ code-reviewer

- Skills: 9 available
  ✓ using-oac
  ✓ context-discovery
  ✓ external-scout
  ✓ task-breakdown
  ✓ code-execution
  ✓ test-generation
  ✓ code-review
  ✓ context-manager
  ✓ parallel-execution

- Commands: 4 available
  ✓ /oac:setup
  ✓ /oac:help
  ✓ /oac:status
  ✓ /oac:cleanup

Context Files: ⚠️ Not installed yet

✅ Success indicator: You should see "Plugin Version: 1.0.0" and all components listed.

❌ If you see errors: See Troubleshooting section below.

Step 3: Download Context Files

Context files contain coding standards, security patterns, and workflow guides that OAC uses to ensure high-quality code.

Choose ONE option:

Option A: Core Context Only (Recommended for First-Time Users)

/oac:setup --core

What this downloads: ~50 essential files (standards, workflows, patterns)
Download time: 30-60 seconds
Disk space: ~2 MB

Expected output:

Downloading OAC Context Files
==============================

Category: core
Source: https://github.com/darrenhinde/OpenAgentsControl

Downloading files...
✓ .opencode/context/core/standards/code-quality.md
✓ .opencode/context/core/standards/security-patterns.md
✓ .opencode/context/core/standards/typescript.md
✓ .opencode/context/core/workflows/6-stage-workflow.md
... (46 more files)

Summary:
========
✓ Downloaded: 50 files
✓ Location: .opencode/context/
✓ Manifest: plugins/claude-code/.context-manifest.json

Next steps:
- Run /oac:status to verify
- Start coding with /using-oac

Option B: All Context (For Advanced Users)

/oac:setup --all

What this downloads: ~200 files (includes examples, guides, plugin docs)
Download time: 2-3 minutes
Disk space: ~8 MB

Step 4: Verify Context Installation

Check that context files were downloaded successfully:

/oac:status

Expected output:

OAC Plugin Status
=================

Plugin Version: 1.0.0
Status: ✅ Installed

Context Files: ✅ Installed
- Version: 1.0.0
- Location: .opencode/context/
- Files: 50 (core)
- Last updated: 2026-02-16

Components:
... (same as before)

✅ Success indicator: "Context Files: ✅ Installed"

You can also verify manually:

# Check that context directory exists
ls .opencode/context/

# Should show:
# core/  openagents-repo/  navigation.md

Step 5: View Available Features

Get an overview of what OAC can do:

/oac:help

Expected output: A comprehensive guide showing:

6-stage workflow overview
Available skills and when to use them
Available subagents and their purposes
Available commands
Quick start examples

Take 2 minutes to skim this output — it's your reference guide.

Step 6: Test the Workflow

Let's test OAC with a simple task to ensure everything works.

Type this into Claude Code:

Add a hello world function to a new file called utils.ts

What should happen:

Stage 1: Analyze & Discover ``` I'll help you add a hello world function. Let me discover relevant context first.

Invoking /context-discovery to find coding standards...


2. **Stage 2: Plan & Approve**

Plan:

Create src/utils.ts
Add helloWorld() function
Follow TypeScript standards from context

Files to create:

src/utils.ts

May I proceed with this plan? (yes/no)

   
   **Type**: `yes`

3. **Stage 3: LoadContext**

Loading context files... ✓ Read .opencode/context/core/standards/typescript.md ✓ Read .opencode/context/core/standards/code-quality.md


4. **Stage 4: Execute**

Creating src/utils.ts... ✓ File created with helloWorld() function


5. **Stage 5: Validate**

Validating implementation... ✓ TypeScript syntax valid ✓ Follows coding standards ✓ No anti-patterns detected


6. **Stage 6: Complete**

✅ Task completed successfully!

Summary:

Created src/utils.ts
Added helloWorld() function
Follows TypeScript standards ```

✅ Success indicator: You should see all 6 stages complete without errors.

🎓 Understanding the 6-Stage Workflow

Every task in OAC follows this workflow:

┌─────────────────────────────────────────────────────────────┐
│ Stage 1: Analyze & Discover                                 │
│ - Understand what you're asking for                         │
│ - Find relevant context files (standards, patterns)         │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Stage 2: Plan & Approve                                     │
│ - Present implementation plan                               │
│ - REQUEST APPROVAL before proceeding                        │
│ - Confirm approach with you                                 │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Stage 3: LoadContext                                        │
│ - Read all discovered context files                         │
│ - Load coding standards, security patterns                  │
│ - Pre-load everything needed for execution                  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Stage 4: Execute                                            │
│ - Simple tasks (1-3 files): Direct implementation           │
│ - Complex tasks (4+ files): Break down 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                                            │
└─────────────────────────────────────────────────────────────┘

Key points:

Approval gate at Stage 2 — You control what gets implemented
Context loaded upfront — Ensures consistent, high-quality code
Validation before completion — Catches issues early
Automatic for every task — You don't need to invoke it manually

🎯 What's Next?

Now that OAC is set up, you can:

1. Start Building Features

Just describe what you want to build:

Build a user authentication system with JWT tokens

OAC will:

Discover relevant security patterns
Break down into subtasks (if complex)
Implement following best practices
Generate tests
Review code quality

2. Explore Advanced Features

Context Manager — Set up project-specific configuration:

/context-manager

Parallel Execution — Speed up multi-component features:

# Automatically used when tasks are independent
# Example: Frontend + Backend + Tests run simultaneously

External Scout — Fetch current library documentation:

/external-scout drizzle schemas
/external-scout react hooks

3. Learn the Skills

Each skill has a specific purpose:

Skill	When to Use
`/using-oac`	Auto-invoked for every task
`/context-discovery`	Find relevant standards and patterns
`/external-scout`	Get current library documentation
`/task-breakdown`	Break down complex features
`/code-execution`	Implement features
`/test-generation`	Create comprehensive tests
`/code-review`	Review code quality
`/context-manager`	Set up projects and configuration
`/parallel-execution`	Execute independent tasks simultaneously

4. Read the Documentation

Quick Start: QUICK-START.md — Usage examples and workflows
Installation: INSTALL.md — Detailed installation guide
Full README: README.md — Complete system overview

🆘 Troubleshooting

Issue: Plugin not found

Symptom: /oac:status returns "command not found"

Solution:

# Check plugin list
/plugin list

# Should show "oac" in the list
# If not, reinstall:
/plugin install oac

Issue: Context files not downloading

Symptom: /oac:setup --core fails or times out

Solution:

# Check internet connection
ping github.com

# Try again with verbose output
/oac:setup --core --verbose

# If still failing, check GitHub access
curl https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/README.md

Issue: Skills not working

Symptom: /context-discovery returns "skill not found"

Solution:

# Verify skill files exist
ls ~/.claude/plugins/cache/oac/skills/

# Should show 9 directories
# If missing, reinstall plugin
/plugin uninstall oac
/plugin install oac

Issue: Subagents not available

Symptom: Error when trying to invoke subagent

Solution:

# Check status
/oac:status

# Should show 6 subagents
# If missing, verify agent files
ls ~/.claude/plugins/cache/oac/agents/

# Should show 6 .md files
# If missing, reinstall plugin

Issue: Workflow not auto-starting

Symptom: Tasks don't automatically invoke /using-oac

Solution:

# Check hooks are installed
ls ~/.claude/plugins/cache/oac/hooks/

# Should show:
# - hooks.json
# - session-start.sh

# Restart Claude Code to reload hooks

Issue: Context files exist but not being used

Symptom: OAC says "context not found" but files exist

Solution:

# Verify context location
ls .opencode/context/core/standards/

# Should show multiple .md files

# Check manifest
cat plugins/claude-code/.context-manifest.json

# Should show version and file list

# If manifest missing, re-run setup
/oac:setup --core --force

✅ Success Checklist

Before you finish, verify:

/oac:status shows "Plugin Version: 1.0.0"
/oac:status shows "Context Files: ✅ Installed"
/oac:status shows 6 subagents, 9 skills, 4 commands
.opencode/context/ directory exists with files
Test task completed successfully (hello world example)
You understand the 6-stage workflow
You know where to find help (/oac:help)

All checked? 🎉 You're ready to build with OAC!

📚 Additional Resources

Quick Reference

Command	Purpose
`/oac:status`	Check installation status
`/oac:help`	View comprehensive help
`/oac:setup --core`	Download context files
`/oac:cleanup`	Clean up old temporary files

Documentation

This guide: First-time setup (you are here)
QUICK-START.md: Usage examples and workflows
INSTALL.md: Detailed installation guide
README.md: Complete system overview

Support

Issues: https://github.com/darrenhinde/OpenAgentsControl/issues
Discussions: https://github.com/darrenhinde/OpenAgentsControl/discussions
Status Check: Run /oac:status for diagnostic information

🎉 Welcome to OAC!

You're now ready to build high-quality, context-aware code with OpenAgents Control.

Remember:

OAC automatically guides you through the 6-stage workflow
Approval gates keep you in control
Context files ensure consistent, high-quality code
Skills and subagents handle the complexity

Happy coding! 🚀

Version: 1.0.0
Last Updated: 2026-02-16
Status: Production Ready

FIRST-TIME-SETUP.md 15 KB History Raw

OAC Plugin - First-Time Setup Guide

🎯 What You'll Accomplish

📋 Prerequisites

🚀 Step-by-Step Setup

Step 1: Install the Plugin

Option A: From GitHub Marketplace (Recommended)

Option B: Local Development

Step 2: Verify Installation

Step 3: Download Context Files

Option A: Core Context Only (Recommended for First-Time Users)

Option B: All Context (For Advanced Users)

Step 4: Verify Context Installation

Step 5: View Available Features

Step 6: Test the Workflow

🎓 Understanding the 6-Stage Workflow

🎯 What's Next?

1. Start Building Features

2. Explore Advanced Features

3. Learn the Skills

4. Read the Documentation

🆘 Troubleshooting

Issue: Plugin not found

Issue: Context files not downloading

Issue: Skills not working

Issue: Subagents not available

Issue: Workflow not auto-starting

Issue: Context files exist but not being used

✅ Success Checklist

📚 Additional Resources

Quick Reference

Documentation

Support

🎉 Welcome to OAC!

FIRST-TIME-SETUP.md 15 KB

History Raw