Teamwork Clean

Overview

Teamwork-clean resets a project to start fresh by cleaning up team and task state.

Core Principles

1. Native API cleanup - Uses TeamDelete() to remove team and all associated tasks
2. Idempotent operation - Safe to run multiple times
3. Clean shutdown - Sends shutdown messages to active workers before cleanup

Use Case

When task state becomes inconsistent, workflow fails, or you need to restart execution with the same project configuration.

When to Use

USE teamwork-clean for:

• Starting a new run in the same project (multiple attempts at same goal)
• Recovering from failed orchestration or stuck workers
• Cleaning up after testing or experimentation
• Resolving state corruption (stuck tasks, orphaned workers)

DON'T use teamwork-clean for:

• Normal project completion (state is valuable)
• Fixing a single task (release the task instead)
• Active projects with workers running (shut down workers first)

Cleanup Process

Step 1: Shutdown Active Workers

Before cleaning, send shutdown messages to all active teammates:

# Notify all workers to stop
SendMessage(
    type="shutdown_request",
    recipient="worker-backend",
    content="Project cleanup in progress. Please stop."
)
SendMessage(
    type="shutdown_request",
    recipient="worker-frontend",
    content="Project cleanup in progress. Please stop."
)

Step 2: Delete Team

Use the native TeamDelete API to remove the team and all associated tasks:

# Delete team (removes all tasks and team state)
TeamDelete()

This removes:

• All task definitions and their status
• Task ownership and dependency information
• Team metadata

Step 3: Recreate (Optional)

If restarting with the same goal, create a new team:

# Create fresh team
TeamCreate(team_name="<team-name>", description="<project goal>")

# Recreate tasks from scratch
TaskCreate(subject="...", description="...")

What Gets Cleaned

After cleanup: The team no longer exists. You start with a blank slate.

What's Preserved

Usage

Command Invocation

/teamwork-clean

Workflow: Clean and Restart

# 1. Check current status
/teamwork-status

# 2. Clean the project
/teamwork-clean

# 3. Start fresh
/teamwork "same goal or updated goal"

Workflow: After Failed Project

# Project failed, want to retry with different approach
/teamwork-clean

# Orchestrator will plan from scratch
/teamwork "updated goal with more context"

Agent Guidance

Decision-Making Checklist

Before recommending /teamwork-clean, verify:

1. Is the project stuck?

   • Check task status for stalled tasks (in_progress for too long)
   • Check if workers are idle with no available tasks

2. Are workers stopped?

   • Cleaning while workers are active causes undefined behavior
   • Send shutdown messages first, then clean

3. Is cleanup the right solution?

   • Single stuck task -> Release the task (TaskUpdate with status="open", owner="")
   • Want to abandon project entirely -> TeamDelete is sufficient
   • Just checking status -> Use /teamwork-status only

When to Recommend Clean

Related Commands