OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add fission-ai/openspec --skill openspec-onboard
Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.
npx skills add fission-ai/openspec --skill openspec-onboard
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.
Store selection: If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run openspec store list --json to discover registered store ids, then pass --store <id> on the commands that read or write specs and changes (new change, status, instructions, list, show, validate, archive, doctor, context, schemas, view). Once selected, treat --store <id> as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run openspec status --change "<name>" --json --store "<id>", not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local openspec/ root.
Before starting, check if the OpenSpec CLI is installed:
If CLI not installed:
OpenSpec CLI is not installed. Install it first, then come back to
/openspec-onboard.
Stop here if not installed.
Display:
Scan the codebase for small improvement opportunities. Look for:
TODO, FIXME, HACK, XXX in code filescatch blocks that swallow errors, risky operations without try-catchsrc/ with test directoriesany types in TypeScript files (: any, as any)console.log, console.debug, debugger statements in non-debug codeAlso check recent git activity:
From your analysis, present 3-4 specific suggestions:
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):
Let the user override if they insist—this is a soft guardrail.
Once a task is selected, briefly demonstrate explore mode:
Spend 1-2 minutes investigating the relevant code:
PAUSE - Wait for user acknowledgment before proceeding.
EXPLAIN:
DO: Create the change with a derived kebab-case name:
SHOW:
/ ├── 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)
EXPLAIN:
DO: Draft the proposal content (don't save yet):
<capability-path> is the spec directory relative to specs/ (for example,
user-auth or identity/user-auth). Use the exact existing path for modified
capabilities. For new capabilities, follow the project's established spec
organization.
PAUSE - Wait for user approval/feedback.
After approval, save the proposal:
Then write the content to the resolvedOutputPath from openspec instructions proposal --change "<name>" --json.
EXPLAIN:
DO: Resolve where the spec file should be created:
Draft the spec content:
Save to the concrete file path chosen from resolvedOutputPath.
EXPLAIN:
DO: Draft design.md:
Save to the resolvedOutputPath from openspec instructions design --change "<name>" --json.
EXPLAIN:
DO: Generate tasks based on specs and design:
PAUSE - Wait for user to confirm they're ready to implement.
Save to the resolvedOutputPath from openspec instructions tasks --change "<name>" --json.
EXPLAIN:
DO: For each task:
- [ ] → - [x]Keep narration light—don't over-explain every line of code.
After all tasks:
EXPLAIN:
DO: Archive the change (--yes answers the confirmation prompts, which you cannot answer from a tool call):
SHOW:
If the user says they need to stop, want to pause, or seem disengaged:
Exit gracefully without pressure.
If the user says they just want to see the commands or skip the tutorial:
Exit gracefully.
## 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.# Unix/macOS
git log --oneline -10 2>/dev/null || echo "No git history"
# Windows (PowerShell)
# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "No git history" }## 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)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]?
2. **Pick something else** - One of the other suggestions, or a different small task?
3. **Do it anyway** - If you really want to tackle this, we can. Just know it'll take longer.
What would you prefer?Before we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction.## Quick Exploration
[Your brief analysis—what you found, any considerations]
┌─────────────────────────────────────────┐
│ [Optional: ASCII diagram if helpful] │
└─────────────────────────────────────────┘
Explore mode (`/openspec-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.## Creating a Change
A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives at the `changeRoot` reported by `openspec status --change "<name>" --json` and holds your artifacts—proposal, specs, design, tasks.
Let me create one for our task.openspec new change "<derived-name>"Created: <changeRoot from status JSON>
The folder structure:
Now let's fill in the first artifact—the proposal.## The Proposal
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.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-path>`: [brief description]
### Modified Capabilities
<!-- If modifying existing behavior -->
- `<existing-capability-path>`: [brief description]
## Impact
- `src/path/to/file.ts`: [what changes]
- [other files if applicable]
---
Does this capture the intent? I can adjust before we save it.openspec instructions proposal --change "<name>" --jsonProposal saved. This is your "why" document—you can always come back and refine it as understanding evolves.
Next up: specs.## 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.openspec instructions specs --change "<name>" --json
# Use resolvedOutputPath from the JSON. If it is a glob, choose the concrete file path using the schema instruction and the change's context.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.## 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.Here's the design:
---
## Context
[Brief context about the current state]
## Goals / Non-Goals
**Goals:**
- [What we're trying to achieve]
**Non-Goals:**
- [What's explicitly out of scope]
## Decisions
### Decision 1: [Key decision]
[Explanation of approach and rationale]
---
For a small task, this captures the key decisions without over-engineering.## Tasks
Finally, we break the work into implementation tasks—checkboxes that drive the apply phase.
These should be small, clear, and in logical order.Here are the implementation tasks:
---
## 1. [Category or file]
- [ ] 1.1 [Specific task] — verify: [test, command, observable behavior, or delivered artifact]
- [ ] 1.2 [Specific task] — verify: [test, command, observable behavior, or delivered artifact]
## 2. Integration Verification
- [ ] 2.1 Verify [broader integration or system behavior] with [end-to-end test or observable result]
---
Each checkbox becomes a unit of work in the apply phase. Ready to implement?## 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.## Implementation Complete
All tasks done:
- [x] Task 1
- [x] Task 2
- [x] ...
The change is implemented! One more step—let's archive it.## Archiving
When a change is complete, we archive it. The archive path is derived from `planningHome.changesDir` and the date.
Archived changes become your project's decision history—you can always find them later to understand why something was built a certain way.openspec archive "<name>" --yesArchived to: `<planningHome.changesDir>/archive/<target-name>/` (the target name prepends today's date, unless the name already starts with a `YYYY-MM-DD-` prefix — then it is kept as-is, no second date)
The change is now part of your project's history. The code is in your codebase, the decision record is preserved.## Congratulations!
You just completed a full OpenSpec cycle:
1. **Explore** - Thought through the problem
2. **New** - Created a change container
3. **Proposal** - Captured WHY
4. **Specs** - Defined WHAT in detail
5. **Design** - Decided HOW
6. **Tasks** - Broke it into steps
7. **Apply** - Implemented the work
8. **Archive** - Preserved the record
This same rhythm works for any size change—a small fix or a major feature.
---
## Command Reference
**Core workflow:**
| Command | What it does |
|-------------------|--------------------------------------------|
| `/openspec-propose` | Create a change and generate all artifacts |
| `/openspec-explore` | Think through problems before/during work |
| `/openspec-apply-change` | Implement tasks from a change |
| `/openspec-archive-change` | Archive a completed change |
**Additional commands** (only if installed - availability depends on your profile):
| Command | What it does |
|--------------------|----------------------------------------------------------|
| `/openspec-new-change` | Start a new change, step through artifacts one at a time |
| `/openspec-continue-change` | Continue working on an existing change |
| `/openspec-ff-change` | Fast-forward: create all artifacts at once |
| `/openspec-verify-change` | Verify implementation matches artifacts |
---
## What's Next?
Try `/openspec-propose` on something you actually want to build. You've got the rhythm now!No problem! Your change is saved at the `changeRoot` reported by `openspec status --change "<name>" --json`.
To pick up where we left off later:
- `/openspec-continue-change <name>` - Resume artifact creation (if installed; otherwise `openspec status --change "<name>" --json` shows the next artifact)
- `/openspec-apply-change <name>` - Jump to implementation (if tasks exist)
The work won't be lost. Come back whenever you're ready.## OpenSpec Quick Reference
**Core workflow:**
| Command | What it does |
|--------------------------|--------------------------------------------|
| `/openspec-propose <name>` | Create a change and generate all artifacts |
| `/openspec-explore` | Think through problems (no code changes) |
| `/openspec-apply-change <name>` | Implement tasks |
| `/openspec-archive-change <name>` | Archive when done |
**Additional commands** (only if installed - availability depends on your profile):
| Command | What it does |
|---------------------------|-------------------------------------|
| `/openspec-new-change <name>` | Start a new change, step by step |
| `/openspec-continue-change <name>` | Continue an existing change |
| `/openspec-ff-change <name>` | Fast-forward: all artifacts at once |
| `/openspec-verify-change <name>` | Verify implementation |
Try `/openspec-propose` to start your first change.