Dynamic Spec Loading

Trellis can attach specs to code paths and deliver the matching rules when an agent touches a file. This keeps the prompt small while putting the relevant rules close to the edit they govern.

Declare which paths a spec governs

Add a paths list to the spec’s YAML frontmatter. Paths are relative to the repository root.

---
name: commands-workflow
description: Workflow command and resolver contracts
paths:
  - packages/cli/src/commands/workflow.ts
  - packages/cli/src/utils/workflow-resolver.ts
  - packages/cli/test/commands/workflow*.test.ts
---

# Workflow command rules

...

The matcher supports:

* within one path segment
** across path segments
? for one character
a trailing / as shorthand for everything below that directory

Specs without paths frontmatter keep their existing behavior. They are not loaded automatically.

What the agent receives

For each matching spec, Trellis chooses one of three deliveries:

Situation	Delivery
First matching touch in a session	Full, budgeted spec body
Unchanged spec inside the refresh window	No repeated output
Unchanged spec after the refresh window	Short ticket with the spec path and read hint
Spec content changed	Full body again
Session was cleared or compacted	Full body again on the next matching touch

The refresh window is fixed. Silent touches do not extend it, so continuous editing still receives a later reminder. When several specs match one file, narrower path patterns are considered before broad patterns. If the event budget cannot hold every full body, remaining matches become an index of spec paths instead of disappearing.

Platform behavior

Platform	Trigger	Behavior
Claude Code	`PostToolUse` for `Read`, `Edit`, `Write`, and `MultiEdit`	Delivers matching context after the file operation. Claude Code’s read-before-write behavior usually loads the rules before the later edit.
Codex	`PreToolUse` for native `apply_patch`	Parses every add, update, delete, and move header before the patch runs.
Other platforms	Pull mode	Query matching spec paths explicitly with `get_context.py`.

Why Codex blocks the first patch once

Codex does not require a file read before an edit. When a patch first matches a spec, the hook returns the full rules and denies that patch once:

patch requested
  → Trellis injects governing specs
  → patch is denied
  → Codex reads the specs and retries
  → retry proceeds

Only a newly delivered full spec blocks the patch. A short refresh ticket does not block, and an unchanged spec inside the refresh window produces no output. This is a context-delivery handshake, not a policy rejection.

Configure the budget and refresh window

The defaults fit the host context limits and require no configuration:

spec_injection:
  enabled: true
  max_spec_chars: 9400
  max_total_chars: 9500
  refresh_window_seconds: 2700
  tools: [Read, Edit, Write, MultiEdit]

Key	Meaning
`enabled`	Set to `false` to disable dynamic spec loading.
`max_spec_chars`	Maximum characters from one spec. `0` removes this limit.
`max_total_chars`	Maximum characters for one hook event. `0` removes this limit.
`refresh_window_seconds`	Seconds before an unchanged spec gets a short ticket. `0` disables time-based refresh.
`tools`	Claude Code tool names that can trigger matching. Codex `apply_patch` uses the logical `Edit` trigger. An empty list disables every trigger.

Truncated bodies include a notice with the full spec path so the agent can read the source file directly.

Inspect matches manually

Use pull mode to check which specs govern a path without loading their bodies:

# macOS and Linux
python3 ./.trellis/scripts/get_context.py --mode spec \
  --file packages/cli/src/commands/workflow.ts

# Windows
python ./.trellis/scripts/get_context.py --mode spec \
  --file packages/cli/src/commands/workflow.ts

Add --json for structured output:

python3 ./.trellis/scripts/get_context.py --mode spec \
  --file packages/cli/src/commands/workflow.ts \
  --json

An empty match is valid and returns no governing specs.

State, reset, and failure behavior

Delivery state is stored outside the repository under ~/.trellis/spec-inject/. Parent and sub-agent histories are separate. SessionStart(source=clear|compact) records a reset marker shared by that session, so rules removed by compaction are delivered again. The hook does not parse Claude Code or Codex transcript contents. Transcript formats are host internals and are not part of this contract. Matching and state failures are fail-open: malformed frontmatter, missing paths, unreadable state, or an internal hook error must not break the host tool call. The only intentional block is the first Codex patch that has just received a full governing spec.

Start Here

Advanced

Use Cases

Resource Marketplace

Community

Declare which paths a spec governs

What the agent receives

Platform behavior

Why Codex blocks the first patch once

Configure the budget and refresh window

Inspect matches manually

State, reset, and failure behavior

​Declare which paths a spec governs

​What the agent receives

​Platform behavior

​Why Codex blocks the first patch once

​Configure the budget and refresh window

​Inspect matches manually

​State, reset, and failure behavior

​Related pages

Declare which paths a spec governs

What the agent receives

Platform behavior

Why Codex blocks the first patch once

Configure the budget and refresh window

Inspect matches manually

State, reset, and failure behavior

Related pages