[Bug]: bundled speckit workflow exposes a scope input that has no effect

[mforce]

Bug Description

The bundled speckit workflow declares a required-choice scope input with full, backend-only, and frontend-only values, but no workflow step references {{ inputs.scope }}. All four command steps receive only {{ inputs.spec }}, so every scope choice has identical behavior.

This is present on current main at commit 31e6b84f701b108a848847a8bc9ea86a1e2890b7 in workflows/speckit/workflow.yml.

Steps to Reproduce

1. Initialize a project with Spec Kit 1.0.3.dev0 so the bundled workflow is installed.

2. Inspect .specify/workflows/speckit/workflow.yml.

3. Observe the declared input:

   scope:
     type: string
     default: "full"
     enum: ["full", "backend-only", "frontend-only"]

4. Search its consumers:

   rg -n 'inputs\.scope|inputs\.spec' .specify/workflows/speckit/workflow.yml

5. Optionally run the same specification with each accepted value:

   specify workflow run speckit -i spec="Add an example feature" -i scope=full
   specify workflow run speckit -i spec="Add an example feature" -i scope=backend-only
   specify workflow run speckit -i spec="Add an example feature" -i scope=frontend-only

Expected Behavior

Each exposed input affects workflow execution. Either:

• the selected scope is propagated using a documented command/workflow contract so the three choices behave differently; or
• the unsupported selector is removed from the bundled workflow.

Actual Behavior

scope appears only in its declaration. The specify, plan, tasks, and implement steps all receive the same argument:

input:
  args: "{{ inputs.spec }}"

Users are therefore prompted to choose among three values that do not affect the run.

Specify CLI Version

1.0.3.dev0

AI Agent

Codex CLI

Operating System

Linux 7.2.0 x86_64

Python Version

Python 3.14.5 (Specify CLI runtime)

Error Logs

$ rg -n 'inputs\.scope|inputs\.spec' .specify/workflows/speckit/workflow.yml
48:      args: "{{ inputs.spec }}"
60:      args: "{{ inputs.spec }}"
72:      args: "{{ inputs.spec }}"
78:      args: "{{ inputs.spec }}"

There is no inputs.scope consumer.

Additional Context

The issue was found while reviewing generated Spec Kit tooling in mforce/cluckwork#635. The local correction removes the unsupported selector in commit c70a5ad1 rather than inventing downstream argument semantics.

I searched open and closed issues and PRs using scope, backend-only, frontend-only, bundled workflow, and unused-input terms. Issue #2142 is the closed workflow-engine proposal and includes intended conditional scope routing as an example; it does not report that the shipped bundled workflow leaves the selector unused.

[github-actions]

Bug assessment — scope-input-no-effect: Valid · severity low

---

Bug Assessment: Bundled speckit workflow scope input has no effect

• Slug: scope-input-no-effect
• Created: 2026-09-01T12:10:03Z
• Source: issue [Bug]: bundled speckit workflow exposes a scope input that has no effect #4384
• Verdict: valid
• Severity: low

Report (summarized)

Reported by @mforce. The bundled workflows/speckit/workflow.yml declares a scope input with an enum of ["full", "backend-only", "frontend-only"], but none of the four workflow steps (specify, plan, tasks, implement) reference {{ inputs.scope }} — they all use only {{ inputs.spec }}. The reporter confirmed this at commit 31e6b84f701b108a848847a8bc9ea86a1e2890b7 and found it while reviewing tooling in an external project. Their local fix removes the unused selector.

Symptom

Users are prompted to select a scope value (full, backend-only, frontend-only) when running the speckit workflow, but the choice has no effect — all three scope values result in identical execution. Expected behavior: either the scope input influences the steps, or it is removed.

Reproduction

1. Initialize a project with Spec Kit so the bundled workflow is installed (e.g. specify init my-project).
2. Open .specify/workflows/speckit/workflow.yml.
3. Observe the scope input declared at lines 38–41 with enum: ["full", "backend-only", "frontend-only"].
4. Search for consumers: rg -n 'inputs\.scope' .specify/workflows/speckit/workflow.yml — returns no results.
5. Optionally run the workflow with different scope values and observe identical behavior.

Suspected Code Paths

• workflows/speckit/workflow.yml:38-41 — scope input declaration; the enum is defined here but never consumed.
• workflows/speckit/workflow.yml:44-78 — all four command steps use args: "{{ inputs.spec }}" with no scope forwarding.

Root Cause Hypothesis

The scope input was added to the workflow declaration (likely during a planning phase, referencing a future feature for conditional scope routing — see closed issue #2142) but the downstream argument wiring was never implemented. The step input.args fields were not updated to incorporate {{ inputs.scope }}. Confidence: high — the code is directly visible and unambiguous.

Proposed Remediation

Preferred: Remove the scope input declaration entirely from workflows/speckit/workflow.yml. The downstream commands (speckit.specify, speckit.plan, speckit.tasks, speckit.implement) have no documented contract for accepting or acting on a scope argument, so inventing scope-propagation semantics would be speculative. Removing the dead input is the safe, honest fix — it matches what the workflow actually does and eliminates user confusion.

Alternatives:

• Implement scope routing: Wire {{ inputs.scope }} into each step's args (e.g. args: "{{ inputs.spec }} --scope {{ inputs.scope }}") and update the underlying commands to honor the flag. This is the fuller feature but requires significant additional work and design — not appropriate as a bug fix alone.
• Add a no-op with a comment: Leave the input but add a YAML comment noting it is reserved/unimplemented. This is worse than removal because it still misleads users at runtime.

Files likely to change:

• workflows/speckit/workflow.yml — remove lines 38–41 (the scope input block).

Tests to add or update:

• Add or update a workflow-schema/fixture test asserting the speckit workflow does not declare a scope input (prevents regression of re-adding a dead input).
• If scope routing is later implemented, add a test asserting that each scope value produces a distinct command invocation.

Risks & Considerations

• Low blast radius: removing a dead input is a backward-compatible change for any user who does not pass -i scope=...; users who explicitly pass a scope value today will see it silently ignored either way, so removing the prompt actually improves clarity.
• No data risk, no migration needed: the input is never persisted or consumed.
• Workflow engine behavior: confirm that the workflow engine does not error on unknown inputs passed via -i; if it does, removal is even more important for users who scripted the flag.

Open Questions

• [NEEDS CLARIFICATION: Was scope routing planned as part of a future milestone, or was it an accidental leftover? Checking closed issue Workflow Engine with Catalog System #2142 may confirm intent, but the fix (removal) is valid regardless.]
• [NEEDS CLARIFICATION: Does the workflow engine validate that all declared enum inputs are consumed, or only that supplied values are within the enum? If it validates consumption, this is already a latent engine error.]

Generated by 🐛 Assess Bug from Labeled Issue for issue #4384 · 73.9 AIC · ⌖ 11 AIC · ⊞ 35.7K · ◷

[Yash-Chindam]

Confirmed on main — scope is declared and never referenced. Two corrections to the framing, though, because the actual behaviour is different from (and slightly worse than) what the report describes.

Workflow inputs are never prompted for. The report says users "are prompted to choose among three values", but nothing in the engine reads an input's prompt: field to ask anything. _resolve_inputs only merges provided values with defaults, and the sole interactive input() call in workflows/ is in the gate step, unrelated to input collection. The prompt: key is currently documentation-only metadata — which is also why scope not having one went unnoticed. It is the only declared input without a prompt:, a fair sign it was never finished rather than deliberately hidden.

What actually happens is a silent accept-and-discard. scope is enum-validated on the way in, then dropped. Calling _coerce_input with the declared definition:

-i scope=full           -> ACCEPTED as 'full'
-i scope=backend-only   -> ACCEPTED as 'backend-only'
-i scope=frontend-only  -> ACCEPTED as 'frontend-only'
-i scope=bogus          -> REJECTED: Input 'scope' value 'bogus' not in allowed values: [...]

So a user passing -i scope=backend-only gets positive confirmation the value was understood — a bogus value would have errored — and then all four steps run with {{ inputs.spec }} exactly as before. Being validated and then ignored is more misleading than being ignored outright, since the rejection of bogus is evidence to the user that the flag works.

That makes this a correctness issue about a silently-dropped input rather than a UI annoyance, though I agree severity stays low since the workflow still does the right thing by default.

On the two options in Expected Behavior: removing the input looks clearly right to me as the immediate fix. Propagating scope has no contract to hang it on — the four steps take a single args string, so "backend-only" could only be smuggled in by appending prose to {{ inputs.spec }}, which puts a scoping instruction into the same free-text field the user's description occupies and leaves its interpretation to the agent. That is a feature with a design question attached, not a bug fix. Deleting three lines restores the invariant that every declared input affects the run, and a real scope selector can land later on its own terms.

Worth considering separately: validate_workflow already rejects invalid enum shapes and out-of-enum defaults, but has no check for an input that no step references. A warning there would have caught this at authoring time and would catch the next one.

Happy to open a PR removing the input if that is the direction you want.

Disclosure: I used an AI assistant (Claude) to help investigate and draft this comment. The input-resolution behaviour and the coercion results above were verified against main.

[mnriem]

@Yash-Chindam Feel free to create a PR with a fix

[Yash-Chindam]

PR up: #4398

Removes the input rather than wiring it up, for the reason in the PR: the four steps take a single args string, so a scope could only be smuggled in as prose appended to {{ inputs.spec }} and left to the agent to interpret. That is a feature with a design question attached, not a bug fix — better to restore the invariant now and leave a real scope selector free to land on its own terms.

Also updates workflows/README.md, which demonstrated "Multiple Inputs" using --input scope="backend-only" against this very workflow — documenting the inert input as if it worked. The inputs.scope reference in the If/Then/Else section is a generic authoring example with its own hypothetical workflow, so it stays.

Declared and referenced inputs now match exactly.

Could you assign this issue to me so ownership is clear? Happy to revise on feedback.