personio-eng-rules-experimental

Atomic engineering rules for Personio backend teams. A growing registry of learned lessons — one skill per domain, one file per rule. Scales to the whole engineering org without bloating Claude's context.

Installation

claude plugin install personio-eng-rules-experimental@personio-claude-code-marketplace

How it works

Rules live as small markdown files in references/ under each domain skill. When you edit code in a domain, the domain skill activates and surfaces its rule index. Claude reads only the rules relevant to the current change — not the full registry.

Skills

kotlin-rules

Surfaces Personio-specific Kotlin language rules when editing .kt files.

Seed rules:

• null-empty-absence — Use null or empty collections for absence; never empty strings, 0, or sentinels
• reject-malformed-data — Validate at every boundary; no silent defaults or fallbacks

kotlin-architecture-rules

Surfaces service-structure rules when designing or modifying Kotlin service architecture — gRPC/REST handlers, layering, persistence, event producers/consumers, multi-tenancy. Rule index is being seeded from a mining pass over Personio Kotlin services; rules land as draft pending Kotlin guild review.

kotlin-testing-rules

Surfaces testing rules when writing or modifying Kotlin tests — test structure, fixtures, testcontainers, mocking, assertions, CDC/Pact. Rule index is being seeded; rules land as draft pending Kotlin guild review.

kotlin-build-rules

Surfaces build-and-tooling rules when editing Kotlin build files — build.gradle.kts, settings.gradle.kts, version catalogs, Detekt, PPM. Mostly thin pointer rules linking to existing personio-framework TechDocs to avoid duplication. Rule index is being seeded; rules land as draft pending Kotlin guild review.

add-engineering-rule

Scaffolds a new rule (in an existing domain) or a new domain skill skeleton.

add a kotlin rule about coroutine error handling
scaffold a grpc-rules domain
add a rule about feature-flagging SQL migrations

Governance

Adding a rule:

1. Use add-engineering-rule or run skills/add-engineering-rule/scripts/scaffold-rule.sh <domain> <rule-id> "<title>"
2. Fill in Rule, Why, Example (bad + good), Related
3. Append one-liner to domain SKILL.md Rule Index
4. Add ≥1 should-fire eval prompt to evals/trigger.json
5. Bump plugin.json version (patch for new rule, minor for new domain)
6. PR reviewed by domain CODEOWNERS

Status lifecycle: draft → active → deprecated

CODEOWNERS: plugin root owned by @personio-internal/dx. Per-subdir ownership delegated to guilds as they adopt domains (add a CODEOWNERS line like /plugins/personio-eng-rules-experimental/skills/kotlin-rules/ @personio-internal/kdx).

Roadmap

• Kotlin pilot: null-empty-absence, reject-malformed-data
• Domain skeletons: kotlin-architecture-rules, kotlin-testing-rules, kotlin-build-rules
• Seed rules per domain from mining pass over Personio Kotlin services (draft status)
• Kotlin guild review flips rules draft → active
• Graduate to personio-eng-rules