Skill532 repo starsupdated 2d ago

journey-docs

Journey-docs is a preparation stage that reads the project plan to identify which Butterbase capabilities are needed, retrieves relevant documentation for each capability via the butterbase_docs tool, and writes a cached summary to `docs/butterbase/03b-docs-cache.md` for downstream build stages to reference. Use it automatically after journey-preflight completes, or manually whenever the plan changes or a build stage encounters undocumented capability usage.

View source Repository: butterbase-skills

Install in Claude Code

Copy

git clone --depth 1 https://github.com/butterbase-ai/butterbase-skills /tmp/journey-docs && cp -r /tmp/journey-docs/skills/journey-docs ~/.claude/skills/journey-docs

Then start a new Claude Code session; the skill loads automatically.

Definition

SKILL.md

# Journey Docs Gate

A short, mechanical priming step. The goal is that every downstream stage starts with the relevant docs already in the conversation, so the model doesn't invent API shapes.

## When to use

Invoke automatically after `journey-preflight` returns. Also invoke standalone (`/butterbase-skills:journey-docs`) any time the user changes the plan or you realize a stage is using a capability you haven't refreshed this session.

## Procedure

1. **Read the plan.** Open `docs/butterbase/02-plan.md`. Identify every Butterbase capability in use (Tables → schema; RLS → auth; Auth → auth; Storage → storage; Functions → functions; AI → ai; RAG → rag; Realtime → realtime; Durable → functions; Frontend → frontend; Integrations → integrations; Substrate → substrate; Payments → billing).

2. **Call `butterbase_docs` per topic.** For each unique topic from step 1, call `butterbase_docs` with that `topic` argument. Skip duplicates.

3. **Write the cache file.** Create `docs/butterbase/03b-docs-cache.md` with this structure:

   ```markdown
   ---
   primed_at: <ISO timestamp>
   topics: [<comma-separated list>]
   ---

   # Docs Cache

   ## <topic-1>
   <one-paragraph summary of what the MCP doc says — key endpoints, common patterns, gotchas>
   URL: https://docs.butterbase.ai/<area>

   ## <topic-2>
   ...
   ```

4. **Update `00-state.md`.** Tick the `docs` row.

5. **Return.** One-line summary: `"Primed docs for: schema, auth, storage, functions. Cache at docs/butterbase/03b-docs-cache.md."`

## Anti-patterns

- ❌ Calling `butterbase_docs` with `topic: "all"`. Burns context. Call once per relevant topic instead.
- ❌ Skipping the cache file. Other stages re-read it; in-memory only doesn't survive context compression.
- ❌ Calling for topics not in the plan. We're priming, not exhaustive.