Journey

Butterbase Guided Journey

End-to-end orchestrator. Walks the user from idea to deployed Butterbase app, and (in hackathon mode) on through submission. Each stage writes a markdown artifact under docs/butterbase/ in the user's project. The orchestrator reads docs/butterbase/00-state.md to know the cursor and dispatches the matching journey-* stage skill.

When to use

Invoke automatically when the user signals end-to-end intent: "I want to build…", "let's build an app", "ship this", "help me build a hackathon project". Invoke explicitly when the user runs /butterbase-skills:journey.

If the user wants to do a single stage only (e.g., just design a schema), defer to the matching standalone skill (schema-design) or per-stage command (/butterbase-skills:journey-schema) instead of starting the full journey.

Toolchain

The journey assumes two npm packages alongside the MCP tools:

| Package | Role | When to install | |---|---|---| | @butterbase/sdk | TypeScript client for the deployed app — auth.signIn, db.from(...).select(), storage.upload, realtime subscriptions, function invocation. Works both in the browser (frontend) and in Node (functions, scripts, server-side). | Install in any frontend or any Node service that talks to the deployed app. Auto-added by frontend scaffolds. | | @butterbase/cli | Local-dev CLI — project scaffolding, log tailing, function invocation from the shell, API-key generation, schema diff preview without the dashboard. | Install globally (npm i -g @butterbase/cli) once per dev machine. Used during journey-preflight. |

The journey will prompt for both in plan (which SDK surfaces does the app need?) and preflight (is the CLI installed?). The MCP tools and these packages are complementary: MCP is for agentic / orchestration flows; SDK + CLI are for ordinary application code and the human dev loop.

Procedure

1. Detect state. Check whether docs/butterbase/00-state.md exists in the working directory.

• If absent: this is a fresh journey. Ask the user "Is this a hackathon submission? (yes/no)" to set hackathon_mode. Create docs/butterbase/ and write a starter 00-state.md (template below). If hackathon_mode: false, the starter template's submit row must be written as - [ ] submit (n/a — not a hackathon) rather than plain - [ ] submit. Then proceed to stage idea.
• If present: read the front-matter and the stage checklist. Identify the first unchecked, non-skipped stage. That is the next stage.

1. Confirm with user. Print a one-line summary of where we are: "Resuming journey at for app_id ." Ask: "Continue from ? (yes / jump to other stage / redo previous)".

1. Dispatch. Invoke the matching skill via the Skill tool. Do not do the stage's work inline — delegate.

| Stage | Skill | |---|---| | idea | butterbase-skills:journey-idea | | plan | butterbase-skills:journey-plan | | preflight | butterbase-skills:journey-preflight | | docs | butterbase-skills:journey-docs | | schema | butterbase-skills:journey-schema | | rls | butterbase-skills:journey-rls | | auth | butterbase-skills:journey-auth | | storage | butterbase-skills:journey-storage | | functions | butterbase-skills:journey-functions | | ai | butterbase-skills:journey-ai | | rag | butterbase-skills:journey-rag | | realtime | butterbase-skills:journey-realtime | | durable | butterbase-skills:journey-durable | | agents | butterbase-skills:journey-agents | | frontend | butterbase-skills:journey-frontend | | deploy | butterbase-skills:journey-deploy | | substrate | butterbase-skills:journey-substrate (optional) | | submit | butterbase-skills:journey-submit (hackathon_mode only) | | templates | butterbase-skills:journey-templates (optional) |

Docs gate. Stage docs runs once, right after preflight, to prime butterbase_docs for every capability in the plan. Subsequent build stages start with the relevant docs cached at docs/butterbase/03b-docs-cache.md. If the user changes the plan mid-build, re-run /butterbase-skills:journey-docs before the affected stage.

1. After the stage skill returns, re-read 00-state.md and ask the user whether to advance to the next unchecked stage. Stage selection rules:

• Build-stage order is: schema → rls → auth → storage → functions → ai → rag → realtime → durable → agents → frontend.
• If hackathon_mode: true and all build stages are done, the next stage is deploy then substrate then submit then templates.
• If hackathon_mode: false, the journey ends at deploy unless the user opts into templates — skip substrate and submit entirely (treat them as (n/a)).
• The substrate stage is always optional. In hackathon mode, default to skipping it (mark as (n/a — optional, can add post-submission)); in non-hackathon mode, skip it entirely as it is not part of the core journey.
• The templates stage is always optional. It runs after deploy (non-hackathon) or after submit (hackathon). Default is to skip unless 01-idea.md or 02-plan.md flags publish_as_template: true.
• Loop until the cursor reaches DONE (every stage checked or annotated n/a).

Starter 00-state.md template

When initialising a fresh journey, write this to docs/butterbase/00-state.md (ask the user "Is this a hackathon submission? (yes/no)" first to set hackathon_mode):

---
app_id: null
api_base: null
hackathon_mode: 
hackathon_deadline: null
frontend_stack: null
current_stage: idea
last_updated: 
---

# Journey state

## Stages
- [ ] idea
- [ ] plan
- [ ] preflight
- [ ] docs
- [ ] schema
- [ ] rls
- [ ] auth
- [ ] storage
- [ ] functions
- [ ] ai
- [ ] rag
- [ ] realtime
- [ ] durable
- [ ] agents
- [ ] frontend
- [ ] deploy
- [ ] substrate (optional)
- [ ] submit
- [ ] templates (optional)

## Notes
- Journey initialised .

If hackathon_mode: false, write the submit row as - [ ] submit (n/a — not a hackathon) instead of the plain unchecked form, so the orchestrator and any direct stage invocation will skip it.

Outputs

• Creates docs/butterbase/ and 00-state.md on first run.
• Updates current_stage and last_updated in 00-state.md whenever it dispatches.

Anti-patterns

• ❌ Doing a stage's work inline instead of delegating to its skill. The orchestrator only routes.
• ❌ Skipping the "Continue from ?" confirmation — users may want to jump or redo.
• ❌ Letting 00-state.md drift out of sync. Always re-read after each stage returns.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: butterbase-ai
• Source: butterbase-ai/butterbase-skills
• License: MIT

Install and usage instructions live in the source repository linked above.