Home Explore Help
Sign In
logic855
/
OpenAgentsControl
mirror of https://github.com/darrenhinde/OpenAgentsControl.git
1
0
Fork 0
Files Issues 0 Wiki
Branch: chore/version-bump-20260216-181517
Branches Tags
OpenAgentsContr...
/
plugins
/
claude-code
/
QUICK-START.md

QUICK-START.md 14 KB
Permalink History Raw

OAC Plugin - Quick Start Guide

Version: 1.0.0
Date: 2026-02-16
Status: ✅ Production Ready

🚀 Getting Started (3 Steps)

1. Install the Plugin

# From GitHub marketplace
/plugin marketplace add darrenhinde/OpenAgentsControl
/plugin install oac

# OR for local development
claude --plugin-dir ./plugins/claude-code

2. Download Context Files

# Download core context (recommended)
/oac:setup --core

# OR download everything
/oac:setup --all

3. Verify Installation

# Check status
/oac:status

# View help
/oac:help

You're ready! Start any development task and the /using-oac skill will automatically guide you.

📋 Quick Reference: 9 Skills

1. /using-oac - Main Workflow Orchestrator

Auto-invoked on every task to ensure context-aware development.

6-Stage Workflow:

  1. Analyze & Discover - Understand task, find context files
  2. Plan & Approve - Present plan, REQUEST APPROVAL
  3. LoadContext - Pre-load all context files (internal + external)
  4. Execute - Implement (direct or via task breakdown)
  5. Validate - Run tests, STOP on failure
  6. Complete - Update docs, summarize

When to use: Automatically invoked (you don't need to call it manually).

2. /context-discovery - Find Relevant Context

Guides the main agent to use the context-scout subagent for discovering standards and patterns.

Usage:

/context-discovery authentication feature

What it does:

  • Searches .opencode/context/ for relevant files
  • Prioritizes by relevance (Critical → High → Medium)
  • Returns list of files to load

Example output:

Critical:
- .opencode/context/core/standards/security.md
- .opencode/context/core/patterns/authentication.md

High:
- .opencode/context/core/standards/typescript.md

3. /external-scout - Fetch External Library Docs

Guides the main agent to use the external-scout subagent for fetching current API documentation.

Usage:

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

What it does:

  • Fetches current documentation from Context7 and other sources
  • Caches results in .tmp/external-context/ (fresh for 7 days)
  • Returns file paths to load
  • Ensures you're using current API patterns (not outdated training data)

Example output:

{
  "status": "success",
  "package": "drizzle",
  "topic": "schemas",
  "files": [".tmp/external-context/drizzle/schemas.md"],
  "message": "Documentation cached. Load file to access current API patterns."
}

Why it matters: Training data is outdated. External libraries change their APIs, deprecate features, and introduce new patterns. ExternalScout ensures you're implementing with current, correct patterns.

4. /task-breakdown - Decompose Complex Features

Guides the main agent to use the task-manager subagent for breaking down complex tasks.

Usage:

/task-breakdown user authentication system

What it does:

  • Breaks feature into atomic subtasks (1-2 hours each)
  • Creates dependency graph
  • Generates subtask JSON files in .tmp/tasks/
  • Enables parallel execution where possible

Example output:

Subtasks created:
1. JWT service implementation
2. Auth middleware (depends on #1)
3. Login endpoint (depends on #1, #2)
4. Refresh token logic (depends on #1)
5. Integration tests (depends on all)

5. /code-execution - Implement Features

Guides the main agent to use the coder-agent subagent for implementing code.

Usage:

/code-execution implement JWT service

What it does:

  • Implements features following loaded context
  • Applies coding standards and patterns
  • Runs self-review before completion
  • Updates subtask status if part of task breakdown

Self-Review Checks:

  • ✅ Type & import validation
  • ✅ Anti-pattern scan (console.log, TODO, hardcoded secrets)
  • ✅ Acceptance criteria verification
  • ✅ External library verification

6. /test-generation - Create Comprehensive Tests

Guides the main agent to use the test-engineer subagent for generating tests.

Usage:

/test-generation authentication service

What it does:

  • Generates tests following TDD principles
  • Covers happy paths, edge cases, error handling
  • Follows test standards from context
  • Ensures test isolation and clarity

Test Coverage:

  • Unit tests for individual functions
  • Integration tests for workflows
  • Edge cases and error scenarios
  • Security validation tests

7. /code-review - Review Code Quality

Guides the main agent to use the code-reviewer subagent for reviewing code.

Usage:

/code-review src/auth/

What it does:

  • Reviews code for quality and standards compliance
  • Checks security patterns
  • Identifies anti-patterns
  • Suggests improvements

Review Areas:

  • Code quality and readability
  • Security vulnerabilities
  • Performance issues
  • Standards compliance
  • Test coverage

8. /context-manager - Manage Context & Configuration

Manage context files, configuration, and project-specific settings.

Usage:

/context-manager

What it does:

  • Set up new projects with OAC context files
  • Configure context sources and download preferences
  • Integrate external task systems (SpecKit, Linear, Jira, custom)
  • Manage personal context files and templates
  • Troubleshoot context loading or configuration issues
  • Update or refresh downloaded context files

Use when:

  • Setting up a new project
  • Configuring .oac file
  • Integrating with external task management
  • Managing personal templates and preferences

9. /parallel-execution - Execute Tasks in Parallel

Execute multiple independent tasks simultaneously to reduce implementation time.

Usage:

# Automatically used when task-manager marks tasks with parallel:true
# Or invoke manually for independent work

What it does:

  • Execute multiple independent tasks simultaneously
  • Dramatically reduce implementation time for multi-component features
  • Coordinate parallel work streams (frontend + backend + tests)
  • Monitor progress and handle failures gracefully

Use when:

  • Multiple independent tasks with no dependencies
  • Multi-component features (frontend + backend + tests)
  • Time-sensitive delivery
  • Batch operations (converting files, running tests)

Time savings: 50-80% reduction for multi-component features

🎮 Quick Reference: 4 Commands

1. /oac:setup - Download Context Files

Usage:

/oac:setup                    # Interactive mode
/oac:setup --core             # Core context only (~50 files)
/oac:setup --all              # All context (~200 files)
/oac:setup --category=standards  # Specific category

What it downloads:

  • Coding standards and conventions
  • Architecture patterns
  • Security guidelines
  • Workflow guides
  • Domain-specific documentation

Output: Creates .opencode/context/ and .context-manifest.json

2. /oac:help - Show Usage Guide

Usage:

/oac:help                     # General help
/oac:help context-discovery   # Skill-specific help

What it shows:

  • 6-stage workflow overview
  • Available subagents and when to use them
  • Available skills and usage examples
  • Available commands
  • Quick start examples
  • Troubleshooting guide

3. /oac:status - Check Installation Status

Usage:

/oac:status

What it shows:

  • Plugin version
  • Context installation status
  • Active sessions count
  • Available subagents (6)
  • Available skills (9)
  • Available commands (4)
  • Recommendations for cleanup or setup

4. /oac:cleanup - Clean Up Temporary Files

Usage:

/oac:cleanup                          # Interactive mode
/oac:cleanup --force                  # Skip confirmation
/oac:cleanup --session-days=3         # Clean sessions older than 3 days
/oac:cleanup --task-days=14           # Clean tasks older than 14 days
/oac:cleanup --external-days=3        # Clean external context older than 3 days

What it cleans:

  • Old session files from .tmp/sessions/
  • Completed task files from .tmp/tasks/
  • Cached external documentation from .tmp/external-context/

Default retention:

  • Sessions: 7 days
  • Completed tasks: 30 days
  • External context: 7 days

Example:

# Clean with defaults
/oac:cleanup

# Aggressive cleanup
/oac:cleanup --session-days=3 --task-days=14 --external-days=3 --force

💡 Example Workflows

Example 1: Simple Feature (Direct Implementation)

Task: "Add a login endpoint"

Workflow:

1. Analyze & Discover
   - Understand: Need POST /api/login endpoint
   - Invoke /context-discovery → finds API standards, security patterns

2. Plan & Approve
   - Plan: Create endpoint in src/api/auth.ts
   - Files: auth.ts, auth.test.ts, api-docs.md
   - REQUEST APPROVAL ← User approves

3. LoadContext
   - Read API standards
   - Read security patterns
   - Read TypeScript conventions
   - (If using external libs) Invoke /external-scout for current API docs

4. Execute
   - Implement endpoint directly (simple task)
   - Follow loaded standards

5. Validate
   - Run tests
   - Verify acceptance criteria

6. Complete
   - Update API docs
   - Summarize changes

Time: ~15-30 minutes

Example 2: Complex Feature (Task Breakdown)

Task: "Build a complete authentication system"

Workflow:

1. Analyze & Discover
   - Understand: Full auth system (JWT, refresh, middleware, endpoints)
   - Invoke /context-discovery → finds security, API, TypeScript standards

2. Plan & Approve
   - Plan: Multi-component system, suggest task breakdown
   - Complexity: 4+ files, >30 min
   - REQUEST APPROVAL ← User approves

3. LoadContext
   - Read security patterns
   - Read API standards
   - Read TypeScript conventions
   - Read test standards
   - Invoke /external-scout for any external libraries (e.g., JWT library, database ORM)

4. Execute
   - Invoke /task-breakdown → creates subtasks:
     * Subtask 1: JWT service (core logic)
     * Subtask 2: Auth middleware (depends on #1)
     * Subtask 3: Login endpoint (depends on #1, #2)
     * Subtask 4: Refresh endpoint (depends on #1)
     * Subtask 5: Integration tests (depends on all)
   
   - For each subtask:
     * Invoke /code-execution
     * Implement following loaded context
     * Run self-review
     * Mark subtask complete

5. Validate
   - Run all integration tests
   - Verify system works end-to-end
   - STOP if any test fails

6. Complete
   - Update API documentation
   - Update security documentation
   - Summarize all changes

Time: ~2-4 hours (broken into 1-2 hour subtasks)

Example 3: Using Subagents Directly

Task: "Review and test the authentication system"

Workflow:

# Step 1: Discover context
Use the context-scout subagent to find:
- Security review checklists
- Test standards
- Code quality guidelines

# Step 2: Review code
Use the code-reviewer subagent to review:
- src/auth/ directory
- Check security patterns
- Identify issues

# Step 3: Generate tests
Use the test-engineer subagent to create:
- Unit tests for JWT service
- Integration tests for auth flow
- Security validation tests

# Step 4: Verify
Run tests and confirm all pass

🏗️ Architecture: Flattened Delegation

OAC for Claude Code uses a flattened hierarchy (no nested subagent calls):

❌ Traditional OAC (Not Allowed in Claude Code)

Main Agent
  └─> TaskManager
       └─> CoderAgent
            └─> ContextScout (nested - not allowed)

✅ Claude Code OAC (Flattened)

Main Agent (orchestrated by /using-oac skill)
  ├─> task-manager subagent
  ├─> context-scout subagent
  ├─> coder-agent subagent
  ├─> test-engineer subagent
  └─> code-reviewer subagent

How it works:

  1. Skills guide the main agent's workflow (when to invoke which subagent)
  2. Main agent invokes subagents directly (no nesting)
  3. Context is pre-loaded in Stage 3 (no nested ContextScout calls during execution)
  4. Subagents return results to main agent for orchestration

🆘 Troubleshooting

"Context files not found"

# Download context
/oac:setup --core

# Verify installation
/oac:status

"Subagent not available"

# Check status
/oac:status

# Should show 6 subagents
# If missing, reinstall plugin

"Approval not requested"

# This is a bug - OAC should ALWAYS request approval in Stage 2
# Please report at: https://github.com/darrenhinde/OpenAgentsControl/issues

"Nested subagent call error"

# Claude Code doesn't support nested calls
# Use skills to orchestrate, not subagents calling subagents
# The /using-oac skill handles this automatically

"Tests failing in Stage 5"

# This is expected behavior - OAC stops on test failure
# Fix the failing tests before proceeding
# Re-run validation after fixes

🎯 Best Practices

1. Context First, Code Second

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

2. Approve Before Execution

Review the plan in Stage 2 carefully. Once approved, OAC will execute automatically.

3. Break Down Complex Tasks

For features with 4+ files or >30 min work, use task breakdown for better tracking and parallel execution.

4. Trust the Self-Review

CoderAgent runs comprehensive checks before completion. If it passes, the code is ready.

5. Use Status Commands

Run /oac:status regularly to check installation and active sessions.

📚 Learn More

  • Installation: See INSTALL.md for detailed setup
  • Full Help: Run /oac:help for comprehensive guide
  • Architecture: See README.md for system overview
  • Context Files: Explore .opencode/context/ after running /oac:setup

🔗 Quick Links

Resource Command/Link
Check Status /oac:status
Get Help /oac:help
Download Context /oac:setup --core
GitHub Issues https://github.com/darrenhinde/OpenAgentsControl/issues
Discussions https://github.com/darrenhinde/OpenAgentsControl/discussions

Ready to build! 🎉

Start any development task and let the /using-oac skill guide you through context-aware development.