/role-builder

name: role-builder
scope: common
category: authoring
description: Create or update a Prismer SS-02 role template from a persona, SOP, job description, or operating brief; instantiate an existing role as a new working agent and run its first task through the bundled one-command harness. Use for "create a role template", "make this role into an agent", "create an agent from this role", or "let this role handle a task". Route standardized instantiate-and-run requests to the script instead of discovering and composing low-level CLI commands.
license: MIT
compatibility:
  - prismer-sdk
  - hermes
  - claude-code
  - codex
  - openclaw
metadata:
  category: authoring
allowed-tools:
  - Read
  - Write
  - Bash
  - WebFetch

Role Builder

Choose exactly one path from the requested outcome. Do not inspect `cloud --help`, create probe assets, or compose low-level commands first.

A. Existing role → new working agent → first task

Run the bundled harness directly:

node scripts/instantiate-and-run.mjs --json

Required environment:

• `PRISMER_API_KEY`
• `PRISMER_CLOUD_BASE`
• `PRISMER_ROLE_SLUG`
• `PRISMER_WORKSPACE_ID`
• `PRISMER_TASK`

Optional environment:

• `PRISMER_AGENT_HANDLE`, `PRISMER_AGENT_DISPLAY_NAME`,

`PRISMER_AGENT_ADAPTER`, `PRISMER_TARGET_DAEMON_ID`

• `PRISMER_REQUEST_ID`, `PRISMER_OPERATION_LEDGER`
• `PRISMER_WORKFLOW_TIMEOUT_MS`, `PRISMER_WORKFLOW_POLL_MS`
• `PRISMER_ALLOW_REMOTE_WRITE=1` for an explicitly confirmed non-local target

The runtime must inject these variables before the turn. Never ask the user to paste a credential into chat and never pass one as a command-line flag.

The harness validates locally, performs server preflight, creates/resumes the role-backed agent, waits for its exact daemon binding, creates one idempotent task, and waits for the canonical result. `--no-wait` skips only the final task result wait. `--preflight-only` performs no mutation.

If it returns `ROLE_CONFIG_REQUIRED`, report the missing level, target, and key names exactly. Do not guess values:

• `level=skill` or `level=role`, user-owned key: the owner supplies it through

Studio or `POST /api/im/user-skill-config`; values are sealed and never enter the model prompt.

• role default: edit the role's `parameters[]` declaration/default.
• global-only Skill key: inject it into the daemon/deployment environment.
• workspace/runtime issue: repair the named workspace or daemon; do not create

a different workspace as a workaround.

B. Material → role template

Create a directory with exactly the role definition and persona:

<role-slug>/
├── role.json
└── SOUL.md

`role.json` is the SS-02 governance manifest. `SOUL.md` is persona only; do not put credentials, per-run instructions, or an `AGENTS.md` in the role bundle.

Minimum useful `role.json`:

{
  "slug": "legal-expert",
  "version": "1.0.0",
  "name": { "en": "Legal Expert", "zh": "法学专家" },
  "description": { "en": "Analyzes legal matters.", "zh": "分析法律事项。" },
  "agentType": "specialist",
  "requiredSkills": [{ "skillSlug": "legal-article-retrieval", "required": true }],
  "taskAuthority": "executor",
  "approvalPolicy": "auto-low-risk",
  "parameters": [],
  "adapters": { "hermes": {} },
  "source": "community",
  "curatedQuality": "review"
}

Use catalog slugs returned by the Skill create/import result. Never derive a slug from a directory name, case-normalize it after creation, or invent one. Build missing skills with `skill-creator` first.

Declare only role-specific business skills in `requiredSkills`. The active Admin Built-in Skill baseline is injected automatically at template creation and re-resolved when an Agent is instantiated. Do not copy system skills into the role manifest and do not attempt to remove an injected skill. Readback separates `requiredSkills`, `injectedSkills`, and `effectiveSkills`, plus the `baselinePolicyVersion` used for the snapshot.

Put the bundle path in `PRISMER_ROLE_BUNDLE`, then run the fixed authoring closure as one command:

node scripts/author-role.mjs --json

Optional environment: `PRISMER_ROLE_PUBLISH=1` for an explicitly requested Marketplace publish, `PRISMER_ROLE_AUTHORING_LEDGER`, `PRISMER_CLOUD_BIN`, `PRISMER_CLOUD_BASE`, and `PRISMER_ALLOW_REMOTE_WRITE=1` for a confirmed non-local target. The harness performs local validation, read-only required Skill preflight, private create/owner-update, and owner readback. It resumes a completed same-revision ledger without pushing another role version. Report the returned slug/version; do not use `role apply` as a test.

The clean lower-level primitives remain available for diagnosis:

cloud role validate ./<role-slug> --json
cloud role test ./<role-slug> --json
cloud role create ./<role-slug> --mine --json
cloud role show <returned-slug-or-id> --json

For the retained legacy entrypoint (requires the current Cloud CLI; no raw HTTP fallback):

node scripts/ingest-role.mjs ./<role-slug> --mine

It reads `PRISMER_API_KEY` and `PRISMER_CLOUD_BASE` from the already-injected environment. Do not write literal secrets in the command, bundle, or ledger. The adapter delegates validation and Skill preflight to Cloud before creation. Ledger-based workflows require an injected API key even if Cloud has saved credentials: the target origin and that executing key's hash bind every receipt. Changing either requires a separate ledger. Completed receipts are read back, not blindly trusted. A lock is never stolen on timeout; after a crash, verify the old process has stopped and reconcile remote writes before explicit recovery.

C. Change an existing agent's role

Only when the user explicitly identifies an existing target:

cloud role apply <role-slug> --agent <imUserId> --workspace-id <workspaceId>

Never apply a role to the currently executing agent as a probe. Template creation is complete after validation, dependency test, ingest, and readback; it does not require