# Journey Preflight

Use before a Butterbase app-building journey stage when project preflight is missing...

- Repository: https://github.com/butterbase-ai/butterbase-skills (535 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add butterbase-ai/butterbase-skills --skill journey-preflight -g -a claude-code -y`
Codex: `npx skills add butterbase-ai/butterbase-skills --skill journey-preflight -g -a codex -y`
Cursor: `npx skills add butterbase-ai/butterbase-skills --skill journey-preflight -g -a cursor -y`
Gemini CLI: `npx skills add butterbase-ai/butterbase-skills --skill journey-preflight -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add butterbase-ai/butterbase-skills`

## Description

Use before a Butterbase app-building journey stage when project preflight is missing, older than 24 hours, or missing app credentials, or when journey-preflight is invoked directly.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Butterbase Preflight

Gate that ensures the user can actually talk to the Butterbase platform before any stage tries to. Writes results to `docs/butterbase/03-preflight.md` and stamps `app_id` + `api_base` into `00-state.md`.

## When to use

- Automatically as the first step of any `journey-*` build stage when `03-preflight.md` is missing, older than 24 hours, or `00-state.md`'s `app_id` is null.
- Directly via `/butterbase-skills:journey-preflight` when the user wants to re-verify.

## Procedure

For each check, write a one-line result to `03-preflight.md` (`<check> ✓/✗ <note>`). Ask the user to fix any ✗ before continuing, do not auto-skip failures.

1. **Butterbase account.** Call `mcp__butterbase__list_regions` (cheapest call). Success → ✓. Auth error → ✗ with `"Sign up at https://butterbase.ai, then run npx @butterbase/cli mcp install and complete the OAuth flow in your client (e.g. /mcp in Claude Code)."`. If MCP tool is not visible at all, jump to step 2.

2. **MCP server connected.** Check whether `mcp__butterbase__*` tools are listed in the agent's available tools. Absent → ✗ with `"Install the Butterbase MCP server: npx @butterbase/cli mcp install. See https://butterbase.ai/docs/mcp."`. Present → ✓.

3. **MCP OAuth complete.** Auth for `mcp__butterbase__*` calls is OAuth, not an env var, step 1 already proved it works if `list_regions` succeeded. If step 1 failed with auth error, retry after the user runs `/mcp` (or `claude mcp login butterbase`) and completes browser consent. `BUTTERBASE_API_KEY` (`bb_sk_…`) is still relevant for **runtime app code** (functions, server-side `@butterbase/sdk`), check separately at deploy time, not here.

The rest: https://github.com/butterbase-ai/butterbase-skills/blob/HEAD/skills/journey-preflight/SKILL.md