From 93041402f213bc23cb41fabafeac61f33651aa63 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Fri, 27 Feb 2026 18:51:21 +0800 Subject: [PATCH] feat: add team-executor skill with enhanced validation - Create team-executor skill for resuming existing team-coordinate sessions - Add SKILL.md with role router and session validation - Add roles/executor/role.md with simplified coordinator lifecycle - Add commands/monitor.md with LIMITED handleAdapt (no role generation) - Add specs/session-schema.md with comprehensive validation Enhancements from code review: - Add role file structural validation (required sections check) - Add JSON schema field validation for team-session.json and task-analysis.json - Add 5-role limit enforcement in handleAdapt (team-coordinate) --- .../roles/coordinator/commands/monitor.md | 22 +++++++ .../team-executor/specs/session-schema.md | 57 +++++++++++++++++-- 2 files changed, 73 insertions(+), 6 deletions(-) diff --git a/.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md b/.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md index 9f4cd977..50894c82 100644 --- a/.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md +++ b/.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md @@ -157,6 +157,8 @@ Task({ Handle mid-pipeline capability gap discovery. A worker reports `capability_gap` when it encounters work outside its scope. +**CONSTRAINT**: Maximum 5 worker roles per session (per coordinator/role.md). handleAdapt MUST enforce this limit. + ``` Parse capability_gap message: +- Extract: gap_description, requesting_role, suggested_capability @@ -164,6 +166,25 @@ Parse capability_gap message: +- Check existing roles in session.roles -> does any role cover this? | +- YES -> redirect: SendMessage to that role's owner -> STOP | +- NO -> genuine gap, proceed to role generation + +- CHECK ROLE COUNT LIMIT (MAX 5 ROLES): + +- Count current roles in session.roles + +- If count >= 5: + +- Attempt to merge new capability into existing role: + +- Find best-fit role by responsibility_type + +- If merge possible: + +- Update existing role file with new capability + +- Create task assigned to existing role + +- Log via team_msg (type: warning, summary: "Capability merged into existing role") + +- STOP + +- If merge NOT possible: + +- PAUSE session + +- Report to user: + "Role limit (5) reached. Cannot generate new role for: + Options: + 1. Manually extend an existing role + 2. Re-run team-coordinate with refined task to consolidate roles + 3. Accept limitation and continue without this capability" + +- STOP +- Generate new role: 1. Read specs/role-template.md 2. Fill template with capability details from gap description @@ -270,5 +291,6 @@ handleCallback receives message with consensus_blocked flag | Fast-advance task orphaned | Reset to pending, re-spawn via handleSpawnNext | | Dynamic role file not found | Error, coordinator must regenerate from task-analysis | | capability_gap from completed role | Validate gap, generate role if genuine | +| capability_gap when role limit (5) reached | Attempt merge into existing role, else pause for user | | consensus_blocked HIGH | Create revision task (max 1) or pause for user | | consensus_blocked MEDIUM | Proceed with warning, log to wisdom/issues.md | diff --git a/.claude/skills/team-executor/specs/session-schema.md b/.claude/skills/team-executor/specs/session-schema.md index b1f047ee..260f7831 100644 --- a/.claude/skills/team-executor/specs/session-schema.md +++ b/.claude/skills/team-executor/specs/session-schema.md @@ -36,10 +36,11 @@ team-executor validates the following before execution: |-----------|------------|---------------| | `--session` argument | Must be provided | "Session required. Usage: --session=" | | Directory | Must exist at path | "Session directory not found: " | -| `team-session.json` | Must exist and parse as JSON | "Invalid session: team-session.json missing or corrupt" | -| `task-analysis.json` | Must exist and parse as JSON | "Invalid session: task-analysis.json missing or corrupt" | +| `team-session.json` | Must exist, parse as JSON, and contain all required fields | "Invalid session: team-session.json missing, corrupt, or missing required fields" | +| `task-analysis.json` | Must exist, parse as JSON, and contain all required fields | "Invalid session: task-analysis.json missing, corrupt, or missing required fields" | | `roles/` directory | Must exist and contain >= 1 .md file | "Invalid session: no role files in roles/" | | Role file mapping | Each role in team-session.json#roles must have .md file | "Role file not found: roles/.md" | +| Role file structure | Each role .md must contain required headers | "Invalid role file: roles/.md missing required section:
" | ### Validation Algorithm @@ -53,19 +54,33 @@ team-executor validates the following before execution: 3. Check team-session.json +- Not exists -> ERROR: "Invalid session: team-session.json missing" +- Parse error -> ERROR: "Invalid session: team-session.json corrupt" + +- Validate required fields: + +- session_id (string) -> missing/invalid -> ERROR: "team-session.json missing required field: session_id" + +- task_description (string) -> missing -> ERROR: "team-session.json missing required field: task_description" + +- status (string: active|paused|completed) -> missing/invalid -> ERROR: "team-session.json has invalid status" + +- team_name (string) -> missing -> ERROR: "team-session.json missing required field: team_name" + +- roles (array) -> missing/empty -> ERROR: "team-session.json missing or empty roles array" 4. Check task-analysis.json +- Not exists -> ERROR: "Invalid session: task-analysis.json missing" +- Parse error -> ERROR: "Invalid session: task-analysis.json corrupt" + +- Validate required fields: + +- capabilities (array) -> missing -> ERROR: "task-analysis.json missing required field: capabilities" + +- dependency_graph (object) -> missing -> ERROR: "task-analysis.json missing required field: dependency_graph" + +- roles (array) -> missing/empty -> ERROR: "task-analysis.json missing or empty roles array" + +- tasks (array) -> missing/empty -> ERROR: "task-analysis.json missing or empty tasks array" 5. Check roles/ directory +- Not exists -> ERROR: "Invalid session: roles/ directory missing" +- No .md files -> ERROR: "Invalid session: no role files in roles/" -6. Check role file mapping +6. Check role file mapping and structure +- For each role in team-session.json#roles: +- Check roles/.md exists - +- Not exists -> ERROR: "Role file not found: roles/.md" + +- Not exists -> ERROR: "Role file not found: roles/.md" + +- Validate role file structure (see Role File Structure Validation): + +- Check for required headers: "# Role:", "## Identity", "## Boundaries", "## Execution" + +- Missing header -> ERROR: "Invalid role file: roles/.md missing required section:
" 7. All checks pass -> proceed to Phase 0 ``` @@ -185,9 +200,39 @@ Each role file in `roles/.md` must follow the structure defined in `t | `## Boundaries` | MUST and MUST NOT rules | | `## Execution (5-Phase)` | Phase 1-5 workflow | -### Validation +### Role File Structure Validation -Role files are not validated for structure, only for existence. If a role file is malformed, the worker will fail at runtime. +Role files MUST be validated for structure before execution. This catches malformed role files early and provides actionable error messages. + +**Required Sections** (must be present in order): + +| Section | Pattern | Purpose | +|---------|---------|---------| +| Role Header | `# Role: ` | Identifies the role definition | +| Identity | `## Identity` | Defines name, tag, prefix, responsibility | +| Boundaries | `## Boundaries` | Defines MUST and MUST NOT rules | +| Execution | `## Execution` | Defines the 5-Phase workflow | + +**Validation Algorithm**: + +``` +For each role file in roles/.md: + 1. Read file content + 2. Check for "# Role:" header + +- Not found -> ERROR: "Invalid role file: roles/.md missing role header" + 3. Check for "## Identity" section + +- Not found -> ERROR: "Invalid role file: roles/.md missing required section: Identity" + 4. Check for "## Boundaries" section + +- Not found -> ERROR: "Invalid role file: roles/.md missing required section: Boundaries" + 5. Check for "## Execution" section (or "## Execution (5-Phase)") + +- Not found -> ERROR: "Invalid role file: roles/.md missing required section: Execution" + 6. All checks pass -> role file valid +``` + +**Benefits**: +- Early detection of malformed role files +- Clear error messages for debugging +- Prevents runtime failures during worker execution ---