OSSA CLI Validator Tool

Objective

Create a professional command-line tool for validating OSSA agent manifests, comparable to `swagger validate` for OpenAPI.

Features

Core Validation

```bash

Basic validation

ossa validate agent.yaml

Validate with detailed output

ossa validate agent.yaml --verbose

Validate directory of manifests

ossa validate ./agents/

Output formats

ossa validate agent.yaml --format json ossa validate agent.yaml --format junit # for CI/CD ```

Advanced Features

Schema versioning: Auto-detect OSSA version, validate against correct schema
Linting: Best practice recommendations (not just schema compliance)
Fix suggestions: Suggest fixes for common errors
CI/CD integration: Exit codes, machine-readable output
Watch mode: `ossa validate --watch` for development

Linting Rules

Warn if agent has no description
Warn if capabilities lack examples
Suggest resource limits for k8s runtime
Flag overly permissive security policies
Recommend observability configuration

Implementation

Tech Stack

TypeScript (for consistency with validator)
Commander.js for CLI framework
Chalk for colored output
AJV for JSON Schema validation
Cosmiconfig for configuration files

CLI Structure

```typescript ossa ├── validate <file|dir> # Validate manifests ├── lint <file|dir> # Lint for best practices ├── info # Display agent metadata ├── init # Generate skeleton manifest └── version # Show OSSA spec version ```

Acceptance Criteria

Validates all examples without errors
Provides clear, actionable error messages
Exit code 0 for valid, non-zero for invalid
JSON output mode for CI integration
`--fix` flag for auto-fixable issues
Published to npm as `@ossa/cli`
Comprehensive README with usage examples
Tested on Linux, macOS, Windows

Package Structure

``` packages/cli/ ├── src/ │ ├── commands/ │ │ ├── validate.ts │ │ ├── lint.ts │ │ └── init.ts │ ├── validators/ │ ├── linters/ │ └── cli.ts ├── tests/ ├── package.json └── README.md ```

Example Output

```bash $ ossa validate agent.yaml

✓ agent.yaml is valid OSSA 1.0 manifest

Agent: compliance-scanner v1.2.0 Runtime: kubernetes Capabilities: 3 Warnings: 1

⚠️ Consider adding resource limits for production deployment Learn more: https://ossa.io/docs/best-practices#resources ```

Labels

`tooling`, `cli`, `validation`, `developer-experience`

Milestone

v0.3.0 - Reference Tooling