p24-infra Docs

2075-role-scoped-workers

3 min read

Design — Specialized Role-Scoped Workers

Issue: #2075 · Status: Design (plan only, no implementation) · Batch: K (#3338)

Documents the current worker/role system as-is and scopes the design work needed to evolve toward specialized, role-scoped workers.

1. As-is inventory

Role personas — 9 global definitions

Location: ~/.claude/agent-prompts/roles/ (global, all projects).

RoleScope
dev-coderFeature implementation, git worktrees, CLAUDE.md compliance
dev-reviewerPR review, security, EU AI Act compliance
dev-testerTest coverage, no-mock enforcement
sys-adminVPS ops, Docker, playbook-first
sys-securityCredential rotation, SOPS, security audits
content-creatorn8n/LinkedIn/HeyGen automation
designerBrand visuals, UI design tokens
video-producerHeyGen renders, platform uploads
marketing-directorCampaign planning, content calendars

Invoked via /role-<name> skill or inline persona adoption. Roles are thin wrappers — they do NOT inject into spawned workers automatically.

Worker templates — 6 in infra/agent-prompts/

WorkerUsed for
worker-issue.mdGeneric GitHub issue implementation (v2.0)
infra-task-request-worker.mdAdmin ops via SSH on VPS/bare-metal
worker-content.mdContent automation (Markdown/n8n/LinkedIn/HeyGen)
worker-nextjs-dev.mdNext.js features (et-operational-platform, BrandPilot)
worker-python-dev.mdPython features (audit-engine, exporters)
review-pr-worker.mdPR review worker

Queue dispatch — current routing (spawn-worker.sh by $QUEUE_JOB_TYPE)

dev-issue       → worker-issue.md (generic)
review-pr       → /review-pr skill
review-plan     → /review-plan skill
continue-issue  → resume stalled worker
infra-alert     → infra-task-request-worker.md
infra-task      → infra-task-request-worker.md

Task playbooks (12, keyword-triggered in .claude/task-playbooks/) work well and are out of scope.

2. Gap analysis

  1. Generic dev-issue overload. All feature work — Next.js, Python, infra docs — funnels through the single 33 KB worker-issue.md. The worker loads all repo-specific rule blocks even when only one applies, bloating context for every job.
  2. No role → worker binding. Roles and worker templates are two disconnected taxonomies. A dev-issue worker does not adopt dev-coder standards automatically; the standards are re-encoded inline in worker-issue.md instead of referenced from the role file. Divergence risk.
  3. Role-mismatch handled reactively. worker-issue.md Step 0b-ROLE detects server-op tasks and reroutes to infra-task, but only for one boundary. Language/stack mismatches (Python job routed to the generic worker) are not detected.

3. Proposed direction (to iterate — not yet approved)

  • Split dev-issue by stack at dispatch. Add job_type sub-routing on repo + changed-area heuristics: dev-issue-nextjs → worker-nextjs-dev.md, dev-issue-python → worker-python-dev.md, fallback worker-issue.md. Dispatcher (spawn-worker.sh) owns the routing table.
  • Single source of standards. Move the per-repo rule blocks out of worker-issue.md into the matching role file under ~/.claude/agent-prompts/roles/; workers Read the role file at Step 4 instead of carrying an inline copy. Eliminates the divergence risk in gap #2.
  • Extend Step 0b-ROLE into a general capability check (stack, credentials, server-op) that emits a typed reroute rather than the single infra-task branch.

4. Decisions required (human)

  • Approve stack-based sub-routing vs. keep one generic worker (context cost vs. maintenance).
  • Where standards live: role files (global) vs. worker-issue.md (repo-versioned) — single source.
  • Whether role personas should be injected into spawned workers automatically.

5. Explicitly out of scope for this doc

No dispatcher, worker template, or role file is modified by this issue. Implementation is separate tracked work once the decisions above are made.

Design-only deliverable. Related: infra/agent-prompts/worker-issue.md, docs/plans/plan-per-role-worker-credentials.md.

Graph View