Role Builder

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:

bashCopy code
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:

textCopy code
<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:

jsonCopy code
{
  "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:

bashCopy code
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:

bashCopy code
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):

bashCopy code
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:

bashCopy code
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 mutating a live agent.

Configuration ownership

Declare each value once at the level that owns it:

Do not duplicate values across Skill prose, role persona, workspace metadata, and workflow flags. Workspace metadata is not a secret store.

Harness negative-control contract

The bundled mutation harness must keep these guarantees:

1. Secret-bearing flags, missing/invalid local input, and unconfirmed remote writes fail locally before any fetch.
2. Server preflight rejects inaccessible/non-deployable roles, missing config, handle collisions, and absent runtime before creating an operation or agent.
3. Instance and task writes carry durable idempotency keys. Instance retries return the same operation and reject changed instance input with 409; task retries return the first committed task and reject changed task input with 409. Derived task keys are fixed-length hashes, so a 191-character instance request ID cannot overflow the task contract. A new invocation gets a fresh request ID; set PRISMER_REQUEST_ID only to resume that same invocation.
4. A secret-free ledger is written atomically before mutation. Output contains stage, code, retryability, and recovery path—never credentials. Reusing the ledger path with a different invocation hash is rejected before fetch.
5. Provisioning failure compensates the newly created agent. Incomplete cleanup remains cleanupStatus=pending with the Agent pointer retained and retryable; it must never be reported as cleaned. Task failure keeps a valid agent for diagnosis/retry.
6. ready means the Agent is bound to the exact requested daemon. A wrong_daemon binding fails explicitly and cannot advance to task creation.

Sources of truth

• Role standard: public/docs/Standardization/02-role-template-standard.md
• Harness standard: public/docs/Standardization/16-automation-harness-standard.md
• Complete catalog example: sdk/cloud/catalog/roles/team-manager.json
• Skill authoring/import: sdk/cloud/catalog/skills/skill-creator/SKILL.md