feat: Enhance Cursor IDE support with new rules and validation

- Added Cursor IDE support documentation in CURSOR-SUPPORT.md, detailing the integration and limitations of Cursor with ControlFlow.
- Introduced new rules under .cursor/rules/ for core functionality, documentation parity, implementation review, planning, and portability.
- Implemented validation for Cursor rules in validate.mjs, ensuring compliance with defined standards and metadata requirements.
- Created regression tests for Cursor rules to verify frontmatter integrity and activation metadata.
- Updated governance documents to reflect Cursor IDE support policies and validation commands.
- Enhanced the structural validation harness to include checks for Cursor rules and their compliance with the canonical source matrix.

Author: Smith

.cursor/rules/controlflow-core.mdc

@@ -0,0 +1,11 @@
+---
+description: "Core ControlFlow identity, source hierarchy, and offline validations for the repository."
+alwaysApply: true
+---
+# ControlFlow Core
+
+This is a prompt/governance/eval repository, not a runtime application.
+Canonical multi-agent policies, roster, and tiers are governed by `.github/copilot-instructions.md` and `plans/project-context.md`.
+Use local sources for context; `AGENTS.md` is compatibility context only, not the primary artifact.
+Cursor cannot execute VS Code-only subagent semantics (`agent/runSubagent`), read policies rather than assuming a runtime capability.
+All changes must pass the deterministic offline validation gate: run `cd evals && npm test`.

.cursor/rules/controlflow-docs-evals.mdc

@@ -0,0 +1,16 @@
+---
+description: "Rules for documentation parity, localized tutorials, and eval verification."
+globs:
+  - "docs/**/*.md"
+  - "evals/**/*.mjs"
+  - "README.md"
+  - "CHANGELOG.md"
+  - "CONTRIBUTING.md"
+---
+# ControlFlow Docs And Evals
+
+Adhere to contribution and PR policies defined in `CONTRIBUTING.md`.
+Documentation changes must maintain English/Russian tutorial parity matching `docs/tutorial-en/` and `docs/tutorial-ru/` structure.
+Offline test expectations and the evaluation harness are documented in `evals/README.md`.
+Eval harness changes (such as `evals/validate.mjs` or `evals/package.json`) must avoid networking dependencies and remain deterministic.
+Always verify code changes by running `cd evals && npm test`.

.cursor/rules/controlflow-implementation-review.mdc

@@ -0,0 +1,14 @@
+---
+description: "Guidelines for implementation, testing, review, and governance alignment."
+globs:
+  - "*.agent.md"
+  - "governance/*.json"
+  - "schemas/*.json"
+---
+# ControlFlow Implementation And Review
+
+Agent files must adhere exactly to the P.A.R.T. order (Prompt, Archive, Resources, Tools) per `docs/agent-engineering/PART-SPEC.md`.
+Implementation and refactoring follow the core-first migration strategy defined in `docs/agent-engineering/MIGRATION-CORE-FIRST.md`.
+Never modify agent tool or permission profiles without updating `governance/agent-grants.json` and `governance/tool-grants.json`.
+All agent execution reports must conform to their schemas (e.g., `schemas/*execution-report.schema.json`).
+Ensure structured failure classification (`transient`, `fixable`, `needs_replan`, `escalate`) is applied in all outputs.

.cursor/rules/controlflow-planning.mdc

@@ -0,0 +1,13 @@
+---
+description: "Rules for planning, scope discipline, and plan artifact tracking."
+globs:
+  - "plans/**/*.md"
+  - "schemas/planner.*.json"
+---
+# ControlFlow Planning
+
+For planning and phase discipline, reference `Planner.agent.md` and `Orchestrator.agent.md`.
+ControlFlow uses explicit complexity tiers and semantic risk discovery documented in `plans/project-context.md`.
+Plan artifacts must follow the structure defined in `schemas/planner.plan.schema.json`.
+Reference `skills/patterns/completeness-traceability.md` for plan completeness criteria.
+Do not invoke VS Code-only subagent mechanics; follow the declarative phases and structured text reports.

.cursor/rules/controlflow-portability.mdc

@@ -0,0 +1,12 @@
+---
+description: "Guidelines for external host adaptation, portable plugins, and routing."
+globs:
+  - "plugins/**/*"
+  - "docs/agent-engineering/TOOL-ROUTING.md"
+---
+# ControlFlow Portability
+
+Adaptations like Codex and Claude Code runtimes are governed by `plugins/controlflow-codex/README.md` and `plugins/controlflow-claude-code/README.md`.
+Asset generation for shared plugins follows `plugins/controlflow-shared-source/README.md`.
+For external tool usage, strictly follow `docs/agent-engineering/TOOL-ROUTING.md` (local-first, verified external docs mapping).
+Do not try to make external IDE environments replicate VS Code-specific features like `runSubagent`.

CHANGELOG.md

@@ -6,6 +6,14 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [Unreleased]
+
+### Added
+
+- **Cursor IDE Support**: Added `.cursor/rules` to provide high-level guidance to the Cursor agent, along with documentation in `docs/agent-engineering/CURSOR-SUPPORT.md`.
+
+---
+
 ## [Unreleased] — Claude Code Plugin (Phase 6)
 
 ### Added - Claude Code Plugin

CONTRIBUTING.md

@@ -123,6 +123,17 @@ Always run `cd evals && npm test` after plugin edits to catch cross-repo drift.
 
 ---
 
+## Editing Cursor Rules (`.cursor/rules`)
+
+When editing `.cursor/rules`, ensure the following:
+
+1. **Frontmatter is valid:** Check that frontmatter starts with `---`, has a closing `---`, and includes at least one of `alwaysApply`, `description`, or `globs`.
+2. **Line budget respected:** Keep rules concise and within 500 lines.
+3. **Canonical references:** Point to canonical ControlFlow files (e.g. `.github/copilot-instructions.md`, `plans/project-context.md`) instead of copying policy content.
+4. **Run structural validation:** After editing, run `cd evals && npm test` to ensure no project-wide structural contracts were accidentally broken.
+
+---
+
 ## Proposing changes
 
 - **Bug reports and feature requests:** Open a GitHub Issue describing the problem or proposal clearly.

README.md

@@ -5,26 +5,42 @@
 ![Eval](https://img.shields.io/badge/eval-offline-brightgreen)
 ![License](https://img.shields.io/badge/license-MIT-green)
 
-A multi-agent orchestration system for VS Code Copilot, plus maintained Codex and Claude Code plugins. ControlFlow coordinates 13 specialized agents under deterministic **P.A.R.T contracts** (Prompt → Archive → Resources → Tools), structured text outputs, and layered reliability gates.
+A multi-agent orchestration system for VS Code Copilot, plus maintained Codex, Claude, and Cursor plugins. ControlFlow coordinates 13 specialized agents under deterministic **P.A.R.T contracts** (Prompt → Archive → Resources → Tools), structured text outputs, and layered reliability gates.
 
 ---
 
 ## Contents
 
-- [Why ControlFlow?](#why-controlflow)
-- [Quick Start](#quick-start)
-- [When to Use Which Agent](#when-to-use-which-agent)
-- [Pipeline by Complexity](#pipeline-by-complexity)
-- [Orchestration State Machine](#orchestration-state-machine)
-- [Failure Routing](#failure-routing)
-- [Agent Architecture](#agent-architecture)
-- [Evaluation Suite](#evaluation-suite)
-- [Project Structure](#project-structure)
-- [Documentation](#documentation)
-- [Installation](#installation)
-- [ControlFlow for Codex (Plugin)](#controlflow-for-codex-plugin)
-- [ControlFlow for Claude Code (Plugin)](#controlflow-for-claude-code-plugin)
-- [License](#license)
+- [ControlFlow](#controlflow)
+  - [Contents](#contents)
+  - [Why ControlFlow?](#why-controlflow)
+  - [Quick Start](#quick-start)
+  - [When to Use Which Agent](#when-to-use-which-agent)
+  - [Pipeline by Complexity](#pipeline-by-complexity)
+  - [Orchestration State Machine](#orchestration-state-machine)
+  - [Failure Routing](#failure-routing)
+  - [Agent Architecture](#agent-architecture)
+    - [Interaction diagram](#interaction-diagram)
+    - [Primary Agents](#primary-agents)
+    - [Specialized Subagents](#specialized-subagents)
+  - [Evaluation Suite](#evaluation-suite)
+  - [Project Structure](#project-structure)
+  - [Documentation](#documentation)
+  - [Installation](#installation)
+    - [Adding Custom Agents](#adding-custom-agents)
+  - [ControlFlow for Codex (Plugin)](#controlflow-for-codex-plugin)
+    - [Included Skills](#included-skills)
+  - [ControlFlow for Claude Code (Plugin)](#controlflow-for-claude-code-plugin)
+    - [Local Development Usage](#local-development-usage)
+    - [Intentional Differences from VS Code](#intentional-differences-from-vs-code)
+  - [ControlFlow for Cursor](#controlflow-for-cursor)
+  - [ControlFlow for Codex Usage and Validation](#controlflow-for-codex-usage-and-validation)
+    - [Plugin Installation](#plugin-installation)
+    - [Usage](#usage)
+    - [Validating Codex Strict-Plan Artifacts](#validating-codex-strict-plan-artifacts)
+    - [Intentional Differences from the VS Code Version](#intentional-differences-from-the-vs-code-version)
+  - [License](#license)
+  - [Acknowledgments](#acknowledgments)
 
 ---
 
@@ -349,6 +365,15 @@ See [`plugins/controlflow-claude-code/README.md`](plugins/controlflow-claude-cod
 
 Complexity routing matches the main project: `TRIVIAL` → optional; `SMALL` → plan-audit; `MEDIUM` → plan-audit + assumption-verifier; `LARGE` → full pipeline.
 
+## ControlFlow for Cursor
+
+This repository includes a `.cursor/rules/` directory with version-controlled Project Rules (`.mdc` files). Cursor automatically loads these rules when you open the project — no installation or configuration required. The rules give Cursor's AI agent high-level instructions about this repository's conventions, agent roles, and architectural principles.
+
+- **What it does:** Provides context and conventions to Cursor's agent.
+- **What it does NOT do:** It does not enable Cursor to run the VS Code subagent dispatch system.
+
+For more details, see the authoritative guide at [docs/agent-engineering/CURSOR-SUPPORT.md](docs/agent-engineering/CURSOR-SUPPORT.md).
+
 ## ControlFlow for Codex Usage and Validation
 
 ### Plugin Installation

docs/agent-engineering/CURSOR-SUPPORT.md

@@ -0,0 +1,73 @@
+# Cursor IDE Support
+
+## Overview
+
+ControlFlow supports Cursor IDE through version-controlled Project Rules under `.cursor/rules/`. These rules give Cursor users access to ControlFlow conventions, governance policies, and the offline verification gate without creating a new runtime plugin or altering VS Code agent semantics.
+
+Cursor IDE support is **documentation and rules only**. Cursor cannot execute VS Code-specific subagent semantics (`agent/runSubagent`) and no new tool grants or executor roles are required.
+
+## Rule Inventory
+
+All rules live under `.cursor/rules/` as `.mdc` files with YAML frontmatter.
+
+| File | Activation | Scope | Description |
+| ---- | ---------- | ----- | ----------- |
+| `controlflow-core.mdc` | `alwaysApply: true` | All sessions | Repo identity, canonical source hierarchy, no-runtime-app warning, offline eval gate |
+| `controlflow-planning.mdc` | `globs: plans/**/*.md, schemas/planner.*.json` | Planning work | Planning discipline, phase decomposition, risk review, plan-artifact conventions |
+| `controlflow-implementation-review.mdc` | `globs: *.agent.md, governance/*.json, schemas/*.json` | Implementation and review | P.A.R.T. preservation, tool/grant update requirements, failure classification |
+| `controlflow-docs-evals.mdc` | `globs: docs/**/*.md, evals/**/*.mjs, ...` | Documentation and evals | Tutorial parity, eval harness conventions, verification gate |
+| `controlflow-portability.mdc` | `globs: plugins/**/*, docs/agent-engineering/TOOL-ROUTING.md` | Portability work | Codex, Claude Code, and shared-source adapter guidance |
+
+## Activation Guidance
+
+- `controlflow-core.mdc` uses `alwaysApply: true` and is automatically active in every Cursor session for this repository.
+- Scoped rules activate via `globs` when the current file matches the specified pattern, keeping detailed instructions focused and session-context efficient.
+- Rules reference canonical ControlFlow files rather than duplicating long agent prompts, minimising stale-instruction risk.
+- Use Cursor Project Rules (`.cursor/rules/`) as the primary integration surface for Cursor users. Do not rely on the root `AGENTS.md` as the distributable Cursor surface; it is a local-only helper (see Limitations).
+
+## Limitations
+
+- **No VS Code runtime semantics.** Cursor does not support `agent/runSubagent`. Cursor rules provide guidance; they do not orchestrate ControlFlow subagents. No rule may claim or imply Cursor can execute VS Code-only capabilities.
+- **No new tool grants.** Cursor support is a documentation surface only. `governance/tool-grants.json` and `governance/agent-grants.json` are unchanged.
+- **No new executor roles.** Adding Cursor rules does not create new `executor_agent` entries in `plans/project-context.md` or `governance/project-context-registry.json`.
+- **Rules must stay under 500 lines.** Each `.mdc` file should reference canonical docs rather than copy them verbatim.
+- **AGENTS.md is local-only.** The root `AGENTS.md` is an explicit local-only helper for AI coding agents working in this repository. It is not the primary Cursor support artifact and must not be treated as a versioned Cursor rule.
+
+## Validation Commands
+
+Run these commands locally to verify Cursor rule integrity:
+
+```sh
+# Structural validation only (schema + P.A.R.T. + Cursor rule structure)
+cd evals && npm run test:structural
+
+# Full offline suite including Cursor rule contract validation
+cd evals && npm test
+```
+
+The offline eval harness validates:
+
+- All `.cursor/rules/*.mdc` files have valid frontmatter delimiters (opening and closing `---`).
+- All rules include at least one activation metadata key: `alwaysApply`, `description`, or `globs`.
+- `controlflow-core.mdc` uses `alwaysApply: true` and references at least one canonical ControlFlow path.
+- No rule file exceeds 500 lines.
+
+## Authoritative References
+
+| Concern | File |
+| ------- | ---- |
+| Cursor rule source of truth | `.cursor/rules/*.mdc` |
+| ControlFlow shared policies | `.github/copilot-instructions.md` |
+| Agent roster and complexity tiers | `plans/project-context.md` |
+| Tool routing policy | `docs/agent-engineering/TOOL-ROUTING.md` |
+| P.A.R.T. specification | `docs/agent-engineering/PART-SPEC.md` |
+| Eval harness documentation | `evals/README.md` |
+
+## Changing Cursor Rules
+
+Before modifying any `.cursor/rules/*.mdc` file:
+
+1. Verify the change does not duplicate content already in `.github/copilot-instructions.md` — reference the canonical file instead.
+2. Confirm the rule does not imply Cursor can use VS Code-only capabilities (`agent/runSubagent`).
+3. If a change requires updated Cursor frontmatter semantics, verify against official Cursor documentation (`https://cursor.com/docs/rules`) before editing; Cursor docs are the external source of truth for `.mdc` activation behaviour.
+4. Run `cd evals && npm test` after any rule change. The structural gate must pass before declaring the change done.

docs/agent-engineering/README.md

@@ -18,12 +18,13 @@ Index of governance and engineering policy documents. Each agent loads the relev
 - [`SCORING-SPEC.md`](SCORING-SPEC.md) — Quantitative scoring reference for reviewers and eval harnesses.
 - [`MIGRATION-CORE-FIRST.md`](MIGRATION-CORE-FIRST.md) — Shared implementation backbone pattern and consolidation exit criteria.
 
-## Portability & Plugins
+## Portability & IDE Support
 
-The repository contains adaptations of the ControlFlow system for non-VS Code environments:
+The repository contains adaptations of the ControlFlow system for non-VS Code environments and IDE integrations:
 
 - **Codex CLI**: See `plugins/controlflow-codex/README.md` for the portable skills and artifacts adapter.
 - **Claude Code**: See `plugins/controlflow-claude-code/README.md` for the native plugin skills, agents, and local development lifecycle.
+- **Cursor IDE**: See [`CURSOR-SUPPORT.md`](CURSOR-SUPPORT.md) for the version-controlled Project Rules surface, activation guidance, limitations, and validation commands. Cursor support does not alter VS Code tool grants or add new executor roles.
 
 ## Runtime capabilities (shipped in the ControlFlow revision program)