Skip to content
Back to search

CodexQB

SkillWorks with CodexGitHub

CodexQB is a Codex plugin for evidence-backed repo comprehension, planning, QA audit, and gated implementation handoffs.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/alicankiraz1/CodexQB with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/alicankiraz1/CodexQB'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alicankiraz1--codexqb/badge.svg)](/listings/alicankiraz1--codexqb)

HTML

<a href="/listings/alicankiraz1--codexqb"><img src="/api/listings/alicankiraz1--codexqb/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install from the repository marketplace:

codex plugin marketplace add alicankiraz1/CodexQB --ref main
codex plugin add codexqb@codexqb

Open a new Codex task in the project you want to plan and invoke the skill explicitly:

Use $codexqb to inspect this repo and plan this project.

CodexQB is configured with `allow_implicit_invocation: false`. Normal Codex prompts should not activate it; only an explicit `$codexqb` request should start the workflow.

The intake covers four stable fields:

- `PROJECT_NAME` - `PROJECT_INTENT` - `TARGET_END_STATE` - `KNOWN_CONSTRAINTS`

CodexQB 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. A future `PLANNER_DOC_LANGUAGE` setting can make this choice explicit; it is not implemented yet.

For installation verification, upgrades, and fresh-task activation probes, see [Installation](docs/INSTALLATION.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 171 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # CodexQB
  2. [![validate](https://github.com/alicankiraz1/CodexQB/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/alicankiraz1/CodexQB/actions/workflows/validate.yml)
  3. **Evidence-backed, vibecoding-first project planning for Codex.**
  4. CodexQB reads the repository before it plans. It turns the current project into a durable, reviewable planning package under `Planner-docs/`, then prepares small implementation handoffs that can be checked before code changes begin.
  5. ![CodexQB workflow](docs/assets/codexqb-workflow.png)
  6. ## What it gives you
  7. - A repository-aware main plan instead of a generic task list.
  8. - An existing-project autopsy, optional project comprehension, and project ontology.
  9. - Phase plans with dependencies, validation commands, risks, and acceptance criteria.
  10. - A QA audit and controlled Goal/Apply handoff for small, verifiable slices.
  11. - A planning ledger that keeps decisions and implementation evidence durable across long Codex sessions.
  12. CodexQB is useful for software, AI, infrastructure, security, and automation projects. It is planning-first: it does not silently turn a planning request into product-code changes.
  13. ## Quick start
  14. Install from the repository marketplace:
  15. ```bash
  16. codex plugin marketplace add alicankiraz1/CodexQB --ref main
  17. codex plugin add codexqb@codexqb
  18. ```
  19. Open a new Codex task in the project you want to plan and invoke the skill explicitly:
  20. ```text
  21. Use $codexqb to inspect this repo and plan this project.
  22. ```
  23. CodexQB is configured with `allow_implicit_invocation: false`. Normal Codex prompts should not activate it; only an explicit `$codexqb` request should start the workflow.
  24. The intake covers four stable fields:
  25. - `PROJECT_NAME`
  26. - `PROJECT_INTENT`
  27. - `TARGET_END_STATE`
  28. - `KNOWN_CONSTRAINTS`
  29. CodexQB 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. A future `PLANNER_DOC_LANGUAGE` setting can make this choice explicit; it is not implemented yet.
  30. For installation verification, upgrades, and fresh-task activation probes, see [Installation](docs/INSTALLATION.md).
  31. ## Workflow
  32. | Step | Purpose | Main output |
  33. | --- | --- | --- |
  34. | 1. Understand | Inspect the repo, ask focused questions, and create the master plan. | `Planner-docs/Main-Planing.md` |
  35. | 1.5 Diagnose | For existing projects, capture current-state gaps, vocabulary, architecture evidence, and open questions. | `Autopsy.md`, optional ontology/comprehension docs |
  36. | 2. Decompose | Turn the active planning horizon into implementation-ready phase plans. | `Sub-Planing-Index.md`, `Faz-*-Plans/*.md` |
  37. | 3. Audit | Check coverage, dependencies, risks, structure, and readiness. | `Sub-Planing-Audit.md` |
  38. | 4. Hand off | Produce bounded Goal/Apply work contracts and record progress. | Goal prompt, optional `Planing-Ledger.md` updates |
  39. Later phases can stay as deferred roadmap cards while CodexQB plans the next useful slice in detail. Bounded subagent exploration and review may be recommended for large projects, but the parent agent remains responsible for final planning artifacts.
  40. ## Generated planning package
  41. ```text
  42. Planner-docs/
  43. Main-Planing.md
  44. Autopsy.md
  45. Project-Ontology.md
  46. Project-Comprehension.md
  47. Sub-Planing-Index.md
  48. Sub-Planing-Audit.md
  49. Planing-Ledger.md
  50. Faz-0-Plans/
  51. Faz-1-Plans/
  52. ```
  53. The historical `Planing` spelling is intentional because validators and prompt contracts use these exact filenames.
  54. Goal and Apply runtime state is stored outside the target repository in an owner-only, repository-bound controller directory under the effective account's passwd home. Production does not trust `HOME` or repository-provided path overrides. Legacy in-repository Goal/Apply run directories are archive-only.
  55. ## Safety boundaries
  56. CodexQB keeps the following rules explicit:
  57. - Repository evidence flows through the bounded `RepositoryIO v1` interface.
  58. - Repository reads are no-follow, identity-checked, mount-aware, size-bounded, and fail closed.
  59. - Planner writes are allowlisted, compare-and-swap guarded, atomically published, and never include secrets.
  60. - Goal/Apply controllers are launched only from the active `$codexqb` skill root resolved by the Codex loader.
  61. - Commit, push, pull request, deployment, destructive commands, and external mutations require explicit user approval.
  62. - Local controller receipts and HMACs do not claim host or agent attestation.
  63. Without an independent trusted host/agent attestation API, `VERIFIED` and every finalization path intentionally remain unavailable. The stable fail-closed code is `trusted_verified_requires_host_agent_attestation`.
  64. ## 0.3.0 status
  65. `0.3.0` is still unreleased. The current line strengthens repository I/O, portable skill launching, source-bound Goal/Apply contracts, privacy scanning, deterministic packaging, and validation evidence.
  66. Release remains blocked until all closure gates are complete:
  67. - The history-privacy baseline still contains 70 hash-only records from reachable historical blobs. It is a migration inventory, not an accepted release baseline.
  68. - `make check-release` must stay blocked until the separately approved history rewrite and a fresh zero-finding history scan are complete.
  69. - A fresh schema-v3 live end-to-end run, installed-copy parity, activation evidence, and final release provenance are still required.
  70. - No history force-push, tag push, or GitHub Release is implied or authorized by normal development work.
  71. The earlier sanitized live smoke is reviewable at [0.3.0 live subagent smoke](docs/release-evidence/0.3.0-live-subagent-smoke.md). It does not prove the full current receipt chain.
  72. ## Validation
  73. Fast local feedback:
  74. ```bash
  75. make check-fast
  76. ```
  77. Full development gates:
  78. ```bash
  79. make check-unit
  80. make check-schema
  81. make check-behavior
  82. make check-package
  83. make check-public-privacy
  84. make check
  85. ```
  86. The full Goal/Apply regression suite can take tens of minutes. Release and package details live in [Maintaining CodexQB](docs/MAINTAINING.md); day-to-day validator and controller examples live in [Usage](docs/USAGE.md).
  87. <details>
  88. <summary>Maintainer contract notes</summary>
  89. Current public contract versions:
  90. ```text
  91. plugin_version: 0.3.0
  92. artifact_schema_version: 3
  93. handoff_contract_version: 2
  94. goal_run_schema_version: 1
  95. apply_run_schema_version: 3
  96. budget_schema_version: 1
  97. ```
  98. Goal artifacts bind the source path and hash, compiler version, template bundle digest, implementation contract digest, validation command IDs, and bounded budget. The fixture corpus checks these contracts across representative project shapes.
  99. Operational commands use the loader-derived absolute `"<CODEXQB_SKILL_ROOT>/scripts/skill_launcher.py"`; `<CODEXQB_SKILL_ROOT>` is documentation notation, not an environment variable. Apply accepts a bounded `codexqb.controller-argv/v1` request through stdin via `--controller apply -- request-stdin`.
  100. The Apply lifecycle is `prepare` → `dispatch` → `record` → `normalize-writer` → `capture-evidence` → `run-validation` → `normalize-review` → `publish-review` → `finalize`. It binds `validation_command_ids`, uses strict Step 4 validation, and persists an `Events.jsonl` chain governed by the bundled `apply-run-schema.json`. Agent identity remains `controller_asserted`; `finalize` cannot bypass `trusted_verified_requires_host_agent_attestation`.
  101. Event recovery is deliberately conservative. `event_log_commit_state_unknown` requires inspection, never a blind retry. The unkeyed event chain is not a trusted external head anchor. Older pre-chain v3 runs are archive-only; use a fresh run after recovery.
  102. Detailed controller, filesystem, receipt, packaging, and recovery contracts are maintained in [Usage](docs/USAGE.md), [Maintaining CodexQB](docs/MAINTAINING.md), and the bundled skill references.
  103. </details>
  104. ## Documentation
  105. - [Installation](docs/INSTALLATION.md)
  106. - [Usage](docs/USAGE.md)
  107. - [Maintaining CodexQB](docs/MAINTAINING.md)
  108. - [0.3 release foundation](docs/revision/CODEXQB-0.3-RELEASE-FOUNDATION.md)
  109. - [Feedback closure audit](docs/FEEDBACK-CLOSURE-AUDIT.md)
  110. ## Contributing
  111. Use GitHub issues for bugs, enhancements, and documentation requests. Before opening a pull request, run the relevant focused tests and then the full applicable gates. Preserve explicit-only `$codexqb` activation, exact `Planing` filenames, dependency-free runtime validation, privacy-safe diagnostics, and fail-closed security boundaries.
  112. ## Community supporters
  113. Thanks to [@ozanturcan](https://github.com/ozanturcan) and [@hsnyvsh](https://github.com/hsnyvsh) for detailed public feedback and PR proposals that improved validation, handoff clarity, package behavior, and test coverage.
  114. ## License
  115. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.