Compare commits

..

23 Commits

Author SHA1 Message Date
Chris Farhood 629261625c Remove antipattern content from UAT skill
Strip "What UAT Is NOT" section per board feedback on PRI-1487.
Focus skill on positive guidance only.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-14 05:09:28 +00:00
Chris Farhood 3abfe53a1e Refactor UAT skill: delegate to UAT_PLAYBOOK.md per plugin
- Rewrite skills/uat/SKILL.md to be a general UAT overview that
  delegates per-plugin test procedures to UAT_PLAYBOOK.md in each
  plugin repository (authoritative source of truth)
- Add "What UAT Is NOT" section to explicitly prevent GitHub-browsing
  anti-pattern
- Update SDLC skill to require UAT_PLAYBOOK.md as a required deliverable
  alongside code changes affecting plugin testing
- Create UAT_PLAYBOOK.md in sealed-secrets and rook plugin repos

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-14 05:07:28 +00:00
Chris Farhood c041da4847 Add dedicated UAT skill with plugin testing procedures
- Add skills/uat/SKILL.md with concrete testing procedures for all 7 Headlamp plugins
- Update SDLC skill to reference the new uat skill for detailed procedures
- Fix namespace reference: UAT runs in headlamp-uat namespace, not privilegedescalation

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-14 03:11:28 +00:00
Chris Farhood fe3b4b90d7 docs(product-context): add headlamp-argocd-plugin to plugin inventory
Plugin existed on GitHub but was missing from the skill inventory, causing
it to be omitted from UAT gap analysis. Count updated from 6 to 7.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-14 01:22:24 +00:00
Chris Farhood 40a8f3d773 Fix SDLC skill: require UUID stage/participant IDs, clarify Reviewers UI field
The previous commit used string IDs like "qa-review" for execution policy
stages, but the API requires UUIDs and rejects non-UUID values. Also
renamed the section to "Issue Reviewers and Approvers" to match the UI
field names that agents need to populate.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-12 00:04:46 +00:00
Chris Farhood b5aa2b54a0 Add 'Issue Handoff via Execution Policy' section to SDLC skill
- Added new section explaining how to configure executionPolicy for automated reviewer handoffs
- Documented Pipeline A execution policy with QA and UAT stages
- Documented Pipeline B execution policy with single QA stage
- Explained triggering handoffs via in_review status
- Referenced Paperclip API reference for full schema

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-11 23:31:52 +00:00
Chris Farhood bfe02545e5 Remove handoff protocol and status semantics from SDLC skill
These are Paperclip platform mechanics already covered by the
Paperclip skill. The SDLC skill should only contain development
process rules, not platform API usage patterns.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-11 21:45:04 +00:00
Chris Farhood 0641848c4b Overhaul SDLC to three-branch promotion model
Replace the 5-stage pipeline (CI→UAT→QA→CTO→CEO) with a three-branch
promotion chain: dev (engineer self-merge) → uat (QA gates) → main
(UAT gates). Removes CTO review stage, CEO merge bottleneck, and SLA
timelines. Each gate owner has merge authority.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-11 21:40:54 +00:00
Chris Farhood 40caf8cfee Remove SLA section from SDLC skill and diagram
SLA timelines are meaningless to agents operating in heartbeats.
Removed the 48-hour PR review SLA from SKILL.md and the SLA
gantt chart from sdlc-diagram.md.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-11 20:56:17 +00:00
Chris Farhood da86aa7754 Add SDLC pipeline Mermaid diagram
Visualizes both pipelines (A: plugin, B: infra), the board approval
gate, PR review SLA, handoff protocol, and issue status lifecycle.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-11 20:54:22 +00:00
privilegedescalation-engineer[bot] b1e2000542 fix: restore CI workflow with markdownlint config (#63)
- Restore .github/workflows/ci.yaml that was deleted in April cleanup
- Add .markdownlint.yaml with relaxed rules for skill files
- Fix MD040 error in skills/sdlc/SKILL.md (add language to code block)
- Allows line lengths > 80, emphasis-as-headings, compact tables

Fixes CI failures on 'Merge POLICIES.md content into agent instruction bundles' commit.

Co-authored-by: Chris Farhood <chris@farhood.org>
Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-05-11 20:22:24 +00:00
Chris Farhood d4a6141986 Add non-negotiable rule: agents must never change other agents' model configs
Board directive (PRI-1245): agents suggesting or making model changes for
other agents due to quota exhaustion is explicitly forbidden. Quota issues
must be escalated to the board.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-11 19:30:03 +00:00
Chris Farhood d077c62bcb Improve CI health check script with enhanced monitoring
Enhanced the ci-health-check.sh script to:
- Add stale repo detection (repos with no updates in 30+ days)
- Add CI workflow configuration checks
- Add color-coded output for better readability
- Track multiple failure types (CI failures, stale repos, no CI)
- Provide clearer summary reporting
- Increase CRITICAL_THRESHOLD to 3 for better filtering

This enables proactive monitoring of both CI health and repository
maintenance status across all privilegedescalation repos.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-11 18:48:23 +00:00
Chris Farhood 8840bd874d Fix: Disable MD004 unordered list style rule in markdownlint
- Skill files use dashes for unordered lists, but markdownlint expects asterisks
- Disable MD004 to allow both dash and asterisk styles
- Aligns with existing exceptions for MD013, MD036, and MD060

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-11 18:33:02 +00:00
Chris Farhood 4c779823a0 Add CI health check script for automated failure detection
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-11 18:28:09 +00:00
Chris Farhood 496be01898 fix: restore CI workflow with markdownlint config
- Restore .github/workflows/ci.yaml that was deleted in April cleanup
- Add .markdownlint.yaml with relaxed rules for skill files
- Fix MD040 error in skills/sdlc/SKILL.md (add language to code block)
- Allows line lengths > 80, emphasis-as-headings, compact tables

Fixes CI failures on 'Merge POLICIES.md content into agent instruction bundles' commit.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-11 18:28:09 +00:00
Chris Farhood 64269836f2 Merge pull request #59 from privilegedescalation/gandalf/safety-anti-impersonation-rules 2026-05-09 12:43:01 -04:00
Chris Farhood a03256c231 Update safety skill: add anti-impersonation and role-boundary rules
Following PRI-737 investigation, add two rules to skills/safety/SKILL.md:

1. Anti-impersonation rule: agents must never sign, attribute, or present
   GitHub comments, PR reviews, or external communications as another
   agent. Every comment must accurately identify the authoring agent.

2. Role-boundary rule for GitHub actions: agents must only post GitHub PR
   comments and reviews within their defined SDLC role (engineer, QA, UAT,
   CTO, CEO). An agent must not post a review type belonging to another
   role, even if that role's agent has not yet completed its review.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-09 16:16:22 +00:00
Chris Farhood 1ebc0b0d89 Merge pull request #62 from privilegedescalation/countess/agent-process-review 2026-05-09 11:46:01 -04:00
Chris Farhood 6930b7a258 Optimize SDLC and coding-standards skills, remove duplication
SDLC skill (250 → ~127 lines):
- Remove Hugh-exclusive .github/workflows/ language; engineers share access
- Condense 48-hour SLA from 38 to 8 lines
- Replace verbose 5-stage pipeline description with compact diagrams
- Condense handoff protocol from 17 to 5 lines
- Remove status transition rules table (redundant with handoff protocol)
- Remove agent roster (agents have UUIDs in their own AGENTS.md)
- Remove work distribution section (redundant with agent instructions)

Coding-standards skill:
- Add SemVer, ArtifactHub distribution, ghcr.io registry rules
- Add Renovate/Dependabot, no-package-mirrors, npm-audit rules
- These were previously only in individual AGENTS.md files

Part of PRI-1094 — agent and process review.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-09 15:29:08 +00:00
Chris Farhood d69f5e4bd4 cleanup 2026-05-09 07:53:46 -07:00
privilegedescalation-ceo[bot] b7335c078e Merge pull request #61 from privilegedescalation/feat/product-context-skill
Add product-context skill
2026-05-09 02:42:34 +00:00
Chris Farhood 8b13f024e5 Add product-context skill extracted from Karen's AGENTS.md
Extracts the product context section (plugin portfolio, target users,
competitive landscape, evaluation framework, feature spec template)
into a version-controlled company skill at skills/product-context/SKILL.md.
Updates CLAUDE.md with skill documentation and loading order.

Part of PRI-1094 — agent and process review.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-05-09 00:50:27 +00:00
17 changed files with 574 additions and 192 deletions
-1
View File
@@ -1 +0,0 @@
ghs_n2DXnoj38RccFYNlzH18XQ739bhr8e2w4BZK
-17
View File
@@ -1,17 +0,0 @@
# The current version of the config schema
version: 1
# What protocol to use when performing git operations. Supported values: ssh, https
git_protocol: https
# What editor gh should run when creating issues, pull requests, etc. If blank, will refer to environment.
editor:
# When to interactively prompt. This is a global config that cannot be overridden by hostname. Supported values: enabled, disabled
prompt: enabled
# A pager program to send command output to, e.g. "less". If blank, will refer to environment. Set the value to "cat" to disable the pager.
pager:
# Aliases allow you to create nicknames for gh commands
aliases:
co: pr checkout
# The path to a unix socket through which send HTTP connections. If blank, HTTP traffic will be handled by net/http.DefaultTransport.
http_unix_socket:
# What web browser gh should use when opening URLs. If blank, will refer to environment.
browser:
-12
View File
@@ -1,12 +0,0 @@
github.com:
users:
privilegedescalation-engineer[bot]:
oauth_token: ghs_n2DXnoj38RccFYNlzH18XQ739bhr8e2w4BZK
privilegedescalation-ceo[bot]:
oauth_token: ghs_K7fsAgb8nVATb7zFV5VoZLUaRExyOX3uPkn3
privilegedescalation-cto[bot]:
oauth_token: ghs_OK6yqSB45aMkas1g5zgJKEgh2CoVH42JLuwu
privilegedescalation-qa[bot]:
oauth_token: ghs_ppIO9dekMz5A5uAqCPERzj5bk9jBHU2Bf0sL
user: privilegedescalation-engineer[bot]
oauth_token: ghs_n2DXnoj38RccFYNlzH18XQ739bhr8e2w4BZK
+17
View File
@@ -0,0 +1,17 @@
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Lint Markdown
uses: DavidAnson/markdownlint-cli2-action@v19
with:
globs: "**/*.md"
+15
View File
@@ -0,0 +1,15 @@
# Markdownlint configuration for the org repo.
# Skill files intentionally use longer lines and emphasis-as-headings.
# Allow these patterns for skills directory.
# Line length is disabled for skill documentation
MD013: false
# Emphasis used as headings is allowed in skill files
MD036: false
# Compact table style is allowed
MD060: false
# Unordered list style (dash vs asterisk) is flexible
MD004: false
+2 -1
View File
@@ -12,6 +12,7 @@ This is the **Privileged Escalation org-level repository**. It contains company-
- `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)
- `skills/product-context/SKILL.md` — Product context (plugin portfolio, target users, competitive landscape, evaluation framework, feature spec template)
## Skill File Format
@@ -31,4 +32,4 @@ 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.
Skills are loaded by Paperclip in this order: `safety``sdlc``coding-standards``product-context`. Later skills can assume earlier ones are already loaded and should not duplicate their content.
Submodule headlamp-rook-plugin deleted from 79eaa6910d
Submodule headlamp-sealed-secrets-plugin deleted from 143b2c36e0
-1
View File
@@ -1 +0,0 @@
test
Submodule org deleted from c420e1543f
+106
View File
@@ -0,0 +1,106 @@
#!/bin/bash
# CI Health Check Script
# Checks CI health across all privilegedescalation repos and reports failures
set -euo pipefail
# Configuration
ORG="privilegedescalation"
MAX_AGE_DAYS=30
CRITICAL_THRESHOLD=3 # Number of consecutive failures to consider critical
# Colors for output
RED='\033[0;31m'
YELLOW='\033[1;33m'
GREEN='\033[0;32m'
NC='\033[0m' # No Color
# Repos to monitor
REPOS=(
"org"
"infra"
"headlamp-sealed-secrets-plugin"
"headlamp-rook-plugin"
"headlamp-intel-gpu-plugin"
"headlamp-kube-vip-plugin"
"headlamp-tns-csi-plugin"
"headlamp-argocd-plugin"
"headlamp-polaris-plugin"
)
echo "=== CI Health Check for $ORG ==="
echo "Generated: $(date -u +"%Y-%m-%d %H:%M:%S UTC")"
echo ""
# Track issues
FAILURES=()
STALE_REPOS=()
NO_CI_REPOS=()
for repo in "${REPOS[@]}"; do
echo "Checking $repo..."
# Check for stale repos
last_updated=$(gh repo view "$ORG/$repo" --json updatedAt --jq '.updatedAt' 2>/dev/null || echo "unknown")
if [[ "$last_updated" != "unknown" ]]; then
last_updated_date=$(date -d "$last_updated" +%s 2>/dev/null || echo "0")
cutoff_date=$(date -d "$MAX_AGE_DAYS days ago" +%s)
if [[ "$last_updated_date" -lt "$cutoff_date" ]]; then
STALE_REPOS+=("$repo (last updated: $last_updated)")
echo -e " ${YELLOW}⚠ Stale repo${NC}"
fi
fi
# Check for CI workflows
workflow_count=$(gh api repos/"$ORG/$repo"/actions/workflows 2>/dev/null | jq -r '.total_count' || echo "0")
if [[ "$workflow_count" -eq 0 ]]; then
NO_CI_REPOS+=("$repo")
echo -e " ${YELLOW}⚠ No CI workflows configured${NC}"
continue
fi
# Check recent CI runs (exclude approval gates)
recent_failures=$(gh run list --repo "$ORG/$repo" --limit 10 \
--json status,conclusion,name \
| jq -r '.[] | select(.conclusion == "failure") | select(.name | contains("CI") or contains("E2E") or contains("ci") or contains("e2e")) | .conclusion' \
| wc -l)
if [[ "$recent_failures" -ge "$CRITICAL_THRESHOLD" ]]; then
FAILURES+=("$repo: $recent_failures recent CI/E2E failures")
echo -e " ${RED}$recent_failures recent CI/E2E failures${NC}"
else
echo -e " ${GREEN}✓ CI healthy${NC}"
fi
done
# Summary
echo ""
echo "=== Summary ==="
if [[ ${#FAILURES[@]} -eq 0 && ${#STALE_REPOS[@]} -eq 0 && ${#NO_CI_REPOS[@]} -eq 0 ]]; then
echo -e "${GREEN}All systems healthy!${NC}"
exit 0
else
if [[ ${#FAILURES[@]} -gt 0 ]]; then
echo -e "${RED}CI Failures:${NC}"
for failure in "${FAILURES[@]}"; do
echo " - $failure"
done
fi
if [[ ${#STALE_REPOS[@]} -gt 0 ]]; then
echo -e "${YELLOW}Stale Repos (no updates in $MAX_AGE_DAYS+ days):${NC}"
for stale in "${STALE_REPOS[@]}"; do
echo " - $stale"
done
fi
if [[ ${#NO_CI_REPOS[@]} -gt 0 ]]; then
echo -e "${YELLOW}Repos without CI:${NC}"
for no_ci in "${NO_CI_REPOS[@]}"; do
echo " - $no_ci"
done
fi
exit 1
fi
+14 -1
View File
@@ -2,7 +2,8 @@
name: coding-standards
description: >
Coding standards for Privileged Escalation. Covers Headlamp plugin
development workflow, registration API, and shared libraries.
development workflow, registration API, shared libraries, versioning,
dependency management, container registry, and distribution policy.
---
# Coding Standards
@@ -52,3 +53,15 @@ const [pods, error] = K8s.ResourceClasses.Pod.useList();
These are provided by Headlamp at runtime — **do not bundle them**:
React, React Router, Redux, MUI, Lodash, Monaco Editor, Notistack, Iconify.
## Versioning & Distribution
- **All releases use SemVer.** ArtifactHub requires SemVer for Headlamp plugin packages — no CalVer, no custom schemes.
- **Plugin distribution is ArtifactHub only.** Plugins are installed through Headlamp's native plugin installer sourced from ArtifactHub. No Helm charts, install scripts, or custom install mechanisms.
- **Container images go to `ghcr.io` only.** Never Docker Hub, never mirror public images, never reference any other registry.
## Dependency Management
- **Dependency updates are owned by Mend Renovate.** Never enable Dependabot, never create `.github/dependabot.yml`, never reference Dependabot in workflows or docs.
- **No package mirrors.** Never set up, configure, or reference package mirrors or proxies (npm, pip, Maven, container, etc.). Always use upstream registries directly.
- **Security scanning uses local tools.** Run `npm audit` or `pnpm audit` for vulnerability scanning. Do not use the GitHub vulnerability alerts API.
+119
View File
@@ -0,0 +1,119 @@
---
name: product-context
description: >
Product context for Privileged Escalation. Covers current plugin portfolio,
target users, competitive landscape, plugin evaluation framework, and feature
spec template.
---
# Product Context
Load this section when triaging feature requests, evaluating new plugin proposals, or writing specs.
## Current plugin portfolio
| Plugin | Repo | What it does | Status |
| ------------------ | -------------------------------- | ----------------------------------------------- | ------ |
| **Polaris** | `headlamp-polaris-plugin` | Kubernetes best practice validation and scoring | Active |
| **Kube-VIP** | `headlamp-kube-vip-plugin` | Kube-VIP load balancer management | Active |
| **Rook/Ceph** | `headlamp-rook-plugin` | Rook-Ceph storage cluster monitoring | Active |
| **Sealed Secrets** | `headlamp-sealed-secrets-plugin` | Bitnami Sealed Secrets management | Active |
| **Intel GPU** | `headlamp-intel-gpu-plugin` | Intel GPU device plugin monitoring | Active |
| **TrueNAS CSI** | `headlamp-tns-csi-plugin` | TrueNAS SCALE CSI driver monitoring | Active |
| **Argo CD** | `headlamp-argocd-plugin` | Argo CD application delivery management | Active |
All plugins distributed via **ArtifactHub**, installed through Headlamp's native plugin installer only.
## Target users
**Primary: The Platform Engineer**
* Manages 1-50 Kubernetes clusters, mid-size company (100-2000 employees)
* Pain point: "I have 15 tools open to monitor my clusters. I want one dashboard that shows me everything."
* Very high tech comfort. Knows Kubernetes deeply. Will read your source code.
* Will adopt a plugin in 5 minutes if it solves a real problem. Will drop it in 5 seconds if it's buggy or doesn't add value over `kubectl`.
**Secondary: The DevOps Lead / SRE Manager**
* Manages a platform team, responsible for cluster health and reliability.
* Wants plugins that visualize what matters and surface problems proactively — NOT another monitoring tool.
**Anti-persona: The Application Developer**
App developers care about their deployments, not the cluster. Features like "show me my pod logs" are already in Headlamp core. Don't build for them.
## Scope
**In scope**
* Headlamp plugins that visualize and manage specific Kubernetes ecosystem tools
* Plugins that surface operational insights not available in Headlamp core
* Plugins for CNCF projects and widely-adopted K8s ecosystem tools
* ArtifactHub packaging and distribution
**Explicitly out of scope**
* Plugins that duplicate Headlamp core functionality
* Non-Kubernetes tools
* Hosted/SaaS versions of plugins
* Helm-based or sidecar-based plugin installation
* Custom Headlamp forks
* Monitoring/alerting backends (we visualize, we don't collect metrics)
* Multi-cluster management
* CLI tools
## Competitive landscape
| Competitor | Where PRI differs |
| -------------------------------- | ----------------------------------------------------------------------------------- |
| **Headlamp core** | We extend it, not compete. If a feature belongs in core, contribute upstream. |
| **Lens** | Heavy, desktop-only, commercial. We make web-based, open source Headlamp better. |
| **k9s** | Different modality (TUI vs web). Not competitive. |
| **Komodor / Kubecost / Robusta** | Standalone products. Our plugins bring their insights INTO Headlamp. Complementary. |
PRI's moat: leading third-party Headlamp plugin developer. Plugins are free, open source, on ArtifactHub.
## Plugin evaluation framework
1. **Is there a widely-adopted K8s ecosystem tool that lacks Headlamp visibility?**
* Fewer than 1,000 GitHub stars or in alpha → too early. Close with "revisit when more mature."
* Already has a Headlamp plugin → duplicate. Close.
2. **Does the plugin add value over `kubectl` + the tool's own CLI/UI?**
* "It shows the same thing but in Headlamp" → weak value prop. Good plugins correlate data, surface problems proactively, simplify complex operations.
3. **Can Gandalf build and maintain it?**
* One engineer can maintain ~6-8 plugins at current complexity. We're at 7 now. New plugins mean either dropping an existing one or hiring.
4. **Is it installable via ArtifactHub without extras?**
* Plugin requires CRDs/RBAC/cluster resources installed separately → degraded experience.
* Unacceptable: plugin requires its own operator or sidecar.
**Priority tiers**
* **P0**: Bugs in existing plugins that break functionality or produce incorrect data
* **P1**: Enhancements to existing plugins users are requesting
* **P2**: New plugins for high-value K8s tools with clear user demand
* **P3**: Speculative plugins, cross-plugin features, UX experiments
## Feature spec template
```markdown
## Problem
What operational visibility or capability is missing? Who needs it? What do they do today instead?
## Proposed Solution
What should the plugin show or enable that isn't available today?
## Acceptance Criteria
- [ ] Plugin displays...
- [ ] User can...
- [ ] Data is accurate when compared to `kubectl` / native CLI output
- [ ] Works with [tool name] version X.Y+
- [ ] Installable via ArtifactHub without additional cluster-level setup
- [ ] Has unit tests covering core display logic
## Out of Scope for This Issue
## Dependencies
What must exist in the cluster for this plugin to work? (CRDs, operators, RBAC)
## Priority
P0/P1/P2/P3 with one-sentence justification.
```
+13 -1
View File
@@ -2,7 +2,8 @@
name: safety
description: >
Non-negotiable safety rules for all agents at Privileged Escalation. Covers
secret handling, destructive command restrictions, sealed-secrets workflow, and
secret handling, destructive command restrictions, sealed-secrets workflow,
anti-impersonation rules, role-boundary rules for GitHub actions, and
escalation protocol when uncertain.
---
@@ -21,6 +22,17 @@ The following rules apply to all agents at Privileged Escalation without excepti
* **Do not use `kubectl create` in production.**
The `privilegedescalation` namespace is Flux-managed. Secret changes go through the SealedSecrets workflow, committed to `privilegedescalation/infra`.
* **Never impersonate another agent or human.** Agents must never sign, attribute, or present GitHub comments, PR reviews, or any external communications as another agent. Every comment must accurately identify the authoring agent. Signing as another agent — even when forwarding their work — is a process violation.
* **Post GitHub comments only within your defined SDLC role.** An agent must not post a review type that belongs to another role, even if that role's agent has not yet completed its review:
- **Engineer bot** posts: implementation comments, CI results
- **QA bot** posts: QA reviews
- **UAT bot** posts: UAT reviews
- **CTO bot** posts: CTO reviews and approvals
- **CEO bot** posts: merge confirmations only
* **Never change another agent's model configuration.** No agent may suggest, request, or execute a change to any other agent's model settings — including for quota exhaustion, cost optimization, or any other reason. Quota issues must be escalated to the board. This is a non-negotiable board directive.
## If you are unsure
If you are unsure whether an action is safe, stop. Post a comment on the Paperclip issue explaining what you are about to do and why you are uncertain, set the issue to `blocked`, and escalate to your manager. Do not guess.
+89 -155
View File
@@ -3,8 +3,7 @@ name: sdlc
description: >
Software development lifecycle rules for Privileged Escalation. Covers GitHub
issue approval gates, authentication, branch strategy, PR review policy,
pipeline stages, agent roster, handoff protocol, status semantics, CI/CD,
security review, and work distribution.
pipeline stages, CI/CD, and security review.
---
# Software Development Lifecycle
@@ -19,7 +18,7 @@ Token expires after ~1 hour. Re-invoke the skill to regenerate if needed.
**If a task originated from GitHub (`originKind: "github"` in the issue data), do not begin any work.** Immediately create a `request_board_approval`:
```
```json
POST /api/companies/{companyId}/approvals
{
"type": "request_board_approval",
@@ -38,13 +37,15 @@ Set the issue to `blocked` until `PAPERCLIP_APPROVAL_STATUS` confirms approval.
## Branch Strategy
All plugin repositories use a single long-lived branch:
All plugin repositories use three long-lived branches representing a promotion chain:
| Branch | Environment | Who merges |
|--------|-------------|------------|
| `main` | Production | CEO (Countess von Containerheim) after triple approval |
| Branch | Environment | Owner | Who merges to it |
|--------|-------------|-------|-----------------|
| `dev` | Development | Engineer | Engineer self-merges after CI passes |
| `uat` | User Acceptance Testing | QA (Regression Regina) | QA merges after code review |
| `main` | Production | UAT (Pixel Patty) | UAT merges after browser validation |
**Engineers always target `main` via feature branches** — never push directly.
**Engineers target `dev` via feature branches** — never push directly to any long-lived branch.
Feature branches follow the convention: `<agent-name>/<short-description>` (e.g., `gandalf/add-sealed-secrets-list`).
@@ -60,190 +61,123 @@ gh pr create --title "..." --body "... cc @cpfarhood"
**Do not approve a PR with failing tests, type errors, or no coverage for new code.**
Requires **3 approving GitHub reviews** before the CEO merges:
### Promotion chain
1. **UAT (Pixel Patty)** — E2E browser testing against `headlamp-dev`
2. **QA (Regression Regina)** — code-level review: test coverage, regressions, edge cases
3. **CTO (Null Pointer Nancy)** — architecture alignment, code quality, security
Each promotion is a PR reviewed and merged by its gate owner:
**Review order is mandatory: CI → UAT → QA → CTO → CEO merge.** Each stage gates the next. No agent merges their own PRs.
1. **feature → dev** — Engineer self-merges after CI passes. No review required. Dev is for validation, not quality gates.
2. **dev → uat** — QA (Regression Regina) reviews code quality: test coverage, regressions, edge cases. QA merges to `uat` after approval.
3. **uat → main** — UAT (Pixel Patty) validates the deployed application via Playwright browser testing. UAT merges to `main` after validation passes. For detailed UAT testing procedures, see the `uat` company skill.
## 48-Hour PR Review SLA (Binding)
**Playbook maintenance:** When plugin testing procedures change (new features, changed UI, different access paths), the engineer must update the plugin's `UAT_PLAYBOOK.md` in the same PR. This is a required deliverable alongside the code change — not optional cleanup.
**MANDATORY: Every open PR must receive its first review within 48 hours of submission. No exceptions.**
### SLA Assignments & Responsibility
- **0-24 hours:** Assigned reviewer must begin review (or explicitly hand off)
- **24-48 hours:** Assigned reviewer must complete review or be flagged for SLA violation
- **48+ hours:** SLA violation is documented and escalated
### Assigned Reviewers & Accountability
1. **UAT (Pixel Patty)** — responsible for all PRs needing E2E testing
- SLA: Initial E2E test within 48 hours of open
2. **QA (Regression Regina)** — responsible for code review after UAT pass
- SLA: Code review within 48 hours of UAT approval
3. **CTO (Null Pointer Nancy)** — responsible for architecture/security review after QA pass
- SLA: Architecture review within 48 hours of QA approval
4. **CEO (Countess von Containerheim)** — responsible for SLA enforcement
- Enforces SLA via daily audit and escalation
### Escalation Protocol (CEO Responsibility)
- **At 24 hours:** CEO tags reviewer with automated comment and surfaces PR in daily status
- **At 48 hours:** CEO blocks PR from merge queue; escalates to reviewer's manager (CTO for most)
- **At 72+ hours:** If critical-path, PR blocks next release until review completes or reviewer hands off
### Exception Policy
If a reviewer cannot meet SLA:
- They must explicitly hand off to another reviewer within the 48-hour window
- If hand-off doesn't happen, the SLA breach is documented and escalated
- Rare exceptions require board approval (documented in PR)
### Enforcement Mechanism
CEO creates daily automated report of SLA status and escalates immediately when thresholds breach. This is non-negotiable work.
**Each gate owner has merge authority.** No separate merge step by another role. No agent merges their own code to `uat` or `main` — only the gate owner merges promotions they review.
## Pipeline
**Two pipelines based on change type:**
### Pipeline A: Plugin/Feature Changes
### Pipeline A: Plugin/Feature Changes (User-Facing Code)
```
CI: Engineer opens PR → CI runs (lint, types, unit tests)
UAT: Pixel Patty validates E2E in headlamp-dev
QA: Regression Regina reviews code quality and test coverage
CTO: Null Pointer Nancy reviews architecture and security
Merge: Countess von Containerheim merges after all approvals
Engineer → PR to dev → self-merge → deploys to dev
→ Engineer validates on dev
→ PR from dev → uat → QA reviews → QA merges
→ Deploys to UAT environment
→ PR from uat → main → UAT validates → UAT merges
→ Production
```
**Applies to:** Changes in `headlamp-*-plugin/` repos (plugin code, features, bug fixes)
Applies to changes in `headlamp-*-plugin/` repos (plugin code, features, bug fixes).
### Pipeline B: Infrastructure Changes (No UI Impact)
```
CI: Engineer opens PR → CI runs (lint, types, unit tests)
QA: Regression Regina reviews code and correctness (no E2E needed)
CTO: Null Pointer Nancy reviews architecture and security
Merge: Countess von Containerheim merges after all approvals
Engineer → PR to main → CI passes → QA reviews → QA merges
→ Production
```
**Applies to:** Changes in `.github/workflows/`, `infra/`, `org/` repos, and template repos (CI workflows, kustomize configs, RBAC manifests, deployment scripts)
**Rule:** If the PR contains ONLY infrastructure changes (no plugin code changes), use Pipeline B and skip UAT. Patty's time is reserved for user-facing feature testing.
Applies to changes in `.github/workflows/`, `infra/`, `org/` repos, and template repos. No UAT stage needed — infrastructure changes have no UI to validate.
**Detection:** If `git diff` shows changes only in `.github/`, `infra/`, `org/`, or deployment files → Pipeline B. If any `headlamp-*-plugin/` code changed → Pipeline A.
### Stage 1 — Engineer Opens PR
**Failure routing:** Any stage failure returns directly to the engineer via PR comments.
1. Engineer (Gandalf the Greybeard) creates a feature branch and opens a PR targeting `main`.
2. CI runs automatically: lint, type checks, unit tests.
3. CI must pass before any reviewer spends tokens. If CI fails, the engineer fixes it.
## Issue Reviewers and Approvers
### Stage 2 — UAT Review (Pipeline A Only)
Every Paperclip issue has **Reviewers** and **Approvers** fields visible in the UI sidebar. These are populated by setting `executionPolicy` when creating the issue. Without an execution policy, those fields show "None" and handoffs never trigger.
4. **Pipeline A only (user-facing changes):** Pixel Patty picks up PRs with passing CI.
5. **Pipeline B skips this:** Infrastructure PRs bypass UAT and go directly to QA.
6. Patty runs E2E browser testing against the deployed build in `headlamp-dev`.
7. Pass → hands off to QA. Fail → goes directly to engineer.
**All stage and participant `id` fields must be random UUIDs.** Generate them at issue-creation time (e.g. via `uuidgen` or your language's UUID library). Do not use descriptive strings — the API rejects non-UUID values.
### Stage 3QA Review
### Pipeline Aset reviewers on issue creation
7. Regression Regina picks up PRs that have passed both CI and UAT.
8. Regina reviews: test coverage, regressions, edge cases, code quality.
9. Pass → hands off to CTO. Fail → goes directly to engineer.
For plugin/feature work (Pipeline A), set a two-stage execution policy so QA and UAT appear as reviewers:
### Stage 4 — CTO Review
10. Null Pointer Nancy picks up PRs that have passed CI, UAT, and QA.
11. Nancy reviews: architecture alignment, code quality, security.
12. Approve → PR is ready for merge. Request changes → goes directly to engineer.
### Stage 5 — CEO Merge
13. Countess von Containerheim merges the PR after all three approvals (UAT + QA + CTO) and CI passing.
14. Reject → returns to CTO → engineer.
### Hierarchy Rules
- CTO rejections go directly to engineer (not through QA or UAT).
- UAT failures go directly to engineer (not through QA or UAT).
- QA failures go directly to engineer (not through QA or UAT).
- CEO rejections go to CTO, who cascades to engineer.
- The CTO is the single routing point for all failures and rejections to and from the CEO.
## Agent Roster
| Role | Agent | Paperclip UUID |
|------|-------|----------------|
| CEO | Countess von Containerheim | `498f4d36-8e5b-4114-8514-d0698a091bd5` |
| CTO | Null Pointer Nancy | `ed1eec37-f868-41b6-bc72-a3493bbce090` |
| Staff Engineer | Gandalf the Greybeard | `fc07dd00-c4c2-4fa0-9a18-dd6fbb1d1eb4` |
| QA Engineer | Regression Regina | `fd5dbec8-ddbb-4b57-9703-624e0ed90053` |
| UAT Engineer | Pixel Patty | `01ec02f7-70c2-4fa1-ac3f-2545f1237ac3` |
| VP Engineering Ops | Hugh Hackman | `2c97cff6-0f0b-4cff-967f-ca244eb2ef9b` |
| CMO | Kubectl Karen | `95314e13-bea7-459d-a637-92381dede759` |
## Handoff Protocol — Mandatory
Every handoff to another agent requires ALL THREE steps:
### Step 1 — Explicit Assignment
PATCH the issue with `assigneeAgentId: "<target-agent-uuid>"`.
@mentioning is NOT a handoff — the agent won't wake without explicit assignment.
### Step 2 — Status = `todo`
Every handoff sets `status: "todo"`. Never `in_review` — it doesn't appear in inbox-lite and the target agent won't wake.
### Step 3 — Release Checkout
```
POST /api/issues/{issueId}/release
Headers: Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
```bash
QA_STAGE_ID=$(uuidgen)
QA_PART_ID=$(uuidgen)
UAT_STAGE_ID=$(uuidgen)
UAT_PART_ID=$(uuidgen)
```
Without this release, the receiving agent cannot checkout the issue.
```json
"executionPolicy": {
"mode": "normal",
"commentRequired": true,
"stages": [
{
"id": "<QA_STAGE_ID>",
"type": "review",
"approvalsNeeded": 1,
"participants": [
{ "id": "<QA_PART_ID>", "type": "agent", "agentId": "fd5dbec8-ddbb-4b57-9703-624e0ed90053" }
]
},
{
"id": "<UAT_STAGE_ID>",
"type": "review",
"approvalsNeeded": 1,
"participants": [
{ "id": "<UAT_PART_ID>", "type": "agent", "agentId": "01ec02f7-70c2-4fa1-ac3f-2545f1237ac3" }
]
}
]
}
```
## Status Semantics
- Stage 1 reviewer: Regression Regina (`fd5dbec8-ddbb-4b57-9703-624e0ed90053`)
- Stage 2 reviewer: Pixel Patty (`01ec02f7-70c2-4fa1-ac3f-2545f1237ac3`)
| Status | Meaning |
|--------|---------|
| `backlog` | Not ready; parked or unscheduled |
| `todo` | Ready and actionable; not checked out |
| `in_progress` | Actively owned; enter by checkout only |
| `in_review` | Self-held only; awaiting external feedback |
| `blocked` | Cannot proceed; state blocker and who must act |
| `done` | Complete, no follow-up remains |
| `cancelled` | Intentionally abandoned |
### Pipeline B — single reviewer
**Never use `in_review` for handoffs.** It does not trigger inbox-lite and the receiving agent will not wake.
For infrastructure changes (Pipeline B), use one QA review stage:
## Status Transition Rules
```json
"executionPolicy": {
"mode": "normal",
"commentRequired": true,
"stages": [
{
"id": "<QA_STAGE_ID>",
"type": "review",
"approvalsNeeded": 1,
"participants": [
{ "id": "<QA_PART_ID>", "type": "agent", "agentId": "fd5dbec8-ddbb-4b57-9703-624e0ed90053" }
]
}
]
}
```
| Handoff | Correct Status |
|---------|----------------|
| Engineer → UAT (Patty) | `todo` |
| UAT (Patty) → QA (Regina) | `todo` |
| QA (Regina) → CTO (Nancy) | `todo` |
| CTO (Nancy) → CEO (Countess) | `todo` |
| Any failure → Engineer | `todo` |
| CEO rejection → CTO (Nancy) | `todo` |
| CTO (Nancy) → Engineer (fix) | `todo` |
### Triggering the handoff
When an engineer completes work and merges to `dev`, set the Paperclip issue status to `in_review`. This activates the execution policy and wakes the first reviewer. Each reviewer approves or requests changes through the normal Paperclip issue update flow — see the Paperclip skill's `references/api-reference.md` for details.
## CI/CD
- CI runs on self-hosted ARC runners: `runs-on: runners-privilegedescalation`
- Only Hugh Hackman has write access to `.github/workflows/` files
- All CI/CD workflow changes must be delegated to Hugh
- CI triggers on PRs to `dev`, `uat`, and `main` branches
- Engineers may modify `.github/workflows/` files directly via PR
- Runners scale to zero when idle and start automatically when a workflow triggers
## Security Review
Security review is handled as part of the CTO review stage. Null Pointer Nancy evaluates security concerns during her architecture and code quality review. There is no separate dedicated security review agent.
## Work Distribution
- All engineering and devops work is broken down and distributed by the CTO (Nancy).
- Engineers do not self-assign — the CTO triages, scopes, and assigns all implementation tasks.
- Hugh Hackman owns CI/CD, infrastructure, and pipeline work.
- Gandalf the Greybeard owns plugin implementation.
- Regression Regina owns QA review and test coverage.
- Pixel Patty owns UAT/E2E browser testing.
Security review is handled as part of the QA review stage. Regression Regina evaluates security concerns during her code quality review. There is no separate dedicated security review agent.
+135
View File
@@ -0,0 +1,135 @@
# SDLC Pipeline Diagram
## Full Lifecycle
```mermaid
flowchart TD
subgraph Origin["Task Origin"]
GH["GitHub Issue"]
PP["Paperclip Issue"]
end
subgraph Approval["Board Gate"]
BA{"Board Approval<br/>Required?"}
REQ["Request Board Approval<br/>→ Issue blocked"]
APPROVED["Approved"]
end
subgraph Detection["Pipeline Detection"]
DET{"Changed files?"}
PA["Pipeline A<br/>Plugin / Feature"]
PB["Pipeline B<br/>Infrastructure"]
end
subgraph PipelineA["Pipeline A: Plugin / Feature Changes"]
direction TB
A_ENG["Engineer writes code<br/>(Gandalf)"]
A_PR_DEV["PR → dev<br/>Engineer self-merges"]
A_CI_DEV{"CI Passes?"}
A_DEV["Deploys to dev<br/>Engineer validates"]
A_PR_UAT["PR dev → uat"]
A_QA["QA Review<br/>(Regression Regina)<br/>Code quality, test coverage"]
A_QA_PASS{"QA Approved?"}
A_QA_MERGE["QA merges to uat"]
A_UAT_DEPLOY["Deploys to UAT env"]
A_PR_MAIN["PR uat → main"]
A_UAT["UAT Review<br/>(Pixel Patty)<br/>Playwright browser validation"]
A_UAT_PASS{"UAT Approved?"}
A_UAT_MERGE["UAT merges to main"]
end
subgraph PipelineB["Pipeline B: Infrastructure Changes"]
direction TB
B_ENG["Engineer writes code<br/>(Gandalf / Hugh)"]
B_PR["PR → main"]
B_CI{"CI Passes?"}
B_QA["QA Review<br/>(Regression Regina)"]
B_QA_PASS{"QA Approved?"}
B_QA_MERGE["QA merges to main"]
end
subgraph Result["Outcome"]
PROD["Merged to main<br/>✓ Production"]
RETURNED["Returned to Engineer<br/>Fix and resubmit"]
end
%% Origin routing
GH --> BA
PP --> DET
BA -->|"originKind: github"| REQ
REQ -->|"PAPERCLIP_APPROVAL_STATUS"| APPROVED
BA -->|"originKind: other"| DET
APPROVED --> DET
%% Pipeline detection
DET -->|"headlamp-*-plugin/ code"| PA
DET -->|".github/, infra/, org/"| PB
%% Pipeline A flow
PA --> A_ENG --> A_PR_DEV --> A_CI_DEV
A_CI_DEV -->|"Pass"| A_DEV
A_CI_DEV -->|"Fail"| RETURNED
A_DEV --> A_PR_UAT --> A_QA --> A_QA_PASS
A_QA_PASS -->|"Approved"| A_QA_MERGE --> A_UAT_DEPLOY
A_QA_PASS -->|"Changes requested"| RETURNED
A_UAT_DEPLOY --> A_PR_MAIN --> A_UAT --> A_UAT_PASS
A_UAT_PASS -->|"Approved"| A_UAT_MERGE --> PROD
A_UAT_PASS -->|"Changes requested"| RETURNED
%% Pipeline B flow
PB --> B_ENG --> B_PR --> B_CI
B_CI -->|"Pass"| B_QA --> B_QA_PASS
B_CI -->|"Fail"| RETURNED
B_QA_PASS -->|"Approved"| B_QA_MERGE --> PROD
B_QA_PASS -->|"Changes requested"| RETURNED
RETURNED -->|"Fix and resubmit"| A_PR_DEV
RETURNED -->|"Fix and resubmit"| B_PR
%% Styling
classDef gate fill:#f9e4e4,stroke:#c0392b,color:#000
classDef pass fill:#e4f9e4,stroke:#27ae60,color:#000
classDef agent fill:#e4e9f9,stroke:#2980b9,color:#000
classDef decision fill:#fef9e7,stroke:#f39c12,color:#000
classDef deploy fill:#e8f4f8,stroke:#2c3e50,color:#000
class BA,A_CI_DEV,A_QA_PASS,A_UAT_PASS,B_CI,B_QA_PASS,DET decision
class A_QA,A_UAT,B_QA gate
class PROD pass
class A_ENG,B_ENG agent
class A_DEV,A_UAT_DEPLOY deploy
```
## Branch Promotion Chain
```mermaid
flowchart LR
subgraph Feature["Feature Branch"]
FB["gandalf/feature-name"]
end
subgraph Dev["dev branch"]
DEV["Engineer self-merges<br/>Deploys to dev env"]
end
subgraph UAT["uat branch"]
UATB["QA reviews & merges<br/>Deploys to UAT env"]
end
subgraph Main["main branch"]
MAIN["UAT validates & merges<br/>Deploys to production"]
end
FB -->|"PR + CI"| DEV
DEV -->|"PR + QA review"| UATB
UATB -->|"PR + UAT review"| MAIN
classDef dev fill:#fff3cd,stroke:#856404,color:#000
classDef uat fill:#cce5ff,stroke:#004085,color:#000
classDef prod fill:#d4edda,stroke:#155724,color:#000
class DEV dev
class UATB uat
class MAIN prod
```
+64
View File
@@ -0,0 +1,64 @@
---
name: uat
description: >
Functional UAT procedures for Privileged Escalation Headlamp plugins. Delegates per-plugin testing procedures to UAT_PLAYBOOK.md in each plugin repository.
---
# UAT Procedures
## Purpose
This skill defines **functional User Acceptance Testing** for all Privileged Escalation Headlamp plugins. UAT validates that plugins work correctly in the deployed environment — by loading plugins in a running Headlamp instance and exercising their features.
## Pipeline Stage
UAT is the final promotion gate before production: `uat → main`. Pixel Patty (UAT agent) validates the deployed application via Playwright browser testing before merging.
## Per-Plugin Testing Procedures
Detailed, up-to-date testing procedures for each plugin are maintained in the plugin's own repository at `UAT_PLAYBOOK.md`. This is the authoritative source — do not copy procedure details into this skill.
| Plugin | Repository |
|--------|------------|
| headlamp-polaris-plugin | `polaris` |
| headlamp-sealed-secrets-plugin | `sealed-secrets` |
| headlamp-intel-gpu-plugin | `intel-gpu` |
| headlamp-kube-vip-plugin | `kube-vip` |
| headlamp-tns-csi-plugin | `tns-csi` |
| headlamp-rook-plugin | `rook` |
| headlamp-argocd-plugin | `argocd` |
Each plugin's `UAT_PLAYBOOK.md` contains:
- Access path (sidebar entry or app bar location)
- Step-by-step test actions
- Expected results for each step
- Pass/fail criteria
- Artifact requirements (screenshots, console errors, environment info)
## General Process
For every `uat→main` promotion:
1. Open the Headlamp UAT instance in the browser
2. Confirm the plugin appears in the sidebar or app bar
3. Retrieve the plugin's `UAT_PLAYBOOK.md` from its repository
4. Execute the test steps in the playbook
5. Capture screenshots of the **running plugin** at each verification step
6. Check the browser console for errors
7. Post a structured test report (see Artifacts section)
## UAT Artifacts
For each plugin tested, the UAT report must include:
1. **Screenshots** of the plugin running in Headlamp — sidebar entry visible, main view loaded, at least one detail view
2. **Test checklist** — each step from the playbook marked pass/fail
3. **Console errors** — any browser console errors observed (attach screenshot if present)
4. **Environment** — Headlamp version, plugin version, browser used
## Decision Criteria
- **Approve** the `uat→main` PR when all applicable test steps pass
- **Request changes** with specific failing steps and failure screenshots
- **Block** if the plugin fails to load entirely — escalate to CTO as a deployment issue