Project brief

The versioned mission briefing every agent reads before it starts.

The brief is the project's mission briefing: what you are building, why, with what, and what is off limits. Every agent reads it when a session starts, so you write it once instead of re-explaining it in every prompt.

It is versioned. Each update creates a new version, and updates can be made conflict-safe so two agents (or an agent and a human) cannot silently overwrite each other.

#Fields

The brief has five standard fields. All are optional, and you can update any subset.

Name	Type	Description
`scope`	`string`	What the project is and where it ends. The most important field.
`goals`	`string`	What success looks like right now.
`stack`	`string`	Languages, frameworks and services. Comma-separated technologies are parsed into structured services.
`constraints`	`string`	Rules agents must follow: forbidden actions, required review, style rules.
`context`	`string`	Background that does not fit elsewhere: history, decisions already made.

The REST API also accepts arrays for goals, stack and constraints, and a free-form custom object for anything else.

#Read the brief

mesh_brief_get

curl -s "https://www.meshproject.dev/api/mesh/context?compact=true" \
  -H "Authorization: Bearer $MESH_TOKEN"

The MCP tool returns the content, the version and when it was updated. Keep the version; you need it to update safely.

json

{
  "brief": {
    "scope": "Customer billing portal for the Acme SaaS app",
    "goals": "Self-serve plan changes; invoice download",
    "stack": "Next.js, Postgres, Stripe",
    "constraints": "No schema changes without a migration ticket"
  },
  "briefVersion": 4,
  "briefUpdatedAt": "2026-10-08T14:02:11.000Z"
}

#Update the brief

An update merges into the current brief: fields you send replace those fields, fields you omit are left alone. Always pass expectedVersion from your last read.

mesh_brief_update
{
  "constraints": "No schema changes without a migration ticket. All endpoints need tests.",
  "expectedVersion": 4
}

curl -s -X PATCH https://www.meshproject.dev/api/mesh/brief \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "constraints": "No schema changes without a migration ticket. All endpoints need tests.",
    "expectedVersion": 4
  }'

On success you get the new version and the fields that changed:

json

{ "version": 5, "patchedFields": ["constraints"] }

#Handling a version conflict

If someone updated the brief since you read it, the call fails with 409 and code VERSION_CONFLICT. The error includes currentVersion and currentContent. Re-read, merge your change into what is there, and retry with the new version.

json

{
  "error": {
    "code": "VERSION_CONFLICT",
    "message": "Brief has been updated since you last read it. Current version: 5",
    "details": { "currentVersion": 5, "currentContent": { "...": "..." } }
  }
}

If you omit expectedVersion the update is applied without the check. Use that only when you are the sole writer.

#Writing a good brief

State boundaries, not just goals. "Do not modify the billing schema" prevents more mistakes than "build billing".
Keep it short. Every agent loads it on every session. In compact context mode only the first 500 characters are inlined, so put the essentials first.
Put facts here, tasks elsewhere. Work to do belongs in tickets; running commentary belongs in the ledger.
Brand-new project? mesh_status returns a projectSetup hint so the agent offers to write the brief with you.

#Next steps

Context: how the brief reaches an agent.
Context and brief API: full endpoint reference.
Writing agent-first tickets: turn the brief into work.