Repository Directory
Back to directory
null0xxx avatar
null0xxx / kimi-atlas

kimi-atlas

Many-agent, quality-calibrated orchestrator for Kimi Code with 115 vendored official skill packages — a first-class agentic backbone (live ContextGraph, explicit state machine, forward-only rollback) over a deterministic 6-lens verification harness with pure pass/fail gates and human-gated output. No LLM ever computes pass/fail.

View on GitHub

13

Stars

1

Forks

0

Watchers

MIT

License

README

Read full README on GitHub →

kimi-atlas

A many-agent, quality-calibrated orchestrator for Kimi Code — with 115 official skill packages built in. No line ships until a pure, deterministic gate says so, and no LLM ever computes pass/fail. Now with a first-class agentic backbone: a live ContextGraph, an explicit state machine, and forward-only rollback.

ci tests skills

kimi-atlas turns a rough coding request into elite, human-gated, verified implemented code — and gives your Kimi Code a curated library of 115 ready-to-use official skills it can select and apply at the right moment. It is four composable capabilities:

  • atlas — the single-change core. One root SKILL drives a deterministic INIT → … → OUTPUT state machine over Kimi's built-in subagents, gated by a 6-lens verification harness and a pure quality backbone that owns the pass/fail decision.

  • ATLAS-WEAVE — the multi-agent meta-machine. It decomposes a larger change into a file-disjoint plan-DAG, drains it with a flat pool of ≤3 concurrent node runs, and merges results through a combined-tree differential gate — degrading byte-identically to a single atlas run when the work doesn't decompose.

  • The skill system — 115 vendored official Kimi skill packages under skills/<name>/ (platform-registered, usable on their own), plus a deterministic selector (scripts/skillselect.py) that picks the right skill for a task intent and injects it into atlas runs — with a user-editable override file.

  • The agentic backbone (Graph + Loop + Verification) — atlas now carries a first-class, live ContextGraph: a pure read-time projection of the run's state (task hierarchy, tools used, errors) that is injected into the coder at the CODED stage and recomputed on every refine pass. It runs on an explicit finite-state machine (scripts/fsm.py — legal transitions derived from the canonical stages), with two-phase forward-only rollback confined to the isolated worktree (never your real tree), and a stdlib ast syntax/lint lens added to the deterministic floor. Its design was hardened by the plugin's own 6-lens harness across six rounds (27 → 0 defects) before a line was written.

The design goal was set explicitly: "the kind of system Kimi's own creators would build." Its answer is quality over quantity — many agents, every one of whose output is caught by a deterministic gate, adversarial verification, and combined-tree integration.

Table of contents

Quick start

Requirements: Kimi Code CLI, and CPython 3.11 or newer as python3. The 3.11 floor is hard, and it is new in v1.5.1. Every script atlas runs is launched with PYTHONSAFEPATH=1, which is what keeps an untrusted target repository from replacing atlas's own modules — including scripts/verdict.py, the frozen gate that decides pass/fail. That variable, and the sys.flags.safe_path the run checks it by, were added in CPython 3.11; on anything older the variable is silently ignored and the isolation the gate's integrity depends on cannot be obtained at all. So atlas fails closed rather than running unprotected: on Python 3.10 or older every run stops at its first step with ATLAS-PRECONDITION-FAILED: import isolation is not active … and does nothing else. Ubuntu 22.04 and several other LTS distributions still ship python3 = 3.10 — check with python3 -V and install 3.11+ (or point python3 at it) before installing or upgrading. Development and CI run on Python 3.12, stdlib-only.

The one-liner (Kimi Code CLI) — install straight from GitHub, no clone needed:

/plugins install https://github.com/null0xxx/kimi-atlas

This fetches the latest release (or the default branch if none), registers the plugin natively, and shows the standard third-party trust confirmation (normal for any non-official source). Then /plugins reload (or start a new session). Pin a version or commit when you need reproducibility:

/plugins install https://github.com/null0xxx/kimi-atlas/releases/tag/v1.5.3.1
/plugins install https://github.com/null0xxx/kimi-atlas/commit/<sha>

From source — for hacking on the plugin itself:

git clone https://github.com/null0xxx/kimi-atlas.git
cd kimi-atlas
./scripts/install.sh                                  # installs into $HOME/.kimi-code/plugins/kimi-atlas
KIMI_CODE_HOME=/path/to/.kimi-code ./scripts/install.sh   # if Kimi lives elsewhere

The source installer deploys the committed HEAD (a consistent snapshot), backs up and atomically rewrites installed.json, and preserves every other plugin. Re-run it after each update; remove with --uninstall. Either way, smoke-test:

kimi -p "/skill:atlas ping"        --output-format text    # single-change core
kimi -p "/skill:atlas-weave ping"  --output-format text    # multi-agent meta-machine

Then hand it real work. Inside a Kimi Code session, type a slash command:

/skill:atlas fix the off-by-one in pagination  verify_cmd: pytest -q  success: page 2 returns rows 11–20  scope: api/pagination.py
/skill:atlas-weave add a --json flag to the export, importer, and CLI  verify_cmd: make test  success: all three accept --json  scope: src/export.py src/import.py src/cli.py
/skill:atlas-resume                # pick up the newest interrupted run from its on-disk ledger

Headless / CI — one-shot, non-interactive:

kimi -p "/skill:atlas <rough change> verify_cmd: <cmd> success: <criteria> scope: <paths>" -m kimi-code/k3
kimi -p "/skill:atlas-weave <larger multi-file change> verify_cmd: <cmd> success: <criteria> scope: <paths>" -m kimi-code/k3

The four fields are the contract: verify_cmd: the command that must pass, success: the human-readable acceptance criteria, scope: the files atlas may touch (anything outside is a blocking scope-creep defect). All are optional — omit them and atlas asks once at the CLARIFY gate. -m kimi-code/k3 selects the 1M-context Kimi-3 model.

Every run is human-gated. atlas produces a verified change and stops at the OUTPUT gate — it never writes your working tree without your approval; in headless mode it works entirely inside an isolated git worktree; and if it can't reach a green gate it labels the result ⚠️ UNVERIFIED rather than pretending. State is persisted to a .atlas/<run_id>/ ledger, so a run survives compaction and can be resumed.

Using the 115 skills

The plugin ships 115 official Kimi skill packages, extracted byte-identically from their source archives and committed under skills/<name>/. Because .kimi-plugin/plugin.json declares skills: ./skills/, they are platform-registered: Kimi Code sees every one of them in its skill listing, can auto-trigger them from their descriptions, and you can invoke any of them explicitly with /skill:<name>.

Category Count Examples
Engineering 28 code-mentor, code-vuln-audit, repo-audit, kubectl, test-suite-architect, deep-module-refactor
Finance 19 financial-ratio-toolkit, discounted-cashflow-model, equity-research-report, stock-signal-analyzer
Featured 18 kimi-find-skills, browse, docx, xlsx, gitlab-cli-skills, fast-browser-use
Productivity 16 gantt-planner, sprint-plan-builder, structured-minutes, okr-strategist, email-to-calendar
Creative 15 keynote-composer, x-thread-crafter, photo-magazine, podcast-episode-writer, theme-factory
Marketing 11 seo-audit, copywriting, ad-creative, x-thread-crafter, email-newsletter-builder
Academic 8 cv-tailor, anki-card-maker, scholarly-writing-refiner, mock-interview-drill

Each package is self-contained: its SKILL.md instructions plus its payload — scripts, references, templates (e.g. skills/financial-ratio-toolkit/scripts/analyze.py). Integrity is anchored by a committed sha256 manifest (references/skills-manifest.json) that CI re-verifies byte-for-byte against the tree — so what you install is exactly what was vetted, with no network fetch and no zip step.

Two things to know:

  • Skills are data, treated with care. The packages were extracted and verified — never executed — at import time. A skill only runs when the platform triggers it or an atlas run selects it.
  • Your own skills coexist safely. The three orchestrator skills (atlas, atlas-weave, atlas-resume) are first-party; the 115 vendored packages live alongside them under the same skills/ tree, and the repo's documentation gates treat every skill package as a self-contained unit.

Automatic skill selection

Beyond platform triggering, atlas itself picks skills for your task — the right skill at the right time:

  1. At the GROUNDED stage of every atlas run, scripts/skillselect.py ranks the committed registry (references/skill-registry.json) against your frozen intent — weighted, explainable matching (name > triggers > description, word-boundary category prior, deterministic tie-breaks; every result carries matched_tokens and a why).
  2. The selection is persisted to the run ledger and injected into the coder packet only: the TOP-1 skill's full SKILL.md body becomes the coder's active skill (its on-disk payload paths included), the remaining top-3 stay advisory names + paths + why. The critics never see it — their packets carry the diff, the frozen intent, one rubric lens and the evidence slice, and nothing else; that isolation is what buys anti-anchoring.
  3. You steer it manually by editing references/skill-overrides.json: pin (force-include, in order), exclude, boost (score multiplier — 0 zeroes a skill out), categories (whitelist). The file is optional; selection is advisory (V6) and can never gate a run.

Try the selector yourself:

PYTHONPATH=. python3 scripts/skillselect.py "turn my notes into anki flashcards"
PYTHONPATH=. python3 scripts/skillselect.py "analyze company financials for a board deck" --top-n 5

The registry is rebuilt from the extracted tree (never from zips) and is schema-validated in CI:

make skill-registry    # rebuild references/skill-registry.json from skills/
make skills-extract    # re-extract + verify the vendored packages against the manifest

How atlas guarantees quality

One uninterrupted run of a canonical state machine (ctxstore.STAGES is the single source of truth):

INIT → INTENT_CAPTURED → [CLARIFY] → TRIAGED → GROUNDED → CODED → VERIFIED → [REFINE]* → OUTPUT

The root holds immutable intent, dispatches context-scout (grounding), elite-coder (implementation), and three isolated adversarial critics, and persists everything to an on-disk ctxstore ledger so the run survives compaction. Three mechanical tiers, cheapest first — no model judgment ever enters a pass/fail decision:

  1. The 6-lens verification harness. A free deterministic floor — runcheck / lint / reqcoverage / pathcheck / astlens (stdlib ast syntax-&-lint) / fail-open semgrep sast — contributes blocking defects on its own, then feeds the 3-critic judgment wave (correctness / code-quality / security — each isolated, adversarially framed). Everything is folded by pure functions: verdict.merge → verdict.gate. A coder cannot rubber-stamp itself; the rubric is references/rubric.md.
  2. Provably-halting refinement. Any CRITICAL/HIGH defect — and any correctness/security defect at any severity (V7) — forces a refine pass; the loop is hard-capped at MAX_PASSES=2 by construction.
  3. Human gates at the only right places. Clarify (once), pre-CODE plan approval, and the OUTPUT gate. Nothing auto-applies.

ATLAS-WEAVE — the multi-agent layer

DECOMPOSED → BUDGETED → SCHEDULE* → INTEGRATE → AGGREGATE → OUTPUT
  1. DECOMPOSED — a read-only planner proposes a file-disjoint plan-DAG; accepted only if acyclic, scope-disjoint, and criteria-covering — else it degrades to the 1-node atlas DAG.
  2. SCHEDULE* — a flat W=3 work-stealing pool with a memory-admissible wave planner (live free -m floor) and provably-bounded gas.
  3. INTEGRATE — git apply the union onto one worktree, re-validate against actually-touched files, and run the combined-tree differential: re-run the union of every node's baseline-green suites on the merged tree — a test green-alone but red-combined is a zero-false-positive cross-change regression.
  4. AGGREGATE — one pure fold of every node's verdict + synthetic UNVERIFIED per unresolved node + a criteria-conservation backstop + the combined-tree result.

Full spec (halting argument, memory model, risk register): references/atlas-weave.md.

The agentic backbone — Graph + Loop + Verification

Layered around the pure core (it wraps, never replaces), the agentic backbone makes an atlas run stateful, self-correcting, and harder to fool. It was designed against the plugin's own 6-lens harness — six rounds, 27 → 24 → 7 → 1 → 0 defects — and every module is stdlib-only, deterministic, and unit-tested.

  • ContextGraph — a live, read-time projection. scripts/contextgraph.py renders the current run into one queryable graph: the task hierarchy (thin pointers into the plan-DAG), the tools invoked and their outcomes, the errors — recomputed from the on-disk ledger + event log at read time, so there is no event-sourced state to drift. At the CODED stage the SAFE-2-wrapped graph is injected into the coder's packet as architectural-state evidence (never instructions), and it recomputes on every refine pass so the loop always sees the true state. It is a hint, never a gate; an empty or unreadable graph degrades to no injection. ctxstore.log.jsonl and the halting counter are provably untouched — events live in a separate hooks.jsonl.

  • An explicit finite-state machine. scripts/fsm.py's legal_transition is derived from the canonical ctxstore.STAGES — one source of truth — plus exactly one hand-declared edge: the REFINE → CODED loop. An import-time guard forces fsm to update if the stages ever change, and a red-team scenario proves an illegal transition is blocked. advance() stays a permissive recorder; the FSM is enforced by tests and the negative gate, not by mutating the hot path.

  • Two-phase forward-only rollback. When a headless run hits a hard failure, scripts/rollback_driver.py runs a crash-safe intent → git-reset → complete sequence, gated by a pure sanctioned_rollback predicate that only fires inside the isolated .atlas/<run_id>/worktree (never your real tree). The ledger is append-only — a rollback never rewrites history, so the MAX_PASSES halting bound survives it — and a torn rollback is idempotently redone on resume. Interactive runs never auto-reset: the residual is surfaced at the OUTPUT gate with an explicit revert / keep / discard choice.

  • A single canonical SAFE-2 wrapper. Every piece of untrusted text a model sees — a selected skill's body, the ContextGraph's tool/error content, a build's runcheck stdout/stderr tails fed back on a refine — passes through one scripts/safewrap.py wrapper that frames it as DATA and neutralizes any break-out attempt. An injection in a failing test's output cannot alter the coder's intent, scope, or target.

Full design + the 6-lens challenge record: docs/superpowers/specs/2026-07-20-agentic-architecture-blueprint.md; the whole-system map: references/system-map.md.

Proven live

  • Validated end-to-end on the live Kimi CLI v0.26.0 / k3 (1M context) — ledgers and numbers in references/live-validation.md: a real 3-file change decomposed into 3 disjoint nodes, each verified OK, union suite green, presented at the human gate without touching the real tree.
  • This plugin's own skill system was built by atlas. The registry/selector (commit 0fb699e) and the vendoring of the 115 packages (commit 115fee7) each went through the full INIT → OUTPUT machine with the 6-lens harness — which caught 39 real defects across the two runs, including a critical zip-slip: a hostile skill's frontmatter name could traverse the extractor's output path (name: .. → arbitrary file write). It was fixed with strict name validation, first-party collision checks, joined-path/symlink guards, and a hostile-input test matrix — before anything shipped. The full unit-test suite is green (run make test).
  • Q/T, told honestly: on a small task, single-shot atlas beats atlas-weave at equal quality — weave's machinery earns its overhead only on larger, genuinely independent multi-file work, and degrades to atlas when it wouldn't.

Honest limits

  • Decomposition incoherence is the deepest residual: the gates catch defects and test-observable regressions, not a coherent-looking yet semantically wrong split. Mitigated (degrade-to-atlas, coupling check, seam critics, criteria-conservation) — not solved.
  • The differential is sound, not complete: an emergent seam interaction with no covering test can still merge green.
  • The integration node is a serial bottleneck — useful K per run is ~12–16, not hundreds. By design: quality over quantity.
  • The 115 vendored skills are third-party content. They are integrity-anchored (sha256 manifest, CI-verified) and their SKILL.md bodies are injected with explicit untrusted-content framing — but they are instructions written by their authors, used on your behalf. Skim a skill's directory before relying on its payload scripts in sensitive environments.
  • The judgment lenses are model critics. The deterministic floor blocks mechanically-detectable defects; a subtle bug behind an adequate-looking test remains a named soft spot (rubric §V3/V5/V7).

Repository layout

.kimi-plugin/plugin.json    manifest (skills dir, interface, skillInstructions, hooks)
skills/atlas/               the single-change root orchestrator (state machine)
skills/atlas-weave/         the multi-agent meta-machine (decompose → integrate → aggregate)
skills/atlas-resume/        graph-aware, compaction-surviving resume
skills/<name>/              115 vendored official skill packages (manifest-anchored)
agents/*.md                 role files (documentation-only frontmatter; read by the subagent itself)
scripts/*.py                the PURE decision cores + the deterministic I/O "hands" (importable, unit-tested)
scripts/skillextract.py     zip → skills/<name>/ extractor + manifest builder + --verify (audit-gated)
scripts/skillregistry.py    builds references/skill-registry.json from the extracted skills/ tree
scripts/skillselect.py      ranks the registry for a task intent (advisory; pin/exclude/boost overrides)
scripts/skillpkgs.py        shared skill-package-aware markdown walk for the doc gates
scripts/contextgraph.py     the live ContextGraph read-time projection (injected into the coder at CODED)
scripts/ctxevents.py        records tool_call/error events into the run's hooks.jsonl (never log.jsonl)
scripts/fsm.py              explicit legal_transition / legal_path, derived from ctxstore.STAGES
scripts/rollback_driver.py  two-phase forward-only rollback + the pure sanctioned_rollback gate
scripts/safewrap.py         the single canonical SAFE-2 untrusted-content wrapper
scripts/astlens.py          stdlib ast syntax/parse + lint floor — a deterministic verification lens
scripts/rubric.py           single-source rubric vocabulary (imported by verdict / quality / negative-gate)
scripts/frontmatter.py      shared BOM+CRLF-aware frontmatter primitive
tests/                      the full unit-test suite + the red-team negative-gate fixtures
references/*.md             the design corpus — architecture, atlas-weave spec, rubric, runtime, live validation
references/skills-manifest.json  sha256 anchor for the extracted skills/ tree (117 zips → 115 packages)
references/skill-registry.json   compact registry of all 115 vendored skills (the skills/ tree is source of truth)
references/skill-overrides.json  manual selector overrides (pin / exclude / boost / categories)
docs/superpowers/plans/     the test-first build plans, one per phase (P6–P12)
probe/                      residual-runtime-unknown probes

The pure decision cores — plandag (DAG + halting), scheduler (flat pool + memory model), planstage (decompose + degrade), integrate / differential (the combined-tree sink), budget, bestofn, verdict, resume — are standard-library-only, fully deterministic, and carry no runtime I/O. The "hands" (suiterun, uniontree, leaseclock, runcaps, dogfood_weave) are the thin, fail-safe boundary that lets the real Kimi runtime drive them.

Developing

make ci               # the full local gate: strict naming + the unit-test suite + inventory-drift + shell-syntax
make test             # unit tests only (python3 -m unittest discover -s tests -v)
make skill-registry   # rebuild references/skill-registry.json from the extracted skills/ tree
make skills-extract   # re-extract the vendored packages + verify against the sha256 manifest
make negative-gate    # red-team fixture matrix: good→OK, each bad_*→UNVERIFIED
make help             # everything else

make ci mirrors .github/workflows/check.yml exactly (Python 3.12, stdlib-only). Conventions that keep the tree clean: every new script gets a tests/test_<module>.py; new design docs live in references/*.md and are linked (the inventory-drift gate enforces it); skill packages under skills/ are self-contained and exempt from the first-party doc gates.

FAQ

Do the 115 skills slow down every session? Only their listing entries (name + one-line description) are present in the skill listing; bodies and payload load lazily, when a skill is actually triggered or selected. The registry that powers automatic selection is a single 80 KB JSON read once per atlas run.

Are the vendored skills safe? They are official Kimi skill packages, extracted byte-identically and anchored by a CI-verified sha256 manifest — tampering fails the build. The extractor itself was hardened against hostile archives (name-traversal, zip-slip, symlink and backslash escapes) with a dedicated hostile-input test matrix. Payload scripts are ordinary third-party code: the platform never executes them unless you or a skill run them.

Can I disable or reprioritize a skill? Yes — references/skill-overrides.json: add it to exclude (never selected), pin (always selected first), boost (reprioritize), or restrict categories. No rebuild needed; the selector reads it live.

A skill is missing / I have a newer version of one. The extracted skills/ tree is the source of truth. Replace the package directory, then run make skills-extract (re-anchors the manifest) and make skill-registry (rebuilds the registry). make ci must stay green — it will tell you if anything drifted.

Where are the original zips? They were a one-time import source and are intentionally not committed (41 MB). Everything they contained is in the committed tree, byte-identical and manifest-anchored.

Does atlas ever change my code without asking? No. Interactive runs edit the real tree only after the pre-CODE plan gate you approve; headless runs are confined to an isolated git worktree; and every change is presented at the OUTPUT human gate. Nothing is ever auto-merged.

Documentation

Built with the same gates it ships: every feature in this repository passed the 6-lens verification harness it implements.

Releases

v1.5.3.1

Jul 30, 2026

v1.5.3.1 — the v1.5.3 tarball did not pass its own gate

Download .zip

No runtime code changes — the plugin behaves identically to v1.5.3. What changed is that the artifact you install now verifies itself. Why this exists make ci run against git archive v1.5.3 — the tarb...

https://github.com/null0xxx/kimi-atlas/archive/refs/tags/v1.5.3.1.zip

v1.5.3

Jul 30, 2026

v1.5.3 — a live false GREEN closed, and two of our own claims withdrawn

Download .zip

This release ships more retractions than features, and that is the point. Every number below was executed; the ones that did not survive are struck out rather than defended. The defect that mattered —...

https://github.com/null0xxx/kimi-atlas/archive/refs/tags/v1.5.3.zip

v1.5.2.1

Jul 26, 2026

v1.5.2.1 — six defects that were live in v1.5.2, one CRITICAL

Download .zip

Security hotfix — upgrade immediately Seven defects were live in the shipped v1.5.2, one CRITICAL. Three of the seven were introduced by v1.5.2's own fixes. Six are closed here; the seventh ships know...

https://github.com/null0xxx/kimi-atlas/archive/refs/tags/v1.5.2.1.zip

v1.5.2

Jul 25, 2026

v1.5.2 — eight audit findings closed, the ordinary run hardened

Download .zip

Eight confirmed security findings of the nineteen-finding v1.5.1 audit are closed — everything that damages an ordinary, non-attacked run:

S7 — the semgrep SECURITY floor had silently never fired (--...

https://github.com/null0xxx/kimi-atlas/archive/refs/tags/v1.5.2.zip

v1.5.1

Jul 25, 2026

v1.5.1 — close the sys.path hijack of the pure gate

Download .zip

Security release — upgrade immediately A target repository could replace any module atlas imports, including the FROZEN pure gate scripts/verdict.py. During an atlas run the working directory is the t...

https://github.com/null0xxx/kimi-atlas/archive/refs/tags/v1.5.1.zip