fix(integrations): stop dispatching workflow steps to SHAI

[kartsan03]

Description

A workflow command or prompt step with integration: shai reports success without running the command. ShaiIntegration inherits MarkdownIntegration.build_exec_args(), so the step runs shai -p "/speckit.plan". The SHAI CLI (ovh/shai, latest release v0.1.11) has no -p or --model flag: shai-cli/src/main.rs collects every argument as free text (trailing_var_arg = true, allow_hyphen_values = true) for its auto-fix mode. SHAI then gives that agent the literal text -p /speckit.plan against its default provider, and it exits 0 even when the model call fails. The step is marked completed and the workflow moves on.

No argv can make this work. SHAI reads headless prompts only from stdin (echo "..." | shai), and it never loads .shai/commands: its only slash commands are the built-in /exit, /auth, /tc, /tokens and /theme. So this opts SHAI out of CLI dispatch, and those steps now fail through the same path as any integration without dispatch. SHAI is one of the unverified integrations listed in #2416.

• ShaiIntegration.build_exec_args() returns None, with a comment pointing at the upstream parser.
• The command and prompt steps said "CLI not found or not installed" whenever dispatch was unavailable, which is wrong when the CLI is on PATH. Both messages now also name the other cause: the integration does not support CLI dispatch.
• The SHAI row in docs/reference/integrations.md notes that workflow steps can't run through it.

Reproduction on current main with the SHAI v0.1.11 release binary on PATH, in a project initialized with --integration shai, run offline (unshare -rn) so nothing reaches a provider:

schema_version: "1.0"
workflow:
  id: "shai-plan"
  name: "SHAI plan"
  version: "1.0.0"

steps:
  - id: plan
    command: speckit.plan
    integration: shai
  - id: after
    type: shell
    run: echo "workflow continued past the plan step"

specify workflow run shai-plan.yml on main:

  ▸ [plan] speckit.plan …
░ gpt-oss-120b on ovhcloud
● Error: LLM error: error sending request
  ▸ [after] shell …
Status: completed

With this change:

  ▸ [plan] speckit.plan …
Status: failed
Error: Cannot dispatch command 'speckit.plan': integration 'shai' CLI not found
or not installed, or the integration does not support CLI dispatch. Install the
CLI tool or check 'specify integration list'.

Online, the same main run sent -p /speckit.plan to SHAI's default OVHcloud model, which treated it as a failed shell command to diagnose. Making SHAI work for these steps would need stdin support in step dispatch, and it still wouldn't have the Spec Kit commands, so that's out of scope here.

Testing

• Tested locally with uv run specify --help

• Ran existing tests with uv sync && uv run pytest

• Tested with a sample project (if applicable)

• New tests in tests/integrations/test_integration_shai.py: build_exec_args() returns None, and a command step and a prompt step fail without calling subprocess.run while shai is on PATH. All three fail on main, where both steps come back completed.

• Full suite: 8763 passed, 251 skipped (Linux, Python 3.13)

• uvx ruff@0.15.0 check src tests: clean. markdownlint on the changed doc: clean.

• Sample project: the workflow above against main and this branch, SHAI v0.1.11.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (fill in the disclosure below)

AI disclosure: Claude Code (Claude Opus 5.5, xhigh reasoning effort, autonomous agent mode) was used to investigate the SHAI CLI, write the code change, the regression tests and this description.

[Copilot]

Copilot review overview

🟢 Approval recommended

The dispatch fix has regression coverage; the remaining issue is a minor inaccuracy in its explanatory wording.

Review effort: Balanced
Findings: 1

Open (1)

• Clarify SHAI argv prompt support versus disabled command dispatch · New

What changed in this PR

This PR prevents SHAI workflow steps from reporting success when they have not run a Spec Kit command.

Changes:

• Opts SHAI out of workflow CLI dispatch.
• Clarifies dispatch-failure messages and adds command and prompt regression tests.
• Documents the workflow limitation.

File	Description
tests/​integrations/​test_integration_shai.py	Tests that SHAI command and prompt steps fail without launching the CLI.
src/​specify_cli/​workflows/​step/​prompt/​__init__.py	Clarifies the prompt dispatch error.
src/​specify_cli/​workflows/​step/​command/​__init__.py	Clarifies the command dispatch error.
src/​specify_cli/​integrations/​shai/​__init__.py	Disables SHAI CLI dispatch.
docs/​reference/​integrations.md	Notes the workflow limitation.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mnriem]

Please address Copilot feedback

[kartsan03]

Addressed in b5512b0. Copilot is right that "no argv form" was wrong: SHAI v0.1.11 takes headless prompt text as positional arguments, on stdin, and through shai agent <name> <prompt>.

Dispatch still has to stay off because of where that text goes. In shai-cli/src/main.rs, every one of those routes calls handle_fix, which is SHAI's auto-fix agent. Nothing in the SHAI source loads .shai/commands, so no route runs an installed Spec Kit command. The code comment, the TestShaiCliDispatch docstring and the SHAI row in docs/reference/integrations.md now say that.

Behavior is unchanged. The SHAI tests pass and ruff check src tests is clean.

---

Drafted on behalf of @kartsan03 by Claude Code (model: claude-opus-5-5, autonomous). The agent checked Copilot's claim against the SHAI v0.1.11 source, made the change and wrote this comment.

[Copilot]

Copilot review overview

🟡 Changes recommended

The command-step error still recommends actions that cannot resolve SHAI’s unsupported-dispatch case.

Review effort: Balanced
Findings: 1

Open (1)

• Unsupported dispatch error gives incorrect remediation guidance · New

Resolved since last review (1)

• Clarify SHAI argv prompt support versus disabled command dispatch

[kartsan03]

Addressed in f059551. The step can't tell the two cases apart: _try_dispatch() returns None both when the executable is missing and when the integration returns no argv. So both step errors now give a separate remedy for each case. If the CLI is missing, install it (the command step also keeps specify integration list). If the integration does not support CLI dispatch, set the step's integration to one that does. The prompt step had no remedy before, so it gets the same two. The SHAI step tests now also check for the second remedy.

tests/test_workflows.py and the SHAI tests pass, and ruff check src tests is clean.

---

Drafted on behalf of @kartsan03 by Claude Code (model: claude-opus-5-5, autonomous). The agent made the change and wrote this comment.

[Copilot]

Copilot review overview

🟢 Approval recommended

The dispatch change and regression tests address the reported false success; the remaining feedback is a minor wording fix.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Unsupported dispatch error gives incorrect remediation guidance

Previously missed (1)

In code that hasn't changed since last review

Fix subject-verb agreement for prompt routes

tests/​integrations/​test_integration_shai.py:24

The subject and verb do not agree in “Its argument, stdin and ... routes all hand,” making the three prompt routes hard to read. Name the routes as the subject and use “all pass.”

[mnriem]

Please address the previously missed Copilot feedback