[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7C8SA9T4EPNH0J8WT5RS3W3":3,"skill-same:01M7C8SA9T4EPNH0J8WT5RS3W3":50},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":29,"commitSha":30,"skillDirectory":31,"forksCount":14,"repositoryHtmlUrl":32,"repositoryHomepageUrl":6,"ownerHtmlUrl":33,"ownerBlogUrl":6,"ownerDescription":34,"updatedAt":35,"install":36,"resources":49},"01M7C8SA9T4EPNH0J8WT5RS3W3","openspec-onboard",null,"Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.","sung1-labs\u002Fsddx","sung1-labs","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F325716214?v=4","01M7C7MDYAWVBFW42T3YCQYG7N","SunG1 Labs","01M7C7MDYZYBYQ5FNSK0XN0YY2",0,"MIT","https:\u002F\u002Fgithub.com\u002Fsung1-labs\u002Fsddx\u002Fblob\u002Fmain\u002Fskills\u002Flibrary\u002Fopenspec\u002Fsddx-openspec-openspec-onboard\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: openspec-onboard\ndescription: Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.\nallowed-tools: Bash(openspec:*)\nlicense: MIT\ncompatibility: Requires openspec CLI.\nmetadata:\n  author: openspec\n  version: \"1.0\"\n---\n\nGuide 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.\n\n**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 \u003Cid>` 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 \u003Cid>` 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 \"\u003Cname>\" --json --store \"\u003Cid>\"`, 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\u002F` root.\n\n---\n\n## Preflight\n\nBefore starting, check if the OpenSpec CLI is installed:\n\n```bash\n# Unix\u002FmacOS\nopenspec --version 2>&1 || echo \"CLI_NOT_INSTALLED\"\n# Windows (PowerShell)\n# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo \"CLI_NOT_INSTALLED\" }\n```\n\n**If CLI not installed:**\n> OpenSpec CLI is not installed. Install it first, then come back to `\u002Fopenspec-onboard`.\n\nStop here if not installed.\n\n---\n\n## Phase 1: Welcome\n\nDisplay:\n\n```\n## Welcome to OpenSpec!\n\nI'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.\n\n**What we'll do:**\n1. Pick a small, real task in your codebase\n2. Explore the problem briefly\n3. Create a change (the container for our work)\n4. Build the artifacts: proposal → specs → design → tasks\n5. Implement the tasks\n6. Archive the completed change\n\n**Time:** ~15-20 minutes\n\nLet's start by finding something to work on.\n```\n\n---\n\n## Phase 2: Task Selection\n\n### Codebase Analysis\n\nScan the codebase for small improvement opportunities. Look for:\n\n1. **TODO\u002FFIXME comments** - Search for `TODO`, `FIXME`, `HACK`, `XXX` in code files\n2. **Missing error handling** - `catch` blocks that swallow errors, risky operations without try-catch\n3. **Functions without tests** - Cross-reference `src\u002F` with test directories\n4. **Type issues** - `any` types in TypeScript files (`: any`, `as any`)\n5. **Debug artifacts** - `console.log`, `console.debug`, `debugger` statements in non-debug code\n6. **Missing validation** - User input handlers without validation\n\nAlso check recent git activity:\n```bash\n# Unix\u002FmacOS\ngit log --oneline -10 2>\u002Fdev\u002Fnull || echo \"No git history\"\n# Windows (PowerShell)\n# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo \"No git history\" }\n```\n\n### Present Suggestions\n\nFrom your analysis, present 3-4 specific suggestions:\n\n```\n## Task Suggestions\n\nBased on scanning your codebase, here are some good starter tasks:\n\n**1. [Most promising task]**\n   Location: `src\u002Fpath\u002Fto\u002Ffile.ts:42`\n   Scope: ~1-2 files, ~20-30 lines\n   Why it's good: [brief reason]\n\n**2. [Second task]**\n   Location: `src\u002Fanother\u002Ffile.ts`\n   Scope: ~1 file, ~15 lines\n   Why it's good: [brief reason]\n\n**3. [Third task]**\n   Location: [location]\n   Scope: [estimate]\n   Why it's good: [brief reason]\n\n**4. Something else?**\n   Tell me what you'd like to work on.\n\nWhich task interests you? (Pick a number or describe your own)\n```\n\n**If nothing found:** Fall back to asking what the user wants to build:\n> I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix?\n\n### Scope Guardrail\n\nIf the user picks or describes something too large (major feature, multi-day work):\n\n```\nThat's a valuable task, but it's probably larger than ideal for your first OpenSpec run-through.\n\nFor learning the workflow, smaller is better—it lets you see the full cycle without getting stuck in implementation details.\n\n**Options:**\n1. **Slice it smaller** - What's the smallest useful piece of [their task]? Maybe just [specific slice]?\n2. **Pick something else** - One of the other suggestions, or a different small task?\n3. **Do it anyway** - If you really want to tackle this, we can. Just know it'll take longer.\n\nWhat would you prefer?\n```\n\nLet the user override if they insist—this is a soft guardrail.\n\n---\n\n## Phase 3: Explore Demo\n\nOnce a task is selected, briefly demonstrate explore mode:\n\n```\nBefore we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction.\n```\n\nSpend 1-2 minutes investigating the relevant code:\n- Read the file(s) involved\n- Draw a quick ASCII diagram if it helps\n- Note any considerations\n\n```\n## Quick Exploration\n\n[Your brief analysis—what you found, any considerations]\n\n┌─────────────────────────────────────────┐\n│   [Optional: ASCII diagram if helpful]  │\n└─────────────────────────────────────────┘\n\nExplore mode (`\u002Fopenspec-explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem.\n\nNow let's create a change to hold our work.\n```\n\n**PAUSE** - Wait for user acknowledgment before proceeding.\n\n---\n\n## Phase 4: Create the Change\n\n**EXPLAIN:**\n```\n## Creating a Change\n\nA \"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 \"\u003Cname>\" --json` and holds your artifacts—proposal, specs, design, tasks.\n\nLet me create one for our task.\n```\n\n**DO:** Create the change with a derived kebab-case name:\n```bash\nopenspec new change \"\u003Cderived-name>\"\n```\n\n**SHOW:**\n```\nCreated: \u003CchangeRoot from status JSON>\n\nThe folder structure:\n```\n\u003CchangeRoot>\u002F\n├── proposal.md    ← Why we're doing this (empty, we'll fill it)\n├── design.md      ← How we'll build it (empty)\n├── specs\u002F         ← Detailed requirements (empty)\n└── tasks.md       ← Implementation checklist (empty)\n```\n\nNow let's fill in the first artifact—the proposal.\n```\n\n---\n\n## Phase 5: Proposal\n\n**EXPLAIN:**\n```\n## The Proposal\n\nThe proposal captures **why** we're making this change and **what** it involves at a high level. It's the \"elevator pitch\" for the work.\n\nI'll draft one based on our task.\n```\n\n**DO:** Draft the proposal content (don't save yet):\n\n`\u003Ccapability-path>` is the spec directory relative to `specs\u002F` (for example,\n`user-auth` or `identity\u002Fuser-auth`). Use the exact existing path for modified\ncapabilities. For new capabilities, follow the project's established spec\norganization.\n\n```\nHere's a draft proposal:\n\n---\n\n## Why\n\n[1-2 sentences explaining the problem\u002Fopportunity]\n\n## What Changes\n\n[Bullet points of what will be different]\n\n## Capabilities\n\n### New Capabilities\n- `\u003Ccapability-path>`: [brief description]\n\n### Modified Capabilities\n\u003C!-- If modifying existing behavior -->\n- `\u003Cexisting-capability-path>`: [brief description]\n\n## Impact\n\n- `src\u002Fpath\u002Fto\u002Ffile.ts`: [what changes]\n- [other files if applicable]\n\n---\n\nDoes this capture the intent? I can adjust before we save it.\n```\n\n**PAUSE** - Wait for user approval\u002Ffeedback.\n\nAfter approval, save the proposal:\n```bash\nopenspec instructions proposal --change \"\u003Cname>\" --json\n```\nThen write the content to the `resolvedOutputPath` from `openspec instructions proposal --change \"\u003Cname>\" --json`.\n\n```\nProposal saved. This is your \"why\" document—you can always come back and refine it as understanding evolves.\n\nNext up: specs.\n```\n\n---\n\n## Phase 6: Specs\n\n**EXPLAIN:**\n```\n## Specs\n\nSpecs define **what** we're building in precise, testable terms. They use a requirement\u002Fscenario format that makes expected behavior crystal clear.\n\nFor a small task like this, we might only need one spec file.\n```\n\n**DO:** Resolve where the spec file should be created:\n```bash\nopenspec instructions specs --change \"\u003Cname>\" --json\n# Use resolvedOutputPath from the JSON. If it is a glob, choose the concrete file path using the schema instruction and the change's context.\n```\n\nDraft the spec content:\n\n```\nHere's the spec:\n\n---\n\n## ADDED Requirements\n\n### Requirement: \u003CName>\n\n\u003CDescription of what the system should do>\n\n#### Scenario: \u003CScenario name>\n\n- **WHEN** \u003Ctrigger condition>\n- **THEN** \u003Cexpected outcome>\n- **AND** \u003Cadditional outcome if needed>\n\n---\n\nThis format—WHEN\u002FTHEN\u002FAND—makes requirements testable. You can literally read them as test cases.\n```\n\nSave to the concrete file path chosen from `resolvedOutputPath`.\n\n---\n\n## Phase 7: Design\n\n**EXPLAIN:**\n```\n## Design\n\nThe design captures **how** we'll build it—technical decisions, tradeoffs, approach.\n\nFor small changes, this might be brief. That's fine—not every change needs deep design discussion.\n```\n\n**DO:** Draft design.md:\n\n```\nHere's the design:\n\n---\n\n## Context\n\n[Brief context about the current state]\n\n## Goals \u002F Non-Goals\n\n**Goals:**\n- [What we're trying to achieve]\n\n**Non-Goals:**\n- [What's explicitly out of scope]\n\n## Decisions\n\n### Decision 1: [Key decision]\n\n[Explanation of approach and rationale]\n\n---\n\nFor a small task, this captures the key decisions without over-engineering.\n```\n\nSave to the `resolvedOutputPath` from `openspec instructions design --change \"\u003Cname>\" --json`.\n\n---\n\n## Phase 8: Tasks\n\n**EXPLAIN:**\n```\n## Tasks\n\nFinally, we break the work into implementation tasks—checkboxes that drive the apply phase.\n\nThese should be small, clear, and in logical order.\n```\n\n**DO:** Generate tasks based on specs and design:\n\n```\nHere are the implementation tasks:\n\n---\n\n## 1. [Category or file]\n\n- [ ] 1.1 [Specific task] — verify: [test, command, observable behavior, or delivered artifact]\n- [ ] 1.2 [Specific task] — verify: [test, command, observable behavior, or delivered artifact]\n\n## 2. Integration Verification\n\n- [ ] 2.1 Verify [broader integration or system behavior] with [end-to-end test or observable result]\n\n---\n\nEach checkbox becomes a unit of work in the apply phase. Ready to implement?\n```\n\n**PAUSE** - Wait for user to confirm they're ready to implement.\n\nSave to the `resolvedOutputPath` from `openspec instructions tasks --change \"\u003Cname>\" --json`.\n\n---\n\n## Phase 9: Apply (Implementation)\n\n**EXPLAIN:**\n```\n## Implementation\n\nNow we implement each task, checking them off as we go. I'll announce each one and occasionally note how the specs\u002Fdesign informed the approach.\n```\n\n**DO:** For each task:\n\n1. Announce: \"Working on task N: [description]\"\n2. Implement the change in the codebase\n3. Reference specs\u002Fdesign naturally: \"The spec says X, so I'm doing Y\"\n4. Mark complete in tasks.md: `- [ ]` → `- [x]`\n5. Brief status: \"✓ Task N complete\"\n\nKeep narration light—don't over-explain every line of code.\n\nAfter all tasks:\n\n```\n## Implementation Complete\n\nAll tasks done:\n- [x] Task 1\n- [x] Task 2\n- [x] ...\n\nThe change is implemented! One more step—let's archive it.\n```\n\n---\n\n## Phase 10: Archive\n\n**EXPLAIN:**\n```\n## Archiving\n\nWhen a change is complete, we archive it. The archive path is derived from `planningHome.changesDir` and the date.\n\nArchived changes become your project's decision history—you can always find them later to understand why something was built a certain way.\n```\n\n**DO:** Archive the change (`--yes` answers the confirmation prompts, which you cannot answer from a tool call):\n```bash\nopenspec archive \"\u003Cname>\" --yes\n```\n\n**SHOW:**\n```\nArchived to: `\u003CplanningHome.changesDir>\u002Farchive\u002F\u003Ctarget-name>\u002F` (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)\n\nThe change is now part of your project's history. The code is in your codebase, the decision record is preserved.\n```\n\n---\n\n## Phase 11: Recap & Next Steps\n\n```\n## Congratulations!\n\nYou just completed a full OpenSpec cycle:\n\n1. **Explore** - Thought through the problem\n2. **New** - Created a change container\n3. **Proposal** - Captured WHY\n4. **Specs** - Defined WHAT in detail\n5. **Design** - Decided HOW\n6. **Tasks** - Broke it into steps\n7. **Apply** - Implemented the work\n8. **Archive** - Preserved the record\n\nThis same rhythm works for any size change—a small fix or a major feature.\n\n---\n\n## Command Reference\n\n**Core workflow:**\n\n | Command           | What it does                               |\n |-------------------|--------------------------------------------|\n | `\u002Fopenspec-propose` | Create a change and generate all artifacts |\n | `\u002Fopenspec-explore` | Think through problems before\u002Fduring work  |\n | `\u002Fopenspec-apply-change`   | Implement tasks from a change              |\n | `\u002Fopenspec-archive-change` | Archive a completed change                 |\n\n**Additional commands** (only if installed - availability depends on your profile):\n\n | Command            | What it does                                             |\n |--------------------|----------------------------------------------------------|\n | `\u002Fopenspec-new-change`      | Start a new change, step through artifacts one at a time |\n | `\u002Fopenspec-continue-change` | Continue working on an existing change                   |\n | `\u002Fopenspec-ff-change`       | Fast-forward: create all artifacts at once               |\n | `\u002Fopenspec-verify-change`   | Verify implementation matches artifacts                  |\n\n---\n\n## What's Next?\n\nTry `\u002Fopenspec-propose` on something you actually want to build. You've got the rhythm now!\n```\n\n---\n\n## Graceful Exit Handling\n\n### User wants to stop mid-way\n\nIf the user says they need to stop, want to pause, or seem disengaged:\n\n```\nNo problem! Your change is saved at the `changeRoot` reported by `openspec status --change \"\u003Cname>\" --json`.\n\nTo pick up where we left off later:\n- `\u002Fopenspec-continue-change \u003Cname>` - Resume artifact creation (if installed; otherwise `openspec status --change \"\u003Cname>\" --json` shows the next artifact)\n- `\u002Fopenspec-apply-change \u003Cname>` - Jump to implementation (if tasks exist)\n\nThe work won't be lost. Come back whenever you're ready.\n```\n\nExit gracefully without pressure.\n\n### User just wants command reference\n\nIf the user says they just want to see the commands or skip the tutorial:\n\n```\n## OpenSpec Quick Reference\n\n**Core workflow:**\n\n | Command                  | What it does                               |\n |--------------------------|--------------------------------------------|\n | `\u002Fopenspec-propose \u003Cname>` | Create a change and generate all artifacts |\n | `\u002Fopenspec-explore`        | Think through problems (no code changes)   |\n | `\u002Fopenspec-apply-change \u003Cname>`   | Implement tasks                            |\n | `\u002Fopenspec-archive-change \u003Cname>` | Archive when done                          |\n\n**Additional commands** (only if installed - availability depends on your profile):\n\n | Command                   | What it does                        |\n |---------------------------|-------------------------------------|\n | `\u002Fopenspec-new-change \u003Cname>`      | Start a new change, step by step    |\n | `\u002Fopenspec-continue-change \u003Cname>` | Continue an existing change         |\n | `\u002Fopenspec-ff-change \u003Cname>`       | Fast-forward: all artifacts at once |\n | `\u002Fopenspec-verify-change \u003Cname>`   | Verify implementation               |\n\nTry `\u002Fopenspec-propose` to start your first change.\n```\n\nExit gracefully.\n\n---\n\n## Guardrails\n\n- **Follow the EXPLAIN → DO → SHOW → PAUSE pattern** at key transitions (after explore, after proposal draft, after tasks, after archive)\n- **Keep narration light** during implementation—teach without lecturing\n- **Don't skip phases** even if the change is small—the goal is teaching the workflow\n- **Pause for acknowledgment** at marked points, but don't over-pause\n- **Handle exits gracefully**—never pressure the user to continue\n- **Use real codebase tasks**—don't simulate or use fake examples\n- **Adjust scope gently**—guide toward smaller tasks but respect user choice\n","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.\n\n**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 \u003Cid>` 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 \u003Cid>` 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 \"\u003Cname>\" --json --store \"\u003Cid>\"`, 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\u002F` root.\n\n---\n\n## Preflight\n\nBefore starting, check if the OpenSpec CLI is installed:\n\n```bash\n# Unix\u002FmacOS\nopenspec --version 2>&1 || echo \"CLI_NOT_INSTALLED\"\n# Windows (PowerShell)\n# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo \"CLI_NOT_INSTALLED\" }\n```\n\n**If CLI not installed:**\n> OpenSpec CLI is not installed. Install it first, then come back to `\u002Fopenspec-onboard`.\n\nStop here if not installed.\n\n---\n\n## Phase 1: Welcome\n\nDisplay:\n\n```\n## Welcome to OpenSpec!\n\nI'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.\n\n**What we'll do:**\n1. Pick a small, real task in your codebase\n2. Explore the problem briefly\n3. Create a change (the container for our work)\n4. Build the artifacts: proposal → specs → design → tasks\n5. Implement the tasks\n6. Archive the completed change\n\n**Time:** ~15-20 minutes\n\nLet's start by finding something to work on.\n```\n\n---\n\n## Phase 2: Task Selection\n\n### Codebase Analysis\n\nScan the codebase for small improvement opportunities. Look for:\n\n1. **TODO\u002FFIXME comments** - Search for `TODO`, `FIXME`, `HACK`, `XXX` in code files\n2. **Missing error handling** - `catch` blocks that swallow errors, risky operations without try-catch\n3. **Functions without tests** - Cross-reference `src\u002F` with test directories\n4. **Type issues** - `any` types in TypeScript files (`: any`, `as any`)\n5. **Debug artifacts** - `console.log`, `console.debug`, `debugger` statements in non-debug code\n6. **Missing validation** - User input handlers without validation\n\nAlso check recent git activity:\n```bash\n# Unix\u002FmacOS\ngit log --oneline -10 2>\u002Fdev\u002Fnull || echo \"No git history\"\n# Windows (PowerShell)\n# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo \"No git history\" }\n```\n\n### Present Suggestions\n\nFrom your analysis, present 3-4 specific suggestions:\n\n```\n## Task Suggestions\n\nBased on scanning your codebase, here are some good starter tasks:\n\n**1. [Most promising task]**\n   Location: `src\u002Fpath\u002Fto\u002Ffile.ts:42`\n   Scope: ~1-2 files, ~20-30 lines\n   Why it's good: [brief reason]\n\n**2. [Second task]**\n   Location: `src\u002Fanother\u002Ffile.ts`\n   Scope: ~1 file, ~15 lines\n   Why it's good: [brief reason]\n\n**3. [Third task]**\n   Location: [location]\n   Scope: [estimate]\n   Why it's good: [brief reason]\n\n**4. Something else?**\n   Tell me what you'd like to work on.\n\nWhich task interests you? (Pick a number or describe your own)\n```\n\n**If nothing found:** Fall back to asking what the user wants to build:\n> I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix?\n\n### Scope Guardrail\n\nIf the user picks or describes something too large (major feature, multi-day work):\n\n```\nThat's a valuable task, but it's probably larger than ideal for your first OpenSpec run-through.\n\nFor learning the workflow, smaller is better—it lets you see the full cycle without getting stuck in implementation details.\n\n**Options:**\n1. **Slice it smaller** - What's the smallest useful piece of [their task]? Maybe just [specific slice]?\n2. **Pick something else** - One of the other suggestions, or a different small task?\n3. **Do it anyway** - If you really want to tackle this, we can. Just know it'll take longer.\n\nWhat would you prefer?\n```\n\nLet the user override if they insist—this is a soft guardrail.\n\n---\n\n## Phase 3: Explore Demo\n\nOnce a task is selected, briefly demonstrate explore mode:\n\n```\nBefore we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction.\n```\n\nSpend 1-2 minutes investigating the relevant code:\n- Read the file(s) involved\n- Draw a quick ASCII diagram if it helps\n- Note any considerations\n\n```\n## Quick Exploration\n\n[Your brief analysis—what you found, any considerations]\n\n┌─────────────────────────────────────────┐\n│   [Optional: ASCII diagram if helpful]  │\n└─────────────────────────────────────────┘\n\nExplore mode (`\u002Fopenspec-explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem.\n\nNow let's create a change to hold our work.\n```\n\n**PAUSE** - Wait for user acknowledgment before proceeding.\n\n---\n\n## Phase 4: Create the Change\n\n**EXPLAIN:**\n```\n## Creating a Change\n\nA \"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 \"\u003Cname>\" --json` and holds your artifacts—proposal, specs, design, tasks.\n\nLet me create one for our task.\n```\n\n**DO:** Create the change with a derived kebab-case name:\n```bash\nopenspec new change \"\u003Cderived-name>\"\n```\n\n**SHOW:**\n```\nCreated: \u003CchangeRoot from status JSON>\n\nThe folder structure:\n```\n\u003CchangeRoot>\u002F\n├── proposal.md    ← Why we're doing this (empty, we'll fill it)\n├── design.md      ← How we'll build it (empty)\n├── specs\u002F         ← Detailed requirements (empty)\n└── tasks.md       ← Implementation checklist (empty)\n```\n\nNow let's fill in the first artifact—the proposal.\n```\n\n---\n\n## Phase 5: Proposal\n\n**EXPLAIN:**\n```\n## The Proposal\n\nThe proposal captures **why** we're making this change and **what** it involves at a high level. It's the \"elevator pitch\" for the work.\n\nI'll draft one based on our task.\n```\n\n**DO:** Draft the proposal content (don't save yet):\n\n`\u003Ccapability-path>` is the spec directory relative to `specs\u002F` (for example,\n`user-auth` or `identity\u002Fuser-auth`). Use the exact existing path for modified\ncapabilities. For new capabilities, follow the project's established spec\norganization.\n\n```\nHere's a draft proposal:\n\n---\n\n## Why\n\n[1-2 sentences explaining the problem\u002Fopportunity]\n\n## What Changes\n\n[Bullet points of what will be different]\n\n## Capabilities\n\n### New Capabilities\n- `\u003Ccapability-path>`: [brief description]\n\n### Modified Capabilities\n\u003C!-- If modifying existing behavior -->\n- `\u003Cexisting-capability-path>`: [brief description]\n\n## Impact\n\n- `src\u002Fpath\u002Fto\u002Ffile.ts`: [what changes]\n- [other files if applicable]\n\n---\n\nDoes this capture the intent? I can adjust before we save it.\n```\n\n**PAUSE** - Wait for user approval\u002Ffeedback.\n\nAfter approval, save the proposal:\n```bash\nopenspec instructions proposal --change \"\u003Cname>\" --json\n```\nThen write the content to the `resolvedOutputPath` from `openspec instructions proposal --change \"\u003Cname>\" --json`.\n\n```\nProposal saved. This is your \"why\" document—you can always come back and refine it as understanding evolves.\n\nNext up: specs.\n```\n\n---\n\n## Phase 6: Specs\n\n**EXPLAIN:**\n```\n## Specs\n\nSpecs define **what** we're building in precise, testable terms. They use a requirement\u002Fscenario format that makes expected behavior crystal clear.\n\nFor a small task like this, we might only need one spec file.\n```\n\n**DO:** Resolve where the spec file should be created:\n```bash\nopenspec instructions specs --change \"\u003Cname>\" --json\n# Use resolvedOutputPath from the JSON. If it is a glob, choose the concrete file path using the schema instruction and the change's context.\n```\n\nDraft the spec content:\n\n```\nHere's the spec:\n\n---\n\n## ADDED Requirements\n\n### Requirement: \u003CName>\n\n\u003CDescription of what the system should do>\n\n#### Scenario: \u003CScenario name>\n\n- **WHEN** \u003Ctrigger condition>\n- **THEN** \u003Cexpected outcome>\n- **AND** \u003Cadditional outcome if needed>\n\n---\n\nThis format—WHEN\u002FTHEN\u002FAND—makes requirements testable. You can literally read them as test cases.\n```\n\nSave to the concrete file path chosen from `resolvedOutputPath`.\n\n---\n\n## Phase 7: Design\n\n**EXPLAIN:**\n```\n## Design\n\nThe design captures **how** we'll build it—technical decisions, tradeoffs, approach.\n\nFor small changes, this might be brief. That's fine—not every change needs deep design discussion.\n```\n\n**DO:** Draft design.md:\n\n```\nHere's the design:\n\n---\n\n## Context\n\n[Brief context about the current state]\n\n## Goals \u002F Non-Goals\n\n**Goals:**\n- [What we're trying to achieve]\n\n**Non-Goals:**\n- [What's explicitly out of scope]\n\n## Decisions\n\n### Decision 1: [Key decision]\n\n[Explanation of approach and rationale]\n\n---\n\nFor a small task, this captures the key decisions without over-engineering.\n```\n\nSave to the `resolvedOutputPath` from `openspec instructions design --change \"\u003Cname>\" --json`.\n\n---\n\n## Phase 8: Tasks\n\n**EXPLAIN:**\n```\n## Tasks\n\nFinally, we break the work into implementation tasks—checkboxes that drive the apply phase.\n\nThese should be small, clear, and in logical order.\n```\n\n**DO:** Generate tasks based on specs and design:\n\n```\nHere are the implementation tasks:\n\n---\n\n## 1. [Category or file]\n\n- [ ] 1.1 [Specific task] — verify: [test, command, observable behavior, or delivered artifact]\n- [ ] 1.2 [Specific task] — verify: [test, command, observable behavior, or delivered artifact]\n\n## 2. Integration Verification\n\n- [ ] 2.1 Verify [broader integration or system behavior] with [end-to-end test or observable result]\n\n---\n\nEach checkbox becomes a unit of work in the apply phase. Ready to implement?\n```\n\n**PAUSE** - Wait for user to confirm they're ready to implement.\n\nSave to the `resolvedOutputPath` from `openspec instructions tasks --change \"\u003Cname>\" --json`.\n\n---\n\n## Phase 9: Apply (Implementation)\n\n**EXPLAIN:**\n```\n## Implementation\n\nNow we implement each task, checking them off as we go. I'll announce each one and occasionally note how the specs\u002Fdesign informed the approach.\n```\n\n**DO:** For each task:\n\n1. Announce: \"Working on task N: [description]\"\n2. Implement the change in the codebase\n3. Reference specs\u002Fdesign naturally: \"The spec says X, so I'm doing Y\"\n4. Mark complete in tasks.md: `- [ ]` → `- [x]`\n5. Brief status: \"✓ Task N complete\"\n\nKeep narration light—don't over-explain every line of code.\n\nAfter all tasks:\n\n```\n## Implementation Complete\n\nAll tasks done:\n- [x] Task 1\n- [x] Task 2\n- [x] ...\n\nThe change is implemented! One more step—let's archive it.\n```\n\n---\n\n## Phase 10: Archive\n\n**EXPLAIN:**\n```\n## Archiving\n\nWhen a change is complete, we archive it. The archive path is derived from `planningHome.changesDir` and the date.\n\nArchived changes become your project's decision history—you can always find them later to understand why something was built a certain way.\n```\n\n**DO:** Archive the change (`--yes` answers the confirmation prompts, which you cannot answer from a tool call):\n```bash\nopenspec archive \"\u003Cname>\" --yes\n```\n\n**SHOW:**\n```\nArchived to: `\u003CplanningHome.changesDir>\u002Farchive\u002F\u003Ctarget-name>\u002F` (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)\n\nThe change is now part of your project's history. The code is in your codebase, the decision record is preserved.\n```\n\n---\n\n## Phase 11: Recap & Next Steps\n\n```\n## Congratulations!\n\nYou just completed a full OpenSpec cycle:\n\n1. **Explore** - Thought through the problem\n2. **New** - Created a change container\n3. **Proposal** - Captured WHY\n4. **Specs** - Defined WHAT in detail\n5. **Design** - Decided HOW\n6. **Tasks** - Broke it into steps\n7. **Apply** - Implemented the work\n8. **Archive** - Preserved the record\n\nThis same rhythm works for any size change—a small fix or a major feature.\n\n---\n\n## Command Reference\n\n**Core workflow:**\n\n | Command           | What it does                               |\n |-------------------|--------------------------------------------|\n | `\u002Fopenspec-propose` | Create a change and generate all artifacts |\n | `\u002Fopenspec-explore` | Think through problems before\u002Fduring work  |\n | `\u002Fopenspec-apply-change`   | Implement tasks from a change              |\n | `\u002Fopenspec-archive-change` | Archive a completed change                 |\n\n**Additional commands** (only if installed - availability depends on your profile):\n\n | Command            | What it does                                             |\n |--------------------|----------------------------------------------------------|\n | `\u002Fopenspec-new-change`      | Start a new change, step through artifacts one at a time |\n | `\u002Fopenspec-continue-change` | Continue working on an existing change                   |\n | `\u002Fopenspec-ff-change`       | Fast-forward: create all artifacts at once               |\n | `\u002Fopenspec-verify-change`   | Verify implementation matches artifacts                  |\n\n---\n\n## What's Next?\n\nTry `\u002Fopenspec-propose` on something you actually want to build. You've got the rhythm now!\n```\n\n---\n\n## Graceful Exit Handling\n\n### User wants to stop mid-way\n\nIf the user says they need to stop, want to pause, or seem disengaged:\n\n```\nNo problem! Your change is saved at the `changeRoot` reported by `openspec status --change \"\u003Cname>\" --json`.\n\nTo pick up where we left off later:\n- `\u002Fopenspec-continue-change \u003Cname>` - Resume artifact creation (if installed; otherwise `openspec status --change \"\u003Cname>\" --json` shows the next artifact)\n- `\u002Fopenspec-apply-change \u003Cname>` - Jump to implementation (if tasks exist)\n\nThe work won't be lost. Come back whenever you're ready.\n```\n\nExit gracefully without pressure.\n\n### User just wants command reference\n\nIf the user says they just want to see the commands or skip the tutorial:\n\n```\n## OpenSpec Quick Reference\n\n**Core workflow:**\n\n | Command                  | What it does                               |\n |--------------------------|--------------------------------------------|\n | `\u002Fopenspec-propose \u003Cname>` | Create a change and generate all artifacts |\n | `\u002Fopenspec-explore`        | Think through problems (no code changes)   |\n | `\u002Fopenspec-apply-change \u003Cname>`   | Implement tasks                            |\n | `\u002Fopenspec-archive-change \u003Cname>` | Archive when done                          |\n\n**Additional commands** (only if installed - availability depends on your profile):\n\n | Command                   | What it does                        |\n |---------------------------|-------------------------------------|\n | `\u002Fopenspec-new-change \u003Cname>`      | Start a new change, step by step    |\n | `\u002Fopenspec-continue-change \u003Cname>` | Continue an existing change         |\n | `\u002Fopenspec-ff-change \u003Cname>`       | Fast-forward: all artifacts at once |\n | `\u002Fopenspec-verify-change \u003Cname>`   | Verify implementation               |\n\nTry `\u002Fopenspec-propose` to start your first change.\n```\n\nExit gracefully.\n\n---\n\n## Guardrails\n\n- **Follow the EXPLAIN → DO → SHOW → PAUSE pattern** at key transitions (after explore, after proposal draft, after tasks, after archive)\n- **Keep narration light** during implementation—teach without lecturing\n- **Don't skip phases** even if the change is small—the goal is teaching the workflow\n- **Pause for acknowledgment** at marked points, but don't over-pause\n- **Handle exits gracefully**—never pressure the user to continue\n- **Use real codebase tasks**—don't simulate or use fake examples\n- **Adjust scope gently**—guide toward smaller tasks but respect user choice\n",{"name":5,"license":15,"metadata":24,"description":7,"allowed-tools":27,"compatibility":28},{"author":25,"version":26},"openspec","1.0","Bash(openspec:*)","Requires openspec CLI.","main","7d9c45c72ac89da53a28423808dabd6dc0be6795","skills\u002Flibrary\u002Fopenspec\u002Fsddx-openspec-openspec-onboard","https:\u002F\u002Fgithub.com\u002Fsung1-labs\u002Fsddx","https:\u002F\u002Fgithub.com\u002Fsung1-labs","Building open-source tools for AI-assisted software development, spec-driven engineering, and reliable developer workflows.","2026-09-07 02:51:20",{"source":8,"skillName":5,"commands":37,"prompt":47,"zipAvailable":48},[38,41,44],{"tool":39,"command":40},"npx","npx skills add sung1-labs\u002Fsddx --skill openspec-onboard",{"tool":42,"command":43},"bunx","bunx skills add sung1-labs\u002Fsddx --skill openspec-onboard",{"tool":45,"command":46},"pnpm","pnpm dlx skills add sung1-labs\u002Fsddx --skill openspec-onboard","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fsung1-labs\u002Fsddx\u002Fblob\u002Fmain\u002Fskills\u002Flibrary\u002Fopenspec\u002Fsddx-openspec-openspec-onboard\u002FSKILL.md",true,[],[51,58,65,72,79,86],{"skillNo":52,"name":53,"nameZh":6,"description":54,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":55,"categories":56,"keywords":57,"publishedAt":19},"01M7C8TCN2HNT036445CS1VBHT","sddx-verify","Verify the complete SDDx change against its specifications, architecture, implementation, tests, security, operations, and deployment expectations.","https:\u002F\u002Fgithub.com\u002Fsung1-labs\u002Fsddx\u002Fblob\u002Fmain\u002Fskills\u002Fworkflow\u002Fsddx-verify\u002FSKILL.md",[],[],{"skillNo":59,"name":60,"nameZh":6,"description":61,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":19},"01M7C8T9FQKTSN971MP6RSV0GK","sddx-quick","Handle a small, bounded change with minimal durable artifacts while preserving verification and automatic escalation when scope grows.","https:\u002F\u002Fgithub.com\u002Fsung1-labs\u002Fsddx\u002Fblob\u002Fmain\u002Fskills\u002Fworkflow\u002Fsddx-quick\u002FSKILL.md",[],[],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":19},"01M7C8T6C21FE8ZX8XDSJ5VJ5R","sddx-propose","Turn a resolved SDDx exploration into durable proposal, requirements, design, tasks, and optional RFC artifacts.","https:\u002F\u002Fgithub.com\u002Fsung1-labs\u002Fsddx\u002Fblob\u002Fmain\u002Fskills\u002Fworkflow\u002Fsddx-propose\u002FSKILL.md",[],[],{"skillNo":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":19},"01M7C8T2QDGTK9PPG4A3JXXS28","sddx-explore","Explore a change before implementation, resolve the applicable product, UX, architecture, security, testing, deployment, and operational questions, and recommend the next SDDx workflow.","https:\u002F\u002Fgithub.com\u002Fsung1-labs\u002Fsddx\u002Fblob\u002Fmain\u002Fskills\u002Fworkflow\u002Fsddx-explore\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":19},"01M7C8SZ9GTETBRKEXT43EZ9G9","sddx-debug","Diagnose and fix a defect through reproduction, evidence-based hypotheses, a minimal fix, regression coverage, and verification.","https:\u002F\u002Fgithub.com\u002Fsung1-labs\u002Fsddx\u002Fblob\u002Fmain\u002Fskills\u002Fworkflow\u002Fsddx-debug\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":19},"01M7C8SW14B7XG3TSQGGWZ0ZCH","sddx-archive","Complete a verified SDDx change, preserve its durable record, synchronize specifications, and recommend the next workflow.","https:\u002F\u002Fgithub.com\u002Fsung1-labs\u002Fsddx\u002Fblob\u002Fmain\u002Fskills\u002Fworkflow\u002Fsddx-archive\u002FSKILL.md",[],[]]