ruvnet/ruflo · error

Invalid --worker spec "${spec}". Missing prompt after "<plat

Error message

Invalid --worker spec "${spec}". Missing prompt after "<platform>:<role>:".

What it means

parseWorkerSpecs() variant thrown when the spec has the two structural colons but the text after the second colon trims to an empty string — the prompt segment is missing even though the shape looks right. The role may default (worker-N) when blank, but the prompt is mandatory because it is the actual task instruction handed to the spawned claude/codex process.

Source

Thrown at v3/@claude-flow/codex/src/dual-mode/cli.ts:277

 * Parse `--worker "<platform>:<role>:<prompt>"` specs into WorkerConfig[].
 * Splits on the first two `:` so the prompt may itself contain colons.
 * Workers chain sequentially (each depends on the previous) unless `parallel`.
 */
export function parseWorkerSpecs(specs: string[], parallel: boolean): WorkerConfig[] {
  const usedIds = new Set<string>();
  const workers: WorkerConfig[] = [];

  specs.forEach((spec, index) => {
    const firstColon = spec.indexOf(':');
    const secondColon = firstColon >= 0 ? spec.indexOf(':', firstColon + 1) : -1;
    if (firstColon < 0 || secondColon < 0) {
      throw new Error(`Invalid --worker spec "${spec}". Expected "<platform>:<role>:<prompt>" (platform = claude|codex).`);
    }
    const platformRaw = spec.slice(0, firstColon).trim().toLowerCase();
    const role = spec.slice(firstColon + 1, secondColon).trim() || `worker-${index + 1}`;
    const prompt = spec.slice(secondColon + 1).trim();
    if (!prompt) {
      throw new Error(`Invalid --worker spec "${spec}". Missing prompt after "<platform>:<role>:".`);
    }
    if (platformRaw !== 'claude' && platformRaw !== 'codex') {
      throw new Error(`Invalid platform "${platformRaw}" in --worker spec "${spec}". Use "claude" or "codex".`);
    }
    const platform: 'claude' | 'codex' = platformRaw;

    // Derive a unique id from the role.
    const base = role.replace(/\s+/g, '-');
    let id = base;
    let suffix = 2;
    while (usedIds.has(id)) { id = `${base}-${suffix++}`; }
    usedIds.add(id);

    const worker: WorkerConfig = { id, platform, role, prompt };
    const prev = workers[workers.length - 1];
    if (!parallel && prev) {
      worker.dependsOn = [prev.id];
    }

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Append a real task description after the second colon: `--worker "codex:reviewer:Check error handling in src/api"`.
2. If building specs programmatically, assert the prompt variable is non-empty before concatenating.
3. Trim leading/trailing whitespace so accidental blank prompts are caught by your own validation with a clearer message.
4. Quote the whole spec so trailing spaces/colons survive the shell intact.

Example fix

# before
$ dual-mode collaborate --worker "codex:reviewer:"
Error: Invalid --worker spec "codex:reviewer:". Missing prompt after "<platform>:<role>:".

# after
$ dual-mode collaborate --worker "codex:reviewer:Audit the retry logic in uploadToGCS"

const specs = rawSpecs.map(s => s.trim());
const empties = specs.filter(s => {
  const second = s.indexOf(':', s.indexOf(':') + 1);
  return second < 0 || s.slice(second + 1).trim() === '';
});
if (empties.length) {
  throw new Error(`worker specs missing a prompt: ${empties.join(' | ')}`);
}
const workers = parseWorkerSpecs(specs, parallel);

try {
  const workers = parseWorkerSpecs(specs, parallel);
} catch (err) {
  if (err instanceof Error && err.message.includes('Missing prompt after')) {
    throw new Error(`every worker needs a task description after "<platform>:<role>:" — got: ${specs.join(', ')}`);
  }
  throw err;
}

When it happens

Trigger: (1) `--worker "codex:reviewer:"` — trailing colon with nothing after it; (2) a spec whose third segment is only whitespace, e.g. "claude:impl: "; (3) templates or scripts that concatenate an empty prompt variable into the spec string.

Common situations: Script-built worker specs where $PROMPT was unset; shell history edits that truncated the tail; copying a spec and deleting the prompt to 'fill in later' then running it.

Related errors

• Invalid --worker spec "${spec}". Expected "<platform>:<role>
• Invalid platform "${platformRaw}" in --worker spec "${spec}"
• Unknown template: ${template}
• Invalid CFP file: ${e instanceof Error ? e.message : String(
• unattended swarm automation is disabled; set [swarm.automati

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/bd47b0a378d55960. Report an issue: GitHub.