Skip to Content

Briefing the agent

Write the brief in business terms, let the agent write a spec first and wait for your review, then build part by part with a check after each part.

An agent connected to manh.run reads the framework docs through the framework_docs tool, so you don’t teach it antd, Hono or the app/ layout. Your job is to make the business clear.

Write the brief

A good brief answers three questions: who uses the app, what they do in which order, and what information it keeps.

Use manh.run to build a "Spa bookings" app. Customers book on a public page: pick a service, a date and time, leave a name and phone. The receptionist confirms or moves the time; each therapist sees their own schedule by day. The owner sees revenue per week and edits the service price list. Email the customer once a booking is confirmed. Write the spec first and wait for my review.
  • Use real work: “the receptionist moves the time”, not “a booking management feature”.
  • State the business rules you already know: who may cancel, how far ahead, which amounts need approval.
  • Price lists, categories and staff are data the owner edits, never hard-coded. Say who edits them.
  • You don’t need to pick libraries, name files or describe every button. The agent proposes those in the spec.

Review the spec before any code

For a new app, or a feature that adds an object, a role or a group of screens, the agent follows manh.run’s spec process. It writes PRD.md, ORCA.md (roles, objects, permissions) and spec/01–04 (data, lifecycles, API, screens) in the working folder, then asks you once.

That one question covers: the roles and what each may do, each object’s status flow, the screen list, the brand color, and the open questions the agent had to assume an answer for. Answer each point. A change here costs far less than a change in code.

An agent running in the browser (ChatGPT, Gemini) has no working folder on your machine. Ask it to show a short spec in the chat before it writes any file.

Build part by part

After your review, the agent builds in order, each part passing check before the next:

  1. Data: the tables and repository.ts (business rules, lifecycles, permissions).
  2. API: thin handlers over the repository, then a deploy to test the API.
  3. Test: demo data through the API, then each role’s main flow. The agent writes these tests into spec/acceptance.json; from then on, every deploy reruns them on a copy with its own database.
  4. UI: the layout and every page, then a deploy.
  5. A checkpoint.

You look at the app in the manh.run dashboard after each part. The app is done when each role’s main flow works on the deployed app and you have looked at the main screens on a phone and a desktop.

Ask for changes

  • One thing at a time, with the place and the result you want: “On the request list, add a department column and a department filter.”
  • Point at the exact spot: select Pick element on the preview, click the part, then Copy prompt. The prompt names the file and the line.
  • Big changes: ask the agent for a checkpoint first, and to change the spec before the code.

Good to know

  • Say “go all the way, no need to ask” and the agent writes its decisions into the spec and keeps going instead of stopping for review.
  • The agent can’t read your old chats. In a new chat, ask it to read the spec in the working folder again, or paste the part it needs.

Next steps

Last updated