From 8074163b1b5190c3ceae324e4b4e452abe159b3d Mon Sep 17 00:00:00 2001
From: Chris Farhood <chris@farhood.org>
Date: Thu, 23 Apr 2026 22:23:52 -0400
Subject: [PATCH] refinement

---
 CLAUDE.md                        | 34 ++++++++++++++++++++
 skills/coding-standards/SKILL.md | 54 ++++++++++++++++++++++++++++++++
 skills/sdlc/SKILL.md             |  2 +-
 3 files changed, 89 insertions(+), 1 deletion(-)
 create mode 100644 CLAUDE.md
 create mode 100644 skills/coding-standards/SKILL.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..752dd17
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,34 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Purpose
+
+This is the **Privileged Escalation org-level repository**. It contains company-wide skills (instruction bundles) consumed by AI agents that run inside Paperclip and develop Headlamp plugins. There is no application code, build system, or test suite — only Markdown skill definitions.
+
+## Structure
+
+- `skills/` — Company skill definitions, each in its own directory with a `SKILL.md` file
+  - `skills/safety/SKILL.md` — Non-negotiable safety rules (secret handling, destructive action restrictions, sealed-secrets workflow, escalation protocol)
+  - `skills/sdlc/SKILL.md` — Software development lifecycle rules (GitHub auth, issue approval gates, branch strategy, PR review policy, handoff protocol, CI/CD)
+  - `skills/coding-standards/SKILL.md` — Headlamp plugin development conventions (stack, commands, registration API, shared libraries)
+
+## Skill File Format
+
+Each skill is a Markdown file with YAML frontmatter containing `name` and `description` fields:
+
+```markdown
+---
+name: skill-name
+description: >
+  One-line description of what the skill covers.
+---
+
+# Skill Title
+
+Content...
+```
+
+## Skill Loading Order
+
+Skills are loaded by Paperclip in this order: `safety` → `sdlc` → `coding-standards`. Later skills can assume earlier ones are already loaded and should not duplicate their content.
diff --git a/skills/coding-standards/SKILL.md b/skills/coding-standards/SKILL.md
new file mode 100644
index 0000000..1c121d0
--- /dev/null
+++ b/skills/coding-standards/SKILL.md
@@ -0,0 +1,54 @@
+---
+name: coding-standards
+description: >
+  Coding standards for Privileged Escalation. Covers Headlamp plugin
+  development workflow, registration API, and shared libraries.
+---
+
+# Coding Standards
+
+## Headlamp Plugins
+
+All plugins extend [Headlamp](https://headlamp.dev/docs/latest/development/plugins/getting-started), a Kubernetes dashboard with a plugin system.
+
+- **Language:** TypeScript + React 18, MUI v5
+- **Scaffolding:** `npx --yes @kinvolk/headlamp-plugin create <plugin-name>`
+- **Entry point:** `src/index.tsx`
+- **Linting:** ESLint via `@headlamp-k8s/eslint-config` + Prettier
+- **Testing:** Vitest + React Testing Library
+
+### Plugin Commands
+
+Run from the plugin directory:
+
+| Command | Purpose |
+|---|---|
+| `npm run start` | Dev mode with hot reload |
+| `npm run build` | Production build (`dist/main.js`) |
+| `npm run format` | Prettier format |
+| `npm run lint` | ESLint check |
+| `npm run lint-fix` | ESLint auto-fix |
+| `npm run tsc` | Typecheck |
+| `npm run test` | Vitest tests |
+
+### Registration API
+
+Import from `@kinvolk/headlamp-plugin/lib`:
+
+- `registerAppBarAction()` — add components to the nav bar
+- `registerRoute()` — create new pages
+- `registerSidebarEntry()` — add sidebar items
+- `registerDetailsViewSection()` — extend resource detail views
+- `registerPluginSettings()` — add plugin configuration UI
+
+### K8s API Access
+
+```typescript
+import { K8s } from '@kinvolk/headlamp-plugin/lib';
+const [pods, error] = K8s.ResourceClasses.Pod.useList();
+```
+
+### Shared Libraries
+
+These are provided by Headlamp at runtime — **do not bundle them**:
+React, React Router, Redux, MUI, Lodash, Monaco Editor, Notistack, Iconify.
diff --git a/skills/sdlc/SKILL.md b/skills/sdlc/SKILL.md
index 9c01112..ebb79bf 100644
--- a/skills/sdlc/SKILL.md
+++ b/skills/sdlc/SKILL.md
@@ -72,4 +72,4 @@ Every handoff requires ALL THREE steps:
 ## CI/CD
 
 - CI runs on self-hosted ARC runners: `runs-on: runners-privilegedescalation`
-- Only Hugh Hackman has write access to `.github/workflows/` files
+- Only Hugh Hackman has write access to `.github/workflows/` files
\ No newline at end of file