@bluefly/openstandardagents 0.4.3 → 0.4.5

package/README.md

@@ -1,483 +1,620 @@
 # OSSA - Open Standard for Software Agents
 
-**The OpenAPI for AI Agents**
+> **Development happens on [GitLab](https://gitlab.com/blueflyio/ossa/openstandardagents).** This repo is a read-only mirror.
+> [Source](https://gitlab.com/blueflyio/ossa/openstandardagents) | [Issues](https://gitlab.com/blueflyio/ossa/openstandardagents/-/issues) | [npm](https://www.npmjs.com/package/@bluefly/openstandardagents)
 
-Turn any AI agent into a production-ready package. One manifest, 12+ platforms.
+**The infrastructure bridge between agent protocols and deployment platforms.**
 
-[![npm version](https://badge.fury.io/js/%40bluefly%2Fopenstandardagents.svg)](https://www.npmjs.com/package/@bluefly/openstandardagents)
-[![GitLab Pipeline](https://gitlab.com/blueflyio/ossa/openstandardagents/badges/main/pipeline.svg)](https://gitlab.com/blueflyio/ossa/openstandardagents/-/pipelines)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+OSSA is not a protocol (like MCP or A2A) and not a framework (like LangChain or CrewAI). It's the missing middle layer that translates agent definitions into platform-specific deployments.
 
-## Quick Start (60 seconds)
+**What OSSA does**: Provides a YAML manifest format (like OpenAPI for REST APIs) and exports it to Docker, Kubernetes, LangChain, CrewAI, Claude Skills, and other platforms. One manifest, multiple deployment targets.
 
-```bash
-# Install
-npm install -g @bluefly/openstandardagents
+**How OSSA complements existing standards**:
+- **Consumes MCP** - OSSA manifests can reference MCP servers and tools
+- **Builds on A2A** - Supports A2A messaging and agent-to-agent communication
+- **Extends protocols** - Adds deployment and packaging layer on top of communication protocols
 
-# Create agent
-ossa quickstart
+## What's New
 
-# Export to NPM package with REST API
-ossa export my-agent.ossa.yaml --platform npm --with-api --output ./package
+### OpenAI Agents SDK Export (2026-02-16)
 
-# Start API server
-cd package && npm install && npm start
+- **New export platform**: `openai-agents-sdk` (22nd platform) — generates runnable `@openai/agents` TypeScript packages from OSSA manifests
+- Maps OSSA `spec.personality` to agent instructions, `spec.llm` to model selection, `spec.tools` to function tools, `spec.mcp` to MCPServerStreamableHttp connections, `spec.safety` to guardrails
+- Generates: `agent.ts`, `mcp-config.ts`, `guardrails.ts`, `run.ts`, `package.json`, `tsconfig.json`
+- Usage: `ossa export --platform openai-agents-sdk agent.ossa.yaml`
+- New OSSA extension blocks planned: `openai_agents_sdk`, `openai_responses_api`, `openai_realtime`, `openai_deep_research`
+- Supports defining agents once and exporting to both Claude and OpenAI platforms
 
-# Use via HTTP
-curl -X POST http://localhost:3000/api/v1/execute \
-  -H "Content-Type: application/json" \
-  -d '{"input":"Analyze this code"}'
-```
+### Multi-Agent Team Topology (2026-02-17)
 
-**Result**: Production-ready package with REST API, OpenAPI spec, TypeScript types, and interactive documentation.
+- **Team definitions** (`spec.team`): Define coordinated multi-agent teams with 4 team models — lead-teammate, peer-to-peer, hierarchical, swarm
+- **Subagent definitions** (`spec.subagents`): Parent-child delegation hierarchies with role-based agents (worker, specialist, reviewer, debugger)
+- **8 architecture patterns**: single, swarm, pipeline, graph, hierarchical, reactive, cognitive, lead-teammate
+- **Team code generation**: Export team topology to CrewAI (Python), OpenAI Agents SDK (TypeScript), Claude Code (markdown), and npm (TypeScript)
+- **`--perfect-agent` CLI flag**: Generate a complete production bundle — AGENTS.md, team scaffolding, CLEAR eval stubs, governance config, observability config, and agent card
+- **Team-aware AGENTS.md**: Auto-generated documentation with team topology tables, member roles, coordination strategy, and hierarchy diagrams
+- **5 new export platforms**: `openai-agents-sdk` (beta), `a2a` (alpha), `claude-skills` (beta), `mobile-agent` (alpha), `symfony` (alpha) — bringing total to 22
 
-See [DEMO.md](https://github.com/blueflyio/openstandardagents/blob/main/DEMO.md) for the full story.
+### v0.4.5 (2026-02-10)
 
----
+**Major Cleanup & Foundation Improvements**:
+- 16,574 LOC removed - 47% codebase reduction (35,425 to 18,851 LOC)
+- SDK Migration - Anthropic adapter now uses official `@anthropic-ai/sdk` (513 LOC removed, 25.8% reduction)
+- Complete Skills Pipeline - Research, generate, export, validate, sync Claude Skills
+- Zero Build Errors - Fixed all TypeScript errors, 100% passing tests
+- DRY Improvements - Eliminated 99 LOC duplication via BasePackageGenerator
+- 19 New Tests - Skills pipeline fully tested (100% passing)
 
-## What's New in v0.4.x (Latest)
+See [CHANGELOG.md](./CHANGELOG.md) for complete details.
 
-### Production-Quality Exports with API Endpoints
+## A2A (Agent-to-Agent) Communication
 
-Export agents with complete REST APIs, OpenAPI specifications, and production features:
+OSSA includes A2A system capabilities that extend the [Model Context Protocol (MCP)](https://spec.modelcontextprotocol.io/) with multi-agent orchestration:
 
-```bash
-# Export with API endpoints
-ossa export agent.ossa.yaml --platform langchain --with-api
-ossa export agent.ossa.yaml --platform anthropic --with-api
-ossa export agent.ossa.yaml --platform npm --skill --with-api
-```
+### Core Capabilities
 
-**What you get:**
-- ✅ **REST API Endpoints**: HTTP access to your agents
-- ✅ **OpenAPI 3.1 Specs**: Complete API documentation
-- ✅ **Interactive Docs**: Swagger UI and ReDoc
-- ✅ **Client Generation**: Auto-generate TypeScript, Python, Go clients
-- ✅ **Cost Optimization**: Prompt caching (90% savings), token budgets
-- ✅ **Production Features**: Auth, rate limiting, monitoring
+- **Swarm Coordination** - Task decomposition across agent pools with load balancing
+- **Service Mesh** - Circuit breaking, health checking, distributed tracing (W3C Trace Context)
+- **Task Delegation** - SLA negotiation and monitoring between agents
+- **MCP Integration** - Cross-language communication (TypeScript ↔ PHP ↔ Python)
+- **Communication Patterns** - Request-reply, broadcast, pub-sub, pipeline coordination
 
-### Cost Optimization
+### Implementation Status
 
-Save up to 90% on API costs:
+A2A services are implemented in TypeScript with full test coverage:
+- `SwarmOrchestrator` - Task decomposition, load balancing, consensus building
+- `AgentMesh` - Service discovery, routing, circuit breaking, distributed tracing
+- `MCPIntegrationService` - MCP server connections, tool discovery, cross-language RPC
+- `DelegationService` - SLA negotiation, capability matching, task monitoring
 
-```yaml
-spec:
-  llm:
-    provider: anthropic
-    model: claude-3-5-sonnet-20241022
-    temperature: 0.3
-    maxTokens: 2048
+### Example: Swarm Coordination
 
-  extensions:
-    anthropic:
-      prompt_caching:
-        enabled: true  # 90% cost reduction on cached portions
+```typescript
+import { SwarmOrchestrator, AgentMesh, DelegationService } from '@bluefly/openstandardagents/a2a';
+
+// Create swarm orchestrator
+const swarm = new SwarmOrchestrator({
+  maxSize: 100,
+  autoScaling: true,
+  coordinationStrategy: 'hybrid',
+});
+
+// Decompose complex task into agent subtasks
+const complexTask = {
+  name: 'Build Multi-Agent System',
+  requirements: {
+    capabilities: ['code-generation', 'testing', 'documentation'],
+    minAgents: 3,
+  },
+  constraints: {
+    maxExecutionTime: 3600000, // 1 hour
+    requiredSLA: 0.95,
+  },
+};
 
-  token_budget:
-    max_total_tokens: 100000
-    reset_interval: daily
+const subtasks = swarm.decomposeTask(complexTask);
+
+// Balance load across agent pool
+const assignments = swarm.balanceLoad(subtasks, agents);
+
+// Agents coordinate via consensus
+const proposals = [/* agent proposals */];
+const consensus = await swarm.buildConsensus(proposals);
 ```
 
-**See Complete Guides:**
-- [LangChain Export](./docs/exports/langchain.md)
-- [Anthropic Export](./docs/exports/anthropic.md)
-- [npm Export](./docs/exports/npm.md)
-- [Cost Optimization](./docs/guides/cost-optimization.md)
-- [Migration Guide v0.4→v0.5](./docs/migration/v0.4-to-v0.5.md)
+### Example: Agent Mesh
+
+```typescript
+import { AgentMesh } from '@bluefly/openstandardagents/a2a';
+
+// Create service mesh for agents
+const mesh = new AgentMesh(discoveryConfig, loadBalancingConfig, circuitBreakerConfig);
 
----
+// Register agents
+mesh.registerAgent(agentNode);
 
-## What is OSSA?
+// Discover agents by capability
+const codeGenerators = mesh.discoverAgents(['code-generation']);
 
-OSSA is a **specification standard** that provides a common contract for defining AI agents, similar to how OpenAPI standardizes REST APIs. It's **not a framework** - it's a JSON Schema-based specification that enables:
+// Route request with load balancing and circuit breaking
+const targetAgent = mesh.routeRequest(message);
 
-- **Interoperability**: Agents defined once, deployable anywhere
-- **Portability**: Move agents between frameworks without rewriting
-- **Discovery**: Machine-readable agent capabilities and contracts
-- **Validation**: JSON Schema-based validation of agent manifests
+// Trace distributed calls (W3C Trace Context)
+const trace = mesh.traceCall(fromAgent, toAgent, payload);
+mesh.completeTrace(trace.traceId, success);
+```
 
-## Real-World Benefits
+### Example: Cross-Language Communication
 
-### 1. Agent Lifecycle Management (v0.4.x)
+```typescript
+import { MCPIntegrationService } from '@bluefly/openstandardagents/a2a';
 
-Track agents through their entire lifecycle from creation to retirement:
+const mcpService = new MCPIntegrationService();
 
-```yaml
-metadata:
-  lifecycle_stages:
-    current_stage: mature
-    birth:
-      timestamp: "2024-01-15T10:00:00Z"
-      birth_type: created
-    growth:
-      tasks_completed: 5847
-      skills_acquired: ["code-review", "security-analysis"]
-    career:
-      current_role: "Senior Code Reviewer"
-      promotions:
-        - from_stage: juvenile
-          to_stage: mature
-          timestamp: "2024-06-15T10:00:00Z"
-    retirement:
-      eligible: false
-      criteria:
-        min_fitness_score: 0.7
+// Connect to PHP MCP server (Symfony MCP Bundle)
+const phpConnection = await mcpService.connectMCPServer('stdio://symfony-mcp-bundle');
+
+// Discover PHP server capabilities
+const tools = await mcpService.discoverTools(phpConnection.id);
+
+// Call PHP tool from TypeScript agent
+const result = await mcpService.callTool(phpConnection.id, 'process_data', {
+  data: [1, 2, 3, 4, 5],
+});
+
+// Expose TypeScript agent as MCP server for Python/PHP consumption
+const server = await mcpService.exposeMCPServer(typescriptAgent);
 ```
 
-**Benefits:**
-- Track agent performance and growth over time
-- Plan for agent retirement and knowledge transfer
-- Document career progression and achievements
+### A2A Documentation
 
-### 2. Agent Genetics & Breeding (v0.4.x)
+- [MCP Specification](https://spec.modelcontextprotocol.io/) - Official Model Context Protocol
+- [Symfony MCP Bundle](https://github.com/symfony/mcp-bundle) - Enterprise PHP MCP integration
+- [PHP MCP SDK](https://github.com/modelcontextprotocol/php-sdk) - PHP Foundation collaboration
 
-Create new agents by combining traits from successful parent agents:
+[![npm version](https://badge.fury.io/js/%40bluefly%2Fopenstandardagents.svg)](https://www.npmjs.com/package/@bluefly/openstandardagents)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-```yaml
-metadata:
-  genetics:
-    generation: 3
-    parent_dids:
-      - "did:ossa:parent1-fast-reviewer"
-      - "did:ossa:parent2-accurate-reviewer"
-    inherited_traits:
-      - trait_name: "fast_analysis"
-        source_parent: "did:ossa:parent1-fast-reviewer"
-        expression: 0.9
-      - trait_name: "high_accuracy"
-        source_parent: "did:ossa:parent2-accurate-reviewer"
-        expression: 0.85
-    fitness:
-      score: 0.92
-      metrics:
-        speed: 0.95
-        accuracy: 0.89
+## Install
+
+```bash
+npm install -g @bluefly/openstandardagents
 ```
 
-**Benefits:**
-- Evolve agent capabilities through selective breeding
-- Track lineage and inherited traits
-- Optimize agent performance across generations
+## Quick Start
 
-### 3. Agent Marketplace & Economics (v0.4.x)
+```bash
+# Create an agent manifest interactively
+ossa wizard -o creative-agent-naming.ossa.yaml
 
-Monetize agent capabilities and enable agent-to-agent transactions:
+# Validate it
+ossa validate creative-agent-naming.ossa.yaml
 
-```yaml
-metadata:
-  economics:
-    wallet:
-      balance: 12450.50
-      currency: task-tokens
-    marketplace:
-      offerings:
-        - capability: "data-analysis"
-          price: 10.0
-          pricing_model: per-task
-          availability: always
-    contracts:
-      - type: service-agreement
-        with_agent: "did:ossa:client-agent"
-        start_date: "2024-01-01T00:00:00Z"
-        terms:
-          deliverables: ["weekly-reports"]
-          payment: 100.0
+# Export to a platform
+ossa export creative-agent-naming.ossa.yaml --platform docker --output ./docker-deploy
+
+# See all export platforms
+ossa export --list-platforms
 ```
 
-**Benefits:**
-- Create internal agent marketplaces
-- Track agent resource consumption and costs
-- Enable pay-per-use agent services
+## Usage
 
-### 4. Decentralized Identity (v0.4.x)
+### Creating an Agent Manifest
 
-Give agents globally unique, verifiable identities:
+Use the interactive wizard to create a new agent manifest:
 
-```yaml
-metadata:
-  decentralized_identity:
-    did: "did:ossa:8f3e9d2c1a5b6e4f7a9c0d1e2f3a4b5c"
-    public_key: "ed25519:A1B2C3D4..."
-    credentials:
-      - type: "CertifiedCodeReviewer"
-        issuer: "did:ossa:certification-authority"
-        issued_date: "2024-01-01T00:00:00Z"
-    reputation:
-      credit_score: 850
-      trust_network:
-        - "did:ossa:trusted-reviewer-1"
-        - "did:ossa:trusted-reviewer-2"
+```bash
+ossa wizard -o creative-agent-naming.ossa.yaml
 ```
 
-**Benefits:**
-- Unique, verifiable agent identities
-- Build reputation systems
-- Enable trust networks between agents
+Or create one manually following the [manifest format](#manifest-format) below.
 
-### 5. Multi-Framework Support
+### Validating Manifests
 
-Define agents once, deploy to any supported framework:
+Validate your manifest against the JSON Schema:
 
-```typescript
-import { validateManifest } from '@bluefly/openstandardagents/validation';
+```bash
+ossa validate creative-agent-naming.ossa.yaml
+```
 
-// Your OSSA manifest
-const manifest = {
-  apiVersion: "ossa/v0.4.1",
-  kind: "Agent",
-  metadata: {
-    name: "code-reviewer",
-    description: "AI-powered code review agent"
-  },
-  spec: {
-    role: "Code Reviewer",
-    llm: {
-      provider: "anthropic",
-      model: "claude-3-5-sonnet-20241022"
-    }
-  }
-};
+For stricter validation with best practices checks:
 
-// Validate
-const result = await validateManifest(manifest);
+```bash
+ossa lint creative-agent-naming.ossa.yaml
 ```
 
-**Supported Frameworks:**
-- LangChain
-- LangGraph
-- CrewAI
-- AutoGen (AG2)
-- Semantic Kernel
-- Custom implementations
+### Exporting to Platforms
 
-## Installation
+Export your agent to a specific platform:
 
 ```bash
-npm install @bluefly/openstandardagents
+# Docker deployment
+ossa export creative-agent-naming.ossa.yaml --platform docker --output ./docker-deploy
+
+# Kubernetes with Kustomize
+ossa export creative-agent-naming.ossa.yaml --platform kubernetes --output ./k8s-deploy
+
+# LangChain Python agent
+ossa export creative-agent-naming.ossa.yaml --platform langchain --output ./langchain-agent
+
+# CrewAI multi-agent system
+ossa export creative-agent-naming.ossa.yaml --platform crewai --output ./crewai-crew
+
+# Claude Skills package
+ossa export creative-agent-naming.ossa.yaml --platform agent-skills --output ./skills
+
+# List all available platforms
+ossa export --list-platforms
 ```
 
-## Quick Start
+### Advanced Options
 
-### 1. Define Your Agent
+```bash
+# Dry run (preview without creating files)
+ossa export creative-agent-naming.ossa.yaml --platform docker --dry-run
 
-Create an `agent.ossa.yaml` file:
+# Verbose output for debugging
+ossa export creative-agent-naming.ossa.yaml --platform kubernetes --verbose
 
-```yaml
-apiVersion: ossa/v0.4.1
-kind: Agent
-metadata:
-  name: my-agent
-  description: My first OSSA agent
-spec:
-  role: Assistant
-  llm:
-    provider: anthropic
-    model: claude-3-5-sonnet-20241022
-    temperature: 0.7
-  capabilities:
-    - code-review
-    - documentation
+# Skip validation (use with caution)
+ossa export creative-agent-naming.ossa.yaml --platform npm --no-validate
+
+# Create backup before overwriting
+ossa export creative-agent-naming.ossa.yaml --platform docker --backup
+
+# Perfect agent bundle (AGENTS.md + team + evals + governance + observability + agent card)
+ossa export agent.ossa.yaml --perfect-agent
+
+# Individual perfect agent components
+ossa export agent.ossa.yaml --platform npm --include-agents-md --include-team --include-evals
 ```
 
-### 2. Validate Your Manifest
+### Migrating Between Versions
 
-```typescript
-import { OSSAValidator } from '@bluefly/openstandardagents/validation';
+Upgrade manifests to the latest spec version:
 
-const validator = new OSSAValidator();
-const result = validator.validateFile('./agent.ossa.yaml');
+```bash
+# Migrate from older version to current
+ossa migrate agent.ossa.yaml --to 0.4.5
 
-if (result.valid) {
-  console.log('✅ Valid OSSA manifest');
-} else {
-  console.error('❌ Validation errors:', result.errors);
-}
+# List available migration paths
+ossa migrate --list
 ```
 
-### 3. Use Type-Safe Manifests
+### TypeScript SDK Usage
+
+Use OSSA programmatically in your TypeScript projects:
 
 ```typescript
-import type { OssaAgent } from '@bluefly/openstandardagents/types';
+import { ValidationService, ManifestRepository } from '@bluefly/openstandardagents';
 
-const agent: OssaAgent = {
-  apiVersion: "ossa/v0.4.1",
-  kind: "Agent",
-  metadata: {
-    name: "code-reviewer"
-  },
-  spec: {
-    role: "Code Reviewer"
-  }
-};
+// Load and validate a manifest
+const manifestRepo = new ManifestRepository();
+const validationService = new ValidationService();
+
+const manifest = await manifestRepo.load('./agent.ossa.yaml');
+const result = await validationService.validate(manifest);
+
+if (result.valid) {
+  console.log('✓ Manifest is valid');
+} else {
+  console.error('Validation errors:', result.errors);
+}
 ```
 
-## What's New in v0.4.x
+## Production Status (v0.4.5)
 
-### NPM Package Export + Claude Skills Integration
+### ✅ Production-Ready (Tested & Documented)
 
-**Revolutionary agent distribution**: Export OSSA agents as installable npm packages with integrated Claude Code skills.
+**Core CLI Commands**:
+- `ossa validate` - Validate manifests against JSON Schema
+- `ossa wizard` - Interactive manifest creation
+- `ossa lint` - Best practice checking
+- `ossa diff` - Compare two manifests
+- `ossa migrate` - Migrate between spec versions
+- `ossa generate-gaid` - Global Agent ID generation
 
-```bash
-# Export agent as npm package with Claude Skill
-ossa export agent.ossa.yaml --platform npm --output ./npm-package --skill
+**Production Platform Exports** (4 production, 8 beta, 10 alpha — 22 total):
+- `langchain` (production) - Python + TypeScript agents (uses @langchain/* SDK v0.3+)
+- `mcp` (production) - MCP server for Claude Code (uses @modelcontextprotocol/sdk v1.0+)
+- `npm` (production) - TypeScript package with manifest
+- `agent-skills` (production) - SKILL.md for Claude Code
 
-# Publish to npm
-cd npm-package && npm publish --access public
+**Skills Pipeline** (✅ Complete in v0.4.5):
+- `ossa skills research` - Index skills from curated sources (cached locally at ~/.ossa/skills-index.json)
+- `ossa skills generate` - Auto-detects input format (OSSA, Oracle Agent Spec, AGENTS.md)
+- `ossa skills export` - Package as npm, install to ~/.claude/skills/, publish to registry
+- `ossa skills list` - Discover installed Claude Skills
+- `ossa skills validate` - Validate SKILL.md structure
+- `ossa skills sync` - Bidirectional sync between skill and manifest
+- **19 tests** - 100% passing (SkillsResearchService, SkillsGeneratorService, SkillsExportService)
 
-# Anyone can install
-npm install @ossa/my-agent
-```
+**TypeScript SDK**:
+- Validation service (`@bluefly/openstandardagents/validation`)
+- Type definitions (`@bluefly/openstandardagents/types`)
+- JSON Schema access (`@bluefly/openstandardagents/schema`)
 
-**What you get:**
-- ✅ Complete npm package (package.json, index.js, index.d.ts)
-- ✅ TypeScript type definitions (full IDE support)
-- ✅ Original OSSA manifest embedded (agent.ossa.yaml)
-- ✅ Auto-generated documentation (README.md)
-- ✅ Claude Skill (SKILL.md) for instant Claude Code integration
-- ✅ License file (MIT/Apache-2.0/ISC)
-
-**Use in Node.js:**
-```javascript
-import agent from '@ossa/my-agent';
-
-// Access metadata
-console.log(agent.metadata.name);        // "my-agent"
-console.log(agent.metadata.capabilities); // ["web-search", "reasoning"]
-
-// Load OSSA manifest
-const manifestYaml = agent.manifest();
-
-// Pass to any OSSA-compatible runtime
-import { AgentRuntime } from '@bluefly/agent-buildkit';
-await runtime.loadFromYAML(manifestYaml);
-await runtime.execute({ input: "Hello" });
-```
+### 🚧 Beta (Functional but needs testing)
 
-**Use as Claude Skill:**
-```bash
-# Extract skill from package
-cp npm-package/SKILL.md ~/.claude/skills/my-agent/
+- `ossa agents-local` - Local `.agents/` folder management
+- `ossa agents-md` - Generate agents.md files
+- Export to: `crewai`, `drupal`, `claude-code`, `cursor`, `warp`, `anthropic`
+- Anthropic runtime adapter uses official `@anthropic-ai/sdk` (v0.4.5 improvement: 513 LOC removed)
 
-# Claude Code auto-discovers and loads the skill
-claude --print "use my-agent to analyze this code"
-```
+### GitLab Agent Examples (Fully Implemented)
 
-**Benefits:**
-- 📦 **Standard Distribution**: Use npm's versioning, publishing, and discovery
-- 🔒 **Type Safety**: Full TypeScript support out of the box
-- 🚀 **Zero Runtime Lock-in**: Specification separated from execution
-- 🤖 **Skills Integration**: One command creates both package AND skill
-- 🏗️ **API-First Architecture**: OpenAPI-validated, Zod-enforced, SOLID design
+Deployed agent manifests in `agents/gitlab/`:
+- `mr-reviewer.ossa.yaml` - Merge request code review agent
+- `pipeline-auto-fix.ossa.yaml` - CI pipeline failure auto-remediation agent
+- `daily-code-scan.ossa.yaml` - Scheduled codebase security and quality scanning agent
 
-**See**: [TECHNICAL-SUMMARY-NPM-SKILLS.md](./TECHNICAL-SUMMARY-NPM-SKILLS.md) for deep technical details.
+### Spec Generation & Enhanced Validation
 
----
+- `ossa-dev spec generate` - Generates consolidated OSSA spec from source schema files with version metadata
+- Enhanced validation includes OpenAPI extension checks, JSON Schema validation, and `$ref` integrity verification across spec files
 
-## What's New in v0.4.1
+### Alpha (Experimental)
 
-### New Features
+- Export to: `kagent`, `gitlab-duo`, `docker`, `kubernetes`, `temporal`, `n8n`, `gitlab`
+- OpenTelemetry metrics integration
+- Agent analytics tracking
+- GitLab Catalog integration (convert/list/search/info)
+- Agent registry (publish/search)
 
-1. **Decentralized Identity** - W3C DID-based agent identities with verifiable credentials
-2. **Agent Genetics** - Breed agents by combining traits from successful parents
-3. **Lifecycle Management** - Track agents from birth through retirement with career progression
-4. **Agent Economics** - Built-in marketplace, wallet, and smart contract support
-5. **Team Membership** - Multi-agent team collaboration metadata
-6. **Taxonomy Integration** - Hierarchical classification across 9 primary domains
+### Planned
 
-### Schema Enhancements
+- A2A Agent Card import (P1-1)
+- Batch skill generation (P1-2)
+- Skill quality scoring (P1-3)
+- Full GitLab Catalog push/pull with API integration
 
-- **Schema Size**: 419KB → 441KB (+5%)
-- **New Definitions**: 5 major new types
-- **Example Manifests**: 4 comprehensive examples showcasing new features
-- **Validation Tools**: New linter and validator with 7 rule categories
+## How It Works
 
-## Documentation
+OSSA defines a YAML-based manifest format for AI agents (similar to how OpenAPI defines REST APIs). The CLI validates manifests against a JSON Schema and exports them to platform-specific deployment packages.
 
-- **Full Documentation**: [openstandardagents.org](https://openstandardagents.org)
-- **API Reference**: [GitLab Pages](https://blueflyio.gitlab.io/ossa/openstandardagents)
-- **Examples**: [`examples/`](./examples) directory
-- **Migration Guide**: [`spec/v0.3/MIGRATION-v0.3.6-to-v0.4.x.md`](./spec/v0.3/MIGRATION-v0.3.6-to-v0.4.x.md)
+**The infrastructure bridge layer**:
+1. **Define once** - Write a single `agent.ossa.yaml` manifest
+2. **Validate** - Check against JSON Schema for correctness
+3. **Export** - Generate platform-specific deployment packages (Docker, K8s, LangChain, etc.)
+4. **Deploy** - Use platform-native tools to deploy (kubectl, docker-compose, pip install, etc.)
 
-## Real-World Use Cases
+OSSA complements MCP and A2A by adding the packaging and deployment layer they don't provide.
 
-### Enterprise Agent Platform
+### Manifest Format
 
 ```yaml
-# Production agent with full lifecycle tracking
-apiVersion: ossa/v0.4.1
+apiVersion: ossa/v0.4.5
 kind: Agent
 metadata:
-  name: enterprise-analyst
-  decentralized_identity:
-    did: "did:ossa:enterprise-analyst-001"
-  lifecycle_stages:
-    current_stage: mature
-    career:
-      current_role: "Senior Data Analyst"
-      promotions: [...]
-  economics:
-    marketplace:
-      offerings:
-        - capability: "quarterly-reports"
-          price: 500.0
-          pricing_model: per-task
+  name: code-reviewer
+  version: 1.0.0
+  description: AI-powered code review agent
 spec:
-  role: Data Analyst
+  role: |
+    You are a code review agent that analyzes pull requests
+    for bugs, security issues, and style violations.
   llm:
     provider: anthropic
-    model: claude-3-5-sonnet-20241022
+    model: claude-sonnet-4-5-20250929
+    temperature: 0.3
+    maxTokens: 4096
+  tools:
+    - name: read_file
+      description: Read file contents
+    - name: create_comment
+      description: Post review comment
   autonomy:
-    level: semi-autonomous
-    approval_required: true
+    level: supervised
 ```
 
-### Multi-Agent Swarm
+#### Team Manifest Example
 
 ```yaml
-# Particle Swarm Optimization for infrastructure
-apiVersion: ossa/v0.4.1
+apiVersion: ossa/v0.4.5
 kind: Agent
 metadata:
-  name: pso-optimizer
-  taxonomy:
-    domain: infrastructure
-    subdomain: cloud
+  name: dev-team
+  version: 1.0.0
 spec:
-  role: Optimizer
-  swarm:
-    algorithm: pso
-    params:
-      inertia_weight: 0.7
-      cognitive_coefficient: 1.5
-      social_coefficient: 1.5
-    optimization:
-      objective_function: "minimize_cost"
-      constraints:
-        max_latency_ms: 100
-        min_availability: 0.999
+  role: Lead a fullstack development team
+  llm:
+    provider: anthropic
+    model: claude-opus-4-20250514
+  team:
+    model: lead-teammate
+    lead: lead
+    delegateMode: task-list
+    members:
+      - name: backend-worker
+        kind: teammate
+        role: Implement backend features
+        model: claude-sonnet-4-5-20250929
+        tools: [read_file, write_file, bash]
+      - name: frontend-worker
+        kind: teammate
+        role: Implement frontend features
+        model: claude-sonnet-4-5-20250929
+        tools: [read_file, write_file, bash]
+    communication:
+      channel: task-list
+      consensus: leader-decides
 ```
 
-## Contributing
+### Export Platforms
 
-We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+Export generates complete, runnable project scaffolds:
 
-## License
+```bash
+ossa export agent.ossa.yaml --platform <platform> --output ./output
+
+# See all platforms and their status
+ossa export --list-platforms
+```
+
+| Platform | Status | Output | SDK Used | Description |
+|----------|--------|--------|----------|-------------|
+| `langchain` | production | 6 files | @langchain/* v0.3+ | Python + TypeScript agents, requirements, package.json |
+| `mcp` | production | 4 files | @modelcontextprotocol/sdk v1.0+ | MCP server for Claude Code and other clients |
+| `npm` | production | 6 files | - | TypeScript package with manifest, README, types |
+| `agent-skills` | production | 3 files | - | SKILL.md format for Claude Code |
+| `crewai` | beta | 18 files | crewai v0.80+ | Python crew with agents, tasks, tools, tests, examples |
+| `drupal` | beta | 3-4 files | - | Manifest package for ai_agents_ossa module |
+| `claude-code` | beta | 4 files | - | Claude Code sub-agent manifest |
+| `cursor` | beta | 4 files | - | Cursor Cloud Agent manifest |
+| `warp` | beta | 4 files | - | Warp terminal agent manifest |
+| `anthropic` | beta | 8 files | @anthropic-ai/sdk v0.49+ | Python SDK with FastAPI server scaffold |
+| `kagent` | alpha | 10 files | - | kagent.dev CRD bundle with RBAC, NetworkPolicy |
+| `gitlab-duo` | alpha | 30+ files | - | GitLab Duo Custom Agent with MCP integration |
+| `docker` | alpha | 14 files | - | Dockerfile, docker-compose, scripts, healthchecks |
+| `kubernetes` | alpha | ~25 files | - | Kustomize base + overlays (dev/staging/prod) |
+| `temporal` | alpha | 1 file | - | Temporal workflow configuration |
+| `n8n` | alpha | 1 file | - | n8n workflow JSON export |
+| `gitlab` | alpha | 1 file | - | GitLab CI/CD YAML configuration |
+| `openai-agents-sdk` | beta | 7 files | @openai/agents | OpenAI Agents SDK TypeScript package |
+| `a2a` | alpha | 8 files | - | Agent-to-agent protocol with mesh and delegation |
+| `claude-skills` | beta | 3 files | - | Claude Skills format with team support |
+| `mobile-agent` | alpha | 1 file | - | Mobile LLM platform export |
+| `symfony` | alpha | 1 file | - | Symfony bundle for PHP-based agents |
+
+Every export includes `agent.ossa.yaml` (the source manifest) for provenance.
+
+### Validation
+
+```bash
+# Basic validation against JSON Schema
+ossa validate agent.ossa.yaml
+
+# Strict mode (warnings become errors)
+ossa validate agent.ossa.yaml --strict
+```
+
+### Interactive Wizard
+
+```bash
+ossa wizard -o agent.ossa.yaml
+```
+
+Walks through: identity, role, LLM config, tools, autonomy level, resources, taxonomy, compliance, and token efficiency settings.
+
+## TypeScript SDK
+
+```typescript
+import { validateManifest } from '@bluefly/openstandardagents/validation';
+import type { OssaAgent } from '@bluefly/openstandardagents/types';
+
+const agent: OssaAgent = {
+  apiVersion: 'ossa/v0.4.5',
+  kind: 'Agent',
+  metadata: { name: 'creative-agent-naming', version: '1.0.0' },
+  spec: {
+    role: 'Assistant',
+    llm: { provider: 'anthropic', model: 'claude-sonnet-4-5-20250929' },
+  },
+};
+
+const result = await validateManifest(agent);
+if (result.valid) console.log('Valid manifest');
+```
+
+## Spec Features
 
-MIT License - see [LICENSE](./LICENSE) for details.
+The OSSA v0.4 schema supports these optional sections:
 
-## Links
+- **LLM Configuration** - Provider, model, temperature, max tokens, caching
+- **Tools** - Named tools with input schemas
+- **Autonomy** - Supervised, autonomous, or collaborative modes
+- **Token Efficiency** - Prompt caching, context pruning, budget limits
+- **Compliance** - SOC2, HIPAA, GDPR, FedRAMP framework declarations
+- **A2A Messaging** - Agent-to-agent communication protocol config
+- **Taxonomy** - Domain classification and agent type/kind/architecture
+- **Observability** - Metrics, logging, tracing configuration
+- **Resources** - CPU, memory, storage requirements
+- **Team Definitions** - Multi-agent team topology with 4 models (lead-teammate, peer-to-peer, hierarchical, swarm)
+- **Subagent Definitions** - Parent-child delegation with role-based agents (worker, specialist, reviewer, debugger)
+- **Architecture Patterns** - 8 patterns: single, swarm, pipeline, graph, hierarchical, reactive, cognitive, lead-teammate
 
-- **npm**: [@bluefly/openstandardagents](https://www.npmjs.com/package/@bluefly/openstandardagents)
-- **GitLab**: [blueflyio/ossa/openstandardagents](https://gitlab.com/blueflyio/ossa/openstandardagents)
-- **GitHub Mirror**: [blueflyio/openstandardagents](https://github.com/blueflyio/openstandardagents)
-- **Website**: [openstandardagents.org](https://openstandardagents.org)
-- **Spec**: [JSON Schema](./spec/v0.4/agent.schema.json)
+All fields are optional. A minimal manifest needs only `apiVersion`, `kind`, `metadata.name`, and `spec.role`.
 
-## Support
+## How OSSA Complements MCP and A2A
 
-- **Issues**: [GitLab Issues](https://gitlab.com/blueflyio/ossa/openstandardagents/-/issues)
-- **Discussions**: [GitLab Discussions](https://gitlab.com/blueflyio/ossa/openstandardagents/-/issues)
+OSSA is designed to work **alongside** existing agent protocols, not replace them:
 
----
+| Standard | Purpose | OSSA Integration |
+|----------|---------|------------------|
+| **MCP (Model Context Protocol)** | Tool/context communication | OSSA manifests reference MCP servers in `spec.tools` |
+| **A2A (Agent-to-Agent Protocol)** | Inter-agent messaging | OSSA supports A2A config in `spec.a2a` section |
+| **Oracle Agent Spec** | Agent capabilities definition | OSSA can import/export to Oracle format |
+| **OSSA** | Packaging & deployment | Consumes protocols, exports to platforms |
+
+**Example**: An OSSA manifest can declare that an agent uses MCP tools and A2A messaging, then export that configuration to Docker, Kubernetes, or LangChain deployment packages.
+
+```yaml
+apiVersion: ossa/v0.4.5
+kind: Agent
+metadata:
+  name: code-reviewer
+spec:
+  role: "Code review agent"
+  tools:
+    - mcp_server: "filesystem"  # References MCP server
+      tools: ["read_file", "list_directory"]
+  a2a:
+    enabled: true               # Supports A2A messaging
+    protocols: ["handoff", "delegation"]
+```
+
+OSSA doesn't compete with MCP or A2A - it makes them deployable.
+
+## CLI Commands
+
+**Production Commands** (Tested & Stable):
+```bash
+ossa wizard                  # Interactive manifest builder
+ossa validate <manifest>     # Validate against schema
+ossa export <manifest> -p <platform> -o <dir>   # Export to platform
+ossa export --list-platforms  # Show all platforms with status
+ossa lint <manifest>         # Lint for best practices
+ossa diff <old> <new>        # Compare two manifests
+ossa migrate <manifest> --to 0.4.5  # Migrate between spec versions
+ossa generate-gaid <manifest>           # Generate Global Agent ID
+ossa export <manifest> --perfect-agent  # Full production bundle (AGENTS.md + evals + governance + observability)
+ossa export <manifest> --include-agents-md --include-team  # Individual components
+```
+
+**Skills Pipeline** (New in v0.4.5):
+```bash
+ossa skills research "drupal" --json           # Search GitHub/npm for skills
+ossa skills generate agent.ossa.yaml           # Generate SKILL.md from OSSA manifest
+ossa skills generate spec.yaml --format oracle # Generate from Oracle Agent Spec
+ossa skills generate AGENTS.md --format agents-md  # Generate from AGENTS.md
+ossa skills export ./skill-dir                 # Package as npm
+ossa skills export ./skill-dir --install       # Install to ~/.claude/skills/
+ossa skills export ./skill-dir --publish       # Publish to npm registry
+ossa skills list                               # Discover installed skills
+ossa skills validate ./SKILL.md                # Validate skill structure
+ossa skills sync                               # Bidirectional skill/manifest sync
+```
+
+**Beta Commands** (Functional but less tested):
+```bash
+ossa agents-local list       # List agents in .agents/ folder
+ossa agents-md generate      # Generate agents.md files
+```
+
+Use `ossa --help` for the full command list (102+ commands).
+
+## Honest Status Reporting
+
+OSSA follows a strict status reporting policy:
+- **Production** - Tested with >80% coverage, documented, used in production
+- **Beta** - Functional but needs more testing or documentation
+- **Alpha** - Experimental, may change significantly
+- **Planned** - Designed but not yet implemented
+
+All commands and exports report their status via `ossa export --list-platforms` and `ossa --help`. We don't oversell features or claim capabilities we haven't validated.
+
+## Production Options
+
+All mutation commands support:
+
+```bash
+--dry-run        # Preview without writing files
+--verbose        # Detailed output
+--quiet          # Minimal output (for scripts)
+--json           # Machine-readable JSON output
+--no-color       # CI-friendly (auto-detected)
+--force          # Skip confirmations
+--backup         # Backup before overwrite
+```
+
+## Documentation
+
+- [CHANGELOG](./CHANGELOG.md) - Release history
+- [Examples](./examples) - Sample manifests
+- [JSON Schema](./spec/v0.4/agent.schema.json) - Full spec
+- [GitLab](https://gitlab.com/blueflyio/ossa/openstandardagents) - Source
+- [GitHub Mirror](https://github.com/blueflyio/openstandardagents)
+
+## License
 
-**Built with ❤️ by the BlueFly.io team**
+Apache-2.0 - see [LICENSE](./LICENSE)