Workday Compliance Agent Extension

Overview

This extension covers the development of standalone compliance rule engines designed to eventually integrate with Workday via the "Built on Workday" Marketplace program. Each agent follows the same architecture pattern and connects to Workday through a thin bridge adapter.

When to Use

Read this extension before building any new Workday-targeted compliance agent (ACA, multi-state tax, Davis-Bacon, or similar).

Architecture Pattern

Every agent follows this structure:

agent-name/
├── SPEC.md                    # What this agent does, IRS/regulatory sources
├── TASKS.md                   # QRPBA task queue
├── .foundry.json              # extensions: ["extend", "workday-agents"]
├── pyproject.toml             # Python 3.10+, FastAPI, Pydantic, pytest
├── src/<package>/
│   ├── models/
│   │   ├── <domain>.py        # Input: the record being audited (employee, worker, etc.)
│   │   └── finding.py         # Output: audit findings with severity, citation, remediation
│   ├── rules/
│   │   ├── __init__.py        # ALL_RULE_CHECKS list aggregating all modules
│   │   ├── <category_1>.py    # One module per rule category
│   │   ├── <category_2>.py    # Each exports check_<category>_rules(record) -> list[Finding]
│   │   └── ...
│   ├── engine/
│   │   └── auditor.py         # Stateless engine: loops ALL_RULE_CHECKS over records
│   ├── api/
│   │   └── routes.py          # FastAPI: POST /audit, GET /health, GET /findings/{id}
│   └── bridge/
│       └── workday.py         # Phase 2 stub: NotImplementedError, scopes documented
├── tests/
│   ├── conftest.py            # Fixture: engine instance
│   ├── fixtures/
│   │   └── scenarios.py       # Regulatory-derived test scenarios with known outcomes
│   ├── test_<category>.py     # One test file per rule category
│   └── test_api.py            # Endpoint tests
└── .buildloop/

Key Design Rules

Rule Functions

• Signature: check_<category>_rules(record: InputModel) -> list[AuditFinding]
• Stateless -- no side effects, no database, no external calls
• Return empty list when the rule category doesn't apply (e.g., no rehire data)
• Each finding includes: rule_id, severity, description, current vs. correct determination, penalty/impact estimate, regulatory citation, remediation

Rule ID Naming

• Format: CATEGORY-NNN (e.g., REHIRE-001, NEXUS-003, SAFE-002)
• When a generic rule and a specific rule can both fire for the same entity, the specific rule REPLACES the generic one (not supplements). Guard the generic rule with a method/type check.

Input Normalization

• All user-provided codes (state codes, category enums) must be normalized at the Pydantic model level via field_validator
• This includes dict KEYS, not just values (e.g., ytd_days_by_state, current_allocations)
• Never rely on case-sensitive lookups against user input

Regulatory Rule Compilation

• Rules come from public sources (IRS CFR, state statutes, DOL wage determinations)
• Compile rules into Python data structures, not a database
• Each rule must cite its source (CFR section, state statute, etc.)
• Rules change annually -- document the indexed year in constants

Ordering Dependencies

• Exemptions/reciprocity must resolve BEFORE general rules fire
• Specific overrides (convenience rule) must check BEFORE generic fallbacks (de minimis)
• When multiple rule categories interact, document the ordering in the engine

Testing

• Derive scenarios from regulatory guidance examples (IRS worked examples, state DOR publications)
• Every rule ID needs at least one positive test (the rule fires) and one negative test (clean record, no finding)
• Test the exact scenario from every Doubt/auditor finding as a regression

Workday Bridge (Phase 2)

• Document required API scopes in the bridge stub docstring
• Read-only access only -- agents audit, they don't write back
• Scopes needed vary by domain:
• ACA: Benefits, Human_Resources, Time_Tracking, Absence_Management, Payroll
• Multi-state tax: Time_Tracking, Human_Resources, Payroll
• Rate limit: ~10 calls/sec per tenant. Batch operations, don't stream.

SPEC.md Accuracy

• The SPEC overview must reflect the current phase (standalone engine vs. integrated marketplace app)
• Counts (rules, states, tests) must match the implementation -- update on every commit
• If the bridge is a stub, say so in the spec

Agent Roster

Complete (Phase 1)

Ready to Build (SPEC + TASKS written, run foundry in the directory)

Killed (researched, not viable)

After Building a New Agent

1. Add it to the table above
2. Capture lessons from Doubt/auditor findings as a new skill: plugins/workday-agents/skills/<slug>/SKILL.md
3. If broadly applicable, also copy to ~/.foundry/skills/<slug>/SKILL.md