mikehasa/golive-skill / skills/golive
golive
FlaggedTake an agent-written app from repo to live production on the user's OWN accounts, with providers they choose (hosting, database, auth, payments, email, domain/DNS). The human connects accounts and approves changes; supported wiring operations run through a local CLI and produce verification evidence with explicit limits. Use when the user wants to ship, deploy, go live, launch, publish, or put their app online, or asks to wire up env vars, webhooks, auth settings (signup, email confirmation, password policy), a real signup → confirmation email → login journey, password recovery, account isolation between two users, auth redirects, email DNS or a custom domain.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 50.0 KB |
| THIRD_PARTY_NOTICES.md | markdown | 817 B |
| references/cloudflare-dns.md | markdown | 7.9 KB |
| references/godaddy.md | markdown | 3.9 KB |
| references/guided.md | markdown | 9.2 KB |
| references/neon.md | markdown | 4.4 KB |
| references/netlify.md | markdown | 6.9 KB |
| references/plan-and-verify.md | markdown | 47.4 KB |
| references/porkbun.md | markdown | 3.4 KB |
| references/posthog.md | markdown | 10.2 KB |
| references/resend.md | markdown | 8.6 KB |
| references/sentry.md | markdown | 10.7 KB |
| references/stripe.md | markdown | 13.1 KB |
| references/supabase.md | markdown | 49.7 KB |
| references/troubleshooting.md | markdown | 5.2 KB |
| references/updates.md | markdown | 5.0 KB |
| references/uptimerobot.md | markdown | 12.3 KB |
| references/vercel.md | markdown | 13.2 KB |
| release.json | config | 2.4 KB |
| scripts/golive.mjs | script | 1.2 MB |
| scripts/install-cli.mjs | script | 5.0 KB |
| scripts/install-lib.mjs | script | 24.4 KB |
references/posthog.md
View on GitHub# PostHog (monitoring): agent notes
Load this when the plan uses `monitoring=posthog`.
Status: the adapter, the link and the `posthog-ingest` check are **implemented and live-validated in
part**. A 2026-09-30 run on a disposable fixture and the owner's free PostHog US-Cloud account
accepted the personal API key and its single organization, adopted the account's existing project
through `projects.monitoring` (a zero-write pin recorded in state, no creation marker), passed
`posthog-ingest` twice — one synthetic `golive_ingest_check` event each, read back through PostHog's
own HogQL count after 22 s and 23 s — saw the free plan refuse a create live (HTTP 403
`permission_denied`, "maximum limit of allowed projects for your current plan", mapped to
reuse/delete/upgrade with nothing created), and left the adopted project to an explicit teardown
handoff. A project read on that account returned `api_token`. Still unverified: the create **and
delete** path of a golive-created project, writing the token to a host env, the EU region and the
app's own event flows. The reference records what the code does and what the official API contract
behind it is (checked 2026-09-29).
## 1. Logging in (least friction first)
1. **Personal API key (only path).** In PostHog: **Settings → Personal API keys → Create personal API
key**, and check its scopes: `organization:read` (list the organization), `project:read` +
`project:write` (list, read, create and delete projects) and `query:read` (read an event count
back). Then hand golive the key privately — on macOS the agent runs
`credentials --prompt POSTHOG_API_KEY --json` for the native hidden-input dialog; their own editor
is the fallback (see [How the human connects accounts](../SKILL.md#how-the-human-connects-accounts)).
Never put the value in chat or argv.
2. **Scope the key to ONE organization.** golive refuses to guess: a key that can see several
organizations fails `doctor` with the list, because picking one would wire the app's analytics into
an account nobody approved.
3. **Region.** `posthog.region: us` (default) or `eu` in `golive.yaml` selects both hosts: the control
plane (`us.posthog.com` / `eu.posthog.com`) and ingestion (`us.i.posthog.com` / `eu.i.posthog.com`).
A key from the EU Cloud is not valid on the US host, and events sent to the wrong ingestion host
never reach the project.
## 2. What golive does vs. what stays with the human
golive automates (after plan approval):
- `analytics:project` — pins the project this repo is already linked to (zero writes), else selects
`projects.monitoring`, else **creates** one named from the repository (`repoName`, from the git
origin remote when there is one) in the key's organization. A created project records
`posthog.createdProjectId`; a pinned or adopted one does not, so teardown can never delete a project
golive did not make.
- `analytics:env:<target>` — reads the project's **public** ingestion token through the API and writes
the names the code actually reads (`POSTHOG_KEY` + `POSTHOG_HOST`, or the framework's client-prefixed
spelling: `NEXT_PUBLIC_POSTHOG_KEY`/`NEXT_PUBLIC_POSTHOG_HOST`, `PUBLIC_POSTHOG_KEY` in SvelteKit,
`VITE_…`, …) into the host's env. Written as one write with the env pipeline's usual rules: names
someone else set are kept, names golive wrote before are rewritten when the project or the token
changes (the recorded source carries the project id and the token's fingerprint), and the whole step
re-reads the token before writing so what was approved is what lands. The `phc_` token is public by
design — it is the key browsers must have — so it is written **non-sensitively** and `bundle-secrets`
does not treat it as a leak.
- `posthog-ingest` (the check) — sends one synthetic event (`golive_ingest_check`, distinct id
`golive-verify`, plus a per-run marker property) and polls PostHog's own HogQL count for that marker
for about three minutes. **Pass only on the read-back**; the capture endpoint's 200 is an acceptance,
not proof. "Not visible yet" is a **warn** (ingestion is asynchronous), a refused read-back (401/403 —
usually a missing `query:read` scope) is a **fail**, an unusable credential is a **skip** naming
`login:posthog` (the `accounts` check owns that verdict), and no linked project is a **skip** naming
`analytics:project`.
- Teardown — a project carrying golive's creation marker is deleted through the API (`golive teardown`
→ `apply --plan <id> --yes --confirm-destroy`), and the provider's own read confirms it: PostHog
**schedules** the deletion, so the confirming answer is `is_pending_deletion` (reported as "pending
deletion (scheduled, not live)") or a 404 — both are confirmations; a project the provider still
reports live fails the step. An adopted project, or one whose provider cannot be reached now, becomes
a handoff naming the PostHog dashboard instead — never a silent gap.
Stays with the human:
- **Initializing the SDK in the app** (and sending the events the product cares about). Until the code
reads the env names golive fills, the plan carries the non-blocking `analytics:snippet` handoff with
that task. No check can see the app's own code, so nothing closes it — it ends when the code reads
those names, and the handoff then stops being planned.
- **The plan and its limits**: a free PostHog account allows **one** project, and PostHog is priced per
ingested event. golive maps a refused create to "reuse the existing project, delete one you no longer
need, or upgrade" and never upgrades, pays or retries a create.
- Dashboards, funnels, alerts, data retention and every product decision inside PostHog.
- Deleting a project by hand when golive did not create it.
## 3. Explain these in plain words
- **Two different keys.** The *personal API key* (`phx_…`, `POSTHOG_API_KEY`) is golive's own
credential and stays server-side; the *project API key / project token* (`phc_…`) is PUBLIC — it is
what the browser SDK sends every event with. Writing `NEXT_PUBLIC_POSTHOG_KEY` is not a leak; writing
a `phx_` key there would be. golive fills the project-token names it knows (`POSTHOG_KEY`,
`POSTHOG_TOKEN`, `POSTHOG_PROJECT_KEY`, `POSTHOG_PROJECT_API_KEY`, `POSTHOG_PROJECT_TOKEN`, and the
framework's client-prefixed forms) but deliberately **never** fills `POSTHOG_API_KEY`: in PostHog that
name means a *personal* key, so an app reading it is left unmapped on purpose (give it a server-only
personal key by hand, or rename the variable to `POSTHOG_KEY` if it only wants the project token).
- **A 200 from the capture endpoint means "accepted", not "ingested".** PostHog queues events, so the
only honest proof is reading the event count back — that is exactly what `posthog-ingest` does.
- **Verify leaves one (or a few) synthetic events in the project.** `golive_ingest_check` events are
golive's own probes; ignore or filter them in dashboards and funnels.
- **Region matters twice**: the API host AND the ingestion host. An EU project receiving events at
`us.i.posthog.com` silently drops them.
- **Deleting a project deletes its data.** PostHog schedules the deletion and keeps the project listed
as pending until it is purged; that is why golive reports the scheduled state instead of waiting.
## 4. Troubleshooting
| Symptom | What to do |
|---|---|
| `doctor`: PostHog key rejected / not authenticated | Create a fresh personal API key with `organization:read`, `project:read`, `project:write`, `query:read`, and store it with `credentials --prompt POSTHOG_API_KEY --json` (§1). |
| `doctor`: "golive needs a key scoped to exactly one PostHog organization" | Scope the personal API key to one organization in PostHog (Personal API keys → scope), or use a key from that organization only, then re-run `doctor`. |
| `403` mentioning scopes | The key is missing one of the four scopes golive uses; the error names them. Re-create the key with all four. |
| Create refused: "free plans allow one project" | Reuse the account's existing project (`projects.monitoring: <id-or-name>`), delete one you no longer need (by hand, or `golive teardown` when golive created it), or upgrade the plan yourself. |
| `analytics:env:*` says the token changed since approval | The project token was rotated in PostHog after the plan was approved. Re-run `golive plan` and apply the new plan. |
| `posthog-ingest` warns "had not recorded the marker yet" | Ingestion can lag minutes. Re-run `golive verify --only posthog-ingest` in a minute. If it never appears: check the project id in the plan/state, the region (`posthog.region`) and that the app initializes the SDK with those env names. |
| `posthog-ingest` fails "the read-back was refused" | The key lacks `query:read` (or was revoked). Re-create it with the scopes above. |
| Events land in the wrong project | The app reads a token that does not match `projects.monitoring`. Re-run `golive plan` (it rewrites the names golive manages) and redeploy. |
| The app reads `POSTHOG_API_KEY` | That name means a *personal* API key in PostHog, so golive never fills it (and `env-parity` names it as unmapped). Give the app a server-only personal key by hand, or rename the variable to `POSTHOG_KEY` if it only needs the public project token, then re-run `plan`. |
| `bundle-secrets` flags a PostHog key | It should not: the `phc_` project token is public by design and is not a scanned pattern. A flagged `phx_` key in a bundle is a real leak — rotate it and keep it server-only. |
| Teardown step fails "still reports the project as live" | The delete did not stick (or the project was recreated). Delete it in the PostHog dashboard, or re-run teardown. |
## Unverified
- The create **and delete** path of a golive-created project: the live run's account was on the free
plan's one-project limit, so the create was refused live and the deletion of a golive-created
project has never been exercised — both stay mock-covered.
- Writing the project token to a host env: no live run has had a host with mapped env names to write.
- EU Cloud behaviour end to end: the host pair is configurable and mock-covered, but no EU account has
run it.
- The ~180 s read-back window: from PostHog's documented ingestion lag — the live runs read their
markers back after 22 s and 23 s, so nothing has approached the window's edge.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |