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
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:
1 parent
c06bde2e95
commit
0f0a5799fd
16 files changed
+385
-54
No files matched your search
@@ -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:
|
||||
|
||||
Reference in new issue
Block a user