deal-to-invoice

Deal to Invoice

The gap between "yes" and "paid, scheduled, and scoped" is where deals stall. Run that gap as one checklist, and never touch billing or the client's calendar without the owner's explicit approval on exact values.

Files

• Proposals: $WORKDIR/pipeline/proposals/*.md
• Deal log: $WORKDIR/pipeline/deals.jsonl (append-only, latest line per deal_id wins)
• Delivery checklists: $WORKDIR/pipeline/deals/<deal-slug>-delivery.md

Workflow

1. Confirm terms. Read, do not assume. Open the accepted proposal. Pull client name, company, contact email, total fee, payment split, deliverables, timeline, kickoff date. If the acceptance changed anything (scope, price, date), get the owner to confirm final terms before touching billing. The proposal file is the source of truth; the deal record snapshots it.
2. Create billing objects, behind an approval gate. Show the owner the exact product name, price amounts, and link settings, then wait for an explicit yes. One product per deal. One price per milestone: a 50/50 split is two separate one-time prices, not one price used twice, so each charge reads clearly on the client's statement. One payment link per milestone, quantity locked to 1. Create only the link for the milestone due now (usually kickoff); create the delivery link when delivery is accepted, not before. After creation, list the payment links back from the billing provider and record the URLs.
3. Draft the payment message. The owner sends it. Write the email or DM carrying the kickoff payment link: plain operator voice, restates the milestone amount, states what triggers the next invoice, confirms the kickoff date. This skill never sends outbound.
4. Book the kickoff. Create the calendar event: title "Kickoff: <client company> <project>", default 45 minutes, description linking the proposal path and the delivery checklist path. Add the client as attendee only after the owner approves the invite going out.
5. Instantiate the delivery checklist. Create pipeline/deals/<deal-slug>-delivery.md from the proposal: deliverables become checklist items, timeline blocks become phase headers, and the out-of-scope list is copied verbatim so scope creep hits a written wall.
6. Record the deal. Append one JSON line to deals.jsonl with: deal_id, timestamp, client fields, proposal path, amount, payment terms, billing object IDs, payment link URLs, kickoff date, calendar event ID, checklist path, status, notes. Statuses: accepted > invoiced_kickoff > paid_kickoff > in_delivery > invoiced_delivery > paid_delivery > closed_won, or stalled / closed_lost with a note. Update by appending a new line with the same deal_id.

Operating Rules

1. Explicit owner approval before any billing object is created and before any invite reaches the client. Show exact values first.
2. Draft the payment message; never send it.
3. One payment link per milestone, created only when due.
4. Payment not in by kickoff date: kickoff moves. Flag it. Never start delivery unpaid.
5. Check the billing provider's payment records before nudging about an unpaid link; the money may already be in.
6. Every deal gets a deals.jsonl line the same day the yes lands, even if billing setup waits.

Verification

Run these before calling it done. Open the payment link URL: expect the correct amount and product name. Check the calendar: expect the event on the confirmed date. Grep the checklist for unfilled placeholders: expect zero. Parse the new deals.jsonl line with python3 -c "import json,sys; json.loads(sys.stdin.read())": expect no error. Any failure: fix the artifact before reporting the deal as set up.

Good vs Bad

Judgment call: the acceptance message mentions "we'd also like the reporting module".

Bad: Create the payment link for the original amount and note the extra scope in the checklist. Now scope grew and price did not.

Good: Stop. Flag the scope change to the owner, get a confirmed price and deliverable list, then run the workflow on the confirmed terms.

Footguns

• Reusing one price for two milestones. The client's statement shows two identical opaque charges. Fix: separate named prices per milestone.
• Creating the delivery-milestone link early. It sits live and can be paid out of order. Fix: create links only when the milestone is due.
• Calendar invite fired before approval. The client gets an invite for an unconfirmed date. Fix: create the event without attendees, add the client after approval.
• Deal recorded only after billing setup. Billing blockers then mean no record exists at all. Fix: log the accepted line immediately.

Red Flags

Stop if you catch yourself thinking or saying:

• "The terms are basically the same, no need to reconfirm"
• "I'll just send the link myself, it's faster"
• "I'll create both payment links now to save a step"
• "The owner approved a deal like this before"

Each approval covers exactly one deal and one set of exact values. Anything not shown and approved is not approved.

Completion Checklist

• [ ] Terms confirmed from the proposal file, changes re-approved by owner
• [ ] Billing objects approved on exact values, created, and verified
• [ ] Payment message drafted, not sent
• [ ] Kickoff booked, invite gated on approval
• [ ] Delivery checklist has zero unfilled placeholders
• [ ] deals.jsonl line appended and parses

Any box unchecked: not done. Fix or say so.