lukealvoeiro · Oct 18, 2026
diff --git a/docs/cli/droid-exec/overview.mdx b/docs/cli/droid-exec/overview.mdx
@@ -354,12 +354,15 @@ Use `--use-spec` to start in specification mode, where the agent plans before ex
 droid exec --use-spec --auto low "refactor the auth module"
 ```
 
-You can also use a different model for the spec phase:
+You can also use a different model for the spec phase. `--spec-model` enables spec mode on its own (it implies `--use-spec`), so these two commands are equivalent:
 
 ```bash
+droid exec --spec-model claude-haiku-4-5-20251001 --auto medium "implement feature X"
 droid exec --use-spec --spec-model claude-haiku-4-5-20251001 --auto medium "implement feature X"
 ```
 
+`--spec-reasoning-effort` does not enable spec mode by itself; combine it with `--use-spec` or `--spec-model`.
+
 ### Tool controls
 
 List available tools for a model:

diff --git a/docs/jp/cli/droid-exec/overview.mdx b/docs/jp/cli/droid-exec/overview.mdx
@@ -319,10 +319,12 @@ droid exec -m claude-sonnet-4-5-20250929 -r medium -f plan.md
 ```bash
 droid exec --use-spec --auto low "refactor the auth module"
 ```
-仕様フェーズで異なるモデルを使用することもできます：
+仕様フェーズで異なるモデルを使用することもできます。`--spec-model` は単独でspecモードを有効にする（`--use-spec` を含意する）ため、次の2つのコマンドは同じ動作になります：
 ```bash
+droid exec --spec-model claude-haiku-4-5-20251001 --auto medium "implement feature X"
 droid exec --use-spec --spec-model claude-haiku-4-5-20251001 --auto medium "implement feature X"
 ```
+`--spec-reasoning-effort` は単独ではspecモードを有効にしません。`--use-spec` または `--spec-model` と組み合わせて使用してください。
 ### ツール制御
 
 モデルで利用可能なツールを一覧表示する：

diff --git a/docs/jp/reference/cli-reference.mdx b/docs/jp/reference/cli-reference.mdx
@@ -67,8 +67,8 @@ CLIは2つのモードで動作します：
 | `--input-format <format>`            | 入力形式（マルチターン用の`stream-jsonrpc`）                                                               | `droid exec --input-format stream-jsonrpc -o stream-jsonrpc` |
 | `-r, --resume [sessionId]`           | 前回のセッションを再開。インタラクティブモードでは `-r` は `--resume`、`droid exec` では `-r` は `--reasoning-effort` にマッピングされます。 | `droid -r`                                                 |
 | `-r, --reasoning-effort <level>`     | 推論努力レベルを上書き（`off`、`none`、`low`、`medium`、`high`）。`droid exec` では `-r` はこのフラグにマッピングされます。 | `droid exec -r high "debug flaky test"`                    |
-| `--spec-model <id>`                  | 仕様計画に別の[モデルID](/jp/models)を使用                                                              | `droid exec --spec-model claude-opus-4-7`                  |
-| `--spec-reasoning-effort <level>`    | specモードの推論努力を上書き                                                                      | `droid exec --use-spec --spec-reasoning-effort high`       |
+| `--spec-model <id>`                  | specモードで使用するモデル。specモードを有効にし（`--use-spec` を含意）、計画フェーズで使用する[モデルID](/jp/models)を指定 | `droid exec --spec-model claude-opus-4-7 "add user profiles"` |
+| `--spec-reasoning-effort <level>`    | specモードの推論努力を上書き（単独ではspecモードを有効にしません）                                        | `droid exec --use-spec --spec-reasoning-effort high`       |
 | `--use-spec`                         | 仕様モードで開始（実行前に計画）                                                          | `droid exec --use-spec "add user profiles"`                |
 | `--skip-permissions-unsafe`          | すべての許可プロンプトをスキップ（⚠️ 極度に注意して使用）                                                    | `droid exec --skip-permissions-unsafe`                     |
 | `--cwd <path>`                       | 特定の作業ディレクトリから実行                                                                    | `droid exec --cwd ../service "run tests"`                  |

diff --git a/docs/reference/cli-reference.mdx b/docs/reference/cli-reference.mdx
@@ -137,8 +137,8 @@ Customize droid's behavior with command-line flags:
 | `-r, --resume [sessionId]`        | Open the session picker, or resume the specified session directly. In `droid exec`, `-r` is `--reasoning-effort`. | `droid -r`                                                   |
 | `--last`                         | With a bare resume, skip the picker and resume the most recent session in the current folder | `droid --resume --last`                                     |
 | `-r, --reasoning-effort <level>`  | Override reasoning effort (`off`, `none`, `low`, `medium`, `high`). In `droid exec`, `-r` maps to this flag. | `droid exec -r high "debug flaky test"`                      |
-| `--spec-model <id>`               | Use a different [model ID](/models) for specification planning     | `droid exec --spec-model claude-opus-4-7`                    |
-| `--spec-reasoning-effort <level>` | Override reasoning effort for spec mode                            | `droid exec --use-spec --spec-reasoning-effort high`         |
+| `--spec-model <id>`               | Model to use for spec mode; enables spec mode (implies `--use-spec`) and selects the [model ID](/models) for the planning phase | `droid exec --spec-model claude-opus-4-7 "add user profiles"` |
+| `--spec-reasoning-effort <level>` | Override reasoning effort for spec mode (does not enable spec mode on its own) | `droid exec --use-spec --spec-reasoning-effort high`         |
 | `--use-spec`                      | Start in specification mode (plan before executing)                | `droid exec --use-spec "add user profiles"`                  |
 | `--skip-permissions-unsafe`       | Skip all permission prompts (⚠️ use with extreme caution)          | `droid exec --skip-permissions-unsafe`                       |
 | `--cwd <path>`                    | Execute from a specific working directory                          | `droid exec --cwd ../service "run tests"`                    |