Repository navigation
docs(cli): document that --spec-model enables spec mode - #78
Closed
lukealvoeiro wants to merge 1 commit into
Closed
lukealvoeiro wants to merge 1 commit into
lukealvoeiro wants to merge 1 commit into
Conversation
droid exec treats --spec-model as enabling spec mode (implies --use-spec). State this in the CLI reference and the droid exec overview, and note that --spec-reasoning-effort does not enable spec mode on its own. Mirrored in the Japanese pages. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
lukealvoeiro
added
the
cli-args-audit
Contributor
|
Droid finished @lukealvoeiro's task —— View job LGTM. The documentation changes accurately clarify that --spec-model enables spec mode, while --spec-reasoning-effort does not. 0 inline comments posted |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Gap
EXEC-N101 (F, P3).
droid exec --spec-model <id>turns on spec mode by itself, but the docs present it only as a model override and show it only together with--use-spec.Code counterpart (help text): https://github.com/Factory-AI/factory-mono/pull/26964
Evidence
docs/reference/cli-reference.mdx:140"Use a different model ID for specification planning";docs/cli/droid-exec/overview.mdx:357-360shows onlydroid exec --use-spec --spec-model .... JP mirrors:docs/jp/reference/cli-reference.mdx:70,docs/jp/cli/droid-exec/overview.mdx:322-324.apps/cli/src/entrypoints/exec):handler.ts:1113if (options.useSpec || options.specModel)sets spec mode;handler.ts:1359useSpec: options.useSpec || Boolean(options.specModel);oneShotJsonRpcOptions.ts:82;assertValidOptions.ts:260,336,340treatspecModellikeuseSpec.--spec-reasoning-effortdoes not enable spec mode.droid exec --spec-model claude-haiku-4-5-20251001 -s abc 'hi'→Invalid flags: --session-id cannot be used with --use-spec or --spec-model. Spec mode is only supported for new sessions.(exit 1), same as--use-spec -s abc.droid exec --spec-reasoning-effort high -s abc 'hi'does not hit the spec check.droid exec --spec-model custom:Mock-0 --auto low ...refuses file edits with "Spec mode is active".Why it matters
Users who pass only
--spec-modelare surprised when droid plans first instead of executing, and hit spec-only restrictions (no--session-id, no--fork, no mission mode).Fix
--spec-modelis now "Model to use for spec mode; enables spec mode (implies--use-spec) and selects the model ID for the planning phase"; the example includes a prompt.--spec-reasoning-effortnotes it does not enable spec mode on its own.--spec-modelimplies--use-spec, shows the two equivalent commands, and notes--spec-reasoning-effortneeds--use-specor--spec-model.Validation
With the hermetic wrapper, each new or changed example gets past option validation and stops only at the expected auth failure:
droid exec --spec-model claude-opus-4-7 'add user profiles',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'.git show --stat HEADlists only the four intended files. Site rendering not checked.Found by the scheduled CLI arguments audit.