teamclaw-orchestrator（团队之爪协调器）

TeamClaw — AI Team Orchestration

Orchestrate a virtual software team through natural conversation. Submit requirements, monitor progress, review deliverables, and answer clarifications — all without leaving your chat.

When to Use This Skill

Activate when the user:

• Wants to build, create, or implement something (e.g., "build me a todo app", "create an auth system")
• Asks to delegate work to a team (e.g., "have the team work on this", "assign this to the developer")
• Wants to check team status (e.g., "what are the workers doing?", "show me task progress")
• Needs to review results (e.g., "show me what the developer built", "check the QA report")
• Has pending clarifications to answer (e.g., "are there questions from the team?")
• Mentions teamclaw by name

Prerequisites

TeamClaw must be running in controller mode. Detect the controller URL:

# Default controller URL
TEAMCLAW_URL="http://127.0.0.1:9527"

# Health check — verify the controller is running
curl -sf "$TEAMCLAW_URL/api/v1/health"

If the health check fails, tell the user to start TeamClaw first (install the teamclaw-setup skill for guidance).

Core Workflow

1. Submit a Requirement

When the user describes what they want built, submit it to the controller intake:

curl -s -X POST "$TEAMCLAW_URL/api/v1/controller/intake" \
  -H "Content-Type: application/json" \
  -d '{"message": "<user requirement here>"}'

The controller will:

1. Analyze the requirement
2. Decompose it into tasks for appropriate roles (developer, architect, QA, etc.)
3. Assign tasks to available workers
4. Return a controller run with tracking info

Response fields:

• controllerRun.id — run identifier for tracking
• controllerRun.status — running, completed, failed
• result — the controller agent's orchestration output

Important: The intake call may take 30-180 seconds as the controller agent plans and decomposes the work. Use --max-time 300 with curl for large requirements.

2. Monitor Progress

Check team overview

curl -s "$TEAMCLAW_URL/api/v1/team/status"

Key response fields:

• workers — map of all workers with their status (idle, busy, offline)
• tasks — map of all tasks with status (pending, assigned, in-progress, completed, failed)
• pendingClarificationCount — number of unanswered questions from workers
• controllerRuns — orchestration run history

List tasks

curl -s "$TEAMCLAW_URL/api/v1/tasks"

Get task details with execution history

curl -s "$TEAMCLAW_URL/api/v1/tasks/<taskId>/execution"

Returns the task with full execution log (lifecycle events, progress updates, errors).

List workers

curl -s "$TEAMCLAW_URL/api/v1/workers"

3. Review Results

When a task completes, its result contract contains structured deliverables:

# Get the task to see its resultContract
curl -s "$TEAMCLAW_URL/api/v1/tasks/<taskId>"

The resultContract includes:

• summary — what was accomplished
• deliverables[] — list of files, notes, or artifacts produced
• discoveredPatterns[] — patterns noticed during execution
• suggestedNextSteps[] — recommended follow-up actions

4. Handle Clarifications

Workers may need clarification to proceed. Check and answer them:

# List pending clarifications
curl -s "$TEAMCLAW_URL/api/v1/clarifications"

# Answer a clarification
curl -s -X POST "$TEAMCLAW_URL/api/v1/clarifications/<clarificationId>/answer" \
  -H "Content-Type: application/json" \
  -d '{"answer": "<your answer>", "answeredBy": "user"}'

5. Create Individual Tasks

For fine-grained control, create tasks directly:

curl -s -X POST "$TEAMCLAW_URL/api/v1/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement user login",
    "description": "Create a login form with email/password auth",
    "priority": "high",
    "assignedRole": "developer"
  }'

Valid roles: pm, architect, developer, qa, release-engineer, infra-engineer, devops, security-engineer, designer, marketing.

Valid priorities: low, medium, high.

6. Send Messages to the Team

# Direct message to a role
curl -s -X POST "$TEAMCLAW_URL/api/v1/messages/direct" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "user",
    "toRole": "developer",
    "content": "Please also add input validation"
  }'

# Broadcast to all workers
curl -s -X POST "$TEAMCLAW_URL/api/v1/messages/broadcast" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "user",
    "content": "Deadline moved up — prioritize core features"
  }'

Response Presentation

When presenting results to the user:

1. After intake submission: Summarize what the controller planned — how many tasks, which roles assigned, estimated workflow.

1. For status checks: Show a concise table of workers and tasks:

   Workers: 3 active (developer: busy, qa: idle, architect: idle)
   Tasks: 5 total (2 completed, 1 in-progress, 2 pending)
   Clarifications: 1 pending

1. For completed tasks: Highlight the deliverables, key files changed, and suggested next steps.

1. For clarifications: Present the question clearly and ask the user to provide an answer.

Web UI

TeamClaw also provides a web dashboard for visual monitoring:

Open in browser: $TEAMCLAW_URL/ui

Mention this to users who prefer a visual overview.

Troubleshooting

Read references for detailed API docs

Read references/api-quick-ref.md for the complete endpoint reference when you need exact request/response formats.