p24-infra Docs

001-operational-roles-architecture

2 min read

ADR 001: Operational Role System Architecture

Status: Accepted Date: 2026-07-05 Issue: #2733

Decision

Four specialized roles (sysadmin, debugger, security-auditor, secret-manager) defined as Markdown files with explicit context boundaries. Security-auditor is adversarially isolated — it must run in a separate session, never inline.

Rationale

General-purpose sessions load too much context for specialized tasks. A security auditor sharing context with the sysadmin confirms the sysadmin’s assumptions rather than challenging them. Specialized roles with explicit EXCLUDE lists prevent this anchoring problem.

The context intersection model (context = role INTERSECT repo, not UNION) keeps each session focused and prevents credential or operational context from leaking across role boundaries.

Implementation

  • Role definitions: .claude/roles/ (in p24-infra repo, version-controlled)
  • Invocable skills: global ~/.claude/commands/role-*.md (existing system)
  • Repo-specific extensions: .claude/role-contexts/{repo-slug}/{role}.md
  • Shared minimal context: .claude/shared-infra-context.md
  • Cross-repo orchestration: /open-role global skill (Phase 2 — not in this ADR)
  • Context = role INTERSECT repo: agent sees only the intersection of role scope and repo scope

Consequences

  • Security-auditor inline invocation is blocked by a self-check at top of role file
  • Role-context templates require authoring per repo+role pair (manageable for current scope)
  • CI regeneration of context templates is future work (known limitation, tracked in #2733)
  • Phase 2 (cross-repo contexts + /open-role skill) and Phase 3 (secret-manager auto-log) are separate issues — not part of this ADR

Phase 2 — Implementation Status

Implemented: 2026-07-05 (issue #2733)

Phase 2 delivered:

  • /open-role global skill at ~/.claude/commands/open-role.md — composes context from three layers (shared-infra-context + role + repo-specific) and spawns an isolated background agent for security-auditor or a repo-scoped agent for other roles
  • Role-context templates for four additional repos:
    • pinbox24/ — sysadmin.md (bms-1 Docker map, PM2, MongoDB rs0) + debugger.md (Mezmo queries, failure modes)
    • et-operational-platform/ — debugger.md (Vercel, Supabase, n8n) + security-auditor.md (RLS gaps, admin key exposure)
    • art-agency/ — debugger.md (Supabase art-agency, KDP, Google Drive) + security-auditor.md (PayPal validation, OAuth token storage)
    • brandpilot/ — debugger.md (Vercel, GH Actions, Wasabi, Claude API) + security-auditor.md (prompt injection, key rotation gaps)
  • CLAUDE_P24_INFRA_PATH env var allows overriding the p24-infra path on Linux workers

Phase 3 (secret-manager auto-log integration) remains a future milestone.

Graph View

Backlinks