Before opening, please confirm:

• I have searched for duplicate or closed issues

Operating System

windows 11

Kiro Version

1.21.0

Bug Description

Summary

When using Kiro CLI 1.21.0 together with GitHub Spec Kit as a custom agent, saved prompts that take "arguments" only work reliably if the entire chat message is wrapped in single quotes at the shell level.

Without the outer quotes, Kiro either doesn't trigger the saved prompt logic or does not pass the trailing text as $ARGUMENTS to the prompt file. This leads to confusing behavior where the same logical command works in one form but silently fails in another.

This looks like a parsing / argument handling bug in the CLI around @prompt-name usage with additional text.

---

Environment

• Kiro CLI version: 1.21.0
• OS: Windows 11 + WSL2 (Ubuntu, bash)
• Admin settings:
  • MCP is disabled by our Amazon Q / Kiro admin
  • Only local / file-based prompts are allowed
• Project setup:

  • Legacy codebase (existing project, not a new empty repo)

  • Using GitHub Spec Kit as a spec-driven workflow tool

  • Spec Kit initialized via uv:

    uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
    cd /path/to/project
    specify init --here --ai q   # or equivalent Kiro/Amazon Q agent option

  • This generates:

    • .specify/** spec files
    • .amazonq/prompts/speckit.*.md (Spec Kit prompt files)

Note: Although /prompts list often shows nothing, the prompt files are being picked up in practice, as shown in the reproduction below (they successfully update .specify/memory/constitution.md).

---

Reproduction steps

1. In the project root (with .specify and .amazonq/prompts generated by Spec Kit), run "kiro-cli" to start the Kiro CLI chat.

2. Try to call the Spec Kit constitution prompt without wrapping the entire message in quotes:

   @speckit.constitution This is an existing old project, please generate the project constitution based on the current repository, request to maintain compatibility, do not major refactoring
   

   Observed behavior:

   • Kiro does not reliably trigger the speckit.constitution prompt.
   • .specify/memory/constitution.md is not updated as expected.
   • The trailing Chinese text appears to be ignored or not passed as $ARGUMENTS.

3. Now run the same logical command, but wrap the whole message in single quotes at the shell level:

   kiro '@speckit.constitution This is an existing old project, please generate the project constitution based on the current repository, request to maintain compatibility, do not major refactoring '

   or inside the CLI, literally paste:

   '@speckit.constitution This is an existing old project, please generate the project constitution based on the current repository, request to maintain compatibility, do not major refactoring '
   

   Observed behavior:

   • Now @speckit.constitution is recognized correctly.
   • .specify/memory/constitution.md is updated with a generated project constitution.
   • The trailing text is treated as the arguments / instructions to the prompt.

So effectively:

• @speckit.constitution <text> → does not work reliably
• '@speckit.constitution <text>' → works and updates the expected file

From the user’s point of view, this is confusing because Spec Kit’s documentation (and Amazon Q saved prompts docs) suggest that @prompt-name additional text should be valid and that additional text will be passed to the prompt as arguments.

---

Expected behavior

I would expect one of the following to be true and documented:

1. Preferred: Kiro CLI should correctly support:

   @prompt-name additional free-form text
   

   and treat the trailing text as a single $ARGUMENTS string passed to the prompt file, regardless of whether the entire line is wrapped in shell quotes.

2. Or at minimum: If this usage is not supported, the CLI should:

   • Either reject @prompt-name followed by extra tokens with a clear error,
   • Or clearly document that @prompt-name must be used without inline “arguments”, and that additional instructions should be sent as a separate message.

Right now the behavior is:

• It sometimes works when the whole message is quoted.
• It does not work when there are no outer quotes.
• There is no error or warning when it fails, which makes debugging very hard.

---

Why this matters

Spec Kit’s Kiro / Amazon Q integration relies heavily on file-based prompts like:

• speckit.constitution
• speckit.specify
• speckit.plan
• speckit.tasks
• speckit.implement

The recommended flow for legacy projects (“brownfield” codebases) is to:

1. Generate a project constitution (.specify/memory/constitution.md) that encodes constraints like “do not do large-scale refactors” and “keep behavior backward compatible”.
2. Use @speckit.specify / @speckit.plan / @speckit.tasks / @speckit.implement with additional inline instructions to safely add or modify features on top of existing logic.

Right now, because the CLI only behaves correctly when the entire message is wrapped in quotes, this workflow is much more brittle and confusing than it needs to be. From a developer UX perspective, it feels like a parsing bug rather than an intentional limitation.

---

Workaround

Currently, the only reliable workaround I have found is:

• Always wrap the entire command + arguments in single quotes at the shell / CLI level, e.g.:

  kiro '@speckit.constitution This is an existing old project, please generate the project constitution based on the current repository, request to maintain compatibility, do not major refactoring '

This makes the command work, but:

• It is not obvious to new users.
• It is easy to forget.
• It feels like a fragile workaround instead of a first-class, documented behavior.

---

Request

• Could you please confirm whether @prompt-name additional text is meant to be supported syntax in Kiro CLI?

• If yes, this looks like a bug in how the CLI parses and forwards messages (especially under WSL / bash) and it would be great to have a fix.

• If no, could you:

  • Document the limitation clearly,
  • And maybe provide an official pattern for using file-based prompts with “arguments” (e.g. recommended two-message pattern, or an explicit $ARGUMENTS usage example for Kiro)?

I’m happy to provide more logs, run a debug build, or test candidate fixes if that would help.

Steps to Reproduce

See the descriptive information above

Expected Behavior

See the descriptive information above

Conversation ID

No response

Additional Context

No response