perf(cli): remaining slow startup paths after #2025, plus guardrails #2026

Summary

Every time the CLI runs, it loads code it doesn't need for that command. #2025 fixes the biggest case: openspec --version now loads 24 modules instead of 485. Other commands still do extra work, though, and some of them run a lot:

• Shell completion runs the CLI on every Tab press.
• OpenSpec Desktop runs list --json, doctor --json, store list --json and config list again and again.
• Agents call status --json and instructions --json many times per change.

This issue lists what's left, explains how the CLI got slow, and proposes guardrails so it doesn't happen again. Nothing here blocks #2025.

What's still slow

Times are medians on macOS with Node 23. A bare node process takes 19 ms. On Windows, expect every number to be several times higher. File paths and line numbers are as of #2025.

Where each one lives and how to fix it

1. Telemetry delays exit. src/cli/index.ts:227 awaits shutdown(), which waits for the fetch in src/telemetry/index.ts (timeout 1000 ms). Fix: don't track the hidden __complete command at all. For other commands, stop waiting on the request before exiting, either by capping the wait or by sending it from a detached process.
2. Completion. src/core/completions/completion-provider.ts:2 imports listSchemas from the artifact-graph/index.js barrel (a file that re-exports a whole folder), and src/commands/completion.ts:1 imports ora at the top of the file. Fix: load listSchemas from resolver.js with await import() inside getSchemaNames, and load ora only in install and uninstall.
3. Store. src/core/store/foundation.ts:3-4 imports yaml and zod and builds its zod schemas at the top of the file. Fix: load yaml and zod inside the functions that read the registry and metadata. Those functions are already async.
4. Config. src/commands/config.ts imports core/config-schema.ts, which builds GlobalConfigSchema with zod as soon as it loads. Fix: move the schema and validateConfig into their own module and load it only from set, edit and reset.
5. Schema re-parsing. resolveSchema in src/core/artifact-graph/resolver.ts has no cache. Fix: cache the result for the life of the process, keyed by schema name and project root.
6. fast-glob. src/core/artifact-graph/outputs.ts:3 imports fast-glob at the top of the file, and the barrel re-exports outputs.ts. Fix: load fast-glob only where it's used, and import resolver.js and outputs.js directly instead of through the barrel.
7. ora. There's a top-level import ora in src/commands/workflow/{status,instructions,new-change,templates}.ts, src/commands/validate.ts and src/commands/schema.ts. Fix: await import('ora') only when not in --json mode.

Two small follow-ups from reviewing #2025:

• test/cli-e2e/startup-modules.test.ts never checks the CLI's exit code. A --version run that crashed right after loading commander would still pass. Fix: assert status === 0 for --version and --help.
• On a broken install, the new lazy imports run outside each command's own error handling. doctor --json, context --json and status --all --json (src/cli/index.ts:726) would print a stack trace instead of their JSON error. The exit code is still 1.

How we got here

--version load cost across published releases (macOS, Node 23):

• The pattern was set on day one. The first CLI commit imported every command at the top of src/cli/index.ts. Every later command followed that example, and the list of top-level imports grew from 1 to 23.
• The biggest jump came in 0.17 to 0.20, when yaml, fast-glob and telemetry were added (+204 modules).
• We fixed a related bug once, but only that one bug. fix(cli): prevent hang in pre-commit hooks by using dynamic imports #380 made init and @inquirer/prompts load lazily to fix a hang. It added a lint rule, but that rule covers only @inquirer/*. The general rule, "keep heavy dependencies out of startup", was never written down.
• Command files mixed help text with implementation. Starting with feat(cli): add openspec config command for global configuration management #382, register*Command files held both a command's definition and its implementation. Loading --help therefore loaded every command's full dependency tree. perf(cli): load each command's implementation only when it runs #2025 splits those files.

Why nothing caught it

• CI has no check for startup. Nothing measures startup time, the number of modules loaded, or bundle size.
• Tests checked behavior, not cost. Tests that run the CLI check its output and never how long it took. perf(cli): load each command's implementation only when it runs #2025 adds the first startup test.
• The warning sign was misread. Fix Windows CI flake hardening #1325 and test: stop two Windows subprocess tests timing out at 10s #1981 blamed Windows test timeouts on slow process creation and raised the timeouts to 60 s. In reality, about 500 ms of each CLI run was our own module loading.
• The cost was easy to miss until Desktop. An extra 150 ms is invisible when a person runs one command. Desktop runs the CLI many times, including a --version check with a 5 s deadline, and takes about 600 ms per call on Windows.

How to prevent it

1. Make the startup test cover every command. Have startup-modules.test.ts fail when a new command is added without a case.
2. Widen the lint rule. Ban static imports of command implementations and heavy packages (zod, yaml, fast-glob, ora, diff, @InQuirer) from src/cli/**.
3. Add a module budget to CI. For example, --version may load at most 30 modules. Unlike timing, this gives the same result on every run.
4. Check startup before raising a timeout. When a Windows test times out, measure how long the CLI takes to start before raising the limit. Add this to CONTRIBUTING.

Suggested order

1. Items 1 and 2: Tab completion gets the most noticeable speedup.
2. Items 3, 4 and 5: Desktop.
3. Items 6 and 7: agents.
4. Guardrails 1 to 3, best done together with the fixes.