sauron-cli 1.3.0 → 1.4.0

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

@@ -1,162 +0,0 @@
-## ADDED Requirements
-
-### Requirement: OPSX Onboard Skill
-
-The system SHALL provide an `/opsx:onboard` skill that guides users through their first complete OpenSpec workflow cycle with narration and real codebase work.
-
-#### Scenario: Skill invocation
-
-- **WHEN** user invokes `/opsx:onboard`
-- **THEN** agent checks if OpenSpec is initialized
-- **AND** if not initialized, prompts user to run `openspec init` first
-- **AND** if initialized, proceeds with onboarding flow
-
-#### Scenario: Welcome and expectations
-
-- **WHEN** onboarding begins
-- **THEN** agent displays welcome message explaining what will happen
-- **AND** sets expectation of ~15 minute duration
-- **AND** explains the workflow phases: explore → new → artifacts → apply → archive
-
-### Requirement: Codebase Analysis for Task Suggestions
-
-The skill SHALL analyze the user's codebase to suggest appropriately-scoped starter tasks.
-
-#### Scenario: Codebase scanning
-
-- **WHEN** onboarding reaches task selection phase
-- **THEN** agent scans codebase for small improvement opportunities
-- **AND** looks for: TODO/FIXME comments, missing error handling, functions without tests, outdated dependencies, type: any in TypeScript, console.log in production code, missing input validation
-- **AND** checks recent git commits for context on current work
-
-#### Scenario: Task suggestion presentation
-
-- **WHEN** agent has analyzed codebase
-- **THEN** agent presents 3-4 specific task suggestions with scope estimates
-- **AND** each suggestion includes: task description, estimated scope (files/lines), why it's a good starter
-- **AND** offers option for user to specify their own task
-
-#### Scenario: Scope guardrail
-
-- **WHEN** user selects or describes a task that is too large
-- **THEN** agent gently redirects toward smaller scope
-- **AND** suggests breaking down or deferring the large task
-- **AND** offers appropriately-sized alternatives
-
-### Requirement: Explore Phase Demo
-
-The skill SHALL briefly demonstrate explore mode before creating a change.
-
-#### Scenario: Brief explore demonstration
-
-- **WHEN** task is selected
-- **THEN** agent briefly demonstrates `/opsx:explore` by investigating relevant code
-- **AND** explains explore mode is for thinking before doing
-- **AND** keeps this phase short (not a full exploration session)
-- **AND** transitions to change creation
-
-### Requirement: Guided Artifact Creation
-
-The skill SHALL guide users through each artifact with narration explaining the purpose.
-
-#### Scenario: Change creation with narration
-
-- **WHEN** creating the change directory
-- **THEN** agent runs `openspec new change "<name>"` with derived kebab-case name
-- **AND** explains what a "change" is (container for thinking and planning)
-- **AND** shows the folder structure that was created
-- **AND** pauses for user acknowledgment before proceeding
-
-#### Scenario: Proposal creation with narration
-
-- **WHEN** creating proposal.md
-- **THEN** agent explains proposals capture WHY we're making this change
-- **AND** drafts proposal based on selected task
-- **AND** shows draft to user for approval before saving
-- **AND** explains the sections (Why, What Changes, Capabilities, Impact)
-
-#### Scenario: Specs creation with narration
-
-- **WHEN** creating spec files
-- **THEN** agent explains specs define WHAT we're building in detail
-- **AND** explains the requirement/scenario format
-- **AND** creates spec file(s) based on proposal capabilities
-- **AND** notes that specs become documentation that stays in sync
-
-#### Scenario: Design creation with narration
-
-- **WHEN** creating design.md
-- **THEN** agent explains design captures HOW we'll build it
-- **AND** notes this is where technical decisions and tradeoffs live
-- **AND** for small changes, acknowledges design may be brief
-- **AND** creates design based on proposal and specs
-
-#### Scenario: Tasks creation with narration
-
-- **WHEN** creating tasks.md
-- **THEN** agent explains tasks break work into checkboxes
-- **AND** explains these drive the apply phase
-- **AND** generates task list from design and specs
-- **AND** shows tasks and asks if ready to implement
-
-### Requirement: Guided Implementation
-
-The skill SHALL implement tasks with narration connecting back to artifacts.
-
-#### Scenario: Implementation with narration
-
-- **WHEN** implementing tasks
-- **THEN** agent announces each task before working on it
-- **AND** implements the change in the codebase
-- **AND** occasionally references how specs/design informed decisions
-- **AND** marks each task complete as it finishes
-- **AND** keeps narration light (not over-explaining)
-
-#### Scenario: Implementation completion
-
-- **WHEN** all tasks are complete
-- **THEN** agent announces completion
-- **AND** summarizes what was done
-- **AND** transitions to archive phase
-
-### Requirement: Archive with Explanation
-
-The skill SHALL archive the completed change and explain what happened.
-
-#### Scenario: Archive with narration
-
-- **WHEN** archiving the change
-- **THEN** agent explains archive moves change to dated folder
-- **AND** runs archive process
-- **AND** shows where archived change lives
-- **AND** explains the long-term value (finding decisions later)
-
-### Requirement: Recap and Next Steps
-
-The skill SHALL conclude with a recap and command reference.
-
-#### Scenario: Final recap
-
-- **WHEN** onboarding is complete
-- **THEN** agent summarizes the workflow phases completed
-- **AND** emphasizes this rhythm works for any size change
-- **AND** provides command reference table (/opsx:explore, /opsx:new, /opsx:ff, /opsx:continue, /opsx:apply, /opsx:verify, /opsx:archive)
-- **AND** suggests next actions (try /opsx:new or /opsx:ff on something)
-
-### Requirement: Graceful Exit Handling
-
-The skill SHALL handle users who want to stop mid-way.
-
-#### Scenario: User wants to stop
-
-- **WHEN** user indicates they want to stop during onboarding
-- **THEN** agent acknowledges gracefully
-- **AND** notes that the in-progress change is saved
-- **AND** explains how to continue later with `/opsx:continue <name>`
-- **AND** exits without pressure
-
-#### Scenario: User wants quick reference only
-
-- **WHEN** user says they just want to see the commands
-- **THEN** agent provides command cheat sheet
-- **AND** exits gracefully with encouragement to try `/opsx:new`

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

@@ -1,21 +0,0 @@
-## 1. Add Skill Template
-
-- [x] 1.1 Add `getOnboardSkillTemplate()` function to `src/core/templates/skill-templates.ts` with full onboarding instruction text covering all phases (preflight, welcome, task selection, explore demo, change creation, proposal, specs, design, tasks, apply, archive, recap)
-- [x] 1.2 Include codebase analysis instructions for suggesting starter tasks (TODO/FIXME, missing error handling, missing tests, type:any, console.log, missing validation)
-- [x] 1.3 Include narration pattern instructions (EXPLAIN → DO → SHOW → PAUSE at key transitions)
-- [x] 1.4 Include scope guardrail instructions for redirecting users away from overly large tasks
-- [x] 1.5 Include graceful exit handling instructions (user stops mid-way, user just wants command reference)
-
-## 2. Add Command Template
-
-- [x] 2.1 Add `getOpsxOnboardCommandTemplate()` function to `src/core/templates/skill-templates.ts` returning CommandTemplate with same instruction content as skill
-
-## 3. Register Templates
-
-- [x] 3.1 Add onboard skill to `getSkillTemplates()` array in `src/core/shared/skill-generation.ts` with dirName `openspec-onboard`
-- [x] 3.2 Add onboard command to `getCommandTemplates()` array in `src/core/shared/skill-generation.ts` with id `onboard`
-
-## 4. Verify
-
-- [x] 4.1 Run `pnpm run build` to ensure TypeScript compiles
-- [x] 4.2 Test skill generation by running `openspec init` in a test directory and verifying onboard skill/command files are created

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

@@ -1,96 +0,0 @@
-# Design: Add /opsx:verify Skill
-
-## Architecture Decision: Dynamic Generation via Setup Command
-
-### Context
-
-All existing opsx experimental skills (explore, new, continue, apply, ff, sync, archive) are dynamically generated when users run `openspec artifact-experimental-setup`. They are not manually created files checked into the repository.
-
-### Decision
-
-**Integrate verify into the existing artifact-experimental-setup system rather than creating static skill files.**
-
-### Rationale
-
-1. **Consistency**: All 7 existing opsx skills follow this pattern. Adding verify as the 8th skill should follow the same architecture.
-
-2. **Maintainability**: Template functions in `skill-templates.ts` are the single source of truth. Changes to skill definitions automatically propagate to all users when they re-run setup.
-
-3. **Distribution**: Users get the verify skill automatically when running `openspec artifact-experimental-setup`, just like all other opsx skills. No special installation steps needed.
-
-4. **Versioning**: Skills are generated from the installed npm package version, ensuring consistency between CLI version and skill behavior.
-
-### Implementation Approach
-
-#### 1. Template Functions
-
-Add two template functions to `src/core/templates/skill-templates.ts`:
-
-```typescript
-export function getVerifyChangeSkillTemplate(): SkillTemplate
-export function getOpsxVerifyCommandTemplate(): CommandTemplate
-```
-
-These return the skill definition (for Agent Skills) and slash command definition (for explicit invocation).
-
-#### 2. Setup Integration
-
-Update `artifactExperimentalSetupCommand()` in `src/commands/artifact-workflow.ts`:
-
-- Import both template functions
-- Add verify to the `skills` array (position 8)
-- Add verify to the `commands` array (position 8)
-- Update help text to list `/opsx:verify`
-
-#### 3. Generated Artifacts
-
-When users run `openspec artifact-experimental-setup`, the command creates:
-
-- `.claude/skills/openspec-verify-change/SKILL.md` - Agent Skills format
-- `.claude/commands/opsx/verify.md` - Slash command format
-
-Both are generated from the template functions, with YAML frontmatter automatically added.
-
-### Alternatives Considered
-
-**Alternative 1: Static skill files in repository**
-
-Create `.claude/skills/openspec-verify-change/SKILL.md` as a static file in the OpenSpec repository.
-
-**Rejected because:**
-- Inconsistent with all other opsx skills
-- Requires users to manually copy/update files
-- Versioning becomes complicated (repo version vs installed package version)
-- Breaks the established pattern
-
-**Alternative 2: Separate verify setup command**
-
-Add `openspec setup-verify` as a separate command.
-
-**Rejected because:**
-- Fragments the setup experience
-- Users would need to run multiple commands
-- Doesn't scale if we add more skills in the future
-- Goes against the "setup once, get everything" philosophy
-
-### Trade-offs
-
-**Advantages:**
-- Consistent with existing architecture
-- Zero additional setup burden for users
-- Easy to update and maintain
-- Automatic version compatibility
-
-**Disadvantages:**
-- Slightly more complex initial implementation (template functions + integration)
-- Requires understanding the setup system (but that's already documented)
-
-### Verification
-
-The implementation correctly follows this design if:
-
-1. Both template functions exist in `skill-templates.ts`
-2. Verify appears in both skills and commands arrays in `artifact-workflow.ts`
-3. Help text mentions `/opsx:verify`
-4. Running `openspec artifact-experimental-setup` generates both skill and command files
-5. Build succeeds with no TypeScript errors

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

@@ -1,48 +0,0 @@
-# Change: Add /opsx:verify Skill
-
-## Why
-
-Users need a way to validate that their implementation actually matches what was requested before archiving a change. Currently, there's no systematic way to check:
-- Whether all tasks are truly complete
-- Whether the implementation covers all spec requirements and scenarios
-- Whether the implementation follows the design decisions
-- Whether the code is coherent and makes sense
-
-A user requested: "Can we get a :verify that will ensure that the implementation matches what was requested?"
-
-## What Changes
-
-- Add `getVerifyChangeSkillTemplate()` function to `skill-templates.ts`
-- Add `getOpsxVerifyCommandTemplate()` function to `skill-templates.ts`
-- Integrate verify skill into `artifactExperimentalSetupCommand` in `artifact-workflow.ts`
-- Add verify to the skills and commands arrays in the setup command
-- Update help text to include `/opsx:verify` in the list of available commands
-- Create `opsx-verify-skill` capability spec
-
-## Verification Dimensions
-
-The skill verifies across three dimensions:
-
-1. **Completeness** - Are all tasks done? Are all specs addressed?
-2. **Correctness** - Does the implementation match specs? Are scenarios covered?
-3. **Coherence** - Does the implementation make sense? Does it follow design.md?
-
-## Output Format
-
-Produces a prioritized report with:
-- Summary scorecard (tasks, specs, design adherence)
-- Critical issues first (must fix before archive)
-- Warnings second (should fix)
-- Suggestions third (nice to have)
-- Actionable fix recommendations for each issue
-
-## Impact
-
-- Affected specs: New `opsx-verify-skill` spec
-- Affected code:
-  - `src/core/templates/skill-templates.ts` - Added 2 new template functions
-  - `src/commands/artifact-workflow.ts` - Integrated verify into experimental setup
-- Generated artifacts: When users run `openspec artifact-experimental-setup`:
-  - Creates `.claude/skills/openspec-verify-change/SKILL.md`
-  - Creates `.claude/commands/opsx/verify.md`
-- Related skills: Works alongside `/opsx:apply` and before `/opsx:archive`

package/OpenSpec-main/openspec/changes/archive/2026-02-17-add-verify-skill/specs/opsx-verify-skill/spec.md

@@ -1,190 +0,0 @@
-# opsx-verify-skill Specification
-
-## Purpose
-Defines the agent skill for verifying that implementation matches change artifacts (specs, tasks, design).
-
-## ADDED Requirements
-
-### Requirement: Verify Skill Invocation
-The system SHALL provide an `/opsx:verify` skill that validates implementation against change artifacts.
-
-#### Scenario: Verify with change name provided
-- **WHEN** agent executes `/opsx:verify <change-name>`
-- **THEN** the agent verifies implementation for that specific change
-- **AND** produces a verification report
-
-#### Scenario: Verify without change name
-- **WHEN** agent executes `/opsx:verify` without a change name
-- **THEN** the agent prompts user to select from available changes
-- **AND** shows only changes that have implementation tasks
-
-#### Scenario: Change has no tasks
-- **WHEN** selected change has no tasks.md or tasks are empty
-- **THEN** the agent reports "No tasks to verify"
-- **AND** suggests running `/opsx:continue` to create tasks
-
-### Requirement: Completeness Verification
-The agent SHALL verify that all required work has been completed.
-
-#### Scenario: Task completion check
-- **WHEN** verifying completeness
-- **THEN** the agent reads tasks.md
-- **AND** counts tasks marked `- [x]` (complete) vs `- [ ]` (incomplete)
-- **AND** reports completion status with specific incomplete tasks listed
-
-#### Scenario: Spec coverage check
-- **WHEN** verifying completeness
-- **AND** delta specs exist in `openspec/changes/<name>/specs/`
-- **THEN** the agent extracts all requirements from delta specs
-- **AND** searches codebase for implementation of each requirement
-- **AND** reports which requirements appear to have implementation vs which are missing
-
-#### Scenario: All tasks complete
-- **WHEN** all tasks are marked complete
-- **THEN** report "Tasks: N/N complete"
-- **AND** mark completeness dimension as passed
-
-#### Scenario: Incomplete tasks found
-- **WHEN** some tasks are incomplete
-- **THEN** report "Tasks: X/N complete"
-- **AND** list each incomplete task
-- **AND** mark as CRITICAL issue
-- **AND** suggest: "Complete remaining tasks or mark as done if already implemented"
-
-### Requirement: Correctness Verification
-The agent SHALL verify that implementation matches the specifications.
-
-#### Scenario: Requirement implementation mapping
-- **WHEN** verifying correctness
-- **THEN** for each requirement in delta specs:
-  - Search codebase for implementation
-  - Identify relevant files and line numbers
-  - Assess whether implementation satisfies the requirement
-
-#### Scenario: Scenario coverage check
-- **WHEN** verifying correctness
-- **THEN** for each scenario in delta specs:
-  - Check if the scenario's conditions are handled in code
-  - Check if tests exist that cover the scenario
-  - Report coverage status
-
-#### Scenario: Implementation matches spec
-- **WHEN** implementation appears to satisfy a requirement
-- **THEN** report which files/lines implement it
-- **AND** mark requirement as covered
-
-#### Scenario: Implementation diverges from spec
-- **WHEN** implementation exists but doesn't match spec intent
-- **THEN** report the divergence as WARNING
-- **AND** explain what differs
-- **AND** suggest: either update implementation or update spec to match reality
-
-#### Scenario: Missing implementation
-- **WHEN** no implementation found for a requirement
-- **THEN** report as CRITICAL issue
-- **AND** suggest: "Implement requirement X" with guidance on what's needed
-
-### Requirement: Coherence Verification
-The agent SHALL verify that implementation is sensible and follows design decisions.
-
-#### Scenario: Design.md adherence check
-- **WHEN** verifying coherence
-- **AND** design.md exists for the change
-- **THEN** extract key decisions from design.md
-- **AND** verify implementation follows those decisions
-- **AND** report any deviations
-
-#### Scenario: No design.md
-- **WHEN** verifying coherence
-- **AND** no design.md exists
-- **THEN** skip design adherence check
-- **AND** note "No design.md to verify against"
-
-#### Scenario: Design decision followed
-- **WHEN** implementation follows a design decision
-- **THEN** report as confirmed
-- **AND** cite evidence from code
-
-#### Scenario: Design decision violated
-- **WHEN** implementation contradicts a design decision
-- **THEN** report as WARNING
-- **AND** explain the contradiction
-- **AND** suggest: either update implementation or update design.md
-
-#### Scenario: Code pattern consistency
-- **WHEN** verifying coherence
-- **THEN** check if new code follows existing project patterns
-- **AND** flag any significant deviations as suggestions
-
-### Requirement: Verification Report Format
-The agent SHALL produce a structured, prioritized report.
-
-#### Scenario: Report summary
-- **WHEN** verification completes
-- **THEN** display summary scorecard:
-  ```
-  ## Verification Report: <change-name>
-
-  ### Summary
-  | Dimension    | Status   |
-  |--------------|----------|
-  | Completeness | X/Y      |
-  | Correctness  | X/Y      |
-  | Coherence    | Followed |
-  ```
-
-#### Scenario: Issue prioritization
-- **WHEN** issues are found
-- **THEN** group and display in priority order:
-  1. CRITICAL - Must fix before archive (missing implementation, incomplete tasks)
-  2. WARNING - Should fix (divergence from spec/design, missing tests)
-  3. SUGGESTION - Nice to fix (pattern inconsistencies, minor improvements)
-
-#### Scenario: Actionable recommendations
-- **WHEN** reporting an issue
-- **THEN** include specific, actionable fix recommendation
-- **AND** reference relevant files and line numbers where applicable
-- **AND** avoid vague suggestions like "consider reviewing"
-
-#### Scenario: All checks pass
-- **WHEN** no issues found across all dimensions
-- **THEN** display:
-  ```
-  All checks passed. Ready for archive.
-  ```
-
-#### Scenario: Critical issues found
-- **WHEN** CRITICAL issues exist
-- **THEN** display:
-  ```
-  X critical issue(s) found. Fix before archiving.
-  ```
-- **AND** do NOT suggest running archive
-
-#### Scenario: Only warnings/suggestions
-- **WHEN** no CRITICAL issues but warnings exist
-- **THEN** display:
-  ```
-  No critical issues. Y warning(s) to consider.
-  Ready for archive (with noted improvements).
-  ```
-
-### Requirement: Flexible Artifact Handling
-The agent SHALL gracefully handle changes with varying artifact completeness.
-
-#### Scenario: Minimal change (tasks only)
-- **WHEN** change has only tasks.md
-- **THEN** verify task completion only
-- **AND** skip spec and design checks
-- **AND** note which checks were skipped
-
-#### Scenario: Change with specs but no design
-- **WHEN** change has tasks.md and delta specs but no design.md
-- **THEN** verify completeness and correctness
-- **AND** skip design adherence
-- **AND** still check code coherence against project patterns
-
-#### Scenario: Full change (all artifacts)
-- **WHEN** change has proposal, design, specs, and tasks
-- **THEN** perform all verification checks
-- **AND** cross-reference artifacts for consistency

package/OpenSpec-main/openspec/changes/archive/2026-02-17-add-verify-skill/tasks.md

@@ -1,15 +0,0 @@
-# Tasks: Add /opsx:verify Skill
-
-## 1. Skill Template Functions
-- [x] 1.1 Add `getVerifyChangeSkillTemplate()` to skill-templates.ts
-- [x] 1.2 Add `getOpsxVerifyCommandTemplate()` to skill-templates.ts
-
-## 2. Integration with artifact-experimental-setup
-- [x] 2.1 Import verify template functions in artifact-workflow.ts
-- [x] 2.2 Add verify to skills array in artifactExperimentalSetupCommand
-- [x] 2.3 Add verify to commands array in artifactExperimentalSetupCommand
-- [x] 2.4 Add verify to help text output
-
-## 3. Verification (Build & Test)
-- [x] 3.1 Verify TypeScript compilation succeeds
-- [x] 3.2 Verify all 8 skills are now included (was 7, now 8)

package/OpenSpec-main/openspec/changes/archive/2026-02-17-merge-init-experimental/.openspec.yaml

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