| 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 for our work)
1. Build the artifacts: proposal → specs → design → tasks
1. Implement the tasks
1. Archive the completed change
**Time:** ~15-20 minutes
Let's start by finding something to work on.
```text
---
## 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
1. **Missing error handling** - `catch` blocks that swallow errors, risky operations without try-catch
1. **Functions without tests** - Cross-reference `src/` with test directories
1. **Type issues** - `any` types in TypeScript files (`: any`, `as any`)
1. **Debug artifacts** - `console.log`, `console.debug`, `debugger` statements in non-debug code
1. **Missing validation** - User input handlers without validation
Also check recent git activity:
```bash
git log --oneline -10 2>/dev/null || echo "No git history"
```text
### Present Suggestions
From your analysis, present 3-4 specific suggestions:
```text
## Task Suggestions
Based on scanning your codebase, here are some good starter tasks:
**1. [Most promising task]**
Location: `src/path/to/file.ts:42`
Scope: ~1-2 files, ~20-30 lines
Why it's good: [brief reason]
**2. [Second task]**
Location: `src/another/file.ts`
Scope: ~1 file, ~15 lines
Why it's good: [brief reason]
**3. [Third task]**
Location: [location]
Scope: [estimate]
Why it's good: [brief reason]
**4. Something else?**
Tell me what you'd like to work on.
Which task interests you? (Pick a number or describe your own)
```text
**If nothing found:** Fall back to asking what the user wants to build:
> I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix?
If the user picks or describes something too large (major feature, multi-day work):
```text
That's a valuable task, but it's probably larger than ideal for your first OpenSpec run-through.
For learning the workflow, smaller is better—it lets you see the full cycle without getting stuck in implementation details.
**Options:**
1. **Slice it smaller** - What's the smallest useful piece of [their task]? Maybe just [specific slice]?
1. **Pick something else** - One of the other suggestions, or a different small task?
1. **Do it anyway** - If you really want to tackle this, we can. Just know it'll take longer.
What would you prefer?
```text
Let the user override if they insist—this is a soft guardrail.
---
Once a task is selected, briefly demonstrate explore mode:
```text
Before we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction.
```text
Spend 1-2 minutes investigating the relevant code:
- Read the file(s) involved
- Draw a quick ASCII diagram if it helps
- Note any considerations
```text
## Quick Exploration
[Your brief analysis—what you found, any considerations]
┌─────────────────────────────────────────┐
│ [Optional: ASCII diagram if helpful] │
└─────────────────────────────────────────┘
Explore mode (`/opsx:explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem.
Now let's create a change to hold our work.
```text
**PAUSE** - Wait for user acknowledgment before proceeding.
---
**EXPLAIN:**
```text
A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives in `openspec/changes/<name>/` and holds your artifacts—proposal, specs, design, tasks.
Let me create one for our task.
```text
**DO:** Create the change with a derived kebab-case name:
```bash
openspec new change "<derived-name>"
```text
**SHOW:**
```text
Created: `openspec/changes/<name>/`
The folder structure:
```text
openspec/changes/<name>/
├── proposal.md ← Why we're doing this (empty, we'll fill it)
├── design.md ← How we'll build it (empty)
├── specs/ ← Detailed requirements (empty)
└── tasks.md ← Implementation checklist (empty)
```text
Now let's fill in the first artifact—the proposal.
```text
---
**EXPLAIN:**
```text
The proposal captures **why** we're making this change and **what** it involves at a high level. It's the "elevator pitch" for the work.
I'll draft one based on our task.
```text
**DO:** Draft the proposal content (don't save yet):
```text
Here's a draft proposal:
---
## Why
[1-2 sentences explaining the problem/opportunity]
## What Changes
[Bullet points of what will be different]
## Capabilities
### New Capabilities
- `<capability-name>`: [brief description]
### Modified Capabilities
<!-- If modifying existing behavior -->
## Impact
- `src/path/to/file.ts`: [what changes]
- [other files if applicable]
---
Does this capture the intent? I can adjust before we save it.
```text
**PAUSE** - Wait for user approval/feedback.
After approval, save the proposal:
```bash
openspec instructions proposal --change "<name>" --json
```text
Then write the content to `openspec/changes/<name>/proposal.md`.
```text
Proposal saved. This is your "why" document—you can always come back and refine it as understanding evolves.
Next up: specs.
```text
---
## Phase 6: Specs
**EXPLAIN:**
```text
## Specs
Specs define **what** we're building in 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
mkdir -p openspec/changes/<name>/specs/<capability-name>
```text
Draft the spec content:
```text
Here's the spec:
---
## ADDED Requirements
### Requirement: <Name>
<Description of what the system should do>
#### Scenario: <Scenario name>
- **WHEN** <trigger condition>
- **THEN** <expected outcome>
- **AND** <additional outcome if needed>
---
This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases.
```text
Save to `openspec/changes/<name>/specs/<capability>/spec.md`.
---
## Phase 7: Design
**EXPLAIN:**
```text
## Design
The design captures **how** we'll build it—technical decisions, tradeoffs, approach.
For small changes, this might be brief. That's fine—not every change needs deep design discussion.
```text
**DO:** Draft design.md:
```text
Here's the design:
---
[Brief context about the current state]
**Goals:**
- [What we're trying to achieve]
**Non-Goals:**
- [What's 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 break the work into implementation tasks—checkboxes that drive the apply phase.
These should be small, clear, and in 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 in the apply phase. Ready to implement?
```text
**PAUSE** - Wait for user to confirm they're ready to implement.
Save to `openspec/changes/<name>/tasks.md`.
---
## Phase 9: Apply (Implementation)
**EXPLAIN:**
```text
## Implementation
Now we implement each task, checking them off as we go. I'll announce each one and occasionally note how the specs/design informed the approach.
```text
**DO:** For each task:
1. Announce: "Working on task N: [description]"
1. Implement the change in the codebase
1. Reference specs/design naturally: "The spec says X, so I'm doing Y"
1. Mark complete in tasks.md: `- [ ]` → `- [x]`
1. Brief status: "✓ Task N complete"
Keep narration light—don't over-explain every line of code.
After all tasks:
```text
## Implementation Complete
All tasks done:
- [x] Task 1
- [x] Task 2
- [x] ...
The change is implemented! One more step—let's 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 project's decision history—you can always find them later to understand why something was built a certain way.
```text
**DO:**
```bash
openspec archive "<name>"
```text
**SHOW:**
```text
Archived to: `openspec/changes/archive/YYYY-MM-DD-<name>/`
The change is now part of your project's history. The code is in 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 in 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 for 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` | 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. You've got the rhythm now!
```text
---
## Graceful Exit Handling
### User wants to stop mid-way
If the user says they need to stop, want to pause, or seem disengaged:
```text
No problem! Your change is saved at `openspec/changes/<name>/`.
To pick up where we left off later:
- `/opsx:continue <name>` - Resume artifact creation
- `/opsx:apply <name>` - Jump to implementation (if tasks exist)
The work won't be lost. Come back whenever you're ready.
```text
Exit gracefully without pressure.
### User just wants command reference
If the user says they just want to see the commands or skip the tutorial:
```text
## OpenSpec Quick Reference
| Command | What it does |
|---------|--------------|
| `/opsx:explore` | Think through problems (no code changes) |
| `/opsx:new <name>` | Start a new change, step by step |
| `/opsx:ff <name>` | Fast-forward: all artifacts at once |
| `/opsx:continue <name>` | Continue an existing change |
| `/opsx:apply <name>` | Implement tasks |
| `/opsx:verify <name>` | Verify implementation |
| `/opsx:archive <name>` | Archive when done |
Try `/opsx:new` to start your first change, or `/opsx:ff` if you want to move fast.
```text
Exit gracefully.
---
## Guardrails
- **Follow the EXPLAIN → DO → SHOW → PAUSE pattern** at key transitions (after explore, after proposal draft, after tasks, after archive)
- **Keep narration light** during implementation—teach without lecturing
- **Don't skip phases** even if the change is small—the goal is teaching the workflow
- **Pause for acknowledgment** at marked points, but don't over-pause
- **Handle exits gracefully**—never pressure the user to continue
- **Use real codebase tasks**—don't simulate or use fake examples
- **Adjust scope gently**—guide toward smaller tasks but respect user choice
