mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
feat: add team-coordinate-v2 and team-executor-v2 with team-worker agent architecture
v2 upgrades using the unified team-worker agent pattern: - Replace general-purpose + Skill spawn with team-worker agent - Use lightweight role-spec files (~80 lines, Phase 2-4 only) instead of full role.md (~250 lines) - Add interactive completion action (Archive/Keep/Export) via handleComplete handler - Remove shared infrastructure from SKILL.md (now in team-worker agent) team-coordinate-v2 (8 files): - SKILL.md: coordinator-only, team-worker spawn template - specs/role-spec-template.md: lightweight Phase 2-4 template - roles/coordinator/: updated for role-spec generation - subagents/: discuss + explore (unchanged) team-executor-v2 (4 files): - SKILL.md: executor-only, team-worker spawn - specs/session-schema.md: validates role-specs (not roles/) - roles/executor/: updated for team-worker spawn + handleComplete
This commit is contained in:
catlog22
274
.claude/skills/team-coordinate-v2/SKILL.md
Normal file
274
.claude/skills/team-coordinate-v2/SKILL.md
Normal file
@@ -0,0 +1,274 @@
|
||||
---
|
||||
name: team-coordinate-v2
|
||||
description: Universal team coordination skill with dynamic role generation. Uses team-worker agent architecture with role-spec files. Only coordinator is built-in -- all worker roles are generated at runtime as role-specs and spawned via team-worker agent. Beat/cadence model for orchestration. Triggers on "team coordinate v2".
|
||||
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
|
||||
---
|
||||
|
||||
# Team Coordinate v2
|
||||
|
||||
Universal team coordination skill: analyze task -> generate role-specs -> dispatch -> execute -> deliver. Only the **coordinator** is built-in. All worker roles are **dynamically generated** as lightweight role-spec files and spawned via the `team-worker` agent.
|
||||
|
||||
## Key Changes from v1
|
||||
|
||||
| Change | Before (v1) | After (v2) | Impact |
|
||||
|--------|------------|------------|--------|
|
||||
| Worker agent | general-purpose + Skill load | team-worker agent (dedicated) | Eliminates Skill indirection |
|
||||
| Role definitions | `<session>/roles/<role>.md` (~250 lines, includes Phase 1/5) | `<session>/role-specs/<role>.md` (~80 lines, Phase 2-4 only) | -68% worker content |
|
||||
| Shared behavior | Duplicated in SKILL.md + each role.md | Built into team-worker agent | Single source of truth |
|
||||
| Coordinator spawn | Skill(team-coordinate, --role=xxx) | Task(team-worker, role_spec=xxx.md) | Direct, no Skill call |
|
||||
| Completion | Manual cleanup | Interactive completion action | Archive/Keep/Export prompt |
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
+---------------------------------------------------+
|
||||
| Skill(skill="team-coordinate") |
|
||||
| args="task description" |
|
||||
+-------------------+-------------------------------+
|
||||
|
|
||||
Orchestration Mode (auto -> coordinator)
|
||||
|
|
||||
Coordinator (built-in)
|
||||
Phase 0-5 orchestration
|
||||
|
|
||||
+-------+-------+-------+-------+
|
||||
v v v v v
|
||||
[team-worker agents, each loaded with a dynamic role-spec]
|
||||
(roles generated at runtime from task analysis)
|
||||
|
||||
Subagents (callable by any worker, not team members):
|
||||
[discuss-subagent] - multi-perspective critique (dynamic perspectives)
|
||||
[explore-subagent] - codebase exploration with cache
|
||||
```
|
||||
|
||||
## Role Router
|
||||
|
||||
This skill is **coordinator-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
|
||||
|
||||
### Input Parsing
|
||||
|
||||
Parse `$ARGUMENTS`. No `--role` needed -- always routes to coordinator.
|
||||
|
||||
### Role Registry
|
||||
|
||||
Only coordinator is statically registered. All other roles are dynamic, stored as role-specs in session.
|
||||
|
||||
| Role | File | Type |
|
||||
|------|------|------|
|
||||
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | built-in orchestrator |
|
||||
| (dynamic) | `<session>/role-specs/<role-name>.md` | runtime-generated role-spec |
|
||||
|
||||
### Subagent Registry
|
||||
|
||||
| Subagent | Spec | Callable By | Purpose |
|
||||
|----------|------|-------------|---------|
|
||||
| discuss | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | any role | Multi-perspective critique (dynamic perspectives) |
|
||||
| explore | [subagents/explore-subagent.md](subagents/explore-subagent.md) | any role | Codebase exploration with cache |
|
||||
|
||||
### Dispatch
|
||||
|
||||
Always route to coordinator. Coordinator reads `roles/coordinator/role.md` and executes its phases.
|
||||
|
||||
### Orchestration Mode
|
||||
|
||||
User just provides task description.
|
||||
|
||||
**Invocation**: `Skill(skill="team-coordinate", args="task description")`
|
||||
|
||||
**Lifecycle**:
|
||||
```
|
||||
User provides task description
|
||||
-> coordinator Phase 1: task analysis (detect capabilities, build dependency graph)
|
||||
-> coordinator Phase 2: generate role-specs + initialize session
|
||||
-> coordinator Phase 3: create task chain from dependency graph
|
||||
-> coordinator Phase 4: spawn first batch workers (background) -> STOP
|
||||
-> Worker executes -> SendMessage callback -> coordinator advances next step
|
||||
-> Loop until pipeline complete -> Phase 5 report + completion action
|
||||
```
|
||||
|
||||
**User Commands** (wake paused coordinator):
|
||||
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| `check` / `status` | Output execution status graph, no advancement |
|
||||
| `resume` / `continue` | Check worker states, advance next step |
|
||||
|
||||
---
|
||||
|
||||
## Coordinator Spawn Template
|
||||
|
||||
### v2 Worker Spawn (all roles)
|
||||
|
||||
When coordinator spawns workers, use `team-worker` agent with role-spec path:
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "team-worker",
|
||||
description: "Spawn <role> worker",
|
||||
team_name: <team-name>,
|
||||
name: "<role>",
|
||||
run_in_background: true,
|
||||
prompt: `## Role Assignment
|
||||
role: <role>
|
||||
role_spec: <session-folder>/role-specs/<role>.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: <team-name>
|
||||
requirement: <task-description>
|
||||
inner_loop: <true|false>
|
||||
|
||||
Read role_spec file to load Phase 2-4 domain instructions.
|
||||
Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
|
||||
})
|
||||
```
|
||||
|
||||
**Inner Loop roles** (role has 2+ serial same-prefix tasks): Set `inner_loop: true`. The team-worker agent handles the loop internally.
|
||||
|
||||
**Single-task roles**: Set `inner_loop: false`.
|
||||
|
||||
---
|
||||
|
||||
## Completion Action
|
||||
|
||||
When pipeline completes (all tasks done), coordinator presents an interactive choice:
|
||||
|
||||
```
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Team pipeline complete. What would you like to do?",
|
||||
header: "Completion",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
|
||||
{ label: "Keep Active", description: "Keep session for follow-up work" },
|
||||
{ label: "Export Results", description: "Export deliverables to target directory, then clean" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
### Action Handlers
|
||||
|
||||
| Choice | Steps |
|
||||
|--------|-------|
|
||||
| Archive & Clean | Update session status="completed" -> TeamDelete -> output final summary with artifact paths |
|
||||
| Keep Active | Update session status="paused" -> output: "Resume with: Skill(skill='team-coordinate', args='resume')" |
|
||||
| Export Results | AskUserQuestion(target path) -> copy artifacts to target -> Archive & Clean |
|
||||
|
||||
---
|
||||
|
||||
## Cadence Control
|
||||
|
||||
**Beat model**: Event-driven, each beat = coordinator wake -> process -> spawn -> STOP.
|
||||
|
||||
```
|
||||
Beat Cycle (single beat)
|
||||
======================================================================
|
||||
Event Coordinator Workers
|
||||
----------------------------------------------------------------------
|
||||
callback/resume --> +- handleCallback -+
|
||||
| mark completed |
|
||||
| check pipeline |
|
||||
+- handleSpawnNext -+
|
||||
| find ready tasks |
|
||||
| spawn workers ---+--> [team-worker A] Phase 1-5
|
||||
| (parallel OK) --+--> [team-worker B] Phase 1-5
|
||||
+- STOP (idle) -----+ |
|
||||
|
|
||||
callback <-----------------------------------------+
|
||||
(next beat) SendMessage + TaskUpdate(completed)
|
||||
======================================================================
|
||||
|
||||
Fast-Advance (skips coordinator for simple linear successors)
|
||||
======================================================================
|
||||
[Worker A] Phase 5 complete
|
||||
+- 1 ready task? simple successor? --> spawn team-worker B directly
|
||||
+- complex case? --> SendMessage to coordinator
|
||||
======================================================================
|
||||
```
|
||||
|
||||
**Pipelines are dynamic**: Unlike static pipeline definitions, team-coordinate pipelines are generated per-task from the dependency graph.
|
||||
|
||||
---
|
||||
|
||||
## Session Directory
|
||||
|
||||
```
|
||||
.workflow/.team/TC-<slug>-<date>/
|
||||
+-- team-session.json # Session state + dynamic role registry
|
||||
+-- task-analysis.json # Phase 1 output: capabilities, dependency graph
|
||||
+-- role-specs/ # Dynamic role-spec definitions (generated Phase 2)
|
||||
| +-- <role-1>.md # Lightweight: frontmatter + Phase 2-4 only
|
||||
| +-- <role-2>.md
|
||||
+-- artifacts/ # All MD deliverables from workers
|
||||
| +-- <artifact>.md
|
||||
+-- shared-memory.json # Cross-role state store
|
||||
+-- wisdom/ # Cross-task knowledge
|
||||
| +-- learnings.md
|
||||
| +-- decisions.md
|
||||
| +-- issues.md
|
||||
+-- explorations/ # Shared explore cache
|
||||
| +-- cache-index.json
|
||||
| +-- explore-<angle>.json
|
||||
+-- discussions/ # Inline discuss records
|
||||
| +-- <round>.md
|
||||
+-- .msg/ # Team message bus logs
|
||||
```
|
||||
|
||||
### team-session.json Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "TC-<slug>-<date>",
|
||||
"task_description": "<original user input>",
|
||||
"status": "active | paused | completed",
|
||||
"team_name": "<team-name>",
|
||||
"roles": [
|
||||
{
|
||||
"name": "<role-name>",
|
||||
"prefix": "<PREFIX>",
|
||||
"responsibility_type": "<type>",
|
||||
"inner_loop": false,
|
||||
"role_spec": "role-specs/<role-name>.md"
|
||||
}
|
||||
],
|
||||
"pipeline": {
|
||||
"dependency_graph": {},
|
||||
"tasks_total": 0,
|
||||
"tasks_completed": 0
|
||||
},
|
||||
"active_workers": [],
|
||||
"completed_tasks": [],
|
||||
"completion_action": "interactive",
|
||||
"created_at": "<timestamp>"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Resume
|
||||
|
||||
Coordinator supports `resume` / `continue` for interrupted sessions:
|
||||
|
||||
1. Scan `.workflow/.team/TC-*/team-session.json` for active/paused sessions
|
||||
2. Multiple matches -> AskUserQuestion for selection
|
||||
3. Audit TaskList -> reconcile session state <-> task status
|
||||
4. Reset in_progress -> pending (interrupted tasks)
|
||||
5. Rebuild team and spawn needed workers only
|
||||
6. Create missing tasks with correct blockedBy
|
||||
7. Kick first executable task -> Phase 4 coordination loop
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Unknown command | Error with available command list |
|
||||
| Dynamic role-spec not found | Error, coordinator may need to regenerate |
|
||||
| Command file not found | Fallback to inline execution |
|
||||
| Discuss subagent fails | Worker proceeds without discuss, logs warning |
|
||||
| Explore cache corrupt | Clear cache, re-explore |
|
||||
| Fast-advance spawns wrong task | Coordinator reconciles on next callback |
|
||||
| capability_gap reported | Coordinator generates new role-spec via handleAdapt |
|
||||
| Completion action fails | Default to Keep Active, log warning |
|
||||
Reference in New Issue
Block a user