Files

T

Chris Farhood 674be5d762 chore: remove Samuel, reduce per-heartbeat token load

- Remove Samuel Stinkpost (terminated) from all files and delete marketing/samuel/
- Update PEM listing in OPERATIONS.md to the 4 role-based keys
- POLICIES.md and TOOLS.md are now conditional reads (only when agents have work to do), not loaded on every heartbeat
- Split product/SOUL.md: core identity stays in SOUL.md, reference material (plugin portfolio, competitive landscape, evaluation framework, spec template) moved to PRODUCT-CONTEXT.md
- CLAUDE.md improvements: add OPERATIONS.md/POLICIES.md/TOOLS.md references, fix adapter list, add PR workflow, document opencode.json purpose

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-25 07:41:51 -04:00

4.3 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repo Is

This is the agent roster repository for Privileged Escalation, an open source software company building Headlamp plugins for Kubernetes (GitHub org: privilegedescalation). It contains canonical definitions for all Paperclip AI agents — their identities, prompts, adapter configs, and heartbeat settings.

There is no application code, build system, or test suite in this repo. It is a documentation/configuration repo.

Repository Structure

COMPANY.md — Agent roster table, known operational issues, and restore procedures
OPERATIONS.md — Pod operations runbook: initial setup, adding agents, credential symlinks, routine maintenance
POLICIES.md — Shared policies for all agents: git workflow, PR process, infrastructure rules, issue tracking
TOOLS.md — Shared tools registry: CLI tools, repos, MCP servers, GitHub Actions runners
ceo/ — CEO agent (Countess von Containerheim)
cto/ — CTO agent (Null Pointer Nancy)
cmo/ — CMO agent (Addison Addington)
product/ — VP of Product (Kubectl Karen)
engineering/gandalf/ — Staff Engineer (Gandalf the Greybeard)
engineering/hugh/ — VP Engineering Ops (Hugh Hackman)
engineering/patty/ — UAT Engineer (Pixel Patty)
engineering/regina/ — QA Engineer (Regression Regina)

Each agent directory contains these standard files:

File	Purpose
`AGENTS.md`	Bootstrap prompt (loaded via `instructionsFilePath`)
`SOUL.md`	Persona, voice, values, decision rules, constraints
`HEARTBEAT.md`	Step-by-step execution checklist run on every heartbeat
`TOOLS.md`	Available CLI tools registry
`CONFIG.md`	Operational backup — identity table, adapter config, heartbeat config
`opencode.json`	Runtime config for `opencode_local` agents (model, MCP servers, permissions)

product/ additionally contains .mcp.json (MCP server config for claude_local). MCP config lives in .mcp.json for claude_local agents and in opencode.json for opencode_local agents.

Infrastructure Policy

Container images: Push to ghcr.io only. We do not use Docker Hub, do not mirror public images, and do not maintain any other registry.
Dependency updates: Managed by Mend Renovate. We do not use Dependabot — never enable it, never create .github/dependabot.yml, never reference it in workflows or docs.

Key Operational Notes

Prompt wipe on adapter switch: Switching an agent's adapter in the Paperclip UI wipes promptTemplate. Always restore from this repo after any adapter switch.
Regina (claude_local adapter): Uses claude_local with claude-sonnet-4-6 and high effort. Reads prompt via instructionsFilePath.
opencode_local agents (CMO, Gandalf, Hugh, Patty): UI saves wipe env and model. The prompt field always appears blank in the UI but works correctly in the DB. They do not use instructionsFilePath — prompts must be restored via DB patch (concatenate AGENTS.md + SOUL.md + HEARTBEAT.md).
Prompts can be restored via kubectl exec against the Paperclip Postgres DB (see COMPANY.md for the command).
This repo is read-only to agents — only the board may approve and merge changes to agent configurations and prompts. Always include cc @cpfarhood at the bottom of any PR body.

Conventions

Agent prompts are split across AGENTS.md (bootstrap), SOUL.md (persona), and HEARTBEAT.md (execution)
Adapters: claude_local (CEO, CTO, VP Product, Regina), opencode_local (CMO, Gandalf, Hugh, Patty)
Agents interact via Paperclip issues (pnpm paperclipai issue ...) and GitHub PRs/issues (gh ...)
Org hierarchy: CEO (Countess) → CTO (Nancy) + CMO (Addison) → Engineers + Marketing
GitHub Actions CI uses self-hosted ARC runners: runs-on: runners-privilegedescalation

PR Workflow (mandatory order)

CI passes (lint, types, unit tests)
Patty (UAT) validates E2E against privilegedescalation-dev
Regina (QA) reviews code — test coverage, regressions, edge cases
Nancy (CTO) reviews — architecture, code quality, security
Countess (CEO) merges — only after UAT + QA + CTO have all approved

Each stage gates the next. No agent merges their own PRs. See POLICIES.md for full details.

4.3 KiB Raw Permalink Blame History