Skip to content
OSTwin

Community Roles

OSTwin ships with a growing library of community-contributed roles alongside the core built-in roles. This page catalogs the role ecosystem, quality standards, and the 5-tier discovery system.

Role Categories

Roles for Unity game development pipelines:

RoleDescription
game-engineerUnity C# code generation, scene building, animation
game-qaPlaytest validation, code review, performance testing
game-architectSystem architecture, ADRs, project context
game-designerGame briefs, GDDs, UX design, epics, stories
game-producerSprint planning, milestone tracking, coordination
game-devopsCI/CD pipelines, Unity Cloud Build, distribution
game-ui-analystUI detection from screenshots, animation extraction
level-designerLevel layouts, difficulty curves, progression tuning
narrative-designerDialogue, lore, story arcs, localization
sound-designerSFX, audio middleware, music integration
tech-artistShaders, VFX, animation polish, art pipeline
ux-researcherPlaytesting, user research, analytics

5-Tier Discovery System

OSTwin uses a 5-tier system to match roles to tasks:

  1. Exact Name Match

    If a plan specifies Roles: game-engineer, the system looks up game-engineer directly in the registry.

  2. Capability Matching

    When capability_matching is enabled, the system scores roles against task requirements:

    Score = count(role.capabilities ∩ task.requirements) / count(task.requirements)

    The highest-scoring role wins.

  3. Alias Resolution

    Capability aliases normalize common terms:

    {
      "sql": "database",
      "react": "frontend",
      "ci-cd": "infrastructure",
      "a11y": "accessibility"
    }

  4. Assignment Rules

    Default fallbacks for common task types:

    Task TypeDefault Role
    taskengineer
    reviewqa
    designarchitect
    orchestrationmanager
    investigationaudit

  5. Dynamic Role Creation

    If no existing role matches, the system can auto-create a dynamic role using auto_create_role.sh. This generates a minimal role.json and ROLE.md from the task description.

Quality Standards

All community roles must meet these standards:

Required

  • Valid role.json with all required fields
  • ROLE.md prompt file with clear identity and responsibilities
  • Unique role name not conflicting with existing registrations
  • At least one capability tag
  • Registration in registry.json
  • Descriptive quality_gates that guide agent behavior
  • Platform restrictions if applicable (e.g., "platform": ["macos"])
  • supported_task_types limiting the role to appropriate work
  • A README.md explaining the role’s purpose and usage

Quality Gates by Category

  • compiles-in-unity or builds-clean
  • unit-tests or tests-pass
  • lint-clean
  • no-hardcoded-secrets
  • Performance targets (e.g., 60fps-non-negotiable)

Submitting Community Roles

  1. Develop your role following the Creating Custom Roles guide

  2. Place files under contributes/roles/

    contributes/roles/my-role/
    ├── role.json
    └── ROLE.md

  3. Add the registry entry with contributes/ prefix

  4. Write tests that verify your role handles its expected task types

  5. Open a PR with the role label against develop

Built-in vs Community

AspectBuilt-inCommunity
Location.agents/roles/contributes/roles/
StabilityGuaranteed backward-compatibleBest-effort
RunnerDedicated PowerShell scriptUsually Start-DynamicRole.ps1
ReviewCore teamCommunity review
Model defaultsConfigured centrallyRole-defined