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.

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

• .trellis/: workflow, config, tasks, spec, workspace, scripts, and runtime state.
• Platform directories: .claude/, .codex/, .cursor/, .opencode/, .kiro/, .gemini/, .qoder/, .codebuddy/, .github/, .factory/, .pi/, .kilocode/, .agent/, .windsurf/, and similar directories.
• Shared skill layer: .agents/skills/.

Do not assume the user has the Trellis source repository. Do not default to modifying the global npm install directory or node_modules.

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 user wants to change behavior, read references/customize-local/overview.md, then open the specific customization topic.
4. 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 three-layer local Trellis architecture and customization principles.
• references/local-architecture/generated-files.md: Files generated by trellis init and their customization boundaries.
• references/local-architecture/workflow.md: Phases, routing, and workflow-state blocks in .trellis/workflow.md.
• references/local-architecture/task-system.md: Task directories, active tasks, JSONL context, and task runtime.
• references/local-architecture/spec-system.md: How .trellis/spec/ is organized and injected.
• references/local-architecture/workspace-memory.md: .trellis/workspace/, journals, and cross-session memory.
• references/local-architecture/context-injection.md: Hooks, sub-agent preludes, and context injection paths.

Platform Files

• references/platform-files/overview.md: How shared .trellis/ files relate to platform directories.
• references/platform-files/platform-map.md: Platform directories and paths for skills, agents, hooks, and extensions.
• references/platform-files/hooks-and-settings.md: How settings/config files, hooks, plugins, and extensions connect to Trellis.
• references/platform-files/agents.md: Local file responsibilities for trellis-research, trellis-implement, and trellis-check.
• 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, and workflow-state.
• references/customize-local/change-task-lifecycle.md: Change task creation, status, archive behavior, and hooks.
• references/customize-local/change-context-loading.md: Change how tasks, specs, journals, and hook context are loaded.
• references/customize-local/change-hooks.md: Change platform hooks, settings, and shell session bridges.
• references/customize-local/change-agents.md: Change research, implement, and check agent behavior.
• references/customize-local/change-skills-or-commands.md: Add or modify local skills, commands, prompts, and workflows.
• references/customize-local/change-spec-structure.md: Adjust the project spec structure under .trellis/spec/.
• 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.
• .trellis/config.yaml is the project-level Trellis configuration and task hook configuration entry point.
• .trellis/spec/ stores the user's project-specific coding conventions and design constraints.
• .trellis/tasks/ stores task PRDs, technical notes, research files, and JSONL context.
• .trellis/workspace/ stores developer journals and cross-session memory.
• Platform settings/config files decide which hooks, agents, skills, commands, prompts, and workflows actually run.
• .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 to implement project needs.
• Do not overwrite user-modified local files with default templates.
• Do not put team-private project rules into the public trellis-meta; put project rules in .trellis/spec/ or a project-local skill.
• Do not describe removed historical mechanisms as current Trellis behavior.