Skip to content

💫 Toolkit to help you get started with SDD or any other process!

fix(kiro-cli): replace literal $ARGUMENTS with prose fallback (#2482)

Eldar Shlomicba00ab9a5f3
diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md
index d41119a98..ec6c89465 100644
--- a/docs/reference/integrations.md
+++ b/docs/reference/integrations.md
@@ -23,7 +23,7 @@ The Specify CLI supports a wide range of AI coding agents. When you run `specify
| [Junie](https://junie.jetbrains.com/) | `junie` | |
| [Kilo Code](https://github.com/Kilo-Org/kilocode) | `kilocode` | |
| [Kimi Code](https://code.kimi.com/) | `kimi` | Skills-based integration; supports `--migrate-legacy` for dotted→hyphenated directory migration |
-| [Kiro CLI](https://kiro.dev/docs/cli/) | `kiro-cli` | Alias: `--integration kiro` |
+| [Kiro CLI](https://kiro.dev/docs/cli/) | `kiro-cli` | Kiro CLI does not substitute `$ARGUMENTS` in file-based prompts, so Spec Kit ships a prose fallback at render time (see [Manage prompts](https://kiro.dev/docs/cli/chat/manage-prompts/) and issue [#1926](https://github.com/github/spec-kit/issues/1926)). Alias: `--integration kiro` |
| [Lingma](https://lingma.aliyun.com/) | `lingma` | Skills-based integration; skills are installed automatically |
| [Mistral Vibe](https://github.com/mistralai/mistral-vibe) | `vibe` | |
| [opencode](https://opencode.ai/) | `opencode` | |
diff --git a/src/specify_cli/integrations/kiro_cli/__init__.py b/src/specify_cli/integrations/kiro_cli/__init__.py
index b316cb4bd..4571b54f9 100644
--- a/src/specify_cli/integrations/kiro_cli/__init__.py
+++ b/src/specify_cli/integrations/kiro_cli/__init__.py
@@ -3,6 +3,14 @@
from ..base import MarkdownIntegration
+# Kiro CLI file-based prompts do NOT support any argument-substitution syntax,
+# so a raw "$ARGUMENTS" token would reach the model verbatim and break the
+# prompt (issue #1926, kirodotdev/Kiro#4141). Use a prose fallback so the
+# rendered prompt instructs the model to take its argument from the user's
+# next message.
+_KIRO_ARG_FALLBACK = "(the user will provide the argument in this conversation)"
+
+
class KiroCliIntegration(MarkdownIntegration):
key = "kiro-cli"
config = {
@@ -15,7 +23,7 @@ class KiroCliIntegration(MarkdownIntegration):
registrar_config = {
"dir": ".kiro/prompts",
"format": "markdown",
- "args": "$ARGUMENTS",
+ "args": _KIRO_ARG_FALLBACK,
"extension": ".md",
}
context_file = "AGENTS.md"
diff --git a/tests/integrations/test_integration_kiro_cli.py b/tests/integrations/test_integration_kiro_cli.py
index e3b260bf0..9b0b23da0 100644
--- a/tests/integrations/test_integration_kiro_cli.py
+++ b/tests/integrations/test_integration_kiro_cli.py
@@ -1,10 +1,41 @@
"""Tests for KiroCliIntegration."""
import os
+import re
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.kiro_cli import _KIRO_ARG_FALLBACK
+from specify_cli.integrations.manifest import IntegrationManifest
from .test_integration_base_markdown import MarkdownIntegrationTests
+# Regex shapes that indicate a value is a placeholder token, not prose.
+# Covers Bash ($VAR, ${VAR}, ${VAR:-default}), Mustache/Handlebars/Jinja
+# ({{var}}, {{{var}}}), Liquid/Jinja control ({% ... %}), Python str.format /
+# .NET ({var}, {0}), angle-bracket (<var>), and Windows-style (%VAR%).
+# Anchored to the FULL STRING so legitimate prose mentioning a placeholder
+# (e.g. "the {{magic}} of placeholders") is not flagged. The Liquid pattern
+# is anchored to the START so multi-tag templates fire while mid-sentence
+# {%-quotation does not.
+_PLACEHOLDER_TOKEN_PATTERNS = (
+ re.compile(r"^\$\w+$"), # $ARGUMENTS, $args
+ re.compile(r"^\$\{\w+(?:[:\-+?][^}]*)?\}$"), # ${ARGS}, ${ARGS:-default}
+ re.compile(r"^\{\{\{?\s*\w+(\s*[|.][^}]*)?\s*\}?\}\}$"), # {{var}} {{{var}}} {{x|y}}
+ re.compile(r"^\{%"), # {% if x %}{{ x }}{% endif %}
+ re.compile(r"^<\w+>$"), # <args>
+ re.compile(r"^%\w+%$"), # %USERNAME%
+ re.compile(r"^\{(?:\d+|[a-zA-Z_]\w*)(?:[.\[][^}]*)?(?:![rsa])?(?::[^}]*)?\}$"), # {0}, {var}, {0:>5}
+)
+
+
+def _looks_like_placeholder_token(value: str) -> bool:
+ """Return True if *value* matches a known placeholder-token shape."""
+ if not value:
+ return False
+ return any(p.search(value) for p in _PLACEHOLDER_TOKEN_PATTERNS)
+
+
class TestKiroCliIntegration(MarkdownIntegrationTests):
KEY = "kiro-cli"
FOLDER = ".kiro/"
@@ -12,6 +43,85 @@ class TestKiroCliIntegration(MarkdownIntegrationTests):
REGISTRAR_DIR = ".kiro/prompts"
CONTEXT_FILE = "AGENTS.md"
+ def test_registrar_config(self):
+ """Override base assertion: kiro-cli uses a prose fallback for args
+ because Kiro CLI file-based prompts do not natively substitute
+ ``$ARGUMENTS`` (see issue #1926 / kirodotdev/Kiro#4141). The
+ regression-guard load is carried by the two layer tests below
+ (exact-fallback + placeholder-shape rejection)."""
+ i = get_integration(self.KEY)
+ assert i.registrar_config["dir"] == self.REGISTRAR_DIR
+ assert i.registrar_config["format"] == "markdown"
+ assert i.registrar_config["extension"] == ".md"
+
+ def test_registrar_config_args_is_exact_prose_fallback(self):
+ """Layer 1 — pin the exact fallback so wording drift requires a
+ deliberate paired commit (production constant + test update)."""
+ i = get_integration(self.KEY)
+ assert i.registrar_config["args"] == _KIRO_ARG_FALLBACK, (
+ f"args drifted from the pinned fallback constant. "
+ f"Got: {i.registrar_config['args']!r}; expected: {_KIRO_ARG_FALLBACK!r}. "
+ f"If the wording change is intentional, update _KIRO_ARG_FALLBACK and "
+ f"this test together."
+ )
+
+ def test_registrar_config_args_does_not_look_like_a_placeholder_token(self):
+ """Layer 2 — independent regression guard: even if someone bypasses
+ layer-1 by changing both constant and test, the value still must not
+ look like ANY placeholder token shape ($X, ${X}, {{X}}, <X>, %X%, {0},
+ {% %}). Catches the class of regression Copilot called out: a swap
+ from $ARGUMENTS to $INPUT or {{userMessage}} would fail this test
+ even if it accidentally passed layer 1."""
+ i = get_integration(self.KEY)
+ args = i.registrar_config["args"]
+ assert not _looks_like_placeholder_token(args), (
+ f"registrar_config['args'] = {args!r} matches a known placeholder-"
+ f"token shape — Kiro CLI does not substitute placeholders so this "
+ f"would reach the model verbatim and break the prompt (issue #1926). "
+ f"Use a prose fallback instead."
+ )
+
+ def test_rendered_prompts_do_not_contain_raw_arguments(self, tmp_path):
+ """Rendered Kiro prompt files must NOT contain the raw ``$ARGUMENTS``
+ token — Kiro CLI does not substitute it, so the literal would reach
+ the model and break the prompt (issue #1926)."""
+ integration = get_integration(self.KEY)
+ manifest = IntegrationManifest(self.KEY, tmp_path)
+ integration.setup(tmp_path, manifest, script_type="sh")
+
+ prompts_dir = tmp_path / self.REGISTRAR_DIR
+ rendered = list(prompts_dir.glob("*.md"))
+ assert rendered, "expected at least one rendered prompt file"
+
+ offenders = [
+ p.name for p in rendered if "$ARGUMENTS" in p.read_text(encoding="utf-8")
+ ]
+ assert offenders == [], (
+ f"these rendered prompts still contain the raw $ARGUMENTS token: {offenders}"
+ )
+
+ def test_rendered_prompts_contain_kiro_arg_placeholder(self, tmp_path):
+ """The chosen kiro-cli args fallback string must end up in at least
+ one rendered prompt (proves substitution actually fired, not just
+ that $ARGUMENTS was removed). Imports the fallback constant directly
+ instead of reading the field back so the test stays independent of
+ the integration's own config — even if the registrar_config['args']
+ regresses, this test still verifies the FALLBACK STRING is in the
+ rendered output."""
+ integration = get_integration(self.KEY)
+ manifest = IntegrationManifest(self.KEY, tmp_path)
+ integration.setup(tmp_path, manifest, script_type="sh")
+
+ expected = _KIRO_ARG_FALLBACK
+ prompts_dir = tmp_path / self.REGISTRAR_DIR
+ contents = "\n".join(
+ p.read_text(encoding="utf-8") for p in prompts_dir.glob("*.md")
+ )
+ assert expected in contents, (
+ f"none of the rendered prompts contain the configured args fallback "
+ f"({expected!r})"
+ )
+
class TestKiroAlias:
"""--ai kiro alias normalizes to kiro-cli and auto-promotes."""