Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use when spawning, terminating, hibernating, or waking agents. Trigger with agent spawn, termination, or hibernation requests.
user-invocable
false
license
Apache-2.0
compatibility
Requires access to agent registry, AI Maestro messaging system, and understanding of agent state management. Requires AI Maestro installed.
metadata
{"author":"Emasoft","version":"1.0.0"}
context
fork
agent
ecos-main
workflow-instruction
Step 4
procedure
proc-create-team
Emasoft Chief of Staff - Agent Lifecycle Skill
Overview
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.
Prerequisites
Before using this skill, ensure:
AI Maestro is running locally
The ai-maestro-agents-management skill is available for agent lifecycle operations
The agent-messaging skill is available for inter-agent communication
tmux is installed for session management
Team registry location is writable (.emasoft/team-registry.json)
Pre-Deployment: Required OAuth Scopes
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]
Required Scopes
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
How to Add Missing Scopes
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.
Pre-Flight Validation
Before spawning agents that use kanban operations, verify scopes:
If scopes are missing, do NOT proceed with agent deployment. Request the human operator to add scopes first.
Instructions
Identify the lifecycle operation needed (spawn, terminate, hibernate, wake)
Check resource availability using the Resource Limits table
Execute the appropriate PROCEDURE (1, 2, or 3)
Update the team registry after each operation
Report completion to EAMA
Output
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
Role Boundaries (CRITICAL)
Before performing any lifecycle operation, you MUST understand your boundaries:
ROLE_BOUNDARIES.md - Your strict role boundaries (see plugin docs/)
FULL_PROJECT_WORKFLOW.md - Complete project workflow (see plugin docs/)
Key Constraints:
You are PROJECT-INDEPENDENT (one ECOS for all projects)
You CREATE agents and ASSIGN them to teams
You do NOT assign tasks (that's EOA's job)
You do NOT manage kanban (that's EOA's job)
You do NOT create projects (that's EAMA's job)
You NEVER spawn a copy of yourself (only EAMA creates ECOS)
Agent vs Sub-Agent Terminology
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.
What Is Agent Lifecycle Management?
Agent lifecycle management is the systematic control of agent states from creation to termination. The lifecycle includes:
Spawning: Creating new agent instances with proper configuration
Running: Active agents executing their assigned tasks
Hibernating: Suspending idle agents while preserving their state
Waking: Resuming hibernated agents when work is available
Terminating: Cleanly shutting down agents when work is complete
Communicate with remote agents using the agent-messaging skill.
Send Message
Use the agent-messaging skill to send a message:
Recipient: the target agent session name
Subject: descriptive subject line
Content: structured message with type and body
Priority: normal, high, or urgent
Verify: confirm message delivery.
Message Types:
role-assignment - Assign role to agent
project-assignment - Assign project to agent
task-delegation - Delegate specific task
status-request - Request status update
status-report - Report status back
team-notification - Notify about teammates
hibernation-warning - Warn agent of pending hibernation
wake-notification - Notify agent it has been woken
registry-update - Team registry has changed
Check Messages
Use the agent-messaging skill to check for unread messages and unread count.
Quality Standards
Agent Management Standards
All agents MUST be registered before activation
Agent session names MUST follow naming convention
Terminated agents MUST be cleaned from registry
Hibernated agents MUST be marked with timestamp
Communication Standards
All AI Maestro messages MUST include from field
All role assignments MUST be acknowledged by target agent
Failed message delivery MUST be retried 3 times before escalating
All broadcasts MUST log recipient list
Resource Standards
NEVER exceed max_concurrent_agents limit
ALWAYS check resource availability before spawning
ALWAYS hibernate before terminating (graceful shutdown)
ALWAYS save agent state before hibernation
Operational Procedures
Step-by-step runbooks for executing individual lifecycle operations. Use these when performing a specific operation.
op-spawn-agent.md - Spawn New Agent: Determine agent type, setup plugin, create instance, verify initialization, register in team registry, and send welcome message
op-terminate-agent.md - Terminate Agent: Verify work is complete, save final state, send termination warning, execute termination, update registry, and cleanup resources
op-hibernate-agent.md - Hibernate Agent: Confirm agent is idle, send hibernation warning, request state capture, execute hibernation, update registry, and log event
op-wake-agent.md - Wake Hibernated Agent: Verify agent is hibernated, check resource availability, execute wake command, verify responsiveness, restore state, and update registry
op-update-team-registry.md - Update Team Registry: Identify update type, execute registry update, verify update, optionally publish to team, and backup registry
op-send-maestro-message.md - Send AI Maestro Message: Determine message type and priority, compose content, send message, verify delivery, and optionally wait for response
