@bluefly/openstandardagents 0.2.5-RC → 0.2.8

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

@@ -0,0 +1,164 @@
+# 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/dist/spec/v0.2.6-dev/README.md

@@ -0,0 +1,75 @@
+# 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/dist/spec/v0.2.6-dev/migrations/v0.2.2-to-v0.2.3.md

@@ -0,0 +1,343 @@
+# 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