Skip to content

Latest commit

 

History

History
1077 lines (855 loc) · 41.7 KB

steering.md

File metadata and controls

1077 lines (855 loc) · 41.7 KB

Steering authoring guide

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.


1. The short version

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.


2. The hierarchy

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.

Things worth knowing about discovery

  • 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 *.md directly inside it is picked up. .tst/rules/python/style.md is 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, build and target, 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.md therefore outranks every rule in .tst/rules/, scoped or not.
  • Nested files are not scoped by what the session touches. Every AGENTS.md anywhere 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/ with appliesTo — 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.md cost 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 workspace map is budgeted too

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.

When an edit takes effect

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.


3. CLAUDE.md compatibility

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.


4. Path-scoped rules

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.

Glob semantics

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.

Three ways a rule quietly fails to scope

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.

Rule names decide what the validator sees

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.)


5. Imports

A line consisting of nothing but @ and a path inlines that file:

@.tst/rules/testing.md
@~/notes/house-style.md
@/opt/team/shared.md

Relative 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.

The directive has to be the whole line

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

Code fences are not evaluated

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.

Depth and cycles

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.md
Ring one.
@ring2.md
Ring two.
@ring.md
import cycle detected: ring.md -> ring2.md -> ring.md

Neither is fatal. The offending import is replaced by a comment and the turn proceeds.

Imports from outside the workspace need approval

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.md may @-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.md
Prefer small, reviewable commits.
(none)
(none)

6. Why 200 lines

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.md that 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:

  1. Cut the paragraphs that restate what the model already does. "Write clean code" costs you tokens on every turn and changes nothing.
  2. Move anything that only applies to part of the tree into .tst/rules/ with appliesTo.
  3. 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.
  4. Only then reach for imports, and only for organisation.

7. Worked example: a small project

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.


8. Worked example: a large project

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.md is deliberately unscoped, because it applies everywhere — and its name puts it in the validator's subset, so review sees it too.
  • ui/AGENTS.md is 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.


9. Coming from another tool

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, with appliesTo.
  • A .claude/ directory inside the workspace is skipped by the nested walk. ~/.claude/CLAUDE.md is not read unless steering.claude_global_fallback is 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: in config.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 its model key is replaced with tier or preset (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 when steering.claude_global_fallback is 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 runs python3 chapters.py or reads references/guide.md can find the file; the shell still starts in the workspace (TD-5011). A skill body over 4,000 tokens is refused by load_skill and /name, not truncated, and is left out of the catalog so the model does not spend a turn on it. description is the one required key; a skill without it, or with a name, whenToUse or when_to_use that is not text, is skipped, and the log names the key once per file (TD-5160). So is a SKILL.md that is not UTF-8 (a Windows-1252 file, or UTF-16 from PowerShell 5.1 Out-File): it is logged once and the other skills load. Save it as UTF-8 to bring it back. whenToUse (or Claude Code's when_to_use; ours wins when both are set) is optional and falls back to description. 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. name is accepted, but the directory name is the skill's name: when they differ, the directory wins and the mismatch is logged. license, version, metadata and argument-hint are labels and pass silently. disable-model-invocation: true (any value but YAML false or no value at all; a quoted '' or "false" counts as set) is honored: the skill is left out of the model's catalog and load_skill refuses it, so only your /name loads 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 covers allowed-tools, model, effort, tools, disallowed-tools, hooks, context, agent, paths, user-invocable: false and any key TST Desk does not know, following the Agent Skills spec's advice to load and warn. Without the allowed-tools grant, the skill's tool calls go through this workspace's policy like any other call, and disallowed-tools is 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's skills row.
  • Frontmatter conventions from other tools are stripped, not interpreted. If your CLAUDE.md opens 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 through appliesTo. A file whose frontmatter scoped it in your old tool arrives here unconditional, and the inspector flags it if it carried an appliesTo — 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.


Slash commands are not steering

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


Proposed edits

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.md and CLAUDE.md at any depth, a .tst/rules/<name>.md rule, a SKILL.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, .vscode or 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 as task-tool-availability is 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.

10. Memory is not steering

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


11. Sharp edges

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 appliesTo pattern matches a filename suffix, not a basename. Fixed. config.py no longer activates on oldconfig.py — a pattern with no / is anchored at the whole basename, and **/config.py means the same thing. See §4.
  • appliesTo outside .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.md to another file under ~/.tstdesk/ load without the external-import gate. Workspace files importing outside the tree still prompt. See §5.

12. How this guide is kept honest

core/tests/test_docs_steering_guide.py runs on every suite run:

  1. 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.
  2. The 200-line warning, the dropped-appliesTo warning 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.
  3. 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.
  4. 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.