openspec-onboard

name	openspec-onboard
description	Guided, narrated walkthrough of one complete OpenSpec cycle — explore, create a change, build proposal then sibling specs/design then tasks, implement, archive — using a real small task in the user's own codebase. Use for "walk me through OpenSpec", "teach me the OpenSpec workflow", "onboard me to OpenSpec", or a first-time user asking what OpenSpec even is. Does real work, not a simulation; teaches by doing rather than lecturing.
compatibility	Requires the openspec CLI on PATH; stops early with a clear message if it is not installed. The external grilling skill is optional — used only if a genuine design uncertainty comes up.

Onboard to OpenSpec

Teach the full OpenSpec cycle by actually running it, once, on a small real task — narrating each step as you go rather than lecturing first and doing later. Prefer invoking the real /openspec-* skills by name so the user learns the same triggers they will use later.

Preflight

Check the CLI is installed (openspec --version, or the PowerShell equivalent). If not installed, say so and stop: "OpenSpec CLI is not installed. Install it first, then come back to onboarding."

Check whether openspec/config.yaml and openspec/schemas/rhdh-spec-driven/ already exist. Only if either is missing, invoke /rhdh-spec-driven-schema and run its project-install step before creating a change.

Phase 1: Welcome

State what will happen: pick a small real task, explore it briefly, scaffold a change, draft proposal, then specs and design as siblings (either order; both depend only on proposal), then tasks, implement, archive — about 15-20 minutes. Then move to task selection.

Phase 2: Task selection

Scan the codebase for small opportunities: TODO/FIXME/HACK/XXX comments, swallowed errors or risky operations without try/catch, functions missing tests, any/as any in TypeScript, stray console.log/debugger, user input handlers missing validation. Check recent activity with git log --oneline -10. Present 3-4 specific, concretely-scoped suggestions (location, scope estimate, why it's good) plus a "something else?" option; let the user pick or describe their own. If nothing turns up, ask directly what small thing they've been meaning to fix.

Scope guardrail: if the chosen task is a major feature or multi-day work, say so and offer to slice it smaller, pick something else, or do it anyway — a soft guardrail; respect the user's choice if they insist on the larger scope.

Phase 3: Explore demo

Briefly demonstrate explore mode by invoking /openspec-explore on the chosen task: 1-2 minutes reading the relevant file(s), an ASCII diagram if it helps, a short note of considerations. Explain that this is what /openspec-explore is for — thinking before implementing, usable any time. Pause for acknowledgment before creating the change.

Phase 4: Create the change

Explain a "change" is a container for the work, living at openspec/changes/<name>/, holding proposal, specs, design, and tasks. Invoke /openspec-new-change for the derived kebab-case name — it scaffolds the folder and shows the first artifact template, then stops. Show the resulting folder structure.

Phase 5: Proposal

Explain the proposal captures why and what, at a high level. Invoke /openspec-continue-change so it drafts and writes exactly the next ready artifact (proposal). Pause for approval or feedback before moving on; if the user wants edits, revise proposal.md and continue.

Phase 6: Specs and design (siblings)

Explain that after proposal, specs and design are both ready: each depends only on proposal, not on each other, so either order (or parallel drafting in other workflows) is valid. For this walkthrough, invoke /openspec-continue-change twice — once for each — narrating which sibling you are writing and why. Typical teaching order is specs then design; if the user prefers design first, do that instead.

Optional: resolve open questions with grilling. If the design draft left a real trade-off unresolved — several plausible approaches, an ambiguous Decision, an open question you can't confidently answer for the user — offer to run the external /grilling skill on it before moving to tasks: "This design has an open question about <X>. Want to run a quick grilling pass to pin it down before we break it into tasks?" This is a soft offer, not a gate — if the user declines, or /grilling is not installed, say so (naming /setup-rhdh-skills install as the next step) and move on with the design as drafted. If the user accepts, invoke /grilling, fold the resolved answers back into design.md's Decisions, then continue. Skip this entirely when the design has no real open question — most small onboarding tasks won't.

Phase 7: Tasks

Explain tasks break the work into checkboxes that drive implementation, and that tasks require both specs and design. Invoke /openspec-continue-change to write tasks.md. Pause for confirmation the user is ready to implement.

Phase 8: Apply (implementation)

Invoke /openspec-apply-change for the change. Keep narration light — teach without over-explaining every line. After all tasks, confirm completion and move to archiving.

Phase 9: Archive

Explain archiving moves the change to openspec/changes/archive/YYYY-MM-DD-<name>/ and becomes part of the project's decision history. Invoke /openspec-archive-change for <name> and show the archive location.

Phase 10: Recap and next steps

Recap the cycle: Explore → New (scaffold) → Continue (proposal) → Continue (specs | design, either order) → Continue (tasks) → Apply → Archive. Show the command reference:

Command	What it does
/openspec-explore	Think through problems before/during work
/openspec-new-change	Scaffold a change directory; stop before drafting
/openspec-continue-change	Create exactly the next ready artifact
/openspec-ff-change	Generate every remaining artifact in one pass
/openspec-apply-change	Implement tasks from a change
/openspec-archive-change	Archive a completed change
/openspec-audit-change	Audit artifacts for cross-artifact consistency (pre-implementation)
/openspec-verify-change	Verify implementation matches artifacts (post-implementation)
/grilling (external, optional)	Resolve a genuinely open design question before moving to tasks

Close with: "Try /openspec-ff-change on something you actually want to build."

Graceful exit handling

User wants to stop mid-way: reassure the work is saved at openspec/changes/<name>/, and that /openspec-continue-change or /openspec-apply-change picks it back up later. Exit without pressure.

User just wants the command reference: show the table above (same content) and stop the tutorial there.

Guardrails

• Follow EXPLAIN -> DO -> SHOW -> PAUSE at key transitions (after explore, after the proposal draft, after tasks, after archive).
• Keep narration light during implementation — teach without lecturing.
• Don't skip phases even for a tiny change — the goal is teaching the rhythm, not speed.
• Do not teach a linear proposal -> specs -> design -> tasks dependency — specs and design are siblings.
• Pause for acknowledgment at marked points; don't over-pause elsewhere.
• Handle exits gracefully — never pressure the user to continue.
• Use a real codebase task — never simulate or fabricate one.
• Guide toward a smaller scope gently; respect the user's final choice.

Completion

Complete when the user has either finished a full real cycle through archive, or exited gracefully at a marked pause point with their change intact and saved — and, either way, can name which /openspec-* skill to reach for next.