fix(cli): add agents plan start alias for v3 plan execute command

Add agents plan start as an alias command that delegates to
agents plan execute. This improves discoverability of the v3
plan execution workflow by providing a more natural command name.

Features:
- plan.py: new start_plan_alias() function with proper docstring
- Updated docstring command table to include 'start' entry
- CHANGELOG.md: Entry under [Unreleased]/Fixed section
- CONTRIBUTORS.md: Contribution entry for this feature
- specification.md: CLI summary and alias info documentation
- BDD tests: plan_start_alias.feature with 5 scenarios
- Test step definitions in plan_start_alias_steps.py
- Updated v3_only_steps to include 'start' in command list

ISSUES CLOSED: #8661

CHANGELOG.md

@@ -7,6 +7,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Fixed
 
+- **`agents plan start` alias for `plan execute`** (#8661): Added ``agents plan start`` as an alias command that delegates to ``agents plan execute``. Users can now invoke ``agents plan start <PLAN_ID>`` or ``agents plan start`` (auto-discover) for the same effect as the longer ``agents plan execute``. Includes BDD test coverage and specification documentation updates.
 - **Cross-actor subgraph cycle detection reads actor_ref field** (#1431): Fixed
   `_detect_subgraph_cycles()`, `_map_node()`, and the `compile_actor()` main loop
   in `src/cleveragents/actor/compiler.py` to read `actor_ref` from the top-level

CONTRIBUTORS.md

@@ -21,6 +21,8 @@ Below are some of the specific details of various contributions.
 * HAL 9000 has contributed the plugin entry point security hardening fix (#7476): enforced entry point allowlist validation before importing plugin modules to prevent malicious plugin loading.
 * HAL 9000 has contributed the benchmark workflow separation (#9040): moved the benchmark-regression job out of the default PR workflow into a dedicated scheduled workflow, reducing median PR CI turnaround time from 99-132 minutes to under 30 minutes.
 * HAL 9000 has contributed the agent-evolution-pool-supervisor PR metadata assignment (#7888): the supervisor now automatically looks up the Type/Automation label and earliest open milestone before dispatching improvement PR creation workers, ensuring all generated improvement PRs have correct Type labels and milestone assignments.
+* HAL 9000 has contributed the ``agents plan start`` alias command (PR #8661): added CLI alias that delegates to ``agents plan execute``. This improves discoverability of the v3 plan execution workflow and completes specification alignment between commands and documentation. Includes BDD test coverage.
+
 * This project was made possible thanks to considerable donation of time, money, and resources by CleverThis, Inc.
 * HAL 9000 has contributed automated bug fixes, CLI output formatting improvements, and ongoing maintenance as part of the CleverAgents automation system.
 * HAL 9000 has contributed the file edit encoding parameter fix (PR #8258 / issue #7559).

docs/specification.md

@@ -333,6 +333,7 @@ The following standards are integrated into the architecture:
                 [<span style="color: cyan;">--arg</span>/<span style="color: yellow;">-a</span> name=value]...
                 <span style="color: #66cc66;">&lt;ACTION&gt;</span> <span style="color: #66cc66;">&lt;PROJECT&gt;</span>...
 <span style="color: cyan; font-weight: 600;">agents</span> plan execute <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span>
+<span style="color: cyan; font-weight: 600;">agents</span> plan start <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span><span style="color: #5599ff;" title="alias for agents plan execute"> (alias)</span>
 <span style="color: cyan; font-weight: 600;">agents</span> plan apply [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span>
 <span style="color: cyan; font-weight: 600;">agents</span> plan status <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span>
 <span style="color: cyan; font-weight: 600;">agents</span> plan cancel [(<span style="color: magenta;"><span style="color: cyan;">--reason</span>|<span style="color: yellow;">-r</span></span>) <span style="color: #66cc66;">&lt;REASON&gt;</span>] <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span>
@@ -12659,7 +12660,7 @@ All actor arguments (`--strategy-actor`, `--execution-actor`, `--estimation-acto
     ╰─────────────────────────────────╯
 
     ╭─ Next Steps ─────────────────────────────────────╮
-    │ - agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
+    │ - <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">plan start</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> / <span style="color: cyan; font-weight: 600;">agents plan execute</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> │
     │ - agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J  │
     │ - agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J    │
     ╰──────────────────────────────────────────────────╯
@@ -12702,7 +12703,7 @@ All actor arguments (`--strategy-actor`, `--execution-actor`, `--estimation-acto
       Hot Token Budget: 12,000
 
     Next Steps
-      - agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+      - <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">plan start</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> / <span style="color: cyan; font-weight: 600;">agents plan execute</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span>
       - agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J
       - agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J
 
@@ -12744,7 +12745,7 @@ All actor arguments (`--strategy-actor`, `--execution-actor`, `--estimation-acto
           "hot_token_budget": 12000
         },
         "next_steps": [
-          "agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J",
+          "<span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">plan start</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> / <span style="color: cyan; font-weight: 600;">agents plan execute</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span>",
           "agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J",
           "agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
         ]
@@ -12784,7 +12785,7 @@ All actor arguments (`--strategy-actor`, `--execution-actor`, `--estimation-acto
         view: strategize
         hot_token_budget: 12000
       next_steps:
-        - "agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
+        - "<span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">plan start</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> / <span style="color: cyan; font-weight: 600;">agents plan execute</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span>"
         - "agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
         - "agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
     timing:
@@ -13032,6 +13033,12 @@ Using an action with custom actor overrides:
 
 ##### agents plan execute
 
+!!! info "Alias"
+    ``agents plan start`` is an alias for ``agents plan execute``. Both commands detect the plan's current phase and process it:
+    - **Strategize/queued**: runs the strategize phase to completion.
+    - **Strategize/complete**: transitions to Execute and runs it.
+
+
 <div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan execute <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span></code></pre></div>
 
 **Purpose**
@@ -13085,7 +13092,7 @@ Start or resume execution for a plan.
 === "Plain"
 
     ```
-    $ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+    $ <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">plan start</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> / <span style="color: cyan; font-weight: 600;">agents plan execute</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span>
 
     Execution
       Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
@@ -14326,7 +14333,7 @@ Status of a plan that encountered an error:
 
     ╭─ Recovery ───────────────────────────────────────────╮
     │ - Resolve credentials                                │
-    │ - Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
+    │ - Run <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">plan start</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> / <span style="color: cyan; font-weight: 600;">agents plan execute</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> │
     ╰──────────────────────────────────────────────────────╯
 
     <span style="color: #66cc66; font-weight: 600;">✓ OK</span> Plan cancelled
@@ -14356,7 +14363,7 @@ Status of a plan that encountered an error:
 
     Recovery
       - Resolve credentials
-      - Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+      - Run <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">plan start</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> / <span style="color: cyan; font-weight: 600;">agents plan execute</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span>
 
     [OK] Plan cancelled
     ```
@@ -14386,7 +14393,7 @@ Status of a plan that encountered an error:
         },
         "recovery": [
           "Resolve credentials",
-          "Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
+          "Run <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">plan start</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> / <span style="color: cyan; font-weight: 600;">agents plan execute</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span>"
         ]
       },
       "timing": {
@@ -14419,7 +14426,7 @@ Status of a plan that encountered an error:
         artifacts_preserved: true
       recovery:
         - "Resolve credentials"
-        - "Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
+        - "Run <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">plan start</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> / <span style="color: cyan; font-weight: 600;">agents plan execute</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span>"
     timing:
       started: "2026-02-08T13:02:15Z"
       duration_ms: 340
@@ -15965,7 +15972,7 @@ Show error decisions with recovery hints and retry history for a plan.
     │                                                                    │
     │ <span style="color: cyan; font-weight: 600;">Recovery Suggestions:</span>                                             │
     │   → Check sandbox permissions and retry execution                  │
-    │     <span style="opacity: 0.7;">$ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J</span>              │
+    │     <span style="opacity: 0.7;">$ <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">plan start</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> / <span style="color: cyan; font-weight: 600;">agents plan execute</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span></span>              │
     │   → Revert to Strategize phase to adjust the plan                  │
     │     <span style="opacity: 0.7;">$ agents plan correct --mode revert -g "..." &lt;DECISION_ID&gt;</span>     │
     ╰────────────────────────────────────────────────────────────────────╯
@@ -15990,7 +15997,7 @@ Show error decisions with recovery hints and retry history for a plan.
 
     Recovery Suggestions
       → Check sandbox permissions and retry execution
-        $ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+        $ <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">plan start</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> / <span style="color: cyan; font-weight: 600;">agents plan execute</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span>
       → Revert to Strategize phase to adjust the plan
         $ agents plan correct --mode revert -g "..." <DECISION_ID>
 
@@ -16014,7 +16021,7 @@ Show error decisions with recovery hints and retry history for a plan.
         {
           "action": "retry",
           "message": "Check sandbox permissions and retry execution",
-          "cli_command": "agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
+          "cli_command": "<span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">plan start</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span> / <span style="color: cyan; font-weight: 600;">agents plan execute</span> <span style="color: #66cc66;">&lt;PLAN_ID&gt;</span>"
         },
         {
           "action": "revert",

features/plan_start_alias.feature

@@ -0,0 +1,28 @@
+Feature: Plan CLI supports "start" alias for execute command
+
+    The ``agents plan start`` command provides a more natural alias for
+    ``agents plan execute``, supporting the same parameters and behavior.
+
+    Background:
+        Given CLI environment is ready for plan command tests
+
+    Scenario: Help output shows "start" as a plan command
+        When I invoke "--help" on plan app
+        Then the help contains "start"
+
+    Scenario: Start command delegates to execute functionality  
+        When I invoke "start --help" on plan app
+        Then the command succeeds with exit code zero
+        And the help output should contain "execute" or "alias"
+
+    Scenario: Start command accepts plan ID argument
+        When I invoke "start 01HXM8C2ZK4Q7C2B3F2R4VYV6J --help" on plan app
+        Then the command succeeds with exit code zero
+
+    Scenario: Start command accepts format option
+        When I invoke "start --format json --help" on plan app
+        Then the command succeeds with exit code zero
+
+    Scenario: Start command shows correct help text  
+        When I invoke "start --help" on plan app
+        Then the output contains "execute" or "delegate" or "alias"

features/steps/plan_cli_v3_only_steps.py

@@ -181,6 +181,7 @@ def step_help_output_complete(context: Context) -> None:
         "artifacts",
         "errors",
     ]
+        "start",
     found_commands = []
     for cmd in v3_commands:
         if cmd in context.help_output:

features/steps/plan_start_alias_steps.py

@@ -0,0 +1,75 @@
+"""Step definitions for plan_start_alias.feature.
+
+Tests that verify the ``agents plan start`` alias command works correctly,
+delegating to ``agents plan execute`` behavior.
+"""
+
+from __future__ import annotations
+
+from behave import given, then, when
+from behave.runner import Context
+from typer.testing import CliRunner
+
+
+def _get_plan_app():
+    """Lazy import of plan app to avoid CLI registration at import time."""
+    from cleveragents.cli.commands.plan import app as plan_app
+    
+    return plan_app
+
+
+@given("CLI environment is ready for plan command tests")
+def step_setup_cli_env(context: Context) -> None:
+    """Initialize CLI test environment."""
+    context.runner = CliRunner()
+    context.help_output = None
+    context.last_exit_code = None
+
+
+@when('I invoke "{command}" on plan app')
+def step_invoke_cli_command(context: Context, command: str) -> None:
+    """Execute a CLI command and capture output."""
+    plan_app = _get_plan_app()
+    parts = command.split() if command else []
+    result = context.runner.invoke(plan_app, parts)
+    context.help_output = result.output
+    context.last_exit_code = result.exit_code
+
+
+@then('the help contains "{text}"')  
+def step_help_contains(context: Context, text: str) -> None:
+    """Verify that help output contains specific text."""
+    assert context.help_output is not None, "No help output available"
+    assert text in context.help_output, (
+        f"Expected '{text}' in output.\nOutput:\n{context.help_output}"
+    )
+
+
+@then("the command succeeds with exit code zero")
+def step_command_succeeds(context: Context) -> None:
+    """Verify that the command succeeded (exit code 0)."""
+    assert context.last_exit_code is not None, "No command result available"
+    assert context.last_exit_code == 0, (
+        f"Expected exit code 0, got {context.last_exit_code}\n"
+        f"Output:\n{context.help_output}"
+    )
+
+
+@then('the output contains "{text}"')
+def step_output_contains_or(context: Context, text: str) -> None:
+    """Verify output contains specific text (supports 'or' clause)."""
+    assert context.help_output is not None, "No output available"
+    parts = text.split(" or ")
+    assert any(p in context.help_output for p in parts), (
+        f"Expected one of {parts} in output.\nOutput:\n{context.help_output}"
+    )
+
+
+@then('the help output should contain "{text}"')
+def step_help_contains_or(context: Context, text: str) -> None:
+    """Verify help contains specific text (supports 'or' clause)."""
+    assert context.help_output is not None, "No help output available"
+    parts = text.split(" or ")
+    assert any(p in context.help_output for p in parts), (
+        f"Expected one of {parts} in output.\nOutput:\n{context.help_output}"
+    )

src/cleveragents/cli/commands/plan.py

@@ -5,11 +5,14 @@ plan lifecycle.
 
 ## Commands
 
+
+> **New**: ``agents plan start`` is an alias for ``agents plan execute`` (PR #8661).
 | Command                       | Description                             |
 |-------------------------------|-----------------------------------------|
 | ``agents plan use``           | Create plan from action + project(s)    |
 | ``agents plan list``          | List plans with optional filters        |
 | ``agents plan status``        | Show plan status / details              |
+| ``agents plan start``       | Start (execute) the current plan              |
 | ``agents plan execute``       | Run phase-aware plan execution          |
 | ``agents plan apply``         | Transition to Apply phase               |
 | ``agents plan cancel``        | Cancel a non-terminal plan              |
@@ -1871,6 +1874,23 @@ def use_action(
         raise typer.Abort() from e
 
 
+@app.command("start")
+def start_plan_alias(
+    *args: Any,
+    **kwargs: Any,
+) -> None:
+    """Start (execute) the current plan in its next phase.
+
+    This is an alias for ``agents plan execute`` — it detects the plan's
+    current phase and processes it automatically (Strategize → Execute).
+    Equivalent to::
+
+        agents plan execute <PLAN_ID>
+    """
+    # Forward to execute_plan directly; all parameters are identical.
+    execute_plan(*args, **kwargs)
+
+
 @app.command("execute")
 def execute_plan(
     plan_id: Annotated[