MOTOKO BASEDocumentation
AI Development Workflow
How to build on Motoko Base with AI agents — from idea to review using OpenSpec and Cursor.
Motoko Base ships with a spec-driven AI workflow. Instead of asking an agent to rewrite the app in one shot, you plan in OpenSpec artifacts, review the plan, then implement task-by-task. Changes stay scoped, reviewable, and aligned with starter architecture.
This is one of the starter's selling points: you get production patterns and the tooling to extend them safely with AI.
The workflow
Idea
↓
OpenSpec (optional explore)
↓
Proposal
↓
Design
↓
Tasks
↓
Cursor / AI Agent (apply)
↓
Implementation
↓
Review → archive| Phase | What you do | Output |
|---|---|---|
| Idea | Describe the feature or fix in chat | Rough goal |
| Explore (optional) | /opsx-explore — trade-offs, codebase mapping | Clarified scope, no code |
| Proposal | /opsx-propose — what & why, non-goals | proposal.md |
| Design | Created with propose — how it fits the starter | design.md |
| Tasks | Checkbox steps for the agent | tasks.md |
| Apply | /opsx-apply — implement tasks one by one | Code changes |
| Review | Read the diff, run checks, test manually | Approved or revise |
| Archive | /opsx-archive — sync specs, move change to archive | Updated openspec/specs/ |
Planning and implementation are separate steps. Propose does not write product code. Apply waits until you explicitly start it.
When to use the full workflow
| Situation | Use OpenSpec? |
|---|---|
| New feature or demo | Yes |
| Multi-file refactor | Yes |
| Cross-cutting change (auth, billing, schema) | Yes |
| Typo, copy tweak, one-line bug | No — normal chat edit |
Example session
/opsx-explore Should team invites be a demo or core feature?
/opsx-propose Add team invites demo with ownership checks
# Review proposal.md, design.md, tasks.md — edit or /opsx-update if needed
/opsx-apply
pnpm lint && pnpm typecheck && pnpm test && pnpm build
/opsx-archivePrerequisites
- OpenSpec CLI installed globally (
npm install -g @fission-ai/openspec@latest) - Cursor (or another agent that loads
.agents/skills/) - Read
AGENTS.mdin the repo root — architecture rules agents follow
The repo is already initialized — no openspec init needed.
After implementation
Run the starter checks before merging:
pnpm lint
pnpm typecheck
pnpm test
pnpm buildPoint the agent at an existing feature (e.g. src/features/links/) as a template for new work.
OpenSpec — Artifacts, commands, apply, and archive in detail.
Cursor / AI Agents — AGENTS.md, skills, and how to prompt within Motoko architecture.