pf-tip-reports

Turn end-of-shift tip pool arithmetic into a 2-minute automated report — with built-in FLSA compliance checks and IRS Form 8027 data prep.

Installation

1. Download the pf-tip-reports.plugin file
2. Open Claude Desktop and navigate to Settings > Plugins
3. Click Install Plugin and select the downloaded .plugin file
4. The plugin will be installed and available immediately

Note: All data stays local on your machine. No external API calls or cloud storage required.

Why This Exists

Restaurant managers spend 15–30 minutes per shift manually calculating tip distributions — checking the POS report, doing the math by role, then transcribing payouts to paper. Errors create conflict and trust issues with staff. Toast, 7shifts, and Square offer tip management add-ons at $720–$3,600/year — for what is fundamentally arithmetic and document generation. This plugin does it in one command, included with your subscription.

Quick Start

1. Install the plugin and run /tip:tip-setup — enter your restaurant name, state, pool method, and role weights
2. After each shift, drop your POS export (CSV or XLSX) in the inbound/ folder
3. Run /tip:tip-run — the plugin loads, calculates, and generates reports automatically
4. Find your printable DOCX report and payroll XLSX in the outbound/ folder
5. At year-end, run /tip:tip-8027 to compile your IRS Form 8027 data worksheet for your accountant

Commands

Command	Description
/tip:tip-setup	Initialize workspace, configure restaurant profile, pool rules, and run FLSA compliance pre-check
/tip:tip-load	Load a POS export CSV/XLSX, validate shift data, and flag wage-hour concerns
/tip:tip-calculate	Compute tip distributions using Python arithmetic with minimum wage gap analysis
/tip:tip-report	Generate DOCX distribution report (with compliance section) and XLSX payroll export
/tip:tip-8027	Generate IRS Form 8027 annual data worksheet with allocation method guidance
/tip:tip-reports-dashboard	Interactive visual dashboard — "show me"
/tip:tip-run	Run the full shift pipeline (load → calculate → report) in one command
/tip:tip-status	Show current pipeline state and output files

How It Works

The plugin follows a 4-stage pipeline per shift:

Setup → .tip/config.json with restaurant profile, pool rules, and FLSA compliance data Load → POS export CSV/XLSX → processing/tip-shift.json (normalized, validated, wage-hour flagged) Calculate → Python Decimal arithmetic → processing/tip-distribution.json (with min wage analysis) Report → DOCX + XLSX in outbound/ + JSON archive in archive/{year}/

At year-end, /tip:tip-8027 reads all archived JSONs to compile annual IRS Form 8027 data with allocation method guidance.

AI-Powered Features

This plugin leverages Claude's AI capabilities to go beyond simple automation:

1. Intelligent POS column mapping — Uploads from Toast, 7shifts, Square, or custom exports are recognized automatically even when column names vary (e.g., "Tip Amount", "CC Tips", "Charged Tips" are all matched to the same internal field)
2. FLSA compliance pre-check — At setup, the plugin validates your tip pool configuration against federal regulations (29 CFR §531.54), state tip credit laws, CC fee deduction legality, and manager exclusion requirements — with auto-corrections and specific citations
3. Wage-and-hour flag system — During data import, each employee is checked for extended shift concerns (80/20/30 rule per 29 CFR §531.56(e)), daily overtime thresholds, negative tip anomalies, and low tip rate indicators
4. Minimum wage gap analysis — When tip credit is active, the plugin computes each employee's effective hourly rate and flags anyone below federal minimum wage per 29 USC §203(m)(2)(A)
5. Duplicate employee resolution — When an employee appears twice with conflicting roles, Claude asks the manager which role to use — rather than silently applying the wrong one
6. Shift narrative generation — Each distribution report includes a 3-4 sentence plain-language summary of the shift written by Claude for the manager's quick review
7. Fair distribution analysis — After calculation, Claude assesses whether the distribution looks reasonable and flags anomalies
8. Regulatory compliance section — Every DOCX report includes a compliance notes section with pool method legal basis, CC fee deduction authority, minimum wage alerts, and wage-hour flags with regulation citations
9. IRS 8027 expert guidance — After the 8% gross receipts test, Claude explains the three IRS-approved allocation methods (hours-worked, gross receipts, good faith agreement) with Treas. Reg. citations, filing deadlines, and FICA liability implications
10. Conversational setup — Configuration is collected through natural conversation rather than JSON files or forms

What It's an Alternative To

SaaS Tool	Annual Cost	Key Overlap
7shifts Tip Pooling	~$300/yr add-on	Tip pool calculations, DCFSA tracking
Toast Tip Management	Bundled @ $1,200–3,600/yr	POS-integrated tip calc, payroll export
Square Payroll	$720–1,440/yr	Tip tracking, payroll integration
Manual spreadsheet	included with your subscription but ~30 min/shift	Full replacement

Key Differentiators

• included with your subscription — No subscription, no per-seat fee, no add-on pricing
• FLSA compliance awareness — Validates pool composition, tip credit eligibility, and manager exclusion per 29 CFR Part 531
• State-specific rules — Knows which states prohibit CC fee deductions and tip credits, with auto-corrections
• Works with any POS — Reads CSV/XLSX exports from Toast, Square, 7shifts, Clover, or any custom format
• Python arithmetic — Uses Python Decimal type for exact monetary math (no floating-point errors)
• Minimum wage gap detection — Alerts when tip credit employees fall below minimum wage threshold
• IRS 8027 prep with allocation guidance — Year-end worksheet includes all three allocation methods with Treas. Reg. citations
• Count integrity — Asserts that output employee count equals input employee count after every calculation
• Fully offline — data is processed within the Cowork environment; nothing is sent to third-party servers
• Customizable templates — Edit the DOCX/XLSX templates to match your brand

Feature Comparison

Feature	pf-tip-reports	7shifts	Toast	Square
POS export import	✅ Any CSV/XLSX	✅ Native	✅ Native	✅ Native
Percentage pool method	✅ Full	✅ Full	✅ Full	✅ Full
Hours-worked method	✅ Full	✅ Full	⚠️ Partial	⚠️ Partial
Points-based method	✅ Full	⚠️ Partial	❌ None	❌ None
FLSA compliance pre-check	✅ Full (29 CFR Part 531)	❌ None	❌ None	❌ None
State CC fee deduction rules	✅ Full (state-by-state)	⚠️ Partial	❌ None	❌ None
Minimum wage gap analysis	✅ Full (29 USC §203(m))	❌ None	❌ None	❌ None
Wage-hour flag system	✅ Full (80/20/30 rule)	❌ None	❌ None	❌ None
Printable DOCX report	✅ Full (with compliance section)	⚠️ Partial	⚠️ Partial	❌ None
XLSX payroll export	✅ Full	✅ Full	✅ Full	✅ Full
IRS Form 8027 worksheet	✅ Full (with allocation methods)	❌ None	❌ None	❌ None
CC fee deduction	✅ Full (state-validated)	✅ Full	✅ Full	✅ Full
Manager sign-off section	✅ Full	❌ None	❌ None	❌ None
Regulatory citations in reports	✅ Full (CFR, USC, state codes)	❌ None	❌ None	❌ None
Works offline	✅ Full	❌ Cloud only	❌ Cloud only	❌ Cloud only
Cost	✅ included with your subscription	❌ ~$300/yr	❌ ~$1,800/yr	❌ ~$1,080/yr

Estimated Cost per Use

Disclaimer: Token estimates are approximate and based on typical usage patterns measured from skill prompt sizes. Actual costs vary with input data size, conversation length, and complexity. Estimates use Claude Sonnet 4.6 pricing ($3/1M input, $15/1M output). Cowork and Claude Desktop subscription users (Pro/Max/Team) are not charged per-token — these estimates apply only to direct Anthropic API usage. Running stages individually in fresh sessions uses fewer input tokens than running the full pipeline sequentially, because pipeline mode accumulates conversation history across stages.

Per skill (run individually in a fresh session):

Stage	Skill Prompt	User Input	Total Input	Output	Est. Cost
tip-dashboard	~4.8K	~500	~8.1K	~8.0K	~$0.14
tip-load	~4.5K	~2.0K	~9.3K	~2.0K	~$0.06
tip-calculate	~5.5K	~800	~9.1K	~5.5K	~$0.11
tip-report	~5.7K	~800	~9.5K	~6.0K	~$0.12
tip-8027	~7.0K	~800	~10.8K	~6.0K	~$0.12
Standalone total			~46.8K	~27.5K	~$0.55

Full pipeline (all stages in one session — context accumulates):

Stage	Base Input	+ History	Total Input	Output	Est. Cost
tip-dashboard	~8.3K	0	~8.3K	~8.0K	~$0.14
tip-load	~9.5K	~8.5K	~18.0K	~2.0K	~$0.08
tip-calculate	~9.3K	~12.5K	~21.8K	~5.5K	~$0.15
tip-report	~9.5K	~18.8K	~28.3K	~6.0K	~$0.17
tip-8027	~10.8K	~25.6K	~36.4K	~6.0K	~$0.20
Pipeline total			~112.8K	~27.5K	~$0.75

Running the full pipeline once typically costs $0.53–$0.98 in API tokens (Claude Sonnet 4.6).

Known Limitations & Workarounds

This is a Claude Cowork plugin, not a traditional SaaS application. It has architectural constraints you should know about before adopting it.

Limitation	Impact	Workaround
No real-time POS integration	Must export a CSV/XLSX manually from your POS after each shift	Set up a 2-minute end-of-shift routine: export → drop in inbound/ → run /tip:tip-run
No payroll system direct integration	Cannot push directly to ADP, Gusto, Paychex	Export the XLSX payroll file and import manually into your payroll system
IRS Form 8027 data only, not filing	Generates a data worksheet, not the actual e-filed form	Send the XLSX worksheet to your CPA or payroll processor for filing
Tip pooling law compliance not verified	Cannot verify your pool method complies with all applicable laws	FLSA pre-check catches common issues; consult a licensed employment attorney for full compliance
No employee acknowledgment signatures	Paper report requires wet signatures; no digital e-sign	Print the DOCX, collect physical signatures, scan and archive
Large shift files (>500 employees)	Performance may degrade for very large hospitality operations	Split large exports by role group and run separately
State law data is point-in-time	Embedded state rules reflect early 2026 regulations	Verify current state law before relying on auto-corrections

Context & Performance Guide

Session management

Claude's context window is shared across your session. For the full tip pipeline (3 stages), start a fresh Claude session before running /tip:tip-run for best results. The plugin saves state between stages, so you can resume from any stage in a new session.

Data volume guidance

Tested with up to 50 employees per shift. For most restaurants (5–25 employees), all pipeline stages run comfortably in a single session. For larger operations (50+ employees), run stages individually with /tip:tip-load, /tip:tip-calculate, /tip:tip-report.

Tips for best results

1. Upload your POS export as a file rather than pasting data into chat — file reading is more context-efficient
2. Keep your messages concise during pipeline runs — every message stays in the context window
3. For cleanest output, start a fresh session before each shift's pipeline run
4. If output quality degrades (shorter responses, missing sections), start a new session and resume from the failed stage

Degradation signals

If responses become shorter or skip sections, start a new session and re-run the current stage. The plugin's checkpoint system means you won't lose work.

Requirements

• Claude Desktop with Cowork mode enabled
• Python 3.x with pip (for dependency installation)
• python-docx and openpyxl (installed automatically by /tip:tip-setup)

Important Disclaimers

• AI-Generated Content: This plugin uses AI (LLM) technology which can produce inaccurate or incomplete outputs. All content should be treated as a starting point and reviewed for accuracy before use.
• Not Professional Advice: Outputs do not constitute legal, financial, tax, medical, or other professional advice. Consult qualified professionals before making decisions based on generated content.
• No Compliance Guarantee: References to industry standards, regulations, or guidelines (including 29 CFR Part 531, IRC §6053, state labor codes) are for informational purposes only. This plugin does not guarantee compliance with any law or regulation. Users are responsible for verifying all outputs meet their specific regulatory requirements.
• No Endorsement or Affiliation: Mention of third-party products, standards, or organizations does not imply endorsement, partnership, or certification by those entities.
• Not Financial or Tax Advice: Financial calculations, tax estimates, IRS Form 8027 data, and related outputs are for informational purposes only. Consult a qualified CPA or financial advisor for tax and financial decisions.