CursorQB

A Cursor-native planning and implementation control plane.

Plan deeply. Gate explicitly. Ship one independently reviewed slice at a time.

Quick start · How it works · Commands · Trust model · Verification · FAQ

CursorQB is an explicit-only Cursor plugin for turning an idea or an existing repository into implementation-ready contracts. It combines a guided, vibecoding-first workflow with deterministic run artifacts, fail-closed readiness gates, repository-safe I/O, and ordered independent reviews.

You answer a few short questions in your own language, and CursorQB:

1. Inspects your repository,
2. writes a senior-architect master plan,
3. breaks it into detailed phase sub-plans,
4. audits them for quality and coverage,
5. and — only if you approve — implements one reviewed slice.

It pauses for explicit approval at every gate. No provider API key is required; the bundled safety controller requires python3.

1. Build a sanitized package from a clean checkout:

make export-sanitized

2. Install by copy — extract the archive, then copy that extracted release into Cursor's local plugins folder. Do not install a dirty checkout or symlink the plugin root:

cp -R "/absolute/path/to/CursorQB" ~/.cursor/plugins/local/cursorqb

3. Reload Cursor — Cmd/Ctrl + Shift + P → Developer: Reload Window.

4. Start explicitly — open the chat in your project and run:

/cursorqb-plan

Then answer the four short questions and approve each gate as you go. Ordinary planning prompts do not implicitly start CursorQB.

See docs/INSTALLATION.md for a copy-based install and verification steps.

flowchart TD
    Start(["/cursorqb-plan"]):::start

    subgraph PLAN["Planning  ·  writes only inside Planner-docs/"]
        direction TB
        S1["<b>Step 1 · Master plan</b><br/><i>you answer 4 questions</i>"]:::step
        S15["<b>Step 1.5 · Repo autopsy</b><br/><i>existing projects only</i>"]:::step
        G1{{"Gate 1 &nbsp;·&nbsp; review &amp; approve"}}:::gate
        S2["<b>Step 2 · Phase sub-plans</b><br/><i>+ coverage index</i>"]:::step
        G2{{"Gate 2 &nbsp;·&nbsp; approve the audit"}}:::gate
        S3["<b>Step 3 · Quality audit</b><br/><i>READY / WARN / BLOCKED</i>"]:::step
    end

    subgraph BUILD["Implementation &nbsp;·&nbsp; the only code-touching step"]
        direction TB
        G3{{"Step-4 gate &nbsp;·&nbsp; clean audit, no blockers"}}:::gate
        S4["<b>Step 4 · Implement one slice</b><br/><i>optional · reversible · you approve</i>"]:::build
    end

    Start --> S1 --> S15 --> G1 --> S2 --> G2 --> S3 --> G3 --> S4

    classDef start fill:#2563EB,stroke:#1E40AF,color:#FFFFFF;
    classDef step fill:#1E293B,stroke:#38BDF8,color:#E2E8F0;
    classDef gate fill:#0F172A,stroke:#FACC15,color:#FACC15;
    classDef build fill:#064E3B,stroke:#34D399,color:#D1FAE5;
    style PLAN fill:#0B1220,stroke:#334155,color:#94A3B8;
    style BUILD fill:#0B1220,stroke:#334155,color:#94A3B8;

Every project-planning artifact lands under Planner-docs/ in your workspace—never in the plugin folder:

Planner-docs/
├── Main-Planing.md         # the master plan                          (Step 1)
├── Autopsy.md              # repo health report for existing projects (Step 1.5)
├── Project-Ontology.md     # optional vocabulary, boundaries, invariants
├── Project-Comprehension.md # optional questions, hypotheses, evidence, traceability
├── Planing-Ledger.md       # v3 planning, implementation, validation, review state
├── Sub-Planing-Index.md    # map of every sub-plan + coverage check   (Step 2)
├── Sub-Planing-Audit.md    # quality/coverage audit + readiness       (Step 3)
└── Faz-1-Plans/            # detailed sub-plans, one folder per phase
    ├── Faz1.1-...md
    └── Faz1.2-...md

CursorQB separates human-readable plans from controller-owned execution evidence:

Controller state is kept outside the target repository:

~/.cursor/cursorqb-trust/controller-state-v1/<repo-id>/
├── Plan-Run.json
├── Plan-Prompt.md
├── Plan-Result.json
└── apply-runs/<run-id>/...

Apply progresses through a monotonic state machine:

CREATED → PREFLIGHT_READY → DISPATCHED → IMPLEMENTED → VALIDATED
        → SPEC_REVIEWED → QUALITY_REVIEWED → SECURITY_REVIEWED?
        → FINAL_REVIEWED → COMPLETE

Any stage may terminate as BLOCKED or FAILED. Interrupted runs resume only when the live repository digest still matches; otherwise a new preflight is required.

• Cursor with plugin support.
• python3 — required for strict validation, deterministic Plan-Run, repository-safe writes, Apply receipts, and release checks.

CI exercises Python 3.12–3.14 on Ubuntu and macOS. The dependency-matched Python 3.12 JSON Schema lane is authoritative for the pinned Cursor manifest schema.

CursorQB proves three different surfaces instead of treating a passing checkout as a complete release:

make check-fast            # manifest, syntax, and static contracts
make check-unit            # complete unit suite
make check-behavior        # Plan-Run and Apply state-machine behavior
make check-schema          # pinned official Cursor manifest schema
make check-public-privacy  # value-redacting public-surface scan
make check-release         # all repository/package gates + clean-tree export

make check-release intentionally requires a clean worktree. 1.0.0 additionally requires a live Cursor receipt validated with:

make check-live-acceptance EVIDENCE=/absolute/path/to/receipt.json

See docs/LIVE_ACCEPTANCE.md for the required IDE observations.

Further reading: docs/INSTALLATION.md · docs/USAGE.md · docs/MAINTAINING.md · CHANGELOG.md