maestro-flow 0.4.5 → 0.4.7

package/.codex/skills/team-quality-assurance/SKILL.md

@@ -1,161 +1,205 @@
----
-name: team-quality-assurance
-description: Team QA combining issue discovery and testing
-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>
-Orchestrate multi-agent QA: scout -> strategist -> generator -> executor -> analyst. Supports discovery, testing, and full closed-loop modes with parallel generation and GC loops.
-
-```
-Skill(skill="team-quality-assurance", 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 workers -> STOP
-                                    |
-                    +-------+-------+-------+-------+-------+
-                    v       v       v       v       v
-                 [scout] [strat] [gen] [exec] [analyst]
-                 team-worker agents, each loads roles/<role>/role.md
-```
-
-</purpose>
-
-<context>
-### Role Registry
-
-| Role | Path | Prefix | Inner Loop |
-|------|------|--------|------------|
-| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | -- | -- |
-| scout | [roles/scout/role.md](roles/scout/role.md) | SCOUT-* | false |
-| strategist | [roles/strategist/role.md](roles/strategist/role.md) | QASTRAT-* | false |
-| generator | [roles/generator/role.md](roles/generator/role.md) | QAGEN-* | false |
-| executor | [roles/executor/role.md](roles/executor/role.md) | QARUN-* | true |
-| analyst | [roles/analyst/role.md](roles/analyst/role.md) | QAANA-* | 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
-
-### Delegation Lock
-
-**Coordinator is a PURE ORCHESTRATOR. It coordinates, it does NOT do.**
-
-Before calling ANY tool, apply this check:
-
-| Tool Call | Verdict | Reason |
-|-----------|---------|--------|
-| `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `followup_task` | ALLOWED | Orchestration |
-| `list_agents` | ALLOWED | Agent health check |
-| `request_user_input` | ALLOWED | User interaction |
-| `mcp__maestro-tools__team_msg` | ALLOWED | Message bus |
-| `Read/Write` on `.workflow/.team/` files | ALLOWED | Session state |
-| `Read` on `roles/`, `commands/`, `specs/` | ALLOWED | Loading own instructions |
-| `Read/Grep/Glob` on project source code | BLOCKED | Delegate to worker |
-| `Edit` on any file outside `.workflow/` | BLOCKED | Delegate to worker |
-| `Bash("maestro delegate ...")` | BLOCKED | Only workers call CLI |
-| `Bash` running build/test/lint commands | BLOCKED | Delegate to worker |
-
-**If a tool call is BLOCKED**: STOP. Create a task, spawn a worker.
-
-**No exceptions for "simple" tasks.** Even a single-file read-and-report MUST go through spawn_agent.
-
-### Shared Constants
-
-- **Session prefix**: `QA`
-- **Session path**: `.workflow/.team/QA-<slug>-<date>/`
-- **Team name**: `quality-assurance`
-- **CLI tools**: `maestro delegate --mode analysis` (read-only), `maestro delegate --mode write` (modifications)
-- **Message bus**: `mcp__maestro-tools__team_msg(session_id=<session-id>, ...)`
-
-### Worker Spawn Template
-
-Spawn via `team-worker` agent. Message includes: role, role_spec path, 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) -> close.
-
-### Model Selection Guide
-
-| Role | reasoning_effort |
-|------|-------------------|
-| Scout (SCOUT-*) | medium |
-| Strategist (QASTRAT-*) | high |
-| Generator (QAGEN-*) | high |
-| Executor (QARUN-*) | medium |
-| Analyst (QAANA-*) | high |
-
-Override via `model`/`reasoning_effort` params in spawn_agent for cost optimization.
-
-### User Commands
-
-| Command | Action |
-|---------|--------|
-| `check` / `status` | View pipeline status graph |
-| `resume` / `continue` | Advance to next step |
-| `--mode=discovery` | Force discovery mode |
-| `--mode=testing` | Force testing mode |
-| `--mode=full` | Force full QA mode |
-
-### v4 Agent Coordination
-
-**Message Semantics**: `send_message` to queue scout findings to strategist. `list_agents` for health checks. `followup_task` not used (all one-shot workers).
-
-**Pipeline Pattern**: Sequential with GC loops: scout -> strategist -> generator -> executor -> analyst. Generator/executor may loop (max 3 rounds) when coverage below target.
-
-**Agent Health Check**: Reconcile `tasks.json` with `list_agents({})`. Reset orphaned tasks to pending.
-
-**Named Targeting**: `send_message({ target: "QASTRAT-001" })`, `close_agent({ target: "SCOUT-001" })`.
-
-### Completion Action
-
-Present choice: **Archive & Clean** (recommended), **Keep Active**, **Export Results**.
-
-### Session Directory
-
-```
-.workflow/.team/QA-<slug>-<date>/
-+-- .msg/messages.jsonl     # Team message bus
-+-- .msg/meta.json          # Session state + shared memory
-+-- wisdom/                 # Cross-task knowledge
-+-- scan/                   # Scout output
-+-- strategy/               # Strategist output
-+-- tests/                  # Generator output (L1/, L2/, L3/)
-+-- results/                # Executor output
-+-- analysis/               # Analyst output
-```
-
-### Specs Reference
-
-- [specs/pipelines.md](specs/pipelines.md) -- Pipeline definitions and task registry
-- [specs/team-config.json](specs/team-config.json) -- Team configuration and shared memory schema
-</context>
-
-<error_codes>
-
-| Scenario | Resolution |
-|----------|------------|
-| Unknown --role value | Error with available role list |
-| Role not found | Error with expected path (roles/<name>/role.md) |
-| CLI tool fails | Worker fallback to direct implementation |
-| Scout finds no issues | Report clean scan, skip to testing mode |
-| GC loop exceeded | Accept current coverage with warning |
-| Fast-advance conflict | Coordinator reconciles on next callback |
-| Completion action fails | Default to Keep Active |
-</error_codes>
-
-<success_criteria>
-- [ ] Role router correctly dispatches to coordinator or worker based on --role flag
-- [ ] Pipeline mode detected (discovery/testing/full) from task description
-- [ ] Scout -> strategist -> generator -> executor -> analyst executed in order
-- [ ] GC loops create fix tasks when coverage is below target (max 3 rounds)
-- [ ] Session state persisted after each pipeline stage
-- [ ] Completion action presented and handled correctly
-</success_criteria>
+---
+name: team-quality-assurance
+description: Team QA combining issue discovery and testing
+argument-hint: "[scope] [-y|--yes] [-c|--concurrency N] [--continue] [--mode discovery|testing|full]"
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Wave-based QA pipeline via `spawn_agents_on_csv`. Progressive test coverage through scout → strategy → generate → execute → analyze cycle with GC loops for coverage convergence.
+
+```
++-------------------------------------------------------------------+
+|                   QA CSV WAVE WORKFLOW                              |
++-------------------------------------------------------------------+
+|  Phase 1: Mode Selection + CSV Generation                          |
+|     +-- Detect mode (discovery/testing/full)                       |
+|     +-- Build tasks.csv from pipeline definition                   |
+|                                                                     |
+|  Phase 2: Wave Execution Engine                                    |
+|     +-- Sequential waves, parallel tasks within wave               |
+|     +-- GC Loop: after QARUN wave, check coverage targets          |
+|     |   +-- Coverage < target → add QAGEN+QARUN waves (max 3)     |
+|     +-- discoveries.ndjson shared across waves                     |
+|                                                                     |
+|  Phase 3: Results Aggregation                                      |
++-------------------------------------------------------------------+
+```
+</purpose>
+
+<context>
+```bash
+$team-quality-assurance "src/auth module"
+$team-quality-assurance -y --mode testing "src/payments"
+$team-quality-assurance --continue "20260518-qa-auth"
+```
+
+**Flags**: `-y` (auto), `-c N` (concurrency, default 3), `--continue` (resume), `--mode discovery|testing|full`
+
+### Role Registry (Fixed)
+
+| Role | Path | Prefix |
+|------|------|--------|
+| scout | [roles/scout/role.md](roles/scout/role.md) | SCOUT-* |
+| strategist | [roles/strategist/role.md](roles/strategist/role.md) | QASTRAT-* |
+| generator | [roles/generator/role.md](roles/generator/role.md) | QAGEN-* |
+| executor | [roles/executor/role.md](roles/executor/role.md) | QARUN-* |
+| analyst | [roles/analyst/role.md](roles/analyst/role.md) | QAANA-* |
+
+**Session**: `.workflow/.csv-wave/{YYYYMMDD}-qa-{slug}/`
+**Output**: tasks.csv, results.csv, discoveries.ndjson, context.md
+
+### Scan Perspectives (scout)
+bug, security, test-coverage, code-quality, ux
+</context>
+
+<csv_schema>
+
+### tasks.csv (Input columns)
+
+```csv
+id,title,description,role,test_layer,deps,context_from,wave
+```
+
+| Column | Description |
+|--------|-------------|
+| `id` | Task ID: `{PREFIX}-{NNN}` or `{PREFIX}-L{layer}-{NNN}` |
+| `title` | Short task title |
+| `description` | PURPOSE/TASK/EXPECTED/CONSTRAINTS |
+| `role` | Fixed role name |
+| `test_layer` | L1/L2/L3 or empty |
+| `deps` | Semicolon-separated dependency IDs |
+| `context_from` | Semicolon-separated context source IDs |
+| `wave` | Wave number |
+
+**Output columns** (via `output_schema` only):
+
+| Column | Description |
+|--------|-------------|
+| `result_status` | completed / failed / blocked |
+| `findings` | Key findings (max 500 chars) |
+| `files_modified` | Semicolon-separated paths |
+| `coverage_score` | Test coverage % (0-100, for QARUN tasks) |
+| `error` | Error message |
+
+**Column separation rule**: Input and Output MUST NOT share names.
+
+### Pipeline Wave Assignments
+
+#### discovery (5 waves, serial)
+
+| Wave | Task | Role |
+|------|------|------|
+| 1 | SCOUT-001 | scout |
+| 2 | QASTRAT-001 | strategist |
+| 3 | QAGEN-001 | generator |
+| 4 | QARUN-001 | executor |
+| 5 | QAANA-001 | analyst |
+
+#### testing (6+ waves, GC loops)
+
+| Wave | Task | Role |
+|------|------|------|
+| 1 | QASTRAT-001 | strategist |
+| 2 | QAGEN-L1-001 | generator |
+| 3 | QARUN-L1-001 | executor |
+| 4+ | GC: QAGEN-L2 + QARUN-L2 if coverage < target | generator, executor |
+| N | QAANA-001 | analyst |
+
+#### full (8+ waves, parallel + GC)
+
+| Wave | Task | Role |
+|------|------|------|
+| 1 | SCOUT-001 | scout |
+| 2 | QASTRAT-001 | strategist |
+| 3 | QAGEN-L1-001; QAGEN-L2-001 | generator (parallel) |
+| 4 | QARUN-L1-001; QARUN-L2-001 | executor (parallel) |
+| 5+ | GC loops if coverage < target | generator, executor |
+| N-1 | QAANA-001 | analyst |
+| N | SCOUT-002 | scout (regression) |
+
+**Coverage Targets**: L1≥80%, L2≥60%, L3≥40%. **Max GC Rounds**: 3 per layer.
+</csv_schema>
+
+<invariants>
+1. **Wave Order Sacred**: Sequential wave execution
+2. **CSV Source of Truth**: Master tasks.csv
+3. **Column Separation Rule**: Input ≠ Output column names
+4. **GC Loop Max 3**: Per-layer generator-executor rounds
+5. **Coverage Targets**: L1≥80%, L2≥60%, L3≥40%
+6. **Discovery Board Append-Only**
+7. **Cleanup Temp Files**: Both wave-N.csv and wave-N-results.csv
+8. **DO NOT STOP**: Continuous until complete
+9. **Role Files Authoritative**: Agents read roles/{role}/role.md
+</invariants>
+
+<state_machine>
+
+<states>
+S_PARSE      — Parse arguments, detect mode
+S_CSV_GEN    — Generate tasks.csv
+S_WAVE_{N}   — Execute wave N
+S_GC_CHECK   — Coverage check after QARUN wave
+S_AGGREGATE  — Generate report
+</states>
+
+<transitions>
+S_PARSE → S_CSV_GEN
+S_CSV_GEN → S_WAVE_1
+S_WAVE_{N} → S_GC_CHECK      WHEN: wave was QARUN
+S_WAVE_{N} → S_WAVE_{N+1}    WHEN: not GC-eligible
+S_GC_CHECK → S_WAVE_{N+1}    WHEN: coverage >= target (converged)
+S_GC_CHECK → S_WAVE_{N+1}    WHEN: coverage < target, gc_rounds < 3 (add QAGEN+QARUN rows)
+S_GC_CHECK → S_WAVE_{N+1}    WHEN: gc_rounds >= 3 (proceed with warning)
+S_WAVE_{N} → S_AGGREGATE     WHEN: last wave
+</transitions>
+
+<actions>
+
+### GC Loop
+
+After each QARUN wave:
+1. Read `coverage_score` from results
+2. coverage >= target → continue
+3. coverage < target AND gc_rounds < 3 → add QAGEN+QARUN rows, increment wave, continue
+4. gc_rounds >= 3 → proceed with warning
+
+### Instruction Builder
+
+```
+You are a team-quality-assurance agent.
+Role: read 'role' column. Task: read 'description' column.
+
+## Role Definition
+Read: {skillRoot}/roles/{role}/role.md
+
+## Context
+Session: {sessionFolder}
+Discovery board: {sessionFolder}/discoveries.ndjson
+Previous context: 'prev_context' column
+
+## Output
+result_status, findings, files_modified, coverage_score (QARUN only), error
+```
+
+</actions>
+</state_machine>
+
+<error_codes>
+
+| Condition | Recovery |
+|-----------|----------|
+| Scout found 0 issues | Skip to analyst, report clean |
+| Coverage never converges | After 3 GC rounds, proceed with warning |
+| Generator produces 0 tests | Mark blocked, skip executor |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode selected and CSV generated
+- [ ] Waves executed via spawn_agents_on_csv
+- [ ] GC loops converge or hit max 3
+- [ ] Coverage tracked per layer
+- [ ] Column separation maintained
+- [ ] Temp files cleaned
+- [ ] results.csv and context.md generated
+</success_criteria>