claude-code-workflow 6.3.53 → 7.0.0

package/.claude/skills/team-executor/roles/executor/role.md

@@ -0,0 +1,202 @@
+# Executor Role
+
+Orchestrate the team-executor workflow: session validation, state reconciliation, worker dispatch, progress monitoring, session state. The sole built-in role -- all worker roles are loaded from the session.
+
+## Identity
+
+- **Name**: `executor` | **Tag**: `[executor]`
+- **Responsibility**: Validate session -> Reconcile state -> Create team -> Dispatch tasks -> Monitor progress -> Report results
+
+## Boundaries
+
+### MUST
+- Validate session structure before any execution
+- Reconcile session state with TaskList on startup
+- Reset in_progress tasks to pending (interrupted tasks)
+- Detect fast-advance orphans and reset to pending
+- Spawn worker subagents in background
+- Monitor progress via worker callbacks and route messages
+- Maintain session state persistence (team-session.json)
+- Handle capability_gap reports with warning only (cannot generate roles)
+
+### MUST NOT
+- Execute task work directly (delegate to workers)
+- Modify task output artifacts (workers own their deliverables)
+- Call implementation subagents (code-developer, etc.) directly
+- Generate new roles (use existing session roles only)
+- Skip session validation
+- Override consensus_blocked HIGH without user confirmation
+
+> **Core principle**: executor is the orchestrator, not the executor. All actual work is delegated to session-defined worker roles. Unlike team-coordinate coordinator, executor CANNOT generate new roles.
+
+---
+
+## Entry Router
+
+When executor is invoked, first detect the invocation type:
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Worker callback | Message contains `[role-name]` from session roles | -> handleCallback |
+| Status check | Arguments contain "check" or "status" | -> handleCheck |
+| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
+| Capability gap | Message contains "capability_gap" | -> handleAdapt |
+| New execution | None of above | -> Phase 0 |
+
+For callback/check/resume/adapt: 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.
+
+**Workflow**:
+
+### Step 1: Session Validation
+
+Validate session structure (see SKILL.md Session Validation):
+- [ ] Directory exists at session path
+- [ ] `team-session.json` exists and parses
+- [ ] `task-analysis.json` exists and parses
+- [ ] `roles/` directory has >= 1 .md files
+- [ ] All roles in team-session.json#roles have corresponding .md files
+
+If validation fails -> ERROR with specific reason -> STOP
+
+### Step 2: Load Session State
+
+```javascript
+session = Read(<session-folder>/team-session.json)
+taskAnalysis = Read(<session-folder>/task-analysis.json)
+```
+
+### Step 3: Reconcile with TaskList
+
+```
+Call TaskList() -> get real status of all tasks
+Compare with session.completed_tasks:
+  +- Tasks in TaskList.completed but not in session -> add to session.completed_tasks
+  +- Tasks in session.completed_tasks but not TaskList.completed -> remove from session.completed_tasks (anomaly, log warning)
+  +- Tasks in TaskList.in_progress -> candidate for reset
+```
+
+### Step 4: Reset Interrupted Tasks
+
+```
+For each task in TaskList.in_progress:
+  +- Reset to pending via TaskUpdate
+  +- Log via team_msg (type: warning, summary: "Task <ID> reset from interrupted state")
+```
+
+### Step 5: Detect Fast-Advance Orphans
+
+```
+For each task in TaskList.in_progress:
+  +- Check if has matching active_worker entry
+  +- No matching active_worker + created > 5 minutes ago -> orphan
+      +- Reset to pending via TaskUpdate
+      +- Log via team_msg (type: error, summary: "Fast-advance orphan <ID> reset")
+```
+
+### Step 6: Create Missing Tasks (if needed)
+
+```
+For each task in task-analysis.json#tasks:
+  +- Check if exists in TaskList
+  +- Not exists -> create via TaskCreate with correct blockedBy
+```
+
+### Step 7: Update Session File
+
+```
+Write updated team-session.json with:
+  +- reconciled completed_tasks
+  +- cleared active_workers (will be rebuilt on spawn)
+  +- status = "active"
+```
+
+### Step 8: Team Setup
+
+```
+Check if team exists (via TaskList with team_name filter)
+  +- Not exists -> TeamCreate with team_name from session
+  +- Exists -> continue with existing team
+```
+
+**Success**: Session validated, state reconciled, team ready -> Phase 1
+
+---
+
+## Phase 1: Spawn-and-Stop
+
+**Objective**: Spawn first batch of ready workers in background, then STOP.
+
+**Design**: Spawn-and-Stop + Callback pattern, with worker fast-advance.
+- Spawn workers with `Task(run_in_background: true)` -> immediately return
+- Worker completes -> may fast-advance to next task OR SendMessage callback -> auto-advance
+- User can use "check" / "resume" to manually advance
+- Executor does one operation per invocation, then STOPS
+
+**Workflow**:
+1. Load `commands/monitor.md`
+2. Find tasks with: status=pending, blockedBy all resolved, owner assigned
+3. For each ready task -> spawn worker (see SKILL.md Executor Spawn Template)
+   - Use Standard Worker template for single-task roles
+   - Use Inner Loop Worker template for multi-task roles
+4. Output status summary with execution graph
+5. STOP
+
+**Pipeline advancement** driven by three wake sources:
+- Worker callback (automatic) -> Entry Router -> handleCallback
+- User "check" -> handleCheck (status only)
+- User "resume" -> handleResume (advance)
+
+---
+
+## Phase 2: Report + Next Steps
+
+**Objective**: Completion report 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. Update session status -> "completed"
+6. Offer next steps: exit / view artifacts / extend with additional tasks
+
+**Output format**:
+
+```
+[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] ============================================
+```
+
+---
+
+## 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 | Respawn worker, reassign task |
+| Session corruption | Attempt recovery, fallback to manual reconciliation |
+| capability_gap reported | handleAdapt: WARN only, cannot generate new roles |
+| All workers still running on resume | Report status, suggest check later |
+| Pipeline stall (no ready, no running) | Check for missing tasks, report to user |
+| Fast-advance conflict | Executor reconciles, no duplicate spawns |
+| Fast-advance task orphaned | Reset to pending, re-spawn via handleSpawnNext |
+| Role file not found | ERROR, cannot proceed without role definition |

package/.claude/skills/team-executor/specs/session-schema.md

@@ -0,0 +1,272 @@
+# 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=<path-to-TC-folder>" |
+| Directory | Must exist at path | "Session directory not found: <path>" |
+| `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/<role>.md" |
+| Role file structure | Each role .md must contain required headers | "Invalid role file: roles/<role>.md missing required section: <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
+
+```json
+{
+  "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
+
+```json
+{
+  "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.

package/.claude/skills/team-executor-v2/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: team-executor-v2
+description: Lightweight session execution skill. Resumes existing team-coordinate-v2 sessions for pure execution via team-worker agents. No analysis, no role generation -- only loads and executes. Session path required. Triggers on "team executor v2".
+allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
+---
+
+# Team Executor v2
+
+Lightweight session execution skill: load session -> reconcile state -> spawn team-worker agents -> execute -> deliver. **No analysis, no role generation** -- only executes existing team-coordinate sessions.
+
+
+## Architecture
+
+```
++---------------------------------------------------+
+|  Skill(skill="team-executor")                      |
+|  args="--session=<path>" [REQUIRED]                |
++-------------------+-------------------------------+
+                    | Session Validation
+         +---- --session valid? ----+
+         | NO                       | YES
+         v                          v
+    Error immediately          Orchestration Mode
+    (no session)               -> executor
+                                    |
+                    +-------+-------+-------+
+                    v       v       v       v
+                 [team-worker agents loaded from session role-specs]
+```
+
+---
+
+## Session Validation (BEFORE routing)
+
+**CRITICAL**: Session validation MUST occur before any execution.
+
+### Parse Arguments
+
+Extract from `$ARGUMENTS`:
+- `--session=<path>`: Path to team-coordinate session folder (REQUIRED)
+
+### Validation Steps
+
+1. **Check `--session` provided**:
+   - If missing -> **ERROR**: "Session required. Usage: --session=<path-to-TC-folder>"
+
+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
+   - `role-specs/` directory has at least one `.md` file
+   - Each role in `team-session.json#roles` has corresponding `.md` file in `role-specs/`
+
+3. **Validation failure**:
+   - Report specific missing component
+   - Suggest re-running team-coordinate or checking path
+
+---
+
+## Role Router
+
+This skill is **executor-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
+
+### Dispatch Logic
+
+| Scenario | Action |
+|----------|--------|
+| No `--session` | **ERROR** immediately |
+| `--session` invalid | **ERROR** with specific reason |
+| Valid session | Orchestration Mode -> executor |
+
+### Orchestration Mode
+
+**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 team-worker agents (background) -> STOP
+  -> Worker executes -> SendMessage callback -> executor advances next step
+  -> Loop until pipeline complete -> Phase 2 report + completion action
+```
+
+**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>/role-specs/<role-name>.md` | loaded from session |
+
+---
+
+## Executor Spawn Template
+
+### v2 Worker Spawn (all roles)
+
+When executor spawns workers, use `team-worker` agent with role-spec path:
+
+```
+Task({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker",
+  team_name: <team-name>,
+  name: "<role>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: <role>
+role_spec: <session-folder>/role-specs/<role>.md
+session: <session-folder>
+session_id: <session-id>
+team_name: <team-name>
+requirement: <task-description>
+inner_loop: <true|false>
+
+Read role_spec file to load Phase 2-4 domain instructions.`
+})
+```
+
+---
+
+## Completion Action
+
+When pipeline completes (all tasks done), executor presents an interactive choice:
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Team pipeline complete. What would you like to do?",
+    header: "Completion",
+    multiSelect: false,
+    options: [
+      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
+      { label: "Keep Active", description: "Keep session for follow-up work" },
+      { label: "Export Results", description: "Export deliverables to target directory, then clean" }
+    ]
+  }]
+})
+```
+
+### Action Handlers
+
+| Choice | Steps |
+|--------|-------|
+| Archive & Clean | Update session status="completed" -> TeamDelete -> output final summary with artifact paths |
+| Keep Active | Update session status="paused" -> output: "Resume with: Skill(skill='team-executor', args='--session=<path>')" |
+| Export Results | AskUserQuestion(target path) -> copy artifacts to target -> Archive & Clean |
+
+---
+
+## 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 ---+--> [team-worker A] Phase 1-5
+                      |  (parallel OK)  --+--> [team-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 team-worker B directly
+    +- complex case? --> SendMessage to executor
+======================================================================
+```
+
+---
+
+## 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 role-specs in session | ERROR, session incomplete, suggest re-run team-coordinate |
+| Role-spec file not found | ERROR with expected path |
+| capability_gap reported | Warn only, cannot generate new role-specs |
+| Fast-advance spawns wrong task | Executor reconciles on next callback |
+| Completion action fails | Default to Keep Active, log warning |