penny

# penny

> Payments and billing wired correctly, for products and their agents: an agent-native, self-improving payments employee that coding agents call through a CLI, an MCP server and skills.

penny is a senior payments engineer as a tool. It wires correct Stripe test-mode billing into a product, reviews an integration against 21 known pitfalls, debugs a live incident against the ledger-is-truth law, and issues scoped, capped, expiring agent-spend credentials. Boundary: product billing only; earning loops stay with helios.

THE LAW (JTBD-0): the ledger is the truth, not the status code. Never infer money-state from a transport status; reconcile, or say "unknown, reconciling." Pinned Stripe API version: `2026-05-27.dahlia`. Test mode is the default and the acceptance bar.

Run it from GitHub with no clone: `npx -y -p github:naman10parikh/penny penny --help` for the CLI and `npx -y -p github:naman10parikh/penny penny-mcp` for the MCP server (stdio). Paths below are relative to the repository root.

## Start here

- [AGENTS.md](./AGENTS.md): what penny does, how to invoke every CLI and MCP tool, the boundary, the NOT-list and the `stripe` self-test rig.
- [CLAUDE.md](./CLAUDE.md): the Claude Code operating doc for this repository (the voice, THE LAW, the cluster order); it imports AGENTS.md.
- [README.md](./README.md): what it is, the quick start, and how to install it in any coding agent.

## Identity

- [identity/SOUL.md](./identity/SOUL.md): who penny is ("counts every cent, trusts no status code"): identity, personality, boundaries.
- [identity/BRAND.md](./identity/BRAND.md): the name (penny, the smallest unit of money, counted exactly), the tagline and design tokens.
- [.well-known/agent.json](./.well-known/agent.json): the A2A agent card (name, description, endpoint, capabilities).

## CLI (`penny`; exit 0 or non-zero)

- [wire](./src/wire/command.ts): `penny wire --product <spec> [--target <dir>] [--dry-run]` is the acceptance test: Stripe test-mode billing with checkout E2E, a raw-body HMAC webhook and idempotent replay.
- [review](./src/review/command.ts): `penny review <path>` audits a billing integration against the 21 known pitfalls (pitfall id, file:line, severity, fix, brain ref); non-zero exit when findings exist.
- [debug](./src/cli/debug.ts): `penny debug <symptom>` root-causes a live billing incident via JTBD-0 (for example "every webhook 400s" leads to P-04/S-03).
- [issue-spt](./src/cli/issue-spt.ts): `penny issue-spt --seller <id> --cap <amt> --expires <ts>` issues a scoped, capped, expiring Shared Payment Token in test mode.
- [reconcile](./src/cli/reconcile.ts): `penny reconcile --since <ts> [--no-network]` diffs the internal ledger against Stripe; with no network it says "unknown, reconciling."
- [webhook](./src/cli/webhook.ts): `penny webhook listen` wraps `stripe listen --forward-to` with a raw-body HMAC self-test.
- [meter](./src/cli/meter.ts): `penny meter create <name> --agg <sum|count|last> --unit <u>` creates a near-immutable Meter and refuses a re-create or a bad aggregation.
- [check-version](./src/cli/check-version.ts): `penny check-version [--api-version <v>]` contract-tests the pinned API-version shape your code reads (no live API).
- [explain](./src/cli/explain.ts): `penny explain <topic>` asks the brain (BM25 over `brain/`) for a cited answer.
- [runs-view](./src/obs/runs-view.ts): `penny runs-view [--json]` summarises the run log and the money-action audit trail.

## The `stripe` CLI, penny's webhook self-test rig (test mode)

- [scripts/install-stripe-cli.sh](./scripts/install-stripe-cli.sh): installs the `stripe` CLI.
- `stripe listen --forward-to localhost:<port>/webhook` forwards test-mode events and prints the signing secret (`penny webhook listen` wraps it); `stripe trigger checkout.session.completed` fires a known event; `stripe fixtures <file>` drives a scripted scenario.
- [test/acceptance/](./test/acceptance): the acceptance test, which leans on this rig.

## MCP server (`penny-mcp`, 8 tools; a taste layer, not a raw `@stripe/mcp` passthrough)

- [src/mcp/server.ts](./src/mcp/server.ts): the stdio server. Tools: `penny_wire`, `penny_review_integration`, `penny_debug`, `penny_issue_spt`, `penny_reconcile`, `penny_meter_create`, `penny_check_version`, `penny_explain`. Hosted OAuth is documented as deferred.
- [.mcp.json](./.mcp.json): the config any MCP client can copy; it starts the server from GitHub. The dev servers (`@stripe/mcp` and others) are in `.mcp.dev.json`.

## Skills (each step cites a brain ref)

- [stripe-webhook-correctness](./skills/stripe-webhook-correctness/SKILL.md): raw-body HMAC, same-transaction idempotency, ack fast and process durably, re-fetch on ordering-sensitive logic.
- [subscription-proration](./skills/subscription-proration/SKILL.md): gate proration on payment status, reconcile the old invoice, use Subscription Schedules, pin `billing_mode`.
- [metered-billing](./skills/metered-billing/SKILL.md): Meters are mandatory, real-time flush plus daily reconcile, meter immutability, degrade gracefully on bill shock.
- [agent-spend-credential](./skills/agent-spend-credential/SKILL.md): a seller-locked, capped, expiring token fused with helios's balance cap; card rail first, x402 as the escape hatch.
- [stripe-version-migration](./skills/stripe-version-migration/SKILL.md): pin the version with a shape-contract test, import first and cancel after, treat non-2xx as ambiguous.

## Sub-agents (`.claude/agents/`, flat)

- [billing-reviewer](./.claude/agents/billing-reviewer.md): audits a billing-code tree against the 21 known pitfalls before it ships (shares the `penny review` logic).
- [payment-debugger](./.claude/agents/payment-debugger.md): root-causes a live incident via JTBD-0 (shares the `penny debug` triage map).

## The brain (what penny knows)

- [brain/MOC - penny.md](./brain/MOC%20-%20penny.md): the hub for the brain.
- [brain/EXPERTISE-MAP.md](./brain/EXPERTISE-MAP.md): the map of mastery by job to be done; JTBD-0 is THE LAW.
- [brain/OPINIONS.md](./brain/OPINIONS.md): the taste layer (O-01 to O-16).
- [brain/KNOWN-PITFALLS.md](./brain/KNOWN-PITFALLS.md): version-specific gotchas with detection and fix (P-01 to P-21).
- [brain/BATTLE-TESTED-SCENARIOS.md](./brain/BATTLE-TESTED-SCENARIOS.md): the golden eval tasks (S-01 to S-18).
- [brain/TOOL-MATRIX.md](./brain/TOOL-MATRIX.md): canonical tools, defaults and alternatives, agent access, required secrets.
- [brain/GAPS-AND-DISPUTES.md](./brain/GAPS-AND-DISPUTES.md): where sources disagree, and the open items the nightly loop works on.
- Query it: `penny explain "<query>"` or `bash scripts/memory-search.sh "<query>"`.

## Install surfaces and self-improvement

- [.claude-plugin/plugin.json](./.claude-plugin/plugin.json): the Claude Code plugin (skills, sub-agents, MCP server); install with `/plugin marketplace add naman10parikh/penny`.
- [.claude-plugin/marketplace.json](./.claude-plugin/marketplace.json): the one-plugin marketplace.
- [hooks/hooks.json](./hooks/hooks.json): the plugin's two hooks (the dead-API and raw-body guard, and the session-start law).
- [.claude/settings.json](./.claude/settings.json): the same two hooks for work inside this repository.
- [gemini-extension.json](./gemini-extension.json): the Gemini CLI extension.
- [workflows/rsi.workflow.js](./workflows/rsi.workflow.js): the deterministic, tokenless nightly loop (`node workflows/rsi.workflow.js --deterministic`).
- [dsip.json](./dsip.json): the self-improvement contract (eval-gated, no self-grading, git snapback).

## Optional

- [SECURITY.md](./SECURITY.md): how to report a vulnerability.
- [CONTRIBUTING.md](./CONTRIBUTING.md): how to contribute.
- [LICENSE](./LICENSE): MIT.