@bluefly/openstandardagents 0.3.2 → 0.3.5

package/spec/v0.2.6-dev/CHANGELOG.md

@@ -1,164 +0,0 @@
-# OSSA v0.2.6-dev Release Notes
-
-**Release Date**: 2025-11-26
-**Type**: Patch Release (Documentation & Examples)
-**Status**: Development
-
-## Overview
-
-OSSA v0.2.6-dev is a documentation-focused release that enhances examples, improves migration guides, adds CLI utilities, and includes brand positioning resources.
-
-## What's New
-
-### CLI Utilities
-- `ossa-dev`: Development server with hot reload
-- `ossa-generate`: Scaffold agents and adapters
-- `ossa-health`: Health check for agent configs
-
-### Documentation Improvements
-
-#### Enhanced Examples
-- Added comprehensive inline documentation to 10 priority examples
-- Annotated kAgent examples with best practices
-- Improved getting-started guides with step-by-step instructions
-- Added production-ready enterprise agent examples
-
-#### Migration Guides (6 Frameworks)
-- **LangChain → OSSA**: Complete migration workflow with code examples
-- **CrewAI → OSSA**: Multi-agent orchestration patterns
-- **OpenAI Agents SDK → OSSA**: Assistants API conversion
-- **Anthropic MCP → OSSA**: Model Context Protocol bridge
-- **Langflow → OSSA**: Visual flow-to-manifest conversion
-- **Drupal ECA → OSSA**: Event-Condition-Action migration
-
-#### Brand Resources
-- Brand positioning and value proposition documentation
-- Visual identity system specification
-- Competitive comparison matrix (LangChain, AutoGen, MCP, Semantic Kernel)
-- Migration paths from alternative frameworks
-
-#### GitLab Wiki Integration
-- Migrated documentation to GitLab wiki
-- Added issue templates for standardized reporting
-- Created milestone tracking system
-- Integrated CI/CD documentation
-
-#### OpenAPI Extensions Documentation
-- Documented x-ossa-agent extension
-- Added x-ossa-manifest reference guide
-- Explained framework-specific extensions
-- Provided OpenAPI spec generation examples
-
-### Examples & Templates
-
-#### New Examples
-- `examples/kagent/README.md` - kAgent integration guide
-- `examples/integration-patterns/agent-to-agent-orchestration.ossa.yaml`
-- `examples/production/enterprise-agent.ossa.yaml`
-
-#### Updated Examples
-All kagent examples updated with:
-- Detailed inline comments
-- Best practice annotations
-- Real-world use cases
-- Troubleshooting tips
-
-### Build & Infrastructure
-
-#### npm Publishing Preparation
-- Package configured for public npm registry
-- Build artifacts optimized
-- Dependencies audited and updated
-- prepublishOnly hooks configured
-
-#### CI/CD Improvements
-- Consolidated GitLab CI/CD pipeline
-- Added comprehensive test coverage reports
-- Implemented security audit checks
-- Configured manual release triggers
-
-## Breaking Changes
-
-**None** - This release is fully backward compatible with v0.2.5.
-
-## Bug Fixes
-
-- Fixed schema validation for edge cases
-- Corrected example formatting inconsistencies
-- Updated broken documentation links
-- Resolved CI pipeline configuration issues
-- Version synchronization across project files
-- Website deployment configuration
-- Missing spec directory structures (v0.2.4, v0.2.5)
-
-## Schema Changes
-
-**No schema changes** - v0.2.6-dev schema is identical to v0.2.5 with updated version metadata only.
-
-## Migration from v0.2.5
-
-### Required Changes
-**None** - Simply update your `apiVersion` field (optional):
-
-```yaml
-# Both versions work identically
-apiVersion: ossa/v0.2.5  # Still valid
-apiVersion: ossa/v0.2.6  # Recommended
-```
-
-### Recommended Changes
-1. Review new migration guides if integrating with frameworks
-2. Update documentation references to use v0.2.6-dev
-3. Check out new examples for best practices
-
-See [migrations/v0.2.5-to-v0.2.6.md](migrations/v0.2.5-to-v0.2.6.md) for detailed migration guide.
-
-## Installation
-
-### npm (Recommended)
-```bash
-npm install -g @bluefly/openstandardagents@0.2.6
-```
-
-### Verify Installation
-```bash
-ossa --version
-# Output: 0.2.6
-```
-
-## Compatibility
-
-| Component | Version | Status |
-|-----------|---------|--------|
-| Node.js | >=18.0.0 | ✅ Required |
-| npm | >=9.0.0 | ✅ Required |
-| kAgent | v1alpha1 | ✅ Full support |
-| Drupal | 11.x, 10.x | ✅ Full support |
-| OpenAI SDK | v2.x | ✅ Full support |
-| LangChain | v0.3.x | ✅ Full support |
-| CrewAI | v0.11.x | ✅ Full support |
-| MCP | Latest | ✅ Full support |
-
-## Related Issues
-
-- #28 - Spec structure preparation
-- #26 - Version synchronization
-- #32 - CLI utilities enhancement
-- #44 - Brand identity development (epic)
-- #47 - Brand positioning
-- #48 - Visual identity
-- #49 - Comparison matrix
-
-## Support
-
-- **Documentation**: https://github.com/blueflyio/openstandardagents
-- **Issues**: https://github.com/blueflyio/openstandardagents/issues
-- **Examples**: https://github.com/blueflyio/openstandardagents/tree/main/examples
-
-## Acknowledgments
-
-Special thanks to the OSSA community for feedback and contributions!
-
----
-
-**Full Changelog**: [v0.2.5...v0.2.6](https://github.com/blueflyio/openstandardagents/compare/v0.2.5...v0.2.6)

package/spec/v0.2.6-dev/README.md

@@ -1,75 +0,0 @@
-# OSSA v0.2.6-dev Specification
-
-**Release Date**: November 26, 2025
-**Status**: Development
-**Version**: 0.2.6-dev
-
-## Overview
-
-OSSA (Open Standard for Scalable AI Agents) v0.2.6-dev is a development release that adds CLI utilities, brand positioning documentation, and competitive comparison resources while maintaining full backward compatibility.
-
-## What's in This Directory
-
-- **`ossa-0.2.6-dev.schema.json`** - JSON Schema definition for OSSA v0.2.6-dev agent manifests
-- **`CHANGELOG.md`** - Detailed release notes and feature descriptions
-- **`README.md`** - This file
-- **`migrations/`** - Upgrade guides from previous versions
-
-## Key Features
-
-### CLI Utilities
-- `ossa-dev`: Development server with hot reload
-- `ossa-generate`: Scaffold agents and adapters
-- `ossa-health`: Health check for agent configs
-
-### Transport Metadata
-- Protocol-specific configuration for capabilities
-- Streaming support (SSE, WebSocket, gRPC)
-- Enhanced integration with Google ADK, A2A protocol, MCP
-
-### Enhanced Security
-- Security policies for tools and memory
-- Access control for capabilities
-- Audit logging support
-
-### State Management
-- Persistent and ephemeral state handling
-- State versioning and migration
-- Multi-agent state coordination
-
-### Capability Versioning
-- Semantic versioning for tools and capabilities
-- Backward compatibility tracking
-- Deprecation warnings
-
-## Compatibility
-
-- **Backward Compatible**: Yes (with v0.2.2, v0.2.3, v0.2.4, v0.2.5)
-- **Breaking Changes**: None
-- **Supported API Versions**: `ossa/v0.2.2`, `ossa/v0.2.3`, `ossa/v0.2.4`, `ossa/v0.2.5`, `ossa/v0.2.6`, `ossa/v1`
-
-## Migration
-
-To upgrade from previous versions, see the migration guides:
-- [v0.2.5 → v0.2.6](./migrations/v0.2.5-to-v0.2.6.md)
-- [v0.2.4 → v0.2.6](./migrations/v0.2.4-to-v0.2.6.md)
-
-## Validation
-
-To validate manifests against this schema:
-
-```bash
-npm install @bluefly/openstandardagents
-ossa validate your-agent.yaml
-```
-
-## Resources
-
-- **Website**: https://openstandardagents.org
-- **Schema URL**: https://openstandardagents.org/schemas/v0.2.6-dev/agent.json
-- **GitHub**: https://github.com/blueflyio/openstandardagents
-- **npm Package**: https://npmjs.com/package/@bluefly/openstandardagents
-
-## License
-
-MIT License - See root LICENSE file for details.

package/spec/v0.2.6-dev/migrations/v0.2.2-to-v0.2.3.md

@@ -1,343 +0,0 @@
-# Migration Guide: OSSA v0.2.2 → v0.2.3
-
-**Migration Difficulty**: 🟢 **Trivial** (No breaking changes)
-**Estimated Time**: < 5 minutes
-**Downtime Required**: None
-
-## Overview
-
-OSSA v0.2.3 is a **documentation-only patch release** with **zero schema changes**. Existing v0.2.2 manifests work without modification. This guide covers optional updates to adopt v0.2.3 conventions.
-
-## TL;DR (Quick Migration)
-
-**No changes required!** Your v0.2.2 manifests work as-is.
-
-**Optional**: Update `apiVersion` field:
-
-```diff
-- apiVersion: ossa/v0.2.2
-+ apiVersion: ossa/v0.2.4
-```
-
-That's it!
-
----
-
-## What Changed?
-
-### Schema: ✅ Identical
-- **v0.2.2 schema hash**: `da22d4d47d4e9cc732c33290f971c670647d3318`
-- **v0.2.3 schema hash**: Same structure, updated version metadata only
-
-### Validation: ✅ Backward Compatible
-Both `ossa/v0.2.2` and `ossa/v0.2.4` accepted by the same validator.
-
-### What Actually Changed?
-- 📚 Enhanced documentation (README, wikis, examples)
-- 📖 6 new migration guides (LangChain, CrewAI, OpenAI, etc.)
-- 🏷️ Improved inline example annotations
-- 🔧 npm publishing preparation
-
----
-
-## Migration Steps
-
-### Step 1: Update CLI (Optional)
-
-If using the OSSA CLI:
-
-```bash
-# Update globally
-npm update -g @bluefly/openstandardagents
-
-# Verify version
-ossa --version
-# Expected: 0.2.3
-```
-
-### Step 2: Update Manifests (Optional)
-
-**Option A: Bulk Update (Recommended)**
-
-```bash
-# Find and replace in all OSSA manifests
-find . -name "*.ossa.yaml" -exec sed -i '' 's/apiVersion: ossa\/v0.2.2/apiVersion: ossa\/v0.2.3/g' {} +
-
-# Verify changes
-git diff
-```
-
-**Option B: Keep v0.2.2 (Also Fine)**
-
-```yaml
-# This still works! No need to update.
-apiVersion: ossa/v0.2.2
-kind: Agent
-# ... rest of manifest
-```
-
-**Option C: Manual Update**
-
-```yaml
-# Before
-apiVersion: ossa/v0.2.2
-kind: Agent
-metadata:
-  name: my-agent
-spec:
-  type: worker
-  # ... rest unchanged
-
-# After (optional)
-apiVersion: ossa/v0.2.4
-kind: Agent
-metadata:
-  name: my-agent
-spec:
-  type: worker
-  # ... rest unchanged
-```
-
-### Step 3: Validate (Recommended)
-
-```bash
-# Validate all manifests
-ossa validate my-agent.ossa.yaml
-
-# Output should be identical for both v0.2.2 and v0.2.3
-```
-
-### Step 4: Update Documentation References
-
-If you have internal docs referencing OSSA:
-
-```diff
-- Documentation: https://github.com/blueflyio/openstandardagents/tree/v0.2.2
-+ Documentation: https://github.com/blueflyio/openstandardagents/tree/v0.2.3
-
-- Schema: spec/v0.2.2/ossa-0.2.2.schema.json
-+ Schema: spec/v0.2.3/ossa-0.2.3.schema.json
-```
-
----
-
-## Compatibility Matrix
-
-| Format | v0.2.2 Validator | v0.2.3 Validator | Notes |
-|--------|------------------|------------------|-------|
-| `apiVersion: ossa/v0.2.2` | ✅ Valid | ✅ Valid | Backward compatible |
-| `apiVersion: ossa/v0.2.4` | ✅ Valid | ✅ Valid | Forward compatible |
-| `apiVersion: ossa/v1` | ✅ Valid | ✅ Valid | Alias for v0.2.x |
-
-**Conclusion**: Use whichever version you prefer - they're identical!
-
----
-
-## Testing Your Migration
-
-### 1. Validation Test
-
-```bash
-# Test with v0.2.2 manifest
-ossa validate examples/kagent/k8s-troubleshooter.ossa.yaml
-
-# Update to v0.2.3
-sed -i '' 's/v0.2.2/v0.2.3/' examples/kagent/k8s-troubleshooter.ossa.yaml
-
-# Validate again (should produce identical results)
-ossa validate examples/kagent/k8s-troubleshooter.ossa.yaml
-```
-
-### 2. Schema Validation Test
-
-```javascript
-const Ajv = require('ajv');
-const ajv = new Ajv();
-
-// Both schemas validate identically
-const schema022 = require('./spec/v0.2.2/ossa-0.2.2.schema.json');
-const schema023 = require('./spec/v0.2.3/ossa-0.2.3.schema.json');
-
-const manifest = {
-  apiVersion: 'ossa/v0.2.4',
-  kind: 'Agent',
-  metadata: { name: 'test' },
-  spec: { type: 'worker' }
-};
-
-console.log(ajv.validate(schema022, manifest)); // true
-console.log(ajv.validate(schema023, manifest)); // true
-```
-
-### 3. Runtime Test
-
-```bash
-# Generate agent with v0.2.3
-ossa generate test-agent --type worker
-
-# Should produce:
-# apiVersion: ossa/v0.2.4
-# kind: Agent
-# ...
-```
-
----
-
-## Troubleshooting
-
-### Issue: "Unsupported API version"
-
-**Solution**: Update OSSA CLI to v0.2.3+
-
-```bash
-npm update -g @bluefly/openstandardagents
-```
-
-### Issue: "Schema validation failed"
-
-**Diagnosis**: Likely a manifest syntax error, not a version issue.
-
-**Solution**:
-```bash
-# Check JSON/YAML syntax
-ossa validate --verbose my-agent.ossa.yaml
-
-# Common issues:
-# - Missing required fields (metadata, spec)
-# - Invalid YAML indentation
-# - Typos in field names
-```
-
-### Issue: "Cannot find schema v0.2.3"
-
-**Solution**: Clear cache and reinstall
-
-```bash
-rm -rf ~/.ossa/cache
-npm install -g @bluefly/openstandardagents@latest
-```
-
----
-
-## Rollback Plan
-
-If you encounter issues (unlikely), rollback is instant:
-
-```bash
-# Revert manifest changes
-git checkout -- *.ossa.yaml
-
-# Downgrade CLI (if needed)
-npm install -g @bluefly/openstandardagents@0.2.2
-```
-
-**Note**: Since there are no schema changes, rollback is safe and instant.
-
----
-
-## Framework-Specific Notes
-
-### kAgent (Kubernetes)
-```yaml
-# Both work identically with kagent CRDs
-apiVersion: ossa/v0.2.2  # ✅
-apiVersion: ossa/v0.2.4  # ✅
-```
-
-### Drupal (ai_agents module)
-```php
-// Both versions supported by ai_agents module
-$agent = new OssaAgent('my-agent', 'v0.2.2');  // ✅
-$agent = new OssaAgent('my-agent', 'v0.2.3');  // ✅
-```
-
-### LangChain
-```python
-# Both versions work with LangChain provider
-from ossa.langchain import OSSAAgent
-
-agent = OSSAAgent.from_manifest('agent-v0.2.2.yaml')  # ✅
-agent = OSSAAgent.from_manifest('agent-v0.2.3.yaml')  # ✅
-```
-
-### OpenAI Agents SDK
-```typescript
-// Both versions supported by OpenAI bridge
-import { OSSABridge } from '@ossa/openai';
-
-const agent = await OSSABridge.load('agent.ossa.yaml');
-// Works regardless of v0.2.2 or v0.2.3
-```
-
----
-
-## New Features to Explore (v0.2.3)
-
-While the schema is unchanged, v0.2.3 includes new resources:
-
-### 1. Enhanced Migration Guides
-- **Location**: `examples/migration-guides/`
-- **Covers**: LangChain, CrewAI, OpenAI, Anthropic MCP, Langflow, Drupal ECA
-- **Benefit**: Faster framework integration
-
-### 2. Annotated Examples
-- **Location**: `examples/kagent/*.ossa.yaml`
-- **Includes**: Inline comments explaining best practices
-- **Benefit**: Learn OSSA patterns by example
-
-### 3. GitHub Repository
-- **URL**: https://github.com/blueflyio/openstandardagents
-- **Content**: Comprehensive guides, tutorials, API references
-- **Benefit**: Centralized, searchable documentation
-
-### 4. Production Templates
-- **Location**: `examples/production/`
-- **Includes**: Enterprise-ready agent configurations
-- **Benefit**: Deploy faster with battle-tested patterns
-
----
-
-## FAQ
-
-### Q: Do I *have* to migrate?
-**A**: No! v0.2.2 manifests work indefinitely.
-
-### Q: Will v0.2.4 break compatibility?
-**A**: Patch versions (0.2.x) never break compatibility. Only minor (0.x.0) or major (x.0.0) versions may introduce changes.
-
-### Q: Should I update `apiVersion` in existing manifests?
-**A**: Optional. Update if you want to reflect the latest spec version, but v0.2.2 works equally well.
-
-### Q: Are there any deprecated features?
-**A**: No. Everything in v0.2.2 is still fully supported.
-
-### Q: Can I mix v0.2.2 and v0.2.3 manifests?
-**A**: Yes! They validate and execute identically.
-
----
-
-## Support
-
-If you encounter issues during migration:
-
-1. **Check Examples**: https://github.com/blueflyio/openstandardagents/tree/main/examples
-2. **Read Documentation**: https://github.com/blueflyio/openstandardagents
-3. **File Issue**: https://github.com/blueflyio/openstandardagents/issues
-
----
-
-## Summary
-
-✅ **No breaking changes**
-✅ **No migration effort required**
-✅ **Backward compatible**
-✅ **Forward compatible**
-✅ **Safe to adopt immediately**
-
-**Recommendation**: Update at your convenience. Both versions work identically.
-
----
-
-**Document Version**: 1.0
-**Last Updated**: 2025-11-12
-**Applies To**: OSSA v0.2.3