DEV Community

Cover image for Open Source Project of the Day (#109): Trellis — Persist Project Specs, Tasks, and Memory Into Your Repository
WonderLab
WonderLab

Posted on

Open Source Project of the Day (#109): Trellis — Persist Project Specs, Tasks, and Memory Into Your Repository

#ai #claude #agents #opensource

Introduction

"AI coding is 10% coding and 90% re-explaining your stack. Trellis fixed the worst part of AI agents: amnesia."

This is article #109 in the Open Source Project of the Day series. Today's project is Trellis — an AI coding agent harness that persists project specs, task context, and session memory into your repository.

You spend a session with Claude Code getting things right: conventions explained, context established, good results produced. You close the terminal. Next day: start over. Re-explain the tech stack choices, re-describe the code style, re-frame the current task's background.

This has a name: agent amnesia. Every session starts fresh, and all accumulated context disappears.

Trellis stores what should be remembered inside the repository: .trellis/spec/ for conventions, .trellis/tasks/ for tasks and PRDs, .trellis/workspace/ for session journals. The agent reads these on startup — no re-explaining required.

What You'll Learn

  • The three-directory system: why spec / tasks / workspace each have distinct roles
  • The 4-phase workflow: Plan → Implement → Verify → Finish as a complete loop
  • Trellis Skills: what each of the four built-in workflow modules does
  • Comparison with CLAUDE.md / AGENTS.md: why single-file approaches become monoliths
  • Team scenario: how committing specs to Git benefits the whole team
  • Supported platforms and initialization

Prerequisites

  • Experience with Claude Code, Cursor, or a similar AI coding tool
  • Familiarity with basic Git workflow
  • Basic familiarity with CLAUDE.md or .cursorrules concepts

Project Background

What Is Trellis?

Trellis is an AI coding agent harness — "scaffolding for AI, guiding it along the path of your conventions."

"Harness" as a term is gaining traction in 2026 AI coding discussions: not the agent itself, but the constraints, memory, and workflow structure built around it. Trellis is among the most systematic open-source implementations in this space, cited in academic work (the "Agent Harness Engineering: A Survey" paper on OpenReview).

The core design decision: persist everything inside the Git repository. Specs can be code-reviewed. Session memory can be team-shared. Task context works across tools. This isn't just a file path choice — it's a decision to bring AI working patterns into the engineering management system.

Author / Team

Project Stats

  • ⭐ GitHub Stars: 11,300+
  • 🍴 Forks: 641+
  • 💻 Supported platforms: 16 AI coding platforms
  • 📄 License: AGPL-3.0

Core Features

The Three-Directory System

Trellis maintains a .trellis/ directory at the repository root with three subdirectories:

.trellis/
├── spec/           ← Project conventions (commit to Git)
│   ├── coding-standards.md
│   ├── architecture.md
│   ├── tech-stack.md
│   └── team-conventions.md
│
├── tasks/          ← Tasks and PRDs (commit to Git)
│   ├── active/
│   │   └── feature-auth/
│   │       ├── prd.md
│   │       ├── implementation-context.md
│   │       └── review-context.md
│   └── completed/
│
└── workspace/      ← Session journals (optionally .gitignored)
    └── your-name/
        └── journal.md
Enter fullscreen mode Exit fullscreen mode

spec/: The core. Everything you don't want to re-explain to an agent every session: the reasoning behind technology choices, code style rules, architecture constraints, naming conventions, known pitfalls. Committed to Git, automatically injected into the agent's context at session start.

tasks/: Tasks are complete work units, not single-line descriptions. Each task has a PRD (product requirements document), implementation context (everything the agent needs to know before writing code), and review context (what to check the diff against).

workspace/: Per-developer session journals. Records what happened this session, what problems were encountered, and what the next session needs to know to continue. The agent reads this file when a new session starts.

The 4-Phase Workflow

Trellis defines a complete work loop:

Plan → Implement → Verify → Finish
  ↑                                ↓
  └──────── spec updated ←─────────┘
Enter fullscreen mode Exit fullscreen mode

Phase 1: Plan (trellis-brainstorm)

Clarify requirements before writing any code:

Invoke trellis-brainstorm
    ↓
Agent walks you through requirement clarification:
  "What does success look like for this feature?"
  "Are there technical constraints to respect?"
  "What edge cases need to be handled?"
    ↓
Produces prd.md (product requirements document)
Research-heavy subtasks → dispatched to sub-agent
    ↓
PRD saved to .trellis/tasks/active/[task-name]/
Enter fullscreen mode Exit fullscreen mode

Phase 2: Implement (trellis-implement)

Context auto-injected at execution time:

Invoke trellis-implement
    ↓
Automatically reads:
  - Relevant specs from .trellis/spec/
  - .trellis/tasks/active/[task-name]/prd.md
  - .trellis/workspace/[your-name]/journal.md
    ↓
Writes code according to the PRD, respecting spec constraints
Enter fullscreen mode Exit fullscreen mode

Phase 3: Verify (trellis-check)

Automated review after code is written:

Invoke trellis-check
    ↓
Compare against spec: does the diff conform to standards?
Run lint, type checking, tests
Issues found → attempt self-correction
Self-correction fails → report to developer
Enter fullscreen mode Exit fullscreen mode

Phase 4: Finish (trellis-update-spec)

The most valuable part of the loop:

Invoke trellis-update-spec
    ↓
Analyze new patterns, conventions, and rules discovered in this task
Promote those learnings into .trellis/spec/
    ↓
The next session starts smarter than this one
Enter fullscreen mode Exit fullscreen mode

Comparison with CLAUDE.md / AGENTS.md 

The problem with CLAUDE.md / .cursorrules:
  Single file → grows into a catch-all dumping ground over time
  Bulk injection → everything in context regardless of task relevance
  No task structure → no PRD, no implementation/review context separation
  No persistent memory → session ends, context is gone

What Trellis does instead:
  Modular specs → injected on demand, relevant to the task at hand
  Task context → PRD + implementation context + review context, layered
  Workspace memory → continuity across sessions
  Finish phase → spec auto-updates every time a task completes
Enter fullscreen mode Exit fullscreen mode

Trellis doesn't replace CLAUDE.md — it builds structure around it. You can still have a CLAUDE.md; Trellis spec files supplement it.

Deep Dive

Installation and Initialization 

# Install Trellis CLI
npm install -g @mindfoldhq/trellis@latest

# Navigate to your project
cd your-project

# Basic init (auto-detects installed AI tools)
trellis init -u your-name

# Platform-specific init
trellis init --claude-code --cursor --codex -u your-name
Enter fullscreen mode Exit fullscreen mode

trellis init does the following:

  1. Creates the .trellis/ directory structure
  2. Generates platform-specific configuration files for detected tools
  3. Creates initial spec templates (can be AI-generated from existing code)
  4. Handles workspace directory .gitignore according to preference

Generating initial specs for an existing project:

In Claude Code:
"Analyze this codebase and generate initial .trellis/spec/ content
 covering the tech stack, code style, and architectural constraints"

Then review and refine the generated spec files manually
Enter fullscreen mode Exit fullscreen mode

Platform Support

Trellis supports 16 AI coding platforms and generates platform-specific configuration:

Confirmed support: Claude Code, Cursor, OpenCode, Codex, GitHub Copilot, Devin, and more.

For Claude Code specifically, Trellis generates a structured CLAUDE.md and corresponding Skill files so Claude Code knows when to invoke trellis-brainstorm, trellis-implement, and the other workflow modules.

Trellis Skill System

Four built-in Skills define the workflow entry points:

Skill When to Use Core Behavior
trellis-brainstorm Starting a new task Guides requirement clarification, outputs PRD
trellis-implement Starting to write code Injects context, executes implementation
trellis-check After code is written Reviews against specs, self-corrects where possible
trellis-update-spec After task completion Promotes learnings back into spec

These Skills follow the agentskills.io open standard, the same format used by android/skills and other projects in the ecosystem.

Team Workflow

When spec files are committed to Git, the entire team benefits from the same standards:

Scenario: New team member joins
Traditional: Docs in Confluence (possibly stale); ask senior devs; stumble through
Trellis:
  After git clone → .trellis/spec/ has complete tech stack and conventions
  AI agent automatically follows those conventions
  New member is productive with team-standard AI workflows within a day
Enter fullscreen mode Exit fullscreen mode 
Scenario: Team discovers a new best practice
Traditional: Verbal knowledge transfer, or updating a doc nobody reads
Trellis:
  Someone runs trellis-update-spec → spec file updated
  Opens a PR, team reviews
  After merge, all subsequent AI sessions across the team use the new standard
Enter fullscreen mode Exit fullscreen mode

Workspace Journal Format

Session journals give agents continuity between sessions:

# Journal - your-name

## 2026-06-28
### Session summary
- Completed JWT verification logic for the auth module
- Discovered a race condition in refresh token handling under concurrent requests
- Temporary fix: Redis distributed lock, but a better approach probably exists

### What the next session needs to know
- Refresh token race condition fix needs further evaluation
- Need to write integration tests for the auth module
- Edge case: same user refreshing from multiple devices simultaneously

### Open questions
- Should we implement rotating refresh tokens? Need to confirm product requirements
Enter fullscreen mode Exit fullscreen mode

When the next session starts, the agent reads this journal, understands the context, and doesn't need re-briefing.

Quick Start 

# Install
npm install -g @mindfoldhq/trellis@latest

# Navigate to your project
cd your-project

# Initialize (auto-detects Claude Code, Cursor, etc.)
trellis init -u your-name

# Start your first task
# In Claude Code, say:
# "Use trellis-brainstorm to start a new task: add MFA support to the auth module"
Enter fullscreen mode Exit fullscreen mode

Links and Resources

Conclusion

Trellis addresses a systemic problem in the AI coding toolchain: every session starts from zero, without awareness of the project's context, the team's conventions, or the previous session's progress.

Storing specs, task context, and session memory inside the Git repository is a design decision, not an implementation detail. It means AI working patterns enter the engineering management system: specs can be reviewed, memory can be shared, changes can be tracked.

The closed-loop workflow design — especially the Finish phase promoting learnings back into specs — means the system improves with use rather than starting from the same baseline each time.

11.3k Stars signals real demand. For developers switching between multiple projects or tools, or tech leads trying to standardize AI-assisted development practices across a team, Trellis is worth serious evaluation.

Explore PrimeSkills — A marketplace for handpicked AI Agents and skills. Each is validated in real enterprise workflows, stripping away hype and keeping only what truly works.

Welcome to my Homepage for more useful insights and interesting products.

Top comments (0)