instructions: the agent speaks the KB language in chat - AGENTS.md § Conversation language, and instructions sync compiles the language tag into every published SKILL.md (#116); 10.0.0-beta.9
CI / verify (push) Successful in 8m6s
CI / pwsh (push) Successful in 2m50s
Release / release (push) Successful in 33s
Release / wiki-mirror (push) Skipped

Files changed:
- AGENTS.md
- CHANGES.md
- VERSION
- docs/explanation/language-boundaries.md
- docs/reference/commands/types-instructions-and-docs.md
- instructions/CONTRACT.md
- instructions/dev/stack-build/SKILL.md
- instructions/dev/stack-close/SKILL.md
- instructions/dev/stack-dev/SKILL.md
- kb/CONVENTIONS.md
- kb/CONVENTIONS.md.template
- tools/CONTRACT.md
- tools/chemenu/commands/doctor.py
- tools/chemenu/commands/instructions_cmd.py
- tools/chemenu/tests/test_doctor.py
- tools/chemenu/tests/test_instructions_cmd.py

Co-Authored-By: Claude Code <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
This commit is contained in:
torbenandClaude Code committed 2026-10-12 06:57:51 +02:00
1 parent c06bde2e95
commit 0f0a5799fd
16 files changed
+385 -54

No files matched your search

+19 -10
View File
@@ -13,6 +13,7 @@ maintained permanently; anything mechanical is done by `tools/wikitool`, never b
- [Bootstrap](#bootstrap)
- [Invariants](#invariants)
- [Conversation language](#conversation-language)
- [File naming](#file-naming)
- [Personalization](#personalization)
- [Environment](#environment)
@@ -81,6 +82,13 @@ These hold regardless of which skill is active or which part of this file is in
8. **One rule, one place.** Every normative rule lives at exactly one location; everywhere
else links to it. Writing a second copy is how the two start disagreeing.
## Conversation language
Write every message to the user - progress notes and the closing report included - in the KB
language: `language:` in `kb/CONVENTIONS.md`'s frontmatter, read at session start. This holds
whatever language a file, a tool's output or a source is in; quoted commands, paths and field
names stay as they are.
## File naming
What a file is called says who it is for and how it is loaded. This is a rule, not a habit;
@@ -111,9 +119,10 @@ documents. What it may not carry is the same content twice - a README that resta
contract is a second copy that drifts. `docs verify` enforces the specific case that already
happened once: no README may hold a copy of the `wikitool` command table.
**Two languages, and which is which.** Which one a line is written in follows from the *For*
**Two rules for the language of a file.** Which one a line is written in follows from the *For*
column above - who reads it - and from nothing else: not from who owns the file, and not from
whether it ever leaves this checkout.
whether it ever leaves this checkout. What an agent says in the chat is a third matter, and
has its own section: [Conversation language](#conversation-language).
1. **The control plane is written in English** - this file, `CLAUDE.md`, every `CONTRACT.md`,
everything under `instructions/`, and the type-specs for non-page artifacts. Quoted
@@ -131,20 +140,20 @@ whether it ever leaves this checkout.
moves this rule;
[docs/explanation/language-boundaries.md](docs/explanation/language-boundaries.md) has the
reasoning.
2. **An agent speaks the instance's KB language**, whatever this file is written in. The value
lives in `kb/CONVENTIONS.md`'s `language:` and nowhere else; an instruction that models a
sentence for the user writes it in English like the rest of the control plane, and the agent
says it in that language.
3. **The stack's human documentation is written in English** - `README.md`, `INSTALL.md` and
An instruction that models a sentence for the user writes that model in English like the rest
of the control plane; the agent says it in the KB language ([Conversation
language](#conversation-language)).
2. **The stack's human documentation is written in English** - `README.md`, `INSTALL.md` and
everything under `docs/` - whatever an instance's `language:` says. It is the
same text in every instance, and the parts of it that are generated come from English
sources, so there is no instance whose language it could follow. `CHANGES.md` is a log, not
documentation, and is not covered.
Nothing checks any of the three mechanically - a stop-word scan would flag the quoted vocabulary
above and miss a translated paragraph that reads cleanly. They are held up by whoever writes the
Nothing checks either mechanically - a stop-word scan would flag the quoted vocabulary above
and miss a translated paragraph that reads cleanly. They are held up by whoever writes the
text, which is why [instructions/CONTRACT.md](instructions/CONTRACT.md) § "Writing an
instruction" names the first two at the step where that happens.
instruction" names the first one at the step where that happens.
**`docs/` carries no normative sentence.** It holds the stack's human documentation - tutorials,
how-to guides and reference, and under `docs/explanation/` why the stack is built the way it is: