feat(workflows): support file-backed inputs

[Adr1an04]

Refs #2405

Summary

This PR adds support for passing workflow inputs from files.

You can still pass inputs inline with repeated --input key=value flags. For longer values, you can now use key=@path, and for multiple values you can use a JSON file with --input-file.

This is handled generically for workflow inputs/parameters, not just for spec.

What changed

• Added CLI-side parsing for workflow inputs.
• Added support for --input key=@path for any workflow input key.
• Added --input-file payload.json to load multiple inputs from a JSON object.
• Made direct --input values override values loaded from --input-file.
• Added clear errors for missing input files, invalid JSON, and non-object JSON.
• Updated the workflow docs with generic examples.

Examples

specify workflow run ./workflow.yml --input prompt=@docs/prompt.md
specify workflow run ./workflow.yml --input-file payload.json
specify workflow run ./workflow.yml --input-file payload.json --input scope=full

Notes

File references are not spec-specific. They work for any workflow input key.

Values starting with @ are only read from a file when that file exists. This keeps literal values like @alice or @ working as normal strings.

--input-file values are loaded first, then direct --input values are applied after that. This lets command-line values override the JSON file.

What did not change

• No changes to WorkflowEngine behavior.
• No new workflow execution semantics.
• Workflow definitions were not made Spec Kit-specific.
• --input-file only accepts a JSON object.
• File-backed --input key=@path values are read as UTF-8 text.

Testing

I ran focused workflow input regression tests:

uv run python -m pytest tests/test_workflows.py -k WorkflowCliInputs -v
# 12 passed, 126 deselected in 0.15s

I also ran the full workflow test file:

uv run python -m pytest tests/test_workflows.py -v
# 138 passed in 0.30s

I used the existing agent config consistency test:

uv run python -m pytest tests/test_agent_config_consistency.py -q
# 24 passed in 0.13s

I ran the full test suite:

uv run python -m pytest -q
# 1833 passed, 29 skipped, 18 warnings in 20.25s

CLI-level validation

I tested the workflow CLI directly in a temporary Spec Kit project.

Covered cases:

• --input key=@path reads an existing UTF-8 text file.
• File references work for generic input keys like prompt and description, not only spec.
• Repeated --input key=value values still work.
• Literal values like @alice and bare @ stay unchanged.
• Missing @path values stay literal.
• --input-file payload.json loads multiple inputs from a JSON object.
• Direct --input values override values loaded from --input-file.
• Direct overrides can also use key=@path.
• Missing --input-file exits cleanly with code 1.
• Invalid JSON exits cleanly with code 1.
• Non-object JSON exits cleanly with code 1.

Smoke test output:

PASS direct file refs and literal @ values
PASS input-file values with CLI override precedence
PASS missing @path remains literal
PASS missing --input-file exits 1
PASS invalid JSON exits 1
PASS non-object JSON exits 1
CLI smoke tests passed

I also checked the command help and confirmed the new CLI options are exposed:

uv run specify workflow run --help
# shows --input / -i with key=@path help
# shows --input-file for JSON object input files

CLI smoke test screenshot showing successful file-backed inputs, JSON input-file overrides, literal `@` handling, and clean error cases for missing/invalid input files.

AI assistance note

I used ChatGPT to help think through edge cases and wording. I wrote, reviewed, and tested the code locally before opening this PR.

[Copilot]

Pull request overview

Adds generic CLI support for providing workflow inputs from files (single values via key=@path and bulk values via --input-file JSON), keeping existing inline --input key=value behavior and defining clear precedence/validation at the CLI boundary.

Changes:

• Added _parse_workflow_inputs (plus helpers) to normalize --input and --input-file into the workflow engine input dict.
• Extended workflow run CLI options with --input-file and --input key=@path semantics (CLI values override file values).
• Added regression tests for parsing/precedence/error cases and updated workflow CLI documentation examples.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
src/specify_cli/__init__.py	Implements file-backed input parsing helpers and wires them into workflow run via new CLI options.
tests/test_workflows.py	Adds targeted tests covering @file inputs, --input-file JSON loading, precedence, and failure modes.
docs/reference/workflows.md	Updates CLI reference docs with the new options and usage examples.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Adr1an04]

@mnriem I handled Copilots feedback and made sure to take into account your message in the issue. Let me know if you need me to edit anything! :D

[Copilot]

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 3/3 changed files
• Comments generated: 0 new