kyber-weave

# Kyber-Weave **End-to-end agent governance and deployment system.** Kyber-Weave is the unified control plane for engineering agent ecosystems. It couples rigorous documentation governance (DocGraph), supply-chain skill and agent linting (ContextHygiene), atomic multi-harness deployment (Kyber-Squad), and unified CI diagnostics into a cohesive platform for teams operating coding agents at scale. ```bash curl -fsSL https://raw.githubusercontent.com/dpalfery/kyber-weave/main/scripts/install.sh | sh ``` Installs the latest release as self-contained binaries in `~/.local/bin` — no .NET runtime, no sudo, checksum-verified: the `kyber-weave` CLI, the `kyber-weave-mcp` server, and, from releases that publish it, the [`kyberdash`](docs/dash/README.md) observability binary. Already installed? `kyber-weave update`. [Install details →](docs/install.md) **Windows users:** download the `.zip` archives from [Releases](https://github.com/dpalfery/kyber-weave/releases), verify the SHA-256 hash, and extract them to a directory on your PATH. See [Verifying a download](docs/install.md#verifying-a-download) and [Windows: unsigned binaries and SmartScreen](docs/install.md#windows-unsigned-binaries-and-smartscreen) for detailed guidance. > **This repository governs its own documentation.** Everything under [`docs/`](docs/) > carries conformant frontmatter and passes `kyber-weave docs validate` and `docs drift` > with zero findings. If the ontology were unusable, you would see it here first. --- ## Five Premier Features Kyber-Weave provides five integrated features for agent governance and lifecycle management: 1. **[DocGraph (Kyber-Docs)](#feature-1--docgraph)** — Typed, governed documentation corpus, drift detection, integrity analysis, and MCP graph retrieval. 2. **[ContextHygiene](#feature-2--contexthygiene)** — Skill and harness agent linting, routing readiness scoring, parity drift detection, and security scanning. 3. **[Kyber-Squad](#feature-3--kyber-squad)** — Unified multi-harness deployment and lifecycle control plane across 10 IDE/CLI harnesses with transactional recovery. 4. **[CI Pipelines](#feature-4--ci-pipelines)** — Unified diagnostic engine with stable `KW-*` rules, SARIF reporting, and GitHub Actions workflows. 5. **[KyberDash](#feature-5--kyberdash)** — Local telemetry observability and context tuning for agentic workflows, across three local surfaces. --- ## Feature 1 — DocGraph A folder of Markdown is not a corpus. DocGraph makes documentation **typed, owned, cross-referenced, and queryable** — then holds it to that. **The opinion.** Eleven closed doc-types, four statuses, a required-key matrix that varies by type, and a catalog that is the authoritative vocabulary for components and owners. A `component` cannot be invented one document at a time until nobody can say how many exist. [The ontology →](docs/documentation-ontology.md) **The enforcement.** `docs validate` checks conformance. `docs drift` resolves every documented symbol against a live code index, which catches the failure nothing else does: after a rename, **prose still reads correctly**. No linter, reviewer, or test notices — only resolution does. [Governance →](docs/docgraph/governance.md) **The payoff.** An in-memory graph that ranks on *declared identity* rather than word frequency, demotes plans and superseded documents so an agent is not handed a closed work artifact as current guidance, and returns budgeted excerpts that name what they omitted. [Retrieval →](docs/docgraph/retrieval.md) ```bash kyber-weave docs init . # scaffold config/catalog/ontology, protect local cache, deploy the skill kyber-weave docs validate . kyber-weave docs drift . kyber-weave docs integrity-check . # advisory duplicate/conflict/terminology findings kyber-weave docs export-graph . --out ./build/doc-graph ``` ### Adopting an existing tree `docs init` does the mechanical half — host config, the catalog that supplies the component and owner vocabularies, the ontology reference every diagnostic points at, and the narrow ignored cache path analysis needs before it can persist verdicts or vectors. It then deploys the **`kyber-weave-docs` skill** through [APM](https://microsoft.github.io/apm), defaulting to `.agents/skills/` so every APM-supported client picks it up. The skill does the judgment half: choosing `doc-type`, verifying that `code-refs` symbols actually resolve, and retrofitting a whole tree as `status: draft` so a partially adopted corpus degrades gracefully rather than serving unreviewed metadata as current guidance. [Adoption guide →](docs/docgraph/onboarding.md) ### The MCP server `kyber-weave-mcp` is where the feature is actually consumed. Point any MCP client at it: | Tool | What it does | |---|---| | `docs_explore(query, maxDocs, charBudget)` | Ranked documents with frontmatter identity, prose within budget, and code joins as `symbol → file:line` | | `docs_for_symbol(symbol)` | Reverse lookup: documents whose `code-refs` **formally claim** a symbol — not those that merely mention it | | `docs_analysis_candidates(kind, cursor, limit, charBudget)` | Capped, stable, read-only duplicate/conflict/terminology evidence with local cost metrics | | `docs_glossary(term)` | Capped, read-only lookup of managed term senses, scopes, and aliases | It is a separate binary from the CLI on purpose: JSON-RPC owns stdout and Spectre.Console also writes there, so separate entry points make stream corruption structurally impossible. [MCP runbook →](docs/docgraph/mcp-runbook.md) ### Documentation analysis and terminology `docs integrity-check` extracts line-addressable claims from paragraphs, list items, table rows, and code fences, then uses DocGraph and one-hop CodeGraph relationships before bounded lexical search. Exact duplicates are deterministic; potential conflicts and distinct term senses can be exported for agent review and imported as reusable, content-addressed verdicts. Source documents are never rewritten. ```bash kyber-weave docs integrity-check . kyber-weave docs review export . --out candidates.json kyber-weave docs review import . --in verdicts.json kyber-weave docs glossary . # preview kyber-weave docs glossary . --write # merge proposals into one reference document ``` Embeddings are off by default. When enabled, endpoints must resolve only to loopback, redirects are disabled, and no document text is sent unless the local SQLite cache is safely ignored. Default hybrid search avoids all-pairs work; `high-recall` is an explicit quadratic first pass outside the default latency target. [Analysis and review →](docs/docgraph/analysis.md) ### One external dependency, and it's optional `docs drift` and `docs export-graph` resolve symbols against a **CodeGraph** index at `.codegraph/codegraph.db`. CodeGraph is a separate, host-owned tool — Kyber-Weave opens that index read-only and never writes to it. Without an index, retrieval and `docs validate` work completely; only the code-join features degrade. [Architecture →](docs/docgraph/architecture.md) --- ## Feature 2 — ContextHygiene Skills and harness agent definitions are supply-chain artifacts: their text becomes instructions. ContextHygiene governs both, against different sources of truth. | Branch | Answers to | Commands | |---|---|---| | Skills | the Agent Skills open-format spec | `validate`, `lint`, `scan`, `route`, `catalog`, `pack`, `new` | | Agents | its own sibling copies across six harnesses | `validate`, `sync-check`, `scan`, `catalog` | `skill lint` scores routing readiness out of 100 with an auditable per-dimension breakdown, because a spec-valid skill that never fires is worthless and the spec has nothing to say about that. `skill route` turns "which skill fires?" into a deterministic, offline regression test that needs no API key in CI. `agent sync-check` catches the role that was fixed in `.claude` and left broken in `.cursor`. [Skill governance →](docs/context-hygiene/skills.md) · [Agent governance →](docs/context-hygiene/agents.md) · [Security scanning →](docs/context-hygiene/security-scanning.md) --- ## Feature 3 — Kyber-Squad Managing agent roles and skill sets across disparate developer environments leads to configuration drift, broken permissions, and fragmented workflows. Kyber-Squad provides a **single, unified lifecycle and deployment control plane** for deploying 21 canonical agents and 24 skills across 12 coding harnesses. **The canonical tree.** Maintains 21 canonical agent bodies and 24 canonical skills under [`products/kyber-squad/`](products/kyber-squad/README.md), governed by strict schemas, model profiles, and capability profiles. Generated target trees and APM packages are never tracked. **The compiler & lowering engine.** Normalizes definitions into AgentIR, enforces a semantic permission lattice (`deny < ask < allow`), and applies deterministic role-skill lowering (with shared conductor identities and prefixed `role-*` collision namespaces) for harnesses without native agent primitives. **Transactional deployment.** Atomic, write-ahead deployments with cross-process OS mutex leasing (`kyber-weave-squad-<root-key>`), same-filesystem no-overwrite leaf claim/publish, and compare-and-restore recovery that safely preserves local operator modifications. ```bash kyber-weave squad install # auto-detects targets across 12 harnesses kyber-weave squad update # updates deployments while preserving local edits kyber-weave squad status # verifies file integrity and reports drift kyber-weave squad doctor # checks toolchain prerequisites kyber-weave squad pack --format all --out ./dist # builds APM and Agent Plugins release packages ``` | Harness Class | Supported Targets | |---|---| | Native Agents | Codex (`.codex`), Cursor (`.cursor`), Claude (`.claude`), GitHub Copilot (`.github`), OpenCode (`.opencode`), Kilo (`.kilo`), Pi (`.pi`), Factory Droids (`.factory`) | | Role-Skill Lowering | Antigravity, Warp | [Adoption & usage guide →](docs/kyber-squad/onboarding.md) · [Architecture →](docs/kyber-squad/architecture.md) · [Requirements & degradation →](docs/kyber-squad/requirements.md) --- ## Feature 4 — CI Pipelines One diagnostic engine behind all artifact classes: stable `KW-*` rule ids that never get renumbered, four output formats including SARIF for GitHub code scanning, and severity gating tuned per branch so adopting scanning does not immediately break every host build. [Architecture →](docs/ci-pipelines/architecture.md) · [Rule reference →](docs/ci-pipelines/rule-reference.md) · [Workflow runbook →](docs/ci-pipelines/workflows-runbook.md) · [Templates](templates/github-actions/) --- ## Feature 5 — KyberDash An agent session is a black box: hundreds of thousands of tokens spent per run with no view of what went to system prompts, tool schemas, or conversation history, and no way to tell a slow tool call from a circular subagent delegation. KyberDash makes that spend **observable and tunable, entirely on your machine** — no telemetry leaves localhost. **One canonical store.** An OTLP receiver on `127.0.0.1:4318` ingests traces and logs into a single SQLite store at `~/.kyberdash/canon.db`, normalizing every supported harness into one span-shaped record. Sessions, runs, execution trees, and findings are derived projections over it, rebuildable without re-ingesting. **Progressive-disclosure diagnostics.** A six-level spine from the cross-harness Context Doctor down to the individual context item: per-turn token breakdown (fresh input, cache read, cache creation, output), context composition by part type, ranked tool-schema cost with unused-schema waste, hierarchical execution timelines, and an inspector that shows the unclipped assembled turn. **Three local surfaces.** Terminal report (`kyberdash report`), browser dashboard (`kyberdash web`), and a macOS/Windows tray (Tauri 2) — all reading the same store. ```bash kyberdash kyber otel # OTLP receiver on 127.0.0.1:4318 kyberdash web # browser dashboard on :4747 kyberdash report # terminal report ``` Installed by the same one-line installer as the CLI, from releases that publish it. KyberDash began as a fork of the MIT-licensed CodeBurn project and is now first-party code under `dash/` ([ADR 0020](docs/adr/0020-kyberdash-one-time-fork.md)). [Overview →](docs/dash/README.md) · [Architecture →](docs/dash/architecture.md) · [Runbook →](docs/dash/runbook.md) · [Telemetry inventory →](docs/dash/telemetry-inventory.md) · [Install →](docs/install.md#kyberdash-and-the-version-floor) --- ## Documentation Full corpus in [`docs/`](docs/README.md). Start with [the ontology](docs/documentation-ontology.md) if you want to understand the opinion, or [install](docs/install.md) if you want to run it. ## Architecture ``` src/ KyberWeave.Core/ shared engine Docs/ Feature 1 — parsing, search, validation, export Skills/ Agents/ Feature 2 — governance per artifact class Security/ Feature 2 — shared instruction-surface scanner Squad/ Feature 3 — multi-harness deployment engine & transaction store Diagnostics/ Feature 4 — rule ids, severities, reports CodeGraph/ read-only port over the CodeGraph index Configuration/ Text/ Parsing/ KyberWeave.Cli/ kyber-weave — skill | agent | squad | docs | update KyberWeave.Mcp/ kyber-weave-mcp — stdio MCP server products/ kyber-squad/ canonical 21 agents, 24 skills, profiles, and schemas dash/ Feature 5 — KyberDash, first-party since a one-time fork of CodeBurn src/ dash/ CLI engine, provider parsers, and the web dashboard kyber/ analyzers, OTLP receiver, canon store tests/KyberWeave.Tests/ .apm/skills/ kyber-weave-docs — the authoring skill, shipped as an APM package samples/ exemplar and deliberately bad skills; routing eval set templates/github-actions/ host gate workflows docs/ this project's own governed corpus ``` Hosts adapt the defaults with [`.kyber-weave/kyber-weave.yml`](docs/configuration.md). ## Develop from source Requires .NET SDK 10 (`global.json`). ```bash dotnet restore KyberWeave.sln dotnet build KyberWeave.sln -c Release dotnet test tests/KyberWeave.Tests/KyberWeave.Tests.csproj -c Release ``` ## Caveats - **The Agent Skills spec is young.** `allowed-tools` is experimental and **not a security control**. - **The routing simulator approximates, not replicates** a real orchestrator. - **`docs drift` needs a CodeGraph index and the `sqlite3` CLI.** - **`docs init` expects [APM](https://microsoft.github.io/apm)** to deploy the authoring skill. Both it and CodeGraph are *expected* dependencies — Kyber-Weave detects them and degrades with a message, but never installs anything on your machine. - **`squad install` and `squad pack` rely on [APM](https://microsoft.github.io/apm)** toolchain capabilities for multi-harness compilation. - **Security scanning is necessary but not sufficient** — pair it with human review. - **The document index is rebuilt, never persisted.** Editing one document rebuilds the whole corpus; comfortable at hundreds of documents, worth revisiting at thousands. - **Documentation analysis persistence is a separate local cache.** `.kyber-weave/cache/docs-analysis.sqlite3` stores reusable vectors and verdicts only when the narrow cache path is safely ignored; it is never a source of retrieval prose. - Some agent Core APIs exist without CLI verbs (`agent route` / `lint` / `new`) — known gap. > **Naming note.** "Kyber" collides with CRYSTALS-Kyber / ML-KEM, the NIST post-quantum KEM > standardised as FIPS 203. In a repository running Snyk, Trivy, CodeQL and Semgrep, > searches and scan output for "kyber" will surface both. "Weave" is safely > non-cryptographic — unlike Lattice, Module, Ring or Key, which read as the algorithm itself. ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). Security reports go through [GitHub Security Advisories](SECURITY.md) — not public issues. ## Licence and attribution MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE). **Thank you, [SkillForge](https://github.com/bonaniibm/SkillForge).** Kyber-Weave's skill-governance feature — `skill validate` / `lint` / `scan` / `route` / `catalog` / `pack` / `new` — originated as **[SkillForge](https://github.com/bonaniibm/SkillForge)** ([bonaniibm/SkillForge](https://github.com/bonaniibm/SkillForge)), an MIT-licensed open-source project by the SkillForge contributors (`Copyright (c) 2026 SkillForge contributors`). That work was absorbed into this repository and is maintained here; there is no ongoing upstream sync. The MIT licence under which it was received is retained in [LICENSE](LICENSE) and explained in [NOTICE](NOTICE). Built on [Markdig](https://github.com/xoofx/markdig), [YamlDotNet](https://github.com/aaubry/YamlDotNet), [Spectre.Console](https://spectreconsole.net/), and the [ModelContextProtocol](https://github.com/modelcontextprotocol/csharp-sdk) C# SDK.