Skip to main content

ALAI Client Invoice Cycle — Runbook

ALAI Client Invoice Cycle — Runbook

Purpose: Actionable command sequence for creating, sending, tracking, and collecting a client invoice. Full skill workflow: ~/.claude/skills/invoice/SKILL.md. Audience: John (primary), Finverge (accounting/Fiken sync), Alem (approval gate) Last updated: 2026-07-28

Step 1 — Validate the Client

NODE_PATH=~/system/node_modules node ~/system/tools/contacts.js search "<client>"
NODE_PATH=~/system/node_modules node ~/system/tools/contacts.js show <id>
  • Client not in contacts.db → ask Alem for details, add them. Never fabricate.
  • No email on file → ask Alem, do not guess.
  • Confirm org number + address are present (required on the invoice).

Step 2 — Collect Invoice Data

Interactively (from Alem or existing context):

  1. Client (name/company)
  2. Amount (excl. VAT)
  3. Currency (NOK, EUR, USD, BAM, RSD)
  4. Description (what's being billed)
  5. Line items (optional, for detail)
  6. Payment terms (default 14 days)
  7. Reference (project, contract, PO number) — mandatory, every invoice must tie to a contract or PO

Step 3 — Create the Invoice

NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js create "<client>" <amount> <currency> "<description>"

Verify the tool output:

  • Invoice ID assigned
  • 25% MVA auto-added for NOK invoices
  • Total = amount + MVA
  • Due date = today + payment terms
  • PDF generated in ~/system/deliverables/invoices/

Step 4 — CEO Review (mandatory, no exceptions)

Show Alem before sending:

Client: {name}
Amount: {amount} {currency}
MVA (25%): {mva}
Total: {total} {currency}
Description: {description}
Due date: {date}
Payment terms: {days} days

Wait for explicit "OK" / "SEND". Never send an invoice without approval — invoice = HIGH-risk draft classification.

Step 5 — Draft, Approve, Send

NODE_PATH=~/system/node_modules node ~/system/tools/drafts.js list pending
NODE_PATH=~/system/node_modules node ~/system/tools/drafts.js approve <draft-id>
NODE_PATH=~/system/node_modules node ~/system/tools/drafts.js send <draft-id>

Or directly via MCP email if no draft was auto-created:

mcp__email__email_send(
  account: "john",
  to: "<client-email>",
  subject: "Invoice #<id> — ALAI Holding AS",
  body: "<text>",
  attachments: ["~/system/deliverables/invoices/INV-<id>.pdf"]
)

Step 6 — Fiken Sync (accounting)

NODE_PATH=~/system/node_modules node ~/system/tools/fiken.js invoices sync

Run after every new invoice if the client has a Fiken contact configured.

Step 7 — Auto-Remind Schedule

The pipeline-watcher daemon runs the reminder cadence automatically:

Day Action
Day 7 Friendly reminder — auto-sent, Norwegian
Day 14 Firm reminder — auto-sent + Slack notify
Day 30+ Escalation — MC task created for Alem

Check status / send manually if needed:

NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js list overdue
NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js remind <invoice-id>

Step 8 — Ongoing Tracking

NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js list all
NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js list unpaid
NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js list overdue
NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js stats
NODE_PATH=~/system/node_modules node ~/system/tools/fiken.js dashboard

For a full financial position (bank balances + outstanding + pipeline forecast), use /financial-overview:

NODE_PATH=~/system/node_modules node ~/system/tools/fiken.js balances

Hard Rules

  1. 25% MVA on all NOK invoices — invoice-generator.js adds it automatically. Verify the total before sending.
  2. CEO approves every invoice — invoice = HIGH risk. Never send without Alem's explicit "OK".
  3. Client must exist in contacts.db — no invoice for an unregistered contact.
  4. Reference is mandatory — every invoice ties to a contract or PO number.
  5. ALAI branding — PDF uses the standard ALAI invoice template.
  6. Currency matches the contract — never mix NOK/EUR on the same client relationship.
  7. Anti-hallucination — never invent an amount. If Alem hasn't stated a figure, ask.
  8. Due date is realistic — default 14 days; check the contract for custom terms.
  9. Fiken sync after every new invoice where Fiken is configured for the client.

References

  • Skill: ~/.claude/skills/invoice/SKILL.md
  • Financial overview skill: ~/.claude/skills/financial-overview/SKILL.md
  • Invoice DB: ~/system/databases/invoices.db
  • Templates: ~/system/templates/invoices/standard-invoice.html
Back to top