Documentation

Cursor / AI Agents

How to use Cursor, Claude, and other AI agents with Motoko Base — AGENTS.md, skills, and architecture-aware prompting.

Motoko Base is built for AI-assisted development. Agents get explicit instructions on where code goes, what patterns to follow, and how to plan changes through OpenSpec — so output matches a real SaaS starter, not a generic Next.js tutorial.

Works with Cursor, Claude Code, and other agents that read project instructions and skills.

Project instructions

Two files define how agents should behave:

File	Role
`AGENTS.md`	Architecture placement, patterns to follow/avoid, demo vs core, check commands
`openspec/config.yaml`	Product philosophy, stack, UI rules, per-artifact rules for OpenSpec

CLAUDE.md points to AGENTS.md for Claude Code. Cursor loads AGENTS.md via workspace rules.

Before any feature work, agents should know:

Code goes in src/features/<name>/, not scattered in src/app/
Database and auth stay server-side
Mutations use Server Actions + Zod + userId ownership
Optional integrations soft-fail when env is unset

Skills and slash commands

Motoko Base includes OpenSpec skills the agent loads automatically:

.agents/skills/openspec-propose/
.agents/skills/openspec-apply-change/
.agents/skills/openspec-archive-change/
.agents/skills/openspec-explore/
.agents/skills/openspec-update-change/
.agents/skills/openspec-sync-specs/

In Cursor, matching slash commands live in .cursor/commands/:

Command	Use when
`/opsx-explore`	Exploring ideas — no code
`/opsx-propose`	Starting a new change
`/opsx-update`	Revising the plan
`/opsx-apply`	Implementing tasks
`/opsx-archive`	Finishing a change

Domain skills (Drizzle, Supabase Postgres) live in .agents/skills/ for schema and query work.

Cursor docs: Cursor documentation

How to give good tasks

Frame requests so the agent stays within Motoko architecture:

Do

/opsx-propose Add a notes demo under src/features/notes/
Reuse the links feature pattern: queries.ts, actions.ts, schemas.ts,
ownership via session userId, thin route in src/app/dashboard/notes/

/opsx-apply
Follow AGENTS.md — server-first, Zod at boundary, no new UI libraries

Add a nav item for Notes in src/features/dashboard/config/nav.ts

Avoid

Build a notes app with Redux and a separate API server

Put all logic in src/app/dashboard/notes/page.tsx

Skip auth checks for now, we'll add them later

Useful references to cite

Pattern	Point the agent here
CRUD demo feature	`src/features/links/`
File uploads	`src/features/storage/`
Settings + sessions	`src/features/dashboard/components/settings/`
Billing integration	`src/lib/billing/` + `src/features/dashboard/actions/billing.ts`
New database table	Adding a New Table
Auth	Better Auth

Say whether work is core infrastructure, a reusable pattern, or a removable demo — agents use that in OpenSpec proposals.

Cursor vs Claude Code

Tool	How Motoko Base hooks in
Cursor	`AGENTS.md` rules + `/opsx-*` commands + `.cursor/skills/`
Claude Code	`CLAUDE.md` → `AGENTS.md` + same OpenSpec CLI/skills
Other agents	Read `AGENTS.md`, `openspec/config.yaml`, run `openspec` CLI manually

Install OpenSpec CLI globally: installation guide

Checks agents should run

AGENTS.md requires these before finishing:

pnpm lint
pnpm typecheck
pnpm test
pnpm build

Ask the agent to run them after /opsx-apply or any substantial edit.

Small fixes without OpenSpec

Typos, copy changes, and one-line bugs do not need a full change proposal. Use normal chat:

Fix the typo on the billing page headline

Use OpenSpec when the change touches multiple files, adds behavior, or needs reviewable requirements.

AI Development Workflow — Full workflow from idea to archive.

OpenSpec — Proposals, tasks, apply, and archive.

Project structure — Where code lives.