semillero-special-hotel/.agents/plugins/remuneration-plugin/skills/remuneration-orchestrator/SKILL.md

name	description
remuneration-orchestrator	Coordinates the Variable Remuneration, Compensation, and Commissions multi-agent team (Planner, Calculator, QA Auditor). Use this when executing or verifying commission calculations, setting up goals/quotas, validating plans, running delta check clawbacks, testing RLS security, or updating results. Use to re-run, modify, update, correct, check, or audit existing calculations and plan versions.

Remuneration Orchestrator

Wires the multi-agent pipeline: Planner Agent -> Calculator Agent -> QA Auditor Agent to manage plans, execute settlements, and audit outputs.

Execution Mode: Sequential Subagent Mode

Subagent Team Configuration

Agent TypeName	Core Role	Assigned Skills	Intermediate Outputs
planner-agent	Plan & Goal Architect	plan-management	_workspace/02_planner_plans.json
calculator-agent	Calculation Engine	settlement-calculation, integration-validation	_workspace/03_calculator_settlements.json
qa-auditor-agent	Compliance & QA Auditor	reconciliation-auditing	_workspace/04_qa_audit_report.json

Workflow Phases

Phase 0: Context Check (Incremental & Follow-up Support)

1. Verify if the _workspace/ directory exists under the project root.
2. Determine execution mode:
   • No _workspace/ folder: Initial run. Proceed to Phase 1.
   • _workspace/ exists + User requests partial edit/fix: Partial re-run. Identify the failing or target agent, call it using invoke_subagent with the existing input/output files in the prompt, and overwrite only the target outputs.
   • _workspace/ exists + User provides new raw data/plan: Fresh run. Backup the current workspace to _workspace_backup_<timestamp>/ and create a clean _workspace/ folder.
3. For partial re-runs, ensure the subagent receives paths to previous outputs to merge changes correctly.

Phase 1: Setup & Initialization

1. Parse the user's input request, target collaborators, plans, and period.
2. Ensure _workspace/ is created and initialize _workspace/00_input/.
3. Save raw input parameters or JSON configurations to _workspace/00_input/parameters.json.

Phase 2: Plan Validation & Goals Mapping

1. Invoke the planner-agent to check goals and plan statuses.
   • TypeName: planner-agent
   • Role: Plan Manager
   • Prompt: "Read the inputs from _workspace/00_input/parameters.json. Verify the compensation plans, quotas, and goals. Ensure active plans are version-controlled and not modified in place. Write the validated configuration to _workspace/02_planner_plans.json."
2. Read the output of planner-agent to ensure no validation flags or unresolved conflicts remain.

Phase 3: Settlement Execution & Retroactive Clawbacks

1. Invoke the calculator-agent to process formulas, run delta checks, and trigger n8n workflows.
   • TypeName: calculator-agent
   • Role: Commission Calculator
   • Prompt: "Using the validated plans in _workspace/02_planner_plans.json, perform the settlement calculation. Verify historical sales for retroactive clawbacks (delta checks). Route tests through /webhook-test endpoints on the internal hostnames. Ensure all aiAuditNotes and flaggedReason strings are stored as bilingual { en, es } JSON objects. Write outputs to _workspace/03_calculator_settlements.json."
2. Verify that settlements were successfully generated.

Phase 4: QA Auditing & Compliance Checks

1. Invoke the qa-auditor-agent to run assertion checks and RLS validations.
   • TypeName: qa-auditor-agent
   • Role: QA Auditor
   • Prompt: "Audit the calculation outputs in _workspace/03_calculator_settlements.json. Verify row-level security (RLS) constraints for the collaborators, ensure log immutability is respected, and assert that aiAuditNotes and flaggedReason are correctly formatted as bilingual { en, es } JSON objects. Write your report to _workspace/04_qa_audit_report.json."
2. Read the audit report. If critical violations (e.g. invalid bilingual JSON, RLS failures) are found, request corrections from the respective agent.

Phase 5: final Integration & Output Generation

1. Read the final QA audit report and the calculation outputs.
2. Compile and save the final settlement run summary to docs/settlement_run_latest.md.
3. Keep the _workspace/ directory preserved for history/auditing.
4. Report the summary of the run to the user, highlighting calculations, adjusted clawbacks, and validation status.

Data Flow Diagram

graph TD
    User([User Request]) --> P1[Phase 1: Setup]
    P1 -->|Save input| RawFile[_workspace/00_input/parameters.json]
    RawFile --> P2[Phase 2: planner-agent]
    P2 -->|Validate plans| PlanFile[_workspace/02_planner_plans.json]
    PlanFile --> P3[Phase 3: calculator-agent]
    P3 -->|Run settlement & n8n| CalcFile[_workspace/03_calculator_settlements.json]
    CalcFile --> P4[Phase 4: qa-auditor-agent]
    P4 -->|Verify RLS & i18n JSON| QAFile[_workspace/04_qa_audit_report.json]
    QAFile --> P5[Phase 5: Orchestrator Integration]
    P5 -->|Write summary| FinalOut[docs/settlement_run_latest.md]

Error Handling Matrix

Failure Mode	Resolution Strategy
Subagent execution error	Retry once. If failure persists, record the traceback, fallback to a safe null output, and flag the failure in the final report.
Non-bilingual { en, es } notes	Re-invoke the calculator-agent to apply the translation chain and rewrite the fields as valid { en, es } JSON.
RLS constraint breach	Immediately halt the pipeline, mark the run as FAILED, and notify the user with the trace details.
n8n webhook connection failure	Verify shared Docker network routing between Caddy and n8n, check internal hostnames, and retry with the correct endpoint.

Verification Test Scenarios

Scenario 1: Standard Commission Run (Success)

1. Input: Quota/goals for collaborator "Juan Perez" with monthly sales data.
2. Execution: Planner validates goal, Calculator computes commission and translates notes to Spanish/English, QA Auditor verifies RLS rules and bilingual JSON.
3. Expected Outcome: docs/settlement_run_latest.md created, all tests pass, and database stores bilingual notes.

Scenario 2: RLS Validation Failure (Error Fallback)

1. Input: Sales imports trying to cross-read records of another hotel site without appropriate permissions.
2. Execution: Planner passes layout, Calculator executes, but QA Auditor detects RLS violation during boundary checking.
3. Expected Outcome: Run halted. No settlements approved. Error logged in _workspace/04_qa_audit_report.json.