Use when spawning, terminating, hibernating, or waking agents. Trigger with agent spawn, termination, or hibernation requests.
npx claudepluginhub emasoft/emasoft-plugins --plugin emasoft-chief-of-staffThis skill uses the workspace's default tool permissions.
Agent lifecycle management is a critical responsibility of the Chief of Staff. It encompasses all operations related to agent creation, state transitions, and termination. This skill teaches you how to properly spawn agents, manage their running state, hibernate idle agents to conserve resources, and terminate agents when their work is complete.
references/cli-examples.mdreferences/cli-reference.mdreferences/hibernation-procedures.mdreferences/op-hibernate-agent.mdreferences/op-send-maestro-message.mdreferences/op-spawn-agent.mdreferences/op-terminate-agent.mdreferences/op-update-team-registry.mdreferences/op-wake-agent.mdreferences/record-keeping.mdreferences/spawn-procedures.mdreferences/sub-agent-role-boundaries-template.mdreferences/success-criteria.mdreferences/termination-procedures.mdreferences/workflow-checklists.mdreferences/workflow-examples.mdManages AI agent lifecycle with AI Maestro CLI: create, list, delete, rename, hibernate/wake, plugin install, export. For agent operations in Claude Code.
Manages agent fleets via CRUD (create, command, monitor, delete) and lifecycle patterns. For multi-agent systems, resource cleanup, and state tracking with Claude Agent SDK.
Guides creation and configuration of autonomous agents for Claude Code plugins, covering frontmatter, triggering descriptions, system prompts, tools, teams, permissions, and best practices.
Share bugs, ideas, or general feedback.
Agent lifecycle management is a critical responsibility of the Chief of Staff. It encompasses all operations related to agent creation, state transitions, and termination. This skill teaches you how to properly spawn agents, manage their running state, hibernate idle agents to conserve resources, and terminate agents when their work is complete.
Before using this skill, ensure:
ai-maestro-agents-management skill is available for agent lifecycle operationsagent-messaging skill is available for inter-agent communication.emasoft/team-registry.json)CRITICAL: Before deploying ANY agent that manages GitHub Projects (EOA, ECOS), the following OAuth scopes MUST be provisioned on the machine.
The default gh auth login does NOT include project scopes. Without them, any command touching GitHub Projects V2 will fail with: error: your authentication token is missing required scopes [project read:project]
| Scope | Required By | Purpose |
|---|---|---|
repo | All agents | Repository access (issues, PRs, code) |
project | EOA, ECOS | Create and modify GitHub Projects V2 boards |
read:project | EOA, ECOS | Read GitHub Projects V2 data |
read:org | ECOS (if org) | Read organization data (org-level projects only) |
workflow | EIA | Manage GitHub Actions workflows |
This is an interactive, one-time step that requires a human with browser access:
# Run in a terminal with browser access (NOT in tmux or SSH without display)
gh auth refresh -h github.com -s project,read:project
# Verify scopes were added
gh auth status
# Should show 'project' and 'read:project' in Token scopes line
This CANNOT be done by agents. The gh auth refresh command requires browser-based OAuth approval. All required scopes must be provisioned by the human operator BEFORE deploying agents.
Before spawning agents that use kanban operations, verify scopes:
gh auth status 2>&1 | grep -q "project" || echo "ERROR: Missing project scope"
If scopes are missing, do NOT proceed with agent deployment. Request the human operator to add scopes first.
| Operation | Output |
|---|---|
| Spawn | New agent registered, tmux session created, AI Maestro notification |
| Terminate | Agent removed from registry, resources freed, confirmation logged |
| Hibernate | State saved, session suspended, registry updated to hibernated |
| Wake | State restored, session resumed, registry updated to running |
Before performing any lifecycle operation, you MUST understand your boundaries:
Key Constraints:
CRITICAL DISTINCTION - Memorize these definitions:
| Term | Definition |
|---|---|
| Agent | A Claude Code instance running as a separate process (typically in its own tmux session). Has its own context, can be hibernated/terminated. Created via the ai-maestro-agents-management skill. |
| Sub-agent | An agent spawned INSIDE the same Claude Code instance via the Task tool. Shares parent's context limits, terminates when parent terminates. |
Why this matters: When you "spawn an agent" via Task tool, you are NOT creating a new Claude Code instance. You are creating a sub-agent within your current instance. To create actual remote agents, you must use the ai-maestro-agents-management skill.
Agent lifecycle management is the systematic control of agent states from creation to termination. The lifecycle includes:
┌──────────────┐
│ SPAWNING │
└──────┬───────┘
│
▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ HIBERNATED │◄──►│ RUNNING │───►│ TERMINATED │
└──────────────┘ └──────────────┘ └──────────────┘
State Transitions:
When to use: When a new task requires an agent instance, when scaling up for parallel work, or when specialized capability is needed.
Steps: Select agent type, prepare configuration, create instance, verify initialization, register in agent registry.
Related documentation:
When to use: When agent task is complete, when agent is no longer needed, or during cleanup operations.
Steps: Verify work complete, save final state, send termination signal, await confirmation, unregister from registry.
Related documentation:
When to use: When agent is idle but may be needed later, when conserving resources, or during low-activity periods.
Steps: Confirm agent idle, capture agent state, persist state to storage, release resources, update registry status.
Related documentation:
Note: Sub-agent routing is defined in the ECOS main agent definition (ecos-chief-of-staff-main-agent.md).
When spawning role agents, you MUST include the --agent flag in the program args to inject their main agent prompt.
Use the ai-maestro-agents-management skill to create a new agent:
<role-prefix>-<project>-<descriptive> (the session name, also the registry identity)~/agents/<session-name>/ (FLAT structure)--dangerously-skip-permissions, --chrome, --add-dir /tmp, --plugin-dir <path>, and --agent <agent-name>Session Naming (ECOS Responsibility):
<role-prefix>-<project>-<descriptive> (e.g., eoa-svgbbox-orchestrator)Plugin Setup (Before Spawning):
ECOS copies plugins from the emasoft-plugins marketplace cache to the agent's local folder:
$HOME/.claude/plugins/cache/emasoft-plugins/<plugin-name>/<latest-version>/$HOME/agents/<session-name>/.claude/plugins/<plugin-name>/Notes:
~/agents/<session-name>/--plugin-dir points to the COPIED plugin in the agent's local folder--continue for NEW spawn (only for waking hibernated agents)Verify: the new agent appears in the agent list with "online" status.
Agent name to --agent flag mapping:
| Role | Plugin | --agent Flag Value |
|---|---|---|
| Orchestrator | emasoft-orchestrator-agent | eoa-orchestrator-main-agent |
| Architect | emasoft-architect-agent | eaa-architect-main-agent |
| Integrator | emasoft-integrator-agent | eia-integrator-main-agent |
| Programmer | emasoft-programmer-agent | epa-programmer-main-agent |
All agents are registered in the project's team registry at .emasoft/team-registry.json. See:
Use the team registry script:
uv run python scripts/ecos_team_registry.py <command> [args]
Commands: create, add-agent, remove-agent, update-status, list, publish
Default resource limits (configurable):
| Resource | Limit | Action When Exceeded |
|---|---|---|
| Max concurrent agents | 5 | Queue new requests, hibernate oldest idle |
| Max memory per agent | 2GB | Terminate or hibernate agent |
| API rate limit | 100 req/min | Throttle agent activity |
| Idle timeout | 30 min | Hibernate agent |
Communicate with remote agents using the agent-messaging skill.
Use the agent-messaging skill to send a message:
normal, high, or urgentVerify: confirm message delivery.
Message Types:
role-assignment - Assign role to agentproject-assignment - Assign project to agenttask-delegation - Delegate specific taskstatus-request - Request status updatestatus-report - Report status backteam-notification - Notify about teammateshibernation-warning - Warn agent of pending hibernationwake-notification - Notify agent it has been wokenregistry-update - Team registry has changedUse the agent-messaging skill to check for unread messages and unread count.
from fieldStep-by-step runbooks for executing individual lifecycle operations. Use these when performing a specific operation.
| Error | Action |
|---|---|
| Agent spawn failed | Retry once, then report to EAMA. See spawn-procedures.md 1.7 |
| AI Maestro unavailable | Use fallback file-based communication |
| Agent unresponsive (5 min) | Send wake/ping, then force terminate |
| Resource limit exceeded | Queue request, hibernate oldest idle |
| Plugin validation failed | Block agent spawn, report to EAMA |
| Agent does not terminate | See termination-procedures.md 2.7 |
| Hibernated agent fails to wake | See hibernation-procedures.md 3.7 |
Copy this checklist and track your progress:
Detailed workflow walkthroughs showing complete lifecycle management scenarios.
See references/workflow-examples.md:
Complete CLI command examples with expected output for all lifecycle operations.
See references/cli-examples.md:
ai-maestro-agents-management skill - For all agent lifecycle operationsSee references/cli-examples.md for the full CLI quick reference table and detailed examples.
See references/spawn-procedures.md for complete spawn documentation.
See references/termination-procedures.md for clean shutdown procedures.
See references/hibernation-procedures.md for state suspension and wake procedures.
Version: 1.0.0 Last Updated: 2025-02-03 Target Audience: Chief of Staff Agents Difficulty Level: Intermediate