The developer platform

format-as-contract · repo-as-backend · no server

THE FORMAT

Everything PlusPlus knows — exercises, workouts, finished sessions — serializes to versioned, deterministic JSON (schema v1). Deterministic means byte-stable: the same data always encodes to the same bytes, so diffs are clean and merges are sane. The format is the contract shared by the app's export/import, the sync engine, the CLI, and anything you build.

Conformance fixtures live in the repo as the language-neutral spec — a port that round-trips the fixtures is a correct implementation.

THE REPO IS THE BACKEND

Your training data belongs in a git repo you own:

• program/ — your workout templates, one JSON file each. Edit them in a PR if you like; the app pulls changes.
• history/2026/… — finished sessions, append-only. Every workout is a commit ("Log: Push Day — 18 sets, 42 min").

Sync is a three-way merge with conflicts surfaced honestly (keep mine / take theirs / postpone). Sessions never merge — they only append. There is no PlusPlus server; GitHub is the transport and git is the audit log.

THE CLI

plusplus is a Swift CLI that operates on a clone of your workouts repo — it never authenticates; git is the transport:

• plusplus init — scaffold a workouts repo with the standard layout
• plusplus lint — validate every file against the schema
• plusplus stats [--json] — sessions, streaks, volume; machine-readable with --json
• plusplus import / export — move bundles in and out

THE MCP SERVER

plusplus mcp exposes your workouts repo to agents over stdio JSON-RPC. Read tools return interchange documents and the --json reports verbatim. The one mutating tool, propose_program_change, is heavily fenced: program/** paths only, clean work tree required, must lint or it rolls back fully, commits to a fresh branch, and never pushes — review is yours.

RECIPES

Copy-paste GitHub Actions for your workouts repo: lint on every PR, a weekly training report opened as an issue. Your program gets CI like the rest of your code.

WHERE THINGS ARE

• github.com/plusplusinc/plusplus — the app (AGPL-3.0), the Kit, the CLI, and the format (MIT)
• docs/PLATFORM.md in the repo — the full architecture
• docs/AGENTS.md — agent quickstart (files, --json, MCP)