Playbook: Claude Worker Roles — Usage Guide
Applies to: all projects in the p24-infra ecosystem (p24-infra, brandpilot, radekkonarski-personal-brand, et-operational-platform)
What exists
10 specialist role personas, each with a companion /role-* skill.
Curated playbook indexes per role: docs/roles/
| Skill | Role file | Playbook index | Use when |
|---|---|---|---|
/role-marketing-director | ~/.claude/agent-prompts/roles/marketing-director.md | marketing-director | Campaign planning, content calendar, pillar decisions |
/role-designer | ~/.claude/agent-prompts/roles/designer.md | designer | Brand visuals, design tokens, HeyGen look IDs, BrandPilot UI |
/role-content-creator | ~/.claude/agent-prompts/roles/content-creator.md | content-creator | LinkedIn posts, YouTube scripts, newsletter copy, captions |
/role-video-producer | ~/.claude/agent-prompts/roles/video-producer.md | video-producer | HeyGen renders, platform uploads, script → video pipeline |
/role-dev-coder | ~/.claude/agent-prompts/roles/dev-coder.md | dev-coder | Feature implementation, migrations, scripts |
/role-dev-reviewer | ~/.claude/agent-prompts/roles/dev-reviewer.md | dev-reviewer | PR reviews, security checklist, EU AI Act check |
/role-dev-tester | ~/.claude/agent-prompts/roles/dev-tester.md | dev-tester | Test suite planning, coverage, no-mock policy enforcement |
/role-sys-admin | ~/.claude/agent-prompts/roles/sys-admin.md | sys-admin | VPS ops, Docker, SSH, infra incidents |
/role-sys-security | ~/.claude/agent-prompts/roles/sys-security.md | sys-security | Security audits, compliance, access investigation |
/role-secret-manager | ~/.claude/agent-prompts/roles/secret-manager.md | secret-manager | Sole authority for SOPS edits, key rotation, and credential distribution. Spawn for any add/rotate/retrieve secret task |
Where skills are registered
Skills live in ~/.claude/commands/ (global user level). They are available in every project — no per-project setup needed. Running /role-sys-admin works equally from p24-infra, brandpilot, or any other repo.
Project-level skills for p24-infra live separately in C:\code_2026\p24-infra\.claude\commands\ and are not duplicated there — global is sufficient.
Invoking a skill
Inline (prime current session)
/role-sys-admin
/role-content-creator
/role-dev-reviewerThe skill reads the role file and adopts the persona for the rest of the session. The startup sequence runs immediately (context guards, playbook checks, brand profile loads, etc.).
With a brand argument (creative roles only)
/role-content-creator radekkonarski
/role-designer acme-furniture
/role-marketing-director radekkonarskiWithout an argument, the creative roles look for [cwd]/brand/PROFILE.md. If they can’t find a brand profile, they halt and ask which brand to work on.
Creative roles — prerequisite: brand profile
All four creative roles (marketing-director, designer, content-creator, video-producer) require a brand/PROFILE.md in the brand repo before they can do any work.
| Brand | Profile location |
|---|---|
| radekkonarski | C:\code_2026\radekkonarski-personal-brand\brand\PROFILE.md |
| BrandPilot customer | [brand-private-repo]/brand/PROFILE.md (dedicated repo per customer) |
If the profile is missing or incomplete, the role will run the brand-definition playbook:
p24-infra/docs/playbooks/brand-definition.md
Technical roles — context guards
sys-admin and sys-security verify they are running in a p24-infra session before doing anything:
- checks that
git remote -vpoints toradieu/p24-infra, or - checks that
p24-infra/CLAUDE.mdis in the current path hierarchy
If invoked from brandpilot or radekkonarski-personal-brand directories, they halt with a clear message. Use them from the C:\code_2026\p24-infra workspace.
Spawning a role as a background agent
For parallel or automated work, spawn the role as a background agent instead of priming your own session:
# Example: spawn a sys-admin agent to check a specific VPS
Agent(
description: "VPS health check — vps-i1",
prompt: "Read ~/.claude/agent-prompts/roles/sys-admin.md and adopt the Sys Admin persona.
Check vps-i1 (217.154.82.162) for disk usage and Docker container health.
Look in p24-infra/docs/playbooks/ for an existing health-check playbook first.",
run_in_background: true
)The agent prompt path is always C:\Users\konar\.claude\agent-prompts\roles\[role].md on this workstation, or ~/.claude/agent-prompts/roles/[role].md on VPSes (if synced).
Handoff labels (creative pipeline)
The creative roles hand work off via GitHub issues. Labels used:
| Label | Created by | Picked up by | Repo |
|---|---|---|---|
content-brief | marketing-director | content-creator | brand’s issue_repo from PROFILE.md |
video-script-ready | content-creator | video-producer | brand’s issue_repo from PROFILE.md |
Issue title format:
[CONTENT] [BRAND] [PILLAR] — short title(content-brief)[VIDEO] [BRAND] [PILLAR] — short title(video-script-ready)
After video-producer completes: closes the issue with render URL + upload confirmation.
HeyGen credit safety
video-producer calls mcp__heygen__get_current_user at startup and halts if the credit balance is below 70. If you see a halt:
- Check current balance in HeyGen dashboard
- Top up credits if needed
- Re-invoke
/role-video-producer
Capability frontmatter (#4705)
Every role file starts with a YAML frontmatter block declaring what the role CAN and CANNOT do:
---
name: dev-coder
summary: Feature implementation, bug fixes, and migrations across the p24-infra ecosystem.
skill: /role-dev-coder
job_types: [dev-issue, continue-issue]
capabilities:
can: [...]
cannot: [...]
delegate_to:
credentials: secret-manager
server-operations: sys-admin
---It is machine-readable and CI-validated for shape
(scripts/tests/test_worker_role_capabilities.py), but not machine-enforced — the persona is
the enforcement. delegate_to targets must name an existing role file; the test fails on a typo.
Role injection into queue workers (#4705)
Roles are no longer session-only. scripts/spawn-worker.sh derives CLAUDE_ROLE from the job type
at spawn time and exports it into the worker, which loads the matching role file and its capability
scope via infra/agent-prompts/worker-issue-scoped.md.
job_type | injected role |
|---|---|
dev-issue, continue-issue | dev-coder |
infra-task, infra-alert, nc-alert-batch | sys-admin |
secret-manager | secret-manager |
review-pr, review-plan | dev-reviewer |
If no role resolves, the worker runs the generic worker-issue.md unchanged. Per-repo standards are
supplied as data via infra/repo-contexts/<repo>.md ($REPO_CONTEXT_FILE) rather than per-project
role variants — see docs/worker-role-scoping-operations.md
for resolution order, the ROLE / P24_CLAUDE_ROLE / CLAUDE_ROLE distinction, and rollback.
Role files — maintenance
Role definitions are version-controlled in p24-infra at .claude/agent-prompts/roles/[role-name].md
and deployed to ~/.claude/agent-prompts/roles/ on vps-i1, vps-h1, and bms-4 by
.github/workflows/sync-claude-skills.yml on merge to main.
Edit the repo copy and open a PR — do not hand-edit a deployed ~/.claude/... copy, it will be
overwritten by the next sync. On the Windows workstation the same file is at
C:\code_2026\p24-infra\.claude\agent-prompts\roles\[role-name].md.
Do NOT edit the companion skill files in ~/.claude/commands/ — they only load the role file and run the startup sequence. Brand-specific values must never be written into role files — they always come from brand/PROFILE.md.
Related playbooks
docs/playbooks/brand-definition.md— run when PROFILE.md is missing or incompletedocs/playbooks/testing-standards.md— no-mock policy + coverage targets (referenced bydev-tester)docs/playbooks/secret-manager.md— master secret playbook (SOPS operations, distribution chain, tier decision tree)docs/secrets-management.md— legacy overview, now redirects to secret-manager.md