journey-agents

Name: journey-agents
Author: butterbase-ai

533stars40forks

How to install journey-agents?

butterbase-ai/butterbase-skills/journey-agents

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

Installs into the current project.

Summary

Use as the agents build stage of the Butterbase journey. Implements the Agents section of 02-plan.md by delegating to the agents skill for each agent. Registers any required MCP servers, validates each graph_spec, creates the agent, and smokes it via invoke_agent. Skipped if th

Files · 1

View on GitHub

SKILL.md

1	# Journey: Agents
2
3	Build the agents described in `02-plan.md`. Order: MCP servers first (probe must pass before any agent references them) → agents → smoke runs.
4
5	## When to use
6
7	- Dispatched by `journey` when `current_stage: agents`.
8	- Directly via `/butterbase-skills:journey-agents`.
9	- Skipped (annotated `(n/a)`) if the plan lists no agents.
10
11	## Preflight
12
13	If `docs/butterbase/03-preflight.md` is missing, older than 24 hours, or `00-state.md` has `app_id: null`, invoke `butterbase-skills:journey-preflight` first. Wait for it to return successfully before proceeding.
14
15	## Inputs
16
17	- `docs/butterbase/02-plan.md` — the Agents section (names, purpose, tool list, visibility, MCP servers needed).
18	- `docs/butterbase/00-state.md` — for `app_id`.
19	- Any handcrafted spec files under `agents/` in the project (preferred — version-controlled and survives clones).
20
21	## Procedure
22
23	0. Refresh docs. Call `butterbase_docs` with `topic: "agents"`. If the cache (`docs/butterbase/03b-docs-cache.md`) already covers agents, skip.
24
25	1. Register MCP servers first. For each MCP server in the plan:
26	- Print: `"Registering MCP server '<label>' at <url> (transport=<sse\|http\|streamable_http>). Proceed?"`. Wait for `yes`.
27	- Call the MCP-servers registration route (or the dashboard's MCP Servers page if a wrapping MCP tool is not yet available — check `butterbase_docs` topic `agents` for the current preferred path).
28	- Wait for probe result. If `status: unhealthy`, surface the error and ask the user to fix (URL, auth header, transport mismatch) before continuing. Do not create agents that reference an unhealthy server.
29
30	2. Build each agent. For each agent in the plan, in order:
31	a. Print: `"About to build agent: <name> (visibility=<v>, tools=<n builtin / m mcp / k function>). Proceed?"`. Wait for `yes`.
32	b. Invoke `butterbase-skills:agents` via the Skill tool with: agent name, intended behaviour, plan-derived tool list, model preference, visibility/limits. The wrapped skill drafts the `graph_spec`, writes it to `agents/<name>.json` in the project repo, and calls `validate_agent_spec`.
33	c. If validation fails, surface the Zod issues and loop the agents skill to fix.
34	d. Safety gate. If `visibility != 'private'` AND any node can reach a write tool (`insert_row`, `update_row`, `delete_row`, `write_storage`, or any `read_write`-mode MCP/function tool), explicitly ask: `"This agent is reachable by <visibility> callers and can write data. Set safety_acknowledged=true? (yes / change to private / reduce tools)"`. Do not proceed silently.
35	e. `create_agent` with the validated spec.
36	f. Smoke: `invoke_agent` with a representative input. Poll `get_agent_run` until terminal. If the run errors, debug per the `agents` skill's debugging procedure; otherwise show the user the final output.
37	g. Append one line per agent to `docs/butterbase/04-build-log.md`:
38	`<ISO timestamp> agents create_agent <agent-name> ok (run smoke=<run_id>)`
39
40	3. Persist specs to the repo. Confirm `agents/<name>.json` files are tracked locally. They will be carried by `butterbase repo push` (run by the `templates` stage if the user is publishing, or any time the user pushes a snapshot). This is the only way a clone recipient can recreate the agents — the `agents` table is not part of clone replay.
41
42	4. Tick state. Mark `- [x] agents` in `00-state.md`, set `current_stage` to the next unchecked stage.
43
44	5. Return to `journey` orchestrator (or ask `"Continue to the next stage? (yes/no)"`).
45
46	## Outputs
47
48	- One or more agents created against the live app.
49	- One or more `agents/<name>.json` spec files in the project repo.
50	- One line per agent in `docs/butterbase/04-build-log.md`.
51
52	## Anti-patterns
53
54	- ❌ Skipping `validate_agent_spec`. Bad specs surface as opaque runtime errors after the agent is live.
55	- ❌ Creating a `public` write-capable agent without rate limits or a `daily_budget_usd`. The runtime requires `safety_acknowledged`, but you should also pick hourly per-IP and per-app caps.
56	- ❌ Hard-coding secrets in `system_prompt` or `args_template`. Read them from `ctx.env` inside a function tool.
57	- ❌ Forgetting that the `agents` table is not replayed on clone. Always commit the spec JSON and document re-import (`butterbase agents create -f agents/<name>.json`) in the README.
58	- ❌ Smoking with `visibility: 'private'` and calling it good for a `public` agent. After the smoke, change visibility and re-test with an unauthenticated curl to confirm the public path works.

People who liked this also viewed

6 picks

Type

journey-agents

533stars40forks

View on GitHub

How to install journey-agents?

butterbase-ai/butterbase-skills/journey-agents

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Journey: Agents
2
3	Build the agents described in `02-plan.md`. Order: MCP servers first (probe must pass before any agent references them) → agents → smoke runs.
4
5	## When to use
6
7	- Dispatched by `journey` when `current_stage: agents`.
8	- Directly via `/butterbase-skills:journey-agents`.
9	- Skipped (annotated `(n/a)`) if the plan lists no agents.
10
11	## Preflight
12
13	If `docs/butterbase/03-preflight.md` is missing, older than 24 hours, or `00-state.md` has `app_id: null`, invoke `butterbase-skills:journey-preflight` first. Wait for it to return successfully before proceeding.
14
15	## Inputs
16
17	- `docs/butterbase/02-plan.md` — the Agents section (names, purpose, tool list, visibility, MCP servers needed).
18	- `docs/butterbase/00-state.md` — for `app_id`.
19	- Any handcrafted spec files under `agents/` in the project (preferred — version-controlled and survives clones).
20
21	## Procedure
22
23	0. Refresh docs. Call `butterbase_docs` with `topic: "agents"`. If the cache (`docs/butterbase/03b-docs-cache.md`) already covers agents, skip.
24
25	1. Register MCP servers first. For each MCP server in the plan:
26	- Print: `"Registering MCP server '<label>' at <url> (transport=<sse\|http\|streamable_http>). Proceed?"`. Wait for `yes`.
27	- Call the MCP-servers registration route (or the dashboard's MCP Servers page if a wrapping MCP tool is not yet available — check `butterbase_docs` topic `agents` for the current preferred path).
28	- Wait for probe result. If `status: unhealthy`, surface the error and ask the user to fix (URL, auth header, transport mismatch) before continuing. Do not create agents that reference an unhealthy server.
29
30	2. Build each agent. For each agent in the plan, in order:
31	a. Print: `"About to build agent: <name> (visibility=<v>, tools=<n builtin / m mcp / k function>). Proceed?"`. Wait for `yes`.
32	b. Invoke `butterbase-skills:agents` via the Skill tool with: agent name, intended behaviour, plan-derived tool list, model preference, visibility/limits. The wrapped skill drafts the `graph_spec`, writes it to `agents/<name>.json` in the project repo, and calls `validate_agent_spec`.
33	c. If validation fails, surface the Zod issues and loop the agents skill to fix.
34	d. Safety gate. If `visibility != 'private'` AND any node can reach a write tool (`insert_row`, `update_row`, `delete_row`, `write_storage`, or any `read_write`-mode MCP/function tool), explicitly ask: `"This agent is reachable by <visibility> callers and can write data. Set safety_acknowledged=true? (yes / change to private / reduce tools)"`. Do not proceed silently.
35	e. `create_agent` with the validated spec.
36	f. Smoke: `invoke_agent` with a representative input. Poll `get_agent_run` until terminal. If the run errors, debug per the `agents` skill's debugging procedure; otherwise show the user the final output.
37	g. Append one line per agent to `docs/butterbase/04-build-log.md`:
38	`<ISO timestamp> agents create_agent <agent-name> ok (run smoke=<run_id>)`
39
40	3. Persist specs to the repo. Confirm `agents/<name>.json` files are tracked locally. They will be carried by `butterbase repo push` (run by the `templates` stage if the user is publishing, or any time the user pushes a snapshot). This is the only way a clone recipient can recreate the agents — the `agents` table is not part of clone replay.
41
42	4. Tick state. Mark `- [x] agents` in `00-state.md`, set `current_stage` to the next unchecked stage.
43
44	5. Return to `journey` orchestrator (or ask `"Continue to the next stage? (yes/no)"`).
45
46	## Outputs
47
48	- One or more agents created against the live app.
49	- One or more `agents/<name>.json` spec files in the project repo.
50	- One line per agent in `docs/butterbase/04-build-log.md`.
51
52	## Anti-patterns
53
54	- ❌ Skipping `validate_agent_spec`. Bad specs surface as opaque runtime errors after the agent is live.
55	- ❌ Creating a `public` write-capable agent without rate limits or a `daily_budget_usd`. The runtime requires `safety_acknowledged`, but you should also pick hourly per-IP and per-app caps.
56	- ❌ Hard-coding secrets in `system_prompt` or `args_template`. Read them from `ctx.env` inside a function tool.
57	- ❌ Forgetting that the `agents` table is not replayed on clone. Always commit the spec JSON and document re-import (`butterbase agents create -f agents/<name>.json`) in the README.
58	- ❌ Smoking with `visibility: 'private'` and calling it good for a `public` agent. After the smoke, change visibility and re-test with an unauthenticated curl to confirm the public path works.

People who liked this also viewed

6 picks

Type