mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 12:03:49 +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
224
.claude/skills/team-executor-v2/SKILL.md
Normal file
224
.claude/skills/team-executor-v2/SKILL.md
Normal file
@@ -0,0 +1,224 @@
|
||||
---
|
||||
name: team-executor-v2
|
||||
description: Lightweight session execution skill. Resumes existing team-coordinate-v2 sessions for pure execution via team-worker agents. No analysis, no role generation -- only loads and executes. Session path required. Triggers on "team executor v2".
|
||||
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
|
||||
---
|
||||
|
||||
# Team Executor v2
|
||||
|
||||
Lightweight session execution skill: load session -> reconcile state -> spawn team-worker agents -> execute -> deliver. **No analysis, no role generation** -- only executes existing team-coordinate sessions.
|
||||
|
||||
## Key Changes from v1
|
||||
|
||||
| Change | Before (v1) | After (v2) | Impact |
|
||||
|--------|------------|------------|--------|
|
||||
| Worker agent | general-purpose + Skill load | team-worker agent (dedicated) | Eliminates Skill indirection |
|
||||
| Role loading | `<session>/roles/<role>.md` (full role.md) | `<session>/role-specs/<role>.md` (Phase 2-4 only) | Lighter validation |
|
||||
| Shared behavior | Duplicated in SKILL.md | Built into team-worker agent | Single source of truth |
|
||||
| Executor spawn | Skill(team-executor, --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-executor") |
|
||||
| args="--session=<path>" [REQUIRED] |
|
||||
+-------------------+-------------------------------+
|
||||
| Session Validation
|
||||
+---- --session valid? ----+
|
||||
| NO | YES
|
||||
v v
|
||||
Error immediately Orchestration Mode
|
||||
(no session) -> executor
|
||||
|
|
||||
+-------+-------+-------+
|
||||
v v v v
|
||||
[team-worker agents loaded from session role-specs]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Validation (BEFORE routing)
|
||||
|
||||
**CRITICAL**: Session validation MUST occur before any execution.
|
||||
|
||||
### Parse Arguments
|
||||
|
||||
Extract from `$ARGUMENTS`:
|
||||
- `--session=<path>`: Path to team-coordinate session folder (REQUIRED)
|
||||
|
||||
### Validation Steps
|
||||
|
||||
1. **Check `--session` provided**:
|
||||
- If missing -> **ERROR**: "Session required. Usage: --session=<path-to-TC-folder>"
|
||||
|
||||
2. **Validate session structure** (see specs/session-schema.md):
|
||||
- Directory exists at path
|
||||
- `team-session.json` exists and valid JSON
|
||||
- `task-analysis.json` exists and valid JSON
|
||||
- `role-specs/` directory has at least one `.md` file
|
||||
- Each role in `team-session.json#roles` has corresponding `.md` file in `role-specs/`
|
||||
|
||||
3. **Validation failure**:
|
||||
- Report specific missing component
|
||||
- Suggest re-running team-coordinate or checking path
|
||||
|
||||
---
|
||||
|
||||
## Role Router
|
||||
|
||||
This skill is **executor-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
|
||||
|
||||
### Dispatch Logic
|
||||
|
||||
| Scenario | Action |
|
||||
|----------|--------|
|
||||
| No `--session` | **ERROR** immediately |
|
||||
| `--session` invalid | **ERROR** with specific reason |
|
||||
| Valid session | Orchestration Mode -> executor |
|
||||
|
||||
### Orchestration Mode
|
||||
|
||||
**Invocation**: `Skill(skill="team-executor", args="--session=<session-folder>")`
|
||||
|
||||
**Lifecycle**:
|
||||
```
|
||||
Validate session
|
||||
-> executor Phase 0: Reconcile state (reset interrupted, detect orphans)
|
||||
-> executor Phase 1: Spawn first batch team-worker agents (background) -> STOP
|
||||
-> Worker executes -> SendMessage callback -> executor advances next step
|
||||
-> Loop until pipeline complete -> Phase 2 report + completion action
|
||||
```
|
||||
|
||||
**User Commands** (wake paused executor):
|
||||
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| `check` / `status` | Output execution status graph, no advancement |
|
||||
| `resume` / `continue` | Check worker states, advance next step |
|
||||
|
||||
---
|
||||
|
||||
## Role Registry
|
||||
|
||||
| Role | File | Type |
|
||||
|------|------|------|
|
||||
| executor | [roles/executor/role.md](roles/executor/role.md) | built-in orchestrator |
|
||||
| (dynamic) | `<session>/role-specs/<role-name>.md` | loaded from session |
|
||||
|
||||
---
|
||||
|
||||
## Executor Spawn Template
|
||||
|
||||
### v2 Worker Spawn (all roles)
|
||||
|
||||
When executor 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.`
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Completion Action
|
||||
|
||||
When pipeline completes (all tasks done), executor 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-executor', args='--session=<path>')" |
|
||||
| Export Results | AskUserQuestion(target path) -> copy artifacts to target -> Archive & Clean |
|
||||
|
||||
---
|
||||
|
||||
## Cadence Control
|
||||
|
||||
**Beat model**: Event-driven, each beat = executor wake -> process -> spawn -> STOP.
|
||||
|
||||
```
|
||||
Beat Cycle (single beat)
|
||||
======================================================================
|
||||
Event Executor 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 executor for simple linear successors)
|
||||
======================================================================
|
||||
[Worker A] Phase 5 complete
|
||||
+- 1 ready task? simple successor? --> spawn team-worker B directly
|
||||
+- complex case? --> SendMessage to executor
|
||||
======================================================================
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with team-coordinate
|
||||
|
||||
| Scenario | Skill |
|
||||
|----------|-------|
|
||||
| New task, no session | team-coordinate |
|
||||
| Existing session, resume execution | **team-executor** |
|
||||
| Session needs new roles | team-coordinate (with resume) |
|
||||
| Pure execution, no analysis | **team-executor** |
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No --session provided | ERROR immediately with usage message |
|
||||
| Session directory not found | ERROR with path, suggest checking path |
|
||||
| team-session.json missing | ERROR, session incomplete, suggest re-run team-coordinate |
|
||||
| task-analysis.json missing | ERROR, session incomplete, suggest re-run team-coordinate |
|
||||
| No role-specs in session | ERROR, session incomplete, suggest re-run team-coordinate |
|
||||
| Role-spec file not found | ERROR with expected path |
|
||||
| capability_gap reported | Warn only, cannot generate new role-specs |
|
||||
| Fast-advance spawns wrong task | Executor reconciles on next callback |
|
||||
| Completion action fails | Default to Keep Active, log warning |
|
||||
Reference in New Issue
Block a user