@zhixuan92/multi-model-agent 3.0.0

package/dist/skills/mma-debug/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: mma-debug
+description: Debug a failure using a structured hypothesis. All provided files are investigated together in a single task.
+when_to_use: When a test fails, a build breaks, or unexpected behavior appears and you need a structured investigation with a hypothesis.
+---
+
+## mma-debug
+
+Submit a problem, context, and hypothesis to a sub-agent for focused
+debugging. Unlike other tools, all `filePaths` are investigated together
+in a single task (not parallelised per file).
+
+### Endpoint
+
+`POST /debug?cwd=<abs-path>`
+
+@include _shared/auth.md
+
+### Request body
+
+```json
+{
+  "problem": "POST /login returns 500 when password contains special characters",
+  "context": "Regression introduced in commit abc123; only affects production config",
+  "hypothesis": "The bcrypt binding fails on non-ASCII input in the Docker image",
+  "filePaths": [
+    "/project/src/auth/login.ts",
+    "/project/src/auth/password.ts"
+  ],
+  "contextBlockIds": []
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `problem` | string | yes | What is broken |
+| `context` | string | no | Background information |
+| `hypothesis` | string | no | Initial theory to test |
+| `filePaths` | string[] | no | All files investigated together |
+| `contextBlockIds` | string[] | no | IDs from `mma-context-blocks` |
+
+### Full example
+
+```bash
+BATCH=$(curl -sf -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"problem":"Tests fail on CI only","hypothesis":"Missing env var","filePaths":["/project/src/config.ts"]}' \
+  "http://localhost:$PORT/debug?cwd=/project")
+BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+```
+
+Then poll until complete:
+
+@include _shared/polling.md
+
+@include _shared/response-shape.md
+
+@include _shared/error-handling.md

package/dist/skills/mma-delegate/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: mma-delegate
+description: Fan out ad-hoc implementation or research tasks to sub-agents in parallel. Use when there is no plan file on disk.
+when_to_use: When you need to delegate one or more implementation or research tasks to sub-agents without a pre-existing plan file. Each task runs in parallel.
+---
+
+## mma-delegate
+
+Dispatch one or more tasks to sub-agents concurrently. Each task is an
+independent instruction with optional file scope, acceptance criteria, and
+context block references.
+
+### Endpoint
+
+`POST /delegate?cwd=<abs-path>`
+
+@include _shared/auth.md
+
+### Request body
+
+```json
+{
+  "tasks": [
+    {
+      "prompt": "Add input validation to the login handler",
+      "agentType": "standard",
+      "filePaths": ["/project/src/auth/login.ts"],
+      "done": "All inputs validated; unit tests pass",
+      "contextBlockIds": ["cb_abc123"]
+    }
+  ]
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `tasks` | array | yes | At least one task |
+| `tasks[].prompt` | string | yes | The task instruction |
+| `tasks[].agentType` | string | no | `standard` (default) or `complex` |
+| `tasks[].filePaths` | string[] | no | Files the sub-agent focuses on |
+| `tasks[].done` | string | no | Acceptance criteria |
+| `tasks[].contextBlockIds` | string[] | no | IDs from `mma-context-blocks` |
+
+Use `agentType: "complex"` for ambiguous scope or security-sensitive tasks.
+
+### Full example
+
+```bash
+BATCH=$(curl -sf -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"tasks":[{"prompt":"Refactor utils.ts to remove dead code","filePaths":["/project/src/utils.ts"]}]}' \
+  "http://localhost:$PORT/delegate?cwd=/project")
+BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+```
+
+Then poll until complete:
+
+@include _shared/polling.md
+
+@include _shared/response-shape.md
+
+@include _shared/error-handling.md

package/dist/skills/mma-execute-plan/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: mma-execute-plan
+description: Implement tasks from a plan or spec file on disk. Task descriptors match plan headings; tasks run in parallel.
+when_to_use: When you have a written plan or spec file and want sub-agents to implement specific tasks from it.
+---
+
+## mma-execute-plan
+
+Dispatch named tasks from a plan file to sub-agents. Task descriptors must
+match plan headings (e.g. `"1. Setup database schema"`). All tasks run in
+parallel and duplicate descriptors are rejected.
+
+### Endpoint
+
+`POST /execute-plan?cwd=<abs-path>`
+
+@include _shared/auth.md
+
+### Request body
+
+```json
+{
+  "tasks": [
+    "1. Add input validation to login handler",
+    "2. Write unit tests for the auth module"
+  ],
+  "context": "Tasks 1-5 are complete; auth module already exists at src/auth/",
+  "filePaths": [
+    "/project/docs/plan.md",
+    "/project/src/auth/login.ts"
+  ],
+  "contextBlockIds": []
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `tasks` | string[] | yes | At least one; must be unique; match plan headings |
+| `context` | string | no | Short additional context not in the plan |
+| `filePaths` | string[] | no | Plan file + relevant source files |
+| `contextBlockIds` | string[] | no | IDs from `mma-context-blocks` |
+
+If the batch reaches `awaiting_clarification`, use `mma-clarifications`
+to confirm or correct the proposed interpretation.
+
+### Full example
+
+```bash
+BATCH=$(curl -sf -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"tasks":["3. Migrate database schema"],"filePaths":["/project/docs/plan.md"]}' \
+  "http://localhost:$PORT/execute-plan?cwd=/project")
+BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+```
+
+Then poll until complete:
+
+@include _shared/polling.md
+
+@include _shared/response-shape.md
+
+@include _shared/error-handling.md

package/dist/skills/mma-retry/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: mma-retry
+description: Re-run specific failed or incomplete tasks from a previous batch by index.
+when_to_use: When some tasks in a previous batch failed or returned incomplete results and you want to re-run only those tasks without re-running the whole batch.
+---
+
+## mma-retry
+
+Re-run selected tasks from a completed or failed batch. Specify the original
+`batchId` and the zero-based indices of the tasks to re-run. The retry runs
+those tasks fresh with the same configuration as the original batch.
+
+### Endpoint
+
+`POST /retry?cwd=<abs-path>`
+
+@include _shared/auth.md
+
+### Request body
+
+```json
+{
+  "batchId": "550e8400-e29b-41d4-a716-446655440000",
+  "taskIndices": [1, 3]
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `batchId` | string (UUID) | yes | Batch ID from a previous dispatch |
+| `taskIndices` | number[] | yes | Zero-based indices to re-run |
+
+`taskIndices` must be non-negative integers. To re-run all tasks, pass all
+indices from `0` to `tasks.length - 1`.
+
+### Full example
+
+```bash
+# Original batch had 4 tasks; re-run tasks at index 1 and 3
+BATCH=$(curl -sf -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"batchId":"550e8400-e29b-41d4-a716-446655440000","taskIndices":[1,3]}' \
+  "http://localhost:$PORT/retry?cwd=/project")
+BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+```
+
+The retry produces a new `batchId`. Poll the new ID until complete:
+
+@include _shared/polling.md
+
+@include _shared/response-shape.md
+
+@include _shared/error-handling.md

package/dist/skills/mma-review/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: mma-review
+description: Review code for quality, security, performance, or correctness. Sub-agents run in parallel per file.
+when_to_use: When you need an independent code review after implementing a feature or fix, or before merging a branch.
+---
+
+## mma-review
+
+Send code or files to sub-agents for structured review. Each file is reviewed
+independently in parallel; results are index-aligned with `filePaths`.
+
+### Endpoint
+
+`POST /review?cwd=<abs-path>`
+
+@include _shared/auth.md
+
+### Request body
+
+```json
+{
+  "code": "inline code snippet (optional if filePaths given)",
+  "focus": ["correctness", "security"],
+  "filePaths": ["/project/src/auth/login.ts"],
+  "contextBlockIds": []
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `code` | string | no | Inline code to review |
+| `focus` | string[] | no | Any of `security`, `performance`, `correctness`, `style` |
+| `filePaths` | string[] | no | Files to review (parallel) |
+| `contextBlockIds` | string[] | no | IDs from `mma-context-blocks` |
+
+Either `code` or `filePaths` (or both) must be provided.
+
+### Full example
+
+```bash
+BATCH=$(curl -sf -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"focus":["security","correctness"],"filePaths":["/project/src/auth/login.ts"]}' \
+  "http://localhost:$PORT/review?cwd=/project")
+BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+```
+
+Then poll until complete:
+
+@include _shared/polling.md
+
+@include _shared/response-shape.md
+
+@include _shared/error-handling.md

package/dist/skills/mma-verify/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: mma-verify
+description: Verify work against a checklist. Sub-agents check each item independently.
+when_to_use: When you need to confirm that implemented work meets a set of acceptance criteria or a review checklist before claiming completion.
+---
+
+## mma-verify
+
+Submit work product and a checklist to sub-agents for independent verification.
+Each checklist item is verified in parallel; results are index-aligned.
+
+### Endpoint
+
+`POST /verify?cwd=<abs-path>`
+
+@include _shared/auth.md
+
+### Request body
+
+```json
+{
+  "work": "inline description of the work (optional if filePaths given)",
+  "checklist": [
+    "All public functions have JSDoc comments",
+    "No console.log statements remain",
+    "Unit tests cover the happy path and at least one error case"
+  ],
+  "filePaths": ["/project/src/utils.ts"],
+  "contextBlockIds": []
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `work` | string | no | Inline work product description |
+| `checklist` | string[] | yes | At least one item |
+| `filePaths` | string[] | no | Files to verify against (parallel) |
+| `contextBlockIds` | string[] | no | IDs from `mma-context-blocks` |
+
+### Full example
+
+```bash
+BATCH=$(curl -sf -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"checklist":["Error handler exists","Tests pass"],"filePaths":["/project/src/handler.ts"]}' \
+  "http://localhost:$PORT/verify?cwd=/project")
+BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+```
+
+Then poll until complete:
+
+@include _shared/polling.md
+
+@include _shared/response-shape.md
+
+@include _shared/error-handling.md

package/dist/skills/multi-model-agent/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: multi-model-agent
+description: Overview of the multi-model-agent local service. Use this skill to understand which specialized mma-* skill to invoke for a given task.
+when_to_use: When the user asks about delegating tool-using work, or when auth/setup issues arise before a specific mma-* skill can run.
+---
+
+## multi-model-agent overview
+
+multi-model-agent is a local HTTP service that fans out tool-using work to
+sub-agents running on different LLM providers (Claude, OpenAI-compatible, Codex).
+
+### Setup check
+
+```bash
+curl -s http://localhost:$PORT/health
+# expects: { "ok": true }
+```
+
+If this fails, start the server:
+```bash
+mmagent serve
+```
+
+### Auth token
+
+Set the token in your environment:
+```bash
+export MMAGENT_AUTH_TOKEN=$(mmagent print-token)
+```
+
+Or read it from the env var `MMAGENT_AUTH_TOKEN` if already set.
+Every request requires `Authorization: Bearer <token>`.
+
+### Skill map
+
+| Skill | Purpose |
+|---|---|
+| `mma-delegate` | Ad-hoc implementation/research (no plan file) |
+| `mma-audit` | Audit a document for security, correctness, style, or performance |
+| `mma-review` | Review code for quality, security, or correctness |
+| `mma-verify` | Verify work against a checklist |
+| `mma-debug` | Debug a failure with a structured hypothesis |
+| `mma-execute-plan` | Implement tasks from a plan or spec file |
+| `mma-retry` | Re-run specific failed tasks from a previous batch |
+| `mma-context-blocks` | Register large reused documents to reference by ID |
+| `mma-clarifications` | Confirm or correct the service's proposed interpretation |
+
+### General flow
+
+1. Call the appropriate `mma-*` skill → receive `{ batchId }`.
+2. Poll `GET /batch/:id` until `state` is terminal.
+3. Read `results` from the completed batch.
+
+If the batch reaches `awaiting_clarification`, use `mma-clarifications`
+to confirm or correct the proposed interpretation before the batch resumes.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@zhixuan92/multi-model-agent",
+  "version": "3.0.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Standalone HTTP server for multi-model-agent. Routes tool-invocation work to Claude, Codex, or OpenAI-compatible sub-agents with async-polling REST dispatch and installable skills for Claude Code, Gemini CLI, Codex CLI, and Cursor.",
+  "author": "Zhang Zhixuan <zhangzhixuan312@gmail.com>",
+  "keywords": [
+    "llm",
+    "claude",
+    "codex",
+    "openai",
+    "agent",
+    "multi-model",
+    "delegation",
+    "http-server"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhixuan312/multi-model-agent.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://github.com/zhixuan312/multi-model-agent#readme",
+  "bugs": "https://github.com/zhixuan312/multi-model-agent/issues",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mmagent": "dist/cli/index.js",
+    "multi-model-agent": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/http/server.d.ts",
+      "import": "./dist/http/server.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc && rm -rf dist/skills && cp -R src/skills dist/skills && chmod +x dist/cli/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@asteasolutions/zod-to-openapi": "^8.5.0",
+    "@zhixuan92/multi-model-agent-core": "^3.0.0",
+    "minimist": "^1.2.8",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/minimist": "^1.2.5"
+  }
+}