Route template agents to the cookbook instead of mandating a bulk read - #26
Conversation
Both template copilot-instructions.md files opened by telling the agent
to read a hardcoded list of reference files ("read at least: ..."). For
the asp template that is ~198K tokens - 62% of the whole reference set -
before writing a single line of code, and "at least" made it a floor.
trellis-start-here.md, which ships in the same .github directory, says
the opposite: the set is ~300K tokens, is not meant to be held at once,
and the way to work is to hold the cookbook's ~4K routing head and open
recipe bodies and area references on demand. It also forbids delegating
reference reading to a sub-agent, because a sub-agent returns a
paraphrase and the exact signatures never reach the caller's context.
That conflict resolved the wrong way every session: copilot-instructions
is auto-loaded, and it mentioned trellis-start-here.md zero times, so an
agent only found the file arguing against the bulk read by accident.
Both files now route to it and carry the sub-agent rule.
Also:
- The asp file quoted the analyzer range as TRLS001-TRLS022; the current
maximum is TRLS059. It now uses the TRLS0xx form the microservices file
already used, because this repo has no lint to keep a number honest.
- The asp project-layout tree hand-listed 18 of the 31 reference files
actually delivered. The 13 omitted included trellis-start-here.md and
trellis-api-anti-patterns.md, so the tree was suppressing discovery of
the very router this change depends on. It now names the entry points
and globs the rest, matching the microservices tree.
- The microservices file never mentioned the framework cookbook at all,
only its own microservices cookbook. Both are now named, in order.
- Added a note that a reference file being present does not mean the
package is available, directing the reader to the project's own .csproj
PackageReference rather than Directory.Packages.props - the latter
lists centrally managed versions for packages no project references.
There was a problem hiding this comment.
Pull request overview
This PR updates the template-level Copilot instruction entrypoints for both the ASP and microservices templates so agents are routed through trellis-start-here.md → the cookbook routing head(s), instead of being instructed (implicitly or explicitly) to bulk-read large reference sets up front. This aligns the always-auto-loaded copilot-instructions.md with the “hold the routing head / read recipes on demand” workflow described by the Trellis docs.
Changes:
- Replaces the “read at least …” bulk-read guidance with a start-here + cookbook routing-head approach and an explicit “don’t read the whole set” budget.
- Adds/clarifies a rule to not delegate reference reading to sub-agents (to avoid paraphrased signatures/overloads).
- Updates the “read first” routing table and the
.github/tree callouts (including analyzer range wording and anti-patterns entry).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| microservices/template/.github/copilot-instructions.md | Routes agents through trellis-start-here.md and both cookbooks; adds budget + sub-agent guidance; expands the routing table and .github/ tree callouts. |
| asp/template/.github/copilot-instructions.md | Routes agents through trellis-start-here.md and the framework cookbook; adds budget + sub-agent guidance; updates routing table and simplifies the .github/ tree callouts. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| │ ├── copilot-instructions.md ← THIS FILE | ||
| │ └── trellis-api-*.md ← shipped API reference set | ||
| │ ├── trellis-start-here.md ← START HERE: routes to the cookbooks | ||
| │ ├── trellis-api-cookbook.md ← framework router: task lookup, recipes, preflight | ||
| │ ├── trellis-api-microservices-cookbook.md ← cross-service recipes | ||
| │ └── trellis-api-*.md ← the rest of the shipped API reference set |
There was a problem hiding this comment.
Correct, and thanks — fixed in 500f0df.
Verified the gap: in both templates exactly two shipped reference docs fall outside trellis-api-*.md — trellis-value-object-taxonomy.md and trellis-start-here.md. The tree named start-here explicitly, so the taxonomy was the one genuinely hidden — and it is one of only four files trellis-start-here.md singles out as worth knowing about.
This is a sharper version of your point: it is the same defect this PR set out to fix. The old asp tree omitted 13 files by enumeration; replacing it with a glob that omits 2 would just have been a quieter instance of the same bug. (The microservices tree already carried this glob before this PR.)
Fixed in three places per template rather than only the tree, since the same shorthand was used elsewhere:
- the project-layout tree;
- the "reference docs are authoritative" precedence rule — which, written as
trellis-api-*.md, excludedtrellis-start-here.mdfrom its own authority, i.e. the file this PR routes agents to was not covered by the rule saying references win; - the
TrellisSyncApiReferenceupgrade note in the asp file (the sync does deliver alltrellis-*.md).
Confirmed after the change: zero trellis-api-* glob claims remain, and zero reference docs in either template fall outside trellis-*.md.
| │ ├── copilot-instructions.md ← THIS FILE | ||
| │ ├── trellis-start-here.md ← START HERE: routes to the cookbook | ||
| │ ├── trellis-api-cookbook.md ← the router: task lookup, recipes, preflight | ||
| │ └── trellis-api-*.md ← the rest of the shipped API reference set |
There was a problem hiding this comment.
Correct, and thanks — fixed in 500f0df.
Verified the gap: in both templates exactly two shipped reference docs fall outside trellis-api-*.md — trellis-value-object-taxonomy.md and trellis-start-here.md. The tree named start-here explicitly, so the taxonomy was the one genuinely hidden — and it is one of only four files trellis-start-here.md singles out as worth knowing about.
This is a sharper version of your point: it is the same defect this PR set out to fix. The old asp tree omitted 13 files by enumeration; replacing it with a glob that omits 2 would just have been a quieter instance of the same bug. (The microservices tree already carried this glob before this PR.)
Fixed in three places per template rather than only the tree, since the same shorthand was used elsewhere:
- the project-layout tree;
- the "reference docs are authoritative" precedence rule — which, written as
trellis-api-*.md, excludedtrellis-start-here.mdfrom its own authority, i.e. the file this PR routes agents to was not covered by the rule saying references win; - the
TrellisSyncApiReferenceupgrade note in the asp file (the sync does deliver alltrellis-*.md).
Confirmed after the change: zero trellis-api-* glob claims remain, and zero reference docs in either template fall outside trellis-*.md.
`trellis-api-*.md` does not match `trellis-value-object-taxonomy.md` or `trellis-start-here.md`, so every place using it as shorthand for "the shipped reference set" was under-claiming by two files - including the taxonomy, one of only four files trellis-start-here.md singles out, and start-here itself, which this PR routes to. This is the same defect the PR set out to fix: the previous asp tree omitted 13 files by enumeration, and replacing it with a glob that omits 2 would have been a quieter version of the same bug. The microservices tree already carried this glob before this PR. Three sites, both templates: the project-layout tree, the "reference docs are authoritative" precedence rule (which otherwise excluded start-here from its own authority), and the asp TrellisSyncApiReference upgrade note. Verified: zero `trellis-api-*` glob claims remain, and zero reference docs in either template fall outside `trellis-*.md`.
Why
Both templates''
copilot-instructions.md— the file auto-loaded into every AI session in a generated consumer project — opened by telling the agent to read a hardcoded list of reference files ("read at least: …"). For the asp template that is ~198K tokens, 62% of the entire reference set, before writing a single line of code. And "at least" made it a floor, not a ceiling.trellis-start-here.mdships in the same.githubdirectory and says the exact opposite: the set is ~300K tokens, is not meant to be held at once, and the way to work is to hold the cookbook''s ~4K routing head and open recipe bodies (~1.25K each, typically 1–3) plus 1–3 area references on demand.That conflict resolved the wrong way every single session, for a structural reason:
copilot-instructions.mdis auto-loaded, and it mentionedtrellis-start-here.mdzero times. The always-present file mandated the bulk read; the file arguing against it could only be found by an agent already looking for it.Same split on sub-agent delegation —
trellis-start-here.mdforbids it (a sub-agent returns a paraphrase, so exact signatures never reach the caller''s context, which is how invented APIs appear), andcopilot-instructions.mdwas silent.What changed
Both files now route to
trellis-start-here.md→trellis-api-cookbook.md, restate the hold-the-head/read-on-demand budget, and carry the sub-agent rule. The existing "When working on… / Read first" table was already the right shape and is kept, with a "start here" row added at the top plus a row fortrellis-api-anti-patterns.md.TRLS001–TRLS022→TRLS001–TRLS0xx. Current max is TRLS059. The microservices file already used theTRLS0xxform — the right call, since this repo has no lint to keep a concrete number honest.trellis-start-here.mdandtrellis-api-anti-patterns.md— so the tree was actively suppressing discovery of the very router this change depends on. Now names the entry points and globs the rest, matching the microservices tree..csprojPackageReference.Where the two templates disagreed, I converged the asp file onto the microservices one rather than inventing a third approach — it had already independently solved both the range and the tree.
Review finding worth calling out
Code review caught that my first draft told readers to confirm a package "is referenced in
Directory.Packages.props". That is central version metadata, not a reference, and following it would falsely authorise APIs that cannot compile. Verified concretely:Trellis.ServiceDefaultshas a<PackageVersion>in both templates but zero<PackageReference>s — and my first draft had also added a routing row pointing attrellis-api-servicedefaults.md, which is precisely the trap. Row removed from both.Trellis.ServiceLevelIndicators.Asp.ApiVersioning,Trellis.ResourceNaming.Azure). Examples replaced and each one re-verified at 0 references.Verification
trellis-*.mdfilename referenced by each file exists in that template''s.github(17 asp / 21 microservices, 0 missing).PackageReferences.TRLS022/TRLS039strings remain; noread at leastmandate remains.Caveat
Nothing in this repo reads or validates
copilot-instructions.md— no script, test, or workflow. Unlike the framework (where I addedTRLDOC010/TRLDOC013for exactly this), these files cannot be guarded the same way, which is why the drift-prone concrete range was replaced withTRLS0xxand the file enumeration with a glob. Both changes remove the things that rot rather than merely correcting them.Documentation only — no template code, no build or packaging changes.