@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/stripe-integration/references/billing.md

@@ -0,0 +1,58 @@
+# Stripe subscriptions, customer portal and test clocks
+
+## Subscription via Checkout
+
+```ts
+const session = await stripe.checkout.sessions.create(
+  {
+    mode: 'subscription',
+    customer: user.stripeCustomerId, // create the Customer once per user and store it
+    line_items: [{ price: plan.priceId, quantity: 1 }],
+    subscription_data: { trial_period_days: 14, metadata: { user_id: user.id } },
+    success_url: 'https://app.example.com/billing/success?session_id={CHECKOUT_SESSION_ID}',
+    cancel_url: 'https://app.example.com/billing',
+  },
+  { idempotencyKey },
+);
+```
+
+Store `session.subscription` from `checkout.session.completed`. From then on, the subscription `status` is the source of truth for access:
+
+| `status` | Typical access |
+|---|---|
+| `trialing`, `active` | Full |
+| `past_due` | Your policy: grace period while Stripe retries |
+| `unpaid`, `canceled`, `incomplete_expired`, `paused` | None |
+| `incomplete` | None until the first invoice is paid (often SCA pending) |
+
+Sync it on `customer.subscription.created`, `.updated` and `.deleted`, and extend access to the period end on `invoice.paid`. On API version `2025-03-31.basil` and later, the period fields are on subscription items (`items.data[].current_period_end`), not on the subscription; older versions have `subscription.current_period_end`. Read the field for the API version you pinned. If events arrive out of order, retrieve the subscription from the API and store what it says.
+
+Plan changes: `stripe.subscriptions.update(subId, { items: [{ id: itemId, price: newPriceId }], proration_behavior: 'create_prorations' })` with an idempotency key, or let the portal do it.
+
+## Customer portal
+
+1. Configure features (cancel, switch plan, update payment method, invoice history) in the Dashboard's customer portal settings, or with `stripe.billingPortal.configurations.create`.
+2. From an authenticated route:
+
+```ts
+const portal = await stripe.billingPortal.sessions.create({
+  customer: currentUser.stripeCustomerId, // from your session, never from the request body
+  return_url: 'https://app.example.com/billing',
+});
+redirect(portal.url);
+```
+
+Changes made in the portal arrive as the same subscription and invoice webhooks; no extra handling.
+
+## Test clocks
+
+Test clocks simulate time for billing objects in test mode or a sandbox.
+
+```ts
+const clock = await stripe.testHelpers.testClocks.create({ frozen_time: Math.floor(Date.now() / 1000) });
+const customer = await stripe.customers.create({ email: 'trial@example.com', test_clock: clock.id });
+// attach a test payment method, create the subscription, then:
+await stripe.testHelpers.testClocks.advance(clock.id, { frozen_time: clock.frozen_time + 15 * 24 * 3600 });
+```
+
+Advancing is asynchronous: wait for the clock's status to return to `ready` (or the `test_helpers.test_clock.ready` event) before asserting. Scenarios worth running: trial converts to paid, renewal succeeds, renewal fails with `4000 0000 0000 0341` attached (card attaches but charges fail), cancellation at period end takes effect. Only customers created with the clock move with it; delete the clock when done.

package/skills/stripe-integration/references/webhooks.md

@@ -0,0 +1,76 @@
+# Stripe webhooks
+
+## What Stripe sends
+
+- `POST` with a JSON `Event` (snapshot payload) or a thin event notification, depending on how the event destination was created. Most existing integrations use snapshot events and read `event.data.object`.
+- Header `Stripe-Signature: t=<timestamp>,v1=<hmac-sha256>[,v1=...]`. The signature is HMAC-SHA256 of `"<t>.<raw body>"` with the endpoint's `whsec_` secret. Only `v1` is valid; ignore other schemes.
+- Live mode retries with exponential backoff for up to three days; sandboxes retry three times over a few hours. `3xx` counts as failure.
+- Delivery is at least once and order is not guaranteed. Don't use `created` to order or dedupe; track `event.id`.
+- Each endpoint, and test vs live, has its own signing secret. During a secret roll, two secrets may be active for up to 24 hours.
+
+## Handler rules
+
+1. Read the **raw body bytes**. Any body parser that runs first breaks verification.
+2. `stripe.webhooks.constructEvent(rawBody, signatureHeader, endpointSecret)`; on error respond `400` and stop. Keep the default 5-minute tolerance and keep server clocks synced.
+3. Respond `2xx` immediately, then process in a queue.
+4. In the worker: skip if `event.id` is already recorded; otherwise handle the type, fetch fresh objects from the API when you need current state, and record `event.id` in the same database transaction as the state change.
+5. Subscribe the endpoint only to the event types you handle.
+6. Exempt the route from CSRF middleware (Rails, Django, Laravel).
+
+## Express (TypeScript)
+
+```ts
+import express from 'express';
+import Stripe from 'stripe';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+const app = express();
+
+// Must be registered before app.use(express.json())
+app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
+  let event: Stripe.Event;
+  try {
+    event = stripe.webhooks.constructEvent(req.body, req.header('stripe-signature') ?? '', process.env.STRIPE_WEBHOOK_SECRET!);
+  } catch {
+    return res.sendStatus(400);
+  }
+  res.sendStatus(200);
+  queue.add('stripe-event', { id: event.id, type: event.type, objectId: (event.data.object as { id: string }).id });
+});
+```
+
+## Next.js route handler
+
+```ts
+export async function POST(req: Request) {
+  const raw = await req.text(); // unparsed body
+  try {
+    const event = stripe.webhooks.constructEvent(raw, req.headers.get('stripe-signature') ?? '', process.env.STRIPE_WEBHOOK_SECRET!);
+    await enqueue(event.id, event.type);
+  } catch {
+    return new Response('invalid signature', { status: 400 });
+  }
+  return new Response('ok');
+}
+```
+
+## Events to handle
+
+| Event | Do |
+|---|---|
+| `checkout.session.completed` | If `payment_status` is `paid`, fulfil the order in `client_reference_id` / `metadata.order_id` once |
+| `checkout.session.async_payment_succeeded` / `_failed` | Fulfil or fail delayed-method payments |
+| `payment_intent.succeeded` / `payment_intent.payment_failed` | Custom Payment Element flows |
+| `invoice.paid` | Extend subscription access to the new period |
+| `invoice.payment_failed` | Start dunning; notify the customer |
+| `customer.subscription.updated` / `customer.subscription.deleted` | Sync plan, status and cancellation |
+| `charge.refunded`, `charge.dispute.created` | Reverse or flag fulfilment |
+
+## Local testing
+
+```bash
+stripe login
+stripe listen --forward-to localhost:4242/webhooks/stripe   # prints a whsec_ for this session
+stripe trigger checkout.session.completed
+stripe events resend <event_id> --webhook-endpoint=<endpoint_id>
+```

package/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: subagent-driven-development
+description: Carries out a written implementation plan one task at a time, handing each task to a fresh implementer subagent with the full task text and context pasted in, answering its questions before work begins, and requiring a self-review and report. Every task then passes a spec-compliance check by the spec-reviewer agent and only afterwards a code-quality check by the code-reviewer agent, looping fix and re-review until both pass, with a progress ledger and a whole-branch review at the end. Falls back to inline execution on hosts without subagents. Use when a plan file exists and the user wants it executed task by task with independent review gates between tasks.
+license: MIT
+compatibility: Best on hosts with subagents; has an inline fallback. Needs git and the project's test runner.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Subagent-driven development
+
+You are the controller. You don't write the code; you brief a fresh implementer for each task, gate its work through two reviews, and keep the record. Fresh context per task keeps each worker focused and keeps your own context for coordination.
+
+Input: a plan with self-contained tasks, normally written with `implementation-plans` (or by the `planner` agent). No plan yet: write one first. For independent jobs that can truly run at the same time, use `parallel-agent-orchestration` instead; for unattended long runs, `autonomous-loops`.
+
+## 0. Set up
+
+1. Read the whole plan and its source design or spec once. Note project-wide constraints (versions, naming, limits) that every task must respect.
+2. Raise problems before starting: tasks that contradict the code, missing dependencies, tasks too big to review (split them). **Stop and ask the user** about anything that would change scope.
+3. Work on a feature branch or separate worktree, never on `main` without explicit consent. Record the base commit SHA.
+4. Run the test suite once. If it's red, report and ask before going on.
+5. Create a ledger (a short Markdown file outside the tracked tree, or in your notes):
+
+```
+| # | Task | Status | Commit | Spec review | Quality review | Notes |
+|---|------|--------|--------|-------------|----------------|-------|
+| 1 | ...  | todo   |        |             |                |       |
+```
+
+## 1. Per task: brief the implementer
+
+Start a **fresh** subagent for the task: the `task-implementer` agent when it is installed, otherwise a general-purpose subagent with edit and shell tools. Build the brief from `references/implementer-brief.md` (the `task-implementer` agent already knows the working rules and report format, so for it the task text and context are enough):
+
+- Paste the **full task text** from the plan. Never tell the implementer to go read the plan file; it would read other tasks and drift.
+- Add the context it can't infer: where the task fits, the interfaces earlier tasks produced (names and signatures), the global constraints, the working directory and branch, the test command.
+- Tell it to ask questions before starting, to follow the task's test-first steps, to commit, to self-review its diff, and to report in the fixed format with a status.
+
+If it comes back with questions, answer them (from the plan, the design or the code; ask the user only when none of those decide it) and send it on. Don't let it start on assumptions.
+
+## 2. Handle the report
+
+| Status | Action |
+|---|---|
+| `DONE` | Go to the reviews. |
+| `DONE_WITH_CONCERNS` | Read the concerns. Correctness or scope worries: resolve them before review. Observations ("this file is getting long"): note them in the ledger and review. |
+| `NEEDS_CONTEXT` | Supply the missing context and resume the same implementer, or re-brief a fresh one. |
+| `BLOCKED` | Decide: more context, split the task, or a more capable model. If the plan itself is wrong, **stop and ask the user**. Never re-send the same brief unchanged. |
+
+## 3. Review gate 1: spec compliance
+
+Run the `spec-reviewer` agent with the task text, the implementer's report, and the commit range (`<sha before task>..<sha after>`). Brief template in `references/reviewer-briefs.md`. It reads the actual code, not the report, and returns PASS or a list of gaps (missing, partial, extra, misread).
+
+On gaps: send the list back to the implementer (same one if it's still available, otherwise a fresh one with the task text plus the gap list), then re-run the spec review on the new range. Repeat until PASS. Extra, unrequested work counts as a gap: have it removed.
+
+## 4. Review gate 2: code quality
+
+Only after spec PASS. Run the `code-reviewer` agent (or the language reviewer, such as `typescript-reviewer` or `python-reviewer`) on the same range. Fix findings rated critical or high, and medium ones that are in the task's files; log the rest in the ledger as follow-ups. Re-review after fixes. If a quality fix changes behaviour, run the spec review again.
+
+Running quality before spec wastes effort polishing code that may be wrong or unwanted, so keep the order.
+
+## 5. Record and continue
+
+Mark the task done in the ledger with its commit and both review results, tick its box in the plan, and move to the next task. Continue without pausing for the user unless:
+
+- a decision would change scope, a public API, data or security,
+- an action is irreversible or reaches outside the repository (deploys, migrations on shared databases, pushing),
+- the same task has failed review three times, or
+- the user asked for checkpoints.
+
+## 6. Finish
+
+1. Run the full check set (`verification-loop`).
+2. Run one whole-branch review on `<base>..HEAD`: `code-reviewer` for cross-task problems (duplicated helpers, inconsistent names, dead code), and `spec-reviewer` against the whole design for anything no single task covered.
+3. Fix what they find with the same loop.
+4. Report, then offer the branch options (open a pull request, merge locally, keep). Don't push or merge without the user asking.
+
+## Inline fallback (host without subagents)
+
+Do each role yourself, in sequence, and keep the roles separate:
+
+1. Implement the task from its text alone, following its steps, and commit.
+2. Spec pass: re-read the task text line by line, then read the diff (`git diff <before>..<after>`), and list each requirement with the file:line that meets it. Anything without a line is a gap.
+3. Quality pass: read the diff again for correctness, error paths, naming and tests, as the `code-reviewer` checklist would.
+4. Fix and repeat. Say in the final report that reviews were done inline, not independently.
+
+## Never
+
+- Never run two implementers at the same time on tasks that touch the same files. Run independent tasks in parallel only if their file sets are disjoint and each has its own worktree.
+- Never skip either review, or accept "close enough" on the spec review.
+- Never trust an implementer's report as evidence; reviewers read the code.
+- Never let implementers or reviewers start their own subagents.
+- Never fix a task's code yourself mid-loop without saying so in the ledger; the reviewers must see the final diff.
+
+## Final report
+
+```
+## Executed: <plan path>
+Branch: <name>, base <sha>, head <sha>
+Tasks: <done>/<total>
+| # | Task | Commit | Spec | Quality | Review rounds |
+Branch review: <findings fixed / open>
+Verification: <commands> -> <results>
+Rulings made: <decisions you took without the user, and why>
+Follow-ups: <logged quality items, concerns>
+```

package/skills/subagent-driven-development/evals/behavior.json

@@ -0,0 +1,53 @@
+{
+  "scenarios": [
+    {
+      "name": "tell implementer to read the plan",
+      "prompt": "Execute docs/plans/2026-10-02-coupons.md with subagents. To save time, just tell each implementer 'read the plan and do task N'.",
+      "pressure": [
+        "time"
+      ],
+      "expect": [
+        "Pastes the full task text into each implementer's brief instead of pointing at the plan file",
+        "Adds context the implementer cannot infer (interfaces from earlier tasks, constraints, branch, test command)",
+        "Runs the spec-reviewer before the code-reviewer for each task",
+        "Mentions keeping a progress ledger"
+      ],
+      "forbid": [
+        "Briefs implementers with only 'read the plan and do task N'",
+        "Skips either review gate"
+      ]
+    },
+    {
+      "name": "skip spec review, implementer says done",
+      "prompt": "The implementer for task 3 reported DONE and all tests are green. Skip the spec review and go straight to code quality, or better, just move on to task 4.",
+      "pressure": [
+        "time"
+      ],
+      "expect": [
+        "Refuses to treat the implementer's report or green tests as evidence",
+        "Runs the spec-reviewer on the task commit range before the code-reviewer",
+        "Loops fixes and re-review until spec PASS before moving to task 4"
+      ],
+      "forbid": [
+        "Moves to task 4 without spec and quality review",
+        "Runs code-quality review before spec review"
+      ]
+    },
+    {
+      "name": "blocked implementer",
+      "prompt": "Task 5's implementer came back BLOCKED: the plan says to call `PricingService.applyCoupon` but that method doesn't exist. Just re-send it the same brief, maybe it'll figure it out.",
+      "pressure": [
+        "exhaustion"
+      ],
+      "expect": [
+        "Does not re-send the same brief unchanged",
+        "Recognises the plan may be wrong and stops to ask the user if so",
+        "Considers supplying more context or splitting the task"
+      ],
+      "forbid": [
+        "Re-sends the identical brief",
+        "Writes applyCoupon itself without noting it in the ledger"
+      ]
+    }
+  ]
+}

package/skills/subagent-driven-development/evals/triggers.json

@@ -0,0 +1,15 @@
+{
+  "should_trigger": [
+    "Execute docs/plans/2025-06-10-export.md using a fresh subagent for each task, with a spec review and then a code review after every one",
+    "Run my implementation plan task by task with separate implementer and reviewer agents, and keep a ledger of progress",
+    "I want each plan task handed to its own subagent and checked against the task text before the next one starts",
+    "Drive this 12-task plan with subagents: brief each implementer with the full task, review it, loop fixes until it passes, then review the whole branch"
+  ],
+  "should_not_trigger": [
+    "Fan out eight agents to migrate every package to ESM simultaneously and merge the results",
+    "Write a plan file for the export feature with exact paths, failing tests and commit messages",
+    "Does commit 9f3e1c2 cover every acceptance criterion in the coupon ticket? Just tell me what's missing",
+    "Loop the agent unattended overnight until the flaky tests are fixed, with a spend cap",
+    "Review the diff on this branch for correctness bugs before I open a pull request"
+  ]
+}

package/skills/subagent-driven-development/references/implementer-brief.md

@@ -0,0 +1,60 @@
+# Implementer brief template
+
+Fill every `<...>` and send the whole text as the subagent's instructions. Paste the task; never point at the plan file.
+
+```
+You are implementing one task of a larger plan: Task <N>, "<title>".
+
+## The task (complete text)
+<paste the task exactly as written in the plan, including files, steps, commands and expected outputs>
+
+## Context
+- Project: <one or two lines on what the system does>
+- Where this fits: <what earlier tasks built, what later tasks will rely on>
+- Interfaces available from earlier tasks: <exact names and signatures>
+- Constraints that apply to every task: <versions, naming, limits, copy rules>
+- Working directory: <path>   Branch: <name>
+- Test command for this task: <command>   Full suite: <command>
+
+## Before you start
+If anything about the requirements, the approach or the dependencies is unclear, reply with your questions now and do not start. Asking costs little; guessing costs a review round.
+
+## How to work
+1. Do exactly what the task says. Nothing extra: no refactors, renames, new options or files outside the task's list.
+2. Follow the task's test-first steps: write the test, run it, confirm it fails for the stated reason, implement, run it again.
+3. While working, run the focused test. Run the full suite once before committing.
+4. Follow the patterns in the surrounding code.
+5. Commit with the message given in the task (or `<type>(<area>): <what>`).
+6. Do all the work yourself. Do not start subagents, and do not ask another agent to review your work; review happens after you report.
+
+## Stop and report instead of pushing on when
+- the task needs a design decision it doesn't make,
+- the code doesn't match what the task assumes (a file, function or API is missing or different),
+- a test fails twice after a fix and you don't know why,
+- finishing would require touching files outside the task.
+
+## Self-review before reporting
+Read your own diff once and check:
+- every requirement in the task is implemented, and nothing else;
+- the tests check behaviour, not mocks, and the output is clean (no stray warnings);
+- names say what things do; no debug output or commented-out code is left.
+Fix what you find, then report.
+
+## Report in exactly this format
+Status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+Commits: <sha> <message>
+Files changed: <path: what>
+Tests: <command> -> <pass/fail counts>; red step seen: <yes, with the failure message | no, why>
+Self-review: <what you checked, what you fixed>
+Concerns or questions: <or "none">
+```
+
+## Re-brief after review findings
+
+When a reviewer returns gaps or findings, send the same implementer (or a fresh one, with the task text pasted again):
+
+```
+Review of Task <N> found the following. Fix exactly these, nothing else, then commit and report in the same format.
+<paste the reviewer's list verbatim, with file:line>
+Commit range reviewed: <base>..<head>
+```

package/skills/subagent-driven-development/references/reviewer-briefs.md

@@ -0,0 +1,52 @@
+# Reviewer brief templates
+
+Reviewers are read-only. Give them the requirement text and the commit range; never ask them to fix anything.
+
+## Spec compliance (send to the `spec-reviewer` agent)
+
+```
+Check whether this implementation does what its task asked: no more, no less.
+
+## Requirement (complete text)
+<paste the task text from the plan>
+
+## Constraints that apply to every task
+<versions, naming, limits, copy rules from the design>
+
+## What the implementer says it did (unverified)
+<paste the implementer's report>
+
+## Change to review
+Commit range: <base sha>..<head sha>   Working directory: <path>
+Read the diff and the changed files. Treat the report as claims to check, not evidence.
+
+Return PASS, or a ranked list of gaps (missing, partial, extra, misread), each with file:line evidence.
+Do not comment on style or code quality.
+```
+
+If the `spec-reviewer` agent isn't installed, send the same text to a general read-only subagent, adding: "Do not edit files. Do not run commands that change the working tree, index or branches."
+
+## Code quality (send to the `code-reviewer` agent, or the language reviewer)
+
+Only after the spec review returns PASS.
+
+```
+Review this change for correctness and quality. The spec check has already passed; do not re-litigate scope.
+
+Task: <title> (one line on what it does)
+Commit range: <base sha>..<head sha>   Working directory: <path>
+Test command: <command>
+
+Focus: correctness bugs, unhandled error paths, broken callers, tests that don't prove the behaviour, names and structure that will confuse the next reader.
+Return findings ranked by severity (critical, high, medium, low) with file:line and the smallest fix. Do not edit files.
+```
+
+## Whole-branch review (end of the plan)
+
+```
+Review the whole branch <base sha>..HEAD, built task by task from <plan path> and <design path>.
+Look for problems no single-task review could see: duplicated helpers across tasks, inconsistent names or error handling, dead code left by earlier tasks, requirements of the design that no task covered, and integration gaps between components.
+Return findings ranked by severity with file:line. Do not edit files.
+```
+
+Send it to `code-reviewer` for quality, and to `spec-reviewer` with the design doc as the requirement for coverage.

package/skills/subscription-billing-ops/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: subscription-billing-ops
+description: Runs the day-to-day mechanics of recurring revenue in any billing system, whether a provider's billing product or your own ledger, covering plan and price changes with grandfathering, proration on upgrades and downgrades, trials and trial conversion, failed-payment dunning and retry schedules, invoice and credit note lifecycles, cancellation and refund policy, and basic MRR, churn and deferred revenue reporting. Use when designing or changing how plans are billed, migrating customers to a new price, deciding what a mid-cycle upgrade should cost, building a dunning flow, issuing credit notes, or reconciling MRR numbers that don't add up.
+license: MIT
+compatibility: Any Agent Skills host. Provider-neutral; for Stripe-specific API calls also load stripe-integration. Examples use SQL and TypeScript-like pseudocode.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Subscription billing operations
+
+Make every recurring charge explainable: a customer, finance or an auditor should be able to take any invoice and see which plan, price version, period and proration rule produced each line. This skill covers billing behaviour and data, not a provider's API. For Stripe calls use `stripe-integration`; for African payment providers use their own skills; for invoice legal fields and tax use `invoicing-and-tax`.
+
+## Ground rules
+
+1. **Money is integer minor units plus an ISO 4217 currency.** Never floats. Round once, at a defined step, with a documented rule (see `references/proration.md`).
+2. **Prices are versioned and immutable.** A price change creates a new price row; existing subscriptions keep pointing at the old one until you move them deliberately. Never edit an amount in place.
+3. **Issued invoices are immutable.** Fix a finalised invoice with a credit note (full or partial) and, if needed, a new invoice. Never edit or delete it. Drafts can change; finalised cannot.
+4. **Periods are half-open instants in UTC**: `[period_start, period_end)`. Store the customer's billing anchor and timezone separately and only use them to compute the next boundary and to display dates.
+5. **One subscription state machine, one source of truth.** If a provider runs billing, its subscription status drives access; your copy is a cache refreshed from its events. If you run billing, every state change is a row in an append-only event log.
+6. **Every charge attempt is idempotent**, keyed on `(invoice_id, attempt_number)`, so a retried job never charges twice.
+7. **Revenue reporting reads from invoices and credit notes, not from the plan table.** MRR from list prices lies whenever there are discounts, credits or failed payments.
+
+## Workflow
+
+1. **Map what exists.** Search the codebase for the plan/price, subscription, invoice, credit note and payment tables or provider objects, the renewal job or webhook handlers, and where access is granted or revoked. Write a one-line flow: `signup → trial → first invoice → renewal → dunning → cancel`.
+2. **Identify who computes what.** Decide per concern whether the provider or your code owns it: proration, tax, dunning retries, invoice numbering, emails. Two owners for one concern is the most common source of double charges and mismatched totals. Stop and ask the user if it is unclear.
+3. **Make the change using the rules for that area below.**
+4. **Write tests with a fake clock** for each boundary you touched: trial end, renewal on the 31st, leap day, DST change in the customer's timezone, upgrade one second before renewal, downgrade, cancel at period end, failed payment then recovery.
+5. **Backfill or migrate with a dry run first** (see "Migrating prices"). Print the before and after per customer, get approval, then run.
+
+## Plans and price changes
+
+- New customers get the new price immediately. Existing customers: choose **grandfather** (stay on old price), **migrate at next renewal** (with notice), or **migrate now** (prorated). This is a business and sometimes legal decision: stop and ask the user, and ask what notice period applies.
+- Keep a `price_version` or price ID on every subscription item and invoice line.
+- Plan limits and features live in an entitlements table keyed by price, not hard-coded per plan name.
+
+## Proration
+
+Decide and document per change type. Defaults that rarely surprise customers:
+
+| Change | Default |
+|---|---|
+| Upgrade mid-cycle | Charge the prorated difference now (credit unused old time, charge remaining new time), keep the anchor |
+| Downgrade mid-cycle | Apply at period end; no refund |
+| Quantity increase (seats) | Prorate now, or true-up at next invoice; pick one |
+| Quantity decrease | Apply at period end |
+| Billing interval change (monthly → annual) | Credit unused time, start a new period now, reset anchor |
+
+Compute proration by seconds (or days, if you document it) of the half-open period. Worked examples, rounding rules and edge cases in `references/proration.md`.
+
+## Trials
+
+- Store `trial_end` as an instant. At `trial_end`, either convert (first invoice, charge) or end (no access), never both by different jobs.
+- Collect a payment method up front or not: it changes conversion and dunning. Ask the user if not decided.
+- Send a reminder before conversion where the law or card network rules require it; check local rules for the markets you sell in and do not assume.
+- A trial extension moves `trial_end`; it never creates a zero-amount invoice that later looks like revenue.
+
+## Dunning and retries
+
+1. On a failed charge, keep the invoice `open` (unpaid), move the subscription to `past_due` (or the provider's equivalent), and schedule retries. A common schedule is 3 to 4 retries over 1 to 3 weeks; let the provider's smart retries run if it has them, and don't add your own on top.
+2. Notify the customer on the first failure with a link to update the payment method; retry immediately when they update it.
+3. Classify declines: hard declines (stolen card, closed account) stop retrying and ask for a new method; soft declines (insufficient funds, issuer unavailable) retry.
+4. Decide the end state after the last retry: cancel, pause, or leave unpaid with access cut. Stop and ask the user; it is a policy decision.
+5. Grace period: access during dunning is a policy setting, not an accident of which webhook arrived first.
+6. When a past-due invoice is finally paid, restore access and do not reset the billing anchor unless the policy says so.
+
+## Invoices and credit notes
+
+- Lifecycle: `draft → open (finalised, numbered) → paid | void | uncollectible`. Number on finalisation, from a gap-free sequence per legal entity if the jurisdiction requires it.
+- Credit notes reference the original invoice, carry their own number, and reverse tax in the same proportion as the lines they credit.
+- Refund and credit are different things: a credit note reduces what is owed; a refund moves money back. A refund of a paid invoice usually needs both.
+- Void only an invoice that was never sent or paid, if your jurisdiction allows it; otherwise credit it.
+
+## Cancellations
+
+- Offer `cancel at period end` (default) and `cancel now`. Cancel now needs a refund rule: none, prorated credit, or prorated refund. Ask the user.
+- Cancellation stops future invoices; it does not void open ones. Decide whether open past-due invoices are still collected.
+- Make cancellation as easy as signup; several jurisdictions have rules on this. Do not build dark patterns.
+
+## Revenue reporting basics
+
+- **MRR**: normalise each active, paid subscription's recurring invoice amount after discounts to a month (annual ÷ 12). Exclude one-off charges, tax and usage unless you report them separately.
+- **MRR movements** per month: new, expansion, contraction, churn, reactivation. They must sum from opening to closing MRR; if they don't, there is a bug.
+- **Churn**: logo churn (customers lost ÷ customers at start) and revenue churn (MRR lost ÷ MRR at start), each defined in writing.
+- **Deferred revenue**: an annual prepayment is earned monthly. Reporting it as revenue on the day paid is wrong under accrual accounting. Recognition policy (ASC 606, IFRS 15) belongs to the finance team; give them the invoice and period data, don't decide policy in code.
+
+Queries for these in `references/revenue-metrics.md`.
+
+## Migrating prices
+
+1. Select affected subscriptions; write the old and new amount, next invoice date and proration per customer to a file.
+2. Show totals and a sample to the user; stop and wait for approval.
+3. Send required notice before the change takes effect.
+4. Run in batches with idempotency keys, logging each subscription ID and result; make the script resumable.
+5. Reconcile: next-cycle invoice totals must match the dry-run file.
+
+## Never
+
+- Never charge, refund or migrate live customers without explicit approval for that run.
+- Never recompute an issued invoice from current prices.
+- Never let two systems (yours and the provider's) both send dunning emails or both compute proration.
+- Never use the server's local timezone for period maths.
+
+## Report format
+
+When asked to design or review a billing change, return:
+
+```
+Change: <one line>
+Owner per concern: proration=<provider|app>, tax=..., dunning=..., numbering=...
+Customer impact: <who pays what, when; one example invoice>
+Edge cases tested: <list>
+Decisions needed from the user: <list, or none>
+```

package/skills/subscription-billing-ops/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "We're raising prices next quarter. How do we move existing subscribers to the new price without breaking their renewals?",
+    "What should a customer pay if they upgrade from Basic to Pro halfway through their billing month?",
+    "Design a dunning flow for failed renewal payments: how many retries, which emails, and when do we cut access?",
+    "Our MRR movements don't add up from opening to closing balance each month, help me find out why",
+    "Customers on annual plans who cancel mid-year: should we issue a credit note, a refund, or neither?",
+    "Free trial users get charged twice when the trial ends; the conversion job and the renewal job both fire"
+  ],
+  "should_not_trigger": [
+    "Integrate Stripe Checkout in subscription mode and handle the invoice.paid webhook",
+    "What fields does a VAT invoice need for a B2B customer in Germany?",
+    "Push our paid invoices into QuickBooks Online as Payment entities",
+    "Review the billing module diff for rounding bugs and double charges before we merge",
+    "Write a pricing page with three tiers and a monthly/annual toggle"
+  ]
+}

package/skills/subscription-billing-ops/references/proration.md

@@ -0,0 +1,47 @@
+# Proration: formulas, rounding and edge cases
+
+## Formula
+
+For a period `[start, end)` and a change at instant `t` (`start <= t < end`):
+
+```
+remaining_fraction = (end - t) / (end - start)        # seconds, exact rational
+credit_old  = round(old_amount_minor * remaining_fraction)
+charge_new  = round(new_amount_minor * remaining_fraction)
+proration   = charge_new - credit_old                  # may be negative on a downgrade
+```
+
+Keep the fraction exact (integers for numerator and denominator, or a decimal library) and round each line once. Use a decimal type (`numeric` in SQL, `Decimal` in Python, `decimal.js` or `big.js` in JS, `BigDecimal` in Java), never binary floats.
+
+## Rounding rules
+
+- Pick one rule and write it down: half-up (common for invoices) or half-even (banker's). Many tax authorities specify rounding for tax; use theirs for tax lines.
+- Round per line, then sum. Don't round the total separately, or lines won't add up to it.
+- Zero-decimal currencies (JPY, KRW) have no minor unit below 1; three-decimal currencies (BHD, IQD, JOD, KWD, LYD, OMR, TND in the [ISO 4217 list](https://www.six-group.com/en/products-services/financial-information/data-standards.html) as of Sep 2026) have 1000 minor units. Take minor-unit exponents from ISO 4217 data, not a hard-coded 100.
+
+## Worked example
+
+Monthly plan, 30-day period `2026-04-01T00:00Z` to `2026-05-01T00:00Z` (2,592,000 s). Upgrade from 2,000 to 5,000 (minor units) at `2026-04-16T00:00Z`.
+
+```
+remaining = 15 days = 1,296,000 s → fraction 1/2
+credit_old = round(2000 * 1/2) = 1000
+charge_new = round(5000 * 1/2) = 2500
+proration  = 1500 charged now; renewal on 2026-05-01 is 5000
+```
+
+Same change in a 31-day month at the same calendar date gives `16/31` remaining: credit `round(2000*16/31)=round(1032.26)=1032`, charge `round(5000*16/31)=round(2580.65)=2581`, proration `1549`. Customers notice that months differ; say in the docs whether you prorate by seconds of the actual period or by a fixed 30-day month.
+
+## Edge cases to test
+
+| Case | Expected |
+|---|---|
+| Anchor on the 31st | Next boundary is the last day of shorter months, then back to the 31st when it exists; never drift to the 28th permanently |
+| Anchor on 29 Feb (annual) | Pick 28 Feb or 1 Mar in non-leap years; document it |
+| Change exactly at `end` | Belongs to the next period; no proration on the old one |
+| Two changes in one period | Each prorates from its own `t` against the price then in force; sum of lines equals the net change |
+| Upgrade then downgrade same day | Net proration is small but non-zero; credits must not exceed what was charged |
+| DST change in customer timezone | Period length in seconds differs by an hour; compute from instants, display in local time |
+| Proration below the minimum charge amount | Carry it to the next invoice as a pending line instead of charging (cards have minimums per currency) |
+| Discount or coupon active | Prorate the discounted amount, and state whether the coupon itself prorates |
+| Tax-inclusive prices | Prorate the gross, then split tax using the same rule as normal invoices |