OpenAgentsControl/packages/plugin-abilities/MINIMAL_TEST.md

Minimal Abilities Plugin - Test Guide

What Was Simplified

This is a bare minimum version to test the core concept:

✅ KEPT

• Script step execution
• Sequential step ordering (with needs dependencies)
• Tool blocking during execution (enforcement)
• Context injection into chat messages
• Input validation
• Single execution tracking

❌ REMOVED

• plugin.ts (duplicate implementation)
• sdk.ts (not needed for testing)
• Agent/skill/approval/workflow step types
• Session tracking and multi-session support
• Agent attachment
• Triggers and auto-detection
• Cleanup timers
• Toast notifications
• Context passing between steps
• Conditional execution (when)

File Structure

src/
  types/index.ts              (~120 lines - minimal types)
  loader/index.ts             (unchanged - already simple)
  validator/index.ts          (unchanged - already simple)
  executor/
    index.ts                  (~240 lines - script steps only)
    execution-manager.ts      (~50 lines - single execution)
  opencode-plugin.ts          (~200 lines - minimal hooks)
  index.ts                    (exports)

examples/
  test/ability.yaml           (3-step test ability)

Total: ~600 lines (down from ~2000+)

Testing the Core Concept

Setup

1. Create test ability directory:

   mkdir -p .opencode/abilities
   cp examples/test/ability.yaml .opencode/abilities/
   

2. Configure OpenCode to use plugin:

   // .opencode/opencode.json
   {
    "plugin": [
      "file://./packages/plugin-abilities/src/opencode-plugin.ts"
    ]
   }
   

Test 1: Basic Execution

Goal: Verify steps execute sequentially

User: ability.run({ name: "test" })

Expected:
✅ Step 1 executes
✅ Step 2 executes (after step 1)
✅ Step 3 executes (after step 2)
✅ Status = completed

Test 2: Tool Blocking (CRITICAL)

Goal: Verify tools are blocked during script execution

User: ability.run({ name: "test" })

[While step 1 is running]
User: bash({ command: "ls" })

Expected:
❌ Error: Tool 'bash' blocked during script step 'step1'

Test 3: Context Injection

Goal: Verify ability context appears in chat

User: ability.run({ name: "test" })

[Send any message while running]
User: What's happening?

Expected:
🔄 Active Ability: test
Progress: 1/3 steps completed
Current Step: step2
⚠️ ENFORCEMENT ACTIVE

Test 4: Status Check

Goal: Verify status tool works

User: ability.run({ name: "test" })
User: ability.status()

Expected:
{
  "status": "running",
  "ability": "test",
  "currentStep": "step2",
  "progress": "1/3"
}

Test 5: Input Validation

Goal: Verify inputs are validated

User: ability.run({ name: "test", inputs: { message: "Custom message" } })

Expected:
✅ Step 1 output contains "Custom message"

Success Criteria

All 5 tests pass = Core concept proven

Then you can add back:

• Agent steps
• Skill steps
• Session management
• Context passing
• Triggers
• etc.

Quick Validation

# Build
cd packages/plugin-abilities
bun run build

# Run minimal test (if you have test runner)
bun test tests/minimal.test.ts

What This Proves

1. Hook-based enforcement works - Tools can be blocked
2. Context injection works - AI sees ability state
3. Sequential execution works - Steps run in order
4. State tracking works - ExecutionManager tracks progress

If these 4 things work, the architecture is sound.

Next Steps After Validation

1. Add agent steps (call other agents)
2. Add session scoping (multi-user support)
3. Add context passing (step outputs → next step inputs)
4. Add triggers (auto-detect abilities from keywords)
5. Add approval steps (human-in-the-loop)
6. Add workflow steps (nested abilities)

But test the minimal version first before adding complexity.