sauron-cli 1.3.0 → 1.4.0

package/OpenSpec-main/openspec/changes/archive/2025-08-06-add-init-command/specs/cli-init/spec.md

@@ -1,148 +0,0 @@
-# CLI Init Specification
-
-## Purpose
-
-The `openspec init` command SHALL create a complete OpenSpec directory structure in any project, enabling immediate adoption of OpenSpec conventions with support for multiple AI coding assistants.
-
-## Behavior
-
-### Progress Indicators
-
-WHEN executing initialization steps
-THEN validate environment silently in background (no output unless error)
-AND display progress with ora spinners:
-- Show spinner: "⠋ Creating OpenSpec structure..."
-- Then success: "✔ OpenSpec structure created"
-- Show spinner: "⠋ Configuring AI tools..."
-- Then success: "✔ AI tools configured"
-
-### Directory Creation
-
-WHEN `openspec init` is executed
-THEN create the following directory structure:
-```
-openspec/
-├── project.md
-├── README.md
-├── specs/
-└── changes/
-    └── archive/
-```
-
-### File Generation
-
-The command SHALL generate:
-- `README.md` containing complete OpenSpec instructions for AI assistants
-- `project.md` with project context template
-
-### AI Tool Configuration
-
-WHEN run interactively
-THEN prompt user to select AI tools to configure:
-- Claude Code (updates/creates CLAUDE.md with OpenSpec markers)
-- Cursor (future)
-- Aider (future)
-
-### AI Tool Configuration Details
-
-WHEN Claude Code is selected
-THEN create or update `CLAUDE.md` in the project root directory (not inside openspec/)
-
-WHEN CLAUDE.md does not exist
-THEN create new file with OpenSpec content wrapped in markers:
-```markdown
-<!-- OPENSPEC:START -->
-# OpenSpec Project
-
-This document provides instructions for AI coding assistants on how to use OpenSpec conventions for spec-driven development. Follow these rules precisely when working on OpenSpec-enabled projects.
-
-This project uses OpenSpec for spec-driven development. Specifications are the source of truth.
-
-See @openspec/README.md for detailed conventions and guidelines.
-<!-- OPENSPEC:END -->
-```
-
-WHEN CLAUDE.md already exists
-THEN preserve all existing content
-AND insert OpenSpec content at the beginning of the file using markers
-AND ensure markers don't duplicate if they already exist
-
-The marker system SHALL:
-- Use `<!-- OPENSPEC:START -->` to mark the beginning of managed content
-- Use `<!-- OPENSPEC:END -->` to mark the end of managed content
-- Allow OpenSpec to update its content without affecting user customizations
-- Preserve all content outside the markers intact
-
-WHY use markers:
-- Users may have existing CLAUDE.md instructions they want to keep
-- OpenSpec can update its instructions in future versions
-- Clear boundary between OpenSpec-managed and user-managed content
-
-### Interactive Mode
-
-WHEN run
-THEN prompt user with: "Which AI tool do you use?"
-AND show single-select menu with available tools:
-- Claude Code
-AND show disabled options as "coming soon" (not selectable):
-- Cursor (coming soon)
-- Aider (coming soon)  
-- Continue (coming soon)
-
-User navigation:
-- Use arrow keys to move between options
-- Press Enter to select the highlighted option
-
-### Safety Checks
-
-WHEN `openspec/` directory already exists
-THEN display error with ora fail indicator:
-"✖ Error: OpenSpec seems to already be initialized. Use 'openspec update' to update the structure."
-
-WHEN checking initialization feasibility
-THEN verify write permissions in the target directory silently
-AND only display error if permissions are insufficient
-
-### Success Output
-
-WHEN initialization completes successfully
-THEN display actionable prompts for AI-driven workflow:
-```
-✔ OpenSpec initialized successfully!
-
-Next steps - Copy these prompts to Claude:
-
-────────────────────────────────────────────────────────────
-1. Populate your project context:
-   "Please read openspec/project.md and help me fill it out
-    with details about my project, tech stack, and conventions"
-
-2. Create your first change proposal:
-   "I want to add [YOUR FEATURE HERE]. Please create an
-    OpenSpec change proposal for this feature"
-
-3. Learn the OpenSpec workflow:
-   "Please explain the OpenSpec workflow from openspec/README.md
-    and how I should work with you on this project"
-────────────────────────────────────────────────────────────
-```
-
-The prompts SHALL:
-- Be copy-pasteable for immediate use with AI tools
-- Guide users through the AI-driven workflow
-- Replace placeholder text ([YOUR FEATURE HERE]) with actual features
-
-### Exit Codes
-
-- 0: Success
-- 1: General error (including when OpenSpec directory already exists)
-- 2: Insufficient permissions (reserved for future use)
-- 3: User cancelled operation (reserved for future use)
-
-## Why
-
-Manual creation of OpenSpec structure is error-prone and creates adoption friction. A standardized init command ensures:
-- Consistent structure across all projects
-- Proper AI instruction files are always included
-- Quick onboarding for new projects
-- Clear conventions from the start

package/OpenSpec-main/openspec/changes/archive/2025-08-06-add-init-command/tasks.md

@@ -1,38 +0,0 @@
-# Implementation Tasks for Init Command
-
-## 1. Core Infrastructure
-- [x] 1.1 Create src/utils/file-system.ts with directory/file creation utilities
-- [x] 1.2 Create src/core/templates/index.ts for template management
-- [x] 1.3 Create src/core/init.ts with main initialization logic
-- [x] 1.4 Create src/core/config.ts for configuration management
-
-## 2. Template Files
-- [x] 2.1 Create src/core/templates/readme-template.ts with OpenSpec README content
-- [x] 2.2 Create src/core/templates/project-template.ts with customizable project.md
-- [x] 2.3 Create src/core/templates/claude-template.ts for CLAUDE.md content with markers
-
-## 3. AI Tool Configurators
-- [x] 3.1 Create src/core/configurators/base.ts with ToolConfigurator interface
-- [x] 3.2 Create src/core/configurators/claude.ts for Claude Code configuration
-- [x] 3.3 Create src/core/configurators/registry.ts for tool registration
-- [x] 3.4 Implement marker-based file updates for existing configurations
-
-## 4. Init Command Implementation
-- [x] 4.1 Add init command to src/cli/index.ts using Commander
-- [x] 4.2 Implement AI tool selection with multi-select prompt (Claude Code available, others "coming soon") - requires at least one selection
-- [x] 4.3 Add validation for existing OpenSpec directories with helpful error message
-- [x] 4.4 Implement directory structure creation
-- [x] 4.5 Implement file generation with templates and markers
-
-## 5. User Experience
-- [x] 5.1 Add colorful console output for better UX
-- [x] 5.2 Implement progress indicators (Step 1/3, 2/3, 3/3)
-- [x] 5.3 Add success message with actionable next steps (edit project.md, create first change)
-- [x] 5.4 Add error handling with helpful messages
-
-## 6. Testing and Documentation
-- [x] 6.1 Add unit tests for file system utilities
-- [x] 6.2 Add unit tests for marker-based file updates
-- [x] 6.3 Add integration tests for init command
-- [x] 6.4 Update package.json with proper bin configuration
-- [x] 6.5 Test the built CLI command end-to-end

package/OpenSpec-main/openspec/changes/archive/2025-08-06-adopt-future-state-storage/proposal.md

@@ -1,24 +0,0 @@
-# Adopt Future State Storage for OpenSpec Changes
-
-## Why
-
-The current approach of storing spec changes as diff files (`.spec.md.diff`) creates friction for both humans and AI. Diff syntax with `+` and `-` prefixes makes specs hard to read, AI tools struggle with the format when understanding future state, and GitHub can't show nice comparisons between current and proposed specs in different folders.
-
-## What Changes
-
-- Change from storing diffs (`patches/[capability]/spec.md.diff`) to storing complete future state (`specs/[capability]/spec.md`)
-- Update all documentation to reflect new storage format
-- Migrate existing `add-init-command` change to new format
-- Add new `openspec-conventions` capability to document these conventions
-
-
-
-## Impact
-
-- Affected specs: New `openspec-conventions` capability
-- Affected code: 
-  - openspec/README.md (lines 85-108)
-  - docs/PRD.md (lines 376-382, 778-783)
-  - docs/openspec-walkthrough.md (lines 58-62, 112-126)
-  - openspec/changes/add-init-command/ (migration needed)
-

package/OpenSpec-main/openspec/changes/archive/2025-08-06-adopt-future-state-storage/specs/openspec-conventions/spec.md

@@ -1,120 +0,0 @@
-# OpenSpec Conventions Specification
-
-## Purpose
-
-OpenSpec conventions SHALL define how system capabilities are documented, how changes are proposed and tracked, and how specifications evolve over time. This meta-specification serves as the source of truth for OpenSpec's own conventions.
-
-## Core Principles
-
-The system SHALL follow these principles:
-- Specs reflect what IS currently built and deployed
-- Changes contain proposals for what SHOULD be changed
-- AI drives the documentation process
-- Specs are living documentation kept in sync with deployed code
-
-## Directory Structure
-
-WHEN an OpenSpec project is initialized
-THEN it SHALL have this structure:
-```
-openspec/
-├── project.md              # Project-specific context
-├── README.md               # AI assistant instructions
-├── specs/                  # Current deployed capabilities
-│   └── [capability]/       # Single, focused capability
-│       ├── spec.md         # WHAT and WHY
-│       └── design.md       # HOW (optional, for established patterns)
-└── changes/                # Proposed changes
-    ├── [change-name]/      # Descriptive change identifier
-    │   ├── proposal.md     # Why, what, and impact
-    │   ├── tasks.md        # Implementation checklist
-    │   ├── design.md       # Technical decisions (optional)
-    │   └── specs/          # Complete future state
-    │       └── [capability]/
-    │           └── spec.md # Clean markdown (no diff syntax)
-    └── archive/            # Completed changes
-        └── YYYY-MM-DD-[name]/
-```
-
-## Change Storage Convention
-
-### Future State Storage
-
-WHEN creating a change proposal
-THEN store the complete future state of affected specs
-AND use clean markdown without diff syntax
-
-The `changes/[name]/specs/` directory SHALL contain:
-- Complete spec files as they will exist after the change
-- Clean markdown without `+` or `-` prefixes
-- All formatting and structure of the final intended state
-
-### Proposal Format
-
-WHEN documenting what changes
-THEN the proposal SHALL explicitly describe each change:
-
-```markdown
-**[Section or Behavior Name]**
-- From: [current state/requirement]
-- To: [future state/requirement]
-- Reason: [why this change is needed]
-- Impact: [breaking/non-breaking, who's affected]
-```
-
-This explicit format compensates for not having inline diffs and ensures reviewers understand exactly what will change.
-
-## Change Lifecycle
-
-The change process SHALL follow these states:
-
-1. **Propose**: AI creates change with future state specs and explicit proposal
-2. **Review**: Humans review proposal and future state
-3. **Approve**: Change is approved for implementation
-4. **Implement**: Follow tasks.md checklist (can span multiple PRs)
-5. **Deploy**: Changes are deployed to production
-6. **Update**: Specs in `specs/` are updated to match deployed reality
-7. **Archive**: Change is moved to `archive/YYYY-MM-DD-[name]/`
-
-## Viewing Changes
-
-WHEN reviewing proposed changes
-THEN reviewers can compare using:
-- GitHub PR diff view when changes are committed
-- Command line: `diff -u specs/[capability]/spec.md changes/[name]/specs/[capability]/spec.md`
-- Any visual diff tool comparing current vs future state
-
-The system relies on tools to generate diffs rather than storing them.
-
-## Capability Naming
-
-Capabilities SHALL use:
-- Verb-noun patterns (e.g., `user-auth`, `payment-capture`)
-- Hyphenated lowercase names
-- Singular focus (one responsibility per capability)
-- No nesting (flat structure under `specs/`)
-
-## When Changes Require Proposals
-
-A proposal SHALL be created for:
-- New features or capabilities
-- Breaking changes to existing behavior
-- Architecture or pattern changes
-- Performance optimizations that change behavior
-- Security updates affecting access patterns
-
-A proposal is NOT required for:
-- Bug fixes restoring intended behavior
-- Typos or formatting fixes
-- Non-breaking dependency updates
-- Adding tests for existing behavior
-- Documentation clarifications
-
-## Why This Approach
-
-Clean future state storage provides:
-- **Readability**: No diff syntax pollution
-- **AI-compatibility**: Standard markdown that AI tools understand
-- **Simplicity**: No special parsing or processing needed
-- **Tool-agnostic**: Any diff tool can show changes
-- **Clear intent**: Explicit proposals document reasoning

package/OpenSpec-main/openspec/changes/archive/2025-08-06-adopt-future-state-storage/tasks.md

@@ -1,38 +0,0 @@
-# Implementation Tasks
-
-## 1. Update Core Documentation
-- [x] 1.1 Update openspec/README.md section on "Creating a Change Proposal"
-  - [x] Replace `patches/` with `specs/` in directory structure
-  - [x] Update step 3 to show storing complete future state
-  - [x] Remove diff syntax instructions (+/- prefixes)
-
-## 2. Migrate Existing Change
-- [x] 2.1 Convert add-init-command change to new format
-  - [x] Create `specs/cli-init/spec.md` with clean content (no diff markers)
-  - [x] Delete old `patches/` directory
-- [x] 2.2 Test that the migrated change is clear and reviewable
-
-## 3. Update Documentation Examples
-- [x] 3.1 Update docs/PRD.md
-  - [x] Fix directory structure examples (lines 376-382)
-  - [x] Update archive examples (lines 778-783)
-  - [x] Ensure consistency throughout
-- [x] 3.2 Update docs/openspec-walkthrough.md
-  - [x] Replace diff examples with future state examples
-  - [x] Ensure the walkthrough reflects new approach
-
-## 4. Create New Spec
-- [x] 4.1 Finalize openspec-conventions spec in main specs/ directory
-  - [x] Document the future state storage approach
-  - [x] Include examples of good proposals
-  - [x] Make it the source of truth for conventions
-
-## 5. Validation
-- [x] 5.1 Verify all documentation is consistent
-- [x] 5.2 Test creating a new change with the new approach
-- [x] 5.3 Ensure GitHub PR view shows diffs clearly
-
-## 6. Deployment
-- [x] 6.1 Get approval for this change
-- [x] 6.2 Implement all tasks above
-- [x] 6.3 After deployment, archive this change with completion date

package/OpenSpec-main/openspec/changes/archive/2025-08-11-add-complexity-guidelines/proposal.md

@@ -1,13 +0,0 @@
-# Add Complexity Management Guidelines
-
-## Why
-OpenSpec currently lacks guidance on managing complexity, leading to over-engineered solutions when simple ones suffice.
-
-## What Changes
-- Add "Start Simple" section to openspec/README.md with default minimalism rules
-- Add complexity triggers to help identify when complexity is justified
-- Enhance AI assistant instructions in CLAUDE.md to bias toward simplicity
-
-## Impact
-- Affected specs: None (documentation only)
-- Affected code: openspec/README.md, CLAUDE.md