Appendix D: JSONL Configuration Format Reference

JSONL entries should point at spec files (.trellis/spec/**) or the task’s research outputs ({TASK_DIR}/research/*.md) — things the sub-agent needs to read before writing code (rules + background). Don’t add raw source files or directories (src/services/foo.ts, packages/<pkg>/, etc.) — sub-agents already have Read / Grep and will fetch code when they need it. Injecting code into context just burns tokens.

File entry

{
  "file": ".trellis/spec/backend/index.md",
  "reason": "Backend development guide"
}

Directory entry

{
  "file": ".trellis/tasks/02-27-user-login/research/",
  "type": "directory",
  "reason": "Research outputs for this task"
}

For directory entries, the hook reads all .md files in the directory, up to 20. Common use: point at the task’s own research/ directory so the sub-agent picks up any upstream investigations.

Complete example (fullstack `implement.jsonl`)

{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
{"file": ".trellis/spec/backend/api-module.md", "reason": "API module conventions"}
{"file": ".trellis/spec/backend/quality.md", "reason": "Code quality requirements"}
{"file": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"}
{"file": ".trellis/spec/frontend/components.md", "reason": "Component conventions"}
{"file": ".trellis/tasks/02-27-user-login/research/", "type": "directory", "reason": "Research outputs for this task"}

JSONL files used by each sub-agent

File	Sub-agent	Typical content
`implement.jsonl`	`trellis-implement`	workflow + relevant spec indexes + task `research/` dir
`check.jsonl`	`trellis-check`	quality-related specs + finish-work / check command specs

trellis-research writes durable findings into the task’s research/ directory. Trellis does not require a separate default research manifest; investigation context comes from the current request, existing specs, task history, and any explicit research instructions.

Start Here

Advanced

Use Cases

Resource Marketplace

Community

Appendix D: JSONL Configuration Format Reference