cursorqb-planner

name	cursorqb-planner
description	Use when the user runs /cursorqb-plan or asks CursorQB to plan a project end to end with repo-aware intake, autopsy, ontology, ledger memory, audit, and gated implementation.
disable-model-invocation	true

CursorQB Planner

Drive the CursorQB five-step planning workflow inside the current Cursor workspace.

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:

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.