refactor(dev): separate start-agent from agent selection (#463)

* fix(dev): align dev new agent flags

* Update auto-generated docs

* refactor(dev): separate start-agent from agent selection

* Update auto-generated docs

Author: basnijholt

.claude-plugin/skills/agent-cli-dev/SKILL.md

@@ -20,7 +20,7 @@ If `agent-cli` is not available, install it first:
 uv tool install agent-cli -p 3.13
 
 # Or run directly without installing
-uvx --python 3.13 agent-cli dev new <branch-name> --agent --prompt "..."
+uvx --python 3.13 agent-cli dev new <branch-name> --prompt "..."
 ```
 
 ## When to spawn parallel agents
@@ -40,17 +40,17 @@ Do NOT spawn when:
 
 For new features (starts from origin/main):
 ```bash
-agent-cli dev new <branch-name> --agent --prompt "Implement the new feature..."
+agent-cli dev new <branch-name> --prompt "Implement the new feature..."
 ```
 
 For work on current branch (review, test, fix) - use `--from HEAD`:
 ```bash
-agent-cli dev new <branch-name> --from HEAD --agent --prompt "Review/test/fix..."
+agent-cli dev new <branch-name> --from HEAD --prompt "Review/test/fix..."
 ```
 
 For longer prompts (recommended for multi-line or complex instructions):
 ```bash
-agent-cli dev new <branch-name> --from HEAD --agent --prompt-file path/to/prompt.md
+agent-cli dev new <branch-name> --from HEAD --prompt-file path/to/prompt.md
 ```
 
 This creates:
@@ -67,10 +67,10 @@ This creates:
 When an assistant is executing this workflow on the user's behalf, the spawn is not complete unless the agent receives a prompt at launch time.
 
 - Prefer `--prompt-file`; create the prompt file first, then launch the agent
-- Use `dev new ... --agent --prompt-file ...` for a new delegated task
+- Use `dev new ... --prompt-file ...` for a new delegated task
 - Use `dev agent ... --prompt-file ...` for another agent in an existing worktree
 - Do not stop after `dev new ...` alone if the user's intent was to delegate work immediately
-- Do not run `dev new ... --agent` or `dev agent ... -m tmux` without `--prompt` or `--prompt-file` unless the user explicitly wants an interactive session that they will drive manually
+- Do not run `dev new ... --start-agent`, `dev new ... --agent <name>`, or `dev agent ... -m tmux` without `--prompt` or `--prompt-file` unless the user explicitly wants an interactive session that they will drive manually
 
 ## Writing effective prompts for spawned agents
 
@@ -92,7 +92,7 @@ Example workflow:
 ```bash
 # 1. Write prompt to file
 # 2. Spawn agent with the file
-agent-cli dev new my-feature --agent --prompt-file .claude/spawn-prompt.md
+agent-cli dev new my-feature --prompt-file .claude/spawn-prompt.md
 # 3. Optionally clean up
 rm .claude/spawn-prompt.md
 ```
@@ -144,7 +144,7 @@ agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-tests.md
 
 Key rules for same-worktree launches:
 - Use `dev agent`, not `dev new`, after the worktree already exists
-- Use `dev agent -a <agent>` to select a specific agent for an existing worktree; `--with-agent` remains a deprecated alias on this subcommand
+- Use `dev agent --agent <agent>` to select a specific agent for an existing worktree; `--with-agent` remains a deprecated alias on this subcommand
 - Use `-m tmux` for headless or scripted launching; it works even when not already inside tmux
 - Each launch joins the same deterministic repo-scoped tmux session, so related agents stay grouped together
 - Ask each agent to write to a unique report path such as `.claude/REPORT-security-<run-id>.md` or `.claude/REPORT-tests-<run-id>.md`
@@ -171,7 +171,7 @@ When complete, write findings to .claude/REPORT-security-20260319-153045-123.md
 For non-interactive contexts (scripts, cron jobs, other assistants), combine `--prompt-file` with `-m tmux`:
 
 ```bash
-agent-cli dev new validation-a --from HEAD --agent --with-agent codex -m tmux \
+agent-cli dev new validation-a --from HEAD --agent codex -m tmux \
   --prompt-file .claude/validation-a.md
 ```
 
@@ -183,9 +183,9 @@ If asked to implement auth, payments, and notifications:
 
 ```bash
 # Spawn three parallel agents
-agent-cli dev new auth-feature --agent --prompt "Implement JWT authentication..."
-agent-cli dev new payment-integration --agent --prompt "Add Stripe payment processing..."
-agent-cli dev new email-notifications --agent --prompt "Implement email notification system..."
+agent-cli dev new auth-feature --prompt "Implement JWT authentication..."
+agent-cli dev new payment-integration --prompt "Add Stripe payment processing..."
+agent-cli dev new email-notifications --prompt "Implement email notification system..."
 ```
 
 Each agent works independently in its own branch. Results can be reviewed and merged separately.
@@ -194,11 +194,11 @@ Each agent works independently in its own branch. Results can be reviewed and me
 
 | Option | Description |
 |--------|-------------|
-| `--agent` / `-a` | Start AI coding agent after creation |
+| `--start-agent` | Start the default/auto-detected agent without an initial prompt |
 | `--prompt` / `-p` | Initial prompt for the agent (short prompts only) |
 | `--prompt-file` / `-P` | Read prompt from file (recommended for longer prompts) |
 | `--from` / `-f` | Base ref (default: origin/main). **Use `--from HEAD` when reviewing/testing current branch!** |
-| `--with-agent` | Specific agent: claude, aider, codex, gemini |
+| `--agent` | Specific agent (or `auto`): claude, aider, codex, gemini |
 | `--agent-args` | Extra arguments for the agent |
 
 @examples.md

.claude-plugin/skills/agent-cli-dev/examples.md

@@ -6,7 +6,7 @@ Real-world scenarios for spawning parallel AI coding agents, optimized for Claud
 >
 > ```bash
 > # Write prompt to file, then spawn
-> agent-cli dev new my-feature --agent --prompt-file .claude/spawn-prompt.md
+> agent-cli dev new my-feature --prompt-file .claude/spawn-prompt.md
 > ```
 >
 > When an assistant is executing these commands, do not launch `dev new` or `dev agent` without `--prompt` or `--prompt-file` unless the user explicitly wants a manual interactive session.
@@ -31,7 +31,7 @@ Each prompt for a spawned agent should follow this structure:
 
 ```bash
 # Review the current branch - MUST use --from HEAD
-agent-cli dev new review-changes --from HEAD --agent --prompt "Review the code changes on this branch.
+agent-cli dev new review-changes --from HEAD --prompt "Review the code changes on this branch.
 
 <workflow>
 - Run git diff origin/main...HEAD to identify all changes
@@ -91,7 +91,7 @@ Write your review to .claude/REPORT.md:
 **Strategy**: Three independent features → spawn three agents.
 
 ```bash
-agent-cli dev new auth-feature --agent --prompt "Implement JWT-based user authentication.
+agent-cli dev new auth-feature --prompt "Implement JWT-based user authentication.
 
 <workflow>
 - Read multiple files in parallel when exploring the codebase
@@ -144,7 +144,7 @@ How to verify the implementation works
 Any items needing review
 </report>"
 
-agent-cli dev new payment-integration --agent --prompt "Integrate Stripe payment processing.
+agent-cli dev new payment-integration --prompt "Integrate Stripe payment processing.
 
 <workflow>
 - Read multiple files in parallel when exploring the codebase
@@ -195,7 +195,7 @@ After verifying tests pass, write to .claude/REPORT.md:
 [Any items for review]
 </report>"
 
-agent-cli dev new email-notifications --agent --prompt "Implement email notification system.
+agent-cli dev new email-notifications --prompt "Implement email notification system.
 
 <workflow>
 - Read multiple files in parallel when exploring the codebase
@@ -240,7 +240,7 @@ After verifying tests pass, write to .claude/REPORT.md with summary, files chang
 **Strategy**: One agent writes tests first, another implements.
 
 ```bash
-agent-cli dev new cache-tests --agent --prompt "Write comprehensive tests for a caching layer.
+agent-cli dev new cache-tests --prompt "Write comprehensive tests for a caching layer.
 
 <task>
 Create a complete test suite that drives the implementation of a caching system. The tests define the interface - write them as if the implementation already exists.
@@ -306,7 +306,7 @@ When complete, write to .claude/REPORT.md:
 After reviewing the tests:
 
 ```bash
-agent-cli dev new cache-impl --from cache-tests --agent --prompt "Implement the caching layer to pass existing tests.
+agent-cli dev new cache-impl --from cache-tests --prompt "Implement the caching layer to pass existing tests.
 
 <workflow>
 - Read all test files first to understand the complete interface
@@ -360,7 +360,7 @@ After ALL tests pass, write to .claude/REPORT.md:
 **Strategy**: Split by module, each agent handles one area.
 
 ```bash
-agent-cli dev new refactor-users-errors --agent --prompt "Refactor error handling in the users module.
+agent-cli dev new refactor-users-errors --prompt "Refactor error handling in the users module.
 
 <workflow>
 - Read all relevant files in parallel before making any changes
@@ -428,7 +428,7 @@ After tests pass and linting is clean, write to .claude/REPORT.md:
 **Strategy**: One agent implements, another writes docs simultaneously.
 
 ```bash
-agent-cli dev new plugin-system --agent --prompt "Implement a plugin system.
+agent-cli dev new plugin-system --prompt "Implement a plugin system.
 
 <workflow>
 - Read existing codebase structure in parallel before designing
@@ -483,7 +483,7 @@ class Plugin:
 [How to create and register a plugin]
 </report>"
 
-agent-cli dev new plugin-docs --agent --prompt "Write documentation for the plugin system.
+agent-cli dev new plugin-docs --prompt "Write documentation for the plugin system.
 
 <context>
 Implementation is happening in parallel in another branch. Write documentation based on a standard plugin system design. The implementation agent will adapt if needed, or you can update docs after reviewing their work.
@@ -595,7 +595,7 @@ Write findings to .claude/REPORT-tests-$run_id.md:
 
 ```bash
 for section in 1 2 3 4 5 6 7 8; do
-  agent-cli dev new "test-section-$section" --from HEAD --agent --with-agent codex -m tmux \
+  agent-cli dev new "test-section-$section" --from HEAD --agent codex -m tmux \
     --prompt-file ".claude/test-section-$section.md"
 done
 ```

.claude/skills/agent-cli-dev/SKILL.md

@@ -20,7 +20,7 @@ If `agent-cli` is not available, install it first:
 uv tool install agent-cli -p 3.13
 
 # Or run directly without installing
-uvx --python 3.13 agent-cli dev new <branch-name> --agent --prompt "..."
+uvx --python 3.13 agent-cli dev new <branch-name> --prompt "..."
 ```
 
 ## When to spawn parallel agents
@@ -40,17 +40,17 @@ Do NOT spawn when:
 
 For new features (starts from origin/main):
 ```bash
-agent-cli dev new <branch-name> --agent --prompt "Implement the new feature..."
+agent-cli dev new <branch-name> --prompt "Implement the new feature..."
 ```
 
 For work on current branch (review, test, fix) - use `--from HEAD`:
 ```bash
-agent-cli dev new <branch-name> --from HEAD --agent --prompt "Review/test/fix..."
+agent-cli dev new <branch-name> --from HEAD --prompt "Review/test/fix..."
 ```
 
 For longer prompts (recommended for multi-line or complex instructions):
 ```bash
-agent-cli dev new <branch-name> --from HEAD --agent --prompt-file path/to/prompt.md
+agent-cli dev new <branch-name> --from HEAD --prompt-file path/to/prompt.md
 ```
 
 This creates:
@@ -67,10 +67,10 @@ This creates:
 When an assistant is executing this workflow on the user's behalf, the spawn is not complete unless the agent receives a prompt at launch time.
 
 - Prefer `--prompt-file`; create the prompt file first, then launch the agent
-- Use `dev new ... --agent --prompt-file ...` for a new delegated task
+- Use `dev new ... --prompt-file ...` for a new delegated task
 - Use `dev agent ... --prompt-file ...` for another agent in an existing worktree
 - Do not stop after `dev new ...` alone if the user's intent was to delegate work immediately
-- Do not run `dev new ... --agent` or `dev agent ... -m tmux` without `--prompt` or `--prompt-file` unless the user explicitly wants an interactive session that they will drive manually
+- Do not run `dev new ... --start-agent`, `dev new ... --agent <name>`, or `dev agent ... -m tmux` without `--prompt` or `--prompt-file` unless the user explicitly wants an interactive session that they will drive manually
 
 ## Writing effective prompts for spawned agents
 
@@ -92,7 +92,7 @@ Example workflow:
 ```bash
 # 1. Write prompt to file
 # 2. Spawn agent with the file
-agent-cli dev new my-feature --agent --prompt-file .claude/spawn-prompt.md
+agent-cli dev new my-feature --prompt-file .claude/spawn-prompt.md
 # 3. Optionally clean up
 rm .claude/spawn-prompt.md
 ```
@@ -144,7 +144,7 @@ agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-tests.md
 
 Key rules for same-worktree launches:
 - Use `dev agent`, not `dev new`, after the worktree already exists
-- Use `dev agent -a <agent>` to select a specific agent for an existing worktree; `--with-agent` remains a deprecated alias on this subcommand
+- Use `dev agent --agent <agent>` to select a specific agent for an existing worktree; `--with-agent` remains a deprecated alias on this subcommand
 - Use `-m tmux` for headless or scripted launching; it works even when not already inside tmux
 - Each launch joins the same deterministic repo-scoped tmux session, so related agents stay grouped together
 - Ask each agent to write to a unique report path such as `.claude/REPORT-security-<run-id>.md` or `.claude/REPORT-tests-<run-id>.md`
@@ -171,7 +171,7 @@ When complete, write findings to .claude/REPORT-security-20260319-153045-123.md
 For non-interactive contexts (scripts, cron jobs, other assistants), combine `--prompt-file` with `-m tmux`:
 
 ```bash
-agent-cli dev new validation-a --from HEAD --agent --with-agent codex -m tmux \
+agent-cli dev new validation-a --from HEAD --agent codex -m tmux \
   --prompt-file .claude/validation-a.md
 ```
 
@@ -183,9 +183,9 @@ If asked to implement auth, payments, and notifications:
 
 ```bash
 # Spawn three parallel agents
-agent-cli dev new auth-feature --agent --prompt "Implement JWT authentication..."
-agent-cli dev new payment-integration --agent --prompt "Add Stripe payment processing..."
-agent-cli dev new email-notifications --agent --prompt "Implement email notification system..."
+agent-cli dev new auth-feature --prompt "Implement JWT authentication..."
+agent-cli dev new payment-integration --prompt "Add Stripe payment processing..."
+agent-cli dev new email-notifications --prompt "Implement email notification system..."
 ```
 
 Each agent works independently in its own branch. Results can be reviewed and merged separately.
@@ -194,11 +194,11 @@ Each agent works independently in its own branch. Results can be reviewed and me
 
 | Option | Description |
 |--------|-------------|
-| `--agent` / `-a` | Start AI coding agent after creation |
+| `--start-agent` | Start the default/auto-detected agent without an initial prompt |
 | `--prompt` / `-p` | Initial prompt for the agent (short prompts only) |
 | `--prompt-file` / `-P` | Read prompt from file (recommended for longer prompts) |
 | `--from` / `-f` | Base ref (default: origin/main). **Use `--from HEAD` when reviewing/testing current branch!** |
-| `--with-agent` | Specific agent: claude, aider, codex, gemini |
+| `--agent` | Specific agent (or `auto`): claude, aider, codex, gemini |
 | `--agent-args` | Extra arguments for the agent |
 
 @examples.md

.claude/skills/agent-cli-dev/examples.md

@@ -6,7 +6,7 @@ Real-world scenarios for spawning parallel AI coding agents, optimized for Claud
 >
 > ```bash
 > # Write prompt to file, then spawn
-> agent-cli dev new my-feature --agent --prompt-file .claude/spawn-prompt.md
+> agent-cli dev new my-feature --prompt-file .claude/spawn-prompt.md
 > ```
 >
 > When an assistant is executing these commands, do not launch `dev new` or `dev agent` without `--prompt` or `--prompt-file` unless the user explicitly wants a manual interactive session.
@@ -31,7 +31,7 @@ Each prompt for a spawned agent should follow this structure:
 
 ```bash
 # Review the current branch - MUST use --from HEAD
-agent-cli dev new review-changes --from HEAD --agent --prompt "Review the code changes on this branch.
+agent-cli dev new review-changes --from HEAD --prompt "Review the code changes on this branch.
 
 <workflow>
 - Run git diff origin/main...HEAD to identify all changes
@@ -91,7 +91,7 @@ Write your review to .claude/REPORT.md:
 **Strategy**: Three independent features → spawn three agents.
 
 ```bash
-agent-cli dev new auth-feature --agent --prompt "Implement JWT-based user authentication.
+agent-cli dev new auth-feature --prompt "Implement JWT-based user authentication.
 
 <workflow>
 - Read multiple files in parallel when exploring the codebase
@@ -144,7 +144,7 @@ How to verify the implementation works
 Any items needing review
 </report>"
 
-agent-cli dev new payment-integration --agent --prompt "Integrate Stripe payment processing.
+agent-cli dev new payment-integration --prompt "Integrate Stripe payment processing.
 
 <workflow>
 - Read multiple files in parallel when exploring the codebase
@@ -195,7 +195,7 @@ After verifying tests pass, write to .claude/REPORT.md:
 [Any items for review]
 </report>"
 
-agent-cli dev new email-notifications --agent --prompt "Implement email notification system.
+agent-cli dev new email-notifications --prompt "Implement email notification system.
 
 <workflow>
 - Read multiple files in parallel when exploring the codebase
@@ -240,7 +240,7 @@ After verifying tests pass, write to .claude/REPORT.md with summary, files chang
 **Strategy**: One agent writes tests first, another implements.
 
 ```bash
-agent-cli dev new cache-tests --agent --prompt "Write comprehensive tests for a caching layer.
+agent-cli dev new cache-tests --prompt "Write comprehensive tests for a caching layer.
 
 <task>
 Create a complete test suite that drives the implementation of a caching system. The tests define the interface - write them as if the implementation already exists.
@@ -306,7 +306,7 @@ When complete, write to .claude/REPORT.md:
 After reviewing the tests:
 
 ```bash
-agent-cli dev new cache-impl --from cache-tests --agent --prompt "Implement the caching layer to pass existing tests.
+agent-cli dev new cache-impl --from cache-tests --prompt "Implement the caching layer to pass existing tests.
 
 <workflow>
 - Read all test files first to understand the complete interface
@@ -360,7 +360,7 @@ After ALL tests pass, write to .claude/REPORT.md:
 **Strategy**: Split by module, each agent handles one area.
 
 ```bash
-agent-cli dev new refactor-users-errors --agent --prompt "Refactor error handling in the users module.
+agent-cli dev new refactor-users-errors --prompt "Refactor error handling in the users module.
 
 <workflow>
 - Read all relevant files in parallel before making any changes
@@ -428,7 +428,7 @@ After tests pass and linting is clean, write to .claude/REPORT.md:
 **Strategy**: One agent implements, another writes docs simultaneously.
 
 ```bash
-agent-cli dev new plugin-system --agent --prompt "Implement a plugin system.
+agent-cli dev new plugin-system --prompt "Implement a plugin system.
 
 <workflow>
 - Read existing codebase structure in parallel before designing
@@ -483,7 +483,7 @@ class Plugin:
 [How to create and register a plugin]
 </report>"
 
-agent-cli dev new plugin-docs --agent --prompt "Write documentation for the plugin system.
+agent-cli dev new plugin-docs --prompt "Write documentation for the plugin system.
 
 <context>
 Implementation is happening in parallel in another branch. Write documentation based on a standard plugin system design. The implementation agent will adapt if needed, or you can update docs after reviewing their work.
@@ -595,7 +595,7 @@ Write findings to .claude/REPORT-tests-$run_id.md:
 
 ```bash
 for section in 1 2 3 4 5 6 7 8; do
-  agent-cli dev new "test-section-$section" --from HEAD --agent --with-agent codex -m tmux \
+  agent-cli dev new "test-section-$section" --from HEAD --agent codex -m tmux \
     --prompt-file ".claude/test-section-$section.md"
 done
 ```