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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: abc03fdf-13b4-4c5e-8280-3d6260ba733c

📥 Commits

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

📒 Files selected for processing (3)

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

🚧 Files skipped from review as they are similar to previous changes (2)

• src/core/init.ts
• src/core/config.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#1214: Both changes modify tool metadata in src/core/config.ts and src/core/init.ts.

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 change to restrict the IDE restart hint to IDE-embedded tools.
Linked Issues check	✅ Passed	The changes address #1067 by suppressing misleading restart guidance for CLI tools and retaining it for applicable IDE-resident tools.
Out of Scope Changes check	✅ Passed	The changeset, configuration updates, implementation changes, and tests are directly related to the linked issue and PR objective.

✨ 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

[alfred-openspec]

The restart hint now follows explicit IDE-tool metadata and only appears when a successful IDE tool receives artifacts; CLI-only and mixed-tool cases are covered. Exact-head checks pass.

[clay-good]

Rebased onto current main by reconstruction: the original branch predated several AI_TOOLS changes (Codex→.agents, Command Code, Rovo Dev, Antigravity, Zoo Code, Kimi/Windsurf), so a direct rebase conflicted heavily in config.ts/init.ts/init.test.ts. Re-applied the exact same semantic change on top of main and verified the flagged IDE-resident set is unchanged (15: amazon-q, antigravity, cline, continue, costrict, cursor, devin, github-copilot, junie, kilocode, kiro, lingma, qoder, roocode, trae). Command Code / Rovo / Codex correctly stay unflagged (CLIs). Full suite green except the two known pre-existing failures; all restart-hint init tests pass.

[cloudflare-workers-and-pages]

Deploying openspec-docs with    Cloudflare Pages

Latest commit:	6554ce3
Status:	✅  Deploy successful!
Preview URL:	https://683f430d.openspec-docs.pages.dev
Branch Preview URL:	https://claude-pr-1097-merge-ready-9.openspec-docs.pages.dev

View logs

[alfred-openspec]

Revalidated the refreshed head: the restart metadata and decision logic are unchanged from the approved version; the main integration only adds Command Code coverage and type cleanup. Five restart-focused tests and the exact-head hosted matrix pass.