Claude-Code-Workflow/.claude/skills/team-executor/specs/session-schema.md

Session Schema

Required session structure for team-executor. All components MUST exist for valid execution.

Directory Structure

<session-folder>/
+-- team-session.json           # Session state + dynamic role registry (REQUIRED)
+-- task-analysis.json          # Task analysis output: capabilities, dependency graph (REQUIRED)
+-- roles/                      # Dynamic role definitions (REQUIRED, >= 1 .md file)
|   +-- <role-1>.md
|   +-- <role-2>.md
+-- artifacts/                  # All MD deliverables from workers
|   +-- <artifact>.md
+-- shared-memory.json          # Cross-role state store
+-- wisdom/                     # Cross-task knowledge
|   +-- learnings.md
|   +-- decisions.md
|   +-- issues.md
+-- explorations/               # Shared explore cache
|   +-- cache-index.json
|   +-- explore-<angle>.json
+-- discussions/                # Inline discuss records
|   +-- <round>.md
+-- .msg/                       # Team message bus logs

Validation Checklist

team-executor validates the following before execution:

Required Components

Component	Validation	Error Message
--session argument	Must be provided	"Session required. Usage: --session="
Directory	Must exist at path	"Session directory not found: "
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

1. Parse --session=<path> from arguments
   +- Not provided -> ERROR: "Session required. Usage: --session=<path-to-TC-folder>"

2. Check directory exists
   +- Not exists -> ERROR: "Session directory not found: <path>"

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 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"
       +- 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

---

team-session.json Schema

{
  "session_id": "TC-<slug>-<date>",
  "task_description": "<original user input>",
  "status": "active | paused | completed",
  "team_name": "<team-name>",
  "roles": [
    {
      "name": "<role-name>",
      "prefix": "<PREFIX>",
      "responsibility_type": "<type>",
      "inner_loop": false,
      "role_file": "roles/<role-name>.md"
    }
  ],
  "pipeline": {
    "dependency_graph": {},
    "tasks_total": 0,
    "tasks_completed": 0
  },
  "active_workers": [],
  "completed_tasks": [],
  "created_at": "<timestamp>"
}

Required Fields

Field	Type	Description
session_id	string	Unique session identifier (e.g., "TC-auth-feature-2026-02-27")
task_description	string	Original task description from user
status	string	One of: "active", "paused", "completed"
team_name	string	Team name for Task tool
roles	array	List of role definitions
roles[].name	string	Role name (must match .md filename)
roles[].prefix	string	Task prefix for this role (e.g., "SPEC", "IMPL")
roles[].role_file	string	Relative path to role file

Optional Fields

Field	Type	Description
pipeline	object	Pipeline metadata
active_workers	array	Currently running workers
completed_tasks	array	List of completed task IDs
created_at	string	ISO timestamp

---

task-analysis.json Schema

{
  "capabilities": [
    {
      "name": "<capability-name>",
      "description": "<description>",
      "artifact_type": "<type>"
    }
  ],
  "dependency_graph": {
    "<task-id>": {
      "depends_on": ["<dependency-task-id>"],
      "role": "<role-name>"
    }
  },
  "roles": [
    {
      "name": "<role-name>",
      "prefix": "<PREFIX>",
      "responsibility_type": "<type>",
      "inner_loop": false
    }
  ],
  "tasks": [
    {
      "id": "<task-id>",
      "subject": "<task-subject>",
      "owner": "<role-name>",
      "blockedBy": ["<dependency-task-id>"]
    }
  ],
  "complexity_score": 0
}

Required Fields

Field	Type	Description
capabilities	array	Detected capabilities
dependency_graph	object	Task dependency DAG
roles	array	Role definitions
tasks	array	Task definitions

---

Role File Schema

Each role file in roles/<role-name>.md must follow the structure defined in team-coordinate/specs/role-template.md.

Minimum Required Sections

Section	Description
# Role: <name>	Header with role name
## Identity	Name, tag, prefix, responsibility
## Boundaries	MUST and MUST NOT rules
## Execution (5-Phase)	Phase 1-5 workflow

Role File Structure Validation

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

---

Example Valid Session

.workflow/.team/TC-auth-feature-2026-02-27/
+-- team-session.json           # Valid JSON with session metadata
+-- task-analysis.json          # Valid JSON with dependency graph
+-- roles/
|   +-- spec-writer.md          # Role file for SPEC-* tasks
|   +-- implementer.md          # Role file for IMPL-* tasks
|   +-- tester.md               # Role file for TEST-* tasks
+-- artifacts/                  # (may be empty)
+-- shared-memory.json          # Valid JSON (may be {})
+-- wisdom/
|   +-- learnings.md
|   +-- decisions.md
|   +-- issues.md
+-- explorations/
|   +-- cache-index.json
+-- discussions/                # (may be empty)
+-- .msg/                       # (may be empty)

---

Recovery from Invalid Sessions

If session validation fails:

1. Missing team-session.json: Re-run team-coordinate with original task
2. Missing task-analysis.json: Re-run team-coordinate with --resume
3. Missing role files: Re-run team-coordinate with --resume
4. Corrupt JSON: Manual inspection or re-run team-coordinate

team-executor cannot fix invalid sessions -- it can only report errors and suggest recovery steps.