sauron-cli 1.1.3 → 1.3.0

package/OpenSpec-main/openspec/changes/archive/2026-01-15-add-nix-ci-validation/tasks.md

@@ -0,0 +1,49 @@
+# Implementation Tasks
+
+## 1. Add Nix Installation to CI
+
+- [x] 1.1 Research Nix installation options for GitHub Actions (nix-installer-action vs manual install)
+- [x] 1.2 Add Nix installation step to .github/workflows/ci.yml
+- [x] 1.3 Configure Nix with experimental features enabled (flakes, nix-command)
+- [x] 1.4 Add Nix store caching to improve CI performance
+
+## 2. Create Nix Build Validation Job
+
+- [x] 2.1 Add new `nix-flake-validate` job to .github/workflows/ci.yml
+- [x] 2.2 Implement `nix build` step with proper error handling
+- [x] 2.3 Add verification step to confirm binary exists in build output
+- [x] 2.4 Add step to test binary execution (`nix run . -- --version`)
+
+## 3. Add Update Script Validation
+
+- [x] 3.1 Add job step to run scripts/update-flake.sh in dry-run or test mode
+- [x] 3.2 Verify script executes without errors
+- [x] 3.3 Add validation that version is correctly extracted from package.json
+- [x] 3.4 Verify flake.nix is updated with correct format (version and hash)
+
+## 4. Configure Job Dependencies and Requirements
+
+- [x] 4.1 Configure Nix validation job to run on pull_request and push events
+- [x] 4.2 Add Nix validation to required checks list
+- [x] 4.3 Configure job to run in parallel with existing test/lint jobs
+- [x] 4.4 Set appropriate timeout (5-10 minutes)
+
+## 5. Test with act Locally
+
+- [x] 5.1 Install act locally if not already available
+- [x] 5.2 Test Nix validation job using `act pull_request`
+- [x] 5.3 Verify act can run the workflow with Nix installed
+- [x] 5.4 Document any act-specific configuration needed in .actrc or README
+
+## 6. Documentation and Finalization
+
+- [x] 6.1 Add documentation about Nix CI validation to README or CONTRIBUTING.md
+- [x] 6.2 Document how to test CI locally with act
+- [ ] 6.3 Update CI badge or status indicators if needed
+- [ ] 6.4 Test end-to-end by creating a test PR
+
+## 7. Archive Change
+
+- [x] 7.1 After merge and verification, create new spec file at openspec/specs/ci-nix-validation/spec.md
+- [x] 7.2 Move change directory to openspec/changes/archive/[date]-add-nix-ci-validation/
+- [x] 7.3 Run `openspec validate --strict` to confirm archived change passes

package/OpenSpec-main/openspec/changes/archive/2026-01-30-opencode-command-references/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-30

package/OpenSpec-main/openspec/changes/archive/2026-01-30-opencode-command-references/README.md

@@ -0,0 +1,3 @@
+# opencode-command-references
+
+Transform /opsx: to /opsx- in both commands and skills for OpenCode

package/OpenSpec-main/openspec/changes/archive/2026-01-30-opencode-command-references/design.md

@@ -0,0 +1,70 @@
+## Context
+
+OpenCode is one of many supported AI tools. Each tool has:
+- A **command adapter** (in `src/core/command-generation/adapters/`) for generating tool-specific command files
+- **Skills** generated via `generateSkillContent()` in `src/core/shared/skill-generation.ts`
+
+Currently:
+- Commands go through the adapter system which can transform content per-tool
+- Skills use a single shared function with no tool-specific transformation
+
+The templates in `src/core/templates/skill-templates.ts` use Claude's colon-based format (`/opsx:new`) as the canonical format. Tools that use different formats need transformation at generation time.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Transform all `/opsx:` command references to `/opsx-` for OpenCode in both commands and skills
+- Create a shared, reusable transformation utility
+- Keep the transformation opt-in via a callback parameter (not hard-coded tool detection)
+
+**Non-Goals:**
+- Modifying the canonical template format (templates stay with `/opsx:`)
+- Applying transformation to other tools (only OpenCode for now)
+- Creating a full adapter system for skills (overkill for current needs)
+
+## Decisions
+
+### Decision 1: Shared Utility Function
+
+**Choice**: Create `transformToHyphenCommands()` in `src/utils/command-references.ts`
+
+**Rationale**: 
+- Single source of truth for the transformation logic
+- Can be used by both command adapter and skill generation
+- Easy to test in isolation
+- Follows existing utils pattern in the codebase
+
+**Alternatives considered**:
+- Inline the transformation in each location - Duplicates logic, harder to maintain
+
+### Decision 2: Callback Parameter for Skill Generation
+
+**Choice**: Add optional `transformInstructions?: (instructions: string) => string` parameter to `generateSkillContent()`
+
+**Rationale**:
+- Flexible - callers define the transformation, not the generation function
+- No coupling - `generateSkillContent()` doesn't need to know about tool formats
+- Extensible - could support other transformations in the future
+- Follows inversion of control principle
+
+**Alternatives considered**:
+- Add tool ID parameter and switch on it - Creates coupling, harder to extend
+- Create skill adapter system parallel to commands - Over-engineering for current needs
+- Transform in templates directly - Breaks single-source-of-truth principle
+
+### Decision 3: Apply at Generation Sites
+
+**Choice**: Pass transformer in `init.ts` and `update.ts` when `tool.value === 'opencode'`
+
+**Rationale**:
+- These are the only two places that generate skills
+- Simple conditional check, no new abstractions needed
+- Easy to extend to other tools if needed later
+
+## Risks / Trade-offs
+
+| Risk | Mitigation |
+|------|------------|
+| Other `/opsx:` patterns exist that shouldn't be transformed | All occurrences in templates are command invocations - verified by inspection |
+| Future tools may need same transformation | Utility is shared and easy to reuse; can add to other tools' generation |
+| Callback adds complexity to function signature | Optional parameter with sensible default (no transformation) |

package/OpenSpec-main/openspec/changes/archive/2026-01-30-opencode-command-references/proposal.md

@@ -0,0 +1,32 @@
+## Why
+
+OpenCode uses hyphen-based command syntax (`/opsx-new`) but our templates contain colon-based references (`/opsx:new`). This creates inconsistency where generated command files and skill files contain references that don't match the actual command invocation syntax, confusing both the AI and users.
+
+## What Changes
+
+- Create a shared transformation utility (`transformToHyphenCommands`) for converting `/opsx:` to `/opsx-`
+- Update the OpenCode command adapter to transform body text using this utility
+- Add an optional `transformInstructions` callback parameter to `generateSkillContent()`
+- Update `init.ts` and `update.ts` to pass the transformer when generating skills for OpenCode
+
+## Capabilities
+
+### New Capabilities
+
+None - this is a bug fix, not a new capability.
+
+### Modified Capabilities
+
+None - no spec-level behavior changes. This is an implementation fix in the OpenCode adapter and skill generation that doesn't change any external requirements or contracts.
+
+## Impact
+
+- **Code**: 
+  - `src/utils/command-references.ts` (new file)
+  - `src/utils/index.ts` (export)
+  - `src/core/shared/skill-generation.ts` (add callback parameter)
+  - `src/core/command-generation/adapters/opencode.ts` (use transformer)
+  - `src/core/init.ts` (pass transformer for OpenCode)
+  - `src/core/update.ts` (pass transformer for OpenCode)
+- **Users**: OpenCode users will see correct `/opsx-` command references in both generated command files AND skill files
+- **Other tools**: No impact - transformation only applies to OpenCode

package/OpenSpec-main/openspec/changes/archive/2026-01-30-opencode-command-references/specs/no-changes.md

@@ -0,0 +1,9 @@
+# No Spec Changes
+
+This is a bug fix that doesn't modify any external requirements or contracts.
+
+The proposal's Capabilities section indicates:
+- **New Capabilities**: None
+- **Modified Capabilities**: None
+
+No spec files are needed for this implementation-only fix.

package/OpenSpec-main/openspec/changes/archive/2026-01-30-opencode-command-references/tasks.md

@@ -0,0 +1,22 @@
+## 1. Implementation
+
+- [x] 1.1 Create `src/utils/command-references.ts` with `transformToHyphenCommands()` function
+- [x] 1.2 Export `transformToHyphenCommands` from `src/utils/index.ts`
+- [x] 1.3 Update `generateSkillContent()` in `src/core/shared/skill-generation.ts` to accept optional `transformInstructions` callback
+- [x] 1.4 Update OpenCode adapter in `src/core/command-generation/adapters/opencode.ts` to use `transformToHyphenCommands()` for body text
+- [x] 1.5 Update `init.ts` to pass transformer when generating skills for OpenCode
+- [x] 1.6 Update `update.ts` to pass transformer when generating skills for OpenCode
+
+## 2. Testing
+
+- [x] 2.1 Create `test/utils/command-references.test.ts` with unit tests for `transformToHyphenCommands()`
+- [x] 2.2 Add test to `test/core/command-generation/adapters.test.ts` for OpenCode body transformation
+- [x] 2.3 Add test to `test/core/shared/skill-generation.test.ts` for transformer callback
+
+## 3. Verification
+
+- [x] 3.1 Run `npx vitest run test/utils/command-references.test.ts test/core/command-generation/adapters.test.ts test/core/shared/skill-generation.test.ts` to ensure tests pass
+- [x] 3.2 Run `pnpm run build` to ensure no TypeScript errors
+- [x] 3.3 Run `openspec init --tools opencode` in a temp directory and verify:
+  - Command files in `.opencode/command/` contain `/opsx-` references (not `/opsx:`)
+  - Skill files in `.opencode/skills/` contain `/opsx-` references (not `/opsx:`)

package/OpenSpec-main/openspec/changes/archive/2026-02-17-add-feedback-command/proposal.md

@@ -0,0 +1,20 @@
+## Why
+
+Users and agents need a simple way to submit feedback about OpenSpec directly from the CLI. Currently there's no mechanism to collect user feedback, feature requests, or bug reports in a way that enables follow-up conversation. Using GitHub Issues allows us to track feedback, prevent spam via GitHub auth, and enables outreach to users.
+
+## What Changes
+
+- Add `openspec feedback <message>` CLI command
+- Leverage `gh` CLI for GitHub authentication and issue creation
+- Add `/feedback` skill for agent-assisted feedback with context enrichment
+- Ensure cross-platform compatibility (macOS, Linux, Windows)
+
+## Impact
+
+- Affected specs: New `cli-feedback` capability
+- Affected code:
+  - `src/cli/index.ts` - Register feedback command
+  - `src/commands/feedback.ts` - Command implementation using `gh` CLI
+  - `src/core/templates/skill-templates.ts` - Feedback skill template
+  - `src/core/completions/command-registry.ts` - Shell completions
+- External dependency: Requires `gh` CLI installed and authenticated

package/OpenSpec-main/openspec/changes/archive/2026-02-17-add-feedback-command/specs/cli-feedback/spec.md

@@ -0,0 +1,188 @@
+## ADDED Requirements
+
+### Requirement: Feedback command
+
+The system SHALL provide an `openspec feedback` command that creates a GitHub Issue in the openspec repository using the `gh` CLI. The system SHALL use `execFileSync` with argument arrays to prevent shell injection vulnerabilities.
+
+#### Scenario: Simple feedback submission
+
+- **WHEN** user executes `openspec feedback "Great tool!"`
+- **THEN** the system executes `gh issue create` with title "Feedback: Great tool!"
+- **AND** the issue is created in the openspec repository
+- **AND** the issue has the `feedback` label
+- **AND** the system displays the created issue URL
+
+#### Scenario: Safe command execution
+
+- **WHEN** submitting feedback via `gh` CLI
+- **THEN** the system uses `execFileSync` with separate arguments array
+- **AND** user input is NOT passed through a shell
+- **AND** shell metacharacters (quotes, backticks, $(), etc.) are treated as literal text
+
+#### Scenario: Feedback with body
+
+- **WHEN** user executes `openspec feedback "Title here" --body "Detailed description..."`
+- **THEN** the system creates a GitHub Issue with the specified title
+- **AND** the issue body contains the detailed description
+- **AND** the issue body includes metadata (OpenSpec version, platform, timestamp)
+
+### Requirement: GitHub CLI dependency
+
+The system SHALL use `gh` CLI for automatic feedback submission when available, and provide a manual submission fallback when `gh` is not installed or not authenticated. The system SHALL use platform-appropriate commands to detect `gh` CLI availability.
+
+#### Scenario: Missing gh CLI with fallback
+
+- **WHEN** user runs `openspec feedback "message"`
+- **AND** `gh` CLI is not installed (not found in PATH)
+- **THEN** the system displays warning: "GitHub CLI not found. Manual submission required."
+- **AND** outputs structured feedback content with delimiters:
+  - "--- FORMATTED FEEDBACK ---"
+  - Title line
+  - Labels line
+  - Body content with metadata
+  - "--- END FEEDBACK ---"
+- **AND** displays pre-filled GitHub issue URL for manual submission
+- **AND** exits with zero code (successful fallback)
+
+#### Scenario: Cross-platform gh CLI detection on Unix
+
+- **WHEN** system is running on macOS or Linux (platform is 'darwin' or 'linux')
+- **AND** checking if `gh` CLI is installed
+- **THEN** the system executes `which gh` command
+
+#### Scenario: Cross-platform gh CLI detection on Windows
+
+- **WHEN** system is running on Windows (platform is 'win32')
+- **AND** checking if `gh` CLI is installed
+- **THEN** the system executes `where gh` command
+
+#### Scenario: Unauthenticated gh CLI with fallback
+
+- **WHEN** user runs `openspec feedback "message"`
+- **AND** `gh` CLI is installed but not authenticated
+- **THEN** the system displays warning: "GitHub authentication required. Manual submission required."
+- **AND** outputs structured feedback content (same format as missing gh CLI scenario)
+- **AND** displays pre-filled GitHub issue URL for manual submission
+- **AND** displays authentication instructions: "To auto-submit in the future: gh auth login"
+- **AND** exits with zero code (successful fallback)
+
+#### Scenario: Authenticated gh CLI
+
+- **WHEN** user runs `openspec feedback "message"`
+- **AND** `gh auth status` returns success (authenticated)
+- **THEN** the system proceeds with feedback submission
+
+### Requirement: Issue metadata
+
+The system SHALL include relevant metadata in the GitHub Issue body.
+
+#### Scenario: Standard metadata
+
+- **WHEN** creating a GitHub Issue for feedback
+- **THEN** the issue body includes:
+  - OpenSpec CLI version
+  - Platform (darwin, linux, win32)
+  - Submission timestamp
+  - Separator line: "---\nSubmitted via OpenSpec CLI"
+
+#### Scenario: Windows platform metadata
+
+- **WHEN** creating a GitHub Issue for feedback on Windows
+- **THEN** the issue body includes "Platform: win32"
+- **AND** all platform detection uses Node.js `os.platform()` API
+
+#### Scenario: No sensitive metadata
+
+- **WHEN** creating a GitHub Issue for feedback
+- **THEN** the issue body does NOT include:
+  - File paths from user's system
+  - Project names or directory names
+  - Environment variables
+  - IP addresses
+
+### Requirement: Feedback always works
+
+The system SHALL allow feedback submission regardless of telemetry settings.
+
+#### Scenario: Feedback with telemetry disabled
+
+- **WHEN** user has disabled telemetry via `OPENSPEC_TELEMETRY=0`
+- **AND** user runs `openspec feedback "message"`
+- **THEN** the feedback is still submitted via `gh` CLI
+- **AND** telemetry events are not sent
+
+#### Scenario: Feedback in CI environment
+
+- **WHEN** `CI=true` is set in the environment
+- **AND** user runs `openspec feedback "message"`
+- **THEN** the feedback submission proceeds normally (if `gh` is available and authenticated)
+
+### Requirement: Error handling
+
+The system SHALL handle feedback submission errors gracefully.
+
+#### Scenario: gh CLI execution failure
+
+- **WHEN** `gh issue create` command fails
+- **THEN** the system displays the error output from `gh` CLI
+- **AND** exits with the same exit code as `gh`
+
+#### Scenario: Network failure
+
+- **WHEN** `gh` CLI reports network connectivity issues
+- **THEN** the system displays the error message from `gh`
+- **AND** suggests checking network connectivity
+- **AND** exits with non-zero code
+
+### Requirement: Feedback skill for agents
+
+The system SHALL provide a `/feedback` skill that guides agents through collecting and submitting user feedback.
+
+#### Scenario: Agent-initiated feedback
+
+- **WHEN** user invokes `/feedback` in an agent conversation
+- **THEN** the agent gathers context from the conversation
+- **AND** drafts a feedback issue with enriched content
+- **AND** anonymizes sensitive information
+- **AND** presents the draft to the user for approval
+- **AND** submits via `openspec feedback` command on user confirmation
+
+#### Scenario: Context enrichment
+
+- **WHEN** agent drafts feedback
+- **THEN** the agent includes relevant context such as:
+  - What task was being performed
+  - What worked well or poorly
+  - Specific friction points or praise
+
+#### Scenario: Anonymization
+
+- **WHEN** agent drafts feedback
+- **THEN** the agent removes or replaces:
+  - File paths with `<path>` or generic descriptions
+  - API keys, tokens, secrets with `<redacted>`
+  - Company/organization names with `<company>`
+  - Personal names with `<user>`
+  - Specific URLs with `<url>` unless public/relevant
+
+#### Scenario: User confirmation required
+
+- **WHEN** agent has drafted feedback
+- **THEN** the agent MUST show the complete draft to the user
+- **AND** ask for explicit approval before submitting
+- **AND** allow the user to request modifications
+- **AND** only submit after user confirms
+
+### Requirement: Shell completions
+
+The system SHALL provide shell completions for the feedback command.
+
+#### Scenario: Command completion
+
+- **WHEN** user types `openspec fee<TAB>`
+- **THEN** the shell completes to `openspec feedback`
+
+#### Scenario: Flag completion
+
+- **WHEN** user types `openspec feedback "msg" --<TAB>`
+- **THEN** the shell suggests available flags (`--body`)

package/OpenSpec-main/openspec/changes/archive/2026-02-17-add-feedback-command/tasks.md

@@ -0,0 +1,30 @@
+## 1. Feedback Command
+
+- [x] 1.1 Create `src/commands/feedback.ts` with command implementation
+- [x] 1.2 Check `gh` CLI availability using platform-appropriate command (`which` on Unix/macOS, `where` on Windows)
+- [x] 1.3 Check GitHub auth status with `gh auth status`
+- [x] 1.4 Execute `gh issue create` with formatted title and body using `execFileSync` to prevent shell injection
+- [x] 1.5 Display issue URL returned by `gh` CLI
+- [x] 1.6 Register `feedback <message>` command in `src/cli/index.ts`
+- [x] 1.7 Ensure cross-platform compatibility (macOS, Linux, Windows)
+
+## 2. Shell Completions
+
+- [x] 2.1 Add `feedback` command to command registry
+- [x] 2.2 Regenerate completion scripts for all shells
+
+## 3. Feedback Skill
+
+- [x] 3.1 Create feedback skill template in `skill-templates.ts`
+- [x] 3.2 Document context gathering workflow
+- [x] 3.3 Document anonymization rules
+- [x] 3.4 Document user confirmation flow
+
+## 4. Testing
+
+- [x] 4.1 Add unit tests for feedback command (mock `gh` subprocess calls)
+- [x] 4.2 Add integration test for full feedback flow with mocked `gh` CLI
+- [x] 4.3 Test error handling for missing `gh` CLI
+- [x] 4.4 Test error handling for unauthenticated `gh` session
+- [x] 4.5 Test cross-platform `gh` CLI detection (verify `which` on Unix, `where` on Windows)
+- [x] 4.6 Test platform metadata includes correct value for Windows (win32)

package/OpenSpec-main/openspec/changes/archive/2026-02-17-add-opsx-onboard-skill/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-24

package/OpenSpec-main/openspec/changes/archive/2026-02-17-add-opsx-onboard-skill/design.md

@@ -0,0 +1,115 @@
+## Context
+
+OpenSpec has a complete skill and slash command generation system. Skills are defined in `src/core/templates/skill-templates.ts` as functions that return `SkillTemplate` objects (for Agent Skills) and `CommandTemplate` objects (for slash commands). These are registered in `src/core/shared/skill-generation.ts` and generated during `openspec init` and `openspec update`.
+
+Existing skills follow a consistent pattern:
+- `getXxxSkillTemplate()` returns the skill with name, description, instructions
+- `getOpsxXxxCommandTemplate()` returns the slash command with name, description, category, tags, content
+- Both are registered in their respective arrays in `skill-generation.ts`
+
+## Goals / Non-Goals
+
+**Goals:**
+- Add `/opsx:onboard` skill that teaches the OpenSpec workflow through guided practice
+- Follow existing patterns for skill/command template generation
+- Provide comprehensive narration that explains each step
+- Include codebase analysis to suggest real, appropriately-scoped tasks
+
+**Non-Goals:**
+- Creating a separate "demo mode" or simulated workflow (we do real work)
+- Adding new CLI commands (this is purely agent instructions)
+- Modifying the init/update flow (just adding to the template arrays)
+
+## Decisions
+
+### Decision 1: Single Monolithic Skill
+
+The onboard skill will be a single comprehensive instruction set rather than composing existing skills with flags.
+
+**Rationale:**
+- Slash commands don't support flags (they're just prompts)
+- A monolithic skill gives complete control over narration and pacing
+- Easier to maintain a single cohesive experience
+- Users learn the real commands by seeing them mentioned in narration
+
+### Decision 2: Codebase Analysis Patterns
+
+The skill instructions will direct the agent to look for specific patterns when suggesting starter tasks:
+
+1. TODO/FIXME comments in code
+2. Missing error handling (`catch` blocks that swallow errors, no try-catch around risky operations)
+3. Functions without tests (cross-reference src/ with test files)
+4. Type: `any` in TypeScript files
+5. Console.log statements in non-debug code
+6. Missing input validation on user-facing inputs
+7. Recent git commits (for context on what user is working on)
+
+**Rationale:** These are universally applicable, easy to detect, and produce well-scoped tasks.
+
+### Decision 3: Narration Integration Style
+
+Each phase will follow a pattern:
+1. **EXPLAIN** what we're about to do and why (1-2 sentences)
+2. **DO** the action (run command, create artifact)
+3. **SHOW** what happened
+4. **PAUSE** at key transitions (not every step)
+
+Pauses occur at:
+- After task selection (before creating change)
+- After drafting proposal (before saving)
+- After tasks are generated (before implementation)
+- After archive (final recap)
+
+**Rationale:** Too many pauses becomes tedious. Too few loses the teaching opportunity. These are the natural "chapter breaks."
+
+### Decision 4: Scope Guardrail Approach
+
+When user selects a task that's too large, the skill will:
+1. Acknowledge the task is valuable
+2. Explain why smaller is better for first time
+3. Suggest a smaller slice or alternative
+4. Let user override if they insist
+
+**Rationale:** Soft guardrails teach without frustrating. Users learn scope calibration as part of the experience.
+
+### Decision 5: Template Structure
+
+The skill template will be ~400-600 lines of instruction text, structured as:
+
+```
+- Preflight checks (init status)
+- Phase 1: Welcome & Setup
+- Phase 2: Task Selection (with codebase analysis instructions)
+- Phase 3: Explore Demo (brief)
+- Phase 4: Change Creation
+- Phase 5: Proposal
+- Phase 6: Specs
+- Phase 7: Design
+- Phase 8: Tasks
+- Phase 9: Apply (Implementation)
+- Phase 10: Archive
+- Phase 11: Recap & Next Steps
+- Edge cases & graceful exits
+```
+
+The command template will be identical to the skill template (same content, different wrapper).
+
+**Rationale:** Following the established pattern where skill and command share the same core instructions.
+
+## Risks / Trade-offs
+
+**Risk: Instruction length**
+The skill will be significantly longer than existing skills (~500 lines vs ~100-200).
+→ Mitigation: This is acceptable since onboarding is inherently comprehensive. Token cost is one-time per session.
+
+**Risk: Codebase analysis may find nothing**
+Some codebases (new projects, very clean code) may not have obvious improvement opportunities.
+→ Mitigation: Fall back to asking user what they want to build. Include "add a new feature" as an option.
+
+**Risk: Task suggestions may be inappropriate**
+Agent might suggest tasks that touch sensitive code or have hidden complexity.
+→ Mitigation: User always chooses; agent just suggests. Scope estimates help set expectations.
+
+**Risk: User abandons mid-way**
+Onboarding takes ~15 minutes; users may not complete it.
+→ Mitigation: Graceful exit handling - note the change is saved, explain how to continue later.

package/OpenSpec-main/openspec/changes/archive/2026-02-17-add-opsx-onboard-skill/proposal.md

@@ -0,0 +1,27 @@
+## Why
+
+Users who run `openspec init` are left with files but no clear path to actually using the system. There's a gap between "I have OpenSpec set up" and "I understand the workflow." An onboarding skill would guide users through their first complete change cycle on a real task in their codebase, teaching the workflow by doing it.
+
+## What Changes
+
+- Add new `/opsx:onboard` skill that guides users through their first OpenSpec change
+- Add corresponding slash command template for editor integrations
+- The skill will:
+  - Analyze the user's codebase to suggest appropriately-scoped starter tasks
+  - Walk through the full workflow (explore → new → proposal → specs → design → tasks → apply → archive)
+  - Provide narration explaining each step as it happens
+  - Result in a real, implemented change in the user's codebase
+
+## Capabilities
+
+### New Capabilities
+- `opsx-onboard-skill`: The onboarding skill that guides users through their first complete OpenSpec workflow cycle with narration and codebase-aware task suggestions
+
+### Modified Capabilities
+<!-- No existing specs are being modified - this is purely additive -->
+
+## Impact
+
+- `src/core/templates/skill-templates.ts`: Add `getOnboardSkillTemplate()` and `getOpsxOnboardCommandTemplate()` functions
+- `src/core/shared/skill-generation.ts`: Register the new skill and command templates in `getSkillTemplates()` and `getCommandTemplates()`
+- Users running `openspec init` or `openspec update` will get the new skill/command files generated