@bluefly/openstandardagents 0.5.1 → 0.5.4

package/README.md

@@ -1,731 +1,262 @@
-# OSSA - Open Standard for Software Agents
+# Open Standard for Software Agents (OSSA)
 
-> **Source of truth**: [GitLab](https://gitlab.com/blueflyio/ossa/openstandardagents) — development, issues, and CI happen here.
-> [GitLab](https://gitlab.com/blueflyio/ossa/openstandardagents) | [Issues](https://gitlab.com/blueflyio/ossa/openstandardagents/-/issues) | [npm](https://www.npmjs.com/package/@bluefly/openstandardagents)
+OSSA is an open standard for defining, validating, discovering, and governing software agents.
 
-**The infrastructure bridge between agent protocols and deployment platforms.**
+OSSA is not a framework. It is a contract layer: schema, identity, capabilities, policy bindings, discovery metadata, and validation rules that allow agents to be portable across runtimes and organizations.
 
-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.
+> Development happens on [GitLab](https://gitlab.com/blueflyio/ossa/openstandardagents) (source of truth).
+> [Source](https://gitlab.com/blueflyio/ossa/openstandardagents) | [Issues](https://gitlab.com/blueflyio/ossa/openstandardagents/-/issues) | [npm](https://www.npmjs.com/package/@bluefly/openstandardagents)
 
-**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.
+## Why OSSA Exists
 
-**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
+Agent systems are fragmenting across IDEs, model providers, MCP servers, workflow engines, Drupal, GitLab, Kubernetes, and private enterprise platforms.
 
-## Why OSSA + DUADP
-
-AI agents need the same foundational infrastructure the internet has: **identity**, **discovery**, and **governance**. OSSA and DUADP together deliver that stack:
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│  Layer 1 — IDENTITY  (this repo)                             │
-│  OSSA (Open Standard for Software Agents)                    │
-│  openstandardagents.org                                      │
-│                                                              │
-│  · Agent DID — W3C decentralized identity per agent          │
-│  · Signed manifests — cryptographic provenance + SBOM        │
-│  · Cedar policies — zero-trust authorization bounds          │
-│  · NIST SP 800-53 control mapping built in                   │
-└─────────────────────┬────────────────────────────────────────┘
-                      │  secure identity
-                      ▼
-┌──────────────────────────────────────────────────────────────┐
-│  Layer 2 — DISCOVERY                                         │
-│  DUADP (Decentralized Universal AI Discovery Protocol)       │
-│  duadp.org | npm install @bluefly/duadp                      │
-│                                                              │
-│  · Federated DNS + WebFinger agent discovery                 │
-│  · Cross-node gossip federation                              │
-│  · Policy-aware capability routing                           │
-│  · Trust-tier gating (community → verified → federal)        │
-└─────────────────────┬────────────────────────────────────────┘
-                      │  policy-filtered
-                      ▼
-┌──────────────────────────────────────────────────────────────┐
-│  Layer 3 — EXECUTION                                         │
-│  Your runtime: Kubernetes, Claude, LangChain, Drupal, etc.   │
-└──────────────────────────────────────────────────────────────┘
-```
-
-**OSSA defines the agent. DUADP discovers it.**
-
-| Security requirement | OSSA | DUADP |
-|---|---|---|
-| Agent identity & authentication | W3C DID (GAID) per agent | DID-verified nodes |
-| Authorization & least-privilege | AWS Cedar policies in manifest | Trust-tier gating |
-| Governance & human oversight | Signed manifests + OSCAL pointers | Audit log + attestation API |
-| Cross-system interoperability | Multi-platform exports | Federated gossip discovery |
-| Monitoring & incident response | Observability config in spec | Revocation + incident endpoints |
-| Supply chain security | `x-signature` + SBOM | Signed resource registry |
-
-> [openstandardagents.org/specification →](https://openstandardagents.org/specification) | [duadp.org →](https://duadp.org)
-
-## NIST CAISI Alignment (NIST-2025-0035)
-
-If you're evaluating OSSA/DUADP for federal or regulated deployments, see the detailed alignment documentation:
-
-OSSA natively aligns with the [NIST CAISI Request for Information on Collaborative AI Systems Integration](https://www.regulations.gov/docket/NIST-2025-0035), providing the critical **Contract Layer** missing from current agent protocols.
-
-- **Agent Identity (IA-3)**: W3C Decentralized Identifiers (GAID) provide cryptographic origin authentication for agents.
-- **Pre-Authorization (AC-3, AC-6)**: Deterministic AWS Cedar policies evaluated at the transport layer enforce zero-trust bounds before an LLM receives context.
-- **Federated Discovery**: Integration with DUADP (`.well-known` endpoints) scales agent discovery securely across organizational boundaries without centralized lock-in.
-- **Supply Chain Security (SI-7)**: Cryptographically signed manifests (`x-signature`) and explicit OSCAL/SBOM pointers prevent tool poisoning and supply chain attacks.
-
-## What's New in v0.5.1
-
-- **Memory Hierarchy (P5)**: Three-tier memory contracts (working → episodic → long-term) with `ossa memory init|index|resolve|promote` CLI.
-- **Execution Economics (Layer 4)**: `ExecutionProfile`, `ContextPack`, `ReplayPacket` schemas; `ossa execution-profile validate`, `ossa context-pack build`, `ossa task quote`.
-- **StateMesh Integration**: Agents publish `StateClaims` to the mesh at runtime; governed state exchange via `extensions.statemesh`.
-- **Reasoning Escrow**: Cryptographic hashing of reasoning traces in the AI SDK v6 `ToolLoopAgent` — auditable yet private.
-- **AI SDK v6 Loop**: Native `ToolLoopAgent` in `OpenAIAdapter`; `@ai-sdk/anthropic` and `@ai-sdk/google` adapters added.
-- **DUADP Trust Tiers**: Native four-tier trust model (Official → Verified → Community → Unverified) wired into discovery.
-- **Agent Builder API**: `/api/agent-builder` canonical route; `apiVersion >= ossa/v0.5.0` enforced at scaffold time.
-- **CAOE cognition types**: `session`, `hypothesis`, `alignment gate` JSON schema extensions + `kind: Role` manifest.
-- **Skills Pipeline (6 commands)**: `ossa skills research|generate|export|list|validate|sync` — production-ready, 19 tests passing.
-- **5 new skill plugins**: `database-migration`, `chaos-engineering`, `performance-profiling`, `compliance-auditing`, `incident-response`.
-- **Dependency compliance**: `uuid ^11.1.0`, `@modelcontextprotocol/sdk ^1.26.0`.
-
-See [CHANGELOG.md](./CHANGELOG.md) for complete details.
-
-## A2A (Agent-to-Agent) Communication
-
-OSSA includes A2A system capabilities that extend the [Model Context Protocol (MCP)](https://spec.modelcontextprotocol.io/) with multi-agent orchestration:
-
-### Core Capabilities
-
-- **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
-
-### Implementation Status
-
-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
-
-### Example: Swarm Coordination
-
-```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,
-  },
-};
-
-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);
-```
-
-### 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);
-
-// Discover agents by capability
-const codeGenerators = mesh.discoverAgents(['code-generation']);
-
-// Route request with load balancing and circuit breaking
-const targetAgent = mesh.routeRequest(message);
-
-// Trace distributed calls (W3C Trace Context)
-const trace = mesh.traceCall(fromAgent, toAgent, payload);
-mesh.completeTrace(trace.traceId, success);
-```
-
-### Example: Cross-Language Communication
+OSSA provides a stable contract for agent identity, manifests, tool declarations, capability boundaries, governance metadata, runtime interoperability, discovery, validation, and auditability.
 
-```typescript
-import { MCPIntegrationService } from '@bluefly/openstandardagents/a2a';
-
-const mcpService = new MCPIntegrationService();
+Without a contract layer, every integration is bespoke. With OSSA, one manifest describes an agent and any conforming runtime can consume it.
 
-// Connect to PHP MCP server (Symfony MCP Bundle)
-const phpConnection = await mcpService.connectMCPServer('stdio://symfony-mcp-bundle');
+## Core Analogy
 
-// Discover PHP server capabilities
-const tools = await mcpService.discoverTools(phpConnection.id);
+**OpenAPI : APIs :: OSSA : Agents**
 
-// Call PHP tool from TypeScript agent
-const result = await mcpService.callTool(phpConnection.id, 'process_data', {
-  data: [1, 2, 3, 4, 5],
-});
+OpenAPI does not implement your API. It describes it.
+OSSA does not implement your agent. It describes it.
 
-// Expose TypeScript agent as MCP server for Python/PHP consumption
-const server = await mcpService.exposeMCPServer(typescriptAgent);
-```
+## Package
 
-### A2A Documentation
+**npm:** `@bluefly/openstandardagents`
 
-- [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
+Current stable release: `0.5.1`
+Prepared release: `0.5.2`
 
-[![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)
-
-## Install
+> **Note:** `0.5.3` was accidentally published during recovery and is deprecated. Do not use it.
 
 ```bash
-npm install -g @bluefly/openstandardagents
+npm install @bluefly/openstandardagents@0.5.2
 ```
 
-OSSA uses [`@bluefly/duadp`](https://www.npmjs.com/package/@bluefly/duadp) for agent discovery and federation via the [UADP protocol](https://github.com/blueflyio/duadp).
+Requires Node.js 20+.
 
-## Quick Start
+## CLI
 
 ```bash
-# Create an agent manifest interactively
-ossa wizard -o creative-agent-naming.ossa.yaml
-
-# Validate it
-ossa validate creative-agent-naming.ossa.yaml
-
-# Export to a platform
-ossa export creative-agent-naming.ossa.yaml --platform docker --output ./docker-deploy
-
-# See all export platforms
-ossa export --list-platforms
+npx ossa validate ./agent.ossa.yaml
+npx ossa validate-spec
+npx ossa discover https://example.com
+npx ossa resolve-did did:web:example.com:agent:demo
+npx ossa lint-openapi
 ```
 
-## Usage
+Exit code `0` means valid. Non-zero prints JSON-pointer paths and error messages.
 
-### Creating an Agent Manifest
-
-Use the interactive wizard to create a new agent manifest:
+From a repo clone (avoids conflicting global shims):
 
 ```bash
-ossa wizard -o creative-agent-naming.ossa.yaml
-# or without global install:
-npx @bluefly/openstandardagents wizard -o creative-agent-naming.ossa.yaml
+pnpm install
+pnpm build
+pnpm run ossa validate path/to/agent.ossa.yaml
 ```
 
-For the full wizard flow (steps 1-10: creation method, basic info, domain, LLM, tools, autonomy, observability, deployment, advanced, token efficiency, separation of duties, review) and the standard folder layout (`.agents/{name}/` with manifest.ossa.yaml), see [What is an Agent](docs/getting-started/what-is-an-agent.md) and [Agent Folder Structure](docs/architecture/agent-folder-structure.md). For a more comprehensive interactive flow, use `ossa agent-wizard`.
-
-Or create one manually following the [manifest format](#manifest-format) below.
+## What This Package Contains
 
-### Validating Manifests
+- JSON Schemas for OSSA v0.5 manifests (agent, workflow, registry, policy-binding)
+- Reference OpenAPI contracts (invocation, compliance-engine)
+- Validation utilities (programmatic and CLI)
+- CLI entrypoint (`ossa`)
+- Reference agent manifests
+- Well-known discovery document (`.well-known/ossa.json`)
 
-Validate your manifest against the JSON Schema:
+## What This Package Does Not Contain
 
-```bash
-ossa validate creative-agent-naming.ossa.yaml
-```
+- Agent runtime
+- Orchestration engine
+- MCP server implementation
+- Deployment controller
+- Drupal module
+- GitLab automation
+- Policy decision point
 
-For stricter validation with best practices checks:
+Those belong in adjacent projects (see Project Ecosystem below).
 
-```bash
-ossa lint creative-agent-naming.ossa.yaml
-```
+## OSSA v0.5 Concepts
 
-### Exporting to Platforms
+**Agent Manifest** — Defines an agent's identity, role, tools, capabilities, governance metadata, and interoperability surfaces.
 
-Export your agent to a specific platform:
+**Role** — A behavioral and operational profile used by an agent, IDE, runtime, or workflow.
 
-```bash
-# Docker deployment
-ossa export creative-agent-naming.ossa.yaml --platform docker --output ./docker-deploy
+**Tool** — A callable capability declared by the manifest and enforced by the runtime or policy layer.
 
-# Kubernetes with Kustomize
-ossa export creative-agent-naming.ossa.yaml --platform kubernetes --output ./k8s-deploy
+**Workflow** — A deterministic or semi-deterministic process composed from agents, tools, events, or external systems.
 
-# 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
-```
+**Registry** — A discoverable index of agent manifests and related metadata.
 
-### Advanced Options
+**Policy Binding** — A link between an agent/action/resource and an external policy authority such as Cedar or ContractPlane.
 
-```bash
-# Dry run (preview without creating files)
-ossa export creative-agent-naming.ossa.yaml --platform docker --dry-run
-
-# Verbose output for debugging
-ossa export creative-agent-naming.ossa.yaml --platform kubernetes --verbose
-
-# 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
-```
-
-### Migrating Between Versions
-
-Upgrade manifests to the latest spec version:
-
-```bash
-# Migrate from older version to current
-ossa migrate agent.ossa.yaml --to 0.5.1
-
-# List available migration paths
-ossa migrate --list
-```
-
-### TypeScript SDK Usage
-
-Use OSSA programmatically in your TypeScript projects:
-
-```typescript
-import { ValidationService, ManifestRepository } from '@bluefly/openstandardagents';
-
-// 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);
-}
-```
-
-## Production Status (v0.5.1)
-
-### Production-Ready (Tested & Documented)
-
-**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
-
-**Production Platform Exports** (see `ossa export --list-platforms` for the live matrix):
-- `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
-
-**Skills Pipeline** (Current in v0.5.1):
-- `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)
-
-**TypeScript SDK**:
-- Validation service (`@bluefly/openstandardagents/validation`)
-- Type definitions (`@bluefly/openstandardagents/types`)
-- JSON Schema access (`@bluefly/openstandardagents/schema`)
-
-### Beta (Functional but needs testing)
-
-- `ossa agents-local` - Local `.agents/` folder management
-- `ossa agents-md` - Generate, validate, sync [agents.md](https://agents.md) files (standard: [agentsmd/agents.md](https://github.com/agentsmd/agents.md)); customize via wizard step or `ossa agents-md generate|validate|sync`
-- Export to: `crewai`, `drupal`, `claude-code`, `cursor`, `warp`, `anthropic`
-- Anthropic runtime adapter uses official `@anthropic-ai/sdk`
-
-### GitLab Agent Examples (Fully Implemented)
-
-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
-
-### 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
-
-### Alpha (Experimental)
-
-- 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)
-
-### Planned
-
-- A2A Agent Card import (P1-1)
-- Batch skill generation (P1-2)
-- Skill quality scoring (P1-3)
-- Full GitLab Catalog push/pull with API integration
-
-## How It Works
-
-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.
-
-**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.)
-
-OSSA complements MCP and A2A by adding the packaging and deployment layer they don't provide.
-
-### Manifest Format
+## Minimal Manifest Example
 
 ```yaml
-apiVersion: ossa/v0.5.1
+apiVersion: ossa/v0.5
 kind: Agent
 metadata:
-  name: code-reviewer
+  name: accessibility-reviewer
+  namespace: blueflyio
   version: 1.0.0
-  description: AI-powered code review agent
+  uuid: 7e3f4b8d-2c91-4a6e-b015-9f8d3e2c7a64
 spec:
-  role: |
-    You are a code review agent that analyzes pull requests
-    for bugs, security issues, and style violations.
-  llm:
-    provider: anthropic
-    model: claude-sonnet-4-5-20250929
-    temperature: 0.3
-    maxTokens: 4096
+  role: accessibility-reviewer
+  description: Reviews content and rendered pages for accessibility issues.
   tools:
-    - name: read_file
-      description: Read file contents
-    - name: create_comment
-      description: Post review comment
-  autonomy:
-    level: supervised
+    - name: drupal_render_api
+      type: mcp
+    - name: axe_core_scanner
+      type: external
+  capabilities:
+    - name: scan_page_accessibility
+    - name: generate_remediation_plan
+  governance:
+    cedar_policy_pack: accessibility-reviewer-v1
+    trust_tier: T2
+    evidence_required: true
+  discovery:
+    duadp: true
 ```
 
-#### Team Manifest Example
+## Validation
 
-```yaml
-apiVersion: ossa/v0.5.1
-kind: Agent
-metadata:
-  name: dev-team
-  version: 1.0.0
-spec:
-  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
-```
-
-### Export Platforms
+### Programmatic
 
-Export generates complete, runnable project scaffolds:
-
-```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 |
-| `agentscope` | alpha | 10 files | agentscope | AgentScope ReAct assistant for Drupal AI Agents |
-
-Every export includes `agent.ossa.yaml` (the source manifest) for provenance.
-
-### Validation
-
-```bash
-# Basic validation against JSON Schema
-ossa validate agent.ossa.yaml
+```typescript
+import { validateManifestFile } from '@bluefly/openstandardagents';
 
-# Strict mode (warnings become errors)
-ossa validate agent.ossa.yaml --strict
+const result = await validateManifestFile('agent.ossa.yaml');
+if (!result.valid) {
+  console.error(result.errors);
+  process.exit(1);
+}
 ```
 
-### Interactive Wizard
+### CLI
 
 ```bash
-ossa wizard -o agent.ossa.yaml
+ossa validate ./agent.ossa.yaml
 ```
 
-Walks through: identity, role, LLM config, tools, autonomy level, resources, taxonomy, compliance, and token efficiency settings.
+## Exports
 
-## TypeScript SDK
+| Export | Purpose |
+|--------|---------|
+| `@bluefly/openstandardagents` | Validator entrypoint |
+| `@bluefly/openstandardagents/schema` | v0.5 agent schema |
+| `@bluefly/openstandardagents/schema/v0.5` | Explicit v0.5 agent schema |
+| `@bluefly/openstandardagents/schema/workflow` | Workflow schema |
+| `@bluefly/openstandardagents/schema/registry` | Registry schema |
+| `@bluefly/openstandardagents/schema/policy-binding` | Policy binding schema |
+| `@bluefly/openstandardagents/openapi/invocation` | Invocation OpenAPI contract |
+| `@bluefly/openstandardagents/well-known` | OSSA well-known discovery document |
+| `@bluefly/openstandardagents/validation` | Validation utilities (alias) |
 
-```typescript
-import { validateManifest } from '@bluefly/openstandardagents/validation';
-import type { OssaAgent } from '@bluefly/openstandardagents/types';
-
-const agent: OssaAgent = {
-  apiVersion: 'ossa/v0.5.1',
-  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');
-```
+## Project Ecosystem
 
-## Spec Features
+| Project | Role |
+|---------|------|
+| [openstandardagents](https://gitlab.com/blueflyio/ossa/openstandardagents) | OSSA schemas, CLI, validator, reference contracts |
+| [duadp](https://gitlab.com/blueflyio/duadp/duadp) | Federated discovery and agent registry resolution |
+| [agents](https://gitlab.com/blueflyio/agentictools/agents) | Canonical Bluefly agent manifests, including @blu |
+| [skills](https://gitlab.com/blueflyio/agentictools/skills) | Reusable skill packages referenced by agents |
+| [compliance-engine](https://gitlab.com/blueflyio/agent-platform/services/compliance-engine) | Cedar policy evaluation, evidence, and OSSA validation API |
+| [cedar-policies](https://gitlab.com/blueflyio/cedar-policies) | Cedar policy source (product IP) |
+| [ai_agents_ossa](https://gitlab.com/blueflyio/agent-platform/drupal/ai_agents_ossa) | Drupal bridge between OSSA manifests and AI Agents |
+| [api_normalization](https://gitlab.com/blueflyio/agent-platform/drupal/api_normalization) | API/OpenAPI normalization layer |
+| [kb_cache](https://gitlab.com/blueflyio/agent-platform/drupal/kb_cache) | Contextual memory and retrieval engine |
+| [ContextControl.ai](https://gitlab.com/blueflyio/contextcontrol.ai) | Governed Drupal-based context/control plane |
+| [blu-cli](https://gitlab.com/blueflyio/blu/blu-cli) | Governed Bluefly operator CLI |
+| [context-cli](https://gitlab.com/blueflyio/contextcontrol.ai/context-cli) | ContextControl/knowledge workflow CLI |
+| [gitlab_components](https://gitlab.com/blueflyio/gitlab_components) | Reusable CI/CD pipeline components |
+| [ossa-studio](https://gitlab.com/blueflyio/ossa/lab/ossa-studio) | Visual/modeling surface for OSSA authoring |
 
-The OSSA v0.5.0 schema supports these optional sections:
+## Relationship to DUADP
 
-- **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
+DUADP handles discovery. OSSA defines what is discovered.
 
-All fields are optional. A minimal manifest needs only `apiVersion`, `kind`, `metadata.name`, and `spec.role`.
-
-## How OSSA Complements MCP and A2A
-
-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.5.1
-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 answers: What is this agent? What can it do? What tools does it declare? What policy bindings apply? What schema validates it?
 
-OSSA doesn't compete with MCP or A2A - it makes them deployable.
+DUADP answers: Where is the agent card? How is it resolved? How is it revoked? How is it discovered across organizations?
 
-## CLI Commands
+## Relationship to ContractPlane and Cedar
 
-**Core workflow** (shown in `ossa --help`):
-- `ossa wizard` - Interactive manifest creation (full flow)
-- `ossa init [name]` - Create new OSSA manifest (interactive or `-y`)
-- `ossa validate [path]` - Validate against OSSA schema (optional `--platform`)
-- `ossa export [manifest]` - Export to platform (`--platform`, `-o`, `--perfect-agent`, etc.)
-- `ossa lint` - Lint manifests
-- `ossa diff` - Diff manifests
-- `ossa build` - Validate + build for platform
-- `ossa migrate` - Migrate manifest to newer OSSA version
+OSSA declares governance metadata and policy bindings. It does not evaluate policy.
 
-**Agent management:** `ossa agents create|list|get`, `ossa agents-local`, `ossa agent-card generate|validate`, `ossa generate-gaid`
+ContractPlane and Cedar are policy/evidence enforcement layers that consume OSSA manifests and evaluate actions before runtime execution. Cedar policies are authored in `cedar-policies` and evaluated by `compliance-engine`.
 
-**Development:** `ossa generate` (agent|types|zod|manifests|vscode|openapi|all|list|validate|sync), `ossa dev`, `ossa serve`, `ossa run`, `ossa test`
+## Relationship to Drupal
 
-**Distribution:** `ossa publish`, `ossa install`, `ossa update`, `ossa search`
+Drupal is one implementation surface for OSSA-governed agents. OSSA remains runtime-agnostic. Drupal is an implementation target, not a dependency of the standard.
 
-**Deployment:** `ossa deploy`, `ossa status`, `ossa rollback`, `ossa stop`
+Relevant Drupal modules: `ai`, `ai_agents`, `ai_agents_ossa`, `tool`, `mcp`, `orchestration`, `eca`, `agui`, `api_normalization`, `ai_context`, `kb_cache`.
 
-**Documentation from manifest:** `ossa agents-md` (generate|validate|sync|discover|maintain), `ossa llms-txt` (generate|validate|sync), `ossa docs`
+## Why OSSA + DUADP
 
-**Skills and templates:** `ossa skills` (list|generate|sync|validate|research|generate-enhanced|export), `ossa template` (list|show|create|validate)
+AI agents need the same foundational infrastructure the internet has: identity, discovery, and governance.
 
-**Tools and capabilities:** `ossa tool` (create|validate|list), `ossa capability`, `ossa manifest`
+```
+Identity   (OSSA)  — Agent DID, signed manifests, Cedar policy bindings
+Discovery  (DUADP) — Federated DNS + WebFinger, gossip, trust-tier gating
+Execution  (yours) — Kubernetes, Claude, LangChain, Drupal, or any runtime
+```
 
-**Compliance:** `ossa conformance`, `ossa compliance`, `ossa governance`, `ossa contract`
+OSSA defines the agent. DUADP discovers it. Your runtime executes it.
 
-**Workspace (two-tier / UADP-style):** `ossa workspace init|list|discover`, `ossa workspace policy list|check <project>`, `ossa workspace sync`, `ossa workspace publish --registry-url <url>` (POST discovery to a registry API, e.g. mesh)
+## Development
 
-**Production commands** (examples):
 ```bash
-ossa wizard -o agent.ossa.yaml
-ossa validate agent.ossa.yaml
-ossa export agent.ossa.yaml --platform docker --output ./docker-deploy
-ossa export --list-platforms
-ossa lint agent.ossa.yaml
-ossa diff old.ossa.yaml new.ossa.yaml
-ossa migrate agent.ossa.yaml --to 0.5.1
-ossa generate-gaid agent.ossa.yaml
-ossa export agent.ossa.yaml --perfect-agent
-ossa export agent.ossa.yaml --include-agents-md --include-team --include-evals
+pnpm install
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm validate
+pnpm gen:check
+pnpm publint
 ```
 
-**Skills pipeline:**
-```bash
-ossa skills research "drupal" --json
-ossa skills generate agent.ossa.yaml
-ossa skills generate spec.yaml --format oracle
-ossa skills generate AGENTS.md --format agents-md
-ossa skills export ./skill-dir [--install|--publish]
-ossa skills list
-ossa skills validate ./SKILL.md
-ossa skills sync
-```
+Full CI-equivalent gate:
 
-**OSSA MCP Server** (10 tools, 5 resources, 4 prompts — stdio transport):
-
-Run `npx ossa-mcp` or add to your MCP client config:
-```json
-{
-  "mcpServers": {
-    "ossa": {
-      "command": "npx",
-      "args": ["ossa-mcp"]
-    }
-  }
-}
+```bash
+pnpm ci:validate
 ```
 
-**Tools:** `ossa_validate`, `ossa_scaffold`, `ossa_generate`, `ossa_publish`, `ossa_list`, `ossa_inspect`, `ossa_convert` (11+ platforms with real SDK refs), `ossa_workspace` (init/discover/status), `ossa_diff` (breaking change detection), `ossa_migrate`.
-
-**Resources:** `ossa://schema/v0.4/agent`, `ossa://template/minimal`, `ossa://template/full`, `ossa://guide/mcp-ossa-a2a`, `ossa://platforms/supported`.
-
-**Prompts:** `create-agent`, `convert-for-platform`, `explain-manifest`, `what-is-ossa`.
-
-**Convert targets:** kagent (v1alpha2), docker, openai, anthropic, langchain, crewai, autogen, semantic-kernel, gitlab-duo, agent-card (universal cross-platform JSON with 12 platform adapters — each with `sdk` npm/pip refs, `config`, and `usage` code snippet).
+Runs install, build, typecheck, vitest conformance, schema validation, OpenAPI validation, generated-code checks, and package dry-run. All jobs are fail-closed.
 
-See [MCP Server Guide](docs/guides/mcp-server.md) for full documentation. Skill: `examples/agent-skills/ossa-agent-authoring/SKILL.md`.
+## Conformance Targets
 
-**Beta:** `ossa agents-local`, `ossa agents-md`, `ossa llms-txt`
+Tests validate the canonical platform agent at `WORKING_DEMOs/agents/agents/@blu/agent.ossa.yaml` when `OSSA_AGENTS_ROOT` points at that repo (default relative path from this checkout). Toy example directories are not shipped in this package.
 
-Use `ossa --help` for the full list.
+## Release Policy
 
-## Discovery and registry
+- Release branches are protected.
+- Release artifacts must pass build, typecheck, tests, schema validation, OpenAPI validation, generated-code checks, and package dry-run.
+- npm versions are immutable after publish.
+- Package contents must be allowlisted through `files`.
+- Do not publish from a dirty working tree.
+- Do not publish from a generated temporary tree unless the package identity and tarball contents are verified.
 
-OSSA defines agents; a **registry** is where agents are listed and queried. You can keep discovery local (workspace only) or publish to a shared registry API.
+## npm State
 
-- **Local:** Run `ossa workspace discover` to scan `.agents/` and update `.agents-workspace/registry/index.yaml`. Use `ossa workspace list` to see agents in this repo.
-- **Publish to a registry:** Run `ossa workspace publish --registry-url <base-url>` to POST the same discovery payload to `<base-url>/api/v1/discovery`. Any service that implements that contract (e.g. a mesh discovery API) can store and serve it; others can GET the same URL to list all published agents.
-- **CI:** In GitLab CI, include the agents-ci template and set `MESH_URL` (or `AGENT_REGISTRY_URL`). The discover job will then POST to that URL so each pipeline run updates the registry.
-- **Contract:** The registry API is a simple HTTP contract: **POST** `/api/v1/discovery` with body `{ source_id, workspace: { name, scanned_at }, projects: [{ name, path, agents }] }` to publish; **GET** `/api/v1/discovery` returns aggregated sources and projects. OSSA and other compatible tools use this same shape.
+`0.5.1` is the current stable release. `0.5.2` is prepared and in pre-release validation.
 
-See [Agents workspace and registry](docs/getting-started/agents-workspace-registry.md) and [Discovery and registry](docs/wiki/Discovery-and-Registry.md) for details. 30+ additional commands (e.g. quickstart, scaffold, import, enhance, registry, migrate-batch, langchain, langflow, workspace, taxonomy, knowledge, audit) are available; run `ossa <command> --help` for any command.
+`0.5.3` was accidentally published during recovery and is **deprecated**. Do not use it.
 
-## Honest Status Reporting
+## Contributing
 
-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
+Use GitLab issues and merge requests against the source of truth:
 
-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.
+https://gitlab.com/blueflyio/ossa/openstandardagents
 
-## Production Options
-
-All mutation commands support:
+Before submitting:
 
 ```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
+pnpm ci:validate
 ```
 
-## Documentation
-
-- [OSSA CLI Reference](./docs/wiki/OSSA-CLI-Reference.md) - Full CLI command and export-platform reference (canonical for wikis)
-- [Discovery and registry](./docs/wiki/Discovery-and-Registry.md) - Workspace discover, publish to registry API, CI, and contract
-- [Agents workspace and registry](./docs/getting-started/agents-workspace-registry.md) - `.agents-workspace/` layout, sources, MCP/A2A
-- [CHANGELOG](./CHANGELOG.md) - Release history
-- [Examples](./examples) - Sample manifests
-- [JSON Schema](./spec/v0.5/agent.schema.json) - Full spec
-- [GitLab](https://gitlab.com/blueflyio/ossa/openstandardagents) - Source
-- [GitHub Mirror](https://github.com/blueflyio/openstandardagents)
-
-**Wiki publishing:** Wiki pages (OSSA-CLI-Reference, Discovery-and-Registry) are published from this repo. Run `npm run wiki:publish` (requires `GITLAB_TOKEN` or `GITLAB_PUSH_TOKEN`). Manifest: `.gitlab/wiki-publish-manifest.json`. To add a page, add an entry there and run the same command. No BuildKit dependency.
-
 ## License
 
-Apache-2.0 - see [LICENSE](./LICENSE)
+Apache-2.0. See [LICENSE](LICENSE).