<div align="center">
<img src="assets/logo.svg" width="96" height="96" alt="CursorQB logo">
# CursorQB
**A Cursor-native planning and implementation control plane.**
Plan deeply. Gate explicitly. Ship one independently reviewed slice at a time.
<br>
[](CHANGELOG.md)
[](https://github.com/alicankiraz1/CursorQB/actions/workflows/validate.yml)
[](#requirements)
[](LICENSE)
[](https://cursor.com)
[](#commands)
[Quick start](#quick-start) ·
[How it works](#how-it-works) ·
[Commands](#commands) ·
[Trust model](#trust-model) ·
[Verification](#verification-and-release-gates) ·
[FAQ](#faq)
</div>
---
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`.
> [!IMPORTANT]
> **Release posture:** `0.8.0` contains the repository, package, Plan-Run, and Apply contracts. `1.0.0` remains gated on a separately authorized active-install sync and live Cursor IDE acceptance. Until Cursor exposes verifiable agent identity/completion attestation, successful Apply runs report `EVIDENCE_COMPLETE_UNATTESTED`—never `VERIFIED`.
---
## Why CursorQB?
| | |
|---|---|
| **Plan from evidence** | Bounded repository inspection grounds the master plan, autopsy, comprehension record, and implementation contracts in observable facts. |
| **Write v3, read legacy** | New artifacts use schema v3; v0.4/v0.5 documents remain readable in compatibility mode and migrate only with explicit `--apply`. |
| **Fail closed** | Missing prerequisites, invalid schemas, P0/P1 findings, stale snapshots, unsafe paths, or exhausted budgets stop before executable work is dispatched. |
| **One writer, ordered reviews** | Apply permits one writer at a time, then runs specification, quality, optional security, and final review in order. |
| **Speaks your language** | CursorQB asks intake questions in the user's language when practical. Generated Planner-docs artifacts are English by default unless the user explicitly requests another body language. Required document headings remain English for validator stability. |
| **Traceable continuity** | Ontology, comprehension, ledger, Plan-Run, validation, patch, and review evidence keep decisions and implementation state inspectable. |
| **Deterministic Plan-Run** | Long steps bind inputs, policy, budgets, prompts, results, and repository digests in an external CursorQB trust store. |
| **Explicit-only** | Skills carry `disable-model-invocation: true`; ordinary planning requests do not activate CursorQB. |
---
## Quick start
**1. Build a sanitized package** from a clean checkout:
```bash
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:
```bash
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:
```text
/cursorqb-plan
```
Then answer the four short questions and approve each gate as you go. Ordinary planning prompts do not implicitly start CursorQB.
> [!NOTE]
> Repository development never overwrites an existing `~/.cursor/plugins/local/cursorqb` installation. Install synchronization and IDE smoke testing are separate, explicit operations.
> See [`docs/INSTALLATION.md`](docs/INSTALLATION.md) for a copy-based install and verification steps.
---
## How it works
```mermaid
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 · review & approve"}}:::gate
S2["<b>Step 2 · Phase sub-plans</b><br/><i>+ coverage index</i>"]:::step
G2{{"Gate 2 · approve the audit"}}:::gate
S3["<b>Step 3 · Quality audit</b><br/><i>READY / WARN / BLOCKED</i>"]:::step
end
subgraph BUILD["Implementation · the only code-touching step"]
direction TB
G3{{"Step-4 gate · 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;
```
| Step | Name | What happens | Your part |
|:--:|---|---|---|
| **1** | Master plan | Repo-aware intake, then a senior-architect plan written to `Main-Planing.md`. | Answer 4 questions |
| **1.5** | Autopsy + comprehension | For existing projects, a technical health report plus optional ontology and evidence-backed comprehension. | — (run / skipped) |
| **Gate 1** | Review | Review the plan (and autopsy) together. | Feedback + approve |
| **2** | Sub-plans | Every phase becomes detailed sub-plans plus an index and v3 state ledger. | — |
| **Gate 2** | Approve audit | Confirm you want the quality audit. | Approve |
| **3** | Audit | Coverage/quality audit with `READY`, `READY_WITH_WARNINGS`, `NO_ACTION_REQUIRED`, or `BLOCKED`. | Approve repairs if needed |
| **4** | Implement | One READY contract by default; `--continuous` is explicit; ordered independent reviews follow validation. | Approve (gated) |
---
## What you'll get
Every project-planning artifact lands under `Planner-docs/` in **your** workspace—never in the plugin folder:
```text
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
```
---
## Commands
| Command | What it does |
|---|---|
| `/cursorqb-plan` | Run the full five-step workflow from the start. |
| `/cursorqb-autopsy` | Analyze an existing repository only (Step 1.5). |
| `/cursorqb-audit` | Re-run the quality audit only (Step 3). |
| `/cursorqb-implement` | Implement the next single `READY` / `READY_WITH_WARNINGS` contract. |
| `/cursorqb-implement --slice <contract-id>` | Select exactly one ready contract. |
| `/cursorqb-implement --continuous` | Process the ordered queue until it is empty or a stop gate fires. |
---
## Runtime contracts
CursorQB separates human-readable plans from controller-owned execution evidence:
| Contract | What is bound |
|---|---|
| **Artifact schema v3** | Artifact kind, CursorQB version, handoff version, source digest, traceability, and machine-readable implementation contracts. |
| **Plan-Run** | Immutable input snapshot, repository evidence, compiler/template version, policy digest, selected contract, budgets, prompt digest, and result. |
| **Apply** | Immutable brief, one writer, patch evidence, bounded validation, fixer cycles, ordered reviewer receipts, HMAC integrity, and live repository digest. |
| **Validation envelope** | Closed `argv` array, repo-bound `cwd`, expected exit code, timeout, network declaration, and probe tier—never an opaque shell string. |
Controller state is kept outside the target repository:
```text
~/.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:
```text
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.
---
## Trust model
| Surface | Authority and boundary |
|---|---|
| **Invocation** | All five skills are explicit-only. Use a CursorQB command or name the skill directly. |
| **Steps 1–3** | May write only beneath `Planner-docs/`; source, configuration, dependencies, Git, deployment, and external systems stay untouched. |
| **Step 4** | May edit only contract-allowed paths after readiness and user-approval gates; exactly one writer is active. |
| **Repository I/O** | Rejects traversal, symlinks, hardlinks, unsafe permissions, oversized artifacts, stale CAS preconditions, and repo-external paths. |
| **Probes** | Tier 0 is static; Tier 1 is bounded/read-only; state-changing Tier 2 and live/external Tier 3 require explicit approval. |
| **Evidence** | Controller receipts are HMAC-bound with a mode-`0600` key outside the repository; sensitive reports use categories, counts, and hashes instead of values. |
| **Host claims** | Bundle integrity is not host attestation. Without a verifiable Cursor primitive, completion remains `EVIDENCE_COMPLETE_UNATTESTED`. |
> [!WARNING]
> CursorQB does not commit, push, open pull requests, deploy, install dependencies, or mutate external systems unless the user separately and explicitly authorizes that operation.
---
## Requirements
- **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.
---
## Verification and release gates
CursorQB proves three different surfaces instead of treating a passing checkout as a complete release:
| Proof surface | Command | Purpose |
|---|---|---|
| **Repository** | `make check` | Static contracts, unit/behavior tests, schema, and privacy checks. |
| **Gitless package** | `make check-package` | Deterministic sanitized export and extracted-package validation without `.git`. |
| **Active Cursor install** | `make check-installed` | Read-only version, file-set, and digest parity against the installed plugin copy. |
```bash
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:
```bash
make check-live-acceptance EVIDENCE=/absolute/path/to/receipt.json
```
See [`docs/LIVE_ACCEPTANCE.md`](docs/LIVE_ACCEPTANCE.md) for the required IDE observations.
---
## FAQ
<details>
<summary><strong>Will it change my code?</strong></summary>
Not during planning. Only Step 4 touches code, and only with your explicit approval — one bounded, reversible slice at a time.
</details>
<details>
<summary><strong>What if my repo is brand new or empty?</strong></summary>
The autopsy is skipped automatically — you still get a full master plan and sub-plans.
</details>
<details>
<summary><strong>What language is the output in?</strong></summary>
Questions follow your language. Planning artifacts are English by default unless you explicitly request another body language. Required headings stay English for validator stability.
</details>
<details>
<summary><strong>Why the names <code>Faz</code> and <code>Planing</code>?</strong></summary>
They are intentional, stable file/folder identifiers that the validator and index references depend on. The document *content* is English.
</details>
<details>
<summary><strong>Do I need an API key or a terminal tool?</strong></summary>
No provider API key is required. CursorQB runs inside Cursor; `python3` is required for the fail-closed controller and validation gates.
</details>
Further reading: [`docs/INSTALLATION.md`](docs/INSTALLATION.md) ·
[`docs/USAGE.md`](docs/USAGE.md) ·
[`docs/MAINTAINING.md`](docs/MAINTAINING.md) ·
[`CHANGELOG.md`](CHANGELOG.md)
---
<div align="center">
**[MIT](LICENSE)** © Alican Kiraz
</div>