Documentation Index
Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt
Use this file to discover all available pages before exploring further.
Trellis is a Team-level Agent Harness with built-in LLM wiki.
In implementation terms, that means two systems share the same project files:
- Agent Harness: workflow state, hooks, skills, sub-agents, and platform adapters that control how AI coding work moves.
- Built-in LLM wiki: specs, tasks, research, and journals stored in the repository so AI sessions can reload project knowledge from files.
- Team-level layer: git-tracked workflow/spec/task files plus per-developer workspace memory, so multiple people and multiple AI tools operate against the same conventions.
This document maps that idea to the current Trellis feature set, the modules that implement each feature, and the files to inspect when customizing a generated project. For the user flow, see How It Works.
Trellis is AGPL-3.0 licensed. Internal team use is permitted. Commercial use of a Trellis-derived product or service requires prior contact: [email protected].
Design principles
Trellis treats AI coding as a workflow and knowledge-management problem, not a single chat session.
| Principle | Implementation rule |
|---|
| Make workflow state explicit | Task status and [workflow-state:STATUS] blocks tell the main session what phase it is in. |
| Store durable knowledge in files | Requirements, specs, research, and journals live under .trellis/, not only in conversation history. |
| Split work by responsibility | Research, implementation, and checking use separate agents or skills depending on platform capability. |
| Keep context scoped | JSONL manifests list the spec/research files needed for the current task instead of dumping the whole repo. |
| Preserve the review boundary | Implement/check agents produce a clean diff; the main session proposes commits, and /trellis:finish-work only archives and journals. |
| Support teams and tool diversity | The same .trellis/ model is adapted into Claude Code, Cursor, Codex, OpenCode, Kiro, Gemini, Qoder, Copilot, Droid, Pi, Kilo, Antigravity, Windsurf, and related tools. |
Feature overview
Agent Harness
| Feature | What it does |
|---|
| Three-phase workflow | Defines Plan, Execute, and Finish in .trellis/workflow.md. |
| Per-turn workflow-state breadcrumb | Injects the current next-action rule into the main session on hook-capable platforms. |
| Task lifecycle | Stores requirements, status, assignee, branch, PR metadata, and subtask relationships in .trellis/tasks/<task>/. |
| Research / implement / check roles | Separates investigation, code writing, and verification. |
| Read-before-write enforcement | Makes implement/check paths read PRD and relevant specs before changing files. |
| Finish boundary | Separates final verification, spec update, work commit, task archive, and journal writing. |
Built-in LLM wiki
| Feature | What it stores |
|---|
| Spec library | Project conventions and thinking guides under .trellis/spec/. |
| Task knowledge | PRDs, research, info docs, and JSONL manifests under .trellis/tasks/. |
| Workspace memory | Per-developer journals under .trellis/workspace/<developer>/. |
| Workflow documentation | The executable workflow contract in .trellis/workflow.md. |
| Local customization map | Bundled trellis-meta references explaining which generated files own each behavior. |
Team-level behavior
| Feature | What it enables |
|---|
| Git-tracked workflow/spec/task files | New team members clone the same workflow and conventions. |
| Per-session active task pointers | Multiple windows can work on different tasks without sharing one global current task. |
| Subtask trees | Parent tasks can hold shared requirements while child tasks run their own Plan -> Execute -> Finish loop. |
| Cross-platform adapters | Teams can use different AI tools while keeping the same .trellis/ facts. |
| Spec distillation | Lessons from one task can be promoted into .trellis/spec/ for future tasks. |
Feature to module map
| Feature | Primary module | Local files to inspect |
|---|
| Workflow phases and routing | Workflow module | .trellis/workflow.md |
| Per-turn next-action injection | Workflow-state module | [workflow-state:STATUS] blocks, inject-workflow-state.py or equivalent plugin |
| Task creation, status, archive | Task store module | .trellis/tasks/<task>/task.json, .trellis/scripts/task.py, .trellis/scripts/common/task_store.py |
| Session-scoped current task | Active-task runtime | .trellis/.runtime/sessions/<session-key>.json, .trellis/scripts/common/active_task.py |
| PRD/spec injection | Context-loading module | implement.jsonl, check.jsonl, inject-subagent-context.py, platform agent preludes |
| Research / implement / check roles | Agent and skill module | Platform agents/, skills/, prompts, workflows |
| Team convention memory | Spec module | .trellis/spec/**/index.md, guideline files |
| Developer memory | Workspace module | .trellis/workspace/<developer>/journal-*.md |
| Platform support | Platform adapter module | .claude/, .codex/, .cursor/, .opencode/, .kiro/, .gemini/, .qoder/, .github/, .pi/, and related settings |
| Finish and archive | Finish module | /trellis:finish-work, .trellis/scripts/add_session.py, task archive scripts |
Workflow module
.trellis/workflow.md is the source of truth for Trellis’s Plan -> Execute -> Finish contract.
Phase 1: Plan -> create a task, write prd.md, curate JSONL context
Phase 2: Execute -> implement, check, and repeat until green
Phase 3: Finish -> final verification, spec update, work commit, archive
- phase definitions and numbered steps
- skill / sub-agent routing by platform capability
[workflow-state:STATUS] blocks used by the per-turn breadcrumb hook
Changing workflow behavior starts here. Platform commands, skills, and agent files may also need wording updates if they describe the same flow, but the workflow contract itself belongs in .trellis/workflow.md.
Workflow-state module
On hook-capable platforms, inject-workflow-state.py or the equivalent plugin runs on each user prompt.
The runtime contract is:
- Resolve the Trellis root from
cwd.
- Resolve the active task for the current session.
- Read
task.json.status, or synthesize no_task when no task is active.
- Parse
.trellis/workflow.md.
- Inject the matching
[workflow-state:STATUS] body into <workflow-state>...</workflow-state>.
Marker syntax:
[workflow-state:planning]
...
[/workflow-state:planning]
Refer to workflow.md for current step.
Default statuses:
| Status | Writer | Notes |
|---|
no_task | Synthesized by the hook | No active task pointer for the current session. |
planning | task.py create | Requirements, research, and JSONL curation are active. |
in_progress | task.py start | Implementation, checking, and finish steps are active. |
completed | task.py archive | Written immediately before archive move; not normally visible as a live breadcrumb. |
task.py create best-effort sets the current session’s active-task pointer, so planning is reachable during brainstorm and JSONL curation.
Task store module
Each task is one directory:
.trellis/tasks/<MM-DD-slug>/
├── task.json
├── prd.md
├── info.md
├── implement.jsonl
├── check.jsonl
└── research/
| File | Purpose |
|---|
task.json | Status, priority, assignee, branch, PR URL, parent/child relationships, and extension metadata. |
prd.md | Requirements and acceptance criteria. |
info.md | Optional technical design. |
implement.jsonl | Spec and research files the implementation path must read first. |
check.jsonl | Spec and research files the verification path must read first. |
research/ | Research artifacts written by trellis-research or the main planning flow. |
| Lifecycle event | Fires when | Meaning |
|---|
after_create | task.py create finishes | A task directory exists. |
after_start | task.py start finishes | The task entered in_progress. |
after_finish | task.py finish clears the session pointer | The current AI session detached from the task; the task may still be active elsewhere. |
after_archive | task.py archive finishes | The task is archived; use this for external “done” sync. |
Active-task runtime module
The current task is session-scoped:
.trellis/.runtime/sessions/<session-key>.json
.trellis/.current-task is a fallback for command-line contexts. Session-scoped runtime pointers take precedence when the platform provides a session identity.
Context-loading module
Trellis loads context through three paths:
| Context type | Source | Used by |
|---|
| Startup context | .trellis/scripts/get_context.py | Main session startup report. |
| Per-turn workflow state | .trellis/workflow.md blocks | Main session next-action guidance. |
| Sub-agent task/spec context | prd.md, info.md, implement.jsonl, check.jsonl, research files | Research, implement, and check roles. |
{"file": ".trellis/spec/docs-site/docs/style-guide.md", "reason": "Docs writing style"}
implement.jsonl and check.jsonl list spec and research files. Seed rows without a file field are ignored. Source files are read during implementation and review, not pre-registered in JSONL.
Trellis uses each platform’s available primitives. The generated project files are the source of truth for an actual repository, but the default capability groups are:
| Group | Platforms | Startup context | Per-turn workflow-state | Implementation/check context |
|---|
| Hook + hook-push sub-agent | Claude Code, Cursor, OpenCode, CodeBuddy, Droid, Pi | Hook, plugin, or extension | Hook or equivalent | Hook injects PRD + JSONL files before sub-agent starts. |
| Hook + pull-prelude sub-agent | Gemini CLI, Qoder, Copilot | Hook | Hook | Sub-agent reads PRD + JSONL itself on startup. |
| Codex | Codex | AGENTS.md; SessionStart when features.hooks = true (legacy: codex_hooks = true) | Optional hook when enabled (0.129+ also requires /hooks review) | Pull-based prelude plus shared .agents/skills/. |
| Kiro | Kiro | Skill files under .kiro/ | No Trellis per-turn hook by default | Agent/skill files read Trellis context. |
| Main-session workflow/skill | Kilo, Antigravity, Windsurf | Manual workflow or skill entry | No Trellis per-turn hook by default | Main session reads specs and task files inline. |
Agent and skill module
Trellis 0.5 ships three sub-agent roles when the platform supports sub-agents:
| Sub-agent | Role | Primary context |
|---|
trellis-research | Investigate code, docs, APIs, and alternatives; write findings under research/. | Research prompt plus optional research context. |
trellis-implement | Write the change against the PRD and relevant specs. | prd.md, info.md, implement.jsonl. |
trellis-check | Review, run checks, and self-fix findings. | prd.md, check.jsonl, changed files. |
dispatch, plan, and debug sub-agents were replaced by skill routing.- The SubagentStop-based Ralph Loop was replaced by
trellis-check owning its retry loop.
- Trellis no longer ships its own
/parallel worktree orchestrator; use the platform’s native worktree support.
LLM wiki modules
The wiki side is a set of repository files that AI sessions can reread.
| Module | Path | Contents |
|---|
| Spec library | .trellis/spec/ | Team conventions, package/layer rules, thinking guides. |
| Task knowledge | .trellis/tasks/ | PRDs, research, technical notes, JSONL manifests, archive. |
| Workspace memory | .trellis/workspace/<developer>/ | Per-developer journals and indexes. |
| Workflow reference | .trellis/workflow.md | The workflow contract and next-action prompt blocks. |
| Trellis meta reference | bundled trellis-meta skill | Local architecture and customization map for generated Trellis files. |
.trellis/spec/. Task-specific facts belong in the task directory. Session notes belong in .trellis/workspace/<developer>/.
Finish module
Trellis separates implementation, work commits, and bookkeeping:
- Implement/check agents produce a clean diff.
- The main session runs final verification and
trellis-update-spec.
- Phase 3.4 proposes a batched commit plan, waits for one user confirmation, stages the listed files, and runs
git commit. It does not amend and does not push.
/trellis:finish-work archives the task and writes the workspace journal. It refuses to run on a dirty tree.
/trellis:finish-work is not the command that commits feature code. Work commits happen first; archive and journal commits are bookkeeping after that.
Generated and protected files
trellis init and trellis update generate local files, but local edits matter:
| Path | Rule of thumb |
|---|
.trellis/workflow.md | Project workflow source of truth; update deliberately. |
.trellis/spec/ | Team-owned; template updates do not overwrite package/layer specs. |
.trellis/tasks/ | Work history; avoid manually deleting active tasks. |
| Platform directories | Tool adapters; inspect local settings before changing behavior. |
.trellis/.template-hashes.json | Managed hash index; edit only when repairing update state. |
.trellis/.runtime/ | Runtime state; normally not edited by hand. |
trellis-meta skill as the map. It tells an AI to read local architecture references first, inspect actual project files, and modify the project copy instead of changing node_modules or a global install.
Customization map
| Goal | First file to inspect |
|---|
| Change phase order, required steps, or next-action wording | .trellis/workflow.md |
| Change task creation, status, archive, or lifecycle sync | .trellis/scripts/common/task_store.py, .trellis/scripts/task.py, .trellis/config.yaml |
| Change spec loading or JSONL rules | .trellis/workflow.md, .trellis/scripts/common/task_context.py, platform agent/prelude files |
| Change hook behavior | Platform hook settings plus .trellis/scripts/ hook implementations |
| Change implement/check agent behavior | Platform agent files and task JSONL context rules |
| Add team-specific coding rules | .trellis/spec/ or a project-local skill |
