payroll_administration v1.0.0

name: payroll_administration description: Run payroll administration for a small team in any jurisdiction: build the jurisdiction profile from official sources, keep a pay calendar, gather hours and changes against a cutoff, calculate gross to net on a tested worksheet, check payslips before approval, report and pay on the right dates, correct errors without hiding them, and keep audit-ready records. Use when setting up payroll, running a pay period, checking a payslip, fixing a pay error, or preparing payroll records for an audit.

Payroll Administration

Purpose

Pay people the right amount, on the right day, with the right amount held back for the tax authority, and keep records that prove all three later.

This skill is jurisdiction-aware on purpose. Payroll rules differ by place and change by year, so the skill does not bake a set of rates into a workflow and call it done. It builds a short jurisdiction profile from official sources at setup and again each year, takes every rate and cap as a verified input at run time, and keeps each run in draft until a person has checked and approved it. Four profiles are worked out in the references (United States, United Kingdom, Canada, Australia), with a field list for building any other.

It covers the recurring administration job for a small team: pay calendar, inputs, calculation, checks, payslips, reporting, payments, corrections, and records. It does not cover choosing a payroll provider, employment law advice, worker classification disputes, or anyone's personal tax return. Classification and disputed cases go to a qualified adviser in that jurisdiction, with the payroll record as evidence, not as the answer.

Workflow

1. Build or refresh the jurisdiction profile before the run

• Open references/jurisdiction-profiles.md and find the profile for where each employee works. Where someone works, not where the company sits, drives the profile.
• Verify every rate, threshold, cap, and deadline in the profile against the official source for the coming pay date: the tax authority for tax and reporting, the labour authority for hours, overtime, and payslip rules. Write the source name and the check date next to the figures you will use.
• If a figure cannot be verified from an official source, the run stays in draft. A rate remembered from last year, a blog summary, or a provider's marketing page is not verification.
• Repeat the refresh at each new tax year and whenever a notice arrives from the authority mid-year, such as a tax code change or a remitter type change.

2. Keep a pay calendar and work to a cutoff

• Maintain one calendar with, for each run: pay period dates, the input cutoff, calculation day, approval day, payday, the reporting deadline, and the dates withheld money and employer contributions must be paid. Those last dates are often not payday, and missing them is where penalties start.
• Set the cutoff before payday with enough room to calculate and check. Hours, leave, bonuses, commissions, and changes that miss the cutoff go to the next run or a planned correction run.
• When payday lands on a weekend or public holiday, apply the jurisdiction or contract rule for paying early or late, and use the reporting date the authority still expects where it sets one.

3. Gather inputs as documents, not messages

• Starters: pay rate and start date from the contract or offer, the tax form or starter declaration the jurisdiction uses, and bank details verified through a second channel. A bank change requested only inside a single email thread is a fraud pattern, not an input.
• Leavers: last day, final items, accrued leave treatment, and any balance the employee owes or is owed, each with its source.
• Changes: keep a changes log for the run. Every rate change, tax withholding change, deduction start or stop, and bank change gets a line with the source document and the date it takes effect. Nothing enters payroll from a verbal request alone.
• Hours: use approved timesheets. Split regular, overtime, and leave hours. Mark bonuses and commissions as discretionary or nondiscretionary where the jurisdiction regular rate rule cares, because that one word changes the overtime math (see the worked case in the correction playbook).

4. Calculate gross to net on the worksheet

• Run each non-standard person, and a sample of standard staff, through the worksheet script. It takes rates and caps as inputs, applies pre-tax deductions to the right tax bases, applies yearly caps against year to date wages, totals employer cost, and fails the run on a negative net.

python3 scripts/gross_to_net.py scripts/examples/us-hourly.json
python3 scripts/gross_to_net.py --self-test

• Enter income tax the way the jurisdiction calculates it: a table or worksheet lookup from the official publication, recorded as a flat amount on the worksheet with its source, or a verified percentage where the system is genuinely flat. Do not approximate a progressive tax with one guessed percentage and call it withholding.
• Work the deduction order deliberately: pre-tax items that reduce a tax base come before that tax, post-tax items after, and court orders follow the priority and floors the order itself sets.
• Check anyone near a yearly cap by name. Caps on social contributions, pension, or insurance premiums are the most common silent error in a growing team's payroll, because the run looks normal the month the cap is crossed.

Worked result for the example file above, with 2026 United States figures used as arithmetic inputs only: gross $980.00 (40 hours at $20.00 plus 6 overtime hours at $30.00), pre-tax deductions $150.00, Social Security $54.56 and Medicare $12.76 on the reduced base of $880.00, income tax $82.00 from the table, post-tax dues $15.00, net $665.68, employer total cost $1,077.32. The script self-test also covers a capped tax case and a correction case, and all four cases pass.

5. Hold the run in draft until it is verified

This is the rule the whole skill turns on: a pay run is a draft until a named person has checked it and approved it, and no file is submitted and no money moves before that approval.

• Run the variance check against the previous run: headcount, gross, total tax, and net, plus a per-person scan. Every new person, missing person, and change over your set threshold gets a reason traced to the changes log.
• Check preview payslips against the checklist in references/pay-run-checklist.md, including recomputing one payslip from the payslip alone.
• Confirm funds cover net pay, withheld money, and employer contributions on the separate dates each one is due.
• Record the preparer and approver. Where the team is one person, the same person prepares and approves at different times, with the variance check done twice, and the calendar is built to allow that gap.

6. Pay, report, and file the run as one packet

• Generate the reporting submission from the approved run only, and match its control totals to the approved run sheet before sending: headcount, gross, tax, net, to the cent.
• Respect the timing rule in the profile. Some systems want the report on or before payday, some want remittance days later, some want both on different dates. The profile, not habit, sets the order.
• Issue payslips by the deadline in the profile, showing at least gross pay, each deduction, and net pay, plus hours where pay varies with time worked.
• File the packet together: approved run sheet, worksheets, payslips, submission confirmation, payment confirmations, and the signed checklist. One folder per run, named by pay date.

7. Correct errors openly and in payroll

• Follow references/error-correction-playbook.md. Recompute first, classify the error (under or over, same or closed tax year, filed or not, still employed or leaver), tell the employee, fix it through a correction run or a line in the next run, and amend the filing for the original period where it was already filed.
• Never pay a fix in cash, never net one person's error against another's, never edit a filed run in place, and never deduct a recovery the employee has not been told about.
• Log the cause, not only the fix. A repeated cause, such as bonuses set up outside the regular rate, becomes a checklist change, not a third correction.

8. Keep records for the audit you hope never comes

• Keep, per person and per run: the inputs and their source documents, the changes log, worksheets, payslips, submissions and confirmations, payment records, correction notes, and year end statements.
• Retention follows the profile: at least 4 years after the tax is due or paid in the United States, at least 3 years from the end of the tax year in the United Kingdom, at least 6 years after the year in Canada, and 7 years for employment records in Australia. Where two rules cover the same record, keep it for the longer one.
• Restrict access. Payroll records hold bank details, tax identifiers, and pay for the whole team. Store them where only the people who run and approve payroll can open them, and never in a shared drive folder or a group chat.

Output Contract

For a single pay run, deliver:

• The jurisdiction profile figures used, each with its official source and check date.
• The run sheet: headcount, gross, each tax and deduction total, net, employer contributions, and employer total cost, with the variance notes against the last run.
• A completed checklist from references/pay-run-checklist.md, signed by the preparer and the approver, or marked draft with the missing check named.
• The payslips and the reporting submission confirmation, with control totals shown to match the run sheet.
• A corrections log for the run: any error found, its classification, the fix, and the amended filing reference where one was needed.

For a setup or review job, deliver the filled jurisdiction profile, the pay calendar for the next 12 months, and a list of any gaps found in the records, with the retention rule each gap breaks.

Operating Rules

• Draft until verified is absolute. No submission, payment file, or payslip leaves as final before the checks and a named approval.
• Every factual figure in a run comes from an official source checked for that pay date. Unverified figures are marked as placeholders and block approval.
• Amounts are always labelled gross or net. A correction, a deduction, and a recovery are each stated as one or the other, never left ambiguous.
• Employee money held back is not company money. Withheld tax and contributions are scheduled and paid on their own dates and never used as working capital.
• Bank detail changes need verification through a second channel, every time, including for long-serving staff and for requests that look internal.
• This skill gives administration method, not legal or tax advice. Where a rule is disputed, a worker's status is in question, or a penalty has been assessed, stop and route it to a qualified adviser in the jurisdiction, with the records as the brief.
• No em dashes in any document this skill produces for people to read.