⚡ Ability Control

Intent-driven orchestration for AI agents - Detects user intent patterns, injects context into Claude's messages, and executes custom workflows.

---

What is Ability Control?

Ability Control is an OpenCode plugin that automatically detects user intent and guides Claude's behavior through abilities - reusable patterns that inject context, suggest tools, and enforce constraints.

Key Features

• 🎯 Intent Detection - Automatically detects user intent from message patterns
• 💉 Context Injection - Injects ability context into Claude's system prompt
• 🔧 Tool Suggestions - Recommends specific tools for each ability
• 🛡️ Constraints - Enforces rules and best practices
• 📦 Custom Abilities - Create your own abilities with simple YAML files
• 🎨 Interactive CLI - Setup wizard like shadcn/ui

---

Installation

1. Install the Plugin

cd .opencode
npm install ability-control

2. Run Interactive Setup

npx ability-control init

This creates:

.opencode/ability-control/
├── config.json              # Configuration
├── abilities/               # Your custom abilities
├── handlers/                # TypeScript handlers (future)
└── schemas/                 # Validation schemas (future)

3. Register the Plugin

Add to .opencode/opencode.json:

{
  "plugin": ["ability-control"]
}

4. Restart OpenCode

The plugin will load automatically and show a toast notification with loaded abilities.

---

Quick Start

Built-in Abilities

Ability Control comes with example abilities:

• cookie-helper - Detects baking/cookie mentions, provides baking tips
• explore-codebase - Detects codebase exploration requests, suggests tools

Try it:

Type: "I want to bake cookies"
Result: ⚡ Ability Activated: cookie-helper

Create Your First Custom Ability

Create .opencode/ability-control/abilities/my-ability.ability.yaml:

name: my-ability
version: 1.0.0
description: My custom ability

triggers:
  - pattern: "(my trigger|my phrase)"
    confidence: 0.9

context:
  hints:
    - What this ability does
    - Key information for Claude
  
  tools:
    - name: bash
      description: Run commands
    - name: read
      description: Read files
  
  constraints:
    - Keep responses professional
    - Always explain your reasoning

Restart OpenCode and type "my trigger" - your ability will activate!

---

Configuration

Edit .opencode/ability-control/config.json:

Enable/Disable Built-in Abilities

{
  "builtInAbilities": {
    "cookie-helper": false,      // Disable this
    "explore-codebase": true     // Keep this
  }
}

Add Custom Ability Directories

{
  "abilityDirectories": [
    "abilities",                  // Default: .opencode/ability-control/abilities/
    "~/shared-abilities",         // Home directory
    "/absolute/path/abilities"    // Absolute path
  ]
}

Configure Logging

{
  "logging": {
    "level": "info",              // debug | info | warn | error
    "directory": ".tmp/ability-control"
  }
}

---

Ability YAML Format

name: ability-name
version: 1.0.0
description: What this ability does

# Trigger patterns (regex supported)
triggers:
  - pattern: "(keyword|phrase)"
    confidence: 0.9              # 0.0 - 1.0
    examples:
      - "Example user message"

# Context injected into Claude's system prompt
context:
  hints:
    - "Key information for Claude"
    - "What to focus on"
  
  tools:
    - name: bash
      description: "When to use this tool"
    - name: read
      description: "When to use this tool"
  
  constraints:
    - "Rules to follow"
    - "Things to avoid"

# Optional: Handler execution (future)
handler:
  file: handlers/my-handler.ts
  function: execute

# Optional: Input validation (future)
validation:
  schema: schemas/my-schema.ts

---

How It Works

1. Pattern Detection

When you send a message, Ability Control checks all ability patterns:

User: "I want to bake cookies"
Match: cookie-helper (pattern: "(cookie|bake|baking)")
Confidence: 95%

2. Context Injection

The ability's context is injected into Claude's system prompt:

# ⚡ Active Ability: cookie-helper

## Context Hints
- User is interested in baking or cookies
- Provide helpful baking tips and measurements

## Available Tools
- search: Search for cookie recipes online
- read: Read recipe files if they exist

## Constraints
- Keep responses fun and encouraging
- Include temperature and timing information

3. Claude Responds

Claude sees the ability context and responds accordingly, using suggested tools and following constraints.

---

CLI Commands

npx ability-control init

Interactive setup wizard - creates config directory and example abilities.

npx ability-control init

Future Commands (Coming Soon)

npx ability-control add <name>           # Create new ability
npx ability-control list                 # Show all abilities
npx ability-control enable <name>        # Enable ability
npx ability-control disable <name>       # Disable ability
npx ability-control validate             # Validate YAML syntax

---

Examples

Example 1: Code Review Ability

name: code-review
description: Triggers when user requests code review

triggers:
  - pattern: "(review|check) (this|my) code"
    confidence: 0.85

context:
  hints:
    - User wants a thorough code review
    - Check for bugs, performance, and best practices
  
  tools:
    - name: read
      description: Read the code files
    - name: grep
      description: Search for patterns
  
  constraints:
    - Be constructive and specific
    - Suggest improvements with examples
    - Highlight security issues

Example 2: Database Query Ability

name: database-query
description: Helps with database queries

triggers:
  - pattern: "(database|db|sql) (query|select|insert)"
    confidence: 0.9

context:
  hints:
    - User needs help with database operations
    - Check for SQL injection vulnerabilities
  
  tools:
    - name: bash
      description: Run database commands
    - name: read
      description: Read schema files
  
  constraints:
    - Always use parameterized queries
    - Explain the query before executing
    - Warn about destructive operations

---

Roadmap

Phase 1: Context Injection ✅ (Current)

• Pattern detection
• Context injection
• Configuration system
• CLI setup wizard

Phase 2: Handler Execution ⏳ (Next)

• Execute TypeScript functions when abilities trigger
• Pass context (client, logger, input)
• Return results to Claude

Phase 3: Input Validation ⏳

• Validate user inputs with Zod schemas
• Extract data from patterns (regex capture groups)
• Type-safe validation

Phase 4: Multi-Step Workflows ⏳

• Sequential steps with dependencies
• Error handling and rollback
• User confirmations

---

Debugging

View Logs

tail -f .tmp/ability-control/*.log

Check Loaded Abilities

Look for these log entries:

[INFO] ✅ Built-in abilities loaded: 2
[INFO] ✅ Custom abilities loaded: 1
[INFO] ✅ Loaded 3 abilities

Test Pattern Matching

[DEBUG] Pattern matching results
[INFO] 🎯 ABILITY DETECTED: cookie-helper (confidence: 0.95)

---

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests (when available)
5. Submit a pull request

---

License

MIT © Darren Hinde

---

Documentation

📚 Complete Documentation

• Vision & Design - Original vision and evolution
• Architecture - System design and principles
• Safety - Comprehensive safety mechanisms
• Checklist - Implementation roadmap
• Plugin Development - Plugin development guide

---

Links

• GitHub: https://github.com/darrenhinde/ability-control
• Issues: https://github.com/darrenhinde/ability-control/issues
• OpenCode: https://opencode.ai
• Documentation: docs/

---

Support

• 📖 Documentation
• 🐛 Report Bug
• 💡 Request Feature

---

Made with ⚡ for OpenCode