OpenWriterControle/plugins/claude-code/FIRST-TIME-SETUP.md

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:

1. 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