@bluefly/openstandardagents 0.4.8 → 0.5.0

package/dist/services/export/testing/test-generator.js

@@ -2323,7 +2323,7 @@ class ${className}FunctionalTest extends BrowserTestBase {
 
   <php>
     <env name="SIMPLETEST_BASE_URL" value="http://localhost:8888"/>
-    <env name="SIMPLETEST_DB" value="mysql://drupal:drupal@localhost/drupal"/>
+    <env name="SIMPLETEST_DB" value="mysql://drupal:\${DRUPAL_DB_PASSWORD}@localhost/drupal"/>
     <env name="BROWSERTEST_OUTPUT_DIRECTORY" value="sites/default/files/simpletest"/>
   </php>
 </phpunit>

package/dist/services/governance/cedar-validator.service.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cedar Policy Validator Service
+ *
+ * Uses @cedar-policy/cedar-wasm to validate Cedar policies embedded in OSSA manifests.
+ * This is OSSA's responsibility: schema definition + offline validation.
+ * Runtime enforcement belongs to DUADP.
+ */
+export interface CedarValidationResult {
+    valid: boolean;
+    policyId?: string;
+    errors: string[];
+    warnings: string[];
+}
+export interface CedarManifestValidationResult {
+    valid: boolean;
+    policyCount: number;
+    results: CedarValidationResult[];
+    hasSchema: boolean;
+}
+/**
+ * Validate a single Cedar policy text for syntax correctness.
+ */
+export declare function validatePolicyText(policyText: string, policyId?: string): CedarValidationResult;
+/**
+ * Validate a Cedar policy against a Cedar schema.
+ */
+export declare function validatePolicyWithSchema(policyText: string, schemaText: string, policyId?: string): CedarValidationResult;
+/**
+ * Extract and validate all Cedar policies from an OSSA manifest.
+ */
+export declare function validateManifestCedarPolicies(manifest: Record<string, unknown>): CedarManifestValidationResult;
+//# sourceMappingURL=cedar-validator.service.d.ts.map

package/dist/services/governance/cedar-validator.service.js

@@ -0,0 +1,88 @@
+/**
+ * Cedar Policy Validator Service
+ *
+ * Uses @cedar-policy/cedar-wasm to validate Cedar policies embedded in OSSA manifests.
+ * This is OSSA's responsibility: schema definition + offline validation.
+ * Runtime enforcement belongs to DUADP.
+ */
+import { checkParsePolicySet, checkParseSchema, } from '@cedar-policy/cedar-wasm';
+function extractErrors(answer) {
+    if (answer.type === 'failure') {
+        return answer.errors.map((e) => e.message ?? JSON.stringify(e));
+    }
+    return [];
+}
+/**
+ * Validate a single Cedar policy text for syntax correctness.
+ */
+export function validatePolicyText(policyText, policyId) {
+    const errors = [];
+    const warnings = [];
+    try {
+        const result = checkParsePolicySet({
+            staticPolicies: policyText,
+        });
+        errors.push(...extractErrors(result));
+    }
+    catch (e) {
+        errors.push(`Cedar WASM error: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return { valid: errors.length === 0, policyId, errors, warnings };
+}
+/**
+ * Validate a Cedar policy against a Cedar schema.
+ */
+export function validatePolicyWithSchema(policyText, schemaText, policyId) {
+    const errors = [];
+    const warnings = [];
+    // First validate schema itself
+    try {
+        const schemaResult = checkParseSchema(schemaText);
+        const schemaErrors = extractErrors(schemaResult);
+        if (schemaErrors.length > 0) {
+            errors.push(...schemaErrors.map((e) => `Schema error: ${e}`));
+            return { valid: false, policyId, errors, warnings };
+        }
+    }
+    catch (e) {
+        errors.push(`Cedar schema parse error: ${e instanceof Error ? e.message : String(e)}`);
+        return { valid: false, policyId, errors, warnings };
+    }
+    // Then validate policy syntax
+    try {
+        const result = checkParsePolicySet({
+            staticPolicies: policyText,
+        });
+        errors.push(...extractErrors(result));
+    }
+    catch (e) {
+        errors.push(`Cedar WASM error: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return { valid: errors.length === 0, policyId, errors, warnings };
+}
+/**
+ * Extract and validate all Cedar policies from an OSSA manifest.
+ */
+export function validateManifestCedarPolicies(manifest) {
+    const extensions = manifest.extensions;
+    const security = extensions?.security;
+    const cedarExt = security?.cedar;
+    if (!cedarExt || !cedarExt.policies || cedarExt.policies.length === 0) {
+        return { valid: true, policyCount: 0, results: [], hasSchema: false };
+    }
+    const results = [];
+    const hasSchema = !!cedarExt.schema_text;
+    for (const policy of cedarExt.policies) {
+        const result = hasSchema
+            ? validatePolicyWithSchema(policy.policy_text, cedarExt.schema_text, policy.id)
+            : validatePolicyText(policy.policy_text, policy.id);
+        results.push(result);
+    }
+    return {
+        valid: results.every((r) => r.valid),
+        policyCount: cedarExt.policies.length,
+        results,
+        hasSchema,
+    };
+}
+//# sourceMappingURL=cedar-validator.service.js.map

package/dist/services/mcp/bridge.service.d.ts

@@ -34,6 +34,7 @@ export declare class McpBridgeService {
     private getRegistryPath;
     private loadRegistry;
     private saveRegistry;
+    private saveToolManifest;
     /**
      * Use @modelcontextprotocol/sdk Client to connect to a stdio server and list its tools.
      * Returns an empty array if connection fails (non-fatal — import still proceeds).

package/dist/services/mcp/bridge.service.js

@@ -58,6 +58,34 @@ let McpBridgeService = class McpBridgeService {
         fs.writeFileSync(registryPath, yaml.dump({ generatedBy: 'ossa-mcp-bridge', apiVersion: getApiVersion(), updatedAt: new Date().toISOString(), servers }, { lineWidth: 120 }), 'utf8');
         return registryPath;
     }
+    saveToolManifest(workspaceDir, server) {
+        const toolsDir = path.join(workspaceDir, '.agents-workspace', 'tools');
+        if (!fs.existsSync(toolsDir)) {
+            fs.mkdirSync(toolsDir, { recursive: true });
+        }
+        const manifest = {
+            apiVersion: 'ossa.dev/v0.5',
+            kind: 'Tool',
+            metadata: {
+                name: server.name,
+                description: `Imported MCP server from ${server.source}`,
+                trust_tier: 'experimental',
+                created: server.importedAt,
+            },
+            spec: {
+                protocol: 'mcp',
+                endpoint: {
+                    transport: server.transport,
+                    command: server.command,
+                    args: server.args,
+                    url: server.url,
+                },
+                capabilities: server.tools ?? [],
+            },
+        };
+        const filePath = path.join(toolsDir, `${server.name}.yaml`);
+        fs.writeFileSync(filePath, yaml.dump(manifest, { lineWidth: -1 }), 'utf8');
+    }
     /**
      * Use @modelcontextprotocol/sdk Client to connect to a stdio server and list its tools.
      * Returns an empty array if connection fails (non-fatal — import still proceeds).
@@ -128,6 +156,9 @@ let McpBridgeService = class McpBridgeService {
         }
         const merged = [...existing, ...newEntries];
         const registryPath = this.saveRegistry(dir, merged);
+        for (const entry of newEntries) {
+            this.saveToolManifest(dir, entry);
+        }
         return { action: 'sync', source, serversFound: parsed.length, serversImported: newEntries.length, registryPath, servers: newEntries };
     }
     async list(workspaceDir) {

package/dist/services/skills-pipeline/skills-install.service.js

@@ -12,10 +12,10 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { injectable } from 'inversify';
+import { Octokit } from '@octokit/rest';
 import * as fs from 'fs/promises';
+import { injectable } from 'inversify';
 import * as path from 'path';
-import { Octokit } from '@octokit/rest';
 /**
  * Parse GitHub URL into owner and repo.
  */

package/dist/services/skills-pipeline/skills-research.service.d.ts

@@ -59,28 +59,27 @@ export declare class SkillsResearchService {
      */
     private updateIndex;
     /**
-     * Fetch skills from a research source — dispatches by source type.
-     * Uses @octokit/rest SDK for GitHub and axios for npm registry.
+     * Fetch skills from a research source — dispatches by source type
      */
     private fetchFromSource;
     /**
      * Fetch skills from an awesome-list repo (e.g., awesome-claude-code)
-     * Uses Octokit SDK to fetch README.md and parses markdown links
+     * Parses the README.md for markdown links to skill repos/tools
      */
     private fetchFromAwesomeList;
     /**
      * Fetch skills from a showcase repo (e.g., claude-code-showcase)
-     * Uses Octokit SDK to list directories and read their READMEs
+     * Lists top-level directories and reads their README for metadata
      */
     private fetchFromShowcase;
     /**
      * Fetch skills from npm registry search
-     * Uses axios to search for packages with keyword "claude-skill" or "ossa-agent"
+     * Searches for packages with keyword "claude-skill" or "ossa-agent"
      */
     private fetchFromNpmRegistry;
     /**
      * Fetch skills from a generic GitHub repo
-     * Uses Octokit SDK to list YAML/MD files that look like agent definitions
+     * Lists YAML/MD files that look like agent definitions
      */
     private fetchFromGitHubRepo;
     /**
@@ -89,7 +88,6 @@ export declare class SkillsResearchService {
     private extractTriggersFromText;
     /**
      * Parse GitHub URL into owner/repo
-     * Logs parsing errors instead of silently swallowing them in catch blocks
      */
     private parseGitHubUrl;
     /**

package/dist/services/skills-pipeline/skills-research.service.js

@@ -58,53 +58,13 @@ const DEFAULT_SOURCES = [
  * Common English stop words to exclude from trigger extraction
  */
 const STOP_WORDS = new Set([
-    'the',
-    'and',
-    'for',
-    'are',
-    'but',
-    'not',
-    'you',
-    'all',
-    'can',
-    'her',
-    'was',
-    'one',
-    'our',
-    'out',
-    'has',
-    'have',
-    'with',
-    'this',
-    'that',
-    'from',
-    'they',
-    'been',
-    'said',
-    'each',
-    'which',
-    'their',
-    'will',
-    'other',
-    'about',
-    'many',
-    'then',
-    'them',
-    'these',
-    'some',
-    'would',
-    'make',
-    'like',
-    'into',
-    'could',
-    'time',
-    'very',
-    'when',
-    'come',
-    'made',
-    'use',
-    'using',
-    'used',
+    'the', 'and', 'for', 'are', 'but', 'not', 'you', 'all',
+    'can', 'her', 'was', 'one', 'our', 'out', 'has', 'have',
+    'with', 'this', 'that', 'from', 'they', 'been', 'said',
+    'each', 'which', 'their', 'will', 'other', 'about', 'many',
+    'then', 'them', 'these', 'some', 'would', 'make', 'like',
+    'into', 'could', 'time', 'very', 'when', 'come', 'made',
+    'use', 'using', 'used',
 ]);
 let SkillsResearchService = class SkillsResearchService {
     indexPath;
@@ -194,8 +154,7 @@ let SkillsResearchService = class SkillsResearchService {
         return deduped;
     }
     /**
-     * Fetch skills from a research source — dispatches by source type.
-     * Uses @octokit/rest SDK for GitHub and axios for npm registry.
+     * Fetch skills from a research source — dispatches by source type
      */
     async fetchFromSource(source) {
         switch (source.type) {
@@ -214,7 +173,7 @@ let SkillsResearchService = class SkillsResearchService {
     }
     /**
      * Fetch skills from an awesome-list repo (e.g., awesome-claude-code)
-     * Uses Octokit SDK to fetch README.md and parses markdown links
+     * Parses the README.md for markdown links to skill repos/tools
      */
     async fetchFromAwesomeList(source) {
         const { owner, repo } = this.parseGitHubUrl(source.url);
@@ -258,7 +217,7 @@ let SkillsResearchService = class SkillsResearchService {
     }
     /**
      * Fetch skills from a showcase repo (e.g., claude-code-showcase)
-     * Uses Octokit SDK to list directories and read their READMEs
+     * Lists top-level directories and reads their README for metadata
      */
     async fetchFromShowcase(source) {
         const { owner, repo } = this.parseGitHubUrl(source.url);
@@ -319,7 +278,7 @@ let SkillsResearchService = class SkillsResearchService {
     }
     /**
      * Fetch skills from npm registry search
-     * Uses axios to search for packages with keyword "claude-skill" or "ossa-agent"
+     * Searches for packages with keyword "claude-skill" or "ossa-agent"
      */
     async fetchFromNpmRegistry(source) {
         const skills = [];
@@ -362,7 +321,7 @@ let SkillsResearchService = class SkillsResearchService {
     }
     /**
      * Fetch skills from a generic GitHub repo
-     * Uses Octokit SDK to list YAML/MD files that look like agent definitions
+     * Lists YAML/MD files that look like agent definitions
      */
     async fetchFromGitHubRepo(source) {
         const { owner, repo } = this.parseGitHubUrl(source.url);
@@ -407,15 +366,11 @@ let SkillsResearchService = class SkillsResearchService {
     }
     /**
      * Parse GitHub URL into owner/repo
-     * Logs parsing errors instead of silently swallowing them in catch blocks
      */
     parseGitHubUrl(url) {
         const match = url.match(/github\.com\/([^/]+)\/([^/]+)/);
-        if (!match) {
-            // Log the specific parsing error before throwing
-            console.warn(`Failed to parse GitHub URL: ${url}`);
+        if (!match)
             throw new Error(`Invalid GitHub URL: ${url}`);
-        }
         return { owner: match[1], repo: match[2].replace(/\.git$/, '') };
     }
     /**

package/dist/services/taxonomy-service.d.ts

@@ -6,8 +6,8 @@ import { z } from 'zod';
 export declare const TaxonomyCategoryTypeSchema: z.ZodEnum<{
     custom: "custom";
     runtime: "runtime";
-    capability: "capability";
     role: "role";
+    capability: "capability";
     domain: "domain";
 }>;
 export declare const TaxonomyCategoryInputSchema: z.ZodObject<{
@@ -16,8 +16,8 @@ export declare const TaxonomyCategoryInputSchema: z.ZodObject<{
     type: z.ZodEnum<{
         custom: "custom";
         runtime: "runtime";
-        capability: "capability";
         role: "role";
+        capability: "capability";
         domain: "domain";
     }>;
     level: z.ZodNumber;
@@ -31,8 +31,8 @@ export declare const TaxonomyCategorySchema: z.ZodObject<{
     type: z.ZodEnum<{
         custom: "custom";
         runtime: "runtime";
-        capability: "capability";
         role: "role";
+        capability: "capability";
         domain: "domain";
     }>;
     level: z.ZodNumber;

package/dist/services/trust/trust.service.d.ts

@@ -35,4 +35,13 @@ export declare function canonicalManifestBytes(manifest: Record<string, unknown>
  * Verifies an agent's x-signature block against its canonical manifest.
  */
 export declare function verifyAgentSignature(manifest: Record<string, unknown>, signature: XSignature, agentId?: string): Promise<TrustVerificationResult>;
+/**
+ * Sign an agent manifest using an Ed25519 private key.
+ *
+ * @param manifest The agent manifest to sign
+ * @param privateKeyHex The Ed25519 private key in hex format
+ * @param issuer Optional DID or identifier of the signer
+ * @returns The manifest with the appended x-signature block
+ */
+export declare function signAgentManifest(manifest: Record<string, unknown>, privateKeyHex: string, issuer?: string): Promise<Record<string, unknown>>;
 //# sourceMappingURL=trust.service.d.ts.map

package/dist/services/trust/trust.service.js

@@ -170,6 +170,41 @@ export async function verifyAgentSignature(manifest, signature, agentId) {
         };
     }
 }
+/**
+ * Sign an agent manifest using an Ed25519 private key.
+ *
+ * @param manifest The agent manifest to sign
+ * @param privateKeyHex The Ed25519 private key in hex format
+ * @param issuer Optional DID or identifier of the signer
+ * @returns The manifest with the appended x-signature block
+ */
+export async function signAgentManifest(manifest, privateKeyHex, issuer) {
+    const payload = canonicalManifestBytes(manifest);
+    // Use @noble/ed25519 to sign the payload
+    const sigBytes = await ed.signAsync(payload, privateKeyHex);
+    const pubBytes = await ed.getPublicKeyAsync(privateKeyHex);
+    // Convert to base64 for the signature block
+    const signatureB64 = Buffer.from(sigBytes).toString('base64');
+    const publicKeyB64 = Buffer.from(pubBytes).toString('base64');
+    const signature = {
+        type: 'Ed25519',
+        value: signatureB64,
+        publicKey: publicKeyB64,
+        timestamp: new Date().toISOString()
+    };
+    if (issuer) {
+        signature.issuer = issuer;
+    }
+    // Insert x-signature into metadata
+    const metadata = manifest.metadata || {};
+    return {
+        ...manifest,
+        metadata: {
+            ...metadata,
+            'x-signature': signature
+        }
+    };
+}
 // ─── Utilities ──────────────────────────────────────────────
 function base64ToBytes(b64) {
     const binary = atob(b64);

package/dist/services/validators/a2a.validator.js

@@ -42,8 +42,8 @@ let A2AValidator = class A2AValidator {
             }
         }
         if (a2aConfig.agent_card &&
-            !a2aConfig.agent_card.agent_uri?.startsWith('agent://')) {
-            errors.push('Agent URI must start with agent://');
+            !a2aConfig.agent_card.agent_uri?.startsWith('uadp://')) {
+            errors.push('Agent URI must start with uadp://');
         }
         if (a2aConfig.handoff_protocol && !a2aConfig.service_discovery?.enabled) {
             warnings.push('Handoff protocol configured without service discovery');

package/dist/skills/test-skill/package.json

@@ -31,6 +31,6 @@
   ],
   "ossa": {
     "type": "claude-skill",
-    "skillPath": "/var/folders/48/d86hncy50j93r_vzsv6knttr0000gn/T/ossa-export-test-1772826461079/test-skill"
+    "skillPath": "/var/folders/48/d86hncy50j93r_vzsv6knttr0000gn/T/ossa-export-test-1773547554392/test-skill"
   }
 }

package/dist/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

package/dist/spec/uadp/README.md

@@ -367,7 +367,7 @@ A more complete implementation adds:
 
 Reference implementations:
 - **Drupal**: `ai_agents_marketplace` module (PHP)
-- **Express**: `@ossa/uadp-node` (TypeScript) — planned
+- **Express**: `@bluefly/duadp` (TypeScript) — planned
 - **Static**: GitHub Pages with JSON files — planned
 
 ## Appendix A: JSON Schemas