trellis-meta

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

1. Read references/local-architecture/overview.md first to establish the local Trellis system model.
2. If the request involves a specific AI tool, read references/platform-files/platform-map.md and the relevant platform file notes.
3. If the request involves multi-agent dispatch or channel workers, read references/local-architecture/multi-agent-channel.md and the bundled .trellis/agents/ files.
4. If the user wants to change behavior, read references/customize-local/overview.md, then open the specific customization topic.
5. 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.