eryao/.trellis/workflow.md

Development Workflow

Based on Effective Harnesses for Long-Running Agents

---

Table of Contents

1. Quick Start (Do This First)
2. Workflow Overview
3. Session Start Process
4. Development Process
5. Session End
6. File Descriptions
7. Best Practices

---

Quick Start (Do This First)

Step 0: Initialize Developer Identity (First Time Only)

Multi-developer support: Each developer/Agent needs to initialize their identity first

# Check if already initialized
python3 ./.trellis/scripts/get_developer.py

# If not initialized, run:
python3 ./.trellis/scripts/init_developer.py <your-name>
# Example: python3 ./.trellis/scripts/init_developer.py cursor-agent

This creates:

• .trellis/.developer - Your identity file (gitignored, not committed)
• .trellis/workspace/<your-name>/ - Your personal workspace directory

Naming suggestions:

• Human developers: Use your name, e.g., john-doe
• Cursor AI: cursor-agent or cursor-<task>
• Claude Code: claude-agent or claude-<task>
• iFlow cli: iflow-agent or iflow-<task>

Step 1: Understand Current Context

# Get full context in one command
python3 ./.trellis/scripts/get_context.py

# Or check manually:
python3 ./.trellis/scripts/get_developer.py      # Your identity
python3 ./.trellis/scripts/task.py list          # Active tasks
git status && git log --oneline -10              # Git state

Step 2: Read Project Guidelines [MANDATORY]

CRITICAL: Read guidelines before writing any code:

# Read frontend guidelines index (if applicable)
cat .trellis/spec/frontend/index.md

# Read backend guidelines index (if applicable)
cat .trellis/spec/backend/index.md

Why read both?

• Understand the full project architecture
• Know coding standards for the entire codebase
• See how frontend and backend interact
• Learn the overall code quality requirements

Step 3: Before Coding - Read Specific Guidelines (Required)

Based on your task, read the detailed guidelines:

Frontend Task:

cat .trellis/spec/frontend/hook-guidelines.md      # For hooks
cat .trellis/spec/frontend/component-guidelines.md # For components
cat .trellis/spec/frontend/type-safety.md          # For types

Backend Task:

cat .trellis/spec/backend/database-guidelines.md   # For DB operations
cat .trellis/spec/backend/type-safety.md           # For types
cat .trellis/spec/backend/logging-guidelines.md    # For logging

---

Workflow Overview

Core Principles

1. Read Before Write - Understand context before starting
2. Follow Standards - [!] MUST read .trellis/spec/ guidelines before coding
3. Incremental Development - Complete one task at a time
4. Record Promptly - Update tracking files immediately after completion
5. Document Limits - [!] Max 2000 lines per journal document

Development Environment

Cloud Supabase Setup:

1. Configure .env with Supabase Cloud credentials:

   ERYAO_SUPABASE__PUBLIC_URL=https://<project-ref>.supabase.co
   ERYAO_DATABASE__HOST=aws-1-us-east-2.pooler.supabase.com
   ERYAO_DATABASE__PORT=5432  # Session pooler
   

2. Start Redis (required for backend):

   cd infra/docker && docker compose up -d redis
   

3. Run database migrations:

   ./infra/scripts/dev-migrate.sh bootstrap
   

4. Start backend server:

   ./infra/scripts/app.sh start
   

Note: Local Supabase is no longer used. All development uses Supabase Cloud.

File System

.trellis/
|-- .developer           # Developer identity (gitignored)
|-- scripts/
|   |-- __init__.py          # Python package init
|   |-- common/              # Shared utilities (Python)
|   |   |-- __init__.py
|   |   |-- paths.py         # Path utilities
|   |   |-- developer.py     # Developer management
|   |   +-- git_context.py   # Git context implementation
|   |-- multi_agent/         # Multi-agent pipeline scripts
|   |   |-- __init__.py
|   |   |-- start.py         # Start worktree agent
|   |   |-- status.py        # Monitor agent status
|   |   |-- create_pr.py     # Create PR
|   |   +-- cleanup.py       # Cleanup worktree
|   |-- init_developer.py    # Initialize developer identity
|   |-- get_developer.py     # Get current developer name
|   |-- task.py              # Manage tasks
|   |-- get_context.py       # Get session context
|   +-- add_session.py       # One-click session recording
|-- workspace/           # Developer workspaces
|   |-- index.md         # Workspace index + Session template
|   +-- {developer}/     # Per-developer directories
|       |-- index.md     # Personal index (with @@@auto markers)
|       +-- journal-N.md # Journal files (sequential numbering)
|-- tasks/               # Task tracking
|   +-- {MM}-{DD}-{name}/
|       +-- task.json
|-- spec/                # [!] MUST READ before coding
|   |-- frontend/        # Frontend guidelines (if applicable)
|   |   |-- index.md               # Start here - guidelines index
|   |   +-- *.md                   # Topic-specific docs
|   |-- backend/         # Backend guidelines (if applicable)
|   |   |-- index.md               # Start here - guidelines index
|   |   +-- *.md                   # Topic-specific docs
|   +-- guides/          # Thinking guides
|       |-- index.md                      # Guides index
|       |-- cross-layer-thinking-guide.md # Pre-implementation checklist
|       +-- *.md                          # Other guides
+-- workflow.md             # This document

---

Session Start Process

Step 1: Get Session Context

Use the unified context script:

# Get all context in one command
python3 ./.trellis/scripts/get_context.py

# Or get JSON format
python3 ./.trellis/scripts/get_context.py --json

Step 2: Read Development Guidelines [!] REQUIRED

[!] CRITICAL: MUST read guidelines before writing any code

Based on what you'll develop, read the corresponding guidelines:

Frontend Development (if applicable):

# Read index first, then specific docs based on task
cat .trellis/spec/frontend/index.md

Backend Development (if applicable):

# Read index first, then specific docs based on task
cat .trellis/spec/backend/index.md

Cross-Layer Features:

# For features spanning multiple layers
cat .trellis/spec/guides/cross-layer-thinking-guide.md

Step 3: Select Task to Develop

Use the task management script:

# List active tasks
python3 ./.trellis/scripts/task.py list

# Create new task (creates directory with task.json)
python3 ./.trellis/scripts/task.py create "<title>" --slug <task-name>

---

Development Process

Task Development Flow

1. Create or select task
   --> python3 ./.trellis/scripts/task.py create "<title>" --slug <name> or list

2. Write code according to guidelines
   --> Read .trellis/spec/ docs relevant to your task
   --> For cross-layer: read .trellis/spec/guides/

3. Self-test
   --> Run project's lint/test commands (see spec docs)
   --> Manual feature testing

4. Commit code
   --> git add <files>
   --> git commit -m "type(scope): description"
       Format: feat/fix/docs/refactor/test/chore

5. Record session (one command)
   --> python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash"

Code Quality Checklist

Must pass before commit:

• [OK] Lint checks pass (project-specific command)
• [OK] Type checks pass (if applicable)
• [OK] Manual feature testing passes

Project-specific checks:

• See .trellis/spec/frontend/quality-guidelines.md for frontend
• See .trellis/spec/backend/quality-guidelines.md for backend

---

Session End

One-Click Session Recording

After code is committed, use:

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

This automatically:

1. Detects current journal file
2. Creates new file if 2000-line limit exceeded
3. Appends session content
4. Updates index.md (sessions count, history table)

Pre-end Checklist

Use /trellis:finish-work command to run through:

1. [OK] All code committed, commit message follows convention
2. [OK] Session recorded via add_session.py
3. [OK] No lint/test errors
4. [OK] Working directory clean (or WIP noted)
5. [OK] Spec docs updated if needed

---

File Descriptions

1. workspace/ - Developer Workspaces

Purpose: Record each AI Agent session's work content

Structure (Multi-developer support):

workspace/
|-- index.md              # Main index (Active Developers table)
+-- {developer}/          # Per-developer directory
    |-- index.md          # Personal index (with @@@auto markers)
    +-- journal-N.md      # Journal files (sequential: 1, 2, 3...)

When to update:

• [OK] End of each session
• [OK] Complete important task
• [OK] Fix important bug

2. spec/ - Development Guidelines

Purpose: Documented standards for consistent development

Structure (Multi-doc format):

spec/
|-- frontend/           # Frontend docs (if applicable)
|   |-- index.md        # Start here
|   +-- *.md            # Topic-specific docs
|-- backend/            # Backend docs (if applicable)
|   |-- index.md        # Start here
|   +-- *.md            # Topic-specific docs
+-- guides/             # Thinking guides
    |-- index.md        # Start here
    +-- *.md            # Guide-specific docs

When to update:

• [OK] New pattern discovered
• [OK] Bug fixed that reveals missing guidance
• [OK] New convention established

3. Tasks - Task Tracking

Each task is a directory containing task.json:

tasks/
|-- 01-21-my-task/
|   +-- task.json
+-- archive/
    +-- 2026-01/
        +-- 01-15-old-task/
            +-- task.json

Commands:

python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>]   # Create task directory
python3 ./.trellis/scripts/task.py archive <name>  # Archive to archive/{year-month}/
python3 ./.trellis/scripts/task.py list            # List active tasks
python3 ./.trellis/scripts/task.py list-archive    # List archived tasks

---

Best Practices

[OK] DO - Should Do

1. Before session start:

   • Run python3 ./.trellis/scripts/get_context.py for full context
   • [!] MUST read relevant .trellis/spec/ docs

2. During development:

   • [!] Follow .trellis/spec/ guidelines
   • For cross-layer features, use /trellis:check-cross-layer
   • Develop only one task at a time
   • Run lint and tests frequently

3. After development complete:

   • Use /trellis:finish-work for completion checklist
   • After fix bug, use /trellis:break-loop for deep analysis
   • Human commits after testing passes
   • Use add_session.py to record progress

[X] DON'T - Should Not Do

1. [!] Don't skip reading .trellis/spec/ guidelines
2. [!] Don't let journal single file exceed 2000 lines
3. Don't develop multiple unrelated tasks simultaneously
4. Don't commit code with lint/test errors
5. Don't forget to update spec docs after learning something
6. [!] Don't execute git commit - AI should not commit code

---

Quick Reference

Must-read Before Development

Task Type	Must-read Document
Frontend work	frontend/index.md → relevant docs
Backend work	backend/index.md → relevant docs
Cross-Layer Feature	guides/cross-layer-thinking-guide.md

Commit Convention

git commit -m "type(scope): description"

Type: feat, fix, docs, refactor, test, chore Scope: Module name (e.g., auth, api, ui)

Common Commands

# Session management
python3 ./.trellis/scripts/get_context.py    # Get full context
python3 ./.trellis/scripts/add_session.py    # Record session

# Task management
python3 ./.trellis/scripts/task.py list      # List tasks
python3 ./.trellis/scripts/task.py create "<title>" # Create task

# Slash commands
/trellis:finish-work          # Pre-commit checklist
/trellis:break-loop           # Post-debug analysis
/trellis:check-cross-layer    # Cross-layer verification

---

Summary

Following this workflow ensures:

• [OK] Continuity across multiple sessions
• [OK] Consistent code quality
• [OK] Trackable progress
• [OK] Knowledge accumulation in spec docs
• [OK] Transparent team collaboration

Core Philosophy: Read before write, follow standards, record promptly, capture learnings

[workflow-state:no_task] No active task. A Direct answer — pure Q&A / explanation / lookup / chat; no file writes + one-line answer + repo reads ≤ 2 files → AI judges, no override needed. B Create a task — any implementation / code change / build / refactor work. Entry sequence: (1) python3 ./.trellis/scripts/task.py create "<title>" to create the task (status=planning, breadcrumb switches to [workflow-state:planning] for brainstorm + jsonl phase guidance) → (2) load trellis-brainstorm skill to discuss requirements with the user and iterate on prd.md → (3) once prd is done and jsonl is curated, run task.py start <task-dir> to enter [workflow-state:in_progress] for the implementation skeleton. For research-heavy work, dispatch trellis-research sub-agents — main agent must NOT do 3+ inline WebFetch / WebSearch / gh api calls. "It looks small" is NOT grounds for downgrading B to A or C. C Inline change (per-turn only, escape hatch for B) — the user's CURRENT message MUST contain one of: "skip trellis" / "no task" / "just do it" / "don't create a task" / "跳过 trellis" / "别走流程" / "小修一下" / "直接改" / "先别建任务" → briefly acknowledge ("ok, skipping trellis flow this turn"), then inline. Without seeing one of these phrases you must NOT inline on your own; do not invent an override the user never said. [/workflow-state:no_task]

[workflow-state:planning] Load the trellis-brainstorm skill and iterate on prd.md with the user. Phase 1.3 (required, once): before task.py start, you MUST curate implement.jsonl and check.jsonl — list the spec / research files sub-agents need so they get the right context injected. You may skip only if the jsonl already has agent-curated entries (the seed _example row alone doesn't count). Then run task.py start <task-dir> to flip status to in_progress. Research output must land in {task_dir}/research/*.md, written by trellis-research sub-agents. The main agent should not inline WebFetch / WebSearch — the PRD only links to research files. [/workflow-state:planning]

[workflow-state:in_progress] Flow: trellis-implement → trellis-check → trellis-update-spec → commit (Phase 3.4) → /trellis:finish-work. Default (no override): dispatch the trellis-implement / trellis-check sub-agents — the main agent does NOT edit code by default. Phase 3.4 commit (required, once): after trellis-update-spec, or whenever implementation is verifiably complete, the main agent drives the commit — state the commit plan in user-facing text, then run git commit — BEFORE suggesting /trellis:finish-work. /finish-work refuses to run on a dirty working tree (paths outside .trellis/workspace/ and .trellis/tasks/). Sub-agent dispatch protocol (class-2 platforms: codex / copilot / gemini / qoder): When you spawn trellis-implement / trellis-check / trellis-research, your dispatch prompt MUST start with one line: Active task: <task path from \task.py current`>`. No exceptions. These platforms have no hook to inject task context into sub-agents, so the sub-agent depends on this line; without it the sub-agent cannot find the task and will block to ask the user. Inline override (per-turn only, escape hatch for sub-agent dispatch): the user's CURRENT message MUST explicitly contain one of: "do it inline" / "no sub-agent" / "你直接改" / "别派 sub-agent" / "main session 写就行" / "不用 sub-agent". Without seeing one of these phrases you must NOT inline on your own; do not invent an override the user never said. [/workflow-state:in_progress]

[workflow-state:completed] Code committed via Phase 3.4; run /trellis:finish-work to wrap up (archive the task + record session). If you reach this state with uncommitted code, return to Phase 3.4 first — /finish-work refuses to run on a dirty working tree. task.py archive deletes any runtime session files that still point at the archived task. [/workflow-state:completed]

[workflow-state:my-status] your per-turn prompt text [/workflow-state:my-status]