Kyber-Weave

Agentic coding framework and meta-harness. Plan. Build. Tune.

Kyber-Weave turns coding assistants into a coordinated engineering team. It combines specialist agents and reusable skills with durable project knowledge, explicit delivery workflows, quality gates, and local observability.

As a meta-harness, Kyber-Weave provides a shared workflow, knowledge, and quality layer across coding harnesses such as Claude Code, Codex, GitHub Copilot, Cursor, and OpenCode. People own the requirements, decisions, and approvals. Agents plan, build, test, review, and maintain the project documentation.

Plan. Build. Tune.

• Plan — turn an idea into a reviewed plan or specification grounded in project knowledge.
• Build — coordinate specialists through implementation, tests, review, and documentation closeout.
• Tune — inspect token and context costs, execution traces, and run comparisons to improve agent instructions and workflows.

Kyber-Weave provides the framework around the coding harnesses your team already uses: a canonical agent team, portable skills, project knowledge, workflow orchestration, automated quality checks, and local evidence about agent runs. Start with the feature map below, or install Kyber-Weave to put the framework to work.

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 observability binary. This one-liner and the Windows .zip are the only supported install paths: npm, Homebrew, and dotnet tool are not. Already installed? kyber-weave update, which also updates an installed KyberDash tray. Install details → · KyberDash adoption →

Windows users: download the .zip archives from Releases, verify the SHA-256 hash, and extract them to a directory on your PATH. See Verifying a download and Windows: unsigned binaries and SmartScreen for detailed guidance.

This repository governs its own documentation. Everything under 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.

The framework, in five parts

Together, these parts cover the agent delivery loop—from durable project context, through coordinated implementation and review, to observable runs that teams can tune.

1. DocGraph (Kyber-Docs) — Give agents durable, searchable project knowledge, and keep documentation aligned with the code.
2. ContextHygiene — Check that skills and agent instructions are clear, portable, consistent, and safe to route.
3. Kyber-Squad — Deploy one canonical team of agents and skills across 13 coding harnesses.
4. CI Pipelines — Catch quality and policy problems before a change reaches a pull request.
5. KyberDash — Understand local agent runs and tune context, tools, and workflows using execution evidence.

Feature 1 — DocGraph

Agents work better when project knowledge survives beyond a chat. DocGraph turns documentation into a typed, owned, cross-referenced, searchable corpus and checks that it stays aligned with the code.

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 →

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 →

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 →

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-docs-authoring skill through 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 →

The MCP server

kyber-weave-mcp is where the feature is actually consumed. Point any MCP client at it:

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 →

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.

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 →

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 →

Feature 2 — ContextHygiene

The framework depends on skills and agent definitions that work as intended across coding harnesses. ContextHygiene checks their format, routing clarity, sibling parity, and security against the appropriate source of truth.

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 → · Agent governance → · Security scanning →

Feature 3 — Kyber-Squad

Kyber-Squad is the portable agent team at the center of the framework: 24 specialist agents and 27 reusable skills, coordinated by a primary conductor and deployed consistently across 13 coding harnesses. The workflow carries work from planning through specialist implementation, testing, review, and documentation closeout. The same canonical definitions and capability rules keep that team recognizable across harnesses.

The canonical tree. Maintains 24 canonical agent bodies and 27 canonical skills under products/kyber-squad/, 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 product-owner and bug-crusher 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.

kyber-weave squad install                    # auto-detects targets across 13 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

Adoption & usage guide → · Architecture → · Requirements & degradation →

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 → · Rule reference → · Workflow runbook → · Templates

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.

Four local views. Use the terminal report (kyberdash report), browser dashboard (kyberdash web), macOS/Windows tray (Tauri 2), or a chat app connected to kyberdash mcp as an MCP client. The chat app is the fourth view; KyberDash supplies the MCP adapter and shared engine, not the chat app. The adapter exposes eight read-only analytics tools through the shared /api/kyber/analytics/* API and canonical store. It attaches to the running engine and does not start or stop it or read the store directly.

Ask which sessions were most expensive, what filled their context, which tool schemas had high measured cost, or how cache use and delegation changed over time. Compare periods and inspect observed outcomes with supporting evidence; when data is missing or unavailable, the tools report that limitation. Search is metadata-only, and captured text requires an explicit content opt-in. Lower cost alone does not establish better work.

kyberdash kyber otel        # OTLP receiver on 127.0.0.1:4318
kyberdash web               # browser dashboard on :4747
kyberdash report            # terminal report
kyberdash web --no-open     # start or attach to the engine for MCP
kyberdash mcp               # configure the MCP client to launch this stdio server

The MCP tools are dash_status, dash_catalog, dash_query, dash_search_sessions, dash_inspect, dash_findings, dash_compare, and dash_outcomes. Register kyberdash mcp in the client’s own MCP configuration; KyberDash does not edit client configuration. Host-client integration remains not live-verified. See the client setup guide and MCP architecture and tool contract.

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).

Overview → · Adoption guide → · Architecture → · Requirements → · Runbook → · Telemetry inventory → · Install →

Documentation

Full corpus in docs/. Start with the ontology if you want to understand the opinion, or install if you want to run it. The complete verb, flag, and exit-code surface of both binaries — plus every canonical install, update, and configure flow — is in the CLI command surface.

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 | utilities | review | update
  KyberWeave.Mcp/         kyber-weave-mcp — stdio MCP server
products/
  kyber-squad/            canonical 24 agents, 27 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-docs-authoring — 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.

Develop from source

Requires .NET SDK 10 (global.json).

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