Advanced structured mode
Reviewers read a generated API surface. CI runs the same file. Cloud keeps the history. Your agent wrote all of it — and there's no second spec for anyone to maintain.
01
The agent aligns on intent first
Before writing anything, your agent restates endpoint, auth, status codes, and business rules — and blocks on anything ambiguous. Bounded and typed intent is exactly what AI code generation needs to stop hallucinating.
02
The agent writes the contract
Agents declare the endpoint surface as executable code: happy path, error cases, auth boundaries. Every case carries a plain-English description of why it exists. You review the file, not a transcript.
03
Build against the same file
The contract runs red before the server exists and turns green as endpoints land. Your agent fixes the implementation against it — not the contract. When green, the same file is already your regression suite.
04
Everyone else reads one surface
The CLI regenerates a readable surface report from the same file on every commit: covered cases, deferred gaps, missing schemas. PMs scan markdown; engineers diff it; Cloud keeps the history. Nobody hand-maintains docs.
Real code in the repo, versioned with the implementation. Nothing to hand-maintain.
The CLI turns the contract into a readable map on every commit. Plain markdown, not raw TypeScript.
The same file runs locally, in CI, and uploads history to Cloud. One source of truth at every layer.
Why it works
Agents keep cross-endpoint rules, per-endpoint cases, and the generated surface report in sync. Reviewers read markdown; the runner executes code; both come from the same file your agent already wrote.
Project rules
Business rules, role boundaries, and state semantics that span the whole API. Written once in GLUBEAN.md, referenced by every contract.
Executable contracts
The API boundary as runnable code. Endpoint surface, happy path, error cases, and auth boundaries — versioned with the implementation it verifies.
Generated surface
A dated report regenerated from the contracts — covered, deferred, and missing cases at a glance. Reviewers read it; nobody maintains it by hand.
Why it holds
The traditional workflow has agents juggling a spec, generated stubs, and hand-written tests that drift apart. Here there's one file. When your agent changes the boundary, the surface report and the regression suite follow automatically.
Why it holds
Before writing any contract, your agent surfaces ambiguous items back to you — auth, optional fields, error behavior. Bounded intent keeps generated contracts honest. A 30-second clarification is cheaper than a wrong contract reviewers have to unpick.
What this is not
Not OpenAPI → codegen → hand-written tests. One file replaces all three.
Not a product/ or docs/ folder that drifts from the real API within a sprint.
Not a Postman collection living outside version control and outside code review.
Not prompt-only generation where next week's agent re-derives coverage from scratch.
Worked example: team invites
The agent captures cross-endpoint rules and drops the 201 / 409 / 403 matrix into one contract file. Reviewers scan it, PMs read the generated surface, and the implementation team builds against the same artifact.
Reviewer
The case list
Reads the case list the agent wrote — 201 / 409 / 403 laid out as structured cases.
PM
The surface report
Reads the generated surface report — covered cases, deferred gaps, missing schemas. Never opens TypeScript.
Implementation
The runnable contract
Builds against the same file the agent produced — runs red until the endpoint lands, then green.
Project rules
Keep the project-level business rules short and explicit. Endpoint-level details live in contracts, not in a second prose layer.
Example: team invites
Only admin may create team invites.
Invite states are pending, accepted, expired, and revoked.
Duplicate pending invite for the same email returns 409.
Expired invite token returns 410.
Build against the contract
Implementation no longer guesses from prompts. It lines up with the endpoint and lifecycle rules already declared in code.
POST /team/invites → 201 with { id, email, role, state: 'pending', expiresAt } when called with an admin key.
POST /team/invites → 409 when a pending invite for the same email already exists.
POST /team/invites → 403 when the client holds a viewer-scoped key.
Keep the same boundary after launch
The contract does not disappear once the API works. It stays as the same verification boundary, with readable projection and Cloud visibility layered on top.
`glubean run contracts/` is your regression suite — same file that started red on day one.
`glubean projection` regenerates the surface report on every commit, so it never lies.
Cloud stores the run history, so a case that breaks in production shows up next to the one that broke in staging.
Executable contracts and readable projection
The source of truth lives in code: project-level business rules in GLUBEAN.md, shared schemas and clients, executable contracts, and a projection the CLI can regenerate into readable surface maps.
Contract artifacts
This is a representative slice, not the full contract surface. Real API suites usually add more contract files, flow verification, and richer projection output over time.
import { contract } from "@glubean/sdk";
import { teamApi } from "../config/team";
import { InviteSchema } from "../schemas/team";
export const inviteMember = contract.http("invite-member", {
description: "Team invites must stay explicit about role rules and token state.",
client: teamApi,
endpoint: "POST /team/invites",
cases: {
created: {
description: "admin can invite a member by email",
request: {
body: { email: "new@example.com", role: "member" },
},
expect: {
status: 201,
schema: InviteSchema,
},
},
duplicatePending: {
description: "duplicate pending invite returns 409",
request: {
body: { email: "existing@example.com", role: "member" },
},
expect: { status: 409 },
},
viewerBlocked: {
description: "viewer key cannot create invites",
client: viewerTeamApi,
request: {
body: { email: "new@example.com", role: "member" },
},
expect: { status: 403 },
},
},
});The contract file is the primary interface artifact: endpoint, cases, descriptions, expected status, and typed schema all live here.