maestro-flow 0.1.0

package/.codex/skills/team-testing/roles/strategist/role.md

@@ -0,0 +1,83 @@
+---
+role: strategist
+prefix: STRATEGY
+inner_loop: false
+message_types:
+  success: strategy_ready
+  error: error
+---
+
+# Test Strategist
+
+Analyze git diff, determine test layers, define coverage targets, and formulate test strategy with prioritized execution order.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract session path and scope from task description
+2. Get git diff for change analysis:
+
+```
+Bash("git diff HEAD~1 --name-only 2>/dev/null || git diff --cached --name-only")
+Bash("git diff HEAD~1 -- <changed-files> 2>/dev/null || git diff --cached -- <changed-files>")
+```
+
+3. Detect test framework from project files:
+
+| Signal File | Framework | Test Pattern |
+|-------------|-----------|-------------|
+| jest.config.js/ts | Jest | `**/*.test.{ts,tsx,js}` |
+| vitest.config.ts/js | Vitest | `**/*.test.{ts,tsx}` |
+| pytest.ini / pyproject.toml | Pytest | `**/test_*.py` |
+| No detection | Default | Jest patterns |
+
+4. Scan existing test patterns:
+
+```
+Glob("**/*.test.*")
+Glob("**/*.spec.*")
+```
+
+5. Read .msg/meta.json if exists for session context
+
+## Phase 3: Strategy Formulation
+
+**Change analysis dimensions**:
+
+| Change Type | Analysis | Priority |
+|-------------|----------|----------|
+| New files | Need new tests | High |
+| Modified functions | Need updated tests | Medium |
+| Deleted files | Need test cleanup | Low |
+| Config changes | May need integration tests | Variable |
+
+**Strategy output structure**:
+
+1. **Change Analysis Table**: File, Change Type, Impact, Priority
+2. **Test Layer Recommendations**:
+   - L1 Unit: Scope, Coverage Target, Priority Files, Patterns
+   - L2 Integration: Scope, Coverage Target, Integration Points
+   - L3 E2E: Scope, Coverage Target, User Scenarios
+3. **Risk Assessment**: Risk, Probability, Impact, Mitigation
+4. **Test Execution Order**: Prioritized sequence
+
+Write strategy to `<session>/strategy/test-strategy.md`
+
+**Self-validation**:
+
+| Check | Criteria | Fallback |
+|-------|----------|----------|
+| Has L1 scope | L1 scope not empty | Default to all changed files |
+| Has coverage targets | L1 target > 0 | Use defaults (80/60/40) |
+| Has priority files | List not empty | Use all changed files |
+
+## Phase 4: Wisdom & State Update
+
+1. Write discoveries to `<session>/wisdom/conventions.md` (detected framework, patterns)
+2. Update `<session>/wisdom/.msg/meta.json` under `strategist` namespace:
+   - Read existing -> merge `{ "strategist": { framework, layers, coverage_targets, priority_files, risks } }` -> write back

package/.codex/skills/team-testing/specs/pipelines.md

@@ -0,0 +1,101 @@
+# Testing Pipelines
+
+Pipeline definitions and task registry for team-testing.
+
+## Pipeline Selection
+
+| Condition | Pipeline |
+|-----------|----------|
+| fileCount <= 3 AND moduleCount <= 1 | targeted |
+| fileCount <= 10 AND moduleCount <= 3 | standard |
+| Otherwise | comprehensive |
+
+## Pipeline Definitions
+
+### Targeted Pipeline (3 tasks, serial)
+
+```
+STRATEGY-001 -> TESTGEN-001 -> TESTRUN-001
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| STRATEGY-001 | strategist | (none) | — | Analyze changes, define test strategy |
+| TESTGEN-001 | generator | STRATEGY-001 | L1 | Generate L1 unit tests |
+| TESTRUN-001 | executor | TESTGEN-001 | L1 | Execute L1 tests, collect coverage |
+
+### Standard Pipeline (6 tasks, progressive layers)
+
+```
+STRATEGY-001 -> TESTGEN-001 -> TESTRUN-001 -> TESTGEN-002 -> TESTRUN-002 -> TESTANA-001
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| STRATEGY-001 | strategist | (none) | — | Analyze changes, define test strategy |
+| TESTGEN-001 | generator | STRATEGY-001 | L1 | Generate L1 unit tests |
+| TESTRUN-001 | executor | TESTGEN-001 | L1 | Execute L1 tests, collect coverage |
+| TESTGEN-002 | generator | TESTRUN-001 | L2 | Generate L2 integration tests |
+| TESTRUN-002 | executor | TESTGEN-002 | L2 | Execute L2 tests, collect coverage |
+| TESTANA-001 | analyst | TESTRUN-002 | — | Defect pattern analysis, quality report |
+
+### Comprehensive Pipeline (8 tasks, parallel windows)
+
+```
+STRATEGY-001 -> [TESTGEN-001 || TESTGEN-002] -> [TESTRUN-001 || TESTRUN-002] -> TESTGEN-003 -> TESTRUN-003 -> TESTANA-001
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| STRATEGY-001 | strategist | (none) | — | Analyze changes, define test strategy |
+| TESTGEN-001 | generator-1 | STRATEGY-001 | L1 | Generate L1 unit tests (parallel) |
+| TESTGEN-002 | generator-2 | STRATEGY-001 | L2 | Generate L2 integration tests (parallel) |
+| TESTRUN-001 | executor-1 | TESTGEN-001 | L1 | Execute L1 tests (parallel) |
+| TESTRUN-002 | executor-2 | TESTGEN-002 | L2 | Execute L2 tests (parallel) |
+| TESTGEN-003 | generator | TESTRUN-001, TESTRUN-002 | L3 | Generate L3 E2E tests |
+| TESTRUN-003 | executor | TESTGEN-003 | L3 | Execute L3 tests, collect coverage |
+| TESTANA-001 | analyst | TESTRUN-003 | — | Defect pattern analysis, quality report |
+
+## GC Loop (Generator-Critic)
+
+Generator and executor iterate per test layer:
+
+```
+TESTGEN -> TESTRUN -> (if pass_rate < 0.95 OR coverage < target) -> TESTGEN-fix -> TESTRUN-fix
+                      (if pass_rate >= 0.95 AND coverage >= target) -> next layer or TESTANA
+```
+
+- Max iterations: 3 per layer
+- After 3 iterations: accept current state with warning
+
+## Coverage Targets
+
+| Layer | Name | Default Target |
+|-------|------|----------------|
+| L1 | Unit Tests | 80% |
+| L2 | Integration Tests | 60% |
+| L3 | E2E Tests | 40% |
+
+## Session Directory
+
+```
+.workflow/.team/TST-<slug>-<YYYY-MM-DD>/
+├── .msg/messages.jsonl          # Message bus log
+├── .msg/meta.json               # Session metadata
+├── wisdom/                     # Cross-task knowledge
+│   ├── learnings.md
+│   ├── decisions.md
+│   ├── conventions.md
+│   └── issues.md
+├── strategy/                   # Strategist output
+│   └── test-strategy.md
+├── tests/                      # Generator output
+│   ├── L1-unit/
+│   ├── L2-integration/
+│   └── L3-e2e/
+├── results/                    # Executor output
+│   ├── run-001.json
+│   └── coverage-001.json
+└── analysis/                   # Analyst output
+    └── quality-report.md
+```

package/.codex/skills/team-testing/specs/team-config.json

@@ -0,0 +1,93 @@
+{
+  "team_name": "team-testing",
+  "team_display_name": "Team Testing",
+  "description": "Testing team with Generator-Critic loop, shared defect memory, and progressive test layers",
+  "version": "1.0.0",
+
+  "roles": {
+    "coordinator": {
+      "task_prefix": null,
+      "responsibility": "Change scope analysis, layer selection, quality gating",
+      "message_types": ["pipeline_selected", "gc_loop_trigger", "quality_gate", "task_unblocked", "error", "shutdown"]
+    },
+    "strategist": {
+      "task_prefix": "STRATEGY",
+      "responsibility": "Analyze git diff, determine test layers, define coverage targets",
+      "message_types": ["strategy_ready", "error"]
+    },
+    "generator": {
+      "task_prefix": "TESTGEN",
+      "responsibility": "Generate test cases by layer (unit/integration/E2E)",
+      "message_types": ["tests_generated", "tests_revised", "error"]
+    },
+    "executor": {
+      "task_prefix": "TESTRUN",
+      "responsibility": "Execute tests, collect coverage, auto-fix failures",
+      "message_types": ["tests_passed", "tests_failed", "coverage_report", "error"]
+    },
+    "analyst": {
+      "task_prefix": "TESTANA",
+      "responsibility": "Defect pattern analysis, coverage gap analysis, quality report",
+      "message_types": ["analysis_ready", "error"]
+    }
+  },
+
+  "pipelines": {
+    "targeted": {
+      "description": "Small scope: strategy → generate L1 → run",
+      "task_chain": ["STRATEGY-001", "TESTGEN-001", "TESTRUN-001"],
+      "gc_loops": 0
+    },
+    "standard": {
+      "description": "Progressive: L1 → L2 with analysis",
+      "task_chain": ["STRATEGY-001", "TESTGEN-001", "TESTRUN-001", "TESTGEN-002", "TESTRUN-002", "TESTANA-001"],
+      "gc_loops": 1
+    },
+    "comprehensive": {
+      "description": "Full coverage: parallel L1+L2, then L3 with analysis",
+      "task_chain": ["STRATEGY-001", "TESTGEN-001", "TESTGEN-002", "TESTRUN-001", "TESTRUN-002", "TESTGEN-003", "TESTRUN-003", "TESTANA-001"],
+      "gc_loops": 2,
+      "parallel_groups": [["TESTGEN-001", "TESTGEN-002"], ["TESTRUN-001", "TESTRUN-002"]]
+    }
+  },
+
+  "innovation_patterns": {
+    "generator_critic": {
+      "generator": "generator",
+      "critic": "executor",
+      "max_rounds": 3,
+      "convergence_trigger": "coverage >= target && pass_rate >= 0.95"
+    },
+    "shared_memory": {
+      "file": "shared-memory.json",
+      "fields": {
+        "strategist": "test_strategy",
+        "generator": "generated_tests",
+        "executor": "execution_results",
+        "analyst": "analysis_report"
+      },
+      "persistent_fields": ["defect_patterns", "effective_test_patterns", "coverage_history"]
+    },
+    "dynamic_pipeline": {
+      "selector": "coordinator",
+      "criteria": "changed_file_count + module_count + change_type"
+    }
+  },
+
+  "test_layers": {
+    "L1": { "name": "Unit Tests", "coverage_target": 80, "description": "Function-level isolation tests" },
+    "L2": { "name": "Integration Tests", "coverage_target": 60, "description": "Module interaction tests" },
+    "L3": { "name": "E2E Tests", "coverage_target": 40, "description": "User scenario end-to-end tests" }
+  },
+
+  "collaboration_patterns": ["CP-1", "CP-3", "CP-5"],
+
+  "session_dirs": {
+    "base": ".workflow/.team/TST-{slug}-{YYYY-MM-DD}/",
+    "strategy": "strategy/",
+    "tests": "tests/",
+    "results": "results/",
+    "analysis": "analysis/",
+    "messages": ".workflow/.team-msg/{team-name}/"
+  }
+}

package/README.md

@@ -0,0 +1,323 @@
+<div align="center">
+
+# Maestro-Flow
+
+### Multi-Agent Workflow Orchestration for Claude Code & Codex
+
+**One command. Multiple AI agents. Structured delivery.**
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-≥18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![MCP](https://img.shields.io/badge/MCP-Protocol-8B5CF6)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+---
+
+*I don't write code — Claude Code and Codex do. But telling them what to do, in what order, with what context, and verifying the result — that's where all the time goes. Maestro-Flow makes that orchestration automatic.*
+
+</div>
+
+---
+
+## Background
+
+This project is a **ground-up rewrite** of [Claude-Code-Workflow (CCW)](https://github.com/catlog22/Claude-Code-Workflow), my earlier multi-CLI orchestration framework. CCW proved that coordinating Claude, Codex, Gemini and other AI agents through structured workflows is powerful — but it grew complex. Too many layers, too many abstractions.
+
+Maestro-Flow takes the core ideas that worked and rebuilds them with a clear philosophy: **less ceremony, faster execution.** The spec-driven phase pipeline is inspired by [GET SHIT DONE (GSD)](https://github.com/gsd-build/get-shit-done) — its context engineering approach and atomic commit discipline are genuinely elegant. Maestro-Flow adopts those design patterns while adding what GSD doesn't have: a real-time visual dashboard, multi-agent execution with Claude Agent SDK, and an autonomous Commander that keeps the pipeline moving without you.
+
+**What changed from CCW:**
+- Stripped the heavy session/beat orchestration layer — replaced with lightweight skill-based routing
+- Merged the terminal dashboard into a proper web UI with Linear-style Kanban
+- Unified CLI tool invocation through a single `maestro cli` interface
+- Added autonomous Commander Agent (assess → decide → dispatch loop)
+- Built a complete Issue closed-loop system (discover → analyze → plan → execute → close)
+
+**What we kept:**
+- Multi-CLI orchestration (Claude, Codex, Gemini, Qwen, OpenCode)
+- Structured workflows as Markdown definitions
+- Slash commands as the user interface
+- Agent definitions as focused role specifications
+
+---
+
+## What It Does
+
+You describe what you want. Maestro-Flow figures out which agents to use, in what order, with what context — and drives it to completion.
+
+```bash
+# Natural language — Maestro-Flow routes to the optimal command chain
+/maestro "implement OAuth2 authentication with refresh tokens"
+
+# Or step by step
+/maestro-init                    # Set up project workspace
+/maestro-roadmap                 # Create phased roadmap interactively
+/maestro-plan 1                  # Generate execution plan for Phase 1
+/maestro-execute 1               # Wave-based parallel agent execution
+/maestro-verify 1                # Goal-backward verification
+```
+
+### The Pipeline
+
+```mermaid
+graph LR
+    A[init] --> B[brainstorm]
+    B --> C[roadmap]
+    C --> D[analyze]
+    D --> E[plan]
+    E --> F[execute]
+    F --> G[verify]
+    G --> H[review]
+    H --> I[test]
+    I --> J[transition]
+    J -->|next phase| D
+```
+
+Each phase has explicit status tracking. The dashboard shows what's happening and what to do next.
+
+### Quick Channels
+
+Not everything needs a full pipeline:
+
+| Channel | Flow | When |
+|---------|------|------|
+| `/maestro-quick` | analyze → plan → execute | Quick fixes, small features |
+| Scratch mode | `analyze -q` → `plan --dir` → `execute --dir` | No roadmap, just get it done |
+| `/maestro "..."` | AI-routed command chain | Describe intent, let Maestro-Flow decide |
+
+---
+
+## The Dashboard
+
+A real-time project control panel at `http://127.0.0.1:3001`. Built with React 19, Tailwind CSS 4, and WebSocket live updates.
+
+### Four Views
+
+| View | Key | What You See |
+|------|-----|-------------|
+| **Board** | `K` | Kanban columns — Backlog, In Progress, Review, Done. Phase cards and Issue cards side by side. |
+| **Timeline** | `T` | Gantt-style phase timeline with progress bars |
+| **Table** | `L` | Every phase and issue in a sortable table |
+| **Center** | `C` | Command center — active executions, issue queue, quality metrics |
+
+### What You Can Do
+
+- **Pick an agent, hit play** — Select Claude / Codex / Gemini on any Issue card, click execute
+- **Batch dispatch** — Multi-select Issues, send them all to agents in parallel
+- **Watch agents work** — Real-time CLI output streaming panel
+- **Full Issue lifecycle** — Create, analyze, plan, execute, close — all from the board
+- **Linear sync** — Import/export Issues to Linear for team workflows
+
+### Commander Agent
+
+The autonomous supervisor. Runs a tick loop in the background:
+
+```
+assess → decide → dispatch → wait → assess → ...
+```
+
+It reads project state (phases, tasks, Issues, agent slots), decides what needs attention, and dispatches agents automatically. Three profiles: `conservative`, `balanced`, `aggressive`.
+
+When the Commander is on, Issues flow from discovery to resolution without manual intervention.
+
+---
+
+## Issue Closed-Loop
+
+Issues aren't just tickets — they're a self-healing pipeline:
+
+```mermaid
+graph LR
+    A[Discover] --> B[Create]
+    B --> C[Analyze]
+    C --> D[Plan]
+    D --> E[Execute]
+    E --> F[Close]
+```
+
+| Stage | Command | What Happens |
+|-------|---------|-------------|
+| **Discover** | `/manage-issue-discover` | 8-perspective scan: bugs, UX, tech debt, security, performance, testing gaps, code quality, documentation |
+| **Analyze** | `/manage-issue-analyze` | Root cause analysis via CLI exploration. Writes structured `analysis` to the Issue. |
+| **Plan** | `/manage-issue-plan` | Generates solution steps — target files, code changes, verification criteria |
+| **Execute** | `/manage-issue-execute` | Dual-mode: Dashboard API dispatch when server is up, direct CLI execution when offline |
+| **Close** | Automatic | Verification passes → `resolved` → `closed` |
+
+### How Issues Connect to the Pipeline
+
+```mermaid
+graph TB
+    subgraph Phase Pipeline
+        EX[execute] --> VE[verify]
+        VE --> RE[review]
+        RE --> TE[test]
+    end
+    subgraph Issue Loop
+        DI[discover] --> AN[analyze]
+        AN --> PL[plan]
+        PL --> IX[execute]
+    end
+    RE -->|critical/high findings| DI
+    TE -->|test failures| DI
+    VE -->|verification gaps| DI
+    IX -->|fixed code| EX
+```
+
+Quality commands (`review`, `test`, `verify`) automatically create Issues for problems they find. Issue fixes flow back into the phase. The loop closes itself.
+
+---
+
+## Multi-Agent Execution
+
+Maestro-Flow doesn't pick one AI — it uses them together:
+
+```
+              ┌────────────────────────────────┐
+              │      ExecutionScheduler         │
+              │   (wave-based parallel engine)  │
+              └───────────┬────────────────────┘
+                          │
+           ┌──────────────┼──────────────┐
+           │              │              │
+     ┌─────┴─────┐ ┌─────┴──────┐ ┌────┴──────┐
+     │  Claude    │ │   Codex    │ │  Gemini   │
+     │ Agent SDK  │ │  CLI       │ │  CLI      │
+     └───────────┘ └────────────┘ └───────────┘
+```
+
+- **Wave execution** — Independent tasks run in parallel across agents, dependent tasks wait for predecessors
+- **Agent SDK** — Native Claude Agent SDK for Claude Code processes
+- **CLI adapters** — Codex, Gemini, Qwen, OpenCode all accessible through `maestro cli`
+- **Workspace isolation** — Each agent gets a clean execution context
+
+---
+
+## 36 Commands, 21 Agents
+
+### Commands (Slash Commands for Claude Code)
+
+| Category | Count | Purpose |
+|----------|-------|---------|
+| `maestro-*` | 15 | Full lifecycle — init, brainstorm, roadmap, analyze, plan, execute, verify, phase-transition |
+| `manage-*` | 9 | Issue CRUD, discovery, analysis, planning, execution, codebase docs, memory |
+| `quality-*` | 7 | Review, test, debug, test-gen, integration-test, refactor, sync |
+| `spec-*` | 4 | Specification setup, add, load, map |
+
+### Agents
+
+21 specialized agent definitions in `.claude/agents/` — each a focused Markdown file that Claude Code loads on demand. Includes `workflow-planner`, `workflow-executor`, `issue-discover-agent`, `workflow-debugger`, `workflow-verifier`, `team-worker`, and more.
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= 18
+- [Claude Code](https://claude.com/code) CLI
+- (Optional) Codex CLI, Gemini CLI for multi-agent workflows
+
+### Install
+
+```bash
+git clone https://github.com/catlog22/Maestro-Flow.git
+cd Maestro-Flow
+npm install && npm run build
+
+# Dashboard
+cd dashboard && npm install && npm run dev
+# → http://127.0.0.1:3001
+```
+
+### First Run
+
+```bash
+/maestro-init                  # Initialize project
+/maestro-roadmap               # Create roadmap
+/maestro-plan 1                # Plan Phase 1
+/maestro-execute 1             # Execute with agents
+
+# Or just:
+/maestro "build a REST API for user management"
+```
+
+### MCP Server
+
+Expose Maestro-Flow tools to Claude Desktop and other MCP clients:
+
+```bash
+npm run mcp  # stdio transport
+```
+
+---
+
+## Architecture
+
+```
+maestro/
+├── bin/                     # CLI entry points
+├── src/                     # Core CLI (Commander.js + MCP SDK)
+│   ├── commands/            # 11 CLI commands (serve, run, cli, ext, tool, ...)
+│   ├── mcp/                 # MCP server (stdio transport)
+│   └── core/                # Tool registry, extension loader
+├── dashboard/               # Real-time web dashboard
+│   └── src/
+│       ├── client/          # React 19 + Zustand + Tailwind CSS 4
+│       │   └── components/
+│       │       └── kanban/  # 19 Kanban components
+│       ├── server/          # Hono API + WebSocket + SSE
+│       │   ├── agents/      # AgentManager + adapters (Claude SDK, Codex CLI, OpenCode)
+│       │   ├── commander/   # Autonomous Commander Agent
+│       │   └── execution/   # ExecutionScheduler + WaveExecutor
+│       └── shared/          # Shared types
+├── .claude/
+│   ├── commands/            # 36 slash commands (.md)
+│   └── agents/              # 21 agent definitions (.md)
+├── workflows/               # 36 workflow implementations (.md)
+├── templates/               # JSON templates (task, plan, issue, ...)
+└── extensions/              # Plugin system
+```
+
+### Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| CLI | Commander.js, TypeScript, ESM |
+| MCP | @modelcontextprotocol/sdk (stdio) |
+| Frontend | React 19, Zustand, Tailwind CSS 4, Framer Motion, Radix UI |
+| Backend | Hono, WebSocket, SSE |
+| Agents | Claude Agent SDK, Codex CLI, Gemini CLI, OpenCode |
+| Build | Vite 6, TypeScript 5.7, Vitest |
+
+---
+
+## Documentation
+
+- **[Command Usage Guide](guide/command-usage-guide.md)** — All 36 commands with workflow diagrams, pipeline chaining, Issue closed-loop, and quick channels
+
+---
+
+## Acknowledgments
+
+Maestro-Flow stands on the shoulders of two projects:
+
+- **[GET SHIT DONE](https://github.com/gsd-build/get-shit-done)** by TACHES — The spec-driven development model, context engineering philosophy, and atomic commit discipline that shaped Maestro-Flow's pipeline design. GSD proved that structured meta-prompting is the right way to drive AI agents at scale.
+
+- **[Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow)** — The predecessor to Maestro-Flow. CCW pioneered multi-CLI orchestration (Gemini + Codex + Qwen + Claude), skill-based workflow routing, and team agent architecture. Maestro-Flow is CCW rebuilt from scratch — faster, leaner, with a visual dashboard and autonomous commander.
+
+## Contributors
+
+<a href="https://github.com/catlog22">
+  <img src="https://github.com/catlog22.png" width="60px" alt="catlog22" style="border-radius:50%"/>
+</a>
+
+**[@catlog22](https://github.com/catlog22)** — Creator & Maintainer
+
+## Links
+
+- [Linux DO：学AI，上L站！](https://linux.do/)
+
+## License
+
+MIT