kyber-weave
AGENTS.md23 starsChanged 2 months agoMITView on GitHub
Kyber-Weave governs the artifacts that shape agent behaviour. What it does and why lives in docs/ — this file is only operational rules for working in the code without breaking the repository. This covers every message to the user, every doc, commit message, PR description and code comment, and every prompt or handoff to another agent. Assume the reader is switching between several tasks and remembers nothing about this one. Write for a strong developer who is reading it for…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- dash/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- product-ownerSkill
The file
We split this AGENTS.md into the rules it gives an agent
12 rules. About 0 are common, 5 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Write for a strong developer who is reading it for the first time.
- Distinctive: line 16
No assumed context: Don't rely on earlier messages, other files or past sessions.
- Distinctive: line 21
Messages to the user: must also follow How to respond to the user.
- Distinctive: line 46
Run the tests that cover your change, plus build/lint of the touched projects, and check each run reports a non-zero test count.
- Very specific: line 72
Run the build and the targeted tests above, the task-gate skill if you are a dev agent, and the docs gates:
- Very specific: line 87
Run any KyberDash/tray test or e2e command you start yourself through scripts/proc-guard.sh run --, and run .NET commands directly via …
- Distinctive: line 101
Do not start with grep, find, or arbitrary browsing when a semantic index covers the question.
- Very specific: line 105
Code: When .codegraph/ exists, use codegraph_explore (or codegraph explore "…") before text search.
- Very specific: line 113
If .codegraph/ is missing or stale and a docs drift / codegraph tool needs it, this repository authorizes codegraph init .
- Very specific: line 121
Before docs/ greps, use Kyber-Weave MCP docs_answer_question_from_repo_documentation.
- Very specific: line 124
No CLI equivalent — fall back to docs/README.md.
- Very specific: line 137
TreatWarningsAsErrorsis on, withAnalysisMode=all: Do not add to NoWarn in Directory.Build.props without a reason you can state.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Working in this repository
Kyber-Weave governs the artifacts that shape agent behaviour. What it does and why
lives in docs/ — this file is only operational rules for working in the
code without breaking the repository.
Writing style: applies to everything you write
This covers every message to the user, every doc, commit message, PR description and code comment, and every prompt or handoff to another agent.
Assume the reader is switching between several tasks and remembers nothing about this one. Write for a strong developer who is reading it for the first time.
- Bottom line first. Open with what happened, what you found, or what you need.
- No assumed context. Don't rely on earlier messages, other files or past sessions. Give the minimum background in one line.
- Plain words. Explain every name, ID, acronym or piece of jargon the first time it appears. Never use internal labels like plan IDs or task numbers as if the reader knows them.
- Short. Cut anything the reader doesn't need in order to act or decide.
- Messages to the user must also follow How to respond to the user.
Commands
Code comments
Write few. Code that follows the coding standards needs no comments; add one only where
the code departs significantly from those standards. Public APIs are the exception: they
always get XML doc comments (///). The writing style above still applies to every comment
you do write.
The inner loop
No dev agent runs the full test suite, in or out of a Kyber-Squad run, and a cross-cutting change is no exception:
run a targeted set instead. The council's test gate and CI run the full suite. To reproduce a CI failure, run the classes or files CI reported.
A dev agent's full run is refused by the guard (best-effort; limits in the test standard): scripts/proc-guard.sh run exits 89 on an unfiltered
dotnet test, npm --prefix dash run test or cargo test, and names the targeted alternative. The
council and CI pass --council; a person at a terminal is not refused.
Inside a Squad run, your task packet names the test command and your agent rules say when to
run it. Otherwise, run scripts/fast-loop.sh while iterating: it inspects modified files and
routes to targeted checks for .NET, KyberDash, the tray crate, and governed docs. --help lists
its modes; --full and --scoped reach the test gate, so they are not for dev agents and exit 89 from a non-terminal shell. It is
not evidence and must never be cited as such (REVIEW.md).
Run the tests that cover your change, plus build/lint of the touched projects, and check each run reports a non-zero test count. The commands for each area:
- .NET:
docs/standards/test/README.md - Repository policy (scripts, workflows, gate configuration, docs prose, source scans):
tests/KyberWeave.RepoPolicy.Tests/AGENTS.md - KyberDash:
dash/AGENTS.md - Tray UI and tray crate:
dash/tray/AGENTS.md
KyberDash and tray tests, gates and e2e commands run through the process watchdog; .NET runs
directly via dotnet. Run .NET build, test and format commands directly so Roslyn/MSBuild build
servers stay warm. For KyberDash (dash/) and tray (dash/tray/) commands from the repository
root, wrap as scripts/proc-guard.sh run -- <command>. The watchdog kills the command's process
tree at an absolute cap (exit 86) and fails a run that leaves children behind (exit 87). The caps
change only by flag (--max-node, --max-tree), never by environment variable. fast-loop.sh
wraps its dash/tray calls and runs .NET directly. Playwright runs only with
--config dash/playwright.isolated.config.ts, and never start the dashboard to run a test. See
Running tests safely and
ADR 0047.
Before opening a PR
A change of at most 300 changed lines (added plus removed, from git diff --numstat <base>...HEAD)
gets the quick review before its pull request is opened; a larger change gets the full pre-push
council. Both are in the code-review skill.
Run the build and the targeted tests above, the task-gate skill if you are a dev agent, and the
docs gates:
dotnet run --project src/KyberWeave.Cli -- docs validate . --merge-ready
dotnet run --project src/KyberWeave.Cli -- docs drift .review gates . is the review council's command, not a dev agent's: its test gate has no filter,
so any .NET change runs the whole product suite, scoped or not. CI runs the full suite on the PR.
Without --council, from a shell with no terminal, its full-suite gates (test, ts-test, cargo-test)
are not run: each is reported as a refused blocking failure (KW-REVIEW-033, exit 1) that means "not run
here", not a code finding. Only the code-reviewer council and CI pass --council. A scoped run still
runs the other gates; with --all a refused full-suite gate ends the run at once, with no gate started.
Run any KyberDash/tray test or e2e command you start yourself through scripts/proc-guard.sh run --,
and run .NET commands directly via dotnet. In .kyber-weave/kyber-weave.yml,
the dash ts-test gate runs through scripts/proc-guard.sh run --, while dotnet test gates
(test, test-policy) run directly via dotnet. Council gates skip gates whose include does not match changed files (KW-REVIEW-026);
see docs/code-review/architecture.md. Format, build,
test, and skill argv are the review.gates entries in
.kyber-weave/kyber-weave.yml. There is no separate
restore gate: --no-restore is omitted on format and build, so those gates restore
themselves. Release/self-updater/kyberdash
build paths: ./scripts/update-loop.sh (docs/distribution.md).
KyberDash and tray gates: dash/AGENTS.md, dash/tray/AGENTS.md.
Exploration order
Do not start with grep, find, or arbitrary browsing when a semantic index covers the question. MCP tool names may be namespace-qualified by the active harness.
<!-- CODEGRAPH_START -->Code: When .codegraph/ exists, use codegraph_explore (or codegraph explore "…")
before text search; name a file or symbol when you need line-numbered source.
<!-- CODEGRAPH_END -->In a worktree, or when the tool is not listed, run codegraph explore "…" from that
worktree's shell; read files directly only if it fails. A worktree indexes ITSELF with
kyber-weave doctor --ensure . and never shares the main checkout's index.
If .codegraph/ is missing or stale and a docs drift / codegraph tool needs it, this
repository authorizes codegraph init . at the root immediately
(repository-local only; installing CodeGraph is the user's decision). Do not ask for user
approval before that provisioning step. Before init, record git status --short and both
staged (git diff --cached) and unstaged (git diff) tracked diffs; afterwards undo only
tracked edits init introduced. Blocked or unusable init → report under GAPS and fall back;
docs drift without an index → report skipped, not passed.
Before docs/ greps, use Kyber-Weave MCP docs_answer_question_from_repo_documentation;
before contract changes, docs_find_documents_citing_code_symbol; for taxonomy,
docs_look_up_glossary_term_definition and docs_find_duplicates_conflicts_ambiguous_terms.
No CLI equivalent — fall back to docs/README.md. Never use docs/archive/ as
current guidance. The server's configuration key is kw-docs. Every answer leads with a
provenance: line carrying root=, branch=, repo=, rev=, dirty= and documents=N
(docs_get_source_repository_and_revision). Compare repo=, the repository's common git
directory, not root=: a root= that is not your own working tree's root is another worktree
of this repository, and only a different repo= means the wrong repository. branch= names the
branch the answer came from.
Non-negotiables
- Persisted plans belong in docs. Under
<docs-root>/plans/<plan-index>; no hidden tool folders. Committed, not untracked — same for archived plans under<docs-root>/archive/plans. TreatWarningsAsErrorsis on, withAnalysisMode=all. Do not add toNoWarninDirectory.Build.propswithout a reason you can state.- Rule ids are permanent (
KW-*). Add new ids; never reuse or renumber. - Editing anything under
docs/means re-runningdocs validateanddocs drift. The corpus stays at zero findings. - Do not widen the ontology to make a failure disappear. Fix the document.
- Todos: capture authorized deferred work under
<todo-index>. A review finding does not authorize a repository change by itself.
KyberDash
The tray and web dashboard are display layers only — no isolated feature logic,
schedulers, or jobs; shared engine, one datastore, one /api/kyber/* API. See
docs/rules/kyberdash-display-layer.md and
dash/AGENTS.md. KyberDash is first-party (ADR 0020); upstream references stay only in dash/LICENSE and dash/THIRD_PARTY_NOTICES.md.
Dependencies
Core dependency policy (Markdig, YamlDotNet, sqlite3 CLI for CodeGraph): see
src/KyberWeave.Core/AGENTS.md.
Where to go next
| Working on | Read |
| Writing C# anywhere in this repository | docs/standards/csharp/README.md, the path declared as <csharp-coding-standard> below |
The engine — KyberWeave.Core, KyberWeave.Core.Docs and KyberWeave.Core.Squad | src/KyberWeave.Core/AGENTS.md |
| CLI commands and output | src/KyberWeave.Cli/AGENTS.md |
| Installing, updating, or configuring Kyber-Weave or KyberDash | docs/cli-command-surface.md — every verb and flag, the exit-code contract, and the canonical flows |
| The MCP server | src/KyberWeave.Mcp/AGENTS.md |
KyberDash gates (dash/web and dash/tray are display layers) | docs/rules/kyberdash-display-layer.md, dash/AGENTS.md |
KyberDash architecture and runbook (dash/web and dash/tray are display layers) | docs/rules/kyberdash-display-layer.md, dash/AGENTS.md, docs/dash/architecture.md, docs/dash/runbook.md |
| Tests | The path declared as <test-coding-standard> below, then tests/KyberWeave.Tests/AGENTS.md for fixtures |
| Authoring documentation | docs/documentation-ontology.md, and the kyber-docs-authoring skill in .apm/skills/ |
House style
Match the surrounding code: comments explain why, not what; diagnostics carry a hint when a nearest-match suggestion is computable.
Protecting hand-authored instruction files
AGENTS.md and CLAUDE.md here are hand-authored, with one exception: the Config Reg
block below is generated. docs init rewrites everything between its two markers from
.kyber-weave/kyber-weave.yml on every run, and touches
nothing outside them. Edit the configuration, not the block. docs validate reports a stale
one as KW-CONFIG-REG-002.
apm.yml deliberately pins targets: [agent-skills]. Do not remove that pin or
add .apm/instructions/: an unscoped compile can overwrite the hand-authored instruction
files. The configuration documents the rationale and why the pin does not constrain consumers.
<!-- KYBER_WEAVE_CONFIG_REG_START -->Repository Configuration & Paths Registry (Config Reg)
Agents and skills look up the following properties to find the documentation and references that belong to this repository.
<docs-root>:docs<documentation-index>:docs/README.md<documentation-ontology>:docs/documentation-ontology.md<component-catalog>:docs/catalog.md<standards-root>:docs/standards<csharp-coding-standard>:docs/standards/csharp/README.md<test-coding-standard>:docs/standards/test/README.md<typescript-coding-standard>:docs/standards/typescript/README.md<rust-coding-standard>:docs/standards/rust/README.md<tauri-coding-standard>:docs/standards/tauri/README.md<go-coding-standard>:docs/standards/go/README.md<github-actions-coding-standard>:docs/standards/github-actions/README.md<plan-index>:docs/plans/README.md<specification-index>:docs/specs/README.md<todo-index>:docs/todo/README.md<adr-index>:docs/adr/README.md<rules-index>:docs/rules/README.md<reference-index>:docs/reference/README.md<review-guidance>:REVIEW.md<onboarding>:done<autonomy>:autonomous
Skills and other portable instruction files SHALL reference these paths by the
property name above — "the path declared as <component-catalog>
in the repository root AGENTS.md" — rather than embedding a relative link that
traverses out of the skill's own directory. A skill written that way stays correct
when this repository moves something; only this registry has to change.
Generated by kyber-weave docs init from .kyber-weave/kyber-weave.yml. Edit that
file rather than this block: everything between the markers is rewritten on the next
run.
<!-- KYBER_WEAVE_CONFIG_REG_END -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

