agent-cli 0.86.1__tar.gz → 0.87.0__tar.gz

{agent_cli-0.86.1/agent_cli/dev/skill → agent_cli-0.87.0/.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

{agent_cli-0.86.1 → agent_cli-0.87.0}/.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
 ```

{agent_cli-0.86.1/.claude → agent_cli-0.87.0/.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

{agent_cli-0.86.1 → agent_cli-0.87.0}/.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
 ```

{agent_cli-0.86.1 → agent_cli-0.87.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-cli
-Version: 0.86.1
+Version: 0.87.0
 Summary: A suite of AI-powered command-line tools for text correction, audio transcription, and voice assistance.
 Project-URL: Homepage, https://github.com/basnijholt/agent-cli
 Author-email: Bas Nijholt <bas@nijho.lt>

{agent_cli-0.86.1 → agent_cli-0.87.0}/agent_cli/dev/cli.py

@@ -51,9 +51,9 @@ has its own branch and working directory.
 
 **Common workflows:**
 
-- `dev new feature-x -a` — Create worktree + start AI agent in new terminal tab
-- `dev new feature-x -e -a` — Create worktree + open editor + start agent
-- `dev new -a -p "Fix the auth bug"` — Create worktree + start agent with prompt
+- `dev new feature-x --start-agent` — Create worktree + start AI agent in new terminal tab
+- `dev new feature-x -e --start-agent` — Create worktree + open editor + start agent
+- `dev new --prompt "Fix the auth bug"` — Create worktree + start agent with prompt
 - `dev status` — See all worktrees with uncommitted changes
 - `dev clean --merged` — Remove worktrees whose PRs are merged
 
@@ -157,6 +157,36 @@ def _resolve_prompt_text(
     return prompt
 
 
+def _resolve_dev_new_agent_request(
+    *,
+    start_agent: bool,
+    start_agent_deprecated: bool,
+    agent_name: str | None,
+    agent_name_deprecated: str | None,
+    prompt: str | None,
+) -> tuple[bool, str | None]:
+    """Normalize launch-related flags for `dev new`."""
+    if start_agent_deprecated:
+        warn("-a is deprecated for 'dev new', use --start-agent instead")
+        start_agent = True
+
+    explicit_agent_requested = agent_name is not None or agent_name_deprecated is not None
+    if agent_name_deprecated is not None:
+        warn("--with-agent is deprecated for 'dev new', use --agent instead")
+        agent_name = agent_name or agent_name_deprecated
+
+    if agent_name is not None:
+        normalized_agent = agent_name.strip().lower()
+        if not normalized_agent:
+            error("--agent cannot be empty")
+        agent_name = None if normalized_agent == "auto" else normalized_agent
+
+    if prompt or explicit_agent_requested:
+        start_agent = True
+
+    return start_agent, agent_name
+
+
 def _resolve_branch_name(
     branch: str | None,
     branch_name_mode: str,
@@ -280,19 +310,34 @@ def new(
             help="Open the worktree in an editor. Uses --with-editor, config default, or auto-detects",
         ),
     ] = False,
-    agent: Annotated[
+    start_agent: Annotated[
+        bool,
+        typer.Option(
+            "--start-agent",
+            help="Start an AI coding agent in a new terminal tab without providing an initial prompt. Uses config default or auto-detects.",
+        ),
+    ] = False,
+    start_agent_deprecated: Annotated[
         bool,
         typer.Option(
-            "--agent",
             "-a",
-            help="Start an AI coding agent in a new terminal tab. Uses --with-agent, config default, or auto-detects. Implied by --prompt",
+            hidden=True,
+            help="[Deprecated: use --start-agent] Start an AI coding agent in a new terminal tab",
         ),
     ] = False,
     agent_name: Annotated[
+        str | None,
+        typer.Option(
+            "--agent",
+            help="Which AI agent to start: claude, codex, gemini, aider, copilot, cn (Continue), opencode, cursor-agent, or auto. Implies starting the agent",
+        ),
+    ] = None,
+    agent_name_deprecated: Annotated[
         str | None,
         typer.Option(
             "--with-agent",
-            help="Which AI agent to start: claude, codex, gemini, aider, copilot, cn (Continue), opencode, cursor-agent",
+            hidden=True,
+            help="[Deprecated: use --agent] Which AI agent to start",
         ),
     ] = None,
     editor_name: Annotated[
@@ -343,7 +388,7 @@ def new(
         str | None,
         typer.Option(
             "--branch-name-agent",
-            help="Headless agent for AI branch naming: claude, codex, or gemini. If omitted, uses --with-agent when supported, otherwise tries available agents in that order",
+            help="Headless agent for AI branch naming: claude, codex, or gemini. If omitted, uses --agent when supported, otherwise tries available agents in that order",
         ),
     ] = None,
     branch_name_timeout: Annotated[
@@ -373,7 +418,7 @@ def new(
         typer.Option(
             "--prompt",
             "-p",
-            help="Initial task for the AI agent. Saved to a unique file in .claude/ to avoid conflicts. Implies --agent. Example: --prompt='Fix the login bug'",
+            help="Initial task for the AI agent. Saved to a unique file in .claude/ to avoid conflicts. Implies starting the agent. Example: --prompt='Fix the login bug'",
         ),
     ] = None,
     prompt_file: Annotated[
@@ -381,7 +426,7 @@ def new(
         typer.Option(
             "--prompt-file",
             "-P",
-            help="Read the agent prompt from a file. Useful for long prompts to avoid shell quoting. Implies --agent",
+            help="Read the agent prompt from a file. Useful for long prompts to avoid shell quoting. Implies starting the agent",
             exists=True,
             readable=True,
         ),
@@ -423,24 +468,27 @@ def new(
     3. Runs project setup: npm install, uv sync, etc. (--setup)
     4. Sets up direnv if installed (--direnv)
     5. Opens editor if requested (-e/--editor)
-    6. Starts AI agent in new terminal tab if requested (-a/--agent or --prompt)
+    6. Starts AI agent in new terminal tab if requested (--start-agent, --agent, --prompt, or --prompt-file)
 
     **Examples:**
 
     - `dev new feature-x` — Create worktree, branching from origin/main (default)
-    - `dev new feature-x -a` — Create + start Claude/detected agent
-    - `dev new feature-x -e -a` — Create + open editor + start agent
-    - `dev new -a --prompt "Fix auth bug"` — Auto-named branch + agent with task
-    - `dev new --branch-name-mode ai -a --prompt "Refactor auth flow"` — AI-generated branch name
+    - `dev new feature-x --start-agent` — Create + start Claude/detected agent
+    - `dev new feature-x -e --start-agent` — Create + open editor + start agent
+    - `dev new --prompt "Fix auth bug"` — Auto-named branch + agent with task
+    - `dev new --branch-name-mode ai --prompt "Refactor auth flow"` — AI-generated branch name
     - `dev new hotfix --from v1.2.3` — Branch from a tag instead of main
     - `dev new feature-x --from origin/develop` — Branch from develop instead
-    - `dev new feature-x --with-agent aider --with-editor cursor` — Specific tools
+    - `dev new feature-x --agent aider --with-editor cursor` — Specific tools
     """
     prompt = _resolve_prompt_text(prompt, prompt_file=prompt_file)
-
-    # If a prompt is provided, automatically enable agent mode
-    if prompt:
-        agent = True
+    start_agent, agent_name = _resolve_dev_new_agent_request(
+        start_agent=start_agent,
+        start_agent_deprecated=start_agent_deprecated,
+        agent_name=agent_name,
+        agent_name_deprecated=agent_name_deprecated,
+        prompt=prompt,
+    )
 
     repo_root = _ensure_git_repo()
 
@@ -455,8 +503,8 @@ def new(
         from_ref,
     )
 
-    resolved_agent = resolve_agent(agent, agent_name, default_agent)
-    if agent:
+    resolved_agent = resolve_agent(start_agent, agent_name, default_agent)
+    if start_agent:
         resolved_agent = _require_available_agent(resolved_agent, requested_name=agent_name)
 
     # Create the worktree
@@ -1185,7 +1233,7 @@ def list_terminals_cmd(
     Shows supported terminals: tmux, zellij, kitty, iTerm2, Terminal.app,
     Warp, GNOME Terminal.
 
-    These are used to open new tabs when launching AI agents with `dev new -a`.
+    These are used to open new tabs when launching AI agents with `dev new --start-agent`.
     The current terminal (if detectable) is marked.
     """
     current = terminals.detect_current_terminal()

{agent_cli-0.86.1/.claude-plugin/skills/agent-cli-dev → agent_cli-0.87.0/agent_cli/dev/skill}/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