maestro-flow 0.1.0

package/README.zh-CN.md

@@ -0,0 +1,323 @@
+<div align="center">
+
+# Maestro-Flow
+
+### 面向 Claude Code & Codex 的多智能体工作流编排
+
+**一条命令，多个 AI 智能体，结构化交付。**
+
+[![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)
+
+---
+
+*我不写代码 —— Claude Code 和 Codex 写。但告诉它们做什么、按什么顺序、带什么上下文、然后验证结果 —— 这才是耗时间的地方。Maestro-Flow 把这些编排自动化了。*
+
+</div>
+
+---
+
+## 背景
+
+这个项目是 [Claude-Code-Workflow (CCW)](https://github.com/catlog22/Claude-Code-Workflow) 的**彻底重写**。CCW 是我之前的多 CLI 编排框架，它证明了通过结构化工作流协调 Claude、Codex、Gemini 等 AI 智能体是可行的 —— 但它越长越复杂。太多层级，太多抽象。
+
+Maestro-Flow 保留了验证过的核心思路，用全新的理念重建：**更少仪式感，更快执行。** 规格驱动的阶段管线设计受 [GET SHIT DONE (GSD)](https://github.com/gsd-build/get-shit-done) 启发 —— 它的上下文工程方法和原子提交纪律确实优雅。Maestro-Flow 采纳了这些设计模式，同时补上 GSD 没有的东西：实时可视化看板、基于 Claude Agent SDK 的多智能体执行、以及自主运行的 Commander 让管线持续推进。
+
+**相比 CCW 改了什么：**
+- 砍掉了重型的 session/beat 编排层 —— 替换为轻量的 skill 路由
+- 终端仪表盘升级为 Linear 风格的 Web 看板 UI
+- 统一所有 CLI 工具调用到 `maestro cli` 单一接口
+- 新增自主 Commander Agent（assess → decide → dispatch 循环）
+- 构建了完整的 Issue 闭环系统（discover → analyze → plan → execute → close）
+
+**保留了什么：**
+- 多 CLI 编排（Claude、Codex、Gemini、Qwen、OpenCode）
+- Markdown 定义的结构化工作流
+- 斜杠命令作为用户界面
+- Agent 定义作为聚焦的角色规格
+
+---
+
+## 它做什么
+
+你描述你想要什么。Maestro-Flow 决定用哪些智能体、按什么顺序、带什么上下文 —— 然后驱动它完成。
+
+```bash
+# 自然语言 —— Maestro-Flow 路由到最优命令链
+/maestro "实现基于 OAuth2 的用户认证，带 refresh token"
+
+# 或者一步步来
+/maestro-init                    # 初始化项目工作区
+/maestro-roadmap                 # 交互式创建路线图
+/maestro-plan 1                  # 生成第一阶段执行计划
+/maestro-execute 1               # 波次并行多智能体执行
+/maestro-verify 1                # 目标反推验证
+```
+
+### 阶段管线
+
+```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 -->|下一阶段| D
+```
+
+每个阶段有明确的状态跟踪。仪表盘展示正在发生什么、下一步该做什么。
+
+### 快速通道
+
+不是所有事情都需要走完整管线：
+
+| 通道 | 流程 | 适用场景 |
+|------|------|---------|
+| `/maestro-quick` | analyze → plan → execute | 快速修复、小功能 |
+| Scratch 模式 | `analyze -q` → `plan --dir` → `execute --dir` | 不需要 roadmap，直接干 |
+| `/maestro "..."` | AI 路由命令链 | 描述意图，让 Maestro-Flow 决定 |
+
+---
+
+## 看板仪表盘
+
+实时项目控制面板，运行在 `http://127.0.0.1:3001`。React 19 + Tailwind CSS 4 构建，WebSocket 实时更新。
+
+### 四种视图
+
+| 视图 | 快捷键 | 你看到什么 |
+|------|--------|-----------|
+| **Board** | `K` | 看板列 —— Backlog、In Progress、Review、Done。Phase 卡片和 Issue 卡片并排展示。 |
+| **Timeline** | `T` | 甘特图风格的阶段时间线，带进度条 |
+| **Table** | `L` | 所有阶段和 Issue 的可排序表格 |
+| **Center** | `C` | 指挥中心 —— 活跃执行、Issue 队列、质量指标 |
+
+### 你能做什么
+
+- **选个智能体，点播放** — 在 Issue 卡片上选 Claude / Codex / Gemini，点执行
+- **批量派发** — 多选 Issue，并行发送给智能体
+- **看智能体工作** — 实时 CLI 输出流式面板
+- **Issue 全生命周期** — 创建、分析、规划、执行、关闭 —— 全在看板上
+- **Linear 同步** — 导入/导出 Issue 到 Linear，支持团队协作
+
+### Commander Agent
+
+自主监督者。后台运行 tick 循环：
+
+```
+评估(assess) → 决策(decide) → 派发(dispatch) → 等待 → 评估 → ...
+```
+
+它读取项目状态（阶段、任务、Issue、智能体工位），判断什么需要处理，自动派发智能体。三档配置：`conservative`、`balanced`、`aggressive`。
+
+Commander 开启后，Issue 从发现到解决全程无需人工干预。
+
+---
+
+## Issue 闭环
+
+Issue 不只是工单 —— 它们是一条自修复管线：
+
+```mermaid
+graph LR
+    A[发现] --> B[创建]
+    B --> C[分析]
+    C --> D[规划]
+    D --> E[执行]
+    E --> F[关闭]
+```
+
+| 阶段 | 命令 | 做了什么 |
+|------|------|---------|
+| **发现** | `/manage-issue-discover` | 8 视角扫描：Bug、UX、技术债、安全、性能、测试缺口、代码质量、文档 |
+| **分析** | `/manage-issue-analyze` | CLI 探索式根因分析，将结构化 `analysis` 写入 Issue |
+| **规划** | `/manage-issue-plan` | 生成解决方案步骤 —— 目标文件、代码变更、验证条件 |
+| **执行** | `/manage-issue-execute` | 双模式：服务器在线走 Dashboard API 派发，离线走 CLI 直接执行 |
+| **关闭** | 自动 | 验证通过 → `resolved` → `closed` |
+
+### Issue 如何连接主干管线
+
+```mermaid
+graph TB
+    subgraph 阶段管线
+        EX[execute] --> VE[verify]
+        VE --> RE[review]
+        RE --> TE[test]
+    end
+    subgraph Issue 闭环
+        DI[discover] --> AN[analyze]
+        AN --> PL[plan]
+        PL --> IX[execute]
+    end
+    RE -->|critical/high 发现| DI
+    TE -->|测试失败| DI
+    VE -->|验证缺口| DI
+    IX -->|修复代码回流| EX
+```
+
+质量命令（`review`、`test`、`verify`）自动为发现的问题创建 Issue。Issue 修复的代码回流到阶段。闭环自动关闭。
+
+---
+
+## 多智能体执行
+
+Maestro-Flow 不挑一个 AI —— 它让它们一起干：
+
+```
+              ┌────────────────────────────────┐
+              │      ExecutionScheduler         │
+              │     （波次并行执行引擎）          │
+              └───────────┬────────────────────┘
+                          │
+           ┌──────────────┼──────────────┐
+           │              │              │
+     ┌─────┴─────┐ ┌─────┴──────┐ ┌────┴──────┐
+     │  Claude    │ │   Codex    │ │  Gemini   │
+     │ Agent SDK  │ │  CLI       │ │  CLI      │
+     └───────────┘ └────────────┘ └───────────┘
+```
+
+- **波次执行** — 无依赖任务跨智能体并行，有依赖任务等前置完成
+- **Agent SDK** — 原生 Claude Agent SDK 驱动 Claude Code 进程
+- **CLI 适配器** — Codex、Gemini、Qwen、OpenCode 全部通过 `maestro cli` 调用
+- **工作区隔离** — 每个智能体获得独立执行上下文
+
+---
+
+## 36 个命令，21 个 Agent
+
+### 命令（Claude Code 斜杠命令）
+
+| 类别 | 数量 | 用途 |
+|------|------|------|
+| `maestro-*` | 15 | 全生命周期 — init、brainstorm、roadmap、analyze、plan、execute、verify、phase-transition |
+| `manage-*` | 9 | Issue CRUD、发现、分析、规划、执行、代码库文档、记忆管理 |
+| `quality-*` | 7 | review、test、debug、test-gen、integration-test、refactor、sync |
+| `spec-*` | 4 | 规格说明 — setup、add、load、map |
+
+### Agent
+
+`.claude/agents/` 下 21 个专业化 Agent 定义 —— 每个是聚焦的 Markdown 文件，Claude Code 按需加载。包括 `workflow-planner`、`workflow-executor`、`issue-discover-agent`、`workflow-debugger`、`workflow-verifier`、`team-worker` 等。
+
+---
+
+## 快速开始
+
+### 前置条件
+
+- Node.js >= 18
+- [Claude Code](https://claude.com/code) CLI
+- （可选）Codex CLI、Gemini CLI 用于多智能体工作流
+
+### 安装
+
+```bash
+git clone https://github.com/catlog22/Maestro-Flow.git
+cd Maestro-Flow
+npm install && npm run build
+
+# 启动仪表盘
+cd dashboard && npm install && npm run dev
+# → http://127.0.0.1:3001
+```
+
+### 第一次运行
+
+```bash
+/maestro-init                  # 初始化项目
+/maestro-roadmap               # 创建路线图
+/maestro-plan 1                # 规划第一阶段
+/maestro-execute 1             # 多智能体执行
+
+# 或者直接：
+/maestro "搭建用户管理的 REST API"
+```
+
+### MCP 服务器
+
+将 Maestro-Flow 工具暴露给 Claude Desktop 和其他 MCP 客户端：
+
+```bash
+npm run mcp  # stdio 传输
+```
+
+---
+
+## 架构
+
+```
+maestro/
+├── bin/                     # CLI 入口
+├── src/                     # 核心 CLI（Commander.js + MCP SDK）
+│   ├── commands/            # 11 个 CLI 命令（serve, run, cli, ext, tool, ...）
+│   ├── mcp/                 # MCP 服务器（stdio 传输）
+│   └── core/                # 工具注册、扩展加载器
+├── dashboard/               # 实时 Web 仪表盘
+│   └── src/
+│       ├── client/          # React 19 + Zustand + Tailwind CSS 4
+│       │   └── components/
+│       │       └── kanban/  # 19 个看板组件
+│       ├── server/          # Hono API + WebSocket + SSE
+│       │   ├── agents/      # AgentManager + 适配器（Claude SDK, Codex CLI, OpenCode）
+│       │   ├── commander/   # 自主 Commander Agent
+│       │   └── execution/   # ExecutionScheduler + WaveExecutor
+│       └── shared/          # 共享类型
+├── .claude/
+│   ├── commands/            # 36 个斜杠命令（.md）
+│   └── agents/              # 21 个 Agent 定义（.md）
+├── workflows/               # 36 个工作流实现（.md）
+├── templates/               # JSON 模板（task, plan, issue, ...）
+└── extensions/              # 插件系统
+```
+
+### 技术栈
+
+| 层级 | 技术 |
+|------|------|
+| CLI | Commander.js, TypeScript, ESM |
+| MCP | @modelcontextprotocol/sdk（stdio） |
+| 前端 | React 19, Zustand, Tailwind CSS 4, Framer Motion, Radix UI |
+| 后端 | Hono, WebSocket, SSE |
+| 智能体 | Claude Agent SDK, Codex CLI, Gemini CLI, OpenCode |
+| 构建 | Vite 6, TypeScript 5.7, Vitest |
+
+---
+
+## 文档
+
+- **[命令使用指南](guide/command-usage-guide.md)** — 全部 36 个命令，含工作流图表、管线衔接、Issue 闭环、快速通道
+
+---
+
+## 致谢
+
+Maestro-Flow 站在两个项目的肩膀上：
+
+- **[GET SHIT DONE](https://github.com/gsd-build/get-shit-done)** by TACHES — 规格驱动开发模型、上下文工程理念、原子提交纪律，塑造了 Maestro-Flow 的管线设计。GSD 证明了结构化的 meta-prompting 才是大规模驱动 AI 智能体的正确方式。
+
+- **[Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow)** — Maestro-Flow 的前身。CCW 开创了多 CLI 编排（Gemini + Codex + Qwen + Claude）、skill 路由工作流、team agent 架构。Maestro-Flow 是 CCW 从零重建 —— 更快、更精简，加上可视化看板和自主 Commander。
+
+## 贡献者
+
+<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)** — 创建者 & 维护者
+
+## 友情链接
+
+- [Linux DO：学AI，上L站！](https://linux.do/)
+
+## 许可证
+
+MIT

package/bin/maestro-context-monitor.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+const { runContextMonitor } = await import('../dist/hooks/context-monitor.js');
+runContextMonitor();

package/bin/maestro-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/mcp/server.js';

package/bin/maestro-statusline.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import '../dist/hooks/statusline.js';
+const { runStatusline } = await import('../dist/hooks/statusline.js');
+runStatusline();

package/bin/maestro.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/chains/_intent-map.json

@@ -0,0 +1,259 @@
+{
+  "$schema": "intent-map.schema.json",
+  "version": "1.0.0",
+  "patterns": [
+    {
+      "type": "state_continue",
+      "regex": "^(continue|next|go|继续|下一步)$",
+      "flags": "i",
+      "route": { "strategy": "state_router" }
+    },
+    {
+      "type": "status",
+      "regex": "^(status|状态|dashboard)$",
+      "flags": "i",
+      "route": { "graph": "singles/status" }
+    },
+    {
+      "type": "spec_generate",
+      "regex": "spec.*(generat|creat|build)|PRD|产品.*规格",
+      "flags": "i",
+      "route": { "graph": "spec-driven" }
+    },
+    {
+      "type": "brainstorm",
+      "regex": "brainstorm|ideate|头脑风暴|发散",
+      "flags": "i",
+      "route": { "graph": "brainstorm-driven" }
+    },
+    {
+      "type": "analyze",
+      "regex": "analy[sz]e|feasib|evaluat|assess|discuss|分析|评估|讨论",
+      "flags": "i",
+      "route": { "graph": "singles/analyze" }
+    },
+    {
+      "type": "ui_design",
+      "regex": "ui.*design|design.*ui|prototype|设计.*原型|UI.*风格",
+      "flags": "i",
+      "route": { "graph": "ui-design-driven" }
+    },
+    {
+      "type": "init",
+      "regex": "init|setup.*project|初始化|新项目",
+      "flags": "i",
+      "route": { "graph": "singles/init" }
+    },
+    {
+      "type": "plan",
+      "regex": "plan(?!.*gap)|break.*down|规划|分解",
+      "flags": "i",
+      "route": { "graph": "singles/plan" }
+    },
+    {
+      "type": "roadmap",
+      "regex": "roadmap|路线图",
+      "flags": "i",
+      "route": { "graph": "roadmap-driven" }
+    },
+    {
+      "type": "execute",
+      "regex": "execute|implement|build|develop|code|实现|开发",
+      "flags": "i",
+      "route": { "graph": "singles/execute" }
+    },
+    {
+      "type": "verify",
+      "regex": "verif[iy]|validate.*result|验证|校验",
+      "flags": "i",
+      "route": { "graph": "singles/verify" }
+    },
+    {
+      "type": "review",
+      "regex": "\\breview.*code|code.*review|代码.*审查",
+      "flags": "i",
+      "route": { "graph": "singles/review" }
+    },
+    {
+      "type": "test_gen",
+      "regex": "test.*gen|generat.*test|add.*test|写测试",
+      "flags": "i",
+      "route": { "graph": "singles/test-gen" }
+    },
+    {
+      "type": "test",
+      "regex": "\\btest|uat|测试|验收",
+      "flags": "i",
+      "route": { "graph": "singles/test" }
+    },
+    {
+      "type": "debug",
+      "regex": "debug|diagnos|troubleshoot|fix.*bug|调试|排查",
+      "flags": "i",
+      "route": { "graph": "singles/debug" }
+    },
+    {
+      "type": "integration_test",
+      "regex": "integrat.*test|e2e|集成测试",
+      "flags": "i",
+      "route": { "graph": "singles/integration-test" }
+    },
+    {
+      "type": "refactor",
+      "regex": "refactor|tech.*debt|重构|技术债",
+      "flags": "i",
+      "route": { "graph": "singles/refactor" }
+    },
+    {
+      "type": "sync",
+      "regex": "sync.*doc|refresh.*doc|同步",
+      "flags": "i",
+      "route": { "graph": "singles/sync" }
+    },
+    {
+      "type": "phase_transition",
+      "regex": "phase.*transit|next.*phase|推进|切换.*阶段",
+      "flags": "i",
+      "route": { "graph": "singles/phase-transition" }
+    },
+    {
+      "type": "phase_add",
+      "regex": "phase.*add|add.*phase|添加.*阶段",
+      "flags": "i",
+      "route": { "graph": "singles/phase-add" }
+    },
+    {
+      "type": "milestone_audit",
+      "regex": "milestone.*audit|里程碑.*审计",
+      "flags": "i",
+      "route": { "graph": "singles/milestone-audit" }
+    },
+    {
+      "type": "milestone_complete",
+      "regex": "milestone.*compl|完成.*里程碑",
+      "flags": "i",
+      "route": { "graph": "singles/milestone-complete" }
+    },
+    {
+      "type": "issue_analyze",
+      "regex": "analyze.*issue|issue.*root.*cause",
+      "flags": "i",
+      "route": { "graph": "singles/issue-analyze" }
+    },
+    {
+      "type": "issue_plan",
+      "regex": "plan.*issue|issue.*solution",
+      "flags": "i",
+      "route": { "graph": "singles/issue-plan" }
+    },
+    {
+      "type": "issue_execute",
+      "regex": "execute.*issue|run.*issue",
+      "flags": "i",
+      "route": { "graph": "singles/issue-execute" }
+    },
+    {
+      "type": "issue_discover",
+      "regex": "discover.*issue|find.*issue|发现.*问题",
+      "flags": "i",
+      "route": { "graph": "singles/issue-discover" }
+    },
+    {
+      "type": "issue",
+      "regex": "issue|问题|缺陷",
+      "flags": "i",
+      "route": { "graph": "singles/issue" }
+    },
+    {
+      "type": "codebase_rebuild",
+      "regex": "codebase.*rebuild|重建.*文档",
+      "flags": "i",
+      "route": { "graph": "singles/codebase-rebuild" }
+    },
+    {
+      "type": "codebase_refresh",
+      "regex": "codebase.*refresh|刷新.*文档",
+      "flags": "i",
+      "route": { "graph": "singles/codebase-refresh" }
+    },
+    {
+      "type": "spec_setup",
+      "regex": "spec.*setup|规范.*初始化",
+      "flags": "i",
+      "route": { "graph": "singles/spec-setup" }
+    },
+    {
+      "type": "spec_add",
+      "regex": "spec.*add|添加.*规范",
+      "flags": "i",
+      "route": { "graph": "singles/spec-add" }
+    },
+    {
+      "type": "spec_load",
+      "regex": "spec.*load|加载.*规范",
+      "flags": "i",
+      "route": { "graph": "singles/spec-load" }
+    },
+    {
+      "type": "spec_map",
+      "regex": "spec.*map|规范.*映射",
+      "flags": "i",
+      "route": { "graph": "singles/spec-map" }
+    },
+    {
+      "type": "memory_capture",
+      "regex": "memory.*captur|save.*memory|compact",
+      "flags": "i",
+      "route": { "graph": "singles/memory-capture" }
+    },
+    {
+      "type": "memory",
+      "regex": "memory|manage.*mem|记忆",
+      "flags": "i",
+      "route": { "graph": "singles/memory" }
+    },
+    {
+      "type": "team_lifecycle",
+      "regex": "team.*lifecycle|团队.*生命周期",
+      "flags": "i",
+      "route": { "graph": "singles/team-lifecycle" }
+    },
+    {
+      "type": "team_coordinate",
+      "regex": "team.*coordinat|团队.*协调",
+      "flags": "i",
+      "route": { "graph": "singles/team-coordinate" }
+    },
+    {
+      "type": "team_qa",
+      "regex": "team.*(qa|quality)|团队.*质量",
+      "flags": "i",
+      "route": { "graph": "singles/team-qa" }
+    },
+    {
+      "type": "team_test",
+      "regex": "team.*test|团队.*测试",
+      "flags": "i",
+      "route": { "graph": "singles/team-testing" }
+    },
+    {
+      "type": "team_review",
+      "regex": "team.*review|团队.*评审",
+      "flags": "i",
+      "route": { "graph": "singles/team-review" }
+    },
+    {
+      "type": "team_tech_debt",
+      "regex": "team.*tech.*debt|团队.*技术债",
+      "flags": "i",
+      "route": { "graph": "singles/team-tech-debt" }
+    },
+    {
+      "type": "quick",
+      "regex": "quick|small.*task|ad.?hoc|简单|快速",
+      "flags": "i",
+      "route": { "graph": "singles/quick" }
+    }
+  ],
+  "fallback": { "graph": "singles/quick" }
+}