Overview

Specs, tasks, workspace - how they fit together

​

The problem Trellis solves

AI coding assistants are smart, but they don’t know your codebase. Every session starts blank. Claude doesn’t know you use snake_case for database columns. Cursor doesn’t know your error handling pattern. You end up explaining the same things over and over.

Trellis fixes this by writing conventions down once and injecting them automatically. The AI gets your context before writing a single line of code.

​

Three systems, one workflow

Trellis has three main pieces:

​

Specs

Your coding standards, written in markdown. Stored in .trellis/spec/.

.trellis/spec/
├── frontend/
│   └── index.md      # React patterns, component structure
├── backend/
│   └── index.md      # API conventions, error handling
└── guides/
    └── index.md      # General thinking guides

When you start a coding session, relevant specs get injected into the AI’s context. The AI reads them before doing anything else.

​

Tasks

Work items with their own context. Stored in .trellis/tasks/.

.trellis/tasks/01-31-user-auth-taosu/
├── task.json         # Metadata, status, branch
├── prd.md            # What you're building
├── implement.jsonl   # Files the implement agent should read
└── check.jsonl       # Files the check agent should review

Each task can specify exactly which files and specs are relevant. The implement agent only sees what it needs.

​

Workspace

Session history per developer. Stored in .trellis/workspace/.

.trellis/workspace/
├── index.md          # Overview
└── taosu/
    ├── index.md      # Personal index
    └── journal-1.md  # What happened in each session

This lets you pick up where you left off. Start a new session, and the AI knows what you did yesterday.

​

How they connect

┌─────────────────────────────────────────────────────────┐
│                     You start a task                     │
└─────────────────────────────┬───────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────┐
│  Hooks inject:                                           │
│  - Relevant specs from .trellis/spec/                   │
│  - Task context from .trellis/tasks/{task}/             │
│  - Session history from .trellis/workspace/             │
└─────────────────────────────┬───────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────┐
│  AI writes code following your conventions               │
└─────────────────────────────┬───────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────┐
│  Session ends → journal updated → ready for next time   │
└─────────────────────────────────────────────────────────┘

​

What makes this different

Other tools try to make AI “remember” things. Trellis doesn’t rely on memory. It injects context fresh every time. The AI can’t forget what you told it because you’re telling it again.

This also means specs are version-controlled. When conventions change, you update the spec file. Everyone gets the new rules automatically.

​

Next steps

Write specs

How to write specs that actually work.

Manage tasks

Create and track work with the task system.