your-project/
├── .trellis/                          # Trellis 核心（平台无关）
│   ├── .developer                     # 开发者身份（gitignored）
│   ├── .version                       # Trellis 版本
│   ├── .template-hashes.json          # 模板文件哈希（用于更新）
│   ├── workflow.md                    # 开发工作流指南
│   ├── config.yaml                    # 项目配置（包、更新策略、钩子）
│   │
│   ├── .runtime/                      # 会话级运行时状态（gitignored）
│   │   └── sessions/                  #   每个 AI 会话的活动任务
│   │       └── <session-key>.json
│   │
│   ├── spec/                          # 项目 Spec 库
│   │   ├── frontend/                  #   前端 Spec
│   │   ├── backend/                   #   后端 Spec
│   │   └── guides/                    #   思维指南
│   │
│   ├── workspace/                     # 开发者工作区
│   │   ├── index.md
│   │   └── {developer-name}/
│   │       ├── index.md			   #   index.md 是所有 journal 的汇总索引
│   │       └── journal-N.md           #   每次会话的日志
│   │
│   ├── tasks/                         # 任务目录
│   │   ├── {MM-DD-task-name}/         #   活跃任务
│   │   │   ├── task.json              #     任务元数据
│   │   │   ├── prd.md                 #     需求文档
│   │   │   ├── info.md                #     技术设计（可选）
│   │   │   ├── implement.jsonl         #     实现子代理上下文
│   │   │   ├── check.jsonl            #     检查子代理上下文
│   │   │   └── research.jsonl         #     研究子代理上下文
│   │   └── archive/                   #   归档任务
│   │       └── {YYYY-MM}/
│   │
│   └── scripts/                       # 自动化脚本（Python）
│       ├── task.py                    #   任务管理
│       ├── get_context.py             #   会话上下文
│       ├── add_session.py             #   记录会话
│       ├── create_bootstrap.py        #   首次 spec 引导
│       └── common/                    #   共享库
│
├── .opencode/                         # OpenCode 配置
│   ├── commands/trellis/              #   命令
│   │   ├── start.md
│   │   ├── finish-work.md
│   │   └── continue.md
│   ├── agents/                        #   子代理定义
│   │   ├── trellis-implement.md
│   │   ├── trellis-check.md
│   │   └── trellis-research.md
│   ├── skills/                        #   自动触发技能
│   │   ├── trellis-brainstorm/
│   │   ├── trellis-before-dev/
│   │   ├── trellis-check/
│   │   ├── trellis-update-spec/
│   │   └── trellis-break-loop/
│   └── plugins/                       #   JS 插件
│       ├── session-start.js
│       ├── inject-subagent-context.js
│       └── inject-workflow-state.js
│
└── .agents/skills/                    # 跨平台共享技能层

┌──────────────────────────────────────────────────────────────────────┐
│ Phase 1: Plan（规划）                                                │
│                                                                      │
│  1.0  task.py create → 创建任务目录                                   │
│  1.1  trellis-brainstorm → 逐个问题讨论需求，迭代 prd.md              │
│  1.2  trellis-research → 调查研究（按需），结果存入 research/          │
│  1.3  精心策划 implement.jsonl / check.jsonl（spec + research 路径）   │
│  1.4  task.py start → 写入当前会话的活动任务                          │
├──────────────────────────────────────────────────────────────────────┤
│ Phase 2: Execute（执行）                                             │
│                                                                      │
│  2.1  trellis-implement → 按 prd.md 写代码，不提交 git                │
│  2.2  trellis-check → 对照 spec 审查 diff + 运行 lint/类型检查/测试   │
│       → 自修复（bounded loop）                                       │
├──────────────────────────────────────────────────────────────────────┤
│ Phase 3: Finish（收尾）                                              │
│                                                                      │
│  3.2  trellis-break-loop → Debug 复盘（按需）                         │
│  3.3  trellis-update-spec → 将新经验写回 .trellis/spec/               │
│  3.4  主会话驱动工作提交（分组 git commit）                            │
└──────────────────────────────────────────────────────────────────────┘

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

create:        创建任务目录 + task.json + 初始 jsonl
curate jsonl:  AI 填充 implement/check/research 上下文
start:         设置当前 AI 会话的活动任务
implement/check: 开发和验证循环
finish:        清除当前 AI 会话的活动任务
archive:       移动已完成任务到 archive/

task.py create   →  status: "planning"
task.py start    →  planning → "in_progress"（其他状态不变）
task.py archive  →  status: "completed" + 移动到 archive/

{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. ..."}

{"file": ".trellis/spec/guides/index.md", "reason": "共享跨包思维指南"}
{"file": ".trellis/spec/cli/backend/index.md", "reason": "后端开发指南"}
{"file": ".trellis/tasks/.../research/auth-library-comparison.md", "reason": "库选择理由"}

.trellis/spec/
├── frontend/
│   ├── index.md                    # 索引：列出所有 spec 及其状态
│   ├── 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

我正在从零开始构建一个 B2B 仪表板。帮我设置 Trellis 用于第一周的工作。

先问缺失的产品和技术栈决策，然后创建一个小的首个任务 PRD 和前端结构、API 形态、错误处理和测试策略的最小 spec。

这是一个已有仓库。先不要重构代码。

检查代码库并提出下一个功能任务的最小 Trellis 引导方案。识别 API 路由、权限检查、日志、测试和前端表单的实际模式。只根据当前代码示例支持的编写 spec。

创建团队邀请功能的 Trellis 任务。

功能应包括：工作区管理员通过邮箱邀请用户、重新发送待处理邀请、撤销邀请、接受邀请。包含产品需求、范围外项目、数据模型变更、API 形态、前端状态、测试和上线风险。

为 src/billing/invoice-service.ts 创建一个行为保持不变的重构任务。

先映射当前职责、调用方、副作用和现有测试。然后提出最安全的顺序。在有特征测试或明确覆盖之前，不要改变行为。

修复 SessionStart 钩子在 `str | None` 上的崩溃。用户终端的 Python 是 3.11，但钩子子进程似乎使用了更旧的版本。

在最小 PATH shell 上复现，识别最小安全修复，添加检测此类问题的方法，然后运行 break-loop 分析。如果根因暴露了缺失的约定，提出 spec 更新。

审查最近几个 PR 的评论，帮我将重复的工程反馈转化为 Trellis spec。

只提出具体的、可执行的、与实际审查评论关联的规则。为每条规则展示目标 spec 文件和好/坏示例。