mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
fix(team): use session-id instead of team-name in team_msg across all skills
Root cause: team_msg --team parameter maps directly to filesystem path
.workflow/.team/{value}/.msg/, so using team-name creates wrong directory.
Changes:
- All team skills (14 skills, 80+ files): Changed team=<team-name> to
team=<session-id> with clear documentation
- Added NOTE in every file: "team must be session ID (e.g., TLS-xxx-date),
NOT team name. Extract from Session: field in task description."
- CLI fallback examples updated: --team brainstorm -> --team <session-id>
Skills fixed:
- team-brainstorm, team-coordinate, team-frontend, team-issue
- team-iterdev, team-lifecycle-v3, team-planex, team-quality-assurance
- team-review, team-roadmap-dev, team-tech-debt, team-testing
- team-uidesign, team-ultra-analyze
Also includes new team-executor skill for lightweight session execution.
This commit is contained in:
catlog22
372
.claude/skills/team-executor/SKILL.md
Normal file
372
.claude/skills/team-executor/SKILL.md
Normal file
@@ -0,0 +1,372 @@
|
||||
---
|
||||
name: team-executor
|
||||
description: Lightweight session execution skill. Resumes existing team-coordinate sessions for pure execution. No analysis, no role generation -- only loads and executes. Session path required. Triggers on "team executor".
|
||||
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
|
||||
---
|
||||
|
||||
# Team Executor
|
||||
|
||||
Lightweight session execution skill: load session -> reconcile state -> spawn workers -> execute -> deliver. **No analysis, no role generation** -- only executes existing team-coordinate sessions.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
+---------------------------------------------------+
|
||||
| Skill(skill="team-executor") |
|
||||
| args="--session=<path>" [REQUIRED] |
|
||||
| args="--role=<name>" (for worker dispatch) |
|
||||
+-------------------+-------------------------------+
|
||||
| Session Validation
|
||||
+---- --session valid? ----+
|
||||
| NO | YES
|
||||
v v
|
||||
Error immediately Role Router
|
||||
(no session) |
|
||||
+-------+-------+
|
||||
| --role present?
|
||||
| |
|
||||
YES | | NO
|
||||
v | v
|
||||
Route to | Orchestration Mode
|
||||
session | -> executor
|
||||
role.md |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Validation (BEFORE routing)
|
||||
|
||||
**CRITICAL**: Session validation MUST occur before any role routing.
|
||||
|
||||
### Parse Arguments
|
||||
|
||||
Extract from `$ARGUMENTS`:
|
||||
- `--session=<path>`: Path to team-coordinate session folder (REQUIRED)
|
||||
- `--role=<name>`: Role to dispatch (optional, defaults to orchestration mode)
|
||||
|
||||
### Validation Steps
|
||||
|
||||
1. **Check `--session` provided**:
|
||||
- If missing -> **ERROR**: "Session required. Usage: --session=<path-to-TC-folder>"
|
||||
- Do NOT proceed
|
||||
|
||||
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
|
||||
- `roles/` directory has at least one `.md` file
|
||||
- Each role in `team-session.json#roles` has corresponding `.md` file in `roles/`
|
||||
|
||||
3. **Validation failure**:
|
||||
- Report specific missing component
|
||||
- Suggest re-running team-coordinate or checking path
|
||||
- Do NOT proceed
|
||||
|
||||
### Validation Checklist
|
||||
|
||||
```
|
||||
Session Validation Checklist:
|
||||
[ ] --session argument provided
|
||||
[ ] Directory exists at path
|
||||
[ ] team-session.json exists and parses
|
||||
[ ] task-analysis.json exists and parses
|
||||
[ ] roles/ directory has >= 1 .md files
|
||||
[ ] All session.roles[] have corresponding roles/<role>.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Role Router
|
||||
|
||||
### Dispatch Logic
|
||||
|
||||
| Scenario | Action |
|
||||
|----------|--------|
|
||||
| No `--session` | **ERROR** immediately |
|
||||
| `--session` invalid | **ERROR** with specific reason |
|
||||
| No `--role` | Orchestration Mode -> executor |
|
||||
| `--role=executor` | Read built-in `roles/executor/role.md` |
|
||||
| `--role=<other>` | Read `<session>/roles/<role>.md` |
|
||||
|
||||
### Orchestration Mode
|
||||
|
||||
When invoked without `--role`, executor auto-starts.
|
||||
|
||||
**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 workers (background) -> STOP
|
||||
-> Worker executes -> SendMessage callback -> executor advances next step
|
||||
-> Loop until pipeline complete -> Phase 2 report
|
||||
```
|
||||
|
||||
**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>/roles/<role-name>.md` | loaded from session |
|
||||
|
||||
> **COMPACT PROTECTION**: Role files are execution documents. After context compression, role instructions become summaries only -- **MUST immediately `Read` the role.md to reload before continuing**. Never execute any Phase based on summaries.
|
||||
|
||||
---
|
||||
|
||||
## Shared Infrastructure
|
||||
|
||||
The following templates apply to all worker roles. Each loaded role.md follows the same structure.
|
||||
|
||||
### Worker Phase 1: Task Discovery (all workers shared)
|
||||
|
||||
Each worker on startup executes the same task discovery flow:
|
||||
|
||||
1. Call `TaskList()` to get all tasks
|
||||
2. Filter: subject matches this role's prefix + owner is this role + status is pending + blockedBy is empty
|
||||
3. No tasks -> idle wait
|
||||
4. Has tasks -> `TaskGet` for details -> `TaskUpdate` mark in_progress
|
||||
|
||||
**Resume Artifact Check** (prevent duplicate output after resume):
|
||||
- Check if this task's output artifacts already exist
|
||||
- Artifacts complete -> skip to Phase 5 report completion
|
||||
- Artifacts incomplete or missing -> normal Phase 2-4 execution
|
||||
|
||||
### Worker Phase 5: Report + Fast-Advance (all workers shared)
|
||||
|
||||
Task completion with optional fast-advance to skip executor round-trip:
|
||||
|
||||
1. **Message Bus**: Call `mcp__ccw-tools__team_msg` to log message
|
||||
- Params: operation="log", team=**<session-id>**, from=<role>, to="executor", type=<message-type>, summary="[<role>] <summary>", ref=<artifact-path>
|
||||
- **`team` must be session ID** (e.g., `TC-my-project-2026-02-27`), NOT team name. Extract from task description `Session:` field -> take folder name.
|
||||
- **CLI fallback**: `ccw team log --team <session-id> --from <role> --to executor --type <type> --summary "[<role>] ..." --json`
|
||||
2. **TaskUpdate**: Mark task completed
|
||||
3. **Fast-Advance Check**:
|
||||
- Call `TaskList()`, find pending tasks whose blockedBy are ALL completed
|
||||
- If exactly 1 ready task AND its owner matches a simple successor pattern -> **spawn it directly** (skip executor)
|
||||
- Otherwise -> **SendMessage** to executor for orchestration
|
||||
4. **Loop**: Back to Phase 1 to check for next task
|
||||
|
||||
**Fast-Advance Rules**:
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| Same-prefix successor (Inner Loop role) | Do not spawn, main agent inner loop (Phase 5-L) |
|
||||
| 1 ready task, simple linear successor, different prefix | Spawn directly via Task(run_in_background: true) |
|
||||
| Multiple ready tasks (parallel window) | SendMessage to executor (needs orchestration) |
|
||||
| No ready tasks + others running | SendMessage to executor (status update) |
|
||||
| No ready tasks + nothing running | SendMessage to executor (pipeline may be complete) |
|
||||
|
||||
**Fast-advance failure recovery**: If a fast-advanced task fails, the executor detects it as an orphaned in_progress task on next `resume`/`check` and resets it to pending for re-spawn. Self-healing. See [monitor.md](roles/executor/commands/monitor.md).
|
||||
|
||||
### Worker Inner Loop (roles with multiple same-prefix serial tasks)
|
||||
|
||||
When a role has **2+ serial same-prefix tasks**, it loops internally instead of spawning new agents:
|
||||
|
||||
**Inner Loop flow**:
|
||||
|
||||
```
|
||||
Phase 1: Discover task (first time)
|
||||
|
|
||||
+- Found task -> Phase 2-3: Load context + Execute work
|
||||
| |
|
||||
| v
|
||||
| Phase 4: Validation (+ optional Inline Discuss)
|
||||
| |
|
||||
| v
|
||||
| Phase 5-L: Loop Completion
|
||||
| |
|
||||
| +- TaskUpdate completed
|
||||
| +- team_msg log
|
||||
| +- Accumulate summary to context_accumulator
|
||||
| |
|
||||
| +- More same-prefix tasks?
|
||||
| | +- YES -> back to Phase 1 (inner loop)
|
||||
| | +- NO -> Phase 5-F: Final Report
|
||||
| |
|
||||
| +- Interrupt conditions?
|
||||
| +- consensus_blocked HIGH -> SendMessage -> STOP
|
||||
| +- Errors >= 3 -> SendMessage -> STOP
|
||||
|
|
||||
+- Phase 5-F: Final Report
|
||||
+- SendMessage (all task summaries)
|
||||
+- STOP
|
||||
```
|
||||
|
||||
**Phase 5-L vs Phase 5-F**:
|
||||
|
||||
| Step | Phase 5-L (looping) | Phase 5-F (final) |
|
||||
|------|---------------------|-------------------|
|
||||
| TaskUpdate completed | YES | YES |
|
||||
| team_msg log | YES | YES |
|
||||
| Accumulate summary | YES | - |
|
||||
| SendMessage to executor | NO | YES (all tasks summary) |
|
||||
| Fast-Advance to next prefix | - | YES (check cross-prefix successors) |
|
||||
|
||||
### Wisdom Accumulation (all roles)
|
||||
|
||||
Cross-task knowledge accumulation. Loaded from session at startup.
|
||||
|
||||
**Directory**:
|
||||
```
|
||||
<session-folder>/wisdom/
|
||||
+-- learnings.md # Patterns and insights
|
||||
+-- decisions.md # Design and strategy decisions
|
||||
+-- issues.md # Known risks and issues
|
||||
```
|
||||
|
||||
**Worker load** (Phase 2): Extract `Session: <path>` from task description, read wisdom files.
|
||||
**Worker contribute** (Phase 4/5): Write discoveries to corresponding wisdom files.
|
||||
|
||||
### Role Isolation Rules
|
||||
|
||||
| Allowed | Prohibited |
|
||||
|---------|-----------|
|
||||
| Process own prefix tasks | Process other role's prefix tasks |
|
||||
| SendMessage to executor | Directly communicate with other workers |
|
||||
| Use tools appropriate to responsibility | Create tasks for other roles |
|
||||
| Fast-advance simple successors | Spawn parallel worker batches |
|
||||
| Report capability_gap to executor | Attempt work outside scope |
|
||||
|
||||
Executor additionally prohibited: directly write/modify deliverable artifacts, call implementation subagents directly, directly execute analysis/test/review, generate new roles.
|
||||
|
||||
---
|
||||
|
||||
## 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 ---+--> [Worker A] Phase 1-5
|
||||
| (parallel OK) --+--> [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 Worker B directly
|
||||
+- complex case? --> SendMessage to executor
|
||||
======================================================================
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Executor Spawn Template
|
||||
|
||||
### Standard Worker (single-task role)
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
description: "Spawn <role> worker",
|
||||
team_name: <team-name>,
|
||||
name: "<role>",
|
||||
run_in_background: true,
|
||||
prompt: `You are team "<team-name>" <ROLE>.
|
||||
|
||||
## Primary Instruction
|
||||
All your work MUST be executed by calling Skill to get role definition:
|
||||
Skill(skill="team-executor", args="--role=<role> --session=<session-folder>")
|
||||
|
||||
Current requirement: <task-description>
|
||||
Session: <session-folder>
|
||||
|
||||
## Role Guidelines
|
||||
- Only process <PREFIX>-* tasks, do not execute other role work
|
||||
- All output prefixed with [<role>] tag
|
||||
- Only communicate with executor
|
||||
- Do not use TaskCreate to create tasks for other roles
|
||||
- Before each SendMessage, call mcp__ccw-tools__team_msg to log (team=<session-id> from Session field, NOT team name)
|
||||
- After task completion, check for fast-advance opportunity (see SKILL.md Phase 5)
|
||||
|
||||
## Workflow
|
||||
1. Call Skill -> get role definition and execution logic
|
||||
2. Follow role.md 5-Phase flow
|
||||
3. team_msg(team=<session-id>) + SendMessage results to executor
|
||||
4. TaskUpdate completed -> check next task or fast-advance`
|
||||
})
|
||||
```
|
||||
|
||||
### Inner Loop Worker (multi-task role)
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
description: "Spawn <role> worker (inner loop)",
|
||||
team_name: <team-name>,
|
||||
name: "<role>",
|
||||
run_in_background: true,
|
||||
prompt: `You are team "<team-name>" <ROLE>.
|
||||
|
||||
## Primary Instruction
|
||||
All your work MUST be executed by calling Skill to get role definition:
|
||||
Skill(skill="team-executor", args="--role=<role> --session=<session-folder>")
|
||||
|
||||
Current requirement: <task-description>
|
||||
Session: <session-folder>
|
||||
|
||||
## Inner Loop Mode
|
||||
You will handle ALL <PREFIX>-* tasks in this session, not just the first one.
|
||||
After completing each task, loop back to find the next <PREFIX>-* task.
|
||||
Only SendMessage to executor when:
|
||||
- All <PREFIX>-* tasks are done
|
||||
- A consensus_blocked HIGH occurs
|
||||
- Errors accumulate (>= 3)
|
||||
|
||||
## Role Guidelines
|
||||
- Only process <PREFIX>-* tasks, do not execute other role work
|
||||
- All output prefixed with [<role>] tag
|
||||
- Only communicate with executor
|
||||
- Do not use TaskCreate to create tasks for other roles
|
||||
- Before each SendMessage, call mcp__ccw-tools__team_msg to log (team=<session-id> from Session field, NOT team name)
|
||||
- Use subagent calls for heavy work, retain summaries in context`
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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 roles in session | ERROR, session incomplete, suggest re-run team-coordinate |
|
||||
| Role file not found | ERROR with expected path |
|
||||
| capability_gap reported | Warn only, cannot generate new roles (see monitor.md handleAdapt) |
|
||||
| Fast-advance spawns wrong task | Executor reconciles on next callback |
|
||||
Reference in New Issue
Block a user