agentleFS
dpalferydpalfery/kyber-weave/AGENTS.md

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.

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
  1. Distinctive:

    Write for a strong developer who is reading it for the first time.

    line 13
  2. Distinctive:

    No assumed context: Don't rely on earlier messages, other files or past sessions.

    line 16
  3. Distinctive:

    Messages to the user: must also follow How to respond to the user.

    line 21
  4. Distinctive:

    Run the tests that cover your change, plus build/lint of the touched projects, and check each run reports a non-zero test count.

    line 46
  5. Very specific:

    Run the build and the targeted tests above, the task-gate skill if you are a dev agent, and the docs gates:

    line 72
  6. Very specific:

    Run any KyberDash/tray test or e2e command you start yourself through scripts/proc-guard.sh run --, and run .NET commands directly via …

    line 87
  7. Distinctive:

    Do not start with grep, find, or arbitrary browsing when a semantic index covers the question.

    line 101
  8. Very specific:

    Code: When .codegraph/ exists, use codegraph_explore (or codegraph explore "…") before text search.

    line 105
  9. Very specific:

    If .codegraph/ is missing or stale and a docs drift / codegraph tool needs it, this repository authorizes codegraph init .

    line 113
  10. Very specific:

    Before docs/ greps, use Kyber-Weave MCP docs_answer_question_from_repo_documentation.

    line 121
  11. Very specific:

    No CLI equivalent — fall back to docs/README.md.

    line 124
  12. Very specific:

    TreatWarningsAsErrors is on, with AnalysisMode=all: Do not add to NoWarn in Directory.Build.props without a reason you can state.

    line 137

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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.
  • TreatWarningsAsErrors is on, with AnalysisMode=all. Do not add to NoWarn in Directory.Build.props without a reason you can state.
  • Rule ids are permanent (KW-*). Add new ids; never reuse or renumber.
  • Editing anything under docs/ means re-running docs validate and docs 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 onRead
Writing C# anywhere in this repositorydocs/standards/csharp/README.md, the path declared as <csharp-coding-standard> below
The engine — KyberWeave.Core, KyberWeave.Core.Docs and KyberWeave.Core.Squadsrc/KyberWeave.Core/AGENTS.md
CLI commands and outputsrc/KyberWeave.Cli/AGENTS.md
Installing, updating, or configuring Kyber-Weave or KyberDashdocs/cli-command-surface.md — every verb and flag, the exit-code contract, and the canonical flows
The MCP serversrc/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
TestsThe path declared as <test-coding-standard> below, then tests/KyberWeave.Tests/AGENTS.md for fixtures
Authoring documentationdocs/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 -->

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.