1---2name: openspec-onboard3description: Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.4license: MIT5compatibility: Requires openspec CLI.6metadata:7 author: openspec8 version: "1.0"9 generatedBy: "1.4.1"10---1112Guide 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.1314---1516## Preflight1718Before starting, check if the OpenSpec CLI is installed:1920```bash21# Unix/macOS22openspec --version 2>&1 || echo "CLI_NOT_INSTALLED"23# Windows (PowerShell)24# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" }25```2627**If CLI not installed:**28> OpenSpec CLI is not installed. Install it first, then come back to `/opsx:onboard`.2930Stop here if not installed.3132---3334## Phase 1: Welcome3536Display:3738```39## Welcome to OpenSpec!4041I'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.4243**What we'll do:**441. Pick a small, real task in your codebase452. Explore the problem briefly463. Create a change (the container for our work)474. Build the artifacts: proposal → specs → design → tasks485. Implement the tasks496. Archive the completed change5051**Time:** ~15-20 minutes5253Let's start by finding something to work on.54```5556---5758## Phase 2: Task Selection5960### Codebase Analysis6162Scan the codebase for small improvement opportunities. Look for:63641. **TODO/FIXME comments** - Search for `TODO`, `FIXME`, `HACK`, `XXX` in code files652. **Missing error handling** - `catch` blocks that swallow errors, risky operations without try-catch663. **Functions without tests** - Cross-reference `src/` with test directories674. **Type issues** - `any` types in TypeScript files (`: any`, `as any`)685. **Debug artifacts** - `console.log`, `console.debug`, `debugger` statements in non-debug code696. **Missing validation** - User input handlers without validation7071Also check recent git activity:72```bash73# Unix/macOS74git log --oneline -10 2>/dev/null || echo "No git history"75# Windows (PowerShell)76# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "No git history" }77```7879### Present Suggestions8081From your analysis, present 3-4 specific suggestions:8283```84## Task Suggestions8586Based on scanning your codebase, here are some good starter tasks:8788**1. [Most promising task]**89 Location: `src/path/to/file.ts:42`90 Scope: ~1-2 files, ~20-30 lines91 Why it's good: [brief reason]9293**2. [Second task]**94 Location: `src/another/file.ts`95 Scope: ~1 file, ~15 lines96 Why it's good: [brief reason]9798**3. [Third task]**99 Location: [location]100 Scope: [estimate]101 Why it's good: [brief reason]102103**4. Something else?**104 Tell me what you'd like to work on.105106Which task interests you? (Pick a number or describe your own)107```108109**If nothing found:** Fall back to asking what the user wants to build:110> I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix?111112### Scope Guardrail113114If the user picks or describes something too large (major feature, multi-day work):115116```117That's a valuable task, but it's probably larger than ideal for your first OpenSpec run-through.118119For learning the workflow, smaller is better—it lets you see the full cycle without getting stuck in implementation details.120121**Options:**1221. **Slice it smaller** - What's the smallest useful piece of [their task]? Maybe just [specific slice]?1232. **Pick something else** - One of the other suggestions, or a different small task?1243. **Do it anyway** - If you really want to tackle this, we can. Just know it'll take longer.125126What would you prefer?127```128129Let the user override if they insist—this is a soft guardrail.130131---132133## Phase 3: Explore Demo134135Once a task is selected, briefly demonstrate explore mode:136137```138Before we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction.139```140141Spend 1-2 minutes investigating the relevant code:142- Read the file(s) involved143- Draw a quick ASCII diagram if it helps144- Note any considerations145146```147## Quick Exploration148149[Your brief analysis—what you found, any considerations]150151┌─────────────────────────────────────────┐152│ [Optional: ASCII diagram if helpful] │153└─────────────────────────────────────────┘154155Explore mode (`/opsx:explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem.156157Now let's create a change to hold our work.158```159160**PAUSE** - Wait for user acknowledgment before proceeding.161162---163164## Phase 4: Create the Change165166**EXPLAIN:**167```168## Creating a Change169170A "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.171172Let me create one for our task.173```174175**DO:** Create the change with a derived kebab-case name:176```bash177openspec new change "<derived-name>"178```179180**SHOW:**181```182Created: <changeRoot from status JSON>183184The folder structure:185```186<changeRoot>/187├── proposal.md ← Why we're doing this (empty, we'll fill it)188├── design.md ← How we'll build it (empty)189├── specs/ ← Detailed requirements (empty)190└── tasks.md ← Implementation checklist (empty)191```192193Now let's fill in the first artifact—the proposal.194```195196---197198## Phase 5: Proposal199200**EXPLAIN:**201```202## The Proposal203204The proposal captures **why** we're making this change and **what** it involves at a high level. It's the "elevator pitch" for the work.205206I'll draft one based on our task.207```208209**DO:** Draft the proposal content (don't save yet):210211```212Here's a draft proposal:213214---215216## Why217218[1-2 sentences explaining the problem/opportunity]219220## What Changes221222[Bullet points of what will be different]223224## Capabilities225226### New Capabilities227- `<capability-name>`: [brief description]228229### Modified Capabilities230<!-- If modifying existing behavior -->231232## Impact233234- `src/path/to/file.ts`: [what changes]235- [other files if applicable]236237---238239Does this capture the intent? I can adjust before we save it.240```241242**PAUSE** - Wait for user approval/feedback.243244After approval, save the proposal:245```bash246openspec instructions proposal --change "<name>" --json247```248Then write the content to the `resolvedOutputPath` from `openspec instructions proposal --change "<name>" --json`.249250```251Proposal saved. This is your "why" document—you can always come back and refine it as understanding evolves.252253Next up: specs.254```255256---257258## Phase 6: Specs259260**EXPLAIN:**261```262## Specs263264Specs define **what** we're building in precise, testable terms. They use a requirement/scenario format that makes expected behavior crystal clear.265266For a small task like this, we might only need one spec file.267```268269**DO:** Resolve where the spec file should be created:270```bash271openspec instructions specs --change "<name>" --json272# Use resolvedOutputPath from the JSON. If it is a glob, choose the concrete file path using the schema instruction and workspace planning context.273```274275Draft the spec content:276277```278Here's the spec:279280---281282## ADDED Requirements283284### Requirement: <Name>285286<Description of what the system should do>287288#### Scenario: <Scenario name>289290- **WHEN** <trigger condition>291- **THEN** <expected outcome>292- **AND** <additional outcome if needed>293294---295296This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases.297```298299Save to the concrete file path chosen from `resolvedOutputPath`.300301---302303## Phase 7: Design304305**EXPLAIN:**306```307## Design308309The design captures **how** we'll build it—technical decisions, tradeoffs, approach.310311For small changes, this might be brief. That's fine—not every change needs deep design discussion.312```313314**DO:** Draft design.md:315316```317Here's the design:318319---320321## Context322323[Brief context about the current state]324325## Goals / Non-Goals326327**Goals:**328- [What we're trying to achieve]329330**Non-Goals:**331- [What's explicitly out of scope]332333## Decisions334335### Decision 1: [Key decision]336337[Explanation of approach and rationale]338339---340341For a small task, this captures the key decisions without over-engineering.342```343344Save to the `resolvedOutputPath` from `openspec instructions design --change "<name>" --json`.345346---347348## Phase 8: Tasks349350**EXPLAIN:**351```352## Tasks353354Finally, we break the work into implementation tasks—checkboxes that drive the apply phase.355356These should be small, clear, and in logical order.357```358359**DO:** Generate tasks based on specs and design:360361```362Here are the implementation tasks:363364---365366## 1. [Category or file]367368- [ ] 1.1 [Specific task]369- [ ] 1.2 [Specific task]370371## 2. Verify372373- [ ] 2.1 [Verification step]374375---376377Each checkbox becomes a unit of work in the apply phase. Ready to implement?378```379380**PAUSE** - Wait for user to confirm they're ready to implement.381382Save to the `resolvedOutputPath` from `openspec instructions tasks --change "<name>" --json`.383384---385386## Phase 9: Apply (Implementation)387388**EXPLAIN:**389```390## Implementation391392Now 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.393```394395**DO:** For each task:3963971. Announce: "Working on task N: [description]"3982. Implement the change in the codebase3993. Reference specs/design naturally: "The spec says X, so I'm doing Y"4004. Mark complete in tasks.md: `- [ ]` → `- [x]`4015. Brief status: "✓ Task N complete"402403Keep narration light—don't over-explain every line of code.404405After all tasks:406407```408## Implementation Complete409410All tasks done:411- [x] Task 1412- [x] Task 2413- [x] ...414415The change is implemented! One more step—let's archive it.416```417418---419420## Phase 10: Archive421422**EXPLAIN:**423```424## Archiving425426When a change is complete, we archive it. The archive path is derived from `planningHome.changesDir` and the date.427428Archived changes become your project's decision history—you can always find them later to understand why something was built a certain way.429```430431**DO:**432```bash433openspec archive "<name>"434```435436**SHOW:**437```438Archived to: `<planningHome.changesDir>/archive/YYYY-MM-DD-<name>/`439440The change is now part of your project's history. The code is in your codebase, the decision record is preserved.441```442443---444445## Phase 11: Recap & Next Steps446447```448## Congratulations!449450You just completed a full OpenSpec cycle:4514521. **Explore** - Thought through the problem4532. **New** - Created a change container4543. **Proposal** - Captured WHY4554. **Specs** - Defined WHAT in detail4565. **Design** - Decided HOW4576. **Tasks** - Broke it into steps4587. **Apply** - Implemented the work4598. **Archive** - Preserved the record460461This same rhythm works for any size change—a small fix or a major feature.462463---464465## Command Reference466467**Core workflow:**468469 | Command | What it does |470 |-------------------|--------------------------------------------|471 | `/opsx:propose` | Create a change and generate all artifacts |472 | `/opsx:explore` | Think through problems before/during work |473 | `/opsx:apply` | Implement tasks from a change |474 | `/opsx:archive` | Archive a completed change |475476**Additional commands:**477478 | Command | What it does |479 |--------------------|----------------------------------------------------------|480 | `/opsx:new` | Start a new change, step through artifacts one at a time |481 | `/opsx:continue` | Continue working on an existing change |482 | `/opsx:ff` | Fast-forward: create all artifacts at once |483 | `/opsx:verify` | Verify implementation matches artifacts |484485---486487## What's Next?488489Try `/opsx:propose` on something you actually want to build. You've got the rhythm now!490```491492---493494## Graceful Exit Handling495496### User wants to stop mid-way497498If the user says they need to stop, want to pause, or seem disengaged:499500```501No problem! Your change is saved at the `changeRoot` reported by `openspec status --change "<name>" --json`.502503To pick up where we left off later:504- `/opsx:continue <name>` - Resume artifact creation505- `/opsx:apply <name>` - Jump to implementation (if tasks exist)506507The work won't be lost. Come back whenever you're ready.508```509510Exit gracefully without pressure.511512### User just wants command reference513514If the user says they just want to see the commands or skip the tutorial:515516```517## OpenSpec Quick Reference518519**Core workflow:**520521 | Command | What it does |522 |--------------------------|--------------------------------------------|523 | `/opsx:propose <name>` | Create a change and generate all artifacts |524 | `/opsx:explore` | Think through problems (no code changes) |525 | `/opsx:apply <name>` | Implement tasks |526 | `/opsx:archive <name>` | Archive when done |527528**Additional commands:**529530 | Command | What it does |531 |---------------------------|-------------------------------------|532 | `/opsx:new <name>` | Start a new change, step by step |533 | `/opsx:continue <name>` | Continue an existing change |534 | `/opsx:ff <name>` | Fast-forward: all artifacts at once |535 | `/opsx:verify <name>` | Verify implementation |536537Try `/opsx:propose` to start your first change.538```539540Exit gracefully.541542---543544## Guardrails545546- **Follow the EXPLAIN → DO → SHOW → PAUSE pattern** at key transitions (after explore, after proposal draft, after tasks, after archive)547- **Keep narration light** during implementation—teach without lecturing548- **Don't skip phases** even if the change is small—the goal is teaching the workflow549- **Pause for acknowledgment** at marked points, but don't over-pause550- **Handle exits gracefully**—never pressure the user to continue551- **Use real codebase tasks**—don't simulate or use fake examples552- **Adjust scope gently**—guide toward smaller tasks but respect user choice