journey-preflight

Name: journey-preflight
Author: butterbase-ai

533stars40forks

How to install journey-preflight?

butterbase-ai/butterbase-skills/journey-preflight

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

Installs into the current project.

Summary

Use before any Butterbase platform-touching action (or when journey-preflight is invoked directly) to verify the user has a Butterbase account, the MCP server is connected, BUTTERBASE_API_KEY is set, and an app_id exists for this project. Re-run automatically if docs/butterbase/0

Files · 1

View on GitHub

SKILL.md

1	# Butterbase Preflight
2
3	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`.
4
5	## When to use
6
7	- 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.
8	- Directly via `/butterbase-skills:journey-preflight` when the user wants to re-verify.
9
10	## Procedure
11
12	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.
13
14	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.
15
16	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 → ✓.
17
18	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.
19
20	4. App provisioned. Read `00-state.md` front-matter for `app_id`.
21	- Non-null and `mcp__butterbase__manage_app` (action `get_config`) succeeds → ✓.
22	- Null → ask the user: `"No app yet. Create one now? (yes/no — if no, you can paste an existing app_id)"`. On yes, call `mcp__butterbase__init_app` (ask for app name and region — recommend `us-east-1` as default). Capture `app_id` and `api_base` from the response. Update `00-state.md` front-matter.
23	- User-provided app_id → verify with `manage_app get_config`; on success update `00-state.md`.
24
25	5. CLI installed. Run `butterbase --version`. If "command not found":
26	- Read the Toolchain section of `02-plan.md`. If `CLI usage: yes` (default), prompt: "Install `@butterbase/cli` globally now? (yes / skip)". On yes, run `npm install -g @butterbase/cli`. On skip, note in `03-preflight.md` that the CLI is not installed and which workflows will require dashboard fallback.
27	- If `CLI usage: no`, skip this check.
28
29	## `03-preflight.md` format
30
31	```markdown
32	# Preflight — <ISO date>
33
34	- account ✓
35	- mcp_connected ✓
36	- api_key ✓
37	- app_provisioned ✓ app_id=app_abc123 region=us-east-1
38
39	Re-run with /butterbase-skills:journey-preflight.
40	```
41
42	## Outputs
43
44	- Writes/overwrites `docs/butterbase/03-preflight.md`.
45	- Updates `00-state.md` front-matter `app_id`, `api_base`, `last_updated`, and ticks `- [x] preflight`.
46
47	## Anti-patterns
48
49	- ❌ Echoing the API key value back to the user.
50	- ❌ Skipping a failed check ("I'll just try anyway"). Stop and ask the user to fix it.
51	- ❌ Calling `init_app` without confirming with the user — apps cost money on paid plans.

People who liked this also viewed

6 picks

Type

journey-preflight

533stars40forks

View on GitHub

How to install journey-preflight?

butterbase-ai/butterbase-skills/journey-preflight

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Butterbase Preflight
2
3	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`.
4
5	## When to use
6
7	- 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.
8	- Directly via `/butterbase-skills:journey-preflight` when the user wants to re-verify.
9
10	## Procedure
11
12	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.
13
14	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.
15
16	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 → ✓.
17
18	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.
19
20	4. App provisioned. Read `00-state.md` front-matter for `app_id`.
21	- Non-null and `mcp__butterbase__manage_app` (action `get_config`) succeeds → ✓.
22	- Null → ask the user: `"No app yet. Create one now? (yes/no — if no, you can paste an existing app_id)"`. On yes, call `mcp__butterbase__init_app` (ask for app name and region — recommend `us-east-1` as default). Capture `app_id` and `api_base` from the response. Update `00-state.md` front-matter.
23	- User-provided app_id → verify with `manage_app get_config`; on success update `00-state.md`.
24
25	5. CLI installed. Run `butterbase --version`. If "command not found":
26	- Read the Toolchain section of `02-plan.md`. If `CLI usage: yes` (default), prompt: "Install `@butterbase/cli` globally now? (yes / skip)". On yes, run `npm install -g @butterbase/cli`. On skip, note in `03-preflight.md` that the CLI is not installed and which workflows will require dashboard fallback.
27	- If `CLI usage: no`, skip this check.
28
29	## `03-preflight.md` format
30
31	```markdown
32	# Preflight — <ISO date>
33
34	- account ✓
35	- mcp_connected ✓
36	- api_key ✓
37	- app_provisioned ✓ app_id=app_abc123 region=us-east-1
38
39	Re-run with /butterbase-skills:journey-preflight.
40	```
41
42	## Outputs
43
44	- Writes/overwrites `docs/butterbase/03-preflight.md`.
45	- Updates `00-state.md` front-matter `app_id`, `api_base`, `last_updated`, and ticks `- [x] preflight`.
46
47	## Anti-patterns
48
49	- ❌ Echoing the API key value back to the user.
50	- ❌ Skipping a failed check ("I'll just try anyway"). Stop and ask the user to fix it.
51	- ❌ Calling `init_app` without confirming with the user — apps cost money on paid plans.

People who liked this also viewed

6 picks

Type