fix(iflow): correct CLI agent invocation syntax

.trellis/spec/cli/backend/platform-integration.md

@@ -419,7 +419,35 @@ find src/templates/*/commands/trellis/ -name "record-session.*"
 - Command invocation syntax (e.g., `/trellis:xxx` vs `$skill-name`)
 - Config directory references (e.g., `.claude/` vs `.qoder/`)
 
+### iFlow CLI agent invocation uses wrong syntax
 
+**Symptom**: Multi-agent pipeline fails with "iflow: unrecognized option '--agent'" error.
+
+**Cause**: iFlow CLI does NOT support the `--agent` flag (unlike Claude Code, OpenCode). It uses skill-based invocation with `$agent_name` prefix syntax (similar to Codex/Kiro). The `cli_adapter.py` was incorrectly generating `iflow -p --agent plan` instead of `iflow -y -p "$plan prompt"`.
+
+**Fix**: Update `cli_adapter.py` `build_run_command()` for iFlow:
+```python
+# Wrong:
+cmd = ["iflow", "-p"]
+cmd.extend(["-y", "--agent", mapped_agent])
+cmd.append(prompt)
+
+# Correct:
+cmd = ["iflow", "-y", "-p"]
+cmd.append(f"${mapped_agent} {prompt}")
+```
+
+**Key points**:
+- iFlow does NOT support `--agent` flag
+- iFlow does NOT support `--verbose` flag
+- Agent name and prompt must be combined: `"$agent_name prompt"`
+- Non-interactive flag is `-y` (before `-p`)
+
+**Prevention**: When adding a new platform, always verify the actual CLI syntax from official docs or by testing. Do NOT assume all platforms follow the same pattern as Claude Code/OpenCode.
+
+---
+
+### iFlow collectTemplates missing trellis/ subdirectory (FIXED)
 
 **Symptom**: `trellis update` creates iFlow commands at `.iflow/commands/{name}.md` (flat) instead of `.iflow/commands/trellis/{name}.md` (correct).
 

packages/cli/src/templates/trellis/scripts/common/cli_adapter.py

@@ -278,12 +278,8 @@ def build_run_command(
             cmd.append(prompt)
 
         elif self.platform == "iflow":
-            cmd = ["iflow", "-p"]
-            cmd.extend(["-y", "--agent", mapped_agent])
-            # iFlow doesn't support --session-id on creation
-            if verbose:
-                cmd.append("--verbose")
-            cmd.append(prompt)
+            cmd = ["iflow", "-y", "-p"]
+            cmd.append(f"${mapped_agent} {prompt}")
         elif self.platform == "codex":
             cmd = ["codex", "exec"]
             cmd.append(prompt)

packages/cli/test/regression.test.ts

@@ -610,6 +610,17 @@ describe("regression: cli_adapter platform support (beta.9, beta.13, beta.16)",
     expect(commonCliAdapter).toContain(".agent");
     expect(commonCliAdapter).toContain(".qoder");
   });
+
+  it("[0.3.10] iFlow CLI uses correct agent invocation syntax", () => {
+    // iFlow does NOT support --agent flag, uses $agent_name prefix instead
+    // Verify the correct command format exists
+    expect(commonCliAdapter).toContain('cmd = ["iflow", "-y", "-p"]');
+    expect(commonCliAdapter).toContain('f"${mapped_agent} {prompt}"');
+
+    // Verify that the old incorrect format does NOT exist
+    // The bug was: cmd.extend(["-y", "--agent", mapped_agent])
+    expect(commonCliAdapter).not.toContain('cmd.extend(["-y", "--agent", mapped_agent])');
+  });
 });
 
 // =============================================================================