@s_s/harmonia 1.0.0

package/build/index.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * Harmonia — Multi-agent orchestration MCP server with pluggable workflows.
+ *
+ * All project data is stored under the Harmonia data directory (platform-specific).
+ * Project source directories contain code only — no Harmonia artifacts.
+ *
+ * Provides tools for managing projects:
+ * - project_init: Register a project and create <data_dir>/<project_name>/ data dirs
+ * - get_project_status: View current project phase and progress
+ * - get_role_prompt: Get role prompts for agent setup
+ * - update_phase: Advance project phases
+ * - write_doc / read_doc / list_docs: Manage project documents
+ */
+export {};

package/build/index.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * Harmonia — Multi-agent orchestration MCP server with pluggable workflows.
+ *
+ * All project data is stored under the Harmonia data directory (platform-specific).
+ * Project source directories contain code only — no Harmonia artifacts.
+ *
+ * Provides tools for managing projects:
+ * - project_init: Register a project and create <data_dir>/<project_name>/ data dirs
+ * - get_project_status: View current project phase and progress
+ * - get_role_prompt: Get role prompts for agent setup
+ * - update_phase: Advance project phases
+ * - write_doc / read_doc / list_docs: Manage project documents
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { registerProjectInit } from './tools/project-init.js';
+import { registerGetRolePrompt } from './tools/get-role-prompt.js';
+import { registerUpdatePhase } from './tools/update-phase.js';
+import { registerDocTools } from './tools/doc-tools.js';
+import { registerGetProjectStatus } from './tools/get-project-status.js';
+import { registerApproveDoc } from './tools/approve-doc.js';
+import { registerOverrideTools } from './tools/override-tools.js';
+import { registerDispatchRole } from './tools/dispatch-role.js';
+import { registerReportDispatch } from './tools/report-dispatch.js';
+import { registerSetupProject } from './tools/setup-project.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Workflows directory is at the package root, sibling to build/
+const WORKFLOWS_DIR = process.env.HARMONIA_WORKFLOWS_DIR ?? resolve(join(__dirname, '..', 'workflows'));
+const server = new McpServer({
+    name: 'harmonia',
+    version: '0.1.0',
+});
+// Register all tools
+registerProjectInit(server, WORKFLOWS_DIR);
+registerGetRolePrompt(server, WORKFLOWS_DIR);
+registerUpdatePhase(server, WORKFLOWS_DIR);
+registerDocTools(server, WORKFLOWS_DIR);
+registerGetProjectStatus(server, WORKFLOWS_DIR);
+registerApproveDoc(server);
+registerOverrideTools(server);
+registerDispatchRole(server, WORKFLOWS_DIR);
+registerReportDispatch(server);
+registerSetupProject(server);
+// Connect via stdio
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,gEAAgE;AAChE,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC;AAExG,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IACzB,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,OAAO;CACnB,CAAC,CAAC;AAEH,qBAAqB;AACrB,mBAAmB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC3C,qBAAqB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC7C,mBAAmB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC3C,gBAAgB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AACxC,wBAAwB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAChD,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC3B,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAC9B,oBAAoB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC5C,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAE7B,oBAAoB;AACpB,KAAK,UAAU,IAAI;IACf,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AACpC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACjB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;IACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC,CAAC,CAAC"}

package/build/setup/inject.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Setup injection — detect host agent type and inject PM guidance into config.
+ *
+ * V1 supports only OpenCode (AGENTS.md injection).
+ * The injection is idempotent — re-running replaces existing harmonia block.
+ */
+import { type PromptTemplateParams } from './templates.js';
+/** Supported host agent types */
+export type HostAgentType = 'opencode' | 'claude-code' | 'codex';
+/**
+ * Detect the host agent type for a given project directory.
+ *
+ * V1 heuristic:
+ * - Check for AGENTS.md → opencode
+ * - Check for .claude/ dir → claude-code
+ * - Default to opencode (most common)
+ *
+ * Future: accept explicit override via parameter.
+ */
+export declare function detectHostAgent(projectDir: string): Promise<HostAgentType>;
+/**
+ * Inject the Harmonia PM guidance block into a config file.
+ * If a harmonia block already exists, it is replaced (idempotent).
+ * If the file doesn't exist, it is created.
+ */
+export declare function injectPrompt(projectDir: string, agentType: HostAgentType, params: PromptTemplateParams): Promise<{
+    filePath: string;
+    created: boolean;
+    replaced: boolean;
+}>;
+/**
+ * Remove the Harmonia block from a config file.
+ */
+export declare function removePrompt(projectDir: string, agentType: HostAgentType): Promise<boolean>;

package/build/setup/inject.js

@@ -0,0 +1,115 @@
+/**
+ * Setup injection — detect host agent type and inject PM guidance into config.
+ *
+ * V1 supports only OpenCode (AGENTS.md injection).
+ * The injection is idempotent — re-running replaces existing harmonia block.
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { generateOpenCodePrompt, HARMONIA_MARKER_START, HARMONIA_MARKER_END, } from './templates.js';
+/**
+ * Detect the host agent type for a given project directory.
+ *
+ * V1 heuristic:
+ * - Check for AGENTS.md → opencode
+ * - Check for .claude/ dir → claude-code
+ * - Default to opencode (most common)
+ *
+ * Future: accept explicit override via parameter.
+ */
+export async function detectHostAgent(projectDir) {
+    // Check for .claude directory (Claude Code)
+    try {
+        await readFile(join(projectDir, '.claude', 'settings.json'), 'utf-8');
+        return 'claude-code';
+    }
+    catch {
+        // not claude-code
+    }
+    // Default to opencode
+    return 'opencode';
+}
+/**
+ * Get the config file path for a host agent type.
+ */
+function getConfigPath(projectDir, agentType) {
+    switch (agentType) {
+        case 'opencode':
+            return join(projectDir, 'AGENTS.md');
+        case 'claude-code':
+            return join(projectDir, 'CLAUDE.md');
+        case 'codex':
+            return join(projectDir, 'AGENTS.md');
+    }
+}
+/**
+ * Inject the Harmonia PM guidance block into a config file.
+ * If a harmonia block already exists, it is replaced (idempotent).
+ * If the file doesn't exist, it is created.
+ */
+export async function injectPrompt(projectDir, agentType, params) {
+    const filePath = getConfigPath(projectDir, agentType);
+    const prompt = generateOpenCodePrompt(params);
+    let existingContent = '';
+    let fileExists = true;
+    try {
+        existingContent = await readFile(filePath, 'utf-8');
+    }
+    catch {
+        fileExists = false;
+    }
+    let replaced = false;
+    let newContent;
+    if (fileExists && existingContent.includes(HARMONIA_MARKER_START)) {
+        // Replace existing harmonia block
+        const startIdx = existingContent.indexOf(HARMONIA_MARKER_START);
+        const endIdx = existingContent.indexOf(HARMONIA_MARKER_END) + HARMONIA_MARKER_END.length;
+        if (endIdx > startIdx) {
+            newContent = existingContent.substring(0, startIdx) + prompt + existingContent.substring(endIdx);
+            replaced = true;
+        }
+        else {
+            // Malformed markers — append
+            newContent = existingContent + '\n\n' + prompt + '\n';
+        }
+    }
+    else if (fileExists) {
+        // Append to existing file
+        newContent = existingContent + '\n\n' + prompt + '\n';
+    }
+    else {
+        // Create new file
+        newContent = prompt + '\n';
+    }
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, newContent, 'utf-8');
+    return { filePath, created: !fileExists, replaced };
+}
+/**
+ * Remove the Harmonia block from a config file.
+ */
+export async function removePrompt(projectDir, agentType) {
+    const filePath = getConfigPath(projectDir, agentType);
+    try {
+        const content = await readFile(filePath, 'utf-8');
+        if (!content.includes(HARMONIA_MARKER_START))
+            return false;
+        const startIdx = content.indexOf(HARMONIA_MARKER_START);
+        const endIdx = content.indexOf(HARMONIA_MARKER_END) + HARMONIA_MARKER_END.length;
+        if (endIdx <= startIdx)
+            return false;
+        // Remove the block and any surrounding blank lines
+        let newContent = content.substring(0, startIdx) + content.substring(endIdx);
+        newContent = newContent.replace(/\n{3,}/g, '\n\n').trim();
+        if (newContent.length === 0) {
+            // File would be empty — could delete it, but safer to leave empty
+            newContent = '';
+        }
+        await writeFile(filePath, newContent + '\n', 'utf-8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=inject.js.map

package/build/setup/inject.js.map

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

package/build/setup/templates.d.ts

@@ -0,0 +1,21 @@
+/**
+ * PM guidance prompt template for OpenCode.
+ *
+ * This template is injected into the project's AGENTS.md to guide the host
+ * agent to act as the PM role in a Harmonia-managed project.
+ */
+export interface PromptTemplateParams {
+    projectName: string;
+    projectDir: string;
+    workflow: string;
+    scale: string;
+}
+/**
+ * Generate the PM guidance prompt for OpenCode AGENTS.md injection.
+ */
+export declare function generateOpenCodePrompt(params: PromptTemplateParams): string;
+/**
+ * The marker tags used to identify Harmonia-injected content in AGENTS.md.
+ */
+export declare const HARMONIA_MARKER_START = "<!-- harmonia:start -->";
+export declare const HARMONIA_MARKER_END = "<!-- harmonia:end -->";

package/build/setup/templates.js

@@ -0,0 +1,177 @@
+/**
+ * PM guidance prompt template for OpenCode.
+ *
+ * This template is injected into the project's AGENTS.md to guide the host
+ * agent to act as the PM role in a Harmonia-managed project.
+ */
+/**
+ * Generate the PM guidance prompt for OpenCode AGENTS.md injection.
+ */
+export function generateOpenCodePrompt(params) {
+    return `<!-- harmonia:start -->
+## Harmonia — Project Manager Mode
+
+You are the **PM (Project Manager)** for project **${params.projectName}**.
+Harmonia is managing the project workflow. You are the central coordinator — the only role that talks directly to the user.
+
+- **Project directory**: ${params.projectDir}
+- **Workflow**: ${params.workflow}
+- **Scale**: ${params.scale}
+
+### Your Responsibilities
+
+1. **Communicate with the user** — clarify requirements, present documents for review, report progress
+2. **Drive the workflow** — advance phases, produce documents, dispatch tasks to team members
+3. **Coordinate the team** — dispatch roles, track sessions and dispatch progress, manage outputs
+4. **Ensure quality** — review documents, handle review cycles, verify deliverables
+
+### Available Harmonia Tools
+
+| Tool | When to Use |
+|------|-------------|
+| \`get_project_status\` | Check current phase, progress, sessions, dispatches, pending reviews, next steps |
+| \`get_role_prompt\` | View any role's prompt and configuration |
+| \`update_phase\` | Advance or update a phase's status |
+| \`write_doc\` | Write/update a project document (auto-triggers review if configured) |
+| \`read_doc\` | Read a project document |
+| \`list_docs\` | List all project documents |
+| \`dispatch_role\` | Prepare data + create dispatch record for a team member (auto-detects reusable sessions) |
+| \`report_dispatch\` | Report dispatch status: register agent session after launch, report completion/failure |
+| \`approve_doc\` | Approve or reject a document after user review |
+| \`list_pending_reviews\` | Check which documents are awaiting user approval |
+| \`set_capability_override\` | Configure a role to use an external tool for a capability |
+| \`set_review_override\` | Enable/disable review for a document type |
+| \`get_overrides\` | View current override configuration |
+
+### Workflow Guide
+
+#### Phase 1: Requirements Clarification (\`clarify\`)
+
+1. Talk to the user to understand their needs
+2. Write the PRD: \`write_doc(project_name, "prd", content)\`
+3. Write user stories: \`write_doc(project_name, "user-stories", content)\`
+4. If the project is medium/large, also write: FSD, prototype (HTML), project plan
+5. Handle review cycles — when \`write_doc\` returns "REVIEW REQUIRED", present the document to the user and wait for confirmation
+6. After all clarify-phase documents are approved, advance: \`update_phase(project_name, "clarify", "completed")\`
+
+#### Phase 2: Design (\`design\`)
+
+1. Dispatch the architect: \`dispatch_role(project_name, "architect", task_brief)\`
+2. Follow the dispatch workflow (see below) to launch and track the architect
+3. The architect will produce: tech-design, task-breakdown (and optionally: data-model, api-design, risk-assessment)
+4. Review the architect's output, ask user for feedback if needed
+5. Advance: \`update_phase(project_name, "design", "completed")\`
+
+#### Phase 3: Development (\`develop\`)
+
+1. Read the task breakdown: \`read_doc(project_name, "task-breakdown")\`
+2. Dispatch developers for each task (or batch): \`dispatch_role(project_name, "developer", task_brief)\`
+3. Developers can work in parallel if tasks are independent — each gets their own dispatch and session
+4. Track progress with \`get_project_status\` — it shows all active sessions and dispatch records
+5. Advance when all tasks are complete: \`update_phase(project_name, "develop", "completed")\`
+
+#### Phase 4: Testing (\`test\`)
+
+1. Dispatch the tester: \`dispatch_role(project_name, "tester", task_brief)\`
+2. Follow the dispatch workflow to launch and track the tester
+3. Tester writes test plan, executes tests, produces test report
+4. If bugs are found, coordinate fixes with developers (re-dispatch as needed)
+5. Advance: \`update_phase(project_name, "test", "completed")\`
+
+#### Phase 5: Delivery (\`deliver\`)
+
+1. Review all deliverables against user stories and acceptance criteria
+2. Present final results to the user
+3. Write retrospective: \`write_doc(project_name, "retrospective", content)\`
+4. Advance: \`update_phase(project_name, "deliver", "completed")\`
+
+### Dispatch Workflow (Critical — follow every time)
+
+Dispatching a team member follows three steps:
+
+#### Step 1: Dispatch
+\`\`\`
+dispatch_role(project_name, role, task_brief)
+→ Returns: data package + dispatch_id + session guidance
+\`\`\`
+Harmonia automatically:
+- Creates a dispatch record for tracking
+- Checks for reusable idle sessions and tells you whether to resume or launch new
+
+#### Step 2: Launch & Report
+Launch the agent based on the session guidance:
+- **If reusable session found**: Resume the existing agent session (use the agent session ID provided)
+- **If no reusable session**: Launch a new agent
+
+After launching, immediately report:
+\`\`\`
+report_dispatch(project_name, dispatch_id, agent_session_id="<id from agent>", agent_type="opencode")
+\`\`\`
+This registers the session and marks the dispatch as running.
+
+#### Step 3: Completion
+When the agent finishes (process exits or session ends):
+\`\`\`
+report_dispatch(project_name, dispatch_id, status="completed")
+\`\`\`
+Or if it failed:
+\`\`\`
+report_dispatch(project_name, dispatch_id, status="failed", note="reason")
+\`\`\`
+Then check: \`get_project_status\` to verify outputs and determine next steps.
+
+### Launching Agents
+
+#### If you are an OpenClaw agent (sessions_spawn)
+Use \`sessions_spawn\` to launch a sub-agent. The sub-agent automatically shares the gateway-level MCP configuration, so it can use all Harmonia tools (write_doc, read_doc, etc.) without additional setup.
+
+\`\`\`
+sessions_spawn with:
+- system prompt = the role prompt from dispatch_role
+- task = the task brief
+- The sub-agent has access to all configured MCP servers including Harmonia
+\`\`\`
+
+#### For other agents (shell exec)
+Launch the agent via shell command (\`exec\`). You need to:
+1. Start the agent process with the role prompt as system instructions
+2. Pass the task brief and input documents as the initial message
+3. Wait for the process to exit
+
+### Session Recovery (after interruption)
+
+If you were interrupted or are resuming from a previous session:
+
+1. **Start with** \`get_project_status\` — it shows everything: phases, active sessions, dispatch records, pending reviews
+2. **Check dispatch records** — any "running" dispatches may need verification (did the agent finish?)
+3. **Check sessions** — "active" sessions may have agents still running; "idle" sessions can be reused; "lost" sessions need re-dispatch
+4. **Follow the next steps** suggested by \`get_project_status\`
+
+### Document Review Flow
+
+Some documents require user approval (PRD, prototype by default).
+When \`write_doc\` returns "REVIEW REQUIRED":
+
+1. Present the full document to the user
+2. Ask if they approve or want changes
+3. If approved → call \`approve_doc(project_name, doc_id, true)\`
+4. If changes needed → revise and call \`write_doc\` again
+5. **Never skip review.** Unapproved documents must not be used as input for subsequent phases.
+
+### Important Rules
+
+1. **Always check status first** — start each session with \`get_project_status\` to understand where you are
+2. **Always report dispatch lifecycle** — dispatch → report launch → report completion. Never skip report_dispatch.
+3. **Document everything** — every phase output must be saved via \`write_doc\`
+4. **Don't skip phases** — follow the workflow order unless blocked
+5. **Don't make technical decisions** — that's the architect's job; ask them via \`dispatch_role\`
+6. **Don't write code** — that's the developer's job
+7. **Scale appropriately** — small projects don't need all documents; check the scale setting
+<!-- harmonia:end -->`;
+}
+/**
+ * The marker tags used to identify Harmonia-injected content in AGENTS.md.
+ */
+export const HARMONIA_MARKER_START = '<!-- harmonia:start -->';
+export const HARMONIA_MARKER_END = '<!-- harmonia:end -->';
+//# sourceMappingURL=templates.js.map

package/build/setup/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/setup/templates.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAA4B;IAC/D,OAAO;;;qDAG0C,MAAM,CAAC,WAAW;;;2BAG5C,MAAM,CAAC,UAAU;kBAC1B,MAAM,CAAC,QAAQ;eAClB,MAAM,CAAC,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAuJL,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,yBAAyB,CAAC;AAC/D,MAAM,CAAC,MAAM,mBAAmB,GAAG,uBAAuB,CAAC"}

package/build/tools/approve-doc.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP Tool: approve_doc
+ * Approve or reject a document that is pending review.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerApproveDoc(server: McpServer): void;

package/build/tools/approve-doc.js

@@ -0,0 +1,79 @@
+/**
+ * MCP Tool: approve_doc
+ * Approve or reject a document that is pending review.
+ */
+import { z } from 'zod';
+import { resolveReview, getPendingReviews } from '../core/reviews.js';
+export function registerApproveDoc(server) {
+    server.tool('approve_doc', 'Approve or reject a document pending review. Call this after the user has reviewed the document and confirmed (or requested changes).', {
+        project_name: z.string().describe('Project name'),
+        doc_id: z.string().describe('Document ID to approve/reject'),
+        approved: z.boolean().describe('true = approved, false = rejected (needs revision)'),
+        comment: z.string().optional().describe('Optional comment — user feedback or reason for rejection'),
+    }, async ({ project_name, doc_id, approved, comment }) => {
+        try {
+            const status = approved ? 'approved' : 'rejected';
+            const review = await resolveReview(project_name, doc_id, status, comment);
+            if (approved) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Document "${doc_id}" approved. You may proceed with the workflow.`,
+                        },
+                    ],
+                };
+            }
+            else {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: [
+                                `Document "${doc_id}" rejected.`,
+                                comment ? `User feedback: ${comment}` : '',
+                                `Please revise the document based on the feedback and call write_doc again.`,
+                            ].join('\n'),
+                        },
+                    ],
+                };
+            }
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool('list_pending_reviews', 'List all documents currently pending user review.', {
+        project_name: z.string().describe('Project name'),
+    }, async ({ project_name }) => {
+        const pending = await getPendingReviews(project_name);
+        if (pending.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No documents pending review.',
+                    },
+                ],
+            };
+        }
+        const list = pending.map((r) => `- ${r.docId} (submitted: ${r.submittedAt})`).join('\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Documents pending review:\n${list}`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=approve-doc.js.map

package/build/tools/approve-doc.js.map

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

package/build/tools/dispatch-role.d.ts

@@ -0,0 +1,16 @@
+/**
+ * MCP Tool: dispatch_role
+ *
+ * Prepare all data needed to hand off a task to a team member role.
+ * Returns: role prompt (with overrides injected), frontmatter config,
+ * input documents, task brief, and dispatch tracking info.
+ *
+ * Automatically:
+ * - Creates a dispatch record for tracking
+ * - Searches for reusable idle sessions and provides guidance
+ *
+ * This tool does NOT launch agents — it only prepares the data.
+ * The host agent (PM) decides how to pass this to the team member.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDispatchRole(server: McpServer, workflowsDir: string): void;