Trellis

Trellis acts as a bridge between a codebase and multiple AI coding platforms (Claude Code, Cursor, OpenCode, Gemini CLI) by maintaining a .trellis/ directory as a Single Source of Truth. The framework auto-injects project-specific specs, task context, and coding guidelines into each AI session via platform-specific integration layers (.claude/, .cursor/, etc.), ensuring every agent operates within consistent project conventions and historical context without manual context setup per session.

Trellis provides a task management system (.trellis/tasks/) that structures AI-assisted work around discrete tasks, each with a PRD (product requirements document), context files, and a task.json state file. Tasks follow a defined lifecycle tracked in task.json, enabling AI agents to understand task scope, dependencies, and completion criteria. The system supports task archival (tasks/archive/) and integrates with the multi-agent pipeline to decompose high-level developer intent into concrete coding work.

Trellis provides developer workflow commands (e.g., via CLI or platform-specific slash commands) that enable developers to create tasks, update task state, and manage project context without leaving their AI platform. Commands like 'create task', 'update task status', and 'add to journal' interact with the task management system and workspace, enabling seamless integration of developer actions into the Trellis workflow. These commands are routed through the CLIAdapter and executed as backend scripts.

Trellis includes a marketplace and template registry that enables teams to discover, share, and reuse project configurations, specs, and task templates contributed by the community. The registry is indexed and searchable, allowing developers to find templates for common project types (microservices, libraries, web apps, etc.) and integrate them into their projects. Registry entries include metadata (name, version, description, tags) and are version-controlled, enabling reproducible template usage.

Trellis supports backend script execution via Python and shell scripts (.trellis/scripts/) that implement task logic, command handlers, and platform integrations. Scripts can access project context (specs, tasks, workspace) via environment variables and file system APIs, and can update task state by modifying task.json files. The script execution layer abstracts platform differences and provides a unified interface for implementing Trellis workflows in Python or shell.

Trellis defines unit test conventions and thinking guides in the spec system that establish standards for test coverage, test structure, and code quality expectations. These conventions are auto-injected into AI sessions, guiding agents to generate code with appropriate test coverage and following project-specific testing patterns. The system includes golden tests (reference implementations) that agents can learn from, and integrates with CI/CD to validate generated code against test conventions.

Trellis supports monorepo structures with a build pipeline and release management system that coordinates builds, tests, and releases across multiple packages. The system uses a TypeScript-based build pipeline (scripts in packages/cli/src/) that orchestrates package builds, test execution, and versioning. Release versioning is managed via .trellis/.version and migration manifests, enabling coordinated releases across the Trellis framework and community templates.

Trellis maintains a .trellis/spec/ directory containing project standards, patterns, coding guidelines, and architectural decisions in markdown format. These specs are automatically injected into AI agent sessions via the context injection layer, ensuring every coding task adheres to project conventions without manual specification per session. The spec system supports hierarchical organization (e.g., spec/cli/backend/) and integrates with the platform integration layer to customize injections per platform.

Trellis implements a context injection layer that automatically loads and injects project context (specs, task details, workspace journals) into AI agent sessions before code generation begins. Session scripts (Python/shell) are executed to prepare the environment, set up state, and configure platform-specific hooks. The CLIAdapter pattern detects the active AI platform and routes context appropriately, supporting Claude Code, Cursor, OpenCode, and other platforms with platform-specific entry points.

Trellis maintains developer-specific workspace journals (.trellis/workspace/<developer>/) as markdown files (e.g., journal-4.md) that preserve project memory, design decisions, and session notes across AI-assisted work. Journals are version-controlled and can be injected into AI sessions as context, enabling agents to understand the project's evolution and previous decisions. The workspace system supports multiple developers with isolated journal spaces while maintaining shared project context via specs and tasks.

Trellis implements a multi-agent pipeline that decomposes high-level developer intent into discrete tasks and coordinates multiple AI agents across those tasks. The pipeline uses the task management system to track decomposition, dependencies, and state, enabling sequential or parallel execution of AI-assisted work. Agents communicate via task.json state files and context injection, creating a workflow where each agent understands its role, dependencies, and success criteria.

Trellis provides a platform integration layer that abstracts differences between AI coding platforms (Claude Code, Cursor, OpenCode, Gemini CLI) via a CLIAdapter pattern. The adapter detects the active platform, routes context injection appropriately, and executes platform-specific hooks and entry points. Platform configurators generate platform-specific configuration files (.claude/, .cursor/, etc.) during initialization, enabling seamless switching between tools while maintaining consistent project context.

Trellis provides a template system (.trellis/templates/) that scaffolds new projects with pre-configured specs, task structures, and integration layers. Templates are extracted and customized during initialization via the Init command, enabling teams to standardize project structure across multiple repositories. The template registry supports community-contributed templates, enabling reuse of proven project configurations and coding guidelines.

Trellis provides a TypeScript-based CLI (@mindfoldhq/trellis) that initializes new projects via the Init command, creating the .trellis/ directory structure and platform-specific integration files. The CLI includes an Update command with a migration system that manages version upgrades, schema changes, and breaking changes via migration manifests (e.g., 0.4.0.json). Version tracking in .trellis/.version enables automatic migration detection and execution, ensuring projects stay synchronized with CLI updates.

Trellis supports skills (Claude Code) and slash commands (Cursor, OpenCode) as platform-specific extensions that enable AI agents to perform specialized tasks within their native environments. Skills and commands are defined in platform-specific configuration files and can invoke backend scripts, access project context, or trigger Trellis workflows. The system enables teams to extend AI platform capabilities with project-specific logic without modifying the core Trellis framework.