fix(init): only show 'Restart your IDE' hint for IDE-embedded tools

[clay-good]

Status: Merge-ready. Supersedes #1097 (rebased onto current main, conflicts resolved, regression gate verified, hardened). Fixes #1067.

This is a conflict-resolved, hardened continuation of @mvanhorn's #1097 — original authorship is preserved in the commit history. #1097 was opened against an older main and went stale (tool list renamed/expanded, restart-message logic changed).

What was wrong

After openspec init, the success screen always printed "Restart your IDE for slash commands to take effect." — even for CLI tools (Claude Code, Codex, Gemini CLI, …) that have no editor process to restart. Their commands/skills work as soon as the files exist. #1067 reports the confusing always-on message.

How it's fixed

• Adds requiresIdeRestart?: boolean to AIToolOption (src/core/config.ts) and marks the IDE/editor-resident tools.
• Threads the flag through validateTools into the validated tool objects (src/core/init.ts).
• The success screen shows the restart line only when an IDE-resident tool itself received a generated surface, and the wording reflects what that tool generated:

  const restartCommandsGenerated = successfulTools.some(t => t.requiresIdeRestart && shouldGenerateCommandsForTool(t.value, activeDelivery));
  const restartSkillsGenerated   = successfulTools.some(t => t.requiresIdeRestart && shouldGenerateSkillsForTool(t.value, activeDelivery));
  if (restartCommandsGenerated || restartSkillsGenerated) { … }

  This couples "is IDE-resident" and "got a surface" to the same tool, so a CLI tool's output can never trigger the hint for an unrelated IDE tool, and the message can't say "commands" when the IDE tool only got skills.

Tool classification (15 flagged)

IDE/editor-resident (get the hint): Amazon Q, Antigravity, Cline, Continue, CoStrict, Cursor, Devin Desktop (Windsurf), GitHub Copilot, Junie, Kilo Code, Kiro, Lingma, Qoder, Trae, Zoo Code (RooCode).

All terminal-invoked tools are left unflagged (Claude Code, Codex, Gemini CLI, Qwen, Kimi, Crush, OpenCode, Rovo, Hermes, …). Two genuinely dual-surface tools — CodeArts and ZCode — are deliberately left unflagged: under-flagging only costs a missing hint, while over-flagging a CLI tool would reintroduce #1067. Maintainers can flip either with a one-line change.

Merge-resolution notes (vs. original #1097)

• Current main uses a ValidatedInitTool type; the flag was added there and the PR's parallel SelectedTool type was dropped (no dangling refs).
• main had already made the message conditional on generated surfaces and varied its wording ("…for the new commands/skills"); the IDE gate is composed with that.
• Renamed tools mapped faithfully (Windsurf→Devin Desktop, RooCode→Zoo Code both keep the flag).

Proof it works

• Tests: CLI-only tool (claude) shows no restart line; IDE tool (cursor) does; mixed CLI+IDE (claude,cursor) does; a pre-existing main test that asserted codex (a CLI) should show the line was corrected to assert no line.
• Regression gate: build ✅, eslint ✅, full suite green locally and on CI (linux/macos/windows all ✅). The only 2 failures seen on main (artifact-workflow "creates skills for Cursor tool", config-profile PATH-resolution) reproduce identically on untouched main — pre-existing, unrelated.
• CodeRabbit's one actionable finding (couple the hint to the same tool's artifacts) is addressed by the gate above.

Follow-up (out of scope)

openspec update still prints the restart hint unconditionally (src/core/update.ts:390) — the same bug on the other command. Tracked separately in #1608.

Related: #1076 (empty /opsx: slash menu) is a different root cause — command discovery, not the message — so it is not fixed here.

AI was used for assistance.

Summary by CodeRabbit

• New Features

  • Improved openspec init guidance by showing IDE restart instructions only for supported IDE-based tools that require a restart.
  • Tailored restart messaging based on whether commands, skills, or both were generated.

• Bug Fixes

  • CLI-only tools, including Codex, no longer display unnecessary IDE restart instructions.

• Tests

  • Added coverage for CLI-only, IDE-based, and mixed tool configurations.

[coderabbitai]

Warning

Review limit reached

@clay-good, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 19 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 92284bec-9825-4066-9dea-fca1c35afb26

📥 Commits

Reviewing files that changed from the base of the PR and between 6ec2e06 and af80903.

📒 Files selected for processing (2)

• src/core/config.ts
• test/core/init.test.ts

📝 Walkthrough

Walkthrough

openspec init now marks IDE-integrated tools with restart requirements. The success message shows restart guidance only when qualifying tools generate skills or commands. Tests cover CLI-only, IDE-resident, mixed, and Codex configurations.

Changes

IDE restart guidance

Layer / File(s)	Summary
Tool restart capabilities src/core/config.ts, src/core/init.ts	Tool definitions declare requiresIdeRestart. Validation carries this capability into initialized tool records.
Conditional restart output and coverage src/core/init.ts, test/core/init.test.ts, .changeset/restart-ide-hint.md	Restart guidance now depends on qualifying tools and generated skills or commands. Tests cover CLI-only, IDE-resident, mixed, and Codex configurations. The changeset documents the behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

• Issue 1608: The related update flow applies the same requiresIdeRestart gating to restart guidance.

Possibly related PRs

• Fission-AI/OpenSpec#323: This change refines the restart guidance implemented in displaySuccessMessage.
• Fission-AI/OpenSpec#1404: Both changes adjust when src/core/init.ts displays restart guidance.
• Fission-AI/OpenSpec#1517: Both changes modify init reporting and its tests.

Suggested reviewers: tabishb

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: limiting the IDE restart hint to IDE-embedded tools.
Linked Issues check	✅ Passed	The changes address issue #1067 by suppressing the restart hint for CLI tools and retaining it for applicable IDE-resident tools.
Out of Scope Changes check	✅ Passed	The configuration, initialization logic, tests, and changeset all directly support the linked issue and stated PR objectives.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/pr-1097-merge-ready-9adcba

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/core/init.ts`:
- Around line 1279-1287: Update the restart-hint logic around
anyRequiresIdeRestart so eligibility is calculated per successful tool,
requiring tool.requiresIdeRestart together with that tool’s corresponding
shouldGenerateCommands and shouldGenerateSkills results; derive the message’s
commands/skills wording from those same IDE-tool artifacts rather than
aggregated totals. Add a regression test covering mixed restart-marked and CLI
tools, including the case where only skills are generated.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 1165dfcc-9f8e-4977-8ee3-24b3da820c56

📥 Commits

Reviewing files that changed from the base of the PR and between e50bd09 and 202f56c.

📒 Files selected for processing (4)

• .changeset/restart-ide-hint.md
• src/core/config.ts
• src/core/init.ts
• test/core/init.test.ts