ai-whisper 0.1.1 → 0.1.2

package/README.md

@@ -21,7 +21,7 @@ Run spec-driven-development using docs/spec.md
 
 From there ai-whisper runs the workflow autonomously:
 
-- **Implementer / reviewer assignment** — one agent is the implementer, the other the reviewer (for `spec-driven-development` the default is implementer = Claude, reviewer = Codex). The baton passes between them; only one owns the turn at a time.
+- **Implementer / reviewer assignment** — the agent you trigger the workflow from becomes the implementer and the other agent becomes the reviewer; pass `--implementer` / `--reviewer` to choose explicitly. (Started outside a mounted session with no flags, it falls back to a default pairing and warns.) The baton passes between them; only one owns the turn at a time.
 - **Autonomous execution** — the implementer does each step in its real session and hands the result back. An LLM evaluator judges whether the deliverable meets the request.
 - **Review loops** — when work isn't good enough yet, the reviewer's findings are composed into a follow-up handoff and the implementer iterates. The loop repeats until the work is approved or the round budget is exhausted.
 - **Resumability** — workflow and chain state is durable. If the broker restarts or you stop for the day, you recover and reconnect rather than starting over.
@@ -100,6 +100,7 @@ For the full mental model, read [Concepts](docs/concepts.md).
 
 ## Learn more
 
+- [Workflows](docs/workflows.md) — how to use the workflows well: choosing between `spec-driven-development` and `ralph-loop`, and authoring the spec or goal that drives the run.
 - [Concepts](docs/concepts.md) — the mental model: baton handoff, real mounted sessions, supervised autonomy, workflow-first execution.
 - [Relay & handoff flows](docs/relay-handoff-flows.md) — the complete handoff state machine, capture-status table, hotkey reference, per-step verdicts, and troubleshooting.
 - [Evaluator configuration](docs/evaluator-configuration.md) — required credentials and options for the LLM evaluator that gates workflows.

package/dist/bin/companion-agent.js

@@ -5866,12 +5866,16 @@ function createNodePty(input) {
   ensureNodePtySpawnHelperExecutable({
     unixTerminalPath: nodePtyUnixTerminalPath
   });
-  return spawn2(input.config.executable, input.config.execArgs, {
-    name: "xterm-256color",
-    cols: input.cols,
-    rows: input.rows,
-    cwd: input.cwd
-  });
+  return spawn2(input.config.executable, input.config.execArgs, buildClaudePtySpawnOptions({ cols: input.cols, rows: input.rows, cwd: input.cwd }));
+}
+function buildClaudePtySpawnOptions(input) {
+  const env = {};
+  for (const [key, value] of Object.entries(input.baseEnv ?? process.env)) {
+    if (typeof value === "string")
+      env[key] = value;
+  }
+  env.AI_WHISPER_AGENT = "claude";
+  return { name: "xterm-256color", cols: input.cols, rows: input.rows, cwd: input.cwd, env };
 }
 function createClaudeLiveSession(input) {
   let pty = null;
@@ -6169,12 +6173,16 @@ function createNodePty2(input) {
   ensureNodePtySpawnHelperExecutable({
     unixTerminalPath: nodePtyUnixTerminalPath2
   });
-  return spawn4(input.config.executable, input.config.execArgs, {
-    name: "xterm-256color",
-    cols: input.cols,
-    rows: input.rows,
-    cwd: input.cwd
-  });
+  return spawn4(input.config.executable, input.config.execArgs, buildCodexPtySpawnOptions({ cols: input.cols, rows: input.rows, cwd: input.cwd }));
+}
+function buildCodexPtySpawnOptions(input) {
+  const env = {};
+  for (const [key, value] of Object.entries(input.baseEnv ?? process.env)) {
+    if (typeof value === "string")
+      env[key] = value;
+  }
+  env.AI_WHISPER_AGENT = "codex";
+  return { name: "xterm-256color", cols: input.cols, rows: input.rows, cwd: input.cwd, env };
 }
 function createCodexLiveSession(input) {
   let pty = null;

package/dist/bin/whisper.js

@@ -6168,12 +6168,16 @@ function createNodePty(input) {
   ensureNodePtySpawnHelperExecutable({
     unixTerminalPath: nodePtyUnixTerminalPath
   });
-  return spawn3(input.config.executable, input.config.execArgs, {
-    name: "xterm-256color",
-    cols: input.cols,
-    rows: input.rows,
-    cwd: input.cwd
-  });
+  return spawn3(input.config.executable, input.config.execArgs, buildClaudePtySpawnOptions({ cols: input.cols, rows: input.rows, cwd: input.cwd }));
+}
+function buildClaudePtySpawnOptions(input) {
+  const env = {};
+  for (const [key, value] of Object.entries(input.baseEnv ?? process.env)) {
+    if (typeof value === "string")
+      env[key] = value;
+  }
+  env.AI_WHISPER_AGENT = "claude";
+  return { name: "xterm-256color", cols: input.cols, rows: input.rows, cwd: input.cwd, env };
 }
 function createClaudeLiveSession(input) {
   let pty = null;
@@ -6471,12 +6475,16 @@ function createNodePty2(input) {
   ensureNodePtySpawnHelperExecutable({
     unixTerminalPath: nodePtyUnixTerminalPath2
   });
-  return spawn5(input.config.executable, input.config.execArgs, {
-    name: "xterm-256color",
-    cols: input.cols,
-    rows: input.rows,
-    cwd: input.cwd
-  });
+  return spawn5(input.config.executable, input.config.execArgs, buildCodexPtySpawnOptions({ cols: input.cols, rows: input.rows, cwd: input.cwd }));
+}
+function buildCodexPtySpawnOptions(input) {
+  const env = {};
+  for (const [key, value] of Object.entries(input.baseEnv ?? process.env)) {
+    if (typeof value === "string")
+      env[key] = value;
+  }
+  env.AI_WHISPER_AGENT = "codex";
+  return { name: "xterm-256color", cols: input.cols, rows: input.rows, cwd: input.cwd, env };
 }
 function createCodexLiveSession(input) {
   let pty = null;
@@ -10802,21 +10810,62 @@ async function runWorkflowStart(deps) {
     }
   }
   const def = getWorkflowDefinition(deps.workflowType);
-  const implementer = deps.implementer ?? def?.defaultImplementer;
-  const reviewer = deps.reviewer ?? def?.defaultReviewer;
-  if (!implementer || !reviewer) {
-    throw new Error(
-      `Workflow type "${deps.workflowType}" has no default role bindings. Pass --implementer and --reviewer explicitly.`
-    );
+  let resolved;
+  try {
+    resolved = resolveRoleBindings({
+      explicitImplementer: deps.implementer,
+      explicitReviewer: deps.reviewer,
+      callerAgent: deps.callerAgent ?? null,
+      def
+    });
+  } catch (e) {
+    if (e instanceof Error && /no default role bindings/.test(e.message)) {
+      throw new Error(
+        `Workflow type "${deps.workflowType}" has no default role bindings. Pass --implementer and --reviewer explicitly.`
+      );
+    }
+    throw e;
   }
-  return deps.broker.control.createWorkflow({
+  const { workflowId } = deps.broker.control.createWorkflow({
     collabId: deps.collabId,
     workflowType: deps.workflowType,
     specPath: deps.specPath,
-    roleBindings: { implementer, reviewer },
+    roleBindings: { implementer: resolved.implementer, reviewer: resolved.reviewer },
     ...deps.name ? { name: deps.name } : {},
     now: deps.now
   });
+  return { workflowId, ...resolved.warning ? { roleWarning: resolved.warning } : {} };
+}
+var otherAgent = (a) => a === "claude" ? "codex" : "claude";
+function resolveRoleBindings(input) {
+  const { explicitImplementer, explicitReviewer, callerAgent, def } = input;
+  if (explicitImplementer || explicitReviewer) {
+    const implementer2 = explicitImplementer ?? (explicitReviewer ? otherAgent(explicitReviewer) : void 0);
+    const reviewer2 = explicitReviewer ?? (explicitImplementer ? otherAgent(explicitImplementer) : void 0);
+    if (implementer2 && reviewer2) {
+      if (implementer2 === reviewer2) {
+        throw new Error("implementer and reviewer cannot be the same agent");
+      }
+      return { implementer: implementer2, reviewer: reviewer2, source: "explicit" };
+    }
+  }
+  if (callerAgent) {
+    return { implementer: callerAgent, reviewer: otherAgent(callerAgent), source: "caller" };
+  }
+  const implementer = def?.defaultImplementer;
+  const reviewer = def?.defaultReviewer;
+  if (!implementer || !reviewer) {
+    throw new Error("no default role bindings");
+  }
+  return {
+    implementer,
+    reviewer,
+    source: "default",
+    warning: `No triggering agent detected; defaulted to implementer=${implementer} / reviewer=${reviewer}. Pass --implementer / --reviewer to choose explicitly.`
+  };
+}
+function parseCallerAgent(raw) {
+  return raw === "claude" || raw === "codex" ? raw : null;
 }
 
 // src/commands/workflow/list.ts
@@ -11184,8 +11233,10 @@ Not attached (stdin/stdout is not a TTY). To view the tmux session, run:
           ...opts.implementer ? { implementer: opts.implementer } : {},
           ...opts.reviewer ? { reviewer: opts.reviewer } : {},
           ...opts.name ? { name: opts.name } : {},
+          callerAgent: parseCallerAgent(process.env.AI_WHISPER_AGENT),
           now: (/* @__PURE__ */ new Date()).toISOString()
         });
+        if (result.roleWarning) console.error(result.roleWarning);
         console.log(`Workflow started: ${result.workflowId}`);
       } finally {
         await broker.stop();

package/dist/skills/ai-whisper-ralph/SKILL.md

@@ -97,7 +97,7 @@ Run:
 whisper workflow start --type=ralph-loop --spec=<resolved-absolute-path>
 ```
 
-(No `--implementer` / `--reviewer` — the CLI fills ralph defaults: implementer=claude, reviewer=codex. `--spec` names the goal file.)
+(No `--implementer` / `--reviewer` needed — the agent triggering this skill becomes the implementer and the other agent the reviewer. Pass `--implementer <agent> --reviewer <agent>` only to override. `--spec` names the goal file.)
 
 Parse the workflowId from stdout (format: `Workflow started: <workflowId>`).
 

package/dist/skills/ai-whisper-sdd/SKILL.md

@@ -94,7 +94,7 @@ Run:
 whisper workflow start --type=spec-driven-development --spec=<resolved-absolute-path>
 ```
 
-(No `--implementer` / `--reviewer` — the CLI fills SDD defaults: implementer=claude, reviewer=codex.)
+(No `--implementer` / `--reviewer` needed — the agent triggering this skill becomes the implementer and the other agent the reviewer. Pass `--implementer <agent> --reviewer <agent>` only to override.)
 
 Parse the workflowId from stdout (format: `Workflow started: <workflowId>`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-whisper",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Terminal-first relay for paired AI coding agents (Claude + Codex), driven by structured workflows.",
   "license": "Apache-2.0",
   "repository": {
@@ -29,11 +29,11 @@
     "@types/better-sqlite3": "^7.6.12",
     "@types/react": "^19.2.14",
     "ink-testing-library": "^4.0.0",
-    "@ai-whisper/adapter-codex": "0.0.0",
+    "@ai-whisper/adapter-claude": "0.0.0",
     "@ai-whisper/broker": "0.0.0",
+    "@ai-whisper/companion-core": "0.0.0",
     "@ai-whisper/shared": "0.0.0",
-    "@ai-whisper/adapter-claude": "0.0.0",
-    "@ai-whisper/companion-core": "0.0.0"
+    "@ai-whisper/adapter-codex": "0.0.0"
   },
   "files": [
     "dist",

package/skills/ai-whisper-ralph/SKILL.md

@@ -97,7 +97,7 @@ Run:
 whisper workflow start --type=ralph-loop --spec=<resolved-absolute-path>
 ```
 
-(No `--implementer` / `--reviewer` — the CLI fills ralph defaults: implementer=claude, reviewer=codex. `--spec` names the goal file.)
+(No `--implementer` / `--reviewer` needed — the agent triggering this skill becomes the implementer and the other agent the reviewer. Pass `--implementer <agent> --reviewer <agent>` only to override. `--spec` names the goal file.)
 
 Parse the workflowId from stdout (format: `Workflow started: <workflowId>`).
 

package/skills/ai-whisper-sdd/SKILL.md

@@ -94,7 +94,7 @@ Run:
 whisper workflow start --type=spec-driven-development --spec=<resolved-absolute-path>
 ```
 
-(No `--implementer` / `--reviewer` — the CLI fills SDD defaults: implementer=claude, reviewer=codex.)
+(No `--implementer` / `--reviewer` needed — the agent triggering this skill becomes the implementer and the other agent the reviewer. Pass `--implementer <agent> --reviewer <agent>` only to override.)
 
 Parse the workflowId from stdout (format: `Workflow started: <workflowId>`).