Handbook

Cursor rules and skills

How to adopt Forge Cursor rules, skills, and the cost-aware planning + model-tiering pattern in the Forge Platform workspace. This page is adoption-focused; the canonical methodology lives in Blueprints (linked below) —…

Related in-repo pages: Cursor workflow, Cursor Kit workflow, and Governed workflows and rules (runtime workflow engine vs IDE .mdc rules — keep the distinction).

Where rules come from

Forge Cursor rules are authored in Blueprints and synced into each repo's .cursor/rules/ by the sync toolchain. From a repo root that has blueprints/ and forge/forge.config.yaml:

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

Full reference: Blueprints Cursor rules quickstart (sdlc/methodologies/forge/setup/CURSOR-RULES-QUICKSTART.md).

Cost-aware planning + model tiering (opt-in)

Two opt-in rules make plans detailed and cost-aware without re-typing instructions each turn:

forge-triage.mdc — 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 updates, PDCA remediation loops, drift gate) plus the t-shirt rubric and model-tiering table.

Install them alongside your preset:

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

This formalizes the guidance already in Cursor workflow: cheap/fast models (Composer Fast) for small bounded Sparks, stronger models for architecture, boundary, security, and execution-path changes. The t-shirt rubric turns that into an explicit per-request decision.

Model tiering in this workspace

Tier	Platform work	Model
Orchestrator (main)	architecture, product-boundary, approval-model, security-sensitive changes	high-tier or Auto
Search / read	finding schemas, workcell specs, contracts	built-in Explore (auto)
Scripts / shell	`bootstrap_forge_platform_foundation.py`, `check_foundation.py`, tests	built-in Bash (auto)
Mechanical edits	schema additions, sample-object edits, static UI wiring	cheap `grunt` subagent (`composer-2.5`)

Subagents each carry their own context window (N parallel ≈ N x tokens), so savings come from a cheap tier doing bulk-token work sequentially, not from fan-out. On legacy request-based plans a subagent's model: is ignored (runs on Composer); token-based plans honor it.

Fast-variant policy (quality-first): when the agent picks a model for a subagent or delegated task, it uses the standard variant of a tier (e.g. composer-2.5), not a speed-tier *-fast variant, unless you explicitly ask for speed. This governs agent-chosen models only; it cannot change your main-chat model picker or Auto.

Companion subagent and commands (manual copy)

Like Skills, these are copied manually from Blueprints templates:

Artifact	Blueprint template	Install into
`grunt` cheap subagent	`blueprints/sdlc/templates/forge/cursor-agents/grunt.md`	`.cursor/agents/grunt.md`
`/plan-detailed` command	`blueprints/sdlc/templates/forge/cursor-commands/plan-detailed.md`	`.cursor/commands/plan-detailed.md`
`/triage` command	`blueprints/sdlc/templates/forge/cursor-commands/triage.md`	`.cursor/commands/triage.md`

Skills

Forge Skills (repeatable short workflows) ship as Blueprints templates under blueprints/sdlc/templates/forge/cursor-skills/ and are copied manually into .cursor/skills/<name>/. The catalog of which Versona invokes which Skill is blueprints/sdlc/methodologies/forge/versona/VERSONA-SKILL-MATRIX.md.

Canonical references

Cost-aware planning + model tiering (pattern, gate, cost math, testing): Blueprints sdlc/methodologies/forge/COST-AWARE-PLANNING-AND-MODEL-TIERING.md.
Respecting resources + autonomy ladder (bounded unattended execution): Respecting resources and autonomy → Blueprints RESPECTING-RESOURCES.md and AUTONOMY-LEVELS.md.
Rules vs AGENTS.md vs Skills vs subagents vs recipes: Blueprints sdlc/methodologies/forge/VERSONA-OPERATING-MODEL.md §3.
Product planning hierarchy (Business Driver → Product Spark → iterations): Blueprints sdlc/methodologies/forge/planning/PLANNING-FLOW.md.