Commands, Upgrades, Tasks & Specs

trellis upgrade              # follows your current channel: latest / beta / rc
trellis upgrade --tag latest # explicitly install the latest stable release
trellis upgrade --dry-run    # print the npm command without running it

trellis update               # sync the project to the local CLI's templates
trellis update --dry-run     # preview changes without applying them
trellis update --migrate     # also apply file migrations (renames / relocations / deletes)

create → plan artifacts → optional jsonl context → start → implement/check → finish → archive

create:                task directory + task.json + default prd.md
plan artifacts:        prd.md for every task; design.md + implement.md before complex work starts
optional jsonl context: AI fills implement/check context when stable spec or research files must be injected
start:                 marks the task in_progress for this AI session/window
implement/check:       development and verification loop
finish:                clears this AI session/window's current task
archive:               moves completed task to archive/

# Create a task
TASK_DIR=$(./.trellis/scripts/task.py create "Add user login" \
  --slug user-login \          # Directory name suffix (optional, auto-slugifies otherwise)
  --assignee alice \           # Assignee (optional)
  --priority P1 \              # Priority: P0/P1/P2/P3 (optional, default P2)
  --description "Implement JWT login")  # Description (optional)

# Created directory: .trellis/tasks/02-27-user-login/
# Created files: task.json, prd.md
# May also create implement.jsonl + check.jsonl on sub-agent-capable platforms

# implement.jsonl + check.jsonl are seeded by `task.py create` on
# sub-agent-capable platforms. Each file starts with one self-describing
# `{"_example": "..."}` line you can leave in place or delete.

# Curate entries — either edit the jsonl in your editor, or use add-context:
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
  ".trellis/spec/backend/index.md" "Backend development guide"
./.trellis/scripts/task.py add-context "$TASK_DIR" check \
  ".trellis/spec/cli/unit-test/conventions.md" "Unit test conventions"
# target arg: implement | check (shorthand, auto-appends .jsonl)
# path arg: a file OR directory path — add-context auto-detects and sets type="directory" for dirs
#
# What to put in the jsonl: spec files (.trellis/spec/**/*.md) and research files
# ($TASK_DIR/research/*.md) relevant to this task. Do NOT add code paths — code
# is read during Phase 2 implementation, not pre-registered here.

# Discover what specs exist
./.trellis/scripts/get_context.py --mode packages

# Validate implement.jsonl + check.jsonl (all referenced files exist)
./.trellis/scripts/task.py validate "$TASK_DIR"

# View all JSONL entries
./.trellis/scripts/task.py list-context "$TASK_DIR"

# Set as the current task for this AI session/window
# Writes .trellis/.runtime/sessions/<session-key>.json
./.trellis/scripts/task.py start "$TASK_DIR"

# Clear the current task for this AI session/window
./.trellis/scripts/task.py finish

# Set Git branch name
./.trellis/scripts/task.py set-branch "$TASK_DIR" "feature/user-login"

# Set PR target branch
./.trellis/scripts/task.py set-base-branch "$TASK_DIR" "main"

# Set scope (used in commit messages: feat(scope): ...)
./.trellis/scripts/task.py set-scope "$TASK_DIR" "auth"

# Option A: create a child directly under a parent
./.trellis/scripts/task.py create "JWT middleware" \
  --slug jwt-middleware \
  --parent 02-27-user-login

# Option B: link two existing tasks
./.trellis/scripts/task.py add-subtask \
  02-27-user-login \                # parent directory
  02-28-jwt-middleware              # child directory

# Unlink (does not delete either task)
./.trellis/scripts/task.py remove-subtask \
  02-27-user-login 02-28-jwt-middleware

# List active tasks
./.trellis/scripts/task.py list
./.trellis/scripts/task.py list --mine            # Only your own
./.trellis/scripts/task.py list --status review   # Filter by status

# Archive completed tasks
./.trellis/scripts/task.py archive user-login
# Moves to archive/2026-02/

# List archived tasks
./.trellis/scripts/task.py list-archive
./.trellis/scripts/task.py list-archive 2026-02  # Filter by month

{
  "id": "02-27-user-login",
  "name": "user-login",
  "title": "Add user login",
  "description": "Implement JWT login flow",
  "status": "planning",
  "dev_type": null,
  "scope": null,
  "package": null,
  "priority": "P1",
  "creator": "alice",
  "assignee": "alice",
  "createdAt": "2026-02-27",
  "completedAt": null,
  "branch": null,
  "base_branch": "main",
  "worktree_path": null,
  "commit": null,
  "pr_url": null,
  "subtasks": [],
  "children": [],
  "parent": null,
  "relatedFiles": [],
  "notes": "",
  "meta": {}
}

task.py create        →  status: "planning"
task.py start         →  flips planning to in_progress (other statuses preserved)
task.py archive       →  status: "completed" + move to archive/

# implement.jsonl (right after task.py create)
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line when done."}

{"file": ".trellis/spec/guides/index.md", "reason": "Shared cross-package thinking guides"}
{"file": ".trellis/spec/cli/backend/index.md", "reason": "Backend dev guide — task touches Python scripts"}
{"file": ".trellis/spec/cli/backend/script-conventions.md", "reason": "Script conventions for the affected files"}
{"file": ".trellis/tasks/.../research/auth-library-comparison.md", "reason": "Library choice rationale"}

# Add implementation spec context
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
  ".trellis/spec/cli/backend/script-conventions.md" "Script conventions for this task"

# Add research produced during planning
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
  "$TASK_DIR/research/auth-library-comparison.md" "Library choice rationale"

# Add check context
./.trellis/scripts/task.py add-context "$TASK_DIR" check \
  ".trellis/spec/guides/cross-layer-thinking-guide.md" "Cross-layer verification"

hooks:
  after_create:
    - 'python3 .trellis/scripts/hooks/linear_sync.py create'
  after_start:
    - 'python3 .trellis/scripts/hooks/linear_sync.py start'
  after_finish:
    - "echo 'Task finished'"
  after_archive:
    - 'python3 .trellis/scripts/hooks/linear_sync.py archive'

{
  "linear": {
    "team": "ENG",
    "project": "My Project",
    "assignees": {
      "alice": "linear-user-id-for-alice"
    }
  }
}

.trellis/spec/
├── frontend/                    # Frontend specs (placeholders)
│   ├── index.md                 #   Index: lists all specs and their status
│   ├── component-guidelines.md  #   Component specs
│   ├── hook-guidelines.md       #   Hook specs
│   ├── state-management.md      #   State management
│   ├── type-safety.md           #   Type safety
│   ├── quality-guidelines.md    #   Quality guidelines
│   └── directory-structure.md   #   Directory structure
│
├── backend/                     # Backend specs (placeholders)
│   ├── index.md
│   ├── database-guidelines.md
│   ├── error-handling.md
│   ├── logging-guidelines.md
│   ├── quality-guidelines.md
│   └── directory-structure.md
│
└── guides/                      # Thinking guides
    ├── index.md
    ├── cross-layer-thinking-guide.md
    └── code-reuse-thinking-guide.md

.trellis/spec/                                # Trellis's own spec tree
├── cli/                                      # Package: CLI
│   ├── backend/
│   │   └── index.md                          #   ← layer registered via index.md
│   └── unit-test/
│       └── index.md                          #   ← another layer
│
├── docs-site/                                # Package: docs site
│   └── docs/
│       └── index.md                          #   ← single-layer package
│
└── guides/                                   # Cross-package thinking guides
    ├── index.md
    ├── cross-layer-thinking-guide.md
    ├── cross-platform-thinking-guide.md
    └── code-reuse-thinking-guide.md

# See how existing code is organized
ls src/components/     # Component structure
ls src/services/       # Service structure

# Component Guidelines

## File Structure

- One component per file
- Use PascalCase for filenames: `UserProfile.tsx`
- Co-locate styles: `UserProfile.module.css`
- Co-locate tests: `UserProfile.test.tsx`

## Patterns

#### Required

- Functional components + hooks (no class components)
- TypeScript with explicit Props interface
- `export default` for page components, named export for shared

#### Forbidden

- No `any` type in Props
- No inline styles (use CSS Modules)
- No direct DOM manipulation

#### Good Example

```tsx
interface UserProfileProps {
  userId: string;
  onUpdate: (user: User) => void;
}

export function UserProfile({ userId, onUpdate }: UserProfileProps) {
  // ...
}
```

#### Bad Example

```tsx
// Don't: no Props interface, using any
export default function UserProfile(props: any) {
  // ...
}
```

| Guideline            | File                    | Status     |
| -------------------- | ----------------------- | ---------- |
| Component Guidelines | component-guidelines.md | **Filled** |
| Hook Guidelines      | hook-guidelines.md      | To fill    |

#### Convention: Use ORM batch methods, never loop single-row DB calls

**What**: For any collection of N rows, call the ORM's batch method (`createMany`, `updateMany`, `deleteMany`) once. Never wrap a single-row `create` / `update` / `delete` in a `for` / `Promise.all` loop.

**Why**: Each DB call is a round-trip. In production, a 200-item loop inside a request handler is how p99 latency silently grows from 50ms to 8s — we've already caught this twice in code review (PRs #312, #417). Batch methods collapse N round-trips into one statement and let the DB plan the write.

**Example**:

```ts
// ✅ Correct — one round-trip
await prisma.user.createMany({ data: users });

// ❌ Wrong — N round-trips
for (const user of users) {
  await prisma.user.create({ data: user });
}

// ❌ Also wrong — still N round-trips, just parallel
await Promise.all(users.map((user) => prisma.user.create({ data: user })));
```

**When batch is not available**: wrap the loop in a single transaction (`prisma.$transaction`) so it's at least one logical unit; add a comment explaining why batch wasn't usable.

**Related**: `quality-guidelines.md#performance`, `error-handling.md#transactions`.

#### Database

- Use good query patterns
- Be careful with SQL
- Follow best practices

#### Variable Naming

- All boolean variables must start with `is` or `has`
- All arrays must end with `List`
- All functions must be less than 20 lines
- All files must be less than 200 lines