fix(onboard): replace broken preflight check with direct config file test

[TabishB]

Summary

• The onboarding preflight used openspec status --json to detect project initialization, but that command requires an existing change — so it always failed on a freshly initialized project (no changes yet), creating a loop where users were told to run openspec init again
• Replaced with two direct checks: openspec --version (CLI installed?) and test -f openspec/config.yaml (project initialized?)

Test plan

• Run openspec init in a fresh project, then trigger onboarding — preflight should pass
• Run onboarding in a directory without openspec/config.yaml — should report "not initialized"
• Run onboarding without the CLI installed — should report "CLI not installed"

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Improved onboarding preflight validation to properly detect CLI installation and project initialization status, providing clearer feedback when requirements are missing.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The changes introduce a fix to the onboarding preflight check by replacing status JSON parsing with direct verification of OpenSpec CLI availability and project initialization. The implementation now performs a two-step check: verifying CLI presence via openspec --version and confirming project initialization by checking for openspec/config.yaml file existence, with distinct error handling for each failure scenario.

Changes

Cohort / File(s)	Summary
Changelog Entry .changeset/fix-onboarding-preflight.md	Documents the fix to the onboarding preflight check, replacing status JSON parsing with direct file existence verification and CLI version validation.
Preflight Verification Logic src/core/templates/skill-templates.ts	Replaces single initialization check with two-step verification: CLI availability check via openspec --version and project initialization check via file presence, each with separate error handling for CLI_NOT_INSTALLED and NOT_INITIALIZED status codes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

A rabbit hops through preflight's door,
Now checking twice, not once before—
The CLI whispers "I'm alive!"
Config files help verify,
Fresh projects now will truly thrive! 🐰✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: replacing a broken preflight check with a direct config file test, which is the primary fix described in the PR objectives.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/onboarding-preflight-check

---

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 and usage tips.}

[vibe-kanban-cloud]

Review Complete

Your review story is ready!

View Story

Comment !reviewfast on this PR to re-generate the story.

[greptile-apps]

Greptile Overview

Greptile Summary

Fixes a critical onboarding loop bug where openspec status --json was incorrectly used to detect project initialization. Since the status command requires an existing change (via --change flag), it always failed on freshly initialized projects with no changes yet, causing users to be stuck in a loop.

The fix replaces the single broken check with two direct, independent checks:

• openspec --version - Verifies the CLI is installed
• test -f openspec/config.yaml - Verifies the project is initialized

This approach correctly identifies both failure modes (CLI not installed vs. project not initialized) and provides appropriate error messages for each case.

Confidence Score: 5/5

• This PR is safe to merge - it fixes a critical bug with a simple, well-targeted solution
• The change is minimal, surgical, and directly addresses the root cause. The new approach uses two simple, reliable checks instead of a command that was never appropriate for this use case. No complex logic or edge cases introduced.
• No files require special attention

Important Files Changed

Filename	Overview
.changeset/fix-onboarding-preflight.md	Added changeset documenting the fix for broken onboarding preflight check
src/core/templates/skill-templates.ts	Replaced broken openspec status --json with two separate checks: CLI installation and config file existence

Sequence Diagram

sequenceDiagram
    participant User
    participant Agent as Onboarding Agent
    participant CLI as OpenSpec CLI
    participant FS as File System

    User->>Agent: Run /opsx:onboard
    Agent->>CLI: openspec --version
    alt CLI not installed
        CLI-->>Agent: Error
        Agent->>User: CLI_NOT_INSTALLED - Install CLI first
    else CLI installed
        CLI-->>Agent: Version info
        Agent->>FS: test -f openspec/config.yaml
        alt Config file not found
            FS-->>Agent: NOT_INITIALIZED
            Agent->>User: Run openspec init first
        else Config file exists
            FS-->>Agent: INITIALIZED
            Agent->>User: Begin onboarding workflow
        end
    end

Loading