# Role Schema — Layer 3 Reusable Entity Type # KNO Schema Version: 0.1.0 # # A role defines responsibilities, capabilities, and behavioral expectations # for an actor (agent, human, or system) within a context. # # EXTENDS: document-schema.kno (which composes identity, history, quality) # USE CASES: # - Playbook agent roles (methodology-specific AI agents) # - Platform roles (admin, contributor, member) # - Workflow participants (reviewer, approver) # - Organization roles (founder, advisor, employee) # # DESIGN PRINCIPLE: Reusable across contexts # A role is NOT playbook-specific. It's a general-purpose schema for any # actor definition with responsibilities and capabilities. # ============================================================================= # SCHEMA DECLARATION # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # IDENTITY # ============================================================================= id: 01KGRBF5CB7YPCTE2PJ4DSP4BJ slug: role-schema type: spec version: 0.1.0 # ============================================================================= # STANDARD TIER # ============================================================================= title: "Role Schema" purpose: | Define the schema for roles — actor definitions with responsibilities, capabilities, and behavioral expectations. **What is a Role?** A role defines how an actor (agent, human, or system) should behave in a given context. It specifies: - What the actor is responsible for - What autonomy level they have - What outputs they produce - When they should be engaged **Subtypes:** | Subtype | Description | Example | |---------|-------------|---------| | `agent` | AI assistant role | "Project Manager Agent" | | `platform` | System access level | "Admin", "Contributor" | | `human` | Human participant | "Code Reviewer", "Product Owner" | | `system` | Automated process | "CI Pipeline", "Deployment Bot" | | `hybrid` | Mixed human/agent | "Pair Programming Partner" | **Usage Contexts:** - **Playbook `_contains.roles`** — Agent behavior definitions - **Platform access control** — Admin/contributor/member - **Workflow stages** — Who does what in a process - **Organization structure** — Team roles **Autonomy Levels (for agent subtypes):** | Level | Agent Authority | Human Involvement | |-------|-----------------|-------------------| | `propose` | Suggest actions | Human decides | | `apply` | Execute with notification | Human monitors | | `review` | Evaluate others' work | Human oversees | | `approve` | Make final decisions | Human delegates | **Layer 3 Position**: Role extends document (Layer 2), which composes identity, history, and quality (Layer 1). # ============================================================================= # RICH TIER — Taxonomy # ============================================================================= provenance: origin: id: 01KGRBF5CB7YPCTE2PJ4DSP4BJ timestamp: "2026-02-05T00:00:00Z" tool: manual taxonomy: topics: - access-control - authorization - methodology - agents - workflows keywords: - role - agent - permission - capability - responsibility - autonomy # ============================================================================= # RICH TIER — Relationships # ============================================================================= relationships: extends: - xri: "kno://specs/document-schema" reason: "Layer 2 base type" depends_on: - xri: "kno://specs/kno-spec" reason: "Defines kno@0.0.9 schema structure" composes: - xri: "kno://specs/identity-schema" reason: "id, slug" - xri: "kno://specs/history-schema" reason: "_history" - xri: "kno://specs/quality-schema" reason: "quality" enables: - xri: "kno://specs/playbook-schema" reason: "Playbooks contain roles as agent definitions" - xri: "kno://specs/workflow-schema" reason: "Workflows assign roles to stages" - xri: "kno://specs/organization-schema" reason: "Organizations define member roles" related_to: - xri: "kno://specs/user-schema" reason: "Users are assigned roles" - xri: "kno://specs/knowledge-source-schema" reason: "Roles complement knowledge sources in playbooks" - xri: "kno://specs/platform-capability-schema" reason: "Platform Capabilities contain role definitions via _contains.roles and reference permission tuples via required_permissions[]. GAP-02: `capabilities[]` here means permission actions; not Platform Capabilities." quality: completeness: 0.75 last_reviewed: "2026-02-05" review_status: draft # ============================================================================= # HISTORY # ============================================================================= _history: version: 1 created: "2026-02-05T00:00:00Z" created_by: "pspace-core-team" modified: "2026-02-05T00:00:00Z" modified_by: "claude" # ============================================================================= # SPECIFICATION # ============================================================================= spec: status: Draft changelog: - version: "0.1.0" date: "2026-02-05" changes: - "Initial creation for Issue #81 (Playbook Container Architecture)" - "Designed as general-purpose schema, not playbook-specific" - "Fulfills existing content/roles/* contract (role@0.1)" - "Supports containment in KAML containers via _contains" schema: type: object required: - id - name - subtype properties: # ----------------------------------------------------------------------- # BASIC TIER # ----------------------------------------------------------------------- $schema: type: string const: "role@0.1.0" description: "Schema declaration" id: type: string description: | Unique identifier for this role. Convention: role_{ulid} for standalone, or slug for contained. examples: - "role_01HXYZ123" - "project-manager" - "admin" # ----------------------------------------------------------------------- # STANDARD TIER # ----------------------------------------------------------------------- subtype: type: string enum: - agent - platform - human - system - hybrid description: "What kind of actor this role defines" name: type: string description: "Human-readable display name" examples: - "Project Manager" - "Administrator" - "Code Reviewer" description: type: string description: "What this role does and why it exists" scope: type: string description: "Permission scope identifier" examples: - "pspace:admin" - "playbook:editor" - "repo:write" # ----------------------------------------------------------------------- # RICH TIER — Responsibilities & Capabilities # ----------------------------------------------------------------------- responsibilities: type: array items: type: string description: "What this role is accountable for" examples: - "Maintain project structure and task organization" - "Review and approve pull requests" capabilities: type: array description: "What actions this role can perform" items: type: object properties: action: type: string description: "The action (e.g., 'create', 'delete', 'approve')" resource: type: string description: "What the action applies to (e.g., 'issues/*')" outputs: type: array items: type: string description: "Artifacts this role produces" examples: - "Project board updates" - "Code review comments" # ----------------------------------------------------------------------- # AGENT-SPECIFIC FIELDS # ----------------------------------------------------------------------- autonomy_level: type: string enum: - propose - apply - review - approve description: "Level of autonomous authority (for agent/system subtypes)" when_to_engage: type: array items: type: string description: "Triggers for engaging this role" examples: - "New GitHub Issue created" - "Pull request opened" - "Milestone deadline approaching" handoff_to: type: array items: type: string description: "Roles this can delegate to" # ----------------------------------------------------------------------- # PLATFORM-SPECIFIC FIELDS # ----------------------------------------------------------------------- inherits_from: type: string description: "Parent role for permission inheritance" examples: - "pspace:member" - "pspace:contributor" # ----------------------------------------------------------------------- # UI HINTS # ----------------------------------------------------------------------- ui: type: object description: "Display hints for UI rendering" properties: badge_color: type: string description: "Hex color for role badge" icon: type: string description: "Icon identifier" priority: type: integer description: "Sort order (higher = more prominent)" # ============================================================================= # EXAMPLES # ============================================================================= examples: - title: "Agent Role in a Playbook" description: "An AI agent role contained in a playbook's _contains.roles" content: | $schema: role@0.1.0 id: project-manager subtype: agent name: "Project Manager" description: | AI agent responsible for maintaining project structure, creating issues, and tracking progress. responsibilities: - "Maintain GitHub Project board" - "Create and structure issues from requirements" - "Track milestone progress" - "Coordinate between specialized agents" autonomy_level: apply outputs: - "GitHub Issues" - "Project board updates" - "Progress reports" when_to_engage: - "New feature request" - "Planning session" - "Milestone checkpoint" handoff_to: - "code-reviewer" - "documentation-writer" - title: "Platform Role" description: "Access control role for the Possibility platform" content: | $schema: role@0.1.0 id: admin subtype: platform name: "Administrator" scope: "pspace:admin" description: | Full access to all Possibility features. inherits_from: "pspace:contributor" capabilities: - action: manage_users resource: "users/*" - action: manage_roles resource: "roles/*" - action: "*" resource: "admin/*" ui: badge_color: "#d69e5a" icon: "shield" priority: 100