spec-gen-cli 1.2.6 → 1.2.8

package/examples/openspec-cli/README.md

@@ -0,0 +1,67 @@
+# Example: OpenSpec CLI Specifications
+
+This example demonstrates spec-gen output by reverse-engineering the OpenSpec CLI tool itself.
+
+## Source Project
+
+- **Project**: OpenSpec CLI
+- **Version**: 1.1.0
+- **Repository**: https://github.com/Fission-AI/OpenSpec
+- **Tech Stack**: Node.js, TypeScript, Commander.js, Zod
+
+## Generated Specifications
+
+```
+openspec/
+├── config.yaml                    # Project configuration with detected context
+└── specs/
+    ├── overview/spec.md           # System overview and capabilities
+    ├── validation/spec.md         # Schema validation and RFC 2119 rules
+    ├── parsing/spec.md            # Markdown parsing and extraction
+    ├── cli/spec.md                # Command-line interface
+    ├── artifact-graph/spec.md     # Dependency resolution
+    └── architecture/spec.md       # System architecture
+```
+
+## Domains Identified
+
+| Domain | Description | Requirements |
+|--------|-------------|--------------|
+| Overview | System capabilities and initialization | 3 |
+| Validation | Schema validation, RFC 2119 keywords, delta limits | 5 |
+| Parsing | Markdown parsing, requirement extraction, delta blocks | 5 |
+| CLI | Commands, interactive prompts, output formats | 6 |
+| Artifact Graph | Schema resolution, dependency validation, instruction loading | 6 |
+| Architecture | Layer separation, adapter pattern, design decisions | 5 |
+
+## Key Patterns Documented
+
+1. **Zod Schema-First Design** - All data structures defined as Zod schemas
+2. **Multi-Location Resolution** - Project > User > Package precedence
+3. **Adapter Pattern** - Support for multiple AI tools
+4. **Layered Architecture** - CLI → Commands → Core → Utils
+
+## Verification
+
+These specs were generated following OpenSpec conventions:
+
+- ✅ Requirements use RFC 2119 keywords (SHALL, MUST, SHOULD, MAY)
+- ✅ Scenarios use `####` heading level
+- ✅ Scenarios follow Given/When/Then format
+- ✅ Technical notes link to source files
+- ✅ config.yaml includes detected context
+
+## Usage
+
+To validate these specs (requires OpenSpec CLI):
+
+```bash
+cd openspec-cli
+openspec validate --all
+```
+
+To view a specific spec:
+
+```bash
+openspec show specs/validation
+```

package/examples/openspec-cli/openspec/config.yaml

@@ -0,0 +1,26 @@
+schema: spec-driven
+
+context: |
+  OpenSpec is an AI-native spec-driven development framework.
+
+  Tech stack: Node.js 20+, TypeScript, Commander.js, Zod, Inquirer
+  Architecture: Layered (CLI → Commands → Core → Utils)
+
+  Key patterns:
+  - Zod schemas as single source of truth
+  - Multi-location resolution (project > user > package)
+  - Adapter pattern for multi-tool AI support
+  - Interactive-first with non-TTY fallback
+
+# Auto-detected by spec-gen
+spec-gen:
+  generatedAt: "2025-01-30T12:00:00Z"
+  domains:
+    - overview
+    - validation
+    - parsing
+    - cli
+    - artifact-graph
+    - architecture
+  confidence: 0.85
+  sourceProject: "OpenSpec CLI v1.1.0"

package/examples/openspec-cli/openspec/specs/architecture/spec.md

@@ -0,0 +1,178 @@
+# Architecture Specification
+
+> Generated by spec-gen on 2025-01-30
+> Source files: src/core/*, src/commands/*, src/cli/index.ts
+
+## Purpose
+
+Documents the architectural patterns and structure of the OpenSpec CLI tool, including its layered design, dependency flow, and key design decisions.
+
+## Architecture Style
+
+OpenSpec follows a **layered architecture** with clear separation between CLI, Commands, and Core:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    CLI Layer                             │
+│              (src/cli/index.ts)                          │
+│         Entry point, Commander.js setup                  │
+├─────────────────────────────────────────────────────────┤
+│                  Commands Layer                          │
+│               (src/commands/*.ts)                        │
+│    Spec, Change, Validate, Schema, Config, Init          │
+├─────────────────────────────────────────────────────────┤
+│                    Core Layer                            │
+│                  (src/core/*.ts)                         │
+│   Validation, Parsing, Artifact Graph, Schemas           │
+├─────────────────────────────────────────────────────────┤
+│                   Utils Layer                            │
+│                  (src/utils/*.ts)                        │
+│      File I/O, Interactive prompts, Formatting           │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Requirements
+
+### Requirement: LayerSeparation
+
+The system SHALL maintain separation between CLI, Commands, Core, and Utils layers.
+
+#### Scenario: CoreIndependence
+- **GIVEN** a core module like validation
+- **WHEN** its imports are analyzed
+- **THEN** it does not import from commands or CLI layers
+
+#### Scenario: CommandsUseCore
+- **GIVEN** a command module like spec.ts
+- **WHEN** it needs validation logic
+- **THEN** it imports from core/validation, not implementing its own
+
+### Requirement: SchemaFirstDesign
+
+The system SHALL use Zod schemas as the single source of truth for data structures.
+
+#### Scenario: TypeInference
+- **GIVEN** a Zod schema for Spec
+- **WHEN** TypeScript types are needed
+- **THEN** types are inferred from schema using z.infer<>
+
+#### Scenario: RuntimeValidation
+- **GIVEN** user input that should match a schema
+- **WHEN** the data is processed
+- **THEN** Zod schema validates at runtime
+
+### Requirement: AdapterPattern
+
+The system SHALL use adapters to support multiple AI tools with a single codebase.
+
+#### Scenario: CommandGeneration
+- **GIVEN** a skill definition for "new change"
+- **WHEN** commands are generated for different tools
+- **THEN** each tool's adapter produces tool-specific format
+
+#### Scenario: AddingNewTool
+- **GIVEN** a new AI tool needs support
+- **WHEN** a developer creates an adapter
+- **THEN** all existing skills work with the new tool
+
+### Requirement: MultiLocationResolution
+
+The system SHALL support configuration and schemas from multiple locations with clear precedence.
+
+#### Scenario: ProjectOverridesUser
+- **GIVEN** config exists in both project and user locations
+- **WHEN** configuration is loaded
+- **THEN** project config takes precedence
+
+#### Scenario: PackageFallback
+- **GIVEN** a schema only exists in the package
+- **WHEN** the schema is requested
+- **THEN** the package schema is used as fallback
+
+### Requirement: InteractiveByDefault
+
+The system SHALL default to interactive mode with graceful fallback for non-TTY environments.
+
+#### Scenario: TTYPrompts
+- **GIVEN** a command missing required arguments
+- **WHEN** running in a TTY terminal
+- **THEN** interactive prompts are shown
+
+#### Scenario: NonTTYErrors
+- **GIVEN** a command missing required arguments
+- **WHEN** running in a non-TTY environment (CI/CD)
+- **THEN** clear error messages are returned instead of prompts
+
+### Requirement: ProgressiveDisclosure
+
+The system SHOULD present information progressively, showing summaries first with detail on demand.
+
+#### Scenario: ValidationSummary
+- **GIVEN** validation of 10 specs
+- **WHEN** validation completes
+- **THEN** a summary (8 passed, 2 failed) is shown first
+- **AND** details are available with --verbose flag
+
+## Layers
+
+### CLI Layer
+
+**Purpose**: Entry point and Commander.js program setup
+**Location**: `src/cli/index.ts`
+**Responsibilities**:
+- Parse command-line arguments
+- Route to appropriate command handlers
+- Handle global options (--version, --help)
+
+### Commands Layer
+
+**Purpose**: Individual command implementations
+**Location**: `src/commands/*.ts`
+**Key Files**:
+- `spec.ts` - Spec viewing and listing
+- `change.ts` - Change management
+- `validate.ts` - Validation operations
+- `schema.ts` - Schema inspection
+- `config.ts` - Configuration management
+- `init.ts` - Project initialization
+
+### Core Layer
+
+**Purpose**: Business logic independent of CLI
+**Location**: `src/core/*.ts`
+**Key Modules**:
+- `validation/` - Schema and rule validation
+- `parsers/` - Markdown parsing
+- `artifact-graph/` - Dependency resolution
+- `schemas/` - Zod schema definitions
+
+### Utils Layer
+
+**Purpose**: Shared utilities
+**Location**: `src/utils/*.ts`
+**Key Files**:
+- `file-system.ts` - File operations
+- `interactive.ts` - Prompt utilities
+- `formatting.ts` - Output formatting
+
+## Data Flow
+
+1. **User Input** → CLI parses arguments
+2. **Command Handler** → Validates options, prompts if needed
+3. **Core Logic** → Processes request using schemas and parsers
+4. **Output** → Formats and displays results
+
+## External Integrations
+
+| System | Purpose | Location |
+|--------|---------|----------|
+| PostHog | Optional telemetry | `src/telemetry/` |
+| YAML Parser | Schema/config files | Throughout |
+| Inquirer | Interactive prompts | `src/utils/interactive.ts` |
+
+## Technical Notes
+
+- **Pattern**: Layered Architecture with Dependency Injection
+- **Build**: esbuild for fast compilation
+- **Testing**: Vitest with fixtures
+- **Distribution**: npm package with bin entry

package/examples/openspec-cli/openspec/specs/artifact-graph/spec.md

@@ -0,0 +1,143 @@
+# Artifact Graph Specification
+
+> Generated by spec-gen on 2025-01-30
+> Source files: src/core/artifact-graph/types.ts, src/core/artifact-graph/schema.ts, src/core/artifact-graph/resolver.ts, src/core/artifact-graph/graph.ts
+
+## Purpose
+
+Manages artifact dependencies and workflow ordering for spec-driven development. Provides schema resolution from multiple locations, dependency graph validation, and instruction loading with context injection.
+
+## Entities
+
+### Artifact
+
+| Property | Type | Description |
+|----------|------|-------------|
+| id | string | Unique artifact identifier |
+| generates | string | Output file/directory pattern |
+| template | string | Template name for generation |
+| instruction | string | AI instruction content |
+| requires | string[] | IDs of dependent artifacts |
+
+### SchemaYaml
+
+| Property | Type | Description |
+|----------|------|-------------|
+| name | string | Schema name |
+| version | number | Schema version |
+| artifacts | Artifact[] | Ordered artifact definitions |
+
+### ResolvedSchema
+
+| Property | Type | Description |
+|----------|------|-------------|
+| schema | SchemaYaml | Parsed schema content |
+| source | 'project' \| 'user' \| 'package' | Resolution location |
+| path | string | File system path |
+
+## Requirements
+
+### Requirement: SchemaResolution
+
+The system SHALL resolve schemas from multiple locations with defined precedence: project > user > package.
+
+#### Scenario: ProjectSchemaOverride
+- **GIVEN** a schema "custom" exists in both project and package locations
+- **WHEN** schema resolution is performed
+- **THEN** the project schema is returned
+- **AND** the source is marked as "project"
+
+#### Scenario: FallbackToPackage
+- **GIVEN** a schema "spec-driven" only exists in package location
+- **WHEN** schema resolution is performed
+- **THEN** the package schema is returned
+- **AND** the source is marked as "package"
+
+#### Scenario: SchemaNotFound
+- **GIVEN** a requested schema "nonexistent" is not in any location
+- **WHEN** schema resolution is attempted
+- **THEN** an error is returned indicating schema not found
+
+### Requirement: DependencyValidation
+
+The system SHALL validate artifact dependency graphs for cycles and missing dependencies.
+
+#### Scenario: ValidDAG
+- **GIVEN** artifacts A → B → C with no cycles
+- **WHEN** graph validation is performed
+- **THEN** validation passes
+- **AND** topological order is [A, B, C]
+
+#### Scenario: CycleDetection
+- **GIVEN** artifacts A → B → C → A forming a cycle
+- **WHEN** graph validation is performed
+- **THEN** validation fails with "CYCLE_DETECTED" error
+- **AND** the cycle path is reported
+
+#### Scenario: MissingDependency
+- **GIVEN** artifact A requires artifact "missing" which doesn't exist
+- **WHEN** graph validation is performed
+- **THEN** validation fails with "MISSING_DEPENDENCY" error
+
+### Requirement: TopologicalOrdering
+
+The system SHALL provide topologically sorted artifact order for workflow execution.
+
+#### Scenario: LinearDependencies
+- **GIVEN** artifacts: proposal → specs → design → tasks
+- **WHEN** topological sort is computed
+- **THEN** order is [proposal, specs, design, tasks]
+
+#### Scenario: ParallelArtifacts
+- **GIVEN** specs and design both only require proposal
+- **WHEN** topological sort is computed
+- **THEN** proposal comes first
+- **AND** specs and design can be in either order after proposal
+
+### Requirement: InstructionLoading
+
+The system SHALL load artifact instructions with context injection and dependency content.
+
+#### Scenario: ContextInjection
+- **GIVEN** project config with context field "This is an API project"
+- **WHEN** instructions are loaded for an artifact
+- **THEN** the context is injected into the instruction template
+
+#### Scenario: DependencyContentInclusion
+- **GIVEN** artifact "design" requires artifact "specs"
+- **WHEN** instructions are loaded for "design"
+- **THEN** the content of completed "specs" artifact is included
+
+#### Scenario: RulesApplication
+- **GIVEN** config.yaml has rules for "specs" artifact
+- **WHEN** instructions are loaded for "specs"
+- **THEN** the artifact-specific rules are appended
+
+### Requirement: ArtifactStateTracking
+
+The system SHALL track which artifacts have been completed for a change.
+
+#### Scenario: CheckArtifactCompletion
+- **GIVEN** a change with "proposal.md" file present
+- **WHEN** artifact state is checked
+- **THEN** "proposal" artifact is marked as complete
+
+#### Scenario: IdentifyNextArtifact
+- **GIVEN** "proposal" is complete but "specs" is not
+- **WHEN** next artifact is requested
+- **THEN** "specs" is returned as the next artifact to work on
+
+### Requirement: SchemaVersioning
+
+The system SHOULD support schema versioning for backwards compatibility.
+
+#### Scenario: VersionMismatchWarning
+- **GIVEN** a project using schema version 1
+- **WHEN** package provides schema version 2
+- **THEN** a warning is issued about version mismatch
+
+## Technical Notes
+
+- **Implementation**: `src/core/artifact-graph/schema.ts`, `src/core/artifact-graph/resolver.ts`, `src/core/artifact-graph/graph.ts`
+- **Pattern**: Multi-location resolution with caching
+- **Dependencies**: YAML parser for schema files

package/examples/openspec-cli/openspec/specs/cli/spec.md

@@ -0,0 +1,138 @@
+# CLI Specification
+
+> Generated by spec-gen on 2025-01-30
+> Source files: src/commands/spec.ts, src/commands/change.ts, src/commands/validate.ts, src/commands/schema.ts
+
+## Purpose
+
+Provides command-line interface for managing OpenSpec projects, including spec viewing, change management, validation, and schema inspection. Supports both interactive and non-interactive modes with multiple output formats.
+
+## Entities
+
+### CommandOptions
+
+| Property | Type | Description |
+|----------|------|-------------|
+| json | boolean | Output as JSON instead of formatted text |
+| noInteractive | boolean | Disable interactive prompts |
+| verbose | boolean | Enable detailed output |
+| all | boolean | Apply to all items |
+
+### OutputFormat
+
+| Value | Description |
+|-------|-------------|
+| text | Human-readable formatted markdown |
+| json | Machine-readable JSON structure |
+
+## Requirements
+
+### Requirement: SpecViewing
+
+The system SHALL display spec content in human-readable or JSON format.
+
+#### Scenario: ViewSpecAsMarkdown
+- **GIVEN** a valid spec file at `openspec/specs/user/spec.md`
+- **WHEN** the user runs `openspec show specs/user`
+- **THEN** the spec content is displayed with formatted markdown
+
+#### Scenario: ViewSpecAsJSON
+- **GIVEN** a valid spec file
+- **WHEN** the user runs `openspec show specs/user --json`
+- **THEN** the spec is output as a JSON object
+- **AND** the JSON includes parsed requirements and scenarios
+
+### Requirement: SpecListing
+
+The system SHALL list all specs in the project with summary information.
+
+#### Scenario: ListAllSpecs
+- **GIVEN** a project with 5 spec files
+- **WHEN** the user runs `openspec list --specs`
+- **THEN** all 5 specs are listed with names and paths
+
+### Requirement: ChangeManagement
+
+The system SHALL support creating, listing, and viewing changes.
+
+#### Scenario: CreateNewChange
+- **GIVEN** an initialized OpenSpec project
+- **WHEN** the user runs `openspec change my-feature`
+- **THEN** a directory `openspec/changes/my-feature/` is created
+- **AND** template files (proposal.md, etc.) are generated
+
+#### Scenario: ListActiveChanges
+- **GIVEN** a project with 3 active changes
+- **WHEN** the user runs `openspec list --changes`
+- **THEN** all 3 changes are listed with status information
+
+### Requirement: BulkValidation
+
+The system SHALL validate multiple specs/changes concurrently with configurable parallelism.
+
+#### Scenario: ValidateAllSpecs
+- **GIVEN** a project with 10 spec files
+- **WHEN** the user runs `openspec validate --all`
+- **THEN** all specs are validated
+- **AND** a summary report shows pass/fail counts
+
+#### Scenario: ValidationWithConcurrency
+- **GIVEN** 20 spec files to validate
+- **WHEN** validation runs with default concurrency
+- **THEN** multiple files are validated in parallel
+- **AND** total validation time is reduced
+
+### Requirement: InteractivePrompts
+
+The system SHALL prompt for missing required arguments when in interactive mode.
+
+#### Scenario: MissingSpecIdPrompt
+- **GIVEN** the user runs `openspec show` without specifying a spec
+- **WHEN** interactive mode is enabled (default)
+- **THEN** a prompt lists available specs for selection
+
+#### Scenario: NonInteractiveFailure
+- **GIVEN** the user runs `openspec show --no-interactive` without a spec
+- **WHEN** the command executes
+- **THEN** an error is returned indicating missing required argument
+
+### Requirement: SchemaInspection
+
+The system SHALL allow inspection of workflow schemas including artifact dependencies.
+
+#### Scenario: ListSchemas
+- **GIVEN** schemas in project, user, and package locations
+- **WHEN** the user runs `openspec schema list`
+- **THEN** all available schemas are listed with source location
+
+#### Scenario: ShowSchemaDetails
+- **GIVEN** a schema named "spec-driven"
+- **WHEN** the user runs `openspec schema show spec-driven`
+- **THEN** the schema artifacts and dependencies are displayed
+
+#### Scenario: ValidateSchemaGraph
+- **GIVEN** a schema with artifact dependencies
+- **WHEN** the user runs `openspec schema validate spec-driven`
+- **THEN** cycle detection is performed
+- **AND** dependency graph is validated
+
+### Requirement: OutputFormatting
+
+The system SHALL support multiple output formats for different use cases.
+
+#### Scenario: ColoredTerminalOutput
+- **GIVEN** a TTY terminal environment
+- **WHEN** commands produce output
+- **THEN** colors and formatting enhance readability
+
+#### Scenario: PlainTextForPipes
+- **GIVEN** output is piped to another command
+- **WHEN** commands produce output
+- **THEN** ANSI codes are stripped
+- **AND** plain text is output
+
+## Technical Notes
+
+- **Implementation**: `src/commands/spec.ts`, `src/commands/change.ts`, `src/commands/validate.ts`
+- **Framework**: Commander.js for command parsing, Inquirer for prompts
+- **Dependencies**: validation, parsing

package/examples/openspec-cli/openspec/specs/overview/spec.md

@@ -0,0 +1,60 @@
+# System Overview
+
+> Generated by spec-gen on 2025-01-30
+> Source files: package.json, src/cli/index.ts, src/core/init.ts
+
+## Purpose
+
+OpenSpec is an AI-native spec-driven development framework that helps teams define, validate, and evolve software specifications. It provides CLI tools for managing specs and changes, multi-tool AI integration, and artifact-guided workflows.
+
+## Domains
+
+| Domain | Description | Spec |
+|--------|-------------|------|
+| validation | Schema validation and rule enforcement | [spec.md](../validation/spec.md) |
+| parsing | Markdown parsing and content extraction | [spec.md](../parsing/spec.md) |
+| cli | Command-line interface and user interaction | [spec.md](../cli/spec.md) |
+| artifact-graph | Dependency resolution and workflow ordering | [spec.md](../artifact-graph/spec.md) |
+
+## Requirements
+
+### Requirement: ProjectInitialization
+
+The system SHALL initialize OpenSpec projects with proper directory structure and configuration files.
+
+#### Scenario: NewProjectSetup
+- **GIVEN** a directory without OpenSpec configuration
+- **WHEN** the user runs `openspec init`
+- **THEN** the system creates `openspec/` directory structure
+- **AND** generates `openspec/config.yaml` with default settings
+
+### Requirement: MultiToolSupport
+
+The system SHALL support multiple AI tools through an adapter-based command generation system.
+
+#### Scenario: ClaudeCodeSkillGeneration
+- **GIVEN** a user selects Claude Code during initialization
+- **WHEN** the init process completes
+- **THEN** skill files are generated in `.claude/skills/`
+- **AND** the skills follow Claude Code's expected format
+
+#### Scenario: CursorCommandGeneration
+- **GIVEN** a user selects Cursor during initialization
+- **WHEN** the init process completes
+- **THEN** command files are generated in `.cursor/commands/`
+
+### Requirement: SpecDrivenWorkflow
+
+The system SHALL enforce a spec-driven development workflow where specifications precede implementation.
+
+#### Scenario: ChangeProposalFlow
+- **GIVEN** a developer wants to make a change
+- **WHEN** they run `openspec change my-feature`
+- **THEN** a change directory is created with proposal template
+- **AND** the workflow guides them through spec → design → tasks
+
+## Technical Notes
+
+- **Implementation**: `src/cli/index.ts`, `src/core/init.ts`
+- **Framework**: Commander.js for CLI, Inquirer for prompts
+- **Dependencies**: validation, parsing, artifact-graph