Understanding Trellis Through Kubernetes

If you’re familiar with Kubernetes, this document will help you quickly grasp Trellis’s design philosophy.

This article was written in the Trellis 0.4.x era. Some named concepts have changed since: the Ralph Loop, dispatch / plan / debug agents, and the Multi-Agent Pipeline were all removed during the 0.5.0 prerelease. The high-level K8s analogy still applies; read specific agent / hook names here as historical references.

K8s Core Concepts Overview
Trellis and K8s Analogy
Reconciliation Mechanism Deep Dive
Complete Workflow
Why This Design

1. K8s Core Concepts Overview

Imperative vs Declarative

Imperative: Describe “how to do it”

# 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”

# 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

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

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) │
└─────────────────────────────────────────────────────────────┘

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

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.

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:

{"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

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):

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

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

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

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.

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.

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.

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.

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.

​Table of Contents

​1. K8s Core Concepts Overview

​Imperative vs Declarative

​Control Loop

​2. Trellis and K8s Analogy

​Architecture Mapping

​Core Component Mapping

​Key Insight

​3. Reconciliation Mechanism Deep Dive

​Hook Injection

​Ralph Loop

​4. Complete Workflow

​Phase Overview

​Exception Path

​5. Why This Design

​One-Click Complete Workflow

​Continuous Accumulation of Development Guidelines

​Preventing Context Rot

​Programmatic Quality Control

​Traceability

​Summary

Table of Contents

1. K8s Core Concepts Overview

Imperative vs Declarative

Control Loop

2. Trellis and K8s Analogy

Architecture Mapping

Core Component Mapping

Key Insight

3. Reconciliation Mechanism Deep Dive

Hook Injection

Ralph Loop

4. Complete Workflow

Phase Overview

Exception Path

5. Why This Design

One-Click Complete Workflow

Continuous Accumulation of Development Guidelines

Preventing Context Rot

Programmatic Quality Control

Traceability

Summary