# Building an AI Collaborative Development System in Real Projects Source: https://docs.trytrellis.app/blog/ai-collaborative-dev-system A few days ago, Anthropic published an article about their internal AI-assisted development approach—giving AI "long-term memory" so it can remember project specifications, past decisions, and coding style. The concept is inspiring, but their explanation was fairly theoretical without much practical implementation detail. Our team recently tried implementing this approach in the Mosi project, extending it significantly to handle real multi-person collaboration scenarios. This article covers how we did it, what pitfalls we encountered, and what the final system feels like in practice. ## 1. Starting Point: The Gap Between Anthropic's Vision and Reality Anthropic's core idea is: **don't start every AI conversation from scratch—let the AI see the project's "memory" from the beginning**. This "memory" includes: * Project tech stack and architecture specifications * Code style conventions * Previously discussed design decisions * Solutions to common problems Their approach is to organize this content into documentation within the project, then feed relevant documents to the AI during conversations. This way, the AI can work like "an experienced employee who knows the project background" rather than needing everything explained from scratch each time. Sounds simple, but implementing this in a real multi-person collaborative project raises many practical issues: * **What about multiple developers working simultaneously?** If everyone's progress is recorded in a single file, conflicts are inevitable. * **What if specification documents are too long?** Our frontend spec has over 1600 lines, backend specs have hundreds more. Feeding everything to AI would blow the token limit, and most content isn't relevant to the current task anyway. * **How do we ensure code quality?** AI-written code can't go directly to the main branch—someone needs to review and test it. * **How do we track AI's work?** If something goes wrong, how do we trace what the AI actually did? We designed solutions for these problems in the Mosi project. ## 2. Implementation: Four Core Design Decisions ### 1. Multi-Person Collaboration: Each Developer Gets an Independent Progress Folder Anthropic's article barely mentions multi-person collaboration, but this is unavoidable in real projects. Our approach: **create an independent folder for each developer (including AI) under `workflow/agent-progress/`**. For example: ```plaintext theme={null} workflow/ ├── agent-progress/ │ ├── taosu/ # Developer taosu's progress │ │ ├── index.md │ │ └── progress-1.md │ ├── developer2/ # Developer developer2's progress │ │ ├── index.md │ │ └── progress-1.md ``` Each folder has an `index.md` that records what this developer is currently working on, how far they've progressed, and what problems they've encountered. AI reads this file before starting work to understand context; after work, it updates this file to record new progress. This way multiple developers can work simultaneously without interfering with each other. ### 2. Solving Information Overload: Two-Layer Index System As mentioned, our spec documents are long (frontend 1600+ lines, backend hundreds of lines). In practice, we found that feeding complete documents to AI causes several problems: **Why do we need a structured system?** 1. **Information overload**: When AI needs to implement a "keyboard shortcut feature," if it reads all 1600 lines of frontend specs, it gets distracted by irrelevant content—like "API calling conventions," "state management specs," etc. These are important but unhelpful for the current task, reducing AI's focus. 2. **Token economics**: In long conversations, if we read complete documents every time, token consumption accumulates rapidly. With 20 rounds of interaction, repeatedly reading documents wastes significant cost. 3. **Knowledge navigation**: Developers (and AI) need to quickly answer "I'm implementing feature X—which part of the spec should I read?" Without a clear navigation system, they can only rely on full-text search or reading chapter by chapter, which is very inefficient. ### Our Solution: Two-Layer Structure We designed an `index.md + doc.md` two-layer knowledge system: ```plaintext theme={null} workflow/ ├── frontend-structure/ │ ├── index.md # Index layer: quick navigation (~100 lines) │ └── doc.md # Detail layer: complete spec (1600+ lines) ``` **What is index.md?** `index.md` is a **lightweight navigation table** that lists all spec chapters with explicit line number ranges. More importantly, it's organized by **development task type**, not document structure. For example: ```markdown theme={null} # Frontend Development Spec Index > **Complete doc**: See `./doc.md` for detailed specifications This index helps you quickly locate the spec chapters you need. Find the corresponding chapters and line numbers based on the type of feature you're developing. ## Related Workflow Documents | Document | Use Case | | ----------------------------------- | ----------------------------- | | `../frontend-figma-workflow/doc.md` | Developing from Figma designs | ## Quick Navigation | Development Task | Chapters to Read | Line Range | | ---------------------------------------- | ------------------------------------------ | ---------- | | **New feature module** | Directory structure spec | L5-36 | | **Writing Command Palette** | Component dev spec > Command Palette | L876-1425 | | **Writing Query Hook** | Hook dev spec > Query Hook | L179-265 | | **Writing Mutation Hook** | Hook dev spec > Mutation Hook | L266-351 | | **Calling backend API** | API calling spec | L382-735 | | **Real-time communication (WebSocket)** | API calling spec > Real-time | L419-465 | | **AI streaming response (SSE)** | API calling spec > SSE | L466-497 | | **AI Tool Calls handling** | API calling spec > Tool Calls | L498-735 | | **State management** | State management spec | L736-873 | | **URL state sync** | State management spec > URL/Context | L738-873 | | **Writing components** | Component dev spec | L874-1645 | | **Accessibility and image optimization** | Component dev spec > Semantic HTML & Image | L1426-1544 | | **Performance optimization** | Performance optimization spec | L1676-1762 | | **Code quality check** | Code quality and formatting spec | L2140-2317 | | **Code review** | General rules + Checklist | L1763-2344 | ...... ``` **Core advantages:** 1. **Instant Knowledge Access**: AI only needs to read \~100 lines of index.md to locate "implementing keyboard shortcuts requires reading lines 876-1425" within seconds. This is much faster than full-text search or browsing chapter by chapter. 2. **On-Demand Loading**: AI reads only relevant sections of `doc.md` based on the current task (e.g., 500 lines instead of 1600). This saves tokens while avoiding information overload. 3. **Standardized Workflow**: This two-layer structure becomes a team standard—everyone (including AI and newly joined human developers) knows "read index first, then doc." This reduces cognitive load and improves collaboration efficiency. **Workflow:** 1. AI reads `index.md` to understand the overall spec structure 2. Based on the current task (e.g., "implement keyboard shortcut"), AI finds "Writing Command Palette → L876-1425" in the navigation table 3. AI precisely reads lines 876-1425 of `doc.md` for detailed implementation guidance 4. AI writes code following the spec, avoiding "not knowing where to start" or "missing key details" ### Fundamental Difference from Claude Skills You might ask: Didn't Anthropic release Claude Skills? Why not just use Skills instead of building this structure ourselves? This is because they solve different problems: * **Claude Skills** are **ecosystem-driven general capability packages**, designed for cross-project reuse. Things like "git operations," "Python testing," "filesystem operations"—these capabilities apply to any project. Skills pursue **breadth and reusability**. * **Our structure** is a **project-specific deep customization system** that indexes and stores Mosi project's specific architecture, tech stack, state management patterns, API calling conventions, etc. This knowledge is unique to the project and cannot be reused across projects. Our system pursues **depth and precision**. A concrete example: * **Skills can teach AI**: "How to write a React component" (general knowledge) * **Our doc.md teaches AI**: "In the Mosi project, how to write components following our specific architecture (Monorepo + Turborepo), state management patterns (Zustand + URL state sync), API calling conventions (tRPC + SSE + Tool Calls)" (project-specific knowledge) Skills are like a "general toolbox"; our structure is like "project blueprints." They're not replacements but complements—Skills provide foundational capabilities, structure provides project-specific implementation details. We use the same organizational approach for backend specs. ### 3. Encapsulating Best Practices: Short Command System To standardize the development process, we defined a series of "short commands," each corresponding to a specific operation. Short commands are stored in the `.cursor/commands/` directory, each command as a `.md` file. Currently common short commands include: * `/init-agent`: Initialize AI session, having AI read the current developer's progress and relevant specs * `/check-frontend`: Have AI check if frontend code follows specifications * `/check-backend`: Have AI check if backend code follows specifications * `/record-agent-flow`: Record this AI session's work content to the progress file **What are short commands?** Short commands are essentially **predefined prompt templates**. Each `.md` file contains a complete AI instruction. For example, `check-frontend.md` might contain: ```markdown theme={null} Check your own work—does the code you just wrote follow frontend development specs? First use git status to see which files were modified, then go to `.cursor/rules/frontend-structure/index.md` to find the corresponding doc details and check against `.cursor/rules/frontend-structure/doc.md` ... ``` **How it works:** When a developer types `/check-frontend` and hits enter: 1. Cursor automatically reads the content of `.cursor/commands/check-frontend.md` 2. Injects this content as a prompt into the current conversation 3. AI performs the corresponding check operations based on this prompt **Why use short commands?** Because every time you ask AI to do code checking or progress recording, you need to input a detailed checklist or operational steps. If these instructions aren't detailed enough, AI output quality becomes inconsistent. Short commands encapsulate these **best practice prompts**—developers just type `/check-frontend`, which is equivalent to sending a carefully designed complete prompt, ensuring instruction consistency and completeness. Plus, short commands can be shared across the team, so new members can immediately benefit from accumulated team experience. > Think of short commands as a kind of prompt SDK—using a short command is like calling a specialized SDK our team built for a specific scenario ### 4. Quality Gate: Human Developer Review Mechanism Although AI can write code, we don't let AI commit directly. **All code requires human developer review and testing before it can be committed**. The typical flow is: 1. AI writes code 2. Developer runs locally to check if functionality works 3. Developer reviews code for obvious issues 4. If there are problems, have AI fix them; if not, developer commits manually This way we get AI's efficiency while ensuring code quality. ## 3. Practice: A Complete Development Flow The design concepts above might still be abstract. Below is a real example showing the complete development flow. **Background:** I need to implement a keyboard shortcut feature on the frontend—pressing `Cmd+K` to open the search box. I've already created a Git branch `feat/keyboard-navigation` locally. ### Step 1: Initialize AI Session ```plaintext theme={null} Me: /init-agent ``` When I input this short command, Cursor injects the content of `init-agent.md` into the conversation. This template defines the initialization steps AI needs to perform: **AI executes according to short command guidance:** 1. Read `workflow/agent-progress/taosu/index.md` to understand my current progress and context 2. Read `workflow/frontend-structure/index.md` to understand the overall frontend spec structure 3. If needed, read further into relevant chapters of `doc.md` **AI's response:** ```plaintext theme={null} Okay, I've read your progress record and frontend specs. Current branch: feat/keyboard-navigation Task: Implement keyboard shortcut feature (Cmd+K opens search) I noticed the frontend spec has a "Keyboard System" chapter—I'll implement according to those specifications. Ready. Tell me what specifically needs to be done. ``` ### Step 2: Describe Requirements ```plaintext theme={null} Me: Help me implement a global keyboard shortcut—when pressing Cmd+K (Mac) or Ctrl+K (Windows), open the search box. The search box component already exists at components/SearchModal.tsx. ``` **What AI does:** 1. Based on the "keyboard shortcut" keyword, read the "Keyboard System" chapter in `workflow/frontend-structure/doc.md` 2. Learn that the project already has a `useKeyboardShortcut` hook ready to use 3. Write code: call this hook in the appropriate place to bind Cmd+K shortcut **AI's response:** ```plaintext theme={null} Okay, here's my implementation: 1. Use useKeyboardShortcut hook in the SearchModal component 2. Listen for Cmd+K / Ctrl+K, trigger search box open 3. Close search box on ESC Code is written, file path: - components/SearchModal.tsx (modified) You can run locally to see the effect. ``` ### Step 3: Local Testing I run the project locally, press `Cmd+K`, search box opens successfully. Feature works. ### Step 4: Code Self-Check ```plaintext theme={null} Me: /check-frontend ``` When I input this short command, Cursor automatically injects the content of `check-frontend.md` (a detailed code check list) into the conversation. **AI executes check according to short command template:** Following check items defined in the template, reviews the code just written: * Check if component naming follows conventions * Check if React hooks dependency arrays are complete * Check if type definitions are strict * Check for potential performance issues\ ... **AI's response:** ```plaintext theme={null} Checked and found two minor issues: 1. useKeyboardShortcut dependency array was missing a state 2. Type definitions could be stricter Already fixed for you—should be fine after running again. ``` I retest and confirm no issues. ### Step 5: Commit Code ```bash theme={null} git add . git commit -m "feat: add Cmd+K keyboard shortcut for search" git push origin feat/keyboard-navigation ``` ### Step 6: Record Flow ```plaintext theme={null} Me: /record-agent-flow ``` Cursor injects the content of `record-agent-flow.md` into the conversation—this template guides AI on how to record the workflow. **AI executes according to template guidance:** 1. Summarize this session's work content (requirements, implementation approach, problems encountered, solutions, etc.) 2. Format and append this information to `workflow/agent-progress/taosu/index.md` **AI's response:** ```plaintext theme={null} Recorded this session's workflow to your progress file. Main content: - Implemented global keyboard shortcut Cmd+K for search - Used useKeyboardShortcut hook - Fixed dependency array and type definition issues - Committed to branch feat/keyboard-navigation ``` This way, next time I continue working with AI, it can quickly understand what I've been doing recently by reading this progress file. ## 4. Pitfalls and Solutions ### Problem 1: Learning Curve for Short Commands New team members need to learn which short commands exist and what each does. We provide an `/onboard-developer` short command to guide newcomers. New members just run this command, and AI follows the preset guidance flow to introduce the entire workflow system, common short commands, and how to start the first task. ### Problem 2: AI "Forgets" Specs in Long Conversations Even if AI reads all specs via `/init-agent` at session start, as conversation turns increase and context lengthens, AI may gradually "forget" the initially read development spec details. This causes AI to drift from spec requirements when writing code. Our solution: **use short commands at key points to force AI to re-consult specs**. For example, the `/check-frontend` short command template explicitly requires AI to: 1. First use `git status` to see which code was just modified 2. Based on the change type (e.g., "added a new Hook"), find the corresponding chapter in `index.md` 3. Re-read the relevant part of `doc.md` (e.g., "Hook dev spec L179-265") 4. Check code against specs item by item This way, even if context is already very long, AI will **mandatorily** re-learn the specs when checking code, ensuring code quality doesn't decline due to "forgetting." This is also why we encapsulate these operations as short commands—not just for convenience, but to **enforce quality assurance processes at key workflow points**. ## 5. Summary and Future Plans Anthropic's "AI long-term memory" concept is valuable, but truly implementing it in real multi-person collaborative projects requires solving many engineering problems. Our practice in the Mosi project did these core things: * **Multi-person collaboration support**: Each developer has an independent progress folder * **Spec index system**: index.md + doc.md structure lets AI efficiently find specs * **Short command system**: Encapsulates common operations, improves development efficiency * **Human in the loop**: AI writes code, humans review and commit, ensuring quality This system is still being continuously improved, but we can already feel noticeable improvements in development efficiency. Improvements we might make next: * **Automate more processes**: e.g., let AI automatically create branches, automatically write commit messages * **Smarter spec indexing**: Currently AI manually judges which chapters to read; in the future, AI could automatically match relevant chapters based on task descriptions * **Team knowledge base**: Organize design decisions discussed by the team and pitfalls encountered into documentation, so AI can learn from this experience If you're also trying AI-assisted development, I hope this article gives you some inspiration. Welcome to discuss. *** ## Resources * Anthropic's original article: [Building effective agents](https://www.anthropic.com/research/building-effective-agents) # Overview Source: https://docs.trytrellis.app/blog/index | Article | Date | | ----------------------------------------------------------------------------------------------------- | ----------- | | [Understanding Trellis Through Kubernetes](/blog/use-k8s-to-know-trellis) | Feb 1, 2026 | | [Building an AI Collaborative Development System in Real Projects](/blog/ai-collaborative-dev-system) | Feb 1, 2026 | # Understanding Trellis Through Kubernetes Source: https://docs.trytrellis.app/blog/use-k8s-to-know-trellis # Understanding Trellis Through Kubernetes > If you're familiar with Kubernetes, this document will help you quickly grasp Trellis's design philosophy. *** ## Table of Contents 1. [K8s Core Concepts Overview](#1-k8s-core-concepts-overview) 2. [Trellis and K8s Analogy](#2-trellis-and-k8s-analogy) 3. [Reconciliation Mechanism Deep Dive](#3-reconciliation-mechanism-deep-dive) 4. [Complete Workflow](#4-complete-workflow) 5. [Why This Design](#5-why-this-design) *** ## 1. K8s Core Concepts Overview ### 1.1 Imperative vs Declarative **Imperative**: Describe "how to do it" ```bash theme={null} # Step-by-step instructions for the system current_pods=$(kubectl get pods -l app=nginx --no-headers | wc -l) if [ $current_pods -lt 3 ]; then kubectl run nginx --image=nginx:1.19 fi ``` **Declarative**: Describe "what you want" ```yaml theme={null} # Just state the desired end state apiVersion: apps/v1 kind: Deployment spec: replicas: 3 template: spec: containers: - name: nginx image: nginx:1.19 ``` | Dimension | Imperative | Declarative | | -------------- | --------------------------- | ---------------------- | | Focus | Process (How) | Result (What) | | Executor | User orchestrates each step | System auto-reconciles | | Idempotency | Requires extra handling | Naturally idempotent | | Error Recovery | Requires user intervention | Self-healing | ### 1.2 Control Loop The core of K8s is the **Control Loop**: ``` Desired State Actual State (User declares) (System observes) | | +---> Controller <----+ | Observe → Diff → Act → Repeat ``` **Power in action**: ``` I declare: I want 3 nginx Pods A Pod gets accidentally deleted → Controller detects 2 ≠ 3 → Auto-creates 1 I modify declaration to 5 → Controller detects 3 ≠ 5 → Auto-creates 2 No manual intervention needed. System auto-detects, auto-recovers, auto-adapts. ``` *** ## 2. Trellis and K8s Analogy ### 2.1 Architecture Mapping ``` ┌─────────────────────────────────────────────────────────────┐ │ Kubernetes │ │ │ │ YAML Manifest ──> Controller ──> Actual State │ │ (Desired State) (Reconcile) (Actual State) │ └─────────────────────────────────────────────────────────────┘ ↕ ┌─────────────────────────────────────────────────────────────┐ │ Trellis │ │ │ │ Task Dir ──> Dispatch + Ralph Loop ──> Compliant Code │ │ (Desired State) (Reconcile) (Actual State) │ └─────────────────────────────────────────────────────────────┘ ``` ### 2.2 Core Component Mapping | Kubernetes | Trellis | Description | | ------------------- | -------------- | ------------------------------- | | YAML Manifest | Task Directory | Declares desired state | | Controller | Dispatch | Orchestrates phase execution | | Reconciliation Loop | Ralph Loop | Loops until verification passes | | Pod/Container | Agent | Actual execution unit | | ConfigMap | jsonl + Hook | Injects config/context | | Actual State | Final Code | Product after reconciliation | ### 2.3 Key Insight K8s solves: **Infrastructure complexity** — Uses declarative to abstract away details, Controller handles reconciliation. Trellis solves: **AI development uncertainty** — Uses declarative to define expectations (prd.md + guidelines), Ralph Loop handles reconciliation. Common ground: * Users only declare "what they want", don't worry about "how to do it" * System continuously reconciles until actual state matches desired * Auto-repairs when deviations occur > Next, Chapter 3 details the reconciliation mechanism (Hook + Ralph Loop), and Chapter 4 expands on the complete workflow (Phase 1-4). *** ## 3. Reconciliation Mechanism Deep Dive Trellis reconciliation is achieved through two mechanisms working together: **Hook Injection** and **Ralph Loop**. ### 3.1 Hook Injection **Timing**: Automatically triggered each time a Subagent is called **Function**: Injects file contents referenced in jsonl into the Agent's context ``` Plan/Research Agent finds needed files in advance │ ▼ Writes to implement.jsonl / check.jsonl │ ▼ Dispatch calls Subagent │ ▼ Hook intercepts, reads jsonl, injects file contents │ ▼ Subagent receives complete context, starts working ``` **jsonl file example**: ```jsonl theme={null} {"file": ".trellis/spec/backend/index.md", "reason": "Backend guidelines"} {"file": "src/api/auth.ts", "reason": "Existing auth pattern"} ``` **Why this design**: * Prevents context overload (Context Rot) — Only injects what's needed for current phase * Traceable — jsonl records what context each task used * Decoupled — Agent doesn't need to search, focuses on execution ### 3.2 Ralph Loop **Essence**: A programmatic quality gate that intercepts Agent stop requests and forces continuation if verification fails. **Trigger timing**: When Check Agent attempts to stop **Flow**: ``` Check Agent attempts to stop │ ▼ SubagentStop Hook triggers ralph-loop.py │ ▼ Has verify config? │ ┌────┴────┐ Yes No │ │ ▼ ▼ Run verify Check completion commands markers (pnpm lint) (parse from output) │ │ ▼ ▼ ┌──┴──┐ ┌──┴──┐ │Pass │ │Complete│ │ │ │ │ ▼ ▼ ▼ ▼ allow block allow block (stop) (continue) (stop) (continue) Max 5 iterations, then force allow ``` **verify config example** (worktree.yaml): ```yaml theme={null} verify: - pnpm lint - pnpm typecheck ``` **Why use programmatic verification instead of letting AI judge**: * Programmatic verification is reliable — lint pass means pass, doesn't depend on AI's judgment * Configurable — Different projects can configure different verification commands * Prevents infinite loops — Max 5 iterations, then force allow **Limitations**: * Complex architectural issues or logic bugs may require human intervention * Depends on guideline quality; unclear guidelines lead to limited check effectiveness *** ## 4. Complete Workflow ### 4.1 Phase Overview ``` Task Directory ├── prd.md (Task requirements) ├── implement.jsonl (Implementation phase context) ├── check.jsonl (Check phase context) └── task.json (Metadata) │ ▼ ┌───────────────────────────────────────────────┐ │ Phase 1: implement │ │ ───────────────── │ │ Agent: Implement Agent │ │ Injects: prd.md + files from implement.jsonl │ │ Task: Write code based on requirements │ └───────────────────────────────────────────────┘ │ ▼ ┌───────────────────────────────────────────────┐ │ Phase 2: check │ │ ───────────────── │ │ Agent: Check Agent │ │ Injects: Guideline files from check.jsonl │ │ Task: Check code compliance, fix issues │ │ Reconcile: Ralph Loop verifies, loops if fail│ └───────────────────────────────────────────────┘ │ ▼ ┌───────────────────────────────────────────────┐ │ Phase 3: finish │ │ ───────────────── │ │ Agent: Check Agent (with [finish] flag) │ │ Injects: finish-work.md (Pre-Commit List) │ │ Task: Pre-commit completeness check │ │ - lint/typecheck/test passing │ │ - Documentation in sync │ │ - API/DB changes complete │ │ Reconcile: Skips Ralph Loop (already verified)│ └───────────────────────────────────────────────┘ │ ▼ ┌───────────────────────────────────────────────┐ │ Phase 4: create-pr │ │ ───────────────── │ │ Task: Create Pull Request │ └───────────────────────────────────────────────┘ │ ▼ Compliant Code + PR ``` ### 4.2 Exception Path If Check Agent reports unfixable issues, Dispatch can call **Debug Agent** for deep analysis. This is not the default flow, but exception handling. *** ## 5. Why This Design ### 5.1 One-Click Complete Workflow `/trellis:start` or `/trellis:parallel` (Claude Code only) launches with one click, AI completes the entire flow: ``` Plan → Implement → Check → Finish → PR ``` Users don't need to guide step-by-step. What to do at each phase, which guidelines to reference — it's all predefined. ### 5.2 Continuous Accumulation of Development Guidelines ``` Guidelines stored in .trellis/spec/ │ ▼ AI executes with guidelines ──> Finds issues ──> Updates guidelines │ │ └────────────────────────────────────┘ Guidelines improve over time ``` Thinking Guides help discover "didn't think of that" problems. ### 5.3 Preventing Context Rot Too much context causes LLM to: * **Distraction** — Gets sidetracked by irrelevant information * **Confusion** — Information contradicts itself * **Clash** — Old and new information conflict Trellis injects by phase: * implement phase: Requirements + related code * check phase: Development guidelines * finish phase: Pre-commit checklist Each phase's Agent only receives context relevant to its task. ### 5.4 Programmatic Quality Control ``` Traditional approach: "Please check code quality" ──> AI says "I checked" ──> Did it really? Trellis approach: Ralph Loop runs pnpm lint ──> Pass to proceed ──> Programmatically guaranteed ``` Doesn't rely on AI's self-judgment, uses programmatic enforcement. ### 5.5 Traceability | Record | Content | | --------- | ---------------------------- | | jsonl | What context each task used | | workspace | Work content of each session | | task.json | Complete task lifecycle | When issues arise, you can trace back to which file was missing, or which guideline was unclear. *** ## Summary | Concept | K8s | Trellis | | ------------------- | ------------- | ------------------------------- | | Desired State | YAML Manifest | Task Directory (prd.md + jsonl) | | Execution Unit | Pod/Container | Agent | | Reconciliation Loop | Controller | Dispatch + Ralph Loop | | Config Injection | ConfigMap | Hook + jsonl | | Final Product | Running Pods | Compliant Code | **Core philosophy aligned**: Declare desired → System reconciles → Eventually consistent. # v0.1.9 Source: https://docs.trytrellis.app/changelog/v0.1.9 2026-01-10 Renamed some slash commands. ## Changes | Old | New | | ---------------------- | ------------------- | | `onboard-developer.md` | `onboard.md` | | `record-agent-flow.md` | `record-session.md` | # v0.2.0 Source: https://docs.trytrellis.app/changelog/v0.2.0 2026-01-15 Comprehensive naming redesign for clarity. ## Changes | Old | New | Description | | ------------------ | --------------- | ---------------------- | | `agent-traces/` | `workspace/` | Developer work records | | `structure/` | `spec/` | Development guidelines | | `backlog/` | `tasks/` | Task tracking | | `.current-feature` | `.current-task` | Current task pointer | | `feature.sh` | `task.sh` | Task management script | # v0.3.0-beta.0 Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.0 2026-01-25 **BREAKING**: Shell to Python migration + Command namespace changes. ## Shell Scripts to Python All `.sh` scripts replaced by `.py` equivalents. Requires Python 3.10+. | Old | New | | ------------------------------- | ------------------------------- | | `.trellis/scripts/*.sh` | `.trellis/scripts/*.py` | | `.trellis/scripts/multi-agent/` | `.trellis/scripts/multi_agent/` | | `./script.sh` | `python3 ./script.py` | ## Command Namespace Commands moved to namespaced paths: | Platform | Old | New | | ----------- | --------------------------- | ----------------------------------- | | Claude Code | `.claude/commands/start.md` | `.claude/commands/trellis/start.md` | | Cursor | `.cursor/commands/start.md` | `.cursor/commands/trellis-start.md` | Run `trellis update --migrate` to apply changes. # v0.3.0-beta.10 Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.10 2026-01-23 Windows UTF-8 encoding fix. ## Changes * Fixed UnicodeEncodeError and SyntaxWarning on Windows * Added UTF-8 encoding declarations and Windows stdout handling in hooks # v0.3.0-beta.11 Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.11 2026-01-23 Bug fix for Windows UTF-8 encoding in hooks. ## Changes * Fixed remaining Windows UTF-8 encoding issues in hook scripts # v0.3.0-beta.12 Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.12 2026-01-24 Windows compatibility and multi-model dispatch improvements. ## Changes * Fixed Windows hook JSON parse error caused by backslash characters in templates * Fixed cross-platform script paths for Python command * Fixed multi-agent dispatch prompt for GPT/Codex model compatibility # v0.3.0-beta.13 Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.13 2026-01-25 Cursor platform support and base branch auto-recording. ## Changes * Added Cursor as supported platform alongside Claude Code and OpenCode * Auto-record `base_branch` on task creation for correct PR targeting * Added `set-base-branch` command # v0.3.0-beta.14 Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.14 2026-01-26 Fix update error for 0.2.x users. ## Changes * Fixed "path argument must be of type string" error when upgrading from 0.2.x * Added missing manifests for 0.2.12, 0.2.13, and earlier beta versions # v0.3.0-beta.15 Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.15 2026-01-27 Add cli\_adapter.py to update system. ## Changes * Added missing `cli_adapter.py` to template files in update mechanism # v0.3.0-beta.16 Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.16 2026-01-28 iFlow CLI support and update mechanism fix. ## Changes * Added iFlow CLI platform support * Fixed Windows stdout encoding in iFlow hooks * Update mechanism now only updates configured platforms # v0.3.0-beta.7 Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.7 2026-01-30 Windows compatibility fixes and hook JSON format corrections. ## Changes * Fixed Claude Code hook JSON output format (Issue #18) * Added UTF-8 encoding for git commands (Issue #19) * Cross-platform `tail_follow()` implementation in status.py * Hook commands now use `python3` directly > **Windows Users**: If your system uses `python` instead of `python3`, manually update `.claude/settings.json` to change `python3` to `python`. # v0.3.0-beta.8 Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.8 2026-01-31 Task commands now support task name lookup. You can use `python3 task.py start my-task` instead of the full path `python3 task.py start .trellis/tasks/01-31-my-task`. ## Changes * Simplified task command syntax * No migration required # v0.3.0-beta.9 Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.9 2026-01-22 OpenCode platform support with agents, commands, and plugins. ## Changes * Added OpenCode platform with agents, commands, and plugin support * Session ID extraction and resume capability # v0.3.0-rc.0 Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.0 2026-02-06 Major internal refactor with centralized platform registry, remote spec templates, and comprehensive test coverage. ## New features * **Remote spec templates**: `trellis init -t electron-fullstack` downloads and applies spec templates * **Centralized platform registry**: All platform metadata in one place, derived helpers replace scattered hardcoded lists * **Test coverage**: 312 tests across 17 files with Vitest coverage reporting ## Changes * Extracted `resolvePlaceholders()` to shared module, removed templates.ts dispatcher * Release tooling supports beta/rc/release workflows * Extracted VERSION constant for consistent version management # v0.3.0-rc.1 Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.1 2026-02-07 Fix CLI version comparison for prerelease versions. ## Changes * Fixed rc version comparison (`0.3.0-rc.0` was incorrectly sorted below `0.3.0-beta.16`) * Deduplicated `compareVersions()` across 3 modules into shared `utils/compare-versions.ts` # v0.3.0-rc.2 Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.2 2026-02-09 Codex platform integration. ## New features * **Codex platform**: `trellis init --codex` sets up OpenAI Codex CLI with skill templates * Extended Python runtime (`cli_adapter.py`) to support Codex platform detection ## Changes * Full test suite passing with coverage * Codex uses skills pattern (`SKILL.md`) instead of slash commands # v0.3.0-rc.3 Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.3 2026-02-15 Code-spec enforcement and robustness fixes. ## Changes * Fixed table separator matching in `add_session.py` to tolerate formatted markdown * Fixed Codex skill templates (replaced `/trellis:` with `$` syntax, removed Claude-specific references) * Enforced code-spec depth requirements across all platform templates # v0.3.0-rc.4 Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.4 2026-02-19 Active spec sync in finish agent. ## Changes * Finish agent now actively syncs spec docs during pipeline runs * Injected `update-spec.md` into finish context across Claude, iFlow, and OpenCode * Restored code-spec enforcement in Codex skill templates # v0.3.0-rc.5 Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.5 2026-02-24 Brainstorm command templates for all platforms. ## New features * **Brainstorm command**: `/trellis:brainstorm` added to all 5 platform templates (Claude, iFlow, OpenCode, Cursor, Codex) for interactive requirements discovery ## Changes * Added brainstorm workflow references to start commands across iFlow, OpenCode, Cursor, and Codex (matching existing Claude start.md) ## Migration No migration required. Run `trellis update` to get the latest templates. # v0.3.0-rc.6 Source: https://docs.trytrellis.app/changelog/v0.3.0-rc.6 2026-02-26 4 new platforms — Trellis now supports 8 AI coding tools. ## New platforms * **Kilo CLI**: Commands-only platform with subdirectory namespacing (`.kilocode/commands/trellis/`) * **Kiro Code**: Skills-based platform (`.kiro/skills/`) * **Gemini CLI**: First TOML-format command platform (`.gemini/commands/trellis/*.toml`) * **Antigravity**: Workflow-based platform adapted from Codex skills (`.agent/workflows/`) ## Bug fixes * Fixed non-existent `spec/shared/` references in init-context defaults * Fixed iFlow start/finish-work template content * Corrected license badge from FSL to AGPL-3.0 * Fixed start process flow ## Tests * Added 50+ new tests covering all 4 new platforms (templates, configurators, init integration, regression) ## Migration No migration required. Run `trellis init --kilo`, `--kiro`, `--gemini`, or `--antigravity` to add new platform support. # v0.3.1 Source: https://docs.trytrellis.app/changelog/v0.3.1 2026-03-02 SessionStart reinject on clear/compact and spec template project-type awareness. ## Enhancements * **SessionStart reinject**: Hook now fires on `clear` and `compact` events in addition to `startup` — ensures context is always re-injected after session reset (Claude + iFlow) * **New slash command**: Added `/trellis:create-manifest` to guide AI through the full manifest creation flow ## Bug fixes * Fixed iFlow command templates writing to wrong path (`.iflow/commands/` → `.iflow/commands/trellis/`) * Fixed `trellis update` injecting spec files for non-existent backend/frontend directories * Fixed `trellis init` creating all spec directories regardless of project type (now respects `projectType`) * Removed dead `guidesCrossPlatformThinkingGuideContent` export and broken links in guides index ## Migration No migration required. Run `trellis update` to sync template changes. # v0.3.10 Source: https://docs.trytrellis.app/changelog/v0.3.10 2026-03-12 Bug fixes for registry URL handling and AI model compatibility. ## Bug Fixes * **HTTPS registry URLs** — `trellis init --registry` now accepts HTTPS URLs (e.g. `https://github.com/user/repo`) by auto-converting them to giget-style format. Supports GitHub, GitLab, and Bitbucket, including `/tree/branch/path` URLs and `.git` suffix. (#87) * **Record-session AI compatibility** — Updated the record-session command wording across all 9 platforms. AI models (especially GPT) previously refused to run `add_session.py` because the old "AI must NOT execute git commit" instruction was too absolute. The new wording clarifies that scripts handling `.trellis/` metadata commits are safe to execute. (#88) # v0.3.2 Source: https://docs.trytrellis.app/changelog/v0.3.2 2026-03-03 Auto-commit workspace changes after record-session and project-level configuration. ## Enhancements * **Auto-commit workspace changes**: `add_session.py` now automatically commits `.trellis/workspace` changes after recording a session — keeps the working directory clean * **Project-level config**: New `.trellis/config.yaml` for customizing `session_commit_message` and `max_journal_lines` * **Config reader module**: New `common/config.py` reads config.yaml with hardcoded fallback defaults * **Skip auto-commit**: Added `--no-commit` flag to `add_session.py` for cases where you don't want automatic commits * **Template updates**: All 8 platform record-session templates updated with auto-commit documentation ## Migration No migration required. Run `trellis update` to sync new files (`config.yaml`, `config.py`) and updated templates. # v0.3.3 Source: https://docs.trytrellis.app/changelog/v0.3.3 2026-03-04 Init download UX improvements, update spec protection, and Windows encoding fixes. ## Enhancements * **Proxy detection**: Automatically detects `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` environment variables and configures undici ProxyAgent for all network calls (including giget template downloads) * **Download timeout with countdown**: Template index fetch has a 5s timeout with live `Loading... 2s/5s` countdown; template downloads have a 30s timeout via `Promise.race` * **Source URL display**: Shows the GitHub URL being fetched during `trellis init` template selection * **Retry hint**: On download failure, suggests `trellis init --template ` for manual retry * **Eliminate double-fetch**: Pre-fetched `SpecTemplate` is passed to `downloadTemplateById` to avoid fetching the index twice * **Update skips spec directory**: `trellis update` no longer touches `.trellis/spec/` — user-customized spec content is fully protected * **Update proxy support**: `trellis update` sets up proxy before npm version check ## Bug Fixes * **Windows stdin UTF-8**: Centralized stdio encoding in `common/__init__.py` — adds `sys.stdin` to `_configure_stream()` to fix garbled Chinese text when piping content via stdin on Windows PowerShell * **Remove inline encoding**: Removed duplicated encoding code from `add_session.py` and `git_context.py` — all streams now handled by `common/__init__.py` * **Record-session template cleanup**: Removed auto-commit implementation details from all 8 platform record-session templates to prevent AI agents from misusing the `--no-commit` flag ## Dependencies * Added `undici ^6.21.0` for ProxyAgent support * Bumped `engines.node` from `>=18.0.0` to `>=18.17.0` (required by undici v6) ## Migration No migration required. Run `trellis update` to sync updated scripts and templates. Node.js >=18.17.0 is now required. # v0.3.4 Source: https://docs.trytrellis.app/changelog/v0.3.4 2026-03-05 Qoder platform support, Kilo workflows migration, and record-session task awareness. ## Enhancements * **Qoder platform**: Added Qoder as a skills-based platform (`--qoder` flag). Templates are placed at `.qoder/skills/{name}/SKILL.md` * **Record-session prompt optimization**: `/record-session` now enforces task archive check before recording — completed tasks must be archived first. `get_context.py` gains `--mode record` for focused context output with MY ACTIVE TASKS shown first * **Task archive auto-commit**: `task.py archive` now auto-commits after archiving. Use `--no-commit` to skip ## Bug Fixes * **Kilo workflows**: Renamed `commands/trellis/` to `workflows/` to match Kilo's official spec at `kilo.ai/docs/customize/workflows` * **iFlow non-interactive**: Added `IFLOW_NON_INTERACTIVE` environment variable check in session-start hook, fixing cross-layer consistency for non-interactive mode * **Multi-agent nested session**: Clear inherited `CLAUDECODE` env var before spawning child processes, fixing nested session guard introduced in Claude Code v2.1.39+ * **Update preserves user files**: `trellis update` no longer overwrites `workflow.md` and `workspace/index.md` — these user-customizable files are only created during init ## Migration Kilo users: `trellis update` will automatically rename `.kilocode/commands/trellis/` to `.kilocode/workflows/`. # v0.3.5 Source: https://docs.trytrellis.app/changelog/v0.3.5 2026-03-05 Hotfix for Kilo workflows delete migration. ## Bug Fixes * **Migration manifest field name**: Fixed `delete` migration manifest using incorrect `path` field instead of `from`, causing Kilo commands cleanup to fail during `trellis update` ## Migration No manual migration required. Run `trellis update` to apply the Kilo workflows migration that was blocked in v0.3.4. # v0.3.6 Source: https://docs.trytrellis.app/changelog/v0.3.6 2026-03-06 Task lifecycle hooks, custom template registries, parent-child subtasks, and PreToolUse hook fix. ## Enhancements * **Custom template registries**: `trellis init --registry` supports fetching Spec templates from custom GitHub/GitLab/Bitbucket repositories. Automatically detects marketplace mode (`index.json`) and direct download mode * **Task lifecycle hooks**: `.trellis/config.yaml` gains a `hooks` configuration block supporting four events: `after_create`, `after_start`, `after_finish`, and `after_archive`. Task information is passed via the `TASK_JSON_PATH` environment variable. Ships with a Linear sync hook example. See: [Task Management](/guide/ch06-task-management) * **Parent-child subtasks**: `task.py add-subtask` / `remove-subtask` commands for linking tasks. `task.json` gains `children`, `parent`, and `meta` fields. `task.py create --parent` creates a child task directly * **Record-session prompt improvement**: Archive decision is now based on actual work state rather than the `task.json` status field * **Brainstorm prompt update**: `/brainstorm` now includes a subtask decomposition step for complex tasks ## Bug Fixes * **PreToolUse context injection failure**: Claude Code v2.1.63 renamed its internal tool from `Task` to `Agent` ([anthropics/claude-code#29677](https://github.com/anthropics/claude-code/issues/29677)), causing hook scripts with `tool_name != "Task"` checks to exit early. This broke code-spec context injection for all implement/check/debug/research agents. Fix: accept both `Task` and `Agent` tool names, and add an `"Agent"` matcher to `settings.json` ## Migration No manual migration required. Run `trellis update` to sync the updated hook scripts and settings. # v0.3.7 Source: https://docs.trytrellis.app/changelog/v0.3.7 2026-03-10 Smart update protection, session-start task awareness, and improved start flow. ## Enhancements * **Update: user-deletion protection**: If you intentionally deleted a file installed by Trellis, `trellis update` now detects this via stored hashes and will not re-add it. A new "Deleted by you (preserved)" section appears in the update summary * **Update: `update.skip` config**: Add an `update.skip` list in `.trellis/config.yaml` to permanently exclude specific files or directories from `trellis update`. Useful for monorepo projects that don't need certain platform-specific commands * **Session-start: task status injection**: Session-start hooks now inject a `` tag with structured state (`NO ACTIVE TASK` / `NOT READY` / `READY` / `COMPLETED`), enabling AI to automatically detect and resume in-progress tasks * **Session-start: dynamic spec discovery**: Session-start hooks now dynamically iterate `spec/` subdirectories instead of hardcoding `frontend/backend/guides`, supporting monorepo package layouts (e.g., `spec/cli/backend/`) * **Start flow: brainstorm enforcement**: Complex tasks now automatically trigger the brainstorm flow across all 9 supported platforms, preventing premature implementation without requirements clarification ## Migration No manual migration required. Run `trellis update` to sync the updated hook scripts and command templates. # v0.3.8 Source: https://docs.trytrellis.app/changelog/v0.3.8 2026-03-12 Fix YAML parser quote stripping. ## Bug Fixes * **YAML parser: greedy quote strip** — `parse_simple_yaml()` in `worktree.py` used Python's `str.strip('"').strip("'")`, which removes ALL matching characters from both ends instead of just one pair of quotes. Values like `"echo 'hello'"` would be corrupted to `echo 'hello`. Replaced with a safe `_unquote()` helper that removes exactly one layer of matching surrounding quotes * **Update: skip path quote handling** — `loadUpdateSkipPaths` in `update.ts` now correctly strips surrounding quotes from skip paths in `.trellis/config.yaml`, fixing cases where quoted paths like `".claude/commands/"` were not matched ## Migration No manual migration required. Run `trellis update` to sync the fixed YAML parser to your project. # v0.3.9 Source: https://docs.trytrellis.app/changelog/v0.3.9 2026-03-12 Fix iFlow hook matcher naming. ## Bug Fixes * **iFlow: hook matcher naming** — Corrected iFlow SessionStart hook matcher from `compact` to `compress` to match the actual Claude Code event name # v0.4.0 Source: https://docs.trytrellis.app/changelog/v0.4.0 2026-04-15 After 11 betas and 2 RCs, Trellis v0.4.0 stable is released! ## Monorepo-native support `trellis init` now detects monorepos and creates **per-package** spec directories — every package gets its own coding conventions and tasks. To keep the command matrix from exploding alongside package count, the type-specific `before-backend-dev` / `before-frontend-dev` / `check-backend` / `check-frontend` are merged into single `before-dev` / `check` commands across 9 platforms. ## More platforms * **GitHub Copilot** — `--copilot` * **Windsurf** — `--windsurf` * **Qoder** — `--qoder` * **Factory Droid** — `--droid` Enable multiple platforms in one go: ```bash theme={null} trellis init --codex --gemini --copilot -u your-name ``` ## Codex now fully supported * **Codex SessionStart hook is enabled.** Codex users get the same auto-injection as Claude Code users — no need to manually invoke `/start` anymore. Task state, workflow, and guidelines are injected at session start. * **Sub-agent definitions.** `.codex/agents/` now ships TOML-format `implement` / `research` / `check` agents, semantically aligned with Claude Code's `Agent` tool. * **Shared skills layer.** Codex writes to `.agents/skills/` (the [agentskills.io](https://agentskills.io) standard directory). The same output is read automatically by Cursor, Gemini CLI, GitHub Copilot, Amp, and Kimi Code — one Codex checkbox covers a wide range of tools. ## Other improvements * **Custom spec template registry.** `trellis init -r ` pulls spec templates from a custom git repository (GitHub / GitLab / Bitbucket, including self-hosted GitLab via HTTPS or SSH) instead of the default marketplace. Teams can host their own coding conventions on internal git servers. * **Re-init fast path.** `trellis init --codex` adds Codex to an existing project; bare `trellis init` shows an interactive menu. * **Branch awareness.** Sessions and journals carry git branch context, so parallel branches don't get tangled. * **Claude Code statusline integration.** * **Multi-agent pipeline.** Supports worktree submodules and PR state tracking. ## Notable fixes * **SessionStart payload size fix.** Reduced from \~29 KB to \~7 KB, fixing a major silent bug where Claude Code was truncating task state on most projects. * **Windows.** Statusline GBK encoding crash (thanks @xiangagou163) and `{{PYTHON_CMD}}` placeholder resolution in Codex `hooks.json`. **Other fixes (selected)** * fix(update): allow rename migrations to target protected paths + warn on config parse failure * fix(update): parse name from `.developer` when creating migration task * fix(hooks): normalize `.current-task` path refs across platforms (#130) * fix(hooks): correct `SubagentStop` event field names in ralph-loop (#152) * fix(opencode): make dispatch wait for child tasks (#147) * fix(init): strip npm scope prefix from monorepo package directory names * fix(init): rename "empty templates" to "from scratch" in template picker * fix(scripts): preserve submodule status prefix in `start.py` ## Install & upgrade ```bash theme={null} # Fresh install npm install -g @mindfoldhq/trellis@latest --registry=https://registry.npmjs.org # Upgrade (existing trellis install) trellis update ``` Upgrading from 0.3.x automatically handles the 36 merged command-file deletions — with hash verification, **your local edits are preserved**; only files that haven't been modified are removed. *** * Full changelog: [https://docs.trytrellis.app/changelog/v0.4.0](https://docs.trytrellis.app/changelog/v0.4.0) * Repo: [https://github.com/mindfold-ai/Trellis](https://github.com/mindfold-ai/Trellis) * Docs: [https://docs.trytrellis.app](https://docs.trytrellis.app) # v0.4.0-beta.1 Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.1 2026-03-12 Monorepo support, unified commands, and Python scripts refactoring. This is a **breaking change** release. Run `trellis update` to migrate. Customized command files will be preserved — only unmodified files are auto-deleted. ## Enhancements * **Monorepo auto-detection** — `trellis init` detects pnpm/npm/Cargo/Go/uv workspaces and git submodules, generates per-package spec directories and `config.yaml` with packages list * **Unified commands** — `before-backend-dev` + `before-frontend-dev` merged into `before-dev`; `check-backend` + `check-frontend` merged into `check` (all 9 platforms) * **Safe file delete** — New migration type that auto-removes deprecated files only when content hash matches (user-modified files are never deleted) * **Protected paths** — `PROTECTED_PATHS` prevents migrations from touching user data (`.trellis/workspace`, `spec`, `tasks`) * **Update skip paths** — `config.yaml` `update.skip` to exclude paths from safe-file-delete and template updates * **Worktree submodule awareness** — Worktree agents auto-initialize git submodules for task packages * **Monorepo script support** — Session-start hook supports `spec_scope` filtering; `task.py` and `add_session.py` support `--package` * **Migration task auto-creation** — Breaking change updates automatically create a `.trellis/tasks/` migration task with guide and AI instructions ## Bug Fixes * **Update: protected path compat** — Allow rename/rename-dir migrations to target protected paths (0.2.0 compat) * **Update: config parse warning** — Warn when `config.yaml` parse fails instead of silently disabling `update.skip` * **Scripts: submodule status** — Preserve git submodule status prefix character (`.strip` → `.rstrip`) ## Internal * **Python scripts refactoring** — Shared `io`/`log`/`git` modules, `TaskInfo` TypedDict type safety, god modules (`task.py`, `git_context.py`, `status.py`) split into focused modules. All entry paths unchanged. ## Migration Run `trellis update` to sync new unified commands. Old `before-backend-dev`, `before-frontend-dev`, `check-backend`, `check-frontend` files will be auto-deleted if unmodified. If you customized these files, merge your changes into the new `before-dev` / `check` files and delete the old ones manually. # v0.4.0-beta.10 Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.10 2026-04-09 Ralph Loop field name fix (P0), migration task assignee parsing fix, and task lifecycle documentation. ## Bug Fixes * **Ralph Loop field names fix (#152)**: The SubagentStop hook was reading non-existent fields (`subagent_type`, `agent_output`, `prompt`) instead of the actual Claude Code event schema (`agent_type`, `last_assistant_message`), so Ralph Loop was silently inert for **all users since release**. Check/implement/debug subagents will now actually trigger loop control as documented. Thanks to @suyuan2022 for the catch. * **Migration task assignee parsing (#153)**: When `trellis update --migrate` created the auto-generated migration task, it read `.trellis/.developer` as a plain string and embedded the entire `name=...\ninitialized_at=...` file contents as the `assignee` field. The timestamp line then leaked into `session-start.py` rendering, breaking the ACTIVE TASKS layout. Now parses the `name=` line correctly. Thanks to @suyuan2022 for the fix. ## Documentation * **Task lifecycle commands**: `workflow.md` now documents `task.py start ` and `task.py finish` — previously both subcommands were wired in argparse but completely unmentioned in the workflow guide, so AI agents never knew to call them and `## CURRENT TASK` was perpetually `(none)`. Task Development Flow expanded from 5 to 7 explicit steps with Start (step 2) and Finish (step 7), plus a new "Current task mechanism" explainer tying `.current-task` to SessionStart hook injection. ## Notes * Run `trellis update` to sync all changes * **Behavior change**: Ralph Loop will now actually fire for check/implement/debug subagents. If you were unknowingly relying on the previously-silent behavior, watch for new loop activity after upgrading. # v0.4.0-beta.2 Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.2 2026-03-12 Hotfix for scoped npm package names in monorepo init. ## Bug Fixes * **Scoped package name fix** — `trellis init` on monorepos with scoped npm packages (e.g. `@zhubao/desktop`) no longer creates nested `@scope/` directories in `.trellis/spec/`. The scope prefix is now stripped, so `@zhubao/desktop` becomes `desktop` in all filesystem paths and `config.yaml` keys. Display-only usages retain the full scoped name. ## Migration If you previously ran `trellis init` on a monorepo with scoped packages, you may need to: 1. Rename `.trellis/spec/@scope/name/` to `.trellis/spec/name/` 2. Update the package keys in `.trellis/config.yaml` (e.g. `@scope/name:` → `name:`) # v0.4.0-beta.3 Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.3 2026-03-13 Fix `trellis update` skipping unregistered Python scripts, plus v0.3.10 fixes merged. ## Bug Fixes * **Update script sync** — `trellis update` now uses `getAllScripts()` as the single source of truth for Python script files. Previously, 11 scripts (9 in `common/` and 2 in `multi_agent/`) were silently skipped because they weren't registered in `collectTemplateFiles()`'s hand-maintained list. ## Merged from v0.3.10 * **HTTPS registry URLs** — `trellis init --registry` now accepts HTTPS URLs (e.g. `https://github.com/user/repo`) by auto-converting them to giget-style format. (#87) * **Record-session AI compatibility** — Updated record-session command wording so AI models (especially GPT) no longer refuse to run metadata scripts. (#88) # v0.4.0-beta.4 Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.4 2026-03-16 Git repo context for monorepo packages + improved init-context hints. ## Enhancements * **Git repo context**: Packages with `git: true` in config.yaml now show branch, working directory status, and recent commits in session context * **init-context hints**: After initializing context, the output now lists auto-injected defaults and all available spec files for the AI to choose from * **publish-skill command**: New `/trellis:publish-skill` slash command * **cc-codex-spec-bootstrap**: New marketplace skill for Claude Code + Codex parallel spec bootstrapping ## Bug Fixes * Use `_is_true_config_value` for `isGitRepo` consistency (case-insensitive matching) ## Notes * Run `trellis update` to sync * No migration required # v0.4.0-beta.5 Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.5 2026-03-16 UX improvements: renamed template picker label + iFlow CLI agent fix. ## Enhancements * **Template picker UX**: Renamed "empty templates" to "from scratch" in `trellis init` template selection for clearer messaging ## Bug Fixes * **iFlow CLI agent**: Corrected CLI agent invocation syntax in `cli_adapter.py` (#95) ## Notes * Run `trellis update` to sync * No migration required # v0.4.0-beta.6 Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.6 2026-03-22 CodeBuddy platform support, OpenCode plugin fix, improved skill descriptions. ## Enhancements * **CodeBuddy platform support**: Added [CodeBuddy](https://copilot.tencent.com/) (Tencent Cloud) as the 11th supported platform. Uses nested slash commands at `.codebuddy/commands/trellis/.md` (e.g., `/trellis:start`). Includes type registry, configurator, 12 command templates, CLI flag (`--codebuddy`), and Python `cli_adapter` integration * **Improved skill descriptions**: Enhanced YAML frontmatter descriptions across Codex, Kiro, and Qoder skill templates for better AI triggering accuracy. Descriptions now include specific use cases and trigger conditions ## Bug Fixes * **OpenCode plugin directory**: Fixed plugin directory name from `plugin/` to `plugins/` in the OpenCode configurator (#103) ## Notes * Run `trellis update` to sync * No migration required # v0.4.0-beta.7 Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.7 2026-03-22 Fix Pyright/Pylance import warnings in session-start hooks. ## Bug Fixes * **IDE import warnings**: Suppressed Pyright/Pylance `reportMissingImports` false positives in `session-start.py` hooks. The `common.config` and `common.paths` imports are resolved at runtime via `sys.path` but IDE static analyzers cannot follow dynamic paths. Added `# type: ignore[import-not-found]` annotations ## Notes * Run `trellis update` to sync * No migration required # v0.4.0-beta.8 Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.8 2026-03-24 Decouple `.agents/skills/` as shared Agent Skills layer, add full `.codex/` directory support with hooks, platform-specific skills, and custom agents. ## Enhancements * **Shared Agent Skills layer**: `.agents/skills/` is now a shared directory following the [agentskills.io](https://agentskills.io) open standard. It is no longer bound to the Codex platform — any universal agent CLI (Codex, Kimi CLI, Amp, Cline, etc.) can read these skills * **Codex `.codex/` directory**: New platform-specific directory structure: * `.codex/config.toml` — project-scoped Codex config * `.codex/agents/` — custom Codex agents (implement, research, check) * `.codex/skills/` — Codex-specific skills (e.g. `parallel` with `--platform codex`) * `.codex/hooks/session-start.py` + `hooks.json` — SessionStart hook injecting full Trellis context (workflow, guidelines, task status) * **Codex SessionStart hook**: Automatically injects Trellis workflow, guidelines, and task context into Codex sessions. Requires `codex_hooks = true` under `[features]` in `~/.codex/config.toml` (experimental Codex feature) * **Branch context in sessions**: Session journal records now include git branch information (#108) ## Bug Fixes * **iFlow CLI adapter**: Reverted incorrect `--agent` flag change from PR #112. iFlow uses `$agent_name` prefix format, not `--agent` * **Codex agent TOML format**: Fixed to use correct fields (`name`, `description`, `developer_instructions`, `sandbox_mode`) instead of invalid `[sandbox_read_only]` + `prompt` format ## Migration * **Automatic**: Old Codex users (`.agents/skills/` without `.codex/`) are auto-detected and upgraded on `trellis update` * **safe-file-delete**: `.agents/skills/parallel/SKILL.md` (moved to `.codex/skills/`), old `trellis-*.toml` agent files (renamed) * Run `trellis update` to apply all changes ## Breaking Changes * **Platform detection**: `.agents/skills/` alone no longer detects as Codex. `.codex/` directory is required * **configDir**: Codex `configDir` changed from `.agents/skills` to `.codex` ## Notes * Codex hooks require `codex_hooks = true` under `[features]` in `~/.codex/config.toml` * Codex hooks `suppressOutput` is not yet functional (Codex experimental limitation — context is still printed in TUI) * `parallel` skill moved from shared `.agents/skills/` to Codex-specific `.codex/skills/` since it contains `--platform codex` # v0.4.0-beta.9 Source: https://docs.trytrellis.app/changelog/v0.4.0-beta.9 2026-04-07 Copilot & Windsurf platform support, self-hosted registry, OpenCode dispatch fix, and 6-phase task lifecycle. ## Enhancements * **GitHub Copilot support**: New platform with standalone prompt templates and hook tracking. Run `trellis init --platform copilot` to set up * **Windsurf support**: Full workflow support for Windsurf IDE — rules, workflows (brainstorm, start, before-dev, finish-work, update-spec, record-session), and AI configuration * **Self-hosted registry**: Support self-hosted GitLab/GitHub Enterprise URLs in `--registry` flag (#131). Template fetcher now correctly parses GHE/GitLab raw file URLs * **StatusLine integration**: Claude Code statusLine now shows Trellis task context (#127) * **CodeBuddy & Codex improvements**: New CodeBuddy platform support, Codex agent and docs fixes (#128, #116) * **6-phase task lifecycle**: Task `next_action` template updated from 4-phase pipeline to full lifecycle: brainstorm → research → implement → check → update-spec → record-session * **Marketplace as submodule**: Marketplace migrated to standalone repo, linked as git submodule (#117) ## Bug Fixes * **OpenCode dispatch sync**: Dispatch now waits for child tasks synchronously instead of background polling, preventing premature phase advancement (#147) * **Cross-platform path normalization**: `.current-task` path references now normalized across platforms (#130) * **Codex Windows fix**: `{{PYTHON_CMD}}` placeholder in `hooks.json` now correctly resolved on Windows (#132) * **Session recording**: `add_session.py` git-add error handling improved, Python 3.10 version check added * **Template fetcher**: Self-hosted GitLab/GHE URL parsing fixed in `template-fetcher.ts` ## Notes * Run `trellis update` to sync all changes * New platforms: `trellis init --platform copilot` or `--platform windsurf` # v0.4.0-rc.0 Source: https://docs.trytrellis.app/changelog/v0.4.0-rc.0 2026-04-14 **v0.4.0 feature freeze.** First release candidate. No new features before stable — only bug fixes accepted. Please test and report regressions. ## SessionStart size fix (#154) Vanilla `additionalContext` reduced from **\~29 KB to \~7 KB**, comfortably under Claude Code's \~20 KB truncation threshold. Task state (ACTIVE TASKS, CURRENT TASK) was being silently lost on most non-trivial projects. Thanks to @21nak for the thorough writeup, measurements, and both PRs. * **#161 workflow\.md ToC**: Replace full `workflow.md` injection (\~12 KB) with a compact section index that lists each `##` heading. Applied to all 5 platforms including copilot. AI reads the full file on demand. * **#160 remove start.md injection**: The `` block pre-injected `start.md` (\~11 KB), but slash commands expand on demand anyway — this was duplicate work. Now removed from 4 platforms; copilot never had it. * **Follow-up cleanup**: `` text no longer references nonexistent "Steps 1-3 / Step 4" after `` was removed. Orphaned `claude_dir` / `codex_dir` / `iflow_dir` variables removed. ## OpenCode plugin v1 refactor (#159) Update OpenCode templates to the v1 plugin API (`export default { id, server }`). Fixes non-persistent context injection: `experimental.chat.messages.transform` didn't write back to history, so injected Trellis context was lost on session reopen. Now routes through `chat.message` hook with SDK history-based dedupe via `metadata.trellis.sessionStart` markers. `task` tool prompt mutation now in-place (`args.prompt = ...`) because the runtime holds a local reference to the args object. Thanks to @Adamcf123. ## Windows encoding fix (#163) `statusline.py` crashed on Windows with `UnicodeEncodeError: 'gbk' codec can't encode` when rendering the `·` separator in the info line. Both the live hook and the claude template now wrap `stdout`/`stderr` in UTF-8 on Windows. Thanks to @xiangagou163. ## Features * **`feat(init)`: re-init fast path (#157)** — When `.trellis/` already exists, `trellis init` offers a streamlined flow instead of the full interactive setup: * `trellis init --codex` → configure only Codex, skip everything else * `trellis init -u name` → set up developer identity (new device sync) * `trellis init` (bare) → menu: add platform / add developer / full re-init * `--force` / `--skip-existing` → bypass fast path, run full init ## Bug Fixes * **`fix(init)`: skip bootstrap task creation on re-init** — re-running `trellis init` no longer creates duplicate bootstrap tasks ## Documentation * **`docs(spec)`: SessionStart size constraint** — platform-integration spec now documents the \~20 KB `additionalContext` truncation threshold with a size budget table, preventing future hooks from silently exceeding the limit ## Notes * RC install: `npm install -g @mindfoldhq/trellis@rc` * Please run `trellis update` on an existing project and report any regressions * Session-start hooks have been significantly restructured — if you customized them locally, re-check after update * Windows users with statusline garbling should also update # v0.4.0-rc.1 Source: https://docs.trytrellis.app/changelog/v0.4.0-rc.1 2026-04-14 **Late-RC additive feature.** Two pure-additive changes — no migrations, no behavior changes for existing platforms. Safe to update mid-RC. ## Factory Droid platform support [Factory Droid](https://factory.ai) is now a first-class Trellis platform. Cursor-level scope: commands-only, no hooks/agents. * `trellis init --droid` writes 12 Trellis commands to `.factory/commands/trellis/.md` * Each file ships with optional YAML frontmatter (`description: ...`) so Droid's `/commands` autocomplete shows a one-line summary * Layout uses nested `trellis/` subdirectory like Claude Code (Droid's docs claim nesting is unsupported but the actual binary picks them up — verified before release) * `cli_adapter.py` fully integrates Droid so Trellis Python scripts (status, archive, journals) detect `.factory/` projects correctly * Multi-agent CLI `run`/`resume` currently raises `ValueError` ("not yet integrated with Trellis multi-agent") — same pattern as Copilot/Windsurf. Can be extended in a future release if there's demand. ## Codex option hints at `.agents/skills/` shared layer The interactive `trellis init` checkbox for Codex now reads: ``` Codex (also writes .agents/skills/ — read by Cursor, Gemini CLI, GitHub Copilot, Amp, Kimi Code) ``` Trellis only writes `.agents/skills/` when Codex is enabled, but that directory is read by many other clients via the [agentskills.io](https://agentskills.io) open standard. Surfacing this in the prompt makes the spillover benefit visible — users picking Codex understand it isn't Codex-specific. Verified against each client's official docs: * [Cursor Skills](https://cursor.com/docs/skills) — explicit `.agents/skills/` entry * [Gemini CLI Skills](https://geminicli.com/docs/cli/skills) — `.agents/skills/` is the cross-client "alias", takes precedence over `.gemini/skills/` * [VS Code Copilot Agent Skills](https://code.visualstudio.com/docs/copilot/customization/agent-skills) — `.agents/skills/` listed alongside `.github/skills/` and `.claude/skills/` * [Amp Owner's Manual](https://ampcode.com/manual) — `.agents/skills/` is the only project-level skill location * [Kimi Code CLI Skills](https://moonshotai.github.io/kimi-cli/en/customization/skills.html) — discovered from `.agents/skills/` (or `.kimi/skills/`, `.claude/skills/`) Note: Claude Code is intentionally omitted. Its [official skills docs](https://code.claude.com/docs/en/skills) only list `.claude/skills/` and `~/.claude/skills/` — Claude Code does NOT read `.agents/skills/`, contrary to several third-party blog claims. ## Notes * Pure-additive update. RC users can `trellis update` safely — no file renames, no behavior changes, no migrations. * Run `trellis init --droid` to try Factory Droid support. * RC install: `npm install -g @mindfoldhq/trellis@rc` # Contribute to Docs Source: https://docs.trytrellis.app/contribute/docs How to contribute to Trellis documentation (mindfold-ai/docs) ## Contribute with AI assistance The easiest way to contribute is with Claude Code. We have a built-in skill that guides you through the process. ### Step 1: Fork and clone ```bash theme={null} # Fork on GitHub first, then: git clone https://github.com/YOUR_USERNAME/docs.git cd docs pnpm install ``` ### Step 2: Tell Claude what you want to contribute Open Claude Code in the project and describe what you want to add: * "I want to add a new spec template for Next.js projects" * "I want to improve the multi-agent documentation" ### Step 3: Claude uses the contribute skill automatically Claude will read the `contribute` skill and guide you through: * Where to put your files * What related files need updating (docs.json, index pages) * Bilingual requirements (EN + ZH) * How to test locally ### Step 4: Review and submit PR Review the changes, test with `pnpm dev`, push to your fork, then open a PR to the original repo. The contribute skill knows the project structure and conventions. It handles the details so you can focus on content. *** ## Ways to contribute ### Report issues Found a problem with the docs? Open an issue: [https://github.com/mindfold-ai/docs/issues](https://github.com/mindfold-ai/docs/issues) Include: * Which page has the issue * What's wrong or confusing * Suggested fix (if you have one) ### Suggest improvements Have an idea for better docs? Open a discussion: [https://github.com/mindfold-ai/docs/discussions](https://github.com/mindfold-ai/docs/discussions) ### Contribute a Skill Skills extend AI capabilities. To add a new skill: 1. Fork the [Trellis repo](https://github.com/mindfold-ai/Trellis) 2. Create skill directory: ``` marketplace/skills/your-skill/ └── SKILL.md ``` 3. Open a PR to the Trellis repo 4. (Optional) Create documentation pages in docs repo (`skills-market/your-skill.mdx` + Chinese version) See [Claude Code Skills documentation](https://code.claude.com/docs/en/skills) for SKILL.md format. Skills are hosted in the [Trellis main repo](https://github.com/mindfold-ai/Trellis), not in docs. ### Contribute a Spec Template Spec templates are Trellis project guidelines (not Claude features). To add one: 1. Fork the repo 2. Create `marketplace/specs/your-template/` with guideline files 3. Create documentation pages (`templates/specs-your-template.mdx` + Chinese version) 4. Update `docs.json` navigation 5. Open a PR Good contributions are: * Specific and actionable * Well-documented * Tested on real projects ### Fix typos and improve clarity Small fixes: edit directly on GitHub and submit a PR. Larger changes: clone locally, make changes, test with `pnpm dev`. *** ## Development setup ```bash theme={null} # Install dependencies pnpm install # Start local dev server pnpm dev # Check markdown lint pnpm lint:md # Verify docs structure pnpm verify # Format files pnpm format ``` *** ## Bilingual requirement All user-facing content must have both English and Chinese versions: | English | Chinese | | ----------------------- | -------------------------- | | `guides/example.mdx` | `zh/guides/example.mdx` | | `templates/example.mdx` | `zh/templates/example.mdx` | Update `docs.json` navigation for both languages. *** ## Commit messages Use conventional commits: ``` docs: add Next.js spec template fix: correct broken link in quickstart feat: add new skill to marketplace ``` *** ## PR process 1. Create a PR with a clear description 2. Ensure CI checks pass (lint, verify) 3. Wait for review 4. Address feedback 5. Merge after approval *** ## License Contributions are licensed under MIT. By contributing, you agree to this. ## Questions? Open a discussion or email [taosu@mindfold.ai](mailto:taosu@mindfold.ai). # Contribute to Trellis Source: https://docs.trytrellis.app/contribute/trellis How to contribute to the Trellis project (mindfold-ai/Trellis) # Contributing to Trellis See the contribution guide on GitHub: English contribution guidelines # Appendix A: Key File Paths Quick Reference Source: https://docs.trytrellis.app/guide/appendix-a ## Appendix A: Key File Paths Quick Reference ### Core Documents | File | Description | When Read | | ------------------------ | --------------------------- | --------------------------- | | `.trellis/workflow.md` | Development workflow guide | Every session start | | `.trellis/worktree.yaml` | Multi-Agent worktree config | During parallel development | | `.trellis/.version` | Current Trellis version | During updates | ### Command Definitions | File | Command | | ----------------------------------------------- | ---------------------------- | | `.claude/commands/trellis/start.md` | `/trellis:start` | | `.claude/commands/trellis/parallel.md` | `/trellis:parallel` | | `.claude/commands/trellis/before-dev.md` | `/trellis:before-dev` | | `.claude/commands/trellis/brainstorm.md` | `/trellis:brainstorm` | | `.claude/commands/trellis/check.md` | `/trellis:check` | | `.claude/commands/trellis/check-cross-layer.md` | `/trellis:check-cross-layer` | | `.claude/commands/trellis/finish-work.md` | `/trellis:finish-work` | | `.claude/commands/trellis/break-loop.md` | `/trellis:break-loop` | | `.claude/commands/trellis/create-command.md` | `/trellis:create-command` | | `.claude/commands/trellis/integrate-skill.md` | `/trellis:integrate-skill` | | `.claude/commands/trellis/onboard.md` | `/trellis:onboard` | | `.claude/commands/trellis/record-session.md` | `/trellis:record-session` | | `.claude/commands/trellis/update-spec.md` | `/trellis:update-spec` | ### Agent Definitions | File | Agent | Role | | ----------------------------- | --------- | ------------------------------ | | `.claude/agents/dispatch.md` | Dispatch | Pure orchestrator | | `.claude/agents/plan.md` | Plan | Requirements assessment | | `.claude/agents/implement.md` | Implement | Code implementation | | `.claude/agents/check.md` | Check | Quality checking | | `.claude/agents/debug.md` | Debug | Bug fixing | | `.claude/agents/research.md` | Research | Information search (read-only) | ### Hook Scripts | File | Trigger Timing | Function | | ------------------------------------------ | -------------------- | --------------------- | | `.claude/hooks/session-start.py` | SessionStart | Auto-inject context | | `.claude/hooks/inject-subagent-context.py` | PreToolUse (Task) | Spec injection engine | | `.claude/hooks/ralph-loop.py` | SubagentStop (check) | Quality control loop | ### Cursor Command Definitions | File | Command | | ----------------------------------------------- | ---------------------------- | | `.cursor/commands/trellis-start.md` | `/trellis-start` | | `.cursor/commands/trellis-before-dev.md` | `/trellis-before-dev` | | `.cursor/commands/trellis-brainstorm.md` | `/trellis-brainstorm` | | `.cursor/commands/trellis-check.md` | `/trellis-check` | | `.cursor/commands/trellis-check-cross-layer.md` | `/trellis-check-cross-layer` | | `.cursor/commands/trellis-finish-work.md` | `/trellis-finish-work` | | `.cursor/commands/trellis-break-loop.md` | `/trellis-break-loop` | | `.cursor/commands/trellis-create-command.md` | `/trellis-create-command` | | `.cursor/commands/trellis-integrate-skill.md` | `/trellis-integrate-skill` | | `.cursor/commands/trellis-onboard.md` | `/trellis-onboard` | | `.cursor/commands/trellis-record-session.md` | `/trellis-record-session` | | `.cursor/commands/trellis-update-spec.md` | `/trellis-update-spec` | ### Codex / OpenCode Configuration | File | Description | | --------------------------------- | ----------------------------------------------------------------------- | | `AGENTS.md` | Entry file, provides base project context (generated for all platforms) | | `.agents/skills/*/SKILL.md` | Shared Agent Skills (13 skills) | | `.codex/config.toml` | Project-scoped Codex configuration | | `.codex/agents/*.toml` | Custom Codex agents (`implement.toml`, `research.toml`, `check.toml`) | | `.codex/skills/parallel/SKILL.md` | Codex-specific skill for multi-agent pipelines | | `.codex/hooks/session-start.py` | SessionStart hook (auto-injects context) | | `.codex/hooks.json` | Hooks configuration | ### Kilo Code Configuration | File | Description | | -------------------------- | ------------------------------------------------------------------------------------ | | `.kilocode/workflows/*.md` | Workflow commands (equivalent to slash commands) — 13 workflows generated by Trellis | ### Kiro Configuration | File | Description | | ------------------------- | ------------------------------------------------------------------------------- | | `.kiro/skills/*/SKILL.md` | Agent Skills (YAML frontmatter + instructions) — 12 skills generated by Trellis | ### Script Tools | Script | Function | | ------------------------------------------- | -------------------------------- | | `.trellis/scripts/task.py` | Task management (14 subcommands) | | `.trellis/scripts/get-context.py` | Get session context | | `.trellis/scripts/get-developer.py` | Get developer identity | | `.trellis/scripts/init-developer.py` | Initialize developer | | `.trellis/scripts/add-session.py` | Record session | | `.trellis/scripts/multi-agent/plan.py` | Plan phase script | | `.trellis/scripts/multi-agent/start.py` | Start worktree Agent | | `.trellis/scripts/multi-agent/status.py` | View status | | `.trellis/scripts/multi-agent/create-pr.py` | Create PR | | `.trellis/scripts/multi-agent/cleanup.py` | Clean up worktree | *** # Appendix B: Complete Command Cheat Sheet Source: https://docs.trytrellis.app/guide/appendix-b ## Appendix B: Complete Command Cheat Sheet ### Slash Commands (Cross-Platform Reference) | Claude Code / OpenCode | Cursor | Codex | Kilo | Kiro | Category | Description | | ---------------------------- | ---------------------------- | -------------------- | ----------------------- | ----- | --------- | ---------------------------------- | | `/trellis:start` | `/trellis-start` | `$start` | `/start.md` | skill | Session | Start development session | | `/trellis:parallel` | ❌ | ❌ | `/parallel.md` | ❌ | Session | Multi-Agent parallel orchestration | | `/trellis:record-session` | `/trellis-record-session` | `$record-session` | `/record-session.md` | skill | Session | Record session history | | `/trellis:onboard` | `/trellis-onboard` | `$onboard` | `/onboard.md` | skill | Session | New member onboarding | | `/trellis:before-dev` | `/trellis-before-dev` | `$before-dev` | `/before-dev.md` | skill | Prep | Development prep | | `/trellis:check` | `/trellis-check` | `$check` | `/check.md` | skill | Quality | Code check | | `/trellis:check-cross-layer` | `/trellis-check-cross-layer` | `$check-cross-layer` | `/check-cross-layer.md` | skill | Quality | Cross-layer consistency check | | `/trellis:finish-work` | `/trellis-finish-work` | `$finish-work` | `/finish-work.md` | skill | Quality | Pre-commit finish checklist | | `/trellis:brainstorm` | `/trellis-brainstorm` | `$brainstorm` | `/brainstorm.md` | skill | Knowledge | Brainstorming | | `/trellis:break-loop` | `/trellis-break-loop` | `$break-loop` | `/break-loop.md` | skill | Knowledge | Deep bug analysis | | `/trellis:update-spec` | `/trellis-update-spec` | `$update-spec` | `/update-spec.md` | skill | Knowledge | Update code-spec | | `/trellis:create-command` | `/trellis-create-command` | `$create-command` | `/create-command.md` | skill | Extension | Create custom command | | `/trellis:integrate-skill` | `/trellis-integrate-skill` | `$integrate-skill` | `/integrate-skill.md` | skill | Extension | Integrate external Skill | **Kilo** commands are implemented as Markdown files under `.kilocode/workflows/`, invoked in chat as `/start.md`, etc. **Kiro** commands are implemented as Agent Skills under `.kiro/skills/*/SKILL.md`. ### task.py Subcommands | Subcommand | Description | Usage | | ----------------- | -------------------- | ------------------------------------------------------------------ | | `create` | Create task | `task.py create "title" [--slug name] [-a assignee] [-p priority]` | | `init-context` | Initialize JSONL | `task.py init-context "$DIR" [--platform]` | | `add-context` | Add context entry | `task.py add-context "$DIR" "" ""` | | `validate` | Validate JSONL | `task.py validate "$DIR"` | | `list-context` | View all entries | `task.py list-context "$DIR"` | | `start` | Set as current task | `task.py start "$DIR"` | | `finish` | Clear current task | `task.py finish` | | `set-branch` | Set branch name | `task.py set-branch "$DIR" "feature/xxx"` | | `set-base-branch` | Set PR target branch | `task.py set-base-branch "$DIR" "main"` | | `set-scope` | Set scope | `task.py set-scope "$DIR" "auth"` | | `create-pr` | Create PR | `task.py create-pr` | | `archive` | Archive task | `task.py archive ` | | `list` | List active tasks | `task.py list [--mine] [--status ]` | | `list-archive` | List archived tasks | `task.py list-archive [YYYY-MM]` | ### Python Scripts ```bash theme={null} # Context management ./.trellis/scripts/get-context.py # Get full context ./.trellis/scripts/get-context.py --json # JSON format ./.trellis/scripts/get-developer.py # Get developer identity # Session recording ./.trellis/scripts/add-session.py --title "..." --commit "..." --summary "..." # Multi-Agent ./.trellis/scripts/multi-agent/plan.py --name "..." --type "..." --requirement "..." ./.trellis/scripts/multi-agent/start.py "$TASK_DIR" ./.trellis/scripts/multi-agent/status.py [--log ] [--watch ] ./.trellis/scripts/multi-agent/cleanup.py ./.trellis/scripts/multi-agent/create-pr.py ``` *** # Appendix C: task.json Schema Reference Source: https://docs.trytrellis.app/guide/appendix-c ## Appendix C: task.json Schema Reference ```json theme={null} { "id": "string", // Task ID, format: MM-DD-slug "name": "string", // Slug name "title": "string", // Task title "description": "string", // Description "status": "string", // planning | in_progress | review | completed | rejected "dev_type": "string", // backend | frontend | fullstack | test | docs "scope": "string", // Commit scope, e.g., "auth" "priority": "string", // P0 | P1 | P2 | P3 (default P2) "creator": "string", // Creator "assignee": "string", // Assignee "createdAt": "string", // ISO 8601 creation time "completedAt": "string", // ISO 8601 completion time (null if not done) "branch": "string", // Feature branch name "base_branch": "string", // PR target branch "worktree_path": "string",// Worktree path (null if not parallel) "current_phase": "number", // Current phase number "next_action": [ // Phase sequence {"phase": 1, "action": "implement"}, {"phase": 2, "action": "check"}, {"phase": 3, "action": "finish"}, {"phase": 4, "action": "create-pr"} ], "commit": "string", // Commit hash "pr_url": "string", // PR URL "subtasks": [], // Subtask list "relatedFiles": [], // Related files list "notes": "string" // Notes } ``` *** # Appendix D: JSONL Configuration Format Reference Source: https://docs.trytrellis.app/guide/appendix-d ## Appendix D: JSONL Configuration Format Reference ### File Entry ```jsonl theme={null} {"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"} ``` ### Directory Entry ```jsonl theme={null} {"file": "src/services/", "type": "directory", "reason": "Existing service patterns"} ``` ### Complete Example (fullstack implement.jsonl) ```jsonl theme={null} {"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"} {"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"} {"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"} {"file": ".trellis/spec/backend/api-module.md", "reason": "API module conventions"} {"file": ".trellis/spec/backend/quality.md", "reason": "Code quality requirements"} {"file": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"} {"file": ".trellis/spec/frontend/components.md", "reason": "Component conventions"} ``` ### Completion Marker Generation Rules `reason` field → UPPERCASE + spaces replaced with underscores + `_FINISH` suffix: | reason | Generated Marker | | --------------------------- | ---------------------------------- | | "TypeCheck" | `TYPECHECK_FINISH` | | "Lint" | `LINT_FINISH` | | "Code quality requirements" | `CODE_QUALITY_REQUIREMENTS_FINISH` | | "Finish work checklist" | `FINISH_WORK_CHECKLIST_FINISH` | *** # Appendix E: worktree.yaml Configuration Reference Source: https://docs.trytrellis.app/guide/appendix-e ## Appendix E: worktree.yaml Configuration Reference ```yaml theme={null} # ─── Paths ─────────────────────────────────── worktree_dir: ../trellis-worktrees # Worktree storage directory (relative path) # ─── Files to Copy ────────────────────────── copy: # Files needing independent copies per worktree - .env - .env.local - .trellis/.developer # ─── Post-Create Hooks ────────────────────── post_create: # Commands to run after creation (sequential) - pnpm install --frozen-lockfile # ─── Ralph Loop Verification ──────────────── verify: # Quality verification commands (all must pass) - pnpm lint - pnpm typecheck - pnpm test ``` | Field | Type | Required | Description | | -------------- | --------- | -------- | -------------------------------------------------------------- | | `worktree_dir` | string | No | Worktree storage directory, defaults to `../trellis-worktrees` | | `copy` | string\[] | No | List of files to copy to each worktree | | `post_create` | string\[] | No | Commands to run after worktree creation; aborts on failure | | `verify` | string\[] | No | Ralph Loop verification commands; all must return 0 to pass | *** # Appendix F: FAQ Source: https://docs.trytrellis.app/guide/appendix-f ## Appendix F: FAQ ### Q1: When should I use `/start` vs `/parallel`? | Dimension | `/start` | `/parallel` | | --------------- | ------------------ | ----------------------------- | | Task complexity | Simple to moderate | Complex, can be split | | Estimated time | \< 30 minutes | > 30 minutes | | Independence | Single task | Multiple independent subtasks | | Isolation | Not needed | Needed (worktree) | ### Q2: When do I need `/check-cross-layer`? **Must use**: When changes span frontend + backend + database **Recommended**: When modifying API interfaces or database schemas **Not needed**: For pure frontend UI tweaks or pure backend internal logic ### Q3: What should I do after `/break-loop` analysis? After `/break-loop` performs deep analysis, you should manually update the analysis results into spec files under `.trellis/spec/`, then git push. The next session's Hook will automatically inject the updated specs. ``` Fix Bug → /break-loop deep analysis → manually update spec → git push → auto-prevented next time ``` ### Q4: How do I monitor multi-Agent parallel tasks? ```bash theme={null} ./.trellis/scripts/multi-agent/status.py # Overview ./.trellis/scripts/multi-agent/status.py --log # View logs ./.trellis/scripts/multi-agent/status.py --watch # Live monitoring ``` Logs are located under the worktree directory in `.dispatch-log` and `.plan-log`. ### Q5: Where is session history stored? ``` .trellis/workspace/ ├── index.md # Master index (all developers) └── {your-name}/ ├── index.md # Personal index (session count, last active, history table) └── journal-N.md # Session journal (max 2,000 lines per file) ``` ### Q6: How detailed should specs be? **200-500 lines per file, 20-50 lines per section** Principles: * Specific enough to include code examples * Explain "why", not just "what" * Concise — one concept per section * Actionable — AI can follow directly * Current — update immediately when outdated ### Q7: Will multiple people using Trellis cause conflicts? **No conflicts**: workspace (per-developer isolation), .developer (gitignored), parallel worktrees **Potential conflicts**: spec files (resolve via PR review), task management (use `--assignee` for clear assignment) ### Q8: How do I migrate an existing project to Trellis? 1. `npm install -g @mindfoldhq/trellis@latest` 2. `trellis init -u your-name` (auto-creates bootstrap guide task) 3. Run `/start` — AI auto-detects the bootstrap task and helps fill specs 4. Manually supplement core specs 5. Add `.trellis/` and `.claude/` to Git 6. Commit and push; team members pull then run `trellis init -u their-name` ### Q9: What if Ralph Loop verification fails? 1. Check Agent auto-attempts fixes (up to 5 iterations) 2. If still failing after 5 attempts, Ralph Loop force-passes with a warning 3. You can manually check and fix, then re-run check 4. If the verify commands themselves are problematic, adjust the `verify` config in `worktree.yaml` ### Q10: How do I update Trellis without losing custom configuration? ```bash theme={null} # Preview updates first trellis update --dry-run # Execute update trellis update # Trellis auto-detects files you've modified # Unmodified files are updated directly # Modified files prompt you to choose: overwrite / skip / merge ``` ### Q11: Can Cursor users get the same automation as Claude Code? Not entirely. Cursor doesn't support the Hook system, so: * **No auto-injection** — you need to manually run `/start` to load context * **No Ralph Loop** — you need to manually run `/trellis-check-backend` and similar check commands * **No Multi-Agent Pipeline** — `/parallel` orchestration is not supported * **Core features retained** — Spec management, Task management, cross-session memory (via `/start`), and all check commands remain available Cursor users can achieve roughly 80% of the Claude Code experience through manual command invocation. See [13.2 Cursor Integration](#132-cursor-integration) for details. ### Q12: How do Windows users install Trellis? All Trellis scripts have been migrated to Python, natively supporting Windows: ```bash theme={null} # 1. Ensure Node.js and Python 3.8+ are installed # 2. Install Trellis npm install -g @mindfoldhq/trellis@latest # 3. Initialize normally cd your-project trellis init -u your-name ``` ### Q13: Do I need to reconfigure when switching from Cursor to Claude Code? No. `trellis init` generates both `.claude/` and `.cursor/` configurations during initialization. If your project already has `.cursor/commands/` but not `.claude/`, simply re-run: ```bash theme={null} trellis init -u your-name ``` Trellis auto-detects the environment and fills in missing configurations. Your `.trellis/` directory (Spec, Workspace, Tasks) is fully shared — no need to recreate. ### Q14: What's the difference between Kilo Code and Claude Code multi-Agent? Both support multi-Agent parallelism, but the mechanisms differ: | Dimension | Claude Code (Trellis) | Kilo Code | | ------------------------ | -------------------------------------------- | ---------------------------------------------------- | | **Isolation method** | git worktree physical isolation | Independent conversation context (Orchestrator Mode) | | **Orchestration method** | Hook-driven (dispatch → implement → check) | Mode switching (Code / Architect / Debug, etc.) | | **Parallel count** | Depends on number of worktrees | Depends on modes and context | | **Code merging** | Each worktree creates independent PR → merge | Within the same workspace | | **Configuration** | `worktree.yaml` + Hook scripts | Built-in, no extra config needed | ### Q15: How do Kiro's Spec mode and Trellis's task management work together? Kiro's Spec-Driven Development and Trellis's task system are complementary: 1. **Create task with Trellis**: `task.py create "New feature"` generates `prd.md` 2. **Refine with Kiro Spec**: In Kiro, select Spec mode to auto-generate `requirements.md` → `design.md` → `tasks.md` based on `prd.md` 3. **Kiro implements via tasks.md**: Agent Hooks auto-trigger checks on file changes 4. **Record with Trellis**: `/record-session` records the session, `task.py finish` archives the task Kiro's `.kiro/specs/` and Trellis's `.trellis/tasks/` manage their own concerns independently, with no conflicts. ### Q16: Are Kilo Code Skills and Trellis Skills the same thing? Yes, they follow the same **Agent Skills open standard**. A single SKILL.md file can be used across Kilo Code, Cursor, Claude Code, and other platforms that support the standard. Kilo Skills are stored at `.kilocode/skills/*/SKILL.md`, while Claude Code Skills are at `.claude/skills/` or `.agents/skills/`. The formats are compatible and can be copied between platforms. ### Q17: Are OpenCode and Codex Trellis configurations compatible? Partially. Both share the `.agents/skills/` directory. Codex relies on `AGENTS.md` as its entry file; OpenCode supports session hook auto-injection, uses `/` prefix for commands (e.g., `/start`), and provides an experience closer to Claude Code. *** # What is Trellis Source: https://docs.trytrellis.app/guide/ch01-what-is-trellis ## What is Trellis ### 1.1 One-Line Summary **Trellis is scaffolding for AI coding assistants** — it automatically injects your project specs into every AI session, so the AI writes code following your standards instead of improvising. > AI's capabilities grow like vines — full of vitality but spreading everywhere. > Trellis is scaffolding for AI, guiding it along the path of your conventions. ### 1.2 Pain Points Addressed | Pain Point | Current State | Trellis Solution | | ----------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- | | **AI ignores your specs** | You write CLAUDE.md, but AI forgets it after 5 conversation turns | Hook auto-injection ensures specs are included in every conversation | | **Fix A, break B cycle** | AI fixes one bug but introduces another | Thinking Guides + Ralph Loop: think first, then act, then verify | | **Inconsistent code** | AI-generated code runs but doesn't integrate well | Cross-Layer Guide: map data flow before writing code | | **Scope creep** | You ask for a button, AI writes 9,000 lines | Plan Agent: rejects and splits oversized requirements | | **Inconsistent team quality** | Each person's AI produces different coding styles | Shared Spec library — one person optimizes, the whole team benefits | | **Cross-session amnesia** | New sessions require re-explaining project context | Session persistence — AI remembers context across sessions | ### 1.3 Comparison with Traditional Approaches | Dimension | `.cursorrules` | `CLAUDE.md` | Skills | **Trellis** | | --------------------- | --------------------------------- | -------------------------------- | ------------------------- | --------------------------------------------------------- | | Spec injection method | Manually loaded each conversation | Auto-loaded but easily truncated | User-initiated | **Hook auto-injection, precisely loaded per task** | | Spec granularity | One large file | One large file | One per Skill | **Modular files, composed per task** | | Cross-session memory | None | None | None | **Workspace journal persistence** | | Parallel development | Not supported | Not supported | Not supported | **Multi-Agent worktree parallelism** | | Quality control | None | None | None | **Ralph Loop automatic verification** | | Team sharing | Single user | Single user | Shareable but no standard | **Git-versioned Spec library** | | Platform support | Cursor only | Claude Code only | Per platform | **Claude Code + Cursor + Codex + OpenCode + Kilo + Kiro** | ### 1.4 Core Concepts at a Glance | Concept | Description | Location | | ------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | **Spec** | Your coding standards, written in Markdown. AI reads specs before writing code | `.trellis/spec/` | | **Workspace** | Each developer's session logs, letting AI remember what was done last time | `.trellis/workspace/` | | **Task** | A work unit containing requirements docs and context configuration | `.trellis/tasks/` | | **Hook** | Auto-triggered scripts that inject context at session start, Agent invocations, etc. `[Claude Code exclusive]` | `.claude/hooks/` | | **Agent** | Specialized AI sub-processes such as Implement, Check, Debug, etc. `[Claude Code exclusive]` | `.claude/agents/` | | **Skill** | Reusable AI capability modules, shareable across projects | `.claude/skills/` | | **Journal** | Session log files recording what was done in each development session | `.trellis/workspace/{name}/journal-N.md` | Hook and Agent systems are Claude Code exclusive features. Cursor, Codex, and other platforms load specs manually via Slash commands, achieving the same effect. Spec, Workspace, Task, Journal, and other core concepts are universal across all platforms. *** # Quick Start Source: https://docs.trytrellis.app/guide/ch02-quick-start ## Quick Start ### 2.1 Installation ```bash theme={null} # Global install npm install -g @mindfoldhq/trellis@latest # Navigate to your project directory cd your-project ``` **OS Requirements**: Mac, Linux, and Windows are fully supported. All scripts have been migrated to Python for cross-platform compatibility. Choose the init command based on your platform: ```bash theme={null} trellis init -u your-name ``` Automatically detects the Claude Code environment and configures the `.claude/` directory (commands, agents, hooks). ```bash theme={null} trellis init -u your-name ``` Automatically detects the Cursor environment and configures the `.cursor/commands/` directory. ```bash theme={null} trellis init --codex -u your-name ``` Configures `AGENTS.md` and `.agents/skills/`. ```bash theme={null} trellis init --opencode -u your-name ``` Configures `.agents/skills/`. Supports session hook for automatic context injection. ```bash theme={null} trellis init --kilo -u your-name ``` Configures the `.kilocode/` directory (workflows, rules, skills). ```bash theme={null} trellis init --kiro -u your-name ``` Configures the `.kiro/` directory (steering, hooks, prompts). `your-name` becomes your developer identity and creates your personal workspace at `.trellis/workspace/your-name/`. ### 2.2 Platform Configuration `trellis init` automatically detects and configures installed platforms: | Platform | Config Directory | Command Format | | --------------- | ---------------------------------------------------------------- | -------------- | | **Claude Code** | `.claude/commands/trellis/`, `.claude/agents/`, `.claude/hooks/` | `/start` | | **Cursor** | `.cursor/commands/*.md` | `/start` | | **Codex** | `AGENTS.md`, `.agents/skills/` | `$start` | | **OpenCode** | `.agents/skills/` | `/start` | | **Kilo** | `.kilocode/workflows/`, `.kilocode/rules/`, `.kilocode/skills/` | `/start.md` | | **Kiro** | `.kiro/steering/`, `.kiro/hooks/`, `.kiro/prompts/` | `@start` | #### Platform Capability Comparison | Capability | Claude Code | Cursor | Codex | OpenCode | Kilo | Kiro | | ------------------------ | :-----------------: | :-------------: | :---------: | :------: | :-----------------------: | :----------------: | | Session auto-injection | ✅ Hook | ❌ Manual /start | ⚡ AGENTS.md | ✅ Hook | ⚡ rules/ + launchConfig | ⚡ steering/ | | Sub-Agent spec injection | ✅ PreToolUse Hook | ❌ | ❌ | ❌ | ⚡ Orchestrator Mode | ⚡ Custom Agents | | Ralph Loop quality gate | ✅ SubagentStop Hook | ❌ | ❌ | ❌ | ❌ | ⚡ Agent Hooks | | Multi-Agent Pipeline | ✅ | ❌ | ❌ | ❌ | ✅ Orchestrator + worktree | ✅ Autonomous Agent | | Number of commands | 13 | 12 | 13 | 13 | workflows | prompts | ### 2.3 Three Steps to Get Started ```bash theme={null} # Step 1: Open the Claude Code terminal # Hook auto-injects context — you can describe your task directly (or run /start to see the full flow) # Step 2: Describe what you want to do "Add user login feature" # Step 3: AI works automatically # AI reads specs → creates task → invokes Agent to implement → self-checks # Once done, you test, commit, and record the session ``` ```bash theme={null} # Step 1: Open Cursor, you must first run /start # Step 2: Describe what you want to do "Add user login feature" # Step 3: AI works automatically # AI reads specs → creates task → implements → you manually run /trellis-check-backend to check # Once done, you test, commit, and record the session ``` ```bash theme={null} # Step 1: Codex provides base context via AGENTS.md # Run $start for full context # Step 2: Describe what you want to do "Add user login feature" # Step 3: AI works automatically # Once done, you test, commit, and record the session ``` ```bash theme={null} # Step 1: Open the OpenCode terminal # Hook auto-injects context — you can describe your task directly (or run /start to see the full flow) # Step 2: Describe what you want to do "Add user login feature" # Step 3: AI works automatically # Once done, you test, commit, and record the session ``` ```bash theme={null} # Step 1: Kilo auto-loads project specs via .kilocode/rules/ # Run the /start.md workflow for full context # Step 2: Describe what you want to do "Add user login feature" # Step 3: AI works automatically # Kilo Orchestrator Mode breaks down tasks and assigns them to Code/Architect modes # Once done, you test, commit, and record the session ``` ```bash theme={null} # Step 1: Kiro auto-loads project specs via .kiro/steering/ # Choose Spec mode to generate requirements → design → tasks # Step 2: Describe what you want to do "Add user login feature" # Step 3: AI works automatically # Kiro implements step by step following the tasks.md checklist # Agent Hooks can auto-trigger checks on file save # Once done, you test, commit, and record the session ``` ### 2.4 Full Directory Structure ``` your-project/ ├── .trellis/ # Trellis core directory │ ├── .developer # Developer identity (gitignored) │ ├── .current-task # Active task pointer │ ├── .version # Trellis version number │ ├── .template-hashes.json # Template file hashes (for update) │ ├── workflow.md # Development workflow guide │ ├── worktree.yaml # Multi-Agent worktree config │ │ │ ├── spec/ # Project spec library │ │ ├── frontend/ # Frontend specs │ │ │ ├── index.md # Spec index │ │ │ ├── component-guidelines.md │ │ │ ├── hook-guidelines.md │ │ │ ├── state-management.md │ │ │ ├── type-safety.md │ │ │ ├── quality-guidelines.md │ │ │ └── directory-structure.md │ │ ├── backend/ # Backend specs │ │ │ ├── index.md │ │ │ ├── database-guidelines.md │ │ │ ├── error-handling.md │ │ │ ├── logging-guidelines.md │ │ │ ├── quality-guidelines.md │ │ │ └── directory-structure.md │ │ └── guides/ # Thinking guides │ │ ├── index.md │ │ ├── cross-layer-thinking-guide.md │ │ └── code-reuse-thinking-guide.md │ │ │ ├── workspace/ # Developer workspace │ │ ├── index.md # Workspace master index │ │ └── {developer-name}/ # Per-developer directory │ │ ├── index.md # Personal index │ │ └── journal-N.md # Session journal │ │ │ ├── tasks/ # Task directory │ │ ├── {MM-DD-task-name}/ # Active tasks │ │ │ ├── task.json # Task metadata │ │ │ ├── prd.md # Requirements document │ │ │ ├── info.md # Technical design (optional) │ │ │ ├── implement.jsonl # Implement Agent context │ │ │ ├── check.jsonl # Check Agent context │ │ │ └── debug.jsonl # Debug Agent context │ │ └── archive/ # Archived tasks │ │ └── {YYYY-MM}/ │ │ │ └── scripts/ # Automation scripts │ ├── task.py # Task management (14 subcommands) │ ├── get-context.py # Get session context │ ├── get-developer.py # Get developer identity │ ├── init-developer.py # Initialize developer │ ├── add-session.py # Record session │ ├── common/ # Shared libraries │ │ ├── paths.py │ │ ├── developer.py │ │ ├── git-context.py │ │ ├── task-utils.py │ │ ├── task-queue.py │ │ ├── phase.py │ │ ├── registry.py │ │ └── worktree.py │ └── multi-agent/ # Parallel development scripts │ ├── plan.py │ ├── start.py │ ├── status.py │ ├── create-pr.py │ └── cleanup.py │ ├── .claude/ # Claude Code configuration │ ├── settings.json # Hook and permission config │ ├── commands/ # Slash commands │ │ └── trellis/ # Trellis command set │ │ ├── start.md │ │ ├── parallel.md │ │ ├── record-session.md │ │ ├── finish-work.md │ │ ├── onboard.md │ │ ├── before-backend-dev.md │ │ ├── before-frontend-dev.md │ │ ├── check-backend.md │ │ ├── check-frontend.md │ │ ├── check-cross-layer.md │ │ ├── break-loop.md │ │ ├── create-command.md │ │ └── integrate-skill.md │ ├── agents/ # Agent definitions │ │ ├── dispatch.md │ │ ├── plan.md │ │ ├── implement.md │ │ ├── check.md │ │ ├── debug.md │ │ └── research.md │ ├── hooks/ # Hook scripts │ │ ├── session-start.py │ │ ├── inject-subagent-context.py │ │ └── ralph-loop.py │ └── skills/ # Skill directory │ ├── .cursor/ # Cursor configuration │ └── commands/ │ └── trellis-*.md # Cursor command set │ ├── AGENTS.md # Codex entry file ├── .agents/ # Agent Skills (Codex / OpenCode) │ └── skills/ │ ├── .kilocode/ # Kilo Code configuration │ ├── rules/ # Project rules (all modes) │ ├── workflows/ # Workflow commands │ └── skills/ # Agent Skills │ └── .kiro/ # Kiro configuration ├── steering/ # Project context (Steering system) ├── hooks/ # Agent Hooks (event-driven automation) ├── prompts/ # Custom prompts └── specs/ # Spec-Driven Development docs ``` *** # Your First Task Source: https://docs.trytrellis.app/guide/ch03-first-task ## Your First Task ### 3.1 Starting a Session Open the Claude Code terminal. The `session-start.py` Hook fires automatically and context is injected. You can describe your task directly, or run `/start` to see the full flow. The AI automatically performs the following: 1. Reads `workflow.md` to understand the development workflow 2. Runs `get-context.py` to get current state (your identity, Git status, active tasks) 3. Reads `spec/frontend/index.md` and `spec/backend/index.md` to understand project specs 4. Asks you: **"What would you like to work on?"** Open Cursor. **You must first enter**: ``` /start ``` Only then will the AI load context. Cursor's Hook support is still in development, so context loading currently requires manual command invocation. Codex provides base context via `AGENTS.md`, but you need to run `$start` to get full project context (identity, Git status, active tasks, etc.). OpenCode's Hook system auto-injects context at session start, no need to manually run `/start`. Users can describe tasks immediately after opening the terminal. Optionally run `/start` for a more detailed context report. ### 3.2 AI Creates the Task and Develops You say: "Add user login feature". The AI will: ``` 1. Invoke Research Agent to analyze the codebase → Find relevant spec files and code patterns 2. Create a task directory → .trellis/tasks/02-27-user-login/ → Generate task.json, prd.md, implement.jsonl, etc. 3. Activate the task → task.py start (set .current-task) 4. Invoke Implement Agent → Hook auto-injects all specs configured in implement.jsonl → Agent implements the feature following specs 5. Invoke Check Agent → Hook injects check specs configured in check.jsonl → Agent checks code quality and auto-fixes issues → Ralph Loop ensures lint/typecheck passes ``` ### 3.3 Testing and Committing After the AI finishes, it will prompt you: ```bash theme={null} # Run project tests pnpm lint && pnpm typecheck && pnpm test # Commit after confirming everything works git add src/components/LoginForm.tsx src/api/auth.ts git commit -m "feat(auth): add user login feature" ``` ### 3.4 Recording the Session ``` /record-session ``` The AI calls `add-session.py` to append the session content to your journal file and update your personal index. ### 3.5 Coming Back the Next Day — Cross-Session Memory The next day, open a new session and enter `/start`: ``` AI: "Hi Alice! Yesterday you completed the user login feature (commit abc1234), including: LoginForm component, JWT middleware, users table. What would you like to work on today?" ``` The AI reads your workspace journal through the `session-start.py` Hook, remembering what you worked on last time. **Platform differences**: Claude Code and OpenCode automatically read journals via Hooks for cross-session memory. Cursor and Codex users need to manually trigger context loading via `/start` (or `$start`) to get cross-session memory. # Architecture Overview Source: https://docs.trytrellis.app/guide/ch04-architecture ## Architecture Overview ### 4.1 Overall Architecture ``` ┌──────────────────────────────────────────────────────────────┐ │ User │ └─────────────────────────────┬────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ Claude Code / Cursor / Codex / OpenCode / Kilo / Kiro │ │ (AI Coding Assistant Interface) │ └─────────────────────────────┬────────────────────────────────┘ │ ┌────────────┼────────────┐ │ │ ▼ ▼ ┌────────────────────┐ ┌───────────────────────────┐ │ Slash Commands │ │ Hook System │ │ /trellis:* │ │ (Auto-inject) │ │ │ │ [Claude Code only] │ │ User-triggered │ │ │ │ Trigger workflows │ │ session-start.py │ │ │ │ inject-context.py │ │ [All platforms] │ │ ralph-loop.py │ └─────────┬──────────┘ └─────────────┬─────────────┘ │ │ └──────────────┬───────────────┘ │ ▼ ┌──────────────────────────────────────────────────────┐ │ .trellis/ Directory │ │ │ │ spec/ workspace/ tasks/ scripts/ │ │ (Specs) (Records) (Tasks) (Auto) │ └─────────────────────────┬────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────┐ │ Agent System │ │ │ │ Plan → Research → Implement → Check → Debug │ │ │ │ Each Agent receives precise context via Hooks │ └─────────────────────────┬────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────┐ │ Your Project Code │ │ (AI generates/modifies code per specs) │ └──────────────────────────────────────────────────────┘ ``` ### 4.2 Session Startup Flow These two platforms' Hook systems **automatically trigger** `session-start.py` at session start, no need to manually enter `/start`. Users can describe tasks immediately after opening the terminal. Optionally run `/start` for a more detailed context report. Cursor's Hook support is still in development, and Codex provides base context via `AGENTS.md`. Users **must manually invoke** `/start` (or `$start` for Codex) to get full project context. The command internally executes the same steps as the Claude Code Hook: reading identity, workflow, history, tasks, etc. Kilo **auto-loads** project rules via `.kilocode/rules/` and `AGENTS.md` into every interaction. Optionally run the `/start.md` workflow for full Trellis context (identity, Git status, active tasks, etc.). Kiro **auto-loads** project context via `.kiro/steering/` (product.md, tech.md, structure.md, etc.) into every interaction. Optionally run a custom prompt for full Trellis context. Kiro also supports auto-generating requirements, design, and task documents via Spec mode. When you enter `/start` (or when the Claude Code Hook fires automatically), here's what happens behind the scenes: ``` /start │ ▼ ┌────────────────────────────────────────┐ │ Hook: session-start.py (auto-trigger) │ │ │ │ Read .trellis/.developer → identity│ │ Read .trellis/workflow.md → workflow│ │ Read workspace/{name}/index → history │ │ Read git log → commits │ │ Read .trellis/tasks/ → tasks │ └───────────────────┬────────────────────┘ │ ▼ ┌──────────────────────────┐ │ Context injected into AI│ └────────────┬─────────────┘ │ ▼ ┌──────────────────────────────────┐ │ start.md command runs: │ │ │ │ Step 1: Read workflow.md │ │ Step 2: Run get-context.py │ │ Step 3: Read spec indexes │ │ Step 4: Report & ask user │ └──────────────────────────────────┘ ``` `session-start.py` is a `SessionStart` Hook that fires automatically at the start of each new session, ensuring the AI always begins with full context. ### 4.3 Spec Injection Mechanism Automatic spec injection is a Claude Code exclusive feature, relying on the Hook system (`PreToolUse` intercepting `Task` tool calls). Cursor, Codex, OpenCode, and other platforms require manually loading specs via commands (e.g., `/before-backend-dev`). `inject-subagent-context.py` is the core engine of Trellis. When the main Agent invokes a sub-Agent (e.g., Implement), this Hook automatically intercepts and injects context. **Workflow**: ``` Main Agent calls: Task(subagent_type="implement", prompt="...") │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ Hook: inject-subagent-context.py (PreToolUse intercept) │ │ │ │ 1. Read .trellis/.current-task │ │ → Get current task directory path │ │ │ │ 2. Read {task_dir}/implement.jsonl │ │ → Get spec file list for this Agent │ │ │ │ 3. Read each file referenced in JSONL │ │ → .trellis/spec/backend/index.md │ │ → .trellis/spec/backend/database-guidelines.md │ │ → ... │ │ │ │ 4. Read prd.md (requirements) and info.md (design) │ │ │ │ 5. Assemble all into new prompt, replace original │ │ │ │ 6. Update current_phase in task.json │ └───────────────────────┬──────────────────────────────────────┘ │ ▼ Actual prompt received by Implement Agent: # Implement Agent Task ## Your Context === .trellis/spec/backend/index.md === (Full backend spec content) === .trellis/spec/backend/database-guidelines.md === (Full database spec content) === {task_dir}/prd.md (Requirements) === (Full requirements doc) ## Your Task Implement the feature ``` #### JSONL Configuration Format Explained JSONL (JSON Lines) files define which files each Agent needs to read. Each line is a JSON object: ```jsonl theme={null} {"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"} {"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"} {"file": ".trellis/spec/backend/database-guidelines.md", "reason": "Database patterns"} {"file": "src/services/", "type": "directory", "reason": "Existing service patterns"} ``` **Field descriptions**: | Field | Required | Description | | -------- | -------- | -------------------------------------------------------------------------------------------- | | `file` | Yes | Relative path to file or directory (relative to project root) | | `reason` | Yes | Why this file is needed (also used to generate completion markers) | | `type` | No | Defaults to `"file"`. Set to `"directory"` to read all `.md` files in the directory (max 20) | **Three types of JSONL files**: | File | Used By | Typical Content | | ----------------- | --------------- | ----------------------------------------------------- | | `implement.jsonl` | Implement Agent | workflow\.md + relevant specs + code pattern examples | | `check.jsonl` | Check Agent | finish-work.md + check commands + relevant specs | | `debug.jsonl` | Debug Agent | relevant specs + check commands | **Practical example** (implement.jsonl for a backend task): ```jsonl theme={null} {"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"} {"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"} {"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"} {"file": ".trellis/spec/backend/api-module.md", "reason": "API module conventions"} {"file": ".trellis/spec/backend/quality.md", "reason": "Code quality requirements"} ``` **Injection timing and control**: * **implement** Agent: injects implement.jsonl + prd.md + info.md * **check** Agent: injects check.jsonl + prd.md (to understand intent) * **check** Agent (`[finish]` marker): lightweight injection of finish-work.md + prd.md * **debug** Agent: injects debug.jsonl + codex-review-output.txt (if available) * **research** Agent: injects project structure overview + research.jsonl (optional) ### 4.4 Quality Control Loop (Ralph Loop) Ralph Loop is a Claude Code exclusive quality control mechanism, relying on the `SubagentStop` Hook. Cursor and other platforms require manually running `/check-backend` (`/trellis-check-backend`) or `/check-frontend` for code checks. Ralph Loop is based on the [Ralph Wiggum technique](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), automatically verifying when the Check Agent finishes its work. ``` Check Agent thinks it's done │ ▼ ┌────────────────────────────────────────────────────────┐ │ Hook: ralph-loop.py (SubagentStop intercept) │ │ │ │ 1. Read verify config from worktree.yaml │ │ │ │ ┌── Has verify commands? ──┐ │ │ │ │ │ │ ▼ Yes ▼ No │ │ Run verify commands Check completion │ │ (pnpm lint etc.) markers │ │ │ │ │ │ ├── All pass ──────────┤── All present ──→ Allow stop │ │ │ │ │ │ └── Has failure ───────┘── Missing ──→ Block stop │ │ │ │ │ Return to Check Agent │ │ Continue fixing │ │ │ │ Safety limit: max 5 iterations │ └────────────────────────────────────────────────────────┘ ``` **Two verification modes**: **Mode A — Programmatic verification** (recommended, configured in `worktree.yaml`): ```yaml theme={null} verify: - pnpm lint - pnpm typecheck - pnpm test ``` Ralph Loop runs each command in sequence; all must return 0 to pass. **Mode B — Completion Markers** (fallback when no verify config): Markers are generated from `check.jsonl` `reason` fields. For example: ```jsonl theme={null} {"file": "...", "reason": "TypeCheck"} {"file": "...", "reason": "Lint"} ``` Generated markers: `TYPECHECK_FINISH`, `LINT_FINISH`. The Check Agent must include all markers in its output to stop. **State tracking**: Ralph Loop tracks iteration count via `.trellis/.ralph-state.json`: ```json theme={null} { "task": ".trellis/tasks/02-27-user-login", "iteration": 2, "started_at": "2026-02-27T10:30:00" } ``` * Resets automatically on task switch * 30-minute timeout auto-reset * Force pass at 5 iterations (prevents infinite loops) ### 4.5 Complete Agent System Trellis includes 6 built-in Agents, each with different roles, tools, and responsibilities: | Agent | Role | Tools | Model | Key Features | | ------------- | ----------------------- | ----------------------------------------------------------------- | ----- | ---------------------------------------------------------- | | **dispatch** | Pure orchestrator | Read, Bash, Exa Search, Exa Code Context | opus | Only invokes other Agents in sequence, does not read specs | | **plan** | Requirements assessment | Read, Bash, Glob, Grep, Task | opus | Can reject unclear requirements | | **implement** | Code implementation | Read, Write, Edit, Bash, Glob, Grep, Exa Search, Exa Code Context | opus | Forbidden from git commit | | **check** | Quality checking | Read, Write, Edit, Bash, Glob, Grep, Exa Search, Exa Code Context | opus | Must self-fix, controlled by Ralph Loop | | **debug** | Bug fixing | Read, Write, Edit, Bash, Glob, Grep, Exa Search, Exa Code Context | opus | Precise fixes only, no extra refactoring | | **research** | Information search | Read, Glob, Grep, Exa Search, Exa Code Context | opus | Read-only, does not modify files | **Agent Collaboration Flow (Multi-Agent Pipeline)**: ``` Plan Agent │ │ Assess requirements → accept/reject │ Invoke Research Agent to analyze codebase │ Create task directory + JSONL config │ ▼ Dispatch Agent │ ├──→ Implement Agent (phase 1) │ Hook injects implement.jsonl context │ Implement feature → report completion │ ├──→ Check Agent (phase 2) │ Hook injects check.jsonl context │ Check code → auto-fix → Ralph Loop verification │ ├──→ Check Agent [finish] (phase 3) │ Lightweight injection of finish-work.md │ Final verification → confirm requirements met │ └──→ create-pr.py (phase 4) Commit code → push → create Draft PR ``` **Dispatch Agent Timeout Configuration**: | Phase | Max Time | Poll Count | | --------- | ---------- | ---------- | | implement | 30 minutes | 6 polls | | check | 15 minutes | 3 polls | | debug | 20 minutes | 4 polls | *** # Complete Command Reference Source: https://docs.trytrellis.app/guide/ch05-commands ## Complete Command Reference Trellis provides 13 Slash commands (Claude Code), organized into 6 categories. The Cursor version has 12 (excluding `/parallel`). #### Cross-Platform Command Reference | Function | Claude Code / OpenCode | Cursor | Codex | | ---------------------- | -------------------------------------------- | -------------------------------------------- | ---------------------- | | Start session | `/start` (optional, Hook auto-injects) | `/start` (required) | `$start` | | Backend prep | `/before-backend-dev` (optional) | `/trellis-before-backend-dev` (recommended) | `$before-backend-dev` | | Frontend prep | `/before-frontend-dev` (optional) | `/trellis-before-frontend-dev` (recommended) | `$before-frontend-dev` | | Check backend | `/check-backend` (Ralph Loop auto-triggers) | `/trellis-check-backend` (manual) | `$check-backend` | | Check frontend | `/check-frontend` (Ralph Loop auto-triggers) | `/trellis-check-frontend` (manual) | `$check-frontend` | | Cross-layer check | `/check-cross-layer` | `/trellis-check-cross-layer` | `$check-cross-layer` | | Finish checklist | `/finish-work` | `/trellis-finish-work` | `$finish-work` | | Parallel orchestration | `/parallel` | ❌ Not supported | ❌ Not supported | | Record session | `/record-session` | `/trellis-record-session` | `$record-session` | | Brainstorm | `/brainstorm` | `/trellis-brainstorm` | `$brainstorm` | | Bug analysis | `/break-loop` | `/trellis-break-loop` | `$break-loop` | | New member onboarding | `/onboard` | `/trellis-onboard` | `$onboard` | | Create command | `/create-command` | `/trellis-create-command` | `$create-command` | | Integrate Skill | `/integrate-skill` | `/trellis-integrate-skill` | `$integrate-skill` | ### 5.1 Session Management #### `/start` — Start a Development Session **When to use**: Every time you open your AI coding assistant to start work. Claude Code users have context auto-injected via Hooks, so `/start` is optional (but recommended for first-time use to see the full flow). Cursor users **must** run `/start`. **Execution flow**: 1. Read `workflow.md` to understand the workflow 2. Run `get-context.py` to get context (identity, Git status, active tasks) 3. Read spec indexes to understand project specs 4. Report context and ask: "What would you like to work on?" **Task classification decisions**: | Type | Criteria | Workflow | | ---------------- | ---------------------------------------------------------- | --------------------- | | Q\&A | User asks about code or architecture | Answer directly | | Quick fix | Typo fix, single-line change, \< 5 minutes | Edit directly | | Development task | Logic changes, new features, bug fixes, multi-file changes | **Use Task Workflow** | > **When in doubt, use Task Workflow**. Task Workflow ensures Agents receive spec injection, resulting in higher code quality. #### `/parallel` — Multi-Agent Parallel Orchestration Claude Code only. Cursor, Codex, and other platforms do not support Multi-Agent Pipeline. **When to use**: * High task complexity, requiring > 30 minutes * Can be split into multiple independent subtasks * Needs isolation in independent worktrees **Two-phase flow**: **Phase 1: Plan** ```bash theme={null} ./.trellis/scripts/multi-agent/plan.py \ --name "feature-name" \ --type "backend|frontend|fullstack" \ --requirement "User requirement description" ``` The Plan Agent will: 1. Assess whether requirements are clear (may reject, see Chapter 6) 2. Invoke Research Agent to analyze the codebase 3. Create task directory and configure JSONL context 4. Generate the prd.md requirements document **Phase 2: Execute** ```bash theme={null} ./.trellis/scripts/multi-agent/start.py "$TASK_DIR" ``` Automatically creates a Git worktree. The Dispatch Agent executes implement, check, finish, and create-pr in sequence. **Monitoring commands**: ```bash theme={null} ./.trellis/scripts/multi-agent/status.py # Overview ./.trellis/scripts/multi-agent/status.py --log # View logs ./.trellis/scripts/multi-agent/status.py --watch # Live monitoring ./.trellis/scripts/multi-agent/cleanup.py # Clean up worktree ``` #### `/record-session` — Record a Session **When to use**: After the user has tested and committed code. **Prerequisite**: The AI does not execute git commit; it only reads git history. **Execution flow**: ```bash theme={null} ./.trellis/scripts/add-session.py \ --title "Session Title" \ --commit "hash1,hash2" \ --summary "What was accomplished in this session" ``` Automatically completes: * Appends session record to `journal-N.md` * Detects line count and auto-creates a new file when exceeding 2,000 lines * Updates `index.md` (session count +1, last active time, history table) #### `/onboard` — New Member Onboarding **When to use**: When a new team member joins. Includes three parts: 1. Core concept walkthrough (spec / workspace / task / hook) 2. 5 hands-on exercises (bug fix, planning session, Code Review fix, large refactor, debugging session) 3. Spec customization guidance ### 5.2 Development Preparation #### `/before-backend-dev` — Backend Development Prep Reads the backend spec index and related spec documents (database, error handling, logging, type safety, quality guidelines), ensuring the AI understands backend coding standards before writing code. #### `/before-frontend-dev` — Frontend Development Prep Reads the frontend spec index and related spec documents (components, Hooks, state management, type safety, quality guidelines). ### 5.3 Quality Checks #### `/check-backend` — Backend Code Check Execution flow: 1. `git status` to view changes 2. Re-read backend specs 3. Compare code against specs line by line 4. Auto-fix violations (Ralph Loop driven, up to 3 rounds) Check items: directory structure, database operations, error handling, logging conventions, type definitions, no `console.log`, no `any` types, no non-null assertions. #### `/check-frontend` — Frontend Code Check Check items: component naming (PascalCase), Props interfaces, Hook usage, state management, style consistency, TypeScript errors, ESLint errors, unused imports. Also uses the Ralph Loop self-fix cycle. #### `/check-cross-layer` — Cross-Layer Consistency Check Reads the cross-layer thinking guide and analyzes 6 dimensions: 1. **Data flow consistency** — Frontend, API, Database, API, Frontend 2. **Type definition sync** — Frontend and backend interfaces match 3. **Error handling continuity** — Errors properly propagated across layers 4. **Constant synchronization** — Shared constants between frontend and backend 5. **Code reuse** — No duplicate implementations 6. **Import path correctness** — No broken references ### 5.4 Parallel Development #### `/parallel` See section 5.1. ### 5.5 Knowledge Accumulation #### `/break-loop` — Deep Bug Analysis **When to use**: After resolving a tricky bug, to perform deep analysis and prevent similar issues. **5-Dimension Analysis Framework**: 1. **Root Cause Classification**: * A — Missing Spec * B — Cross-layer Contract Violation * C — Change Propagation Failure * D — Test Coverage Gap * E — Implicit Assumption 2. **Why Fixes Failed** — Analyze why previous fix attempts failed 3. **Prevention Mechanisms** (6 types): * Spec update * Type constraints * Lint rules * Test cases * Code review checklist items * Documentation updates 4. **Systematic Expansion** — Search for other potential issues with the same pattern 5. **Knowledge Capture** — Solidify analysis results into specs **Core philosophy**: > The value of debugging is not fixing this bug, but ensuring this class of bugs never happens again. ### 5.6 Utility Commands #### `/finish-work` — Pre-Commit Checklist 6-dimension check before committing: 1. Code quality (lint, type-check, test) 2. Documentation sync 3. API changes 4. Database changes 5. Cross-layer verification 6. Manual testing #### `/create-command` — Create Custom Commands Generates dual-IDE command files under `.claude/commands/trellis/` and `.cursor/commands/`. See Chapter 9 for details. #### `/integrate-skill` — Integrate External Skills Integrates community Skills into your project, creating a unified `/use-[skill-name]` command. See Chapter 12 for details. *** # Task Management Workflow Source: https://docs.trytrellis.app/guide/ch06-task-management ## Task Management Workflow ### 6.1 Task Lifecycle ``` create → init-context → add-context → start → implement/check → finish → archive │ │ │ │ │ │ │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ▼ ▼ Create Init JSONL Add context Set as Development/ Clear Archive to directory config files entries current check cycle current archive/ task.json task ptr task ``` ### 6.2 task.py 14 Subcommands Explained #### Task Creation ```bash theme={null} # Create a task TASK_DIR=$(./.trellis/scripts/task.py create "Add user login" \ --slug user-login \ # Directory name suffix (optional, auto-slugifies otherwise) --assignee alice \ # Assignee (optional) --priority P1 \ # Priority: P0/P1/P2/P3 (optional, default P2) --description "Implement JWT login") # Description (optional) # Created directory: .trellis/tasks/02-27-user-login/ # Created file: task.json ``` #### Context Configuration ```bash theme={null} # Initialize JSONL config ./.trellis/scripts/task.py init-context "$TASK_DIR" backend # dev_type: backend | frontend | fullstack | test | docs # Optional: --platform cursor (default claude) # Add extra context entries ./.trellis/scripts/task.py add-context "$TASK_DIR" implement \ "src/services/auth.ts" "Existing auth patterns" # Target: implement | check | debug (shorthand, auto-appends .jsonl) # Automatically detects whether it's a file or directory # Validate all JSONL-referenced files exist ./.trellis/scripts/task.py validate "$TASK_DIR" # View all JSONL entries ./.trellis/scripts/task.py list-context "$TASK_DIR" ``` #### Task Control ```bash theme={null} # Set as current task (Hook reads this pointer for injection) ./.trellis/scripts/task.py start "$TASK_DIR" # Clear current task (no arguments needed, auto-reads .current-task) ./.trellis/scripts/task.py finish # Set Git branch name ./.trellis/scripts/task.py set-branch "$TASK_DIR" "feature/user-login" # Set PR target branch ./.trellis/scripts/task.py set-base-branch "$TASK_DIR" "main" # Set scope (used in commit messages: feat(scope): ...) ./.trellis/scripts/task.py set-scope "$TASK_DIR" "auth" ``` #### Task Management ```bash theme={null} # List active tasks ./.trellis/scripts/task.py list ./.trellis/scripts/task.py list --mine # Only show your own ./.trellis/scripts/task.py list --status review # Filter by status # Archive completed tasks ./.trellis/scripts/task.py archive user-login # Moves to archive/2026-02/ # List archived tasks ./.trellis/scripts/task.py list-archive ./.trellis/scripts/task.py list-archive 2026-02 # Filter by month # Create PR (delegates to multi-agent/create-pr.py) ./.trellis/scripts/task.py create-pr ``` ### 6.3 task.json Schema ```json theme={null} { "id": "02-27-user-login", "name": "user-login", "title": "Add user login", "description": "Implement JWT login flow", "status": "in_progress", "dev_type": "backend", "scope": "auth", "priority": "P1", "creator": "alice", "assignee": "alice", "createdAt": "2026-02-27T10:00:00Z", "completedAt": null, "branch": "feature/user-login", "base_branch": "main", "worktree_path": null, "current_phase": 1, "next_action": [ { "phase": 1, "action": "implement" }, { "phase": 2, "action": "check" }, { "phase": 3, "action": "finish" }, { "phase": 4, "action": "create-pr" } ], "commit": null, "pr_url": null, "subtasks": [], "relatedFiles": [], "notes": "" } ``` **Status transitions**: ``` planning → in_progress → review → completed ↘ rejected ``` ### 6.4 JSONL Context Configuration in Practice #### Auto-Generated Default Configuration `task.py init-context` generates default JSONL files based on dev\_type: **backend type default implement.jsonl**: ```jsonl theme={null} {"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"} {"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"} {"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"} {"file": ".trellis/spec/backend/api-module.md", "reason": "API module conventions"} {"file": ".trellis/spec/backend/quality.md", "reason": "Code quality requirements"} ``` **backend type default check.jsonl** (Claude Code platform): ```jsonl theme={null} {"file": ".claude/commands/trellis/finish-work.md", "reason": "Finish work checklist"} {"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"} {"file": ".claude/commands/trellis/check-backend.md", "reason": "Backend check spec"} ``` **fullstack type** includes both frontend and backend spec files. #### Adding Custom Context ```bash theme={null} # Add existing code as reference (file) ./.trellis/scripts/task.py add-context "$TASK_DIR" implement \ "src/services/user.ts" "Existing user service patterns" # Add an entire directory (auto-reads all .md files) ./.trellis/scripts/task.py add-context "$TASK_DIR" implement \ "src/services/" "Existing service patterns" # Add custom check context ./.trellis/scripts/task.py add-context "$TASK_DIR" check \ ".trellis/spec/guides/cross-layer-thinking-guide.md" "Cross-layer verification" ``` ### 6.5 Plan Agent and Requirements Assessment The Plan Agent performs strict assessment before accepting requirements, and may reject them. **5 rejection categories**: | Rejection Type | Trigger Condition | Example | | -------------------------- | --------------------------------------- | ----------------------------------- | | **Unclear or Vague** | No specific outcome defined | "Make it better", "Fix the bugs" | | **Incomplete Information** | Missing critical implementation details | References unknown systems | | **Out of Scope** | Does not belong to this project | Requires modifying external systems | | **Potentially Harmful** | Security risk | Intentionally creating backdoors | | **Too Large** | Should be split | Requesting 6 features at once | **On rejection**: * `task.json` status set to `"rejected"` * `REJECTED.md` generated with reasons and improvement suggestions * Task directory preserved for user review **Rejection example**: ``` Input: "Add user authentication, authorization, password reset, 2FA, OAuth integration, and audit logging" === PLAN REJECTED === Reason: Too Large / Should Be Split Details: This requirement bundles 6 distinct features: 1. User authentication (login/logout) 2. Authorization (roles/permissions) 3. Password reset flow 4. Two-factor authentication 5. OAuth integration 6. Audit logging Suggestions: - Start with basic authentication first - Create separate features for each capability ``` ### 6.6 Task Lifecycle Hooks You can configure shell commands that run automatically when task lifecycle events occur. This enables integrations like syncing tasks to Linear, posting to Slack, or triggering CI pipelines. #### Configuration Add a `hooks` block to `.trellis/config.yaml`: ```yaml theme={null} hooks: after_create: - 'python3 .trellis/scripts/hooks/linear_sync.py create' after_start: - 'python3 .trellis/scripts/hooks/linear_sync.py start' after_finish: - "echo 'Task finished'" after_archive: - 'python3 .trellis/scripts/hooks/linear_sync.py archive' ``` The default `config.yaml` ships with the hooks section **commented out**. Uncomment and edit to activate. #### Supported Events | Event | Fires When | Use Case | | --------------- | ---------------------------------------- | -------------------------------------- | | `after_create` | `task.py create` completes | Create linked issue in project tracker | | `after_start` | `task.py start` sets the current task | Update issue status to "In Progress" | | `after_finish` | `task.py finish` clears the current task | Notify team, trigger review | | `after_archive` | `task.py archive` moves the task | Mark issue as "Done" | #### Environment Variables Each hook receives: | Variable | Value | | ---------------- | --------------------------------------- | | `TASK_JSON_PATH` | Absolute path to the task's `task.json` | All other environment variables from the parent process are inherited. #### Execution Behavior * **Working directory**: Repository root * **Shell**: Commands run through the system shell (`shell=True`) * **Failures don't block**: A failing hook prints a `[WARN]` message to stderr but does not prevent the task operation from completing * **Sequential**: Multiple hooks per event execute in list order; a failure in one does not skip the rest * **stdout captured**: Hook stdout is not displayed to the user — use stderr for diagnostic output The `after_archive` hook receives `TASK_JSON_PATH` pointing to the **archived** location (e.g., `.trellis/tasks/archive/2026-03/task-name/task.json`), not the original path. #### Example: Linear Sync Hook Trellis ships with an example hook at `.trellis/scripts/hooks/linear_sync.py` that syncs task lifecycle events to [Linear](https://linear.app). **What it does**: | Action | Trigger | Effect | | --------- | --------------- | ------------------------------------------------------------------------- | | `create` | `after_create` | Creates a Linear issue from task.json (title, priority, assignee, parent) | | `start` | `after_start` | Updates the linked issue to "In Progress" | | `archive` | `after_archive` | Updates the linked issue to "Done" | | `sync` | Manual | Pushes `prd.md` content to the Linear issue description | **Prerequisites**: 1. Install the [`linearis`](https://www.npmjs.com/package/linearis) CLI and set `LINEAR_API_KEY` 2. Create `.trellis/hooks.local.json` (gitignored) with your team config: ```json theme={null} { "linear": { "team": "ENG", "project": "My Project", "assignees": { "alice": "linear-user-id-for-alice" } } } ``` The hook writes the Linear issue identifier back to `task.json` under `meta.linear_issue` (e.g., `"ENG-123"`), making subsequent events idempotent. *** # Writing Specs Source: https://docs.trytrellis.app/guide/ch07-writing-specs ## Writing Specs ### 7.1 Spec Directory Structure and Layering ``` .trellis/spec/ ├── frontend/ # Frontend specs │ ├── index.md # Index: lists all specs and their status │ ├── component-guidelines.md # Component specs │ ├── hook-guidelines.md # Hook specs │ ├── state-management.md # State management │ ├── type-safety.md # Type safety │ ├── quality-guidelines.md # Quality guidelines │ └── directory-structure.md # Directory structure │ ├── backend/ # Backend specs │ ├── index.md │ ├── database-guidelines.md │ ├── error-handling.md │ ├── logging-guidelines.md │ ├── quality-guidelines.md │ └── directory-structure.md │ └── guides/ # Thinking guides ├── index.md ├── cross-layer-thinking-guide.md └── code-reuse-thinking-guide.md ``` **Layering principles**: * `index.md` is the entry point, listing all spec files and their status * Each file focuses on a single topic, 200-500 lines * Each section 20-50 lines * Write in English (technical terms are naturally English); Chinese projects may use Chinese ### 7.2 From Empty Templates to Complete Specs `trellis init` generates empty templates marked "(To be filled by the team)". Here's how to fill them: **Step 1**: Extract patterns from actual code ```bash theme={null} # See how existing code is organized ls src/components/ # Component structure ls src/services/ # Service structure ``` **Step 2**: Write down your conventions ```markdown theme={null} # Component Guidelines ## File Structure - One component per file - Use PascalCase for filenames: `UserProfile.tsx` - Co-locate styles: `UserProfile.module.css` - Co-locate tests: `UserProfile.test.tsx` ## Patterns ### Required - Functional components + hooks (no class components) - TypeScript with explicit Props interface - `export default` for page components, named export for shared ### Forbidden - No `any` type in Props - No inline styles (use CSS Modules) - No direct DOM manipulation ``` **Step 3**: Add code examples ````markdown theme={null} ### Good Example ```tsx interface UserProfileProps { userId: string; onUpdate: (user: User) => void; } export function UserProfile({ userId, onUpdate }: UserProfileProps) { // ... } ```` ### Bad Example ```tsx theme={null} // Don't: no Props interface, using any export default function UserProfile(props: any) { // ... } ``` ```` **Step 4**: Update index.md status ```markdown | Guideline | File | Status | |-----------|------|--------| | Component Guidelines | component-guidelines.md | **Filled** | | Hook Guidelines | hook-guidelines.md | To fill | ```` ### 7.3 Good Specs vs Bad Specs **Good specs** (specific, with code, with reasoning): ````markdown theme={null} ### Database Query Pattern **Always use parameterized queries** to prevent SQL injection. ```sql -- Good SELECT * FROM users WHERE id = $1 -- Bad SELECT * FROM users WHERE id = '${userId}' ```` **Why**: Parameterized queries are automatically escaped by the database driver. ```` **Bad specs** (too vague, no code, no reasoning): ```markdown ### Database - Use good query patterns - Be careful with SQL - Follow best practices ```` **Over-specified specs** (too granular, stifles creativity): ```markdown theme={null} ### Variable Naming - All boolean variables must start with `is` or `has` - All arrays must end with `List` - All functions must be less than 20 lines - All files must be less than 200 lines ``` ### 7.4 Bootstrap Guided Initial Fill `trellis init` automatically creates a bootstrap guide task (`00-bootstrap-guidelines`). The AI detects it during the first `/start` and guides you through filling in the blank spec files. During this guided task, the AI analyzes your codebase, extracts existing patterns, and auto-fills spec templates. ### 7.5 Continuous Spec Evolution Specs are not written once and forgotten; they evolve continuously with development: | Trigger | Update Frequency | Example | | ----------------------------- | ---------------- | ---------------------------- | | Fixed a non-obvious bug | Immediately | Add to "Common Mistakes" | | Discovered a better practice | Same day | Add to "Patterns" | | Team agrees on new convention | Same day | Add to "Conventions" | | Routine improvements | Weekly | Refine wording, add examples | **Evolution flywheel**: ``` Develop → Discover pattern/issue → Manually update Spec file → git push ↓ Entire team benefits ← Hook auto-injects ← Next session auto-loads ← git pull ``` *** # Real-World Scenarios Source: https://docs.trytrellis.app/guide/ch08-real-world ## Real-World Scenarios ### 8.1 Simple Feature Development (Single Session) **Task**: Add user login feature ```bash theme={null} # 1. Open terminal (Hook auto-injects context, can skip /start) # 2. Describe the task "Add user login feature" # 3. AI works automatically... # Hook injects specs → creates task → invokes Implement Agent → Check Agent → Ralph Loop verification # 4. Test pnpm lint && pnpm typecheck && pnpm test # 5. Commit git add . git commit -m "feat(auth): add user login feature" # 6. Record session /record-session ``` ```bash theme={null} # 1. Start session (required) /start # 2. Describe the task "Add user login feature" # 3. AI works automatically... # Reads specs → implements feature # 4. Manually check code quality /trellis-check-backend # 5. Test pnpm lint && pnpm typecheck && pnpm test # 6. Commit git add . git commit -m "feat(auth): add user login feature" # 7. Record session /trellis-record-session ``` ### 8.2 Complex Parallel Development (Multi-Agent Worktree) This scenario is Claude Code only. Cursor, Codex, and other platforms do not support Multi-Agent Pipeline. **Task**: Develop three independent features in parallel ```bash theme={null} # 1. Start parallel mode /parallel # 2. Describe requirements "I need to develop three features in parallel: 1. User profile page 2. Email notification system 3. Data export feature" # 3. AI automatically creates a worktree for each feature and starts Agents # 4. Monitor progress ./.trellis/scripts/multi-agent/status.py # Task 1: user-profile ✅ Complete (PR #123) # Task 2: email-notify 🔄 In Progress (Check phase) # Task 3: data-export 🔄 In Progress (Implement phase) # 5. Review and merge PRs # 6. Clean up worktrees ./.trellis/scripts/multi-agent/cleanup.py user-profile ``` ### 8.3 Cross-Layer Feature Development **Task**: Add product review feature (database + API + frontend) ```bash theme={null} # 1. Open terminal (Hook auto-injects) # 2. Describe the task "Add product review feature, requiring database, API, and frontend" # 3. AI automatically reads the cross-layer thinking guide # mapping: UI → API → DB → API → UI # 4. AI develops layer by layer # Phase 1: Database (comments table) # Phase 2: Backend API (POST /api/comments) # Phase 3: Frontend (CommentForm component) # 5. Cross-layer check (Hook auto-triggers, or run manually) /check-cross-layer ``` ```bash theme={null} # 1. Start (required) /start # 2. Load backend + frontend specs /trellis-before-backend-dev /trellis-before-frontend-dev # 3. Describe the task "Add product review feature, requiring database, API, and frontend" # 4. AI develops layer by layer... # 5. Manual cross-layer check /trellis-check-cross-layer ``` ```bash theme={null} # ✅ Database Layer: comments table created # ✅ API Layer: POST /api/comments endpoint # ✅ UI Layer: CommentForm component # ✅ Data Flow: UI → API → DB ✓ # 6. Test, commit, record ``` ### 8.4 Team Collaboration The core mechanisms for team collaboration (Spec sharing, task assignment) are platform-agnostic. Team members on different platforms can share the same Spec library. ```bash theme={null} # Alice develops and documents specs (Claude Code example, Cursor uses /start) trellis init -u alice /start # ... develop authentication system ... # Manually write auth best practices into specs git add .trellis/spec/ git commit -m "docs: add auth guidelines" git push # Bob pulls and automatically benefits git pull trellis init -u bob /start "Add permission management" # AI auto-reads Alice's auth guidelines # Bob's code automatically follows Alice's specs ``` ### 8.5 Bug Debugging with break-loop ```bash theme={null} # 1. Start /start # 2. Fix the bug "Users can't log in under certain conditions" # 3. AI debugs and fixes... # 4. Deep analysis /break-loop # AI output: # Root Cause: B - Cross-layer Contract Violation # Token format sent by frontend doesn't match backend expectations # # Prevention: # - Update spec: define token format contract # - Add type constraint: shared Token interface # - Add test: token format validation # 5. Manually update specs # Write token format contract into .trellis/spec/ files ``` ### 8.6 Spec Iteration Flywheel ```bash theme={null} # Discover a pattern # AI discovers during development: all API errors should return a uniform format # { error: string, code: number, details?: any } # Manually update specs # Write this pattern into .trellis/spec/backend/error-handling.md # Next time anyone does API development # Hook auto-injects error-handling.md # AI automatically follows the uniform error format # → All API errors are consistently formatted ``` ### 8.7 Building a New Project from Scratch ```bash theme={null} # 1. Create project mkdir my-app && cd my-app git init # 2. Install Trellis npm install -g @mindfoldhq/trellis@latest trellis init -u your-name # 3. trellis init has auto-created the bootstrap guide task (00-bootstrap-guidelines) /start # AI auto-detects the bootstrap task, analyzes your codebase, and helps fill in specs # 4. Manually supplement core specs # Edit .trellis/spec/backend/index.md, etc. # Write down your tech stack choices, coding conventions, directory structure # 5. Start developing /start "Set up the project foundation" ``` # Custom Slash Commands Source: https://docs.trytrellis.app/guide/ch09-custom-commands ## Custom Slash Commands ### 9.1 Command File Format and Location | Platform | Location | Naming Convention | | ----------- | ------------------------------------ | --------------------- | | Claude Code | `.claude/commands/trellis/{name}.md` | Invoked as: `/{name}` | | Cursor | `.cursor/commands/{name}.md` | Invoked as: `/{name}` | Command files are simply Markdown files whose content is injected as a prompt to the AI. ### 9.2 Using `/create-command` to Generate Commands ``` /create-command ``` The AI will ask: 1. Command name 2. Command purpose 3. Files to read 4. Execution steps Then automatically generates dual-IDE command files. ### 9.3 Command Design Best Practices **Good command structure**: ````markdown theme={null} # Command Name Brief description of what this command does. --- ## Operation Types | Marker | Meaning | Executor | |--------|---------|----------| | `[AI]` | AI executes | You (AI) | | `[USER]` | User executes | User | --- ## Step 1: Read Context `[AI]` ```bash cat .trellis/spec/relevant-spec.md ```` ## Step 2: Analyze `[AI]` Describe what to analyze... ## Step 3: Report Output format... ```` **Principles**: - Each command does one thing - Clearly mark which steps are AI's and which are the user's - List files that need to be read - Define output format ### 9.4 Example: Creating a `/deploy-check` Command `.claude/commands/deploy-check.md`: ```markdown # Deploy Check Pre-deployment verification checklist. --- ## Step 1: Read deployment config `[AI]` ```bash cat deploy.config.js cat .env.production ```` ## Step 2: Verify `[AI]` Check these items: * [ ] All tests pass * [ ] No TODO comments in production code * [ ] Environment variables are set * [ ] Database migrations are up to date * [ ] API endpoints are documented ## Step 3: Report Output a deployment readiness report. ``` --- ``` # Custom Agents Source: https://docs.trytrellis.app/guide/ch10-custom-agents ## Custom Agents ### 10.1 Agent Definition File Format Agent definition files are stored at `.claude/agents/{name}.md`, using YAML front matter: ```markdown theme={null} --- name: agent-name description: | One-line description of what this agent does. tools: Read, Write, Edit, Bash, Glob, Grep model: opus --- # Agent Name Agent instructions go here... ``` ### 10.2 Available Tools and Model Selection **Available tools**: | Tool | Description | | ------------------------------------- | ------------------ | | Read | Read files | | Write | Write files | | Edit | Edit files | | Bash | Execute commands | | Glob | File search | | Grep | Content search | | Task | Invoke sub-Agents | | Skill | Invoke Skills | | mcp\_\_exa\_\_web\_search\_exa | Web search | | mcp\_\_exa\_\_get\_code\_context\_exa | Code search | | mcp\_\_chrome-devtools\_\_\* | Browser automation | **Model selection**: | Model | Use Case | | -------- | --------------------------------------------------- | | `opus` | Complex tasks (implementation, checking, debugging) | | `sonnet` | Medium tasks | | `haiku` | Simple, fast tasks | ### 10.3 Modifying Existing Agents For example, adding timeout control to the Check Agent: ```markdown theme={null} --- name: check description: | Code quality check expert with 10-minute timeout. tools: Read, Write, Edit, Bash, Glob, Grep model: opus timeout: 600000 --- ``` ### 10.4 Creating a New Agent ````markdown theme={null} --- name: test description: | Test writing expert. Writes comprehensive tests for code changes. tools: Read, Write, Edit, Bash, Glob, Grep model: opus --- # Test Agent You are the Test Agent in the Trellis workflow. ## Core Responsibilities 1. **Analyze code changes** - Understand what was modified 2. **Write unit tests** - Cover new functionality 3. **Write integration tests** - Test cross-module interactions 4. **Run tests** - Verify all tests pass ## Workflow ### Step 1: Get Changes ```bash git diff --name-only ```` ### Step 2: Identify Testable Code For each changed file, identify functions/components that need tests. ### Step 3: Write Tests Follow existing test patterns in the codebase. ### Step 4: Run Tests ```bash theme={null} pnpm test ``` ``` --- ``` # Custom Hooks Source: https://docs.trytrellis.app/guide/ch11-custom-hooks ## Custom Hooks ### 11.1 Hook Types | Hook Type | Trigger Timing | Purpose | | -------------- | ---------------------- | ----------------------------------------------- | | `SessionStart` | New session starts | Load context, initialize environment | | `PreToolUse` | Before tool invocation | Intercept and modify parameters, inject context | | `PostToolUse` | After tool invocation | Log activity, trigger follow-up actions | | `SubagentStop` | When sub-Agent stops | Verify output quality, control loops | ### 11.2 settings.json Configuration Format Configure Hooks in `.claude/settings.json`: ```json theme={null} { "hooks": { "SessionStart": [ { "matcher": "startup", "hooks": [ { "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.py\"", "timeout": 10 } ] } ], "PreToolUse": [ { "matcher": "Task", "hooks": [ { "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/inject-subagent-context.py\"", "timeout": 30 } ] } ], "SubagentStop": [ { "matcher": "check", "hooks": [ { "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/ralph-loop.py\"", "timeout": 10 } ] } ] } } ``` **Configuration notes**: * Each event type is an array containing `{ matcher, hooks }` objects * `matcher`: Matching rule (`"startup"` matches session start, `"Task"` matches Task tool calls, `"check"` matches check Agent stop) * `hooks`: Array of Hooks to execute when matched, executed in order * `$CLAUDE_PROJECT_DIR`: Automatically expanded by Claude Code to the project root * `timeout`: Timeout in seconds; Hook is skipped if exceeded ### 11.3 Existing Hook Source Code Walkthrough #### session-start.py — Context Loading **Trigger**: `SessionStart` **Functionality**: * Reads `.trellis/.developer` to get developer identity * Reads `workflow.md` to get workflow guide * Reads `workspace/{name}/index.md` to get session history * Reads `git log` to get recent commits * Reads the active task list **Output**: Injects all context as a system message at the beginning of the session. #### inject-subagent-context.py — Spec Injection Engine **Trigger**: `PreToolUse`, matching `Task` tool calls **Functionality** (see section 4.3 for details): * Intercepts Task tool calls * Reads the corresponding JSONL file based on subagent\_type * Reads all files referenced in the JSONL * Builds the complete Agent prompt (specs + requirements + original instructions) * Replaces the original prompt * Updates current\_phase in task.json **Key design decisions**: * Dispatch Agent does not read specs, keeping it simple * Each Agent receives full context, no resume needed * `[finish]` marker triggers lightweight context injection #### ralph-loop.py — Quality Loop **Trigger**: `SubagentStop`, matching `check` Agent **Functionality** (see section 4.4 for details): * Checks verify commands or completion markers * Pass allows stop, failure blocks stop * Maximum 5 iterations * State tracked in `.ralph-state.json` ### 11.4 Writing Custom Hooks Hooks receive JSON input via stdin and output JSON results via stdout. **Input format** (PreToolUse example): ```json theme={null} { "hook_event_name": "PreToolUse", "tool_name": "Task", "tool_input": { "subagent_type": "implement", "prompt": "..." }, "cwd": "/path/to/project" } ``` **Output format**: ```json theme={null} { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "allow", "updatedInput": { "subagent_type": "implement", "prompt": "modified prompt..." } } } ``` ### 11.5 Example: Adding an Auto-Test Hook `.claude/hooks/auto-test.py`: ```python theme={null} #!/usr/bin/env python3 """Run tests automatically after Edit tool completes.""" import json import os import subprocess import sys def main(): input_data = json.load(sys.stdin) hook_event = input_data.get("hook_event_name", "") tool_name = input_data.get("tool_name", "") # Only trigger after Edit tool if hook_event != "PostToolUse" or tool_name != "Edit": sys.exit(0) # Get the edited file file_path = input_data.get("tool_input", {}).get("file_path", "") # Only for .ts/.tsx files if not file_path.endswith((".ts", ".tsx")): sys.exit(0) # Run typecheck result = subprocess.run( ["pnpm", "typecheck"], capture_output=True, timeout=30 ) if result.returncode != 0: output = { "hookSpecificOutput": { "message": f"TypeCheck failed after editing {file_path}:\n{result.stderr.decode()}" } } print(json.dumps(output)) sys.exit(0) if __name__ == "__main__": main() ``` Register it in `settings.json`: ```json theme={null} { "hooks": { "PostToolUse": [ { "matcher": "Edit", "type": "command", "command": "python3 .claude/hooks/auto-test.py" } ] } } ``` *** # Custom Skills Source: https://docs.trytrellis.app/guide/ch12-custom-skills ## Custom Skills ### 12.1 What is a Skill | Concept | Command | Agent | Skill | | ----------------- | -------------------------------- | ------------------------------ | ----------------------------- | | **Purpose** | User-triggered specific workflow | System-invoked autonomous unit | Reusable AI capability module | | **Trigger** | `/xxx` | `Task(subagent_type)` | Skill system auto-matches | | **Cross-project** | No | No | Yes (npm publish) | | **Granularity** | Workflow-level | Role-level | Capability-level | ### 12.2 SKILL.md File Format Skill files are stored in the `.claude/skills/` or `.agents/skills/` directory: ```markdown theme={null} # Skill Name ## Trigger When the user asks to [describe trigger condition]... ## Instructions [Detailed instructions for the AI] ## Tools Required - Tool1 - Tool2 ## Examples ### Example 1 User: "..." AI: [Expected behavior] ``` ### 12.3 Creating Skills with skill-creator ``` /create-command # Select Skill type ``` Or use the skill-creator Skill directly: ``` I want to create a new Skill for auto-generating API documentation ``` ### 12.4 Integrating External Skills ``` /integrate-skill ``` The AI will: 1. Identify the Skill source 2. Analyze the Skill's functionality 3. Create integration docs in `spec/guides/` 4. Create a wrapper command in `.claude/commands/trellis/` 5. Generate a unified `/use-[skill-name]` entry point ### 12.5 Sharing Skills If you want to share a Skill, you can publish it via npm or share it directly on GitHub. Other users can integrate your Skill into their projects via the `/integrate-skill` command. *** # Multi-Platform and Team Configuration Source: https://docs.trytrellis.app/guide/ch13-multi-platform ## Multi-Platform and Team Configuration ### 13.1 Claude Code Full Experience Claude Code is Trellis's primary platform, with the most complete automation capabilities. Three core Hooks form the automation loop: | Hook | Trigger Timing | Capability | | ---------------------------- | -------------------- | ----------------------------------------------- | | `session-start.py` | SessionStart | Auto-injects context (identity, history, tasks) | | `inject-subagent-context.py` | PreToolUse (Task) | Auto-injects precise Spec context for Agents | | `ralph-loop.py` | SubagentStop (check) | Auto-verifies code quality (Ralph Loop) | **Claude Code exclusive features**: * Hook auto-injection — start working immediately upon opening terminal, no manual `/start` needed * Multi-Agent Pipeline — `/parallel` orchestrates multiple worktree Agents in parallel * Ralph Loop — automatic quality gate, Check Agent auto-retries on failure * Agent system — 6 specialized Agents (dispatch, plan, implement, check, debug, research) ### 13.2 Cursor Integration `trellis init` automatically generates Trellis command files under `.cursor/commands/`: | Claude Code Command | Cursor Equivalent | | ---------------------------- | ---------------------------- | | `/trellis:start` | `/trellis-start` | | `/trellis:before-dev` | `/trellis-before-dev` | | `/trellis:brainstorm` | `/trellis-brainstorm` | | `/trellis:check` | `/trellis-check` | | `/trellis:check-cross-layer` | `/trellis-check-cross-layer` | | `/trellis:finish-work` | `/trellis-finish-work` | | `/trellis:break-loop` | `/trellis-break-loop` | | `/trellis:create-command` | `/trellis-create-command` | | `/trellis:integrate-skill` | `/trellis-integrate-skill` | | `/trellis:onboard` | `/trellis-onboard` | | `/trellis:record-session` | `/trellis-record-session` | | `/trellis:update-spec` | `/trellis-update-spec` | **Differences from Claude Code**: * Files located at `.cursor/commands/trellis-{name}.md` * Cursor has 12 commands (no `/parallel`, as Cursor doesn't support Multi-Agent Pipeline) * No Hook support — spec injection requires manual command invocation * No Agent system — all work happens in the main conversation * No Ralph Loop — check commands must be run manually **Recommended workflow for Cursor users**: ```bash theme={null} # 1. Start session (required, replaces Hook auto-injection) /trellis-start # 2. Load relevant specs (recommended, replaces PreToolUse Hook) /trellis-before-dev # 3. Describe task, AI develops... # 4. Manually check code quality (replaces Ralph Loop) /trellis-check /trellis-check-cross-layer # Cross-layer check # 5. Finish checklist /trellis-finish-work ``` ### 13.3 Codex Integration ```bash theme={null} trellis init --codex -u your-name ``` Generates the following configuration: * **`AGENTS.md`** (root directory) — Codex entry file, provides base project context (similar to `CLAUDE.md`) * **`.agents/skills/`** — Shared Agent Skills directory ([agentskills.io](https://agentskills.io) open standard, used by Codex, Kimi CLI, Amp, Cline, and others) * **`.codex/config.toml`** — Project-scoped Codex configuration * **`.codex/agents/`** — Custom Codex agents (`implement.toml`, `research.toml`, `check.toml`) * **`.codex/skills/`** — Codex-specific skills (e.g. `parallel` for multi-agent pipelines) * **`.codex/hooks/session-start.py`** + **`.codex/hooks.json`** — SessionStart hook that injects Trellis workflow, guidelines, and task context into Codex sessions As of Codex CLI v0.116.0 (2026-03-24), hooks are an experimental feature that requires manual opt-in. Add this to `~/.codex/config.toml`: ```toml theme={null} [features] multi_agent = true codex_hooks = true ``` This requirement may be removed in a future Codex release when hooks become stable. ### 13.4 Kilo Code Integration [Kilo Code](https://kilo.ai) is an open-source (Apache 2.0) AI coding Agent platform, available as a VS Code extension, JetBrains plugin, and CLI, with 750K+ users. ```bash theme={null} trellis init --kilo -u your-name ``` Generates configuration under the `.kilocode/` directory: **What Trellis generates for Kilo**: `trellis init --kilo` generates workflow files under `.kilocode/workflows/`. These are Kilo's equivalent of slash commands — invoked in chat as `/start.md`, `/check.md`, etc. | Trellis / Claude Code | Kilo Code (generated by Trellis) | Description | | ----------------------- | -------------------------------- | ---------------------------------------------- | | `.claude/commands/*.md` | `.kilocode/workflows/*.md` | Workflow commands invoked as `/start.md`, etc. | **Generated directory structure**: ``` project/ ├── .kilocode/ │ └── workflows/ # Commands (equivalent to slash commands) │ ├── start.md # /start.md — session init │ ├── brainstorm.md # /brainstorm.md │ ├── before-dev.md # /before-dev.md │ ├── check.md # /check.md │ ├── check-cross-layer.md # /check-cross-layer.md │ ├── finish-work.md # /finish-work.md │ ├── break-loop.md # /break-loop.md │ ├── create-command.md # /create-command.md │ ├── integrate-skill.md # /integrate-skill.md │ ├── onboard.md # /onboard.md │ ├── parallel.md # /parallel.md │ ├── record-session.md # /record-session.md │ └── update-spec.md # /update-spec.md ``` Kilo also supports `rules/`, `rules-code/`, `rules-architect/`, `skills/`, `launchConfig.json`, and `mcp.json` — but these are **not generated by Trellis**. You can create them manually if needed. See [Kilo Code documentation](https://kilo.ai) for details. **Recommended workflow for Kilo users**: ```bash theme={null} # 1. Run the start workflow for full context /start.md # 2. Switch to Orchestrator mode for complex tasks # Kilo auto-decomposes tasks and assigns to Code/Architect modes # 3. Describe task, AI develops... # 4. Run check workflow /check.md # 5. Finish /finish-work.md ``` Kilo's Orchestrator Mode shares a similar philosophy with Trellis's Multi-Agent Pipeline, but the implementation differs: Trellis uses git worktree physical isolation + Hook orchestration, while Kilo uses built-in mode switching + independent conversation context. The two are complementary — Trellis's Spec management and Task system provide structured project context for Kilo. ### 13.5 Kiro Integration [Kiro](https://kiro.dev) is an AI IDE by Amazon, built on Code OSS (VS Code open-source core), focused on **Spec-Driven Development**. It supports IDE, CLI, and Autonomous Agent modes. ```bash theme={null} trellis init --kiro -u your-name ``` **What Trellis generates for Kiro**: `trellis init --kiro` generates skill files under `.kiro/skills/`. Each skill is a `SKILL.md` file with YAML frontmatter, following the [Agent Skills open standard](https://agentskills.io). | Trellis / Claude Code | Kiro (generated by Trellis) | Description | | ----------------------- | --------------------------- | ------------------------------- | | `.claude/commands/*.md` | `.kiro/skills/*/SKILL.md` | 12 skills with YAML frontmatter | **Generated directory structure**: ``` project/ ├── .kiro/ │ └── skills/ # Agent Skills (YAML frontmatter + instructions) │ ├── start/SKILL.md │ ├── brainstorm/SKILL.md │ ├── before-dev/SKILL.md │ ├── check/SKILL.md │ ├── check-cross-layer/SKILL.md │ ├── finish-work/SKILL.md │ ├── break-loop/SKILL.md │ ├── create-command/SKILL.md │ ├── integrate-skill/SKILL.md │ ├── onboard/SKILL.md │ ├── record-session/SKILL.md │ └── update-spec/SKILL.md ``` Kiro also supports `steering/`, `hooks/`, `specs/`, `prompts/`, `agents/`, and `settings/` directories — but these are **not generated by Trellis**. You can create them manually if needed. See [Kiro documentation](https://kiro.dev) for details. **Recommended workflow for Kiro users**: ```bash theme={null} # 1. Use the start skill to initialize session context # 2. Describe task, AI develops... # 3. Use the check skill to verify code quality # 4. Use the finish-work skill for pre-commit checklist # 5. Commit code when done ``` ### 13.5b CodeBuddy Integration [CodeBuddy](https://copilot.tencent.com/) is Tencent Cloud's AI coding assistant, supporting IDE and CLI forms with MCP extensibility. ```bash theme={null} trellis init --codebuddy -u your-name ``` **What Trellis generates for CodeBuddy**: `trellis init --codebuddy` generates command files under `.codebuddy/commands/trellis/`. These are invoked in chat as `/trellis:start`, `/trellis:check`, etc. | Trellis / Claude Code | CodeBuddy (generated by Trellis) | Description | | ----------------------- | ---------------------------------- | -------------------------------------- | | `.claude/commands/*.md` | `.codebuddy/commands/trellis/*.md` | 12 slash commands in Trellis namespace | **Generated directory structure**: ``` project/ ├── .codebuddy/ │ └── commands/ # Slash commands │ └── trellis/ # Trellis namespace │ ├── start.md # /trellis:start │ ├── brainstorm.md # /trellis:brainstorm │ ├── before-dev.md # /trellis:before-dev │ ├── check.md # /trellis:check │ ├── check-cross-layer.md # /trellis:check-cross-layer │ ├── finish-work.md # /trellis:finish-work │ ├── break-loop.md # /trellis:break-loop │ ├── create-command.md # /trellis:create-command │ ├── integrate-skill.md # /trellis:integrate-skill │ ├── onboard.md # /trellis:onboard │ ├── record-session.md # /trellis:record-session │ └── update-spec.md # /trellis:update-spec ``` CodeBuddy also supports `.rules/`, `agents/`, `settings.json`, and hooks — but these are **not generated by Trellis**. You can create them manually if needed. See [CodeBuddy documentation](https://copilot.tencent.com/) for details. **Differences from Claude Code**: * Files located at `.codebuddy/commands/trellis/{name}.md` * CodeBuddy has 12 commands (no `/parallel`, as CodeBuddy doesn't support Multi-Agent Pipeline) * No Hook support at Trellis level — spec injection requires manual command invocation * No Agent system integration — all work happens in the main conversation **Recommended workflow for CodeBuddy users**: ```bash theme={null} # 1. Start session (required) /trellis:start # 2. Load relevant specs /trellis:before-dev # 3. Describe task, AI develops... # 4. Check code quality /trellis:check /trellis:check-cross-layer # 5. Finish checklist /trellis:finish-work ``` ### 13.6 Operating System Compatibility | OS | Support Status | Notes | | ----------- | -------------- | --------------------------------------------------------- | | **macOS** | ✅ Full support | Primary development platform, all features verified | | **Linux** | ✅ Full support | All features verified | | **Windows** | ✅ Full support | All scripts migrated to Python, natively supports Windows | **Cross-platform notes**: | Consideration | Details | | --------------- | ---------------------------------------------------------------------------------------------- | | Python scripts | Scripts under `.trellis/scripts/` are Python, requiring Python 3.8+, cross-platform compatible | | Python Hooks | Hook scripts under `.claude/hooks/` require Python 3.8+, cross-platform compatible | | Path separators | Trellis internally uses `/`, Python handles path conversion automatically | | Git worktree | Multi-Agent Pipeline relies on git worktree, supported on all platforms | ### 13.7 Multi-Developer Collaboration **Non-conflicting parts** (per-developer isolation): * `workspace/{name}/` — each developer has their own directory * `.developer` — gitignored, per-developer * Parallel task worktrees — physically isolated **Potentially conflicting parts** (require coordination): * `spec/` — multiple people may modify the same spec simultaneously * `tasks/` — multiple people may operate on the same task **Best practices**: * Spec changes go through PR review * Task assignments are explicit (`--assignee` parameter) * Important spec changes are discussed in team meetings ### 13.8 Complete worktree.yaml Configuration ```yaml theme={null} # Worktree Configuration for Multi-Agent Pipeline #─────────────────────────────────────────────────── # Paths #─────────────────────────────────────────────────── # Worktree storage directory (relative to project root) worktree_dir: ../trellis-worktrees #─────────────────────────────────────────────────── # Files to Copy #─────────────────────────────────────────────────── # Files that need independent copies in each worktree # These files contain sensitive info or need independent config copy: - .env # Environment variables - .env.local # Local environment variables - .trellis/.developer # Developer identity #─────────────────────────────────────────────────── # Post-Create Hooks #─────────────────────────────────────────────────── # Commands to run after creating a worktree # Executed sequentially in the worktree directory; aborts on failure post_create: - pnpm install --frozen-lockfile # - npm install # - yarn install --frozen-lockfile #─────────────────────────────────────────────────── # Check Agent Verification (Ralph Loop) #─────────────────────────────────────────────────── # Commands to verify code quality # When configured, Ralph Loop runs these — all must pass # Without configuration, falls back to completion markers mode verify: - pnpm lint - pnpm typecheck # - pnpm test ``` ### 13.9 `trellis update` and Version Management ```bash theme={null} # Check current version cat .trellis/.version # Update to latest version trellis update # Preview updates (dry run) trellis update --dry-run # Force overwrite all files trellis update -f # Skip all changed files trellis update -s ``` **Template hash mechanism**: `.trellis/.template-hashes.json` stores the SHA-256 hash of each template file. During `trellis update`: 1. Compute local file hashes 2. Compare with recorded template hashes 3. If they match — file not modified by user — safe to update 4. If they differ — file was modified by user — prompt for conflict resolution 5. User chooses: overwrite / skip / merge *** # Resources & Acknowledgments Source: https://docs.trytrellis.app/guide/resources ## Resource Links * **GitHub**: [https://github.com/mindfold-ai/Trellis](https://github.com/mindfold-ai/Trellis) * **Documentation**: [https://docs.trytrellis.app/zh](https://docs.trytrellis.app/zh) * **Discord**: [https://discord.com/invite/tWcCZ3aRHc](https://discord.com/invite/tWcCZ3aRHc) * **npm**: [https://www.npmjs.com/package/@mindfoldhq/trellis](https://www.npmjs.com/package/@mindfoldhq/trellis) * **Design Philosophy**: [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) *** ## Acknowledgments Thanks to the following community members for reviewing and contributing to this document: * **Murphy233666** — Platform detail corrections (OpenCode command prefix, Kiro invocation methods, etc.) * **jsfaint** — Technical accuracy review * **Joel (Azu)** — Cursor Hook status clarification, OpenCode hook capability confirmation # Trellis Source: https://docs.trytrellis.app/index All-in-one AI framework & toolkit for Claude Code & Cursor ## What is Trellis? AI's capabilities grow like vines — full of vitality but spreading everywhere. Trellis is scaffolding for AI, guiding it along the path of your conventions. ## Why Trellis? | Feature | Problem Solved | | ----------------------------- | ------------------------------------------------------------------------------------------- | | **Auto-Injection** | Required specs and workflows auto-inject into every conversation. Write once, apply forever | | **Auto-updated Spec Library** | Best practices live in auto-updated spec files. The more you use it, the better it gets | | **Parallel Sessions** | Run multiple agents in tandem - each in its own worktree | | **Team Sync** | Share specs across your team. One person's best practice benefits everyone | | **Session Persistence** | Work traces persist in your repo. AI remembers project context across sessions | Install Trellis and set up your first project in 5 minutes. Understand specs, tasks, hooks, and workspaces. Complete reference for all 13 slash commands. From bug fixes to full-stack development. # Showcase Source: https://docs.trytrellis.app/showcase/index macOS voice input app, built in 1 day. Shows the full workflow: spec organization, task breakdown, parallel development. Community fork optimized for Cursor with Chinese subagents and MCP integration. *** ## Add your project 1. Fork the [docs repo](https://github.com/mindfold-ai/docs) 2. Copy `showcase/template.mdx` and `zh/showcase/template.mdx` to create bilingual pages 3. Add page paths to both EN and ZH showcase pages arrays in `docs.json` 4. Add Card to both `showcase/index.mdx` and `zh/showcase/index.mdx` 5. Open a PR Use `/contribute` skill in Claude Code for assistance. # open-typeless Source: https://docs.trytrellis.app/showcase/open-typeless # About A macOS voice input app, built with Trellis in 1 day. [![open-typeless](https://opengraph.githubassets.com/1/mindfold-ai/open-typeless)](https://github.com/mindfold-ai/open-typeless) ## How it was built Copied specs from an existing Electron project, AI filtered and organized them into 3 task batches. Used `/trellis:parallel` to launch 3 worktree agents for parallel development, PRs created automatically upon completion. # Workflow Demo Source: https://docs.trytrellis.app/showcase/terminal-demo See the full Trellis workflow in action — from brainstorm to ship
❯ /trellis:start
● Loaded — workflow, 3 active tasks, branch feat/v0.4.0-beta
● What would you like to work on?
❯ Add Gemini CLI support, similar to how Cursor is integrated
● Bash (task.py create "Gemini CLI support" --slug gemini-cli)
▶ research (Find platform integration specs and code patterns)
└ Initializing...
└ Done (36 tool uses · 86.5k tokens · 2m 25s) ✓
● Bash (task.py add-context ... platform-integration.md, cursor.ts, ai-tools.ts)
└ 6 spec files added to implement.jsonl
● Bash (task.py start ...) — hooks will inject context into agents
▶ implement (Implement Gemini CLI platform)
└ Writing src/configurators/gemini.ts...
└ Done (99 tool uses · 162.5k tokens · 12m 3s) ✓
● TypeCheck ✓ · Lint ✓ · Tests: 337/337 ✓
▶ check (Review implementation against code-specs)
└ Reading diff... 14 files changed
└ Found 1 issue: missing EXCLUDE\_PATTERNS entry
└ Fixed automatically ✓
❯ /trellis:update-spec
● Read (.trellis/spec/backend/platform-integration.md)
● Update (platform-integration.md) — added Gemini CLI conventions
❯ /trellis:record-session
● Bash (task.py archive gemini-cli)
● Bash (add\_session.py --title "feat: Gemini CLI support" --commit "ec6114a")
└ Task archived. Session recorded to journal-4.md.
❯

Session loaded

AI reads your project context — workflow rules, active tasks, git status, and recent journal entries.

Natural language input

Describe your feature in plain language. Trellis creates a tracked task with a structured PRD.

Research & configure

Research Agent finds relevant specs and code patterns. Context files configured in jsonl — hooks auto-inject them into agents.

Implement

Agent writes code across 5 layers following project conventions. 99 tool calls, all 337 tests pass on first try.

Quality check

Check Agent reviews every changed file against code-specs. Issues found and fixed automatically.

Update specs

New patterns captured into the spec library — making future sessions even better.

Session archived

5 atomic commits, session recorded to journal. The branch is ready for review.

*** ## What just happened? This demo replays a real Trellis session where we added **Gemini CLI platform support** — a feature touching types, templates, configurators, CLI flags, Python adapters, and documentation. ### The workflow `/trellis:start` loads your project context — workflow rules, active tasks, git status, and recent journal entries. The AI is immediately oriented. You describe what you want in natural language. Trellis creates a tracked task with a structured PRD. Research Agent reads 36 files to find relevant specs and code patterns. Context files are configured in jsonl so agents receive the right conventions via hooks. Implement Agent writes code across 5 layers (types → templates → configurator → CLI → Python). 99 tool calls. All 337 tests pass on first try. Check Agent reviews every changed file against code-specs. Finds 1 missing `EXCLUDE_PATTERNS` entry and fixes it automatically. `/trellis:update-spec` captures new patterns learned from this session into the spec library — making future sessions even better. `/trellis:record-session` archives the session to your journal. 5 atomic commits on the feature branch, ready for review. ### Key metrics | Metric | Value | | ----------------- | ----------------------------------------------------------- | | **Total time** | \~20 minutes | | **Tool calls** | 169 (explore + research + implement + check) | | **Files changed** | 14 TOML templates + 5 source files | | **Tests** | 337/337 passed | | **Commits** | 5 atomic commits | | **Human input** | 3 messages (feature request + update-spec + record-session) | Install Trellis and run `/trellis:start` with your own feature request. # Trellis for Cursor Source: https://docs.trytrellis.app/showcase/trellis-cursor # About Community fork optimized for Cursor with Chinese subagents and MCP integration. Based on Trellis v0.2.12. [![Trellis for Cursor](https://opengraph.githubassets.com/1/jojolionss/Trellis)](https://github.com/jojolionss/Trellis) ## Key Features * **Cursor Commands**: 13 slash commands in `.cursor/commands/` format * **Chinese Localization**: All commands translated to Chinese * **MCP Integration**: `trellis-context.*` tools for task management * **Multi-model Support**: Specify models like `claude-4.5-opus-high-thinking` # cc-codex-spec-bootstrap Source: https://docs.trytrellis.app/skills-market/cc-codex-spec-bootstrap Bootstrap coding specs with Claude Code + Codex parallel pipeline A multi-agent pipeline where **Claude Code** orchestrates and **Codex** executes in parallel. CC analyzes the repo with GitNexus (knowledge graph) + ABCoder (AST), creates Trellis task PRDs with full architectural context, then Codex agents fill the coding spec files — each with access to the same code intelligence MCP tools. ## Why This Skill? AI coding agents produce better code when they have project-specific coding guidelines. But writing those guidelines manually is tedious. This skill automates the bootstrap: 1. **Claude Code** analyzes your repo architecture using GitNexus + ABCoder 2. **Claude Code** creates Trellis tasks with rich PRDs containing architectural context + MCP tool instructions 3. **Codex agents** run those tasks in parallel, each filling one spec directory using the same MCP tools The result: every spec file contains real code examples, actual patterns, and project-specific anti-patterns — not placeholder text. ## Prerequisites | Tool | Purpose | Required | | ------------------------------------------------------- | ------------------------------------------------------- | -------- | | [Trellis](https://github.com/mindfold-ai/Trellis) | Workflow framework with `.trellis/spec/` structure | Yes | | [GitNexus](https://github.com/abhigyanpatwari/GitNexus) | Code → knowledge graph (Tree-sitter + KuzuDB) | Yes | | [ABCoder](https://github.com/cloudwego/abcoder) | Code → UniAST (ts-morph for TS, tree-sitter for others) | Yes | | [Codex CLI](https://github.com/openai/codex) | Parallel task execution agent | Yes | ## Install ```bash theme={null} npx skills add mindfold-ai/marketplace --skill cc-codex-spec-bootstrap ``` Or install all available skills: ```bash theme={null} npx skills add mindfold-ai/marketplace ``` Options: | Flag | Description | | ---------------- | -------------------------------------- | | `-g` | Install globally (`~/.claude/skills/`) | | `-a claude-code` | Target a specific agent | | `-y` | Non-interactive mode | ## Verify Installation Check if the skill is available: ``` What skills do you have access to? ``` Claude should list `cc-codex-spec-bootstrap` in the response. ## Usage After installation, tell AI to bootstrap your specs: ``` Bootstrap coding specs for this project using Codex ``` ``` Set up Trellis spec files with code intelligence ``` ``` Run the CC + Codex spec pipeline ``` ## How It Works ### Phase 1 — Analyze Claude Code indexes the repo with GitNexus (knowledge graph) and ABCoder (AST), then maps the architecture: package boundaries, module clusters, key patterns, and cross-package data flows. ### Phase 2 — Plan Claude Code creates one Trellis task per (package, layer) combination. Each task PRD contains the architectural context from Phase 1 plus MCP tool instructions so the Codex agent can independently explore the codebase. ### Phase 3 — Execute Codex agents run all tasks in parallel. Each agent reads its PRD, uses GitNexus + ABCoder MCP tools to analyze the relevant code, and fills the spec files with real examples and patterns. ## What's Included | File | Contents | | ------------------------- | -------------------------------------------------------------------- | | `SKILL.md` | Full pipeline instructions (3 phases, checklists, PRD templates) | | `references/mcp-setup.md` | Detailed GitNexus + ABCoder MCP installation and configuration guide | # frontend-fullchain-optimization Source: https://docs.trytrellis.app/skills-market/frontend-fullchain-optimization Optimize frontend performance with a Web Vitals-driven diagnosis workflow An evidence-first skill for diagnosing and improving frontend performance with Web Vitals. It helps AI prioritize the right bottleneck, choose targeted fixes, and verify whether a change actually improved user experience. Use it when you need to optimize or review: * slow page loads * poor LCP, FCP, INP, CLS, TTFB, or TBT * layout shifts and unstable rendering * slow interactions caused by main-thread work * image, font, or code-splitting regressions ## Why This Skill? Most frontend performance work fails because teams optimize without enough evidence or fix symptoms before upstream bottlenecks. This skill gives AI a repeatable workflow: 1. Collect the minimum useful evidence 2. Identify the primary bottleneck 3. Pick the matching optimization branch 4. Re-measure when possible before claiming success It supports both tool-rich and tool-light environments: * **MCP-assisted mode** when Lighthouse or browser performance tooling is available * **Manual-evidence mode** when you only have reports, traces, screenshots, or metric snapshots By default, the workflow assumes Lighthouse and Performance evidence is collected manually. If you do not have manual measurements yet, the skill should only provide inferred suggestions and recommend follow-up verification after the change. ## Install ```bash theme={null} npx skills add mindfold-ai/marketplace --skill frontend-fullchain-optimization ``` Or install all available skills: ```bash theme={null} npx skills add mindfold-ai/marketplace ``` Options: | Flag | Description | | ---------------- | -------------------------------------- | | `-g` | Install globally (`~/.claude/skills/`) | | `-a claude-code` | Target a specific agent | | `-y` | Non-interactive mode | ## Verify Installation Check if the skill is available: ``` What skills do you have access to? ``` Claude should list `frontend-fullchain-optimization` in the response. ## Usage After installation, ask AI to analyze the current performance evidence: ``` Use frontend-fullchain-optimization to diagnose why this route has poor LCP and tell me what to fix first. ``` ``` Review this Lighthouse report with frontend-fullchain-optimization and propose the smallest high-impact fix. ``` ``` I only have DevTools screenshots and metric snapshots. Use frontend-fullchain-optimization in manual-evidence mode. ``` ## What It Covers | Area | Included guidance | | ------------ | ------------------------------------------------------------------------------------------ | | Metrics | LCP, FCP, INP, CLS, TTFB, and TBT thresholds and prioritization | | Diagnosis | Primary bottleneck decision tree and required evidence checklist | | Optimization | Rendering, images, fonts, code splitting, layout stability, and interaction responsiveness | | Verification | Before/after template for documenting improvements and remaining bottlenecks | ## What's Included | File | Contents | | ---------- | ---------------------------------------------------------------------------------------------- | | `SKILL.md` | The full performance workflow, metric playbooks, evidence checklist, and verification template | # Overview Source: https://docs.trytrellis.app/skills-market/index Ready-to-use skills for Trellis Skills extend Trellis with specialized knowledge and workflows. Install a skill, and AI instantly knows how to help you with that domain. Install any skill with one command via [skills.sh](https://skills.sh): ```bash theme={null} npx skills add mindfold-ai/marketplace ``` ## Official Skills | Skill | Description | Install | | --------------------------------------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------- | | [trellis-meta](/skills-market/trellis-meta) | Customize and modify Trellis | `npx skills add mindfold-ai/marketplace -s trellis-meta` | | [cc-codex-spec-bootstrap](/skills-market/cc-codex-spec-bootstrap) | Bootstrap coding specs with CC + Codex pipeline | `npx skills add mindfold-ai/marketplace -s cc-codex-spec-bootstrap` | | [frontend-fullchain-optimization](/skills-market/frontend-fullchain-optimization) | Diagnose and optimize frontend performance with Web Vitals | `npx skills add mindfold-ai/marketplace -s frontend-fullchain-optimization` | ## Community Skills Coming soon. # trellis-meta Source: https://docs.trytrellis.app/skills-market/trellis-meta The essential skill for customizing Trellis The official meta-skill for understanding and customizing Trellis. Install this skill, and AI can help you: * Add specialized agents for your workflow * Change how context gets injected * Add project-specific commands * Modify quality checks ## Install Works with Claude Code, Cursor, OpenCode, iFlow, Codex, Kilo, Kiro, Gemini CLI, Antigravity, and more. ```bash theme={null} npx skills add mindfold-ai/marketplace --skill trellis-meta ``` Or install all available skills: ```bash theme={null} npx skills add mindfold-ai/marketplace ``` Options: | Flag | Description | | ---------------- | -------------------------------------- | | `-g` | Install globally (`~/.claude/skills/`) | | `-a claude-code` | Target a specific agent | | `-y` | Non-interactive mode | ## Verify Installation Check if the skill is available: ``` What skills do you have access to? ``` Claude should list `trellis-meta` in the response. ## Usage After installation, just tell AI what you want: ``` I want to add a deploy agent to handle deployment workflow ``` ``` Help me modify the check hook to add a custom verification command ``` ``` I want to add a new workflow phase called review ``` AI will automatically use the skill's documentation and give you the correct modification steps. ## What's Included | Directory | Contents | | ---------------- | --------------------------------------------------------------- | | `core/` | Core systems (workspace, tasks, specs, scripts) | | `claude-code/` | Claude Code features (hooks, agents, Ralph Loop, multi-session) | | `how-to-modify/` | Modification guides (add agent, add command, modify hook, etc.) | | `meta/` | Platform compatibility, self-iteration guide | # Cloudflare Workers + Hono + Turso Source: https://docs.trytrellis.app/templates/specs-cf-workers Full-stack spec template for Cloudflare Workers apps with Hono framework and Turso database A complete coding convention template for production Cloudflare Workers applications with Hono framework, Drizzle ORM, and Turso edge database. Download as ZIP and extract to `.trellis/spec/` ## What's Included | Category | Files | Coverage | | -------- | ------------------ | ---------------------------------------------------- | | Backend | 11 files | Hono, Drizzle/Turso, API patterns, security, storage | | Frontend | 7 files + examples | Components, hooks, auth, design templates | | Shared | 5 files | TypeScript, code quality, dependencies, timestamps | | Guides | 3 files | OAuth consent flow, serverless connections | | Pitfalls | 6 files | Workers compat, cross-layer, env config, CSS | ## Template Structure ``` spec/ ├── backend/ │ ├── index.md │ ├── hono-framework.md │ ├── database.md │ ├── api-module.md │ ├── api-patterns.md │ ├── security.md │ ├── storage.md │ └── ... │ ├── frontend/ │ ├── index.md │ ├── authentication.md │ ├── components.md │ ├── hooks.md │ ├── directory-structure.md │ ├── examples/frontend-design/ │ └── ... │ ├── guides/ │ ├── oauth-consent-flow.md │ ├── serverless-connection-guide.md │ └── ... │ ├── shared/ │ ├── typescript.md │ ├── code-quality.md │ ├── dependency-versions.md │ └── ... │ ├── big-question/ │ ├── workers-nodejs-compat.md │ ├── cross-layer-contract.md │ ├── env-configuration.md │ └── ... │ └── README.md ``` ## Key Topics ### Backend * Hono framework patterns (type-safe bindings, middleware, WebSocket) * Drizzle ORM + Turso/libSQL (batch ops, N+1 prevention, Workers pitfalls) * Cloudflare storage (R2, KV, Cache API for session caching) * Security (token generation, timing-safe comparison, OAuth redirect validation) * Structured JSON logging with request context ### Frontend * React 19 + React Router v7 with Vite * Better Auth UI v3.x integration (SSR-safe, Cloudflare Workers considerations) * shadcn/ui components + Tailwind CSS v4 * Design example templates (minimalist hero, maximalist dashboard, animations) ### Guides * OAuth 2.1 consent flow with resource selection * Serverless connection debugging (stale connections, subrequest limits) ### Common Pitfalls * Workers Node.js compatibility (`nodejs_compat` flag) * Cross-layer contract violations (data flows but never reaches client) * Build-time vs runtime environment variables * CSS debugging in Tailwind v4 ## Usage 1. Download the ZIP file 2. Extract to your project's `.trellis/spec/` directory 3. Replace generic env var names with your actual bindings 4. Customize for your specific conventions 5. Remove sections that don't apply Browse the template source code # Electron + React + TypeScript Source: https://docs.trytrellis.app/templates/specs-electron Full-stack spec template for Electron desktop apps with React frontend A complete coding convention template for Electron applications with React frontend and TypeScript. Download as ZIP and extract to `.trellis/spec/` ## What's Included | Category | Files | Coverage | | -------- | -------- | -------------------------------------- | | Frontend | 11 files | Components, hooks, state, IPC, CSS | | Backend | 14 files | API patterns, database, error handling | | Guides | 8 files | Cross-layer thinking, debugging | | Shared | 6 files | TypeScript, git, code quality | ## Template Structure ``` spec/ ├── frontend/ │ ├── index.md │ ├── components.md │ ├── hooks.md │ ├── state-management.md │ ├── ipc-electron.md │ └── ... │ ├── backend/ │ ├── index.md │ ├── api-patterns.md │ ├── database.md │ ├── error-handling.md │ └── ... │ ├── guides/ │ ├── cross-layer-thinking-guide.md │ ├── bug-root-cause-thinking-guide.md │ └── ... │ ├── shared/ │ ├── typescript.md │ ├── git-conventions.md │ └── ... │ └── README.md ``` ## Key Topics ### Frontend * React component patterns and hooks * Electron IPC communication * State management with Zustand * CSS design system ### Backend * API module structure * SQLite database patterns * Error handling and logging * macOS permissions ### Guides * Cross-layer thinking for full-stack changes * Bug root cause analysis * Database schema migrations ## Usage 1. Download the ZIP file 2. Extract to your project's `.trellis/spec/` directory 3. Customize for your specific conventions 4. Remove sections that don't apply 5. Update examples to match your codebase Browse the template source code # Overview Source: https://docs.trytrellis.app/templates/specs-index Coding convention templates for common tech stacks Spec templates help you quickly set up coding guidelines for your project. Download, customize, use. **Specs are meant to be customized.** Trellis ships with empty spec templates by default — they are placeholders for *your* project's conventions. Every team's stack, patterns, and quality bar are different, so the specs you write should reflect your actual codebase, not generic best practices. Templates from the marketplace give you a head start, but always tailor them to your project. ## Available Templates | Template | Stack | Description | | ---------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------- | | [Electron + React + TypeScript](https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/electron-fullstack) | Full-stack | Electron desktop app with React frontend | | [Next.js + oRPC + PostgreSQL](https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/nextjs-fullstack) | Full-stack | Next.js app with oRPC API and PostgreSQL | | [CF Workers + Hono + Turso](https://github.com/mindfold-ai/Trellis/tree/main/marketplace/specs/cf-workers-fullstack) | Full-stack | Cloudflare Workers with Hono and Turso | Electron + React + TypeScript (50 files) Next.js + oRPC + PostgreSQL (35 files) CF Workers + Hono + Turso (38 files) ## Template Marketplace v0.3.6 Starting from v0.3.6, you can fetch spec templates directly from any Git repository using the `--registry` flag: ```bash theme={null} # Fetch from a custom registry trellis init --registry https://github.com/your-org/your-spec-templates # Combine with platform flags trellis init --registry https://github.com/your-org/your-spec-templates --cursor -u your-name ``` ### How it works Trellis auto-detects two modes: * **Marketplace mode**: If the repository contains a `marketplace/index.json` file, Trellis reads the template index and lets you pick which template to install * **Direct download mode**: If no `index.json` is found, Trellis treats the entire `marketplace/specs/` directory as a single template and downloads it directly ### Publishing your own templates To create a spec template registry that others can use with `--registry`: 1. Create a Git repository (GitHub, GitLab, or Bitbucket) 2. Add a `marketplace/` directory with your spec templates 3. Create `marketplace/index.json` to list available templates: ```json theme={null} { "version": 1, "templates": [ { "id": "my-stack", "type": "spec", "name": "My Stack Template", "description": "Conventions for our tech stack", "path": "marketplace/specs/my-stack", "tags": ["react", "node", "typescript"] } ] } ``` 4. Inside each template path, place your spec files following the standard structure (see below) 5. Share the repository URL — users install with `trellis init --registry ` ## Template Structure Each template follows this structure: ``` spec/ ├── frontend/ # Frontend guidelines │ ├── index.md # Navigation index │ ├── components.md # Component patterns │ ├── hooks.md # Hook conventions │ └── state-management.md │ ├── backend/ # Backend guidelines │ ├── index.md │ └── ... │ ├── guides/ # Thinking guides │ ├── index.md │ └── ... │ └── README.md # Template overview ``` ## How to Use 1. Download the template ZIP or use `trellis init --registry` 2. Extract to `.trellis/spec/` in your project 3. Customize for your project's specific conventions 4. Remove sections that don't apply 5. Update paths and examples to match your codebase You don't have to fill every spec file at once. Start with the areas that matter most to your project, then expand over time. The `/trellis:start` bootstrap task will guide you through the initial fill. ## Contributing Templates Want to share your specs with the community? Create a repository with your templates and open a PR to add it to the [official template registry](https://github.com/mindfold-ai/Trellis/tree/main/marketplace). # Next.js + oRPC + PostgreSQL Source: https://docs.trytrellis.app/templates/specs-nextjs Full-stack spec template for Next.js applications with oRPC API layer and PostgreSQL A complete coding convention template for production Next.js applications with oRPC API layer, Drizzle ORM, and PostgreSQL. Download as ZIP and extract to `.trellis/spec/` ## What's Included | Category | Files | Coverage | | -------- | -------- | ------------------------------------------------- | | Frontend | 12 files | Components, hooks, state, oRPC, AI SDK, CSS | | Backend | 10 files | oRPC router, database, auth, performance, logging | | Guides | 3 files | Cross-layer thinking, pre-implementation | | Shared | 4 files | TypeScript, code quality, dependencies | | Pitfalls | 5 files | PostgreSQL, build system, mobile CSS | ## Template Structure ``` spec/ ├── frontend/ │ ├── index.md │ ├── components.md │ ├── hooks.md │ ├── state-management.md │ ├── orpc-usage.md │ ├── authentication.md │ ├── ai-sdk-integration.md │ └── ... │ ├── backend/ │ ├── index.md │ ├── orpc-usage.md │ ├── database.md │ ├── authentication.md │ ├── performance.md │ └── ... │ ├── guides/ │ ├── pre-implementation-checklist.md │ ├── cross-layer-thinking-guide.md │ └── ... │ ├── shared/ │ ├── typescript.md │ ├── code-quality.md │ ├── dependencies.md │ └── ... │ ├── big-question/ │ ├── postgres-json-jsonb.md │ ├── sentry-nextintl-conflict.md │ └── ... │ └── README.md ``` ## Key Topics ### Frontend * Next.js 15 App Router with React 19 * oRPC client + React Query integration * Server Components vs Client Components * Authentication with better-auth * Vercel AI SDK (useChat, tool calls, streaming) * TailwindCSS 4 + Radix UI patterns ### Backend * oRPC router, procedures, and middleware * Drizzle ORM + PostgreSQL (N+1 prevention, transactions, JSON/JSONB) * better-auth server configuration * Performance patterns (concurrency, caching, rate limiting) * Structured logging with Sentry ### Guides * Pre-implementation checklist (search before write) * Cross-layer thinking for Next.js full-stack changes ### Common Pitfalls * PostgreSQL `json` vs `jsonb` with Drizzle ORM * Sentry + next-intl plugin conflict * Turbopack vs Webpack flexbox differences * WebKit tap highlight on mobile ## Usage 1. Download the ZIP file 2. Extract to your project's `.trellis/spec/` directory 3. Replace `@your-app/*` placeholders with your monorepo package paths 4. Customize for your specific conventions 5. Remove sections that don't apply Browse the template source code # open-typeless Source: https://docs.trytrellis.app/use-cases/open-typeless Step-by-step guide: Building a macOS voice input app with Trellis # open-typeless A step-by-step tutorial showing how to use Trellis to build a macOS voice input app from scratch. **Source Code**: [github.com/mindfold-ai/open-typeless](https://github.com/mindfold-ai/open-typeless) ## Step 1: Project Initialization ### 1.1 Create Electron Project ```bash theme={null} npx create-electron-app@latest open-typeless --template=vite-typescript cd open-typeless # Remove npm generated files rm -rf node_modules package-lock.json # Create .npmrc (required for pnpm + Electron) cat > .npmrc << 'EOF' node-linker=hoisted shamefully-hoist=true EOF # Reinstall with pnpm pnpm install ``` ### 1.2 Initialize Trellis ```bash theme={null} trellis init ``` trellis init ### 1.3 Copy Specs from Existing Project If you have specs from a similar project, copy them over: ```bash theme={null} cp -r /path/to/old-project/.trellis/spec ./ ``` ### 1.4 Ask AI to Fill in Specs **Prompt:** > Help me select useful specs from electron-doc/ and organize them into this project's .trellis/spec/ AI will analyze and organize specs: spec selection ## Step 2: Task Planning ### 2.1 Ask AI to Plan Tasks **Prompt:** > I want to use Volcengine ASR BigModel API to build this. Help me plan how to break down the tasks. AI creates a batch-based task plan: task planning ### 2.2 Create Tasks AI creates tasks organized into batches: | Batch | Tasks | Purpose | | ------- | -------------------------------------------------------------------- | -------------------------------- | | Batch 1 | `asr-infrastructure` | Foundation (must complete first) | | Batch 2 | `asr-audio-recorder`, `asr-volcengine-client`, `asr-floating-window` | Can run in parallel | | Batch 3 | `asr-integration` | Integration (depends on Batch 2) | tasks created ### 2.3 Complete Batch 1 After Batch 1 completes, verify and update downstream task contexts: batch 1 complete ## Step 3: Parallel Development ### 3.1 Start Parallel Agents **Prompt:** `/trellis:parallel` AI launches 3 worktree agents for Batch 2, each working in an isolated git worktree: parallel agents ## Step 4: Monitor Progress ### 4.1 Check Agent Status AI monitors agent status and task progress: agent status ### 4.2 Record Session After parallel agents complete, they create PRs automatically: parallel PRs After merging and completing a batch, record the session: **Prompt:** `/trellis:record-session` record session ## Step 5: Continue Development ### 5.1 Check Remaining Tasks AI shows remaining tasks in the current project: task list ### 5.2 Implement Next Feature Select the next task, AI uses implement agent then check agent: implement and check ### 5.3 Configure and Test AI helps with remaining setup (environment config, permissions): final setup ## Summary Using Trellis to build open-typeless: | Step | What | Trellis Feature | | ---- | -------------------- | ------------------------------------ | | 1 | Initialize project | `trellis init`, spec organization | | 2 | Plan tasks | AI task breakdown, batch planning | | 3 | Parallel development | `/trellis:parallel`, worktree agents | | 4 | Monitor & record | `/trellis:record-session` | | 5 | Continue iterating | Task hooks, implement/check agents | **Result:** Complete Electron app in 1 day, with structured specs and documented progress.