mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-25 19:48:33 +08:00
feat: migrate all codex team skills from spawn_agents_on_csv to spawn_agent + wait_agent architecture
- Delete 21 old team skill directories using CSV-wave pipeline pattern (~100+ files) - Delete old team-lifecycle (v3) and team-planex-v2 - Create generic team-worker.toml and team-supervisor.toml (replacing tlv4-specific TOMLs) - Convert 19 team skills from Claude Code format (Agent/SendMessage/TaskCreate) to Codex format (spawn_agent/wait_agent/tasks.json/request_user_input) - Update team-lifecycle-v4 to use generic agent types (team_worker/team_supervisor) - Convert all coordinator role files: dispatch.md, monitor.md, role.md - Convert all worker role files: remove run_in_background, fix Bash syntax - Convert all specs/pipelines.md references - Final state: 20 team skills, 217 .md files, zero Claude Code API residuals Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
catlog22
170
.codex/skills/team-executor/roles/executor/role.md
Normal file
170
.codex/skills/team-executor/roles/executor/role.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# Executor Role
|
||||
|
||||
Orchestrate the team-executor workflow: session validation, state reconciliation, team_worker dispatch, progress monitoring, completion action. The sole built-in role -- all worker roles are loaded from session role-specs and spawned via team_worker agent.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `executor` | **Tag**: `[executor]`
|
||||
- **Responsibility**: Validate session -> Reconcile state -> Create session -> Dispatch team_worker agents -> Monitor progress -> Completion action -> Report results
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Validate session structure before any execution
|
||||
- Reconcile session state with tasks.json on startup
|
||||
- Reset in_progress tasks to pending (interrupted tasks)
|
||||
- Detect fast-advance orphans and reset to pending
|
||||
- Spawn team_worker agents via spawn_agent and wait via wait_agent
|
||||
- Monitor progress via wait_agent and route messages
|
||||
- Maintain session state persistence (tasks.json)
|
||||
- Handle capability_gap reports with warning only (cannot generate role-specs)
|
||||
- Execute completion action when pipeline finishes
|
||||
|
||||
### MUST NOT
|
||||
- Execute task work directly (delegate to workers)
|
||||
- Modify task output artifacts (workers own their deliverables)
|
||||
- Call CLI tools or spawn utility members directly for implementation (code-developer, etc.)
|
||||
- Generate new role-specs (use existing session role-specs only)
|
||||
- Skip session validation
|
||||
- Override consensus_blocked HIGH without user confirmation
|
||||
- Spawn workers with `general-purpose` agent (MUST use `team_worker`)
|
||||
|
||||
> **Core principle**: executor is the orchestrator, not the executor. All actual work is delegated to session-defined worker roles via team_worker agents. Unlike team-coordinate coordinator, executor CANNOT generate new role-specs.
|
||||
|
||||
---
|
||||
|
||||
## Entry Router
|
||||
|
||||
When executor is invoked, first detect the invocation type:
|
||||
|
||||
| Detection | Condition | Handler |
|
||||
|-----------|-----------|---------|
|
||||
| Status check | Arguments contain "check" or "status" | -> handleCheck |
|
||||
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
|
||||
| Capability gap | Message contains "capability_gap" | -> handleAdapt |
|
||||
| Pipeline complete | All tasks completed, no pending/in_progress | -> handleComplete |
|
||||
| New execution | None of above | -> Phase 0 |
|
||||
|
||||
For check/resume/adapt/complete: load `commands/monitor.md` and execute the appropriate handler, then STOP.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Session Validation + State Reconciliation
|
||||
|
||||
**Objective**: Validate session structure and reconcile session state with actual task status.
|
||||
|
||||
### Step 1: Session Validation
|
||||
|
||||
Validate session structure (see SKILL.md Session Validation):
|
||||
- [ ] Directory exists at session path
|
||||
- [ ] `tasks.json` exists and parses
|
||||
- [ ] `task-analysis.json` exists and parses
|
||||
- [ ] `role-specs/` directory has >= 1 .md files
|
||||
- [ ] All roles in tasks.json#roles have corresponding role-spec .md files
|
||||
- [ ] Role-spec files have valid YAML frontmatter + Phase 2-4 sections
|
||||
|
||||
If validation fails -> ERROR with specific reason -> STOP
|
||||
|
||||
### Step 2: Load Session State
|
||||
|
||||
Read tasks.json and task-analysis.json.
|
||||
|
||||
### Step 3: Reconcile with tasks.json
|
||||
|
||||
Compare tasks.json task statuses with session expectations, bidirectional sync.
|
||||
|
||||
### Step 4: Reset Interrupted Tasks
|
||||
|
||||
Reset any in_progress tasks to pending.
|
||||
|
||||
### Step 5: Detect Fast-Advance Orphans
|
||||
|
||||
In_progress tasks without matching active_agents + created > 5 minutes -> reset to pending.
|
||||
|
||||
### Step 6: Create Missing Tasks (if needed)
|
||||
|
||||
For each task in task-analysis, check if exists in tasks.json, create if missing.
|
||||
|
||||
### Step 7: Update Session File
|
||||
|
||||
Write reconciled tasks.json.
|
||||
|
||||
### Step 8: Session Setup
|
||||
|
||||
Initialize session folder if needed.
|
||||
|
||||
**Success**: Session validated, state reconciled, session ready -> Phase 1
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Spawn-and-Wait
|
||||
|
||||
**Objective**: Spawn first batch of ready workers as team_worker agents, wait for completion, then continue.
|
||||
|
||||
**Workflow**:
|
||||
1. Load `commands/monitor.md`
|
||||
2. Find tasks with: status=pending, deps all resolved, owner assigned
|
||||
3. For each ready task -> spawn team_worker via spawn_agent, wait via wait_agent
|
||||
4. Process results, advance pipeline
|
||||
5. Repeat until all tasks complete or pipeline blocked
|
||||
6. Output status summary with execution graph
|
||||
|
||||
**Pipeline advancement** driven by:
|
||||
- Synchronous wait_agent loop (automatic)
|
||||
- User "check" -> handleCheck (status only)
|
||||
- User "resume" -> handleResume (advance)
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Report + Completion Action
|
||||
|
||||
**Objective**: Completion report, interactive completion choice, and follow-up options.
|
||||
|
||||
**Workflow**:
|
||||
1. Load session state -> count completed tasks, duration
|
||||
2. List all deliverables with output paths in `<session>/artifacts/`
|
||||
3. Include discussion summaries (if inline discuss was used)
|
||||
4. Summarize wisdom accumulated during execution
|
||||
5. Output report:
|
||||
|
||||
```
|
||||
[executor] ============================================
|
||||
[executor] TASK COMPLETE
|
||||
[executor]
|
||||
[executor] Deliverables:
|
||||
[executor] - <artifact-1.md> (<producer role>)
|
||||
[executor] - <artifact-2.md> (<producer role>)
|
||||
[executor]
|
||||
[executor] Pipeline: <completed>/<total> tasks
|
||||
[executor] Roles: <role-list>
|
||||
[executor] Duration: <elapsed>
|
||||
[executor]
|
||||
[executor] Session: <session-folder>
|
||||
[executor] ============================================
|
||||
```
|
||||
|
||||
6. **Execute Completion Action** (based on tasks.json completion_action):
|
||||
|
||||
| Mode | Behavior |
|
||||
|------|----------|
|
||||
| `interactive` | request_user_input with Archive/Keep/Export options |
|
||||
| `auto_archive` | Execute Archive & Clean (rm -rf session folder) without prompt |
|
||||
| `auto_keep` | Execute Keep Active without prompt |
|
||||
|
||||
**Interactive handler**: See SKILL.md Completion Action section.
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| Session validation fails | ERROR with specific reason, suggest re-run team-coordinate |
|
||||
| Task timeout | Log, mark failed, ask user to retry or skip |
|
||||
| Worker crash | Reset task to pending in tasks.json, respawn via spawn_agent |
|
||||
| Session corruption | Attempt recovery, fallback to manual reconciliation |
|
||||
| capability_gap reported | handleAdapt: WARN only, cannot generate new role-specs |
|
||||
| Pipeline stall (no ready, no running) | Check for missing tasks, report to user |
|
||||
| Fast-advance conflict | Executor reconciles, no duplicate spawns |
|
||||
| Role-spec file not found | ERROR, cannot proceed without role definition |
|
||||
| Completion action fails | Default to Keep Active, log warning |
|
||||
Reference in New Issue
Block a user