@bluefly/openstandardagents 0.4.8 → 0.5.0

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@bluefly/openstandardagents",
-  "version": "0.4.8",
+  "version": "0.5.0",
   "exports": {
-    "./schema": "./spec/v0.4/agent.schema.json",
+    "./schema": "./spec/v0.5/agent.schema.json",
     "./schema/v0.4": "./spec/v0.4/agent.schema.json",
     "./schema/v0.4.1": "./spec/v0.4/agent.schema.json",
+    "./schema/v0.5": "./spec/v0.5/agent.schema.json",
+    "./schema/v0.5.0": "./spec/v0.5/agent.schema.json",
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
@@ -46,7 +48,7 @@
       "import": "./dist/services/agent-card-generator.js",
       "require": "./dist/services/agent-card-generator.js"
     },
-    "./agent-card-schema": "./spec/v0.4/agent-card.schema.json",
+    "./agent-card-schema": "./spec/v0.5/agent-card.schema.json",
     "./sdk": {
       "types": "./dist/sdk.d.ts",
       "import": "./dist/sdk.js",
@@ -141,113 +143,21 @@
     "url": "https://gitlab.com/blueflyio/ossa/openstandardagents/-/issues"
   },
   "homepage": "https://openstandardagents.org",
-  "scripts": {
-    "// ─────────────────────────────────────────────────────────────────────────────": "",
-    "// BUILD & DEVELOPMENT": "",
-    "mcp": "node dist/mcp-server/index.js",
-    "prebuild": "npm run docs:process",
-    "build": "tsc && npm run build:assets",
-    "build:assets": "cp -r spec dist/ && cp package.json .version.json dist/",
-    "build:clean": "npm run clean && npm run build",
-    "dev": "tsc --watch",
-    "clean": "rm -rf dist coverage .tsbuildinfo",
-    "// TESTING": "",
-    "test": "jest",
-    "test:unit": "jest tests/unit --forceExit",
-    "test:integration": "jest tests/integration",
-    "test:e2e": "jest tests/e2e --passWithNoTests",
-    "test:smoke": "jest tests/e2e --testPathPattern=smoke.spec.ts --runInBand --forceExit",
-    "test:smoke:cli": "jest tests/e2e/cli.smoke.spec.ts",
-    "test:smoke:npm-pack": "jest tests/e2e/npm-pack.smoke.spec.ts",
-    "test:smoke:schema": "jest tests/e2e/schema-coverage.smoke.spec.ts",
-    "test:coverage": "jest --coverage",
-    "test:mutation": "stryker run",
-    "test:mutation:ci": "stryker run --logLevel error",
-    "test:watch": "jest --watch",
-    "test:ci": "jest --ci --coverage --reporters=default --reporters=jest-junit",
-    "test:mcp": "vitest run src/mcp-server/__tests__/mcp-server.spec.ts",
-    "test:mcp:watch": "vitest watch src/mcp-server/__tests__/mcp-server.spec.ts",
-    "ci:validate": "npm run build:clean && npm run quality && npm run test:unit && npm run test:smoke && npm run validate:all",
-    "ci:validate:fast": "npm run typecheck && npm run test:unit && npm run validate:schema",
-    "// CODE QUALITY": "",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src tests --ext .ts",
-    "lint:fix": "eslint src tests --ext .ts --fix",
-    "format": "prettier --write 'src/**/*.ts' 'tests/**/*.ts'",
-    "format:check": "prettier --check 'src/**/*.ts' 'tests/**/*.ts'",
-    "quality": "npm run typecheck && npm run format:check",
-    "quality:fix": "npm run format",
-    "// VALIDATION": "",
-    "validate": "npm run validate:no-symlinks && npm run validate:schema && npm run validate:openapi && npm run validate:examples",
-    "validate:all": "npm run validate && npm run validate:sdks",
-    "validate:sdks": "npm run validate:sdk:typescript && npm run validate:sdk:python",
-    "validate:sdk:typescript": "cd src/sdks/typescript && npm install && npm run build && npm run typecheck",
-    "validate:sdk:python": "cd src/sdks/python && python -m pip install --quiet -e . && python -m pytest tests/ -v || true",
-    "validate:schema": "npx ajv-cli compile -s $(node -p \"require('./.version.json').spec_path\")/$(node -p \"require('./.version.json').schema_file\") -r $(node -p \"require('./.version.json').spec_path\")/extensions/kagent/kagent.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/mcp/mcp.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/a2a/a2a.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/langchain/langchain.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/langgraph/langgraph.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/ag2/ag2.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/crewai/crewai.schema.json --strict=false --allow-union-types",
-    "validate:manifest": "npx ajv-cli validate -s $(node -p \"require('./.version.json').spec_path\")/$(node -p \"require('./.version.json').schema_file\") --strict=false --allow-union-types -d",
-    "validate:examples": "find examples \\( -name '*.ossa.yaml' -o -name '*.ossa.yml' \\) | grep -v 'swarm-to-ossa' | head -20 | xargs -I {} npm run validate:manifest -- {} || true",
-    "validate:versions": "tsx src/tools/validate-versions.ts",
-    "fix:versions": "tsx src/tools/fix-versions.ts",
-    "validate:power": "tsx src/tools/validation/validate-ossa.ts",
-    "validate:openapi": "spectral lint openapi/**/*.yaml --ruleset .spectral.yml 2>/dev/null || spectral lint openapi/**/*.yaml",
-    "validate:openapi:ossa": "tsx src/tools/validation/validate-openapi-extensions.ts",
-    "validate:no-symlinks": "tsx src/tools/validate-no-symlinks.ts",
-    "// VERSION MANAGEMENT (via ossa-dev CLI - single source of truth)": "",
-    "version:release": "tsx src/dev-cli/src/index.ts version release",
-    "version:validate": "tsx src/dev-cli/src/index.ts version validate",
-    "version:sync": "tsx src/dev-cli/src/index.ts version sync",
-    "version:detect": "tsx src/dev-cli/src/index.ts version detect",
-    "version:audit": "tsx src/dev-cli/src/index.ts version audit",
-    "// INFRASTRUCTURE (deploy tooling out of scope for OSSA)": "",
-    "env:list": "tsx src/dev-cli/src/index.ts env-cleanup --list",
-    "env:cleanup": "tsx src/dev-cli/src/index.ts env-cleanup --stop-stuck",
-    "// DOCUMENTATION": "",
-    "wiki:publish": "node .gitlab/wiki-publish.cjs",
-    "docs:process": "tsx src/tools/docs/process-doc-templates.ts",
-    "docs:check": "test -f README.md && test -f CHANGELOG.md",
-    "docs:generate": "tsx src/tools/docs/generate-api-docs.ts && tsx src/tools/docs/generate-cli-docs.ts && tsx src/tools/docs/generate-schema-docs.ts && tsx src/tools/docs/generate-examples-docs.ts && tsx src/tools/generators/generate-agents-catalog.ts && tsx src/tools/docs/generate-types-docs.ts && tsx src/tools/docs/generate-errors-docs.ts && tsx src/tools/docs/generate-config-docs.ts && tsx src/tools/docs/lowercase-docs.ts",
-    "// CODE GENERATION": "",
-    "gen:types": "tsx src/tools/generators/gen-types.ts",
-    "gen:zod": "tsx src/tools/generators/gen-zod.ts",
-    "gen:all": "npm run gen:types && npm run gen:zod",
-    "gen:current:schema": "tsx src/tools/generators/merge-v$(node -p \"require('./.version.json').current\")-schema.ts",
-    "// SYNC & COMPLIANCE": "",
-    "sync:pr": "tsx src/cli/commands/github-sync.command.ts pr",
-    "sync:batch": "tsx src/cli/commands/github-sync.command.ts batch",
-    "sync:list": "tsx src/cli/commands/github-sync.command.ts list",
-    "migrate:batch": "node dist/cli/index.js migrate-batch",
-    "compliance:audit": "tsx src/tools/compliance-audit.ts",
-    "verify:npm-auth": "tsx src/tools/verify-npm-auth.ts",
-    "audit:mrs": "tsx src/tools/audit-mrs.ts",
-    "// MAINTENANCE": "",
-    "fix:schemas": "node src/tools/generators/fix-schema-formats.js",
-    "hooks:install": "lefthook install",
-    "hooks:uninstall": "lefthook uninstall",
-    "prepare": "lefthook install || true",
-    "postinstall": "node bin/postinstall || true",
-    "// RELEASE & PUBLISH": "",
-    "prepublishOnly": "publint && npm run test:unit && npm run build",
-    "validate:deps": "depcheck --ignore-dirs=examples --ignores='@anthropic-ai/claude-agent-sdk,@langchain/openai,@openai/agents,@temporalio/activity,@temporalio/workflow,pino-pretty,readline,@types/*,ts-jest,eslint*,prettier*,lefthook,jest*,vitest,semantic-release*,@semantic-release/*,keep-a-changelog,jest-junit,publint,conventional-changelog-conventionalcommits,ajv-cli,json-schema-to-typescript,json-schema-to-zod,ts-node,@playwright/test,@langchain/anthropic,@langchain/core,langchain'",
-    "validate:package": "publint",
-    "publish:dry-run": "npm publish --dry-run",
-    "release:check": "npm run typecheck && npm run test:unit && npm run validate:schema && publint",
-    "release:semantic": "npx semantic-release",
-    "release:semantic:dry": "npx semantic-release --dry-run"
-  },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.50",
     "@anthropic-ai/sdk": "^0.71.0",
     "@aws-sdk/client-bedrock-runtime": "^3.955.0",
+    "@cedar-policy/cedar-wasm": "^4.9.1",
     "@gitbeaker/node": "^35.8.1",
     "@gitbeaker/rest": "^43.8.0",
     "@google/generative-ai": "^0.21.0",
     "@langchain/anthropic": "^0.3.10",
     "@langchain/core": "^0.3.29",
     "@langchain/openai": "^0.3.17",
-    "@modelcontextprotocol/sdk": "^0.6.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "@noble/ed25519": "^2.3.0",
     "@octokit/rest": "^20.0.0",
-    "@openai/agents": "^0.4.6",
+    "@openai/agents": "^0.7.1",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/exporter-jaeger": "^1.28.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.211.0",
@@ -260,7 +170,7 @@
     "@opentelemetry/sdk-metrics": "^2.5.0",
     "@opentelemetry/sdk-node": "^0.54.0",
     "@opentelemetry/sdk-trace-base": "^1.28.0",
-    "@qdrant/js-client-rest": "^1.9.0",
+    "@qdrant/js-client-rest": "^1.17.0",
     "@temporalio/activity": "^1.11.3",
     "@temporalio/workflow": "^1.11.3",
     "@types/tar": "^6.1.13",
@@ -293,7 +203,7 @@
     "readline": "^1.3.0",
     "reflect-metadata": "^0.2.2",
     "semver": "^7.7.3",
-    "tar": "^7.5.3",
+    "tar": "^7.5.11",
     "uuid": "^11.0.5",
     "web-did-resolver": "^2.0.32",
     "ws": "^8.19.0",
@@ -301,6 +211,7 @@
     "zod": "^4.1.11"
   },
   "devDependencies": {
+    "@bluefly/duadp": "^0.1.4",
     "@jest/globals": "^29.7.0",
     "@octokit/rest": "^22.0.1",
     "@semantic-release/changelog": "^6.0.3",
@@ -342,12 +253,8 @@
     "vitest": "^2.1.8"
   },
   "optionalDependencies": {
-    "nodemailer": "^6.9.0"
+    "nodemailer": "^8.0.2"
   },
-  "bundledDependencies": [
-    "ajv",
-    "ajv-formats"
-  ],
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"
@@ -356,8 +263,106 @@
     "node": "22.19.0",
     "npm": "11.10.0"
   },
-  "bundleDependencies": [
-    "ajv",
-    "ajv-formats"
-  ]
-}
+  "overrides": {
+    "@hono/node-server": "^1.19.10",
+    "express-rate-limit": "^8.2.2",
+    "hono": "^4.12.7",
+    "langsmith": "^0.4.6",
+    "fast-xml-parser": "^5.3.8",
+    "@langchain/anthropic": {
+      "fast-xml-parser": "^4.5.4"
+    }
+  },
+  "scripts": {
+    "// ─────────────────────────────────────────────────────────────────────────────": "",
+    "// BUILD & DEVELOPMENT": "",
+    "mcp": "node dist/mcp-server/index.js",
+    "prebuild": "npm run docs:process",
+    "build": "tsc && npm run build:assets",
+    "build:assets": "cp -r spec dist/ && cp package.json .version.json dist/",
+    "build:clean": "npm run clean && npm run build",
+    "dev": "tsc --watch",
+    "clean": "node -e \"const fs=require('node:fs'); ['dist','coverage','.tsbuildinfo'].forEach((p)=>fs.rmSync(p,{recursive:true,force:true}))\"",
+    "// TESTING": "",
+    "pretest": "npm run build",
+    "test": "jest",
+    "test:unit": "jest tests/unit --forceExit",
+    "test:integration": "jest tests/integration",
+    "test:e2e": "jest tests/e2e --passWithNoTests",
+    "test:smoke": "jest tests/e2e --testPathPattern=smoke.spec.ts --runInBand --forceExit",
+    "test:smoke:cli": "jest tests/e2e/cli.smoke.spec.ts",
+    "test:smoke:npm-pack": "jest tests/e2e/npm-pack.smoke.spec.ts",
+    "test:smoke:schema": "jest tests/e2e/schema-coverage.smoke.spec.ts",
+    "test:coverage": "jest --coverage",
+    "test:mutation": "stryker run",
+    "test:mutation:ci": "stryker run --logLevel error",
+    "test:watch": "jest --watch",
+    "test:ci": "jest --ci --coverage --reporters=default --reporters=jest-junit",
+    "test:mcp": "vitest run src/mcp-server/__tests__/mcp-server.spec.ts",
+    "test:mcp:watch": "vitest watch src/mcp-server/__tests__/mcp-server.spec.ts",
+    "ci:validate": "npm run build:clean && npm run quality && npm run test:unit && npm run test:smoke && npm run validate:all",
+    "ci:validate:fast": "npm run typecheck && npm run test:unit && npm run validate:schema",
+    "// CODE QUALITY": "",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests --ext .ts",
+    "lint:fix": "eslint src tests --ext .ts --fix",
+    "format": "prettier --write 'src/**/*.ts' 'tests/**/*.ts'",
+    "format:check": "prettier --check 'src/**/*.ts' 'tests/**/*.ts'",
+    "quality": "npm run typecheck && npm run format:check",
+    "quality:fix": "npm run format",
+    "// VALIDATION": "",
+    "validate": "npm run validate:no-symlinks && npm run validate:schema && npm run validate:openapi && npm run validate:examples",
+    "validate:all": "npm run validate && npm run validate:sdks",
+    "validate:sdks": "npm run validate:sdk:typescript && npm run validate:sdk:python",
+    "validate:sdk:typescript": "cd src/sdks/typescript && npm install && npm run build && npm run typecheck",
+    "validate:sdk:python": "cd src/sdks/python && python -m pip install --quiet -e . && python -m pytest tests/ -v || true",
+    "validate:schema": "npx ajv-cli compile -s $(node -p \"require('./.version.json').spec_path\")/$(node -p \"require('./.version.json').schema_file\") -r $(node -p \"require('./.version.json').spec_path\")/extensions/kagent/kagent.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/mcp/mcp.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/a2a/a2a.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/langchain/langchain.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/langgraph/langgraph.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/ag2/ag2.schema.json -r $(node -p \"require('./.version.json').spec_path\")/extensions/crewai/crewai.schema.json --strict=false --allow-union-types",
+    "validate:manifest": "npx ajv-cli validate -s $(node -p \"require('./.version.json').spec_path\")/$(node -p \"require('./.version.json').schema_file\") --strict=false --allow-union-types -d",
+    "validate:examples": "tsx src/tools/validation/validate-examples.ts",
+    "validate:versions": "tsx src/tools/validate-versions.ts",
+    "fix:versions": "tsx src/tools/fix-versions.ts",
+    "validate:power": "tsx src/tools/validation/validate-ossa.ts",
+    "validate:openapi": "spectral lint openapi/**/*.yaml --ruleset .spectral.yml 2>/dev/null || spectral lint openapi/**/*.yaml",
+    "validate:openapi:ossa": "tsx src/tools/validation/validate-openapi-extensions.ts",
+    "validate:no-symlinks": "tsx src/tools/validate-no-symlinks.ts",
+    "// VERSION MANAGEMENT (via ossa-dev CLI - single source of truth)": "",
+    "version:release": "tsx src/dev-cli/src/index.ts version release",
+    "version:validate": "tsx src/dev-cli/src/index.ts version validate",
+    "version:sync": "tsx src/dev-cli/src/index.ts version sync",
+    "version:detect": "tsx src/dev-cli/src/index.ts version detect",
+    "version:audit": "tsx src/dev-cli/src/index.ts version audit",
+    "// INFRASTRUCTURE (deploy tooling out of scope for OSSA)": "",
+    "env:list": "tsx src/dev-cli/src/index.ts env-cleanup --list",
+    "env:cleanup": "tsx src/dev-cli/src/index.ts env-cleanup --stop-stuck",
+    "// DOCUMENTATION": "",
+    "wiki:publish": "node .gitlab/wiki-publish.cjs",
+    "docs:process": "tsx src/tools/docs/process-doc-templates.ts",
+    "docs:check": "test -f README.md && test -f CHANGELOG.md",
+    "docs:generate": "tsx src/tools/docs/generate-api-docs.ts && tsx src/tools/docs/generate-cli-docs.ts && tsx src/tools/docs/generate-schema-docs.ts && tsx src/tools/docs/generate-examples-docs.ts && tsx src/tools/generators/generate-agents-catalog.ts && tsx src/tools/docs/generate-types-docs.ts && tsx src/tools/docs/generate-errors-docs.ts && tsx src/tools/docs/generate-config-docs.ts && tsx src/tools/docs/lowercase-docs.ts",
+    "// CODE GENERATION": "",
+    "gen:types": "tsx src/tools/generators/gen-types.ts",
+    "gen:zod": "tsx src/tools/generators/gen-zod.ts",
+    "gen:all": "npm run gen:types && npm run gen:zod",
+    "gen:current:schema": "tsx src/tools/generators/merge-v$(node -p \"require('./.version.json').current\")-schema.ts",
+    "// SYNC & COMPLIANCE": "",
+    "sync:pr": "tsx src/cli/commands/github-sync.command.ts pr",
+    "sync:batch": "tsx src/cli/commands/github-sync.command.ts batch",
+    "sync:list": "tsx src/cli/commands/github-sync.command.ts list",
+    "migrate:batch": "node dist/cli/index.js migrate-batch",
+    "compliance:audit": "tsx src/tools/compliance-audit.ts",
+    "verify:npm-auth": "tsx src/tools/verify-npm-auth.ts",
+    "audit:mrs": "tsx src/tools/audit-mrs.ts",
+    "// MAINTENANCE": "",
+    "fix:schemas": "node src/tools/generators/fix-schema-formats.js",
+    "hooks:install": "lefthook install",
+    "hooks:uninstall": "lefthook uninstall",
+    "postinstall": "node bin/postinstall || true",
+    "// RELEASE & PUBLISH": "",
+    "validate:deps": "depcheck --ignore-dirs=examples --ignores='@anthropic-ai/claude-agent-sdk,@langchain/openai,@openai/agents,@temporalio/activity,@temporalio/workflow,pino-pretty,readline,@types/*,ts-jest,eslint*,prettier*,lefthook,jest*,vitest,semantic-release*,@semantic-release/*,keep-a-changelog,jest-junit,publint,conventional-changelog-conventionalcommits,ajv-cli,json-schema-to-typescript,json-schema-to-zod,ts-node,@playwright/test,@langchain/anthropic,@langchain/core,langchain'",
+    "validate:package": "publint",
+    "publish:dry-run": "npm publish --dry-run",
+    "release:check": "npm run typecheck && npm run test:unit && npm run validate:schema && publint",
+    "release:semantic": "npx semantic-release",
+    "release:semantic:dry": "npx semantic-release --dry-run"
+  }
+}

package/spec/extensions/role-manifest.md

@@ -0,0 +1,188 @@
+# OSSA Role Manifest Extension
+
+**Version:** 0.5.0
+**Status:** Draft
+**Last Updated:** 2026-03-13
+
+## Overview
+
+This extension introduces `kind: Role` as a new OSSA manifest type. Roles define **behavioral overlays** for IDE and CLI agents (Claude Code, Cursor, Codex CLI, etc.) — configuring instructions, tool access, hooks, MCP server connections, and activation conditions.
+
+### Role vs Agent
+
+| Aspect | `kind: Agent` | `kind: Role` |
+|--------|--------------|--------------|
+| **Purpose** | Autonomous agentic loop | Operator context overlay |
+| **Execution** | Runs independently | Applied to an existing agent session |
+| **Lifecycle** | Deployed, scaled, monitored | Activated, composed, switched |
+| **Identity** | Has its own agent ID | Inherits the host agent's identity |
+| **Example** | A code review bot | "Drupal developer" context for Claude Code |
+
+Roles answer the question: *"What context, rules, and tools should an AI coding assistant have when working in this domain?"*
+
+## Manifest Structure
+
+```yaml
+apiVersion: ossa/v0.5
+kind: Role
+metadata:
+  name: <role-name>           # Required: DNS-style identifier
+  version: <semver>           # Recommended: e.g. 1.0.0
+  description: <string>       # Human-readable summary
+  labels:                     # Optional: key-value pairs for filtering
+    platform: claude-code
+    domain: drupal
+  annotations:                # Optional: non-identifying metadata
+    org: example-corp
+spec:
+  role: <string>              # System prompt / persona definition
+  instructions:               # Behavioral instructions
+    preamble: <markdown>      # Prepended to every conversation
+    constraints:              # Hard rules (MUST/MUST NOT)
+      - <string>
+  tools:                      # Tool access configuration
+    allowed: [<string>]       # Allowed tool names
+    denied: [<string>]        # Denied tool names (overrides allowed)
+    skills: [<string>]        # OSSA skill references
+  hooks:                      # Lifecycle hooks
+    on_activate: <string>     # Run when role is activated
+    on_deactivate: <string>   # Run when role is deactivated
+    pre_commit: <string>      # Run before git commits
+    post_save: <string>       # Run after file saves
+  context:                    # Context injection
+    schemas: [<path>]         # JSON/OpenAPI schemas to load
+    files:                    # Files to include in context
+      - path: <glob>
+        description: <string>
+    knowledge: [<path>]       # Knowledge base files (markdown, text)
+  protocols:                  # Protocol connections
+    mcp:                      # Model Context Protocol
+      servers:
+        - name: <string>
+          transport: stdio | sse
+          command: <string>   # For stdio transport
+          args: [<string>]
+          url: <string>       # For SSE transport
+  extends:                    # Role composition
+    - role: <role-name>       # Inherit from another role
+      override: true | false  # Whether to override conflicts (default: false)
+  activation:                 # When this role should activate
+    file_patterns: [<glob>]   # Activate when matching files are open
+    command: <string>         # CLI command to activate (e.g. "/role drupal")
+    env:                      # Environment variable conditions
+      <key>: <value>
+```
+
+## Field Reference
+
+### `spec.role`
+
+A string defining the agent's persona when this role is active. This is the system-level identity statement.
+
+```yaml
+spec:
+  role: |
+    You are a Drupal module developer following Drupal coding standards.
+    You write PHP 8.2+ code with strict typing and dependency injection.
+```
+
+### `spec.instructions`
+
+Structured behavioral instructions.
+
+- **`preamble`**: Markdown content prepended to every conversation. Use for rules, conventions, and domain knowledge that should always be present.
+- **`constraints`**: An array of hard rules. Each constraint is a MUST or MUST NOT statement that the agent should never violate.
+
+### `spec.tools`
+
+Controls which tools the agent can use within this role.
+
+- **`allowed`**: Whitelist of tool names. If specified, only these tools are available.
+- **`denied`**: Blacklist of tool names. Takes precedence over `allowed`.
+- **`skills`**: References to OSSA `kind: Skill` manifests that should be loaded.
+
+### `spec.hooks`
+
+Lifecycle hooks executed at specific points. Values are command strings or script references.
+
+- **`on_activate`**: Runs when the role is first activated in a session.
+- **`on_deactivate`**: Runs when switching away from this role.
+- **`pre_commit`**: Runs before git commit operations.
+- **`post_save`**: Runs after file save operations.
+
+### `spec.context`
+
+Injects additional context into the agent's working memory.
+
+- **`schemas`**: Paths to JSON Schema or OpenAPI specification files. The agent can reference these for type-correct code generation.
+- **`files`**: Specific files or globs to include in the agent's context window.
+- **`knowledge`**: Paths to knowledge base documents (markdown, text) that provide domain reference material.
+
+### `spec.protocols.mcp`
+
+MCP server connections available when this role is active.
+
+Each server entry requires:
+- **`name`**: Identifier for the MCP server.
+- **`transport`**: Either `stdio` (local process) or `sse` (HTTP Server-Sent Events).
+- **`command`** + **`args`**: For `stdio` transport, the command to spawn.
+- **`url`**: For `sse` transport, the endpoint URL.
+
+### `spec.extends`
+
+Enables role composition by inheriting from other roles.
+
+- **`role`**: Name of the parent role to inherit from.
+- **`override`**: If `true`, child fields replace parent fields. If `false` (default), child fields merge with parent fields (arrays are concatenated, objects are deep-merged).
+
+### `spec.activation`
+
+Defines conditions under which this role should automatically activate.
+
+- **`file_patterns`**: Glob patterns matched against open files. If any file matches, the role activates.
+- **`command`**: A slash command (e.g., `/role drupal`) that activates the role.
+- **`env`**: Environment variable conditions. All specified variables must match for activation.
+
+## Composition Rules
+
+When a role extends another:
+
+1. **`spec.role`**: Child replaces parent (no merge).
+2. **`spec.instructions.preamble`**: Child is appended after parent.
+3. **`spec.instructions.constraints`**: Arrays are concatenated (all constraints apply).
+4. **`spec.tools.allowed`**: Intersection of parent and child (child cannot grant tools the parent denies).
+5. **`spec.tools.denied`**: Union of parent and child (denials accumulate).
+6. **`spec.tools.skills`**: Arrays are concatenated.
+7. **`spec.hooks`**: Child hooks replace parent hooks for the same lifecycle event.
+8. **`spec.context`**: All context entries are merged (files, schemas, knowledge concatenated).
+9. **`spec.protocols.mcp.servers`**: Arrays are concatenated (all servers available).
+10. **`spec.activation`**: Child activation conditions replace parent.
+
+## Relationship to Other OSSA Kinds
+
+| Kind | Relationship to Role |
+|------|---------------------|
+| `Agent` | Roles are applied to agents. An agent can have multiple roles. |
+| `Skill` | Roles reference skills via `spec.tools.skills`. Skills provide capabilities; roles provide context. |
+| `Task` | Roles may influence how tasks are executed by setting constraints and tool access. |
+| `Workflow` | Roles can be assigned per workflow step to change agent behavior. |
+
+## Platform Mapping
+
+Roles map naturally to platform-specific configuration:
+
+| Role Field | Claude Code | Cursor | Codex CLI |
+|-----------|-------------|--------|-----------|
+| `spec.role` | CLAUDE.md system prompt | .cursorrules | instructions |
+| `spec.instructions.preamble` | CLAUDE.md content | .cursorrules content | --instructions |
+| `spec.tools.allowed` | Tool permissions | Tool config | --tools |
+| `spec.protocols.mcp` | .mcp.json servers | MCP config | MCP servers |
+| `spec.activation.file_patterns` | Glob triggers | File associations | --pattern |
+
+## Examples
+
+See `examples/roles/` for complete role manifests:
+
+- `drupal-developer.role.yaml` — Drupal module development
+- `security-auditor.role.yaml` — Security audit and compliance review
+- `platform-operator.role.yaml` — Full-stack platform operations with composition