maestro-flow 0.4.9 → 0.4.11

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

@@ -0,0 +1,198 @@
+# 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)
+
+### Tech Profile Injection
+
+When generating role-specs for analysis or exploration roles, append a Tech Profile Scan instruction after their Phase 3:
+- Instruct the role to scan analysis results for codebase signals relevant to its domain
+- Include `tech_profile` in state_update data for coordinator specialist injection evaluation
+
+### 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/.agy/skills/team-executor/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: team-executor
+description: Lightweight session execution skill. Resumes existing team-coordinate sessions for pure execution via team-worker agents. No analysis, no role generation -- only loads and executes. Session path required. Triggers on "Team Executor".
+agy-subagents:
+  - team-worker
+---
+
+## Sub-Agent Registration (Antigravity)
+
+Before any `invoke_subagent` call below, register each sub-agent type once per session by reading the system_prompt from `<agy-agents-dir>/<name>.md` and passing it to `define_subagent`. The `<agy-agents-dir>` is:
+- global install: `~/.gemini/antigravity-cli/agents/`
+- workspace install: `<project>/.agents/agents/`
+
+- `define_subagent(name="team-worker", description="<from agents/team-worker.md frontmatter>", system_prompt=<contents of agents/team-worker.md body>, enable_write_tools=true, enable_mcp_tools=true, enable_subagent_tools=false)`
+
+**ConversationId tracking**: `invoke_subagent` returns a ConversationId per spawned instance. Subsequent `send_message(Recipient=<ConversationId>, Message=...)` calls require that ConversationId — never use the role name as the recipient.
+
+---
+
+# Team Executor
+
+Lightweight session execution skill: load session -> reconcile state -> spawn team-worker agents -> execute -> deliver. **No analysis, no role generation** -- only executes existing team-coordinate sessions.
+
+
+## Architecture
+
+```
++---------------------------------------------------+
+|  view_file(AbsolutePath="<agy-skills-dir>/team-executor/SKILL.md") + execute inline                      |
+|  args="--session=<path>" [REQUIRED]                |
++-------------------+-------------------------------+
+                    | Session Validation
+         +---- --session valid? ----+
+         | NO                       | YES
+         v                          v
+    Error immediately          Orchestration Mode
+    (no session)               -> executor
+                                    |
+                    +-------+-------+-------+
+                    v       v       v       v
+                 [team-worker agents loaded from session role-specs]
+```
+
+---
+
+## Session Validation (BEFORE routing)
+
+**CRITICAL**: Session validation MUST occur before any execution.
+
+### Parse Arguments
+
+Extract from `$ARGUMENTS`:
+- `--session=<path>`: Path to team-coordinate session folder (REQUIRED)
+
+### Validation Steps
+
+1. **Check `--session` provided**:
+   - If missing -> **ERROR**: "Session required. Usage: --session=<path-to-TC-folder>"
+
+2. **Validate session structure** (see specs/session-schema.md):
+   - Directory exists at path
+   - `team-session.json` exists and valid JSON
+   - `task-analysis.json` exists and valid JSON
+   - `role-specs/` directory has at least one `.md` file
+   - Each role in `team-session.json#roles` has corresponding `.md` file in `role-specs/`
+
+3. **Validation failure**:
+   - Report specific missing component
+   - Suggest re-running team-coordinate or checking path
+
+---
+
+## Role Router
+
+This skill is **executor-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
+
+### Dispatch Logic
+
+| Scenario | Action |
+|----------|--------|
+| No `--session` | **ERROR** immediately |
+| `--session` invalid | **ERROR** with specific reason |
+| Valid session | Orchestration Mode -> executor |
+
+### Orchestration Mode
+
+**Invocation**: `view_file(AbsolutePath="<agy-skills-dir>/team-executor/SKILL.md") + execute inline (args: "--session=<session-folder>")`
+
+**Lifecycle**:
+```
+Validate session
+  -> executor Phase 0: Reconcile state (reset interrupted, detect orphans)
+  -> executor Phase 1: Spawn first batch team-worker agents (background) -> STOP
+  -> Worker executes -> send_message callback -> executor advances next step
+  -> Loop until pipeline complete -> Phase 2 report + completion action
+```
+
+**User Commands** (wake paused executor):
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | Output execution status graph, no advancement |
+| `resume` / `continue` | Check worker states, advance next step |
+
+---
+
+## Role Registry
+
+| Role | File | Type |
+|------|------|------|
+| executor | [roles/executor/role.md](roles/executor/role.md) | built-in orchestrator |
+| (dynamic) | `<session>/role-specs/<role-name>.md` | loaded from session |
+
+---
+
+## Executor Spawn Template
+
+### v2 Worker Spawn (all roles)
+
+When executor spawns workers, use `team-worker` agent with role-spec path:
+
+```
+invoke_subagent([{ TypeName: "team-worker", Role: "<role>", Prompt: "<Prompt>", Workspace: "inherit" }])
+```
+
+---
+
+## Completion Action
+
+When pipeline completes (all tasks done), executor presents an interactive choice:
+
+```
+ask_question({
+  questions: [{
+    question: "Team pipeline complete. What would you like to do?",
+    header: "Completion",
+    multiSelect: false,
+    options: [
+      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
+      { label: "Keep Active", description: "Keep session for follow-up work" },
+      { label: "Export Results", description: "Export deliverables to target directory, then clean" }
+    ]
+  }]
+})
+```
+
+### Action Handlers
+
+| Choice | Steps |
+|--------|-------|
+| Archive & Clean | Update session status="completed" -> TeamDelete -> output final summary with artifact paths |
+| Keep Active | Update session status="paused" -> output: "Resume with: view_file(AbsolutePath="<agy-skills-dir>/team-executor/SKILL.md") + execute inline (args: "--session=<path>")" |
+| Export Results | ask_question(target path) -> copy artifacts to target -> Archive & Clean |
+
+---
+
+## Integration with team-coordinate
+
+| Scenario | Skill |
+|----------|-------|
+| New task, no session | team-coordinate |
+| Existing session, resume execution | **team-executor** |
+| Session needs new roles | team-coordinate (with resume) |
+| Pure execution, no analysis | **team-executor** |
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| No --session provided | ERROR immediately with usage message |
+| Session directory not found | ERROR with path, suggest checking path |
+| team-session.json missing | ERROR, session incomplete, suggest re-run team-coordinate |
+| task-analysis.json missing | ERROR, session incomplete, suggest re-run team-coordinate |
+| No role-specs in session | ERROR, session incomplete, suggest re-run team-coordinate |
+| Role-spec file not found | ERROR with expected path |
+| capability_gap reported | Warn only, cannot generate new role-specs |
+| Fast-advance spawns wrong task | Executor reconciles on next callback |
+| Completion action fails | Default to Keep Active, log warning |

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

@@ -0,0 +1,235 @@
+
+## Sub-Agent Registration (Antigravity)
+
+Before any `invoke_subagent` call below, register each sub-agent type once per session by reading the system_prompt from `<agy-agents-dir>/<name>.md` and passing it to `define_subagent`. The `<agy-agents-dir>` is:
+- global install: `~/.gemini/antigravity-cli/agents/`
+- workspace install: `<project>/.agents/agents/`
+
+- `define_subagent(name="team-worker", description="<from agents/team-worker.md frontmatter>", system_prompt=<contents of agents/team-worker.md body>, enable_write_tools=true, enable_mcp_tools=true, enable_subagent_tools=false)`
+
+**ConversationId tracking**: `invoke_subagent` returns a ConversationId per spawned instance. Subsequent `send_message(Recipient=<ConversationId>, Message=...)` calls require that ConversationId — never use the role name as the recipient.
+
+---
+# Command: monitor
+
+## Purpose
+
+Event-driven pipeline coordination with Spawn-and-Stop pattern for team-executor v2. Role names are read from `team-session.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 |
+|----------|-------|-------------|
+| 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 role-specs |
+| WORKER_AGENT | team-worker | All workers spawned as team-worker agents |
+
+## 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`. Role-spec paths are in `session.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.
+
+```
+Receive callback from [<role>]
+  +- Find matching active worker by role (from session.roles)
+  +- Is this a progress update (not final)?
+  |   +- 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**: Check if expected next task is already `in_progress` (fast-advanced). If yes -> skip spawning, sync active_workers.
+
+---
+
+### Handler: handleCheck
+
+Read-only status report. No pipeline advancement.
+
+```
+[executor] Pipeline Status
+[executor] Progress: <completed>/<total> (<percent>%)
+
+[executor] Execution Graph:
+  <visual representation with status icons>
+
+  done=completed  >>>=running  o=pending  .=not created
+
+[executor] Active Workers:
+  > <subject> (<role>) - running <elapsed>
+
+[executor] Ready to spawn: <subjects>
+[executor] Commands: 'resume' to advance | 'check' to refresh
+```
+
+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 team-worker agents 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 -> handleComplete
+  +- HAS ready tasks -> for each:
+      +- Is task owner an Inner Loop role AND already has active_worker?
+      |   +- YES -> SKIP spawn (existing worker picks it up)
+      |   +- NO -> normal spawn below
+      +- TaskUpdate -> in_progress
+      +- team_msg log -> task_unblocked (session_id=<session-id>)
+      +- Spawn team-worker (see spawn tool call below)
+      +- Add to session.active_workers
+      Update session file -> output summary -> STOP
+```
+
+**Spawn worker tool call**:
+
+```
+invoke_subagent([{ TypeName: "team-worker", Role: "<role>", Prompt: "<Prompt>", Workspace: "inherit" }])
+```
+
+---
+
+### Handler: handleComplete
+
+Pipeline complete. Execute completion action.
+
+```
+All tasks completed (no pending, no in_progress)
+  +- Generate pipeline summary (deliverables, stats, duration)
+  +- Read session.completion_action:
+      |
+      +- "interactive":
+      |   ask_question -> user choice:
+      |   +- "Archive & Clean": session status="completed" -> TeamDelete -> summary
+      |   +- "Keep Active": session status="paused" -> resume command
+      |   +- "Export Results": copy artifacts -> Archive & Clean
+      |
+      +- "auto_archive": Execute Archive & Clean
+      +- "auto_keep": Execute Keep Active
+```
+
+**Fallback**: If completion action fails, default to Keep Active, log warning.
+
+---
+
+### Handler: handleAdapt (LIMITED)
+
+**UNLIKE team-coordinate, executor CANNOT generate new role-specs.**
+
+```
+Receive capability_gap from [<role>]
+  +- Log via team_msg (type: warning)
+  +- Check existing roles -> does any cover this?
+  |   +- YES -> redirect to that role -> STOP
+  |   +- NO -> genuine gap, report to user:
+  |       "Capability gap detected. team-executor cannot generate new role-specs.
+  |        Options: 1. Continue  2. Re-run team-coordinate  3. Manually add role-spec"
+  +- Continue execution with existing roles
+```
+
+---
+
+### Worker Failure Handling
+
+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
+
+Detect orphaned tasks (in_progress without active_worker, > 5 minutes) -> reset to pending -> handleSpawnNext.
+
+### Consensus-Blocked Handling
+
+```
+Route by severity:
+  +- HIGH: Create REVISION task (max 1). Already revised -> PAUSE for user
+  +- 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_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 fast-advanced tasks, sync to active_workers |
+
+## 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 | 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 |