spec-driven-development 0.0.0-canary-20251223010757

package/AGENT_MODES.md

@@ -0,0 +1,247 @@
+# AI Agent Modes
+
+The contracts-cli supports multiple AI agent modes for code generation and validation. Each mode offers different capabilities and trade-offs.
+
+## Available Agent Modes
+
+### 1. Simple Mode (Default)
+- **Mode**: `simple`
+- **Description**: Direct LLM API calls for code generation
+- **Best For**: Quick prototyping, basic implementations
+- **Requirements**: API key for your chosen provider (Claude, OpenAI, Ollama)
+- **Speed**: Fast
+- **Quality**: Good baseline quality
+
+**Example:**
+```bash
+contractspec build spec.contracts.ts --agent-mode simple
+```
+
+### 2. Cursor Agent Mode
+- **Mode**: `cursor`
+- **Description**: Leverages Windsurf/Cursor's agentic capabilities
+- **Best For**: Complex implementations, iterative development
+- **Requirements**: Running in Windsurf/Cursor environment
+- **Speed**: Moderate
+- **Quality**: High quality with context awareness
+
+**Example:**
+```bash
+contractspec build spec.contracts.ts --agent-mode cursor
+```
+
+**Note**: This mode requires Windsurf/Cursor CLI access. If not available, falls back to simple mode.
+
+### 3. Claude Code Mode
+- **Mode**: `claude-code`
+- **Description**: Uses Anthropic's Claude with extended thinking for code generation
+- **Best For**: Production-quality code, complex logic, thorough validation
+- **Requirements**: `ANTHROPIC_API_KEY` environment variable
+- **Speed**: Moderate to slow
+- **Quality**: Very high quality, excellent for validation
+
+**Features:**
+- Extended context understanding
+- Detailed code review capabilities
+- Comprehensive validation reports
+- Best for critical implementations
+
+**Example:**
+```bash
+export ANTHROPIC_API_KEY=your_key
+contractspec build spec.contracts.ts --agent-mode claude-code
+```
+
+### 4. OpenAI Codex Mode
+- **Mode**: `openai-codex`
+- **Description**: Uses OpenAI's GPT-4o and o1 models for code generation
+- **Best For**: Complex algorithms, optimization tasks
+- **Requirements**: `OPENAI_API_KEY` environment variable
+- **Speed**: Fast (GPT-4o) to slow (o1 reasoning)
+- **Quality**: High quality, excellent for algorithmic problems
+
+**Features:**
+- Automatically selects o1 for complex tasks
+- Uses GPT-4o for standard generation
+- Strong at optimization and algorithms
+
+**Example:**
+```bash
+export OPENAI_API_KEY=your_key
+contractspec build spec.contracts.ts --agent-mode openai-codex
+```
+
+## Configuring Agent Modes
+
+### Via Configuration File
+
+Add to `.contractsrc.json`:
+
+```json
+{
+  "aiProvider": "claude",
+  "agentMode": "claude-code",
+  "aiModel": "claude-3-7-sonnet-20250219"
+}
+```
+
+### Via Environment Variables
+
+```bash
+export CONTRACTSPEC_AGENT_MODE=claude-code
+export CONTRACTSPEC_AI_PROVIDER=claude
+export ANTHROPIC_API_KEY=your_key
+```
+
+### Via CLI Options
+
+```bash
+contractspec build spec.ts --agent-mode claude-code --provider claude
+```
+
+## Agent Mode Comparison
+
+| Feature | Simple | Cursor | Claude Code | OpenAI Codex |
+|---------|--------|--------|-------------|--------------|
+| Speed | ⚡⚡⚡ | ⚡⚡ | ⚡⚡ | ⚡⚡⚡ |
+| Quality | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
+| Validation | Basic | Good | Excellent | Good |
+| Setup | Easy | Moderate | Easy | Easy |
+| Cost | Low | N/A | Moderate | Low-Moderate |
+
+## Fallback Behavior
+
+The CLI automatically falls back to simpler modes if the primary mode fails:
+
+1. **cursor** → **claude-code** → **openai-codex** → **simple**
+2. **claude-code** → **openai-codex** → **simple**
+3. **openai-codex** → **simple**
+4. **simple** → Basic templates (no AI)
+
+## Usage Examples
+
+### Build with Agent Mode
+
+```bash
+# Use Claude Code for high-quality generation
+contractspec build user.contracts.ts --agent-mode claude-code
+
+# Use OpenAI for algorithmic code
+contractspec build optimizer.contracts.ts --agent-mode openai-codex
+
+# Disable AI entirely
+contractspec build simple.contracts.ts --no-agent
+```
+
+### Validate with Agent Mode
+
+```bash
+# Validate implementation with AI
+contractspec validate user.contracts.ts --check-implementation --agent-mode claude-code
+
+# Interactive validation
+contractspec validate user.contracts.ts -i --agent-mode claude-code
+
+# Specify implementation path
+contractspec validate user.contracts.ts \
+  --check-implementation \
+  --implementation-path ./handlers/user.handler.ts \
+  --agent-mode claude-code
+```
+
+## Best Practices
+
+### For Development
+- Use **simple** mode for rapid iteration
+- Use **cursor** mode if working in Windsurf/Cursor
+
+### For Production
+- Use **claude-code** for critical implementations
+- Always validate with `--check-implementation`
+- Review AI-generated code before committing
+
+### For Complex Logic
+- Use **openai-codex** for algorithmic problems
+- Use **claude-code** for comprehensive validation
+
+### For CI/CD
+- Use **simple** mode for speed
+- Configure via environment variables
+- Set up validation in pre-commit hooks
+
+## Troubleshooting
+
+### Agent Mode Not Working
+
+Check:
+1. API keys are set correctly
+2. Network connectivity to AI providers
+3. Provider quotas and rate limits
+
+### Fallback to Simple Mode
+
+This happens when:
+- API key is missing
+- Provider is unavailable
+- Agent cannot handle the task
+
+The CLI will show warnings explaining why.
+
+### Poor Quality Output
+
+Try:
+1. Using a more powerful agent mode
+2. Adding more context to your spec
+3. Reviewing and refining the spec structure
+
+## Environment Variables Reference
+
+```bash
+# Provider selection
+CONTRACTSPEC_AI_PROVIDER=claude|openai|ollama|custom
+
+# Agent mode
+CONTRACTSPEC_AGENT_MODE=simple|cursor|claude-code|openai-codex
+
+# Model selection
+CONTRACTSPEC_AI_MODEL=claude-3-7-sonnet-20250219
+
+# API Keys
+ANTHROPIC_API_KEY=your_anthropic_key
+OPENAI_API_KEY=your_openai_key
+
+# Custom endpoints
+CONTRACTSPEC_LLM_ENDPOINT=https://your-custom-endpoint
+CONTRACTSPEC_LLM_API_KEY=your_custom_key
+```
+
+## Advanced Configuration
+
+### Custom Agent Priorities
+
+You can configure fallback priorities in `.contractsrc.json`:
+
+```json
+{
+  "agentMode": "claude-code",
+  "aiProvider": "claude",
+  "aiModel": "claude-3-7-sonnet-20250219",
+  "outputDir": "./src",
+  "defaultOwners": ["@team"],
+  "defaultTags": ["auto-generated"]
+}
+```
+
+### Multi-Model Strategy
+
+Use different models for different tasks:
+
+```bash
+# Use Claude for generation
+contractspec build spec.ts --agent-mode claude-code
+
+# Use OpenAI for validation
+contractspec validate spec.ts \
+  --check-implementation \
+  --agent-mode openai-codex
+```

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# spec-driven-development
+
+## 0.0.0-canary-20251223010757
+
+### Minor Changes
+
+- 66a5dfd: initial release
+
+### Patch Changes
+
+- Updated dependencies [66a5dfd]
+  - @lssm/app.cli-contractspec@0.0.0-canary-20251223010757

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QUICK_REFERENCE.md

@@ -0,0 +1,209 @@
+# Quick Reference Guide
+
+## New Commands Overview
+
+```bash
+# Discovery & Management
+contractspec list                           # List all contracts
+contractspec list --type operation         # Filter contracts
+contractspec list --pattern 'src/**/*.ts'  # Custom discovery pattern
+contractspec list --deep                   # Load spec modules (richer metadata)
+contractspec deps                          # Analyze dependencies
+contractspec deps --circular               # Find circular deps
+contractspec deps --format dot > deps.dot  # GraphViz dot output
+
+# Development Workflow
+contractspec watch --build                # Auto-build on changes
+contractspec watch --validate             # Auto-validate on changes
+contractspec watch --on-start both         # Run on startup too
+contractspec watch --continue-on-error     # Keep watching even on failures
+
+# Maintenance & Comparison
+contractspec clean                        # Clean generated files
+contractspec clean --dry-run              # Preview cleanup
+contractspec diff spec1.ts spec2.ts       # Compare specs
+contractspec diff spec.ts spec.ts --baseline main  # Compare with git baseline
+contractspec sync                         # Build all discovered specs
+contractspec sync --buckets api,ui        # Repeat builds into ./generated/<bucket>/
+
+# Validation & Testing
+contractspec validate '**/*.ts'           # Validate all specs
+contractspec validate spec.ts --check-implementation
+```
+
+## Agent Modes at a Glance
+
+```bash
+# Simple (default) - Fast, basic quality
+contractspec build spec.ts
+
+# Claude Code - Best quality, production-ready
+contractspec build spec.ts --agent-mode claude-code
+
+# OpenAI Codex - Best for algorithms
+contractspec build spec.ts --agent-mode openai-codex
+
+# Cursor - IDE-integrated (Windsurf/Cursor)
+contractspec build spec.ts --agent-mode cursor
+
+# No AI - Templates only
+contractspec build spec.ts --no-agent
+```
+
+## Build Examples
+
+```bash
+# Basic build
+contractspec build user.contracts.ts
+# (Falls back to templates automatically if the requested agent is unavailable)
+
+# Production build with tests
+contractspec build user.contracts.ts --agent-mode claude-code
+
+# Fast build without tests
+contractspec build user.contracts.ts --no-tests
+
+# Custom output directory
+contractspec build user.contracts.ts -o ./src/handlers
+```
+
+## Validation Examples
+
+```bash
+# Validate spec only
+contractspec validate user.contracts.ts
+
+# Validate implementation with AI
+contractspec validate user.contracts.ts --check-implementation
+
+# Interactive validation
+contractspec validate user.contracts.ts -i
+
+# Default prompt (no flags): choose spec-only vs spec+implementation
+contractspec validate user.contracts.ts
+
+# Validate with specific implementation
+contractspec validate user.contracts.ts \
+  --check-implementation \
+  --implementation-path ./handlers/user.handler.ts \
+  --agent-mode claude-code
+```
+
+## Configuration
+
+### Minimal .contractsrc.json
+```json
+{
+  "aiProvider": "claude",
+  "agentMode": "claude-code",
+  "outputDir": "./src"
+}
+```
+
+### Environment Variables
+```bash
+# Required for Claude
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Required for OpenAI
+export OPENAI_API_KEY=sk-...
+
+# Agent mode (optional)
+export CONTRACTSPEC_AGENT_MODE=claude-code
+```
+
+## Common Workflows
+
+### Development Flow
+```bash
+# 1. Create spec
+contractspec create --type operation --ai
+
+# 2. Generate implementation
+contractspec build spec.contracts.ts --agent-mode claude-code
+
+# 3. Validate
+contractspec validate spec.contracts.ts --check-implementation
+```
+
+### CI/CD Flow
+```bash
+# Fast validation in CI
+contractspec validate '**/*.contracts.ts' --agent-mode simple
+
+# Validate implementations (skip prompt)
+contractspec validate '**/*.contracts.ts' --check-implementation
+```
+
+### Multi-Provider Strategy
+```bash
+# Draft with local model (free)
+contractspec create --ai --provider ollama
+
+# Build with Claude (quality)
+contractspec build spec.ts --agent-mode claude-code
+
+# Validate with OpenAI (cost-effective)
+contractspec validate spec.ts --check-implementation --agent-mode openai-codex
+```
+
+## Troubleshooting
+
+### AI Not Working
+```bash
+# Check API key
+echo $ANTHROPIC_API_KEY
+
+# Use simple mode as fallback
+contractspec build spec.ts --agent-mode simple
+
+# Disable AI completely
+contractspec build spec.ts --no-agent
+```
+
+### Wrong Implementation Path
+```bash
+# Specify path explicitly
+contractspec validate spec.contracts.ts \
+  --check-implementation \
+  --implementation-path ./custom/path/handler.ts
+```
+
+### Slow Generation
+```bash
+# Use faster agent mode
+contractspec build spec.ts --agent-mode simple
+
+# Skip tests
+contractspec build spec.ts --no-tests
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use `claude-code` for production implementations
+- Validate with `--check-implementation` before committing
+- Set agent mode in `.contractsrc.json` for consistency
+- Use environment variables for API keys
+
+❌ **DON'T:**
+- Commit AI-generated code without review
+- Use expensive agents in CI/CD unnecessarily
+- Store API keys in `.contractsrc.json`
+- Skip validation for critical code
+
+## Performance Tips
+
+| Task | Recommended Agent | Speed | Quality |
+|------|------------------|-------|---------|
+| Prototyping | simple | ⚡⚡⚡ | ⭐⭐⭐ |
+| Production | claude-code | ⚡⚡ | ⭐⭐⭐⭐⭐ |
+| Algorithms | openai-codex | ⚡⚡⚡ | ⭐⭐⭐⭐ |
+| CI/CD | simple | ⚡⚡⚡ | ⭐⭐⭐ |
+| Validation | claude-code | ⚡⚡ | ⭐⭐⭐⭐⭐ |
+
+## More Information
+
+- Full documentation: [README.md](./README.md)
+- Agent modes guide: [AGENT_MODES.md](./AGENT_MODES.md)
+- Quick start: [QUICK_START.md](./QUICK_START.md)

package/QUICK_START.md

@@ -0,0 +1,174 @@
+# Quick Start Guide
+
+Get started with contracts-cli in 5 minutes.
+
+## Installation
+
+```bash
+cd packages/lssm/tools/contracts-cli
+pnpm install
+pnpm build
+```
+
+## First Spec
+
+### 1. Create a spec interactively
+
+```bash
+pnpm exec contractspec create
+```
+
+Follow the prompts:
+- Choose "Operation (Command/Query)"
+- Select "Command"
+- Name: `user.signup`
+- Fill in description, goal, context
+- Set auth to `anonymous`
+- Add owners: `@team`
+
+This creates: `src/interactions/commands/user-signup.contracts.ts`
+
+### 2. Or use AI assistance
+
+```bash
+export ANTHROPIC_API_KEY=your-key-here
+pnpm exec contractspec create --ai
+```
+
+Describe what you want:
+> "Create a command for user signup that takes an email and sends a magic link"
+
+Review and accept the AI-generated spec!
+
+### 3. Generate handler
+
+```bash
+pnpm exec contractspec build src/interactions/commands/user-signup.contracts.ts
+```
+
+This generates:
+- `src/handlers/user-signup.handler.ts` - Implementation stub
+- `src/handlers/user-signup.handler.test.ts` - Tests
+
+### 4. Validate
+
+```bash
+pnpm exec contractspec validate src/interactions/commands/user-signup.contracts.ts
+# You'll be prompted to validate the spec only or the implementation as well.
+```
+
+## Using Local Models (Free!)
+
+### Install Ollama
+
+```bash
+# macOS
+brew install ollama
+
+# Start Ollama
+ollama serve
+
+# Pull a model
+ollama pull codellama
+```
+
+### Generate with Ollama
+
+```bash
+pnpm exec contractspec create --ai --provider ollama --model codellama
+```
+
+No API keys needed! Everything runs locally.
+
+## Configuration
+
+Create `.contractsrc.json` in your project root:
+
+```json
+{
+  "aiProvider": "claude",
+  "outputDir": "./src",
+  "defaultOwners": ["@my-team"],
+  "conventions": {
+    "operations": "interactions/commands|queries",
+    "events": "events"
+  }
+}
+```
+
+Now commands use these defaults:
+
+```bash
+# Uses Claude from config
+pnpm exec contractspec create --ai
+
+# Override with Ollama
+pnpm exec contractspec create --ai --provider ollama
+```
+
+## Next Steps
+
+1. **Complete the TODO items** in generated files
+2. **Implement handler logic** with real business rules
+3. **Run tests**: `pnpm test`
+4. **Validate**: `pnpm exec contractspec validate src/**/*.contracts.ts`
+5. **Register in registry** and mount REST/GraphQL adapters
+
+## Common Workflows
+
+### Create Event
+
+```bash
+pnpm exec contractspec create --type event
+```
+
+### Build Presentation Component
+
+```bash
+pnpm exec contractspec create --type presentation
+pnpm exec contractspec build src/presentations/user-profile.presentation.ts
+```
+
+### Multi-Spec Workflow
+
+```bash
+# Create operation spec
+pnpm exec contractspec create --type operation --ai
+
+# Create related event spec
+pnpm exec contractspec create --type event --ai
+
+# Generate all implementations
+pnpm exec contractspec build src/contracts/**/*.ts
+```
+
+## Tips
+
+- Use `--ai` for faster spec creation
+- Use Ollama for free local generation
+- Use Claude/GPT-4 for production-quality code
+- Always validate before committing
+- Keep specs close to implementations
+
+## Troubleshooting
+
+**No AI provider?**
+```bash
+# Use interactive wizard instead
+pnpm exec contractspec create
+```
+
+**Can't find contractspec?**
+```bash
+# Use pnpm exec
+pnpm exec contractspec --help
+```
+
+**Import errors?**
+```bash
+# Install dependencies
+pnpm add @lssm/lib.contracts @lssm/lib.schema
+```
+
+Happy contract authoring! 🎉
+

package/README.md

@@ -0,0 +1,628 @@
+ContractSpec
+
+**Stabilize your AI-generated code** — Define contracts once, generate consistent code across API, DB, UI, and events. Safe regeneration. No lock-in.
+
+CLI tool for creating, building, and validating contract specifications.
+
+## Installation
+
+```bash
+bun add -D contractspec
+```
+
+## Quick Start
+
+```bash
+# Create a new contract spec interactively
+contractspec create
+
+# Create with AI assistance
+contractspec create --ai
+
+# Build implementation from spec
+contractspec build src/contracts/mySpec.ts
+
+# Validate a spec
+contractspec validate src/contracts/mySpec.ts
+```
+
+## Commands
+
+### `contractspec list`
+
+List all contract specifications in the project with filtering options.
+
+**Options:**
+- `--pattern <pattern>` - File pattern to search (glob)
+- `--deep` - Load spec modules to extract richer metadata (executes spec modules)
+- `--type <type>` - Filter by spec type (operation, event, presentation, etc.)
+- `--owner <owner>` - Filter by owner
+- `--tag <tag>` - Filter by tag
+- `--stability <level>` - Filter by stability (experimental, beta, stable, deprecated)
+- `--json` - Output as JSON for scripting
+
+**Examples:**
+
+```bash
+# List all specs
+contractspec list
+
+# Filter by type and stability
+contractspec list --type operation --stability stable
+
+# Find specs by owner
+contractspec list --owner @team-platform
+
+# JSON output for scripting
+contractspec list --json
+```
+
+### `contractspec watch`
+
+Watch contract specifications and auto-regenerate on changes.
+
+**Options:**
+- `--pattern <pattern>` - File pattern to watch (default: `**/*.contracts.ts`)
+- `--build` - Auto-run build command on changes
+- `--validate` - Auto-run validate command on changes
+- `--on-start <mode>` - Run action on startup: none|validate|build|both (default: none)
+- `--continue-on-error` - Do not exit on build/validate errors
+- `--debounce <ms>` - Debounce delay in milliseconds (default: 500)
+
+**Examples:**
+
+```bash
+# Watch for changes and auto-build
+contractspec watch --build
+
+# Watch and auto-validate
+contractspec watch --validate
+
+# Custom pattern and debounce
+contractspec watch --pattern 'src/**/*.ts' --debounce 1000
+```
+
+### `contractspec sync`
+
+Sync contracts by building all discovered specs.
+
+**Options:**
+- `--pattern <pattern>` - File pattern to search (glob)
+- `--buckets <buckets>` - Optional output buckets (comma-separated). Builds repeat into `./generated/<bucket>/`
+- `--surfaces <surfaces>` - (deprecated) Alias for `--buckets`
+- `--validate` - Validate each spec before building (spec-only)
+- `--dry-run` - Show what would be synced without making changes
+
+**Examples:**
+
+```bash
+# Sync all surfaces
+contractspec sync
+
+# Sync specific surfaces
+contractspec sync --surfaces api,ui
+
+# Preview changes
+contractspec sync --dry-run
+```
+
+### `contractspec clean`
+
+Clean generated files and build artifacts.
+
+**Options:**
+- `--dry-run` - Show what would be deleted without deleting
+- `--generated-only` - Only clean generated directories (generated/, dist/, .turbo/, outputDir artifacts)
+- `--older-than <days>` - Only clean files older than specified days
+- `--force` - Skip confirmation prompts
+- `--git-clean` - Use `git clean -fdx` for comprehensive cleanup (requires confirmation or `--force`)
+
+**Examples:**
+
+```bash
+# Clean all generated files
+contractspec clean
+
+# Preview cleanup
+contractspec clean --dry-run
+
+# Clean only old files
+contractspec clean --older-than 30
+
+# Use git clean
+contractspec clean --git-clean
+```
+
+### `contractspec deps`
+
+Analyze contract dependencies and relationships.
+
+**Options:**
+- `--pattern <pattern>` - File pattern to search (glob)
+- `--entry <name>` - Focus on a specific contract name
+- `--format <format>` - text|json|dot (default: text)
+- `--graph` - (deprecated) Same as `--format dot`
+- `--circular` - Find circular dependencies
+- `--missing` - Find missing dependencies
+- `--json` - (deprecated) Same as `--format json`
+
+**Examples:**
+
+```bash
+# Show dependency overview
+contractspec deps
+
+# Analyze specific contract
+contractspec deps --entry user.signup
+
+# Find circular dependencies
+contractspec deps --circular
+
+# Generate graphviz graph
+contractspec deps --format dot > deps.dot
+```
+
+### `contractspec diff`
+
+Compare contract specifications and show differences.
+
+**Arguments:**
+- `<spec1> <spec2>` - Two spec files to compare
+
+**Options:**
+- `--breaking` - Only show breaking changes
+- `--semantic` - Show semantic differences (not just text)
+- `--json` - Output as JSON for scripting
+- `--baseline <ref>` - Compare with git reference (branch/commit)
+
+**Examples:**
+
+```bash
+# Compare two specs
+contractspec diff spec1.ts spec2.ts
+
+# Compare with git branch
+contractspec diff spec.ts spec.ts --baseline main
+
+# Show only breaking changes
+contractspec diff spec1.ts spec2.ts --breaking
+
+# Semantic comparison
+contractspec diff spec1.ts spec2.ts --semantic
+```
+
+### `contractspec create`
+
+Interactive wizard to create contract specifications.
+
+**Options:**
+- `--type <type>` - Spec type: operation, event, presentation, form, feature
+- `--ai` - Use AI to generate spec from description
+- `--provider <provider>` - AI provider: claude, openai, ollama, custom
+- `--model <model>` - AI model to use
+
+**Examples:**
+
+```bash
+# Interactive wizard
+contractspec create
+
+# Create operation spec with AI
+contractspec create --type operation --ai
+
+# Use local Ollama model
+contractspec create --ai --provider ollama --model codellama
+```
+
+### `contractspec build`
+
+Generate implementation code from contract specs using AI agents with automatic fallbacks.
+
+**Options:**
+- `--output-dir <dir>` - Output directory (default: ./generated)
+- `--provider <provider>` - AI provider: claude, openai, ollama, custom
+- `--model <model>` - AI model to use
+- `--agent-mode <mode>` - Agent mode: simple, cursor, claude-code, openai-codex
+- `--no-tests` - Skip test generation
+- `--no-agent` - Disable AI (use basic templates)
+
+> ℹ️ The build command automatically orchestrates between the selected agent and lightweight templates. If an agent becomes unavailable (missing API key, Cursor not running, etc.) the CLI falls back to deterministic templates so the build never blocks.
+
+**Examples:**
+
+```bash
+# Generate handler from operation spec (default: simple agent)
+contractspec build src/contracts/signup.contracts.ts
+
+# Use Claude Code agent for high-quality production code
+contractspec build src/contracts/signup.contracts.ts --agent-mode claude-code
+
+# Use OpenAI Codex for algorithmic implementations
+contractspec build src/contracts/optimizer.contracts.ts --agent-mode openai-codex
+
+# Generate without AI (basic templates only)
+contractspec build src/contracts/simple.contracts.ts --no-agent
+```
+
+### `contractspec validate`
+
+Validate contract specifications and optionally verify implementations against specs using AI.
+
+**Options:**
+- `--check-implementation` - Validate implementation against spec using AI
+- `--implementation-path <path>` - Path to implementation (auto-detected if not specified)
+- `--agent-mode <mode>` - Agent mode for validation: simple, claude-code, openai-codex
+- `--check-handlers` - Verify handler implementations exist
+- `--check-tests` - Verify test coverage
+- `-i, --interactive` - Interactive mode - prompt for what to validate
+
+> ℹ️ When no validation scope is provided, the CLI prompts you to choose between spec-only validation or full spec + implementation validation. In non-interactive environments it defaults to spec-only. Use `--check-implementation` to skip the prompt.
+
+**Examples:**
+
+```bash
+# Validate spec structure only
+contractspec validate src/contracts/signup.contracts.ts
+
+# Validate implementation against spec with AI
+contractspec validate src/contracts/signup.contracts.ts --check-implementation
+
+# Interactive validation with Claude Code agent
+contractspec validate src/contracts/signup.contracts.ts -i --agent-mode claude-code
+
+# Validate specific implementation file
+contractspec validate src/contracts/signup.contracts.ts \
+  --check-implementation \
+  --implementation-path src/handlers/signup.handler.ts \
+  --agent-mode claude-code
+```
+
+### `contractspec ci`
+
+Run all validation checks for CI/CD pipelines with machine-readable output formats.
+
+**Options:**
+- `--pattern <glob>` - Glob pattern for spec discovery
+- `--format <format>` - Output format: text, json, sarif (default: text)
+- `--output <file>` - Write results to file
+- `--fail-on-warnings` - Exit with code 2 on warnings
+- `--skip <checks>` - Skip specific checks (comma-separated)
+- `--checks <checks>` - Only run specific checks (comma-separated)
+- `--check-handlers` - Include handler implementation checks
+- `--check-tests` - Include test coverage checks
+- `--verbose` - Verbose output
+
+**Available Checks:**
+- `structure` - Spec structure validation (meta, io, policy)
+- `integrity` - Contract integrity (orphaned specs, broken refs)
+- `deps` - Dependency analysis (circular deps, missing refs)
+- `doctor` - Installation health (skips AI in CI)
+- `handlers` - Handler implementation existence
+- `tests` - Test file existence
+
+**Exit Codes:**
+- `0` - All checks passed
+- `1` - Errors found
+- `2` - Warnings found (with `--fail-on-warnings`)
+
+**Examples:**
+
+```bash
+# Run all CI checks
+contractspec ci
+
+# Output as JSON for parsing
+contractspec ci --format json
+
+# Output SARIF for GitHub Code Scanning
+contractspec ci --format sarif --output results.sarif
+
+# Skip doctor checks
+contractspec ci --skip doctor
+
+# Run only structure and integrity checks
+contractspec ci --checks structure,integrity
+
+# Fail on warnings
+contractspec ci --fail-on-warnings
+```
+
+For comprehensive CI/CD integration guides (GitHub Actions, GitLab CI, Jenkins, AWS CodeBuild, etc.), see [docs/ci-cd.md](./docs/ci-cd.md).
+
+## Configuration
+
+Create a `.contractsrc.json` file in your project root:
+
+```json
+{
+  "aiProvider": "claude",
+  "aiModel": "claude-3-7-sonnet-20250219",
+  "agentMode": "claude-code",
+  "outputDir": "./src",
+  "conventions": {
+    "operations": "interactions/commands|queries",
+    "events": "events",
+    "presentations": "presentations",
+    "forms": "forms"
+  },
+  "defaultOwners": ["@team"],
+  "defaultTags": ["auto-generated"]
+}
+```
+
+### Agent Modes
+
+The CLI supports multiple AI agent modes for different use cases:
+
+- **simple** (default) - Direct LLM API calls, fast and straightforward
+- **cursor** - Leverages Windsurf/Cursor agentic capabilities (requires Cursor environment)
+- **claude-code** - Uses Claude with extended thinking, best for production code and validation
+- **openai-codex** - Uses GPT-4o/o1 models, excellent for algorithms and optimization
+
+See [AGENT_MODES.md](./AGENT_MODES.md) for detailed comparison and usage guide.
+
+### AI Providers
+
+#### Claude (Anthropic)
+
+```bash
+export ANTHROPIC_API_KEY=your-key-here
+contractspec create --ai --provider claude
+```
+
+#### OpenAI
+
+```bash
+export OPENAI_API_KEY=your-key-here
+contractspec create --ai --provider openai --model gpt-4o
+```
+
+#### Ollama (Local)
+
+Install Ollama and pull a model:
+
+```bash
+ollama pull codellama
+contractspec create --ai --provider ollama --model codellama
+```
+
+#### Custom OpenAI-Compatible Endpoint
+
+```bash
+contractspec create --ai --provider custom \
+  --endpoint https://your-llm.com/v1 \
+  --model your-model-name
+```
+
+Set via environment:
+
+```bash
+export CONTRACTSPEC_LLM_ENDPOINT=https://your-llm.com/v1
+export CONTRACTSPEC_LLM_API_KEY=your-key
+export CONTRACTSPEC_LLM_MODEL=your-model
+```
+
+### Supported Local Models (Ollama)
+
+- `codellama` - Code generation (recommended)
+- `llama3.1` - General purpose
+- `mistral` - Fast, good quality
+- `deepseek-coder` - Specialized for code
+
+## Examples
+
+### Create a Command Spec
+
+```bash
+contractspec create --type operation
+# Follow prompts:
+# - Name: user.signup
+# - Kind: command
+# - Description: Start user signup flow
+# etc.
+```
+
+### Build Handler from Spec
+
+Given a spec file `src/contracts/signup.contracts.ts`:
+
+```bash
+contractspec build src/contracts/signup.contracts.ts
+# Generates:
+# - src/handlers/signup.handler.ts
+# - src/handlers/signup.handler.test.ts
+```
+
+### Multi-Provider Workflow
+
+```bash
+# Draft with free local model
+contractspec create --ai --provider ollama
+
+# Refine with Claude for production
+contractspec build src/contracts/draft.ts --provider claude
+```
+
+## Advanced Usage
+
+### Multi-Provider and Multi-Agent Workflows
+
+Combine different providers and agents for optimal results:
+
+```bash
+# Draft specs with free local model
+contractspec create --ai --provider ollama --model codellama
+
+# Generate production code with Claude Code agent
+contractspec build src/contracts/user-signup.contracts.ts \
+  --agent-mode claude-code
+
+# Validate implementation with AI
+contractspec validate src/contracts/user-signup.contracts.ts \
+  --check-implementation \
+  --agent-mode claude-code
+
+# Use OpenAI for algorithmic code
+contractspec build src/contracts/search-algorithm.contracts.ts \
+  --agent-mode openai-codex
+```
+
+### Environment Variables
+
+```bash
+# API Keys
+export ANTHROPIC_API_KEY=your-key-here
+export OPENAI_API_KEY=your-key-here
+
+# Agent configuration
+export CONTRACTSPEC_AGENT_MODE=claude-code
+export CONTRACTSPEC_AI_PROVIDER=claude
+export CONTRACTSPEC_AI_MODEL=claude-3-7-sonnet-20250219
+
+# Custom provider
+export CONTRACTSPEC_LLM_ENDPOINT=https://your-llm.com/v1
+export CONTRACTSPEC_LLM_API_KEY=your-api-key
+```
+
+### CI/CD Integration
+
+```yaml
+# .github/workflows/contracts.yml
+name: Validate Contracts
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: oven-sh/setup-bun@v1
+      - run: pnpm install
+      - run: contractspec validate 'src/contracts/**/*.ts'
+```
+
+### Project Structure
+
+Recommended organization:
+
+```
+src/
+├── contracts/           # Contract specs
+│   ├── events/
+│   │   └── user-created.event.ts
+│   ├── interactions/
+│   │   ├── commands/
+│   │   │   └── user-signup.contracts.ts
+│   │   └── queries/
+│   │       └── user-get-profile.contracts.ts
+│   └── presentations/
+│       └── user-profile-card.presentation.ts
+├── handlers/            # Generated handlers
+├── components/          # Generated components
+└── forms/              # Generated forms
+```
+
+## Troubleshooting
+
+### "Provider not available" error
+
+**Claude:**
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+**OpenAI:**
+```bash
+export OPENAI_API_KEY=sk-...
+```
+
+**Ollama:**
+```bash
+# Install Ollama from https://ollama.ai
+ollama serve
+ollama pull codellama
+```
+
+### Slow generation
+
+For faster local generation, use smaller models:
+```bash
+contractspec create --ai --provider ollama --model codellama:7b
+```
+
+For cloud, use faster models:
+```bash
+contractspec build spec.ts --provider openai --model gpt-3.5-turbo
+```
+
+### Import errors in generated code
+
+Make sure `@lssm/lib.contracts` and `@lssm/lib.schema` are installed:
+```bash
+pnpm add @lssm/lib.contracts @lssm/lib.schema
+```
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Follow existing code style
+2. Add tests for new features
+3. Update documentation
+4. Ensure all tests pass: `pnpm test`
+
+## Agent Modes Deep Dive
+
+### When to Use Each Mode
+
+**Simple Mode** - Default, good for:
+- Rapid prototyping
+- Basic implementations
+- Quick iterations
+- CI/CD pipelines (fast)
+
+**Cursor Mode** - Best for:
+- Working in Windsurf/Cursor IDE
+- Complex, iterative development
+- Context-aware code generation
+
+**Claude Code Mode** - Best for:
+- Production-quality implementations
+- Critical business logic
+- Comprehensive code validation
+- Detailed code reviews
+
+**OpenAI Codex Mode** - Best for:
+- Algorithmic problems
+- Performance optimization
+- Mathematical computations
+- Complex data transformations
+
+For more details, see [AGENT_MODES.md](./AGENT_MODES.md).
+
+## Roadmap
+
+- [x] AI-powered code generation
+- [x] Multiple agent modes (simple, cursor, claude-code, openai-codex)
+- [x] AI-powered implementation validation
+- [x] Contract listing and discovery (`contractspec list`)
+- [x] Watch mode for auto-regeneration (`contractspec watch`)
+- [x] Multi-surface synchronization (`contractspec sync`)
+- [x] Cleanup utilities (`contractspec clean`)
+- [x] Dependency analysis (`contractspec deps`)
+- [x] Contract diffing and comparison (`contractspec diff`)
+- [x] CI/CD integration (`contractspec ci`) with SARIF/JSON output
+- [x] GitHub Action for CI/CD
+- [ ] Form spec generation
+- [ ] Feature spec bundling
+- [ ] Handler signature checking in validation
+- [ ] Test coverage validation
+- [ ] Interactive spec editing
+- [ ] GraphQL schema generation
+- [ ] OpenAPI/Swagger export
+
+## License
+
+MIT
+

package/bin/contractspec.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// One bin, picks the right runtime via conditional exports.
+import "@lssm/app.cli-contractspec/run";

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "spec-driven-development",
+  "version": "0.0.0-canary-20251223010757",
+  "description": "CLI tool for creating, building, and validating contract specifications",
+  "bin": {
+    "sdd": "./bin/contractspec.mjs"
+  },
+  "dependencies": {
+    "@lssm/app.cli-contractspec": "0.0.0-canary-20251223010757"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary"
+  },
+  "keywords": [
+    "cli",
+    "contracts",
+    "code-generation",
+    "ai",
+    "typescript"
+  ],
+  "publishConfig": {
+    "name": "contractspec",
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/apps/contractspec"
+  }
+}