Feedback: Onboards fails because openspec status returns : Error: No changes found. Create one with: openspec new change <name>

[mtruel]

---

Submitted via OpenSpec CLI

• Version: 1.1.1
• Platform: linux
• Timestamp: 2026-02-15T09:43:51.742Z

[21st-connector]

Task completed.

The enrichment comment has been posted on issue #714. Here's a summary of what was found:

Root Cause: The error No changes found. Create one with: openspec new change <name> comes from src/commands/workflow/shared.ts:114 when openspec status is called and no change directories exist. A previous fix (PR #637, commit be51bcb) removed a broken openspec status --json preflight check from the onboarding flow, but the error can still surface if:

1. The AI agent calls openspec status without --change during onboarding
2. The change creation step in Phase 4 fails silently
3. A different skill is triggered instead of the onboard skill

Suggested fixes: Make openspec status exit gracefully (instead of throwing) when no changes exist, and add a guard in the onboard template to verify change creation succeeded before proceeding.

The comment also links to all relevant code paths, related issues (#665, #712), and prior fixes (PRs #637, #638), and asks the reporter for additional context since the issue description was minimal.

---

View full conversation

Powered by 1Code

[21st-connector]

Issue Analysis

Context

The error message No changes found. Create one with: openspec new change <name> originates from src/commands/workflow/shared.ts:114, inside the validateChangeExists function. This is thrown when openspec status is called and no change directories exist under openspec/changes/.

Root Cause

This issue was previously addressed in commit be51bcb (PR #637), which removed a broken preflight check that ran openspec status --json during onboarding. That check failed on fresh projects (after openspec init) because no changes had been created yet.

The fix replaced the openspec status --json preflight with a simple openspec --version CLI installation check (see src/core/templates/skill-templates.ts:938-952):

## Preflight

Before starting, check if the OpenSpec CLI is installed:

openspec --version 2>&1 || echo "CLI_NOT_INSTALLED"

However, the onboarding flow at Phase 4 (line 1099) runs openspec new change "<derived-name>" to create the change, and subsequent phases use openspec status --change "<name>" which should work because the change exists by then.

Possible Remaining Scenarios

The error can still occur if:

1. openspec status is called without --change — The --change option is optional in the CLI definition (src/cli/index.ts:424). If the AI agent runs openspec status (or openspec status --json) without specifying --change, and no changes exist, the validation at shared.ts:111-114 throws this error.

2. The AI agent runs a skill other than onboard that calls openspec status --change "<name>" before any change is created — for example, if the user accidentally triggers /opsx:continue or /opsx:apply instead of /opsx:onboard.

3. Phase 4 (openspec new change) fails silently — If the change creation step fails, subsequent openspec status --change "<name>" calls would hit shared.ts:131-134 with a similar error.

Relevant Code Paths

File	Lines	Purpose
src/commands/workflow/shared.ts	93-119	validateChangeExists — throws the error
src/core/templates/skill-templates.ts	938-952	Onboard preflight (current: --version check only)
src/core/templates/skill-templates.ts	1086-1116	Phase 4: Create the change
src/commands/workflow/status.ts	35-63	statusCommand — calls validateChangeExists
src/cli/index.ts	420-434	CLI status command registration (--change is optional)

Related Issues / Prior Fixes

• PR fix(onboard): replace broken preflight check with direct config file test #637 (be51bcb) — Fixed the original preflight issue by replacing openspec status --json with openspec --version
• PR fix(onboard): add Windows PowerShell alternatives for shell commands #638 (0541f93) — Added Windows PowerShell alternatives for onboarding shell commands
• openspec init won't create default spec-driven schema #665 — openspec init won't create default spec-driven schema (could affect onboarding if config is missing)
• openspec init --tools none does not create openspec/config.yaml #712 — openspec init --tools none does not create openspec/config.yaml (could affect onboarding environment)

Suggested Approach

To fully resolve this, consider:

1. Make openspec status more graceful when no changes exist — Instead of throwing an error in shared.ts:114, print a friendly message like "No active changes. Run 'openspec new change <name>' to get started." and exit with code 0. This prevents the error from surfacing regardless of how status is invoked.

2. Add a guard in the onboard template before status calls — After Phase 4 creates the change, verify it was created successfully before proceeding to phases that call openspec status --change.

Additional Information Needed

The issue description is minimal (submitted via CLI feedback). It would help to know:

• At which phase of onboarding did the failure occur?
• Was openspec init run successfully before /opsx:onboard?
• Which AI coding tool was being used (Claude, Cursor, etc.)?
• Full terminal/error output if available