fix(init): skip the welcome animation for reduced-motion users

[clay-good]

Closes #722

Status: LGTM — full suite green (112 files, 2,287 tests), verified end-to-end against a real PTY, three independent adversarial review passes applied.

What was wrong: the openspec init welcome screen animates eight ASCII frames on a 120ms loop with ANSI cursor-clearing, and there was no way to turn it off. As #722 explains, flashing and animation are seizure and nausea triggers; the only escape hatches (NO_COLOR, a narrow terminal) are unrelated workarounds.

How it's fixed: canAnimate() now also routes to the pre-existing static welcome screen when any of these say "no motion":

Signal	Behavior
OS reduced-motion preference	Detected best-effort: macOS Reduce Motion (defaults read com.apple.universalaccess reduceMotion), GNOME animations disabled (gsettings get org.gnome.desktop.interface enable-animations). 500ms timeout, SIGKILL on expiry; any lookup failure keeps animation on.
OPENSPEC_NO_ANIMATION env var	Presence-based: any value, including empty, disables the animation
openspec init --no-animation	Per-run flag

Defaults are untouched: users with no preference set see the exact same animation, non-TTY output is byte-identical, and the OS lookup only runs on interactive TTYs (last check, so CI/tests never spawn a process). The static screen was already the fallback for non-TTY/NO_COLOR, so no new rendering path is introduced.

Proof: driving the built CLI through a PTY (script) and counting welcome-frame paints in the transcript:

default:                  9 paints, 10 cursor-up repaint sequences (animates, unchanged)
--no-animation:           1 paint, no repaints
OPENSPEC_NO_ANIMATION=1:  1 paint, no repaints

New unit tests cover both env/flag static paths (including the empty-value env case), the macOS/GNOME/other-platform detection branches (child_process mocked, so tests are deterministic on machines that really have Reduce Motion on), and the completion-registry parity test pins the new flag against Commander.

Notes:

• Detection is deliberately fail-open (any error = animate) so a missing defaults/gsettings, sandboxed exec, or slow MDM machine can never break or stall init — worst case is one ≤500ms lookup before an animation the user sits at anyway.
• Windows has no reliable console reduced-motion signal, so it relies on the flag/env var (no process is spawned there).
• Scope limit: the ora progress spinners later in init ("Setting up <tool>...") still animate; they're single-line, brief, and orthogonal to the welcome-screen loop the issue describes. Extending the no-motion signal to spinners (init + update) is a natural follow-up.
• Pre-existing nit, unchanged: the static welcome text ends with "Press Enter to select tools..." even though the static path doesn't wait for Enter (the selector appears immediately). Same behavior NO_COLOR users already get; happy to fix in a follow-up.
• Docs: docs/cli.md init options + environment-variable table updated; changeset included (patch).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added a --no-animation option to openspec init to show a static welcome screen instead of animations.
  • The welcome animation now automatically falls back to the static screen when reduced-motion preferences are enabled, when animations are disabled via OPENSPEC_NO_ANIMATION, or when NO_COLOR is set.
• Documentation
  • Updated CLI docs to document --no-animation, OPENSPEC_NO_ANIMATION, and reduced-motion behavior.
• Tests
  • Expanded welcome-screen tests to cover reduced-motion and animation-disabling scenarios.

[coderabbitai]

📝 Walkthrough

Walkthrough

openspec init now supports --no-animation, OPENSPEC_NO_ANIMATION, and operating-system reduced-motion preferences. When animation is disabled, the command renders a static welcome screen. Tests, documentation, and Changesets metadata cover the new behavior.

Changes

Init welcome accessibility

Layer / File(s)	Summary
CLI animation control src/cli/index.ts, src/core/completions/command-registry.ts, src/core/init.ts	The init command defines --no-animation, stores the animation setting, and passes it to the welcome screen.
Welcome motion detection and static rendering src/ui/welcome-screen.ts	The welcome screen checks explicit options, OPENSPEC_NO_ANIMATION, and macOS/Linux reduced-motion preferences before choosing animated or static output.
Validation and user-facing documentation test/ui/welcome-screen.test.ts, test/core/init.test.ts, docs/cli.md, .changeset/init-no-animation.md	Tests cover animation suppression and platform detection; documentation and release metadata describe the new controls.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant InitCommand
  participant WelcomeScreen
  participant OSSettings
  CLI->>InitCommand: pass animation option
  InitCommand->>WelcomeScreen: showWelcomeScreen(workflows, animate)
  WelcomeScreen->>OSSettings: query reduced-motion preferences
  OSSettings-->>WelcomeScreen: return motion preference
  WelcomeScreen-->>InitCommand: render animated or static screen

Loading

Possibly related PRs

• Fission-AI/OpenSpec#560: Modifies the animated CLI welcome UI in src/ui/welcome-screen.ts.
• Fission-AI/OpenSpec#1410: Modifies the openspec init integration with showWelcomeScreen.

Suggested reviewers: alfred-openspec

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR satisfies #722 by adding a --no-animation option and related accessibility controls for the init welcome screen.
Out of Scope Changes check	✅ Passed	The added env var support, reduced-motion detection, docs, tests, and changeset all support the stated init accessibility objective.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: skipping the init welcome animation for reduced-motion users.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/init-no-animation

---

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.}

[cloudflare-workers-and-pages]

Deploying openspec-docs with    Cloudflare Pages

Latest commit:	5cdb0a3
Status:	✅  Deploy successful!
Preview URL:	https://757b261a.openspec-docs.pages.dev
Branch Preview URL:	https://fix-init-no-animation.openspec-docs.pages.dev

View logs

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

test/core/init.test.ts (1)

902-902: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Exercise the disabled value through InitCommand.

This only locks in the default path. Add a companion test constructing InitCommand with { animation: false } and asserting showWelcomeScreenMock receives { animate: false }, so a core-layer wiring regression cannot pass the UI-only static-render tests.

🤖 Prompt for 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.

In `@test/core/init.test.ts` at line 902, Add a companion test around the existing
InitCommand welcome-screen test that constructs InitCommand with animation
disabled, then invokes it and asserts showWelcomeScreenMock is called with
['explore', 'new'] and { animate: false }.

🤖 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/ui/welcome-screen.ts`:
- Around line 124-125: Update the OPENSPEC_NO_ANIMATION check in the animation
decision logic to disable animation whenever the environment variable is
explicitly set, including an empty string, by checking specifically for
undefined. Add a regression test covering OPENSPEC_NO_ANIMATION= and preserve
the existing behavior when the variable is unset.

---

Nitpick comments:
In `@test/core/init.test.ts`:
- Line 902: Add a companion test around the existing InitCommand welcome-screen
test that constructs InitCommand with animation disabled, then invokes it and
asserts showWelcomeScreenMock is called with ['explore', 'new'] and { animate:
false }.

🪄 Autofix (Beta)

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: 6bd23da5-b35e-4752-9dcc-1287a003ce3b

📥 Commits

Reviewing files that changed from the base of the PR and between 05c7019 and 5fc4421.

📒 Files selected for processing (8)

• .changeset/init-no-animation.md
• docs/cli.md
• src/cli/index.ts
• src/core/completions/command-registry.ts
• src/core/init.ts
• src/ui/welcome-screen.ts
• test/core/init.test.ts
• test/ui/welcome-screen.test.ts

[alfred-openspec]

Reviewed at 5cdb0a3. Reduced-motion detection, --no-animation, and present-even-empty OPENSPEC_NO_ANIMATION all use the existing static path; 84 focused tests, build, lint, the 2,286-test cross-platform suite, and all CI/security checks pass.