From 030c669c371df85d3617003d5716b7e3b2aa71f3 Mon Sep 17 00:00:00 2001
From: suraj-markup <sk9261712674@gmail.com>
Date: Tue, 17 Mar 2026 14:32:35 +0530
Subject: [PATCH] Show friendly warning instead of hard error for old two-arg
 spawn syntax

When users run `ao spawn <project> <issue>`, show a yellow warning
explaining the new syntax (`ao spawn <issue>`) instead of Commander's
raw "too many arguments" error.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/cli/__tests__/commands/spawn.test.ts | 11 +++++++--
 packages/cli/src/commands/spawn.ts            | 23 +++++++++++++++----
 2 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/packages/cli/__tests__/commands/spawn.test.ts b/packages/cli/__tests__/commands/spawn.test.ts
index c4abf109a..c9074cc07 100644
--- a/packages/cli/__tests__/commands/spawn.test.ts
+++ b/packages/cli/__tests__/commands/spawn.test.ts
@@ -307,10 +307,17 @@ describe("spawn command", () => {
     });
   });
 
-  it("rejects two positional args with helpful usage message", async () => {
+  it("warns and exits when two positional args given (old syntax)", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
     await expect(
       program.parseAsync(["node", "test", "spawn", "my-app", "INT-100"]),
-    ).rejects.toThrow();
+    ).rejects.toThrow("process.exit(1)");
+
+    const warnings = warnSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(warnings).toContain("no longer supported");
+    expect(warnings).toContain("ao spawn INT-100");
+    warnSpy.mockRestore();
   });
 
   it("reports error when spawn fails", async () => {
diff --git a/packages/cli/src/commands/spawn.ts b/packages/cli/src/commands/spawn.ts
index 49d71e877..eecd3d075 100644
--- a/packages/cli/src/commands/spawn.ts
+++ b/packages/cli/src/commands/spawn.ts
@@ -158,7 +158,8 @@ export function registerSpawn(program: Command): void {
   program
     .command("spawn")
     .description("Spawn a single agent session")
-    .argument("[issue]", "Issue identifier (project is auto-detected)")
+    .argument("[first]", "Issue identifier (project is auto-detected)")
+    .argument("[second]", "", /* hidden second arg to catch old two-arg usage */)
     .option("--open", "Open session in terminal tab")
     .option("--agent <name>", "Override the agent plugin (e.g. codex, claude-code)")
     .option("--claim-pr <pr>", "Immediately claim an existing PR for the spawned session")
@@ -167,7 +168,8 @@ export function registerSpawn(program: Command): void {
     .option("--max-depth <n>", "Max decomposition depth (default: 3)")
     .action(
       async (
-        issue: string | undefined,
+        first: string | undefined,
+        second: string | undefined,
         opts: {
           open?: boolean;
           agent?: string;
@@ -177,12 +179,25 @@ export function registerSpawn(program: Command): void {
           maxDepth?: string;
         },
       ) => {
+        // Catch old two-arg usage: ao spawn <project> <issue>
+        if (first && second) {
+          console.warn(
+            chalk.yellow(
+              `⚠ 'ao spawn <project> <issue>' is no longer supported.\n` +
+                `  The project is now auto-detected. Use:\n\n` +
+                `    ao spawn ${second}    # spawn with issue ${second}\n` +
+                `    ao spawn              # spawn without an issue\n`,
+            ),
+          );
+          process.exit(1);
+        }
+
         const config = loadConfig();
         let projectId: string;
         let issueId: string | undefined;
 
-        if (issue) {
-          issueId = issue;
+        if (first) {
+          issueId = first;
           try {
             projectId = autoDetectProject(config);
           } catch (err) {