Compensation & Benefits Pack

We built the Compensation & Benefits Pack because watching engineers and HR directors manually reconcile salary bands, equity grants, and benefits administration across spreadsheets and disparate tools is a structural failure. You are trying to run a total rewards strategy with tools designed for data entry, not data integrity. When you prompt a generic LLM to "draft a compensation plan," you get generic text. You do not get a validated Carta Draft Issuer payload. You do not get a Python script that calculates fully diluted percentages from a JSON cap table. You do not get a JSON Schema that enforces compliance flags on benefits records.

Compensation planning is not a creative writing exercise. It is a technical workflow involving precise calculations, regulatory constraints, and multi-system integrations. We see teams trying to bolt on benefits administration system workflows after the fact, or relying on HR analytics that are starving for clean, structured input because the source data was never validated at the point of entry. If your compensation data lives in a mix of CSV exports, unstructured emails, and memory, you are already losing money.

Why Spreadsheet Drift and Generic Prompts Fail at Scale

The cost of manual compensation planning compounds fast. When you rely on spreadsheet formulas that no one audits, you risk equity over-granting, which dilutes founder ownership and triggers tax events you didn't plan for. When you benchmark salaries against outdated or unverified market data, you either bleed cash on over-market offers or lose critical talent to competitors who priced correctly. According to WorldatWork, compensation benchmarking is a critical discipline for practitioners to make best use of market data, yet most organizations struggle to operationalize it effectively ^[1].

The market has shifted. The 2023 Salary Structure Survey results show significant changes in how organizations structure compensation due to volatile market conditions ^[7]. Teams that are still using static salary bands from 2021 are already mispricing their workforce. Generic AI models cannot help you here because they lack access to your specific cap table, your internal equity constraints, and your real-time benchmarking data. They cannot run a calculate-equity.sh script against your JSON data to verify dilution before you send the offer letter.

This drift also cascades into performance management. If your compensation data is wrong, your performance review cycles become exercises in defending arbitrary numbers rather than rewarding actual impact. You end up in a loop where bad data drives bad decisions, which drives bad retention, which forces you to hire again, which costs you more in recruiting fees. The financial impact is measurable: a single mispriced senior engineer role can cost your company $50k-$100k annually in excess pay or lost productivity. A single equity calculation error can trigger a 409A valuation dispute or an IRS compliance issue. We built this skill so you can stop gambling with your P&L.

A Series B Startup's Equity and Benchmarking Nightmare

Imagine a Series B fintech startup with 150 employees. They just raised $30M and need to issue equity to a new batch of hires and re-balance the existing cap table. The HR director is manually calculating vesting schedules in a spreadsheet. The engineering lead is trying to understand the fully diluted percentage of a new grant but doesn't have a script to parse the JSON cap table. They are also trying to benchmark salaries for a new AI team against market data, but their internal compensation records are unstructured.

Without a structured workflow, this team faces three immediate failures:

Equity Calculation Errors: The HR director calculates a grant size based on a rough estimate of outstanding shares. They miss a derivative security in the cap table. The resulting fully diluted percentage is off by 15%. This leads to an over-grant that dilutes the founders more than intended.

Benchmarking Blindness: The recruiter pulls salary data from a generic report. They don't account for the specific job architecture or the total rewards mix. They make an offer that is 10% above market for base salary but ignores equity, resulting in a total compensation package that is misaligned with the candidate's expectations and the company's budget. WorldatWork's Total Rewards Inventory of Programs & Practices highlights the prevalence of diverse reward programs, yet many organizations fail to align them strategically ^[3].

Compliance Gaps: The benefits administrator uploads employee data to a third-party vendor without validation. Missing fields in the JSON payload cause the benefits enrollment to fail for 20% of the staff. The team spends three days fixing data errors instead of managing the open enrollment period.

A 2024 study on Total Rewards practices adapted to a changed job market shows that organizations must evolve their compensation and HR practices to respond to these dynamics ^[5]. Another WorldatWork survey on employee compensation reveals how organizations approach market pricing for their U.S. workforce, but only if they have the data infrastructure to support it ^[8]. This team had the intent but lacked the technical framework. They needed a way to validate equity structures, generate benchmarking payloads, and enforce data integrity across benefits administration.

If you are managing a recruiting pipeline, you know that recruiting pipeline management is only as good as the offer you extend. A broken compensation workflow breaks the offer. You cannot fix this with a prompt. You need a skill that treats compensation as a technical system.

Automated Equity Calculations and Validated Reward Structures

Once the Compensation & Benefits Pack is installed, your workflow shifts from manual reconciliation to automated validation. We provide the orchestrator, the schemas, the scripts, and the references to turn compensation planning into a deterministic process.

Equity Structuring becomes deterministic. You no longer guess about dilution. You feed your cap table JSON into scripts/calculate-equity.sh. The script reads the data, extracts derivatives and share counts, and outputs precise fully diluted and outstanding percentages. You can then validate the grant against the templates/carta-draft-issuer.yaml using validators/carta-payload-validator.sh. If the payload is missing required fields like share class or vesting schedule, the validator exits non-zero. You catch the error before it hits Carta. Benchmarking becomes structured. You stop pasting salary data into an LLM and hoping for the best. You run scripts/benchmark-analysis.py to process your internal compensation data. The script generates OpenAI Fine-Tuning Job payloads that are ready for API consumption. You get clean, structured data that respects the hyperparameters and format requirements of your benchmarking models. This aligns with the WorldatWork emphasis on using benchmarking effectively to guide compensation decisions ^[1]. Benefits Administration becomes compliant. You enforce data integrity using templates/benefits-admin-schema.json. This JSON Schema validates your benefits records against required fields for employee benefits, cost centers, and compliance flags. You ensure that every benefits record you process meets your internal standards and external regulatory requirements. This reduces the risk of enrollment errors and data breaches. Total Rewards becomes strategic. You leverage the canonical knowledge in references/total-rewards-framework.md to align your compensation strategy with HR goals. The framework details the five elements of reward strategy and benchmarking methodologies. You can use this to design a total rewards package that includes health, equity, and wellness components, as shown in examples/benefits-optimization.yaml. This holistic approach ensures that your compensation strategy supports your broader business objectives, as emphasized in WorldatWork's resources on total rewards ^[2].

This skill integrates seamlessly with your existing HR stack. You can use the output of the equity calculations to inform your performance review bonuses. You can use the benefits data to update your employee handbook and ensure employment law compliance. You are no longer siloed. You have a unified, technical framework for managing your most expensive asset: your people.

What's in the Compensation & Benefits Pack

• skill.md — Orchestrator skill defining the Compensation & Benefits expert persona, workflow, and file references. Guides the agent through equity structuring, benchmarking, benefits validation, and total rewards optimization.
• templates/carta-draft-issuer.yaml — Production-grade YAML template for creating a Carta Draft Issuer. Mirrors the Carta API structure with placeholders for company details, share class, vesting schedules, and stakeholder info.
• templates/benefits-admin-schema.json — JSON Schema for validating benefits administration records. Enforces required fields for employee benefits, cost centers, and compliance flags to ensure data integrity.
• references/equity-structures.md — Canonical knowledge on equity structures derived from Carta API docs. Covers cap table data structure, FMV retrieval, fully diluted percentage calculation, vesting terms, and OAuth flows.
• references/total-rewards-framework.md — Canonical knowledge on Total Rewards optimization from WorldatWork. Details the five elements of reward strategy, alignment with HR goals, and benchmarking methodologies.
• scripts/calculate-equity.sh — Executable shell script to calculate fully diluted and outstanding percentages for equity awards. Reads JSON cap table data, extracts derivatives and share counts, and outputs dilution metrics.
• scripts/benchmark-analysis.py — Executable Python script to prepare OpenAI Fine-Tuning Job payloads for salary benchmarking. Processes compensation data and generates API-ready payloads with hyperparameters.
• validators/carta-payload-validator.sh — Validator script that checks a JSON payload against the Carta Draft Issuer structure. Exits non-zero if required fields like name, share class, or vesting schedule are missing or invalid.
• examples/worked-equity-simulation.json — Worked example of a cap table JSON structure with real values. Demonstrates how to populate the Carta template and serves as input for the equity calculation script.
• examples/benefits-optimization.yaml — Worked example of a benefits package configuration. Shows a complete benefits structure with health, equity, and wellness components for reference and validation.

Stop the Spreadsheet Drift

Your compensation data is too valuable to leave to chance. You need a technical framework that validates equity calculations, structures benchmarking payloads, and enforces benefits compliance. Upgrade to Pro to install the Compensation & Benefits Pack and start shipping with confidence.