journey-templates

Name: journey-templates
Author: butterbase-ai

533stars40forks

How to install journey-templates?

butterbase-ai/butterbase-skills/journey-templates

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

Installs into the current project.

Summary

Use as the optional template-publishing stage of the Butterbase journey, after deploy (and substrate, if used). Walks the user through authoring a clone-ready README, bundling agent spec files, dry-running and pushing the repo snapshot, flipping visibility to public + listed, and

Files · 1

View on GitHub

SKILL.md

1	# Journey: Publish-as-template (optional)
2
3	Turn the deployed app into a public, forkable template. This stage is only for apps the user explicitly wants to share — most journeys end at `deploy` (or `submit` in hackathon mode).
4
5	## When to use
6
7	- Dispatched by `journey` when `current_stage: templates`.
8	- Directly via `/butterbase-skills:journey-templates`.
9	- The row is optional in the checklist; skip silently if the user declines.
10
11	## Inputs
12
13	- A deployed, working app (post-`journey-deploy`).
14	- `docs/butterbase/02-plan.md` — to know what features the app uses (agents, MCP servers, OAuth providers, function env vars).
15	- `docs/butterbase/04-build-log.md` — to confirm deploy smoke passed.
16
17	## Preflight
18
19	- `00-state.md` must have `current_stage: templates` or later AND `deploy` ticked.
20	- The `@butterbase/cli` must be installed locally (`butterbase --version` works). If not, invoke `journey-preflight` to fix.
21	- The repo must be bound: `.butterbase/config.json` exists with the right `currentApp`. If not, run `butterbase repo init <app_id>`.
22
23	## Procedure
24
25	0. Refresh docs. Call `butterbase_docs` with `topic: "templates"` (and `topic: "repo"` if the cache doesn't already cover snapshot push). Skip if `03b-docs-cache.md` is fresh.
26
27	1. Confirm intent. Ask:
28	> "Publish '<app_name>' as a public template? Public + listed makes it appear in the gallery; public + unlisted is forkable by anyone with the app_id but hidden from search. Or skip. (listed / unlisted / skip)"
29
30	Default: skip (especially in hackathon mode unless the user explicitly chose to publish their submission).
31
32	2. On skip: mark the row `- [x] templates (skipped — not publishing)` in `00-state.md`. Write `docs/butterbase/06-template.md` with one line: `Skipped on <date>.` Return to orchestrator.
33
34	3. On listed / unlisted: delegate to `butterbase-skills:templates`. The wrapped skill walks the user through:
35	a. Author / review README.md. This is the most important step — clone replay does not carry OAuth secrets, agent records, MCP server registrations, function secrets, or user data. The README must explain every manual step a cloner will need. The `templates` skill has the full checklist; do not let it write a short README and move on.
36	b. Bundle agent specs. If the app has agents, ensure `agents/<name>.json` exist (export with `butterbase agents get <name>` if missing) and are tracked.
37	c. Inspect drift. `butterbase repo status`. Walk the modified / untracked / deleted lists with the user. This is the chance to catch a stray secret file or an unwanted directory before it ends up in the snapshot.
38	d. Dry-run. `butterbase repo push --dry-run`. Confirm the final upload manifest matches what `repo status` showed.
39	e. Push. `butterbase repo push -m "publish v1"`. Capture the snapshot id.
40	f. Flip visibility. `butterbase visibility public --listed` (or `--unlisted`).
41	g. Self-clone test. `butterbase clone <app_id> /tmp/clone-test-<ts>` into a scratch directory — this also exercises the cloner-side `repo pull` that `butterbase clone` runs internally. The wrapped skill walks the README from a cold cloner's perspective and reports any gap. Loop back to (a) if gaps exist.
42
43	4. Write artifact. `docs/butterbase/06-template.md`:
44
45	```markdown
46	---
47	published_at: <ISO>
48	app_id: <id>
49	visibility: public
50	listed: <true\|false>
51	snapshot_id: <id>
52	selfclone_test: <pass \| gaps fixed in round N>
53	---
54
55	# Template publication
56
57	- Visibility: public (<listed \| unlisted>)
58	- Latest snapshot: <id>
59	- README covers: env vars, OAuth, agent re-import, MCP servers, seed data, first-run smoke
60	- Self-clone test directory: /tmp/clone-test-<ts>
61	- Gallery URL: https://butterbase.ai/templates/<app_id> (or wherever discovery lives)
62	```
63
64	5. Update state. Tick `- [x] templates` in `00-state.md`.
65
66	6. Return to orchestrator (or end the journey, since this is the last optional stage).
67
68	## Anti-patterns
69
70	- ❌ Pushing the repo after flipping visibility. Order matters: snapshot first, public second. Otherwise the gallery briefly advertises an empty template.
71	- ❌ Skipping the README. The clone preflight tells the cloner which env vars exist but not what they're for or what manual setup remains. A bare-bones README publishes a broken-on-clone experience.
72	- ❌ Skipping the self-clone test. The author always knows too much; only a cold walk-through catches missing instructions.
73	- ❌ Forgetting agent specs. The `agents` DB table doesn't replay. Without `agents/*.js

People who liked this also viewed

6 picks

Type

journey-templates

533stars40forks

View on GitHub

How to install journey-templates?

butterbase-ai/butterbase-skills/journey-templates

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Journey: Publish-as-template (optional)
2
3	Turn the deployed app into a public, forkable template. This stage is only for apps the user explicitly wants to share — most journeys end at `deploy` (or `submit` in hackathon mode).
4
5	## When to use
6
7	- Dispatched by `journey` when `current_stage: templates`.
8	- Directly via `/butterbase-skills:journey-templates`.
9	- The row is optional in the checklist; skip silently if the user declines.
10
11	## Inputs
12
13	- A deployed, working app (post-`journey-deploy`).
14	- `docs/butterbase/02-plan.md` — to know what features the app uses (agents, MCP servers, OAuth providers, function env vars).
15	- `docs/butterbase/04-build-log.md` — to confirm deploy smoke passed.
16
17	## Preflight
18
19	- `00-state.md` must have `current_stage: templates` or later AND `deploy` ticked.
20	- The `@butterbase/cli` must be installed locally (`butterbase --version` works). If not, invoke `journey-preflight` to fix.
21	- The repo must be bound: `.butterbase/config.json` exists with the right `currentApp`. If not, run `butterbase repo init <app_id>`.
22
23	## Procedure
24
25	0. Refresh docs. Call `butterbase_docs` with `topic: "templates"` (and `topic: "repo"` if the cache doesn't already cover snapshot push). Skip if `03b-docs-cache.md` is fresh.
26
27	1. Confirm intent. Ask:
28	> "Publish '<app_name>' as a public template? Public + listed makes it appear in the gallery; public + unlisted is forkable by anyone with the app_id but hidden from search. Or skip. (listed / unlisted / skip)"
29
30	Default: skip (especially in hackathon mode unless the user explicitly chose to publish their submission).
31
32	2. On skip: mark the row `- [x] templates (skipped — not publishing)` in `00-state.md`. Write `docs/butterbase/06-template.md` with one line: `Skipped on <date>.` Return to orchestrator.
33
34	3. On listed / unlisted: delegate to `butterbase-skills:templates`. The wrapped skill walks the user through:
35	a. Author / review README.md. This is the most important step — clone replay does not carry OAuth secrets, agent records, MCP server registrations, function secrets, or user data. The README must explain every manual step a cloner will need. The `templates` skill has the full checklist; do not let it write a short README and move on.
36	b. Bundle agent specs. If the app has agents, ensure `agents/<name>.json` exist (export with `butterbase agents get <name>` if missing) and are tracked.
37	c. Inspect drift. `butterbase repo status`. Walk the modified / untracked / deleted lists with the user. This is the chance to catch a stray secret file or an unwanted directory before it ends up in the snapshot.
38	d. Dry-run. `butterbase repo push --dry-run`. Confirm the final upload manifest matches what `repo status` showed.
39	e. Push. `butterbase repo push -m "publish v1"`. Capture the snapshot id.
40	f. Flip visibility. `butterbase visibility public --listed` (or `--unlisted`).
41	g. Self-clone test. `butterbase clone <app_id> /tmp/clone-test-<ts>` into a scratch directory — this also exercises the cloner-side `repo pull` that `butterbase clone` runs internally. The wrapped skill walks the README from a cold cloner's perspective and reports any gap. Loop back to (a) if gaps exist.
42
43	4. Write artifact. `docs/butterbase/06-template.md`:
44
45	```markdown
46	---
47	published_at: <ISO>
48	app_id: <id>
49	visibility: public
50	listed: <true\|false>
51	snapshot_id: <id>
52	selfclone_test: <pass \| gaps fixed in round N>
53	---
54
55	# Template publication
56
57	- Visibility: public (<listed \| unlisted>)
58	- Latest snapshot: <id>
59	- README covers: env vars, OAuth, agent re-import, MCP servers, seed data, first-run smoke
60	- Self-clone test directory: /tmp/clone-test-<ts>
61	- Gallery URL: https://butterbase.ai/templates/<app_id> (or wherever discovery lives)
62	```
63
64	5. Update state. Tick `- [x] templates` in `00-state.md`.
65
66	6. Return to orchestrator (or end the journey, since this is the last optional stage).
67
68	## Anti-patterns
69
70	- ❌ Pushing the repo after flipping visibility. Order matters: snapshot first, public second. Otherwise the gallery briefly advertises an empty template.
71	- ❌ Skipping the README. The clone preflight tells the cloner which env vars exist but not what they're for or what manual setup remains. A bare-bones README publishes a broken-on-clone experience.
72	- ❌ Skipping the self-clone test. The author always knows too much; only a cold walk-through catches missing instructions.
73	- ❌ Forgetting agent specs. The `agents` DB table doesn't replay. Without `agents/*.js

People who liked this also viewed

6 picks

Type