trellis-meta - SKILL.md Agent Skill

name: trellis-meta description: "Understand and customize the local Trellis architecture inside a user project. Use when modifying .trellis plus platform hooks, settings, agents, skills, commands, prompts, workflows, the channel runtime (trellis channel), bundled runtime agents under .trellis/agents/, selectable workflow templates, registry-backed spec refresh, cross-session memory (trellis mem) generated by trellis init, or AI-facing bundled skills (trellis-channel, trellis-session-insight, trellis-spec-bootstrap) and bundled-skill auto-dispatch flow."

Trellis Meta

This skill is for local Trellis users who have already run trellis init in a project. After reading it, an AI should understand the Trellis architecture, operating model, and customization entry points inside that user project, then modify the generated .trellis/ and platform directory files according to the user's request.

Trellis v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow / persistence / platform model. First, a multi-agent collaboration runtime: trellis channel coordinates multiple AI worker processes through project-scoped JSONL event logs at ~/.trellis/channels/<project>/<channel>/events.jsonl, with worker OOM guard, forum/thread channels, durable idempotency keys, and bundled .trellis/agents/{check,implement}.md runtime definitions. Second, cross-session memory: trellis mem list | search | context | extract | projects reads raw Claude Code and Codex JSONL already on disk, slices by --phase brainstorm|implement|all, and never uploads anything. Third, a dual-package npm release: @mindfoldhq/trellis (CLI) and @mindfoldhq/trellis-core (SDK with /channel, /task, /mem, /testing subpaths) ship in lockstep on one version. Treat these as first-class customization surfaces alongside the per-platform integration files.

The default operating scope is local files in the user project:

.trellis/: workflow, config, tasks, spec, workspace, scripts, bundled runtime agents, and runtime state.
Platform directories: .claude/, .codex/, .cursor/, .opencode/, .kiro/, .gemini/, .qoder/, .codebuddy/, .github/, .factory/, .pi/, .reasonix/, .kilocode/, .agent/, .windsurf/, and similar directories. Pi additionally exposes a native trellis_subagent tool with single / parallel / chain dispatch modes, throttled progress cards, and isTrellisAgent() validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as .reasonix/skills/<name>/SKILL.md; subagent skills carry runAs: subagent frontmatter.
Shared skill layer: .agents/skills/.
User-owned channel store outside the project tree: ~/.trellis/channels/<project>/<channel>/events.jsonl.
Raw platform conversation logs queryable via trellis mem: ~/.claude/projects/ and ~/.codex/sessions/ (OpenCode adapter degraded for the v0.6 line).

Do not assume the user has the Trellis source repository. Do not default to modifying the global npm install directory or node_modules — both @mindfoldhq/trellis and @mindfoldhq/trellis-core ship as published packages sharing one version and one git tag per release.

How To Use

Read references/local-architecture/overview.md first to establish the local Trellis system model.
If the request involves a specific AI tool, read references/platform-files/platform-map.md and the relevant platform file notes.
If the request involves multi-agent dispatch or channel workers, read references/local-architecture/multi-agent-channel.md and the bundled .trellis/agents/ files.
If the user wants to change behavior, read references/customize-local/overview.md, then open the specific customization topic.
Before editing, read the actual files in the user project and treat local content as authoritative.

References

Local Architecture

references/local-architecture/overview.md: The layered local Trellis architecture (workflow / persistence / platform / channel runtime) and customization principles.
references/local-architecture/generated-files.md: Files generated by trellis init and their customization boundaries, including .trellis/agents/.
references/local-architecture/workflow.md: Phases, routing, workflow-state blocks, and selectable workflow templates (native, tdd, channel-driven-subagent-dispatch, marketplace) in .trellis/workflow.md.
references/local-architecture/task-system.md: Task directories, active task, JSONL context, parent/child task trees, and task runtime.
references/local-architecture/spec-system.md: How .trellis/spec/ is organized, injected, and refreshed from a registry.spec source.
references/local-architecture/workspace-memory.md: .trellis/workspace/ journals plus trellis mem cross-session recall and the @mindfoldhq/trellis-core/mem SDK.
references/local-architecture/context-injection.md: Hooks, sub-agent preludes, and channel-runtime worker inbox routing.
references/local-architecture/multi-agent-channel.md: trellis channel subcommands, project-scoped event store, forum/thread channels, worker OOM guard, durable idempotency, and bundled .trellis/agents/ runtime agents.
references/local-architecture/bundled-skills.md: Auto-dispatched bundled skills (trellis-meta, trellis-spec-bootstrap, trellis-session-insight) and how getBundledSkillTemplates() ships them to every platform skill root.

Platform Files

references/platform-files/overview.md: How shared .trellis/ files relate to platform directories and the four platform integration modes (hook-driven, agent prelude, main-session workflow, channel runtime).
references/platform-files/platform-map.md: Platform directories and paths for skills, agents, hooks, and extensions across all 15 supported platforms including Reasonix and Pi's native trellis_subagent extension.
references/platform-files/hooks-and-settings.md: How settings/config files, hooks, plugins, and extensions connect to Trellis; covers channel.worker_guard.* and codex.dispatch_mode.
references/platform-files/agents.md: Per-platform trellis-research / trellis-implement / trellis-check sub-agent files plus bundled .trellis/agents/{check,implement}.md for the channel runtime.
references/platform-files/skills-and-commands.md: Differences between skills, commands, prompts, and workflows, plus how to change them.

Local Customization

references/customize-local/overview.md: Choose the right local customization entry point for the user's request.
references/customize-local/change-workflow.md: Change phases, routing, next actions, workflow-state, and the selected workflow template.
references/customize-local/change-task-lifecycle.md: Change task creation, status, archive behavior, parent/child links, archive slug collision handling, and lifecycle hooks.
references/customize-local/change-context-loading.md: Change how tasks, specs, journals, hook context, channel inbox messages, and trellis mem recall are loaded.
references/customize-local/change-hooks.md: Change platform hooks, settings, task lifecycle hooks (hooks.after_*), and shell session bridges.
references/customize-local/change-agents.md: Change research, implement, and check agent behavior across platform sub-agents, bundled channel runtime agents, and the Codex dispatch_mode toggle.
references/customize-local/change-skills-or-commands.md: Add or modify local skills, commands, prompts, and workflows; covers upstream bundled-skill auto-dispatch.
references/customize-local/change-spec-structure.md: Adjust the project spec structure under .trellis/spec/, including registry-backed sources.
references/customize-local/add-project-local-conventions.md: Put team rules into project-local specs or local skills.

Current Rules

.trellis/workflow.md is the local workflow source of truth; its initial content was selected from a workflow template (built-in native, tdd, channel-driven-subagent-dispatch, or a marketplace template) at trellis init time and can be re-selected via trellis workflow --template <id>. Missing .trellis/agents/<name>.md files referenced by the active template trigger a non-blocking stderr warning pointing at trellis update.
.trellis/config.yaml is the project-level Trellis configuration entry point. It hosts task lifecycle hooks (hooks.after_create / after_start / after_finish / after_archive), journal shape (session_commit_message / max_journal_lines / session_auto_commit), channel worker guard (channel.worker_guard.idle_timeout / max_live_workers), Codex dispatch mode (codex.dispatch_mode: inline | sub-agent), and the spec registry block (registry.spec.source + registry.spec.template).
.trellis/spec/ stores the user's project-specific coding conventions and design constraints. When registry.spec is set, files are refreshed by trellis update; local edits surface as "modified by user" conflicts in .trellis/.template-hashes.json.
.trellis/tasks/ stores task PRDs, design notes, implement plans, research files, and JSONL context. Tasks form parent/child trees: task.py create --parent <slug>, task.py add-subtask <parent> <child>, task.py remove-subtask <parent> <child>, and task.py list-context <task>. task.py create rejects a slug already present in .trellis/tasks/archive/**.
.trellis/workspace/ stores deliberately written developer journals. Raw cross-session dialogue is not stored here — it lives on disk under ~/.claude/projects/ and ~/.codex/sessions/ and is recovered via trellis mem search|extract|context. The bundled trellis-session-insight skill teaches when to reach for mem.
.trellis/agents/{check,implement}.md are bundled, platform-agnostic channel runtime agent definitions loaded by trellis channel spawn --agent <name>. Editable; trellis update backfills missing ones. Editing the per-platform trellis-implement.md / trellis-check.md does not change channel-runtime worker behavior.
~/.trellis/channels/<project>/<channel>/events.jsonl is the channel runtime event log per project per channel. User-owned, file-locked sequence numbering, durable idempotencyKey support; never under .trellis/.
Bundled multi-file skills (trellis-meta, trellis-spec-bootstrap, trellis-session-insight, trellis-channel) are auto-dispatched to every platform skill root by getBundledSkillTemplates() in packages/cli/src/templates/common/index.ts. Dropping a new directory under packages/cli/src/templates/common/bundled-skills/ (upstream) ships it to every platform on the next trellis update.
Platform settings/config files decide which hooks, agents, skills, commands, prompts, and workflows actually run. Reasonix has no settings file — behavior is encoded inside skill frontmatter.
.trellis/.template-hashes.json and .trellis/.runtime/ are management/runtime state files. Confirm necessity before editing them.

Do Not

Do not treat Trellis upstream source code as the default target for local customization.
Do not modify the global npm install directory or node_modules/@mindfoldhq/trellis or node_modules/@mindfoldhq/trellis-core to implement project needs; both packages ship in lockstep.
Do not overwrite user-modified local files with default templates; check .trellis/.template-hashes.json first and prefer .new sidecar files over destructive overwrites.
Do not put team-private project rules into any public bundled skill (trellis-meta, trellis-spec-bootstrap, trellis-session-insight, trellis-channel); put project rules in .trellis/spec/, a project-local skill, the current task, or the workspace journal — trellis update will overwrite anything inside a bundled skill directory.
Do not hand-edit ~/.trellis/channels/<project>/<channel>/events.jsonl; sequence numbers are assigned under a file lock and replay-safe writes go through the trellis channel CLI or the @mindfoldhq/trellis-core/channel SDK.
Do not edit .claude/agents/trellis-implement.md (or any other per-platform sub-agent file) when the goal is to change channel runtime worker behavior — edit .trellis/agents/<name>.md instead.
Do not describe removed or never-shipped mechanisms as current Trellis behavior; cross-check against the local .trellis/config.yaml and the installed CLI's trellis --help before claiming a knob exists.