Handbook
Forge `forge.config.yaml` ↔ `.cursor/rules/` alignment
Quickstart (one screen): Cursor rules — quickstart (Forge + Versonas)
Forge forge.config.yaml ↔ .cursor/rules/ alignment
Quickstart (one screen): Cursor rules — quickstart (Forge + Versonas)
forge/forge.config.yaml declares which Versona families and sub-disciplines are active, but Cursor does not read that file automatically. After you change YAML, ensure matching .mdc rules exist (copied from blueprints/sdlc/methodologies/forge/versona/ — versona-generic.mdc.template at the versona/ root; all other templates under catalog/ in discipline/<domain>/, discipline/<domain>/family/ for aggregators, plus catalog/routing/, catalog/meta/, catalog/workflow/; drop the .template suffix). Optional: root versona-generic.mdc.template (Layer 0 baseline only) is not driven by YAML—install if you want an explicit @ companion to discipline rules. See versona/catalog/ANCESTRY.md and versona/catalog/TEMPLATE-INDEX.md for paths and the kind/domain map.
Single entry: sync-forge-cursor-rules.sh
Single source of truth: versona_cursor_rules.py maps forge.config.yaml → template paths (shared with check).
From repository root (with blueprints/ submodule and forge/forge.config.yaml):
| Subcommand | Maps to | Typical use |
|---|---|---|
sync |
install |
Copy templates into .cursor/rules/ |
diff |
diff |
SHA256 compare installed files vs blueprints |
status |
status |
Per-file missing / drift / ok (exit 1 if bad) |
check |
check |
YAML-expected Versona files exist (CI / quick audit) |
Recommended for humans:
bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh sync --preset recommended
Backward compatible (YAML-driven Versonas only, no preset bundle):
bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh sync
Thin wrappers still work: install-versona-cursor-rules.sh → sync sync, diff-versona-cursor-rules.sh → sync diff, check-forge-cursor-alignment.sh → sync check.
Presets
| Preset | Effect |
|---|---|
(omit) / --preset minimal |
Copy only versona-*.mdc implied by forge.config.yaml (same as pre-preset behavior) |
--preset recommended |
Minimal + standard Forge five (forge-daily, forge-planning, forge-versona, forge-setup, forge-product-manager) + versona-all, versona-project-setup, versona-roadmap-gate, versona-forge-sdlc (methodology orchestrator), versona-cursor-rules-sync, versona-sampling (meta-Versona aligned with tasklets; idempotent with install-tasklets.sh) |
--preset full |
Recommended + family aggregators (versona-family-*) + versona-generic |
Additive: --with-* flags on sync / diff / status add on top of the chosen preset.
After git submodule update on blueprints/, re-run sync (use --force only after reviewing local globs/edits and diff / status).
Repo-level agent instructions (AGENTS.md) and enriched Versona layout
Cursor rules (installed .mdc files) carry Versona identity and invocation behavior. AGENTS.md at the repository root (if present) is a sensible place for repo-wide defaults that rules should not duplicate: e.g. whether forge-logs/versona-track/ is enabled, gitignore policy for transcripts, and compliance overrides that supersede methodology. Skills hold short repeatable workflows; subagents run narrow tasks with a fixed output shape. Recipes under agents/recipes/ own execution-plane steps. See Versona operating model — process-first layout, artifacts, and tooling split §3.
Team Rules, registries, and standards precedence
Cursor Team Rules (org/enterprise) are the preferred surface for L1–L2 controls that must always apply: link to policy portals or GRC IDs instead of pasting full standard text. Pair with a consuming-repo forge/standards-registry.yaml (JSON Schema: ../standards/schemas/standards-registry.schema.json) so Versonas can cite control_id values in §5.1 traceability. Precedence order (external → org → repo → Forge → discipline → heuristics): Standards precedence — which controls win. Per-Versona standards profiles: Versona standards matrix.
status and diff
bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh status --preset recommended
bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh diff --preset recommended
Pass the same --preset and --with-* flags as for sync so the job list matches. Exit code 1 when something is missing or differs.
Quick check (YAML expectations only)
bash blueprints/sdlc/methodologies/forge/setup/sync-forge-cursor-rules.sh check
Requires Python 3 and PyYAML (pip install pyyaml). If PyYAML is missing, use the tables below manually.
Manifest (.forge/cursor-rules-manifest.json)
After each successful sync (non–dry-run install), the tool writes .forge/cursor-rules-manifest.json at the repository root unless you pass --no-write-manifest. It records a UTC generated_at, optional blueprints_commit (git rev-parse HEAD in the resolved blueprints/ root when it is a git work tree), the preset used (if any), and for each file in the install job list: name, label, source_sha256, installed_sha256. Compare source vs installed to spot drift; compare blueprints_commit across machines to confirm submodule alignment.
Manifest split: Cursor rules vs adoption hints (process-first)
Do not overload cursor-rules-manifest.json with Skills, tasklets, or recipe paths. That file is a per-rule SHA ledger for .cursor/rules/*.mdc (and standard Forge rules) only—stable for CI and drift checks.
Companion file (opt-in): pass --write-adoption-manifest on sync to also write .forge/versona-adoption-manifest.json. It holds schema_version, generated_at, blueprints_commit, preset_used, a pointer to cursor-rules-manifest, and static paths for copying Skills (sdlc/templates/forge/cursor-skills/), running tasklets/install-tasklets.sh, and recipes (agents/ORCHESTRATION.md). It is not a second SHA manifest and is safe to omit in minimal pipelines. See Verification — process-first Versona install (local / manual primary) for an end-to-end check that uses status / diff / check plus optional adoption steps.
Reference: granular flags (sync / install)
Use these with sync-forge-cursor-rules.sh sync (or install-versona-cursor-rules.sh, which delegates to sync).
| Flag | Effect |
|---|---|
| (default) | Copy missing versona-*.mdc only when no preset bundle applies (does not overwrite local edits) |
--preset minimal, recommended, or full |
See Presets above |
--force |
Overwrite existing files |
--dry-run |
Print source → dest |
--no-write-manifest |
Skip writing .forge/cursor-rules-manifest.json |
--write-adoption-manifest |
Also write .forge/versona-adoption-manifest.json (Skills / tasklets / recipes pointers only; see Manifest split) |
--with-project-setup |
Also versona-project-setup.mdc |
--with-roadmap-gate |
Also versona-roadmap-gate.mdc |
--with-forge-sdlc |
Also versona-forge-sdlc.mdc (Forge SDLC A–F orchestration; included in recommended / full) |
--with-all-routing |
Also versona-all.mdc |
--with-cursor-rules-sync |
Also versona-cursor-rules-sync.mdc |
--with-family-product / --with-family-engineering / --with-family-data |
Family aggregators |
--with-sampling |
Also versona-sampling.mdc (included in recommended / full; still useful if you use minimal + tasklets only) |
--with-generic |
Also versona-generic.mdc |
--with-standard-forge-rules |
Also forge-daily, forge-planning, forge-versona, forge-setup, forge-product-manager from sdlc/templates/forge/cursor-rules/ |
Family → template sources
versona.families.* |
When true, install from versona/ (see source path in Versona template index (source paths)) |
|---|---|
engineering |
Each engineering_disciplines.* that is true → matching versona-*.mdc under versona/catalog/discipline/engineering/ (see sub-table). Optional: catalog/discipline/engineering/family/versona-family-engineering.mdc.template for aggregator. |
data |
catalog/discipline/data/versona-bigdata.mdc.template, catalog/discipline/data/versona-datascience.mdc.template (or catalog/discipline/data/family/versona-family-data.mdc.template). |
product |
Each product_disciplines.* that is true → matching versona-*.mdc under versona/catalog/discipline/product/. Optional: catalog/discipline/product/family/versona-family-product.mdc.template. |
governance |
catalog/discipline/governance/versona-pm.mdc.template |
versona.cross_cutting.* |
Template (source) |
|---|---|
security |
catalog/discipline/cross-cutting/versona-security.mdc.template |
compliance |
catalog/discipline/cross-cutting/versona-compliance.mdc.template |
Engineering sub-disciplines → filenames
| YAML key | Installed rule (example) |
|---|---|
software_engineering |
versona-se.mdc |
software_architecture |
versona-architecture.mdc |
devops |
versona-devops.mdc |
testing |
versona-testing.mdc |
frontend |
versona-frontend.mdc |
mobile |
versona-mobile.mdc |
embedded_iot |
versona-iot.mdc |
Product sub-disciplines → filenames
| YAML key | Installed rule (example) |
|---|---|
product_management |
versona-product-management.mdc |
business_analysis |
versona-ba.mdc |
ux_design |
versona-ux.mdc |
marketing |
versona-marketing.mdc |
customer_success |
versona-cs.mdc |
Standard Forge Cursor rules (not driven by versona)
Usually copied from blueprints/sdlc/templates/forge/cursor-rules/ (included in --preset recommended and above, or --with-standard-forge-rules):
| File | Purpose |
|---|---|
forge-daily.mdc |
Charge, hats, Ember Log, journal |
forge-planning.mdc |
Ore, Product Sparks, planning |
forge-versona.mdc |
Master routing |
forge-setup.mdc |
First-time setup (optional after onboarding) |
forge-product-manager.mdc |
Product orchestration (optional; product-led teams) |
Tasklets (optional)
Run blueprints/sdlc/methodologies/forge/tasklets/install-tasklets.sh for cognition tasklets (forge-tasklet-*.mdc) — not controlled by forge.config.yaml today. versona-sampling.mdc is installed by --preset recommended (and full); the tasklet installer remains the way to add the tasklet rules themselves.
Optional Versonas (not driven by forge.config.yaml)
These templates are not mapped from versona.* YAML flags today. Use --preset recommended / full or individual --with-* flags to install into .cursor/rules/:
| Template (source) | Installed rule (example) | Purpose |
|---|---|---|
catalog/meta/versona-sampling.mdc.template |
versona-sampling.mdc |
Meta-Versona for tasklet-style flows; recommended / full preset, or install-tasklets.sh + minimal if you prefer YAML-only Versonas first |
catalog/workflow/versona-project-setup.mdc.template |
versona-project-setup.mdc |
Repo bootstrap checklist and gap analysis; trigger setup or @versona-project-setup |
catalog/workflow/versona-roadmap-gate.mdc.template |
versona-roadmap-gate.mdc |
Roadmap quality gate playbook |
catalog/workflow/versona-forge-sdlc.mdc.template |
versona-forge-sdlc.mdc |
Forge SDLC methodology orchestrator (A–F phase plans, merge owners, trace); see Forge SDLC orchestration |
catalog/workflow/versona-cursor-rules-sync.mdc.template |
versona-cursor-rules-sync.mdc |
Chat playbook: commands to install/diff Cursor Versona rules |