forge-lcdl

Handbook

Cursor integration (Sprint 8)

Use this when working in forge-lcdl from Cursor so the agent follows the LCDL loop: contract → context pack → patch unit → verification → repair → proof report.

MCP: two directions

Direction Use case Doc
Client Your Python script calls Playwright MCP (or another server): McpHub, PlaywrightAdapter, snapshots MCP-CLIENT.md
Sidecar Cursor calls LCDL as MCP tools (lcdl.verify, …) MCP-SIDECAR.md + .cursor/mcp.json.example

Copy the example MCP JSON into your user or project MCP config (adjust cwd / PYTHONPATH for your machine).

Open the right folder

Open the forge-lcdl repository root (the directory that contains pyproject.toml and src/forge_lcdl/). For multi-root workspaces, include this repo so .cursor/ rules apply.

Project rules (.cursor/rules/)

Rule Scope
lcdl-core.mdc Always on — contract-first workflow, proof report, no big unverified edits; MCP client/sidecar doc pointers.
lcdl-cheap-model.mdc Always on — one patch unit, bounded context, verify after edits, escalate sparingly.
lcdl-python.mdc Python files (**/*.py) — 3.11+, pytest/compileall, no live credentials in default tests.
lcdl-mcp-client.mdc forge_lcdl/mcp_client/**/*.py — hub, adapter, policy; docs/MCP-CLIENT.md.

Older lcdl-cheap-model-operating-mode.mdc is a short pointer only (alwaysApply: false) so content is not duplicated.

Skills — invoke with /

Type / in chat and choose the skill (or use the command palette). Names match the name field in each SKILL.md.

Command Purpose
/lcdl-implement Feature work: contract → build_context_pack → create_patch_units → one unit → verify → repair → proof report.
/lcdl-debug Failures: reproduce → classify → minimal fix → re-verify.
/lcdl-refactor Safe refactor: tests or characterization first, explicit allowed paths, preserve public API unless you say otherwise.
/lcdl-benchmark Run cheap_model_baseline (offline by default) and compare JSON reports.

Skill sources: .cursor/skills/lcdl-*/SKILL.md.

Helper scripts (thin wrappers)

Script Use
.cursor/skills/lcdl-implement/scripts/run_lcdl_checks.py From repo root (or any path under the repo): runs pytest -q then python -m compileall -q src tests. Extra args pass through to pytest (e.g. tests/test_x.py).
.cursor/skills/lcdl-benchmark/scripts/run_baseline.py Runs python -m forge_lcdl.benchmarks.runner --suite cheap_model_baseline --out …. Optional --compare PREV.json prints regression summary. --live forwards to the runner (needs credentials; see docs/BENCHMARKS.md).

Example:

python3 .cursor/skills/lcdl-implement/scripts/run_lcdl_checks.py
python3 .cursor/skills/lcdl-benchmark/scripts/run_baseline.py --out reports/baseline.json

Subagents (.cursor/agents/)

Delegate from the main chat when you want isolated context or a specialized pass:

Agent Mode Use when
lcdl-verifier Read-only (readonly: true) You want a skeptical check: tests run offline, gaps called out, no file edits.
lcdl-planner Read-only You want a written plan: contract, context strategy, ordered PatchUnits — no edits.
lcdl-debugger May suggest fixes / text diffs Failures need minimal repro and concrete repair steps for the main agent to apply.

How to delegate depends on your Cursor build (subagent picker / instructions in system prompt). Name matches the name field in each .md file.

Documentation map

  1. Contracts / spec — docs/CONTRACT-SPEC.md, src/forge_lcdl/contracts/ (v2 extensions where needed)
  2. Client / execution — docs/CLIENT-API.md, docs/EXECUTION-ENGINE.md, forge_lcdl.execution
  3. RAG / inference — docs/RAG.md, forge_lcdl.retrieval, forge_lcdl.inference
  4. Prompt caching — docs/PROMPT-CACHING.md, forge_lcdl.prompts
  5. Task packs — docs/TASK-PACKS.md, FORGE_LCDL_TASK_PACKS
  6. Context packs — docs/CONTEXT-PACKS.md, forge_lcdl.context
  7. Graph — docs/GRAPH.md, forge_lcdl.graph
  8. Patch units / planner / proof — docs/CODING-EXECUTOR.md, forge_lcdl.coding
  9. Verification — docs/VERIFICATION.md (including rag.citations)
  10. Repair — docs/REPAIR-LOOPS.md
  11. Benchmarks — docs/BENCHMARKS.md
  12. MCP client — docs/MCP-CLIENT.md (Playwright MCP from Python); MCP sidecar — docs/MCP-SIDECAR.md
  13. Handbook site — sibling forge-lcdl-website: run python3 generator/build-site.py from that repo after doc changes in forge-lcdl (see workspace rule forge-lcdl-handbook.mdc).
  • Workspace proof format and default checks overlap with former lcdl-cheap-model-operating-mode.mdc content now split across lcdl-core + lcdl-cheap-model + lcdl-python.