fix(onboard): add Windows PowerShell alternatives for shell commands by TabishB · Pull Request #638 · Fission-AI/OpenSpec

TabishB · 2026-02-01T02:59:37Z

Summary

Follow-up to fix(onboard): replace broken preflight check with direct config file test #637 which fixed the broken preflight check
Removes the test -f openspec/config.yaml check (not cross-platform) added in fix(onboard): replace broken preflight check with direct config file test #637, keeping just openspec --version
Adds Windows PowerShell alternatives (as comments) for all platform-specific shell commands in the onboarding skill:
- 2>&1 || → ; if ($LASTEXITCODE -ne 0) {}
- 2>/dev/null → 2>$null
- mkdir -p → New-Item -ItemType Directory -Force

Test plan

Verify onboarding skill renders correctly with both Unix and Windows command variants
Run openspec init on a fresh project to regenerate skill files and confirm template output matches

🤖 Generated with Claude Code

Summary by CodeRabbit

Bug Fixes
- More accurate onboarding preflight: verifies CLI installation by version to avoid misclassifying new projects.
Documentation
- Updated onboarding messaging to remove an unnecessary initialization prerequisite and harmonized phase text.
- Added Windows PowerShell alternatives and adjusted shell examples for clearer cross-platform guidance.

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

coderabbitai · 2026-02-01T02:59:51Z

Warning

Rate limit exceeded

@TabishB has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 13 minutes and 11 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📝 Walkthrough

Walkthrough

Replaces the onboarding preflight check's status-based validation with a CLI version check and removes "initialized" prerequisites. Adds Windows PowerShell alternatives for platform-specific shell commands across onboarding templates and documents the fix in a changeset.

Changes

Cohort / File(s)	Summary
Onboarding Preflight Updates `.changeset/fix-onboarding-preflight.md`, `src/core/templates/skill-templates.ts`	Documents and implements the preflight change: replace `openspec status --json` with `openspec --version` for CLI verification; removes initialization-based messaging and updates onboarding instructions to reference "installed" rather than "initialized". Adds PowerShell command variants alongside Unix/macOS examples.
Minor text/consistency edits `minor_updates`	Small phrasing and consistency tweaks across onboarding phases and example commands; no public API or signature changes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

fix(onboard): replace broken preflight check with direct config file test #637: Edits the onboarding preflight logic to use openspec --version and checks for config file presence instead of relying on openspec status --json.

Poem

🐇 I sniffed the CLI, gave a cheerful check,
Replaced the status hunt with a version peck.
PowerShell hops in, Unix keeps the tune,
Now onboarding hums beneath the moon. ✨

🚥 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 describes a significant change in the PR: adding Windows PowerShell alternatives for shell commands in the onboarding process. This is concrete and specific to the main work documented in the changeset.
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 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

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

vibe-kanban-cloud · 2026-02-01T03:01:44Z

Review Complete

Your review story is ready!

View Story

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

greptile-apps · 2026-02-01T03:02:48Z

Greptile Overview

Greptile Summary

Improved cross-platform compatibility of the onboarding skill by removing the non-portable test -f openspec/config.yaml preflight check and adding Windows PowerShell command alternatives as comments.

Key Changes:

Simplified preflight check to only verify CLI installation using openspec --version (removed the separate initialization check that was added in fix(onboard): replace broken preflight check with direct config file test #637)
Added PowerShell alternatives for three platform-specific command patterns:
- Error handling: 2>&1 || → ; if ($LASTEXITCODE -ne 0) {}
- Stderr redirection: 2>/dev/null → 2>$null
- Directory creation: mkdir -p → New-Item -ItemType Directory -Force
Updated user-facing messages to reflect the simplified check

Impact:

Makes onboarding instructions accessible to Windows users without requiring translation
Maintains backward compatibility since Windows commands are commented out
Follows up on fix(onboard): replace broken preflight check with direct config file test #637's Windows compatibility improvements

Confidence Score: 4/5

Safe to merge with one minor style suggestion about path separators in PowerShell commands
The changes are straightforward and improve cross-platform compatibility. The only concern is a minor style inconsistency in the PowerShell path separator choice (backslashes vs forward slashes), which doesn't affect functionality but could be more consistent
No files require special attention - the changes are documentation/template updates with no runtime logic

Important Files Changed

Filename	Overview
.changeset/fix-onboarding-preflight.md	Added changeset documenting the preflight check fix and Windows PowerShell command additions
src/core/templates/skill-templates.ts	Removed non-cross-platform preflight check, simplified to CLI version check, and added Windows PowerShell alternatives for shell commands

Sequence Diagram

sequenceDiagram
    participant User
    participant OnboardSkill as Onboard Skill
    participant CLI as OpenSpec CLI
    participant Shell as Shell (Unix/Windows)

    User->>OnboardSkill: Start /opsx:onboard
    
    Note over OnboardSkill: Preflight Check Phase
    OnboardSkill->>Shell: Execute: openspec --version
    alt Unix/macOS
        Shell->>CLI: Run command with 2>&1 || echo
    else Windows PowerShell
        Shell->>CLI: Run command with LASTEXITCODE check
    end
    
    alt CLI Installed
        CLI-->>OnboardSkill: Version info returned
        OnboardSkill->>User: Continue with onboarding
    else CLI Not Installed
        CLI-->>OnboardSkill: Error
        OnboardSkill->>User: Show "CLI_NOT_INSTALLED" message
        OnboardSkill->>OnboardSkill: Stop execution
    end

    Note over OnboardSkill: Task Selection Phase
    OnboardSkill->>Shell: Execute: git log --oneline -10
    alt Unix/macOS
        Shell->>Shell: Redirect stderr to 2>/dev/null
    else Windows PowerShell
        Shell->>Shell: Redirect stderr to 2>$null
    end
    Shell-->>OnboardSkill: Git history or error message

    Note over OnboardSkill: Spec Creation Phase
    OnboardSkill->>Shell: Create directory
    alt Unix/macOS
        Shell->>Shell: mkdir -p openspec/changes/.../specs/...
    else Windows PowerShell
        Shell->>Shell: New-Item -ItemType Directory -Force
    end
    Shell-->>OnboardSkill: Directory created
    OnboardSkill->>User: Continue with spec creation

greptile-apps

_{2 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-02-01T03:02:52Z

+# Unix/macOS
 mkdir -p openspec/changes/<name>/specs/<capability-name>
+# Windows (PowerShell)
+# New-Item -ItemType Directory -Force -Path "openspec\\changes\\<name>\\specs\\<capability-name>"


PowerShell accepts forward slashes in paths, consider using / instead of \ for consistency with the Unix command above

Suggested change

# New-Item -ItemType Directory -Force -Path "openspec\\changes\\<name>\\specs\\<capability-name>"

# New-Item -ItemType Directory -Force -Path "openspec/changes/<name>/specs/<capability-name>"

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review. Path: src/core/templates/skill-templates.ts Line: 1196:1196 Comment: PowerShell accepts forward slashes in paths, consider using `/` instead of `\` for consistency with the Unix command above ```suggestion # New-Item -ItemType Directory -Force -Path "openspec/changes/<name>/specs/<capability-name>" ``` <sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub> How can I resolve this? If you propose a fix, please make it concise.

coderabbitai

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/core/templates/skill-templates.ts`:
- Around line 940-947: Replace the commented PowerShell check that relies on
$LASTEXITCODE with a Get-Command based existence check: use Get-Command -Name
"openspec" -ErrorAction SilentlyContinue to detect whether the openspec command
is available, and only run openspec --version if Get-Command returns truthy;
otherwise output "CLI_NOT_INSTALLED". Update the commented guidance in
src/core/templates/skill-templates.ts (the PowerShell guidance surrounding the
"openspec --version" snippet) to use this pattern so missing-command detection
is robust across PowerShell sessions.

…ility The onboarding preflight used `openspec status --json` to detect if a project was initialized, but that command requires an existing change to succeed. After a fresh `openspec init` (no changes yet), it always failed — causing the onboarding to incorrectly tell users to run init again. Replace with `openspec --version` to verify the CLI is installed. Also add Windows PowerShell alternatives for all platform-specific shell commands in the onboarding skill: - `2>&1 ||` → `; if ($LASTEXITCODE -ne 0) {}` - `2>/dev/null` → `2>$null` - `mkdir -p` → `New-Item -ItemType Directory -Force`

Use Get-Command for robust CLI detection instead of $LASTEXITCODE (which stays stale when a command isn't found), and use forward slashes in PowerShell paths for consistency with Unix commands.

…ission-AI#638) * fix(onboard): replace broken preflight check and add Windows compatibility The onboarding preflight used `openspec status --json` to detect if a project was initialized, but that command requires an existing change to succeed. After a fresh `openspec init` (no changes yet), it always failed — causing the onboarding to incorrectly tell users to run init again. Replace with `openspec --version` to verify the CLI is installed. Also add Windows PowerShell alternatives for all platform-specific shell commands in the onboarding skill: - `2>&1 ||` → `; if ($LASTEXITCODE -ne 0) {}` - `2>/dev/null` → `2>$null` - `mkdir -p` → `New-Item -ItemType Directory -Force` * fix(onboard): address PR review feedback for PowerShell commands Use Get-Command for robust CLI detection instead of $LASTEXITCODE (which stays stale when a command isn't found), and use forward slashes in PowerShell paths for consistency with Unix commands.

TabishB force-pushed the fix/onboarding-preflight-check branch from 16bdf21 to 11dbd5c Compare February 1, 2026 03:01

greptile-apps Bot reviewed Feb 1, 2026

View reviewed changes

coderabbitai Bot reviewed Feb 1, 2026

View reviewed changes

Comment thread src/core/templates/skill-templates.ts

TabishB force-pushed the fix/onboarding-preflight-check branch from 11dbd5c to 64e50d1 Compare February 1, 2026 03:03

TabishB force-pushed the fix/onboarding-preflight-check branch from 64e50d1 to a5dd4aa Compare February 1, 2026 03:07

TabishB mentioned this pull request Feb 1, 2026

chore: remove broken changeset from #637 #639

Closed

1 task

fix(onboard): address PR review feedback for PowerShell commands

63ca79a

Use Get-Command for robust CLI detection instead of $LASTEXITCODE (which stays stale when a command isn't found), and use forward slashes in PowerShell paths for consistency with Unix commands.

TabishB merged commit 0541f93 into main Feb 1, 2026
9 checks passed

TabishB deleted the fix/onboarding-preflight-check branch February 1, 2026 03:30

1code-async Bot mentioned this pull request Feb 15, 2026

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

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(onboard): add Windows PowerShell alternatives for shell commands#638

fix(onboard): add Windows PowerShell alternatives for shell commands#638
TabishB merged 2 commits into
mainfrom
fix/onboarding-preflight-check

TabishB commented Feb 1, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Feb 1, 2026 •

edited

Loading

Rate limit exceeded

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

vibe-kanban-cloud Bot commented Feb 1, 2026

Uh oh!

greptile-apps Bot commented Feb 1, 2026

Uh oh!

greptile-apps Bot left a comment

Uh oh!

greptile-apps Bot Feb 1, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

	# New-Item -ItemType Directory -Force -Path "openspec\\changes\\<name>\\specs\\<capability-name>"
	# New-Item -ItemType Directory -Force -Path "openspec/changes/<name>/specs/<capability-name>"

Uh oh!

Conversation

TabishB commented Feb 1, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rate limit exceeded

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

vibe-kanban-cloud Bot commented Feb 1, 2026

Review Complete

Uh oh!

greptile-apps Bot commented Feb 1, 2026

Greptile Overview

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps Bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

TabishB commented Feb 1, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Feb 1, 2026 •

edited

Loading