Emery

CI License: MIT OR Apache-2.0 Docs

Spec-driven development in Cursor: plan a change, approve it, then refine → build → merge each slice from durable artifacts — not chat history.

Emery uses Source Adapters (like intent or typescript) to ingest requirements and Target Adapters (like contracts or omnia) to generate outputs.

Quick start

Starting fresh? Follow the steps below. Migrating an existing codebase? See Migrate a legacy service · hosted.

Prerequisites

1. Cursor with the Augentic marketplace plugin installed (Settings → Plugins → search Augentic → install → restart). That gives you the /emery:* skills.
2. Optional: the emery CLI on PATH (the plugin can install it on /emery:init):

# prebuilt binary (verifies the Release archive's sha256, installs to ~/.local/bin)
curl -fsSL https://raw.githubusercontent.com/augentic/emery/main/scripts/install.sh | sh

# from source
cargo install --git https://github.com/augentic/emery --tag v0.32.0 --locked

Verify installation:

emery --version

First change

This path uses the Contracts target. A bare adapter name resolves local-first and pulls the newest published version from GHCR when nothing local exists; you do not need to clone emery-adapters.

Option A: Cursor Agent In Cursor Agent chat, in a fresh or disposable repository:

/emery:init contracts
/emery:plan first-contract

When prompted, give a one-line intent such as: Author an HTTP API contract for a health endpoint that returns status and version. Then:

/emery:execute
/emery:finalize first-contract

Option B: Terminal CLI The same steps run manually:

emery init contracts
emery plan author first-contract \
  --intent "Author an HTTP API contract for a health endpoint that returns status and version."
# review change.md, discovery.md, plan.yaml
emery plan execute   # opens authorization epoch; drives the loop
emery plan status     # must be drained
emery plan archive    # after you publish via git

What you should see after execute: slice artifacts under .emery/slices/…, generated files under contracts/, and merged baseline specs under .emery/specs/.

How it works: The rhythm

/emery:init  →  /emery:plan  →  review  →  /emery:execute  →  /emery:finalize
                                    │
                                    └─ per slice: refine → build → merge

The pause after planning is the operator review step: nothing privileged runs until you invoke emery plan execute — that journals plan.execute.started and drives the loop under gap gates. A one-slice change uses the same steps as a twelve-slice migration. Code generation lives in target adapters, not in Cursor skills.

When plan execute parks, or you want to drive one slice without the drained loop, you can use the breakout skills: /emery:refine, /emery:build, /emery:merge, and /emery:drop (or their CLI equivalents).

Documentation & Guides

• Quick Start Tutorial: Guided Omnia walkthrough · hosted
• Migrate a legacy service: TypeScript → Omnia walkthrough · hosted
• Command Lookup: Quick reference
• Core Concepts: What is Emery? · Core concepts · AGENTS.md § Workflow nouns
• Installation: Prerequisites
• How-tos:
  • Drive a slice manually
  • Amend a plan before executing
  • Drop down a layer (when automation fails)
  • Bind multiple sources
  • Resolve spec conflicts
• Troubleshooting: GitHub Issues
• Full Developer Guide: emery.augentic.io · In-tree book source

Developing Emery (contributors)

The repository root is a Rust workspace producing the emery binary. The root Makefile forwards every goal to cargo-make.

make test    # native integration suite
make check   # format, lint, tests, doctests, and docs
make ci      # full pre-commit gate, including vet and deny

Use make eval only for changes to engine prompts or answer schemas; it requires model credentials. make lab -- ARGS is the native mock-catalog lab shim, not the installed operator CLI.

Preview the working-tree Cursor skills against a local CLI:

cursor-agent --plugin-dir plugins/emery

Start with the developer loop, then Cursor operator plugins and CONTRIBUTING.md. See also GOVERNANCE.md and Code of Conduct.

License

Dual-licensed under MIT or Apache 2.0, at your option.