| name | atmux-create-role |
| description | Scaffold a new ATMUX role directory with `atmux role create`. Use when the user wants to author a reusable agent role, team role, or team-private member role. |
| allowed-tools | Bash(atmux role create*, mktemp*, rm*) |
ATMUX Create Role
Use atmux role create to scaffold a new role directory. Standalone agent roles are discoverable with atmux role resolve --kind agent <name> and usable as atmux agent create <agent> --role <name>. Team roles are discoverable with atmux role resolve --kind team <name> and usable as atmux team create <team> --role <name>. Team-private member roles created with --parent-team <team> are only resolved while that parent team spawns its members.
Arguments
$ARGUMENTS should contain fields separated by |:
name | description | intelligence? | adapters? | hooks? | scope? | parent-team? | kind?
| # | Field | Required | Notes |
|---|
| 1 | name | yes | Role identifier (^[A-Za-z0-9._-]+$). |
| 2 | description | yes | One- to few-sentence statement of what the role does. |
| 3 | intelligence | no | Integer 0–100. |
| 4 | adapters | no | Comma-separated subset (e.g. claude-code,codex). |
| 5 | hooks | no | Comma-separated subset of start,stop (or none). |
| 6 | scope | no | repo | global | auto (default auto). |
| 7 | parent-team | no | Team name for a private member role under roles/teams/<team>/roles/<name>. |
| 8 | kind | no | agent | team (default agent; must be agent when parent-team is set). |
Examples:
/atmux-create-role pr-reviewer | reviews incoming GitHub PRs and posts structured feedback | 75 | claude-code,codex | start,stop | repo/atmux-create-role tester | runs the test suite for assigned changes and reports failures | 55/atmux-create-role release-pair | coordinates release prep as a team | | | none | repo | | team
Behavior
- Split
$ARGUMENTS on | and trim whitespace from each field.
- If
description is non-trivial enough to warrant a hand-authored role.md, draft the body yourself (heading, "You are…" framing, ## Workflow steps grounded in the description, ## Tools available pointing at atmux/git/gh as relevant). Write it to a temp file via mktemp. Otherwise, skip this step and let atmux role create --description ... generate a stub.
- Run
atmux role create <name> with:
--from-file <tmpfile> if you authored the body, OR --description "<text>" to use the built-in stub.--intelligence <n> if provided.--adapters <list> if provided.--hooks <list> if provided (or --hooks none to be explicit).--scope <repo|global|auto> if provided (defaults to auto).--parent-team <team> if provided.--kind <agent|team> if provided.
- Clean up the temp file with
rm -f.
- Report the path printed by
atmux role create and the correct follow-up:
- For standalone agent roles:
atmux agent create <suggested-agent-name> --role <name> --intelligence <n> [--adapter <first-adapter>].
- For team roles:
atmux team create <suggested-team-name> --role <name>.
- For team-private member roles: tell the user to add
--role <name> to the parent team's MEMBERS=(...); do not suggest spawning it directly.
atmux role create validates the name, refuses to overwrite without --force, strips reserved <atmux> fence lines from supplied bodies, writes the manifest with INTELLIGENCE/ADAPTERS=(), and chmod +x's any hooks. Trust it for those concerns.
