zhongwei/gh-jbabin91-super-claude-plugins-workflow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:50:12 +08:00
commit d16c5de665
29 changed files with 4788 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
commands/openspec/apply.md Normal file
View File

@@ -0,0 +1,28 @@
---
name: openspec:apply
description: Implement an approved OpenSpec change and keep tasks in sync.
category: openspec
tags: [openspec, apply]
---
<!-- OPENSPEC:START -->
**Guardrails**
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
- Keep changes tightly scoped to the requested outcome.
- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
**Steps**
Track these steps as TODOs and complete them one by one.
1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
5. Reference `openspec list` or `openspec show <item>` when additional context is required.
**Reference**
- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
<!-- OPENSPEC:END -->

36
commands/openspec/archive.md Normal file
View File

@@ -0,0 +1,36 @@
---
name: openspec:archive
description: Archive a deployed OpenSpec change and update specs.
category: openspec
tags: [openspec, archive]
---
<!-- OPENSPEC:START -->
**Guardrails**
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
- Keep changes tightly scoped to the requested outcome.
- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
**Steps**
1. Determine the change ID to archive:
- If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
- If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
- Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
- If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
5. **Update CHANGELOG.md** - Add entry under appropriate version (Unreleased or next version) and category:
- **Added** - New skills/features
- **Changed** - Modified existing functionality
- **Fixed** - Bug fixes
6. Validate with `openspec validate --strict` and inspect with `openspec show <id>` if anything looks off.
**Reference**
- Use `openspec list` to confirm change IDs before archiving.
- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
<!-- OPENSPEC:END -->

162
commands/openspec/checkpoint.md Normal file
View File

@@ -0,0 +1,162 @@
---
name: openspec:checkpoint
description: Save current progress and context to design.md.
category: openspec
tags: [openspec, checkpoint, save]
---
<!-- OPENSPEC:START -->
**Purpose**
This command saves your current progress as a checkpoint in design.md. It's the equivalent of the Reddit post's "checkpoint" concept - preserving context so you can resume work later without losing your train of thought.
**When to Use**
- Before taking a break or ending a session
- After completing a significant subtask
- When you've made important decisions or discoveries
- Before switching to a different change
- Regularly during long work sessions (every 30-60 minutes)
**Steps**
1. **Check for active change**
- Read `openspec/active.json`
- If no active change: "No active change. Use /openspec:work to start working on a change first."
- Exit if no active change
2. **Gather current context**
- Ask user to summarize current progress:
```txt
Let's save a checkpoint. Please provide:
1. What did you just complete?
2. What are you working on now?
3. What's next?
4. Any blockers or decisions made?
(You can provide a brief summary or detailed notes)
```
3. **Load existing design.md**
- Path: `openspec/changes/<change-id>/design.md`
- If doesn't exist, create with initial structure:
```markdown
# Design: <change-id>
## Overview
(Brief description of the approach)
## Progress Log
### Checkpoint: <ISO 8601 timestamp>
(User's progress notes)
```
- If exists, append new checkpoint section
4. **Append checkpoint to design.md**
- Add new section at the end:
```markdown
### Checkpoint: <ISO 8601 timestamp>
**Completed:**
- (what user completed)
**Current:**
- (what user is working on)
**Next:**
- (what's next)
**Notes:**
- (any blockers/decisions)
```
5. **Update tasks.md if needed**
- Ask user: "Any tasks to mark complete in tasks.md? (y/n)"
- If yes, ask which task numbers to mark with `[x]`
- Update tasks.md with completed tasks
6. **Update active.json**
- Update `lastCheckpoint` field to current timestamp:
```json
{
"change": "<change-id>",
"started": "<original timestamp>",
"lastCheckpoint": "<current ISO 8601 timestamp>"
}
```
7. **Confirm checkpoint saved**
```txt
✓ Checkpoint saved to design.md
Updated:
- design.md: Added progress notes
- tasks.md: Marked <X> tasks complete
- active.json: Updated lastCheckpoint
You can safely resume this work later. The SessionStart hook will load this context automatically.
Use /openspec:status to see current progress.
```
**Error Handling**
- If no active change: Guide user to use /openspec:work first
- If design.md write fails: Show error and suggest checking file permissions
- If tasks.md parsing fails: Skip task updates but still save checkpoint
**Example Usage**
**Scenario 1: Quick checkpoint**
```txt
User: /openspec:checkpoint
Assistant: Let's save a checkpoint. Please provide:
1. What did you just complete?
2. What are you working on now?
3. What's next?
User: Just finished the theme provider. Working on the toggle component now. Next is localStorage persistence.
Assistant: [Appends to design.md]
[Updates active.json]
✓ Checkpoint saved
```
**Scenario 2: Checkpoint with task updates**
```txt
User: /openspec:checkpoint
Assistant: Let's save a checkpoint...
User: Completed theme context and provider setup
Assistant: Any tasks to mark complete in tasks.md? (y/n)
User: y
Assistant: Which task numbers? (e.g., 1,3,5)
User: 1,2
Assistant: [Updates tasks.md: marks tasks 1 and 2 complete]
[Appends checkpoint to design.md]
✓ Checkpoint saved. 2 tasks marked complete.
```
**Notes**
- design.md acts as a "living doc" that grows with the project
- Checkpoints create a timeline of progress and decisions
- The SessionStart hook reads design.md to restore context
- This is inspired by diet103's "context.md" approach from Reddit
- Unlike git commits, checkpoints capture thought process and decisions
<!-- OPENSPEC:END -->

149
commands/openspec/done.md Normal file
View File

@@ -0,0 +1,149 @@
---
name: openspec:done
description: Complete and archive an OpenSpec change.
category: openspec
tags: [openspec, done, archive, complete]
---
<!-- OPENSPEC:START -->
**Purpose**
This command finalizes your work on an OpenSpec change:
- Verifies all tasks are complete
- Archives the change proposal
- Updates CHANGELOG.md
- Clears the active change tracker
- Guides you to commit the changes
**Steps**
1. **Check for active change**
- Read `openspec/active.json`
- If no active change: "No active change. Use /openspec:work to start working on a change first."
- Exit if no active change
2. **Verify all tasks complete**
- Read `openspec/changes/<change-id>/tasks.md`
- Count incomplete tasks (lines with `- [ ]`)
- If any incomplete:
```txt
⚠️ Not all tasks are complete!
Remaining tasks: <X>
- (list first 5 incomplete tasks)
Options:
1. Continue anyway and mark as done (not recommended)
2. Cancel and finish remaining tasks
3. Save checkpoint and resume later (/openspec:checkpoint)
What would you like to do?
```
- Wait for user decision
3. **Final checkpoint**
- Ask user: "Would you like to save a final checkpoint before archiving? (y/n)"
- If yes, run /openspec:checkpoint workflow
- This captures final state in design.md
4. **Run OpenSpec archive**
- Execute: `openspec archive <change-id>`
- This moves the change to archived folder with timestamp
- Updates specs/ folder with approved changes
- Shows success message from OpenSpec CLI
5. **Clear active change tracker**
- Delete or clear `openspec/active.json`:
```json
{}
```
- Or delete the file entirely
6. **Guide CHANGELOG update**
- Show message:
```txt
✓ Change archived successfully!
Next steps:
1. Review the changes made by OpenSpec
2. Update CHANGELOG.md with this change:
## [Unreleased]
### Added
- **<change-id>** - <brief description>
3. Commit all changes:
git add .
git commit -m "feat: <change description>"
4. The change is now archived in:
openspec/changes/<timestamp>-<change-id>/
Use /openspec:work to start on the next change.
```
7. **Show OpenSpec view**
- Run `openspec view` to show updated dashboard
- Confirms change is archived and specs are updated
**Error Handling**
- If no active change: Guide user to use /openspec:work
- If openspec archive fails: Show error and suggest checking change validity
- If CHANGELOG.md doesn't exist: Create it with standard format
- If active.json clear fails: Warn but continue (non-critical)
**Example Usage**
**Scenario 1: All tasks complete**
```txt
User: /openspec:done
Assistant: [Checks tasks.md - all complete ✓]
Would you like to save a final checkpoint? (y/n)
User: y
Assistant: [Runs checkpoint flow]
[Runs openspec archive add-dark-mode]
[Clears active.json]
✓ Change archived successfully!
[Shows next steps]
```
**Scenario 2: Tasks incomplete**
```txt
User: /openspec:done
Assistant: ⚠️ Not all tasks are complete!
Remaining tasks: 3
- [ ] Add localStorage persistence
- [ ] Write tests for theme toggle
- [ ] Update documentation
Options:
1. Continue anyway (not recommended)
2. Cancel and finish tasks
3. Save checkpoint and resume later
What would you like to do?
User: 2
Assistant: Cancelled. Use /openspec:status to see remaining work.
```
**Notes**
- This command wraps `openspec archive` with pre/post checks
- Clears active.json so SessionStart hook doesn't load old context
- Encourages final checkpoint for documentation
- Guides user through commit process
- Ensures clean state for starting next change
<!-- OPENSPEC:END -->

145
commands/openspec/init.md Normal file
View File

@@ -0,0 +1,145 @@
---
name: openspec:init
description: Initialize OpenSpec directory structure in your project without duplicating slash commands.
category: openspec
tags: [openspec, setup, init]
---
# OpenSpec Init Command
Initialize OpenSpec directory structure in your project without duplicating slash commands.
## Purpose
Creates the `openspec/` directory structure (specs, changes, AGENTS.md, project.md) while avoiding conflicts with the workflow plugin's enhanced OpenSpec commands.
## Usage
This command should be run **once per project** when you first want to use OpenSpec.
## What This Command Does
1. **Validates openspec CLI is installed**
- Check if `openspec` command is available
- If not, provide installation instructions
2. **Runs `openspec init --tools none`**
- Creates `openspec/` directory structure
- Creates `openspec/AGENTS.md` (OpenSpec workflow instructions)
- Creates `openspec/project.md` (project context template)
- Creates `openspec/changes/` (for proposals)
- Creates `openspec/specs/` (for specifications)
- Creates root `AGENTS.md` (agent instructions)
- Does NOT create `.claude/commands/` (prevents duplication)
3. **Explains next steps**
- How to fill out `openspec/project.md`
- How to use OpenSpec slash commands from this plugin
- How to create first change proposal
## Why `--tools none`?
The workflow plugin provides **enhanced OpenSpec commands** with additional context and customization:
- `/openspec:proposal` - Create new change proposals
- `/openspec:work` - Start working on a proposal with full context loading
- `/openspec:apply` - Implement approved proposals with task tracking
- `/openspec:checkpoint` - Save progress and context
- `/openspec:status` - Show current proposal status
- `/openspec:done` - Complete and prepare for archiving
- `/openspec:archive` - Archive completed changes
Using `--tools none` prevents OpenSpec CLI from creating duplicate basic commands, ensuring you get the full enhanced experience from this plugin.
## Implementation
```bash
# Get current working directory first for cleaner checks
PROJECT_DIR=$(pwd)
# Check if already initialized - exit early with helpful message
if [ -d "$PROJECT_DIR/openspec" ]; then
echo "✅ OpenSpec is already initialized in this project!"
echo ""
echo "📂 Current structure:"
echo " openspec/"
echo " ├── AGENTS.md"
echo " ├── project.md"
echo " ├── changes/"
echo " └── specs/"
echo ""
echo "💡 Useful commands:"
echo " /openspec:update - Update instruction files to latest"
echo " /openspec:proposal - Create a new change proposal"
echo " /openspec:status - Check current proposal status"
echo ""
echo "🔧 To reinitialize (advanced):"
echo " 1. Remove openspec/ directory manually"
echo " 2. Run /openspec:init again"
echo ""
exit 0
fi
# Check if openspec is installed
if ! command -v openspec &> /dev/null; then
echo "Error: openspec CLI not found"
echo ""
echo "Install with:"
echo " npm install -g @jsdocs-io/openspec"
echo " # or"
echo " pnpm add -g @jsdocs-io/openspec"
echo " # or"
echo " yarn global add @jsdocs-io/openspec"
exit 1
fi
# Initialize OpenSpec without tool-specific commands
echo "Initializing OpenSpec in: $PROJECT_DIR"
echo ""
openspec init "$PROJECT_DIR" --tools none
# Check if successful
if [ $? -eq 0 ]; then
echo ""
echo "✅ OpenSpec initialized successfully!"
echo ""
echo "📂 Created structure:"
echo " openspec/"
echo " ├── AGENTS.md # OpenSpec workflow instructions"
echo " ├── project.md # Project context (fill this out!)"
echo " ├── changes/ # Change proposals"
echo " └── specs/ # Specifications"
echo ""
echo "🎯 Next steps:"
echo ""
echo "1. Fill out project context:"
echo " 'Please read openspec/project.md and help me fill it out"
echo " with details about my project, tech stack, and conventions'"
echo ""
echo "2. Create your first proposal:"
echo " 'I want to add [FEATURE]. Please create an OpenSpec change"
echo " proposal using /openspec:proposal'"
echo ""
echo "3. Available commands from workflow plugin:"
echo " /openspec:proposal - Create new proposal"
echo " /openspec:work - Start working on proposal"
echo " /openspec:apply - Implement approved proposal"
echo " /openspec:checkpoint - Save progress"
echo " /openspec:status - Show current status"
echo " /openspec:done - Mark proposal complete"
echo " /openspec:archive - Archive completed proposal"
echo ""
else
echo ""
echo "❌ OpenSpec initialization failed"
echo "Check the error messages above"
exit 1
fi
```
## Notes
- **Run once per project** - Not needed in every session
- **Safe to re-run** - Will ask before overwriting existing structure
- **No conflicts** - Won't create duplicate commands (uses `--tools none`)
- **Enhanced commands** - You get our customized OpenSpec workflow from the plugin

32
commands/openspec/proposal.md Normal file
View File

@@ -0,0 +1,32 @@
---
name: openspec:proposal
description: Scaffold a new OpenSpec change and validate strictly.
category: openspec
tags: [openspec, change]
---
<!-- OPENSPEC:START -->
**Guardrails**
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
- Keep changes tightly scoped to the requested outcome.
- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
**Steps**
1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behavior; note any gaps that require clarification.
2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
7. Validate with `openspec validate <id> --strict` and resolve every issue before sharing the proposal.
**Reference**
- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
<!-- OPENSPEC:END -->

104
commands/openspec/status.md Normal file
View File

@@ -0,0 +1,104 @@
---
name: openspec:status
description: Show current OpenSpec change status and progress.
category: openspec
tags: [openspec, status, progress]
---
<!-- OPENSPEC:START -->
**Purpose**
This command shows the current state of your OpenSpec work:
- Which change you're actively working on
- Progress on tasks (completed vs remaining)
- Time since you started and last checkpoint
- Quick access to the OpenSpec dashboard
**Steps**
1. **Check for active change**
- Read `openspec/active.json`
- If file doesn't exist or is empty: "No active change. Use /openspec:work to start working on a change."
- Exit if no active change
2. **Parse active change data**
- Extract: `change` (change ID), `started` (timestamp), `lastCheckpoint` (timestamp)
- Calculate time elapsed since started and last checkpoint
3. **Run OpenSpec dashboard**
- Execute `openspec view` to get current state of all changes
- This shows the progress bars and task counts
4. **Load task progress**
- Read `openspec/changes/<change-id>/tasks.md`
- Count total tasks (lines starting with `- [ ]` or `- [x]`)
- Count completed tasks (lines starting with `- [x]`)
- Calculate percentage: `(completed / total) * 100`
5. **Display status summary**
```txt
📊 OpenSpec Status
Active Change: <change-id>
Started: <X hours/days ago>
Last Checkpoint: <Y minutes/hours ago>
Progress:
├─ Tasks: <completed>/<total> (<percentage>%)
├─ Status: <In Progress|Blocked|Ready for Review>
└─ Next: <first incomplete task from tasks.md>
Recent Context (from design.md):
<last 5-10 lines of design.md to show recent decisions/progress>
Commands:
- /openspec:checkpoint - Save current progress
- /openspec:work - Switch to different change
- /openspec:done - Complete and archive
```
6. **Show OpenSpec dashboard**
- Output result of `openspec view` for full context
**Error Handling**
- If active.json exists but change directory missing: "Active change '<change-id>' not found. It may have been archived. Use /openspec:work to select a new change."
- If tasks.md missing: Show "0/0 tasks (no tasks.md found)"
- If design.md missing: Skip "Recent Context" section
**Example Usage**
```txt
User: /openspec:status
Assistant:
📊 OpenSpec Status
Active Change: add-dark-mode
Started: 2 hours ago
Last Checkpoint: 15 minutes ago
Progress:
├─ Tasks: 8/12 (67%)
├─ Status: In Progress
└─ Next: Implement theme toggle in settings page
Recent Context (from design.md):
- Created ThemeContext with light/dark modes
- Added theme provider to root layout
- Implemented CSS variable system for colors
- Need to add persistence with localStorage
[openspec view output shown]
```
**Notes**
- This command is read-only - it doesn't modify anything
- Useful for quick progress checks without reading all files
- Shows "at a glance" summary before diving into details
- Complements `openspec view` with active change focus
<!-- OPENSPEC:END -->

122
commands/openspec/update.md Normal file
View File

@@ -0,0 +1,122 @@
---
name: openspec:update
description: Update OpenSpec instruction files to the latest version without affecting slash commands.
category: openspec
tags: [openspec, setup, update]
---
# OpenSpec Update Command
Update OpenSpec instruction files to the latest version without affecting slash commands.
## Purpose
Refreshes OpenSpec workflow documentation (AGENTS.md files) when the OpenSpec CLI is updated, ensuring you have the latest best practices and patterns.
## Usage
Run this command after updating the OpenSpec CLI to get the latest instruction files:
```bash
# Update OpenSpec CLI first
npm update -g @jsdocs-io/openspec
# Then refresh instruction files
/openspec-update
```
## What This Command Does
1. **Validates openspec CLI is installed**
- Checks if `openspec` command is available
- Shows current version
2. **Runs `openspec update`**
- Updates `openspec/AGENTS.md` (OpenSpec workflow instructions)
- Updates root `AGENTS.md` (if it exists)
- **Does NOT touch slash commands** (we maintain our own enhanced versions)
3. **Shows what was updated**
- Lists files that changed
- Explains what's new (if possible)
## Safety
This command is **safe to run repeatedly**:
- ✅ Updates instruction files only
- ✅ Won't override workflow plugin commands
- ✅ Won't modify your specs or changes
- ✅ Won't affect project configuration
## When to Run
- After updating OpenSpec CLI to a new version
- When you want the latest OpenSpec patterns and best practices
- After reading OpenSpec release notes mentioning instruction updates
## Implementation
```bash
# Check if openspec is installed
if ! command -v openspec &> /dev/null; then
echo "Error: openspec CLI not found"
echo ""
echo "Install with:"
echo " npm install -g @jsdocs-io/openspec"
echo " # or"
echo " pnpm add -g @jsdocs-io/openspec"
echo " # or"
echo " yarn global add @jsdocs-io/openspec"
exit 1
fi
# Show current version
OPENSPEC_VERSION=$(openspec --version 2>&1 || echo "unknown")
echo "OpenSpec CLI version: $OPENSPEC_VERSION"
echo ""
# Get current working directory
PROJECT_DIR=$(pwd)
# Check if initialized
if [ ! -d "$PROJECT_DIR/openspec" ]; then
echo "Error: OpenSpec not initialized in this project"
echo ""
echo "Run /openspec-init first to set up OpenSpec"
exit 1
fi
# Update instruction files
echo "Updating OpenSpec instruction files in: $PROJECT_DIR"
echo ""
openspec update "$PROJECT_DIR"
# Check if successful
if [ $? -eq 0 ]; then
echo ""
echo "✅ OpenSpec instruction files updated successfully!"
echo ""
echo "📝 Updated files:"
echo " openspec/AGENTS.md # Latest workflow instructions"
echo " AGENTS.md # Updated agent guidance"
echo ""
echo "💡 Note:"
echo " Slash commands (/openspec:*) are managed by the workflow plugin"
echo " and are NOT affected by this update. You're using enhanced versions"
echo " customized for Claude Code."
echo ""
else
echo ""
echo "❌ Update failed"
echo "Check the error messages above"
exit 1
fi
```
## Notes
- **Safe to run anytime** - Won't break existing work
- **No command conflicts** - Won't override workflow plugin commands
- **Version aware** - Get instructions matching your CLI version
- **Preserves customization** - Your specs and changes untouched

101
commands/openspec/work.md Normal file
View File

@@ -0,0 +1,101 @@
---
name: openspec:work
description: Start working on an OpenSpec change with full context loading.
category: openspec
tags: [openspec, work, context]
---
<!-- OPENSPEC:START -->
**Purpose**
This command helps you start or resume work on an OpenSpec change proposal. It:
- Shows the OpenSpec dashboard with all changes
- Loads the change context (proposal, design, tasks)
- Tracks the active change for session persistence
- Enables automatic context loading on session resume
**Steps**
1. **Show OpenSpec dashboard**
- Run `openspec view` to display all changes with progress
- Output the dashboard so user can see status
2. **Select change to work on**
- Ask user: "Which change would you like to work on? (provide change ID)"
- Change ID is the folder name in `openspec/changes/`
- Example: `add-dark-mode`, `fix-auth-bug`, `refactor-api`
3. **Verify change exists**
- Check that `openspec/changes/<change-id>/` directory exists
- If not found, show error: "Change '<change-id>' not found. Run 'openspec view' to see available changes."
- Exit if not found
4. **Load change context**
- Read and display key files in this order:
- `openspec/changes/<change-id>/proposal.md` - The WHY (goals, motivation)
- `openspec/changes/<change-id>/design.md` - The HOW (living doc with approach)
- `openspec/changes/<change-id>/tasks.md` - The WHAT (checklist of work)
- If design.md doesn't exist, note: "No design.md yet. Create one to track your approach and decisions."
5. **Update active change tracker**
- Write to `openspec/active.json`:
```json
{
"change": "<change-id>",
"started": "<ISO 8601 timestamp>",
"lastCheckpoint": "<ISO 8601 timestamp>"
}
```
- Use JavaScript/TypeScript Date: `new Date().toISOString()`
6. **Confirm and guide next steps**
- Show success message:
```txt
✓ Now working on: <change-id>
Context loaded:
- Proposal: <brief summary from proposal.md>
- Tasks: <X> remaining, <Y> completed
Next steps:
1. Review the proposal and design above
2. Work through tasks in tasks.md sequentially
3. Use /openspec:checkpoint to save progress
4. Use /openspec:status to check progress anytime
5. Use /openspec:done when all tasks complete
The SessionStart hook will automatically load this context if you resume later.
```
**Error Handling**
- If `openspec` CLI not found: "OpenSpec CLI not installed. Run 'npm install -g @fission-codes/openspec'"
- If no changes exist: "No OpenSpec changes found. Create one with /openspec:proposal"
- If `openspec/` directory doesn't exist: Show error (should be created by 'openspec init')
- If active.json write fails: Show error but continue (non-critical)
**Example Usage**
```txt
User: /openspec:work
Assistant: [Runs openspec view, shows dashboard]
Which change would you like to work on? (provide change ID)
User: add-dark-mode
Assistant: [Loads proposal.md, design.md, tasks.md]
[Updates active.json]
[Shows success message with context summary]
```
**Notes**
- This command wraps `openspec view` and adds context loading
- The active.json file enables session resume via SessionStart hook
- design.md serves as the "living doc" (Reddit's context.md equivalent)
- Use /openspec:checkpoint frequently to update design.md with progress
<!-- OPENSPEC:END -->