zl-q
04b493ed09
- Remove legacy .opencode/ directory and configuration - Update .trellis/ to v0.5.0-rc.6 structure - Refactor scripts: modularize common/, remove multi_agent/ - Add new common modules: git.py, io.py, log.py, types.py, etc. - Update workflow.md and AGENTS.md - Archive completed migration tasks
3.8 KiB
Local Files Generated After Init
trellis init writes the Trellis runtime into the user project. Later, trellis update tries to update Trellis-managed template files, but it uses .trellis/.template-hashes.json to determine which files have already been modified by the user.
This page only describes files that are visible and editable inside the user project.
.trellis/
.trellis/
├── workflow.md
├── config.yaml
├── .developer
├── .version
├── .template-hashes.json
├── .runtime/
├── scripts/
├── spec/
├── tasks/
└── workspace/
| Path | Usually editable? | Notes |
|---|---|---|
.trellis/workflow.md |
Yes | Local workflow documentation and AI routing rules. |
.trellis/config.yaml |
Yes | Project configuration, hooks, packages, journal line limits, and related settings. |
.trellis/spec/ |
Yes | Project specs, intended to be updated regularly by users and AI. |
.trellis/tasks/ |
Yes | Task material and research artifacts, maintained by the task workflow. |
.trellis/workspace/ |
Yes | Session records, usually written by add_session.py. |
.trellis/scripts/ |
Carefully | Local runtime. It can be customized, but only after understanding the call chain. |
.trellis/.runtime/ |
No | Runtime state, usually written automatically by hooks/scripts. |
.trellis/.developer |
Carefully | Current developer identity. |
.trellis/.version |
No | Trellis version record used by update/migration logic. |
.trellis/.template-hashes.json |
No | Template hash record. Do not hand-write business rules here. |
Platform Directories
Different platforms generate different directories. Common categories:
| Category | Example paths | Purpose |
|---|---|---|
| hooks | .claude/hooks/, .codex/hooks/, .cursor/hooks/ |
Inject session context, workflow-state, and sub-agent context. |
| settings | .claude/settings.json, .codex/hooks.json, .qoder/settings.json |
Tell the platform when to run hooks or plugins. |
| agents | .claude/agents/, .codex/agents/, .kiro/agents/ |
Define agents such as trellis-research, trellis-implement, and trellis-check. |
| skills | .claude/skills/, .agents/skills/, .qoder/skills/ |
Skills that auto-trigger or can be read by AI. |
| commands/prompts/workflows | .cursor/commands/, .github/prompts/, .windsurf/workflows/ |
Explicit user-invoked command or workflow entry points. |
When modifying a platform directory, also confirm whether .trellis/workflow.md still describes the same flow.
Meaning Of Template Hashes
.trellis/.template-hashes.json records the content hash from the last time Trellis wrote a template file. trellis update uses it to distinguish three cases:
| Case | Update behavior |
|---|---|
| File was not modified by the user | It can be updated automatically. |
| File was modified by the user | Prompt the user to overwrite, keep, or generate .new. |
| File is no longer a current template | It may be deleted, renamed, or preserved according to migration rules. |
When an AI customizes local Trellis files, it does not need to maintain hashes manually. It is normal for Trellis update to recognize the result as "modified by the user."
Local Customization Boundaries
Editable by default:
.trellis/workflow.md.trellis/config.yaml.trellis/spec/**.trellis/scripts/**- Platform hooks, settings, agents, skills, commands, prompts, and workflows
Do not edit by default:
- Global npm install directory
node_modules/@mindfoldhq/trellis- Trellis GitHub repository source code
- Concrete state files under
.trellis/.runtime/** - Hash contents inside
.trellis/.template-hashes.json
Switch to the Trellis CLI source-code perspective only when the user explicitly wants to contribute upstream.