openclaw-swarm-layer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xu Cheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+<div align="center">
+
+# OpenClaw Swarm Layer
+
+### Spec-Driven Workflow Orchestration for AI Agent Swarms
+
+**The Evolution of Agent Orchestration:** Spec &rarr; Plan &rarr; Execute &rarr; Review &rarr; Ship
+
+Turn workflow specifications into executable task graphs, dispatch through pluggable runners, and orchestrate multi-agent collaboration with persistent sessions.
+
+[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-green.svg)](https://nodejs.org)
+[![OpenClaw](https://img.shields.io/badge/OpenClaw-%3E%3D2026.2-purple.svg)](https://openclaw.dev)
+[![Tests](https://img.shields.io/badge/Tests-187%20unit%20%7C%2022%20e2e-brightgreen.svg)](#development)
+
+[Quick Start](#quick-start) &bull; [Features](#features) &bull; [CLI Reference](#cli-commands) &bull; [Configuration](docs/configuration.md) &bull; [License](LICENSE)
+
+![TypeScript](https://img.shields.io/badge/TypeScript-Strict-3178C6?logo=typescript&logoColor=white)
+![OpenClaw Plugin](https://img.shields.io/badge/OpenClaw-Plugin-8B5CF6)
+![ACP Runner](https://img.shields.io/badge/Runner-ACP-FF6B35)
+![Subagent Runner](https://img.shields.io/badge/Runner-Subagent-0EA5E9)
+![Session Reuse](https://img.shields.io/badge/Session-Reuse-10B981)
+![Thread Binding](https://img.shields.io/badge/Thread-Binding-F59E0B)
+![Review Gates](https://img.shields.io/badge/Review-Gates-EF4444)
+
+</div>
+
+---
+
+## Features
+
+- **Spec-driven orchestration** — import a spec, generate a task graph, execute in dependency order
+- **Multiple runners** — manual (operator-driven), ACP (external harness), subagent (OpenClaw-native)
+- **Review gates** — tasks require approval before marking done
+- **Session management** — persistent sessions with reuse, thread binding, follow-up/steer
+- **Automatic retry** — configurable retry policy with dead letter tracking
+- **Operator UX** — attention items, highlights, recommended actions, reports
+- **Report sync** — local reports + optional Obsidian vault sync
+
+## Prerequisites
+
+- Node.js >= 22
+- [OpenClaw](https://openclaw.dev) >= 2026.2.24
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/xucheng/openclaw-swarm-layer.git
+cd openclaw-swarm-layer
+npm install
+npm run build
+
+# Install as an OpenClaw plugin
+openclaw plugins install -l /path/to/openclaw-swarm-layer
+```
+
+## Quick Start
+
+```bash
+# 1. Initialize a project
+openclaw swarm init --project /path/to/your/project
+
+# 2. Write a spec file (Markdown with Goals/Phases/Tasks sections)
+cat > SPEC.md << 'EOF'
+# My Workflow
+
+## Goals
+- Build and test the feature
+
+## Phases
+### Phase 1
+- Implement the core logic
+- Write unit tests
+### Phase 2
+- Integration testing
+EOF
+
+# 3. Import the spec and generate task graph
+openclaw swarm plan --project . --spec SPEC.md
+
+# 4. Check status
+openclaw swarm status --project .
+
+# 5. Execute (dry-run first)
+openclaw swarm run --project . --dry-run
+openclaw swarm run --project .
+
+# 6. Review completed tasks
+openclaw swarm review --project . --task <taskId> --approve
+
+# 7. Generate report
+openclaw swarm report --project .
+```
+
+## CLI Commands
+
+### Core Workflow
+| Command | Description |
+|---------|-------------|
+| `swarm init --project <path>` | Initialize swarm state for a project |
+| `swarm status --project <path>` | Show workflow status with attention items |
+| `swarm plan --project <path> --spec <path>` | Import spec and build task graph |
+| `swarm run --project <path> [--runner acp\|manual\|subagent] [--dry-run]` | Execute next runnable task |
+| `swarm review --project <path> --task <id> --approve\|--reject` | Approve or reject a task |
+| `swarm report --project <path>` | Generate workflow report |
+| `swarm doctor` | Diagnose bridge compatibility |
+
+### Session Management
+| Command | Description |
+|---------|-------------|
+| `swarm session list --project <path>` | List all sessions |
+| `swarm session inspect --project <path> --session <id>` | Inspect a session |
+| `swarm session status --project <path> --run <id>` | Poll session status |
+| `swarm session cancel --project <path> --run <id>` | Cancel an active session |
+| `swarm session close --project <path> --run <id>` | Close a session |
+| `swarm session follow-up --project <path> --session <id> --task <desc>` | Inject follow-up task |
+| `swarm session steer --project <path> --session <id> --message <text>` | Send steering message |
+| `swarm session cleanup --project <path> [--stale-minutes <n>]` | Clean up orphaned sessions |
+
+## Architecture
+
+```
+CLI (src/cli/)  <->  Tools (src/tools/)
+        |                  |
+   SwarmOrchestrator (src/services/orchestrator.ts)
+        |
+   RunnerRegistry -> TaskRunner implementations
+        |                    |                |
+   ManualRunner        AcpRunner        SubagentRunner
+        |
+   StateStore + SessionStore (src/state/, src/session/)
+```
+
+See [docs/configuration.md](docs/configuration.md) for all configuration options.
+
+## Development
+
+```bash
+npm run build          # TypeScript -> dist/
+npm test               # Unit + e2e tests
+npm run test:unit      # Unit tests only
+npm run test:e2e       # E2E tests only
+npm run test:watch     # Watch mode
+```
+
+## Documentation
+
+**User Guides:**
+- [User Manual](docs/user-manual.md) — complete usage guide from install to daily operations (Chinese)
+- [Skills Guide](docs/skills-guide.md) — unified skill with 5 modules (setup/operate/diagnose/report/tools)
+- [Configuration Reference](docs/configuration.md) — all config options, journal setup, directory structure
+
+**Operations:**
+- [Operator Runbook](docs/operator-runbook.md) — install, smoke test, upgrade, rollback
+- [Migration Checklist](docs/migration-checklist.md) — bridge replacement strategy
+
+**Project History:**
+- [Roadmap](docs/roadmap.md) — M1-M3 milestone structure
+- [Milestones](docs/milestones.md) — definition of done per milestone
+- [Current Plan](docs/current-plan.md) — delivery status and future directions
+
+## License
+
+[MIT](LICENSE)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).

package/dist/src/cli/context.d.ts

@@ -0,0 +1,18 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+import type { SwarmPluginConfig } from "../config.js";
+import { type OpenClawSessionAdapter } from "../runtime/openclaw-session-adapter.js";
+import { type OpenClawSubagentAdapter } from "../runtime/openclaw-subagent-adapter.js";
+import { SessionStore } from "../session/session-store.js";
+import { StateStore } from "../state/state-store.js";
+export type SwarmCliContext = {
+    config?: Partial<SwarmPluginConfig>;
+    stateStore?: StateStore;
+    sessionStore?: SessionStore;
+    sessionAdapter?: OpenClawSessionAdapter;
+    subagentAdapter?: OpenClawSubagentAdapter;
+    runtime?: Pick<PluginRuntime, "config" | "system">;
+};
+export declare function resolveStateStore(context?: SwarmCliContext): StateStore;
+export declare function resolveSessionStore(context?: SwarmCliContext): SessionStore;
+export declare function resolveSessionAdapter(context?: SwarmCliContext): OpenClawSessionAdapter;
+export declare function resolveSubagentAdapter(context?: SwarmCliContext): OpenClawSubagentAdapter;

package/dist/src/cli/context.js

@@ -0,0 +1,60 @@
+import { defaultSwarmPluginConfig } from "../config.js";
+import { createBridgeSessionAdapter } from "../runtime/bridge-openclaw-session-adapter.js";
+import { createBridgeSubagentAdapter } from "../runtime/bridge-openclaw-subagent-adapter.js";
+import { UnsupportedOpenClawSessionAdapter } from "../runtime/openclaw-session-adapter.js";
+import { UnsupportedOpenClawSubagentAdapter } from "../runtime/openclaw-subagent-adapter.js";
+import { createSessionAdapter } from "../runtime/real-openclaw-session-adapter.js";
+import { SessionStore } from "../session/session-store.js";
+import { StateStore } from "../state/state-store.js";
+export function resolveStateStore(context) {
+    return context?.stateStore ?? new StateStore(context?.config);
+}
+export function resolveSessionStore(context) {
+    return context?.sessionStore ?? new SessionStore(context?.stateStore?.config ?? context?.config);
+}
+export function resolveSessionAdapter(context) {
+    if (context?.sessionAdapter) {
+        return context.sessionAdapter;
+    }
+    const config = context?.stateStore?.config
+        ? context.stateStore.config
+        : context?.config
+            ? {
+                ...defaultSwarmPluginConfig,
+                ...context.config,
+                acp: {
+                    ...defaultSwarmPluginConfig.acp,
+                    ...context.config.acp,
+                },
+            }
+            : defaultSwarmPluginConfig;
+    const bridgeAdapter = createBridgeSessionAdapter(context?.runtime, { acp: config.acp, bridge: config.bridge });
+    if (bridgeAdapter) {
+        return bridgeAdapter;
+    }
+    const runtimeAdapter = createSessionAdapter(context?.runtime, { acp: config.acp });
+    return runtimeAdapter ?? new UnsupportedOpenClawSessionAdapter();
+}
+export function resolveSubagentAdapter(context) {
+    if (context?.subagentAdapter) {
+        return context.subagentAdapter;
+    }
+    const config = context?.stateStore?.config
+        ? context.stateStore.config
+        : context?.config
+            ? {
+                ...defaultSwarmPluginConfig,
+                ...context.config,
+                acp: {
+                    ...defaultSwarmPluginConfig.acp,
+                    ...context.config.acp,
+                },
+                bridge: {
+                    ...defaultSwarmPluginConfig.bridge,
+                    ...context.config.bridge,
+                },
+            }
+            : defaultSwarmPluginConfig;
+    const bridgeAdapter = createBridgeSubagentAdapter({ bridge: config.bridge });
+    return bridgeAdapter ?? new UnsupportedOpenClawSubagentAdapter();
+}

package/dist/src/cli/output.d.ts

@@ -0,0 +1 @@
+export declare function formatOutput(payload: unknown, asJson?: boolean): string;

package/dist/src/cli/output.js

@@ -0,0 +1,9 @@
+export function formatOutput(payload, asJson) {
+    if (asJson) {
+        return JSON.stringify(payload, null, 2);
+    }
+    if (typeof payload === "string") {
+        return payload;
+    }
+    return JSON.stringify(payload, null, 2);
+}

package/dist/src/cli/register-swarm-cli.d.ts

@@ -0,0 +1,6 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { type SwarmCliContext } from "./context.js";
+export declare function registerSwarmCli(api: OpenClawPluginApi): void;
+export declare function registerSwarmCliCommands(ctx: {
+    program: any;
+}, cliContext?: SwarmCliContext): void;

package/dist/src/cli/register-swarm-cli.js

@@ -0,0 +1,130 @@
+import { resolvePluginConfigFromApi } from "../config.js";
+import { StateStore } from "../state/state-store.js";
+import { runSwarmInit } from "./swarm-init.js";
+import { formatOutput } from "./output.js";
+import { runSwarmPlan } from "./swarm-plan.js";
+import { runSwarmDoctor } from "./swarm-doctor.js";
+import { runSwarmReport } from "./swarm-report.js";
+import { runSwarmReview } from "./swarm-review.js";
+import { runSwarmSessionCancel } from "./swarm-session-cancel.js";
+import { runSwarmSessionCleanup } from "./swarm-session-cleanup.js";
+import { runSwarmSessionClose } from "./swarm-session-close.js";
+import { runSwarmSessionFollowup } from "./swarm-session-followup.js";
+import { runSwarmSessionInspect } from "./swarm-session-inspect.js";
+import { runSwarmSessionList } from "./swarm-session-list.js";
+import { runSwarmRun } from "./swarm-run.js";
+import { runSwarmSessionStatus } from "./swarm-session-status.js";
+import { runSwarmSessionSteer } from "./swarm-session-steer.js";
+import { runSwarmStatus } from "./swarm-status.js";
+function bindCommand(command, action) {
+    command.action(async (options) => {
+        const output = await action(options);
+        if (output !== undefined) {
+            process.stdout.write(`${formatOutput(output, Boolean(options?.json))}\n`);
+        }
+    });
+}
+export function registerSwarmCli(api) {
+    api.registerCli((ctx) => {
+        registerSwarmCliCommands(ctx, {
+            config: resolvePluginConfigFromApi(api),
+            stateStore: new StateStore(resolvePluginConfigFromApi(api)),
+            runtime: api.runtime,
+        });
+    }, { commands: ["swarm"] });
+}
+export function registerSwarmCliCommands(ctx, cliContext) {
+    const swarm = ctx.program.command("swarm").description("Swarm workflow commands");
+    const init = swarm.command("init").requiredOption("--project <path>").option("--json");
+    bindCommand(init, (options) => runSwarmInit({ project: options.project }, cliContext));
+    const status = swarm.command("status").requiredOption("--project <path>").option("--json");
+    bindCommand(status, (options) => runSwarmStatus({ project: options.project }, cliContext));
+    const plan = swarm
+        .command("plan")
+        .requiredOption("--project <path>")
+        .requiredOption("--spec <path>")
+        .option("--json");
+    bindCommand(plan, (options) => runSwarmPlan({ project: options.project, spec: options.spec }, cliContext));
+    const run = swarm
+        .command("run")
+        .requiredOption("--project <path>")
+        .option("--task <taskId>")
+        .option("--dry-run")
+        .option("--runner <kind>")
+        .option("--json");
+    bindCommand(run, (options) => runSwarmRun({
+        project: options.project,
+        task: options.task,
+        dryRun: options.dryRun,
+        runner: options.runner,
+    }, cliContext));
+    const review = swarm
+        .command("review")
+        .requiredOption("--project <path>")
+        .requiredOption("--task <taskId>")
+        .option("--approve")
+        .option("--reject")
+        .option("--note <text>")
+        .option("--json");
+    bindCommand(review, (options) => runSwarmReview({
+        project: options.project,
+        task: options.task,
+        approve: options.approve,
+        reject: options.reject,
+        note: options.note,
+    }, cliContext));
+    const report = swarm.command("report").requiredOption("--project <path>").option("--json");
+    bindCommand(report, (options) => runSwarmReport({ project: options.project }, cliContext));
+    const doctor = swarm.command("doctor").option("--json");
+    bindCommand(doctor, () => runSwarmDoctor({}, cliContext));
+    const session = swarm.command("session").description("ACP session operator commands");
+    const sessionList = session.command("list").requiredOption("--project <path>").option("--json");
+    bindCommand(sessionList, (options) => runSwarmSessionList({ project: options.project }, cliContext));
+    const sessionInspect = session
+        .command("inspect")
+        .requiredOption("--project <path>")
+        .requiredOption("--session <sessionId>")
+        .option("--json");
+    bindCommand(sessionInspect, (options) => runSwarmSessionInspect({ project: options.project, session: options.session }, cliContext));
+    const sessionStatus = session
+        .command("status")
+        .requiredOption("--project <path>")
+        .requiredOption("--run <runId>")
+        .option("--json");
+    bindCommand(sessionStatus, (options) => runSwarmSessionStatus({ project: options.project, run: options.run }, cliContext));
+    const sessionCancel = session
+        .command("cancel")
+        .requiredOption("--project <path>")
+        .requiredOption("--run <runId>")
+        .option("--reason <text>")
+        .option("--json");
+    bindCommand(sessionCancel, (options) => runSwarmSessionCancel({ project: options.project, run: options.run, reason: options.reason }, cliContext));
+    const sessionClose = session
+        .command("close")
+        .requiredOption("--project <path>")
+        .requiredOption("--run <runId>")
+        .option("--reason <text>")
+        .option("--json");
+    bindCommand(sessionClose, (options) => runSwarmSessionClose({ project: options.project, run: options.run, reason: options.reason }, cliContext));
+    const sessionFollowup = session
+        .command("follow-up")
+        .requiredOption("--project <path>")
+        .requiredOption("--session <sessionId>")
+        .requiredOption("--task <description>")
+        .option("--runner <kind>")
+        .option("--json");
+    bindCommand(sessionFollowup, (options) => runSwarmSessionFollowup({ project: options.project, session: options.session, task: options.task, runner: options.runner }, cliContext));
+    const sessionCleanup = session
+        .command("cleanup")
+        .requiredOption("--project <path>")
+        .option("--stale-minutes <minutes>")
+        .option("--json");
+    bindCommand(sessionCleanup, (options) => runSwarmSessionCleanup({ project: options.project, staleMinutes: options.staleMinutes ? Number(options.staleMinutes) : undefined }, cliContext));
+    const sessionSteer = session
+        .command("steer")
+        .requiredOption("--project <path>")
+        .requiredOption("--session <sessionId>")
+        .requiredOption("--message <text>")
+        .option("--json");
+    bindCommand(sessionSteer, (options) => runSwarmSessionSteer({ project: options.project, session: options.session, message: options.message }, cliContext));
+}

package/dist/src/cli/swarm-doctor.d.ts

@@ -0,0 +1,40 @@
+import { runBridgeCommandDirect } from "../runtime/bridge-openclaw-session-adapter.js";
+import { type SwarmCliContext } from "./context.js";
+type BridgeDoctorResult = {
+    ok: boolean;
+    severity: "healthy" | "warning" | "blocked";
+    openclawRoot: string;
+    version?: string;
+    compatibility: {
+        strategy?: "internal-bundle";
+        testedAt?: string;
+        supportedRunners: string[];
+        replacementCandidates: string[];
+        notes: string[];
+    };
+    publicApi: {
+        acpControlPlaneExport: boolean;
+        subagentSpawnExport: boolean;
+        readyReplacementPoints: string[];
+    };
+    replacementPlan: Array<{
+        runner: "acp" | "subagent";
+        publicExport: string;
+        available: boolean;
+        status: "ready" | "blocked";
+        currentImplementation: string;
+        targetImplementation: string;
+        affectedModules: string[];
+        nextStep: string;
+    }>;
+    migrationChecklist: string[];
+    checks: Record<string, boolean>;
+    blockers: string[];
+    warnings: string[];
+    risks: string[];
+    remediation: string[];
+    nextAction: string;
+};
+export type BridgeCommandRunner = typeof runBridgeCommandDirect;
+export declare function runSwarmDoctor(_options: Record<string, never>, context?: SwarmCliContext, commandRunner?: BridgeCommandRunner): Promise<BridgeDoctorResult>;
+export {};

package/dist/src/cli/swarm-doctor.js

@@ -0,0 +1,69 @@
+import { defaultSwarmPluginConfig } from "../config.js";
+import { resolveBridgeScriptPath, resolveTsxLoaderPath, runBridgeCommandDirect } from "../runtime/bridge-openclaw-session-adapter.js";
+function resolveEffectiveConfig(context) {
+    if (context?.stateStore?.config) {
+        return context.stateStore.config;
+    }
+    if (context?.config) {
+        return {
+            ...defaultSwarmPluginConfig,
+            ...context.config,
+            acp: {
+                ...defaultSwarmPluginConfig.acp,
+                ...context.config.acp,
+            },
+            bridge: {
+                ...defaultSwarmPluginConfig.bridge,
+                ...context.config.bridge,
+            },
+        };
+    }
+    return defaultSwarmPluginConfig;
+}
+export async function runSwarmDoctor(_options, context, commandRunner = runBridgeCommandDirect) {
+    const config = resolveEffectiveConfig(context);
+    if (!config.bridge.enabled) {
+        return {
+            ok: false,
+            severity: "blocked",
+            openclawRoot: config.bridge.openclawRoot ?? "(unset)",
+            compatibility: {
+                supportedRunners: [],
+                replacementCandidates: [],
+                notes: [],
+            },
+            publicApi: {
+                acpControlPlaneExport: false,
+                subagentSpawnExport: false,
+                readyReplacementPoints: [],
+            },
+            replacementPlan: [],
+            migrationChecklist: [
+                "Enable bridge mode first, then rerun `openclaw swarm doctor --json` to generate a migration checklist.",
+            ],
+            checks: {
+                bridgeEnabled: false,
+            },
+            blockers: ["bridge.enabled=false"],
+            warnings: [],
+            risks: ["bridge mode is disabled"],
+            remediation: ["Enable plugins.entries.openclaw-swarm-layer.config.bridge.enabled before using bridge-backed execution."],
+            nextAction: "Enable bridge mode before running bridge-backed ACP or subagent execution.",
+        };
+    }
+    const result = await commandRunner([config.bridge.nodePath ?? process.execPath, "--import", resolveTsxLoaderPath(), resolveBridgeScriptPath(), "doctor"], {
+        timeoutMs: 120_000,
+        cwd: process.cwd(),
+        input: JSON.stringify({
+            bridge: {
+                openclawRoot: config.bridge.openclawRoot,
+                versionAllow: config.bridge.versionAllow,
+            },
+        }),
+    });
+    if (result.code !== 0) {
+        throw new Error(result.stderr.trim() || result.stdout.trim() || "bridge doctor failed");
+    }
+    const parsed = JSON.parse(result.stdout);
+    return parsed.result;
+}

package/dist/src/cli/swarm-init.d.ts

@@ -0,0 +1,9 @@
+import { type SwarmCliContext } from "./context.js";
+export type SwarmInitResult = {
+    ok: true;
+    projectRoot: string;
+    swarmRoot: string;
+};
+export declare function runSwarmInit(options: {
+    project: string;
+}, context?: SwarmCliContext): Promise<SwarmInitResult>;

package/dist/src/cli/swarm-init.js

@@ -0,0 +1,10 @@
+import { resolveStateStore } from "./context.js";
+export async function runSwarmInit(options, context) {
+    const stateStore = resolveStateStore(context);
+    const paths = await stateStore.initProject(options.project);
+    return {
+        ok: true,
+        projectRoot: paths.projectRoot,
+        swarmRoot: paths.swarmRoot,
+    };
+}

package/dist/src/cli/swarm-plan.d.ts

@@ -0,0 +1,13 @@
+import { type SwarmCliContext } from "./context.js";
+export type SwarmPlanResult = {
+    ok: true;
+    specId: string;
+    taskCount: number;
+    activeSpecId: string;
+    localReportPath: string;
+    obsidianReportPath?: string;
+};
+export declare function runSwarmPlan(options: {
+    project: string;
+    spec: string;
+}, context?: SwarmCliContext): Promise<SwarmPlanResult>;

package/dist/src/cli/swarm-plan.js

@@ -0,0 +1,39 @@
+import { resolveSwarmPaths } from "../lib/paths.js";
+import { planTasksFromSpec } from "../planning/planner.js";
+import { journalSpecArchive } from "../reporting/obsidian-journal.js";
+import { writeWorkflowReport } from "../reporting/reporter.js";
+import { importSpecFromMarkdown } from "../spec/spec-importer.js";
+import { resolveStateStore } from "./context.js";
+export async function runSwarmPlan(options, context) {
+    const stateStore = resolveStateStore(context);
+    const reportConfig = context?.config ?? stateStore.config;
+    const workflow = await stateStore.loadWorkflow(options.project);
+    const spec = await importSpecFromMarkdown(options.spec, { defaultProjectRoot: workflow.projectRoot });
+    const tasks = planTasksFromSpec(spec, context?.config);
+    await stateStore.writeSpec(options.project, spec);
+    const nextWorkflow = {
+        ...workflow,
+        activeSpecId: spec.specId,
+        lifecycle: tasks.length > 0 ? "planned" : workflow.lifecycle,
+        tasks,
+        reviewQueue: [],
+        lastAction: {
+            at: new Date().toISOString(),
+            type: "plan",
+            message: `planned ${tasks.length} tasks for ${spec.specId}`,
+        },
+    };
+    await stateStore.saveWorkflow(options.project, nextWorkflow);
+    const report = await writeWorkflowReport(options.project, nextWorkflow, reportConfig);
+    // Obsidian journal: spec archive
+    const paths = resolveSwarmPaths(options.project, reportConfig);
+    await journalSpecArchive(paths, stateStore.config.obsidianJournal, spec);
+    return {
+        ok: true,
+        specId: spec.specId,
+        taskCount: tasks.length,
+        activeSpecId: spec.specId,
+        localReportPath: report.localReportPath,
+        obsidianReportPath: report.obsidianReportPath,
+    };
+}

package/dist/src/cli/swarm-report.d.ts

@@ -0,0 +1,9 @@
+import { type SwarmCliContext } from "./context.js";
+export declare function runSwarmReport(options: {
+    project: string;
+}, context?: SwarmCliContext): Promise<{
+    ok: true;
+    report: string;
+    localReportPath: string;
+    obsidianReportPath?: string;
+}>;

package/dist/src/cli/swarm-report.js

@@ -0,0 +1,14 @@
+import { writeWorkflowReport } from "../reporting/reporter.js";
+import { resolveStateStore } from "./context.js";
+export async function runSwarmReport(options, context) {
+    const stateStore = resolveStateStore(context);
+    const reportConfig = context?.config ?? stateStore.config;
+    const workflow = await stateStore.loadWorkflow(options.project);
+    const written = await writeWorkflowReport(options.project, workflow, reportConfig);
+    return {
+        ok: true,
+        report: written.report,
+        localReportPath: written.localReportPath,
+        obsidianReportPath: written.obsidianReportPath,
+    };
+}

package/dist/src/cli/swarm-review.d.ts

@@ -0,0 +1,8 @@
+import { type SwarmCliContext } from "./context.js";
+export declare function runSwarmReview(options: {
+    project: string;
+    task: string;
+    approve?: boolean;
+    reject?: boolean;
+    note?: string;
+}, context?: SwarmCliContext): Promise<unknown>;