claude-tempo 0.6.0 → 0.7.0

package/README.md

@@ -91,7 +91,7 @@ claude-tempo <command> [options]
 
 | Command | Description |
 |---------|-------------|
-| `up [ensemble]` | First-time setup: start Temporal, configure MCP, launch conductor |
+| `up [ensemble]` | First-time setup: start Temporal, configure MCP, launch conductor. Use `--from` to load a blueprint. |
 | `down` | Stop Temporal, terminate sessions, remove MCP config |
 | `server` | Start the Temporal dev server and register search attributes |
 | `conduct [ensemble]` | Start a conductor session (one per ensemble). Use `--resume` or `--replace` if one exists. |
@@ -101,6 +101,7 @@ claude-tempo <command> [options]
 | `stop [ensemble]` | Stop sessions (`-n <name>` for one, `--all` for everything) |
 | `init` | Register claude-tempo MCP server globally (`--project` for per-directory) |
 | `preflight` | Run environment checks |
+| `ensemble <sub>` | Manage saved blueprints (`save`, `list`, `show`) |
 | `help` | Show usage info |
 
 ### Global options
@@ -115,6 +116,7 @@ claude-tempo <command> [options]
 --skip-preflight              Skip preflight checks (start/conduct)
 -d, --dir <path>              Target directory (default: cwd)
 --background                  Run Temporal in background (server only)
+--from <file>                 Load an ensemble blueprint on startup (up only)
 --resume                      Resume an existing conductor session (conduct only)
 --replace                     Stop existing conductor and start fresh (conduct only)
 ```
@@ -212,6 +214,8 @@ These tools are available inside Claude Code sessions connected to claude-tempo:
 | `schedule` | Create a one-shot or recurring schedule to cue a player. |
 | `unschedule` | Cancel a named schedule. |
 | `schedules` | List all active schedules. |
+| `save_ensemble` | Save the current ensemble as a YAML blueprint (conductor only). |
+| `load_ensemble` | Load a blueprint to recruit players and create schedules. |
 
 ## Scheduling
 
@@ -244,6 +248,80 @@ Schedules support one-shot delays, fixed times, and recurring intervals with opt
 - `claude-tempo status` shows active schedules alongside sessions
 - A single durable scheduler workflow per ensemble manages all schedules using Temporal timers
 
+## Ensemble Blueprints
+
+Define reusable ensemble configurations as YAML files. A blueprint specifies which players to recruit, what instructions to give them, what schedules to create, and optionally which custom agent files to use.
+
+### Example blueprint
+
+```yaml
+name: my-project
+conductor:
+  instructions: "Coordinate the frontend and backend teams"
+players:
+  - name: frontend
+    workDir: /repos/my-app
+    instructions: "Build the React dashboard in src/components"
+  - name: backend
+    workDir: /repos/my-api
+    instructions: "Implement the REST endpoints in src/routes"
+  - name: ops
+    workDir: /repos/infra
+    agent: agents/ops-agent.md
+    instructions: "Monitor deployments and run health checks"
+schedules:
+  - name: status-check
+    message: "Report your current progress and any blockers"
+    target: all
+    every: 30m
+  - name: deploy-reminder
+    message: "Check if the staging deploy succeeded"
+    target: ops
+    delay: 10m
+```
+
+### Three ways to use blueprints
+
+1. **From the CLI** — load a blueprint when starting an ensemble:
+
+   ```bash
+   claude-tempo up --from my-blueprint.yaml
+   ```
+
+2. **From inside a session** — use the `load_ensemble` tool:
+
+   *"Load the blueprint from ~/.claude-tempo/ensembles/my-project.yaml"*
+
+3. **Save the current state** — snapshot a running ensemble as a blueprint (conductor only):
+
+   *"Save this ensemble as a blueprint called my-project"*
+
+### Natural language examples
+
+Tell your session things like:
+
+- *"Load the my-project blueprint"*
+- *"Save this ensemble as a blueprint"*
+- *"Load the blueprint from /repos/configs/team.yaml"*
+
+### Fan-out schedules
+
+Use `target: "all"` in a schedule to deliver a message to every active player (excluding the conductor). This is useful for periodic status checks or broadcast announcements:
+
+- *"Schedule a message every 30 minutes to all players asking for a progress update"*
+
+### Custom agents
+
+The `agent` field on a player can be a path to a `.md` file that will be used as the session's system prompt via `--system-prompt`. This lets you create specialized agents with domain-specific instructions:
+
+```yaml
+players:
+  - name: security-reviewer
+    workDir: /repos/my-app
+    agent: agents/security-review.md
+    instructions: "Review the latest PR for security issues"
+```
+
 ## Conductors
 
 A **conductor** is an optional special player that acts as an orchestration hub. Use one when you want:

package/dist/activities/schedule-fire.js

@@ -10,7 +10,43 @@ function createScheduleActivities(client) {
         async fireSchedule(input) {
             const { ensemble, scheduleName, message, target, createdBy } = input;
             try {
-                // Resolve target player by querying running session workflows
+                const text = `[scheduled: ${scheduleName}] ${message}`;
+                // Handle target "all" — deliver to every active player except the conductor
+                if (target === 'all') {
+                    const query = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"`;
+                    const failures = [];
+                    let delivered = 0;
+                    for await (const wf of client.workflow.list({ query })) {
+                        try {
+                            const handle = client.workflow.getHandle(wf.workflowId);
+                            const metadata = await handle.query('getMetadata');
+                            if (metadata.ensemble !== ensemble)
+                                continue;
+                            if (metadata.isConductor)
+                                continue; // skip conductor
+                            await handle.signal('receiveMessage', {
+                                from: createdBy,
+                                text,
+                                isScheduled: true,
+                                scheduleName,
+                            });
+                            delivered++;
+                        }
+                        catch (err) {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            failures.push(`${wf.workflowId}: ${msg}`);
+                        }
+                    }
+                    if (delivered === 0 && failures.length === 0) {
+                        await notifyFailure(client, ensemble, createdBy, scheduleName, target, 'No active players found in the ensemble.');
+                        return { success: false, error: 'No active players found' };
+                    }
+                    return {
+                        success: failures.length === 0,
+                        error: failures.length > 0 ? `Delivered to ${delivered} players, ${failures.length} failed: ${failures.join('; ')}` : undefined,
+                    };
+                }
+                // Resolve single target player by querying running session workflows
                 const handle = await resolveSession(client, ensemble, target);
                 if (!handle) {
                     // Notify the creator (or conductor as fallback) about the failure
@@ -18,7 +54,6 @@ function createScheduleActivities(client) {
                     return { success: false, error: `No active session found for "${target}"` };
                 }
                 // Send cue signal with from set to the original creator's name
-                const text = `[scheduled: ${scheduleName}] ${message}`;
                 await handle.signal('receiveMessage', {
                     from: createdBy,
                     text,

package/dist/cli/commands.d.ts

@@ -27,6 +27,7 @@ export declare function server(opts: ServerOpts): Promise<void>;
 interface UpOpts extends CliOverrides {
     ensemble: string;
     name?: string;
+    from?: string;
     agent: AgentType;
 }
 export declare function up(opts: UpOpts): Promise<void>;
@@ -44,6 +45,11 @@ interface StopOpts extends CliOverrides {
     all?: boolean;
 }
 export declare function stop(opts: StopOpts): Promise<void>;
+interface EnsembleCommandOpts extends CliOverrides {
+    subcommand?: string;
+    name?: string;
+}
+export declare function ensembleCommand(opts: EnsembleCommandOpts): Promise<void>;
 export declare function help(): void;
 export declare function version(): void;
 export {};

package/dist/cli/commands.js

@@ -40,6 +40,7 @@ exports.server = server;
 exports.up = up;
 exports.down = down;
 exports.stop = stop;
+exports.ensembleCommand = ensembleCommand;
 exports.help = help;
 exports.version = version;
 const fs_1 = require("fs");
@@ -50,8 +51,11 @@ const spawn_1 = require("../spawn");
 const config_1 = require("../config");
 const connection_1 = require("../connection");
 const signals_1 = require("../workflows/signals");
+const scheduler_signals_1 = require("../workflows/scheduler-signals");
 const preflight_1 = require("./preflight");
 const mcp_1 = require("./mcp");
+const loader_1 = require("../ensemble/loader");
+const saver_1 = require("../ensemble/saver");
 const out = __importStar(require("./output"));
 /** Package root is two levels up from dist/cli/ */
 const PACKAGE_ROOT = (0, path_1.resolve)(__dirname, '..', '..');
@@ -555,11 +559,18 @@ async function up(opts) {
         temporalEnvVars[config_1.ENV.TEMPORAL_TLS_CERT_PATH] = config.temporalTlsCertPath;
     if (config.temporalTlsKeyPath)
         temporalEnvVars[config_1.ENV.TEMPORAL_TLS_KEY_PATH] = config.temporalTlsKeyPath;
+    // Load blueprint if --from is provided
+    const blueprint = opts.from ? (0, loader_1.loadBlueprint)((0, path_1.resolve)(opts.from)) : undefined;
+    if (blueprint) {
+        out.check('Blueprint loaded', true, blueprint.name);
+    }
+    // Resolve conductor agent from blueprint or CLI flags
+    const conductorAgent = blueprint?.conductor?.agent === 'copilot' ? 'copilot' : opts.agent;
     // Step 5: Launch conductor
     console.log();
-    out.log(`Launching conductor in ensemble ${out.cyan(opts.ensemble)}${opts.agent === 'copilot' ? out.dim(' (copilot)') : ''}...`);
+    out.log(`Launching conductor in ensemble ${out.cyan(opts.ensemble)}${conductorAgent === 'copilot' ? out.dim(' (copilot)') : ''}...`);
     let pid;
-    if (opts.agent === 'copilot') {
+    if (conductorAgent === 'copilot') {
         ({ pid } = (0, spawn_1.spawnCopilotBridge)({
             name: opts.name || `${opts.ensemble}-conductor`,
             ensemble: opts.ensemble,
@@ -587,16 +598,199 @@ async function up(opts) {
             [config_1.ENV.PLAYER_NAME]: sessionName,
         }));
     }
+    out.success(`Conductor launched (pid ${pid ?? 'unknown'})`);
+    // Step 6: If blueprint provided, recruit players and create schedules
+    if (blueprint) {
+        // Connect to Temporal to send signals
+        const connection = await (0, connection_1.createTemporalConnection)(config);
+        const client = new client_1.Client({ connection, namespace: config.temporalNamespace });
+        // Wait for conductor workflow to appear
+        out.log(`\n  Waiting for conductor to register...`);
+        const conductorWfId = (0, config_1.conductorWorkflowId)(opts.ensemble);
+        let conductorReady = false;
+        for (let i = 0; i < 30; i++) {
+            await new Promise(r => setTimeout(r, 500));
+            try {
+                const handle = client.workflow.getHandle(conductorWfId);
+                const desc = await handle.describe();
+                if (desc.status.name === 'RUNNING') {
+                    conductorReady = true;
+                    break;
+                }
+            }
+            catch { /* not yet */ }
+        }
+        if (!conductorReady) {
+            out.warn('Conductor did not register within 15s — skipping blueprint players/schedules');
+        }
+        else {
+            out.check('Conductor registered', true);
+            // Send conductor instructions if provided
+            if (blueprint.conductor?.instructions) {
+                try {
+                    const handle = client.workflow.getHandle(conductorWfId);
+                    await handle.signal('receiveMessage', {
+                        from: 'blueprint',
+                        text: blueprint.conductor.instructions,
+                    });
+                    out.check('Conductor instructions sent', true);
+                }
+                catch (err) {
+                    out.warn(`Could not send conductor instructions: ${err}`);
+                }
+            }
+            // Recruit players sequentially (each polls for ~15s)
+            if (blueprint.players.length > 0) {
+                console.log();
+                out.log(`Recruiting ${blueprint.players.length} player${blueprint.players.length !== 1 ? 's' : ''} from blueprint...`);
+                for (const player of blueprint.players) {
+                    const playerAgent = player.agent === 'copilot' ? 'copilot' : 'claude';
+                    const playerWorkDir = player.workDir || process.cwd();
+                    // Record existing workflows to detect the new one
+                    const existingIds = new Set();
+                    const listQuery = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"`;
+                    for await (const wf of client.workflow.list({ query: listQuery })) {
+                        existingIds.add(wf.workflowId);
+                    }
+                    // Spawn the player
+                    if (playerAgent === 'copilot') {
+                        (0, spawn_1.spawnCopilotBridge)({
+                            name: player.name,
+                            ensemble: opts.ensemble,
+                            temporalAddress: config.temporalAddress,
+                            temporalNamespace: config.temporalNamespace,
+                            temporalApiKey: config.temporalApiKey,
+                            temporalTlsCertPath: config.temporalTlsCertPath,
+                            temporalTlsKeyPath: config.temporalTlsKeyPath,
+                            isConductor: false,
+                            workDir: playerWorkDir,
+                        });
+                    }
+                    else {
+                        const claudeArgs = [
+                            '--dangerously-skip-permissions',
+                            '--dangerously-load-development-channels', 'server:claude-tempo',
+                            '-n', player.name,
+                        ];
+                        (0, spawn_1.spawnInTerminal)(claudeArgs, playerWorkDir, {
+                            ...temporalEnvVars,
+                            [config_1.ENV.ENSEMBLE]: opts.ensemble,
+                            [config_1.ENV.CONDUCTOR]: '',
+                            [config_1.ENV.PLAYER_NAME]: player.name,
+                        });
+                    }
+                    // Poll for the new workflow to appear (up to ~15s)
+                    let newWorkflowId = null;
+                    for (let attempt = 0; attempt < 30; attempt++) {
+                        await new Promise(r => setTimeout(r, 500));
+                        for await (const wf of client.workflow.list({ query: listQuery })) {
+                            if (!existingIds.has(wf.workflowId)) {
+                                newWorkflowId = wf.workflowId;
+                                break;
+                            }
+                        }
+                        if (newWorkflowId)
+                            break;
+                    }
+                    if (newWorkflowId && player.instructions) {
+                        try {
+                            const handle = client.workflow.getHandle(newWorkflowId);
+                            await handle.signal('receiveMessage', {
+                                from: 'blueprint',
+                                text: player.instructions,
+                            });
+                        }
+                        catch { /* best effort */ }
+                    }
+                    const status = newWorkflowId ? out.green('ok') : out.yellow('slow');
+                    out.log(`  ${status} ${out.bold(player.name)} in ${playerWorkDir}`);
+                }
+            }
+            // Create schedules
+            if (blueprint.schedules && blueprint.schedules.length > 0) {
+                console.log();
+                out.log(`Creating ${blueprint.schedules.length} schedule${blueprint.schedules.length !== 1 ? 's' : ''}...`);
+                for (const sched of blueprint.schedules) {
+                    try {
+                        const entry = blueprintScheduleToEntry(sched);
+                        const schedulerWfId = (0, config_1.schedulerWorkflowId)(opts.ensemble);
+                        const handle = client.workflow.getHandle(schedulerWfId);
+                        await handle.signal(scheduler_signals_1.addScheduleSignal, entry);
+                        out.check(sched.name, true, `→ ${sched.target}`);
+                    }
+                    catch (err) {
+                        out.warn(`Could not create schedule "${sched.name}": ${err}`);
+                    }
+                }
+            }
+        }
+        await connection.close();
+    }
     console.log();
     out.success('You\'re all set!');
-    out.log(`  Conductor launched (pid ${pid ?? 'unknown'})`);
     out.log(`  Ensemble: ${out.cyan(opts.ensemble)}`);
-    out.log(`\n  ${out.bold('What next?')}`);
-    out.log(`  ${out.dim('claude-tempo start ' + opts.ensemble)}    Add a player session`);
-    out.log(`  ${out.dim('claude-tempo status ' + opts.ensemble)}   See who\'s active`);
-    out.log(`  Or ask the conductor to ${out.dim('recruit')} players for you`);
+    if (!blueprint) {
+        out.log(`\n  ${out.bold('What next?')}`);
+        out.log(`  ${out.dim('claude-tempo start ' + opts.ensemble)}    Add a player session`);
+        out.log(`  ${out.dim('claude-tempo status ' + opts.ensemble)}   See who\'s active`);
+        out.log(`  Or ask the conductor to ${out.dim('recruit')} players for you`);
+    }
+    else {
+        out.log(`  Blueprint: ${out.dim(blueprint.name)}`);
+        out.log(`  Players: ${blueprint.players.length}`);
+        if (blueprint.schedules?.length)
+            out.log(`  Schedules: ${blueprint.schedules.length}`);
+        out.log(`\n  ${out.dim('claude-tempo status ' + opts.ensemble)}   See who\'s active`);
+    }
     console.log();
 }
+/** Convert a blueprint schedule definition to a ScheduleEntry for the scheduler workflow. */
+function blueprintScheduleToEntry(sched) {
+    const now = Date.now();
+    let nextFireAt;
+    let interval;
+    if (sched.every) {
+        interval = parseDuration(sched.every);
+        nextFireAt = sched.delay
+            ? new Date(now + parseDuration(sched.delay)).toISOString()
+            : new Date(now + interval).toISOString();
+    }
+    else if (sched.at) {
+        nextFireAt = new Date(sched.at).toISOString();
+    }
+    else if (sched.delay) {
+        nextFireAt = new Date(now + parseDuration(sched.delay)).toISOString();
+    }
+    else {
+        nextFireAt = new Date(now + 60_000).toISOString(); // default: 1 minute
+    }
+    return {
+        name: sched.name,
+        message: sched.message,
+        target: sched.target,
+        createdBy: 'blueprint',
+        nextFireAt,
+        interval,
+        until: sched.until,
+        remainingCount: sched.count,
+        firedCount: 0,
+        type: interval ? 'interval' : 'once',
+    };
+}
+/** Parse a human duration string like "10m", "1h", "30s" to milliseconds. */
+function parseDuration(s) {
+    const match = s.match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d)$/);
+    if (!match)
+        throw new Error(`Invalid duration: "${s}"`);
+    const value = parseFloat(match[1]);
+    switch (match[2]) {
+        case 's': return value * 1_000;
+        case 'm': return value * 60_000;
+        case 'h': return value * 3_600_000;
+        case 'd': return value * 86_400_000;
+        default: throw new Error(`Unknown duration unit: "${match[2]}"`);
+    }
+}
 async function down(opts) {
     const config = (0, config_1.getConfig)(opts);
     out.heading('claude-tempo teardown');
@@ -867,6 +1061,57 @@ function killBridgeProcesses() {
         // logs dir unreadable
     }
 }
+async function ensembleCommand(opts) {
+    switch (opts.subcommand) {
+        case 'save': {
+            const config = (0, config_1.getConfig)(opts);
+            const connection = await (0, connection_1.createTemporalConnection)(config);
+            const client = new client_1.Client({ connection, namespace: config.temporalNamespace });
+            const ensemble = opts.name || config.ensemble;
+            try {
+                const path = await (0, saver_1.saveBlueprint)(client, ensemble);
+                out.success(`Saved ensemble "${ensemble}" to ${path}`);
+            }
+            finally {
+                await connection.close();
+            }
+            break;
+        }
+        case 'list': {
+            const blueprints = (0, saver_1.listBlueprints)();
+            if (blueprints.length === 0) {
+                out.log('No saved ensembles. Use `claude-tempo ensemble save [name]` to save one.');
+                return;
+            }
+            out.heading('Saved ensembles');
+            for (const bp of blueprints) {
+                out.log(`  ${out.bold(bp.name)}  ${out.dim(bp.path)}`);
+            }
+            console.log();
+            break;
+        }
+        case 'show': {
+            if (!opts.name) {
+                out.error('Usage: claude-tempo ensemble show <name>');
+                process.exit(1);
+            }
+            const content = (0, saver_1.readSavedBlueprint)(opts.name);
+            if (!content) {
+                out.error(`No saved ensemble named "${opts.name}"`);
+                out.log(`  Run ${out.dim('claude-tempo ensemble list')} to see available ensembles.`);
+                process.exit(1);
+            }
+            console.log(content);
+            break;
+        }
+        default:
+            out.error('Usage: claude-tempo ensemble <save|list|show> [name]');
+            out.log(`\n  ${out.dim('claude-tempo ensemble save [name]')}   Save current ensemble state`);
+            out.log(`  ${out.dim('claude-tempo ensemble list')}          List saved ensembles`);
+            out.log(`  ${out.dim('claude-tempo ensemble show <name>')}   Display a saved blueprint`);
+            process.exit(1);
+    }
+}
 function help() {
     console.log(`
 ${out.bold('claude-tempo')} — Multi-session Claude Code coordination via Temporal
@@ -885,6 +1130,7 @@ ${out.bold('Commands:')}
   ${out.cyan('start')}   [ensemble]    Start a player session
   ${out.cyan('stop')}    [ensemble]    Stop sessions (-n <name> for one, or --all)
   ${out.cyan('status')}  [ensemble]    Show active sessions and Temporal health
+  ${out.cyan('ensemble')} <sub>       Manage saved ensemble blueprints (save/list/show)
   ${out.cyan('config')}                Configure Temporal connection settings
   ${out.cyan('init')}                  Register MCP server globally (or --project for .mcp.json)
   ${out.cyan('preflight')}             Run preflight checks only
@@ -905,6 +1151,7 @@ ${out.bold('Other options:')}
   --project                   Use per-project .mcp.json instead of global (init only)
   --keep-mcp                  Don't remove MCP config (down only)
   --all                       Stop all sessions (stop only)
+  --from <file>               Load ensemble from a YAML blueprint (up only)
   --ensemble <name>           Target a specific ensemble (stop only)
   -d, --dir <path>            Target directory (default: cwd)
 

package/dist/cli.js

@@ -70,6 +70,9 @@ function parseArgs(argv) {
         else if (arg === '--temporal-tls-key' && i + 1 < argv.length) {
             result.temporalTlsKeyPath = argv[++i];
         }
+        else if (arg === '--from' && i + 1 < argv.length) {
+            result.from = argv[++i];
+        }
         else if ((arg === '-n' || arg === '--name') && i + 1 < argv.length) {
             result.name = argv[++i];
         }
@@ -201,10 +204,18 @@ async function main() {
             await (0, commands_1.up)({
                 ensemble,
                 name: args.name,
+                from: args.from,
                 agent: resolvedAgent(),
                 ...overrides,
             });
             break;
+        case 'ensemble':
+            await (0, commands_1.ensembleCommand)({
+                subcommand: args.positional[1],
+                name: args.positional[2],
+                ...overrides,
+            });
+            break;
         case 'init':
             await (0, commands_1.init)({ dir: args.dir, project: args.project });
             break;

package/dist/ensemble/loader.d.ts

@@ -0,0 +1,5 @@
+import { EnsembleBlueprint } from './schema';
+/**
+ * Load and validate an ensemble blueprint from a YAML file.
+ */
+export declare function loadBlueprint(filePath: string): EnsembleBlueprint;

package/dist/ensemble/loader.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadBlueprint = loadBlueprint;
+const fs_1 = require("fs");
+const yaml_1 = require("yaml");
+/**
+ * Load and validate an ensemble blueprint from a YAML file.
+ */
+function loadBlueprint(filePath) {
+    const raw = (0, fs_1.readFileSync)(filePath, 'utf8');
+    const doc = (0, yaml_1.parse)(raw);
+    if (!doc || typeof doc !== 'object') {
+        throw new Error(`Invalid blueprint: file does not contain a YAML object`);
+    }
+    // Required: name
+    if (typeof doc.name !== 'string' || !doc.name) {
+        throw new Error(`Invalid blueprint: "name" is required and must be a non-empty string`);
+    }
+    // Required: players array
+    if (!Array.isArray(doc.players)) {
+        throw new Error(`Invalid blueprint: "players" must be an array`);
+    }
+    for (let i = 0; i < doc.players.length; i++) {
+        const p = doc.players[i];
+        if (typeof p.name !== 'string' || !p.name) {
+            throw new Error(`Invalid blueprint: players[${i}].name is required`);
+        }
+        if (!/^[a-zA-Z0-9_-]+$/.test(p.name)) {
+            throw new Error(`Invalid blueprint: players[${i}].name "${p.name}" contains invalid characters`);
+        }
+    }
+    // Validate schedules if present
+    if (doc.schedules != null) {
+        if (!Array.isArray(doc.schedules)) {
+            throw new Error(`Invalid blueprint: "schedules" must be an array`);
+        }
+        for (let i = 0; i < doc.schedules.length; i++) {
+            const s = doc.schedules[i];
+            if (typeof s.name !== 'string' || !s.name) {
+                throw new Error(`Invalid blueprint: schedules[${i}].name is required`);
+            }
+            if (typeof s.message !== 'string' || !s.message) {
+                throw new Error(`Invalid blueprint: schedules[${i}].message is required`);
+            }
+            if (typeof s.target !== 'string' || !s.target) {
+                throw new Error(`Invalid blueprint: schedules[${i}].target is required`);
+            }
+            if (!s.at && !s.delay && !s.every) {
+                throw new Error(`Invalid blueprint: schedules[${i}] must have at least one of: at, delay, every`);
+            }
+        }
+    }
+    return {
+        name: doc.name,
+        description: doc.description,
+        conductor: doc.conductor,
+        players: doc.players,
+        schedules: doc.schedules,
+    };
+}

package/dist/ensemble/saver.d.ts

@@ -0,0 +1,17 @@
+import { Client } from '@temporalio/client';
+/**
+ * Save the current live ensemble state to a YAML blueprint file.
+ * Queries all running sessions and active schedules from Temporal.
+ */
+export declare function saveBlueprint(client: Client, ensemble: string, filePath?: string): Promise<string>;
+/**
+ * List all saved ensemble blueprints in ~/.claude-tempo/ensembles/.
+ */
+export declare function listBlueprints(): Array<{
+    name: string;
+    path: string;
+}>;
+/**
+ * Read a saved blueprint by name from ~/.claude-tempo/ensembles/.
+ */
+export declare function readSavedBlueprint(name: string): string | null;

package/dist/ensemble/saver.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveBlueprint = saveBlueprint;
+exports.listBlueprints = listBlueprints;
+exports.readSavedBlueprint = readSavedBlueprint;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const yaml_1 = require("yaml");
+const config_1 = require("../config");
+const ENSEMBLES_DIR = (0, path_1.join)(config_1.CLAUDE_TEMPO_HOME, 'ensembles');
+function ensemblesDir() {
+    (0, fs_1.mkdirSync)(ENSEMBLES_DIR, { recursive: true });
+    return ENSEMBLES_DIR;
+}
+/**
+ * Save the current live ensemble state to a YAML blueprint file.
+ * Queries all running sessions and active schedules from Temporal.
+ */
+async function saveBlueprint(client, ensemble, filePath) {
+    const outputPath = filePath || (0, path_1.join)(ensemblesDir(), `${ensemble}.yaml`);
+    // Query all running session workflows
+    const query = 'WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"';
+    const players = [];
+    let conductor;
+    for await (const wf of client.workflow.list({ query })) {
+        try {
+            const handle = client.workflow.getHandle(wf.workflowId);
+            const [metadata, part] = await Promise.all([
+                handle.query('getMetadata').catch(() => ({})),
+                handle.query('getPart').catch(() => ''),
+            ]);
+            const meta = metadata;
+            if (meta.ensemble !== ensemble)
+                continue;
+            const isConductor = meta.isConductor || false;
+            const agentType = meta.agentType || 'claude';
+            const workDir = meta.workDir || undefined;
+            if (isConductor) {
+                conductor = {
+                    agent: agentType === 'copilot' ? 'copilot' : undefined,
+                };
+            }
+            else {
+                const name = meta.playerId || wf.workflowId.split('-').pop() || 'unknown';
+                players.push({
+                    name,
+                    workDir,
+                    agent: agentType === 'copilot' ? 'copilot' : undefined,
+                });
+            }
+        }
+        catch {
+            // workflow may have closed between list and query
+        }
+    }
+    // Query active schedules
+    const schedules = [];
+    try {
+        const schedulerWfId = (0, config_1.schedulerWorkflowId)(ensemble);
+        const handle = client.workflow.getHandle(schedulerWfId);
+        const entries = await handle.query('getSchedules');
+        for (const entry of entries) {
+            const sched = {
+                name: entry.name,
+                message: entry.message,
+                target: entry.target,
+            };
+            if (entry.interval) {
+                sched.every = formatDurationMs(entry.interval);
+            }
+            if (entry.until) {
+                sched.until = entry.until;
+            }
+            if (entry.remainingCount != null) {
+                sched.count = entry.remainingCount;
+            }
+            schedules.push(sched);
+        }
+    }
+    catch {
+        // No scheduler running or no schedules
+    }
+    const blueprint = {
+        name: ensemble,
+        conductor,
+        players,
+        ...(schedules.length > 0 ? { schedules } : {}),
+    };
+    // Ensure parent directory exists
+    const parentDir = outputPath.substring(0, outputPath.lastIndexOf('/') >= 0 ? outputPath.lastIndexOf('/') : outputPath.lastIndexOf('\\'));
+    if (parentDir)
+        (0, fs_1.mkdirSync)(parentDir, { recursive: true });
+    (0, fs_1.writeFileSync)(outputPath, (0, yaml_1.stringify)(blueprint));
+    return outputPath;
+}
+/**
+ * List all saved ensemble blueprints in ~/.claude-tempo/ensembles/.
+ */
+function listBlueprints() {
+    const dir = ensemblesDir();
+    if (!(0, fs_1.existsSync)(dir))
+        return [];
+    return (0, fs_1.readdirSync)(dir)
+        .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))
+        .map(f => ({
+        name: f.replace(/\.ya?ml$/, ''),
+        path: (0, path_1.join)(dir, f),
+    }));
+}
+/**
+ * Read a saved blueprint by name from ~/.claude-tempo/ensembles/.
+ */
+function readSavedBlueprint(name) {
+    const dir = ensemblesDir();
+    for (const ext of ['.yaml', '.yml']) {
+        const path = (0, path_1.join)(dir, name + ext);
+        if ((0, fs_1.existsSync)(path))
+            return (0, fs_1.readFileSync)(path, 'utf8');
+    }
+    return null;
+}
+function formatDurationMs(ms) {
+    if (ms >= 86_400_000 && ms % 86_400_000 === 0)
+        return `${ms / 86_400_000}d`;
+    if (ms >= 3_600_000 && ms % 3_600_000 === 0)
+        return `${ms / 3_600_000}h`;
+    if (ms >= 60_000 && ms % 60_000 === 0)
+        return `${ms / 60_000}m`;
+    return `${ms / 1000}s`;
+}

package/dist/ensemble/schema.d.ts

@@ -0,0 +1,24 @@
+export interface EnsembleBlueprint {
+    name: string;
+    description?: string;
+    conductor?: {
+        agent?: string;
+        instructions?: string;
+    };
+    players: Array<{
+        name: string;
+        workDir?: string;
+        agent?: string;
+        instructions?: string;
+    }>;
+    schedules?: Array<{
+        name: string;
+        message: string;
+        target: string;
+        at?: string;
+        delay?: string;
+        every?: string;
+        until?: string;
+        count?: number;
+    }>;
+}

package/dist/ensemble/schema.js

@@ -0,0 +1,3 @@
+"use strict";
+// Ensemble blueprint types — defines the structure of a saved/loaded ensemble configuration.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/server.js

@@ -55,6 +55,8 @@ const set_name_1 = require("./tools/set-name");
 const schedule_1 = require("./tools/schedule");
 const unschedule_1 = require("./tools/unschedule");
 const schedules_1 = require("./tools/schedules");
+const save_ensemble_1 = require("./tools/save-ensemble");
+const load_ensemble_1 = require("./tools/load-ensemble");
 const channel_1 = require("./channel");
 const log = (...args) => console.error('[claude-tempo]', ...args);
 function getGitInfo(workDir) {
@@ -195,6 +197,8 @@ async function main() {
     (0, schedule_1.registerScheduleTool)(mcpServer, client, config, getPlayerId);
     (0, unschedule_1.registerUnscheduleTool)(mcpServer, client, config);
     (0, schedules_1.registerSchedulesTool)(mcpServer, client, config);
+    (0, save_ensemble_1.registerSaveEnsembleTool)(mcpServer, client, config, getPlayerId, isConductor);
+    (0, load_ensemble_1.registerLoadEnsembleTool)(mcpServer, client, config, getPlayerId, isBridgeMode ? 'copilot' : 'claude');
     const MAESTRO_ACK = '\n\n[IMPORTANT: This message is from a human (Maestro). Immediately cue the sender back with a brief acknowledgment and your planned next step before doing the work.]';
     // Start message poller — push messages into Claude Code via channel notifications.
     // Skip when running under the Copilot bridge: the bridge has its own poller that

package/dist/tools/load-ensemble.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@temporalio/client';
+import { Config } from '../config';
+import { AgentType } from '../types';
+export declare function registerLoadEnsembleTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string, ownAgentType?: AgentType): void;

package/dist/tools/load-ensemble.js

@@ -0,0 +1,282 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerLoadEnsembleTool = registerLoadEnsembleTool;
+const zod_1 = require("zod");
+const path_1 = require("path");
+const client_1 = require("@temporalio/client");
+const config_1 = require("../config");
+const loader_1 = require("../ensemble/loader");
+const saver_1 = require("../ensemble/saver");
+const resolve_1 = require("./resolve");
+const spawn_1 = require("../spawn");
+const helpers_1 = require("./helpers");
+const log = (...args) => console.error('[claude-tempo:load-ensemble]', ...args);
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Parse a duration string like "30s", "10m", "2h", "1d" into milliseconds. */
+function parseDuration(dur) {
+    const match = dur.match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d)$/i);
+    if (!match)
+        return null;
+    const value = parseFloat(match[1]);
+    switch (match[2].toLowerCase()) {
+        case 's': return value * 1000;
+        case 'm': return value * 60_000;
+        case 'h': return value * 3_600_000;
+        case 'd': return value * 86_400_000;
+        default: return null;
+    }
+}
+function registerLoadEnsembleTool(server, client, config, getPlayerId, ownAgentType = 'claude') {
+    (0, helpers_1.defineTool)(server, 'load_ensemble', 'Load an ensemble blueprint — recruits players and creates schedules.', {
+        name: zod_1.z.string().optional().describe('Name of a saved blueprint (from ~/.claude-tempo/ensembles/)'),
+        path: zod_1.z.string().optional().describe('Explicit file path to a blueprint YAML file'),
+    }, async (args) => {
+        const blueprintName = args.name;
+        const blueprintPath = args.path;
+        if (!blueprintName && !blueprintPath) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: 'Provide either `name` (saved blueprint) or `path` (file path). Exactly one is required.',
+                    }],
+                isError: true,
+            };
+        }
+        if (blueprintName && blueprintPath) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: 'Provide either `name` or `path`, not both.',
+                    }],
+                isError: true,
+            };
+        }
+        try {
+            // Resolve the file path
+            let filePath;
+            if (blueprintPath) {
+                filePath = blueprintPath;
+            }
+            else {
+                // Try to find saved blueprint by name
+                const savedContent = (0, saver_1.readSavedBlueprint)(blueprintName);
+                if (!savedContent) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `No saved blueprint found with name "${blueprintName}". Check ~/.claude-tempo/ensembles/.`,
+                            }],
+                        isError: true,
+                    };
+                }
+                // readSavedBlueprint returns content, but loadBlueprint wants a path.
+                // Construct the path directly.
+                const ensemblesDir = (0, path_1.join)(config_1.CLAUDE_TEMPO_HOME, 'ensembles');
+                // Try both extensions
+                const { existsSync } = require('fs');
+                filePath = (0, path_1.join)(ensemblesDir, `${blueprintName}.yaml`);
+                if (!existsSync(filePath)) {
+                    filePath = (0, path_1.join)(ensemblesDir, `${blueprintName}.yml`);
+                }
+            }
+            const blueprint = (0, loader_1.loadBlueprint)(filePath);
+            const recruited = [];
+            const failed = [];
+            // Recruit players sequentially
+            for (const player of blueprint.players) {
+                const playerName = player.name;
+                const workDir = player.workDir || process.cwd();
+                const agentType = player.agent === 'copilot' ? 'copilot' : 'claude';
+                const isCustomAgent = player.agent && player.agent !== 'default' && player.agent !== 'copilot';
+                const systemPrompt = isCustomAgent ? player.agent : undefined;
+                // Skip if already active
+                const existing = await (0, resolve_1.resolveSession)(client, config.ensemble, playerName);
+                if (existing) {
+                    log(`Player "${playerName}" already active — skipping recruit`);
+                    recruited.push(`${playerName} (already active)`);
+                    // Still send instructions if provided
+                    if (player.instructions) {
+                        try {
+                            await existing.signal('receiveMessage', {
+                                from: getPlayerId(),
+                                text: player.instructions,
+                            });
+                        }
+                        catch {
+                            // best effort
+                        }
+                    }
+                    continue;
+                }
+                // Record existing workflows to detect the new one
+                const existingIds = new Set();
+                const listQuery = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"`;
+                for await (const wf of client.workflow.list({ query: listQuery })) {
+                    existingIds.add(wf.workflowId);
+                }
+                // Spawn
+                try {
+                    if (agentType === 'copilot') {
+                        (0, spawn_1.spawnCopilotBridge)({
+                            name: playerName,
+                            ensemble: config.ensemble,
+                            temporalAddress: config.temporalAddress,
+                            temporalNamespace: config.temporalNamespace,
+                            temporalApiKey: config.temporalApiKey,
+                            temporalTlsCertPath: config.temporalTlsCertPath,
+                            temporalTlsKeyPath: config.temporalTlsKeyPath,
+                            isConductor: false,
+                            workDir,
+                        });
+                    }
+                    else {
+                        const spawnArgs = [
+                            '--dangerously-skip-permissions',
+                            '--dangerously-load-development-channels', 'server:claude-tempo',
+                            '-n', playerName,
+                            ...(systemPrompt ? ['--system-prompt', systemPrompt] : []),
+                        ];
+                        const envVars = {
+                            [config_1.ENV.ENSEMBLE]: config.ensemble,
+                            [config_1.ENV.CONDUCTOR]: '',
+                            [config_1.ENV.PLAYER_NAME]: playerName,
+                            [config_1.ENV.TEMPORAL_ADDRESS]: config.temporalAddress,
+                            [config_1.ENV.TEMPORAL_NAMESPACE]: config.temporalNamespace,
+                        };
+                        if (config.temporalApiKey)
+                            envVars[config_1.ENV.TEMPORAL_API_KEY] = config.temporalApiKey;
+                        if (config.temporalTlsCertPath)
+                            envVars[config_1.ENV.TEMPORAL_TLS_CERT_PATH] = config.temporalTlsCertPath;
+                        if (config.temporalTlsKeyPath)
+                            envVars[config_1.ENV.TEMPORAL_TLS_KEY_PATH] = config.temporalTlsKeyPath;
+                        (0, spawn_1.spawnInTerminal)(spawnArgs, workDir, envVars);
+                    }
+                }
+                catch (err) {
+                    failed.push(`${playerName}: spawn failed — ${err}`);
+                    continue;
+                }
+                // Poll for the new workflow to appear (up to ~15s)
+                let newWorkflowId = null;
+                for (let attempt = 0; attempt < 30; attempt++) {
+                    await sleep(500);
+                    for await (const wf of client.workflow.list({ query: listQuery })) {
+                        if (!existingIds.has(wf.workflowId)) {
+                            newWorkflowId = wf.workflowId;
+                            break;
+                        }
+                    }
+                    if (newWorkflowId)
+                        break;
+                }
+                if (!newWorkflowId) {
+                    failed.push(`${playerName}: spawned but did not register within 15s`);
+                    continue;
+                }
+                // Send initial instructions if provided
+                if (player.instructions) {
+                    try {
+                        const newHandle = client.workflow.getHandle(newWorkflowId);
+                        await newHandle.signal('receiveMessage', {
+                            from: getPlayerId(),
+                            text: player.instructions,
+                        });
+                    }
+                    catch {
+                        // best effort
+                    }
+                }
+                recruited.push(playerName);
+                log(`Recruited "${playerName}" in ${workDir}`);
+            }
+            // Create schedules
+            const schedulesCreated = [];
+            if (blueprint.schedules && blueprint.schedules.length > 0) {
+                for (const sched of blueprint.schedules) {
+                    try {
+                        const now = Date.now();
+                        let nextFireAt;
+                        let interval;
+                        if (sched.at) {
+                            nextFireAt = Date.parse(sched.at);
+                        }
+                        else if (sched.delay) {
+                            const ms = parseDuration(sched.delay);
+                            if (!ms)
+                                throw new Error(`Invalid delay: ${sched.delay}`);
+                            nextFireAt = now + ms;
+                        }
+                        else if (sched.every) {
+                            const ms = parseDuration(sched.every);
+                            if (!ms)
+                                throw new Error(`Invalid interval: ${sched.every}`);
+                            nextFireAt = now + ms;
+                            interval = ms;
+                        }
+                        else {
+                            throw new Error('No timing specified');
+                        }
+                        const scheduleEntry = {
+                            name: sched.name,
+                            message: sched.message,
+                            target: sched.target,
+                            type: sched.every ? 'interval' : 'once',
+                            nextFireAt: new Date(nextFireAt).toISOString(),
+                            interval,
+                            until: sched.until,
+                            remainingCount: sched.count,
+                            firedCount: 0,
+                            createdBy: getPlayerId(),
+                        };
+                        const wfId = (0, config_1.schedulerWorkflowId)(config.ensemble);
+                        try {
+                            const handle = client.workflow.getHandle(wfId);
+                            await handle.describe();
+                            await handle.signal('addSchedule', scheduleEntry);
+                        }
+                        catch {
+                            await client.workflow.start('claudeSchedulerWorkflow', {
+                                workflowId: wfId,
+                                taskQueue: config.taskQueue,
+                                args: [{ ensemble: config.ensemble, entries: [scheduleEntry] }],
+                                workflowIdConflictPolicy: client_1.WorkflowIdConflictPolicy.USE_EXISTING,
+                                searchAttributes: {
+                                    ClaudeTempoEnsemble: [config.ensemble],
+                                },
+                            });
+                        }
+                        schedulesCreated.push(sched.name);
+                    }
+                    catch (err) {
+                        failed.push(`schedule "${sched.name}": ${err}`);
+                    }
+                }
+            }
+            // Build summary
+            const lines = [`Loaded blueprint **${blueprint.name}**.`];
+            if (recruited.length > 0) {
+                lines.push(`Recruited: ${recruited.join(', ')}`);
+            }
+            if (schedulesCreated.length > 0) {
+                lines.push(`Schedules created: ${schedulesCreated.join(', ')}`);
+            }
+            if (failed.length > 0) {
+                lines.push(`Failures:\n${failed.map(f => `  - ${f}`).join('\n')}`);
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: lines.join('\n'),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Failed to load blueprint: ${err}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/recruit.js

@@ -20,10 +20,13 @@ function registerRecruitTool(server, client, config, getPlayerId, ownAgentType =
             .describe('Optional task or message for the new session (sent after it sets its name)'),
         agent: zod_1.z.enum(['claude', 'copilot']).optional()
             .describe(`Which agent to use (default: "${ownAgentType}", same as this session)`),
+        systemPrompt: zod_1.z.string().optional()
+            .describe('Path to a .md file to use as custom agent system prompt (--system-prompt)'),
     }, async (args) => {
         const { workDir, name, initialMessage } = args;
         const isConductor = args.conductor === true;
         const agent = args.agent || ownAgentType;
+        const systemPrompt = args.systemPrompt;
         // Validate name
         if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
             return {
@@ -101,6 +104,7 @@ function registerRecruitTool(server, client, config, getPlayerId, ownAgentType =
                     '--dangerously-skip-permissions',
                     '--dangerously-load-development-channels', 'server:claude-tempo',
                     '-n', name,
+                    ...(systemPrompt ? ['--system-prompt', systemPrompt] : []),
                 ];
                 const envVars = {
                     [config_1.ENV.ENSEMBLE]: config.ensemble,

package/dist/tools/save-ensemble.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@temporalio/client';
+import { Config } from '../config';
+export declare function registerSaveEnsembleTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string, isConductor: boolean): void;

package/dist/tools/save-ensemble.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSaveEnsembleTool = registerSaveEnsembleTool;
+const zod_1 = require("zod");
+const saver_1 = require("../ensemble/saver");
+const helpers_1 = require("./helpers");
+const log = (...args) => console.error('[claude-tempo:save-ensemble]', ...args);
+function registerSaveEnsembleTool(server, client, config, getPlayerId, isConductor) {
+    (0, helpers_1.defineTool)(server, 'save_ensemble', 'Save the current ensemble state as a YAML blueprint. Only available to the conductor.', {
+        name: zod_1.z.string().optional().describe('Blueprint name (defaults to ensemble name)'),
+        path: zod_1.z.string().optional().describe('Explicit file path to save to'),
+    }, async (args) => {
+        if (!isConductor) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: 'Only the conductor can save ensemble blueprints.',
+                    }],
+                isError: true,
+            };
+        }
+        const blueprintName = args.name;
+        const filePath = args.path;
+        try {
+            // If a custom name is provided but no path, we don't override —
+            // saveBlueprint uses the ensemble name for the default path.
+            // We pass filePath through directly.
+            const outputPath = await (0, saver_1.saveBlueprint)(client, config.ensemble, filePath);
+            log(`Saved blueprint to ${outputPath}`);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Ensemble blueprint saved to **${outputPath}**.`,
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Failed to save ensemble: ${err}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-tempo",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "MCP server for multi-session Claude Code coordination via Temporal",
   "repository": {
     "type": "git",
@@ -53,6 +53,7 @@
     "@temporalio/client": "~1.15.0",
     "@temporalio/worker": "~1.15.0",
     "@temporalio/workflow": "~1.15.0",
+    "yaml": "^2.8.3",
     "zod": "^3.25.76"
   },
   "devDependencies": {