/onboard

name: "Specs: Onboard"
description: Guided onboarding - walk through a complete OpenSpec workflow cycle with narration
category: Workflow
tags: [workflow, onboarding, tutorial, learning]

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.

UUID Enforcement

**CRITICAL**: All conversation_id values used in this onboarding MUST be UUIDs (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`). Generate one with `uuidgen` if needed. NEVER use descriptive names like `onboard-demo` or `first-task`.

---

Preflight

Before starting, check if the conversations directory structure exists:

ls -d .scaffolding/conversations/ 2>/dev/null || echo "NOT_INITIALIZED"

**If not initialized:** > The conversations directory isn't set up yet. Let me create it.

Create `.scaffolding/conversations/` if it doesn't exist.

---

Phase 1: Welcome

Display:

## 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 specs directory (the container for our work)
4. Build the artifacts: proposal -> design -> tasks
5. Implement the tasks
6. Archive the completed change

**Time:** ~15-20 minutes

Let's start by finding something to work on.

---

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 2. **Missing error handling** - `catch` blocks that swallow errors, risky operations without try-catch 3. **Functions without tests** - Cross-reference `src/` with test directories 4. **Type issues** - `any` types in TypeScript files (`: any`, `as any`) 5. **Debug artifacts** - `console.log`, `console.debug`, `debugger` statements in non-debug code 6. **Missing validation** - User input handlers without validation

Also check recent git activity:

git log --oneline -10 2>/dev/null || echo "No git history"

Present Suggestions

From your analysis, present 3-4 specific suggestions:

## 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)

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

Scope Guardrail

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

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?

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

---

Phase 3: Explore Demo

Once a task is selected, briefly demonstrate explore mode:

Before we create a change, let me quickly show you **explore mode**--it's how you think through problems before committing to a direction.

Spend 1-2 minutes investigating the relevant code:

• Read the file(s) involved
• Draw a quick ASCII diagram if it helps
• Note any considerations

## Quick Exploration

[Your brief analysis--what you found, any considerations]

+------------------------------------------+
|   [Optional: ASCII diagram if helpful]   |
+------------------------------------------+

Explore mode (`/specs: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 specs directory to hold our work.

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

---

Phase 4: Create the Specs Directory

**EXPLAIN:**

## Creating a Specs Directory

In this workflow, specs live in the conversation directory: `.scaffolding/conversations/{conversation_id}/specs/`. The conversation_id is always a UUID -- a unique identifier for this conversation.

Let me create one for our task.

**DO:** Generate a UUID and create the specs directory:

# Generate UUID for this conversation
CONV_ID=$(uuidgen || python3 -c "import uuid; print(uuid.uuid4())")
mkdir -p .scaffolding/conversations/$CONV_ID/specs/

**SHOW:**

Created: `.scaffolding/conversations/{conversation_id}/specs/`

The folder structure:

.scaffolding/conversations/{conversation_id}/specs/ ├── proposal.md <- Why we're doing this (to be created) ├── design.md <- How we'll build it (to be created) └── tasks.md <- Implementation checklist (to be created)

Now let's fill in the first artifact--the proposal.

---

Phase 5: Proposal

**EXPLAIN:**

## 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.

**DO:** Draft the proposal content using the template at `.scaffolding/openspec/schemas/scaffolding-workflow/templ