cursorqb-planner

# CursorQB Planner Drive the CursorQB five-step planning workflow inside the current Cursor workspace. ```text Step 1 repo-aware intake -> First-Planner -> Main-Planing.md Step 1.5 cursorqb-autopsy -> Autopsy.md and optional Project-Ontology.md Step 2 cursorqb-subplanner -> Faz-*-Plans/ + Sub-Planing-Index.md Step 3 cursorqb-auditor -> Sub-Planing-Audit.md Step 4 cursorqb-implementer -> gated implementation slices ``` ## Required References Before long runs, read: - `references/workflow-quality.md` - `references/repo-aware-intake.md` - `references/vibecoding-principles.md` - `references/assessment-and-budget.md` - `references/engineering-principles.md` For existing projects, also read: - `references/planning-ledger.md` - `references/project-ontology.md` - `references/subagent-playbook.md` when subagents would reduce context or improve evidence quality Resolve the plugin root by walking up to `.cursor-plugin/plugin.json`. Invoke the bundled validator only through the fixed launcher: ```bash python3 -I -S -B <plugin-root>/scripts/cursorqb_launcher.py --controller planner-validator -- --root . --mode <step> [--strict] ``` ## Language Contract 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. ## Plan-Run Contract CursorQB uses Cursor Plan Mode plus the bundled deterministic Plan-Run controller. It is explicit-only and never unattended by default. Long Step 1.5, Step 2, Step 3, and Step 4 runs bind their inputs, policy, budget, and result to `Plan-Run.json`; do not depend on an external goal skill or use Codex-only invocation wording. ## Vibecoding, Memory, Ontology, and Subagents CursorQB uses a vibecoding-first planning style: understand the repo, preserve a clear target, plan the next useful verified moves, and keep implementation slices small, reversible, and evidence-backed. Vibecoding does not relax safety, validation, secret, approval, or file-boundary rules. If `Planner-docs/Planing-Ledger.md` or `Planner-docs/Project-Ontology.md` exists, read it before intake and use it as supporting history, not as unquestioned truth. Use subagents only when they reduce context pollution or improve evidence quality: large repo exploration, Step 1.5 Autopsy, ontology mapping, multi-phase Step 2 drafting, Step 3 readiness/security audit, or Step 4 implementation/review separation. Parent CursorQB owns final artifact writes. ## Step 1 Intake Read `references/repo-aware-intake.md`. Before asking `PROJECT_NAME`, run a bounded, read-only repository scan. Ask these fields one at a time in the user's language: 1. `PROJECT_NAME` 2. `PROJECT_INTENT` 3. `TARGET_END_STATE` 4. `KNOWN_CONSTRAINTS` The fourth answer should capture team, infrastructure, budget, timeline, stack, compliance boundaries, must-use/must-not-use tools, desired autonomy level, human review cadence, and any token/usage budget. After all four values are available: 1. Read `planners/first-planner.md`. 2. Substitute the collected values in memory only. 3. Create or update only `Planner-docs/Main-Planing.md`. 4. Run `--mode step1 --strict`. 5. Decide whether Step 1.5 applies. ## Step 1.5 Autopsy Run for existing or partially built projects with meaningful evidence such as README, manifests, source/service/package directories, tests, docs, configs, or CI. Skip for new or nearly empty repos. When it applies, use `cursorqb-autopsy`. It may create/update `Planner-docs/Autopsy.md`; when enough evidence exists, it may also create/update `Planner-docs/Project-Ontology.md`. It must not modify source files, `Planner-docs/Main-Planing.md`, or Step 2/3 files. ## Step 2 Handoff After Step 1 feedback is handled, ask whether the user wants to continue to Step 2. If yes, read and return the exact canonical handoff in `references/handoffs/run-step2.md`. When executing directly, read `skills/cursorqb-subplanner/second-planner.md`, `references/workflow-quality.md`, and optional `Autopsy.md`, `Project-Ontology.md`, and `Planing-Ledger.md` when present. Run `--mode step2 --strict`. ## Step 3 Handoff After Step 2 is complete, ask whether the user wants to continue to Step 3. If yes, read and return the exact canonical handoff in `references/handoffs/run-step3.md`. When executing directly, read `skills/cursorqb-auditor/third-planner.md`, run `--mode step3-preflight --strict` before the audit, and run `--mode step3 --strict` after writing it. ## Step 4 Handoff Step 4 is implementation work and must not run automatically from the planner. When Step 3 completes: 1. Read `skills/cursorqb-implementer/fourth-planner.md`. 2. Run `--mode step4`. 3. If validation fails because the audit is `BLOCKED` or contains P0/P1 findings, do not print the implementation prompt; print the minimal repair/unblock prompt. 4. If validation passes, print the Step 4 copy block and keep P2/P3 warnings visible. The Step 4 prompt comes from `references/handoffs/run-step4.md`. With no argument it executes exactly one READY/READY_WITH_WARNINGS slice; `--slice <contract-id>` selects one contract and `--continuous` is the only way to continue through the queue. It updates `Planner-docs/Planing-Ledger.md` after each verified slice or stop event and uses one writer per run. ## Safety Rules - Treat the current working directory as the project being planned. - Do not implement product features, refactor source code, install dependencies, commit, push, deploy, or open PRs during Steps 1-3. - Do not write secrets, tokens, credentials, private keys, or local sensitive environment values into planning files. - Preserve the required filenames exactly: `Main-Planing.md`, `Sub-Planing-Index.md`, `Sub-Planing-Audit.md`, `Autopsy.md`, `Project-Ontology.md`, and `Planing-Ledger.md`. ## Completion Reporting For each executed step, report which step ran, files created/updated, whether it succeeded or was blocked, the highest-priority next action, and any uncertainty or blocker discovered.