Steering is how you tell the agent what your project expects before it ever reads a line of
code. You write it, the agent reads it, and the agent can never write it back — AGENTS.md,
CLAUDE.md and .tst/rules/** are refused by the filesystem tool no matter what your boundary
config says. The agent can propose an exact diff, and only your approval writes it (see
Proposed edits). Memory runs the other way: the agent writes it, you read it. Keeping those two
apart is what stops last month's decisions from being read as this month's rules.
This repository is its own example. The AGENTS.md at the root is a real steering file, read
by TST Desk the same way it reads yours.
Every worked example below is a real workspace tree that
core/tests/test_docs_steering_guide.py builds on disk and runs through the actual assembler.
The resolved stacks and prompt blocks printed here are its output, not an illustration of it.
If the assembler's behaviour drifts from this page, the suite fails.
Put an AGENTS.md at the root of your repo. Write the things a new teammate would need told
twice. Keep it under 200 lines.
That is the whole requirement. Everything else on this page is for when one file stops being enough.
Skills are not steering. A SKILL.md under .tst/skills/<name>/ (or the
user-global tree) is a catalog entry the brain can load on demand. It
never joins the steering block or the cache prefix, and the agent cannot
write any file named SKILL.md. A Claude Code skill loads with its body
unchanged and a line naming its directory; §9 lists the trees read and the
frontmatter keys.
If your repo already has a CLAUDE.md, you are already done — see §9.
Four scopes are read at the start of every turn, lowest precedence first:
| Scope | Location | What belongs there |
|---|---|---|
user global |
~/.tstdesk/AGENTS.md |
Your preferences, in every workspace you open |
workspace |
<workspace>/AGENTS.md |
Team conventions. Git-tracked |
rules |
<workspace>/.tst/rules/*.md |
Modular rules, each scopeable to paths |
nested |
<workspace>/**/AGENTS.md |
Rules for one subtree |
They are concatenated in that order into a single block, each file wrapped in a provenance comment naming where it came from. Nothing is merged or de-duplicated: precedence is a matter of ordering, and when two files disagree the later one wins because the model reads it last. Say "prefer X" in the workspace file and "never X" in a nested file, and the nested file carries the subtree.
Here is all four levels at once:
Prefer small, reviewable commits.# Team conventions
Python 3.11+. Type hints on every public function.---
appliesTo: ["src/api/**"]
---
Every endpoint returns a Pydantic model, never a raw dict.Routes live in `routes.py`. One module per resource.With the session having touched one file under src/api/:
src/api/routes.py
the resolved stack is:
~/.tstdesk/AGENTS.md (user global)
AGENTS.md (workspace)
.tst/rules/api.md (rules) [scoped]
src/api/AGENTS.md (nested: src/api)
and this is the exact steering block the model receives:
<!-- from: ~/.tstdesk/AGENTS.md (user global) -->
Prefer small, reviewable commits.
<!-- from: <workspace>/AGENTS.md (workspace) -->
# Team conventions
Python 3.11+. Type hints on every public function.
<!-- from: <workspace>/.tst/rules/api.md (rules) -->
Every endpoint returns a Pydantic model, never a raw dict.
<!-- from: <workspace>/src/api/AGENTS.md (nested: src/api) -->
Routes live in `routes.py`. One module per resource.
Note what the provenance comment buys you: when the agent does something you did not expect, you can ask it which rule it was following, and the answer is in its own context. Note also that sources are butted together with no blank line between them, and that a file's trailing newline is dropped — if you end a steering file mid-sentence, the next file's provenance comment is the very next line.
- A missing file is never an error. Neither is an unreadable one, or one that is not valid UTF-8 — it is logged and skipped, and the rest of the stack assembles normally.
.tst/rules/is not recursive. Only*.mddirectly inside it is picked up..tst/rules/python/style.mdis silently invisible.- Rules load in byte order of their filename, which puts capitals first:
Mid.md,alpha.md,zebra.md. If the order matters, prefix with numbers —00-,10-,20-. - Nested files load shallowest first, so a deeper file overrides a shallower one.
- The nested walk skips
.git,.tst,.tstdesk,.claude,__pycache__,node_modules,.venv,dist,buildandtarget, and does not follow directory symlinks. A steering file inside any of those is not found. - Rules come before nested files. A
src/api/AGENTS.mdtherefore outranks every rule in.tst/rules/, scoped or not. - Nested files are not scoped by what the session touches. Every
AGENTS.mdanywhere in the tree loads on every turn, whether or not the agent goes near that subtree. Ten nested files means ten files in every prompt. If you want a rule that only costs you when it is relevant, that is.tst/rules/withappliesTo— see §4. - Nested files share an 8,000-token budget. Past it, the rest are left out, shallowest kept first, and Doctor names them. Each one left out says this in the inspector: "nested steering budget of 8,000 tokens used up; not loaded". A tree of worktrees or vendored repos is the usual way to hit it. Open the project folder itself instead of its parent.
- Identical nested files load once. A nested file whose text matches one already loaded
says "same text as a steering file already loaded; not loaded again". Worktree copies of the
same
AGENTS.mdcost one file, not one per copy. - The home folder gets no nested walk. Open a session on
~itself and only the global, root and rules levels load. Every repo under home has its own contract, and loading them all at once is how a session outgrows the model before the first message. Doctor says: "workspace is your home folder; AGENTS.md and CLAUDE.md files in its subfolders were not loaded. Open a project folder to use them".
The brain tier also gets a file map of the workspace, after steering. It takes at most 15% of
the brain tier's context_window and is cut on a whole line past that, with a marker saying
where. The share is converted to characters at the brain endpoint's learned token ratio once it
has one, 4 characters per token before (TD-5013). A git repo maps what git ls-files lists. A
folder that is not a repo is walked instead, and that walk skips hidden directories (.cache,
.local, .npm and the like), which on a home folder are nearly every file. The agent can
still list or read anything the map leaves out; the map only saves it a first look.
Steering is re-resolved at the top of every turn. Save the file and the next message picks it up; there is nothing to restart. The timeline announces the reload and the instruction inspector refreshes. A save while a turn is running waits for the next message: within a turn the system prompt goes out unchanged on every call, so a local server's prompt cache keeps the conversation behind it.
The cost of that is a cache miss. Steering is the second block of the stable prompt prefix, so the turn after an edit cannot reuse the cached prefix and pays full input price for it. Editing steering mid-session is cheap but not free — batch your edits rather than tuning one sentence at a time.
That assumes the prefix was being reused in the first place, which is a fact about your provider, not about the prompt. The inspector's cache badge reports only what the provider said:
| Badge | What it means |
|---|---|
cache unknown until a turn runs |
No turn has completed yet. |
provider reports no cache figure |
The endpoint returned no cached-token count. Nothing is known about reuse — this is not a miss. |
cache miss |
The provider reported zero cached tokens. |
cached N tokens |
The provider reported reusing N. |
A local endpoint usually sits on provider reports no cache figure. Ollama's
OpenAI-compatible responses carry prompt_tokens, completion_tokens and total_tokens and
nothing else, and llama.cpp discards its context checkpoints on hybrid-attention models, so
the whole prefix is re-processed every turn. The prefix ordering still pays off against cloud
providers that do report and do reuse; on a local model, expect no saving and expect the badge
to say so.
Inside a workspace, at every path in the hierarchy, the rule is the same: AGENTS.md if it
exists, otherwise CLAUDE.md. A repo that already has CLAUDE.md and no AGENTS.md is
read on the first run.
The user-global level is TST Desk's own file, ~/.tstdesk/AGENTS.md. ~/.claude/CLAUDE.md
is Claude Code's global file and is not read unless steering.claude_global_fallback is
true in config.yaml (default false). When the key is false and that file exists with
no ~/.tstdesk/AGENTS.md, Doctor's steering row says
not loaded — enable steering.claude_global_fallback to use it. Turning the key on loads
the file as the user-global fallback. An import from it that leaves the workspace still
asks for approval.
A workspace with no AGENTS.md anywhere, and a Claude Code global file on disk, resolves
the project files only:
Ask before installing anything.Rebase, never merge.No new abstractions in `src/` without a second caller.CLAUDE.md (workspace) [claude-fallback]
src/CLAUDE.md (nested: src) [claude-fallback]
The global file is on disk in this example and is absent from the stack. That is the default. Workspace and nested entries are flagged as fallbacks in the instruction inspector, so you can always see which file a rule actually came from.
When both files exist at one path, AGENTS.md wins and the CLAUDE.md is recorded as
shadowed — the inspector shows you the file that was skipped rather than pretending it is not
there. And note the second half of this example: a .claude/ directory inside the workspace
is skipped by the nested walk, so a CLAUDE.md in it is never read.
Rebase, never merge.This file is shadowed and contributes nothing.This file is never discovered at all.AGENTS.md (workspace) [shadows CLAUDE.md]
<!-- from: <workspace>/AGENTS.md (workspace) -->
Rebase, never merge.
There is no precedence between the two names beyond that, and no format difference. A
CLAUDE.md is parsed exactly like an AGENTS.md: same imports, same everything.
Files in .tst/rules/ may carry YAML frontmatter with an appliesTo array of globs. A scoped
rule loads only once the session has touched a file matching one of them. This is the one
mechanism on this page that actually reduces what you pay per turn.
---
appliesTo: ["src/api/**", "tests/api/**"]
---
Every endpoint returns a Pydantic model, never a raw dict.
Every route needs a test in `tests/api/` before merge."Touched" means a path that appeared in a successful tool call — a read, a write, an edit. The set starts empty at session start, which means every scoped rule is inactive on the first turn and switches on as the agent moves through the tree. When one activates mid-session the timeline says so, so context never changes silently.
---
appliesTo: ["src/api/**"]
---
Every endpoint returns a Pydantic model, never a raw dict.Line length 100. Trailing commas everywhere.---
appliesTo: ["ui/**/*.svelte"]
---
Runes only. No stores in components.Before the agent has touched anything:
(none)
.tst/rules/api.md (rules) [scoped inactive]
.tst/rules/style.md (rules)
.tst/rules/ui.md (rules) [scoped inactive]
After it opens src/api/routes.py:
src/api/routes.py
.tst/rules/api.md (rules) [scoped]
.tst/rules/style.md (rules)
.tst/rules/ui.md (rules) [scoped inactive]
An inactive rule is still listed in the inspector, greyed, so "why did that rule not fire?" is a glance rather than an investigation. It contributes nothing to the prompt and nothing to the token count.
Patterns are matched against workspace-relative paths.
| Pattern | Matches | Does not match |
|---|---|---|
*.py |
src/deep/thing.py |
src/thing.pyi |
Dockerfile |
Dockerfile, infra/Dockerfile |
MyDockerfile, Dockerfile.dev |
src/api/* |
src/api/routes.py |
src/api/v1/routes.py |
src/api/** |
src/api/routes.py, src/api/v1/routes.py |
src/api itself |
ui/**/*.svelte |
ui/App.svelte, ui/src/App.svelte |
src/App.svelte |
** |
everything | — |
A pattern with no / matches at any depth, the way .gitignore does. A pattern with a /
is matched against the whole relative path, where * stops at a separator and ** crosses
them. ? and [abc] / [!abc] character classes work too.
A bare name matches the whole basename, not a suffix of it, so a longer filename that
merely ends with the pattern does not activate the rule. config.py does not catch
oldconfig.py:
---
appliesTo: ["config.py"]
---
Config keys are sorted and documented in the same commit.src/oldconfig.py
.tst/rules/config.md (rules) [scoped inactive]
Touch the file it actually names and it activates, at any depth:
pkg/config.py
.tst/rules/config.md (rules) [scoped]
config.py and **/config.py are synonyms — both mean "a file named config.py, anywhere in
the tree" — so the bare name is already the anchored spelling and there is nothing longer to
write for the strict match. To narrow it further, name the directory: src/config.py matches
only there, because a pattern containing a / is matched against the whole relative path.
1. appliesTo outside .tst/rules/. Scope is a rules-directory feature. Frontmatter is
stripped from every steering file, so a block at the top of an AGENTS.md never reaches the
model — but outside .tst/rules/ that is all that happens to it. The appliesTo is dropped,
not honoured, and the file stays unconditionally on:
---
appliesTo: ["src/**"]
---
Rebase, never merge.(none)
AGENTS.md (workspace) [appliesTo-ignored]
<!-- from: <workspace>/AGENTS.md (workspace) -->
Rebase, never merge.
The delimiters are gone from the prompt, and there is no scoped flag — the session touched
nothing, and a rule scoped to src/** would have been inactive here. This one is not. The
inspector flags the file so the dropped scope is not itself silent:
appliesTo only scopes rules in .tst/rules/; it was stripped from this file and had no effect — see the steering authoring guide
Why stripped and not honoured: a steering file's location is already its scope. Root
AGENTS.md is the workspace-wide agreement, src/api/AGENTS.md is the agreement for that
subtree. Letting frontmatter re-scope a file on top of that would give one file two scoping
mechanisms that can disagree, and would let the workspace-wide working agreement vanish from a
turn because of which files the session happened to open first. Scope belongs in .tst/rules/,
which exists for exactly this and where a missing rule is the expected outcome rather than a
surprise.
2. An empty or malformed appliesTo. appliesTo: [], a string instead of a list, or YAML
that does not parse all degrade to unscoped, which means always on. That is the safe
direction, but it is not what you meant, and the inspector will show the rule with no scope
where you expected one.
3. A pattern anchored where the paths are not. Touched paths are workspace-relative and
never start with ./ or /. /src/api/** matches nothing.
The validator tier gets a subset of steering rather than all of it — the standards it needs to
review a diff, and nothing else. The subset is chosen by filename: AGENTS.md,
standards*.md, conventions*.md, and style*.md. A rule you want applied during review is
worth naming to match; one called api-notes.md will not be there. (The validator is
on-demand in v0.1, not scheduled automatically, so this shapes review turns you ask for rather
than every turn.)
A line consisting of nothing but @ and a path inlines that file:
@.tst/rules/testing.md
@~/notes/house-style.md
@/opt/team/shared.mdRelative paths resolve against the directory of the importing file, not the workspace root.
~ expands to your home directory. Imported content carries its own provenance comment, so a
rule that came in through two levels of import still names its real source.
Imports organise; they do not save tokens. Imported content is inlined in full, on every turn, exactly as if you had pasted it. If your goal is a smaller prompt, you want §4.
Two-space indents in YAML.# Conventions
@style.md
Everything else: see @style.md for the details.
- @style.md
@missing.md<!-- from: <workspace>/AGENTS.md (workspace) -->
# Conventions
<!-- from: <workspace>/style.md (imported) -->
Two-space indents in YAML.
Everything else: see @style.md for the details.
- @style.md
<!-- import file not found: <workspace>/missing.md -->
Three things to take from that. A mention mid-sentence is left alone, which is what lets you
write about imports without triggering them. A list item is also left alone — - @style.md
looks like an import and is not one, and this is the mistake people actually make. And a
missing file is a warning, not a failure: the session continues, the comment marks the hole,
and the issue is listed in the inspector.
import file not found: <workspace>/missing.md
Two-space indents in YAML.Documenting the syntax, not using it:
```
@style.md
```
Using it:
@style.md<!-- from: <workspace>/AGENTS.md (workspace) -->
Documenting the syntax, not using it:
```
@style.md
```
Using it:
<!-- from: <workspace>/style.md (imported) -->
Two-space indents in YAML.
The fence tracker is a simple toggle on lines starting with three backticks, so an unclosed fence swallows every import after it. If an import stopped resolving for no apparent reason, count your fences.
Imports nest four deep. A fifth level is refused with the chain named, so you can see which link to cut:
max import depth 4 exceeded: a.md -> b.md -> c.md -> d.md -> e.md
A cycle is caught wherever it closes, and reported the same way:
@ring.mdRing one.
@ring2.mdRing two.
@ring.mdimport cycle detected: ring.md -> ring2.md -> ring.md
Neither is fatal. The offending import is replaced by a comment and the turn proceeds.
Reading a file outside the workspace is an untrusted-file read, so the first one parks the turn and asks you:
Two-space indents in YAML.@~/notes/house-style.md~/notes/house-style.md
external import awaiting approval: ~/notes/house-style.md
<!-- from: <workspace>/AGENTS.md (workspace) -->
<!-- external import awaiting approval: ~/notes/house-style.md -->
Approve it and the path is written to approved_external_imports in the workspace's
.tst/config.yaml, so you are asked once per workspace rather than once per session — see
configuration.md §4.4. Deny it and it is omitted for the rest of that
session only; the next session asks again. Approving one file can reveal external imports
nested inside it, so a deep chain asks more than once.
Two consequences that surprise people:
- A missing external file is "not found", not "awaiting approval". There is nothing to read, so there is nothing to approve, and no prompt appears.
- Imports under your personal steering tree are not gated.
~/.tstdesk/AGENTS.mdmay@-import siblings inside~/.tstdesk/(for example@rules/style.md) without the external-import prompt — those files are part of your personal steering, not workspace escapes. Imports from a workspace file into~/.tstdesk/still ask once per workspace; imports from global steering into~/notes/…outside.tstdesk/still ask too.
Splitting personal steering across files under ~/.tstdesk/ looks like this:
@shared.mdPrefer small, reviewable commits.(none)
(none)
Steering rides in the prompt on every single turn, and long instruction files measurably lose adherence: the middle of a long list is followed less reliably than a short one, and the effect compounds as the conversation grows and the file sits further from the model's attention. Target under 200 lines per file and push the detail into path-scoped rules, where it is present when it matters and absent when it does not.
Past 200 lines, here is exactly what happens:
file exceeds 200 lines; long files measurably reduce adherence — see the steering authoring guide
That is a warning attached to the source in the instruction inspector. Nothing is truncated, nothing is dropped, and no turn fails. The file loads in full and costs you in full. The limit is advice with a nag attached, not a cap — TST Desk will not decide for you which of your rules to discard.
Three details about how the count is taken:
- It is lines, not tokens. The inspector shows you the token count separately, per source and in total.
- Exactly 200 lines does not warn. 201 does.
- It is measured after imports are inlined. A twelve-line
AGENTS.mdthat imports a 300-line file warns, and it is right to: the prompt carries all 312 lines. This is the same reason §5 says imports do not save tokens.
When a file is too long, in order of what usually works:
- Cut the paragraphs that restate what the model already does. "Write clean code" costs you tokens on every turn and changes nothing.
- Move anything that only applies to part of the tree into
.tst/rules/withappliesTo. - Move rarely-needed reference material — a long list of internal service names, a schema — out of steering entirely, and let the agent read the file when it needs it.
- Only then reach for imports, and only for organisation.
One CLI tool, one package, one contributor. One file is the whole steering surface, and there is no reason for it to be more.
# hoverfly — working agreement
A single-package Python 3.11 CLI. No framework, no plugins, no service.
## Conventions
- `ruff` for lint and format. `mypy --strict` clean before any commit.
- Errors raise. Nothing returns `None` to signal failure.
- One thing per function. Split a module before it passes 400 lines.
## Tests
- `pytest -q` green is part of "done", not a follow-up.
- A bug fix starts with the test that reproduces it.
## Ask first
- Adding a dependency.
- Changing the CLI's public flags.
- Anything under `scripts/release.sh`.AGENTS.md (workspace)
The steering block is that file verbatim behind a single provenance comment — see §2 for what the concatenation looks like once there is more than one source.
What makes it work: every line is a thing the agent would otherwise get wrong, and the "ask
first" list is specific enough to act on. There is no .tst/rules/ directory, no imports, and
no nested files. Resist adding them until a single file genuinely stops fitting.
A monorepo — Python API, Svelte frontend, SQL migrations — where a single file would be a thousand lines and most of it irrelevant to any given turn. The root file stays short and universal; everything domain-specific becomes a scoped rule.
Show me the plan before a multi-file change. I would rather redirect early.# monolith — working agreement
Three trees: `src/` (Python API), `ui/` (Svelte), `db/` (migrations).
Detailed rules live in `.tst/rules/` and load when you touch the tree they cover.
## Always
- Conventional commits. One logical change per commit.
- No secret in a file, a log, or a fixture. Ever.
- If the spec and this file disagree, the spec wins — say so, do not guess.Type hints on every public function, in every language that has them.
No dead code, no commented-out blocks, no debug prints left behind.---
appliesTo: ["src/**/*.py", "tests/**/*.py"]
---
Every endpoint returns a Pydantic model, never a raw dict.
Every route needs a test in `tests/api/` before merge.
Async throughout the I/O path — no blocking call in the event loop.---
appliesTo: ["ui/**/*.svelte", "ui/**/*.ts"]
---
Runes, not stores, inside components.
Design tokens only. No hardcoded colour or spacing.---
appliesTo: ["db/migrations/**"]
---
Every migration is reversible and has a tested `down`.
Never edit a migration that has shipped. Add another one.`npm run check` before you call a UI change done.At the start of a session, nothing has been touched, so only the universal material is in the prompt:
(none)
~/.tstdesk/AGENTS.md (user global)
AGENTS.md (workspace)
.tst/rules/00-standards.md (rules)
.tst/rules/10-python-api.md (rules) [scoped inactive]
.tst/rules/20-svelte.md (rules) [scoped inactive]
.tst/rules/30-migrations.md (rules) [scoped inactive]
ui/AGENTS.md (nested: ui)
The agent then works across the API and the frontend, and two rules switch on. The migration
rules stay out of the prompt, because the session never went near db/:
src/api/routes.py
ui/src/App.svelte
~/.tstdesk/AGENTS.md (user global)
AGENTS.md (workspace)
.tst/rules/00-standards.md (rules)
.tst/rules/10-python-api.md (rules) [scoped]
.tst/rules/20-svelte.md (rules) [scoped]
.tst/rules/30-migrations.md (rules) [scoped inactive]
ui/AGENTS.md (nested: ui)
Four choices in there are worth copying:
- The root file is short and universal. Anything that only applies to one tree was moved out. It is the file that can never be scoped, so it is the one to keep lean.
- Rules are numbered.
00-,10-,20-fixes the order, which byte-order sorting would otherwise decide for you. 00-standards.mdis deliberately unscoped, because it applies everywhere — and its name puts it in the validator's subset, so review sees it too.ui/AGENTS.mdis one line. A nested file loads on every turn regardless of what the session touches, so anything sizeable that belongs to one tree belongs in a scoped rule instead. Use nested files for the short, standing fact about a directory.
The scoped rules cost nothing until they are relevant. That is the whole point of the mechanism, and on a repo this size it is the difference between a steering block you can afford on every turn and one you cannot.
Nothing needs porting. Point TST Desk at a repo already set up for Claude Code, Cursor, or anything else that reads a markdown instruction file, and the parts it understands work on the first run.
| You have | What happens |
|---|---|
CLAUDE.md at the repo root |
Read as the workspace steering file. Nothing to rename |
CLAUDE.md in subdirectories |
Read as nested steering for that subtree |
~/.claude/CLAUDE.md |
Not read unless steering.claude_global_fallback is true. Prefer ~/.tstdesk/AGENTS.md |
~/.claude/skills/ |
Same key. A workspace's own .claude/skills/ is read without it |
@path imports in any of them |
Resolved the same way, max depth 4 |
Both AGENTS.md and CLAUDE.md |
AGENTS.md wins; inside the workspace the other is shown as shadowed |
The §3 example above is this case, run for real: a workspace with no AGENTS.md resolves its
CLAUDE.md files, and ~/.claude/CLAUDE.md stays out of the stack unless you enable the key.
What does not carry over, and what to do about it:
.cursor/rules/,.github/copilot-instructions.md, and similar tool-specific directories are not read. Copy the content into.tst/rules/— and if the originals had path scoping, this is where you get it back, withappliesTo.- A
.claude/directory inside the workspace is skipped by the nested walk.~/.claude/CLAUDE.mdis not read unlesssteering.claude_global_fallbackis true. Move anything you need into~/.tstdesk/AGENTS.md. - MCP server definitions, hooks, and subagent files are configuration for
another product, not steering. They are ignored. TST Desk's own hooks are
set under
hooks:inconfig.yaml(or a trusted.tst/config.yaml); see docs/configuration.md (TD-5134). TST Desk's own named workers live in.tst/agents/*.md(and~/.tstdesk/agents/*.md);.claude/agents/is not read. A Claude Code subagent file can be copied over once itsmodelkey is replaced withtierorpreset(configuration §4.11, TD-5133). - Slash commands live in
.tst/commands/*.md(and~/.tstdesk/commands/*.md). They are not steering: the assembler never puts them in the cache prefix. Type/in the composer to list them. The agent cannot write those trees. If both of our trees are empty,.claude/commands/(and~/.claude/commands/) is the fallback. See TD-4501. - Skills live in
.tst/skills/<name>/SKILL.md(and~/.tstdesk/skills/). If both of our trees are empty, the workspace's.claude/skills/is the fallback.~/.claude/skills/joins it only whensteering.claude_global_fallbackis true, the same key that gates~/.claude/CLAUDE.md(TD-4845): its catalog lines go into every brain prompt. When the workspace is your home folder,~/.claude/skills/is that workspace's own tree and loads without the key. A loaded skill's block names its directory (~/.claude/skills/yt-edit, or a workspace-relative path), so a body that runspython3 chapters.pyor readsreferences/guide.mdcan find the file; the shell still starts in the workspace (TD-5011). A skill body over 4,000 tokens is refused byload_skilland/name, not truncated, and is left out of the catalog so the model does not spend a turn on it.descriptionis the one required key; a skill without it, or with aname,whenToUseorwhen_to_usethat is not text, is skipped, and the log names the key once per file (TD-5160). So is aSKILL.mdthat is not UTF-8 (a Windows-1252 file, or UTF-16 from PowerShell 5.1Out-File): it is logged once and the other skills load. Save it as UTF-8 to bring it back.whenToUse(or Claude Code'swhen_to_use; ours wins when both are set) is optional and falls back todescription.compatibility(the Agent Skills spec's environment needs) is shown to the model beside the description, as is a when-to-use that says more than the description.nameis accepted, but the directory name is the skill's name: when they differ, the directory wins and the mismatch is logged.license,version,metadataandargument-hintare labels and pass silently.disable-model-invocation: true(any value but YAMLfalseor no value at all; a quoted''or"false"counts as set) is honored: the skill is left out of the model's catalog andload_skillrefuses it, so only your/nameloads it; the inspector marks it "slash only". Every other key loads with the skill and is ignored (TD-5107; before it, these keys skipped the whole skill). That coversallowed-tools,model,effort,tools,disallowed-tools,hooks,context,agent,paths,user-invocable: falseand any key TST Desk does not know, following the Agent Skills spec's advice to load and warn. Without theallowed-toolsgrant, the skill's tool calls go through this workspace's policy like any other call, anddisallowed-toolsis not enforced. The ignored keys are logged once per file while the daemon runs, shown on the skill in the Stack inspector ("ignored: hooks, model"), and named in Doctor'sskillsrow. - Frontmatter conventions from other tools are stripped, not interpreted. If your
CLAUDE.mdopens with a YAML block —description,globs,alwaysApply, or anything else — it is removed before the file is assembled, so it never reaches the model and you have nothing to clean up. What it meant does not carry over: only.tst/rules/scopes, and only throughappliesTo. A file whose frontmatter scoped it in your old tool arrives here unconditional, and the inspector flags it if it carried anappliesTo— see §4.
There is no import step and no migration command. When you are ready to commit to the open
name, rename CLAUDE.md to AGENTS.md; until then, both work, and you can keep one repo
serving both tools indefinitely.
.tst/commands/ and ~/.tstdesk/commands/ are human-authored insert snippets.
The instruction stack never reads them. Invoking /review inserts the file
body into the user message; until then the body is absent from the prompt.
Agent writes to .tst/commands/** and .claude/commands/** are Class C, the
same refusal as AGENTS.md.
Named worker definitions (.tst/agents/ and ~/.tstdesk/agents/, TD-5133) are
not steering either: a worker's prompt reaches only that worker, after the worker
tier's stack. Agent writes to both trees are Class C, the same refusal.
The agent never writes a steering file, but it can propose one with propose_steering_edit
(TD-5140). Ask it to "add this to AGENTS.md", to remember a project rule, or to draft a starter
AGENTS.md for a repo that has none; it reads what is there (for a starter, the README, build
and test commands, CI config and layout) and proposes the whole new file.
- What can be proposed:
AGENTS.mdandCLAUDE.mdat any depth, a.tst/rules/<name>.mdrule, aSKILL.md, and a slash-command file directly under.tst/commands/or.claude/commands/, all inside the workspace. Names match exactly. (~/.tstdesk/commands/is read from your home folder only, so a.tstdesk/commands/inside a workspace can't be proposed.) The signed charter (.tst/autonomy/CHARTER.md), the approval policy (.tst/config.yaml), and any path under.git,.vscodeor another folder that runs code later can't be proposed. - What you see: a card with the diff and Accept, Edit and Reject. Edit opens the
proposed text; Save writes what you typed. The tool itself writes nothing and asks
nothing, so the card is the one approval. The card shows exactly what Accept writes: the
session log blanks secret-shaped strings (
sk-…,ghp_…and the like; a word such astask-tool-availabilityis not one), so a proposal whose file name, file or text holds one is refused, and so is a Save of one. Change such a file by hand. - Who writes: the daemon, on your Accept or Save, never the filesystem tool. If the file changed after the proposal (you edited it, or another proposal was accepted), Accept is refused with "the file changed since this was proposed" and a fresh diff replaces the card. Accept and Save come only from this computer's own window; a paired phone can reject.
- What is kept: every proposal and every decision (accepted, edited or rejected) goes in
the session log with its diff. Open proposals are held by the daemon in memory, so a restart
closes them: the log records each as
expired, the card does not come back, and you ask the agent again. A card the daemon no longer holds says nothing was written and offers Dismiss. - Nothing accepts for you. Skip-all doesn't, and an unattended run parks its proposals in the run summary ("Steering edits") until you decide.
.tst/memory/ is a different tree. The agent writes it (distill) and you correct it; the
instruction stack never reads it. Mixing the two is how last month's decisions get treated as
this month's rules.
A freshly opened workspace gets three commented templates and nothing else:
<workspace>/.tst/memory/
MEMORY.md ← the index
decisions.md ← why things are the way they are
gotchas.md ← things that bit us
You (or distill) may add <topic>.md files beside those. The scaffold never invents topic
names. Frontmatter in a memory file is not an appliesTo rule. The first brain turn
loads MEMORY.md plus topic files whose headings overlap the task — still not as
steering. The agent may write this tree (Class A); it is still refused on AGENTS.md,
CLAUDE.md, and .tst/rules/**. Layout and git tracking are in
configuration.md §5.
Writing this guide against the running assembler surfaced three places where the behaviour is not what an author would predict. Two have since been fixed and the examples above now demonstrate the corrected behaviour; the one that remains is reported as a defect, is not worked around here, and is demonstrated by a live example above rather than asserted.
- A bare-name
appliesTopattern matches a filename suffix, not a basename. Fixed.config.pyno longer activates onoldconfig.py— a pattern with no/is anchored at the whole basename, and**/config.pymeans the same thing. See §4. appliesTooutside.tst/rules/is neither honoured nor stripped. Fixed. Frontmatter is stripped at every level now, so nothing reaches the model. It is still not honoured outside.tst/rules/— that half is deliberate, and flagged rather than silent. See §4.- Splitting user-global steering across files under
~/.tstdesk/. Fixed (TD-4905).@imports from~/.tstdesk/AGENTS.mdto another file under~/.tstdesk/load without the external-import gate. Workspace files importing outside the tree still prompt. See §5.
core/tests/test_docs_steering_guide.py runs on every suite run:
- Every example is materialised as a real workspace and home directory and assembled by the
real
ContextAssembler. The stacks, prompt blocks, import issues and pending approvals printed above are compared to its output exactly. - The 200-line warning, the dropped-
appliesTowarning and the import-depth message are quoted from strings the test provokes out of the assembler, so rewording any of them in code fails here until this page catches up. Every warning the assembler can raise must also have a flag named in this guide before a stack line can render it. - Every precedence level, every directory skipped by the nested walk, and every pattern in the validator's default subset must appear in this text. Adding one fails the suite until it is documented.
- The claim in §6 that nothing is truncated past the limit is checked by assembling an over-limit file and looking for its last line in the block.