KB Agentic Skill for Claude Code, Gemini CLI, Google Antigravity & Codex

kb-agentic turns an AI agent into the keeper of a second brain built on the documents you supply — not on what the model remembers. It supports Claude Code, Codex, Gemini CLI, Google Antigravity 2.0, Cursor/Windsurf-style project instructions, and optional devPNT governance.

The sibling of @antoneeo/agentic-sdlc-skill, transplanted from source code to knowledge: same process, one different fidelity discipline.

What's new in 1.35.1

Codex hook checks can recognize the work the agent is doing. The shared validator recognizes supported native Codex patches and transcript records, and gives more accurate orientation-hook diagnostics when definitions are disabled or cannot be verified. Existing hook setup and opt-outs are preserved.

What to do

Run npm install -g @antoneeo/kb-agentic-skill@latest, then kb-agentic-install-skill, and restart your agent sessions so they load the updated validator. Check that npm ls -g @antoneeo/kb-agentic-skill shows 1.35.1. Any configured Codex hooks still require their normal client trust review.

Full history: CHANGELOG

What it does

Two axes are kept apart on purpose — abstraction (a topic made of topics: the graph edges) and certainty (how strongly the corpus supports a statement: the claim rows).

1. Intake — the source becomes untouchable. Every document enters verbatim under corpus/given/, content-addressed by a raw-byte digest. A new version is appended with supersedes:, never overwritten. Non-text files get a stored canonical extraction (.txt, registered extractor) — those are the bytes locators point at, so an id stays valid across re-ingestion. On a large binary corpus the extraction is the artifact: the digest moves onto it (immutability still enforced, on the bytes that actually matter) and the original stays where it lives, recorded as original_path: + original_sha256:. 233 MB of manuals do not enter your repository to protect bytes no locator addresses — and the two recorded fields are honest about their limits, which differ: original_sha256 checks nothing on its own (we do not hold the bytes), while original_path is verified to still resolve, and warns when it does not — a folder you reorganised should not leave sixteen sidecars pointing at nothing behind a green run. Spoken input is a note with origin: elicited; a synthesis carries derived_from:; your decision carries basis:. A note with none of the three is model knowledge dressed as a source, and the validator rejects it.

2. Extraction — the unit is the claim. Rows of id | claim | valid | qty | about | source | prov | state. The id hashes the location and the quantity, never the text, so an LLM rephrasing mints no new identity. The locator (p=17@412-509) is verified: the validator opens the extraction and checks the span exists — and anchor <path> <phrase> produces it for you, matching spaces as \s+ because a PDF extraction breaks phrases mid-line. Gates are extracted alongside powers: for every row saying what something can do, the source is asked what must hold first — default-off, licence tier, version floor, dependency — because "yes, supported" without the gate is a plan that fails on site. The rule is ask, never produce: a source that states no gate yields no row. Validity scopes are half-open ("until March" and "from March" do not conflict). Quantities are typed — mixed kinds or currencies refuse to sum. What the source does not assert becomes a gaps: line, never a claim. When the code does not yet do what a specification claim says and the fix is deferred, the claim carries not-yet-honored-by -> ANALYSIS_<name> (in a Hybrid project, SHADOW_<doc_key>, the newest devPNT shadow of the design); check verifies that the target exists and cites the claim id, and export drops the marker.

   The source is exhausted, not sampled. "Invents nothing" is a floor, and an extractor that stops when nothing it wrote is false stops on page twenty of a two-hundred-page manual with every row correct — which is exactly what a 200-page manual produces in the field. So a long source is read in bounded windows (30 pages by default, one plan task each, the ledger holding your place across sessions), and every window closes by advancing extracted_through: on the artifact's sidecar. That field is what makes "I am finished" falsifiable: claims with no coverage recorded are an error, a claim addressing a page past the declared coverage is a contradiction, and coverage short of the end is reported until it reaches it. Its limit is stated where it is written — nothing proves a page was read; what changes is that the shortcut must now be written down to pass. And exhaustive means read, never a row per page: a page that asserts nothing yields nothing.

3. Placement — five verdicts, after querying the graph. Descent through the generated index following every parent (polyhierarchy). EXISTS → reconcile; INADEQUATE → child; MISSING only after the graph was actually asked; GENERALIZES → escalate (a new root stops at you); UNPLACED → quarantine. Similar-but-maybe-different becomes a sibling with the distinguishing line written — if you cannot write it, it is the same concept. Cycles are refused at write time; merged nodes leave a tombstone with redirect_to:, never a deletion.

4. Reconciliation — the machine detects and holds, it never decides. Five outcomes: new / confirmation (the source is appended to the row — the base strengthens, it does not lengthen) / refinement (the old row goes SUPERSEDED, its text intact) / coexistence (disjoint scopes) / conflict → the whole set goes CONTESTED, symmetrically: flipping one cell by hand fails the check. Only new information resolves it — a later source, or your ruling with a basis:, the fact you know and the corpus does not. No basis, no ruling: a preference is not a fact. A ruling is challengeable — a later document reopens the case with your basis beside it.

5. Escalation in one batch at the end of the run, in legal form (the claims, the reopenable sources, the dates, why the machine cannot decide). Ingestion never stops to interrogate you.

6. Recall — the graph is read when answering, not only written when distilling. Whenever a reply would assert facts about the project's domain, the agent scans the topic index and descends before answering from model memory — plausibility of coverage is judged ON the scanned index, never before it. Answers cite claim ids; a superseded claim is never cited without its successor; a claim marked not-yet-honored is cited as required but not yet done by the code, naming its target; the verdict is declared only when the recall ran (kb: <slug> → N claims cited, a matched node with no claims surfaces its gaps:, and a missing index is reported as index-absent — not as a missing graph — with the regenerate command). When a DERIVED claim grounds a decision, its chain is walked to non-DERIVED ground (the given artifact or the elicited/ruled note) and that ground is cited — re-reading the agent's own synthesis is the echo chamber this rule exists to break. By construction, not exhortation: the kb orient opens every session with the topic router in sight.

7. Capture — the day's decisions reach the ledger before they evaporate. At a user-signed closing ("chiudiamo"), one sweep question — carrying its own inline result: "today I recorded X and Y — any other decisions from today?" — reaches even the decisions taken outside the session, which no transcript search could find. What surfaces lands on the existing rails (an elicited dated note, an L1 claim row) with explicit provenance; the sweep is idempotent (nothing captured twice), never creates topics, and stays silent when no one signed off. The kb orient shows notes recency at every session start — dated from note frontmatter, because file mtimes lie after a clone or worktree — so a missed capture is visible the next morning.

8. Revision — documents read as current state. Incorporating new knowledge into an existing document is a full re-read and a body rewrite, not a stack of dated deltas: anchored edits are each correct while the document as a whole rots. The doctrine keeps history in the Diary (past entries never rewritten), leaves claim tables to reconciliation and graph edges to the taxonomy, and runs per document even in a multi-document pass. Born from a real field post-mortem: twelve documents realigned by append, every untouched sentence left standing as printed truth.

Deliberately absent: any per-node coverage or completion state. gaps: says what a node lacks; nothing collects it into a dashboard. A source does record how far it has been read, but on its own sidecar and nowhere else — the corpus index prints that fact for every artifact, including the finished ones, because a list of only what is behind is the dashboard this method refuses.

Key features

• Risk-proportional triage, measured in knowledge and never in files: one claim row → propagating a fact already settled → a new knowledge unit (a source ingested, a node created or superseded, the hierarchy moved). Carrying one settled fact into eight documents is small; one claim that re-parents a node is not. On a live front, a new source or statement within an open unit's declared scope is an ingestion step of that unit — recorded on the ledger at once — while the rewrite of dependent documents, the registry and the full check run once, at a closure the practitioner calls. A Write Triggers table maps each knowledge event to exactly one destination.
• Portable knowledge: export bundles a subgraph together with the bytes its claims cite — a closure, not a selection, because a claim whose source cannot be reopened is model knowledge arriving by another route. import merges it into another project additively: it never overwrites a node and never deletes, and claims already present are recognised by id rather than by comparing text, since the same artifact cited at the same span mints the same id in every project. Knowledge crosses the project boundary; authority does not — an imported ruling arrives as prov: IMPORTED on a renamed copy of its note that names its origin, keeps its original basis:, and the question it had closed is open again (CONTESTED) until you ratify it with a ruling of your own.
• Several people, one project: the workstream registry (audit/handoff.md) is generated from one file per open workstream, so two people opening or closing two workstreams on two branches edit two different files and their merge is clean. Row-per-workstream alone was not enough — a file-global Date: header defeats row-level ownership — so the header is derived from the sources and no writer touches it. The generated view can still conflict; that conflict is resolved by re-running index, never by hand, and validate refuses CLEAN until the file matches its sources. The append-only review log gets merge=union (a built-in driver, no per-clone configuration). It all works with no VCS at all: it is files and a generator.
• Vision-guided governance: Standalone projects use ai_docs/vision/; Hybrid projects use devPNT M-VISION as the milestone north star. DRAFT informs, APPROVED binds, promotion is the user's alone. Every Vision, the M-VISION included, is written only after a six-question owner interview and your explicit approval of a one- or two-sentence north star in your own words — the agent never writes one alone.
• Independent review, twice: the design before it is implemented, the result before it is declared done — fresh-context subagent > one-shot run > a declared self-pass, 3 rounds max, one log line each, and a PASS is invalid on "found nothing". After the design review passes, the owner approves the design before any drafting.
• Question discipline: a real doubt is asked when it emerges, before its answer is written, with the pros and cons of each option; a choice whose pros clearly win is taken with the weighing written next to it. A question is legal only when the agent searched first, names the search with its result, and names the decision it unblocks.
• Verbatim request record: every L3 starts audit/requests/REQUEST_[topic].md before the Vision Gate — the practitioner's own words and every later decision (answers, approvals, costs, rulings), append-only and redacted for secrets — so analyses cite what was asked instead of paraphrasing it, and reviews check owner statements against it.
• Operative guides + agent-global KB: distil user-provided indications into source-faithful GUIDE_*.md (source_kind: document) — verbatim snapshot plus hash, so drift is detected mechanically.
• Mechanical checks: check, validate, index, graph, corpus, claim-id, anchor, export, import, adopt (dry run: document guides on snapshots and what moving them into the corpus involves), inventory <path> (each project file under a path against the corpus: INGESTED, INGESTED_EARLIER, EXCLUDED, NOT_EXAMINED, SKIPPED; orient prints an upper bound of the files never examined), stale (spine staleness plus ## claims -- superseded-cited documents, expired valid windows, superseded derivation chains), plus the spine's mark/benefit/gate/plan/orient/migrate. benefit reports what the review gates have already caught, beside what the doctrine costs to read; it always exits 0 and carries no verdict. The graph and corpus checks verify spans against the stored extraction, recompute every id, refuse cycles and unreachable nodes, and enforce CONTESTED symmetry.
• Installed support files: Claude, Codex, Gemini and Google Antigravity receive the full skill folder — SKILL.md, templates.md, taxonomy.md, distillation.md, reconciliation.md, guides.md, vision.md, elicitation.md, review.md, dispatch.md, routing.md, ENFORCEMENT.md, memory.md, and the validator's three files, scripts/sdlc_check.py + scripts/sdlc_core.py + scripts/knowledge.py (copy all three) — plus the docs site generator scripts/docs_site.py and its page docs_site/, and the LICENSE and NOTICE it ships under.
• Docs site (scripts/docs_site.py --root <project> [--open] [--zip <file>]): a static, offline, read-only website of what the agent reads in the project — reading guide, Vision, rules, documents, open work with each next step, analyses and, with a knowledge base, the topic map, each fact with its exact source passage, and the source documents. Written to .docs-site/ (added to .gitignore on the first run), outside ai_docs/; nothing is ranked or recommended.

Shared project memory

All four lenses include project memory by default; install the lens you need, not a second skill just for recall. index registers guides, decisions and plans in the docs root's memory/INDEX.md, linking originals without copying them. recall "onboarding" finds related metadata across domains; optional topics: [onboarding] links documents by subject. Read the originals for authority, status and evidence: discovery is not approval or proof of implementation.

Registration happens at index/documentation closure, not through a background watcher. Existing projects acquire the catalog on their next index; recall also sees live metadata. The KB lens remains the specialist for ingestion and taxonomy. Marketing retains its numerical validators. See the skill's memory.md. Vendoring requires all three files: the entry point, sdlc_core.py, knowledge.py.

Installation

npm install -g @antoneeo/kb-agentic-skill@latest

That is enough — the package's postinstall runs the installer. If your npm blocks install scripts (--ignore-scripts, some CI/pnpm setups), run it by hand:

kb-agentic-install-skill

The command is on your PATH only after a global (-g) install; after a local npm i, invoke it as npx kb-agentic-install-skill.

The installer copies skills/kb-agentic-skill/ recursively into native skill locations:

• Claude Code: ~/.claude/skills/kb-agentic/
• Codex: ~/.codex/skills/kb-agentic/
• Gemini CLI: ~/.gemini/skills/kb-agentic/
• Google Antigravity: ~/.gemini/config/skills/kb-agentic/ (override the home with ANTIGRAVITY_HOME)

Restart the relevant agent, or reload skills where the CLI supports it.

Initialize a project:

kb-agentic-init

Run it inside a project to create ai_docs/, Vision stubs awaiting your interview, strategic docs, audit plan, and agent protocol files (AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules).

Installing or updating the npm package wires the session-orientation hook machine-wide (user-level ~/.claude/settings.json, Claude Code with Python): every project with a docs root greets its agent already oriented, and removing the entry is a standing opt-out that no update ever overrides. init still wires per-project where that is the better shape (a vendored validator, a shared team file), so an agent opening the project is handed the triage line, the guide router, the workstream registry and the reading guide (with pointers to the manifest) before it does anything — instead of only when it remembers to look. That wiring used to be a manual step documented in ENFORCEMENT.md; being manual, it was skipped, and a project could run fully governed with an agent that never met the process.

The hook command names a validator, so where that validator lives decides which file gets it: a repo that vendors it gets a repo-relative command in the shared .claude/settings.json (portable — commit it); otherwise the path is machine-specific and goes to the git-ignored .claude/settings.local.json, and each teammate runs init once. Re-running init never duplicates the hook, and a hook whose validator no longer resolves is reported as broken with the correction rather than counted as installed. check prints a one-line note when a machine has no orientation hook at project or user level (or a dead one), and an opt-in per-turn reminder exists for long sessions: sdlc_check.py remind, one constant line via UserPromptSubmit -- documented in ENFORCEMENT.md par.4, never wired by default.

The family: four lenses, one spine

The four lenses ship the common validator core and knowledge-integrity engine. When two live in the same project, routing.md decides which lens owns a given piece of work. Marketing uses its numerical checks, and course creator checks the instructional graph and references. A course may use KB sources without making the KB topic graph its prerequisite graph.

Standalone vs Hybrid

• Standalone — ai_docs/ is the source of truth: vision, topics, corpus, audit, handoff.
• Hybrid with devPNT — devPNT governs M-VISION, Master Plan, Action Plan and versioned artifacts; ai_docs/ stays as readable context, fallback and shadow. Divergence between your request, the local Vision and the M-VISION is surfaced before any work.

Created By

Created by Antonio Pinto (GitHub).

License

Apache-2.0 — the full terms are in the LICENSE file, the attribution in NOTICE. Copyright 2026 Antonio Pinto.

If you redistribute this skill, or a version you modified, keep LICENSE and NOTICE with it.

Using the skill in your own project carries no obligation: the documents it creates or templates there are yours, and so is a copy of the validator and its tests placed in that project to check its own documents.

Versions up to 1.16.0 were released under the MIT license and remain available under it.

If you use the skill in commercial work, a mention on your product page or website is appreciated. It is a request, not a condition of the license. A ready-made badge:

[![Made with kb-agentic](https://img.shields.io/badge/made%20with-kb--agentic-blue)](https://www.npmjs.com/package/@antoneeo/kb-agentic-skill)

Which model to run it on

The skill names capability tiers, never providers — a model name in doctrine rots at the next release. The binding is yours to make, and the rule is one line:

A session's floor is the highest floor among the roles it performs itself.

Authoring a governed artifact — the vision, the analysis, the use cases, the threat model — is a deep-tier role: its output is judgement, and nothing downstream scores it. So a session that will DESIGN wants your strongest model. A session that only executes an already-approved plan, or does small maintenance, can sit a tier lower. The cheapest tier is the wrong choice for the main session whatever the task, because the failure there is not a wrong answer — it is silently not applying the process: a triage never run, a router verdict declared without the lookup, a gate nobody noticed. That failure is invisible to every check in here.

The reviewer's tier is not automatically yours. On some clients a subagent inherits the session's model; on others it takes one from its own definition, so a strong session can be reviewed by a weak one — and a weak session can buy a strong review. Set it deliberately; the model column in the review log is where the choice becomes visible.

Avoid one combination: authoring below the floor AND reviewing below the floor on the same unit. One disclosed weakness is a disclosed weakness; two is an artifact nobody competent ever read. Where your client offers nothing better, the review still runs and both facts are recorded — a disclosed worst case beats skipping the review.