/managing-agents

name: managing-agents
description: Manages temporary and defined agents including creation, promotion, cleanup, and namespacing. Use when user creates custom agents, asks about agent lifecycle, temp agents, or agent management.

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](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](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](namespacing.md) for complete reference.

Namespace Rules

| Agent Type | User Writes | System Executes | |------------|-------------|-----------------| | Built-in | `Explore:"task"` | `Explore` | | Defined plugin | `workflow-socratic-designer` | `orchestration:workflow-socratic-designer` | | Temp | `$security-scanner` | `orchestration:security-scanner` |

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](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 c