maestro-flow 0.4.6 → 0.4.8

package/.codex/skills/team-coordinate/specs/quality-gates.md

@@ -1,112 +0,0 @@
-# Quality Gates
-
-## 1. Quality Thresholds
-
-| Result | Score | Action |
-|--------|-------|--------|
-| Pass | >= 80% | Report completed |
-| Review | 60-79% | Report completed with warnings |
-| Fail | < 60% | Retry Phase 3 (max 2 retries) |
-
-## 2. Scoring Dimensions
-
-| Dimension | Weight | Criteria |
-|-----------|--------|----------|
-| Completeness | 25% | All required outputs present with substantive content |
-| Consistency | 25% | Terminology, formatting, cross-references are uniform |
-| Accuracy | 25% | Outputs are factually correct and verifiable against sources |
-| Depth | 25% | Sufficient detail for downstream consumers to act on deliverables |
-
-**Score** = weighted average of all dimensions (0-100 per dimension).
-
-## 3. Dynamic Role Quality Checks
-
-Quality checks vary by `output_type` (from task-analysis.json role metadata).
-
-### output_type: artifact
-
-| Check | Pass Criteria |
-|-------|---------------|
-| Artifact exists | File written to `<session>/artifacts/` |
-| Content non-empty | Substantive content, not just headers |
-| Format correct | Expected format (MD, JSON) matches deliverable |
-| Cross-references | All references to upstream artifacts resolve |
-
-### output_type: codebase
-
-| Check | Pass Criteria |
-|-------|---------------|
-| Files modified | Claimed files actually changed (Read to confirm) |
-| Syntax valid | No syntax errors in modified files |
-| No regressions | Existing functionality preserved |
-| Summary artifact | Implementation summary written to artifacts/ |
-
-### output_type: mixed
-
-All checks from both `artifact` and `codebase` apply.
-
-## 4. Verification Protocol
-
-Derived from Behavioral Traits in [role-spec-template.md](role-spec-template.md).
-
-| Step | Action | Required |
-|------|--------|----------|
-| 1 | Verify all claimed files exist via Read | Yes |
-| 2 | Confirm artifact written to `<session>/artifacts/` | Yes |
-| 3 | Check verification summary fields present | Yes |
-| 4 | Score against quality dimensions | Yes |
-| 5 | Apply threshold -> Pass/Review/Fail | Yes |
-
-**On Fail**: Retry Phase 3 (max 2 retries). After 2 retries, report `partial_completion`.
-
-**On Review**: Proceed with warnings logged to `<session>/wisdom/issues.md`.
-
-## 5. Code Review Dimensions
-
-For REVIEW-* or validation tasks during implementation pipelines.
-
-### Quality
-
-| Check | Severity |
-|-------|----------|
-| Empty catch blocks | Error |
-| `as any` type casts | Warning |
-| `@ts-ignore` / `@ts-expect-error` | Warning |
-| `console.log` in production code | Warning |
-| Unused imports/variables | Info |
-
-### Security
-
-| Check | Severity |
-|-------|----------|
-| Hardcoded secrets/credentials | Error |
-| SQL injection vectors | Error |
-| `eval()` or `Function()` usage | Error |
-| `innerHTML` assignment | Warning |
-| Missing input validation | Warning |
-
-### Architecture
-
-| Check | Severity |
-|-------|----------|
-| Circular dependencies | Error |
-| Deep cross-boundary imports (3+ levels) | Warning |
-| Files > 500 lines | Warning |
-| Functions > 50 lines | Info |
-
-### Requirements Coverage
-
-| Check | Severity |
-|-------|----------|
-| Core functionality implemented | Error if missing |
-| Acceptance criteria covered | Error if missing |
-| Edge cases handled | Warning |
-| Error states handled | Warning |
-
-## 6. Issue Classification
-
-| Class | Label | Action |
-|-------|-------|--------|
-| Error | Must fix | Blocks progression, must resolve before proceeding |
-| Warning | Should fix | Should resolve, can proceed with justification |
-| Info | Nice to have | Optional improvement, log for future |

package/.codex/skills/team-coordinate/specs/role-spec-template.md

@@ -1,192 +0,0 @@
-# Dynamic Role-Spec Template
-
-Template used by coordinator to generate lightweight worker role-spec files at runtime. Each generated role-spec is written to `<session>/role-specs/<role-name>.md`.
-
-**Key difference from v1**: Role-specs contain ONLY Phase 2-4 domain logic + YAML frontmatter. All shared behavior (Phase 1 Task Discovery, Phase 5 Report/Fast-Advance, Message Bus, Consensus, Inner Loop) is built into the `team-worker` agent.
-
-## Template
-
-```markdown
----
-role: <role_name>
-prefix: <PREFIX>
-inner_loop: <true|false>
-CLI tools: [<CLI tool-names>]
-message_types:
-  success: <prefix>_complete
-  error: error
----
-
-# <Role Name> — Phase 2-4
-
-## Phase 2: <phase2_name>
-
-<phase2_content>
-
-## Phase 3: <phase3_name>
-
-<phase3_content>
-
-## Phase 4: <phase4_name>
-
-<phase4_content>
-
-## Error Handling
-
-| Scenario | Resolution |
-|----------|------------|
-<error_entries>
-```
-
-## Frontmatter Fields
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `role` | Yes | Role name matching session registry |
-| `prefix` | Yes | Task prefix to filter (e.g., RESEARCH, DRAFT, IMPL) |
-| `inner_loop` | Yes | Whether team-worker loops through same-prefix tasks |
-| `CLI tools` | No | Array of CLI tool types this role may call |
-| `output_tag` | Yes | Output tag for all messages, e.g., `[researcher]` |
-| `message_types` | Yes | Message type mapping for team_msg |
-| `message_types.success` | Yes | Type string for successful completion |
-| `message_types.error` | Yes | Type string for errors (usually "error") |
-
-## Design Rules
-
-| Rule | Description |
-|------|-------------|
-| Phase 2-4 only | No Phase 1 (Task Discovery) or Phase 5 (Report) — team-worker handles these |
-| No message bus code | No team_msg calls — team-worker handles logging |
-| No consensus handling | No consensus_reached/blocked logic — team-worker handles routing |
-| No inner loop logic | No Phase 5-L/5-F — team-worker handles looping |
-| ~80 lines target | Lightweight, domain-focused |
-| No pseudocode | Decision tables + text + tool calls only |
-| `<placeholder>` notation | Use angle brackets for variable substitution |
-| Reference CLI tools by name | team-worker resolves invocation from its delegation templates |
-
-## Generated Role-Spec Structure
-
-Every generated role-spec MUST include these blocks:
-
-### Identity Block (mandatory — first section of generated spec)
-
-```
-Tag: [<role_name>] | Prefix: <PREFIX>-*
-Responsibility: <one-line from task analysis>
-```
-
-### Boundaries Block (mandatory — after Identity)
-
-```
-### MUST
-- <3-5 rules derived from task analysis>
-
-### MUST NOT
-- Execute work outside assigned prefix
-- Modify artifacts from other roles
-- Skip Phase 4 verification
-```
-
-## Behavioral Traits
-
-All dynamically generated role-specs MUST embed these traits into Phase 4. Coordinator copies this section verbatim into every generated role-spec as a Phase 4 appendix.
-
-**Design principle**: Constrain behavioral characteristics (accuracy, feedback, quality gates), NOT specific actions (which tool, which CLI tool, which path). Tasks are diverse — the coordinator composes task-specific Phase 2-3 instructions, while these traits ensure execution quality regardless of task type.
-
-### Accuracy — outputs must be verifiable
-
-- Files claimed as **created** → Read to confirm file exists and has content
-- Files claimed as **modified** → Read to confirm content actually changed
-- Analysis claimed as **complete** → artifact file exists in `<session>/artifacts/`
-
-### Feedback Contract — completion report must include evidence
-
-Phase 4 must produce a verification summary with these fields:
-
-| Field | When Required | Content |
-|-------|---------------|---------|
-| `files_produced` | New files created | Path list |
-| `files_modified` | Existing files changed | Path + before/after line count |
-| `artifacts_written` | Always | Paths in `<session>/artifacts/` |
-| `verification_method` | Always | How verified: Read confirm / syntax check / diff |
-
-### Quality Gate — verify before reporting complete
-
-- Phase 4 MUST verify Phase 3's **actual output** (not planned output)
-- Verification fails → retry Phase 3 (max 2 retries)
-- Still fails → report `partial_completion` with details, NOT `completed`
-- Update shared state via `team_msg(operation="log", type="state_update", data={...})` after verification passes
-
-Quality thresholds from [specs/quality-gates.md](quality-gates.md):
-- Pass >= 80%: report completed
-- Review 60-79%: report completed with warnings
-- Fail < 60%: retry Phase 3 (max 2)
-
-### Error Protocol
-
-- Primary approach fails → try alternative (different CLI tool / different tool)
-- 2 retries exhausted → escalate to coordinator with failure details
-- NEVER: skip verification and report completed
-
----
-
-## Reference Patterns
-
-Coordinator MAY reference these patterns when composing Phase 2-4 content for a role-spec. These are **structural guidance, not mandatory templates**. The task description determines specific behavior — patterns only suggest common phase structures.
-
-### Research / Exploration
-
-- Phase 2: Define exploration scope + load prior knowledge from shared state and wisdom
-- Phase 3: Explore via CLI tools, direct tool calls, or codebase search — approach chosen by agent
-- Phase 4: Verify findings documented (Behavioral Traits) + update shared state
-
-### Document / Content
-
-- Phase 2: Load upstream artifacts + read target files (if modifying existing docs)
-- Phase 3: Create new documents OR modify existing documents — determined by task, not template
-- Phase 4: Verify documents exist with expected content (Behavioral Traits) + update shared state
-
-### Code Implementation
-
-- Phase 2: Load design/spec artifacts from upstream
-- Phase 3: Implement code changes — CLI tool choice and approach determined by task complexity
-- Phase 4: Syntax check + file verification (Behavioral Traits) + update shared state
-
-### Analysis / Audit
-
-- Phase 2: Load analysis targets (artifacts or source files)
-- Phase 3: Multi-dimension analysis — perspectives and depth determined by task
-- Phase 4: Verify report exists + severity classification (Behavioral Traits) + update shared state
-
-### Validation / Testing
-
-- Phase 2: Detect test framework + identify changed files from upstream
-- Phase 3: Run test-fix cycle — iteration count and strategy determined by task
-- Phase 4: Verify pass rate + coverage (Behavioral Traits) + update shared state
-
----
-
-## Knowledge Transfer Protocol
-
-Full protocol: [specs/knowledge-transfer.md](knowledge-transfer.md)
-
-Generated role-specs Phase 2 MUST declare which upstream sources to load.
-Generated role-specs Phase 4 MUST include state update and artifact publishing.
-
----
-
-## Generated Role-Spec Validation
-
-Coordinator verifies before writing each role-spec:
-
-| Check | Criteria |
-|-------|----------|
-| Frontmatter complete | All required fields present (role, prefix, inner_loop, output_tag, message_types, CLI tools) |
-| Identity block | Tag, prefix, responsibility defined |
-| Boundaries | MUST and MUST NOT rules present |
-| Phase 2 | Context loading sources specified |
-| Phase 3 | Execution goal clear, not prescriptive about tools |
-| Phase 4 | Behavioral Traits copied verbatim |
-| Error Handling | Table with 3+ scenarios |
-| Line count | Target ~80 lines (max 120) |
-| No built-in overlap | No Phase 1/5, no message bus code, no consensus handling |

package/.codex/skills/team-executor/SKILL.md

@@ -1,116 +0,0 @@
----
-name: team-executor
-description: Resume team-coordinate sessions for pure execution
-allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), followup_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__maestro-tools__team_msg(*)
----
-
-<purpose>
-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.
-
-```
-Skill(skill="team-executor")
-  args="--session=<path>" [REQUIRED]
-         |
-  Session Validation
-         |
-  +-- valid? --+-- NO --> Error immediately
-               +-- YES -> Orchestration Mode -> executor
-                              |
-              +-------+-------+-------+
-              v       v       v       v
-           [team-worker agents loaded from session role-specs]
-```
-
-</purpose>
-
-<context>
-$ARGUMENTS — session path (required).
-
-**Parse:** `--session=<path>` — Path to team-coordinate session folder (REQUIRED)
-
-**Validation Steps:**
-1. Check `--session` provided
-2. Directory exists at path
-3. `team-session.json` exists and valid JSON
-4. `task-analysis.json` exists and valid JSON
-5. `role-specs/` directory has at least one `.md` file
-6. Each role in `team-session.json#roles` has corresponding `.md` in `role-specs/`
-
-**Dispatch:**
-| Scenario | Action |
-|----------|--------|
-| No `--session` | ERROR immediately |
-| `--session` invalid | ERROR with specific reason |
-| Valid session | Orchestration Mode -> executor |
-
-**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 |
-
-**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** |
-</context>
-
-<execution>
-
-### Orchestration Lifecycle
-
-Validate session -> Phase 0 (reconcile state, reset interrupted tasks, detect orphans) -> Phase 1 (spawn first batch workers, STOP) -> callback loop (advance next step) -> Phase 2 (report + completion action).
-
-### Worker Spawn Template
-
-Spawn via `team-worker` agent with role-spec path from session. Message includes: role, role_spec, session folder/id, requirement, inner_loop flag, task context, upstream context. After spawning: `wait_agent` (30 min). Timeout: STATUS_CHECK (3 min) -> FINALIZE (3 min) -> mark timed_out, close.
-
-### Model Selection
-
-Implementation/fix roles: `reasoning_effort: "high"`. Verification/test: `"medium"`. Default: `"high"`.
-
-### State Reconciliation
-
-On resume: compare `list_agents({})` with task-analysis.json. Reset orphaned tasks to pending.
-
-### Worker Communication
-
-`send_message` (supplementary context), `followup_task` (assign work to inner_loop worker), `close_agent` (cleanup).
-
-### Completion Action
-
-Present choice: **Archive & Clean** (mark completed, output summary), **Keep Active** (mark paused, output resume command), **Export Results** (prompt path, copy, archive).
-</execution>
-
-<error_codes>
-| 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 |
-</error_codes>
-
-<success_criteria>
-- [ ] Session validated (all required files present)
-- [ ] State reconciled on resume (orphaned tasks reset)
-- [ ] Team-worker agents spawned with correct role-specs
-- [ ] Workers complete or timeout handled gracefully
-- [ ] Pipeline advances step-by-step through all tasks
-- [ ] Completion action presented and executed
-- [ ] Session state updated throughout lifecycle
-</success_criteria>

package/.codex/skills/team-executor/roles/executor/commands/monitor.md

@@ -1,213 +0,0 @@
-# Command: monitor
-
-## Purpose
-
-Synchronous pipeline coordination using spawn_agent + wait_agent for team-executor v2. Role names are read from `tasks.json#roles`. Workers are spawned as `team_worker` agents with role-spec paths. **handleAdapt is LIMITED**: only warns, cannot generate new role-specs. Includes `handleComplete` for pipeline completion action.
-
-## Constants
-
-| Constant | Value | Description |
-|----------|-------|-------------|
-| WORKER_AGENT | team_worker | All workers spawned via spawn_agent |
-| ONE_STEP_PER_INVOCATION | false | Synchronous wait loop |
-| FAST_ADVANCE_AWARE | true | Workers may skip executor for simple linear successors |
-| ROLE_GENERATION | disabled | handleAdapt cannot generate new role-specs |
-
-## Phase 2: Context Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Session file | `<session-folder>/tasks.json` | Yes |
-| Active agents | tasks.json active_agents | Yes |
-| Role registry | tasks.json roles[] | Yes |
-
-**Dynamic role resolution**: Known worker roles are loaded from `tasks.json roles[].name`. Role-spec paths are in `tasks.json roles[].role_spec`.
-
-## 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 | Pipeline detected as complete | handleComplete |
-| 6 | None of the above (initial spawn after dispatch) | handleSpawnNext |
-
----
-
-### Handler: handleCallback
-
-Worker completed a task. Verify completion, update state, auto-advance.
-
-```
-Match agent by role -> route:
-  progress_update (not final) -> update state, keep in active_agents -> STOP
-  completed -> close_agent, remove from active_agents, -> handleSpawnNext
-  not_completed -> log progress -> STOP
-  no_match -> scan all agents for completions -> process any found -> handleSpawnNext, else STOP
-```
-
-**Fast-advance note**: Check if expected next task is already `in_progress` (fast-advanced). If yes -> skip spawning, sync active_agents.
-
----
-
-### Handler: handleCheck
-
-Read-only status report. No pipeline advancement.
-
-Read team_msg (type="progress", last=50) + team_msg (type="blocker", last=10). Aggregate per-worker milestones.
-
-**Output format**:
-```
-[executor] Pipeline Status — Progress: <completed>/<total> (<percent>%)
-[executor] Execution Graph: <dependency graph with status icons> done=completed >>>=running o=pending .=not created
-[executor] Active Workers: <task_id> <role> <milestone_phase> <pct>% "<summary>" <time_ago>
-[executor] Blockers: <task_id> <role> "<blocker_summary>" <time_ago> (omit if none)
-[executor] Ready to spawn: <subjects>
-[executor] Commands: 'resume' to advance | 'check' to refresh
-```
-
-**CLI monitoring**: `maestro agent-msg list -s "<session_id>" --type progress --last 10`
-
-Then STOP.
-
----
-
-### Handler: handleResume
-
-Check active agent completion, process results, advance pipeline.
-
-```
-Load active_agents -> route:
-  none -> handleSpawnNext
-  has agents -> classify each: completed(close_agent) | in_progress | failed(reset to pending)
-    some completed -> handleSpawnNext
-    all running -> report status -> STOP
-    all failed -> handleSpawnNext (retry)
-```
-
----
-
-### Handler: handleSpawnNext
-
-Find all ready tasks, spawn team_worker agents, wait for completion, process results.
-
-```
-Classify tasks: completed | in_progress | ready (pending + all deps completed)
-
-Ready tasks -> route:
-  none + in_progress exists -> report waiting -> STOP
-  none + nothing in_progress -> PIPELINE_COMPLETE -> handleComplete
-  has ready -> for each:
-    skip if Inner Loop role already has active_agent
-    else: set status="in_progress", log task_unblocked, spawn team_worker, add to active_agents
-```
-
-**Spawn worker message template**:
-```
-## 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 for Phase 2-4 instructions.
-## Task Context
-task_id: <taskId> | title: <task-title> | description: <task-description>
-## Upstream Context
-<prevContext>
-## Progress Milestones
-Report progress via team_msg at phase boundaries. Blockers via type="blocker". Completion via type="task_complete" after report_agent_job_result.
-```
-
-### Wait and Process Results
-
-`wait_agent({ timeout_ms: 1800000 })` (30 min), drain progress from team_msg.
-
-**Timeout escalation**: STATUS_CHECK (3 min) -> FINALIZE with interrupt (3 min) -> mark timed_out with last progress context, close_agent.
-
-**Normal completion**: Read `discoveries/{task_id}.json` for status/findings/error. Missing file -> status="failed". Close each agent.
-
-### Persist and Loop
-
-Write tasks.json -> more tasks ready? -> loop handleSpawnNext. All done -> handleComplete. Blocked -> report, STOP.
-
----
-
-### Handler: handleComplete
-
-Pipeline complete. Execute completion action.
-
-```
-Generate summary: deliverables + stats + duration
-
-Route by completion_action:
-  "interactive" -> request_user_input:
-    "Archive & Clean" -> rm session folder, output summary
-    "Keep Active"     -> status="paused", output resume command
-    "Export Results"   -> copy artifacts, then Archive & Clean
-  "auto_archive" -> Archive & Clean without prompt
-  "auto_keep"    -> Keep Active without prompt
-```
-
-**Fallback**: If completion action fails, default to Keep Active, log warning.
-
----
-
-### Handler: handleAdapt (LIMITED)
-
-**UNLIKE team-coordinate, executor CANNOT generate new role-specs.**
-
-```
-Log capability_gap via team_msg (type: warning)
-Existing role covers gap? -> redirect -> STOP
-Genuine gap -> report to user: "Options: 1. Continue  2. Re-run team-coordinate  3. Manually add role-spec"
-Continue with existing roles
-```
-
----
-
-### Worker Failure Handling
-
-1. Reset task -> pending in tasks.json
-2. Log via team_msg (type: error)
-3. Report to user: task reset, will retry on next resume
-
-### Fast-Advance Failure Recovery
-
-Detect orphaned tasks (in_progress without active_agents, > 5 minutes) -> reset to pending -> handleSpawnNext.
-
-### Consensus-Blocked Handling
-
-```
-Route by consensus_blocked severity:
-  HIGH   -> create REVISION task (max 1, else PAUSE + escalate)
-  MEDIUM -> proceed with warning, log to wisdom/issues.md
-  LOW    -> proceed normally as consensus_reached with notes
-```
-
-## Phase 4: Validation
-
-| Check | Criteria |
-|-------|----------|
-| Session state consistent | active_agents matches tasks.json in_progress tasks |
-| No orphaned tasks | Every in_progress task has an active_agents entry |
-| Dynamic roles valid | All task owners exist in tasks.json roles |
-| Completion detection | readyTasks=0 + inProgressTasks=0 -> PIPELINE_COMPLETE |
-| Fast-advance tracking | Detect fast-advanced tasks, sync to active_agents |
-
-## Error Handling
-
-| Scenario | Resolution |
-|----------|------------|
-| Session file not found | Error, suggest re-run team-coordinate |
-| Unknown role in callback | Log info, scan for other completions |
-| All workers still running on resume | Report status, suggest check later |
-| Pipeline stall | Check for missing tasks, report to user |
-| Fast-advance conflict | Executor reconciles, no duplicate spawns |
-| Role-spec file not found | Error, cannot proceed |
-| capability_gap | WARN only, cannot generate new role-specs |
-| Completion action fails | Default to Keep Active, log warning |