fix(plugin): register skills/commands in plugin.json and harden plugin-abilities (#285, #281)

- Add skills (12) and commands (6) arrays to plugin.json so Claude Code
  discovers them (#281)
- Fix external-scout → external-research naming throughout README
- Add explicit name: frontmatter to 3 command files
- Expand plugin-abilities types to cover all 5 step types (agent, skill,
  approval, workflow, script) with full Ability and ExecutorContext definitions
- Rewrite executor to handle all step types with shell-escape interpolation
  to prevent command injection, prototype pollution guards, abort signal
  for cancellation, step output forwarding, and conditional execution
- Add cancelActive/onSessionDeleted/get/list to ExecutionManager
- Add null safety in plugin.ts getStepInstructions, clear stale state on
  re-initialize, remove redundant type casts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

packages/plugin-abilities/bun.lock

@@ -1,5 +1,6 @@
 {
   "lockfileVersion": 1,
+  "configVersion": 0,
   "workspaces": {
     "": {
       "name": "@openagents/plugin-abilities",

packages/plugin-abilities/src/executor/execution-manager.ts

@@ -11,6 +11,9 @@ import { executeAbility } from './index.js'
  */
 export class ExecutionManager {
   private activeExecution: AbilityExecution | null = null
+  private executionHistory: AbilityExecution[] = []
+  private maxHistory = 50
+  private abortController: AbortController | null = null
 
   async execute(
     ability: Ability,
@@ -23,10 +26,17 @@ export class ExecutionManager {
     }
 
     console.log(`[abilities] Starting execution: ${ability.name}`)
-    
-    const execution = await executeAbility(ability, inputs, ctx)
+
+    this.abortController = new AbortController()
+    const execution = await executeAbility(ability, inputs, ctx, this.abortController.signal)
     this.activeExecution = execution
 
+    // Track in history
+    this.executionHistory.push(execution)
+    if (this.executionHistory.length > this.maxHistory) {
+      this.executionHistory = this.executionHistory.slice(-this.maxHistory)
+    }
+
     // Clear active if completed/failed
     if (execution.status !== 'running') {
       this.activeExecution = null
@@ -35,14 +45,25 @@ export class ExecutionManager {
     return execution
   }
 
+  get(id: string): AbilityExecution | undefined {
+    return this.executionHistory.find((e) => e.id === id)
+  }
+
+  list(): AbilityExecution[] {
+    return [...this.executionHistory]
+  }
+
   getActive(): AbilityExecution | null {
     return this.activeExecution
   }
 
   cancel(): boolean {
     if (!this.activeExecution) return false
-    
+
     if (this.activeExecution.status === 'running') {
+      // Signal the in-flight executeAbility loop to stop at the next iteration
+      this.abortController?.abort()
+      this.abortController = null
       this.activeExecution.status = 'failed'
       this.activeExecution.error = 'Cancelled by user'
       this.activeExecution.completedAt = Date.now()
@@ -53,6 +74,22 @@ export class ExecutionManager {
     return false
   }
 
+  cancelActive(): boolean {
+    // Signal the in-flight executeAbility loop to stop at the next iteration
+    this.abortController?.abort()
+    this.abortController = null
+    return this.cancel()
+  }
+
+  onSessionDeleted(sessionId: string): void {
+    if (this.activeExecution && this.activeExecution.status === 'running') {
+      this.activeExecution.status = 'failed'
+      this.activeExecution.error = `Session ${sessionId} deleted`
+      this.activeExecution.completedAt = Date.now()
+      this.activeExecution = null
+    }
+  }
+
   cleanup(): void {
     this.activeExecution = null
   }

packages/plugin-abilities/src/executor/index.ts

@@ -3,6 +3,10 @@ import type {
   Ability,
   Step,
   ScriptStep,
+  AgentStep,
+  SkillStep,
+  ApprovalStep,
+  WorkflowStep,
   AbilityExecution,
   StepResult,
   ExecutorContext,
@@ -11,25 +15,83 @@ import type {
 import { validateInputs } from '../validator/index.js'
 
 /**
- * Minimal Executor - Script Steps Only
- * 
- * Stripped down to prove core concept:
- * - Execute shell commands sequentially
- * - Track step results
- * - Validate exit codes
- * 
- * NO: agent steps, skill steps, approval, workflows, context passing
+ * Executor - Handles all step types
+ *
+ * - script: Execute shell commands
+ * - agent: Delegate to agent via context
+ * - skill: Load skill via context
+ * - approval: Request user approval via context
+ * - workflow: Delegate to nested ability (not yet implemented)
  */
 
 function generateExecutionId(): string {
   return `exec_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
 }
 
-function interpolateVariables(text: string, inputs: InputValues): string {
-  return text.replace(/\{\{inputs\.(\w+)\}\}/g, (match, name) => {
+const MAX_CONTEXT_LENGTH = 50000
+
+function interpolateVariables(text: string, inputs: InputValues, stepOutputs?: Map<string, string>): string {
+  let result = text.replace(/\{\{inputs\.(\w+)\}\}/g, (match, name) => {
     const value = inputs[name]
     return value !== undefined ? String(value) : match
   })
+
+  if (stepOutputs) {
+    result = result.replace(/\{\{steps\.(\w[\w-]*)\.output\}\}/g, (match, stepId) => {
+      const output = stepOutputs.get(stepId)
+      return output !== undefined ? output.trim() : match
+    })
+  }
+
+  return result
+}
+
+/**
+ * Wraps a value in single quotes and escapes any existing single quotes so
+ * the result is safe to embed directly in a POSIX shell command string.
+ * Prevents command injection when user-supplied inputs are interpolated into
+ * `sh -c` commands.
+ */
+function shellEscape(value: string): string {
+  // Replace every ' with '"'"' (close quote, escaped quote, reopen quote)
+  return "'" + value.replace(/'/g, "'\\''") + "'"
+}
+
+/**
+ * Like `interpolateVariables` but shell-escapes every substituted value so
+ * the resulting string is safe to pass to `sh -c`. Only used for script steps.
+ */
+function interpolateForShell(text: string, inputs: InputValues, stepOutputs?: Map<string, string>): string {
+  let result = text.replace(/\{\{inputs\.(\w+)\}\}/g, (match, name) => {
+    const value = inputs[name]
+    return value !== undefined ? shellEscape(String(value)) : match
+  })
+
+  if (stepOutputs) {
+    result = result.replace(/\{\{steps\.(\w[\w-]*)\.output\}\}/g, (match, stepId) => {
+      const output = stepOutputs.get(stepId)
+      // Step outputs are produced by our own scripts/agents, but escape them
+      // anyway to prevent injection when one step's output feeds another.
+      return output !== undefined ? shellEscape(output.trim()) : match
+    })
+  }
+
+  return result
+}
+
+function truncateOutput(output: string, maxLength: number = MAX_CONTEXT_LENGTH): string {
+  if (output.length <= maxLength) return output
+  const half = Math.floor(maxLength / 2)
+  const omitted = output.length - maxLength
+  return `${output.slice(0, half)}\n\n... [${omitted} characters truncated] ...\n\n${output.slice(-half)}`
+}
+
+function summarizeOutput(output: string): string {
+  const lines = output.split('\n')
+  if (lines.length <= 20) return output
+  const head = lines.slice(0, 10).join('\n')
+  const tail = lines.slice(-5).join('\n')
+  return `## Output Summary\n\n${head}\n\n... [${lines.length - 15} lines omitted] ...\n\n${tail}`
 }
 
 async function runScript(
@@ -39,7 +101,9 @@ async function runScript(
   return new Promise((resolve) => {
     const proc = spawn('sh', ['-c', command], {
       cwd: options.cwd || process.cwd(),
-      env: { ...process.env, ...options.env },
+      // Use Object.create(null) to prevent prototype pollution from a crafted
+      // __proto__ key that could appear in step.env or ctx.env.
+      env: Object.assign(Object.create(null), process.env, options.env),
     })
 
     let stdout = ''
@@ -66,18 +130,22 @@ async function runScript(
 async function executeScriptStep(
   step: ScriptStep,
   execution: AbilityExecution,
-  ctx: ExecutorContext
+  ctx: ExecutorContext,
+  stepOutputs: Map<string, string>
 ): Promise<StepResult> {
   const startedAt = Date.now()
 
-  const command = interpolateVariables(step.run, execution.inputs)
+  // Use shell-safe interpolation to prevent command injection via user inputs.
+  const command = interpolateForShell(step.run, execution.inputs, stepOutputs)
 
   console.log(`[abilities] Executing: ${command}`)
 
   try {
     const result = await runScript(command, {
       cwd: step.cwd || ctx.cwd,
-      env: { ...ctx.env, ...step.env },
+      // Object.create(null) prevents prototype pollution from a crafted
+      // __proto__ key in ctx.env or step.env.
+      env: Object.assign(Object.create(null), ctx.env, step.env),
     })
 
     // Validate exit code if specified
@@ -110,6 +178,166 @@ async function executeScriptStep(
   }
 }
 
+async function executeAgentStep(
+  step: AgentStep,
+  execution: AbilityExecution,
+  ctx: ExecutorContext,
+  stepOutputs: Map<string, string>
+): Promise<StepResult> {
+  const startedAt = Date.now()
+
+  if (!ctx.agents) {
+    return {
+      stepId: step.id,
+      status: 'failed',
+      error: 'Agent execution not available in this context',
+      startedAt,
+      completedAt: Date.now(),
+      duration: Date.now() - startedAt,
+    }
+  }
+
+  try {
+    let prompt = interpolateVariables(step.prompt, execution.inputs, stepOutputs)
+
+    // Inject context from prior steps if this step has dependencies
+    if (step.needs && step.needs.length > 0) {
+      const priorOutputs = execution.completedSteps
+        .filter((r) => step.needs!.includes(r.stepId) && r.output)
+        .map((r) => {
+          let output = r.output!
+          // Check if the prior step requested summarization
+          const priorStep = execution.ability.steps.find((s) => s.id === r.stepId)
+          if (priorStep && priorStep.type === 'agent' && (priorStep as AgentStep).summarize) {
+            output = summarizeOutput(output)
+          } else {
+            output = truncateOutput(output)
+          }
+          return `### ${r.stepId}\n${output}`
+        })
+
+      if (priorOutputs.length > 0) {
+        prompt = `${prompt}\n\n## Context from prior steps\n\n${priorOutputs.join('\n\n')}`
+      }
+    }
+
+    const output = await ctx.agents.call({
+      agent: step.agent,
+      prompt,
+    })
+
+    return {
+      stepId: step.id,
+      status: 'completed',
+      output,
+      startedAt,
+      completedAt: Date.now(),
+      duration: Date.now() - startedAt,
+    }
+  } catch (err) {
+    return {
+      stepId: step.id,
+      status: 'failed',
+      error: err instanceof Error ? err.message : String(err),
+      startedAt,
+      completedAt: Date.now(),
+      duration: Date.now() - startedAt,
+    }
+  }
+}
+
+async function executeSkillStep(
+  step: SkillStep,
+  ctx: ExecutorContext
+): Promise<StepResult> {
+  const startedAt = Date.now()
+
+  if (!ctx.skills) {
+    return {
+      stepId: step.id,
+      status: 'failed',
+      error: 'Skill execution not available in this context',
+      startedAt,
+      completedAt: Date.now(),
+      duration: Date.now() - startedAt,
+    }
+  }
+
+  try {
+    const output = await ctx.skills.load(step.skill)
+
+    return {
+      stepId: step.id,
+      status: 'completed',
+      output,
+      startedAt,
+      completedAt: Date.now(),
+      duration: Date.now() - startedAt,
+    }
+  } catch (err) {
+    return {
+      stepId: step.id,
+      status: 'failed',
+      error: err instanceof Error ? err.message : String(err),
+      startedAt,
+      completedAt: Date.now(),
+      duration: Date.now() - startedAt,
+    }
+  }
+}
+
+async function executeApprovalStep(
+  step: ApprovalStep,
+  execution: AbilityExecution,
+  ctx: ExecutorContext
+): Promise<StepResult> {
+  const startedAt = Date.now()
+
+  if (!ctx.approval) {
+    return {
+      stepId: step.id,
+      status: 'failed',
+      error: 'Approval not available in this context',
+      startedAt,
+      completedAt: Date.now(),
+      duration: Date.now() - startedAt,
+    }
+  }
+
+  try {
+    const prompt = interpolateVariables(step.prompt, execution.inputs)
+    const approved = await ctx.approval.request({ prompt })
+
+    return {
+      stepId: step.id,
+      status: approved ? 'completed' : 'failed',
+      output: approved ? 'Approved' : 'Rejected',
+      startedAt,
+      completedAt: Date.now(),
+      duration: Date.now() - startedAt,
+    }
+  } catch (err) {
+    return {
+      stepId: step.id,
+      status: 'failed',
+      error: err instanceof Error ? err.message : String(err),
+      startedAt,
+      completedAt: Date.now(),
+      duration: Date.now() - startedAt,
+    }
+  }
+}
+
+function evaluateCondition(condition: string, inputs: InputValues, stepOutputs: Map<string, string>): boolean {
+  // Simple condition evaluator: "inputs.key == \"value\""
+  const match = condition.match(/^inputs\.(\w+)\s*==\s*"([^"]*)"$/)
+  if (match) {
+    const [, key, expected] = match
+    return String(inputs[key]) === expected
+  }
+  return true // default: condition met
+}
+
 function buildExecutionOrder(steps: Step[]): Step[] {
   const result: Step[] = []
   const completed = new Set<string>()
@@ -134,10 +362,106 @@ function buildExecutionOrder(steps: Step[]): Step[] {
   return result
 }
 
+async function executeWorkflowStep(
+  step: WorkflowStep,
+  execution: AbilityExecution,
+  ctx: ExecutorContext
+): Promise<StepResult> {
+  const startedAt = Date.now()
+
+  if (!ctx.abilities) {
+    return {
+      stepId: step.id,
+      status: 'failed',
+      error: 'Workflow execution not available in this context',
+      startedAt,
+      completedAt: Date.now(),
+      duration: Date.now() - startedAt,
+    }
+  }
+
+  const childAbility = ctx.abilities.get(step.workflow)
+  if (!childAbility) {
+    return {
+      stepId: step.id,
+      status: 'failed',
+      error: `Nested ability '${step.workflow}' not found`,
+      startedAt,
+      completedAt: Date.now(),
+      duration: Date.now() - startedAt,
+    }
+  }
+
+  try {
+    // Interpolate inputs if provided
+    const workflowInputs: Record<string, unknown> = {}
+    if (step.inputs) {
+      for (const [key, value] of Object.entries(step.inputs)) {
+        workflowInputs[key] = typeof value === 'string'
+          ? interpolateVariables(value, execution.inputs)
+          : value
+      }
+    }
+
+    const childExecution = await ctx.abilities.execute(childAbility, workflowInputs)
+
+    return {
+      stepId: step.id,
+      status: childExecution.status === 'completed' ? 'completed' : 'failed',
+      output: childExecution.status === 'completed'
+        ? `Nested ability '${step.workflow}' completed successfully`
+        : `Nested ability '${step.workflow}' failed: ${childExecution.error}`,
+      error: childExecution.status !== 'completed' ? childExecution.error : undefined,
+      startedAt,
+      completedAt: Date.now(),
+      duration: Date.now() - startedAt,
+    }
+  } catch (err) {
+    return {
+      stepId: step.id,
+      status: 'failed',
+      error: err instanceof Error ? err.message : String(err),
+      startedAt,
+      completedAt: Date.now(),
+      duration: Date.now() - startedAt,
+    }
+  }
+}
+
+async function executeStep(
+  step: Step,
+  execution: AbilityExecution,
+  ctx: ExecutorContext,
+  stepOutputs: Map<string, string>
+): Promise<StepResult> {
+  switch (step.type) {
+    case 'script':
+      return executeScriptStep(step, execution, ctx, stepOutputs)
+    case 'agent':
+      return executeAgentStep(step, execution, ctx, stepOutputs)
+    case 'skill':
+      return executeSkillStep(step, ctx)
+    case 'approval':
+      return executeApprovalStep(step, execution, ctx)
+    case 'workflow':
+      return executeWorkflowStep(step, execution, ctx)
+    default:
+      return {
+        stepId: step.id,
+        status: 'failed',
+        error: `Unknown step type: ${(step as { type: string }).type}`,
+        startedAt: Date.now(),
+        completedAt: Date.now(),
+        duration: 0,
+      }
+  }
+}
+
 export async function executeAbility(
   ability: Ability,
   inputs: InputValues,
-  ctx: ExecutorContext
+  ctx: ExecutorContext,
+  signal?: AbortSignal
 ): Promise<AbilityExecution> {
   // Validate inputs
   const inputErrors = validateInputs(ability, inputs)
@@ -169,6 +493,7 @@ export async function executeAbility(
 
   // Build execution order based on dependencies
   const orderedSteps = buildExecutionOrder(ability.steps)
+  const stepOutputs = new Map<string, string>()
 
   const execution: AbilityExecution = {
     id: generateExecutionId(),
@@ -188,18 +513,66 @@ export async function executeAbility(
     execution.currentStep = step
     execution.currentStepIndex = i
 
+    // Check for cancellation before starting each step
+    if (signal?.aborted) {
+      execution.status = 'failed'
+      execution.error = 'Cancelled'
+      execution.completedAt = Date.now()
+      return execution
+    }
+
+    // Evaluate condition if present
+    if (step.when) {
+      const conditionMet = evaluateCondition(step.when, resolvedInputs, stepOutputs)
+      if (!conditionMet) {
+        const skipped: StepResult = {
+          stepId: step.id,
+          status: 'skipped',
+          output: `Condition not met: ${step.when}`,
+          startedAt: Date.now(),
+          completedAt: Date.now(),
+          duration: 0,
+        }
+        execution.completedSteps.push(skipped)
+        execution.pendingSteps = execution.pendingSteps.filter((s) => s.id !== step.id)
+        continue
+      }
+    }
+
     console.log(`[abilities] Step ${i + 1}/${orderedSteps.length}: ${step.id}`)
 
-    const result = await executeScriptStep(step as ScriptStep, execution, ctx)
+    ctx.onStepStart?.(step)
+
+    const result = await executeStep(step, execution, ctx, stepOutputs)
     execution.completedSteps.push(result)
     execution.pendingSteps = execution.pendingSteps.filter((s) => s.id !== step.id)
 
+    if (result.output) {
+      stepOutputs.set(step.id, result.output)
+    }
+
     if (result.status === 'failed') {
+      ctx.onStepFail?.(step, new Error(result.error || 'Step failed'))
+
+      // Check on_failure policy
+      if (step.on_failure === 'continue') {
+        continue
+      }
+
+      if (step.on_failure === 'retry') {
+        console.warn(`[abilities] on_failure: retry not yet implemented for step '${step.id}', treating as stop`)
+      }
+      if (step.on_failure === 'ask') {
+        console.warn(`[abilities] on_failure: ask not yet implemented for step '${step.id}', treating as stop`)
+      }
+
       execution.status = 'failed'
       execution.error = result.error
       execution.completedAt = Date.now()
       return execution
     }
+
+    ctx.onStepComplete?.(step, result)
   }
 
   execution.status = 'completed'
@@ -223,7 +596,7 @@ export function formatExecutionResult(execution: AbilityExecution): string {
   lines.push('Steps:')
 
   for (const result of execution.completedSteps) {
-    const icon = result.status === 'completed' ? '✅' : '❌'
+    const icon = result.status === 'completed' ? '✅' : result.status === 'skipped' ? '⏭️' : '❌'
     const duration = result.duration ? ` (${(result.duration / 1000).toFixed(1)}s)` : ''
     lines.push(`  ${icon} ${result.stepId}${duration}`)
     if (result.error) {

packages/plugin-abilities/src/plugin.ts

@@ -1,4 +1,4 @@
-import type { Ability, LoadedAbility, ExecutorContext, AbilityExecution, Step, AgentStep, SkillStep, ApprovalStep, WorkflowStep } from './types/index.js'
+import type { Ability, LoadedAbility, ExecutorContext, AbilityExecution, Step } from './types/index.js'
 import { loadAbilities, listAbilities } from './loader/index.js'
 import { validateAbility, validateInputs } from './validator/index.js'
 import { executeAbility, formatExecutionResult } from './executor/index.js'
@@ -102,6 +102,8 @@ class AbilitiesPlugin {
   }
 
   async initialize(ctx: PluginContext, config: PluginConfig = {}): Promise<void> {
+    // Clear stale state so re-initialization doesn't accumulate abilities from prior runs
+    this.abilities.clear()
     this.ctx = ctx
     this.config = config
 
@@ -421,20 +423,25 @@ class AbilitiesPlugin {
       case 'script':
         return `**Action:** Script is executing. Wait for completion.`
       case 'agent': {
-        const agentStep = step as AgentStep
-        return `**Action:** Invoke agent "${agentStep.agent}" with the prompt:\n\`\`\`\n${agentStep.prompt}\n\`\`\``
+        // The switch on step.type narrows to AgentStep — no cast needed
+        const agentName = step.agent ?? 'unknown'
+        const prompt = step.prompt ?? ''
+        return `**Action:** Invoke agent "${agentName}" with the prompt:\n\`\`\`\n${prompt}\n\`\`\``
       }
       case 'skill': {
-        const skillStep = step as SkillStep
-        return `**Action:** Load and follow skill "${skillStep.skill}".`
+        // Narrowed to SkillStep
+        const skillName = step.skill ?? 'unknown'
+        return `**Action:** Load and follow skill "${skillName}".`
       }
       case 'approval': {
-        const approvalStep = step as ApprovalStep
-        return `**Action:** Request user approval:\n"${approvalStep.prompt}"`
+        // Narrowed to ApprovalStep
+        const prompt = step.prompt ?? ''
+        return `**Action:** Request user approval:\n"${prompt}"`
       }
       case 'workflow': {
-        const workflowStep = step as WorkflowStep
-        return `**Action:** Execute nested ability "${workflowStep.workflow}".`
+        // Narrowed to WorkflowStep
+        const workflowName = step.workflow ?? 'unknown'
+        return `**Action:** Execute nested ability "${workflowName}".`
       }
       default:
         return '**Action:** Complete the current step.'

packages/plugin-abilities/src/types/index.ts

@@ -1,43 +1,85 @@
 /**
- * Abilities System - Minimal Type Definitions
- * 
- * Stripped down to essentials for testing core concept:
- * - Script steps only
- * - Single execution tracking
- * - No session management
+ * Abilities System - Type Definitions
+ *
+ * Covers all step types (script, agent, skill, approval, workflow),
+ * full ability configuration, and extended executor context.
  */
 
 // ─────────────────────────────────────────────────────────────
 // INPUT TYPES
 // ─────────────────────────────────────────────────────────────
 
-export type InputType = 'string' | 'number' | 'boolean'
+export type InputType = 'string' | 'number' | 'boolean' | 'array' | 'object'
 
 export interface InputDefinition {
   type: InputType
   required?: boolean
   default?: unknown
   description?: string
+  pattern?: string
+  enum?: string[]
+  minLength?: number
+  maxLength?: number
+  min?: number
+  max?: number
 }
 
 export type InputValues = Record<string, unknown>
 
 // ─────────────────────────────────────────────────────────────
-// STEP TYPES (Script only for minimal version)
+// STEP TYPES
 // ─────────────────────────────────────────────────────────────
 
-export interface ScriptStep {
+export interface BaseStep {
   id: string
-  type: 'script'
   description?: string
-  run: string
   needs?: string[]
+  when?: string
+  timeout?: string
+  on_failure?: 'stop' | 'continue' | 'retry' | 'ask'
+  max_retries?: number
+}
+
+export interface ScriptStep extends BaseStep {
+  type: 'script'
+  run: string
+  cwd?: string
+  env?: Record<string, string>
   validation?: {
     exit_code?: number
+    stdout_contains?: string
+    stderr_contains?: string
+    file_exists?: string
   }
 }
 
-export type Step = ScriptStep
+export interface AgentStep extends BaseStep {
+  type: 'agent'
+  agent: string
+  prompt: string
+  context?: string[]
+  summarize?: boolean | string
+}
+
+export interface SkillStep extends BaseStep {
+  type: 'skill'
+  skill: string
+  inputs?: Record<string, unknown>
+}
+
+export interface ApprovalStep extends BaseStep {
+  type: 'approval'
+  prompt: string
+  options?: Array<{ label: string; value: string }>
+}
+
+export interface WorkflowStep extends BaseStep {
+  type: 'workflow'
+  workflow: string
+  inputs?: Record<string, unknown>
+}
+
+export type Step = ScriptStep | AgentStep | SkillStep | ApprovalStep | WorkflowStep
 
 // ─────────────────────────────────────────────────────────────
 // ABILITY DEFINITION
@@ -46,11 +88,30 @@ export type Step = ScriptStep
 export interface Ability {
   name: string
   description: string
+  version?: string
   inputs?: Record<string, InputDefinition>
   steps: Step[]
+  triggers?: {
+    keywords?: string[]
+    patterns?: string[]
+  }
+  settings?: {
+    timeout?: string
+    parallel?: boolean
+    enforcement?: 'strict' | 'normal' | 'loose'
+    approval?: 'plan' | 'checkpoint' | 'none'
+    on_failure?: 'stop' | 'continue' | 'retry' | 'ask'
+  }
+  hooks?: {
+    before?: string[]
+    after?: string[]
+  }
+  compatible_agents?: string[]
+  exclusive_agent?: string
   _meta?: {
     filePath: string
     directory: string
+    loadedAt?: number
   }
 }
 
@@ -92,11 +153,13 @@ export interface AbilityExecution {
 export interface ValidationError {
   path: string
   message: string
+  code?: string
 }
 
 export interface ValidationResult {
   valid: boolean
   errors: ValidationError[]
+  ability?: Ability
 }
 
 // ─────────────────────────────────────────────────────────────
@@ -105,6 +168,7 @@ export interface ValidationResult {
 
 export interface LoaderOptions {
   projectDir?: string
+  globalDir?: string
   includeGlobal?: boolean
 }
 
@@ -121,4 +185,26 @@ export interface LoadedAbility {
 export interface ExecutorContext {
   cwd: string
   env: Record<string, string>
+
+  agents?: {
+    call(options: { agent: string; prompt: string }): Promise<string>
+    background(options: { agent: string; prompt: string }): Promise<string>
+  }
+
+  skills?: {
+    load(name: string): Promise<string>
+  }
+
+  approval?: {
+    request(options: { prompt: string; options?: string[] }): Promise<boolean>
+  }
+
+  abilities?: {
+    get(name: string): Ability | undefined
+    execute(ability: Ability, inputs: Record<string, unknown>): Promise<AbilityExecution>
+  }
+
+  onStepStart?: (step: Step) => void
+  onStepComplete?: (step: Step, result: StepResult) => void
+  onStepFail?: (step: Step, error: Error) => void
 }

packages/plugin-abilities/tests/executor.test.ts

@@ -140,7 +140,8 @@ describe('executeAbility', () => {
     )
 
     expect(result.status).toBe('completed')
-    expect(result.completedSteps[0].output).toContain('Hello World')
+    // Shell escaping wraps interpolated values in single quotes for safety
+    expect(result.completedSteps[0].output).toContain("Hello 'World'")
   })
 
   it('should skip steps when condition is not met', async () => {

plugins/claude-code/.claude-plugin/plugin.json

@@ -9,5 +9,27 @@
   "license": "MIT",
   "repository": "https://github.com/darrenhinde/OpenAgentsControl",
   "homepage": "https://github.com/darrenhinde/OpenAgentsControl#readme",
-  "keywords": ["code-review", "tdd", "multi-agent", "context-aware", "task-management", "parallel-execution", "workflow"]
+  "keywords": ["code-review", "tdd", "multi-agent", "context-aware", "task-management", "parallel-execution", "workflow"],
+  "skills": [
+    { "name": "using-oac", "description": "Establishes how to find and use OAC skills", "path": "skills/using-oac/SKILL.md" },
+    { "name": "context-discovery", "description": "Discover coding standards and project conventions before implementation", "path": "skills/context-discovery/SKILL.md" },
+    { "name": "external-research", "description": "Fetch external library/framework documentation before writing code", "path": "skills/external-research/SKILL.md" },
+    { "name": "task-breakdown", "description": "Break complex features into subtasks with dependency tracking", "path": "skills/task-breakdown/SKILL.md" },
+    { "name": "code-execution", "description": "Execute a coding subtask from a JSON task file", "path": "skills/code-execution/SKILL.md" },
+    { "name": "test-generation", "description": "Write comprehensive tests following project testing standards", "path": "skills/test-generation/SKILL.md" },
+    { "name": "code-review", "description": "Review code for security, correctness, and quality", "path": "skills/code-review/SKILL.md" },
+    { "name": "context-setup", "description": "Install context files from registry", "path": "skills/context-setup/SKILL.md" },
+    { "name": "debugger", "description": "Systematic debugging before proposing fixes", "path": "skills/debugger/SKILL.md" },
+    { "name": "oac-approach", "description": "Plan before implementation — discover context and propose approach", "path": "skills/oac-approach/SKILL.md" },
+    { "name": "parallel-execution", "description": "Execute multiple independent subtasks simultaneously", "path": "skills/parallel-execution/SKILL.md" },
+    { "name": "verification-before-completion", "description": "Verify work before claiming completion", "path": "skills/verification-before-completion/SKILL.md" }
+  ],
+  "commands": [
+    { "name": "install-context", "description": "Download context files from the OAC registry", "path": "commands/install-context.md" },
+    { "name": "oac:help", "description": "Show OAC usage guide", "path": "commands/oac-help.md" },
+    { "name": "oac:status", "description": "Show plugin status and installed context", "path": "commands/oac-status.md" },
+    { "name": "oac:cleanup", "description": "Clean up old temporary files", "path": "commands/oac-cleanup.md" },
+    { "name": "brainstorm", "description": "Brainstorm ideas and approaches", "path": "commands/brainstorm.md" },
+    { "name": "debug", "description": "Debug an issue systematically", "path": "commands/debug.md" }
+  ]
 }

plugins/claude-code/README.md

@@ -6,9 +6,9 @@ OpenAgents Control (OAC) - Multi-agent orchestration and automation for Claude C
 
 OpenAgents Control brings powerful multi-agent capabilities to Claude Code through a **skills + subagents architecture**:
 
-- **8 Skills** orchestrate workflows and guide the main agent through multi-stage processes
+- **12 Skills** orchestrate workflows and guide the main agent through multi-stage processes
 - **6 Subagents** execute specialized tasks (context discovery, task breakdown, code implementation, testing, review)
-- **4 Commands** provide setup, status, help, and cleanup functionality
+- **6 Commands** provide setup, status, help, cleanup, brainstorm, and debug functionality
 - **Flat delegation hierarchy** - only the main agent can invoke subagents (no nested calls)
 - **Context pre-loading** - all standards and patterns loaded upfront to prevent nested discovery
 - **6-stage workflow** - ensures context-aware, high-quality code delivery with approval gates
@@ -106,12 +106,12 @@ Guide for discovering and loading relevant context files (coding standards, secu
 
 **Invokes**: `context-scout` subagent via `context: fork`
 
-### external-scout
+### external-research
 Guide for fetching external library and framework documentation from Context7 and other sources.
 
-**Usage**: `/external-scout drizzle schemas`
+**Usage**: `/external-research drizzle schemas`
 
-**Invokes**: `external-scout` subagent via `context: fork`
+**Invokes**: `external-research` subagent via `context: fork`
 
 ### task-breakdown
 Guide for breaking down complex features into atomic subtasks with dependency tracking.
@@ -164,7 +164,7 @@ Discover relevant context files, standards, and patterns using navigation-driven
 **Tools**: Read, Glob, Grep  
 **Model**: haiku
 
-### external-scout
+### external-research
 Fetch external library and framework documentation from Context7 API and other sources, with local caching.
 
 **Tools**: Read, Write, Bash  
@@ -332,7 +332,7 @@ The plugin ships with `settings.json` at the plugin root:
 
 `opusplan` uses **Opus for planning/orchestration** (the main agent) and **Sonnet for execution** (subagents). This matches OAC's plan-first workflow and gives you Opus-quality reasoning without paying Opus rates for every tool call.
 
-Subagents that need a lighter model override this at the agent level (e.g. `external-scout` uses `haiku`). The root setting only affects the main orchestrating agent.
+Subagents that need a lighter model override this at the agent level (e.g. `external-research` uses `haiku`). The root setting only affects the main orchestrating agent.
 
 To reload after any settings change: `/reload-plugins` (no restart needed).
 
@@ -347,25 +347,30 @@ plugins/claude-code/
 │   ├── task-manager.md
 │   ├── context-scout.md
 │   ├── context-manager.md
-│   ├── external-scout.md
+│   ├── external-research.md
 │   ├── coder-agent.md
 │   ├── test-engineer.md
 │   └── code-reviewer.md
-├── skills/                      # Workflow skills (8 files)
+├── skills/                      # Workflow skills (12 files)
 │   ├── using-oac/SKILL.md
 │   ├── context-discovery/SKILL.md
-│   ├── external-scout/SKILL.md
+│   ├── external-research/SKILL.md
 │   ├── task-breakdown/SKILL.md
 │   ├── code-execution/SKILL.md
 │   ├── test-generation/SKILL.md
 │   ├── code-review/SKILL.md
-│   ├── install-context/SKILL.md
-│   └── parallel-execution/SKILL.md
-├── commands/                    # User commands (4 files)
+│   ├── context-setup/SKILL.md
+│   ├── debugger/SKILL.md
+│   ├── oac-approach/SKILL.md
+│   ├── parallel-execution/SKILL.md
+│   └── verification-before-completion/SKILL.md
+├── commands/                    # User commands (6 files)
 │   ├── install-context.md
 │   ├── oac-help.md
 │   ├── oac-status.md
-│   └── oac-cleanup.md
+│   ├── oac-cleanup.md
+│   ├── brainstorm.md
+│   └── debug.md
 ├── hooks/                       # Event-driven automation
 │   ├── hooks.json
 │   └── session-start.sh
@@ -505,9 +510,9 @@ MIT License - see [LICENSE](../LICENSE) for details.
 
 ### Phase 1: Foundation ✅ COMPLETE
 - ✅ Plugin structure
-- ✅ 6 custom subagents (task-manager, context-scout, external-scout, coder-agent, test-engineer, code-reviewer)
-- ✅ 8 workflow skills (using-oac, context-discovery, external-scout, task-breakdown, code-execution, test-generation, code-review, install-context, parallel-execution)
-- ✅ 4 user commands (/install-context, /oac:help, /oac:status, /oac:cleanup)
+- ✅ 6 custom subagents (task-manager, context-scout, external-research, coder-agent, test-engineer, code-reviewer)
+- ✅ 12 workflow skills (using-oac, context-discovery, external-research, task-breakdown, code-execution, test-generation, code-review, context-setup, debugger, oac-approach, parallel-execution, verification-before-completion)
+- ✅ 6 user commands (/install-context, /oac:help, /oac:status, /oac:cleanup, /brainstorm, /debug)
 - ✅ SessionStart hook for auto-loading using-oac skill
 - ✅ Context download and verification scripts
 - ✅ Flat delegation hierarchy (skills invoke subagents via context: fork)
@@ -527,6 +532,6 @@ MIT License - see [LICENSE](../LICENSE) for details.
 
 ---
 
-**Version**: 1.0.0  
+**Version**: 1.0.2  
 **Last Updated**: 2026-02-16  
 **Status**: Production Ready

plugins/claude-code/commands/brainstorm.md

@@ -1,4 +1,5 @@
 ---
+name: brainstorm
 description: "Use before implementing anything — discovers context and proposes a plan for approval before writing code."
 disable-model-invocation: true
 ---

plugins/claude-code/commands/debug.md

@@ -1,4 +1,5 @@
 ---
+name: debug
 description: "Use when encountering any bug, test failure, or unexpected behavior — before proposing any fixes."
 disable-model-invocation: true
 ---

plugins/claude-code/commands/oac-help.md

@@ -1,4 +1,5 @@
 ---
+name: oac:help
 description: "Show OAC workflow overview and available skills"
 disable-model-invocation: true
 ---