mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-05 16:13:08 +08:00
Refactor and optimize templates and code structure
- Deleted outdated templates for epics, product brief, and requirements PRD. - Introduced lazy loading for locale messages in i18n module to enhance performance. - Updated main application bootstrap to parallelize CSRF token fetching and locale loading. - Implemented code splitting for router configuration to optimize bundle size and loading times. - Added WebSocket connection limits and rate limiting to improve server performance and prevent abuse. - Enhanced input validation with compiled regex patterns for better performance and maintainability.
This commit is contained in:
catlog22
@@ -1,372 +0,0 @@
|
||||
---
|
||||
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 |
|
||||
@@ -1,277 +0,0 @@
|
||||
# Command: monitor
|
||||
|
||||
## Purpose
|
||||
|
||||
Event-driven pipeline coordination with Spawn-and-Stop pattern for team-executor. Adapted from team-coordinate monitor.md -- role names are read from `team-session.json#roles` instead of hardcoded. **handleAdapt is LIMITED**: only warns, cannot generate new roles.
|
||||
|
||||
## Constants
|
||||
|
||||
| Constant | Value | Description |
|
||||
|----------|-------|-------------|
|
||||
| SPAWN_MODE | background | All workers spawned via `Task(run_in_background: true)` |
|
||||
| ONE_STEP_PER_INVOCATION | true | Executor does one operation then STOPS |
|
||||
| FAST_ADVANCE_AWARE | true | Workers may skip executor for simple linear successors |
|
||||
| ROLE_GENERATION | disabled | handleAdapt cannot generate new roles |
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Session file | `<session-folder>/team-session.json` | Yes |
|
||||
| Task list | `TaskList()` | Yes |
|
||||
| Active workers | session.active_workers[] | Yes |
|
||||
| Role registry | session.roles[] | Yes |
|
||||
|
||||
**Dynamic role resolution**: Known worker roles are loaded from `session.roles[].name`. This is the same pattern as team-coordinate.
|
||||
|
||||
## Phase 3: Handler Routing
|
||||
|
||||
### Wake-up Source Detection
|
||||
|
||||
Parse `$ARGUMENTS` to determine handler:
|
||||
|
||||
| Priority | Condition | Handler |
|
||||
|----------|-----------|---------|
|
||||
| 1 | Message contains `[<role-name>]` from session roles | handleCallback |
|
||||
| 2 | Contains "capability_gap" | handleAdapt |
|
||||
| 3 | Contains "check" or "status" | handleCheck |
|
||||
| 4 | Contains "resume", "continue", or "next" | handleResume |
|
||||
| 5 | None of the above (initial spawn after dispatch) | handleSpawnNext |
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleCallback
|
||||
|
||||
Worker completed a task. Verify completion, update state, auto-advance.
|
||||
|
||||
```
|
||||
Receive callback from [<role>]
|
||||
+- Find matching active worker by role (from session.roles)
|
||||
+- Is this a progress update (not final)? (Inner Loop intermediate task completion)
|
||||
| +- YES -> Update session state, do NOT remove from active_workers -> STOP
|
||||
+- Task status = completed?
|
||||
| +- YES -> remove from active_workers -> update session
|
||||
| | +- -> handleSpawnNext
|
||||
| +- NO -> progress message, do not advance -> STOP
|
||||
+- No matching worker found
|
||||
+- Scan all active workers for completed tasks
|
||||
+- Found completed -> process each -> handleSpawnNext
|
||||
+- None completed -> STOP
|
||||
```
|
||||
|
||||
**Fast-advance note**: A worker may have already spawned its successor via fast-advance. When processing a callback:
|
||||
1. Check if the expected next task is already `in_progress` (fast-advanced)
|
||||
2. If yes -> skip spawning that task, update active_workers to include the fast-advanced worker
|
||||
3. If no -> normal handleSpawnNext
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleCheck
|
||||
|
||||
Read-only status report. No pipeline advancement.
|
||||
|
||||
**Output format**:
|
||||
|
||||
```
|
||||
[executor] Pipeline Status
|
||||
[executor] Progress: <completed>/<total> (<percent>%)
|
||||
|
||||
[executor] Execution Graph:
|
||||
<visual representation of dependency graph with status icons>
|
||||
|
||||
done=completed >>>=running o=pending .=not created
|
||||
|
||||
[executor] Active Workers:
|
||||
> <subject> (<role>) - running <elapsed> [inner-loop: N/M tasks done]
|
||||
|
||||
[executor] Ready to spawn: <subjects>
|
||||
[executor] Commands: 'resume' to advance | 'check' to refresh
|
||||
```
|
||||
|
||||
**Icon mapping**: completed=done, in_progress=>>>, pending=o, not created=.
|
||||
|
||||
**Graph rendering**: Read dependency_graph from task-analysis.json, render each node with status icon. Show parallel branches side-by-side.
|
||||
|
||||
Then STOP.
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleResume
|
||||
|
||||
Check active worker completion, process results, advance pipeline.
|
||||
|
||||
```
|
||||
Load active_workers from session
|
||||
+- No active workers -> handleSpawnNext
|
||||
+- Has active workers -> check each:
|
||||
+- status = completed -> mark done, log
|
||||
+- status = in_progress -> still running, log
|
||||
+- other status -> worker failure -> reset to pending
|
||||
After processing:
|
||||
+- Some completed -> handleSpawnNext
|
||||
+- All still running -> report status -> STOP
|
||||
+- All failed -> handleSpawnNext (retry)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleSpawnNext
|
||||
|
||||
Find all ready tasks, spawn workers in background, update session, STOP.
|
||||
|
||||
```
|
||||
Collect task states from TaskList()
|
||||
+- completedSubjects: status = completed
|
||||
+- inProgressSubjects: status = in_progress
|
||||
+- readySubjects: pending + all blockedBy in completedSubjects
|
||||
|
||||
Ready tasks found?
|
||||
+- NONE + work in progress -> report waiting -> STOP
|
||||
+- NONE + nothing in progress -> PIPELINE_COMPLETE -> Phase 2
|
||||
+- HAS ready tasks -> for each:
|
||||
+- Is task owner an Inner Loop role AND that role already has an active_worker?
|
||||
| +- YES -> SKIP spawn (existing worker will pick it up via inner loop)
|
||||
| +- NO -> normal spawn below
|
||||
+- TaskUpdate -> in_progress
|
||||
+- team_msg log -> task_unblocked (team=<session-id>, NOT team name)
|
||||
+- Spawn worker (see spawn tool call below)
|
||||
+- Add to session.active_workers
|
||||
Update session file -> output summary -> STOP
|
||||
```
|
||||
|
||||
**Spawn worker tool call** (one per ready task):
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
description: "Spawn <role> worker for <subject>",
|
||||
team_name: <team-name>,
|
||||
name: "<role>",
|
||||
run_in_background: true,
|
||||
prompt: "<worker prompt from SKILL.md Executor Spawn Template>"
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleAdapt (LIMITED)
|
||||
|
||||
Handle mid-pipeline capability gap discovery. **UNLIKE team-coordinate, executor CANNOT generate new roles.**
|
||||
|
||||
```
|
||||
Receive capability_gap from [<role>]
|
||||
+- Log via team_msg (type: warning)
|
||||
+- Report to user:
|
||||
"Capability gap detected: <gap_description>
|
||||
|
||||
team-executor cannot generate new roles.
|
||||
Options:
|
||||
1. Continue with existing roles (worker will skip gap work)
|
||||
2. Re-run team-coordinate with --resume=<session> to extend session
|
||||
3. Manually add role to <session>/roles/ and retry"
|
||||
+- Extract: gap_description, requesting_role, suggested_capability
|
||||
+- Validate gap is genuine:
|
||||
+- Check existing roles in session.roles -> does any role cover this?
|
||||
| +- YES -> redirect: SendMessage to that role's owner -> STOP
|
||||
| +- NO -> genuine gap, report to user (cannot fix)
|
||||
+- Do NOT generate new role
|
||||
+- Continue execution with existing roles
|
||||
```
|
||||
|
||||
**Key difference from team-coordinate**:
|
||||
| Aspect | team-coordinate | team-executor |
|
||||
|--------|-----------------|---------------|
|
||||
| handleAdapt | Generates new role, creates tasks, spawns worker | Only warns, cannot fix |
|
||||
| Recovery | Automatic | Manual (re-run team-coordinate) |
|
||||
|
||||
---
|
||||
|
||||
### Worker Failure Handling
|
||||
|
||||
When a worker has unexpected status (not completed, not in_progress):
|
||||
|
||||
1. Reset task -> pending via TaskUpdate
|
||||
2. Log via team_msg (type: error)
|
||||
3. Report to user: task reset, will retry on next resume
|
||||
|
||||
### Fast-Advance Failure Recovery
|
||||
|
||||
When executor detects a fast-advanced task has failed (task in_progress but no callback and worker gone):
|
||||
|
||||
```
|
||||
handleCallback / handleResume detects:
|
||||
+- Task is in_progress (was fast-advanced by predecessor)
|
||||
+- No active_worker entry for this task
|
||||
+- Original fast-advancing worker has already completed and exited
|
||||
+- Resolution:
|
||||
1. TaskUpdate -> reset task to pending
|
||||
2. Remove stale active_worker entry (if any)
|
||||
3. Log via team_msg (type: error, summary: "Fast-advanced task <ID> failed, resetting for retry")
|
||||
4. -> handleSpawnNext (will re-spawn the task normally)
|
||||
```
|
||||
|
||||
**Detection in handleResume**:
|
||||
|
||||
```
|
||||
For each in_progress task in TaskList():
|
||||
+- Has matching active_worker? -> normal, skip
|
||||
+- No matching active_worker? -> orphaned (likely fast-advance failure)
|
||||
+- Check creation time: if > 5 minutes with no progress callback
|
||||
+- Reset to pending -> handleSpawnNext
|
||||
```
|
||||
|
||||
**Prevention**: Fast-advance failures are self-healing. The executor reconciles orphaned tasks on every `resume`/`check` cycle.
|
||||
|
||||
### Consensus-Blocked Handling
|
||||
|
||||
When a worker reports `consensus_blocked` in its callback:
|
||||
|
||||
```
|
||||
handleCallback receives message with consensus_blocked flag
|
||||
+- Extract: divergence_severity, blocked_round, action_recommendation
|
||||
+- Route by severity:
|
||||
|
|
||||
+- severity = HIGH
|
||||
| +- Create REVISION task:
|
||||
| +- Same role, same doc type, incremented suffix (e.g., DRAFT-001-R1)
|
||||
| +- Description includes: divergence details + action items from discuss
|
||||
| +- blockedBy: none (immediate execution)
|
||||
| +- Max 1 revision per task (DRAFT-001 -> DRAFT-001-R1, no R2)
|
||||
| +- If already revised once -> PAUSE, escalate to user
|
||||
| +- Update session: mark task as "revised", log revision chain
|
||||
|
|
||||
+- severity = MEDIUM
|
||||
| +- Proceed with warning: include divergence in next task's context
|
||||
| +- Log action items to wisdom/issues.md
|
||||
| +- Normal handleSpawnNext
|
||||
|
|
||||
+- severity = LOW
|
||||
+- Proceed normally: treat as consensus_reached with notes
|
||||
+- Normal handleSpawnNext
|
||||
```
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
| Check | Criteria |
|
||||
|-------|----------|
|
||||
| Session state consistent | active_workers matches TaskList in_progress tasks |
|
||||
| No orphaned tasks | Every in_progress task has an active_worker entry |
|
||||
| Dynamic roles valid | All task owners exist in session.roles |
|
||||
| Completion detection | readySubjects=0 + inProgressSubjects=0 -> PIPELINE_COMPLETE |
|
||||
| Fast-advance tracking | Detect tasks already in_progress via fast-advance, sync to active_workers |
|
||||
| Fast-advance orphan check | in_progress tasks without active_worker entry -> reset to pending |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Session file not found | Error, suggest re-run team-coordinate |
|
||||
| Worker callback from unknown role | Log info, scan for other completions |
|
||||
| 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 |
|
||||
| Dynamic role file not found | Error, cannot proceed without role definition |
|
||||
| capability_gap from role | WARN only, cannot generate new roles |
|
||||
| consensus_blocked HIGH | Create revision task (max 1) or pause for user |
|
||||
| consensus_blocked MEDIUM | Proceed with warning, log to wisdom/issues.md |
|
||||
@@ -1,202 +0,0 @@
|
||||
# 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 |
|
||||
@@ -1,272 +0,0 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user