docs(billing): add org KiloClaw billing specs#3060
docs(billing): add org KiloClaw billing specs#3060jeanduplessis wants to merge 7 commits intomainfrom
Conversation
Code Review SummaryStatus: 2 Issues Found | Recommendation: Address before merge Overview
Issue Details (click to expand)WARNING
Files Reviewed (9 files)
Reviewed by gpt-5.5-2026-04-23 · 2,178,678 tokens |
Adds /prototype/org-kc-billing — a design-review surface that renders every visual element from .plans/org-kiloclaw-billing-ui.md with mock data, role-aware variants (admin / member), and a journey-ordered TOC. Covers PR 1–4b plus Wave A–C: subscription page (admin + member), status banners, lock dialogs, destroy confirm, provisioning preflight, org settings tabs + Enterprise opt-out, subscription detail page + group + dashboard alert, associated-user banner, and instance owner chip. Sidebar nav and dashboard CTA mocks surface the cross-PR navigation deltas. Also adds: - PRODUCT.md and design.md (impeccable skill context) - .impeccable/design.json (design tokens manifest) - yellow color in shared Banner (additive, no behavior change for existing callers)
![kilo-code-bot[bot]](https://avatars.githubusercontent.com/in/2193792?s=60&v=4){kind=small}
|
|
||
| export function formatDate(iso: string | null | undefined, fallback = '—'): string { | ||
| if (!iso) return fallback; | ||
| return new Date(iso).toLocaleDateString('en-US', { |
There was a problem hiding this comment.
WARNING: Date-only fixtures can render one day early
Several mock dates are stored as YYYY-MM-DD strings, and new Date('2026-06-12') is parsed as UTC midnight before being formatted in the viewer's local timezone. Users in negative-offset time zones can see the previous day for renewal/trial dates, which makes the billing prototype show incorrect deadlines. Format date-only values in UTC or parse them as local calendar dates before calling toLocaleDateString.
| </TableCell> | ||
| <TableCell className="py-3"> | ||
| <div className="flex flex-wrap gap-1.5"> | ||
| <StatusBadge kind={row.operationalKind} /> |
There was a problem hiding this comment.
WARNING: Canceled rows show conflicting statuses
Canceled subscriptions still render the operational badge first. The canceled fixture has operationalKind: 'available', so this table displays both Active and Canceled for the same row. Use the effective subscription status for canceled rows, or skip the operational badge when showCanceledBadge is true.
alexkgold
left a comment
alexkgold
left a comment
There was a problem hiding this comment.
Had a bunch of nitpicky comments.
The biggest issue I see here is a bunch of confusion around trial duration.
Here's what I'd propose:
- KiloClaw trials are always 7 days, irrespective of user or org.
- Kilo admins can arbitrarily adjust KiloClaw trial end dates for the individual KiloClaw
- KiloClaw trial duration is not affected by organization state (Trial, purchased, past due)
- KiloClaw access is contingent on organization state (aka, can only access if in trial/purchased and paid)
| - **Organization KiloClaw opt-out**: An Enterprise-only organization | ||
| admin setting that disables organization KiloClaw access and | ||
| provisioning while enforced. | ||
| - **Organization KiloClaw billing launch date**: The date from which |
There was a problem hiding this comment.
I'm not sure it matters, but org seats trials are only 2 weeks (can't remember if 14 or 15 days). Unless there's a good reason to do 30 days, I think we should align duration with either seats trial duration or regular KiloClaw trial.
| access before org billing launches are also outside these funding | ||
| invariants; they remain a temporary carveout until org billing | ||
| integration ships. | ||
| exempt from the paid funding invariants in rules 2 and 3. Organization |
There was a problem hiding this comment.
This sentence on Org KiloClaws feels like a non-sequitor?
Maybe it has no relation to the sentence before? I'm just not claer if it should.
| 9. Internal plan fields MAY remain future-compatible, but org KiloClaw | ||
| UI/API behavior MUST expose only the month-to-month organization | ||
| plan. | ||
| 10. Creating an organization KiloClaw subscription, including a trialing |
There was a problem hiding this comment.
So that means I can't start the trial unless I've already added credits to the account?
| backfill. | ||
| 11. If organization credits are insufficient at creation, the system | ||
| MUST NOT create or activate the subscription. | ||
| 12. When creation fails for insufficient credits, organization owners |
There was a problem hiding this comment.
This feels out of scope and related to separate work about admin credit management (which admittedly needs work as well).
|
|
||
| #### Organization Trials | ||
|
|
||
| 1. A user receives at most one 7-day organization KiloClaw trial per |
| organization trial end and the associated user's 7-day org KiloClaw | ||
| trial end. | ||
| 5. Organization-trial time MAY consume the user's 7-day KiloClaw trial. | ||
| 6. If the organization becomes active after the user's 7-day KiloClaw |
| organization KiloClaw billing launch date. | ||
| 8. Existing organization KiloClaw launch-trial backfill MUST NOT deduct | ||
| organization credits at creation. | ||
| 9. The 30-day billing-launch trial is migration-granted access and |
There was a problem hiding this comment.
There is a mixture of 30 day and 7 day trials here. That is confusing.
| 6. Organization KiloClaw state MUST NOT affect, extend, or recover the | ||
| parent organization subscription state. | ||
|
|
||
| #### Organization Trials |
There was a problem hiding this comment.
To add: A kilo admin (not account admin) must have the ability to arbitrarily extend individual KiloClaw trials.
| provisioning, and trial or credit rules allow subscription creation. | ||
| 2. The associated user MAY manage their own organization KiloClaw | ||
| lifecycle. | ||
| 3. Organization owners and billing managers MAY manage any organization |
There was a problem hiding this comment.
Just flagging this requirement adds a whole layer of UX
| 5. Non-billing-admin associated users MUST NOT see subscription details, | ||
| including price, organization credit balance, invoices, billing | ||
| period dates, renewal dates, or subscription identifiers. | ||
| 6. Non-billing-admin associated users MAY see operational access state, |
There was a problem hiding this comment.
Just for their own? Or for all in the org?
I'd suggest just for their own.
3 participants
Summary
Adds source-of-truth spec coverage for organization-context KiloClaw subscription billing before implementation work begins.
Verification
Reviewed the updated specs for coherence with the agreed org KiloClaw billing decisions, existing KiloClaw billing invariants, and Team/Enterprise entitlement rules.
Visual Changes
N/A
Reviewer Notes