ClaudeQB

Vibecoding-first repo planning for Claude Code. ClaudeQB turns a project repository into a durable planning package: main plan, existing-project autopsy, optional project comprehension, project ontology, planning ledger, phase sub-plans, QA audit, and a gated implementation handoff.

ClaudeQB is a Claude Code plugin that installs the /claudeqb:claudeqb skill. It is built for software, AI, infrastructure, security, and automation projects where planning needs to be evidence-backed, reviewable, adaptive, and ready for small verified execution slices.

The current 0.2.1 release adds gate-integrity compatibility on top of evidence-backed project comprehension while keeping repository marketplace distribution hardened through dependency-free make check, GitHub Actions validation, deterministic fixture corpus checks, and tracked-file sanitized exports through make export-sanitized.

Release contracts:

plugin_version: 0.2.1
artifact_schema_version: 2
handoff_contract_version: 1

Why ClaudeQB

• Repo-aware intake: ClaudeQB inspects the current repository before asking questions, then proposes evidence-backed defaults for project name, intent, target end state, constraints, autonomy/review cadence, and token/context budget assumptions.
• Durable planning docs: Output is written under Planner-docs/ so long planning work, ontology, and implementation history survive context changes and can be reviewed like normal project documentation.
• Project Autopsy + Ontology + Comprehension: Existing projects get a focused Autopsy.md report and may get Project-Ontology.md plus Project-Comprehension.md to capture evidence confidence, CQ/TRACE/ARC links, architecture reflexion, quality scenarios, and open validation probes.
• Full phase decomposition: The main plan can be expanded into ordered phase folders and detailed sub-plan files, using Autopsy feedback when available.
• QA before implementation: The audit step checks coverage, naming, ordering, section structure, readiness, ontology consistency, planning-history continuity, security/governance, vibecoding slice quality, and implementation preparedness.
• Gated execution handoff: ClaudeQB does not implement product changes itself. It prints a separate fresh Claude Code session prompt only when the audit says implementation can begin, then guides that run through the READY queue in small verified slices and asks Step 4 to append concise implementation summaries to Planing-Ledger.md.

Vibecoding-First Behavior

ClaudeQB is intentionally vibecoding-first: it keeps the target vision clear, reads the repository's real shape, avoids fake certainty, and plans the next useful verified moves instead of freezing unnecessary implementation detail too early. Generated plans should favor small reversible slices, fast validation signals, explicit deferrals, and human-review checkpoints. Vibecoding never relaxes safety, secret handling, approval, validation, or file-boundary rules.

When a project is large or ambiguous, ClaudeQB may recommend or explicitly request bounded subagents for read-only repo exploration, readiness/security review, ontology mapping, phase drafting, Step 3 audit, or Step 4 implementation/review separation. The parent ClaudeQB agent remains responsible for final artifact writes.

Workflow

Step 1 runs in the current Claude Code thread. Steps 2, 3, and 4 are intentionally handed off as text-only fresh Claude Code session prompts so the user stays in control of long-running work. Canonical fresh-session handoffs live under references/handoffs/ and include the Fresh Session Run Contract, resume/recovery protocol, validation gates, stop gates, context budget, and subagent policy.

Quick Start

Add this repository as a Claude Code plugin marketplace:

claude plugin marketplace add alicankiraz1/ClaudeQB --scope user
claude plugin install claudeqb@claudeqb --scope user

If the repository is private, your Claude Code/GitHub environment must have access to alicankiraz1/ClaudeQB.

Start a new Claude Code thread in the project you want to plan, then ask:

Use /claudeqb:claudeqb to inspect this repo and plan this project.

ClaudeQB will inspect the repository briefly, then ask for:

• PROJECT_NAME
• PROJECT_INTENT
• TARGET_END_STATE
• KNOWN_CONSTRAINTS

ClaudeQB asks intake questions in the user's language when practical. Generated Planner-docs artifacts are English by default unless the user explicitly requests another content language. Required document headings remain English for validator stability. Intake should also surface desired autonomy, human review cadence, and any token/usage budget so ClaudeQB can describe rough fresh-session cost/context risk without pretending to know exact spend.

Future language-mode work should add an explicit PLANNER_DOC_LANGUAGE or intake-level language setting. Until then, headings stay English and only body content should vary when the user requests another language.

For existing repositories, the questions include repo-derived suggestions. For empty or minimal repositories, ClaudeQB falls back to concise generic questions and marks repository evidence as limited.

Generated Artifacts

ClaudeQB writes planning artifacts under the target project's Planner-docs/ directory:

Planner-docs/
  Main-Planing.md
  Autopsy.md
  Project-Ontology.md
  Project-Comprehension.md
  Planing-Ledger.md
  Sub-Planing-Index.md
  Sub-Planing-Audit.md
  Faz-0-Plans/
    Faz0.1-*.md
  Faz-1-Plans/
    Faz1.1-*.md

The Planing spelling is intentionally preserved because the bundled planner prompts and validators use these exact filenames.

Evidence-Based Project Comprehension

Planner-docs/Project-Comprehension.md is optional and intended for medium or large existing projects. It records question-driven comprehension, evidence registers, confidence, domain-to-code trace maps, intended-vs-implemented architecture relations, bounded history/hotspot signals, quality scenarios, and open hypotheses with next probes.

Allowed evidence types are source, test, runtime, history, configuration, documentation, and user-confirmed. Confidence values are confirmed, probable, tentative, and contradicted. Step 2 turns tentative claims into validation work; Step 3 audits evidence quality and trace coverage; Step 4 verifies relevant assumptions before code changes.

Validator

The skill includes a read-only validator:

python3 plugins/claudeqb/skills/claudeqb/scripts/validate_planner_docs.py --root /path/to/project --mode autopsy --strict
python3 plugins/claudeqb/skills/claudeqb/scripts/validate_planner_docs.py --root /path/to/project --mode step2 --strict
python3 plugins/claudeqb/skills/claudeqb/scripts/validate_planner_docs.py --root /path/to/project --mode step3-preflight --strict
python3 plugins/claudeqb/skills/claudeqb/scripts/validate_planner_docs.py --root /path/to/project --mode step3 --strict
python3 plugins/claudeqb/skills/claudeqb/scripts/validate_planner_docs.py --root /path/to/project --mode step4

Validator modes:

These commands are for manual validation from a ClaudeQB repository checkout. When running through an installed plugin, ClaudeQB should use the bundled validator path exposed by the active skill; if that path is unavailable, it should perform equivalent all-file validation and report the fallback clearly.

The validator checks required sections, optional ontology/ledger/comprehension headings and content, phase folders, filename conventions, index references, duplicate numbering, unindexed files, length-bounded secret patterns, and Step 4 readiness. Open P0/P1 audit findings block the implementation handoff. Open or accepted P2/P3 findings require PASS_WITH_WARNINGS; resolved/not_applicable P2/P3 findings do not keep the audit in warning state forever.

Repository maintainers can run the dependency-free repo check with:

make check

make check validates plugin JSON, required package files, .claude-plugin/plugin.json semantic fields, stale invocation names, tracked-file secret hygiene, archive hygiene, the fixture corpus, and the unit test suite without requiring PyYAML or local Claude Code validator dependencies.

On a normal local development machine, make check is expected to finish well under 30 seconds. A timeout or hang in validator tests is a release blocker, not a warning to ignore.

Release Validation

Run this before sharing, committing, or pushing release changes:

make check

The repository also includes GitHub Actions at .github/workflows/validate.yml, which runs the same check on pushes to main and pull requests.

For sanitized zip sharing, use the tracked-file archive target instead of Finder or generic directory compression:

make export-sanitized

This creates ClaudeQB-sanitized.zip from git archive, excluding .git/, ignored Python caches, local env files, runtime folders, and other untracked local clutter. The default validation gate also checks that forbidden tracked archive entries are not present.

Safety Model

ClaudeQB is planning-first. Steps 1-3 should not:

• implement product features;
• refactor source code;
• install dependencies;
• run destructive commands;
• commit, push, deploy, or open pull requests;
• write secrets, tokens, credentials, private keys, or local sensitive environment values into planning files.

Generated plans should distinguish documentation readiness, local readiness, live readiness, production readiness, and operational evidence.

Repository Layout

.claude-plugin/marketplace.json
.github/workflows/validate.yml
Makefile
plugins/claudeqb/
  .claude-plugin/plugin.json
  skills/claudeqb/
    SKILL.md
    .claude-plugin/plugin.json
    scripts/validate_planner_docs.py
    references/
      First-Planner.md
      Autopsy-Planner.md
      Second-Planner.md
      Third-Planner.md
      Fourth-Planner.md
      handoffs/
        run-step2.md
        run-step3.md
        run-step4.md
      repo-aware-intake.md
      workflow-quality.md
      vibecoding-principles.md
      subagent-playbook.md
      planning-ledger.md
      project-ontology.md
      project-comprehension-methods.md
      probe-policy.md
      assessment-and-budget.md
      engineering-principles.md
docs/
  INSTALLATION.md
  MAINTAINING.md
  USAGE.md
evals/
  run_fixture_corpus_checks.py
scripts/
  validate.sh
tests/
CHANGELOG.md
LICENSE
README.md

Documentation

• Installation
• Usage
• Maintaining ClaudeQB

Public Plugin Directory Status

ClaudeQB currently uses repository marketplace distribution. Public directory or workspace sharing distribution can be revisited separately; this release focuses on repo-marketplace installation and local/team validation.

License

MIT. See LICENSE.