命令、任务与规范

create → curate jsonl → start → implement/check → finish → archive

create：         任务目录 + task.json + seed jsonl
curate jsonl：   AI 填 implement/check/research 上下文
start：          写入当前 AI 会话/窗口的任务
implement/check：开发与验证循环
finish：         清除当前 AI 会话/窗口的任务
archive：        把完成任务移动到 archive/

# 创建任务
TASK_DIR=$(./.trellis/scripts/task.py create "新增用户登录" \
  --slug user-login \          # 目录名后缀（可选，不写自动生成）
  --assignee alice \           # 负责人（可选）
  --priority P1 \              # 优先级：P0/P1/P2/P3（可选，默认 P2）
  --description "实现 JWT 登录")  # 描述（可选）

# 创建的目录：.trellis/tasks/02-27-user-login/
# 创建的文件：task.json

# sub-agent 平台上 implement.jsonl + check.jsonl 已在 task.py create 时
# seed 好了——每个文件起手一行自描述 {"_example": "..."}，可保留也可删除。

# curate 条目：在编辑器里改 jsonl，或用 add-context：
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
  ".trellis/spec/backend/index.md" "后端开发指南"
./.trellis/scripts/task.py add-context "$TASK_DIR" check \
  ".trellis/spec/cli/unit-test/conventions.md" "单测约定"
# target：implement | check（自动补 .jsonl）
# path：文件或目录路径——add-context 自动识别，目录会 type="directory"
#
# jsonl 里放什么：任务相关的 spec 文件（.trellis/spec/**/*.md）和 research
# 文件（$TASK_DIR/research/*.md）。不要放代码路径——代码在 Phase 2 实现时
# 读，不在这里预注册。

# 看有哪些 spec 可选
./.trellis/scripts/get_context.py --mode packages
# 可选：--package PACKAGE   （monorepo 必填，选 spec/<pkg>/ 根）

# 追加额外的上下文条目
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
  "src/services/auth.ts" "现有 auth 模式"
# file 参数：implement | check（简写，自动补 .jsonl）
# path 参数：文件 or 目录路径，add-context 自动识别目录并设 type="directory"

# 校验 implement.jsonl + check.jsonl 里引用的文件都存在
./.trellis/scripts/task.py validate "$TASK_DIR"

# 查看所有 JSONL 条目
./.trellis/scripts/task.py list-context "$TASK_DIR"

# 设为当前 AI 会话/窗口的任务
# 写入 .trellis/.runtime/sessions/<session-key>.json
./.trellis/scripts/task.py start "$TASK_DIR"

# 清除当前 AI 会话/窗口的任务
./.trellis/scripts/task.py finish

# 设置 Git 分支名
./.trellis/scripts/task.py set-branch "$TASK_DIR" "feature/user-login"

# 设置 PR 目标分支
./.trellis/scripts/task.py set-base-branch "$TASK_DIR" "main"

# 设置 scope（用在 commit message：feat(scope): ...）
./.trellis/scripts/task.py set-scope "$TASK_DIR" "auth"

# 方式 A：在父任务下直接建子任务
./.trellis/scripts/task.py create "JWT middleware" \
  --slug jwt-middleware \
  --parent 02-27-user-login

# 方式 B：把两个已有任务链起来
./.trellis/scripts/task.py add-subtask \
  02-27-user-login \                # 父任务目录
  02-28-jwt-middleware              # 子任务目录

# 解除关联（不会删除任何任务）
./.trellis/scripts/task.py remove-subtask \
  02-27-user-login 02-28-jwt-middleware

# 列出活跃任务
./.trellis/scripts/task.py list
./.trellis/scripts/task.py list --mine            # 只看自己的
./.trellis/scripts/task.py list --status review   # 按状态过滤

# 归档完成的任务
./.trellis/scripts/task.py archive user-login
# 移动到 archive/2026-02/

# 列出归档任务
./.trellis/scripts/task.py list-archive
./.trellis/scripts/task.py list-archive 2026-02  # 按月过滤

{
  "id": "02-27-user-login",
  "name": "user-login",
  "title": "新增用户登录",
  "description": "实现 JWT 登录流程",
  "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      →  planning 自动改写成 in_progress（其他状态保留）
task.py archive    →  status: "completed" + 移到 archive/

# task.py create 刚跑完的 implement.jsonl
{"_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": "跨包思维指引"}
{"file": ".trellis/spec/cli/backend/index.md", "reason": "后端开发指南——本次改动涉及 Python 脚本"}
{"file": ".trellis/spec/cli/backend/script-conventions.md", "reason": "脚本规范"}
{"file": ".trellis/tasks/.../research/auth-library-comparison.md", "reason": "三方库选型依据"}

# 把现有代码作为参考（文件）
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
  "src/services/user.ts" "现有 user service 模式"

# 整个目录（自动读所有 .md）
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
  "src/services/" "现有 service 模式"

# 自定义 check 上下文
./.trellis/scripts/task.py add-context "$TASK_DIR" check \
  ".trellis/spec/guides/cross-layer-thinking-guide.md" "跨层验证"

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": "我的项目",
    "assignees": {
      "alice": "linear-user-id-for-alice"
    }
  }
}

.trellis/spec/
├── frontend/                    # 前端规范（占位）
│   ├── index.md                 #   索引：列出所有规范及状态
│   ├── component-guidelines.md  #   组件规范
│   ├── hook-guidelines.md       #   Hook 规范
│   ├── state-management.md      #   状态管理
│   ├── type-safety.md           #   类型安全
│   ├── quality-guidelines.md    #   质量指南
│   └── directory-structure.md   #   目录结构
│
├── backend/                     # 后端规范（占位）
│   ├── index.md
│   ├── database-guidelines.md
│   ├── error-handling.md
│   ├── logging-guidelines.md
│   ├── quality-guidelines.md
│   └── directory-structure.md
│
└── guides/                      # 思维指南
    ├── index.md
    ├── cross-layer-thinking-guide.md
    └── code-reuse-thinking-guide.md

.trellis/spec/                                # Trellis 自己的 spec 树
├── cli/                                      # Package: CLI
│   ├── backend/
│   │   └── index.md                          #   ← 通过 index.md 注册为一层
│   └── unit-test/
│       └── index.md                          #   ← 又一层
│
├── docs-site/                                # Package: 文档站
│   └── docs/
│       └── index.md                          #   ← 单层 package
│
└── guides/                                   # 跨 package 的思维指南
    ├── index.md
    ├── cross-layer-thinking-guide.md
    ├── cross-platform-thinking-guide.md
    └── code-reuse-thinking-guide.md

# 看看现有代码是怎么组织的
ls src/components/     # 组件结构
ls src/services/       # 服务结构

# 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：用 ORM batch 方法，别在循环里一条一条写 DB

**What**：对 N 条数据，调一次 ORM 的 batch 方法（`createMany` / `updateMany` / `deleteMany`）。不要把单行 `create` / `update` / `delete` 套进 `for` 或 `Promise.all`。

**Why**：每次 DB 调用都是一次 round-trip。线上接口里一个 200 条的循环就能把 p99 从 50ms 悄悄拖到 8s——这种坑已经在 code review 里抓到过两次（PR #312、#417）。Batch 方法把 N 次 round-trip 压成一次 SQL，DB 可以自己规划写入。

**Example**：

```ts
// ✅ 正确——一次 round-trip
await prisma.user.createMany({ data: users });

// ❌ 错误——N 次 round-trip
for (const user of users) {
  await prisma.user.create({ data: user });
}

// ❌ 还是错——并发的 N 次 round-trip
await Promise.all(users.map((user) => prisma.user.create({ data: user })));
```

**Batch 不可用时**：把循环包进单事务（`prisma.$transaction`），至少是一个逻辑单元；加注释说明为什么 batch 用不了。

**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