@s_s/harmonia 1.0.0

package/build/tools/update-phase.js

@@ -0,0 +1,79 @@
+/**
+ * MCP Tool: update_phase
+ * Advance or update the status of a project phase.
+ * When completing a phase, checks that all doc-type outputs exist (output guard).
+ */
+import { z } from 'zod';
+import { readState, updatePhaseStatus } from '../core/state.js';
+import { loadWorkflow } from '../core/workflow.js';
+import { listDocs } from '../core/docs.js';
+export function registerUpdatePhase(server, workflowsDir) {
+    server.tool('update_phase', 'Update the status of a project phase. When a phase is completed, the next phase is automatically started. Completing a phase checks that all required doc outputs exist.', {
+        project_name: z.string().describe('Project name'),
+        phase_id: z.string().describe('Phase ID to update (e.g. clarify, design, develop, test, deliver)'),
+        status: z.enum(['pending', 'in_progress', 'completed', 'blocked']).describe('New status for the phase'),
+        blocked_reason: z.string().optional().describe("Reason for blocking (required when status is 'blocked')"),
+        force: z.boolean().optional().describe('Force completion even if outputs are missing (default: false)'),
+    }, async ({ project_name, phase_id, status, blocked_reason, force }) => {
+        try {
+            // Output guard: when completing a phase, check doc outputs exist
+            if (status === 'completed' && !force) {
+                const currentState = await readState(project_name);
+                const wf = await loadWorkflow(workflowsDir, currentState.workflow);
+                const existingDocs = await listDocs(project_name);
+                const phaseDef = wf.definition.phases.find((p) => p.id === phase_id);
+                if (phaseDef) {
+                    const missingDocOutputs = phaseDef.outputs.filter((o) => {
+                        const docDef = wf.definition.docs[o];
+                        if (!docDef)
+                            return false; // unknown output, skip
+                        if (docDef.external)
+                            return false; // external outputs not managed by write_doc
+                        const scaleVal = docDef.scale[currentState.scale];
+                        if (scaleVal === 'skip' || scaleVal === 'optional')
+                            return false; // not required at this scale
+                        return !existingDocs.includes(o);
+                    });
+                    if (missingDocOutputs.length > 0) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Cannot complete phase "${phase_id}" — missing doc outputs: ${missingDocOutputs.join(', ')}.\n\nProduce these documents with write_doc first, or use force=true to skip this check.`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                }
+            }
+            const state = await updatePhaseStatus(project_name, phase_id, status, blocked_reason);
+            const phasesSummary = state.phases
+                .map((p) => {
+                const marker = p.id === state.currentPhase ? ' <-- current' : '';
+                return `  ${p.id}: ${p.status}${p.blockedReason ? ` (${p.blockedReason})` : ''}${marker}`;
+            })
+                .join('\n');
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Phase "${phase_id}" updated to "${status}".\n\nProject phases:\n${phasesSummary}`,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=update-phase.js.map

package/build/tools/update-phase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-phase.js","sourceRoot":"","sources":["../../src/tools/update-phase.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@s_s/harmonia",
+  "version": "1.0.0",
+  "description": "Multi-agent orchestration MCP server with pluggable workflows",
+  "type": "module",
+  "main": "./build/index.js",
+  "bin": {
+    "harmonia": "build/index.js"
+  },
+  "files": [
+    "build",
+    "workflows"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node build/index.js",
+    "prettier": "prettier --check \"**/*\"",
+    "prettier:fix": "prettier -c --write \"**/*\"",
+    "prettier:staged": "prettier --write",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "release": "bash scripts/release.sh",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "mcp",
+    "agent",
+    "orchestration",
+    "workflow",
+    "multi-agent"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.2",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "lint-staged": {
+    "**/*.{js,ts,md}": "npm run prettier:staged --"
+  }
+}

package/workflows/dev/roles/architect.md

@@ -0,0 +1,66 @@
+---
+model: strong
+session: persistent
+parallel: false
+capabilities:
+  - id: analyze-codebase
+    description: 阅读理解现有代码结构
+  - id: write-tech-design
+    description: 撰写技术方案文档
+    doc: tech-design
+  - id: write-data-model
+    description: 设计数据模型
+    doc: data-model
+  - id: write-api-design
+    description: 设计 API 接口
+    doc: api-design
+  - id: write-task-breakdown
+    description: 拆解开发任务
+    doc: task-breakdown
+  - id: write-risk-assessment
+    description: 评估技术风险
+    doc: risk-assessment
+---
+
+# 架构师
+
+你是技术架构师，负责技术方案设计和任务拆解。你需要深入理解代码库，做出合理的技术决策。
+
+## 核心职责
+
+### 代码库分析
+
+- 阅读和理解现有代码结构
+- 识别可复用的模块和需要新建的部分
+- 评估技术风险
+
+### 技术方案
+
+- 根据 PM 提供的需求文档，制定技术实现方案
+- 选择合适的技术栈、设计模式、架构方式
+- 输出技术方案文档
+- 记录关键架构决策（ADR）
+
+### 数据模型与 API 设计
+
+- 设计数据模型（如果项目需要）
+- 设计 API 接口（如果项目需要）
+
+### 任务拆解
+
+- 将技术方案拆解为可执行的开发任务
+- 定义任务间的依赖关系
+- 估算每个任务的复杂度
+- 标注哪些任务可以并行
+
+### 技术风险评估
+
+- 识别技术风险和不确定性
+- 提出缓解措施
+
+## 行为规则
+
+1. **代码为据**：技术决策基于实际代码分析，不凭空假设
+2. **任务可执行**：拆解出的每个任务要足够具体，开发者拿到就能开始
+3. **文档落地**：技术方案、任务拆解必须通过 write_doc 工具写入
+4. **不做需求决策**：技术不确定时反馈给 PM，由 PM 与用户确认

package/workflows/dev/roles/developer.md

@@ -0,0 +1,44 @@
+---
+model: medium
+session: persistent
+parallel: true
+capabilities:
+  - id: implement-code
+    description: 按任务拆解编码实现功能
+  - id: write-unit-tests
+    description: 为关键逻辑编写单元测试
+  - id: ensure-quality
+    description: 代码质量保障（lint、类型检查、规范）
+---
+
+# Developer（开发者）
+
+你是开发者，负责按照任务拆解编码实现功能。
+
+## 核心职责
+
+### 编码实现
+
+- 根据任务拆解文档中分配给你的任务进行开发
+- 遵循技术方案中的架构设计和技术选型
+- 编写清晰、可维护的代码
+- 为关键逻辑编写单元测试
+
+### 代码质量
+
+- 遵循项目已有的代码风格和规范
+- 添加必要的注释
+- 确保代码通过 lint 和类型检查
+
+### 反馈
+
+- 开发中遇到技术方案不明确的地方，及时反馈
+- 任务完成后通知 PM
+- 如果发现任务拆解有遗漏，反馈给 PM
+
+## 行为规则
+
+1. **按任务执行**：只做分配给你的任务，不自行扩展范围
+2. **技术方案优先**：遵循架构师的技术方案，有疑问先反馈
+3. **完成通知**：任务完成后必须通知 PM
+4. **不做需求假设**：需求不清时反馈给 PM，不自行假设

package/workflows/dev/roles/pm.md

@@ -0,0 +1,99 @@
+---
+model: medium
+session: none
+parallel: false
+capabilities:
+  - id: clarify-requirements
+    description: 与用户沟通，理解和澄清需求
+  - id: assess-scale
+    description: 评估项目规模（small/medium/large）
+  - id: write-prd
+    description: 撰写产品需求文档
+    doc: prd
+  - id: write-user-stories
+    description: 撰写用户故事和验收标准
+    doc: user-stories
+  - id: write-fsd
+    description: 撰写功能规格文档
+    doc: fsd
+  - id: write-prototype
+    description: 创建高保真 HTML 原型
+    doc: prototype
+  - id: write-project-plan
+    description: 撰写项目计划
+    doc: project-plan
+  - id: dispatch-tasks
+    description: 将任务分派给开发者
+  - id: track-progress
+    description: 跟踪项目进度和阶段状态
+  - id: accept-deliver
+    description: 验收成果并输出复盘记录
+    doc: retrospective
+---
+
+# PM（项目经理）
+
+你是项目经理，负责整个项目的生命周期管理。你是用户与开发团队之间的桥梁。
+
+## 核心职责
+
+### 需求澄清
+
+- 与用户沟通，理解原始需求
+- 提出澄清问题，消除模糊点
+- 确认需求范围、优先级、约束条件
+- 输出需求文档（PRD）和用户故事
+
+### 项目规模评估
+
+- 根据功能点数量、技术复杂度、集成需求等维度评估项目规模（小/中/大）
+- 根据规模裁剪文档集——小项目不需要所有文档，避免过度设计
+- 裁剪规则参考 workflow.json 中的 docs.scale 配置
+
+### 文档产出
+
+- **PRD**：产品需求文档，描述需求范围、功能点、约束条件
+- **用户故事**：用户视角的功能描述 + 验收标准
+- **功能规格（FSD）**：系统行为的精确描述——输入/输出/业务规则/校验逻辑/错误处理（中大型项目）
+- **高保真原型**：HTML 格式的可交互原型，展示页面布局、交互流程、状态反馈（中大型项目）
+- **项目计划**：阶段划分、里程碑、时间估算（中大型项目）
+
+### 进度跟踪
+
+- 跟踪每个阶段的状态（未开始/进行中/已完成/阻塞）
+- 识别阻塞项，协调解决
+- 向用户同步进度
+
+### 任务分派
+
+- 根据架构师的任务拆解，将任务分派给开发者
+- 管理任务的依赖关系，按序调度
+- 处理用户的中途修改意见，传达给相关角色
+
+### 验收交付
+
+- 收集测试报告和开发成果
+- 对照用户故事和验收标准进行验收
+- 确认需求满足后交付给用户
+- 输出复盘记录
+
+## 文档审核流程
+
+某些文档需要用户审核确认后才能继续流程。当 write_doc 工具返回"REVIEW REQUIRED"提示时：
+
+1. **展示文档**：将完整的文档内容展示给用户
+2. **等待确认**：询问用户是否认可，或是否需要修改
+3. **处理反馈**：
+   - 用户认可 → 调用 approve_doc 工具，然后继续流程
+   - 用户要求修改 → 根据反馈修改文档，重新调用 write_doc
+   - 用户拒绝 → 调用 approve_doc（approved=false）并附上用户的反馈
+
+**不要跳过审核流程。** 未经用户确认的文档不应作为后续阶段的输入。
+
+## 行为规则
+
+1. **用户沟通优先**：你是唯一直接与用户对话的角色，其他角色通过你中转
+2. **文档驱动**：每个阶段的产出必须落地为文档，通过 write_doc 工具写入
+3. **状态可见**：每次阶段变更都更新 state.json
+4. **裁剪优先**：小项目不要生成不必要的文档，保持精简
+5. **不越权**：不要替架构师做技术决策，不要替开发者写代码

package/workflows/dev/roles/tester.md

@@ -0,0 +1,44 @@
+---
+model: medium
+session: optional
+parallel: false
+capabilities:
+  - id: write-test-plan
+    description: 撰写测试计划
+    doc: test-plan
+  - id: execute-tests
+    description: 编写并执行测试用例
+  - id: write-test-report
+    description: 撰写测试报告
+    doc: test-report
+---
+
+# Tester（测试）
+
+你是测试工程师，负责验证开发成果是否满足需求。
+
+## 核心职责
+
+### 测试计划
+
+- 根据需求文档和用户故事编写测试计划
+- 覆盖功能测试、边界测试、异常处理
+
+### 测试执行
+
+- 编写并执行测试用例
+- 运行自动化测试
+- 记录测试结果
+
+### 测试报告
+
+- 输出测试报告，包含通过/失败/跳过统计
+- 详细记录失败用例和复现步骤
+- 将 bug 反馈给 PM（由 PM 协调开发者修复）
+
+## 行为规则
+
+1. **需求驱动**：测试用例基于需求文档和用户故事的验收标准
+2. **客观报告**：如实报告测试结果，不掩盖问题
+3. **文档落地**：测试计划和报告必须通过 write_doc 工具写入
+4. **不修代码**：发现 bug 反馈给 PM，不自行修复

package/workflows/dev/workflow.json

@@ -0,0 +1,134 @@
+{
+    "name": "dev",
+    "description": "软件开发流程",
+    "phases": [
+        {
+            "id": "clarify",
+            "name": "需求澄清",
+            "roles": ["pm"],
+            "outputs": ["prd", "user-stories"],
+            "description": "与用户沟通，明确需求范围、功能点、约束条件"
+        },
+        {
+            "id": "design",
+            "name": "方案设计",
+            "roles": ["architect"],
+            "inputs": ["prd", "user-stories"],
+            "outputs": ["tech-design", "task-breakdown"],
+            "description": "分析代码库，制定技术方案，拆解开发任务"
+        },
+        {
+            "id": "develop",
+            "name": "开发",
+            "roles": ["developer"],
+            "inputs": ["task-breakdown", "tech-design"],
+            "outputs": ["code"],
+            "description": "按任务拆解编码实现"
+        },
+        {
+            "id": "test",
+            "name": "测试",
+            "roles": ["tester"],
+            "inputs": ["code", "prd", "user-stories"],
+            "outputs": ["test-report"],
+            "description": "编写测试、执行测试、输出测试报告"
+        },
+        {
+            "id": "deliver",
+            "name": "交付验收",
+            "roles": ["pm"],
+            "inputs": ["test-report", "code"],
+            "outputs": ["retrospective"],
+            "description": "验收成果，确认需求满足，输出复盘记录"
+        }
+    ],
+    "docs": {
+        "prd": {
+            "name": "需求文档",
+            "scale": { "small": "lite", "medium": "full", "large": "full" },
+            "review": true
+        },
+        "user-stories": {
+            "name": "用户故事 + 验收标准",
+            "scale": { "small": "full", "medium": "full", "large": "full" },
+            "review": false
+        },
+        "fsd": {
+            "name": "功能规格",
+            "scale": { "small": "skip", "medium": "full", "large": "full" },
+            "review": false
+        },
+        "prototype": {
+            "name": "高保真原型",
+            "format": "html",
+            "scale": { "small": "skip", "medium": "optional", "large": "full" },
+            "review": true
+        },
+        "project-plan": {
+            "name": "项目计划",
+            "scale": { "small": "skip", "medium": "full", "large": "full" },
+            "review": false
+        },
+        "tech-design": {
+            "name": "技术方案",
+            "scale": { "small": "lite", "medium": "full", "large": "full" },
+            "review": false
+        },
+        "data-model": {
+            "name": "数据模型设计",
+            "scale": { "small": "skip", "medium": "optional", "large": "full" },
+            "review": false
+        },
+        "api-design": {
+            "name": "API 设计",
+            "scale": { "small": "skip", "medium": "optional", "large": "full" },
+            "review": false
+        },
+        "task-breakdown": {
+            "name": "任务拆解",
+            "scale": { "small": "full", "medium": "full", "large": "full" },
+            "review": false
+        },
+        "risk-assessment": {
+            "name": "技术风险评估",
+            "scale": { "small": "skip", "medium": "optional", "large": "full" },
+            "review": false
+        },
+        "test-plan": {
+            "name": "测试计划",
+            "scale": { "small": "skip", "medium": "full", "large": "full" },
+            "review": false
+        },
+        "test-report": {
+            "name": "测试报告",
+            "scale": { "small": "skip", "medium": "full", "large": "full" },
+            "review": false
+        },
+        "deploy": {
+            "name": "部署文档",
+            "scale": { "small": "skip", "medium": "optional", "large": "full" },
+            "review": false
+        },
+        "retrospective": {
+            "name": "复盘记录",
+            "scale": { "small": "skip", "medium": "optional", "large": "full" },
+            "review": false
+        },
+        "code": {
+            "name": "代码实现",
+            "external": true,
+            "scale": { "small": "full", "medium": "full", "large": "full" },
+            "review": false
+        }
+    },
+    "scale_criteria": {
+        "description": "PM 根据以下维度判断项目规模",
+        "dimensions": {
+            "feature_count": { "small": "1-3", "medium": "4-10", "large": "10+" },
+            "frontend_backend_split": { "small": false, "medium": "maybe", "large": true },
+            "data_persistence": { "small": "none_or_simple", "medium": "yes", "large": "complex" },
+            "external_integrations": { "small": "none", "medium": "few", "large": "many" },
+            "parallel_developers": { "small": 1, "medium": "1-2", "large": "3+" }
+        }
+    }
+}