maestro-flow 0.2.0 → 0.2.2

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

@@ -0,0 +1,171 @@
+# Executor Role
+
+Orchestrate the team-executor workflow: session validation, state reconciliation, team-worker dispatch, progress monitoring, completion action. The sole built-in role -- all worker roles are loaded from session role-specs and spawned via team-worker agent.
+
+## Identity
+
+- **Name**: `executor` | **Tag**: `[executor]`
+- **Responsibility**: Validate session -> Reconcile state -> Create team -> Dispatch team-worker agents -> Monitor progress -> Completion action -> 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 team-worker agents in background (NOT general-purpose)
+- Monitor progress via worker callbacks and route messages
+- Maintain session state persistence (team-session.json)
+- Handle capability_gap reports with warning only (cannot generate role-specs)
+- Execute completion action when pipeline finishes
+
+### MUST NOT
+- Execute task work directly (delegate to workers)
+- Modify task output artifacts (workers own their deliverables)
+- Call CLI tools or spawn utility members directly for implementation (code-developer, etc.)
+- Generate new role-specs (use existing session role-specs only)
+- Skip session validation
+- Override consensus_blocked HIGH without user confirmation
+- Spawn workers with `general-purpose` agent (MUST use `team-worker`)
+
+> **Core principle**: executor is the orchestrator, not the executor. All actual work is delegated to session-defined worker roles via team-worker agents. Unlike team-coordinate coordinator, executor CANNOT generate new role-specs.
+
+---
+
+## 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 |
+| Pipeline complete | All tasks completed, no pending/in_progress | -> handleComplete |
+| New execution | None of above | -> Phase 0 |
+
+For callback/check/resume/adapt/complete: 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.
+
+### 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
+- [ ] `role-specs/` directory has >= 1 .md files
+- [ ] All roles in team-session.json#roles have corresponding role-spec .md files
+- [ ] Role-spec files have valid YAML frontmatter + Phase 2-4 sections
+
+If validation fails -> ERROR with specific reason -> STOP
+
+### Step 2: Load Session State
+
+Read team-session.json and task-analysis.json.
+
+### Step 3: Reconcile with TaskList
+
+Compare TaskList() with session.completed_tasks, bidirectional sync.
+
+### Step 4: Reset Interrupted Tasks
+
+Reset any in_progress tasks to pending.
+
+### Step 5: Detect Fast-Advance Orphans
+
+In_progress tasks without matching active_worker + created > 5 minutes -> reset to pending.
+
+### Step 6: Create Missing Tasks (if needed)
+
+For each task in task-analysis, check if exists in TaskList, create if missing.
+
+### Step 7: Update Session File
+
+Write reconciled team-session.json.
+
+### Step 8: Team Setup
+
+TeamCreate if team does not exist.
+
+**Success**: Session validated, state reconciled, team ready -> Phase 1
+
+---
+
+## Phase 1: Spawn-and-Stop
+
+**Objective**: Spawn first batch of ready workers as team-worker agents in background, then STOP.
+
+**Workflow**:
+1. Load `commands/monitor.md`
+2. Find tasks with: status=pending, blockedBy all resolved, owner assigned
+3. For each ready task -> spawn team-worker (see SKILL.md Executor Spawn Template)
+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 + Completion Action
+
+**Objective**: Completion report, interactive completion choice, 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. Output report:
+
+```
+[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] ============================================
+```
+
+6. **Execute Completion Action** (based on session.completion_action):
+
+| Mode | Behavior |
+|------|----------|
+| `interactive` | AskUserQuestion with Archive/Keep/Export options |
+| `auto_archive` | Execute Archive & Clean without prompt |
+| `auto_keep` | Execute Keep Active without prompt |
+
+**Interactive handler**: See SKILL.md Completion Action section.
+
+---
+
+## 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 role-specs |
+| 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 |
+| Role-spec file not found | ERROR, cannot proceed without role definition |
+| Completion action fails | Default to Keep Active, log warning |

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

@@ -0,0 +1,264 @@
+# Session Schema
+
+Required session structure for team-executor v2. All components MUST exist for valid execution. Updated for role-spec architecture (lightweight Phase 2-4 files instead of full role.md files).
+
+## Directory Structure
+
+```
+<session-folder>/
++-- team-session.json           # Session state + dynamic role registry (REQUIRED)
++-- task-analysis.json          # Task analysis output: capabilities, dependency graph (REQUIRED)
++-- role-specs/                 # Dynamic role-spec definitions (REQUIRED, >= 1 .md file)
+|   +-- <role-1>.md             # Lightweight: YAML frontmatter + Phase 2-4 only
+|   +-- <role-2>.md
++-- artifacts/                  # All MD deliverables from workers
+|   +-- <artifact>.md
++-- .msg/                       # Team message bus + state
+|   +-- messages.jsonl          # Message log
+|   +-- meta.json               # Session metadata + cross-role state
++-- 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
+```
+
+## 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" |
+| `role-specs/` directory | Must exist and contain >= 1 .md file | "Invalid session: no role-spec files in role-specs/" |
+| Role-spec file mapping | Each role in team-session.json#roles must have .md file | "Role-spec file not found: role-specs/<role>.md" |
+| Role-spec structure | Each role-spec must have YAML frontmatter + Phase 2-4 sections | "Invalid role-spec: role-specs/<role>.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 -> ERROR
+       +- task_description (string) -> missing -> ERROR
+       +- status (string: active|paused|completed) -> invalid -> ERROR
+       +- team_name (string) -> missing -> ERROR
+       +- roles (array, non-empty) -> missing/empty -> ERROR
+
+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
+       +- dependency_graph (object) -> missing -> ERROR
+       +- roles (array, non-empty) -> missing/empty -> ERROR
+
+5. Check role-specs/ directory
+   +- Not exists -> ERROR: "Invalid session: role-specs/ directory missing"
+   +- No .md files -> ERROR: "Invalid session: no role-spec files in role-specs/"
+
+6. Check role-spec file mapping and structure
+   +- For each role in team-session.json#roles:
+       +- Check role-specs/<role.name>.md exists
+           +- Not exists -> ERROR: "Role-spec file not found: role-specs/<role.name>.md"
+       +- Validate role-spec structure (see Role-Spec Structure Validation)
+
+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_spec": "role-specs/<role-name>.md"
+    }
+  ],
+  "pipeline": {
+    "dependency_graph": {},
+    "tasks_total": 0,
+    "tasks_completed": 0
+  },
+  "active_workers": [],
+  "completed_tasks": [],
+  "completion_action": "interactive",
+  "created_at": "<timestamp>"
+}
+```
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `session_id` | string | Unique session identifier |
+| `task_description` | string | Original task description from user |
+| `status` | string | One of: "active", "paused", "completed" |
+| `team_name` | string | Team name for Agent tool |
+| `roles` | array | List of role definitions |
+| `roles[].name` | string | Role name (must match .md filename) |
+| `roles[].prefix` | string | Task prefix for this role |
+| `roles[].role_spec` | string | Relative path to role-spec file |
+
+### Optional Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `pipeline` | object | Pipeline metadata |
+| `active_workers` | array | Currently running workers |
+| `completed_tasks` | array | List of completed task IDs |
+| `completion_action` | string | Completion mode: interactive, auto_archive, auto_keep |
+| `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,
+      "role_spec_metadata": {
+        "additional_members": [],
+        "message_types": {
+          "success": "<prefix>_complete",
+          "error": "error"
+        }
+      }
+    }
+  ],
+  "complexity_score": 0
+}
+```
+
+---
+
+## Role-Spec File Schema
+
+Each role-spec in `role-specs/<role-name>.md` follows the lightweight format with YAML frontmatter + Phase 2-4 body.
+
+### Required Structure
+
+```markdown
+---
+role: <name>
+prefix: <PREFIX>
+inner_loop: <true|false>
+message_types:
+  success: <type>
+  error: error
+---
+
+# <Role Name> — Phase 2-4
+
+## Phase 2: <Name>
+<domain-specific context loading>
+
+## Phase 3: <Name>
+<domain-specific execution>
+
+## Phase 4: <Name>
+<domain-specific validation>
+```
+
+### Role-Spec Structure Validation
+
+```
+For each role-spec in role-specs/<role>.md:
+  1. Read file content
+  2. Check for YAML frontmatter (content between --- markers)
+     +- Not found -> ERROR: "Invalid role-spec: role-specs/<role>.md missing frontmatter"
+  3. Parse frontmatter, check required fields:
+     +- role (string) -> missing -> ERROR
+     +- prefix (string) -> missing -> ERROR
+     +- inner_loop (boolean) -> missing -> ERROR
+     +- message_types (object) -> missing -> ERROR
+  4. Check for "## Phase 2" section
+     +- Not found -> ERROR: "Invalid role-spec: missing Phase 2"
+  5. Check for "## Phase 3" section
+     +- Not found -> ERROR: "Invalid role-spec: missing Phase 3"
+  6. Check for "## Phase 4" section
+     +- Not found -> ERROR: "Invalid role-spec: missing Phase 4"
+  7. All checks pass -> role-spec valid
+```
+
+---
+
+## 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
++-- role-specs/
+|   +-- researcher.md           # YAML frontmatter + Phase 2-4
+|   +-- developer.md            # YAML frontmatter + Phase 2-4
+|   +-- tester.md               # YAML frontmatter + Phase 2-4
++-- artifacts/                  # (may be empty)
++-- .msg/                       # Team message bus + state (messages.jsonl + meta.json)
++-- wisdom/
+|   +-- learnings.md
+|   +-- decisions.md
+|   +-- issues.md
++-- explorations/
+|   +-- cache-index.json
++-- discussions/                # (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-spec files**: Re-run team-coordinate with resume
+4. **Invalid frontmatter**: Manual fix or re-run team-coordinate
+5. **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-lifecycle-v4/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: team-lifecycle-v4
+description: Full lifecycle team skill — plan, develop, test, review in one coordinated session. Role-based architecture with coordinator-driven beat model. Triggers on "team lifecycle v4".
+allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ccw-tools__team_msg(*)
+---
+
+# Team Lifecycle v4
+
+Orchestrate multi-agent software development: specification → planning → implementation → testing → review.
+
+## Architecture
+
+```
+Skill(skill="team-lifecycle-v4", args="task description")
+                    |
+         SKILL.md (this file) = Router
+                    |
+     +--------------+--------------+
+     |                             |
+  no --role flag              --role <name>
+     |                             |
+  Coordinator                  Worker
+  roles/coordinator/role.md    roles/<name>/role.md
+     |
+     +-- analyze → dispatch → spawn → STOP
+                                 |
+                    +--------+---+--------+
+                    v        v            v
+             [team-worker]  ...    [team-supervisor]
+              per-task               resident agent
+              lifecycle              message-driven
+                                     (woken via SendMessage)
+```
+
+## Role Registry
+
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
+| analyst | [roles/analyst/role.md](roles/analyst/role.md) | RESEARCH-* | false |
+| writer | [roles/writer/role.md](roles/writer/role.md) | DRAFT-* | true |
+| planner | [roles/planner/role.md](roles/planner/role.md) | PLAN-* | true |
+| executor | [roles/executor/role.md](roles/executor/role.md) | IMPL-* | true |
+| tester | [roles/tester/role.md](roles/tester/role.md) | TEST-* | false |
+| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REVIEW-*, QUALITY-*, IMPROVE-* | false |
+| supervisor | [roles/supervisor/role.md](roles/supervisor/role.md) | CHECKPOINT-* | false |
+
+## Role Router
+
+Parse `$ARGUMENTS`:
+- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
+
+## Shared Constants
+
+- **Session prefix**: `TLV4`
+- **Session path**: `.workflow/.team/TLV4-<slug>-<date>/`
+- **CLI tools**: `maestro cli --mode analysis` (read-only), `maestro cli --mode write` (modifications)
+- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+Agent({
+  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: <skill_root>/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: <team-name>
+requirement: <task-description>
+inner_loop: <true|false>
+
+## Progress Milestones
+session_id: <session-id>
+Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
+Report blockers immediately via team_msg type="blocker".
+Report completion via team_msg type="task_complete" after final SendMessage.
+
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
+})
+```
+
+## Supervisor Spawn Template
+
+Supervisor is a **resident agent** (independent from team-worker). Spawned once during session init, woken via SendMessage for each CHECKPOINT task.
+
+### Spawn (Phase 2 — once per session)
+
+```
+Agent({
+  subagent_type: "team-supervisor",
+  description: "Spawn resident supervisor",
+  team_name: <team-name>,
+  name: "supervisor",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: supervisor
+role_spec: <skill_root>/roles/supervisor/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: <team-name>
+requirement: <task-description>
+
+## Progress Milestones
+session_id: <session-id>
+Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
+Report blockers immediately via team_msg type="blocker".
+Report completion via team_msg type="task_complete" after final SendMessage.
+
+Read role_spec file (@<skill_root>/roles/supervisor/role.md) to load checkpoint definitions.
+Init: load baseline context, report ready, go idle.
+Wake cycle: coordinator sends checkpoint requests via SendMessage.`
+})
+```
+
+### Wake (handleSpawnNext — per CHECKPOINT task)
+
+```
+SendMessage({
+  type: "message",
+  recipient: "supervisor",
+  content: `## Checkpoint Request
+task_id: <CHECKPOINT-NNN>
+scope: [<upstream-task-ids>]
+pipeline_progress: <done>/<total> tasks completed`,
+  summary: "Checkpoint request: <CHECKPOINT-NNN>"
+})
+```
+
+### Shutdown (handleComplete)
+
+```
+SendMessage({
+  type: "shutdown_request",
+  recipient: "supervisor",
+  content: "Pipeline complete, shutting down supervisor"
+})
+```
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph |
+| `resume` / `continue` | Advance to next step |
+| `revise <TASK-ID> [feedback]` | Revise specific task |
+| `feedback <text>` | Inject feedback for revision |
+| `recheck` | Re-run quality check |
+| `improve [dimension]` | Auto-improve weakest dimension |
+
+## Completion Action
+
+When pipeline completes, coordinator presents:
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "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" }
+    ]
+  }]
+})
+```
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
+- [specs/quality-gates.md](specs/quality-gates.md) — Quality gate criteria and scoring
+- [specs/knowledge-transfer.md](specs/knowledge-transfer.md) — Artifact and state transfer protocols
+
+## Session Directory
+
+```
+.workflow/.team/TLV4-<slug>-<date>/
+├── team-session.json           # Session state + role registry
+├── spec/                       # Spec phase outputs
+├── plan/                       # Implementation plan + TASK-*.json
+├── artifacts/                  # All deliverables
+├── wisdom/                     # Cross-task knowledge
+├── explorations/               # Shared explore cache
+├── discussions/                # Discuss round records
+└── .msg/                       # Team message bus
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Unknown command | Error with available command list |
+| Role not found | Error with role registry |
+| CLI tool fails | Worker fallback to direct implementation |
+| Fast-advance conflict | Coordinator reconciles on next callback |
+| Supervisor crash | Respawn with `recovery: true`, auto-rebuilds from existing reports |
+| Supervisor not ready for CHECKPOINT | Spawn/respawn supervisor, wait for ready, then wake |
+| Completion action fails | Default to Keep Active |