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.