opsx-onboard

OpenSpec project root. The openspec/ directory lives in the REPO, not the workspace this skill is driven from. The repo root is ${SPECRAILS_REPO_DIR:-.} (a default-unset env var: when unset it resolves to ., i.e. the current directory, so a classic in-repo run is unchanged). Run EVERY openspec command against that root — wrap each invocation as (cd "${SPECRAILS_REPO_DIR:-.}" && openspec …). Treat ${SPECRAILS_REPO_DIR:-.} as the OpenSpec project root for any path the CLI prints or you read/write.

Guide the user through their first complete OpenSpec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step.

---

Preflight

Before starting, check if OpenSpec is initialized:

(cd "${SPECRAILS_REPO_DIR:-.}" && openspec status --json) 2>&1 || echo "NOT_INITIALIZED"

If not initialized:

OpenSpec isn't set up in this project yet. Run openspec init first, then come back to /opsx:onboard.

Stop here if not initialized.

---

Phase 1: Welcome

Display:

## Welcome to OpenSpec!

I'll walk you through a complete change cycle—from idea to implementation—using a real task in your codebase. Along the way, you'll learn the workflow by doing it.

**What we'll do:**
1. Pick a small, real task in your codebase
2. Explore the problem briefly
3. Create a change (the container for our work)
4. Build the artifacts: proposal → specs → design → tasks
5. Implement the tasks
6. Archive the completed change

**Time:** ~15-20 minutes

Let's start by finding something to work on.

---

Phase 2: Task Selection

Codebase Analysis

Scan the codebase for small improvement opportunities. Look for:

1. TODO/FIXME comments - Search for TODO, FIXME, HACK, XXX in code files
2. Missing error handling - catch blocks that swallow errors, risky operations without try-catch
3. Functions without tests - Cross-reference src/ with test directories
4. Type issues - any types in TypeScript files (: any, as any)
5. Debug artifacts - console.log, console.debug, debugger statements in non-debug code
6. Missing validation - User input handlers without validation