安装 && 快速上手使用

# 全局安装（beta 通道）
npm install -g @mindfoldhq/trellis@rc

# 进入你的项目目录
cd your-project

# 交互式：检测已安装的平台并询问要配置哪些
trellis init -u your-name

# 显式：配置一个或多个平台
trellis init -u your-name --claude
trellis init -u your-name --claude --cursor --opencode
trellis init -u your-name --codex --gemini
trellis init -u your-name --pi

# 1. 描述你要做什么
"新增用户登录功能"

# 2. AI 判断当前 turn，必要时询问是否创建任务

# 3. 如果这是 Trellis task，AI 按 workflow.md 走 Plan → Execute → Finish

# 4. 工作 commit 已存在后
/trellis:finish-work

your-project/
├── .trellis/                          # Trellis 核心（跨平台一致）
│   ├── .developer                     # 开发者身份（gitignored）
│   ├── .version                       # Trellis 版本号
│   ├── .template-hashes.json          # 模板文件 hash（update 用）
│   ├── workflow.md                    # 开发工作流指南
│   ├── config.yaml                    # 项目配置（packages、update.skip、hooks）
│   │
│   ├── .runtime/                      # 每个会话自己的运行时状态（gitignored）
│   │   └── sessions/                  #   每个 AI 会话/窗口对应一个 active task
│   │       └── <session-key>.json
│   │
│   ├── spec/                          # 项目 spec 库
│   │   ├── frontend/                  #   前端 spec（monorepo 可按 package 分层）
│   │   ├── backend/                   #   后端 spec
│   │   └── guides/                    #   思考指南
│   │
│   ├── workspace/                     # 开发者工作区
│   │   ├── index.md
│   │   └── {developer-name}/
│   │       ├── index.md
│   │       └── journal-N.md
│   │
│   ├── tasks/                         # 任务目录
│   │   ├── {MM-DD-task-name}/         #   活跃任务
│   │   │   ├── task.json              #     任务元信息
│   │   │   ├── prd.md                 #     需求文档
│   │   │   ├── design.md              #     复杂任务的技术设计
│   │   │   ├── implement.md           #     复杂任务的实施计划
│   │   │   ├── implement.jsonl        #     实现阶段 spec/research manifest
│   │   │   ├── check.jsonl            #     review 阶段 spec/research manifest
│   │   │   └── research/              #     持久调研记录
│   │   └── archive/                   #   归档任务
│   │       └── {YYYY-MM}/
│   │
│   └── scripts/                       # 自动化脚本（Python）
│       ├── task.py                    #   任务管理
│       ├── get_context.py             #   会话上下文
│       ├── add_session.py             #   记录会话
│       ├── create_bootstrap.py        #   首次 spec bootstrap
│       └── common/                    #   共享库
│
├── .claude/                           # Claude Code 配置
│   ├── settings.json                  #   hook 和权限配置
│   ├── commands/trellis/              #   显式命令
│   │   ├── start.md
│   │   ├── finish-work.md
│   │   └── continue.md
│   ├── agents/                        #   Sub-agent 定义
│   │   ├── trellis-implement.md
│   │   ├── trellis-check.md
│   │   └── trellis-research.md
│   ├── skills/                        #   Auto-trigger skills
│   │   ├── trellis-brainstorm/
│   │   ├── trellis-before-dev/
│   │   ├── trellis-check/
│   │   ├── trellis-update-spec/
│   │   └── trellis-break-loop/
│   └── hooks/                         #   Hook 脚本
│       ├── session-start.py
│       ├── inject-subagent-context.py
│       └── inject-workflow-state.py
│
├── .cursor/           # Cursor：commands/ + rules/
├── .opencode/         # OpenCode：commands/trellis/、agents/、skills/、plugins/
├── .codex/            # Codex：prompts/、skills/ + 仓库根 AGENTS.md
├── .kiro/             # Kiro：steering/、prompts/、skills/
├── .gemini/           # Gemini CLI：commands/trellis/
├── .qoder/            # Qoder：commands/、skills/、agents/、hooks/
├── .codebuddy/        # CodeBuddy：commands/trellis/
├── .factory/          # Droid：commands/trellis/、skills/、hooks/
├── .pi/               # Pi Agent：prompts/、skills/、agents/、extensions/trellis/
└── .github/           # Copilot：copilot-instructions.md、prompts/

I am starting a new B2B dashboard from scratch. Help me set up Trellis for the first week of work.

First, ask for the missing product and tech-stack decisions. Then create a small first task and the minimum specs needed for frontend structure, API shape, error handling, and test strategy.

Phase 1 — Plan（和你互动）
 1.0 task.py create 创建任务目录和默认 prd.md
 1.1 激活 trellis-brainstorm skill，和你一问一答澄清需求，迭代 prd.md
 1.2 复杂任务在实现前写 design.md 和 implement.md
 1.3 需要调研时，结论写到 research/
 1.4 Sub-agent mode curate implement.jsonl / check.jsonl，只放 spec + research
     路径，不放源码路径
 1.5 Review 后 task.py start 把 status 改成 in_progress

Phase 2 — Execute
 2.1 按 prd.md、存在时的 design.md、存在时的 implement.md 和相关 spec 实现。
     具体是 sub-agent 还是主会话 inline，取决于平台和模式
 2.2 运行 trellis-check → 对照 artifacts + spec 审 diff，跑 lint / typecheck / test，
     能修则自修

Phase 3 — Finish
 3.1 激活 trellis-check skill，做最终验证
 3.2（按需）激活 trellis-break-loop skill 做 debug 复盘
 3.3 激活 trellis-update-spec skill，把新知识写回 .trellis/spec/
 3.4 提出工作 commit 计划，提交确认的批次，然后运行 /trellis:finish-work
     做 archive 和 journal 记账

/trellis:finish-work

AI："Alice 好，你上次完成了用户登录功能（commit abc1234），
     包含 LoginForm 组件、JWT 中间件、users 表。
     接下来想干什么？"

# 交互式：浏览可用模板并挑一个
trellis init -u your-name

# 非交互式：按 ID 指定模板
trellis init -u your-name --template electron-fullstack

# 直接下载：仓库目录变成 .trellis/spec/
trellis init --registry gh:myorg/myrepo/my-team-spec

# Marketplace 模式：仓库里有 index.json 定义多模板
trellis init --registry gh:myorg/myrepo/marketplace

# 从自定义 marketplace 选特定模板
trellis init --registry gh:myorg/myrepo/marketplace --template my-template

# 指定分支
trellis init --registry gh:myorg/myrepo/specs#develop

# GitLab 或 Bitbucket
trellis init --registry gitlab:myorg/myrepo/specs
trellis init --registry bitbucket:myorg/myrepo/specs

{
  "version": 1,
  "templates": [
    {
      "id": "my-backend-spec",
      "type": "spec",
      "name": "My Backend Spec",
      "description": "团队后端约定",
      "path": "marketplace/specs/my-backend-spec",
      "tags": ["backend", "node"]
    }
  ]
}

GIGET_AUTH=ghp_xxxxx trellis init --registry gh:myorg/private-repo/specs