@mindfoldhq/trellis

<p align="center" <picture <source srcset="assets/trellis.png" media="(prefers-color-scheme: dark)" <source srcset="assets/trellis.png" media="(prefers-color-scheme: light)" <img src="assets/trellis.png" alt="Trellis Logo" width="500" style="image-rendering: -webkit-optimize-contrast; image-rendering: crisp-edges;" </picture </p

<p align="center" <strongAn out-of-the-box engineering framework for AI coding.</strong<br/ <subAI writes code fast, but every session it starts from scratch — no memory of your project, your conventions, or your team's requirements. Trellis persists specs, tasks, and memory into your repo, so any coding agent works to your engineering standards.</sub </p

<p align="center" <a href="./READMECN.md"简体中文</a • <a href="https://docs.trytrellis.app/"Docs</a • <a href="https://docs.trytrellis.app/start/install-and-first-task"Quick Start</a • <a href="https://docs.trytrellis.app/advanced/multi-platform"Supported Platforms</a • <a href="https://docs.trytrellis.app/start/real-world-scenarios"Use Cases</a </p

<p align="center" <a href="https://www.npmjs.com/package/@mindfoldhq/trellis"<img src="https://img.shields.io/npm/v/@mindfoldhq/trellis.svg?style=flat-square&color=2563eb" alt="npm version" /</a <a href="https://www.npmjs.com/package/@mindfoldhq/trellis"<img src="https://img.shields.io/npm/dw/@mindfoldhq/trellis?style=flat-square&color=cb3837&label=downloads" alt="npm downloads" /</a <a href="https://github.com/mindfold-ai/Trellis/blob/main/LICENSE"<img src="https://img.shields.io/badge/license-AGPL--3.0-16a34a.svg?style=flat-square" alt="license" /</a <a href="https://github.com/mindfold-ai/Trellis/stargazers"<img src="https://img.shields.io/github/stars/mindfold-ai/Trellis?style=flat-square&color=eab308" alt="stars" /</a <a href="https://docs.trytrellis.app/"<img src="https://img.shields.io/badge/docs-trytrellis.app-0f766e?style=flat-square" alt="docs" /</a <a href="https://discord.com/invite/tWcCZ3aRHc"<img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord" /</a <a href="https://github.com/mindfold-ai/Trellis/issues"<img src="https://img.shields.io/github/issues/mindfold-ai/Trellis?style=flat-square&color=e67e22" alt="open issues" /</a <a href="https://github.com/mindfold-ai/Trellis/pulls"<img src="https://img.shields.io/github/issues-pr/mindfold-ai/Trellis?style=flat-square&color=9b59b6" alt="open PRs" /</a <a href="https://deepwiki.com/mindfold-ai/Trellis"<img src="https://img.shields.io/badge/Ask-DeepWiki-blue?style=flat-square" alt="Ask DeepWiki" /</a <a href="https://chatgpt.com/?q=Explain+the+project+mindfold-ai/Trellis+on+GitHub"<img src="https://img.shields.io/badge/Ask-ChatGPT-74aa9c?style=flat-square&logo=openai&logoColor=white" alt="Ask ChatGPT" /</a </p

<p align="center" <img src="assets/trellis-demo.gif" alt="Trellis workflow demo" width="100%" </p

Why Trellis?

| Capability | What it changes | | --- | --- | | Auto-injected specs | Write conventions once in .trellis/spec/, then let Trellis inject the relevant context into each session instead of repeating yourself. | | Task-centered workflow | Keep PRDs, implementation context, review context, and task status in .trellis/tasks/ so AI work stays structured. | | Project memory | Journals in .trellis/workspace/ preserve what happened last time, so each new session starts with real context. | | Team-shared standards | Specs live in the repo, so one person's hard-won workflow or rule can benefit the whole team. | | Multi-platform setup | Bring the same Trellis structure to 20 AI coding platforms instead of rebuilding your workflow per tool. |

Prerequisites:

• Node.js = 18
• Python = 3.9

Quick Start

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

# 2. Initialize in your repo
trellis init -u your-name

# 3. Or initialize with the platforms you actually use
trellis init --cursor --opencode --codex -u your-name

See the Quick Start and Supported Platforms guides for setup details.

How to Use

The workflow is simple:

• Describe what you want in natural language.
• Brainstorm with the AI one question at a time until the PRD is clear, then implementation begins.
• Let it run — the AI calls Trellis Implement and auto-checks the result against specs, lint, type-check, and tests.
• Type /trellis:finish-work when the work is done or the session context fills up. Trellis archives the task and updates journals.

How It Works

Trellis runs a 4-phase loop with auto-invoked skills and sub-agents:

• Plan — trellis-brainstorm walks through requirements one question at a time and writes prd.md. Research-heavy items go to a trellis-research sub-agent. The result is curated specs + research files referenced from implement.jsonl / check.jsonl.
• Implement — a trellis-implement sub-agent writes code from the PRD with the curated context auto-injected, no git commit.
• Verify — a trellis-check sub-agent reviews the diff against specs and runs lint, type-check, and tests, self-fixing where it can.
• Finish — a final check runs, then trellis-update-spec promotes new learnings back into .trellis/spec/ so the next session starts smarter.