Franchise Royalty Automation Plugin

pf-franchise-royalty-automation automates monthly royalty management for franchise networks, as an alternative to FranConnect's royalty module at zero licensing cost.

Installation

1. Download the pf-franchise-royalty-automation.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.

Overview

Turn 4-6 hour monthly royalty reconciliation into 30 minutes:

• Import and validate franchisee sales data (Square, Toast, or generic CSV)
• Calculate tiered royalties, tech fees, and marketing fund contributions
• Generate per-franchisee DOCX invoices with payment instructions
• Reconcile payments with aging analysis and pattern detection
• Produce structured for audit preparation compliance reports with certification statements

Key Features

✓ Tiered Royalty Calculation — Apply progressive rates based on sales volume ✓ Deterministic Math — All calculations via Python, never LLM-generated ✓ Automated Invoice Generation — Create professional DOCX per franchisee ✓ Payment Reconciliation — Match payments to invoices with fuzzy tolerance ✓ AI-Powered Anomaly Detection — Flag outlier sales and payment patterns ✓ Compliance Audit Reports — Generate structured for audit preparation docs with legal disclaimers ✓ Pipeline Checkpoints — Resume interrupted runs from last failed stage ✓ Scalable — Handle 10-75 franchisees with batch processing support

Quick Start

1. Initialize Workspace

/franchise-setup "Acme Franchises Inc" "2026-03" "USD" "45"

Creates directory structure, verifies dependencies, and configures franchisor settings.

2. Import Sales Data

Place sales-data.csv in inbound/ directory with columns:

• franchisee_id — Unique identifier
• franchisee_name — Franchisee name
• period — Reporting period (YYYY-MM)
• gross_sales — Gross sales amount

Then run:

/franchise-import

3. Calculate Royalties

/franchise-calculate

Applies tiered rates, fees, and adjustments. Output: franchise-royalties-calculated.json

4. Generate Invoices

/franchise-invoice

Creates per-franchisee DOCX invoices. Output: outbound/invoices/[franchisee_id]-invoice-[period].docx

5. Reconcile Payments

Place payment-log.csv in inbound/ with columns:

• franchisee_id — Payer
• amount_paid — Payment amount
• payment_date — When received
• payment_method — Wire, ACH, Check, etc. (optional)
• reference — Payment reference (optional)

Then run:

/franchise-payments

6. Generate Audit Report

/franchise-audit

Creates compliance audit with metrics, tier application, and certification. Output: outbound/compliance-audit-[period].docx

Full Pipeline Mode

Run all stages in sequence with checkpoint/resume:

/franchise-pipeline

Resume from failure:

/franchise-pipeline --resume

Start from specific stage:

/franchise-pipeline --start-from=invoice

Commands

Command	Purpose
franchise-setup	Initialize workspace and configuration
franchise-import	Import and validate sales data
franchise-calculate	Calculate tiered royalties and fees
franchise-invoice	Generate DOCX invoices
franchise-payments	Reconcile payments and generate report
franchise-audit	Generate compliance audit report
franchise-royalty-dashboard	Interactive visual dashboard — "show me"
franchise-pipeline	Execute full pipeline with checkpoints
franchise-status	Display current pipeline status

Configuration

Edit .franchise/config.json to customize:

{
  "franchisor_name": "Acme Franchises Inc",
  "royalty_period": "2026-03",
  "currency": "USD",
  "franchisee_count": 45,
  "royalty_rates": {
    "tier_1": {"threshold": 0, "rate": 0.05},
    "tier_2": {"threshold": 50000, "rate": 0.04},
    "tier_3": {"threshold": 100000, "rate": 0.03}
  },
  "fees": {
    "tech_fee": 150.00,
    "marketing_fund_percent": 0.02,
    "marketing_fund_min": 50.00
  },
  "due_date_offset_days": 30,
  "currency_symbol": "$"
}

Directory Structure

workspace/
├── inbound/                          # CSV imports (sales-data.csv, payment-log.csv)
├── processing/                       # Intermediate JSON files
│   ├── franchise-sales-validated.json
│   ├── franchise-royalties-calculated.json
│   ├── franchise-invoices-manifest.json
│   ├── franchise-reconciliation.json
│   └── audit-record-2026-03.json
├── outbound/                         # Final outputs
│   ├── invoices/                     # Per-franchisee DOCX invoices
│   ├── payment-reconciliation-2026-03.docx
│   └── compliance-audit-2026-03.docx
├── archive/                          # Historical snapshots
├── templates/                        # DOCX templates and configs
│   ├── invoice-template.docx
│   ├── reconciliation-template.docx
│   ├── audit-template.docx
│   └── *.json (configuration)
└── .franchise/                       # Configuration and state
    ├── config.json
    └── project.json

AI-Powered Features

• FDD Item 6-Aligned Fee Structures: Config.json fields map directly to FTC 16 CFR 436.5(f) disclosure categories with compliance verification workflow
• FASB ASC 606 Revenue Classification: Separates royalties (variable consideration per ASC 606-10-55-65A), tech fees (fixed consideration per ASC 606-10-25-27), and marketing contributions for proper revenue recognition
• AICPA AU-C 240 Anomaly Detection: Sales data validation uses fraud risk indicator thresholds aligned with professional auditing standards (AU-C 240.A27, AU-C 240.A28)
• Tiered Royalty Calculation with Minimum Royalty Support: Applies FDD-disclosed progressive rates with optional minimum royalty per franchise agreement, using deterministic Python math (never LLM-generated)
• IFA-Standard Invoice Best Practices: Generates per-franchisee DOCX invoices implementing the IFA 6-element framework: period, calculation basis, rate applied, fee breakdown, payment instructions, and dispute contact
• FASB ASC 326 (CECL) Aging Analysis: Payment reconciliation uses CECL-aligned aging buckets with industry-average loss rate estimates for allowance for doubtful accounts calculations
• IFA Collection Escalation Framework: Aging buckets map to IFA-recommended collection actions (personal contact → formal demand → cure notice → termination proceedings)
• Late Fee Calculation with Usury Law Compliance: Configurable late fees with state-specific APR caps (CA 10%, NY 16%) per UCC Article 2A and state usury statutes
• AICPA AU-C 315 Audit Reports: Compliance narratives follow professional audit documentation structure with FDD Item 6 adherence confirmation and FASB ASC 606 revenue recognition verification
• State Franchise Registration Awareness: Supports the 14 registration states (CA, HI, IL, IN, MD, MI, MN, NY, ND, RI, SD, VA, WA, WI) with state-specific compliance context

Feature Comparison

Feature	This Plugin (v1.1)	FranConnect ($12-24K/yr)	Excel ($0)
FDD Item 6-aligned fee structures	Yes (automated)	Yes	Manual
FASB ASC 606 revenue classification	Yes (per-field)	Partial	No
AICPA AU-C 240 anomaly detection	Yes (statistical)	Basic	No
CECL aging analysis	Yes (with loss rates)	Yes	Manual
State usury law late fee caps	Yes (configurable)	Yes	Manual
Deterministic calculation verification	Yes ($0.01 tolerance)	Proprietary	No
structured for audit preparation compliance reports	Yes (AICPA AU-C 315)	Yes	No
Franchisee self-service portal	No	Yes	No
Real-time payment processing	No	Yes	No
Cost	$0	$12,000-24,000/yr	$0

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 payment processing	Cannot charge franchisees directly; cannot auto-apply payments from bank feed	Export payment CSV from Stripe/bank statement; plugin reconciles from that file
No persistent database	Multi-month payment history requires maintaining a running payment-log.csv as source of truth	Append new payments to payment-log.csv each period; plugin reads cumulative history for aging analysis
No franchisee self-service portal	Franchisees cannot log in to view their own royalty statements or payment history	Email DOCX invoices; use shared Google Drive folder for statement access
No scheduled automation	Cannot auto-trigger at month-end; requires manual session to run monthly batch	Set recurring calendar reminder to run /franchise:franchise-pipeline at period close; takes ~30 min
Legal disclaimer required	Financial calculations must carry disclaimer on all output documents	Disclaimer auto-added to all DOCX outputs by invoice and audit skills

Legal Compliance

All DOCX outputs include mandatory disclaimers:

Invoice & Reconciliation:

This document is for informational purposes only and does not constitute legal or financial advice.

Audit Report (Certification):

This audit report reflects calculations performed as of [DATE] and is provided for informational purposes only.

These disclaimers are required and cannot be removed.

Calculation Guarantees

• No LLM Math: All royalty calculations use deterministic Python code
• Verification: Each calculation verified within $0.01 tolerance
• Audit Trail: Full tier-by-tier breakdown included for compliance review
• Atomic Writes: All file operations use temp+rename for reliability

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
franchise-import	~3.1K	~2.0K	~10.0K	~2.0K	~$0.06
franchise-invoice	~3.4K	~800	~9.3K	~3.4K	~$0.08
franchise-dashboard	~4.1K	~500	~7.4K	~8.0K	~$0.14
franchise-payments	~4.8K	~800	~11.3K	~4.8K	~$0.11
franchise-audit	~4.4K	~800	~10.9K	~4.0K	~$0.09
franchise-calculate	~3.5K	~800	~9.6K	~3.5K	~$0.08
Standalone total			~58.6K	~25.8K	~$0.56

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

Stage	Base Input	+ History	Total Input	Output	Est. Cost
franchise-import	~9.5K	0	~9.5K	~2.0K	~$0.06
franchise-invoice	~8.6K	~4.0K	~12.6K	~3.4K	~$0.09
franchise-dashboard	~9.0K	~8.2K	~17.3K	~8.0K	~$0.17
franchise-payments	~10.1K	~16.7K	~26.8K	~4.8K	~$0.15
franchise-audit	~9.6K	~22.4K	~32.0K	~4.0K	~$0.16
franchise-calculate	~8.7K	~27.2K	~35.9K	~3.5K	~$0.16
Pipeline total			~134.0K	~25.8K	~$0.79

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

Context & Performance Guide

Session Management

Claude's context window is 200K tokens, shared across the session. For the franchise royalty pipeline (6 stages), start a fresh Claude session before running /franchise:franchise-pipeline for best quality. At 75 franchisees, the full pipeline uses only ~14% of the context window.

Data Volume Guidance

Tested with up to 75 franchisees in a single run. For networks larger than 75 locations, use batch mode: /franchise:franchise-pipeline --batch-size=25 to process in groups of 25 and merge outputs.

Tips for Best Results

1. Place input CSV in inbound/ before starting — file reading is more context-efficient than pasting data into chat
2. Keep messages concise during pipeline runs — every message stays in the context window
3. For highest quality audit reports, run /franchise:franchise-audit in a separate fresh session after the pipeline completes
4. If output quality degrades, start a new session and re-run the current stage — the plugin saves state between stages

Degradation Signals

If responses become shorter or skip sections, start a new session and re-run the current stage. State is preserved in .franchise/project.json.

Error Recovery

If a stage fails:

1. Fix the underlying issue (e.g., add missing CSV column)
2. Run:

   /franchise-pipeline --resume
   

3. Pipeline resumes from the failed stage without re-running completed stages

Performance

• 44 franchisees: ~30 seconds end-to-end
• 75 franchisees: ~45 seconds (batched processing)
• Bottleneck: Invoice generation (parallel possible with --parallel=true)

Requirements

• Python 3.7+
• python-docx >= 0.8.11
• pandas >= 1.5.0
• openpyxl >= 3.0.9
• 50 MB disk space for templates and sample data

All dependencies installed by franchise-setup.

Troubleshooting

Issue	Solution
CSV not found	Verify file in inbound/ with exact name sales-data.csv
Column mapping fails	Check CSV headers match or try manual column rename
Template not found	Re-run franchise-setup to regenerate templates
Math verification fails	Check for floating-point precision issues
Permission denied	Ensure workspace directory is writable

Support

For issues or questions:

1. Check USER-GUIDE.md for detailed documentation
2. Review CHANGELOG.md for recent updates
3. Verify input CSV format matches specification
4. Check .franchise/project.json for pipeline state

Version

v1.1 (March 2026) — Iteration 1: Deep Domain Knowledge

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 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, and related outputs are for informational purposes only. Consult a qualified CPA or financial advisor for tax and financial decisions.