openspec-onboard

name	openspec-onboard
description	Guided end-to-end walkthrough of the OPSX workflow using the real codebase. Trigger: When the user wants to learn OPSX or do a guided first change.
license	MIT
compatibility	Requires openspec CLI.
metadata	{"author":"gentleman-programming","version":"2.0"}

Purpose

Guide the user through a complete OPSX cycle using their actual codebase. This is a real change with real artifacts — the goal is to teach by doing.

Flow

1. Check: is openspec installed and initialized?
2. Explore: think about what to build
3. Propose: create a real change with artifacts
4. Apply: implement the tasks
5. Archive: close the cycle

Steps

Step 1: Check Prerequisites

openspec --version
openspec list --json

If openspec is not installed:

• Direct the user to install it: npm install -g openspec or the relevant method
• Stop until it's available

If not initialized:

• Run through the openspec-init skill first

Step 2: Pick a Real Change

Ask the user:

"What's something small but real you want to build or fix in this project? Could be a bug fix, a small feature, or a refactor. Real is better than made-up."

Help them pick something that:

• Is concrete and completable (not "redesign the auth system")
• Has a clear definition of done
• Won't take more than a few hours

Step 3: Walk Through the Full Cycle

Now guide them through each OPSX action:

Explore (optional but recommended):

• Load openspec-explore
• Think through the change together

Propose:

• Load openspec-propose
• Create the change with all artifacts

Apply:

• Load openspec-apply-change
• Implement at least one task together
• Show them how task checkboxes work

Archive (when done):

• Load openspec-archive-change
• Show how the change gets closed out

Step 4: Debrief

After the cycle, explain:

• What each artifact does (proposal = what/why, design = how, tasks = checklist)
• How to run any step again: /opsx:apply to continue implementing
• How to update artifacts mid-flight: just edit the file and re-run apply
• The key OPSX principle: no phase locks — you can update anything at any time

Rules

• Use the user's real codebase, not toy examples
• Don't rush — this is learning time
• After each step, check if they have questions before continuing
• Emphasize the fluidity: OPSX doesn't have phase gates