<div align="center">
# KimiQB
**Source-bound repository planning, audit gates, and apply-run contracts for Kimi Code.**
[](https://github.com/alicankiraz1/KimiQB/actions/workflows/validate.yml)
KimiQB turns a software repository into a durable vibecoding-first planning
package: repo-aware intake, existing-state autopsy, project comprehension,
ontology, Ledger v3 continuity, phase sub-plans, QA audit, and a gated
implementation handoff for Kimi Code.
</div>
---
## Overview
KimiQB is a vibecoding-first Kimi Code plugin that installs the `/skill:kimiqb`
skill. It is built for teams that want planning to be tied to repository
evidence instead of chat memory. The workflow reads the project, asks a small
set of intake questions, writes stable Markdown artifacts under `Planner-docs/`,
validates those artifacts, and only then prepares implementation handoffs.
It is intentionally planning-first. Steps 1 through 3 should not implement
features, refactor product code, install dependencies, commit, push, deploy, or
open pull requests. Step 4 is a separate implementation path and is only exposed
when the audit and validator gates allow it.
KimiQB 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.
## Current Contract
| Contract field | Value |
| --- | --- |
| Plugin version | `0.3.0` |
| Invocation | `/skill:kimiqb` |
| Plugin manifest | `kimi.plugin.json` |
| Skill root | `skills/kimiqb/` |
| Runtime artifact root | `.kimiqb/` |
| Apply run root | `.kimiqb/apply-runs/` |
| `artifact_schema_version` | `artifact_schema_version: 3` |
| `handoff_contract_version` | `handoff_contract_version: 2` |
| `kimi_session_run_schema_version` | `kimi_session_run_schema_version: 1` |
| `apply_run_schema_version` | `apply_run_schema_version: 3` |
| Public package shape | `kimi.plugin.json` plus `skills/` |
| Source package shape | `KimiQB/` archive prefix |
## Why KimiQB
- **Evidence-backed intake:** KimiQB scans the repository before asking for
project name, intent, target end state, and constraints.
- **Existing-state awareness:** Step 1.5 Autopsy captures stubs, gaps, technical
debt, integration risks, validation gaps, and operational readiness.
- **Durable comprehension:** Optional `Project-Comprehension.md` keeps evidence,
confidence, hypotheses, architecture reflexion, traceability, and quality
scenarios outside volatile model context.
- **Project ontology:** `Project-Ontology.md` preserves vocabulary, domain
entities, workflows, invariants, and open questions for future planning runs.
- **Ledger v3 continuity:** `Planing-Ledger.md` separates `Planning Status` from
`Execution Status`, while legacy v1/v2 ledgers remain compatibility-only
outside strict Step 4.
- **Gate-aware Step 4:** Implementation can proceed only from audited
`READY` or `READY_WITH_WARNINGS` queue entries. `BLOCKED` and P0/P1 findings
stop the handoff.
- **Kimi-native handoffs:** Step 2, Step 3, and Step 4 prompts live in canonical
Kimi Code session handoff files under `skills/kimiqb/references/handoffs/`.
- **Subagent-aware operation:** Large repositories can separate exploration,
planning, audit, implementation, review, fix, and security-review roles while
keeping the parent session responsible for final artifacts.
- **Dependency-free validation:** Runtime validators use Python standard library
code so planning gates can run in minimal environments.
## Workflow
| Step | Purpose | Primary output |
| --- | --- | --- |
| 1. Repo Scan + Main Plan | Read repository evidence, ask four intake questions, and create the master plan. | `Planner-docs/Main-Planing.md` |
| 1.5 Autopsy + Comprehension | Audit existing project reality and preserve durable understanding when the repo is non-trivial. | `Planner-docs/Autopsy.md`, `Project-Ontology.md`, optional `Project-Comprehension.md` |
| 2. Phase Sub-Plans | Expand the main plan into implementation-ready phase and task plans. | `Planner-docs/Sub-Planing-Index.md`, `Planner-docs/Faz-*-Plans/*.md` |
| 3. QA Audit + Gate | Validate coverage, evidence, sequencing, readiness, security, and Step 4 queue status. | `Planner-docs/Sub-Planing-Audit.md` |
| 4. Gated Handoff | Print or compile implementation-session artifacts only when the audit allows it. | Kimi Code handoff, session run, or apply run artifacts |
The `Planing` spelling is preserved on purpose because the bundled prompts and
validators use those exact filenames.
## Quick Start
Install from GitHub inside Kimi Code:
```text
/plugins install https://github.com/alicankiraz1/KimiQB
/plugins info kimiqb
/plugins reload
/new
```
Install from a local checkout:
```text
/plugins install /path/to/KimiQB
/plugins info kimiqb
/plugins reload
/new
```
Start a planning run from the target repository:
```text
/skill:kimiqb inspect this repo and plan this project
```
If the skill was just updated, use `/plugins reload` and start `/new`. Kimi Code
may otherwise keep an older in-memory copy of the skill.
## Planner Artifacts
KimiQB writes planning state into the target project's `Planner-docs/`
directory:
```text
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
```
These files are not transcripts. They are stable source-bound contracts that
can be reviewed, repaired, validated, and handed to a fresh Kimi Code session
without relying on the previous conversation context.
## Validator
The planner validator is read-only and dependency-free:
```bash
python3 skills/kimiqb/scripts/validate_planner_docs.py --root /path/to/project --mode step1
python3 skills/kimiqb/scripts/validate_planner_docs.py --root /path/to/project --mode autopsy --strict
python3 skills/kimiqb/scripts/validate_planner_docs.py --root /path/to/project --mode step2 --strict
python3 skills/kimiqb/scripts/validate_planner_docs.py --root /path/to/project --mode step3-preflight --strict
python3 skills/kimiqb/scripts/validate_planner_docs.py --root /path/to/project --mode step3 --strict
python3 skills/kimiqb/scripts/validate_planner_docs.py --root /path/to/project --mode step4
```
It checks required headings, optional comprehension and ontology documents,
Ledger v3, legacy ledger compatibility outside strict Step 4, ontology question
statuses, audit readiness tables, finding statuses, unsafe sub-plan paths,
strict Step 4 migration rules, secret hygiene, and semantic queue gates:
```text
READY
READY_WITH_WARNINGS
BLOCKED
COMPLETE
SUPERSEDED
DEFERRED
NO_ACTION_REQUIRED
```
The deterministic fixture corpus exercises representative project states such
as clean layered services, drifted architecture, stale ledgers, runtime-only
behavior, hidden coupling, distributed domain features, and security-boundary
risk.
```bash
python3 evals/run_fixture_corpus_checks.py
```
## Session Compiler
Maintainers and advanced local workflows can compile deterministic Kimi Code
session prompts without invoking Kimi Code:
```bash
python3 skills/kimiqb/scripts/session_run.py prepare \
--root /path/to/project \
--stage step4 \
--mode kimi_session_serial
python3 skills/kimiqb/scripts/session_run.py validate \
--root /path/to/project \
--session-run /path/to/Session-Run.json
```
`Session-Run.json` records source snapshots, selected READY queue scope,
validation checkpoints, stop gates, budget policy, and `session_policy_digest`.
Validation recomputes the digest so tampered policy envelopes are rejected.
## Apply v3 Runtime
`apply_run.py` prepares local artifact state for Step 4 execution. It does not
call Kimi Code, push, open pull requests, deploy, or mutate external systems.
```bash
python3 skills/kimiqb/scripts/apply_run.py prepare \
--root /path/to/project \
--mode kimi_session_serial
python3 skills/kimiqb/scripts/apply_run.py validate \
--run-dir /path/to/project/.kimiqb/apply-runs/<run-id>
```
Supported modes:
| Mode | Use |
| --- | --- |
| `direct` | Parent-controlled bounded execution with local evidence capture. |
| `kimi_session_serial` | One fresh Kimi Code implementation session at a time, followed by ordered review phases. |
| `external_adapter` | Optional adapter path with explicit readiness and fallback to `kimi_session_serial`. |
| `no_action` | Records `NO_ACTION_REQUIRED` without starting implementation. |
Apply v3 tracks `Apply-Run.json`, `Progress.json`, `Events.jsonl`, task briefs,
dispatch packets, normalized writer reports, controller change-set evidence,
validation receipts, ordered review receipts, final review state, and result
artifacts.
The review chain is:
```text
spec -> quality -> security when required -> final
```
The controller can produce a complete local evidence chain with signed receipts
and event hashes. Trusted `VERIFIED` and finalization still fail closed until a
Kimi host or agent-attestation boundary exists. This is deliberate: controller
evidence is useful, but it is not a substitute for host-issued identity and
completion proof.
## Safety Model
KimiQB is designed to avoid accidental trust expansion:
- planning steps write only `Planner-docs/` artifacts;
- apply-run state lives under `.kimiqb/apply-runs/`;
- runtime output is redacted and bounded before being persisted;
- validation commands use a closed, root-aware command envelope;
- artifact writes use safe path and package-policy checks;
- package export rejects caches, bytecode, nested zips, local notes, secret-like
payloads, unsafe paths, symlinks, and hidden runtime directories;
- release privacy checks include visible remote heads and hidden GitHub
`refs/pull/*` refs.
If a remote privacy scan still finds private-path evidence in `refs/pull/*`,
branch cleanup is not enough. Publish from a clean-history replacement
repository or keep the old repository private or non-canonical until those refs
are purged or retired.
## Maintainer Gates
Run the default dependency-free gate:
```bash
make check
```
Run split gates when diagnosing a failure:
```bash
make check-fast
make check-static
make check-unit
make check-platform
make check-behavior
make check-package
make check-public-privacy
```
Run schema parity with the development dependency:
```bash
make check-schema
```
Run the strict release gate only from clean release provenance:
```bash
make check-release
```
The CI workflow mirrors these gates across Ubuntu and macOS Python versions,
with separate portability, behavior, package, schema, and strict-release jobs.
## Packaging
KimiQB has explicit package modes:
| Artifact type | Target | Shape |
| --- | --- | --- |
| Plugin artifact | `make export-plugin-worktree` | `kimi.plugin.json`, `skills/`, `PACKAGE-MANIFEST.json` |
| Source artifact | `make export-source-worktree` | `KimiQB/` prefix with source, docs, tests, scripts, and manifest |
| Strict release plugin | `make export-plugin` | Clean Git provenance required |
| Strict release source | `make export-source` | Clean Git provenance required |
| Filesystem source package | `make export-source-package` | Gitless/package fallback mode |
Verify and extract packages with:
```bash
python3 scripts/verify_package_manifest.py --zip kimiqb-plugin-0.3.0-worktree.zip
python3 scripts/verify_package_manifest.py --zip KimiQB-source-0.3.0-worktree.zip
tmpdir="$(mktemp -d)"
python3 scripts/extract_verified_package.py \
--zip KimiQB-source-0.3.0-worktree.zip \
--output "$tmpdir" \
--artifact-type source
(cd "$tmpdir/KimiQB" && \
KIMIQB_VALIDATE_SKIP_UNITTESTS=1 \
KIMIQB_VALIDATE_SKIP_BEHAVIOR_SMOKE=1 \
bash scripts/validate.sh)
```
## Managed Kimi Code Copy
Kimi Code installs plugins into a managed copy, usually under:
```text
$KIMI_CODE_HOME/plugins/managed/kimiqb
```
If `KIMI_CODE_HOME` is unset, Kimi Code commonly uses:
```text
~/.kimi-code/plugins/managed/kimiqb
```
After source changes, reinstall through Kimi Code or sync the managed copy with
cache excludes:
```bash
rsync -a --delete \
--exclude '.git/' \
--exclude '__pycache__/' \
--exclude '*.pyc' \
--exclude '.pytest_cache/' \
--exclude '.mypy_cache/' \
--exclude '.ruff_cache/' \
/path/to/KimiQB/ "$KIMI_CODE_HOME/plugins/managed/kimiqb/"
```
Then run `/plugins reload` and start `/new` before relying on the updated skill.
## Repository Layout
```text
kimi.plugin.json
Makefile
.github/workflows/validate.yml
docs/
INSTALLATION.md
USAGE.md
MAINTAINING.md
PUBLIC_RELEASE_AUDIT.md
assets/kimiqb-workflow.png
evals/
fixtures/
run_fixture_corpus_checks.py
skills/kimiqb/
SKILL.md
scripts/
validate_planner_docs.py
session_run.py
apply_run.py
artifact_io.py
safety_contracts.py
repository_evidence.py
git_evidence.py
mount_identity.py
doctor.py
references/
First-Planner.md
Autopsy-Planner.md
Second-Planner.md
Third-Planner.md
Fourth-Planner.md
handoffs/
session-specs/
apply/
scripts/
adapt_from_codexqb.py
check_public_privacy.py
export_sanitized.py
extract_verified_package.py
package_policy.py
validate_apply_schema.py
verify_package_manifest.py
tests/
```
## Documentation
- [Installation](docs/INSTALLATION.md)
- [Usage](docs/USAGE.md)
- [Maintaining KimiQB](docs/MAINTAINING.md)
- [Public Release Audit](docs/PUBLIC_RELEASE_AUDIT.md)
- [Changelog](CHANGELOG.md)
## License
MIT. See [LICENSE](LICENSE).