Managing Orchestration Agents

I manage the lifecycle of agents in the orchestration system: creation, execution, promotion, and cleanup.

When I Activate

I automatically activate when you: - Create or define custom agents - Ask about agent lifecycle - Mention temp agents or agent promotion - Want to understand agent namespacing - Ask "how do I create an agent?"

Agent Types

Built-in Agents

No namespace prefix, always available: - Explore - Codebase exploration - general-purpose - General-purpose tasks - code-reviewer - Code review - implementation-architect - Architecture planning - expert-code-implementer - Code implementation

Plugin Defined Agents

With orchestration: prefix, permanent agents in this plugin: - orchestration:workflow-socratic-designer - orchestration:workflow-syntax-designer - Custom agents you promote

Located in: agents/ directory Registry: agents/registry.json

Temp Agents

With orchestration: prefix, workflow-specific ephemeral agents: - Created during workflow design - Saved in temp-agents/ directory - Auto-cleaned after workflow execution - Can be promoted to permanent

Reference in workflows: $agent-name

Temp Agent Lifecycle

See temp-agents.md for complete guide.

1. Creation

Created automatically during workflow design:

---
name: security-scanner
description: Scans for security vulnerabilities
created: 2025-01-08
---

You are a security expert specializing in vulnerability detection...

Saved to: temp-agents/security-scanner.md

2. Execution

Referenced in workflow with $ prefix:

$security-scanner:"Scan codebase":findings ->
general-purpose:"Analyze {findings}"

Executed with namespace: orchestration:security-scanner

3. Promotion

After workflow completion, you can save temp agents:

Workflow complete!

Temp agents created:
  - security-scanner
  - performance-profiler

Save as permanent agents? [Y/n]

If saved: - Moved from temp-agents/ to agents/ - Added to agents/registry.json - Available in all future workflows - No need to recreate

4. Cleanup

Unsaved temp agents are deleted:

🧹 Cleaned up 2 temporary file(s):
   - temp-agents/security-scanner.md
   - examples/workflow-data.json

Creating Defined Agents

See defined-agents.md for detailed guide.

To create a permanent agent manually:

1. Create Agent File

agents/custom-agent.md:

---
name: custom-agent
namespace: orchestration:custom-agent
description: One-line description of what this agent does
tools: [Read, Grep, Edit]
usage: "Use via Task tool with subagent_type: 'orchestration:custom-agent'"
---

You are a specialized agent for [purpose].

Your responsibilities:
1. Task 1
2. Task 2

Output format:
[Expected output format]

Use these tools:
- Read: [When to use]
- Grep: [When to use]

2. Register Agent

Add to agents/registry.json:

{
  "custom-agent": {
    "file": "custom-agent.md",
    "description": "One-line description",
    "namespace": "orchestration:custom-agent",
    "created": "2025-01-08",
    "usageCount": 0
  }
}

3. Use in Workflows

Reference by name (system adds namespace automatically):

custom-agent:"Perform specialized task":output

Namespace Conventions

See namespacing.md for complete reference.

Namespace Rules

Why Namespacing?

1. Avoid conflicts - Plugin agents don't conflict with built-ins
2. Clear identification - Know which plugin provides agent
3. Proper routing - System knows where to find agent

Resolution Algorithm

function resolveAgent(name) {
  // 1. Check if built-in
  if (isBuiltIn(name)) return name;

  // 2. Check if other plugin (e.g., superpowers:)
  if (name.includes(':')) return name;

  // 3. Add orchestration namespace
  return `orchestration:${name}`;
}

Agent Promotion Process

See promotion.md for details.

After workflow execution with temp agents:

1. Review Phase

Temp agents used in this workflow:

1. security-scanner
   Description: Scans for security vulnerabilities
   Used: 1 time in workflow

2. performance-profiler
   Description: Analyzes code performance
   Used: 1 time in workflow

Select agents to save (space-separated numbers, or 'none'):

2. Selection

You selected: security-scanner

Promotion options:
[P]romote as-is - Save with current definition
[E]dit first - Modify before saving
[S]kip - Don't save this agent

3. Promotion

If promoted: 1. File moved from temp-agents/ to agents/ 2. Entry added to agents/registry.json 3. Confirmation message shown

4. Cleanup

Unselected agents are deleted

Agent Maintenance

Updating Agents

To update a defined agent:

1. Edit agents/agent-name.md
2. Update description/responsibilities/tools
3. Optionally update agents/registry.json metadata

Changes take effect immediately in new workflows.

Deleting Agents

To remove a defined agent:

1. Delete agents/agent-name.md
2. Remove entry from agents/registry.json

Agent will no longer be available in workflows.

Agent Usage Statistics

Track agent usage in agents/registry.json:

{
  "security-scanner": {
    "usageCount": 15,
    "lastUsed": "2025-01-08T14:30:00Z"
  }
}

Best Practices

Creating Agents

✅ DO: - Make prompts comprehensive and specific - Include clear output format requirements - Recommend appropriate tools - Handle edge cases - Define success criteria

❌ DON'T: - Create for simple one-line tasks - Make too generic ("do analysis") - Forget error handling - Skip tool recommendations

Promoting Agents

✅ Promote when: - Agent is reusable across workflows - Well-tested and reliable - Provides domain-specific expertise - Saves time in future workflows

❌ Don't promote when: - One-time use only - Too specific to single workflow - Untested or unreliable - Duplicates existing agent

Naming Agents

✅ Good names: - security-scanner (clear purpose) - api-doc-generator (descriptive) - performance-profiler (specific)

❌ Bad names: - helper (too generic) - agent1 (meaningless) - do-stuff (vague)

Common Issues

"Agent not found" error: - Check spelling of agent name - Verify temp agent file exists in temp-agents/ - Ensure defined agent in agents/ and registry - Check if agent was already cleaned up

Namespace conflict: - Built-in agents don't need prefix - Plugin agents automatically prefixed - Don't manually add orchestration: in workflows

Temp agent disappeared: - Temp agents auto-deleted after workflow - Save important agents during promotion phase - Check cleanup logs for what was deleted

Registry Structure

agents/registry.json:

{
  "$schema": {
    "description": "Registry of defined agents",
    "namespace": "orchestration:",
    "usage": "All agents accessed via 'orchestration:{agent-name}'"
  },
  "agent-name": {
    "file": "agent-name.md",
    "description": "One-line description",
    "namespace": "orchestration:agent-name",
    "created": "2025-01-08",
    "usageCount": 0,
    "lastUsed": null
  }
}

Examples

See examples in: - temp-agents.md - Temp agent examples - defined-agents.md - Permanent agent examples - promotion.md - Promotion workflow examples

Related Skills

• creating-workflows: Create workflows that use agents
• executing-workflows: Execute workflows with agents
• designing-syntax: Design custom syntax for agents

Need to create or manage agents? Just ask!