Cursor rules — quickstart (Forge + Versonas)

Full reference: Forge `forge.config.yaml` ↔ `.cursor/rules/` alignment · Implementation: versona_cursor_rules.py

Guide · Updated 2026-07-22 · Source

From the consuming repository root (with blueprints/ and forge/forge.config.yaml):

After submodule update or a new machine

Install YAML-driven Versonas plus the recommended bundle (standard Forge rules, routing, project setup, roadmap gate, cursor-rules-sync playbook):

bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh sync --preset recommended

Use --force only after you have reviewed local edits (it overwrites existing .mdc files).

Check what would change

bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh status --preset recommended

Exit code 1 if something is missing or differs from blueprints templates — same idea as diff, but one line per file.

Submodule bump: diff then sync

bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh diff --preset recommended
bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh sync --preset recommended --force

After Blueprints bump: coding rules and footprint scan

The code-footprint rule is opt-in so existing --preset recommended checks do not change unexpectedly. To check for the optional coding/style rule and scan large source files:

bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh status --preset recommended --with-code-footprint-rules
bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh diff --preset recommended --with-code-footprint-rules
python3 blueprints/sdlc/methodologies/forge/setup/code_footprint_scan.py .

Default scan profile is tight (reports risky and poor — files above the tight target). Use --profile comfortable to also list files in the tight band. Bands: comfortable → tight (default target) → risky → poor; see Code analyzability and file footprint in agentic-coding-standards.md.

Propagate this rule to sibling repos (from blueprints/):

bash sdlc/methodologies/forge/setup/propagate-code-footprint-rules.sh /path/to/workspace

Review diff / status before using --force. The footprint scanner is readonly; it excludes generated website/tutorial/CDN output and reports split candidates for normal repo planning.

Automated PDCA campaigns (worktree + Cursor CLI agent + PR): see Code-footprint compliance campaigns (Forge setup) and run workbench/code-compliance/run-code-compliance-pdca.sh from the multi-repo hub.

Opt-in: cost-aware planning + triage rules

Two rules make planning detailed and cost-aware without re-typing instructions each time. They are opt-in (not in any preset) so existing --preset recommended checks stay stable:

forge-triage.mdc (lean, always-apply) — emits a one-line t-shirt size (XS-XL) per request and gates expensive orchestration on size.
forge-planning-standards.mdc — full plan structure (phases, tests, dual wiki, PDCA remediation loops, drift gate) plus the t-shirt rubric and model-tiering table.

bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh status --preset recommended --with-cost-tiering-rules
bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh sync --preset recommended --with-cost-tiering-rules

Companion grunt subagent (cheap composer-2.5 tier) and plan-detailed / triage commands are copied manually (like Skills) from sdlc/templates/forge/cursor-agents/ and sdlc/templates/forge/cursor-commands/ into .cursor/agents/ and .cursor/commands/. Rationale and the full pattern: Cost-aware planning and model tiering.

YAML-only install (CI / backward compatible)

Omitting --preset keeps the old behavior: only versona-*.mdc files implied by forge.config.yaml (no standard Forge five, no optional workflow bundle).

bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh sync

Quick audit: config vs disk

bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh check

Requires Python 3 and PyYAML (pip install pyyaml).

Presets (summary)

Preset	What you get
(none) / `minimal`	YAML-driven Versonas only
`recommended`	minimal + standard Forge rules (`forge-daily`, `forge-planning`, `forge-versona`, `forge-setup`, `forge-product-manager`, `branch-steward`) + `versona-all`, `versona-project-setup`, `versona-roadmap-gate`, `versona-forge-sdlc`, `versona-cursor-rules-sync`, `versona-sampling`
`full`	recommended + three family aggregators + `versona-generic`

Extra --with-* flags add on top of a preset. See Reference: granular flags in Forge `forge.config.yaml` ↔ `.cursor/rules/` alignment.

Manifest after sync

Each successful sync (install) writes .forge/cursor-rules-manifest.json at the repository root (unless --no-write-manifest): UTC timestamp, blueprints_commit when blueprints/ is a git checkout, active preset, and per-rule source_sha256 / installed_sha256 for the install job list. Use it to see whether installed files still match templates after local edits or a submodule bump.

Optional: … sync --preset recommended --write-adoption-manifest also writes .forge/versona-adoption-manifest.json — pointers for Skills, tasklets, and recipes (not a SHA ledger). See Forge `forge.config.yaml` ↔ `.cursor/rules/` alignment § Manifest split.

Migration / verification: Migration: discipline-first Cursor rules → process-first Versona model · Verification — process-first Versona install (local / manual primary)

Software delivery