Trellis Meta

Trellis Meta-Skill

Version Compatibility

⚠️ Version Mismatch Warning: If your Trellis CLI version differs from above, some features may not work as documented. Run trellis --version to check.

---

Platform Compatibility

Feature Support Matrix

Legend

• ✅ Full: Feature works as documented
• ⚠️ Limited/Manual: Works but requires manual steps
• ❌ None/Manual: Not supported or requires manual workaround

Platform Categories

Full Hook Support (Claude Code, iFlow)

All features work as documented. Hooks provide automatic context injection and quality enforcement. iFlow shares the same Python hook system as Claude Code.

Partial Hook Support (Codex)

• Works: Workspace, tasks, specs, skills (.codex/skills/ + .agents/skills/ shared layer), TOML agent definitions (.codex/agents/), optional SessionStart hook
• Doesn't work: PreToolUse, SubagentStop, Ralph Loop, Multi-Session
• Note: SessionStart hook requires codex_hooks = true in ~/.codex/config.toml

Commands Only (Cursor, OpenCode, Kilo, Kiro, Gemini CLI, Antigravity, Qoder, CodeBuddy)

• Works: Workspace, tasks, specs, commands/skills (platform-specific format)
• Doesn't work: Hooks, auto-injection, Ralph Loop, Multi-Session
• Workaround: Manually read spec files at session start; no automatic quality gates
• Note: Each platform uses its own command format (Kiro/Qoder use Skills, Gemini uses TOML, Antigravity uses Workflows, CodeBuddy uses nested Markdown commands)

Designing for Portability

When customizing Trellis, consider platform compatibility:

┌─────────────────────────────────────────────────────────────┐
│                 PORTABLE (All 11 Platforms)                  │
│  - .trellis/workspace/    - .trellis/tasks/                 │
│  - .trellis/spec/         - Platform commands/skills        │
│  - File-based configs     - JSONL context files             │
│  - config.yaml            - Monorepo packages support       │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│         SHARED AGENT SKILLS (agentskills.io standard)       │
│  - .agents/skills/          (Codex + universal agent CLIs)  │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│              HOOK-CAPABLE (Claude Code + iFlow)              │
│  - .claude/hooks/ or .iflow/hooks/                          │
│  - settings.json hook configuration                         │
│  - Auto context injection   - SubagentStop control          │
│  - Ralph Loop               - Multi-Session worktrees       │
│  - Task lifecycle hooks     - Dynamic spec discovery        │
└─────────────────────────────────────────────────────────────┘

---

Purpose

This is the meta-skill for Trellis - it documents the original, unmodified Trellis system. When customizing Trellis for a specific project, record changes in a project-local skill (trellis-local), keeping this meta-skill as the authoritative reference for vanilla Trellis.

Skill Hierarchy

~/.claude/skills/
└── trellis-meta/              # THIS SKILL - Original Trellis documentation
                               # ⚠️ DO NOT MODIFY for project-specific changes

project/.claude/skills/
└── trellis-local/             # Project-specific customizations
                               # ✅ Record all modifications here

Why this separation?

• User may have multiple projects with different Trellis customizations
• Each project's trellis-local skill tracks ITS OWN modifications
• The meta-skill remains clean as the reference for original Trellis
• Enables easy upgrades: compare meta-skill with new Trellis version

---

Self-Iteration Protocol

When modifying Trellis for a project, follow this protocol:

1. Check for Existing Project Skill

# Look for project-local skill
ls -la .claude/skills/trellis-local/

2. Create Project Skill if Missing

If no trellis-local exists, create it:

mkdir -p .claude/skills/trellis-local

Then create .claude/skills/trellis-local/SKILL.md:

---
name: trellis-local
description: |
  Project-specific Trellis customizations for [PROJECT_NAME].
  This skill documents modifications made to the vanilla Trellis system
  in this project. Inherits from trellis-meta for base documentation.
---

# Trellis Local - [PROJECT_NAME]

## Base Version

Trellis version: X.X.X (from package.json or trellis --version)
Date initialized: YYYY-MM-DD

## Customizations

### Commands Added

(none yet)

### Agents Modified

(none yet)

### Hooks Changed

(none yet)

### Specs Customized

(none yet)

### Workflow Changes

(none yet)

---

## Changelog

### YYYY-MM-DD

- Initial setup

3. Record Every Modification

When making ANY change to Trellis, update trellis-local/SKILL.md:

Example: Adding a new command

### Commands Added

#### /trellis:my-command

- **File**: `.claude/commands/trellis/my-command.md`
- **Purpose**: [what it does]
- **Added**: 2026-01-31
- **Why**: [reason for adding]

Example: Modifying a hook

### Hooks Changed

#### inject-subagent-context.py

- **Change**: Added support for `my-agent` type
- **Lines modified**: 45-67
- **Date**: 2026-01-31
- **Why**: [reason]

4. Never Modify Meta-Skill for Project Changes

The trellis-meta skill should ONLY be updated when:

• Trellis releases a new version
• Fixing documentation errors in the original
• Adding missing documentation for original features

---

Architecture Overview

Trellis transforms AI assistants into structured development partners through enforced context injection.

System Layers

┌─────────────────────────────────────────────────────────────────────┐
│                        USER INTERACTION                              │
│  /trellis:start  /trellis:brainstorm  /trellis:parallel             │
│  /trellis:finish-work  /trellis:before-dev  /trellis:check          │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                         SKILLS LAYER                                 │
│  .claude/commands/trellis/*.md   (17 slash commands)                │
│  .claude/agents/*.md             (6 sub-agent definitions)          │
│  .agents/skills/*/SKILL.md       (shared agent skills layer)        │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                          HOOKS LAYER                                 │
│  SessionStart      → session-start.py (workflow + context + status) │
│  PreToolUse:Agent  → inject-subagent-context.py (spec injection)    │
│  SubagentStop      → ralph-loop.py (quality enforcement)            │
│  Task Lifecycle    → config.yaml hooks (after_create/start/finish/  │
│                      archive → e.g. Linear sync)                    │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                       PERSISTENCE LAYER                              │
│  .trellis/workspace/  (journals, session history)                   │
│  .trellis/tasks/      (task tracking, context files, subtasks)      │
│  .trellis/spec/       (coding guidelines, monorepo per-package)     │
│  .trellis/config.yaml (packages, hooks, update.skip, spec_scope)   │
└─────────────────────────────────────────────────────────────────────┘

Key Design Principles

---

Core Components

1. Workspace System

Track development progress across sessions with per-developer isolation.

.trellis/workspace/
├── index.md                    # Global overview
└── {developer}/                # Per-developer
    ├── index.md                # Personal index (@@@auto markers)
    └── journal-N.md            # Session journals (max 2000 lines)

Key files: .trellis/.developer (identity), journals (session history)

2. Task System

Track work items with phase-based execution, parent-child subtasks, and lifecycle hooks.

.trellis/tasks/{MM-DD-slug}/
├── task.json           # Metadata, phases, branch, subtasks
├── prd.md              # Requirements
├── info.md             # Technical design (optional)
├── implement.jsonl     # Context for implement agent
├── check.jsonl         # Context for check agent
├── debug.jsonl         # Context for debug agent
├── research.jsonl      # Context for research agent (optional)
└── cr.jsonl            # Context for code review (optional)

3. Spec System

Maintain coding standards that get injected to agents. Supports both single-repo and monorepo layouts.

# Single repo
.trellis/spec/
├── frontend/           # Frontend guidelines
├── backend/            # Backend guidelines
└── guides/             # Thinking guides

# Monorepo (per-package)
.trellis/spec/
├── <package-name>/     # Per-package specs
│   ├── backend/
│   ├── frontend/
│   └── unit-test/
└── guides/             # Shared thinking guides

4. Hooks System

Automatically inject context and enforce quality.

Claude Code / iFlow Hooks (settings.json):

Task Lifecycle Hooks (config.yaml):

5. Agent System

Specialized agents for different phases.

6. Multi-Agent Pipeline

Run parallel isolated sessions via Git worktrees.

plan.py → start.py → Dispatch → implement → check → create-pr

---

Customization Guide

Adding a Command

1. Create .claude/commands/trellis/my-command.md 2. Update trellis-local skill with the change

Adding an Agent

1. Create .claude/agents/my-agent.md with YAML frontmatter 2. Update inject-subagent-context.py to handle new agent type 3. Create my-agent.jsonl in task directories 4. Update trellis-local skill

Modifying Hooks

1. Edit the hook script in .claude/hooks/ 2. Document the change in trellis-local skill 3. Note which lines were modified and why

Extending Specs

1. Create new category in .trellis/spec/my-category/ 2. Add index.md and guideline files 3. Reference in JSONL context files 4. Update trellis-local skill

Changing Task Workflow

1. Modify next_action array in task.json 2. Update dispatch or hook scripts as needed 3. Document in trellis-local skill

---

Resources

Reference documents are organized by platform compatibility:

references/
├── core/              # All Platforms (Claude Code, Cursor, etc.)
├── claude-code/       # Claude Code Only
├── how-to-modify/     # Modification Guides
└── meta/              # Documentation & Templates

core/ - All Platforms

claude-code/ - Claude Code Only

how-to-modify/ - Modification Guides

meta/ - Documentation

---

Quick Reference

Key Scripts

Key Paths

---

Upgrade Protocol

When upgrading Trellis to a new version:

1. Compare new meta-skill with current 2. Review changes in new version 3. Check trellis-local for conflicts 4. Merge carefully, preserving customizations 5. Update trellis-local with migration notes

## Changelog

### 2026-02-01 - Upgraded to Trellis X.Y.Z

- Merged new hook behavior from meta-skill
- Kept custom agent `my-agent`
- Updated check.jsonl template

Agents Reference

Documentation for the Trellis agent system - specialized AI agents for different development phases.

---

Overview

Trellis uses specialized agents for different tasks. Each agent has specific capabilities, restrictions, and context injection.

Key Insight: Agents work in the current directory - no worktree needed. Multi-Session (worktree isolation) is a separate concept.

---

Agent Types

---

Agent Definitions

Location: .claude/agents/*.md

Format

---
name: agent-name
description: |
  What this agent does.
tools: Read, Write, Edit, Bash, Glob, Grep
model: opus
---

# Agent Name

## Core Responsibilities

...

## Workflow

...

## Forbidden Operations

...

---

Dispatch Agent

File: .claude/agents/dispatch.md

Purpose: Pure orchestrator - calls other agents in sequence.

Key Principle: Does NOT read specs directly. Hooks inject context to subagents.

Tools: Read, Bash

Workflow:

1. Read .trellis/.current-task → find task directory
2. Read task.json → get next_action array
3. For each phase:
   - implement → Task(subagent_type="implement")
   - check → Task(subagent_type="check")
   - finish → Task(subagent_type="check", prompt="[finish]...")
   - create-pr → Bash("python3 ... create_pr.py")

Forbidden:

• Reading spec files directly
• Modifying code
• Git operations (except via create-pr script)

---

Plan Agent

File: .claude/agents/plan.md

Purpose: Evaluate requirements and configure task directory.

Tools: Read, Bash, Glob, Grep, Task

Capabilities:

• REJECT unclear/vague requirements
• Call Research Agent to analyze codebase
• Create prd.md with requirements
• Configure task.json (branch, scope, phases)
• Initialize JSONL context files

Rejection Criteria:

• Vague requirements ("make it better")
• Incomplete information
• Out of scope
• Potentially harmful
• Too large (should split)

Output:

task-dir/
├── task.json      # Configured with branch, scope, dev_type
├── prd.md         # Clear requirements
├── implement.jsonl
├── check.jsonl
└── debug.jsonl

---

Research Agent

File: .claude/agents/research.md

Purpose: Find and explain code patterns. Pure research, no modifications.

Tools: Read, Glob, Grep, web search, chrome-devtools

Allowed:

• Describe what exists
• Describe where it is
• Describe how it works
• Describe interactions

Forbidden (unless explicitly asked):

• Suggest improvements
• Criticize implementation
• Recommend refactoring
• Modify any files
• Git operations

Output Format:

## Query Summary

...

## Files Found

- path/to/file.ts - description

## Code Patterns

...

## Related Specs

...

---

Implement Agent

File: .claude/agents/implement.md

Purpose: Write code following injected specs.

Tools: Read, Write, Edit, Bash, Glob, Grep

Workflow:

1. Understand specs (from injected context) 2. Understand requirements (prd.md, info.md) 3. Implement features 4. Self-check (run lint/typecheck)

Forbidden:

• git commit
• git push
• git merge

Context Injection: Hook injects implement.jsonl + prd.md + info.md

---

Check Agent

File: .claude/agents/check.md

Purpose: Review code and self-fix issues.

Tools: Read, Write, Edit, Bash, Glob, Grep

Key Principle: Fix issues yourself, don't just report them.

Workflow:

1. Get changes: git diff 2. Check against specs 3. Self-fix issues directly 4. Run verification (lint, typecheck) 5. Output completion markers

Controlled by: Ralph Loop (SubagentStop hook)

Completion Markers:

TYPECHECK_FINISH
LINT_FINISH
CODEREVIEW_FINISH

---

Debug Agent

File: .claude/agents/debug.md

Purpose: Fix specific reported issues.

Tools: Read, Write, Edit, Bash, Glob, Grep

Workflow:

1. Parse issues (prioritize P1 > P2 > P3) 2. Research if needed 3. Fix one by one 4. Verify each fix (run typecheck)

Forbidden:

• Refactor surrounding code
• Add new features
• Modify unrelated files
• Use non-null assertion (x!)
• Git commit

---

Invoking Agents

Use the Task tool with subagent_type:

Task(
  subagent_type: "implement",
  prompt: "Implement the login feature",
  model: "opus",
  run_in_background: true  // optional
)

Agent Resolution

1. Claude Code looks for .claude/agents/{subagent_type}.md 2. Loads agent definition (tools, model, instructions) 3. PreToolUse hook fires → inject-subagent-context.py 4. Hook injects context from JSONL files 5. Agent runs with full context

---

Context Injection

How It Works

Task(subagent_type="implement") called
            │
            ▼
    PreToolUse hook fires
            │
            ▼
inject-subagent-context.py runs
            │
            ├── Read .trellis/.current-task
            │
            ├── Find task directory
            │
            ├── Load implement.jsonl
            │   {"file": ".trellis/spec/backend/index.md", "reason": "..."}
            │   {"file": "src/services/auth.ts", "reason": "..."}
            │
            ├── Read each file content
            │
            └── Build new prompt:
                # Implement Agent Task
                ## Your Context
                === .trellis/spec/backend/index.md ===
                [content]
                === src/services/auth.ts ===
                [content]
                ## Your Task
                [original prompt]

JSONL Files

---

Multi-Agent Workflow

In the current directory (no worktree):

User request
    │
    ▼
Orchestrator (you or dispatch)
    │
    ├── Task(subagent_type="research")
    │   └── Returns: code patterns, relevant files
    │
    ├── Task(subagent_type="implement")
    │   └── Returns: implemented code
    │
    ├── Task(subagent_type="check")
    │   └── Returns: reviewed & fixed code
    │
    └── Human commits

Task Workflow (from /trellis:start)

1. User describes task
2. AI classifies (Question / Trivial / Development Task)
3. For Development Task:
   a. Research Agent → analyze codebase
   b. Create task directory + JSONL files
   c. task.py start → set .current-task
   d. Implement Agent → write code
   e. Check Agent → review & fix
   f. Human tests and commits

---

Adding Custom Agents

1. Create Definition

.claude/agents/my-agent.md:

---
name: my-agent
description: |
  What this agent specializes in.
tools: Read, Write, Edit, Bash, Glob, Grep
model: opus
---

# My Agent

## Core Responsibilities

1. ...

## Workflow

1. ...

## Forbidden Operations

- ...

2. Update Hook

Edit .claude/hooks/inject-subagent-context.py:

# Add constant
AGENT_MY_AGENT = "my-agent"

# Add to list
AGENTS_ALL = (..., AGENT_MY_AGENT)

# Add context function
def get_my_agent_context(repo_root, task_dir):
    # Load my-agent.jsonl or fallback
    ...

# Add to main switch
elif subagent_type == AGENT_MY_AGENT:
    context = get_my_agent_context(repo_root, task_dir)
    new_prompt = build_my_agent_prompt(original_prompt, context)

3. Create JSONL

In task directories, create my-agent.jsonl:

{
  "file": ".trellis/spec/my-spec.md",
  "reason": "My agent spec"
}

4. (Optional) Add to Dispatch

Update task.json default phases:

"next_action": [
  {"phase": 1, "action": "my-agent"},
  ...
]

---

vs Multi-Session

Multi-Agent is the agent system - dispatch calling implement, check, etc.

Multi-Session is parallel execution - multiple worktrees running simultaneously.

They can combine: Multi-Session runs Multi-Agent workflows in each worktree.

Hooks System

Claude Code / iFlow hooks for automatic context injection and quality enforcement, plus task lifecycle hooks configured in config.yaml.

---

Overview

There are two types of hooks in Trellis:

1. Platform hooks (Claude Code / iFlow) — Intercept AI lifecycle events via settings.json 2. Task lifecycle hooks (all platforms) — Shell commands triggered by task.py operations via config.yaml

┌─────────────────────────────────────────────────────────────────────────┐
│                      PLATFORM HOOK LIFECYCLE                             │
│                                                                          │
│  Session Start ──► SessionStart hook ──► Inject workflow + task status  │
│  (startup/clear/compact)                                                │
│                                                                          │
│  Agent() called ──► PreToolUse:Agent hook ──► Inject specs from JSONL  │
│  Task() called  ──► PreToolUse:Task hook  ──► (same, legacy matcher)   │
│                                                                          │
│  Agent stops ──► SubagentStop hook ──► Ralph Loop verification          │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                      TASK LIFECYCLE HOOKS                                 │
│                                                                          │
│  task.py create  ──► after_create  ──► e.g. Create Linear issue        │
│  task.py start   ──► after_start   ──► e.g. Update status              │
│  task.py finish  ──► after_finish  ──► e.g. Mark done                  │
│  task.py archive ──► after_archive ──► e.g. Close issue                │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

---

Platform Hook Configuration

.claude/settings.json

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.py\"",
            "timeout": 10
          }
        ]
      },
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.py\"",
            "timeout": 10
          }
        ]
      },
      {
        "matcher": "compact",
        "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
          }
        ]
      },
      {
        "matcher": "Agent",
        "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": 300
          }
        ]
      }
    ]
  }
}

Note: PreToolUse matches both Task and Agent because Claude Code renamed the Task tool to Agent in v2.1.63. Both matchers are kept for backward compatibility.

---

SessionStart Hook

Purpose

Inject initial context when a Claude Code session starts, clears, or compacts.

Matchers

Script: session-start.py

Injects:

• Developer identity from .trellis/.developer
• Git status and recent commits
• Current task info (if .trellis/.current-task exists)
• workflow.md content
• All dynamically discovered spec/*/index.md files (supports monorepo layout)
• Spec guideline indexes
• Start instructions
• Task status tag (<task-status>) with structured state:
• NO ACTIVE TASK — no current task set
• NOT READY — task exists but no JSONL context files
• READY — task has context, ready to implement
• COMPLETED — task is done

Dynamic spec discovery: The hook iterates spec/ subdirectories at runtime instead of hardcoding frontend/backend/guides. This means adding a new spec category requires no hook modification.

Output format:

{
  "result": "continue",
  "message": "# Session Context\n\n## Developer\ntaosu\n\n<task-status>Status: READY\n...</task-status>"
}

---

PreToolUse:Agent Hook

Purpose

Inject relevant specs when a subagent is invoked.

Script: inject-subagent-context.py

Trigger: When Agent(subagent_type="...") or Task(subagent_type="...") is called.

Flow:

1. Read subagent_type from tool input 2. Find current task from .trellis/.current-task 3. Load {subagent_type}.jsonl from task directory 4. Read each file listed in JSONL 5. Build augmented prompt with context 6. Update task.json with current phase

Output format:

{
  "result": "continue",
  "updatedInput": {
    "prompt": "# Implement Agent Task\n\n## Context\n...\n\n## Your Task\n..."
  }
}

JSONL Format

{"file": ".trellis/spec/cli/backend/index.md", "reason": "Backend guidelines"}
{"file": "src/services/auth.ts", "reason": "Existing pattern"}
{"file": ".trellis/tasks/03-24-add-login/prd.md", "reason": "Requirements"}

---

SubagentStop Hook

Purpose

Quality enforcement via Ralph Loop.

Script: ralph-loop.py

Trigger: When Check Agent tries to stop.

Flow:

1. Read verify commands from worktree.yaml 2. Execute each command (pnpm lint, pnpm typecheck, etc.) 3. If all pass → allow stop 4. If any fail → block stop, agent continues

→ See ralph-loop.md for details.

---

Task Lifecycle Hooks

Purpose

Run shell commands after task lifecycle events. Works on all platforms (file-based, no hook system required).

Configuration (config.yaml)

hooks:
  after_create:
    - python3 .trellis/scripts/hooks/linear_sync.py create
  after_start:
    - python3 .trellis/scripts/hooks/linear_sync.py start
  after_finish:
    - python3 .trellis/scripts/hooks/linear_sync.py finish
  after_archive:
    - python3 .trellis/scripts/hooks/linear_sync.py archive

Events

Environment Variable

Built-in: Linear Sync Hook

Ships with hooks/linear_sync.py that syncs task events to Linear via the linearis CLI tool.

---

Codex SessionStart Hook

Codex has its own optional SessionStart hook at .codex/hooks/session-start.py configured via .codex/hooks.json.

Requires: codex_hooks = true in ~/.codex/config.toml

Injects: Same Trellis context as the Claude Code hook (workflow, guidelines, task status).

---

Hook Scripts Location

.claude/hooks/                          # Claude Code platform hooks
├── session-start.py                    # SessionStart handler
├── inject-subagent-context.py          # PreToolUse:Agent/Task handler
└── ralph-loop.py                       # SubagentStop:check handler

.trellis/scripts/hooks/                 # Task lifecycle hooks (all platforms)
└── linear_sync.py                      # Linear issue sync

.codex/hooks/                           # Codex platform hooks (optional)
├── session-start.py                    # Codex SessionStart handler
└── hooks.json                          # Codex hook configuration

---

Environment Variables

Available in platform hook scripts:

---

Hook Response Format

Continue (allow operation)

{
  "result": "continue",
  "message": "Optional message to inject"
}

Continue with modified input

{
  "result": "continue",
  "updatedInput": {
    "prompt": "Modified prompt..."
  }
}

Block (prevent operation)

{
  "result": "block",
  "message": "Reason for blocking"
}

---

Debugging Hooks

View hook output

# Check if hooks are configured
cat .claude/settings.json | grep -A 20 '"hooks"'

# Test session-start manually
python3 .claude/hooks/session-start.py

# Test inject-context (needs TOOL_INPUT env var)
TOOL_INPUT='{"subagent_type":"implement","prompt":"test"}' \
  python3 .claude/hooks/inject-subagent-context.py

Common Issues

Multi-Session Reference

Documentation for parallel isolated sessions using Git worktrees.

---

Overview

Multi-Session enables parallel, isolated development sessions using Git worktrees. Each session runs in its own directory with its own branch.

Key Distinction:

• Multi-Agent = Multiple agents in current directory (dispatch → implement → check)
• Multi-Session = Parallel sessions in separate worktrees (this document)

---

When to Use Multi-Session

---

Architecture

┌────────────────────────────────────────────────────────────────────────────┐
│                         MAIN REPOSITORY                                     │
│                         (your current directory)                            │
│                                                                             │
│  /trellis:parallel → Configure task → start.py                             │
│                                           │                                 │
│                                           │ Creates worktree               │
│                                           │ Starts agent                   │
│                                           ▼                                 │
└───────────────────────────────────────────┼─────────────────────────────────┘
                                            │
              ┌─────────────────────────────┼─────────────────────────────────┐
              │                             │                                 │
              ▼                             ▼                                 ▼
┌──────────────────────┐  ┌──────────────────────┐  ┌──────────────────────┐
│ WORKTREE 1           │  │ WORKTREE 2           │  │ WORKTREE 3           │
│ feature/add-login    │  │ feature/user-profile │  │ fix/api-bug          │
│                      │  │                      │  │                      │
│ ┌──────────────────┐ │  │ ┌──────────────────┐ │  │ ┌──────────────────┐ │
│ │ Dispatch Agent   │ │  │ │ Dispatch Agent   │ │  │ │ Dispatch Agent   │ │
│ │       ↓          │ │  │ │       ↓          │ │  │ │       ↓          │ │
│ │ Implement Agent  │ │  │ │ Implement Agent  │ │  │ │ Implement Agent  │ │
│ │       ↓          │ │  │ │       ↓          │ │  │ │       ↓          │ │
│ │ Check Agent      │ │  │ │ Check Agent      │ │  │ │ Check Agent      │ │
│ │       ↓          │ │  │ │       ↓          │ │  │ │       ↓          │ │
│ │ create_pr.py     │ │  │ │ create_pr.py     │ │  │ │ create_pr.py     │ │
│ └──────────────────┘ │  │ └──────────────────┘ │  │ └──────────────────┘ │
│                      │  │                      │  │                      │
│ Session: abc123      │  │ Session: def456      │  │ Session: ghi789      │
│ PID: 12345           │  │ PID: 12346           │  │ PID: 12347           │
└──────────────────────┘  └──────────────────────┘  └──────────────────────┘

Location: ../worktrees/  (default)

---

Git Worktree

What is a Worktree?

Git worktrees allow multiple working directories from one repository:

/project/                              # Main repo (main branch)
/project/../worktrees/                 # Default: ../worktrees
├── feature/add-login/                # Worktree 1 (own branch)
├── feature/user-profile/             # Worktree 2 (own branch)
└── fix/api-bug/                      # Worktree 3 (own branch)

Benefits

---

Configuration

worktree.yaml

Location: .trellis/worktree.yaml

# Where worktrees are created (relative to project)
# Default: ../worktrees
worktree_dir: ../worktrees

# Files to copy to each worktree (default: [])
copy:
  - .trellis/.developer # Developer identity
  - .env # Environment variables
  - .env.local # Local overrides

# Commands after worktree creation (default: [])
post_create:
  - npm install # Install dependencies
  # - pnpm install --frozen-lockfile

# Verification commands for Ralph Loop (default: [])
verify:
  - pnpm lint
  - pnpm typecheck

Task Configuration

Each session needs a configured task:

// task.json
{
  "branch": "feature/add-login", // Required for worktree
  "base_branch": "main",
  "worktree_path": null, // Set by start.py
  "current_phase": 0,
  "next_action": [
    { "phase": 1, "action": "implement" },
    { "phase": 2, "action": "check" },
    { "phase": 3, "action": "finish" },
    { "phase": 4, "action": "create-pr" }
  ]
}

---

Scripts

start.py - Start Session

Creates worktree and starts agent.

python3 .trellis/scripts/multi_agent/start.py <task-dir>

Actions:

1. Read task.json for branch name 2. Create git worktree:

   git worktree add -b <branch> ../trellis-worktrees/<branch>

3. Copy files from worktree.yaml copy list 4. Copy task directory to worktree 5. Run post_create hooks 6. Set .trellis/.current-task in worktree 7. Start Claude Dispatch Agent:

   claude -p --agent dispatch \
     --session-id <uuid> \
     --dangerously-skip-permissions \
     --output-format stream-json \
     --verbose "Start the pipeline"

8. Register to registry.json

Example:

python3 .trellis/scripts/multi_agent/start.py .trellis/tasks/01-31-add-login-taosu
# Output: Started agent in ../trellis-worktrees/feature/add-login

---

status.py - Monitor Sessions

Check all running sessions.

# Overview
python3 .trellis/scripts/multi_agent/status.py

# Detailed view
python3 .trellis/scripts/multi_agent/status.py --detail <task-name>

# Watch mode
python3 .trellis/scripts/multi_agent/status.py --watch <task-name>

# View logs
python3 .trellis/scripts/multi_agent/status.py --log <task-name>

# Show registry
python3 .trellis/scripts/multi_agent/status.py --registry

Output:

Active Sessions:
┌──────────────┬──────────┬────────────────┬──────────┬───────────┐
│ Task         │ Status   │ Phase          │ Elapsed  │ Files     │
├──────────────┼──────────┼────────────────┼──────────┼───────────┤
│ add-login    │ Running  │ 2/4 (check)    │ 15m 32s  │ 5 changed │
│ fix-api      │ Stopped  │ 1/4 (implement)│ 8m 15s   │ 2 changed │
└──────────────┴──────────┴────────────────┴──────────┴───────────┘

Resume stopped sessions:
  cd ../trellis-worktrees/feature/fix-api && claude --resume <session-id>

---

create_pr.py - Create PR

Creates PR from worktree changes.

python3 .trellis/scripts/multi_agent/create_pr.py [--dry-run]

Actions:

1. Stage changes: git add -A 2. Exclude: git reset .trellis/workspace/ 3. Commit: feat(<scope>): <task-name> 4. Push to remote 5. Create Draft PR: gh pr create --draft 6. Update task.json: status: "completed", pr_url

---

cleanup.py - Remove Worktrees

Clean up after completion.

# Specific worktree
python3 .trellis/scripts/multi_agent/cleanup.py <branch-name>

# All merged worktrees
python3 .trellis/scripts/multi_agent/cleanup.py --merged

# All worktrees (with confirmation)
python3 .trellis/scripts/multi_agent/cleanup.py --all

Actions:

1. Archive task to .trellis/tasks/archive/YYYY-MM/ 2. Remove from registry 3. Remove worktree: git worktree remove <path> 4. Optionally delete branch

---

plan.py - Auto-Configure Task

Launches Plan Agent to create task configuration.

python3 .trellis/scripts/multi_agent/plan.py \
  --name <task-slug> \
  --type <backend|frontend|fullstack> \
  --requirement "<description>"

Plan Agent:

1. Evaluates requirements (can REJECT) 2. Calls Research Agent 3. Creates prd.md 4. Configures task.json 5. Initializes JSONL files

---

Session Registry

Tracks all running sessions.

Location: .trellis/workspace/<developer>/.agents/registry.json

{
  "agents": [
    {
      "id": "feature-add-login",
      "worktree_path": "/abs/path/to/trellis-worktrees/feature/add-login",
      "pid": 12345,
      "started_at": "2026-01-31T10:30:00",
      "task_dir": ".trellis/tasks/01-31-add-login-taosu"
    }
  ]
}

API (common/registry.py):

registry_add_agent(agent_id, worktree_path, pid, task_dir)
registry_remove_by_id(agent_id)
registry_remove_by_worktree(worktree_path)
registry_search_agent(pattern)
registry_list_agents()

---

Complete Workflow

1. Configure Task

# Create task
python3 .trellis/scripts/task.py create "Add login" --slug add-login

# Configure
python3 .trellis/scripts/task.py init-context <task-dir> fullstack
python3 .trellis/scripts/task.py set-branch <task-dir> feature/add-login

# Write prd.md
# ...

2. Start Session

python3 .trellis/scripts/multi_agent/start.py <task-dir>

3. Monitor

python3 .trellis/scripts/multi_agent/status.py --watch add-login

4. After Completion

# PR auto-created
# Review on GitHub, merge

# Cleanup
python3 .trellis/scripts/multi_agent/cleanup.py feature/add-login

---

Parallel Execution

Start multiple sessions:

# Session 1
python3 .trellis/scripts/multi_agent/start.py .trellis/tasks/01-31-add-login

# Session 2 (immediately)
python3 .trellis/scripts/multi_agent/start.py .trellis/tasks/01-31-fix-api

# Session 3
python3 .trellis/scripts/multi_agent/start.py .trellis/tasks/01-31-update-docs

# Monitor all
python3 .trellis/scripts/multi_agent/status.py

Each runs independently:

• Own worktree
• Own branch
• Own Claude process
• Own registry entry

---

Resuming Sessions

If a session stops:

# Find session info
python3 .trellis/scripts/multi_agent/status.py --detail <task-name>

# Resume
cd ../trellis-worktrees/feature/task-name
claude --resume <session-id>

---

Ralph Loop

Quality enforcement for Check Agent in sessions.

Mechanism:

1. Check Agent completes 2. SubagentStop hook fires 3. ralph-loop.py runs verify commands 4. All pass → allow stop 5. Any fail → block, continue agent

Constants:

Configuration (worktree.yaml):

verify:
  - pnpm lint
  - pnpm typecheck

State (.trellis/.ralph-state.json):

{
  "task": ".trellis/tasks/01-31-add-login",
  "iteration": 2,
  "started_at": "2026-01-31T10:30:00"
}

Limits: Max 5 iterations (MAX_ITERATIONS), 30min timeout (STATE_TIMEOUT_MINUTES), 120s per command

---

Troubleshooting

Session Not Starting

1. Check worktree.yaml exists 2. Verify branch name doesn't exist 3. Check post_create hooks 4. Look at start.py output

Session Stuck

1. Check Ralph Loop iteration (max 5) 2. Verify verify commands 3. Manually run verify commands 4. Check .trellis/.ralph-state.json

Worktree Issues

# Force remove
git worktree remove --force <path>

# Prune stale
git worktree prune

# List all
git worktree list

Registry Out of Sync

# View
python3 .trellis/scripts/multi_agent/status.py --registry

# Manual edit
vim .trellis/workspace/<dev>/.agents/registry.json

Claude Code Features Overview

These features require Claude Code (or iFlow, which shares the same hook system) and don't work on other platforms.

---

Why Claude Code Only?

Claude Code provides unique capabilities:

---

Feature Categories

Hooks System

Automatic context injection and quality enforcement.

→ See hooks.md

Agent System

Specialized agents for different development phases.

→ See agents.md

Ralph Loop

Quality enforcement for Check Agent.

• Runs verify commands when Check Agent stops
• Blocks completion until all pass
• Max 5 iterations, 30min timeout

→ See ralph-loop.md

Multi-Session

Parallel isolated sessions using Git worktrees.

• Each session in separate worktree
• Own branch, own Claude process
• Automated PR creation

→ See multi-session.md

worktree.yaml

Configuration for Multi-Session and Ralph Loop.

→ See worktree-config.md

---

Documents in This Directory

---

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                      CLAUDE CODE INTEGRATION                             │
│                                                                          │
│  ┌────────────────┐    ┌────────────────┐    ┌────────────────┐        │
│  │  SessionStart  │    │  PreToolUse    │    │  SubagentStop  │        │
│  │     Hook       │    │     Hook       │    │     Hook       │        │
│  └───────┬────────┘    └───────┬────────┘    └───────┬────────┘        │
│          │                     │                     │                  │
│          ▼                     ▼                     ▼                  │
│  ┌────────────────┐    ┌────────────────┐    ┌────────────────┐        │
│  │ session-start  │    │ inject-context │    │  ralph-loop    │        │
│  │     .py        │    │     .py        │    │     .py        │        │
│  └───────┬────────┘    └───────┬────────┘    └───────┬────────┘        │
│          │                     │                     │                  │
│          ▼                     ▼                     ▼                  │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                     CORE SYSTEMS (File-Based)                    │   │
│  │  Workspace  │  Tasks  │  Specs  │  Commands  │  Scripts          │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

---

Checking Claude Code Availability

# Check if Claude Code is installed
claude --version

# Verify hooks are configured
cat .claude/settings.json | grep -A 5 '"hooks"'

If hooks aren't present, Claude Code features won't work.

Ralph Loop

Quality enforcement mechanism for Check Agent.

---

Overview

Ralph Loop prevents Check Agent from stopping until all verification commands pass.

┌─────────────────────────────────────────────────────────────────────────┐
│                           RALPH LOOP                                     │
│                                                                          │
│  Check Agent completes                                                   │
│         │                                                                │
│         ▼                                                                │
│  SubagentStop hook fires ──► ralph-loop.py runs                         │
│         │                                                                │
│         ▼                                                                │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  Run verify commands from worktree.yaml:                         │    │
│  │                                                                  │    │
│  │    pnpm lint        → exit 0 ✓                                   │    │
│  │    pnpm typecheck   → exit 0 ✓                                   │    │
│  │    pnpm test        → exit 1 ✗                                   │    │
│  │                                                                  │    │
│  │  Result: FAIL (test failed)                                      │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│         │                                                                │
│         ▼                                                                │
│  ┌─────────────────┐              ┌─────────────────┐                   │
│  │   All pass?     │──── YES ────►│  Allow stop     │                   │
│  └────────┬────────┘              └─────────────────┘                   │
│           │ NO                                                           │
│           ▼                                                              │
│  ┌─────────────────┐                                                    │
│  │  Block stop     │ ◄─── Agent continues to fix issues                 │
│  │  Inject errors  │                                                    │
│  └─────────────────┘                                                    │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

---

Configuration

worktree.yaml

verify:
  - pnpm lint
  - pnpm typecheck
  # - pnpm test
  # - pnpm build

---

Constants

---

State File

.trellis/.ralph-state.json

Tracks loop state across iterations.

{
  "task": ".trellis/tasks/01-31-add-login",
  "iteration": 2,
  "started_at": "2026-01-31T10:30:00"
}

---

Flow

Iteration 1

1. Check Agent completes work 2. SubagentStop hook fires 3. ralph-loop.py creates state file (iteration=1) 4. Runs verify commands 5. If fail: block stop, inject error messages 6. Check Agent continues fixing

Iteration 2-5

1. Check Agent tries to stop again 2. Hook reads state file, increments iteration 3. Runs verify commands again 4. Repeat until pass or max iterations

Max Iterations Reached

1. Iteration 5 still fails 2. Hook allows stop (prevents infinite loop) 3. Logs warning about unresolved issues

Timeout

1. State file older than 30 minutes 2. Hook resets state (fresh start) 3. Treats as iteration 1

---

Verify Commands

Execution Order

Commands run in config order. First failure stops execution.

verify:
  - pnpm lint # Runs first (fast)
  - pnpm typecheck # Runs second
  - pnpm test # Runs third (slow)

Recommendation: Order fast → slow

Exit Codes

• Exit 0 = Pass
• Non-zero = Fail

Timeout

Each command has 120 second timeout. Long-running tests may need:

• Splitting into smaller test suites
• Running only fast tests in Ralph Loop
• Adjusting COMMAND_TIMEOUT in script

---

Fallback: Completion Markers

If worktree.yaml has no verify config, Ralph Loop uses completion markers.

How It Works

1. Read check.jsonl for reason fields 2. Generate expected markers: {REASON}_FINISH 3. Check agent output for all markers 4. Missing marker = block stop

Example

{"file": "...", "reason": "typecheck"}
{"file": "...", "reason": "lint"}

Expected markers:

• TYPECHECK_FINISH
• LINT_FINISH

---

Debugging

Check State

cat .trellis/.ralph-state.json

Manual Verify

# Run verify commands manually
pnpm lint && pnpm typecheck && pnpm test

Reset State

rm .trellis/.ralph-state.json

View Hook Output

Check agent output for Ralph Loop messages:

• "Verification passed" = all commands succeeded
• "Verification failed" = blocking, shows errors
• "Max iterations reached" = giving up

---

Customizing

Add Test Verification

verify:
  - pnpm lint
  - pnpm typecheck
  - pnpm test

Add Build Verification

verify:
  - pnpm lint
  - pnpm typecheck
  - pnpm build

Different Languages

Go:

verify:
  - go fmt ./...
  - go vet ./...
  - go test ./...

Python:

verify:
  - ruff check .
  - mypy .
  - pytest

Rust:

verify:
  - cargo fmt --check
  - cargo clippy
  - cargo test

---

Disabling Ralph Loop

To disable for a project:

1. Remove verify from worktree.yaml 2. Or remove SubagentStop hook from settings.json

Warning: Without Ralph Loop, code quality isn't automatically enforced.

Claude Code Scripts

Scripts that require Claude Code CLI and hook system.

---

Overview

These scripts require:

• claude CLI command
• Hook system for context injection
• --resume for session persistence

.trellis/scripts/
├── common/
│   ├── worktree.py         # Worktree utilities
│   └── registry.py         # Agent registry
│
└── multi_agent/            # Multi-Session scripts
    ├── plan.py             # Launch Plan agent
    ├── start.py            # Start worktree agent
    ├── status.py           # Monitor agents
    ├── create_pr.py        # Create pull request
    └── cleanup.py          # Cleanup worktree

---

Multi-Session Scripts

multi_agent/plan.py

Launch Plan Agent to create task configuration.

python3 .trellis/scripts/multi_agent/plan.py \
  --name <task-name> \
  --type <dev-type> \
  --requirement "<requirement text>"

Options:

• --name - Task slug
• --type - frontend, backend, fullstack
• --requirement - Task description

Actions:

1. Creates task directory 2. Launches Plan Agent via claude 3. Plan Agent can REJECT unclear requirements 4. Creates prd.md, task.json, JSONL files

---

multi_agent/start.py

Start agent in a new worktree.

python3 .trellis/scripts/multi_agent/start.py <task-dir>

Actions:

1. Read task.json for branch name 2. Create git worktree:

   git worktree add -b <branch> ../worktrees/<branch>

3. Copy files from worktree.yaml copy list 4. Copy task directory to worktree 5. Run post_create commands 6. Set .trellis/.current-task 7. Start Claude Dispatch Agent:

   claude -p --agent dispatch \
     --session-id <uuid> \
     --dangerously-skip-permissions \
     --output-format stream-json \
     "Start the pipeline"

8. Register to registry.json

---

multi_agent/status.py

Monitor running sessions.

# Overview of all sessions
python3 .trellis/scripts/multi_agent/status.py

# Detailed view
python3 .trellis/scripts/multi_agent/status.py --detail <task-name>

# Watch mode (auto-refresh)
python3 .trellis/scripts/multi_agent/status.py --watch <task-name>

# View logs
python3 .trellis/scripts/multi_agent/status.py --log <task-name>

# Show registry
python3 .trellis/scripts/multi_agent/status.py --registry

Output:

Active Sessions:
┌──────────────┬──────────┬────────────────┬──────────┬───────────┐
│ Task         │ Status   │ Phase          │ Elapsed  │ Files     │
├──────────────┼──────────┼────────────────┼──────────┼───────────┤
│ add-login    │ Running  │ 2/4 (check)    │ 15m 32s  │ 5 changed │
│ fix-api      │ Stopped  │ 1/4 (implement)│ 8m 15s   │ 2 changed │
└──────────────┴──────────┴────────────────┴──────────┴───────────┘

---

multi_agent/create_pr.py

Create pull request from worktree changes.

python3 .trellis/scripts/multi_agent/create_pr.py [--dry-run]

Actions:

1. Stage changes: git add -A 2. Exclude workspace: git reset .trellis/workspace/ 3. Commit with conventional format 4. Push to remote 5. Create Draft PR via gh pr create --draft 6. Update task.json with pr_url

---

multi_agent/cleanup.py

Clean up completed worktrees.

# Specific worktree
python3 .trellis/scripts/multi_agent/cleanup.py <branch-name>

# All merged worktrees
python3 .trellis/scripts/multi_agent/cleanup.py --merged

# All worktrees (with confirmation)
python3 .trellis/scripts/multi_agent/cleanup.py --all

Actions:

1. Archive task to .trellis/tasks/archive/YYYY-MM/ 2. Remove from registry 3. Remove worktree: git worktree remove <path> 4. Optionally delete branch

---

Common Utilities

common/worktree.py

Worktree management utilities.

from common.worktree import (
    read_worktree_config,  # Read worktree.yaml
    get_worktree_path,     # Get path for branch
    create_worktree,       # Create new worktree
    remove_worktree,       # Remove worktree
)

common/registry.py

Agent registry for tracking running sessions.

from common.registry import (
    registry_add_agent,       # Add agent to registry
    registry_remove_by_id,    # Remove by agent ID
    registry_remove_by_worktree,  # Remove by path
    registry_search_agent,    # Search by pattern
    registry_list_agents,     # List all agents
)

Registry file: .trellis/workspace/<developer>/.agents/registry.json

{
  "agents": [
    {
      "id": "feature-add-login",
      "worktree_path": "/abs/path/to/worktrees/feature/add-login",
      "pid": 12345,
      "started_at": "2026-01-31T10:30:00",
      "task_dir": ".trellis/tasks/01-31-add-login-taosu"
    }
  ]
}

---

Claude CLI Usage

Agent Mode

claude --agent dispatch "Start the pipeline"

Print Mode (non-interactive)

claude -p "Do something"

Session Resume

claude --resume <session-id>

Automation Mode

claude --dangerously-skip-permissions -p "..."

JSON Output

claude --output-format stream-json -p "..."

---

Resuming Stopped Sessions

# Find session info
python3 .trellis/scripts/multi_agent/status.py --detail <task-name>

# Resume in worktree
cd ../worktrees/feature/task-name
claude --resume <session-id>

worktree.yaml Configuration Reference

Complete guide to .trellis/worktree.yaml configuration.

---

Overview

worktree.yaml configures both Multi-Session (worktree isolation) and some Multi-Agent behaviors (like Ralph Loop).

# .trellis/worktree.yaml

# Multi-Session only
worktree_dir: ../worktrees # Default value
copy:
  - .trellis/.developer
  - .env
post_create:
  - npm install

# Both Multi-Session AND Multi-Agent
verify:
  - pnpm lint
  - pnpm typecheck

Note: Trellis uses a custom YAML parser (not PyYAML). Supports basic key-value pairs and arrays; complex nested structures may not work.

---

Configuration Sections

Which Config Affects What?

Key point: verify config applies to BOTH modes!

---

Full Configuration

# =============================================================================
# MULTI-SESSION ONLY - Only used in worktree mode
# =============================================================================

# Worktree creation location (relative to project root)
# Default: ../worktrees
worktree_dir: ../worktrees

# Files to copy to each worktree
# These files are not in git, need manual copy
# Default: [] (empty array)
copy:
  - .trellis/.developer # Developer identity
  - .env # Environment variables
  - .env.local # Local overrides
  # - .npmrc                  # npm config
  # - credentials.json        # Credential files

# Commands to run after worktree creation
# Runs in order, stops on first failure
# Default: [] (empty array)
post_create:
  - npm install # or pnpm install
  # - pnpm install --frozen-lockfile
  # - cp .env.example .env
  # - npm run db:migrate

# =============================================================================
# BOTH MODES - Used in both Multi-Agent and Multi-Session
# =============================================================================

# Verification commands - Used by Ralph Loop
# Runs when Check Agent stops
# All must pass to allow stop
# Default: [] (empty array)
verify:
  - pnpm lint
  - pnpm typecheck
  # - pnpm test
  # - pnpm build

Default Values

---

Scenario: Multi-Agent in Current Directory

Requirement: Run dispatch → implement → check in current directory, no worktree

worktree.yaml config:

# These can be omitted (not used in current directory mode)
# worktree_dir: ...
# copy: ...
# post_create: ...

# This is needed! Ralph Loop uses it
verify:
  - pnpm lint
  - pnpm typecheck

Workflow:

1. Set .trellis/.current-task 2. Call Task(subagent_type="implement") 3. Call Task(subagent_type="check") 4. When Check Agent completes, Ralph Loop runs verify commands 5. Human commits

---

Scenario: Custom Workflows

Add test verification

verify:
  - pnpm lint
  - pnpm typecheck
  - pnpm test # Add tests

Add build verification

verify:
  - pnpm lint
  - pnpm typecheck
  - pnpm build # Add build check

Go projects

verify:
  - go fmt ./...
  - go vet ./...
  - go test ./...

Python projects

verify:
  - ruff check .
  - mypy .
  - pytest

Rust projects

verify:
  - cargo fmt --check
  - cargo clippy
  - cargo test

---

Scenario: Custom Worktree Creation

Different package managers

post_create:
  # npm
  - npm install

  # or pnpm
  # - pnpm install --frozen-lockfile

  # or yarn
  # - yarn install --frozen-lockfile

  # or bun
  # - bun install

Database migrations required

post_create:
  - pnpm install
  - pnpm db:migrate
  - pnpm db:seed

Code generation required

post_create:
  - pnpm install
  - pnpm codegen
  - pnpm prisma generate

Copy additional files

copy:
  - .trellis/.developer
  - .env
  - .env.local
  - .npmrc # npm private registry config
  - firebase-credentials.json # Firebase credentials
  - google-cloud-key.json # GCP credentials

---

When worktree.yaml is Missing

If worktree.yaml doesn't exist:

Ralph Loop fallback behavior:

• Without verify config, uses completion markers
• Generates markers from check.jsonl reason field
• Example: {"reason": "typecheck"} → expects TYPECHECK_FINISH

---

Minimal Configuration

Multi-Agent only (current directory)

# .trellis/worktree.yaml
verify:
  - pnpm lint
  - pnpm typecheck

Multi-Session only (worktree)

# .trellis/worktree.yaml
worktree_dir: ../worktrees
copy:
  - .trellis/.developer
post_create:
  - npm install
verify:
  - pnpm lint
  - pnpm typecheck

---

Complete Examples

Node.js/TypeScript Project

worktree_dir: ../worktrees

copy:
  - .trellis/.developer
  - .env
  - .env.local

post_create:
  - pnpm install --frozen-lockfile

verify:
  - pnpm lint
  - pnpm typecheck
  - pnpm test

Python Project

worktree_dir: ../worktrees

copy:
  - .trellis/.developer
  - .env
  - venv/ # or recreate venv

post_create:
  - python -m venv venv
  - ./venv/bin/pip install -r requirements.txt

verify:
  - ./venv/bin/ruff check .
  - ./venv/bin/mypy .
  - ./venv/bin/pytest

Go Project

worktree_dir: ../worktrees

copy:
  - .trellis/.developer
  - .env

post_create:
  - go mod download

verify:
  - go fmt ./...
  - go vet ./...
  - golangci-lint run
  - go test ./...

Monorepo Project

worktree_dir: ../worktrees

copy:
  - .trellis/.developer
  - .env
  - .npmrc

post_create:
  - pnpm install --frozen-lockfile
  - pnpm -r build # Build all packages

verify:
  - pnpm -r lint
  - pnpm -r typecheck
  - pnpm -r test

---

Verification Command Notes

Ralph Loop Constants

Timeout

Each verify command has 120 seconds (2 minutes) timeout. Long-running tests may need:

• Split tests
• Run only fast tests
• Modify COMMAND_TIMEOUT constant in ralph-loop.py

Exit Codes

• Exit code 0 = Pass
• Non-zero = Fail, blocks Check Agent from stopping

Order

Commands run in config order, stops on first failure.

Recommended order: fast → slow

verify:
  - pnpm lint # Fast (seconds)
  - pnpm typecheck # Medium (seconds-minutes)
  - pnpm test # Slow (minutes)

---

YAML Parser Notes

Trellis uses a custom YAML parser (not PyYAML) with these limitations:

Supported Syntax

# Simple key-value
worktree_dir: ../worktrees

# Arrays (2-space indent, starts with -)
copy:
  - .trellis/.developer
  - .env

# Quoted values
worktree_dir: "../worktrees with spaces"

Unsupported Syntax

# ❌ Inline arrays
copy: [.env, .npmrc]

# ❌ Complex nesting
nested:
  key:
    subkey: value

# ❌ Multi-line strings
description: |
  Multiple
  lines

---

Debugging Configuration

View current config

cat .trellis/worktree.yaml

Test verify commands

# Manual run
pnpm lint && pnpm typecheck

# Or view Ralph Loop state
cat .trellis/.ralph-state.json

View worktree status

git worktree list

Ralph Loop debugging

# View state file
cat .trellis/.ralph-state.json

# Example output
# {
#   "task": ".trellis/tasks/01-31-add-login",
#   "iteration": 2,
#   "started_at": "2026-01-31T10:30:00"
# }

# Ralph Loop auto-stops when exceeding MAX_ITERATIONS (5) or STATE_TIMEOUT_MINUTES (30)

Configuration Reference

Complete reference for .trellis/config.yaml.

---

Overview

config.yaml is the project-level configuration file for Trellis. All values have sensible hardcoded defaults — if the file is missing or a key is absent, the default is used.

Read by: common/config.py

---

Full Schema

# --- Session ---
# Commit message used when auto-committing journal/index changes
session_commit_message: 'chore: record journal'

# Maximum lines per journal file before rotating to a new one
max_journal_lines: 2000

# --- Monorepo Packages ---
packages:
  <package-name>:
    path: <relative-path>          # Required. Path relative to repo root
    type: local                    # Optional. "local" (default) or "submodule"
    git: false                     # Optional. true if package has own git repo
    tags:                          # Optional. Tags for filtering (e.g., [backend, unit-test])
      - <tag>

# Default package when --package is omitted
default_package: <package-name>

# --- Update ---
update:
  skip:                            # Files/dirs to permanently exclude from `trellis update`
    - <path>

# --- Task Lifecycle Hooks ---
hooks:
  after_create:                    # Shell commands run after task creation
    - <command>
  after_start:                     # Shell commands run after task start
    - <command>
  after_finish:                    # Shell commands run after task finish
    - <command>
  after_archive:                   # Shell commands run after task archive
    - <command>

# --- Session Context ---
session:
  spec_scope: active_task          # Control which packages' specs are scanned
                                   # Options: "active_task" | list of package names | null (all)

---

Section Details

Session Settings

Monorepo Packages

Declares packages in a monorepo. If absent or empty, the project is treated as single-repo.

packages:
  cli:
    path: packages/cli
    tags: [backend, unit-test]
  docs-site:
    path: docs-site
    type: submodule
    tags: [docs]
default_package: cli

Package types:

`git: true`: Marks packages with their own independent git repo. Session context shows branch, working directory status, and recent commits for these packages.

Effect on spec system: When packages are configured, specs live at .trellis/spec/<package>/<layer>/ instead of .trellis/spec/<layer>/.

Update Skip

Permanently exclude files or directories from trellis update:

update:
  skip:
    - .trellis/spec/custom/
    - .claude/commands/trellis/my-command.md

Task Lifecycle Hooks

Shell commands executed after task lifecycle events. Task info is passed via the TASK_JSON_PATH environment variable.

hooks:
  after_create:
    - python3 .trellis/scripts/hooks/linear_sync.py create
  after_start:
    - python3 .trellis/scripts/hooks/linear_sync.py start
  after_archive:
    - python3 .trellis/scripts/hooks/linear_sync.py archive

Events:

Environment variables available to hook commands:

Session Spec Scope

Control which packages' specs are scanned during session start:

session:
  spec_scope: active_task    # Only scan the package of the current task

---

Example: Full config.yaml

session_commit_message: 'chore: record journal'
max_journal_lines: 2000

packages:
  cli:
    path: packages/cli
    tags: [backend, unit-test]
  docs-site:
    path: docs-site
    type: submodule
    tags: [docs]

default_package: cli

update:
  skip:
    - .trellis/spec/custom-internal/

hooks:
  after_create:
    - python3 .trellis/scripts/hooks/linear_sync.py create
  after_start:
    - python3 .trellis/scripts/hooks/linear_sync.py start
  after_archive:
    - python3 .trellis/scripts/hooks/linear_sync.py archive

session:
  spec_scope: active_task

Trellis File Reference

Complete reference of all files in the .trellis/ directory.

---

Directory Structure

.trellis/
├── .developer              # Developer identity (gitignored)
├── .current-task           # Active task pointer (gitignored)
├── .ralph-state.json       # Ralph Loop state (gitignored)
├── .template-hashes.json   # Template version tracking
├── .version                # Installed Trellis version
├── .gitignore              # Git ignore rules
├── workflow.md             # Main workflow documentation
├── config.yaml             # Project-level configuration (packages, hooks, etc.)
├── worktree.yaml           # Multi-session configuration
│
├── workspace/              # Developer workspaces
├── tasks/                  # Task tracking (with subtask support)
├── spec/                   # Coding guidelines (monorepo: per-package)
└── scripts/                # Automation scripts
    ├── common/             # Shared utilities (19 modules)
    ├── hooks/              # Task lifecycle hook scripts
    └── multi_agent/        # Multi-agent pipeline scripts

---

Root Files

.developer

Purpose: Store current developer identity.

Created by: init_developer.py

Format: Plain text, single line with developer name.

taosu

Gitignored: Yes - each machine has its own identity.

---

.current-task

Purpose: Point to the active task directory.

Created by: task.py start <task-dir>

Format: Plain text, relative path to task directory.

.trellis/tasks/01-31-add-login-taosu

Gitignored: Yes - each developer works on different tasks.

Used by:

• Hooks read this to find task context
• Scripts use this for current task operations

---

.ralph-state.json

Purpose: Track Ralph Loop iteration state.

Created by: ralph-loop.py (Claude Code only)

Format: JSON

{
  "task": ".trellis/tasks/01-31-add-login",
  "iteration": 2,
  "started_at": "2026-01-31T10:30:00"
}

Gitignored: Yes - runtime state.

Fields:

---

.template-hashes.json

Purpose: Track template file versions for trellis update.

Created by: trellis init or trellis update

Format: JSON object mapping file paths to SHA-256 hashes.

{
  ".trellis/workflow.md": "028891d1fe839a266...",
  ".claude/hooks/session-start.py": "0a9899e80f6bfe15...",
  ".claude/commands/start.md": "d1276dcbff880299..."
}

Used by:

• trellis update - Detect which files have been modified
• Determines if files can be auto-updated or need conflict resolution

Behavior:

• File hash matches template → Safe to update
• File hash differs → User modified, needs manual merge

---

.version

Purpose: Track installed Trellis CLI version.

Created by: trellis init or trellis update

Format: Plain text, semver version string.

0.4.0-beta.8

Used by:

• trellis update - Determine if update is needed
• Version mismatch detection

---

.gitignore

Purpose: Define which files to exclude from git.

Default content:

# Developer identity (local only)
.developer

# Current task pointer
.current-task

# Ralph Loop state
.ralph-state.json

# Agent runtime files
.agents/
.agent-log
.agent-runner.sh
.session-id

# Task directory runtime files
.plan-log

# Atomic update temp files
*.tmp
.backup-*
*.new

# Python cache
**/__pycache__/
**/*.pyc

---

workflow.md

Purpose: Main workflow documentation for developers and AI.

Created by: trellis init

Content sections:

1. Quick Start guide 2. Workflow overview 3. Session start process 4. Development process 5. Session end 6. File descriptions 7. Best practices

Injected by: session-start.py hook (Claude Code)

For Cursor: Read manually at session start.

---

config.yaml

Purpose: Project-level Trellis configuration.

Created by: trellis init

Format: YAML

# Session settings
session_commit_message: 'chore: record journal'
max_journal_lines: 2000

# Monorepo packages
packages:
  cli:
    path: packages/cli
    tags: [backend, unit-test]
  docs-site:
    path: docs-site
    type: submodule
    tags: [docs]
default_package: cli

# Update exclusions
update:
  skip:
    - .trellis/spec/custom/

# Task lifecycle hooks
hooks:
  after_create:
    - python3 .trellis/scripts/hooks/linear_sync.py create
  after_start:
    - python3 .trellis/scripts/hooks/linear_sync.py start
  after_archive:
    - python3 .trellis/scripts/hooks/linear_sync.py archive

# Session context scope
session:
  spec_scope: active_task

Used by: common/config.py

Behavior: All values have sensible hardcoded defaults. If config.yaml is missing or a key is absent, the default is used.

→ See core/config.md for full schema reference.

---

worktree.yaml

Purpose: Configure Multi-Session and Ralph Loop.

Created by: trellis init

Format: YAML

worktree_dir: ../worktrees
copy:
  - .trellis/.developer
  - .env
post_create:
  - npm install
verify:
  - pnpm lint
  - pnpm typecheck

→ See claude-code/worktree-config.md for details.

---

Runtime Files (Gitignored)

.agents/

Purpose: Agent registry for Multi-Session.

Location: .trellis/workspace/{developer}/.agents/

Content: registry.json tracking running agents.

---

.session-id

Purpose: Store Claude Code session ID for resume.

Created by: Multi-Session start.py

Format: UUID string.

---

.agent-log

Purpose: Agent execution log.

Created by: Multi-Session scripts.

---

.plan-log

Purpose: Plan Agent execution log.

Location: Task directory.

---

Directories

workspace/

Developer workspaces with journals and indexes.

→ See core/workspace.md

tasks/

Task directories with PRDs and context files.

→ See core/tasks.md

spec/

Coding guidelines and specifications.

→ See core/specs.md

scripts/

Automation scripts.

→ See core/scripts.md and claude-code/scripts.md

---

Template Files

These files are managed by trellis update:

Update behavior:

1. Compare file hash with .template-hashes.json 2. If unchanged → Auto-update 3. If modified → Create .new file for manual merge 4. If user-deleted → Skip (respects intentional deletion) 5. Update hashes after successful update

Protected paths (never touched by update/migration):

• .trellis/workspace/
• .trellis/spec/
• .trellis/tasks/

Exclusions: Files listed in update.skip in config.yaml are permanently excluded.

---

File Lifecycle

Created by trellis init

.trellis/
├── .template-hashes.json
├── .version
├── .gitignore
├── workflow.md
├── config.yaml
├── worktree.yaml
├── spec/                    # Single repo: frontend/, backend/, guides/
│   └── ...                  # Monorepo: <package>/<layer>/, guides/
└── scripts/
    ├── common/
    ├── hooks/
    └── multi_agent/

Created at runtime

.trellis/
├── .developer           # init_developer.py
├── .current-task        # task.py start
├── .ralph-state.json    # ralph-loop.py
├── workspace/{dev}/     # init_developer.py
│   ├── index.md
│   ├── journal-1.md
│   └── .agents/
└── tasks/{task}/        # task.py create
    ├── task.json
    ├── prd.md
    └── *.jsonl

Cleaned up

# After task completion
.trellis/tasks/{task}/ → .trellis/tasks/archive/YYYY-MM/

# After worktree removal
.agents/registry.json entries removed

Core Systems Overview

These systems work on all 11 platforms (Claude Code, Cursor, OpenCode, iFlow, Codex, Kilo, Kiro, Gemini CLI, Antigravity, Qoder, CodeBuddy).

---

What's in Core?

---

Why These Are Portable

All core systems are file-based:

• No special runtime required
• Read/write with any tool
• Works in any AI coding environment

┌─────────────────────────────────────────────────────────────┐
│                    CORE SYSTEMS (File-Based)                 │
│                                                              │
│  .trellis/                                                   │
│  ├── workspace/     → Journals, session history              │
│  ├── tasks/         → Task directories, PRDs, subtasks       │
│  ├── spec/          → Coding guidelines (monorepo support)   │
│  ├── config.yaml    → Packages, hooks, update.skip           │
│  └── scripts/       → Python utilities (core subset)         │
│                                                              │
│  .claude/                                                    │
│  └── commands/      → Slash command prompts                  │
│                                                              │
│  .agents/                                                    │
│  └── skills/        → Shared agent skills (agentskills.io)   │
│                                                              │
└─────────────────────────────────────────────────────────────┘

---

Platform Usage

Claude Code

All core systems work automatically with hook integration.

iFlow

All core systems work automatically with hook integration (same as Claude Code).

Codex

Core systems work with optional SessionStart hook and TOML agents. See meta/platform-compatibility.md.

Cursor, OpenCode, Kilo, Kiro, Gemini CLI, Antigravity, Qoder, CodeBuddy

Read files manually at session start:

1. Read .trellis/workflow.md 2. Read relevant specs from .trellis/spec/ 3. Check .trellis/.current-task for active work 4. Read JSONL files for context

---

Documents in This Directory

Core Scripts

Platform-independent Python scripts for Trellis automation.

---

Overview

These scripts work on all platforms — they only read/write files and don't require Claude Code's hook system.

.trellis/scripts/
├── common/                  # Shared utilities (19 modules)
│   ├── __init__.py
│   ├── paths.py             # Path constants
│   ├── types.py             # Core type definitions (TaskData, AgentRecord)
│   ├── developer.py         # Developer management
│   ├── config.py            # config.yaml reader
│   ├── io.py                # I/O utilities
│   ├── log.py               # Logging with colors
│   ├── git.py               # Git command utilities
│   ├── git_context.py       # Git and session context shim
│   ├── session_context.py   # Session context generation
│   ├── packages_context.py  # Package discovery (monorepo)
│   ├── tasks.py             # Task loading and iteration
│   ├── task_utils.py        # Task utilities (resolve, hooks)
│   ├── task_store.py        # Task store ops (create, archive, subtasks)
│   ├── task_queue.py        # Task queue (list by status/assignee)
│   ├── task_context.py      # JSONL context management
│   ├── phase.py             # Phase tracking
│   ├── registry.py          # Agent registry (registry.json)
│   ├── worktree.py          # Worktree utilities
│   └── cli_adapter.py       # Multi-platform CLI adapter
│
├── hooks/                   # Task lifecycle hook scripts
│   └── linear_sync.py       # Linear issue sync
│
├── init_developer.py        # Initialize developer
├── get_developer.py         # Get developer name
├── get_context.py           # Get session context
├── task.py                  # Task management CLI (16 subcommands)
├── add_session.py           # Record session
└── create_bootstrap.py      # First-time spec bootstrap

---

Developer Scripts

init_developer.py

Initialize developer identity.

python3 .trellis/scripts/init_developer.py <name>

Creates:

• .trellis/.developer
• .trellis/workspace/<name>/
• .trellis/workspace/<name>/index.md
• .trellis/workspace/<name>/journal-1.md

---

get_developer.py

Get current developer name.

python3 .trellis/scripts/get_developer.py
# Output: taosu

Exit codes:

• 0 - Success
• 1 - Not initialized

---

Context Scripts

get_context.py

Get session context for AI consumption.

python3 .trellis/scripts/get_context.py              # Default mode (text)
python3 .trellis/scripts/get_context.py --json        # JSON output
python3 .trellis/scripts/get_context.py --mode record    # For record-session
python3 .trellis/scripts/get_context.py --mode packages  # Package info only

Modes:

Output includes:

• Developer identity
• Git status and recent commits
• Current task (if any)
• Active tasks list
• Workspace summary
• Package info (monorepo)

---

add_session.py

Record session entry to journal.

python3 .trellis/scripts/add_session.py \
  --title "Session Title" \
  --commit "hash1,hash2" \
  --summary "Brief summary"

Options:

• --title - Session title (required)
• --commit - Comma-separated commit hashes
• --summary - Brief summary
• --content-file - Path to file with detailed content
• --no-commit - Skip auto-commit of workspace changes
• --package - Package name (monorepo)

Actions:

1. Appends to current journal 2. Updates index markers 3. Rotates journal if >max_journal_lines 4. Auto-commits .trellis/workspace changes (unless --no-commit)

---

create_bootstrap.py

Create a bootstrap task for first-time setup.

python3 .trellis/scripts/create_bootstrap.py

Creates a task that guides filling in project-specific spec guidelines.

---

Task Scripts

task.py

Task management CLI with 16 subcommands.

Create Task

python3 .trellis/scripts/task.py create "Task name" --slug task-slug

Options:

• --slug - URL-safe identifier
• --assignee - Developer name (default: current)
• --priority - Priority level (P0, P1, P2, P3)
• --description - Task description
• --parent - Parent task directory (for subtasks)
• --package - Package name (monorepo)

List Tasks

python3 .trellis/scripts/task.py list
python3 .trellis/scripts/task.py list --mine          # My tasks only
python3 .trellis/scripts/task.py list --status active  # Filter by status

Start / Finish Task

python3 .trellis/scripts/task.py start <task-dir>   # Set .current-task
python3 .trellis/scripts/task.py finish              # Clear .current-task

Initialize Context

python3 .trellis/scripts/task.py init-context <task-dir> <dev-type>

Dev types: frontend, backend, fullstack, test, docs

Creates JSONL files with appropriate spec references. After initialization, outputs available spec files as hints.

Manage Context

python3 .trellis/scripts/task.py add-context <task-dir> <agent> <path> <reason>
python3 .trellis/scripts/task.py list-context <task-dir>
python3 .trellis/scripts/task.py validate <task-dir>

Agent types for add-context: implement, check, debug

Branch Management

python3 .trellis/scripts/task.py set-branch <task-dir> <branch-name>
python3 .trellis/scripts/task.py set-base-branch <task-dir> <base-branch>
python3 .trellis/scripts/task.py set-scope <task-dir> <scope>

Subtask Management

python3 .trellis/scripts/task.py create "Subtask" --parent <parent-dir>
python3 .trellis/scripts/task.py add-subtask <parent-dir> <child-dir>
python3 .trellis/scripts/task.py remove-subtask <parent-dir> <child-dir>

Archive and PR

python3 .trellis/scripts/task.py archive <task-dir>         # Auto-commits
python3 .trellis/scripts/task.py archive <task-dir> --no-commit
python3 .trellis/scripts/task.py list-archive [YYYY-MM]
python3 .trellis/scripts/task.py create-pr <task-dir>       # Delegates to multi_agent/create_pr.py

---

Hook Scripts

hooks/linear_sync.py

Syncs task lifecycle events to Linear via linearis CLI.

# Called automatically by task lifecycle hooks in config.yaml
python3 .trellis/scripts/hooks/linear_sync.py create
python3 .trellis/scripts/hooks/linear_sync.py start
python3 .trellis/scripts/hooks/linear_sync.py archive

Environment variable: TASK_JSON_PATH — path to the task's task.json.

---

Common Utilities

Core Types (common/types.py)

from common.types import TaskData, TaskInfo, AgentRecord

• TaskData — TypedDict for task.json fields
• TaskInfo — Extended task info with directory path
• AgentRecord — Agent registry entry

Paths (common/paths.py)

from common.paths import (
    TRELLIS_DIR,      # .trellis/
    WORKSPACE_DIR,    # .trellis/workspace/
    TASKS_DIR,        # .trellis/tasks/
    SPEC_DIR,         # .trellis/spec/
)

Developer (common/developer.py)

from common.developer import (
    get_developer,     # Get current developer name
    get_workspace_dir, # Get developer's workspace directory
)

Config (common/config.py)

from common.config import (
    get_session_commit_message,  # Commit message for auto-commit
    get_max_journal_lines,       # Max lines per journal file
    get_packages,                # Monorepo package dict or None
    get_default_package,         # Default package name
    is_monorepo,                 # Check if packages are configured
    get_submodule_packages,      # Packages with type: submodule
    get_git_packages,            # Packages with git: true
    get_spec_base,               # "spec" or "spec/<package>"
    get_spec_scope,              # Session spec scope setting
)

Task Modules

from common.task_utils import (
    resolve_task_dir,   # Resolve task directory from name
    run_task_hooks,     # Execute task lifecycle hooks
)

from common.task_store import (
    create_task,        # Create new task directory
    archive_task,       # Archive completed task
    add_subtask,        # Link child to parent
    remove_subtask,     # Unlink child from parent
)

from common.task_queue import (
    list_by_status,     # List tasks by status
    list_by_assignee,   # List tasks by assignee
)

from common.task_context import (
    init_context,       # Create JSONL files for a task
    add_context,        # Add entry to a JSONL file
    validate_context,   # Validate JSONL files
    list_context,       # List JSONL entries
)

Git (common/git.py)

from common.git import run_git  # Execute git commands

I/O and Logging

from common.io import read_file, write_file  # File operations
from common.log import info, warn, error     # Colored logging

Multi-Platform (common/cli_adapter.py)

Abstracts CLI differences between all 11 platforms for the multi-agent pipeline.

from common.cli_adapter import get_cli_adapter  # Get platform-specific adapter

---

Usage Examples

Initialize New Developer

cd /path/to/project
python3 .trellis/scripts/init_developer.py john-doe

Create and Start Task

# Create task
python3 .trellis/scripts/task.py create "Add user login" --slug add-login

# Initialize context for fullstack work
python3 .trellis/scripts/task.py init-context \
  .trellis/tasks/03-24-add-login fullstack

# Start task
python3 .trellis/scripts/task.py start \
  .trellis/tasks/03-24-add-login

Create Subtask

# Create a child task under an existing parent
python3 .trellis/scripts/task.py create "Login API endpoint" \
  --slug login-api --parent .trellis/tasks/03-24-add-login

Record Session

python3 .trellis/scripts/add_session.py \
  --title "Implement login form" \
  --commit "abc1234" \
  --summary "Added login form, pending API integration"

Archive Completed Task

python3 .trellis/scripts/task.py archive \
  .trellis/tasks/03-24-add-login

Spec System

Maintain coding standards that guide AI development. Supports single-repo and monorepo layouts with dynamic discovery.

---

Directory Structure

Single Repo

.trellis/spec/
├── frontend/                   # Frontend guidelines
│   ├── index.md                # Overview and quick reference
│   ├── component-guidelines.md
│   └── ...
│
├── backend/                    # Backend guidelines
│   ├── index.md
│   ├── directory-structure.md
│   └── ...
│
└── guides/                     # Thinking guides (shared)
    ├── index.md
    ├── cross-layer-thinking-guide.md
    ├── code-reuse-thinking-guide.md
    └── cross-platform-thinking-guide.md

Monorepo (Per-Package)

When packages: is defined in config.yaml, specs are organized per-package:

.trellis/spec/
├── cli/                        # Package: cli
│   ├── backend/
│   │   ├── index.md
│   │   └── *.md
│   └── unit-test/
│       ├── index.md
│       └── *.md
│
├── docs-site/                  # Package: docs-site
│   └── docs/
│       ├── index.md
│       └── *.md
│
└── guides/                     # Shared across all packages
    ├── index.md
    └── *.md

Discovery: python3 .trellis/scripts/get_context.py --mode packages lists all packages, paths, types, and spec layers.

---

Spec Categories

Package-Specific Layers

Each package can have its own set of layers (subdirectories):

Guides (guides/)

Cross-cutting thinking guides shared across all packages:

• How to think about cross-layer changes
• Code reuse strategies
• Platform considerations

---

Index Files

Each layer has an index.md that:

1. Provides category overview 2. Lists all specs with links 3. Includes a Pre-Development Checklist 4. Includes a Quality Check section

Example: cli/backend/index.md

# Backend Development Guidelines

## Guidelines Index

| Guide | Description | Status |
|-------|-------------|--------|
| [Directory Structure](./directory-structure.md) | Module organization | Done |
| [Error Handling](./error-handling.md) | Error strategies | Done |

## Pre-Development Checklist

Before writing backend code, read:
- Error handling → error-handling.md
- Logging → logging-guidelines.md

## Quality Check

After writing code:
1. Run `pnpm lint && pnpm typecheck`
2. Check relevant guidelines

---

Dynamic Spec Discovery

The session-start hook dynamically discovers spec directories instead of hardcoding frontend/backend/guides:

1. Iterates all subdirectories under .trellis/spec/ 2. For monorepo: iterates spec/<package>/<layer>/ 3. Reads index.md from each discovered layer 4. Injects all found indexes into session context

This means adding a new spec category only requires creating the directory — no hook modification needed.

Spec Scope Filtering

In monorepo projects, session.spec_scope in config.yaml controls which packages' specs are loaded:

session:
  spec_scope: active_task    # Only load specs for the current task's package

---

Using Specs

In JSONL Context Files

Reference specs in task context:

{"file": ".trellis/spec/cli/backend/index.md", "reason": "Backend overview"}
{"file": ".trellis/spec/cli/backend/error-handling.md", "reason": "Error patterns"}

Manual Reading (Non-Hook Platforms)

Read specs at session start:

1. Read .trellis/spec/{package}/{layer}/index.md
2. Follow the Pre-Development Checklist
3. Read specific guidelines as needed

---

Creating New Specs

1. Choose Location

• Single repo: .trellis/spec/<layer>/
• Monorepo: .trellis/spec/<package>/<layer>/

2. Create Spec File

touch .trellis/spec/cli/backend/new-pattern.md

3. Follow Format

````markdown

[Spec Title]

Overview

Brief description.

Guidelines

1. [Guideline Name]

Do:

// Good example

Don't:

// Bad example

Related Specs

• Related Spec

````

4. Update Index

Add to the layer's index.md Guidelines Index table.

5. Reference in JSONL

Add to relevant task context files.

---

Best Practices

1. Keep specs focused - One topic per file 2. Use examples - Show do/don't patterns 3. Link related specs - Cross-reference 4. Update regularly - Specs evolve with codebase 5. Index everything - Keep index files current 6. Guides are shared - Put cross-package concerns in guides/

Task System

Track work items with phase-based execution, parent-child subtasks, and lifecycle hooks.

---

Directory Structure

.trellis/tasks/
├── {MM-DD-slug}/                  # Active task directories
│   ├── task.json                  # Metadata, phases, branch, subtasks
│   ├── prd.md                     # Requirements document
│   ├── info.md                    # Technical design (optional)
│   ├── implement.jsonl            # Context for implement phase
│   ├── check.jsonl                # Context for check phase
│   ├── debug.jsonl                # Context for debug phase
│   ├── research.jsonl             # Context for research phase (optional)
│   └── cr.jsonl                   # Context for code review (optional)
│
└── archive/                       # Completed tasks
    └── {YYYY-MM}/
        └── {task-dir}/

---

Task Directory Naming

Format: {MM-DD}-{slug}

Examples:

• 03-24-add-login
• 03-10-fix-api-bug

---

task.json

Task metadata and workflow configuration.

{
  "id": "03-24-add-login",
  "name": "Add user login",
  "title": "Add user login",
  "description": "Implement email/password authentication",
  "status": "planning",
  "dev_type": "fullstack",
  "scope": "auth",
  "package": "cli",
  "priority": "P1",
  "creator": "taosu",
  "assignee": "taosu",
  "createdAt": "2026-03-24T10:30:00",
  "completedAt": null,
  "branch": "feature/add-login",
  "base_branch": "main",
  "worktree_path": null,
  "current_phase": 1,
  "next_action": [
    { "phase": 1, "action": "implement" },
    { "phase": 2, "action": "check" },
    { "phase": 3, "action": "finish" }
  ],
  "commit": null,
  "pr_url": null,
  "children": [],
  "parent": null,
  "subtasks": [],
  "relatedFiles": [],
  "notes": "",
  "meta": {}
}

Fields

---

prd.md

Requirements document for the task.

# Add User Login

## Goal
Implement user authentication with email/password.

## Requirements
- Login form with email and password fields
- Form validation
- API endpoint for authentication

## Acceptance Criteria
- [ ] User can log in with valid credentials
- [ ] Error shown for invalid credentials

## Technical Notes
- Use existing auth service pattern

---

JSONL Context Files

List files to inject as context for each agent phase.

Format

{"file": ".trellis/spec/backend/index.md", "reason": "Backend guidelines"}
{"file": "src/services/auth.ts", "reason": "Existing pattern"}
{"file": ".trellis/tasks/03-24-add-login/prd.md", "reason": "Requirements"}

Files

---

Subtasks

Tasks can have parent-child relationships for decomposing complex work.

Create Subtask

# Option 1: Create with --parent flag
python3 .trellis/scripts/task.py create "Login API" --parent .trellis/tasks/03-24-add-login

# Option 2: Link existing tasks
python3 .trellis/scripts/task.py add-subtask <parent-dir> <child-dir>

Behavior

• Parent's children array contains child directory names
• Child's parent field points to parent directory name
• task.py list shows subtask hierarchy
• Unlinking: task.py remove-subtask <parent-dir> <child-dir>

---

Task Lifecycle Hooks

Shell commands that run automatically after task lifecycle events.

Configuration (config.yaml)

hooks:
  after_create:
    - python3 .trellis/scripts/hooks/linear_sync.py create
  after_start:
    - python3 .trellis/scripts/hooks/linear_sync.py start
  after_finish:
    - python3 .trellis/scripts/hooks/linear_sync.py finish
  after_archive:
    - python3 .trellis/scripts/hooks/linear_sync.py archive

Events

Environment

Hook commands receive TASK_JSON_PATH — the absolute path to the task's task.json.

Built-in Hook: Linear Sync

Ships with hooks/linear_sync.py that syncs task events to Linear via the linearis CLI tool.

---

Current Task Pointer

.trellis/.current-task

Points to active task directory.

.trellis/tasks/03-24-add-login

Set Current Task

python3 .trellis/scripts/task.py start <task-dir>

Clear Current Task

python3 .trellis/scripts/task.py finish

---

Task CLI (16 Subcommands)

---

Workflow Phases

Standard phase progression:

1. implement  →  Write code
2. check      →  Review and fix
3. finish     →  Final verification
4. create-pr  →  Create pull request (Multi-Session only)

Custom Phases

Modify next_action in task.json:

"next_action": [
  {"phase": 1, "action": "research"},
  {"phase": 2, "action": "implement"},
  {"phase": 3, "action": "check"}
]

---

Best Practices

1. One task at a time - Use .current-task to track focus 2. Clear PRDs - Write specific, testable requirements 3. Relevant context - Only include needed files in JSONL 4. Archive completed - Keep task directory clean 5. Use subtasks - Decompose complex work into trackable units 6. Configure lifecycle hooks - Integrate with external issue trackers

How To: Change Verify Commands

Add or modify Ralph Loop verification commands.

Platform: Claude Code only (Ralph Loop)

---

Files to Modify

---

Step 1: Edit worktree.yaml

Open .trellis/worktree.yaml and modify the verify section:

verify:
  - pnpm lint
  - pnpm typecheck
  - pnpm test # Add this

---

Common Scenarios

Add Test Verification

verify:
  - pnpm lint
  - pnpm typecheck
  - pnpm test

Add Build Verification

verify:
  - pnpm lint
  - pnpm typecheck
  - pnpm build

Add Specific Test Suite

verify:
  - pnpm lint
  - pnpm typecheck
  - pnpm test:unit # Fast unit tests only

Different Languages

Go:

verify:
  - go fmt ./...
  - go vet ./...
  - golangci-lint run
  - go test ./...

Python:

verify:
  - ruff check .
  - mypy .
  - pytest -x

Rust:

verify:
  - cargo fmt --check
  - cargo clippy
  - cargo test

---

Execution Details

Order

Commands run in order. First failure stops execution.

Recommended order: fast → slow

verify:
  - pnpm lint # ~2 seconds
  - pnpm typecheck # ~10 seconds
  - pnpm test:unit # ~30 seconds
  - pnpm build # ~60 seconds

Timeout

Each command has 120 second timeout.

For long-running commands:

• Split into smaller chunks
• Use faster subset for Ralph Loop
• Run full suite manually

Exit Codes

• Exit 0 = Pass
• Non-zero = Fail, agent continues

---

Testing

Manual Test

# Run commands manually
pnpm lint && pnpm typecheck && pnpm test

# Should all pass for Ralph Loop to allow stop

Integration Test

1. Make a change that fails linting 2. Run check agent 3. Verify Ralph Loop blocks and shows error 4. Fix the issue 5. Verify Ralph Loop allows stop

---

Troubleshooting

Command Not Found

Ensure command is available:

which pnpm  # or npm, yarn, etc.

Timeout Issues

Increase timeout in ralph-loop.py:

COMMAND_TIMEOUT = 180  # Default is 120

Skip Verify Temporarily

Comment out commands:

verify:
  - pnpm lint
  # - pnpm typecheck  # Skip temporarily

---

Checklist

• [ ] Commands added to worktree.yaml
• [ ] Commands tested manually
• [ ] Order is fast → slow
• [ ] No timeout issues