[Bug]: kiro-cli workflow dispatch exits 2, and Kiro doesn't expand dotted /speckit.* prompt names

[kartsan03]

Bug Description

Workflow command and prompt steps with integration: kiro-cli don't work, in two layers. Both are checked against Kiro CLI 2.26.0, the current release.

1. Dispatch argv. KiroCliIntegration inherits MarkdownIntegration.build_exec_args(), so a step runs kiro-cli -p "/speckit.constitution", which Kiro rejects at argument parsing (exit 2). Kiro runs one prompt headless as kiro-cli chat --no-interactive "<prompt>". In that mode it can't ask for tool approval: without --trust-all-tools every write is denied (tool permission approval is not supported in non-interactive mode. Use --trust-all-tools to auto-approve.) and the run still exits 0. Its --output-format takes text or stream-json, not json.

2. Prompt names. Even with that argv, Kiro doesn't expand /speckit.constitution. In headless mode it expands /name from .kiro/prompts/name.md only when the name has no dot:

   Input	File in .kiro/prompts/	Result
   /hello	hello.md	the prompt file runs
   /hello-world	hello-world.md	the prompt file runs
   /hello.world	hello.world.md	"That doesn't look like a recognized slash command."

   @name, the form in Kiro's prompt docs, isn't expanded in headless mode either. Spec Kit installs every Kiro prompt with a dot (speckit.plan.md), so no /speckit.* input reaches its prompt file.

Kiro CLI is one of the integrations listed as unverified in #2416.

Steps to Reproduce

1. specify init kproj --integration kiro-cli --script sh, with Kiro CLI 2.26.0 on PATH and logged in.
2. Add this workflow and run specify workflow run kiro-wf.yml:

schema_version: "1.0"
workflow:
  id: "kiro-constitution"
  name: "Kiro constitution"
  version: "1.0.0"

steps:
  - id: constitution
    command: speckit.constitution
    integration: kiro-cli
  - id: after
    type: shell
    run: echo "workflow continued past the constitution step"

Expected Behavior

The step runs the speckit.constitution prompt through Kiro CLI and the workflow continues.

Actual Behavior

On main:

  ▸ [constitution] speckit.constitution …
error: unexpected argument '-p' found
Usage: kiro-cli [OPTIONS] [COMMAND]
For more information, try '--help'.
Status: failed
Error: Command exited with code 2

With the argv changed to kiro-cli chat --no-interactive --trust-all-tools "/speckit.constitution", the workflow completes, but only because Kiro's model worked around the input:

`/speckit.constitution` is not a built-in Kiro CLI slash command. It's not documented as a built-in command.
...
Found it — it's a prompt at `.kiro/prompts/speckit.constitution.md`. Let me read it.

Specify CLI Version

1.0.14.dev0 (main at 2c0a57a)

AI Agent

Kiro CLI

Operating System

Linux 6.17

Python Version

3.13.15

Error Logs

error: unexpected argument '-p' found

Additional Context

Proposed fix:

• Override build_exec_args() to run kiro-cli chat --no-interactive --trust-all-tools [--model M] [--output-format stream-json] <prompt>. I have this ready with tests.
• Install Kiro prompts under hyphenated names (speckit-plan.md, invoked as /speckit-plan), the way Junie and Cline already format their command names.

The rename changes file names in existing projects, so I'd like to check the direction first: both in one PR, or the argv fix first? I'd also like to be assigned to this and open the PR, if that's okay with you.

Separately, --model is accepted, but in headless mode Kiro prints [warn] failed to set model '...': Method not found and falls back to its default model. That one is on Kiro's side.

AI Disclosure

Claude Code (Claude Opus 5.5, autonomous agent mode) was used to investigate Kiro CLI, run the reproductions and draft this issue.

[github-actions]

Bug assessment — kiro-cli-dispatch: Valid · severity medium

---

Bug Assessment: kiro-cli workflow dispatch exits 2 and dotted prompt names are not expanded

• Slug: kiro-cli-dispatch
• Created: 2026-09-30T13:29:43Z
• Source: issue [Bug]: kiro-cli workflow dispatch exits 2, and Kiro doesn't expand dotted /speckit.* prompt names #4797
• Verdict: valid
• Severity: medium

Report (summarized)

The reporter tested Spec Kit 1.0.14.dev0 (main at 2c0a57a) with Kiro CLI 2.26.0 on Linux. A workflow command step using integration: kiro-cli fails before executing the prompt because the inherited command line includes -p, which Kiro CLI rejects. The proposed alternate invocation (kiro-cli chat --no-interactive --trust-all-tools) runs, but Kiro does not recognize the installed dotted slash-command /speckit.constitution; Kiro's headless prompt expansion expects a name without a dot, matching a file such as .kiro/prompts/hello-world.md and invocation /hello-world.

The report includes a concrete specify init ... --integration kiro-cli setup and workflow reproduction, plus the observed exit-2 error. No additional reproduction comments were available.

Symptom

Kiro CLI workflow dispatch is unusable for the reported path: the default dispatch exits with unexpected argument '-p', while an argv workaround still fails to directly expand Spec Kit's dotted prompt names. Expected behavior is for the Kiro integration to invoke the installed Spec Kit prompt and allow the workflow to continue.

Reproduction

1. Initialize a project with specify init kproj --integration kiro-cli --script sh, with Kiro CLI 2.26.0 on PATH and authenticated.
2. Add a workflow containing a command: speckit.constitution step with integration: kiro-cli, followed by a shell step.
3. Run specify workflow run kiro-wf.yml.
4. Observe error: unexpected argument '-p' found and exit code 2.
5. If the command is manually changed to kiro-cli chat --no-interactive --trust-all-tools "/speckit.constitution", observe that Kiro does not natively expand the dotted prompt name and may only succeed after the model manually locates the prompt file.

The report's Kiro CLI behavior was tested by the reporter; the repository-side code-path analysis below is based on the checked-out source.

Suspected Code Paths

• src/specify_cli/integrations/base.py:1089-1104 — MarkdownIntegration.build_exec_args() constructs [executable, "-p", prompt], then appends --model and --output-format json. This is the inherited implementation used by Kiro and does not match the reported Kiro headless syntax or its supported output formats.
• src/specify_cli/integrations/kiro_cli/__init__.py:14-38 — KiroCliIntegration subclasses MarkdownIntegration but does not override build_exec_args() or build_command_invocation(). Its registration only configures .kiro/prompts and .md output, so both dispatch and invocation retain the markdown-base defaults.
• src/specify_cli/integrations/base.py:352-370 — the inherited build_command_invocation() converts speckit.constitution to /speckit.constitution, preserving the dot separator.
• src/specify_cli/integrations/base.py:548-555 and base.py:979-990 — the default command_filename() emits speckit.<template>.md, and shared Markdown setup uses that hook when copying templates. This matches the report's installed dotted filenames, which Kiro headless prompt expansion reportedly does not recognize.
• tests/integrations/test_integration_kiro_cli.py:111-116 — the current integration test explicitly asserts that speckit.plan.md is created, locking in the filename shape implicated by the report.
• tests/test_workflows.py:1104-1201 — shared dispatch argument tests cover other CLI integrations but have no Kiro-specific argv regression coverage.

Root Cause Hypothesis

Confidence: high. Kiro CLI is currently modeled as a conventional MarkdownIntegration, but its headless CLI contract differs in two independent ways: invocation requires the chat --no-interactive command (and tool auto-approval for write-capable workflows), and prompt lookup uses a hyphenated/no-dot name. Because KiroCliIntegration overrides neither the execution argv builder nor the filename/invocation hooks, it inherits incompatible -p/JSON arguments and dotted prompt names. The report's observation about --model producing a Kiro-side warning is separate and should not be treated as a Spec Kit root cause without additional evidence.

Proposed Remediation

Preferred: Add Kiro-specific dispatch and naming hooks rather than changing MarkdownIntegration globally. Override build_exec_args() in KiroCliIntegration to emit Kiro's supported headless form (kiro-cli chat --no-interactive --trust-all-tools <prompt>), preserve the shared runtime validation and environment extra-argument behavior, and map the requested JSON output mode to a Kiro-supported format or omit it when Kiro cannot provide the workflow's expected machine-readable output. The implementation should explicitly decide how the workflow runner consumes Kiro output before selecting text versus stream-json.

Override command_filename() and build_command_invocation() consistently so installed files and dispatched names use the same Kiro-compatible hyphenated spelling (for example speckit-constitution.md and /speckit-constitution). Treat existing dotted files during upgrade/uninstall carefully: preserve or remove them according to the manifest/stale-file contract, and avoid silently leaving a duplicate command that could confuse users. Update the integration documentation to describe the Kiro-specific layout and headless limitations.

Alternatives:

• Keep dotted files and introduce a Kiro-specific wrapper/manifest mechanism if a future Kiro CLI release adds a reliable way to invoke dotted prompt files. This avoids project-file renames but depends on external CLI behavior that the report says is unsupported.
• Implement only the argv override first. This would remove the immediate exit-2 failure but leave prompt dispatch dependent on model workarounds, so it is not a complete fix.

Files likely to change:

• src/specify_cli/integrations/kiro_cli/__init__.py
• tests/integrations/test_integration_kiro_cli.py
• tests/test_workflows.py (or a Kiro-specific dispatch test module)
• design/integration.md and/or the supported integrations reference, if Kiro-specific behavior is documented there
• Upgrade/manifest tests if filename migration behavior is added

Tests to add or update:

• Assert Kiro dispatch args contain kiro-cli, chat, --no-interactive, and the selected prompt, and do not contain inherited -p or unsupported JSON output arguments.
• Assert model, integration args/options, and environment extra-argument handling follow the repository's standard dispatch contract where Kiro supports them.
• Assert Kiro setup writes the chosen hyphenated filename and command invocation uses the identical spelling.
• Add a regression test that a command or prompt workflow step passes the Kiro-specific invocation to the dispatcher and preserves failure reporting when the subprocess exits nonzero.
• Cover upgrade/uninstall behavior for projects containing the current dotted filenames, if the remediation migrates names.

Risks & Considerations

• --trust-all-tools changes approval behavior and should be documented as an intentional requirement for non-interactive write-capable workflows; verify it is acceptable for the project's execution model.
• The workflow runner may expect structured output when output_json=True; using Kiro text or stream-json without adapting parsing could create a second failure after argv is fixed.
• Renaming installed prompt files affects existing initialized projects and must not delete user-modified files or break manifest-based upgrade safety.
• Kiro CLI behavior is external and versioned; compatibility should be pinned to the supported behavior or covered with clear preflight/error messaging if versions differ.
• The report's Kiro-side --model warning is a separate upstream limitation and should not be silently masked as a successful model selection.

Open Questions

• [NEEDS CLARIFICATION: Which Kiro CLI output format should Spec Kit use, and does the workflow runner require JSON parsing for Kiro command/prompt steps?]
• [NEEDS CLARIFICATION: Should --trust-all-tools always be added by the integration, or be opt-in through integration options/environment settings?]
• [NEEDS CLARIFICATION: What migration policy should apply to existing .kiro/prompts/speckit.*.md files when switching to hyphenated names?]
• [NEEDS CLARIFICATION: Which Kiro CLI versions are supported, and should the integration preflight or gate behavior by version?]

Generated by 🐛 Assess Bug from Labeled Issue for #4797 · copilot · gpt52codex · 1.84 AIC · ⌖ 5.57 AIC · ⊞ 21.8K · ◷