team-eo-org

Skills and tools for the EO Org team at Personio.

Installation

claude plugin install team-eo-org@personio-claude-code-marketplace

What does this plugin do?

Claude Code skills for the EO Org team — covering two distinct use cases:

• OPS / data corrections — guided, safety-gated SQL workflows for data changes that the Personio UI doesn't support. Intended for anyone handling an OPS ticket, not just engineers.
• Engineering migration playbooks — step-by-step playbooks for cross-service code migrations. Intended for engineers working in the EO Org codebase.

OPS / Data corrections

These skills require the data-access CLI and a Jira OPS ticket. They walk you through each SQL step with explicit approval gates — no write runs without your confirmation.

move-le-registration-date

Moves a Legal Entity (LE) registration date to a future date via guided SQL steps. This change cannot be made through the UI.

What you need:

• data-access CLI available in your shell
• A Jira ticket (e.g. OPS-1234) to attach to the data-access commands
• An approver email in {name}.{surname}@personio.de format
• Manager approval may be required to access the company data via data-access auth request-company-access

Quick Start:

"Move the registration date for legal entity 42 to 2026-03-01"
"I need to push the LE registration date forward — it can't be done via UI"
"Help me with an OPS task: change LE 99 registration date to 2025-09-15 for company 500"

What it does:

Walks you through each step with full safety gates:

1. Collects company ID, LE ID, Jira ticket, approver email, and new date
2. Checks for employee assignments and payroll runs that predate the new registration date
3. Shows you a SELECT of the current LE state and validates the new date is strictly after the current one
4. Runs the UPDATE on legal_entities with your explicit approval
5. Updates org_attribute_history milestones, with constraint-failure recovery if needed
6. Updates attribute_history in the payroll-org-entity-attributes-service (PEAS), if data exists
7. Guides you to trigger the Rundeck republish job for ECEs

Every write command requires its own explicit approval — no blanket authorisation.

Why would you want this?

• The Personio UI does not allow moving an LE registration date forward — this is the only supported path.
• The skill enforces the correct order of operations and prevents writes without prior reads.
• Safety gates at each step mean you stay in control; the skill halts completely if you decline any step.

move-pe-registration-date

Moves a Permanent Establishment (PE) registration date to a future date via guided SQL steps. This change cannot be made through the UI.

What you need:

• data-access CLI available in your shell
• A Jira ticket (e.g. OPS-1234) to attach to the data-access commands
• An approver email in {name}.{surname}@personio.de format
• Manager approval may be required to access the company data via data-access auth request-company-access

Quick Start:

"Move the registration date for permanent establishment 42 to 2026-03-01"
"I need to push the PE registration date forward — it can't be done via UI"
"Help me with an OPS task: change PE 99 registration date to 2025-09-15 for company 500"

What it does:

Walks you through each step with full safety gates:

1. Collects company ID, PE ID, Jira ticket, approver email, and new date
2. Fetches the current PE valid_from and linked legal_entity_id, then validates the new date is strictly after the current one
3. Checks that the linked Legal Entity's registration date is on or before the new PE date (a PE cannot predate its parent LE)
4. Checks for payroll runs that predate the new registration date
5. Runs the UPDATE on permanent_establishments with your explicit approval
6. Updates org_attribute_history milestones, with constraint-failure recovery if needed
7. Updates attribute_history in the payroll-org-entity-attributes-service (PEAS), if data exists
8. Guides you to trigger the Rundeck republish job for ECEs

Every write command requires its own explicit approval — no blanket authorisation.

Why would you want this?

• The Personio UI does not allow moving a PE registration date forward — this is the only supported path.
• The LE date guard prevents creating data inconsistencies where a PE predates its parent Legal Entity.
• Safety gates at each step mean you stay in control; the skill halts completely if you decline any step.

Engineering migration playbooks

These skills are for engineers. They assume a local dev environment, gh CLI access to Personio-Internal, and familiarity with the EO Org codebase.

le-rest-to-grpc

Migrates Personio services from the deprecated Legal Entity JSON/REST API (org-management-json-api-v1) to the LegalEntityService gRPC API.

What you need:

• gh CLI authenticated against Personio-Internal
• Local clone of the target consumer repo at ~/dev/<repo-name>/
• A Jira migration ticket (e.g. ORG-1234) and a feature flag name from the consuming team

Quick Start:

"Migrate payroll-documents from the LE REST API to gRPC"
"Let's do the next pending migration in the LE tracker"
"Update the LE REST to gRPC migration tracker — some PRs have merged"
"Which services are still calling /public/v1/legal-entities?"

What it does:

Three modes selectable at startup:

• migrate — picks the next ⏳ Pending repo from the tracker (or a named repo), walks through all 16 steps: repo prep, call site discovery, gRPC dependency check, field mask determination, Shape A/B feature flag wiring, compile + lint + test, clean build, smoke test, draft PR creation, and tracker update.
• update tracker — checks whether 👀 In review PRs have merged and whether ⏳ Pending repos have been self-migrated, then updates the tracker in place.
• discover — searches GitHub for all consumers of the deprecated REST endpoints across the Personio org and produces a LE-REST-GRPC-MIGRATION-TRACKER.md.

Every migration is behind a feature flag. The skill enforces draft PRs, no lockfile commits, and mandatory log lines in every feature-flag branch.

Why would you want this?

• The playbook encodes 25+ hard-won gotchas from real migrations (pagination loops, blocking vs coroutine stubs, MockK edge cases, ktlint CI failures, etc.).
• Consistent PR descriptions and reviewer checklists across all consumer repos.
• Tracker keeps the full migration programme visible without manual bookkeeping.

Contributing a skill to team-eo-org

Anyone on the EO Org team can add a skill to this plugin. To keep it coherent as it grows:

• Use descriptive skill names that clearly identify the entity or workflow (e.g. move-le-registration-date). Avoid generic names that could collide with other plugins' skills.
• The skill's description frontmatter must name the domain, service, or workflow it applies to. This is what lets Claude route prompts correctly.
• Add trigger and output evals under skills/<skill-name>/evals/ — see the evals README for format and thresholds.
• Place the skill under the right category in this README — OPS / data corrections for data-access-based workflows, Engineering migration playbooks for developer-facing playbooks.