team-lifecycle

name	team-lifecycle
description	Full team lifecycle management from creation through operation to shutdown and cleanup. Handles pre-flight checks, graceful shutdown, and resource cleanup.

Team Lifecycle Management

End-to-end management of agent teams from initial planning through creation, operation, shutdown, and cleanup. Every team follows the same five-phase lifecycle. Skipping phases leads to orphaned resources, lost work, or unclean shutdowns.

The Five Phases

Planning --> Creation --> Operation --> Shutdown --> Cleanup

Each phase has a clear entry condition, a set of actions, and an exit condition that gates progression to the next phase.

Phase 1: Planning

Define what the team needs to accomplish before creating anything.

Inputs required:

• A clear goal statement (what does "done" look like?)
• The work to be divided (what tasks exist?)
• The skills needed (what roles are required?)

Steps:

1. Define the goal. Write a single sentence describing the team's deliverable. If you cannot write one sentence, the scope is too broad -- split into multiple teams.

2. Design the team structure. Decide how many agents are needed and what each one does. A team of 2-4 agents covers most workloads. Larger teams add coordination overhead.

3. Select a template. If a predefined template matches the work (e.g., research-team, code-review, refactor-squad), use it. Templates encode proven role definitions and task structures.

4. Draft the task list. Write out every task with dependencies. Each task becomes a Task JSON object later. Identify which tasks block others to define the critical path.

5. Assess risks. Will any task take disproportionately long? Are there external dependencies? Plan mitigations now.

Exit condition: You have a goal, a roster of roles, and a task list with dependencies.

Phase 2: Creation

Instantiate the team and assign work.

Steps:

1. Validate prerequisites. Confirm that no team with the same name already exists at ~/.claude/teams/{name}/config.json. Check that required files, repos, or resources are accessible.

2. Create the team.

   Use TeamCreate with:
   - name: the team identifier
   - roles: list of agent roles with instructions
   - template: (optional) a predefined template name
   

3. Spawn agents. TeamCreate spawns agents according to the role definitions. Each agent receives its role instructions and begins in an idle state waiting for tasks.

4. Create tasks. For each item in the task list, create a Task JSON:

   {
     "id": "task-001",
     "subject": "Implement auth module",
     "description": "Build the authentication middleware...",
     "status": "pending",
     "owner": "backend-dev",
     "blockedBy": [],
     "blocks": ["task-003"]
   }
   

5. Assign tasks. Send each agent its initial tasks via SendMessage. Agents with no blocking dependencies can start immediately.

6. Verify the team is operational. Confirm every agent has acknowledged its tasks. If any agent fails to spawn, re-create it before proceeding.

Exit condition: All agents are running, all tasks are assigned, and at least one agent has begun work.

Phase 3: Operation

The team is running. Your job is to monitor, orchestrate, and intervene when needed.

Ongoing activities:

• Monitor progress. Check task statuses periodically. Look for tasks stuck in in_progress for too long.
• Orchestrate handoffs. When a blocking task completes, notify the agents whose tasks are now unblocked.
• Communicate. Use SendMessage to relay information between agents that need to coordinate. Prefer targeted messages over broadcasts.
• Handle issues. If an agent is stuck, provide guidance. If a task is no longer needed, mark it completed or reassign it. If scope changes, create new tasks and adjust dependencies.

Common interventions:

Symptom	Action
Agent idle, tasks remain	Check if blocked; reassign if the blocker is stale
Agent producing wrong output	Clarify instructions via SendMessage
Task dependency cycle	Break the cycle by splitting a task or removing a dependency
Agent unresponsive	Attempt SendMessage; if no response, plan for shutdown and replacement

Exit condition: All tasks are completed (or explicitly cancelled), and the team's goal has been met.

Phase 4: Shutdown

Gracefully stop all agents and collect results. Never kill agents without warning.

Steps:

1. Run the health check. Use team_health_check.py to verify all tasks are complete:

   python scripts/team_health_check.py my-team
   

   If the output is NOT READY, resolve incomplete tasks before proceeding.

2. Collect deliverables. Before shutting anyone down, gather all outputs, artifacts, and summaries from agents. Once an agent shuts down, you cannot query it.

3. Shut down workers first. Send shutdown requests to non-lead agents first:

   SendMessage:
     type: "shutdown_request"
     recipient: "worker-agent-name"
     content: "All tasks complete. Please wrap up and shut down."
   

4. Handle rejections. An agent may reject the shutdown if it believes work remains:

   SendMessage:
     type: "shutdown_response"
     request_id: "..."
     approve: false
     content: "Still finalizing task-007."
   

   If rejected: verify the claim, resolve the issue, then re-request shutdown.

5. Shut down the lead last. The team lead coordinates others, so it must be the last to go. Send its shutdown request only after all workers have confirmed shutdown.

6. Verify shutdown. Confirm no agents remain active for the team.

Exit condition: All agents have confirmed shutdown. No active processes remain.

Phase 5: Cleanup

Remove team resources and archive results.

Steps:

1. Scan for stale teams. Use cleanup_teams.py to identify teams ready for cleanup:

   python scripts/cleanup_teams.py --stale-days 7
   

2. Delete the team. Use TeamDelete to remove the team configuration:

   TeamDelete:
     name: my-team
   

   This removes ~/.claude/teams/my-team/config.json and associated metadata.

3. Archive if needed. Before deletion, copy any task files or logs you want to retain. TeamDelete does not preserve history.

4. Clean up task files. Remove completed task JSON files from ~/.claude/tasks/{name}/ or let them age out naturally.

Exit condition: No configuration, task files, or active agents remain for the team.

Complete Walkthrough Example

Scenario: Build a team to refactor a legacy authentication module.

Planning

Goal: Replace the legacy auth module with a modern JWT-based implementation.
Roles: team-lead, backend-dev, test-writer
Tasks:
  1. Audit existing auth code (no dependencies)
  2. Design new JWT auth (blocked by 1)
  3. Implement JWT auth (blocked by 2)
  4. Write integration tests (blocked by 3)
  5. Write migration guide (blocked by 2)

Creation

TeamCreate:
  name: auth-refactor
  roles:
    - name: team-lead
      instructions: "Coordinate the auth refactor. Monitor progress and handle blockers."
    - name: backend-dev
      instructions: "Implement the JWT auth module. Start with an audit of the existing code."
    - name: test-writer
      instructions: "Write comprehensive tests for the new auth module."

Create five tasks as JSON. Assign tasks 1 and 5 to backend-dev, tasks 4 to test-writer, task coordination to team-lead.

Operation

backend-dev completes task 1 (audit) --> unblock task 2
backend-dev completes task 2 (design) --> unblock tasks 3 and 5
backend-dev starts task 3, test-writer prepares test framework
backend-dev completes task 3 --> unblock task 4
test-writer completes task 4, backend-dev completes task 5

Shutdown

python scripts/team_health_check.py auth-refactor
# Output: READY - 5/5 tasks completed

SendMessage shutdown_request --> test-writer    (approved)
SendMessage shutdown_request --> backend-dev    (approved)
SendMessage shutdown_request --> team-lead      (approved)

Cleanup

python scripts/cleanup_teams.py
# Shows auth-refactor as "Completed"

TeamDelete: auth-refactor

The refactor is delivered, the team is dissolved, and no resources remain.

Quick Reference

Phase	Key Tool / Script	Gate
Planning	(manual)	Goal + roster + task list defined
Creation	TeamCreate	All agents running, tasks assigned
Operation	SendMessage	All tasks completed
Shutdown	shutdown_request/response, team_health_check.py	All agents shut down
Cleanup	cleanup_teams.py, TeamDelete	All resources removed

Anti-Patterns

• Skipping the health check before shutdown. You will shut down agents that still have pending work.
• Shutting down the lead first. Remaining workers lose their coordinator.
• Never cleaning up. Stale teams accumulate and clutter the teams directory.
• Broadcasting instead of targeted messages. Every broadcast goes to every agent. Use targeted SendMessage unless every agent truly needs the information.
• Teams larger than necessary. Each additional agent adds coordination cost. Prefer 2-4 agents.
• No dependency tracking. Without blockedBy/blocks, agents work on tasks whose prerequisites are incomplete.

Related Skills

• team-architect -- Design teams during the Planning phase
• team-builder -- Automate team creation during the Creation phase
• team-orchestrator -- Manage tasks and workflows during the Operation phase
• team-communicator -- Coordinate agents during Operation
• team-monitor -- Track health and progress during Operation
• team-doctor -- Diagnose and fix issues during Operation