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)

.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: <gap_description>
+                      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 |

.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=<path-to-TC-folder>" |
 | Directory | Must exist at path | "Session directory not found: <path>" |
-| `team-session.json` | Must exist and parse as JSON | "Invalid session: team-session.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 and parse as JSON | "Invalid session: task-analysis.json missing or corrupt" |
+| `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/<role>.md" |
+| Role file structure | Each role .md must contain required headers | "Invalid role file: roles/<role>.md missing required section: <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/<role.name>.md exists
-       +- Not exists -> ERROR: "Role file not found: roles/<role.name>.md"
+           +- Not exists -> ERROR: "Role file not found: roles/<role.name>.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/<role.name>.md missing required section: <section>"
 
 7. All checks pass -> proceed to Phase 0
 ```
@@ -185,9 +200,39 @@ Each role file in `roles/<role-name>.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: <name>` | 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/<role>.md:
+  1. Read file content
+  2. Check for "# Role:" header
+     +- Not found -> ERROR: "Invalid role file: roles/<role>.md missing role header"
+  3. Check for "## Identity" section
+     +- Not found -> ERROR: "Invalid role file: roles/<role>.md missing required section: Identity"
+  4. Check for "## Boundaries" section
+     +- Not found -> ERROR: "Invalid role file: roles/<role>.md missing required section: Boundaries"
+  5. Check for "## Execution" section (or "## Execution (5-Phase)")
+     +- Not found -> ERROR: "Invalid role file: roles/<role>.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
 
 ---