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.

2. **Confirm with user.** Print a one-line summary of where we are: `"Resuming journey at <stage> for app_id <id or 'not yet provisioned'>."` Ask: `"Continue from <stage>? (yes / jump to other stage / redo previous)"`.

3. **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.

4. **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`):

```markdown
---
app_id: null
api_base: null
hackathon_mode: <true|false>
hackathon_deadline: null
frontend_stack: null
current_stage: idea
last_updated: <ISO-8601 timestamp>
---

# Journey state

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