Journey Preflight

A precondition gate that verifies your Butterbase setup before any platform operation runs. It checks four things: account access via a test API call, MCP server connectivity, API key presence in your environment, and whether an app_id exists for the project. Results get written to a timestamped markdown file that auto-expires after 24 hours, forcing a recheck. The nice part is it won't let you proceed on failures instead of failing halfway through a deploy, and it handles the app provisioning conversation upfront rather than assuming you want to burn API quota. If you're chaining multiple Butterbase operations, this runs once at the start and caches the validated state.

GitHub stars: 532
last updated: Jun 11, 2026

View on GitHub

Install

$ npx -y skills add butterbase-ai/butterbase-skills --skill journey-preflight --agent claude-code

Installs into .claude/skills of the current project.

Files

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.

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.

SKILL.md on GitHub