Skip to content

AI-DLC on Cursor

The Cursor runtime is one of the framework's harness distributions, for Cursor. One tree serves both the Cursor IDE and the Cursor CLI (agent): they share the same .cursor/ discovery. One deterministic core, many harnesses: the engine, state machine, audit log, graph, swarm referee, and learnings gate are byte-identical across every distribution - only the shell differs. The source/development tree is generated into ignored local dist/cursor/ from core/ + harness/cursor/ by bun scripts/package.ts cursor; never hand-edit it.

Harness-specific onboarding lives in .cursor/rules/aidlc-onboarding.mdc, loaded automatically through alwaysApply: true. The root AGENTS.md block is harness-neutral and shared with other installed harnesses whose engine directories differ.

Layout

Cursor is the most "native" port so far - it consumes the standard core projection directly (no emit.ts, no split dot-dir). The distribution is:

  • .cursor/ - the framework tree. Cursor reads only a few subdirs as native meaning: rules/ (always-applied onboarding, one standing and four phase method pointers), agents/ (the 14 personas as native subagents), skills/ (the orchestrator, utility shortcuts, and generated stage runners), hooks.json + hooks/ (the hook wiring and adapter), cli.json (permissions), and mcp.json (MCP servers, if you add one). The engine dirs beside them (tools/, aidlc-common/, knowledge/, sensors/, scopes/) are inert data to Cursor and safely share the directory.
  • aidlc/ - the workspace shell (the pre-built aidlc/spaces/default/memory/ method tree the engine reads), a sibling of .cursor/.
  • AGENTS.md - project-root ambient instructions Cursor auto-reads.

Prerequisites

  • Cursor - the IDE, or the Cursor CLI (install with curl https://cursor.com/install -fsS | bash; invoked as agent). Both read this install's .cursor/ surfaces. Verified against cursor-agent 2026.07; hooks (.cursor/hooks.json) and skills (.cursor/skills/) are current-line features.
  • bun only for source development or the optional manual-copy install.ts helper. Once installed, native and versioned release runtimes invoke aidlc.
  • A paid Cursor plan for named models - Free accounts can only use Auto. The tiered persona surfaces ship with no model pins (all tiers project to null on Cursor: model availability is plan-dependent), so every agent inherits your session model. Headless CLI runs that pass --model need a plan that allows it. Bedrock BYOK is IDE-only: static keys on Pro, an IAM role on Teams (doc-verified against Cursor's model settings, not live-verified here); the CLI routes models through Cursor's own backend.

Install

Install the native command as described in Install and Lifecycle, then:

cd your-project
aidlc config --harness cursor
aidlc doctor

Cursor may skip project hooks in a folder that is not in a git repository, and without them your approvals are never recorded. If the project is not a git repository yet, run git init in it before opening it in Cursor (fully restart Cursor if it is already open). aidlc config, the copy installer, and /aidlc --doctor all say so when it is missing.

Versioned manual-copy alternative

Download and extract a specific release's aidlc-copy-runtime-X.Y.Z.tar.gz as described in Install and Lifecycle: Copy Channel, then install that versioned projection:

bun "$RUNTIME_ROOT/cursor/install.ts" your-project

The copy installer is single-harness: its root sections use private AIDLC CURSOR markers and it does not write an aidlc config ownership baseline. Multi-harness projects must add Cursor with aidlc config --harness cursor instead; the copy installer refuses root blocks already managed by aidlc config.

The installer preflights the full copy, refuses project-owned collisions, preserves .cursor/.gitignore and existing method memory, structurally merges .cursor/hooks.json and .cursor/cli.json, and adds marked AI-DLC sections to existing AGENTS.md and .gitignore files instead of replacing them. It records framework ownership in .cursor/aidlc-install.json; re-running it upgrades managed files while preserving aidlc/active-space and explicit plugin selection/composed state, and reapplying that space to all mutable rule and persona pointers, including files restored after deletion. Plugin-composed stage files are preserved only when a contribution sidecar or seam sentinel identifies that stage, and the installer prints every managed path it preserves; unrelated core stages continue through normal receipt-hash collision/upgrade handling. The aidlc/ shell ships the pre-built aidlc/spaces/default/memory/ method tree the engine reads; /aidlc --doctor fails its "workspace shell ready" check without it.

Open the project in the Cursor IDE (or start agent in it) and run /aidlc --doctor, then /aidlc followed by what you want to build. Native utility shortcuts are /aidlc-status, /aidlc-jump --stage <slug> (or --phase <name>), and /aidlc-scope <name>.

What's different on this harness

  • Questions render as numbered prose options (no structured-question widget); the questions FILE with [Answer]: tags remains the source of truth.
  • Hooks ride .cursor/hooks.json through the AIDLC adapter (.cursor/hooks/aidlc-cursor-adapter.ts), which maps Cursor's camelCase hook events (sessionStart, sessionEnd, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, preCompact, stop) onto the byte-shared core hook bodies (run as bun subprocesses): human-turn recording on each human turn, the state-transition, reviewer read-scope, review-freeze, and plan-approval guards before a tool runs, audit + sensors on write/edit, failed-Task attribution cleanup, stage-graph rebuilds on shell, and state validation before compaction. The PreToolUse guards answer on Cursor's {"permission":"allow"|"deny"} stdout channel (deny may add agent_message) and register failClosed: true. Empty stdout is invalid JSON, so the IDE blocks the call; malformed input also denies the operation. A guard that is missing or crashes refuses nothing, as on every other harness, and doctor names it. Cursor names its shell tool Shell; the adapter maps it to the core hooks' Bash. An edit that arrives as StrReplace with the file in path is handled as Edit, so it is recorded and checked like any other edit. Cursor's first-class Delete tool (unique to this harness - everywhere else deletion goes through the shell) is presented to the reviewer-scope guard as a write so a unit-scoped reviewer cannot delete a sibling unit's artifacts. Shell payloads' nested cwd/working_directory fields are promoted to the shared guard contract, so relative reads and writes are checked where Cursor will execute them.
  • Forwarding-loop enforcement is advisory. Cursor's stop hook cannot refuse a stop, so when the core stop hook answers block the adapter surfaces a follow-up nudge instead (the same posture as opencode). Its host loop_limit is 10 rather than Cursor's default 5, which covers the core's autonomous no-progress cap of 8. The forwarding loop in the conductor skill is the real discipline.
  • Background agents are side workers. A Cursor background agent you start while a workflow runs in the foreground chat (a review, a test run, a code change) is left out of that workflow. At session start it gets a short note, instead of the workflow context, saying the workflow belongs to the foreground chat: don't run /aidlc or AIDLC workflow commands, or edit aidlc/ or AIDLC's own files under .cursor/ (its hooks, tools, skills, agents, and aidlc rules); your own Cursor configuration, such as .cursor/mcp.json, is fine, and so are reads and bun .cursor/tools/aidlc.ts status. Its stops get no forwarding nudge, its prompts never count as a human turn, and its session end is not recorded. Nothing is blocked: the note is the only guard, so an agent that ignores it could still move the workflow, as a second session could on any harness. Cursor flags a background agent only on sessionStart, beforeSubmitPrompt, and sessionEnd, so the adapter records the flag in aidlc/.aidlc-cursor-subagents/ for the conversation's later stops and removes it at sessionEnd; if the record cannot be written, the agent runs normally and its stops get the foreground nudge.
  • A real session-end moment exists (unlike Codex): sessionEnd fires, so SESSION_ENDED audit events are emitted. Pre-compaction validation also fires (preCompact).
  • Personas are native subagents. The 14 persona .md files in .cursor/agents/ are discovered by frontmatter name; the conductor adopts them inline for most stages and delegates via the task tool for the two subagent stages (2.1 reverse-engineering, 3.5 code-generation). Worker agents do not get the task tool, so a delegate cannot delegate again.
  • Subagent identity is reconstructed. Cursor emits no per-subagent identity on hook payloads (its subagentStart/subagentStop events are documented but never fire on the CLI), so the adapter maintains a protected project-local runtime ledger under aidlc/.aidlc-cursor-subagents/ plus independent aidlc/.aidlc-cursor-subagent-*.json active-delegation witnesses. Top-level conversations register themselves at sessionStart/beforeSubmitPrompt (subagent conversations get neither event), each Task spawn records its agent, and reviewer read-scope enforcement attributes calls from conversations that are not registered top-level sessions. A parent's next synchronous Task dispatch retires and logs its prior record (Cursor CLI emits no Task postToolUse); genuine cross-parent ambiguity stays conservative whenever a reviewer is live, so it cannot disable reviewer-scope enforcement. Delegated tools cannot access the ledger or dispatch record, including through ancestor deletes or unquoted shell glob/character-class paths. If the primary ledger is missing or unreadable while any delegation witness remains active, operations fail closed rather than losing delegated-agent attribution. Delegates may use ordinary Shell commands, but general-purpose interpreters and dynamic command evaluation are denied; use Cursor's native read/search tools and let the parent conversation run executable probes. AI-DLC's own commands that a delegate is given, such as Reverse Engineering's scope fingerprint and its check, run as their instructions spell them, one plain command at a time. These delegate limits apply only while the reviewer read-scope or state-transition check holds for the piece of work: when both stand aside (Guard Policy off does that), delegates run builds, tests and searches like the main conversation, a Task starts even when its record cannot be written, and Cursor's own approval applies.
  • Generated stage and scope runners are explicit-only. Cursor receives disable-model-invocation: true on generated runner skills, including plugin runners, so ordinary coding prompts cannot auto-activate state-mutating workflow shortcuts.
  • Utility shortcuts are native skills. /aidlc-status, /aidlc-jump, and /aidlc-scope improve slash-menu discovery without creating a second engine path. They all carry disable-model-invocation: true; Cursor invokes them only when the user chooses them. The legacy .cursor/commands/ surface is not shipped.
  • Method rules are read instructions, not imports. Cursor rules do not expand @-import lines. .cursor/rules/aidlc.mdc is always applied and points to the active space's org/team/project files; four .cursor/rules/aidlc-phase-*.mdc rules are agent-decided and point to the matching phase file only when relevant (live-verified on cursor-agent: a phase-framed prompt loads exactly the matching phase rule, an unrelated prompt loads none). The sessionStart hook separately injects live workflow context. All five rule files read aidlc/active-memory/, the engine's git-ignored copy of the active space's method; /aidlc space <name> rewrites the copy, never the rules.
  • Construction swarm runs as task-tool fan-out only (AIDLC_USE_SWARM=1 is a loud no-op - no Workflow tool exists).
  • No statusline / welcome message - use /aidlc-status (or /aidlc --status) and the progress lines at gates.
  • Tab autocomplete is untouched by this install - it rides Cursor's own models regardless of configuration.
  • Permissions: .cursor/cli.json pre-approves only AI-DLC's own workflow commands: its engine commands, doctor, version, status (and their --doctor, --version and --status spellings, and doctor with --verbose), config --help, config --show and the read-only config <section> --show (with or without --json) and --help forms, turning a check back on (config flags --clear-bypass <switch> --yes), and its aidlc-*.ts tools (a project-level cli.json carries permissions only). A native install pre-approves the same commands run as the installed aidlc command, and aidlc engine .... Every other shell command follows your Cursor approval settings, including any other config change (turning a check off too), the commands that change the machine's AI-DLC install (use, update, rollback, uninstall, system), and the tool scripts behind them.
  • MCP servers: none ship; configure your own under .cursor/mcp.json if needed.
  • Headless agent -p runs cannot pass approval gates. The human-presence mint rides beforeSubmitPrompt, which Cursor fires only for an interactive submission (verified against cursor-agent 2026.07) - so a print-mode run records no HUMAN_TURN and a gated stage refuses its approval by design, rather than letting an unattended model approve its own work. Use headless mode for the read-only utilities (--status, --doctor, --version) and for autonomous Construction (which is exempt because it has no human at the gate); run gated workflows in an interactive Cursor session. This is a property of the framework's presence gate, not a Cursor limitation - every harness mints presence from a human-prompt event.
  • In-session configuration is interactive. Use /aidlc --config [section] in a Cursor chat so the conductor can gather choices before landing exact deterministic config flags.

Verifying an install

bun .cursor/tools/aidlc-utility.ts doctor        # all checks pass on a fresh copy in a git repository
agent -p "/aidlc --status" --output-format text --trust   # /aidlc --status through the CLI

The doctor's Cursor-specific checks: the hook wiring at .cursor/hooks.json, the permission pre-approval for AI-DLC's commands at .cursor/cli.json, the standing rule at .cursor/rules/aidlc.mdc, all four phase-rule pointers, and whether the project is in a git repository.

Scripting trap: Cursor CLI always exits 0. Headless agent -p "<prompt>" --output-format text --trust returns exit code 0 even when the run errors, so a CI check must assert on the emitted text, never on the exit status. Named models (--model) need a paid plan; without one, use Auto.

Next steps

Installed and verified? The methodology is the same on every harness - keep going with the neutral chapters:

Other harnesses: AI-DLC on opencode · the harness family index.