openspec-onboard

name	openspec-onboard
description	Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.
license	MIT
compatibility	Requires openspec CLI.
metadata	{"author":"openspec","version":"1.0","generatedBy":"1.0.2"}

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:

openspec status --json 2>&1 || echo "NOT_INITIALIZED"
```text

**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:

```text
## 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
1. Explore the problem briefly
1. Create a change (the container  our work)
1. Build the artifacts: proposal → specs → design → tasks
1. Implement the tasks
1. Archive the completed change

**Time:** ~15-20 minutes

Lets good: [brief reason]

**2. [Second task]**
   Location: `src/another/file.ts`
   Scope: ~1 file, ~15 lines
   Why its good: [brief reason]

**4. Something ?**
   Tell me what yout find obvious quick wins  your codebase. Whatve been meaning to add or fix?



If the user picks or describes something too large (major feature, multi-day work):

```text
Thats probably larger than ideal  your first OpenSpec run-through.

For learning the workflow, smaller is better—it lets you see the full cycle without getting stuck  implementation details.

**Options:**
1. **Slice it smaller** - Whatll take longer.

What would you prefer?
```text

Let the user override  they insist—this is a soft guardrail.

---



Once a task is selected, briefly demonstrate explore mode:

```text
Before we create a change,  me quickly show you **explore mode**—its create a change to hold our work.
```text

**PAUSE** - Wait  user acknowledgment before proceeding.

---



**EXPLAIN:**

```text


A   OpenSpec is a container  all the thinking and planning around a piece of work. It lives  `openspec/changes/<name>/` and holds your artifacts—proposal, specs, design, tasks.

Let me create one  our task.
```text

**DO:** Create the change with a derived kebab-case name:

```bash
openspec new change 
```text

**SHOW:**

```text
Created: `openspec/changes/<name>/`

The folder structure:
```text

openspec/changes/<name>/
├── proposal.md    ← Why well fill it)
├── design.md      ← How wes fill  the first artifact—the proposal.
```text

---



**EXPLAIN:**

```text


The proposal captures **why** wes the   the work.

It save yet):

```text
Herere building  precise, testable terms. They use a requirement/scenario format that makes expected behavior crystal clear.

For a small task like this, we might only need one spec file.
```text

**DO:** Create the spec file:

```bash
 -p openspec/changes/<name>/specs/<capability-name>
```text

Draft the spec content:

```text
Herell build it—technical decisions, tradeoffs, approach.

For small changes, this might be brief. Thats the design:

---



[Brief context about the current state]



**Goals:**
- [What wes explicitly out of scope]





[Explanation of approach and rationale]

---

For a small task, this captures the key decisions without over-engineering.
```text

Save to `openspec/changes/<name>/design.md`.

---



**EXPLAIN:**

```text


Finally, we  the work into implementation tasks—checkboxes that drive the apply phase.

These should be small, clear, and  logical order.
```text

**DO:** Generate tasks based on specs and design:

```text
Here are the implementation tasks:

---



- [ ] 1.1 [Specific task]
- [ ] 1.2 [Specific task]



- [ ] 2.1 [Verification step]

---

Each checkbox becomes a unit of work  the apply phase. Ready to implement?
```text

**PAUSE** - Wait  user to confirm theyll announce each one and occasionally note how the specs/design informed the approach.
```text

**DO:** For each task:

1. Announce: 
1. Implement the change  the codebase
1. Reference specs/design naturally: 
1. Mark complete  tasks.md: `- [ ]` → `- [x]`
1. Brief status: 

Keep narration light—dons archive it.
```text

---



**EXPLAIN:**

```text


When a change is complete, we archive it. This moves it from `openspec/changes/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`.

Archived changes become your projects . The code is  your codebase, the decision record is preserved.
```text

---



```text


You just completed a full OpenSpec cycle:

1. **Explore** - Thought through the problem
1. **New** - Created a change container
1. **Proposal** - Captured WHY
1. **Specs** - Defined WHAT  detail
1. **Design** - Decided HOW
1. **Tasks** - Broke it into steps
1. **Apply** - Implemented the work
1. **Archive** - Preserved the record

This same rhythm works  any size change—a small fix or a major feature.

---



| Command | What it does |
|---------|--------------|
| `/opsx:explore` | Think through problems before/during work |
| `/opsx:new` | Start a new change, step through artifacts |
| `/opsx:ff` | Fast-forward: create all artifacts at once |
| `/opsx:` | Continue working on an existing change |
| `/opsx:apply` | Implement tasks from a change |
| `/opsx:verify` | Verify implementation matches artifacts |
| `/opsx:archive` | Archive a completed change |

---



Try `/opsx:new` or `/opsx:ff` on something you actually want to build. Yout be lost. Come back whenever yout skip phases** even  the change is small—the goal is teaching the workflow
- **Pause  acknowledgment** at marked points, but dont simulate or use fake examples
- **Adjust scope gently**—guide toward smaller tasks but respect user choice