OpenSpec

OpenSpec is a spec-driven workflow for AI-assisted development. Motoko Base uses it so agents plan before coding — scoped changes instead of random diffs across the repo.

Official docs: openspec.dev

Why OpenSpec?

OpenSpec separates planning (proposal, design, specs, tasks) from implementation (apply). You review the plan before any product code changes.

Folder structure

openspec/
├── config.yaml              # Project context + rules for AI artifacts
├── specs/                   # Durable requirements (main specs)
│   └── <capability>/
│       └── spec.md
└── changes/
    ├── <active-change>/     # Work in progress
    │   ├── .openspec.yaml
    │   ├── proposal.md
    │   ├── design.md
    │   ├── tasks.md
    │   └── specs/<capability>/spec.md   # delta spec
    └── archive/
        └── <date>-<change-name>/        # completed changes

Main specs (openspec/specs/) are long-lived product memory — what the starter must do per capability (links, billing, storage, etc.).

Changes (openspec/changes/) are short-lived plans for one outcome. After archive, durable requirements merge into main specs.

Project-specific AI rules live in openspec/config.yaml (philosophy, stack, architecture constraints, per-artifact rules).

Create a proposal

Use Cursor slash command or ask the agent to run the propose skill:

/opsx-propose Add a bookmarks demo with user ownership

This creates openspec/changes/<name>/ and generates:

Planning only — no product code until you run apply.

To think without planning: /opsx-explore. To revise after review: /opsx-update.

Design

design.md records architectural decisions for the change:

• Which existing patterns to reuse (src/features/links/ as CRUD template)
• Schema, routes, and file touchpoints
• Trade-offs and non-goals at design level

Agents read proposal.md + existing codebase before writing design. Keep it short — prefer reusing starter patterns over inventing new layers.

Tasks

tasks.md is a checkbox list the agent follows during apply:

- [ ] 1.1 Add schema in src/lib/db/schema/...
- [ ] 2.1 Create queries.ts with ownership filters
- [ ] 3.1 Wire dashboard route and nav item

Tasks should be small, ordered (schema → server → UI → wiring), and name concrete file paths when known.

Apply

When the plan looks good:

/opsx-apply

The agent:

1. Reads proposal.md, delta specs, design.md, and tasks.md
2. Implements each unchecked task
3. Marks tasks - [x] as completed
4. Pauses if scope is unclear or the spec needs updating

You can run apply in multiple sessions — progress is tracked in tasks.md.

Archive

When all tasks are done and you have reviewed the code:

/opsx-archive

Archive:

1. Optionally syncs delta specs into openspec/specs/<capability>/spec.md
2. Moves the change folder to openspec/changes/archive/<date>-<name>/

Main specs become the source of truth for future AI sessions on that capability.

Useful CLI commands

openspec list                      # active changes
openspec status --change <name>    # artifact progress
openspec validate <name>           # check a change
openspec view                      # browse specs and changes

Install: OpenSpec installation

Cursor commands

Skills live in .agents/skills/openspec-* and .cursor/skills/openspec-*.

AI Development Workflow — End-to-end flow from idea to review.

Cursor / AI Agents — AGENTS.md and prompting tips.