APEX Cursor Integration Proposal

Status: DRAFT Author: Robert Matsuoka Date: 2026-02-13 Requested By: Kartik

Summary

Integrate APEX with Cursor IDE through custom instructions (rules) and slash commands (skills) to enable AI-assisted product development workflows directly within the development environment.

Goals

Contextual AI Assistance - Cursor understands APEX artifacts and workflows
Streamlined Artifact Creation - Slash commands for creating Initiatives, PRDs, Experiments
Validation & Quality - AI validates artifacts against APEX schemas
Cross-Reference Navigation - Jump between related artifacts and code

Integration Architecture

┌─────────────────────────────────────────────────────────┐
│                      Cursor IDE                          │
├─────────────────────────────────────────────────────────┤
│  Custom Instructions (.cursor/rules/)                    │
│  ├── apex-context.mdc      # APEX framework awareness   │
│  ├── artifact-patterns.mdc # Artifact creation rules    │
│  └── product-context.mdc   # Domain/product hierarchy   │
├─────────────────────────────────────────────────────────┤
│  Slash Commands (.cursor/skills/)                        │
│  ├── /apex-init           # Initialize APEX in project  │
│  ├── /apex-initiative     # Create new initiative       │
│  ├── /apex-prd            # Create PRD from initiative  │
│  ├── /apex-experiment     # Create experiment           │
│  ├── /apex-validate       # Validate artifact           │
│  ├── /apex-link-repo      # Link repository to init     │
│  └── /apex-status         # Show product/init status    │
├─────────────────────────────────────────────────────────┤
│  MCP Server (optional future)                            │
│  └── apex-mcp             # Advanced integrations       │
└─────────────────────────────────────────────────────────┘

Custom Instructions (Rules)

1. apex-context.mdc

Provides framework awareness to Cursor's AI:

---
description: APEX Framework Context
globs: ["**/*.md", "**/Initiative.md", "**/PRD-*.md", "**/repos.yaml"]
alwaysApply: true
---

# APEX Framework

APEX (AI Product Execution) is Duetto's product development framework.

## Directory Structure
- `products/{domain}/{product}/initiatives/` - Product initiatives
- `docs/` - Framework documentation
- `templates/` - Artifact templates
- `schemas/` - JSON Schema validation

## Artifact Types
- **Initiative** (I-YYYY-NNN): Time-bounded delivery effort
- **Experiment** (E-YYYY-NNN): Hypothesis validation
- **PRD** (PRD-YYYY-NNN): Product requirements document
- **Team Charter** (TC-NNN): Team definition

## Status Workflows
- Initiative: discovery → validated → delivery → deployed → learning → success (or killed)
- PRD: draft → review → approved → in-development → deployed → learning

## Key Files
- `Initiative.md` - Initiative specification
- `repos.yaml` - Repository linking
- `PRD-*.md` - Product requirements

When working in APEX:
- Follow artifact ID conventions
- Validate against schemas in `schemas/`
- Link repos at initiative level via repos.yaml
- Use templates from `templates/`

2. artifact-patterns.mdc

Rules for creating APEX artifacts:

---
description: APEX Artifact Creation Patterns
globs: ["**/initiatives/**", "**/prds/**", "**/experiments/**"]
---

# Artifact Creation Rules

## Initiative Creation
When creating an Initiative:
1. Generate ID: I-{YEAR}-{NNN} (sequential)
2. Create directory: `products/{domain}/{product}/initiatives/{id}/`
3. Copy template from `templates/initiative/`
4. Fill required fields: title, hypothesis, metrics, timeline
5. Create repos.yaml if repositories known

## PRD Creation
When creating a PRD:
1. Generate ID: PRD-{YEAR}-{NNN}
2. Link to parent Initiative
3. Define user stories with acceptance criteria
4. Map to JIRA epic creation

## Experiment Creation
When creating an Experiment:
1. Generate ID: E-{YEAR}-{NNN}
2. Define clear hypothesis
3. Set success/failure criteria
4. Specify duration and resources

## Validation
Before finalizing any artifact:
- Validate against schema in `schemas/`
- Ensure all required fields populated
- Check cross-references are valid

3. product-context.mdc

Product hierarchy awareness:

---
description: Duetto Product Hierarchy
globs: ["**/products/**"]
---

# Duetto Product Portfolio

## Domains
- **applications**: GameChanger, Essentials, BlockBuster, OpenSpace, Duetto Go, ScoreBoard, Advance
- **analytics**: Forecasting, ML Platform, Pricing, Product Analytics
- **data-platform**: Canonical Data Model, Data Pipelines, Data Lake
- **integrations**: PMS Connectors, CRS Connectors, Channel Managers
- **engineering-platform**: Security, Monolith, Infrastructure
- **apex**: APEX Framework (meta)

## Repository Linking
Repos are linked at initiative level via `repos.yaml`:
- `role: primary` - Main deliverable repo
- `role: supporting` - Helper repos
- `role: dependency` - Dependencies (read-only)
- `role: shared` - Multi-product repos

## Navigation
- Domain README shows all products and rolled-up repos
- Product README shows all initiatives and repos
- Initiative README shows linked repos and artifacts

Slash Commands (Skills)

/apex-init

Initialize APEX in current project:

---
name: apex-init
description: Initialize APEX framework in current project
---

# APEX Initialization

Creates APEX structure in current directory:
1. Create `products/` directory with domain structure
2. Copy templates to `templates/`
3. Copy schemas to `schemas/`
4. Create `.cursor/rules/` with APEX context
5. Initialize first product/initiative if specified

## Usage
/apex-init [--product <name>] [--domain <domain>]

## Example
/apex-init --product gamechanger --domain applications

/apex-initiative

Create new initiative:

---
name: apex-initiative
description: Create a new APEX initiative
---

# Create Initiative

Prompts for:
- Domain (select from list)
- Product (select from domain)
- Initiative title
- Problem statement
- Hypothesis
- Success metrics
- Timeline

Generates:
- Initiative ID (I-YYYY-NNN)
- Directory structure
- Initiative.md from template
- Empty repos.yaml

## Usage
/apex-initiative [--domain <domain>] [--product <product>]

## Example
/apex-initiative --domain applications --product gamechanger

/apex-prd

Create PRD from initiative:

---
name: apex-prd
description: Create PRD linked to initiative
---

# Create PRD

Creates product requirements document linked to an initiative.

Prompts for:
- Initiative ID or select from list
- PRD title
- User stories
- Acceptance criteria
- Technical requirements

Generates:
- PRD ID (PRD-YYYY-NNN)
- PRD-{id}.md in initiative directory
- JIRA epic creation (optional)

## Usage
/apex-prd [--initiative <id>]

## Example
/apex-prd --initiative I-2026-042

/apex-experiment

Create experiment:

---
name: apex-experiment
description: Create hypothesis validation experiment
---

# Create Experiment

Creates experiment for validating hypotheses.

Prompts for:
- Initiative ID (optional parent)
- Hypothesis
- Success criteria
- Failure criteria
- Duration
- Resources needed

Generates:
- Experiment ID (E-YYYY-NNN)
- Experiment.md from template
- Tracking metrics setup

## Usage
/apex-experiment [--initiative <id>]

/apex-link-repo

Link repository to initiative:

---
name: apex-link-repo
description: Link repository to initiative
---

# Link Repository

Adds repository to initiative's repos.yaml.

Prompts for:
- Initiative ID or select
- Repository name/URL
- Role (primary/supporting/dependency/shared)
- Team (optional)
- Paths (for monolith references)

Updates:
- `repos.yaml` in initiative directory
- Product README roll-up
- Domain README roll-up

## Usage
/apex-link-repo [--initiative <id>] [--repo <name>]

## Example
/apex-link-repo --initiative I-2026-042 --repo duetto-pricing-engine

/apex-validate

Validate APEX artifacts:

---
name: apex-validate
description: Validate APEX artifacts against schemas
---

# Validate Artifacts

Validates current file or directory against APEX schemas.

Checks:
- Required fields present
- ID format correct
- Status values valid
- Cross-references exist
- repos.yaml structure

Reports:
- Validation errors
- Warnings
- Suggestions

## Usage
/apex-validate [--path <path>]
/apex-validate --all  # Validate entire products/ directory

/apex-status

Show product/initiative status:

---
name: apex-status
description: Show APEX product and initiative status
---

# APEX Status

Shows status of products and initiatives.

Output:
- Domain summary (products, repos, initiatives)
- Product details (initiatives by status)
- Initiative progress
- Repository coverage

## Usage
/apex-status [--domain <domain>] [--product <product>]
/apex-status --all  # Full portfolio view

Implementation Plan

Phase 1: Custom Instructions (Week 1)

Create .cursor/rules/ directory in APEX
Write apex-context.mdc
Write artifact-patterns.mdc
Write product-context.mdc
Test with Cursor AI interactions

Phase 2: Basic Slash Commands (Week 2)

Create .cursor/skills/ directory
Implement /apex-init
Implement /apex-initiative
Implement /apex-validate
Test artifact creation flow

Phase 3: Advanced Commands (Week 3)

Implement /apex-prd
Implement /apex-experiment
Implement /apex-link-repo
Implement /apex-status
Test full workflow

Phase 4: MCP Server (Future)

Design MCP server architecture
Implement JIRA integration
Implement GitHub integration
Advanced cross-referencing

File Structure

APEX/
├── .cursor/
│   ├── rules/                    # Custom instructions
│   │   ├── apex-context.mdc
│   │   ├── artifact-patterns.mdc
│   │   └── product-context.mdc
│   └── skills/                   # Slash commands
│       ├── apex-init.md
│       ├── apex-initiative.md
│       ├── apex-prd.md
│       ├── apex-experiment.md
│       ├── apex-link-repo.md
│       ├── apex-validate.md
│       └── apex-status.md
├── products/                     # Product hierarchy
├── templates/                    # Artifact templates
├── schemas/                      # Validation schemas
└── docs/                         # Documentation

Success Metrics

Metric	Target	Measurement
Artifact creation time	-50%	Time to create Initiative/PRD
Validation errors	<5%	Post-creation validation failures
Developer adoption	>80%	Teams using APEX commands
Cross-reference accuracy	100%	Valid links in repos.yaml

Open Questions

Claude Code vs Cursor: Support both? Different skill formats?
MCP Priority: Build MCP server early for JIRA integration?
Template Customization: Per-team template variants?
ID Generation: Centralized registry vs local generation?

Approval

[ ] Kartik - Architecture approval
[ ] Bob - CTO approval
[ ] Engineering leads - Workflow validation

This document is DRAFT and subject to revision based on feedback.