Developer Handover Pack

Developer Handover Pack

Tax Preparation Workflow

Compares the QuickBooks transaction export against the expected document checklist and identifies every missing receipt, uncategorised entry, or unmatched statement. Builds a structured request list broken down by employee or vendor. This agent fires at the start of each preparation window and produces the input list that drives all downstream agents. It must handle QuickBooks Online OAuth token refresh transparently and must not re-flag transactions already resolved in a prior partial run. Complexity: Moderate. Estimated build time: 10 hours.

// Input
quickbooks.export.profit_loss   -> { period_start, period_end, line_items[] }
quickbooks.export.general_ledger -> { transactions[]: { txn_id, date, vendor, amount, category, receipt_attached } }
google_drive.checklist_sheet    -> { required_docs[]: { doc_type, employee_or_vendor, due_date } }

// Output
gap_list: {
  missing_receipts[]:    { txn_id, employee, amount, date, category }
  uncategorised_txns[]:  { txn_id, vendor, amount, date }
  unmatched_statements[]:{ account_id, period, expected_closing_balance }
  generated_at:          ISO8601 timestamp
  preparation_period:    { start, end }
}

Sends personalised receipt request emails to employees via Gmail, monitors replies and uploads, processes incoming documents through Hubdoc, and matches each receipt to its corresponding QuickBooks transaction. Any item that cannot be matched automatically is escalated to the bookkeeper via a dedicated Slack channel with full transaction context. This agent handles steps 4, 5, and 6 of the manual process and is the highest-volume agent in the workflow. Complexity: Complex. Estimated build time: 18 hours.

// Input
gap_list.missing_receipts[]: { txn_id, employee_email, amount, date, category, vendor }
gmail.inbound_reply:          { from_email, thread_id, attachments[]: { filename, mime_type, file_data } }
hubdoc.extraction_result:     { doc_id, vendor_name, date, total_amount, currency, confidence_score }

// Output
receipt_log: {
  matched[]:   { txn_id, hubdoc_doc_id, qb_attachment_id, confidence_score, matched_at }
  unmatched[]: { txn_id, employee_email, reason_code, escalated_at }
}

// On exception (unmatched item)
slack.post to #tax-exceptions: {
  txn_id, employee, amount, date, category,
  reason_code: 'LOW_CONFIDENCE' | 'NO_REPLY' | 'WRONG_AMOUNT' | 'DUPLICATE',
  action_required: 'Bookkeeper to resolve manually'
}

Assembles the verified reports, matched receipts, and reconciled statements into a structured document package in Google Drive, then dispatches the DocuSign sign-off request to the appropriate approver. Posts a Slack notification to the Finance Manager confirming the package is ready for the accountant. This agent is triggered only after the bookkeeper has confirmed all manual exception items are resolved. Complexity: Moderate. Estimated build time: 10 hours.

// Input
receipt_log.matched[]:           { txn_id, hubdoc_doc_id, qb_attachment_id }
quickbooks.reports[]:            { report_type, file_id, period }
google_drive.checklist_sheet:    { all items status = 'resolved' }
slack.trigger_event:             { user_id, action: 'confirm_exceptions_resolved', period }

// Output
google_drive.package_folder: {
  folder_id,
  folder_path: '/Tax Packages/{YYYY-QQ}/',
  contents[]: { file_name, file_id, category }
}
docusign.envelope: {
  envelope_id,
  signer_email,
  signer_name,
  status: 'sent',
  sent_at: ISO8601 timestamp
}

// On approval (DocuSign webhook callback)
docusign.envelope.status = 'completed' ->
  slack.post to #finance-ops: {
    message: 'Tax package signed off. Ready for accountant.',
    drive_folder_link, envelope_id, completed_at
  }

// ── TRIGGER ──────────────────────────────────────────────────────────────
// Scheduled cron OR manual trigger from Finance Manager
TRIGGER: preparation_window_open
  -> payload: { period_start: DATE, period_end: DATE, entity_id: STRING }

// ── STEP 1: QuickBooks report export ─────────────────────────────────────
// Automation platform calls QuickBooks Reports API
GET /v3/company/{realmId}/reports/ProfitAndLoss
  params: { start_date, end_date, accounting_method: 'Accrual' }
  -> profit_loss: { rows[]: { account, amount } }

GET /v3/company/{realmId}/reports/GeneralLedger
  params: { start_date, end_date }
  -> general_ledger: { transactions[]: { txn_id, date, vendor, amount, category, receipt_attached: BOOL } }

// ── HANDOFF 1: To Document Gap Detector ─────────────────────────────────
AGENT_IN (Document Gap Detector):
  general_ledger.transactions[]
  google_drive.checklist_sheet -> required_docs[]: { doc_type, employee_or_vendor, status }

AGENT_LOGIC:
  FOR EACH txn IN general_ledger.transactions:
    IF txn.receipt_attached == FALSE OR txn.category == NULL:
      append to gap_list.missing_receipts { txn_id, employee, amount, date, category }
  FOR EACH doc IN required_docs WHERE doc.status != 'received':
      append to gap_list.unmatched_statements { account_id, period }

AGENT_OUT (Document Gap Detector):
  gap_list: { missing_receipts[], uncategorised_txns[], unmatched_statements[], generated_at }
  -> written to: error_log_table { run_id, period, gap_list_json, created_at }

// ── HANDOFF 2: To Receipt Collection Coordinator ─────────────────────────
AGENT_IN (Receipt Collection Coordinator):
  gap_list.missing_receipts[]: { txn_id, employee_email, amount, date, category, vendor }

AGENT_LOGIC (per missing_receipt):
  gmail.send(
    to: employee_email,
    template: 'receipt_request_v1',
    vars: { employee_name, txn_date, amount, vendor, upload_link }
  )
  -> thread_id stored against txn_id in run state

  ON inbound reply (gmail.watch Pub/Sub event):
    attachment -> POST /hubdoc/documents (multipart/form-data)
    POLL GET /hubdoc/documents/{doc_id} until status = 'processed'
    hubdoc_result: { vendor_name, date, total_amount, confidence_score }

  MATCH hubdoc_result TO general_ledger.txn:
    IF amount_delta <= 0.10 AND date_delta <= 3 days AND vendor_fuzzy <= 2:
      -> POST /v3/company/{realmId}/attachments { txn_id, doc_id }  // attach to QB
      -> receipt_log.matched[]: { txn_id, hubdoc_doc_id, qb_attachment_id, confidence_score }
    ELSE:
      -> receipt_log.unmatched[]: { txn_id, reason_code }
      -> slack.post #tax-exceptions { txn_id, employee, amount, reason_code }

  IF no reply after 3 business days:
    gmail.send follow_up (once)
    IF no reply after further 3 days:
      slack.post #tax-exceptions { action: 'ESCALATE', txn_id, employee_email }

AGENT_OUT (Receipt Collection Coordinator):
  receipt_log: { matched[], unmatched[] }
  -> written to: error_log_table { run_id, receipt_log_json, updated_at }

// ── MANUAL STEP: Bookkeeper resolves exceptions ───────────────────────────
// Bookkeeper reviews #tax-exceptions, resolves items manually (<30 min/cycle)
// When done, triggers Package Builder via Slack button or /resolve-exceptions slash command
SLACK_EVENT: { user_id, action: 'confirm_exceptions_resolved', period }

// ── HANDOFF 3: To Package Builder and Dispatcher ─────────────────────────
AGENT_IN (Package Builder and Dispatcher):
  receipt_log.matched[]
  quickbooks.reports[]: { report_type, file_id, period }
  google_drive.checklist_sheet (all statuses confirmed = 'resolved')

AGENT_LOGIC:
  CREATE Drive folder: /Tax Packages/{YYYY}/{QQ}/
  COPY reports      -> /Tax Packages/{YYYY}/{QQ}/Reports/
  COPY receipts     -> /Tax Packages/{YYYY}/{QQ}/Receipts/
  COPY statements   -> /Tax Packages/{YYYY}/{QQ}/Statements/
  UPDATE checklist_sheet: all rows status = 'packaged'

  POST /docusign/envelopes {
    templateId: entity_template_id,
    signers[]: [{ email: director_email, name: director_name, role: 'Director' }],
    emailSubject: 'Tax Return Sign-Off Required - {period}'
  }
  -> envelope_id stored in run state

ON DocuSign Connect webhook { envelope_id, status: 'completed' }:
  slack.post #finance-ops {
    message: 'Package signed. Ready for accountant.',
    drive_folder_link, envelope_id, completed_at
  }

ON DocuSign Connect webhook { envelope_id, status: 'declined' }:
  slack.post #tax-exceptions { alert: 'Sign-off declined. Investigate.' }
  -> HALT workflow

// ── END ──────────────────────────────────────────────────────────────────
// Final state: signed package in Drive, Slack confirmation sent,
// run record closed in error_log_table { run_id, status: 'complete', completed_at }