sauron-cli 1.1.3 → 1.3.0

package/OpenSpec-main/openspec/changes/add-qa-smoke-harness/specs/developer-qa-workflow/spec.md

@@ -0,0 +1,49 @@
+## ADDED Requirements
+
+### Requirement: Makefile QA Entry Point
+
+The repository SHALL provide Makefile targets as the primary developer entrypoint for CLI QA flows.
+
+#### Scenario: Default QA target runs smoke suite
+
+- **WHEN** a developer runs `make qa`
+- **THEN** the command SHALL execute the non-interactive smoke suite
+- **AND** exit with status code 0 only when all smoke scenarios pass
+
+#### Scenario: Smoke suite target is directly invokable
+
+- **WHEN** a developer runs `make qa-smoke`
+- **THEN** the command SHALL execute the same smoke suite used by `make qa`
+- **AND** return a non-zero exit code on assertion failure
+
+#### Scenario: Interactive checklist target exists
+
+- **WHEN** a developer runs `make qa-interactive`
+- **THEN** the command SHALL provide the manual interactive verification checklist
+- **AND** SHALL NOT run interactive prompt automation by default
+
+### Requirement: Sandboxed Smoke Scenario Runner
+
+The smoke suite SHALL run CLI scenarios in isolated sandboxes so tests are repeatable and do not depend on machine-global state.
+
+#### Scenario: Scenario execution is environment-isolated
+
+- **WHEN** a smoke scenario runs
+- **THEN** it SHALL use temporary values for `HOME`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `CODEX_HOME`
+- **AND** global config from the host machine SHALL NOT affect scenario outcomes
+
+#### Scenario: Scenario artifacts are captured for review
+
+- **WHEN** a smoke scenario completes
+- **THEN** the runner SHALL capture command output and exit status
+- **AND** SHALL capture enough filesystem state to inspect before/after behavior
+
+#### Scenario: High-risk workflow coverage exists
+
+- **WHEN** the smoke suite executes
+- **THEN** it SHALL include scenarios covering profile/delivery behavior and migration-sensitive flows
+- **AND** include at least:
+  - non-interactive tool detection
+  - migration when profile is unset
+  - delivery cleanup (`both -> skills`, `both -> commands`)
+  - commands-only update detection

package/OpenSpec-main/openspec/changes/add-tool-command-surface-capabilities/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-19

package/OpenSpec-main/openspec/changes/add-tool-command-surface-capabilities/proposal.md

@@ -0,0 +1,111 @@
+## Why
+
+OpenSpec currently assumes command delivery maps directly to command adapters. That assumption does not hold for all tools.
+
+Trae is a concrete example: it invokes OpenSpec workflows via skill entries (for example `/openspec-new-change`) rather than adapter-generated command files. In this model, skills are the command surface.
+
+Today, this creates a behavior gap:
+
+- `delivery=commands` can remove skills
+- tools without adapters skip command generation
+- result: selected tools like Trae can end up with no invocable workflow artifacts
+
+This is more than a prompt UX issue because non-interactive and CI flows bypass interactive guidance. We need a capability-aware model in core generation logic.
+
+## What Changes
+
+### 1. Add explicit command-surface capability metadata
+
+Add an optional field in tool metadata to describe how a tool exposes commands:
+
+- `adapter`: command files are generated through a command adapter
+- `skills-invocable`: skills are directly invocable as commands
+- `none`: no OpenSpec command surface
+
+Field should be optional. Default behavior is inferred from adapter registry presence: tools with a registered adapter resolve to `adapter`; tools with no adapter registration and no explicit annotation resolve to `none`.
+Capability values use kebab-case string tokens for consistency with serialized metadata conventions.
+
+Initial explicit override:
+
+- Trae -> `skills-invocable`
+
+### 2. Make delivery behavior capability-aware
+
+Update `init` and `update` to compute effective artifact actions per tool from:
+
+- global delivery (`both | skills | commands`)
+- tool command surface capability
+
+Behavior matrix:
+
+- `both`:
+  - generate skills for all tools with `skillsDir` (including `skills-invocable`)
+  - generate command files only for `adapter` tools
+  - `none`: no artifact action; MAY emit compatibility warning
+- `skills`:
+  - generate skills for all tools with `skillsDir` (including `skills-invocable`)
+  - remove adapter-generated command files
+  - `none`: no artifact action; MAY emit compatibility warning
+- `commands`:
+  - `adapter`: generate commands, remove skills
+  - `skills-invocable`: generate (or keep if up-to-date) skills as command surface; do not remove them
+  - `none`: fail fast with clear error
+
+### 3. Add preflight validation and clearer output
+
+Before writing/removing artifacts, validate selected/configured tools against delivery mode:
+
+- interactive flow: show clear compatibility note before confirmation
+- non-interactive flow: fail with deterministic error listing incompatible tools and supported alternatives
+
+Update summaries to show effective delivery outcomes per tool (for example, when commands mode still installs skills for skills-invocable tools).
+
+### 4. Update docs and tests
+
+- document capability model and Trae behavior under delivery modes
+- ensure CLI docs and supported-tools docs reflect effective behavior
+- add test coverage for:
+  - `init --tools trae` with `delivery=commands`
+  - `update` with Trae configured under `delivery=commands`
+  - mixed selections (`claude + trae`) across all delivery modes
+  - explicit error path for tools with no command surface under `delivery=commands`
+
+### 5. Coordinate with install-scope behavior
+
+When combined with `add-global-install-scope`, init/update planning must compose:
+
+- install scope (`global | project`)
+- delivery mode (`both | skills | commands`)
+- command surface capability (`adapter | skills-invocable | none`)
+
+Implementation tests should cover mixed-tool matrices to ensure deterministic behavior when both changes are active.
+
+## Capabilities
+
+### New Capabilities
+
+- `tool-command-surface`: Capability model that classifies tools as `adapter`, `skills-invocable`, or `none` to drive delivery behavior
+
+### Modified Capabilities
+
+- `cli-init`: Delivery handling becomes tool-capability-aware with preflight compatibility validation
+- `cli-update`: Delivery sync becomes tool-capability-aware with consistent compatibility validation and messaging
+- `supported-tools-docs`: Documents command-surface semantics for non-adapter tools
+
+## Impact
+
+- `src/core/config.ts` - add optional command-surface metadata and Trae override
+- `src/core/command-generation/registry.ts` (or shared helper) - capability inference from adapter presence
+- `src/core/init.ts` - capability-aware generation/removal planning + compatibility validation + summary messaging
+- `src/core/update.ts` - capability-aware sync/removal planning + compatibility validation + summary messaging
+- `src/core/shared/tool-detection.ts` - include capability-aware detection so `skills-invocable` tools remain detectable under `delivery=commands`, and `none` tools are excluded from command-surface artifact detection
+- `docs/supported-tools.md` and `docs/cli.md` - document delivery behavior and compatibility notes
+- `test/core/init.test.ts` and `test/core/update.test.ts` - add coverage for skills-invocable behavior and mixed-tool delivery scenarios
+
+## Sequencing Notes
+
+- This change is intended to stack safely with `simplify-skill-installation` by introducing additive, capability-specific requirements for init/update.
+- If `simplify-skill-installation` merges first, this change should be rebased and keep the capability-aware rule as the source of truth for `delivery=commands` behavior on `skills-invocable` tools.
+- If this change merges first, the `simplify-skill-installation` branch should be rebased to avoid re-introducing a global "commands-only means no skills for all tools" assumption.
+- If `add-global-install-scope` merges first, this change should be rebased to compose capability-aware behavior on top of scope-resolved path decisions from that change.
+- If this change merges first, `add-global-install-scope` should be rebased to preserve Section 5 composition rules (`install scope` + `delivery mode` + `command surface capability`) without overriding capability-aware command-surface outcomes.

package/OpenSpec-main/openspec/changes/add-tool-command-surface-capabilities/specs/cli-init/spec.md

@@ -0,0 +1,121 @@
+## ADDED Requirements
+
+### Requirement: Command surface capability resolution
+The init command SHALL resolve each selected tool's command surface using explicit metadata first, then deterministic inference.
+
+#### Scenario: Explicit command surface override
+- **WHEN** a tool declares an explicit command-surface capability
+- **THEN** init SHALL use that explicit capability
+- **AND** SHALL NOT override it based on adapter presence
+
+#### Scenario: Inferred command surface from adapter presence
+- **WHEN** a tool does not declare an explicit command-surface capability
+- **AND** a command adapter is registered for the tool
+- **THEN** init SHALL infer `adapter` as the command surface
+
+#### Scenario: Inferred command surface for skills-only tool
+- **WHEN** a tool does not declare an explicit command-surface capability
+- **AND** no command adapter is registered for the tool
+- **AND** the tool has a configured `skillsDir`
+- **THEN** init SHALL infer `skills-invocable` as the command surface
+
+#### Scenario: Inferred command surface without adapter or skills
+- **WHEN** a tool does not declare an explicit command-surface capability
+- **AND** no command adapter is registered for the tool
+- **AND** the tool has no `skillsDir`
+- **THEN** init SHALL infer `none` as the command surface
+
+### Requirement: Delivery compatibility by tool command surface
+The init command SHALL apply delivery settings using each tool's command surface capability, not adapter presence alone.
+
+#### Scenario: Both delivery for adapter-backed tool
+- **WHEN** user runs `openspec init` with a selected tool that has a command adapter
+- **AND** delivery is set to `both`
+- **THEN** the system SHALL generate command files for active workflows using that adapter
+- **AND** SHALL generate or refresh managed skills when the tool has `skillsDir`
+
+#### Scenario: Both delivery for skills-invocable tool
+- **WHEN** user runs `openspec init` with a selected tool whose command surface is `skills-invocable`
+- **AND** delivery is set to `both`
+- **THEN** the system SHALL generate or refresh managed skill directories when the tool has `skillsDir`
+- **AND** SHALL NOT require adapter-generated command files for that tool
+
+#### Scenario: Both delivery for none command surface
+- **WHEN** user runs `openspec init` with a selected tool whose command surface is `none`
+- **AND** delivery is set to `both`
+- **THEN** the system SHALL perform no command-surface artifact action for that tool
+- **AND** MAY emit a compatibility note indicating no command surface is available
+
+#### Scenario: Skills delivery for adapter-backed tool
+- **WHEN** user runs `openspec init` with a selected tool that has a command adapter
+- **AND** delivery is set to `skills`
+- **THEN** the system SHALL generate or refresh managed skill directories when the tool has `skillsDir`
+- **AND** SHALL remove managed adapter-generated command files for that tool
+
+#### Scenario: Skills delivery for skills-invocable tool
+- **WHEN** user runs `openspec init` with a selected tool whose command surface is `skills-invocable`
+- **AND** delivery is set to `skills`
+- **THEN** the system SHALL generate or refresh managed skill directories when the tool has `skillsDir`
+- **AND** SHALL NOT require adapter-generated command files for that tool
+
+#### Scenario: Skills delivery for none command surface
+- **WHEN** user runs `openspec init` with a selected tool whose command surface is `none`
+- **AND** delivery is set to `skills`
+- **THEN** the system SHALL perform no command-surface artifact action for that tool
+- **AND** MAY emit a compatibility note indicating no command surface is available
+
+#### Scenario: Commands delivery for adapter-backed tool
+- **WHEN** user runs `openspec init` with a selected tool that has a command adapter
+- **AND** delivery is set to `commands`
+- **THEN** the system SHALL generate command files for active workflows using that adapter
+- **AND** the system SHALL remove managed skill directories for that tool
+
+#### Scenario: Commands delivery for skills-invocable tool
+- **WHEN** user runs `openspec init` with a selected tool whose command surface is `skills-invocable`
+- **AND** delivery is set to `commands`
+- **THEN** the system SHALL generate or refresh managed skill directories for active workflows
+- **AND** the system SHALL NOT remove those managed skill directories as part of commands-only cleanup
+- **AND** the system SHALL NOT require a command adapter for that tool
+
+#### Scenario: Commands delivery for mixed tool selection
+- **WHEN** user runs `openspec init` with multiple tools
+- **AND** selected tools include both adapter-backed and skills-invocable command surfaces
+- **AND** delivery is set to `commands`
+- **THEN** the system SHALL apply commands-only behavior per tool capability
+- **AND** the resulting install SHALL include command files for adapter-backed tools and skills for skills-invocable tools
+
+#### Scenario: Commands delivery for unsupported command surface
+- **WHEN** user runs `openspec init` with a selected tool that has no command surface capability
+- **AND** delivery is set to `commands`
+- **THEN** the system SHALL fail before generating or deleting artifacts
+- **AND** the error SHALL list incompatible tool IDs and explain supported alternatives (`both` or `skills`)
+
+#### Scenario: Interactive handling for unsupported command surface
+- **WHEN** user runs `openspec init` interactively
+- **AND** delivery is set to `commands`
+- **AND** selected tools include one or more tools with command surface `none`
+- **THEN** the CLI SHALL show a compatibility error and return to the interactive selection flow for correction
+- **AND** SHALL not perform artifact writes until a valid selection is confirmed
+
+### Requirement: Init compatibility signaling
+The init command SHALL clearly signal command-surface compatibility outcomes in both interactive and non-interactive flows.
+
+#### Scenario: Interactive compatibility note
+- **WHEN** init runs interactively
+- **AND** delivery is `commands`
+- **AND** selected tools include skills-invocable command surfaces
+- **THEN** the system SHALL display a compatibility note before the confirmation prompt indicating those tools will use skills as their command surface
+
+#### Scenario: Non-interactive compatibility summary for skills-invocable tools
+- **WHEN** init runs non-interactively (including `--tools` usage)
+- **AND** delivery is `commands`
+- **AND** selected tools include one or more `skills-invocable` command surfaces
+- **THEN** the command SHALL proceed with exit code 0
+- **AND** the command SHALL write deterministic compatibility summary lines to stdout indicating those tools will use managed skills as their command surface
+
+#### Scenario: Non-interactive compatibility failure
+- **WHEN** init runs non-interactively (including `--tools` usage)
+- **AND** delivery is `commands`
+- **AND** selected tools include any tool with no command surface capability
+- **THEN** the command SHALL exit with code 1
+- **AND** the command SHALL write deterministic, actionable guidance for resolving the selection to stderr

package/OpenSpec-main/openspec/changes/add-tool-command-surface-capabilities/specs/cli-update/spec.md

@@ -0,0 +1,48 @@
+## ADDED Requirements
+
+### Requirement: Delivery sync by command surface capability
+The update command SHALL synchronize artifacts using each configured tool's command surface capability.
+
+#### Scenario: Commands delivery for adapter-backed configured tool
+- **WHEN** user runs `openspec update`
+- **AND** delivery is set to `commands`
+- **AND** a configured tool has an adapter-backed command surface
+- **THEN** the system SHALL generate or refresh command files for active workflows
+- **AND** the system SHALL remove managed skill directories for that tool
+
+#### Scenario: Commands delivery for skills-invocable configured tool
+- **WHEN** user runs `openspec update`
+- **AND** delivery is set to `commands`
+- **AND** a configured tool has `skills-invocable` command surface capability
+- **THEN** the system SHALL generate or refresh managed skill directories for active workflows
+- **AND** the system SHALL NOT remove those managed skill directories as part of commands-only cleanup
+- **AND** the system SHALL NOT attempt to require adapter-generated command files for that tool
+
+#### Scenario: Commands delivery with unsupported command surface
+- **WHEN** user runs `openspec update`
+- **AND** delivery is set to `commands`
+- **AND** a configured tool has no command surface capability
+- **THEN** the system SHALL fail with exit code 1 before applying partial updates
+- **AND** the output SHALL identify incompatible tools and recommended remediation
+
+### Requirement: Configured-tool detection for skills-invocable command surfaces
+The update command SHALL treat tools with skills-invocable command surfaces as configured when managed skill artifacts are present, including under commands delivery.
+
+#### Scenario: Skills-invocable tool under commands delivery
+- **WHEN** user runs `openspec update`
+- **AND** delivery is set to `commands`
+- **AND** a tool has no adapter-generated command files
+- **AND** that tool is marked `skills-invocable` and has managed skills installed
+- **THEN** the system SHALL include the tool in configured-tool detection
+- **AND** the system SHALL apply normal version/profile/delivery sync to that tool
+
+### Requirement: Update summary reflects effective per-tool delivery
+The update command SHALL report effective artifact behavior when delivery intent and artifact type differ due to tool capability.
+
+#### Scenario: Summary for skills-invocable tools in commands delivery
+- **WHEN** update completes successfully
+- **AND** delivery is `commands`
+- **AND** at least one updated tool is `skills-invocable`
+- **THEN** output SHALL include a clear note that those tools use skills as their command surface
+- **AND** output SHALL avoid implying that command generation was skipped due to an error
+

package/OpenSpec-main/openspec/changes/add-tool-command-surface-capabilities/tasks.md

@@ -0,0 +1,53 @@
+## 0. Stacking Coordination
+
+- [ ] 0.1 Rebase this change on latest `main` before implementation
+- [ ] 0.2 If `simplify-skill-installation` is merged first, preserve its profile/delivery model and apply this change as a capability-aware refinement
+- [ ] 0.3 If this change merges first, ensure follow-up rebases do not reintroduce a blanket "commands = remove all skills" rule
+- [ ] 0.4 If `add-global-install-scope` is merged, verify combined scope × delivery × command-surface behavior remains deterministic
+
+## 1. Tool Command-Surface Capability Model
+
+- [ ] 1.1 Extend tool metadata in `src/core/config.ts` with an optional command-surface capability field
+- [ ] 1.2 Define supported capability values: `adapter`, `skills-invocable`, `none`
+- [ ] 1.3 Mark Trae as `skills-invocable`
+- [ ] 1.4 Add a shared capability resolver (explicit metadata override first, inferred fallback from adapter presence second)
+- [ ] 1.5 Add focused unit tests for capability resolution (explicit override, inferred adapter, inferred none)
+
+## 2. Init: Capability-Aware Delivery Planning
+
+- [ ] 2.1 Refactor init generation logic to compute per-tool effective actions (generate/remove skills and commands) instead of using only global booleans
+- [ ] 2.2 In `delivery=commands`, keep/generate skills for `skills-invocable` tools and do not remove those managed skill directories
+- [ ] 2.3 In `delivery=commands`, fail fast before writes when any selected tool resolves to `none`
+- [ ] 2.4 Update init output to clearly report effective behavior for `skills-invocable` tools (skills used as command surface)
+- [ ] 2.5 Ensure init no longer reports "no adapter" for tools intentionally using `skills-invocable`
+- [ ] 2.6 Add/adjust init tests for `delivery=commands` + `trae` (skills retained/generated, no adapter error), mixed tools (`claude,trae`) with per-tool expected outputs, and deterministic failure path for unsupported command surface (`none`)
+
+## 3. Update: Capability-Aware Sync and Drift Detection
+
+- [ ] 3.1 Refactor update sync logic to apply delivery behavior per tool capability (not globally per run)
+- [ ] 3.2 In `delivery=commands`, keep/generate managed skills for `skills-invocable` tools
+- [ ] 3.3 In `delivery=commands`, fail before partial updates when configured tools include a `none` command surface
+- [ ] 3.4 Update profile/delivery drift detection to avoid perpetual drift for `skills-invocable` tools under commands delivery
+- [ ] 3.5 Ensure configured-tool detection still includes `skills-invocable` tools under commands delivery when managed skills exist
+- [ ] 3.6 Update summary output so skills-invocable behavior is reported as expected behavior (not implicit skip/error)
+- [ ] 3.7 Add/adjust update tests for `delivery=commands` + configured Trae (skills retained/generated), idempotent second update (no false drift loop), mixed configured tools (`claude` + `trae`), and deterministic preflight failure for unsupported command surface (`none`)
+
+## 4. UX and Error Messaging
+
+- [ ] 4.1 Add interactive init compatibility note for `delivery=commands` when selected tools include `skills-invocable`
+- [ ] 4.2 Add deterministic non-interactive error text with incompatible tool IDs and suggested alternatives (`both` or `skills`)
+- [ ] 4.3 Align init and update wording so capability-related behavior/messages are consistent
+
+## 5. Documentation Updates
+
+- [ ] 5.1 Update `docs/supported-tools.md` to document command-surface semantics for Trae and clarify delivery interactions
+- [ ] 5.2 Update `docs/cli.md` delivery guidance to explain capability-aware behavior for `delivery=commands`
+- [ ] 5.3 Add a short troubleshooting note for "commands-only + unsupported tool" failures
+
+## 6. Verification
+
+- [ ] 6.1 Run targeted tests: `test/core/init.test.ts` and `test/core/update.test.ts`
+- [ ] 6.2 Run any new capability/unit test files added in this change
+- [ ] 6.3 Run full test suite (`pnpm test`) and resolve regressions
+- [ ] 6.4 Manual smoke check: `openspec init --tools trae` with `delivery=commands`
+- [ ] 6.5 Manual smoke check: mixed tools (`claude,trae`) with `delivery=commands`

package/OpenSpec-main/openspec/changes/archive/2025-01-11-add-update-command/design.md

@@ -0,0 +1,86 @@
+# Technical Design
+
+## Architecture Decisions
+
+### Simplicity First
+- No version tracking - always update when commanded
+- Full replacement for OpenSpec-managed files only (e.g., `openspec/README.md`)
+- Marker-based updates for user-owned files (e.g., `CLAUDE.md`)
+- Templates bundled with package - no network required
+- Minimal error handling - only check prerequisites
+
+### Template Strategy
+- Use existing template utilities
+  - `readmeTemplate` from `src/core/templates/readme-template.ts` for `openspec/README.md`
+  - `TemplateManager.getClaudeTemplate()` for `CLAUDE.md`
+- Directory name is fixed to `openspec` (from `OPENSPEC_DIR_NAME`)
+
+### File Operations
+- Use async utilities for consistency
+  - `FileSystemUtils.writeFile` for `openspec/README.md`
+  - `FileSystemUtils.updateFileWithMarkers` for `CLAUDE.md`
+- No atomic operations needed - users have git
+- Check directory existence before proceeding
+
+## Implementation
+
+### Update Command (`src/core/update.ts`)
+```typescript
+export class UpdateCommand {
+  async execute(projectPath: string): Promise<void> {
+    const openspecDirName = OPENSPEC_DIR_NAME;
+    const openspecPath = path.join(projectPath, openspecDirName);
+
+    // 1. Check openspec directory exists
+    if (!await FileSystemUtils.directoryExists(openspecPath)) {
+      throw new Error(`No OpenSpec directory found. Run 'openspec init' first.`);
+    }
+
+    // 2. Update README.md (full replacement)
+    const readmePath = path.join(openspecPath, 'README.md');
+    await FileSystemUtils.writeFile(readmePath, readmeTemplate);
+
+    // 3. Update CLAUDE.md (marker-based)
+    const claudePath = path.join(projectPath, 'CLAUDE.md');
+    const claudeContent = TemplateManager.getClaudeTemplate();
+    await FileSystemUtils.updateFileWithMarkers(
+      claudePath,
+      claudeContent,
+      OPENSPEC_MARKERS.start,
+      OPENSPEC_MARKERS.end
+    );
+
+    // 4. Success message (ASCII-safe, checkmark optional by terminal)
+    console.log('Updated OpenSpec instructions');
+  }
+}
+```
+
+## Why This Approach
+
+### Benefits
+- **Dead simple**: ~40 lines of code total
+- **Fast**: No version checks, minimal parsing
+- **Predictable**: Same result every time; idempotent
+- **Maintainable**: Reuses existing utilities
+
+### Trade-offs Accepted
+- No version tracking (unnecessary complexity)
+- Full overwrite only for OpenSpec-managed files
+- Marker-managed updates for user-owned files
+
+## Error Handling
+
+Only handle critical errors:
+- Missing `openspec` directory → throw error handled by CLI to present a friendly message
+- File write failures → let errors bubble up to CLI
+
+## Testing Strategy
+
+Manual smoke tests are sufficient initially:
+1. Run `openspec init` in a test project
+2. Modify both files (including custom content around markers in `CLAUDE.md`)
+3. Run `openspec update`
+4. Verify `openspec/README.md` fully replaced; `CLAUDE.md` OpenSpec block updated without altering user content outside markers
+5. Run the command twice to verify idempotency and no duplicate markers
+6. Test with missing `openspec` directory (expect failure)

package/OpenSpec-main/openspec/changes/archive/2025-01-11-add-update-command/proposal.md

@@ -0,0 +1,29 @@
+# Add Update Command
+
+## Why
+
+Users need a way to update their local OpenSpec instructions (README.md and CLAUDE.md) when the OpenSpec package releases new versions with improved AI agent instructions or structural conventions.
+
+## What Changes
+
+- Add new `openspec update` CLI command that updates OpenSpec instructions
+- Replace `openspec/README.md` with the latest template
+  - Safe because this file is fully OpenSpec-managed
+- Update only the OpenSpec-managed block in `CLAUDE.md` using markers
+  - Preserve all user content outside markers
+  - If `CLAUDE.md` is missing, create it with the managed block
+- Display success message after update (ASCII-safe): "Updated OpenSpec instructions"
+  - A leading checkmark MAY be shown when the terminal supports it
+  - Operation is idempotent (re-running yields identical results)
+
+## Impact
+
+- Affected specs: `cli-update` (new capability)
+- Affected code:
+  - `src/core/update.ts` (new command class, mirrors `InitCommand` placement)
+  - `src/cli/index.ts` (register new command)
+  - Uses existing templates via `TemplateManager` and `readmeTemplate`
+
+## Out of Scope
+
+- No `.openspec/config.json` is introduced by this change. The default directory name `openspec` is used.

package/OpenSpec-main/openspec/changes/archive/2025-01-11-add-update-command/specs/cli-update/spec.md

@@ -0,0 +1,59 @@
+# Update Command Specification
+
+## Purpose
+
+As a developer using OpenSpec, I want to update the OpenSpec instructions in my project when new versions are released, so that I can benefit from improvements to AI agent instructions.
+
+## Core Requirements
+
+### Update Behavior
+
+The update command SHALL update OpenSpec instruction files to the latest templates.
+
+WHEN a user runs `openspec update` THEN the command SHALL:
+- Check if the `openspec` directory exists
+- Replace `openspec/README.md` with the latest template (complete replacement)
+- Update the OpenSpec-managed block in `CLAUDE.md` using markers
+  - Preserve user content outside markers
+  - Create `CLAUDE.md` if missing
+- Display ASCII-safe success message: "Updated OpenSpec instructions"
+
+### Prerequisites
+
+The command SHALL require:
+- An existing `openspec` directory (created by `openspec init`)
+
+IF the `openspec` directory does not exist THEN:
+- Display error: "No OpenSpec directory found. Run 'openspec init' first."
+- Exit with code 1
+
+### File Handling
+
+The update command SHALL:
+- Completely replace `openspec/README.md` with the latest template
+- Update only the OpenSpec-managed block in `CLAUDE.md` using markers
+- Use the default directory name `openspec`
+- Be idempotent (repeated runs have no additional effect)
+
+## Edge Cases
+
+### File Permissions
+IF file write fails THEN let the error bubble up naturally with file path.
+
+### Missing CLAUDE.md
+IF CLAUDE.md doesn't exist THEN create it with the template content.
+
+### Custom Directory Name
+Not supported in this change. The default directory name `openspec` SHALL be used.
+
+## Success Criteria
+
+Users SHALL be able to:
+- Update OpenSpec instructions with a single command
+- Get the latest AI agent instructions
+- See clear confirmation of the update
+
+The update process SHALL be:
+- Simple and fast (no version checking)
+- Predictable (same result every time)
+- Self-contained (no network required)

package/OpenSpec-main/openspec/changes/archive/2025-01-11-add-update-command/tasks.md

@@ -0,0 +1,20 @@
+# Implementation Tasks
+
+## 1. Update Command Implementation
+- [x] 1.1 Create `src/core/update.ts` with `UpdateCommand` class
+- [x] 1.2 Check if `openspec` directory exists (use `FileSystemUtils.directoryExists`)
+- [x] 1.3 Write `readmeTemplate` to `openspec/README.md` using `FileSystemUtils.writeFile`
+- [x] 1.4 Update `CLAUDE.md` using markers via `FileSystemUtils.updateFileWithMarkers` and `TemplateManager.getClaudeTemplate()`
+- [x] 1.5 Display ASCII-safe success message: `Updated OpenSpec instructions`
+
+## 2. CLI Integration
+- [x] 2.1 Register `update` command in `src/cli/index.ts`
+- [x] 2.2 Add command description: `Update OpenSpec instruction files`
+- [x] 2.3 Handle errors with `ora().fail(...)` and exit code 1 (missing `openspec` directory, file write errors)
+
+## 3. Testing
+- [x] 3.1 Verify `openspec/README.md` is fully replaced with latest template
+- [x] 3.2 Verify `CLAUDE.md` OpenSpec block updates without altering user content outside markers
+- [x] 3.3 Verify idempotency (running twice yields identical files, no duplicate markers)
+- [x] 3.4 Verify error when `openspec` directory is missing with friendly message
+- [x] 3.5 Verify success message displays properly in ASCII-only terminals

package/OpenSpec-main/openspec/changes/archive/2025-01-13-add-list-command/proposal.md

@@ -0,0 +1,20 @@
+# Add List Command to OpenSpec CLI
+
+## Why
+
+Developers need visibility into available changes and their status to understand the project's evolution and pending work.
+
+## What Changes
+
+- Add `openspec list` command that displays all changes in the changes/ directory
+- Show each change name with task completion count (e.g., "add-auth: 3/5 tasks")
+- Display completion status indicator (✓ for fully complete, progress for partial)
+- Skip the archive/ subdirectory to focus on active changes
+- Simple table output for easy scanning
+
+## Impact
+
+- Affected specs: New capability `cli-list` will be added
+- Affected code:
+  - `src/cli/index.ts` - Add list command
+  - `src/core/list.ts` - New file with directory scanning and task parsing (~60 lines)