Skip to content
Documentation

ADR-026: LLM Agent Workflow & Token Discipline

FieldValue
TypeSkill Resource
Source~/.copilot/skills/adr/references/adr-026-llm-agent-workflow-and-token-discipline.md
DescriptionNot specified

Source Content

ADR-026: LLM Agent Workflow & Token Discipline

Decision

LLM agents working in this codebase follow a search-first, seven-stage workflow and read narrowly to conserve tokens. Pull component context from the dmwd Storybook MCP (or the component’s stories and docgen) before opening its source, search before reading, and read targeted ranges instead of whole files — except for cross-cutting, accessibility, security, legal, or ADR-governed work, where you read more context, not less.

Key rules

  • Search before you read: run rg -l 'pattern' to find candidate files, then open only what you need.
  • Get component context first from the dmwd Storybook MCP (or the component’s stories + TypeScript docgen) — it is the integration contract and orients the rest of the work.
  • Read targeted ranges, not whole files: use rg --files, rg -l, wc -l, and sed -n 'start,endp' to scope reads.
  • Never cat a large file when a targeted rg or sed range would suffice.
  • Read MORE (not less) for cross-cutting changes, accessibility, security, legal documents, and ADR-governed components.
  • Follow the seven stages in order: understand the task, search for relevant files, pull component context (MCP / stories / docgen), read the relevant files, read the governing ADRs, implement, then verify.
  • Delegate tool-heavy, multi-file, or exploratory work to a subagent/Task and return only the compact result; keep the top-level thread for framing, decisions, and synthesis. Fan out flat (depth 1) — never nest delegation. Inline tool calls in the root are fine for a quick single-step check.

Why

A search-first workflow keeps an agent’s context window focused on the lines that matter, which lowers token cost and reduces the chance of acting on stale or irrelevant code. Pulling component context from the MCP first front-loads the integration contract so changes respect the component’s intended API — without a hand-maintained per-component prompt. The read-more carve-out for high-stakes work keeps token frugality from causing accessibility, security, or compliance regressions.

Delegating tool-heavy work to subagents (the orchestrator / context-isolation pattern) keeps the root context small and coherent across long sessions: raw reads and command output stay in the worker, only the result returns to the top thread. It trades more total tokens (each delegation re-establishes context) for a root window that never bloats — worth it for large, long-running work, not for a quick single-file edit. Keep delegation flat: one level of fan-out is what current models orchestrate reliably; deeper recursion gives no measurable gain.

Applies when

You are an LLM agent starting any task in this codebase — read this first, before any other ADR, as the operating instructions for agent workflows.

  • ADR-021 — self-documenting code examples.
  • ADR-024 — engineering standards.