Build with agents

This page is the whole loop for a coding agent and the developer who runs it: what the agent reads first, the rules it follows, how it builds and repairs, and what it must never do. Reading it takes about five minutes.

MainSDK is pre-release: the commands on this page are the planned design and do not run yet. mainsdk check --json --agent is planned for 0.3.

A coding agent builds your app. An app agent runs inside it and acts for a user; that is a different job, covered in Agents with an identity, a budget and approvals. The words are fixed in the vocabulary.

App agents path

If your app runs agents of its own, read these in order:

1. Agents with an identity, a budget and approvals: name the agent in each call, give it a budget, and make a person approve risky or costly steps.
2. MCP server and client: expose your actions as tools, and call other MCP servers from an allowlist, both under the same checks.
3. Agent payments and wallets: let an agent pay a declared payee inside its budget, and add wallet sign-in (milestone 0.7).

What the agent reads first

If a call or option is not in the docs or the skill's references/interfaces.md, it does not exist yet. The agent says so and never invents it.

The rules the agent follows

1. Call interfaces (import { auth, db, ai } from "mainsdk"), never a provider SDK.
2. Keep secrets out of code: secret:NAME in main.yaml.
3. Deny by default. Every route and action names its permission, and records are read through db.<model>.for(user).
4. Destructive actions ask a person, also when an agent calls them.
5. Uploads and share links go through files and share.
6. Declare what the change needs in main.yaml (driver, permissions, data labels, network hosts) and keep the change minimal.

The loop

  read the spec or issue
          |
          v
  build on interfaces  <-----------------------+
          |                                    |
          v                                    |
  mainsdk check --json --agent                 |
          |                                    |
     passed: true? --- yes --> report and stop |
          |                                    |
          no                                   |
          v                                    |
  read each finding: code, file, line, fix     |
          |                                    |
          v                                    |
  fix the code (never the rule) ---------------+

  Same finding still open after three rounds:
  the check returns `ask: person`. Stop and ask.

1. Read the spec or the issue, then the interface page for each interface the change touches.
2. Build on the interfaces. Write tests with @mainsdk/testing.
3. Run npx mainsdk check --json --agent. Exit code 0 means passed, 1 means a gate failed, 2 means a usage or configuration error.
4. Fix every finding from its file, line and fix. Run npx mainsdk explain <code> if a fix is unclear.
5. Run the same command again.
6. After the third unresolved round on the same finding, stop and ask a person. The repair loop has the output shape.

What the agent must never do

• Weaken a check: lower a severity, relax a main.yaml rule, a network allowlist or a limit, delete a test or a gate, or hide a use behind raw().
• Add an exception without an owner and an expiry. An exception is a person's decision, so the agent proposes it and tells the developer.
• Call a provider SDK directly (stripe, openai, @aws-sdk/*) for something an interface covers.
• Commit a secret, a .env file or a key in the client bundle.

For agents

Goal:    Make the requested change and reach `"passed": true`.
Read:    llms.txt, .claude/skills/mainsdk/SKILL.md, AGENTS.md, main.yaml, the spec or issue.
Touch:   the files the change needs, plus main.yaml to declare what it uses. Nothing else.
Verify:  npx mainsdk check --json --agent   (pass = "passed": true and exit code 0)
Repair:  fix each finding from its file, line and fix. Re-run. After three unresolved
         rounds on one finding, stop and ask the developer.
Never:   weaken a check, add an exception without an owner and expiry, call a provider
         SDK directly, or commit a secret.

In this section

Next

• Use MainSDK with your coding agent
• The check
• Prompts that work