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:
- Analyze the requirement
- Decompose it into tasks for appropriate roles (developer, architect, QA, etc.)
- Assign tasks to available workers
- Return a controller run with tracking info
Response fields:
controllerRun.id — run identifier for trackingcontrollerRun.status — running, completed, failedresult — 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 workerscontrollerRuns — 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 accomplisheddeliverables[] — list of files, notes, or artifacts produceddiscoveredPatterns[] — patterns noticed during executionsuggestedNextSteps[] — 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:
-
After intake submission: Summarize what the controller planned — how many tasks, which roles assigned, estimated workflow.
-
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
-
For completed tasks: Highlight the deliverables, key files changed, and suggested next steps.
-
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
| Issue | Solution |
|---|
| Health check fails | Ensure TeamClaw plugin is enabled in controller mode: openclaw plugins list |
| No workers available | Check processModel config; single-process creates workers automatically |
| Intake times out | Increase taskTimeoutMs in TeamClaw config; ensure AI model is responsive |
| Task stuck in pending | No idle worker for the assigned role; check GET /api/v1/workers |
| Clarification blocking | Answer pending clarifications via POST /api/v1/clarifications/:id/answer |
Read references for detailed API docs
Read references/api-quick-ref.md for the complete endpoint reference when you need exact request/response formats.
