diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 9b81cdec..6d8a9da3 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -2,7 +2,6 @@ name: goreleaser on: - pull_request: push: # run only against tags tags: diff --git a/README.md b/README.md index 9f26a430..194141d2 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,1031 @@ # spectr + ![Logo](https://github.com/conneroisu/spectr/blob/main/assets/logo.png) -Validatable spec driven development (inspired by openspec and kiro) + +**Validatable spec-driven development (inspired by openspec and kiro)** Tired of your specs disappearing like a ghost? `spectr archive` is your friend - it merges your change deltas into spec files so nothing gets lost. -Built with Go 👻 +Built with Go + +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) +[![Go Version](https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go)](https://go.dev/) + +--- + +## Table of Contents + +- [Overview](#overview) +- [Key Features](#key-features) +- [Installation](#installation) + - [Using Nix Flakes](#using-nix-flakes) + - [Building from Source](#building-from-source) + - [Requirements](#requirements) +- [Quick Start](#quick-start) + - [Initialize a Project](#initialize-a-project) + - [Create Your First Change](#create-your-first-change) + - [File Structure](#file-structure) +- [Command Reference](#command-reference) + - [spectr init](#spectr-init) + - [spectr list](#spectr-list) + - [spectr validate](#spectr-validate) + - [spectr archive](#spectr-archive) + - [spectr view](#spectr-view) +- [Architecture & Development](#architecture--development) + - [Architecture Overview](#architecture-overview) + - [Package Structure](#package-structure) + - [Development Setup](#development-setup) + - [Testing Strategy](#testing-strategy) +- [Contributing](#contributing) + - [Contribution Workflow](#contribution-workflow) + - [Code Style Guidelines](#code-style-guidelines) + - [Commit Conventions](#commit-conventions) + - [Testing Requirements](#testing-requirements) +- [Advanced Topics](#advanced-topics) + - [Spec-Driven Development](#spec-driven-development) + - [Delta Specifications](#delta-specifications) + - [Validation Rules](#validation-rules) + - [Archiving Workflow](#archiving-workflow) +- [Troubleshooting](#troubleshooting) + - [Common Issues](#common-issues) + - [FAQ](#faq) +- [Links & Resources](#links--resources) +- [License](#license) + +--- + +## Overview + +**Spectr** is a CLI tool for validatable spec-driven development. It helps teams manage specifications and changes through a structured three-stage workflow: + +1. **Creating Changes**: Write proposals with delta specs showing what SHOULD change +2. **Implementing Changes**: Follow the implementation checklist in `tasks.md` +3. **Archiving Changes**: Merge deltas into specs, preserving history + +Spectr enforces a clear separation between current truth (`specs/` - what IS built) and proposed changes (`changes/` - what SHOULD change), ensuring all modifications are intentional, documented, and validated. + +## Key Features + +- **Structured Workflow**: Propose, validate, implement, and archive changes systematically +- **Delta Specifications**: Track proposed changes separately from current specs +- **Strict Validation**: Enforce requirements format, scenarios, and spec consistency +- **Interactive TUI**: Beautiful terminal UI for wizards and selection flows +- **Archive Merging**: Automatically merge change deltas into spec files with `spectr archive` +- **Clean Architecture**: Well-organized codebase with clear separation of concerns +- **Comprehensive Testing**: Table-driven tests with high coverage +- **Nix Integration**: First-class Nix flake support for reproducible builds + +--- + +## Installation + +### Using Nix Flakes + +The recommended way to install Spectr is via Nix flakes: + +```bash +# Run directly without installing +nix run github:conneroisu/spectr + +# Install to your profile +nix profile install github:conneroisu/spectr + +# Add to your flake.nix inputs +{ + inputs.spectr.url = "github:conneroisu/spectr"; +} +``` + +### Building from Source + +If you prefer to build from source: + +```bash +# Clone the repository +git clone https://github.com/conneroisu/spectr.git +cd spectr + +# Build with Go +go build -o spectr + +# Or use Nix +nix build + +# Install to your PATH +mv spectr /usr/local/bin/ # or any directory in your PATH +``` + +### Requirements + +- **Go 1.25+** (if building from source) +- **Nix with flakes enabled** (optional, for Nix installation) +- **Git** (for project version control) + +--- + +## Quick Start + +### Initialize a Project + +Start by initializing Spectr in your project: + +```bash +# Initialize with interactive wizard +spectr init + +# Or specify a path +spectr init /path/to/project + +# Non-interactive mode with defaults +spectr init --non-interactive +``` + +This creates the following structure: + +``` +your-project/ +└── spectr/ + ├── project.md # Project conventions and context + ├── specs/ # Current specifications (truth) + │ └── [capability]/ # One directory per capability + │ ├── spec.md # Requirements and scenarios + │ └── design.md # Technical patterns (optional) + └── changes/ # Proposed changes + └── archive/ # Completed changes +``` + +### Create Your First Change + +Let's create a simple "Hello World" change: + +```bash +# 1. List current state +spectr list # See active changes +spectr list --specs # See existing capabilities + +# 2. Create a change directory +mkdir -p spectr/changes/add-hello-world/specs/greeting + +# 3. Write a proposal +cat > spectr/changes/add-hello-world/proposal.md << 'EOF' +# Change: Add Hello World Greeting + +## Why +We need a simple greeting capability to welcome users. + +## What Changes +- Add new `greeting` capability with hello world functionality + +## Impact +- Affected specs: greeting (new) +- Affected code: None (example) +EOF + +# 4. Create delta spec +cat > spectr/changes/add-hello-world/specs/greeting/spec.md << 'EOF' +## ADDED Requirements + +### Requirement: Hello World Greeting +The system SHALL provide a greeting function that returns "Hello, World!". + +#### Scenario: Greet successfully +- **WHEN** the greeting function is called +- **THEN** it SHALL return "Hello, World!" +EOF + +# 5. Create tasks checklist +cat > spectr/changes/add-hello-world/tasks.md << 'EOF' +## 1. Implementation +- [ ] 1.1 Create greeting.go file +- [ ] 1.2 Implement HelloWorld() function +- [ ] 1.3 Write tests for greeting +- [ ] 1.4 Update documentation +EOF + +# 6. Validate the change +spectr validate add-hello-world --strict + +# 7. After implementation, archive it +spectr archive add-hello-world +``` + +### File Structure + +Understanding the directory structure is crucial: + +``` +spectr/ +├── project.md # Project-wide conventions +├── specs/ # CURRENT TRUTH - what IS built +│ └── [capability]/ +│ ├── spec.md # Requirements with scenarios +│ └── design.md # Technical patterns (optional) +├── changes/ # PROPOSALS - what SHOULD change +│ ├── [change-id]/ +│ │ ├── proposal.md # Why, what, impact +│ │ ├── tasks.md # Implementation checklist +│ │ ├── design.md # Technical decisions (optional) +│ │ └── specs/ # Delta changes +│ │ └── [capability]/ +│ │ └── spec.md # ADDED/MODIFIED/REMOVED requirements +│ └── archive/ # Completed changes (history) +│ └── YYYY-MM-DD-[change-id]/ +``` + +**Key Concepts:** +- **specs/**: The source of truth for what's currently built +- **changes/**: Proposed modifications, kept separate until approved +- **archive/**: Historical record of all changes with timestamps +- **Delta Specs**: Use `## ADDED`, `## MODIFIED`, `## REMOVED`, or `## RENAMED Requirements` headers + +--- + +## Command Reference + +### spectr init + +Initialize Spectr in a project directory. + +**Usage:** +```bash +spectr init [PATH] [FLAGS] +``` + +**Flags:** +- `--tools `: Comma-separated list of tools to include (e.g., `git,github`) +- `--non-interactive`: Skip interactive wizard, use defaults +- `--path `: Project directory (default: current directory) + +**Examples:** +```bash +# Interactive initialization (recommended) +spectr init + +# Initialize specific directory with Git integration +spectr init /path/to/project --tools git + +# Non-interactive with defaults +spectr init --non-interactive +``` + +**Output:** +``` +✓ Created spectr/ directory +✓ Created specs/ directory +✓ Created changes/ directory +✓ Created project.md +✓ Spectr initialized successfully! +``` + +### spectr list + +List active changes or specifications. + +**Usage:** +```bash +spectr list [FLAGS] +``` + +**Flags:** +- `--specs`: List specifications instead of changes +- `--json`: Output in JSON format +- `--long`: Show detailed information +- `--no-interactive`: Disable interactive selection + +**Examples:** +```bash +# List all active changes +spectr list + +# List all specifications +spectr list --specs + +# Get detailed JSON output +spectr list --json --long + +# List specs with full details +spectr list --specs --long +``` + +**Example Output:** +``` +Active Changes: + add-two-factor-auth Add 2FA authentication support + refactor-validation Improve validation error messages + +Run 'spectr show ' for details +``` + +### spectr validate + +Validate changes or specifications against rules. + +**Usage:** +```bash +spectr validate [ITEM] [FLAGS] +``` + +**Flags:** +- `--strict`: Enable strict validation (warnings become errors) +- `--type `: Disambiguate when name conflicts exist +- `--json`: Output validation results as JSON +- `--no-interactive`: Skip interactive mode + +**Examples:** +```bash +# Validate a specific change (strict mode recommended) +spectr validate add-two-factor-auth --strict + +# Validate all changes interactively +spectr validate + +# Validate a specification +spectr validate auth --type spec + +# Get JSON validation results +spectr validate add-2fa --json +``` + +**Validation Rules:** +- Every requirement MUST have at least one scenario +- Scenarios MUST use `#### Scenario:` format (4 hashtags) +- Purpose sections MUST be at least 50 characters +- MODIFIED requirements MUST include complete updated content +- Change directories MUST contain at least one delta spec + +**Example Output:** +``` +Validating change: add-two-factor-auth + +✓ Proposal file exists +✓ Delta specs found +✓ All requirements have scenarios +✓ Scenario formatting correct +✓ All validations passed! +``` + +### spectr archive + +Archive a completed change, merging deltas into specs. + +**Usage:** +```bash +spectr archive [FLAGS] +``` + +**Flags:** +- `--skip-specs`: Archive without updating specs (for tooling-only changes) +- `--yes` / `-y`: Skip confirmation prompts (non-interactive) +- `--no-interactive`: Disable interactive mode + +**Examples:** +```bash +# Archive with interactive confirmation +spectr archive add-two-factor-auth + +# Archive without updating specs +spectr archive fix-typo --skip-specs + +# Non-interactive archive (for CI/CD) +spectr archive add-feature --yes +``` + +**What It Does:** +1. Validates the change before archiving +2. Merges delta specs into `specs/` (unless `--skip-specs`) +3. Moves `changes/[name]` → `changes/archive/YYYY-MM-DD-[name]` +4. Preserves complete history in archive + +**Example Output:** +``` +Archiving change: add-two-factor-auth + +✓ Validation passed +✓ Merging deltas into specs/auth/spec.md + - Added 2 requirements + - Modified 1 requirement +✓ Moving to archive/2025-11-18-add-two-factor-auth/ +✓ Archive complete! +``` + +### spectr view + +Display detailed information about a change or spec. + +**Usage:** +```bash +spectr view [ITEM] [FLAGS] +``` + +**Flags:** +- `--type `: Specify item type +- `--json`: Output in JSON format +- `--deltas-only`: Show only delta specifications (changes only) + +**Examples:** +```bash +# View a change interactively +spectr view + +# View specific change +spectr view add-two-factor-auth + +# View spec details +spectr view auth --type spec + +# Debug delta parsing +spectr view add-2fa --json --deltas-only +``` + +**Example Output:** +``` +Change: add-two-factor-auth +Status: Active + +Proposal: + Add two-factor authentication support via OTP + +Affected Specs: + - auth + - notifications + +Tasks: 4 total, 2 completed + +Delta Summary: + auth: + - ADDED: 2 requirements + - MODIFIED: 1 requirement +``` + +--- + +## Architecture & Development + +### Architecture Overview + +Spectr follows **Clean Architecture** principles with clear separation of concerns: + +``` +spectr/ +├── cmd/ # CLI command definitions (thin layer) +│ ├── root.go # Kong CLI framework setup +│ ├── init.go # Init command handler +│ ├── list.go # List command handler +│ ├── validate.go # Validate command handler +│ ├── archive.go # Archive command handler +│ └── view.go # View command handler +├── internal/ # Core business logic (not importable externally) +│ ├── init/ # Initialization wizard and setup +│ ├── validation/ # Spec and change validation rules +│ ├── parsers/ # Requirement and delta parsing +│ ├── archive/ # Archive workflow and spec merging +│ ├── list/ # Listing and formatting logic +│ ├── discovery/ # File discovery utilities +│ └── view/ # Display and formatting +├── main.go # Application entry point +└── testdata/ # Test fixtures and integration tests +``` + +**Design Principles:** +- **Thin CLI Layer**: Commands delegate to internal packages +- **No Circular Dependencies**: Strict dependency flow from cmd → internal +- **Single Responsibility**: Each package has one focused purpose +- **Testability**: Logic separated from I/O for easy testing + +### Package Structure + +| Package | Purpose | Key Types | +|---------|---------|-----------| +| `cmd/` | CLI command handlers using Kong framework | Command structs | +| `internal/init/` | Project initialization wizard and templates | `Wizard`, `Executor`, `Templates` | +| `internal/validation/` | Validation rules for specs and changes | `Validator`, `Rule`, `ValidationResult` | +| `internal/parsers/` | Parse requirements, scenarios, and deltas | `RequirementParser`, `DeltaParser` | +| `internal/archive/` | Archive changes and merge deltas into specs | `Archiver`, `SpecMerger` | +| `internal/list/` | List changes and specs with formatting | `Lister`, `Formatter` | +| `internal/discovery/` | Discover spec and change files | `Discoverer`, `FileInfo` | +| `internal/view/` | Display detailed information with TUI | `Dashboard`, `ProgressTracker` | + +### Development Setup + +#### Using Nix (Recommended) + +```bash +# Clone the repository +git clone https://github.com/conneroisu/spectr.git +cd spectr + +# Enter development shell (provides all tools) +nix develop + +# Available tools: +# - go_1_25: Go compiler and runtime +# - air: Live reload during development +# - gopls: Language server for IDE integration +# - golangci-lint: Comprehensive linting +# - gotestsum: Enhanced test output +# - delve: Debugger +``` + +#### Without Nix + +```bash +# Install Go 1.25+ +# Download from https://go.dev/dl/ + +# Clone repository +git clone https://github.com/conneroisu/spectr.git +cd spectr + +# Install dependencies +go mod download + +# Build +go build -o spectr + +# Run +./spectr --help +``` + +### Testing Strategy + +Spectr uses **table-driven tests** with high coverage: + +```bash +# Run all tests +go test ./... + +# Run with coverage +go test ./... -cover + +# Run with race detector +go test ./... -race + +# Run with enhanced output (if gotestsum installed) +gotestsum --format testname + +# Run specific package tests +go test ./internal/validation/... + +# Run with verbose output +go test -v ./internal/parsers/... +``` + +**Test Organization:** +- **Unit Tests**: Co-located with source files (`*_test.go`) +- **Table-Driven**: Subtests with `t.Run()` for different scenarios +- **Integration Tests**: Located in `testdata/integration/` +- **Test Fixtures**: Stored in `testdata/` directory + +**Example Test Structure:** +```go +func TestValidator_ValidateSpec(t *testing.T) { + tests := []struct { + name string + spec *Spec + wantErr bool + }{ + {"valid spec", validSpec, false}, + {"missing scenarios", specNoScenarios, true}, + {"invalid format", malformedSpec, true}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + err := validator.ValidateSpec(tt.spec) + if (err != nil) != tt.wantErr { + t.Errorf("got error = %v, wantErr = %v", err, tt.wantErr) + } + }) + } +} +``` + +--- + +## Contributing + +We welcome contributions! Please follow these guidelines to ensure smooth collaboration. + +### Contribution Workflow + +1. **Fork the Repository** + ```bash + # Click "Fork" on GitHub, then clone your fork + git clone https://github.com/YOUR-USERNAME/spectr.git + cd spectr + ``` + +2. **Create a Feature Branch** + ```bash + git checkout -b add-new-feature + ``` + +3. **Make Changes** + - Follow code style guidelines + - Write tests for new functionality + - Update documentation as needed + +4. **Run Tests and Linting** + ```bash + go test ./... + golangci-lint run + ``` + +5. **Commit Your Changes** + ```bash + git add . + git commit -m "Add new validation rule for scenarios" + ``` + +6. **Push and Create Pull Request** + ```bash + git push origin add-new-feature + # Create PR on GitHub + ``` + +### Code Style Guidelines + +- **Formatting**: Use `gofmt` (or `gofumpt` for stricter formatting) +- **Linting**: All code must pass `golangci-lint run` +- **Naming Conventions**: + - Packages: lowercase, single-word (e.g., `validation`, `parsers`) + - Interfaces: Descriptive nouns (e.g., `Validator`, `Parser`) + - Exported functions: Clear, verb-led names (e.g., `ValidateSpec`, `ParseRequirement`) +- **Comments**: All exported types and functions MUST have doc comments +- **Error Handling**: Use explicit error returns with context via `fmt.Errorf` wrapping + +**Example:** +```go +// ValidateSpec checks if a specification meets all validation rules. +// It returns an error if any rule is violated. +func ValidateSpec(spec *Spec) error { + if spec == nil { + return fmt.Errorf("spec cannot be nil") + } + // validation logic... +} +``` + +### Commit Conventions + +Use clear, descriptive commit messages: + +``` +: + + + + +``` + +**Types:** +- `feat`: New feature +- `fix`: Bug fix +- `refactor`: Code refactoring +- `test`: Adding or updating tests +- `docs`: Documentation changes +- `chore`: Maintenance tasks + +**Examples:** +``` +feat: add strict validation mode + +Implement --strict flag for validate command that treats +warnings as errors. Useful for CI/CD pipelines. + +fix: correct scenario header parsing + +Scenarios with extra whitespace were not being recognized. +Updated regex to trim whitespace before matching. + +docs: update README with archive examples +``` + +### Testing Requirements + +All contributions MUST include appropriate tests: + +- **New Features**: Add unit tests covering success and error cases +- **Bug Fixes**: Add regression test demonstrating the fix +- **Refactoring**: Ensure existing tests still pass +- **Test Coverage**: Aim for high coverage (current: >80%) + +**Running Tests Before PR:** +```bash +# Run all tests +go test ./... + +# Check coverage +go test ./... -coverprofile=coverage.out +go tool cover -func=coverage.out + +# Run linting +golangci-lint run + +# Format code +go fmt ./... +``` + +--- + +## Advanced Topics + +### Spec-Driven Development + +Spectr implements a **three-stage workflow** for managing changes: + +#### Stage 1: Creating Changes +Create a proposal when you need to: +- Add features or functionality +- Make breaking changes (API, schema) +- Change architecture or patterns +- Optimize performance (changes behavior) +- Update security patterns + +**Skip proposals for:** +- Bug fixes (restore intended behavior) +- Typos, formatting, comments +- Dependency updates (non-breaking) +- Tests for existing behavior + +#### Stage 2: Implementing Changes +1. Read `proposal.md` - Understand what's being built +2. Read `design.md` (if exists) - Review technical decisions +3. Read `tasks.md` - Get implementation checklist +4. Implement tasks sequentially +5. Mark tasks complete with `- [x]` after implementation +6. **Approval gate**: Do not implement until proposal is approved + +#### Stage 3: Archiving Changes +After deployment: +1. Run `spectr validate --strict` to ensure quality +2. Run `spectr archive ` to merge deltas into specs +3. Changes move to `archive/YYYY-MM-DD-/` +4. Specs in `specs/` are updated with merged requirements + +### Delta Specifications + +**Delta specs** describe proposed changes using operation headers: + +```markdown +## ADDED Requirements +### Requirement: New Feature +The system SHALL provide new functionality. + +#### Scenario: Success case +- **WHEN** condition occurs +- **THEN** expected result + +## MODIFIED Requirements +### Requirement: Existing Feature +[Complete modified requirement with all scenarios] + +## REMOVED Requirements +### Requirement: Deprecated Feature +**Reason**: Why removing +**Migration**: How to handle existing usage + +## RENAMED Requirements +- FROM: `### Requirement: Old Name` +- TO: `### Requirement: New Name` +``` + +**Key Rules:** +- **ADDED**: New capabilities that stand alone +- **MODIFIED**: Changes to existing requirements (include FULL updated content) +- **REMOVED**: Deprecated features (provide reason and migration path) +- **RENAMED**: Name-only changes (use with MODIFIED if behavior changes too) + +### Validation Rules + +Spectr enforces strict validation rules to maintain quality: + +| Rule | Description | Severity | +|------|-------------|----------| +| Requirement Scenarios | Every requirement MUST have ≥1 scenario | Error | +| Scenario Format | Scenarios MUST use `#### Scenario:` (4 hashtags) | Error | +| Purpose Length | Purpose sections MUST be ≥50 characters | Warning | +| MODIFIED Complete | MODIFIED requirements MUST be complete, not partial | Error | +| Delta Presence | Changes MUST have ≥1 delta spec | Error | +| Scenario Structure | Scenarios SHOULD have WHEN/THEN bullets | Warning | +| Header Matching | Operation headers use trim() - whitespace ignored | Info | + +**Strict Mode:** +```bash +# Treat warnings as errors +spectr validate --strict +``` + +**Debugging Validation:** +```bash +# See detailed validation output +spectr validate --json | jq '.errors' + +# Check delta parsing +spectr view --json --deltas-only +``` + +### Archiving Workflow + +The `spectr archive` command performs an atomic operation: + +1. **Pre-Archive Validation** + - Validates change structure + - Checks all delta specs + - Ensures requirements have scenarios + +2. **Delta Merging** + - Reads each delta spec in `changes//specs/` + - For each capability: + - **ADDED**: Appends to `specs//spec.md` + - **MODIFIED**: Replaces entire requirement block + - **REMOVED**: Removes requirement (keeps comment) + - **RENAMED**: Updates requirement header + +3. **Archive Move** + - Creates `changes/archive/YYYY-MM-DD-/` + - Moves entire change directory + - Preserves all history (proposal, tasks, design, deltas) + +4. **Post-Archive Verification** + - Validates updated specs + - Ensures merge was successful + - Reports summary + +**Example Archive:** +```bash +$ spectr archive add-two-factor-auth + +Archiving change: add-two-factor-auth +✓ Validation passed +✓ Merging deltas: + - specs/auth/spec.md: +2 ADDED, 1 MODIFIED + - specs/notifications/spec.md: +1 ADDED +✓ Moved to archive/2025-11-18-add-two-factor-auth/ +✓ Archive complete! +``` + +--- + +## Troubleshooting + +### Common Issues + +#### "Change must have at least one delta" + +**Problem**: Validation fails because no delta specs found. + +**Solution:** +1. Ensure `changes//specs/` directory exists +2. Create at least one `.md` file with delta operations +3. Verify files have `## ADDED`, `## MODIFIED`, `## REMOVED`, or `## RENAMED Requirements` headers + +```bash +# Check delta structure +ls -la changes/my-change/specs/ +cat changes/my-change/specs/*/spec.md | grep "^## " +``` + +#### "Requirement must have at least one scenario" + +**Problem**: Requirement found without scenarios. + +**Solution:** +Use the exact format for scenarios (4 hashtags, specific text): + +```markdown +### Requirement: My Feature +The system SHALL do something. + +#### Scenario: Success case +- **WHEN** user does X +- **THEN** system does Y +``` + +**Common Mistakes:** +- Using `###` (3 hashtags) instead of `####` (4 hashtags) +- Using bold `**Scenario:**` instead of header `####` +- Using bullets `- Scenario:` instead of header + +#### Validation Errors in Strict Mode + +**Problem**: `--strict` flag causes warnings to fail. + +**Solution:** +1. Review warning messages carefully +2. Fix underlying issues (often scenario structure or purpose length) +3. Use non-strict mode during development: `spectr validate ` +4. Use strict mode before archiving: `spectr validate --strict` + +#### Archive Merge Conflicts + +**Problem**: Multiple changes modify the same requirement. + +**Solution:** +1. Archive changes sequentially, not in parallel +2. Resolve conflicts manually in `specs/` after first archive +3. Validate the second change after first is archived +4. Consider combining related changes into a single proposal + +### FAQ + +#### Do I need approval before implementing changes? + +**Yes**. The approval gate is intentional. Changes should be reviewed and approved before implementation begins. This prevents wasted effort on changes that may be rejected or need significant revision. + +#### How do I handle multiple capabilities in one change? + +Create multiple delta specs, one per capability: + +``` +changes/add-2fa-notifications/ +├── proposal.md +├── tasks.md +└── specs/ + ├── auth/ + │ └── spec.md # Auth-related deltas + └── notifications/ + └── spec.md # Notification-related deltas +``` + +#### What's the difference between design.md in specs/ vs changes/? + +- **specs/[capability]/design.md**: Current technical patterns for a capability +- **changes/[name]/design.md**: Design decisions for a proposed change + +The change's `design.md` explains new architectural decisions. After archiving, relevant design details may be added to capability design docs. + +#### Can I modify specs directly without a change? + +**For minor fixes only**: typos, formatting, clarifications that don't change meaning. + +**For everything else**: Create a change proposal. This ensures: +- Changes are reviewed and approved +- History is preserved in archive +- Validation catches errors before merging + +#### How do I debug silent scenario parsing failures? + +Use JSON output to see parsed structure: + +```bash +# Check what was parsed +spectr view --json --deltas-only | jq '.deltas[].requirements[].scenarios' + +# Verify scenario count +spectr validate --json | jq '.errors[] | select(.rule == "RequirementScenarios")' +``` + +#### What happens to archive/ directory over time? + +Archives accumulate but remain organized by date: + +``` +changes/archive/ +├── 2025-11-15-add-auth/ +├── 2025-11-16-fix-validation/ +├── 2025-11-18-add-notifications/ +└── ... +``` + +Periodically, you may: +- Compress old archives +- Move ancient archives to separate storage +- Keep 6-12 months in active repository + +--- + +## Links & Resources + +- **GitHub Repository**: [github.com/conneroisu/spectr](https://github.com/conneroisu/spectr) +- **Specification Documentation**: See `spectr/specs/` for detailed capability specs + - [CLI Interface](spectr/specs/cli-interface/spec.md) + - [Validation Rules](spectr/specs/validation/spec.md) + - [Archive Workflow](spectr/specs/archive-workflow/spec.md) + - [CLI Framework](spectr/specs/cli-framework/spec.md) +- **AI Agents Documentation**: See [spectr/AGENTS.md](spectr/AGENTS.md) for AI assistant instructions +- **Project Conventions**: See [spectr/project.md](spectr/project.md) +- **Issue Tracker**: [GitHub Issues](https://github.com/conneroisu/spectr/issues) +- **Discussions**: [GitHub Discussions](https://github.com/conneroisu/spectr/discussions) + +--- + +## License + +Copyright 2025 Conner Ohnesorge + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +--- + +**Built with care by the Spectr community** diff --git a/spectr/changes/archive/2025-11-18-add-nix-packaging-spec/proposal.md b/spectr/changes/archive/2025-11-18-add-nix-packaging-spec/proposal.md new file mode 100644 index 00000000..2bdb9601 --- /dev/null +++ b/spectr/changes/archive/2025-11-18-add-nix-packaging-spec/proposal.md @@ -0,0 +1,17 @@ +# Change: Add Nix Packaging Specification + +## Why +Spectr currently lacks documented specifications for how the CLI is packaged and distributed via Nix flakes. The `packages.default` configuration exists but is not formally spec'd. This creates ambiguity about build requirements, distribution mechanisms, and packaging responsibilities. Formalizing this as a capability spec ensures the packaging workflow is explicit, testable, and maintainable. + +## What Changes +- Introduces a new "Nix Packaging" capability in `specs/nix-packaging/` +- Documents the `packages.default` buildGoModule configuration +- Specifies requirements for building the CLI binary +- Defines distribution and release workflows +- Establishes conventions for version management + +## Impact +- **Affected specs**: New capability (nix-packaging) +- **Affected code**: `flake.nix` (packages.default), main.go (version info), release workflows +- **Breaking changes**: None +- **Implementation**: No code changes required; spec-only documentation diff --git a/spectr/changes/archive/2025-11-18-add-nix-packaging-spec/specs/nix-packaging/spec.md b/spectr/changes/archive/2025-11-18-add-nix-packaging-spec/specs/nix-packaging/spec.md new file mode 100644 index 00000000..d2a97a3a --- /dev/null +++ b/spectr/changes/archive/2025-11-18-add-nix-packaging-spec/specs/nix-packaging/spec.md @@ -0,0 +1,64 @@ +# Nix Packaging Specification + +## ADDED Requirements + +### Requirement: CLI Binary Build via Nix +The system SHALL build the spectr CLI binary using Nix flakes with a `packages.default` configuration that uses `buildGoModule` to compile the Go source code into an executable binary. + +#### Scenario: Build default package +- **WHEN** user runs `nix build` in the project root +- **THEN** a spectr CLI binary is produced at `result/bin/spectr` + +#### Scenario: Build with specific Go version +- **WHEN** the flake.nix specifies Go 1.25.0 as the compiler +- **THEN** the built binary uses Go 1.25.0 runtime + +### Requirement: Vendor Hash Configuration +The system SHALL specify a `vendorHash` in `packages.default` that ensures reproducible builds by pinning Go module dependencies to a known state. + +#### Scenario: Reproducible builds +- **WHEN** `nix build` is executed multiple times with the same source +- **THEN** the output binary hash remains identical + +### Requirement: Package Metadata +The system SHALL include package metadata (pname, version, description, homepage, license, maintainers) in the flake outputs for distribution and discoverability. + +#### Scenario: Package metadata presence +- **WHEN** the flake is evaluated +- **THEN** pname="spectr", version follows semantic versioning, and license is Apache 2.0 + +#### Scenario: Homepage and license information +- **WHEN** the package is published to Nixpkgs or documentation systems +- **THEN** homepage points to the authoritative repository and license is explicitly stated + +### Requirement: Development Shell Integration +The system SHALL provide a development shell via `devShells.default` that includes Go toolchain, linting, testing, and formatting tools required for spectr development. + +#### Scenario: Enter development environment +- **WHEN** developer runs `nix develop` +- **THEN** all required build and development tools are available in PATH (Go, golangci-lint, gotestsum, etc.) + +#### Scenario: Use live reload during development +- **WHEN** developer is in the development shell +- **THEN** `air` command is available for live reloading code changes + +### Requirement: Source Code Inclusion +The system SHALL ensure the flake correctly specifies the project source (`src = self`) so that all Go source files, go.mod, and go.sum are included in the build context. + +#### Scenario: All source files included +- **WHEN** `nix build` executes +- **THEN** all .go files and module metadata are available to the Go compiler + +### Requirement: Output Structure +The system SHALL produce a standard Nix package output with the binary executable in the expected location within the derivation. + +#### Scenario: Binary in correct location +- **WHEN** build completes successfully +- **THEN** the spectr binary is located at `$out/bin/spectr` and is executable + +### Requirement: Cross-Platform Support +The system SHALL support building on multiple platforms (x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin) through proper Nix flake configuration. + +#### Scenario: Build on supported platforms +- **WHEN** the flake is evaluated on aarch64-darwin (Apple Silicon) +- **THEN** the build produces a native aarch64-darwin binary diff --git a/spectr/changes/archive/2025-11-18-add-nix-packaging-spec/tasks.md b/spectr/changes/archive/2025-11-18-add-nix-packaging-spec/tasks.md new file mode 100644 index 00000000..147ebb6d --- /dev/null +++ b/spectr/changes/archive/2025-11-18-add-nix-packaging-spec/tasks.md @@ -0,0 +1,16 @@ +# Implementation Tasks + +## 1. Specification +- [ ] 1.1 Review and approve proposal.md +- [ ] 1.2 Review spec delta in specs/nix-packaging/spec.md +- [ ] 1.3 Validate change proposal with `spectr validate add-nix-packaging-spec --strict` + +## 2. Deployment +- [ ] 2.1 Merge proposal to main branch +- [ ] 2.2 Create PR with change proposal +- [ ] 2.3 Get code review approval + +## 3. Archive +- [ ] 3.1 After approval and merge, archive the change with `spectr archive add-nix-packaging-spec` +- [ ] 3.2 Verify nix-packaging spec appears in specs/ directory +- [ ] 3.3 Confirm archive/YYYY-MM-DD-add-nix-packaging-spec/ contains the change history diff --git a/spectr/changes/comprehensive-readme/proposal.md b/spectr/changes/comprehensive-readme/proposal.md new file mode 100644 index 00000000..202b1403 --- /dev/null +++ b/spectr/changes/comprehensive-readme/proposal.md @@ -0,0 +1,22 @@ +# Change: Comprehensive README Documentation + +## Why +The current README is minimal (8 lines) and provides insufficient information for both users and developers. It lacks installation instructions, usage examples, command reference, architecture overview, and contribution guidelines. A comprehensive README is critical for project discoverability, onboarding, and community contribution. + +## What Changes +- Replace minimal 8-line README with comprehensive 400+ line documentation +- Add installation instructions (direct binary, Nix, building from source) +- Add quick-start guide with workflow examples +- Add command reference for all CLI commands (init, list, validate, archive, view) +- Add architecture overview for developers +- Add contributing guide with testing and development setup +- Add troubleshooting section +- Add links to relevant specification documents +- Maintain visual branding with logo and description + +## Impact +- Affected specs: documentation (new capability) +- Affected code: README.md only (no code changes) +- Breaking changes: None +- User-facing: Yes (primary artifact) +- Developer-facing: Yes (development guide and architecture) diff --git a/spectr/changes/comprehensive-readme/specs/documentation/spec.md b/spectr/changes/comprehensive-readme/specs/documentation/spec.md new file mode 100644 index 00000000..c0f7e763 --- /dev/null +++ b/spectr/changes/comprehensive-readme/specs/documentation/spec.md @@ -0,0 +1,81 @@ +# Documentation Specification + +## ADDED Requirements + +### Requirement: Comprehensive README with Multiple Sections +The system SHALL provide a comprehensive README.md file that serves both end users and developers, including installation instructions, usage guide, command reference, architecture overview, and contribution guidelines. + +#### Scenario: User finds installation instructions +- **WHEN** a new user visits the repository +- **THEN** they SHALL find clear instructions for installing via Nix, building from source, or using pre-built binaries + +#### Scenario: Developer understands architecture +- **WHEN** a developer reads the README +- **THEN** they SHALL find an architecture overview explaining the clean separation of concerns and package structure + +#### Scenario: Contributor knows how to contribute +- **WHEN** someone wants to contribute +- **THEN** they SHALL find guidelines for code style, testing, commit conventions, and PR process + +### Requirement: Quick Start Workflow Guide +The system SHALL provide a quick-start guide demonstrating the core workflow: creating a change, validating it, implementing it, and archiving it. + +#### Scenario: User follows workflow example +- **WHEN** a user reads the quick start section +- **THEN** they SHALL see a concrete example of `spectr init`, `spectr list`, `spectr validate`, and `spectr archive` commands in sequence + +#### Scenario: User understands file structure +- **WHEN** a user completes the quick start +- **THEN** they SHALL understand the distinction between `specs/`, `changes/`, and `archive/` directories + +### Requirement: Complete Command Reference +The system SHALL document all CLI commands with flags, examples, and expected output. + +#### Scenario: User learns init command usage +- **WHEN** a user reads the init command documentation +- **THEN** they SHALL see all available flags (`--path`, `--tools`, `--non-interactive`) with explanations and examples + +#### Scenario: User learns list command options +- **WHEN** a user reads the list command documentation +- **THEN** they SHALL understand the `--specs`, `--json`, and `--long` flags with example outputs + +#### Scenario: User learns validate command options +- **WHEN** a user reads the validate command documentation +- **THEN** they SHALL see how to use `--strict` flag and understand what validation rules are enforced + +#### Scenario: User learns archive command +- **WHEN** a user reads the archive command documentation +- **THEN** they SHALL understand the archiving workflow and `--skip-specs` flag usage + +### Requirement: Development Setup Guide +The system SHALL provide clear instructions for setting up a development environment and running tests. + +#### Scenario: Developer sets up environment with Nix +- **WHEN** a developer reads the development setup section +- **THEN** they SHALL see instructions to run `nix develop` and what tools are available + +#### Scenario: Developer runs tests +- **WHEN** a developer reads the testing section +- **THEN** they SHALL know how to run `go test ./...` and understand test organization + +### Requirement: Spec-Driven Development Explanation +The system SHALL explain the three-stage workflow and key concepts for users unfamiliar with spec-driven development. + +#### Scenario: User understands change proposals +- **WHEN** a user reads about spec-driven development +- **THEN** they SHALL understand that changes are proposals separate from current specs + +#### Scenario: User understands requirements and scenarios +- **WHEN** a user reads about key concepts +- **THEN** they SHALL know what requirements, scenarios, and delta specs mean + +### Requirement: Troubleshooting and FAQ Section +The system SHALL provide solutions for common issues and answer frequently asked questions. + +#### Scenario: User encounters validation error +- **WHEN** a user reads the troubleshooting section +- **THEN** they SHALL find explanations of common validation errors and how to fix them + +#### Scenario: User has question about workflow +- **WHEN** a user reads the FAQ +- **THEN** they SHALL find answers to questions like "Do I need approval before implementing?" or "How do I handle merge conflicts?" diff --git a/spectr/changes/comprehensive-readme/tasks.md b/spectr/changes/comprehensive-readme/tasks.md new file mode 100644 index 00000000..c81402b8 --- /dev/null +++ b/spectr/changes/comprehensive-readme/tasks.md @@ -0,0 +1,51 @@ +# Implementation Tasks + +## 1. Header & Introduction +- [x] 1.1 Add project logo and tagline +- [x] 1.2 Add project description and key features +- [x] 1.3 Add table of contents + +## 2. Installation Guide +- [x] 2.1 Add Nix flake installation instructions +- [x] 2.2 Add building from source instructions +- [x] 2.3 Add requirements section (Go 1.25+) + +## 3. Quick Start Guide +- [x] 3.1 Add basic workflow example (init → list → validate → archive) +- [x] 3.2 Add file structure explanation +- [x] 3.3 Add simple "Hello World" change example + +## 4. Command Reference +- [x] 4.1 Document `spectr init` with flags and examples +- [x] 4.2 Document `spectr list` with flags and examples +- [x] 4.3 Document `spectr validate` with flags and examples +- [x] 4.4 Document `spectr archive` with flags and examples +- [x] 4.5 Document `spectr view` with output explanation + +## 5. Architecture & Development +- [x] 5.1 Add architecture overview (clean separation, package structure) +- [x] 5.2 Document each internal package purpose +- [x] 5.3 Add development setup instructions +- [x] 5.4 Add testing strategy and how to run tests + +## 6. Contributing Guide +- [x] 6.1 Add contribution workflow (fork, branch, PR) +- [x] 6.2 Add code style guidelines +- [x] 6.3 Add commit message conventions +- [x] 6.4 Add testing requirements for contributions + +## 7. Advanced Topics +- [x] 7.1 Add spec-driven development explanation +- [x] 7.2 Add delta specifications concepts +- [x] 7.3 Add validation rules and requirements format +- [x] 7.4 Add archiving and merging explanation + +## 8. Troubleshooting & FAQ +- [x] 8.1 Add common issues and solutions +- [x] 8.2 Add FAQ section +- [x] 8.3 Add links to detailed specs + +## 9. Footer & Links +- [x] 9.1 Add license information +- [x] 9.2 Add relevant links (GitHub, docs, specs) +- [x] 9.3 Add footer credits diff --git a/spectr/specs/nix-packaging/spec.md b/spectr/specs/nix-packaging/spec.md new file mode 100644 index 00000000..3bea0b4f --- /dev/null +++ b/spectr/specs/nix-packaging/spec.md @@ -0,0 +1,69 @@ +# Nix Packaging Specification + +## Purpose + +Enable reproducible and declarative builds of the Spectr CLI using Nix flakes. This specification defines how the Spectr project integrates with the Nix package manager to provide binary distributions, reproducible development environments, and cross-platform support. By using Nix, the project ensures consistent builds across different systems, isolates dependencies, and provides a foundation for distribution through Nixpkgs or standalone installation via Nix. + +## Requirements + +### Requirement: CLI Binary Build via Nix +The system SHALL build the spectr CLI binary using Nix flakes with a `packages.default` configuration that uses `buildGoModule` to compile the Go source code into an executable binary. + +#### Scenario: Build default package +- **WHEN** user runs `nix build` in the project root +- **THEN** a spectr CLI binary is produced at `result/bin/spectr` + +#### Scenario: Build with specific Go version +- **WHEN** the flake.nix specifies Go 1.25.0 as the compiler +- **THEN** the built binary uses Go 1.25.0 runtime + +### Requirement: Vendor Hash Configuration +The system SHALL specify a `vendorHash` in `packages.default` that ensures reproducible builds by pinning Go module dependencies to a known state. + +#### Scenario: Reproducible builds +- **WHEN** `nix build` is executed multiple times with the same source +- **THEN** the output binary hash remains identical + +### Requirement: Package Metadata +The system SHALL include package metadata (pname, version, description, homepage, license, maintainers) in the flake outputs for distribution and discoverability. + +#### Scenario: Package metadata presence +- **WHEN** the flake is evaluated +- **THEN** pname="spectr", version follows semantic versioning, and license is Apache 2.0 + +#### Scenario: Homepage and license information +- **WHEN** the package is published to Nixpkgs or documentation systems +- **THEN** homepage points to the authoritative repository and license is explicitly stated + +### Requirement: Development Shell Integration +The system SHALL provide a development shell via `devShells.default` that includes Go toolchain, linting, testing, and formatting tools required for spectr development. + +#### Scenario: Enter development environment +- **WHEN** developer runs `nix develop` +- **THEN** all required build and development tools are available in PATH (Go, golangci-lint, gotestsum, etc.) + +#### Scenario: Use live reload during development +- **WHEN** developer is in the development shell +- **THEN** `air` command is available for live reloading code changes + +### Requirement: Source Code Inclusion +The system SHALL ensure the flake correctly specifies the project source (`src = self`) so that all Go source files, go.mod, and go.sum are included in the build context. + +#### Scenario: All source files included +- **WHEN** `nix build` executes +- **THEN** all .go files and module metadata are available to the Go compiler + +### Requirement: Output Structure +The system SHALL produce a standard Nix package output with the binary executable in the expected location within the derivation. + +#### Scenario: Binary in correct location +- **WHEN** build completes successfully +- **THEN** the spectr binary is located at `$out/bin/spectr` and is executable + +### Requirement: Cross-Platform Support +The system SHALL support building on multiple platforms (x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin) through proper Nix flake configuration. + +#### Scenario: Build on supported platforms +- **WHEN** the flake is evaluated on aarch64-darwin (Apple Silicon) +- **THEN** the build produces a native aarch64-darwin binary +