Cursor Installation

Cursor supports Agent Teams Lite through .cursorrules files. Skills work as inline instructions, providing structured SDD workflow within Cursor’s AI-first editing experience.

Prerequisites

Cursor installed and configured
Git installed for cloning the repository
Access to ~/.cursor/skills/ (global) or project directory (project-local)

Installation Steps

Clone the repository

git clone https://github.com/gentleman-programming/agent-teams-lite.git
cd agent-teams-lite

Choose installation scope

Cursor supports both global and project-local installations.

Global (Recommended)
Project-Local

Available across all projects:

./scripts/install.sh
# Choose option 7: Cursor

./scripts/install.sh --agent cursor

Skills install to ~/.cursor/skills/sdd-*/

Only available in current project:

# Copy skills to project
mkdir -p skills
cp -r skills/sdd-* ./skills/
cp -r skills/_shared ./skills/

Skills install to ./skills/sdd-*/

You should see output like:

Installing skills for Cursor...
  ✓ _shared (3 convention files)
  ✓ sdd-init
  ✓ sdd-explore
  ✓ sdd-propose
  ✓ sdd-spec
  ✓ sdd-design
  ✓ sdd-tasks
  ✓ sdd-apply
  ✓ sdd-verify
  ✓ sdd-archive

  9 skills installed → ~/.cursor/skills

Add orchestrator to .cursorrules

Cursor reads AI instructions from .cursorrules files in your project root.Navigate to your project directory and create or edit .cursorrules:

cd your-project
code .cursorrules

Append the contents from examples/cursor/.cursorrules.

View orchestrator rules

The orchestrator rules teach Cursor to:

Detect SDD triggers and commands
Read skill files from ~/.cursor/skills/sdd-*/SKILL.md (or ./skills/)
Execute skills inline within current context
Track state between phases
Follow artifact storage policies (engram/openspec/none)

Key sections:

Operating Mode (delegate-only principle)
Artifact Store Policy
Commands table
Command → Skill Mapping
Dependency graph
Engram Artifact Convention

.cursorrules files are project-specific. Add SDD rules to each project where you want to use it, or include it in your project template.

Verify installation

Open Cursor in your project:

cursor .

Open the AI chat panel (Cmd+L / Ctrl+L) and type:

/sdd-init

Expected response:

Reading sdd-init skill from ~/.cursor/skills/sdd-init/SKILL.md...

✓ Detected stack: [your project's stack]
✓ SDD initialized

Configuration Locations

Global Skills

~/.cursor/skills/sdd-*/Available across all projects

Project Skills

./skills/sdd-*/Project-specific skills

Rules

.cursorrulesProject-level AI instructions

How It Works

Cursor doesn’t have a Task tool for sub-agent delegation. Skills run inline: Characteristics:

Skills execute in the same context window
No fresh context per phase
Still provides structured workflow
Planning phases work well
Implementation guided by skill instructions
Orchestrator handles batching

Example Usage

Initialize SDD

You: /sdd-init

Cursor: Reading sdd-init skill...
        
        Analyzing project...
        ✓ Framework: Next.js 14 (App Router)
        ✓ Language: TypeScript
        ✓ Database: Prisma + PostgreSQL
        ✓ Styling: Tailwind CSS
        
        Checking for persistence backend...
        ✓ Engram MCP server detected
        
        SDD initialized:
        - Project: my-saas
        - Artifact store: engram
        
        Ready to start building.

Start a New Feature

You: /sdd-new add-stripe-integration

Cursor: Exploring codebase for payment-related code...
        
        ✓ No existing payment integration
        ✓ API routes: app/api/
        ✓ Auth: NextAuth.js with session
        ✓ User model has userId field
        
        Creating proposal...
        
        Proposal Summary:
        - Intent: Integrate Stripe for subscription payments
        - Scope: Stripe SDK setup, webhook handling, subscription management
        - Approach: Stripe Checkout for payments, webhooks for events, Prisma for subscription state
        - Rollback: Remove Stripe API routes, drop subscription tables, remove webhook endpoint
        
        Artifact stored: sdd/add-stripe-integration/proposal
        
        Ready to continue with specs and design?

Fast-Forward Planning

You: /sdd-ff add-stripe-integration

Cursor: Running all planning phases...
        
        Creating specifications...
        ✓ 7 requirements (SHALL statements for payment, webhook, subscription)
        ✓ 15 scenarios (checkout flow, webhook handling, cancellation, etc.)
        ✓ Stored: sdd/add-stripe-integration/spec
        
        Creating technical design...
        ✓ Stripe SDK initialization in lib/stripe.ts
        ✓ API routes: /api/checkout, /api/webhooks/stripe
        ✓ Database models: Subscription, Payment
        ✓ Webhook signature verification
        ✓ Environment variables: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
        ✓ Stored: sdd/add-stripe-integration/design
        
        Creating task breakdown...
        ✓ Phase 1: Stripe setup (3 tasks)
        ✓ Phase 2: Checkout flow (4 tasks)
        ✓ Phase 3: Webhook handling (3 tasks)
        ✓ Phase 4: Subscription UI (3 tasks)
        ✓ Total: 13 tasks
        ✓ Stored: sdd/add-stripe-integration/tasks
        
        All planning complete. Run /sdd-apply to implement.

Apply Changes

You: /sdd-apply add-stripe-integration

Cursor: Implementing tasks from sdd/add-stripe-integration/tasks...
        
        Phase 1: Stripe setup
        ✓ 1.1 Install stripe package
        ✓ 1.2 Create lib/stripe.ts with SDK initialization
        ✓ 1.3 Add environment variables to .env.example
        
        Phase 2: Checkout flow
        ✓ 2.1 Create POST /api/checkout endpoint
        ✓ 2.2 Generate Checkout Session
        ✓ 2.3 Add success/cancel redirect URLs
        ✓ 2.4 Create SubscribeButton component
        
        4/13 tasks complete. Continue with Phase 3?

Artifact Storage

engram (Recommended)
openspec
none

# Auto-detected if Engram MCP server is available
artifact_store:
  mode: engram

Cursor can use Engram’s MCP server for persistent storage:Naming convention:

title:     sdd/add-stripe-integration/proposal
topic_key: sdd/add-stripe-integration/proposal
type:      architecture
project:   my-saas

Benefits:

Repository stays clean
Persistent across sessions
Searchable via mem_search

# Only when explicitly requested
artifact_store:
  mode: openspec

Creates file-based artifacts in your project:

openspec/
├── config.yaml
├── specs/
└── changes/
    └── add-stripe-integration/
        ├── proposal.md
        ├── specs/
        ├── design.md
        └── tasks.md

# Ephemeral mode - default fallback
artifact_store:
  mode: none

No persistence. Results returned inline only.

Team Setup

To share SDD with your team:

Commit .cursorrules to repository

git add .cursorrules
git commit -m "Add Agent Teams Lite SDD workflow"
git push

(Optional) Commit project-local skills

If using project-local skills instead of global:

git add skills/
git commit -m "Add SDD skills for local reference"
git push

Document in README

Add to your project’s README:

## Development Workflow

This project uses Spec-Driven Development (SDD) via Agent Teams Lite.

### Setup for Team Members

Install skills globally:
```bash
git clone https://github.com/gentleman-programming/agent-teams-lite.git
cd agent-teams-lite
./scripts/install.sh --agent cursor

Usage

Open Cursor and run:

/sdd-init - Initialize SDD context
/sdd-new <feature> - Start a new feature
/sdd-apply - Implement tasks

See .cursorrules for complete command reference.

</Step>

<Step title="Team members get rules automatically">
When team members pull, they get `.cursorrules` automatically:
```bash
git pull
cursor .
# SDD rules are now active

They’ll need to install skills globally (one-time setup).

Verification Checklist

Check skills directory (global)

ls ~/.cursor/skills/sdd-*/

Should show 9 directories:

sdd-apply/  sdd-design/  sdd-init/  sdd-spec/
sdd-archive/  sdd-explore/  sdd-propose/  sdd-tasks/  sdd-verify/

Check skills directory (project-local)

If using project-local installation:

ls ./skills/sdd-*/

Should show same 9 directories.

Check shared conventions

ls ~/.cursor/skills/_shared/
# or
ls ./skills/_shared/

Should show:

engram-convention.md
openspec-convention.md
persistence-contract.md

Verify .cursorrules exists

cat .cursorrules | grep -i "sdd"

Should return matches if orchestrator rules are present.

Test in Cursor

cursor .
# Open AI panel (Cmd+L / Ctrl+L)
# Type: /sdd-init

Should recognize the command and read the skill.

Troubleshooting

Command not recognized

Problem: Cursor doesn’t recognize /sdd-initSolutions:

Verify .cursorrules exists in project root
Check orchestrator rules are appended to .cursorrules
Restart Cursor to reload configuration
Try alternative phrasing: “Initialize SDD for this project”

Skills not found

Problem: Cursor can’t read skill filesSolutions:

Check skills location:
- Global: ~/.cursor/skills/sdd-*/
- Project: ./skills/sdd-*/
Verify each skill has SKILL.md file
Check file permissions allow reading
Ensure .cursorrules references correct path

Rules not loading

Problem: Orchestrator behavior not activeSolutions:

Check .cursorrules is in project root (not subdirectory)
Ensure file is readable: cat .cursorrules
Verify file has correct content (check for SDD section)
Restart Cursor after making changes
Try opening project folder directly (not individual files)

Context issues on large features

Problem: Errors about context lengthSolutions:

Use /sdd-explore first to understand scope
Break large features into smaller changes
Use none artifact mode to reduce context usage
Consider using Claude Code or OpenCode for large features (true sub-agents)

Limitations

Cursor runs skills inline rather than as true sub-agents. This means:

No fresh context per phase
Higher context usage than true sub-agent systems
May hit context limits on very large features
Planning phases work well
Implementation may need manual intervention on complex changes

For the best sub-agent experience with fresh context windows, consider:

Claude Code - Full sub-agent support
OpenCode - Full sub-agent support with slash commands

Next Steps

Quick Start

Learn the SDD workflow

Commands Reference

Complete command documentation

Engram Setup

Install recommended persistence

Team Workflows

Share SDD with your team

Get Started

Installation

Guides

Commands

Prerequisites

Installation Steps

Configuration Locations

Global Skills

Project Skills

Rules

How It Works

Example Usage

Initialize SDD

Start a New Feature

Fast-Forward Planning

Apply Changes

Artifact Storage

Team Setup

Usage

Verification Checklist

Troubleshooting

Limitations

Next Steps

Quick Start

Commands Reference

Engram Setup

Team Workflows

​Prerequisites

​Installation Steps

​Configuration Locations

Global Skills

Project Skills

Rules

​How It Works

​Example Usage

​Initialize SDD

​Start a New Feature

​Fast-Forward Planning

​Apply Changes

​Artifact Storage

​Team Setup

​Usage

​Verification Checklist

​Troubleshooting

​Limitations

​Next Steps

Quick Start

Commands Reference

Engram Setup

Team Workflows

Prerequisites

Installation Steps

Configuration Locations

How It Works

Example Usage

Initialize SDD

Start a New Feature

Fast-Forward Planning

Apply Changes

Artifact Storage

Team Setup

Usage

Verification Checklist

Troubleshooting

Limitations

Next Steps