[Bug]: kiro-cli workflow dispatch exits 2, and Kiro doesn't expand dotted /speckit.* prompt names · Issue #4797 · github/spec-kit · GitHub
Skip to content

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

Open
#4798
Open
[Bug]: kiro-cli workflow dispatch exits 2, and Kiro doesn't expand dotted /speckit.* prompt names#4797
#4798
Labels
bug-assesstriage-nice-to-haveVerdict: evidence-backed fix or greenlit feature — land after review

Agent suggestions

Public preview

Description

@kartsan03
kartsan03
opened on Sep 30, 2026

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.

Activity

  1. mnriem
    added
    triage-nice-to-haveVerdict: evidence-backed fix or greenlit feature — land after review
    bug-assess
    on Sep 30, 2026

  2. github-actions commented on Sep 30, 2026

    @github-actions
    github-actionsBot
    on Sep 30, 2026 – with GitHub Actions
    Contributor

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

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

    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 · ◷

  3. kartsan03
    added 12 commits that reference this issue on Sep 30, 2026

    fix(integrations): install kiro-cli prompts with hyphenated names

    86afed7

    test(integrations): restore the kiro prompt as bytes in the upgrade test

    cb898ce

    fix(integrations): remove dotted kiro extension prompts on upgrade

    270f740

    fix(integrations): retire dotted Kiro prompts only after their replac…

    cc91560

    fix(integrations): refuse the Kiro prompt rename while presets are in…

    f53b21f

    fix(integrations): stop treating the Kiro IDE launcher as Kiro CLI

    ec15335

    fix(integrations): keep Kiro prompts tracked when a command source is…

    3bcee7e

    fix(integrations): keep Kiro prompts that hyphenate to one file

    62732e8

    fix(integrations): skip Kiro prompts that share a file instead of rew…

    8570f0a

    fix(extensions): count unreadable owners at install, remove skipped Q…

    fdb8d75

    fix(integrations): refuse the Kiro rename when prompt ownership is un…

    cce66b5

    fix(extensions): check the ownership marker before removal deletes a …

    24630bc

  4. 6 remaining items

  5. kartsan03
    added 15 commits that reference this issue on Oct 9, 2026

    fix(extensions): count unreadable owners at install, remove skipped Q…

    e7d15bf

    fix(integrations): refuse the Kiro rename when prompt ownership is un…

    18aca19

    fix(extensions): check the ownership marker before removal deletes a …

    5a22b1b

    fix(extensions): keep unwritten registered names for Kiro CLI and Qod…

    7950bed

    fix(extensions): let a disabled extension's manifest claim its files

    237f781

    fix(extensions): check ownership on every Kiro CLI and Qoder cleanup …

    02c6311

    fix(integrations): detect a pending Kiro rename from the prompts on disk

    8014038

    fix(integrations): ignore dotted Kiro prompts left after the rename

    f77f6ad

    fix(integrations): journal Kiro CLI prompt rewrites like Cline and Junie

    64ebbc8

    fix(extensions): print the unowned prompt path with forward slashes

    5b7a674

    test(integrations): build the dotted Kiro fixture from the integratio…

    5ba189e

    fix(extensions): retire a dropped Kiro CLI or Qoder alias that shares…

    a844c73

    fix(extensions): keep Kiro CLI and Qoder cleanup in the project's con…

    e8bf882

    fix(extensions): load installed integrations before checking every agent

    e9b6a9b

    fix(extensions): keep a prompt that is a symlink loop

    7c446b3
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bug-assesstriage-nice-to-haveVerdict: evidence-backed fix or greenlit feature — land after review

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions