[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6WZB3J0FJQJ0WSW9EK6447P":3,"skill-same:01M6WZB3J0FJQJ0WSW9EK6447P":64},{"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":32,"linkOnly":33,"markdownContent":34,"markdownBody":35,"frontMatter":36,"refName":41,"commitSha":42,"skillDirectory":43,"forksCount":44,"repositoryHtmlUrl":45,"repositoryHomepageUrl":6,"ownerHtmlUrl":46,"ownerBlogUrl":47,"ownerDescription":48,"updatedAt":49,"install":50,"resources":63},"01M6WZB3J0FJQJ0WSW9EK6447P","openspec-onboard",null,"Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.","huangjia2019\u002Fsdd-in-action","huangjia2019","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F48795276?v=4","01M6RVB2A5TS40SQTN843K74XF","Jia Huang (黄佳)","01M6RVB2DWAKV004CDR8A4QXCY",172,"MIT","https:\u002F\u002Fgithub.com\u002Fhuangjia2019\u002Fsdd-in-action\u002Fblob\u002Fmaster\u002Fweek3\u002Fcode\u002F.opencode\u002Fskills\u002Fopenspec-onboard\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31],"openspec onboard","onboard","openspec","cli","workflow","onboarding","work","narration","cycle","complete","with","for","codebase","2026-11-10 10:12:30",false,"---\nname: openspec-onboard\ndescription: Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.\nlicense: MIT\ncompatibility: Requires openspec CLI.\nmetadata:\n  author: openspec\n  version: \"1.0\"\n  generatedBy: \"1.3.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---\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 `\u002Fopsx-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 (`\u002Fopsx-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 in `openspec\u002Fchanges\u002F\u003Cname>\u002F` 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: `openspec\u002Fchanges\u002F\u003Cname>\u002F`\n\nThe folder structure:\n```\nopenspec\u002Fchanges\u002F\u003Cname>\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```\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-name>`: [brief description]\n\n### Modified Capabilities\n\u003C!-- If modifying existing behavior -->\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 `openspec\u002Fchanges\u002F\u003Cname>\u002Fproposal.md`.\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:** Create the spec file:\n```bash\n# Unix\u002FmacOS\nmkdir -p openspec\u002Fchanges\u002F\u003Cname>\u002Fspecs\u002F\u003Ccapability-name>\n# Windows (PowerShell)\n# New-Item -ItemType Directory -Force -Path \"openspec\u002Fchanges\u002F\u003Cname>\u002Fspecs\u002F\u003Ccapability-name>\"\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 `openspec\u002Fchanges\u002F\u003Cname>\u002Fspecs\u002F\u003Ccapability>\u002Fspec.md`.\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 `openspec\u002Fchanges\u002F\u003Cname>\u002Fdesign.md`.\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]\n- [ ] 1.2 [Specific task]\n\n## 2. Verify\n\n- [ ] 2.1 [Verification step]\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 `openspec\u002Fchanges\u002F\u003Cname>\u002Ftasks.md`.\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. This moves it from `openspec\u002Fchanges\u002F` to `openspec\u002Fchanges\u002Farchive\u002FYYYY-MM-DD-\u003Cname>\u002F`.\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:**\n```bash\nopenspec archive \"\u003Cname>\"\n```\n\n**SHOW:**\n```\nArchived to: `openspec\u002Fchanges\u002Farchive\u002FYYYY-MM-DD-\u003Cname>\u002F`\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 | `\u002Fopsx-propose` | Create a change and generate all artifacts |\n | `\u002Fopsx-explore` | Think through problems before\u002Fduring work  |\n | `\u002Fopsx-apply`   | Implement tasks from a change              |\n | `\u002Fopsx-archive` | Archive a completed change                 |\n\n**Additional commands:**\n\n | Command            | What it does                                             |\n |--------------------|----------------------------------------------------------|\n | `\u002Fopsx-new`      | Start a new change, step through artifacts one at a time |\n | `\u002Fopsx-continue` | Continue working on an existing change                   |\n | `\u002Fopsx-ff`       | Fast-forward: create all artifacts at once               |\n | `\u002Fopsx-verify`   | Verify implementation matches artifacts                  |\n\n---\n\n## What's Next?\n\nTry `\u002Fopsx-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 `openspec\u002Fchanges\u002F\u003Cname>\u002F`.\n\nTo pick up where we left off later:\n- `\u002Fopsx-continue \u003Cname>` - Resume artifact creation\n- `\u002Fopsx-apply \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 | `\u002Fopsx-propose \u003Cname>` | Create a change and generate all artifacts |\n | `\u002Fopsx-explore`        | Think through problems (no code changes)   |\n | `\u002Fopsx-apply \u003Cname>`   | Implement tasks                            |\n | `\u002Fopsx-archive \u003Cname>` | Archive when done                          |\n\n**Additional commands:**\n\n | Command                   | What it does                        |\n |---------------------------|-------------------------------------|\n | `\u002Fopsx-new \u003Cname>`      | Start a new change, step by step    |\n | `\u002Fopsx-continue \u003Cname>` | Continue an existing change         |\n | `\u002Fopsx-ff \u003Cname>`       | Fast-forward: all artifacts at once |\n | `\u002Fopsx-verify \u003Cname>`   | Verify implementation               |\n\nTry `\u002Fopsx-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---\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 `\u002Fopsx-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 (`\u002Fopsx-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 in `openspec\u002Fchanges\u002F\u003Cname>\u002F` 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: `openspec\u002Fchanges\u002F\u003Cname>\u002F`\n\nThe folder structure:\n```\nopenspec\u002Fchanges\u002F\u003Cname>\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```\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-name>`: [brief description]\n\n### Modified Capabilities\n\u003C!-- If modifying existing behavior -->\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 `openspec\u002Fchanges\u002F\u003Cname>\u002Fproposal.md`.\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:** Create the spec file:\n```bash\n# Unix\u002FmacOS\nmkdir -p openspec\u002Fchanges\u002F\u003Cname>\u002Fspecs\u002F\u003Ccapability-name>\n# Windows (PowerShell)\n# New-Item -ItemType Directory -Force -Path \"openspec\u002Fchanges\u002F\u003Cname>\u002Fspecs\u002F\u003Ccapability-name>\"\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 `openspec\u002Fchanges\u002F\u003Cname>\u002Fspecs\u002F\u003Ccapability>\u002Fspec.md`.\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 `openspec\u002Fchanges\u002F\u003Cname>\u002Fdesign.md`.\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]\n- [ ] 1.2 [Specific task]\n\n## 2. Verify\n\n- [ ] 2.1 [Verification step]\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 `openspec\u002Fchanges\u002F\u003Cname>\u002Ftasks.md`.\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. This moves it from `openspec\u002Fchanges\u002F` to `openspec\u002Fchanges\u002Farchive\u002FYYYY-MM-DD-\u003Cname>\u002F`.\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:**\n```bash\nopenspec archive \"\u003Cname>\"\n```\n\n**SHOW:**\n```\nArchived to: `openspec\u002Fchanges\u002Farchive\u002FYYYY-MM-DD-\u003Cname>\u002F`\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 | `\u002Fopsx-propose` | Create a change and generate all artifacts |\n | `\u002Fopsx-explore` | Think through problems before\u002Fduring work  |\n | `\u002Fopsx-apply`   | Implement tasks from a change              |\n | `\u002Fopsx-archive` | Archive a completed change                 |\n\n**Additional commands:**\n\n | Command            | What it does                                             |\n |--------------------|----------------------------------------------------------|\n | `\u002Fopsx-new`      | Start a new change, step through artifacts one at a time |\n | `\u002Fopsx-continue` | Continue working on an existing change                   |\n | `\u002Fopsx-ff`       | Fast-forward: create all artifacts at once               |\n | `\u002Fopsx-verify`   | Verify implementation matches artifacts                  |\n\n---\n\n## What's Next?\n\nTry `\u002Fopsx-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 `openspec\u002Fchanges\u002F\u003Cname>\u002F`.\n\nTo pick up where we left off later:\n- `\u002Fopsx-continue \u003Cname>` - Resume artifact creation\n- `\u002Fopsx-apply \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 | `\u002Fopsx-propose \u003Cname>` | Create a change and generate all artifacts |\n | `\u002Fopsx-explore`        | Think through problems (no code changes)   |\n | `\u002Fopsx-apply \u003Cname>`   | Implement tasks                            |\n | `\u002Fopsx-archive \u003Cname>` | Archive when done                          |\n\n**Additional commands:**\n\n | Command                   | What it does                        |\n |---------------------------|-------------------------------------|\n | `\u002Fopsx-new \u003Cname>`      | Start a new change, step by step    |\n | `\u002Fopsx-continue \u003Cname>` | Continue an existing change         |\n | `\u002Fopsx-ff \u003Cname>`       | Fast-forward: all artifacts at once |\n | `\u002Fopsx-verify \u003Cname>`   | Verify implementation               |\n\nTry `\u002Fopsx-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":37,"description":7,"compatibility":40},{"author":21,"version":38,"generatedBy":39},"1.0","1.3.0","Requires openspec CLI.","master","7ccc24b38f7cae09897ace41ebae14780250ac86","week3\u002Fcode\u002F.opencode\u002Fskills\u002Fopenspec-onboard",60,"https:\u002F\u002Fgithub.com\u002Fhuangjia2019\u002Fsdd-in-action","https:\u002F\u002Fgithub.com\u002Fhuangjia2019","https:\u002F\u002Fkage-ai.com","AI researcher at A*STAR | Author of Designing AI Agents (Manning) | Co-founder of ADPS","2026-08-25 16:05:09",{"source":8,"skillName":5,"commands":51,"prompt":61,"zipAvailable":62},[52,55,58],{"tool":53,"command":54},"npx","npx skills add huangjia2019\u002Fsdd-in-action --skill openspec-onboard",{"tool":56,"command":57},"bunx","bunx skills add huangjia2019\u002Fsdd-in-action --skill openspec-onboard",{"tool":59,"command":60},"pnpm","pnpm dlx skills add huangjia2019\u002Fsdd-in-action --skill openspec-onboard","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fhuangjia2019\u002Fsdd-in-action\u002Fblob\u002Fmaster\u002Fweek3\u002Fcode\u002F.opencode\u002Fskills\u002Fopenspec-onboard\u002FSKILL.md",true,[],[65,85,99,115,130,140],{"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":32},"01M6WZBHKBA02YT2SHSACNJR91","openspec-verify-change","Verify implementation matches change artifacts. Use when the user wants to validate that implementation is complete, correct, and coherent before archiving.","https:\u002F\u002Fgithub.com\u002Fhuangjia2019\u002Fsdd-in-action\u002Fblob\u002Fmaster\u002Fweek3\u002Fcode\u002F.opencode\u002Fskills\u002Fopenspec-verify-change\u002FSKILL.md",[],[72,73,74,75,21,76,77,28,78,79,80,81,82,83,84,22],"change","openspec verify change","verify","verify change","validate","when","verify implementation","coherent","implementation","use","user","correct","artifacts",{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":32},"01M6WZBEQRPC45MDYVPMG17X89","openspec-sync-specs","Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.","https:\u002F\u002Fgithub.com\u002Fhuangjia2019\u002Fsdd-in-action\u002Fblob\u002Fmaster\u002Fweek3\u002Fcode\u002F.opencode\u002Fskills\u002Fopenspec-sync-specs\u002FSKILL.md",[],[92,93,21,72,94,22,95,96,77,97,29,98,81,82],"openspec sync specs","sync","spec","main","update","changes","delta",{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":32},"01M6WZBA2QKBW10Z1ZYA4K2AV9","openspec-propose","Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.","https:\u002F\u002Fgithub.com\u002Fhuangjia2019\u002Fsdd-in-action\u002Fblob\u002Fmaster\u002Fweek3\u002Fcode\u002F.opencode\u002Fskills\u002Fopenspec-propose\u002FSKILL.md",[],[21,106,80,81,107,77,108,109,30,29,110,111,28,72,82,84,112,22,113,114],"openspec propose","ready","get","describe","build","proposal","tasks","design","generated",{"skillNo":116,"name":117,"nameZh":6,"description":118,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":119,"categories":120,"keywords":121,"publishedAt":32},"01M6WZAZX6QSAV79619M68K8N1","openspec-new-change","Start a new OpenSpec change using the experimental artifact workflow. Use when the user wants to create a new feature, fix, or modification with a structured step-by-step approach.","https:\u002F\u002Fgithub.com\u002Fhuangjia2019\u002Fsdd-in-action\u002Fblob\u002Fmaster\u002Fweek3\u002Fcode\u002F.opencode\u002Fskills\u002Fopenspec-new-change\u002FSKILL.md",[],[122,72,21,123,77,29,124,125,81,126,127,82,128,129,23,22],"openspec new change","artifact","feature","structured","new feature","fix","start","create",{"skillNo":131,"name":132,"nameZh":6,"description":133,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":134,"categories":135,"keywords":136,"publishedAt":32},"01M6WZAX8300NEPY3T1J8FRS3C","openspec-ff-change","Fast-forward through OpenSpec artifact creation. Use when the user wants to quickly create all artifacts needed for implementation without stepping through each one individually.","https:\u002F\u002Fgithub.com\u002Fhuangjia2019\u002Fsdd-in-action\u002Fblob\u002Fmaster\u002Fweek3\u002Fcode\u002F.opencode\u002Fskills\u002Fopenspec-ff-change\u002FSKILL.md",[],[72,21,137,138,123,80,81,82,139,84,129,22,30,77],"openspec ff change","creation","fast",{"skillNo":141,"name":142,"nameZh":6,"description":143,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":144,"categories":145,"keywords":146,"publishedAt":32},"01M6WZAT3BM9W7SKVTKN2P894M","openspec-explore","Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.","https:\u002F\u002Fgithub.com\u002Fhuangjia2019\u002Fsdd-in-action\u002Fblob\u002Fmaster\u002Fweek3\u002Fcode\u002F.opencode\u002Fskills\u002Fopenspec-explore\u002FSKILL.md",[],[147,148,21,30,77,149,150,151,152,153,154,155,81,82,72,22],"openspec explore","explore","mode","partner","requirements","ideas","thinking","thinking partner","think"]