Documentation

Working with the agent

How to prompt the AI agent inside Vibe Studio for good results.

The agent embedded in Vibe Studio is agent-zero — the same runtime documented in agent-zero overview, wired into your workspace with file-system access, shell, AppMint discovery, and the planner. It can do a lot, but the gap between great output and frustrating output is mostly about how you ask.

Set the context once

The most expensive thing the agent does is rebuild context. If it has to re-read the project structure and the requirements from your prompt every turn, you waste tokens and time. Two cheap fixes:

  • Keep CLAUDE.md at the workspace root current. Every agent turn injects it into the system prompt. Use it for invariants: stack, conventions, lint rules, where things live.
  • Use the planner. The agent can read planner cards and append logs as it works. A well-formed card with description and acceptance criteria is the cheapest way to give the agent structured intent.

A typical CLAUDE.md:

# Project: My Storefront

## Stack
- Vite + React + TypeScript
- Tailwind v3
- AppMint customer audience

## Conventions
- Files live under src/ — pages in src/pages, components in src/components.
- Tailwind classes only. No styled-components, no CSS modules.
- All AppMint calls go through src/lib/appmint.ts.

## AppMint
- orgId is in env (VITE_APPMINT_ORG_ID).
- Customer signin via /profile/customer/signin.
- Repository pattern: PUT /repository/create with { name, datatype, isNew, data }.

Be specific about scope

Vague: "Improve the homepage."

Specific: "On the homepage, replace the hero section with a centered headline and one CTA. Headline reads 'Build the future'. The CTA links to /signup. Don't touch any other section."

The specific version gives the agent a clear edit target, an unambiguous content, and an explicit boundary. It writes a single edit, the preview reflects it immediately, and you can review and iterate.

Tell it which files to read

The agent will Glob and Grep to find what it needs, but those tool calls cost tokens. If you know the file, name it:

"Look at src/pages/checkout.tsx and add an error banner above the form when submitError is set."

The agent reads the one file, edits it, done. No exploration needed.

Reference the discovery API for AppMint work

Whenever the agent generates code that calls AppMint, it should hit discovery first:

curl "$APPMINT_API_URL/discover/02-data"
curl "$APPMINT_API_URL/discover/04-storefront"

You can prompt this explicitly:

"Add a /products page that lists products from AppMint. Use the discover/04-storefront endpoint for the schema; don't guess."

This isn't optional — the agent's instructions baked into AppMint integration explicitly say "discover first, code second". When you see the agent invent endpoint shapes that don't exist, point it at discovery.

Use the planner for multi-step work

For anything bigger than a single edit, ask the agent to plan first:

"Plan the next three features as planner cards: customer signup, product list, cart. Give each card a description and acceptance criteria. Don't write any code yet."

Then work through cards one at a time:

"Pick up the 'customer signup' card. Move it to In Progress. Implement and append logs to the card as you go."

This pattern keeps the agent working in small, reviewable chunks instead of producing a 2000-line dump that you can't sanely review.

Where the agent's output lands

Three places, all visible from the studio:

WhatWhere
File editsThe workspace on disk. session-manager exposes them at /preview/<orgId>/<projectName>/. Monaco refreshes the file in your tab automatically (with a "this file changed" toast if you have unsaved local edits).
Planner updates.vibe/planner.json. The studio's planner tab listens for planner:updated socket events and re-renders.
Conversation logsession-manager's conversationService persists every turn under data/conversations/<orgId>/<projectName>/<conversationId>.json. The studio reloads recent conversations from GET /api/conversations/<orgId>/<projectName>.
Memory.nano_claude/memory/ (when using a-mini) — long-running context, cross-session. See agent memory.
Shell side-effectsThe workspace folder. npm install, git commit, file moves all happen on real disk.

Stop work in progress

If the agent is going down the wrong path, the chat panel has a stop button. It cancels the streaming response and the in-flight tool call. The current state of the workspace is preserved — partial edits remain on disk, so if the stop hits during a Write, you may have a half-applied change. Re-prompt or revert with git.

When to delegate to a sub-agent

For research tasks ("find every place we call /repository/create") the main agent will spawn a sub-agent (general-purpose or researcher) automatically. You don't have to ask. For complex refactors that should run in isolation (a worktree on a different branch), prompt explicitly:

"Spawn a sub-agent in an isolated worktree to refactor src/lib/appmint.ts to use the new SDK. Report results when done."

See Multi-agent for the full sub-agent model.

Don't accept fabricated outputs

The agent's instructions explicitly forbid:

  • Inventing AppMint endpoints or response shapes.
  • Inventing CLI commands (no spinforge CLI exists).
  • Inventing config files (no spinforge.toml, no deploy.yaml).
  • Claiming a deploy succeeded without evidence.

When the agent does invent something — usually because it's been asked about a tool that genuinely doesn't exist — call it out. "Don't fabricate. Check discovery." resets the behaviour.

Quick review of agent behaviour

The agent will:

  • Read files before editing them.
  • Hit discovery before AppMint code.
  • Use the planner for multi-step work.
  • Keep memory of decisions across sessions.
  • Spawn sub-agents for research and isolated refactors.
  • Use git for non-trivial changes if the workspace has a repo.

The agent will not:

  • Modify .vibe/project.json's immutable fields.
  • Bake API keys into client code.
  • Use /profile/user/signin for customer apps.
  • Echo $APPMINT_TOKEN or any sfpk_….
  • Claim a deploy worked when it didn't.

When to escalate

If you've tried specific prompts and the agent keeps producing wrong output:

  • Check that .vibe/project.json exists and has the right orgId.
  • Confirm CLAUDE.md actually describes the project.
  • Re-read the agent's response — sometimes it's literally telling you what's missing.
  • File an issue against the agent-zero repo with the prompt and the (sanitised) output.