fix(integrations): dispatch kiro-cli headless and install hyphenated prompts - #4798

Pushed 86afed7, which adds the second half of #4797: Kiro prompts are now hyphenated. The assessment on #4797 says the argv change alone is not a complete fix, and I agree. With only 88c9c13, a workflow step sends /speckit.constitution, and Kiro answers that it "is not a built-in Kiro CLI slash command". The step then passes only because the model searches for and reads .kiro/prompts/speckit.constitution.md on its own.

What 86afed7 changes

• Prompts install as .kiro/prompts/speckit-<command>.md, and dispatch sends /speckit-<command>. This follows Junie (Integrate Junie with dot-to-hyphen behavior and command formatting  #4073) and Cline:

  • format_kiro_command_name and the command_filename, build_command_invocation and invoke_separator = "-" overrides, so shared templates and scripts render /speckit-plan.
  • format_name in registrar_config, so extension and preset prompts get the same names. The bundled git extension installs speckit-git-commit.md.
  • The hook note and handoff rewrite. The hook note uses the per-instruction check from fix(cline): stop unrelated prose from suppressing the hook command note #4150, not the older whole-document check.

• This also resolves the Copilot finding. The build_exec_args docstring now says a /speckit-* input runs the prompt file, which is true once the files are hyphenated.

• New tests:

  • the formatter, filenames and invocation;
  • a CommandStep dispatch test asserting the exact Kiro argv with /speckit-constitution;
  • the hook note and handoffs;
  • hyphenated overrides of the base Markdown inventory tests;
  • test_upgrade_replaces_dotted_kiro_prompts.

  12 of these fail with the previous kiro_cli/__init__.py.

• docs/reference/integrations.md: the Kiro row now says prompts are hyphenated and why.

Answers to the assessment's open questions

1. Output format. Workflow command steps call dispatch_command() with the default stream=True, and prompt steps pass output_json=False. So Kiro gets no --output-format and prints text, which the runner streams without parsing. If a caller does ask for JSON, output_json=True maps to --output-format stream-json (JSON Lines), since Kiro has no plain json format.
2. --trust-all-tools. It's always added. Headless Kiro can't ask for approval, so without it every write is denied while the run still exits 0. A workflow step would then report success with nothing written. Copilot's --yolo and Cursor's --force do the same job in their integrations.
3. Migration. specify integration upgrade kiro-cli stale-removes the dotted prompts through the existing manifest contract.
   • I ran it on a project initialized with the code before this PR. Output: "Removed 10 stale file(s) from previous install", and all 10 prompts are now speckit-*.md.
   • If a dotted prompt was modified, the upgrade stops and lists it, and the file stays until --force is used. test_upgrade_replaces_dotted_kiro_prompts covers both cases.
   • Kiro dispatch exited 2 before this PR, so nothing that worked before depended on the dotted names being dispatched.
4. Versions. I tested only Kiro CLI 2.26.0, the current stable download, and added no version gate.

Real run (Kiro CLI 2.26.0, specify workflow run with a speckit.constitution step and a shell step)

• With this commit, Kiro expands the prompt itself. The model's first tool calls are the prompt's own steps: the extensions.yml hook check and resolve-template.sh. It never opens .kiro/prompts, and the run ends Status: completed.
• One limitation is unchanged: headless Kiro drops any text after /speckit-<name>. I tried it on the same line and on the next line, and neither reached the model. So a step's input.args still don't arrive. This is the same Kiro limitation the existing prose fallback covers ([Bug]: $ARGUMENTS placeholder not substituted in Kiro CLI — file-based prompts don't support arguments #1926).

The full suite passes: 8771 passed, 251 skipped. ruff check src tests is clean.

One correction: 88c9c13 is missing the Assisted-by: trailer. The same agent made it, and 86afed7 carries the trailer.

Drafted on behalf of @kartsan03 by Claude Code (model: claude-opus-5-5, autonomous). The agent wrote the code, tests and this comment, and ran the Kiro CLI and upgrade checks above.

I updated the title and description for Copilot's scope finding. They now cover the prompt rename, the integration upgrade migration of the old speckit.*.md files, and the docs row, and they say Fixes #4797 because both halves are in this PR. The code is unchanged since 86afed7.

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

Fixed the Windows pytest failure in cb898ce. The problem was in the test I added, not the Kiro change.

test_upgrade_replaces_dotted_kiro_prompts edits .kiro/prompts/speckit.plan.md to check that upgrade stops on a modified prompt, then restores it. It restored the file with write_text(), which writes CRLF on Windows. write_file_and_record() writes LF bytes, so the restored file no longer matched its manifest hash, and the second upgrade was still blocked. The test now reads and writes the prompt as bytes.

The macOS 3.13 job was cancelled by fail-fast after the Windows failure; it didn't fail itself. The upgrade and Kiro test modules pass locally (75).

Drafted on behalf of @kartsan03 by Claude Code (model: claude-opus-5-5, autonomous). The agent diagnosed the CI failure from the job logs, fixed the test and wrote this comment.

Please address Copilot feedback

Addressed the latest Copilot review in 270f740.

Extension prompts on upgrade. Confirmed and fixed. I initialized a project with the code before this PR and added the bundled git extension, then ran specify integration upgrade kiro-cli on the branch. The 10 core prompts were replaced, but the five speckit.git.*.md prompts stayed beside the new speckit-git-*.md ones. That happened because upgrade only calls _unregister_enabled_extension_commands_for_agent() when the command directory changes. _command_file_names_changed() now also triggers it when the core command files were renamed inside the same directory. unregister_commands() already removes both the formatted name and the raw registered name, so the existing cleanup deletes the dotted files before re-registration. The real upgrade now leaves 15 speckit-*.md prompts and no dotted ones. test_upgrade_replaces_dotted_kiro_prompts now installs the git extension under the old naming and fails without the fix.

Preset prompts. I didn't reproduce a leftover here. With the bundled lean preset installed under the old naming, upgrade --force (the preset overrides make a plain upgrade stop as "modified", same as on main) left the lean content in the hyphenated core prompts and no dotted copies.

--trust-all-tools. The Kiro row in docs/reference/integrations.md now says headless dispatch runs kiro-cli chat --no-interactive --trust-all-tools, which auto-approves every tool call, and why.

The full suite passes: 8771 passed, 251 skipped. ruff check src tests and markdownlint are clean.

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

Please address Copilot feedback

Both findings from the latest Copilot pass are addressed in 569a1bd.

Rename detection. _command_file_names_changed() no longer treats "some files added, some removed" as a rename. It only fires when a removed command file and an added one have the same name once . and - are treated as the same separator, as with speckit.plan.md → speckit-plan.md. A release that adds speckit.new.md and drops speckit.old.md no longer unregisters extension commands. test_command_file_names_changed_needs_a_rename covers the rename case, the add-and-drop case, and an add-only case.

Preset commands. When that rename happens on the active integration, upgrade now calls _unregister_presets_for_agent() before the existing _register_presets_for_agent(), the same pairing switch uses. test_upgrade_replaces_dotted_kiro_prompts now installs a preset with a custom speckit.fakeext.cmd command under the old naming. After the upgrade, it checks that no speckit.*.md prompt is left and that speckit-fakeext-cmd.md has the preset content. Without the change, that test fails with speckit.fakeext.cmd.md still in .kiro/prompts.

tests/specify_cli/integrations, tests/integrations and tests/specify_cli/presets pass (3668 passed, 6 skipped), and ruff is clean on the changed files.

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

Two more fixes in 268a908. The second one is Copilot's finding on 569a1bd; another review pass over the whole PR turned up both:

Disabled presets keep their prompts. The rename path unregistered every preset for the agent, but only enabled ones get re-registered. So integration upgrade kiro-cli deleted a disabled preset's prompt and never put it back, although specify preset disable says registered commands stay until the preset is removed. PresetManager.unregister_agent_artifacts() now has the same enabled_only switch as ExtensionManager's, and upgrade passes enabled_only=True. Covered by test_upgrade_keeps_disabled_preset_kiro_prompts.

Rename check on skill layouts. _command_file_names_changed() compared file names only. In skill layouts every file is SKILL.md, so adding one command and dropping another still looked like a rename. It now compares whole manifest paths, keeping the parent directory as Copilot suggested. There's a new SKILL.md case in test_command_file_names_changed_needs_a_rename.

tests/specify_cli/integrations, tests/integrations, tests/specify_cli/presets and tests/extensions pass (4055 passed, 112 skipped), and ruff check src tests is clean.

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

Please address Copilot feedback

Addressed Copilot's finding on 268a908 in cc91560. I reproduced it: with the git extension's extension.yml and a preset's preset.yml corrupted, specify integration upgrade kiro-cli on 268a908 exited 0 but left neither the dotted nor the hyphenated prompts for either of them, and both registries stopped tracking kiro-cli.

What changed

• For the Kiro rename, upgrade no longer unregisters anything before re-registration. It re-registers enabled extensions and presets as before. Then _retire_renamed_command_files() removes each old speckit.*.md file only when the file under the new name exists. This is the replacement-before-retirement rule from _retire_legacy_flat_extension_commands() and test_upgrade_layout_change_preserves_extension_artifacts_when_reregistration_fails. It still runs only when _command_file_names_changed() finds a real rename, and only for the active integration.
• With nothing unregistered up front, the enabled_only switch that 268a908 added to PresetManager.unregister_agent_artifacts() has no caller. presets/_manager_commands.py is back to main. Disabled extensions and presets aren't re-registered, so they keep their files; test_upgrade_keeps_disabled_preset_kiro_prompts still passes.

Test: test_upgrade_keeps_dotted_kiro_prompts_when_reregistration_fails corrupts both manifests and then upgrades. The dotted git and preset prompts and both registry entries must survive. It fails on 268a908 and passes now.

Real run. The project was made by main with the git extension and a custom preset command, and the upgrade ran offline:

Full suite: 8777 passed, 251 skipped. ruff check src tests (0.15.0) is clean. I also updated the Migration and Upgrade lines in the description.

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

@mnriem Copilot's latest finding is about a preset that can't be re-registered during integration upgrade. main already loses that preset's overrides in the same case. The core-override example it gives is removed by the existing stale cleanup before this code runs. The real-run comparison is in my reply on the thread.

Would you take this PR as it is, with a follow-up PR that keeps a failed preset's overrides when another layer shares the path? Or do you want that in this PR?

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

@kartsan03 Because you are touching shared code it can surface pre-existing bugs and as such I do think we should address those at the time they surface because if we do not it might be hiding other new bugs we might have introduced with the current set of changes. So please address the Copilot feedback. Thanks a lot for workng on this!

Addressed Copilot's finding on cc91560 in f53b21f, per your note. Rather than add more cleanup logic, I reused the guard integration upgrade already has for this class of problem.

What changed

• While presets have commands registered for the integration, upgrade now refuses the Kiro rename before changing any files. It's the same guard as for the Kilo command-root move and the command↔skills layout change (review feat: update Bob integration to skills-based layout for Bob 2.0 #3415). A preset override shares its path with the command it overrides, and its rescaffold is best-effort. If the preset can't be re-registered, Phase 2 stale cleanup (for a core command) or the extension's new file (for an extension command) leaves only the other layer's prompt. The message says to remove the preset, upgrade, and add it back.
• The rename is detected before setup. _command_file_names_changed() now compares the old manifest with _planned_command_files(), the files setup will write.
• Presets no longer reach _retire_renamed_command_files(), so it only handles extension commands. It still removes an old file only once its replacement exists.

Test: test_upgrade_refuses_kiro_prompt_rename_while_presets_are_installed is the regression Copilot asked for. A preset overrides core speckit.plan, its installed source is removed, and upgrade --force must refuse and leave every prompt byte-identical. On cc91560 the upgrade exits 0 and the override is gone. It passes now. The two extension tests now install only the git extension.

Real runs (offline; project made by main with the git extension and a preset overriding speckit.plan and speckit.git.commit):

• Following the message with an intact preset: preset remove, then integration upgrade kiro-cli (no --force needed), then preset add. The result is 15 speckit-*.md prompts with both overrides.
• With only the git extension, all 15 prompts move to speckit-*.md. With its manifest corrupted, its 5 dotted prompts stay and are still tracked.
• The check finds no rename on a fresh install of each of 41 integrations (all but generic, which has no fixed command dir). It also finds none for the 15 integrations with a --skills or --legacy-commands mode, installed in that mode. So the new guard can't block their ordinary upgrades.

Full suite: 8777 passed, 251 skipped. ruff check src tests (0.15.0) is clean. The Migration and Upgrade lines in the description are updated.

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

Please address Copilot feedback

Addressed Copilot's "previously missed" finding on f53b21f in ec15335, but from the other side than it suggested. A kiro fallback in dispatch would make Kiro workflow steps pass without running anything.

Why not fall back to kiro

• Kiro's CLI reference (Kiro Command Router section): "By default, the kiro command launches Kiro IDE." kiro opens the CLI only after kiro-cli integrations install kiro-command-router and kiro set-default cli, while "kiro-cli - Always launches CLI". The router is installed by kiro-cli itself, so a fallback that fires only when kiro-cli is missing would reach the IDE launcher.

• Kiro CLI 2.26.0's Linux package and its installer create kiro-cli, kiro-cli-chat and kiro-cli-term, and no kiro.

• Kiro IDE 1.2.4 (Linux tarball, only its kiro on PATH, offline):

  $ kiro --version
  1.2.4
  22de6f99b82d81a5eb027ac417caa5e395f651a4
  x64
  $ kiro chat --no-interactive --trust-all-tools /speckit-plan
  Warning: 'interactive' is not in the list of known options for subcommand 'chat'
  Warning: 'trust-all-tools' is not in the list of known options for subcommand 'chat'
  exit=0 elapsed=1.14s
  

  kiro chat opens a chat session in the editor (per its --help), and the launcher exits 0, so the step would be marked completed.

What changed

• The mismatch Copilot found was real, so I fixed it on the detection side. check_tool() in src/specify_cli/_utils.py no longer accepts kiro for kiro-cli, so specify check and specify init now agree with both workflow preflights. The kiro alternative came from feat: add kiro-cli and AGENT_CONFIG consistency coverage #1690 ("Kiro currently supports both executable names"), which Kiro's docs don't bear out. An IDE-only setup gets nothing from this integration anyway: Kiro IDE builds its slash commands from steering files, agents and skills, not from .kiro/prompts.
• .devcontainer/post-create.sh checks for kiro-cli only, for the same reason.
• SPECKIT_INTEGRATION_KIRO_CLI_EXECUTABLE=kiro still works as an explicit opt-in for anyone who routes kiro to the CLI.
• Docs: one sentence in the Kiro row.

Tests: test_steps_do_not_dispatch_the_kiro_ide_launcher[command|prompt] puts only kiro on PATH. check_tool reports Kiro CLI missing, both steps fail without running anything, and with the executable override both dispatch kiro chat --no-interactive --trust-all-tools /speckit-plan. test_kiro_fallback is now test_kiro_ide_launcher_is_not_kiro_cli. With src/ reverted, all 3 fail. They pass now.

Windows failure on f53b21f: pytest (windows-latest, 3.14) failed test_unqualified_add_still_uses_current_and_invalid_version_scope with "Integrity check failed for 'history-wf'". That's a flake in the test helper from #4788, not this change. _archive() stamps workflow.yml with the current time, which zip stores at 2-second resolution, and the tests hash one build for the catalog and serve another as the download. #4338 hit the same failure on windows-latest 3.13 today. With zipfile's clock advancing between the two builds, 2 tests in test_catalog_versions.py fail every time. ed42004 pins the entry time, and with that fix they pass under the same clock. It's a separate commit, so it's easy to drop if you'd rather fix it elsewhere.

Full suite: 8779 passed, 251 skipped. ruff check src tests (0.15.0), shellcheck --severity=error and markdownlint are clean. The description now covers detection and the test fix.

Drafted on behalf of @kartsan03 by Claude Code (model: claude-opus-5-5, autonomous). The agent checked Kiro's docs and packages, ran Kiro IDE 1.2.4 locally, made both changes and wrote this comment.

Addressed Copilot's "previously missed" finding on ed42004 in 234bbd2. I reproduced it on a project made by the released 1.0.13 with the git extension, then installed Claude and made it the default, so Kiro was secondary. On ed42004, specify integration upgrade kiro-cli renamed the 10 core prompts but left the 5 speckit.git.*.md prompts, because upgrade re-registers extensions only for the active integration (#2948). integration use kiro-cli or integration switch kiro-cli then wrote the 5 speckit-git-*.md prompts beside them. A later upgrade no longer saw a rename, so the dotted ones stayed for good. An extension that was disabled during the upgrade and enabled later ended up the same way.

What changed

• Kiro now declares its dotted prompts as legacy flat command files (legacy_flat_command_dir = ".kiro/prompts"). ExtensionManager._retire_legacy_flat_extension_commands() retires them, the same step Qoder's skills migration ([bug-fix] Fix qodercli-skills-migration: migrate QodercliIntegration to SkillsIntegration #4205) uses: after a registration pass writes an extension command's new file, it removes the old one. It runs on every pass (use, switch, and upgrade of the active integration), so it no longer depends on the upgrade detecting the rename. It only handles names that pass just wrote and whose replacement exists, so an extension that can't be re-registered keeps its old prompt and its registry entry.
• That step assumed the replacement is a SKILL.md. It now uses the registrar's output path, and it skips a name that is its own replacement. In Kiro a dot-free alias such as speckit-git-c is its own replacement, and without that check its new prompt would be deleted.
• The upgrade-only _retire_renamed_command_files() from cc91560 is removed, so integrations/_helpers.py matches main again. Rename detection now feeds only the preset guard, which also refuses the rename when Kiro is upgraded as a secondary integration.
• I merged main first, because Register extension commands and skills for generic integration #4785 and feat(extensions): select exact catalog releases #4726 changed extensions/__init__.py.

Tests

• test_activating_kiro_after_secondary_upgrade_retires_dotted_prompts (use and switch) and test_enabling_extension_after_kiro_rename_retires_its_dotted_prompts fail on ed42004 (the dotted git prompts remain) and pass now.
• test_kiro_prompt_named_without_dots_is_not_retired fails when the same-path check is removed.
• The existing Kiro migration tests and the Qoder test pass unchanged.

Real runs (offline, project made by 1.0.13 as above):

• Failure path: with the git extension's extension.yml corrupted before use kiro-cli, its 5 dotted prompts stay and the registry still tracks them.
• Presets: with lean registered for Kiro on 1.0.13 and Claude as the default, integration upgrade kiro-cli --force is refused before any file changes. preset remove lean, the upgrade, use kiro-cli and preset add lean then leave 15 speckit-*.md prompts with lean's content.

Full suite: 9046 passed, 250 skipped. ruff check src tests (0.15.0) is clean. The Migration line and the test list in the description are updated.

@mnriem this is ready for another Copilot pass.

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