@bluefly/openstandardagents 0.4.9 → 0.5.0

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/v0.4/extensions/mcp/README.md

@@ -187,7 +187,7 @@ spec:
               - "-y"
               - "@modelcontextprotocol/server-postgres"
           env:
-            DATABASE_URL: "postgresql://user:pass@localhost:5432/db"
+            DATABASE_URL: "postgresql://user:${POSTGRES_PASSWORD}@localhost:5432/db"
           capabilities:
             tools:
               listChanged: false

package/dist/spec/v0.5/agent.schema.json

@@ -25,11 +25,12 @@
       "type": "string",
       "enum": [
         "Agent",
+        "Role",
         "Task",
         "Workflow",
         "Flow"
       ],
-      "description": "Resource type: Agent (agentic loops), Task (deterministic steps), Workflow (composition), or Flow (streaming)"
+      "description": "Resource type: Agent (agentic loops), Role (IDE operator overlay), Task (deterministic steps), Workflow (composition), or Flow (streaming)"
     },
     "metadata": {
       "$ref": "#/definitions/Metadata"

package/dist/spec/v0.5/extensions/mcp/README.md

@@ -187,7 +187,7 @@ spec:
               - "-y"
               - "@modelcontextprotocol/server-postgres"
           env:
-            DATABASE_URL: "postgresql://user:pass@localhost:5432/db"
+            DATABASE_URL: "postgresql://user:${POSTGRES_PASSWORD}@localhost:5432/db"
           capabilities:
             tools:
               listChanged: false

package/dist/spec/v0.5/role.schema.json

@@ -0,0 +1,268 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.5/role.schema.json",
+  "title": "OSSA v0.5 Role Manifest Schema",
+  "description": "Open Standard for Software Agents (OSSA) v0.5 - Role manifest. Defines behavioral overlays for IDE/CLI agents (Claude Code, Cursor, etc.) with instructions, tool sets, hooks, MCP connections, and activation conditions.",
+  "type": "object",
+  "required": ["apiVersion", "kind", "metadata", "spec"],
+  "properties": {
+    "apiVersion": {
+      "type": "string",
+      "pattern": "^ossa/v[0-9]+(\\.[0-9]+)*(-[a-zA-Z0-9.]+)?$",
+      "description": "OSSA API version",
+      "examples": ["ossa/v0.5", "ossa/v1"]
+    },
+    "kind": {
+      "type": "string",
+      "const": "Role",
+      "description": "Resource type — must be Role"
+    },
+    "metadata": {
+      "$ref": "#/definitions/RoleMetadata"
+    },
+    "spec": {
+      "$ref": "#/definitions/RoleSpec"
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Platform-specific extensions",
+      "additionalProperties": true
+    }
+  },
+  "definitions": {
+    "RoleMetadata": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "DNS-style role name (lowercase, hyphens)",
+          "examples": ["drupal-developer", "security-auditor", "platform-operator"]
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.]+)?$",
+          "description": "Semantic version",
+          "examples": ["1.0.0", "2.1.0-beta"]
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description"
+        },
+        "labels": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Key-value labels for filtering and categorization"
+        },
+        "annotations": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Non-identifying metadata"
+        }
+      }
+    },
+    "RoleSpec": {
+      "type": "object",
+      "properties": {
+        "role": {
+          "type": "string",
+          "description": "System prompt / persona definition"
+        },
+        "instructions": {
+          "$ref": "#/definitions/RoleInstructions"
+        },
+        "tools": {
+          "$ref": "#/definitions/RoleTools"
+        },
+        "hooks": {
+          "$ref": "#/definitions/RoleHooks"
+        },
+        "context": {
+          "$ref": "#/definitions/RoleContext"
+        },
+        "protocols": {
+          "$ref": "#/definitions/RoleProtocols"
+        },
+        "extends": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/RoleExtension" },
+          "description": "Role composition — inherit from other roles"
+        },
+        "activation": {
+          "$ref": "#/definitions/RoleActivation"
+        }
+      }
+    },
+    "RoleInstructions": {
+      "type": "object",
+      "properties": {
+        "preamble": {
+          "type": "string",
+          "description": "Markdown content prepended to every conversation"
+        },
+        "constraints": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Hard rules — MUST/MUST NOT statements"
+        }
+      }
+    },
+    "RoleTools": {
+      "type": "object",
+      "properties": {
+        "allowed": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Whitelist of allowed tool names"
+        },
+        "denied": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Blacklist of denied tool names (overrides allowed)"
+        },
+        "skills": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "References to OSSA Skill manifests"
+        }
+      }
+    },
+    "RoleHooks": {
+      "type": "object",
+      "properties": {
+        "on_activate": {
+          "type": "string",
+          "description": "Run when role is activated"
+        },
+        "on_deactivate": {
+          "type": "string",
+          "description": "Run when switching away from this role"
+        },
+        "pre_commit": {
+          "type": "string",
+          "description": "Run before git commits"
+        },
+        "post_save": {
+          "type": "string",
+          "description": "Run after file saves"
+        }
+      }
+    },
+    "RoleContext": {
+      "type": "object",
+      "properties": {
+        "schemas": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Paths to JSON Schema or OpenAPI spec files"
+        },
+        "files": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/RoleContextFile" },
+          "description": "Files to include in agent context"
+        },
+        "knowledge": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Paths to knowledge base documents"
+        }
+      }
+    },
+    "RoleContextFile": {
+      "type": "object",
+      "required": ["path"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "File path or glob pattern"
+        },
+        "description": {
+          "type": "string",
+          "description": "Description of what this file provides"
+        }
+      }
+    },
+    "RoleProtocols": {
+      "type": "object",
+      "properties": {
+        "mcp": {
+          "$ref": "#/definitions/RoleMCPConfig"
+        }
+      }
+    },
+    "RoleMCPConfig": {
+      "type": "object",
+      "properties": {
+        "servers": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/RoleMCPServer" },
+          "description": "MCP servers available when this role is active"
+        }
+      }
+    },
+    "RoleMCPServer": {
+      "type": "object",
+      "required": ["name", "transport"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Server identifier"
+        },
+        "transport": {
+          "type": "string",
+          "enum": ["stdio", "sse"],
+          "description": "Transport type"
+        },
+        "command": {
+          "type": "string",
+          "description": "Command to spawn (stdio transport)"
+        },
+        "args": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Command arguments (stdio transport)"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Endpoint URL (SSE transport)"
+        }
+      }
+    },
+    "RoleExtension": {
+      "type": "object",
+      "required": ["role"],
+      "properties": {
+        "role": {
+          "type": "string",
+          "description": "Name of the parent role to inherit from"
+        },
+        "override": {
+          "type": "boolean",
+          "default": false,
+          "description": "If true, child fields replace parent fields; if false, they merge"
+        }
+      }
+    },
+    "RoleActivation": {
+      "type": "object",
+      "properties": {
+        "file_patterns": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Glob patterns — activate when matching files are open"
+        },
+        "command": {
+          "type": "string",
+          "description": "CLI command to activate (e.g., /role drupal)"
+        },
+        "env": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Environment variable conditions (all must match)"
+        }
+      }
+    }
+  }
+}

package/dist/types/index.d.ts

@@ -22,6 +22,8 @@ export * from './security.js';
 export type { AuditConfig, DataClassification, EgressPolicy, NetworkAccessConfig, NetworkProtocol, ResourceLimits, SandboxingConfig, SandboxType, SecurityCapability, SecurityPosture, ThreatCategory, ThreatModelEntry, ThreatSeverity } from './security.js';
 export { isOssaSkill } from './skill.js';
 export type { OssaSkill } from './skill.js';
+export { createRoleManifest, isOssaRole } from './role.js';
+export type { OssaRole, RoleActivation, RoleContext, RoleExtension, RoleHooks, RoleInstructions, RoleMCPServer, RoleProtocols, RoleSpec, RoleTools } from './role.js';
 export { isOssaMCPServer } from './mcp-server-manifest.js';
 export type { OssaMCPServer } from './mcp-server-manifest.js';
 export * from './protocols.js';

package/dist/types/index.js

@@ -21,6 +21,8 @@ export * from './architect.js';
 export * from './security.js';
 // Export Skill types (AgentSkills / OSSA skills)
 export { isOssaSkill } from './skill.js';
+// Export Role types (v0.5 — IDE operator contexts)
+export { createRoleManifest, isOssaRole } from './role.js';
 // Export MCP server manifest types
 export { isOssaMCPServer } from './mcp-server-manifest.js';
 // Export Protocol Declaration types (v0.5)

package/dist/types/role.d.ts

@@ -0,0 +1,126 @@
+/**
+ * OSSA Role Manifest Types
+ * Type definitions for role.ossa.yaml manifests (kind: Role)
+ *
+ * Roles define behavioral overlays for IDE/CLI agents (Claude Code, Cursor, etc.)
+ * Unlike Agents (autonomous loops), Roles configure operator context — instructions,
+ * tool access, hooks, MCP connections, and activation conditions.
+ */
+export interface OssaRole {
+    apiVersion: string;
+    kind: 'Role';
+    metadata: RoleMetadata;
+    spec: RoleSpec;
+    extensions?: Record<string, unknown>;
+}
+export interface RoleMetadata {
+    /** DNS-style role name (lowercase, hyphens) */
+    name: string;
+    /** Semantic version */
+    version?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Key-value labels for filtering and categorization */
+    labels?: Record<string, string>;
+    /** Non-identifying metadata */
+    annotations?: Record<string, string>;
+}
+export interface RoleSpec {
+    /** System prompt / persona definition */
+    role?: string;
+    /** Behavioral instructions */
+    instructions?: RoleInstructions;
+    /** Tool access configuration */
+    tools?: RoleTools;
+    /** Lifecycle hooks */
+    hooks?: RoleHooks;
+    /** Context injection */
+    context?: RoleContext;
+    /** Protocol connections */
+    protocols?: RoleProtocols;
+    /** Role composition — inherit from other roles */
+    extends?: RoleExtension[];
+    /** Activation conditions */
+    activation?: RoleActivation;
+}
+export interface RoleInstructions {
+    /** Markdown content prepended to every conversation */
+    preamble?: string;
+    /** Hard rules — MUST/MUST NOT statements */
+    constraints?: string[];
+}
+export interface RoleTools {
+    /** Whitelist of allowed tool names */
+    allowed?: string[];
+    /** Blacklist of denied tool names (overrides allowed) */
+    denied?: string[];
+    /** References to OSSA Skill manifests */
+    skills?: string[];
+}
+export interface RoleHooks {
+    /** Run when role is activated */
+    on_activate?: string;
+    /** Run when switching away from this role */
+    on_deactivate?: string;
+    /** Run before git commits */
+    pre_commit?: string;
+    /** Run after file saves */
+    post_save?: string;
+}
+export interface RoleContext {
+    /** Paths to JSON Schema or OpenAPI spec files */
+    schemas?: string[];
+    /** Files to include in agent context */
+    files?: RoleContextFile[];
+    /** Paths to knowledge base documents */
+    knowledge?: string[];
+}
+export interface RoleContextFile {
+    /** File path or glob pattern */
+    path: string;
+    /** Description of what this file provides */
+    description?: string;
+}
+export interface RoleProtocols {
+    /** MCP server connections */
+    mcp?: RoleMCPConfig;
+}
+export interface RoleMCPConfig {
+    /** MCP servers available when this role is active */
+    servers?: RoleMCPServer[];
+}
+export interface RoleMCPServer {
+    /** Server identifier */
+    name: string;
+    /** Transport type */
+    transport: 'stdio' | 'sse';
+    /** Command to spawn (stdio transport) */
+    command?: string;
+    /** Command arguments (stdio transport) */
+    args?: string[];
+    /** Endpoint URL (SSE transport) */
+    url?: string;
+}
+export interface RoleExtension {
+    /** Name of the parent role to inherit from */
+    role: string;
+    /** If true, child fields replace parent fields; if false, they merge */
+    override?: boolean;
+}
+export interface RoleActivation {
+    /** Glob patterns — activate when matching files are open */
+    file_patterns?: string[];
+    /** CLI command to activate (e.g., "/role drupal") */
+    command?: string;
+    /** Environment variable conditions (all must match) */
+    env?: Record<string, string>;
+}
+/**
+ * Type guard for OssaRole
+ */
+export declare function isOssaRole(obj: unknown): obj is OssaRole;
+/**
+ * Create a minimal OssaRole manifest
+ */
+export declare function createRoleManifest(name: string, description: string, role?: string): OssaRole;
+//# sourceMappingURL=role.d.ts.map

package/dist/types/role.js

@@ -0,0 +1,38 @@
+/**
+ * OSSA Role Manifest Types
+ * Type definitions for role.ossa.yaml manifests (kind: Role)
+ *
+ * Roles define behavioral overlays for IDE/CLI agents (Claude Code, Cursor, etc.)
+ * Unlike Agents (autonomous loops), Roles configure operator context — instructions,
+ * tool access, hooks, MCP connections, and activation conditions.
+ */
+/**
+ * Type guard for OssaRole
+ */
+export function isOssaRole(obj) {
+    if (!obj || typeof obj !== 'object')
+        return false;
+    const o = obj;
+    return (o.kind === 'Role' &&
+        typeof o.apiVersion === 'string' &&
+        o.metadata != null &&
+        o.spec != null);
+}
+/**
+ * Create a minimal OssaRole manifest
+ */
+export function createRoleManifest(name, description, role) {
+    return {
+        apiVersion: 'ossa/v0.5',
+        kind: 'Role',
+        metadata: {
+            name,
+            version: '1.0.0',
+            description,
+        },
+        spec: {
+            ...(role ? { role } : {}),
+        },
+    };
+}
+//# sourceMappingURL=role.js.map

package/dist/validation/validator.js

@@ -22,7 +22,7 @@ export class OSSAValidator {
         });
         addFormats(this.ajv);
         // Load schema
-        const defaultSchemaPath = join(__dirname, '../spec/v0.4/agent.schema.json');
+        const defaultSchemaPath = join(__dirname, '../spec/v0.5/agent.schema.json');
         const resolvedPath = schemaPath || defaultSchemaPath;
         try {
             const schemaContent = readFileSync(resolvedPath, 'utf-8');