flower-trellis 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +113 -0
- package/bin/flower-trellis.js +4 -0
- package/enhancements/0.5/.agents/skills/trellis-analyze-task/SKILL.md +142 -0
- package/enhancements/0.5/.agents/skills/trellis-check-all/SKILL.md +324 -0
- package/enhancements/0.5/.agents/skills/trellis-create-command/SKILL.md +258 -0
- package/enhancements/0.5/.agents/skills/trellis-create-prd/SKILL.md +197 -0
- package/enhancements/0.5/.agents/skills/trellis-draw-uml/SKILL.md +148 -0
- package/enhancements/0.5/.agents/skills/trellis-migrate-skill/SKILL.md +216 -0
- package/enhancements/0.5/.agents/skills/trellis-plan-version/SKILL.md +140 -0
- package/enhancements/0.5/.agents/skills/trellis-push/SKILL.md +240 -0
- package/enhancements/0.5/.agents/skills/trellis-re-implement/SKILL.md +166 -0
- package/enhancements/0.5/.agents/skills/trellis-route/SKILL.md +159 -0
- package/enhancements/0.5/.agents/skills/trellis-run-full-chain/SKILL.md +402 -0
- package/enhancements/0.5/.agents/skills/trellis-sync-prd/SKILL.md +150 -0
- package/enhancements/0.5/.agents/skills/trellis-verify-prd/SKILL.md +217 -0
- package/enhancements/0.5/.claude/skills/trellis-analyze-task/SKILL.md +142 -0
- package/enhancements/0.5/.claude/skills/trellis-check-all/SKILL.md +324 -0
- package/enhancements/0.5/.claude/skills/trellis-create-command/SKILL.md +258 -0
- package/enhancements/0.5/.claude/skills/trellis-create-prd/SKILL.md +197 -0
- package/enhancements/0.5/.claude/skills/trellis-draw-uml/SKILL.md +148 -0
- package/enhancements/0.5/.claude/skills/trellis-migrate-skill/SKILL.md +216 -0
- package/enhancements/0.5/.claude/skills/trellis-plan-version/SKILL.md +140 -0
- package/enhancements/0.5/.claude/skills/trellis-push/SKILL.md +240 -0
- package/enhancements/0.5/.claude/skills/trellis-re-implement/SKILL.md +166 -0
- package/enhancements/0.5/.claude/skills/trellis-route/SKILL.md +159 -0
- package/enhancements/0.5/.claude/skills/trellis-run-full-chain/SKILL.md +402 -0
- package/enhancements/0.5/.claude/skills/trellis-sync-prd/SKILL.md +150 -0
- package/enhancements/0.5/.claude/skills/trellis-verify-prd/SKILL.md +217 -0
- package/enhancements/0.5/overrides/trellis-route.md +52 -0
- package/enhancements/0.6/.agents/skills/trellis-check-all/SKILL.md +342 -0
- package/enhancements/0.6/.agents/skills/trellis-create-command/SKILL.md +293 -0
- package/enhancements/0.6/.agents/skills/trellis-draw-uml/SKILL.md +148 -0
- package/enhancements/0.6/.agents/skills/trellis-extract-prd/SKILL.md +197 -0
- package/enhancements/0.6/.agents/skills/trellis-plan-version/SKILL.md +140 -0
- package/enhancements/0.6/.agents/skills/trellis-push/SKILL.md +316 -0
- package/enhancements/0.6/.agents/skills/trellis-route/SKILL.md +159 -0
- package/enhancements/0.6/.agents/skills/trellis-run-full-chain/SKILL.md +402 -0
- package/enhancements/0.6/.agents/skills/trellis-verify-task/SKILL.md +360 -0
- package/enhancements/0.6/.claude/skills/trellis-check-all/SKILL.md +342 -0
- package/enhancements/0.6/.claude/skills/trellis-create-command/SKILL.md +293 -0
- package/enhancements/0.6/.claude/skills/trellis-draw-uml/SKILL.md +148 -0
- package/enhancements/0.6/.claude/skills/trellis-extract-prd/SKILL.md +197 -0
- package/enhancements/0.6/.claude/skills/trellis-plan-version/SKILL.md +140 -0
- package/enhancements/0.6/.claude/skills/trellis-push/SKILL.md +316 -0
- package/enhancements/0.6/.claude/skills/trellis-route/SKILL.md +159 -0
- package/enhancements/0.6/.claude/skills/trellis-run-full-chain/SKILL.md +402 -0
- package/enhancements/0.6/.claude/skills/trellis-verify-task/SKILL.md +360 -0
- package/enhancements/0.6/overrides/workflow-states/in_progress-inline.md +5 -0
- package/enhancements/0.6/overrides/workflow-states/in_progress.md +7 -0
- package/enhancements/0.6/overrides/workflow-states/no_task.md +6 -0
- package/enhancements/0.6/overrides/workflow-states/planning.md +6 -0
- package/enhancements/0.6/overrides/workflow.md +53 -0
- package/enhancements/MANIFEST.json +109 -0
- package/enhancements/old/.agents/skills/analyze-task/SKILL.md +143 -0
- package/enhancements/old/.agents/skills/check-all/SKILL.md +128 -0
- package/enhancements/old/.agents/skills/check-impl/SKILL.md +159 -0
- package/enhancements/old/.agents/skills/check-prd/SKILL.md +219 -0
- package/enhancements/old/.agents/skills/check-prd-impl/SKILL.md +190 -0
- package/enhancements/old/.agents/skills/create-prd/SKILL.md +154 -0
- package/enhancements/old/.agents/skills/draw-uml/SKILL.md +148 -0
- package/enhancements/old/.agents/skills/plan-version/SKILL.md +140 -0
- package/enhancements/old/.agents/skills/push/SKILL.md +191 -0
- package/enhancements/old/.agents/skills/re-implement/SKILL.md +166 -0
- package/enhancements/old/.agents/skills/sync-prd/SKILL.md +146 -0
- package/enhancements/old/.claude/commands/trellis/analyze-task.md +139 -0
- package/enhancements/old/.claude/commands/trellis/check-all.md +124 -0
- package/enhancements/old/.claude/commands/trellis/check-impl.md +154 -0
- package/enhancements/old/.claude/commands/trellis/check-prd-impl.md +186 -0
- package/enhancements/old/.claude/commands/trellis/check-prd.md +215 -0
- package/enhancements/old/.claude/commands/trellis/create-prd.md +150 -0
- package/enhancements/old/.claude/commands/trellis/draw-uml.md +144 -0
- package/enhancements/old/.claude/commands/trellis/plan-version.md +136 -0
- package/enhancements/old/.claude/commands/trellis/push.md +187 -0
- package/enhancements/old/.claude/commands/trellis/re-implement.md +162 -0
- package/enhancements/old/.claude/commands/trellis/sync-prd.md +142 -0
- package/package.json +39 -0
- package/src/cli.js +151 -0
- package/src/commands/init.js +66 -0
- package/src/commands/uninstall.js +85 -0
- package/src/commands/update.js +42 -0
- package/src/constants.js +50 -0
- package/src/lib/apply-enhancements.js +133 -0
- package/src/lib/banner.js +45 -0
- package/src/lib/codex-tweaks.js +112 -0
- package/src/lib/copy-skills.js +91 -0
- package/src/lib/fs-utils.js +60 -0
- package/src/lib/legacy-blocks.js +70 -0
- package/src/lib/manifest.js +32 -0
- package/src/lib/paths.js +16 -0
- package/src/lib/pick-platforms.js +57 -0
- package/src/lib/trellis-runner.js +190 -0
- package/src/lib/variant.js +40 -0
- package/src/lib/versions.js +30 -0
- package/src/lib/workflow-inject.js +193 -0
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: trellis-migrate-skill
|
|
3
|
+
description: "Migrate an existing /trellis:<X> command to a skill; syncs target project + skill-garden copies."
|
|
4
|
+
---
|
|
5
|
+
# Migrate Command → Skill
|
|
6
|
+
|
|
7
|
+
把 `.claude/commands/trellis/<name>.md` 命令迁移到 `.claude/skills/trellis-<name>/` skill 形态,同步所有副本 + skill-garden 分发。
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 适用场景
|
|
12
|
+
|
|
13
|
+
- 命令更适合自然语触发(查询 / 分析 / 检查类:如 check-all、analyze-task)
|
|
14
|
+
- 命令内部引用已过时(agent 重命名、multi_agent 已删除、check-cross-layer 已合并等)
|
|
15
|
+
- 多个相邻命令语义重复,想融合成一个宿主 skill
|
|
16
|
+
- trellis 脚手架升级后要同步 skill-garden 的分发包
|
|
17
|
+
|
|
18
|
+
## 前置条件
|
|
19
|
+
|
|
20
|
+
- **`<target>`(目标项目)**:默认 = 当前工作目录(`pwd`)。如需迁移其他项目的命令,由用户显式指定绝对路径;本 skill 不主动 `cd`
|
|
21
|
+
- **`<skill-garden>`(分发源)**:默认 `/root/project/skill-garden`。路径不存在或与用户期望不符 → 询问用户
|
|
22
|
+
- 目标命令存在于 `<target>/.claude/commands/trellis/<name>.md` 或 `<target>/.agents/skills/<name>/SKILL.md`
|
|
23
|
+
- 若 `<target>` 与 `<skill-garden>` 是同一路径(在 skill-garden 仓库里迁移),副本去重、只写一次
|
|
24
|
+
- skill-garden 使用 variant 结构(`.trellis/0.5/` 对应新版,`.trellis/old/` 向后兼容)
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## 执行步骤
|
|
29
|
+
|
|
30
|
+
### Step 1: 读两份副本 + 对齐扫描
|
|
31
|
+
|
|
32
|
+
读取当前内容:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
cat <target>/.claude/commands/trellis/<name>.md
|
|
36
|
+
cat <target>/.agents/skills/<name>/SKILL.md
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
对齐扫描(grep 过时引用):
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
# 旧 multi_agent 脚本
|
|
43
|
+
grep -nE "multi_agent|scripts/(start|plan|cleanup|create_pr|status)\.py" <target_files>
|
|
44
|
+
|
|
45
|
+
# 旧 agent 名(应改 trellis-*)
|
|
46
|
+
grep -nE 'subagent_type: "(check|implement|research)"' <target_files>
|
|
47
|
+
|
|
48
|
+
# 悬空 skill(已合并)
|
|
49
|
+
grep -n "check-cross-layer" <target_files>
|
|
50
|
+
|
|
51
|
+
# 已删除命令
|
|
52
|
+
grep -nE "/trellis:(start|brainstorm)" <target_files>
|
|
53
|
+
|
|
54
|
+
# 已废弃目录
|
|
55
|
+
grep -n ".cursor/commands" <target_files>
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
把扫描发现汇总成 `清单 (文件 → 行号 → 过时引用 → 应替换为)` 呈现给用户。
|
|
59
|
+
|
|
60
|
+
### Step 2: 形态决策
|
|
61
|
+
|
|
62
|
+
询问用户:
|
|
63
|
+
|
|
64
|
+
| 选项 | 适用 | description 策略 |
|
|
65
|
+
|------|------|------------------|
|
|
66
|
+
| 仅对齐修复 | 保持 command 形态,只修过时引用(finish-work / continue 这类显式动作) | — |
|
|
67
|
+
| skill 化(Auto-routing) | 删 command 副本,改/新增 agents + skill;**需要** Claude 按自然语自动加载(查询 / 分析 / 检查类:analyze-task、check-all) | 80–300 字三段式 |
|
|
68
|
+
| skill 化(Manual-only) | 删 command 副本,改/新增 agents + skill;用法明确、频率低、不希望占 skill 列表 token(管理工具:migrate-skill、create-command) | 15–20 tokens 单句 |
|
|
69
|
+
| 融合到宿主 skill | 内容内嵌到 check-all 这类宿主,删除本身所有副本 | — |
|
|
70
|
+
|
|
71
|
+
> **推荐原则**:日常工作流(check / analyze / draw / sync)走 Auto-routing;低频管理工具走 Manual-only;迁移时有疑问就默认 Auto-routing(更灵活)。
|
|
72
|
+
|
|
73
|
+
### Step 3: 融合判断(仅形态 = 融合时)
|
|
74
|
+
|
|
75
|
+
| 问法 | 对应动作 |
|
|
76
|
+
|------|---------|
|
|
77
|
+
| 彻底融合 | 删所有副本(command + agents 各 2 份),内容并入宿主 |
|
|
78
|
+
| 仅删 command | 保留 agents 作为宿主引用的组件 |
|
|
79
|
+
| 保留现状 | 不融合(与"仅对齐修复"等价) |
|
|
80
|
+
|
|
81
|
+
彻底融合时注意 diff 对比宿主和被融合者:识别 Step/原则/反模式/报告模板等模块,合理合并,避免遗漏关键 checklist。
|
|
82
|
+
|
|
83
|
+
### Step 4: 执行同步(skill 化模式)
|
|
84
|
+
|
|
85
|
+
对每个要 skill 化的 `<name>`,共 6 步、涉及 4 份副本:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
# (1-2) 删 command 副本
|
|
89
|
+
rm <target>/.claude/commands/trellis/<name>.md
|
|
90
|
+
rm <skill-garden>/.trellis/0.5/.claude/commands/trellis/<name>.md
|
|
91
|
+
|
|
92
|
+
# (3-4) 更新 agents 副本(正文 + frontmatter 完全对齐 skill 版,name=trellis-<name>)
|
|
93
|
+
# — 用最新已对齐的内容覆盖写入;路径为 .agents/skills/trellis-<name>/SKILL.md
|
|
94
|
+
|
|
95
|
+
# (5-6) 新增 skill 副本
|
|
96
|
+
mkdir -p <target>/.claude/skills/trellis-<name>
|
|
97
|
+
mkdir -p <skill-garden>/.trellis/0.5/.claude/skills/trellis-<name>
|
|
98
|
+
# 写入 SKILL.md(frontmatter name=trellis-<name>)
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### Step 5: 执行同步(融合模式)
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
# 删 4 份副本
|
|
105
|
+
rm <target>/.claude/commands/trellis/<name>.md
|
|
106
|
+
rm <skill-garden>/.trellis/0.5/.claude/commands/trellis/<name>.md
|
|
107
|
+
rm -rf <target>/.agents/skills/trellis-<name>/
|
|
108
|
+
rm -rf <skill-garden>/.trellis/0.5/.agents/skills/trellis-<name>/
|
|
109
|
+
|
|
110
|
+
# 编辑宿主 skill 的 4 份副本,内嵌融合内容
|
|
111
|
+
# 注意保留:原核心原则 / 报告模板 / 反模式 / Dimension checklist 等关键段
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### Step 6: frontmatter 规则
|
|
115
|
+
|
|
116
|
+
**name**:两份副本的目录名和 frontmatter `name:` 字段都统一使用 `trellis-<X>`。
|
|
117
|
+
|
|
118
|
+
| 文件位置 | name |
|
|
119
|
+
|---------|------|
|
|
120
|
+
| `.claude/skills/trellis-<X>/SKILL.md` | `trellis-<X>` |
|
|
121
|
+
| `.agents/skills/trellis-<X>/SKILL.md` | `trellis-<X>` |
|
|
122
|
+
|
|
123
|
+
> 历史说明:0.5 早期 agents 版曾用无前缀 `<X>` 作为 name,迁移脚本需 `sed` 替换。自 2026-04 起统一为 `trellis-<X>`,4 份副本完全一致,不再需要 sed 替换 frontmatter。
|
|
124
|
+
|
|
125
|
+
**description** 按 Step 2 选定的策略:
|
|
126
|
+
|
|
127
|
+
| 策略 | 长度 | 写法 |
|
|
128
|
+
|------|------|------|
|
|
129
|
+
| **Auto-routing** | 80–300 字 | 三段式:What(动词开头)+ When(中英触发词)+ Exclusion("For X, use Y instead")。Claude 据此按自然语路由,每次对话都会注入 skill 列表 |
|
|
130
|
+
| **Manual-only** | 15–20 tokens | 单句动作 + 产出物。靠用户 `/trellis-<X>` 显式触发,description 不作路由依据,节省 skill 列表 token |
|
|
131
|
+
|
|
132
|
+
**body 正文和 frontmatter 都 4 份完全一致**,直接 `cp` 即可,不需要 sed 改 name:
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
cp <target>/.claude/skills/trellis-<X>/SKILL.md <target>/.agents/skills/trellis-<X>/SKILL.md
|
|
136
|
+
cp <target>/.claude/skills/trellis-<X>/SKILL.md <skill-garden>/.trellis/0.5/.claude/skills/trellis-<X>/SKILL.md
|
|
137
|
+
cp <target>/.claude/skills/trellis-<X>/SKILL.md <skill-garden>/.trellis/0.5/.agents/skills/trellis-<X>/SKILL.md
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Step 7: 更新 install.sh 支持(如需)
|
|
141
|
+
|
|
142
|
+
确认 skill-garden install.sh 已有:
|
|
143
|
+
- 3c 段 `.claude/skills/` 循环安装
|
|
144
|
+
- `should_install` 支持 `trellis-` 前缀去除匹配(`install.sh TARGET analyze-task` 能命中 `trellis-analyze-task`)
|
|
145
|
+
|
|
146
|
+
如果某次迁移涉及新路径约定,同步修改 install.sh + 端到端测试。
|
|
147
|
+
|
|
148
|
+
### Step 8: 更新 skill-garden README
|
|
149
|
+
|
|
150
|
+
必改:
|
|
151
|
+
- "全部技能" 表:对该 skill 标注 "0.5+ skill 化为 trellis-<name>"
|
|
152
|
+
- "variant 说明" 表:列举新版的变化点
|
|
153
|
+
|
|
154
|
+
可选:
|
|
155
|
+
- "推荐命令" 表:高频 skill 加入
|
|
156
|
+
- "新增 Trellis 技能" 指引:如果约定有变
|
|
157
|
+
|
|
158
|
+
### Step 9: 验证
|
|
159
|
+
|
|
160
|
+
| 检查项 | 命令 |
|
|
161
|
+
|-------|------|
|
|
162
|
+
| skill 出现在 Claude skill list | 读 `<available-skills>` 区,确认 `trellis-<name>` 存在且 description 正确 |
|
|
163
|
+
| `/trellis:<name>` 已消失 | 同上,原 command 不应再出现 |
|
|
164
|
+
| install 分发通过 | `rm -rf /tmp/sg-test && mkdir -p /tmp/sg-test/.trellis && echo "0.5.0-beta.8" > /tmp/sg-test/.trellis/.version && bash <skill-garden>/scripts/install.sh /tmp/sg-test <name>` |
|
|
165
|
+
| 4 份副本内容一致 | `wc -l` 对比行数;`diff` 关键段落 |
|
|
166
|
+
|
|
167
|
+
如 skill list 未刷新:harness 有缓存,在下一轮对话系统会自动刷新;不要反复确认。
|
|
168
|
+
|
|
169
|
+
### Step 10: 提交(可选)
|
|
170
|
+
|
|
171
|
+
按 skill-garden commit message 风格:
|
|
172
|
+
|
|
173
|
+
```
|
|
174
|
+
<type>(trellis): <概述,40 字内>
|
|
175
|
+
|
|
176
|
+
<空行>
|
|
177
|
+
|
|
178
|
+
<背景:为什么做这次迁移,引用 trellis 版本变化或业务动因>
|
|
179
|
+
|
|
180
|
+
<改动:做了什么具体动作,列关键路径和数量>
|
|
181
|
+
|
|
182
|
+
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
`<type>` 参考:
|
|
186
|
+
- `refactor(trellis):` — 迁移/重构(典型场景)
|
|
187
|
+
- `feat(trellis):` — 新增能力(如首次 skill 化某类工具)
|
|
188
|
+
- `chore(trellis):` — 清理/对齐
|
|
189
|
+
- `docs(trellis):` — 仅文档
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
## 反模式(避免)
|
|
194
|
+
|
|
195
|
+
- ❌ 跳过 Step 1 对齐扫描就动手——会留下过时引用,运行时报错
|
|
196
|
+
- ❌ 只改目标项目不同步 skill-garden——下次 install 会被 skill-garden 旧版覆盖
|
|
197
|
+
- ❌ skill 版和 agents 版正文不一致——同一入口行为分裂
|
|
198
|
+
- ❌ 选 Auto-routing 策略但 description 过短(< 80 字)——Claude 路由不稳;Manual-only 策略无此要求
|
|
199
|
+
- ❌ 所有迁移都默认 Auto-routing——低频管理工具(migrate-skill / create-command 这类)可选 Manual-only 节省 token
|
|
200
|
+
- ❌ 融合后不删被融合者——两个入口冲突,Claude 不知选哪个
|
|
201
|
+
- ❌ 改动后 skill list 未出现新项就直接"验证通过"——可能 frontmatter 语法错(YAML 缩进/引号)
|
|
202
|
+
- ❌ skill-garden README 不更新——未来迁移者看不到新约定
|
|
203
|
+
- ❌ 提交时把不相关改动一起塞入 commit——应该一个迁移一个 commit
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## 快速参考:4 份副本对照表
|
|
208
|
+
|
|
209
|
+
| 序号 | 路径 | 角色 |
|
|
210
|
+
|------|------|------|
|
|
211
|
+
| 1 | `<target>/.claude/commands/trellis/<name>.md` | command 版,skill 化后删除 |
|
|
212
|
+
| 2 | `<target>/.agents/skills/trellis-<name>/SKILL.md` | agents 版,trellis agent 系统读取(保留,名字带 trellis- 前缀) |
|
|
213
|
+
| 3 | `<target>/.claude/skills/trellis-<name>/SKILL.md` | skill 版,Claude harness 自动路由(新增) |
|
|
214
|
+
| 4 | `<skill-garden>/.trellis/0.5/.*` | 对应的 3 份 skill-garden 副本(分发源) |
|
|
215
|
+
|
|
216
|
+
同步顺序建议:先 skill 版(Claude harness 立刻能感知变化) → 再 agents 版 → 最后 skill-garden 副本。
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: trellis-plan-version
|
|
3
|
+
description: "Generate a version development plan from a source requirements doc: requirements list, effort estimate, and team assignment."
|
|
4
|
+
---
|
|
5
|
+
# 版本开发计划 — 从需求文档到任务拆分
|
|
6
|
+
|
|
7
|
+
从原始需求文档出发,生成版本开发计划(需求清单 + 工时评估 + 人员分工),内置覆盖度校验确保不遗漏需求。
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 核心原则
|
|
12
|
+
|
|
13
|
+
1. **需求文档是唯一真相** — 需求清单必须从文档全文提取,不能只看目录/总表
|
|
14
|
+
2. **先扫后拆** — 先完成覆盖度扫描,确认无遗漏后再做工时评估和分工
|
|
15
|
+
3. **可追溯** — 每个任务可追溯到原始文档的具体位置(行号/章节)
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## 输入
|
|
20
|
+
|
|
21
|
+
用户需提供:
|
|
22
|
+
- **原始需求文档路径**
|
|
23
|
+
- **版本号或迭代标识**
|
|
24
|
+
- **开发团队信息**(人数、角色分工模式)
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## 执行步骤
|
|
29
|
+
|
|
30
|
+
### Step 1: 理解文档结构 + 全文扫描
|
|
31
|
+
|
|
32
|
+
#### 1.0 先读后扫
|
|
33
|
+
|
|
34
|
+
读取文档,识别其组织方式:
|
|
35
|
+
- 需求的划分单元是什么?(编号体系 / 章节 / 功能模块 / 用户故事)
|
|
36
|
+
- 有无需求总表或变更日志?
|
|
37
|
+
- 版本变更如何标记?(显式标记 / 总表版本列 / 变更日志章节 / 无标记)
|
|
38
|
+
|
|
39
|
+
> **不要假设文档有特定格式**,先读再判断。
|
|
40
|
+
|
|
41
|
+
#### 1.1 多策略识别本版本变更
|
|
42
|
+
|
|
43
|
+
根据文档实际结构,组合使用以下策略:
|
|
44
|
+
|
|
45
|
+
| 策略 | 方法 |
|
|
46
|
+
|------|------|
|
|
47
|
+
| **标记扫描** | grep 搜索版本相关标记,**包括段落中间嵌入的** |
|
|
48
|
+
| **需求总表** | 读取需求列表中版本相关列,提取本版本的条目 |
|
|
49
|
+
| **全文通读** | 逐章扫描「新增」「变更」「调整」等动作词 |
|
|
50
|
+
|
|
51
|
+
#### 1.2 归组到需求单元
|
|
52
|
+
|
|
53
|
+
每个变更点定位到所属的需求单元,记录:
|
|
54
|
+
- 需求单元标识(编号、名称或章节)
|
|
55
|
+
- 变更内容摘要
|
|
56
|
+
- 在文档中的位置
|
|
57
|
+
- 变更类型:整体新增 / 局部变更 / 字段级嵌入
|
|
58
|
+
|
|
59
|
+
> **[!] 关键:必须识别出「字段级嵌入变更」。**
|
|
60
|
+
> 有些需求单元整体是旧版本的,但内部某个字段/段落属于新版本变更。
|
|
61
|
+
> 仅看需求单元标题会遗漏这类变更。
|
|
62
|
+
|
|
63
|
+
#### 1.3 识别散射型变更
|
|
64
|
+
|
|
65
|
+
检查是否有同一功能点散布在多个需求单元中:
|
|
66
|
+
- 同一字段在不同页面的展示/编辑/导出
|
|
67
|
+
- 同一业务规则在不同入口的复用
|
|
68
|
+
- 标记每组散射变更,确保后续分工时归同一人
|
|
69
|
+
|
|
70
|
+
### Step 2: 输出需求清单 — 覆盖度确认
|
|
71
|
+
|
|
72
|
+
输出完整的需求清单,请用户确认无遗漏:
|
|
73
|
+
|
|
74
|
+
```markdown
|
|
75
|
+
## <版本> 需求清单
|
|
76
|
+
|
|
77
|
+
### 扫描统计
|
|
78
|
+
- 需求总表中本版本条目: X 个
|
|
79
|
+
- 全文扫描发现的变更: Y 个
|
|
80
|
+
- 去重后独立需求单元: Z 个
|
|
81
|
+
|
|
82
|
+
### 需求列表
|
|
83
|
+
|
|
84
|
+
| # | 需求单元 | 功能点 | 变更类型 | 变更摘要 | 文档位置 |
|
|
85
|
+
|---|---------|--------|---------|---------|---------|
|
|
86
|
+
|
|
87
|
+
### 散射型变更(同一功能点跨多个需求单元)
|
|
88
|
+
|
|
89
|
+
| 功能点 | 涉及的需求单元 | 建议处理 |
|
|
90
|
+
|--------|--------------|---------|
|
|
91
|
+
|
|
92
|
+
### 需求总表 vs 全文扫描差异
|
|
93
|
+
|
|
94
|
+
| 来源 | 仅在总表 | 仅在全文 | 两者都有 |
|
|
95
|
+
|------|---------|---------|---------|
|
|
96
|
+
|
|
97
|
+
> 仅在全文中的变更 = 总表未收录的嵌入式变更,最易遗漏。
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
**等待用户确认后再继续。**
|
|
101
|
+
|
|
102
|
+
### Step 3: 工时评估
|
|
103
|
+
|
|
104
|
+
基于确认后的需求清单,评估每个需求的工时。
|
|
105
|
+
|
|
106
|
+
输出表格的列结构**根据项目实际的角色分工来定**(如前端/后端/全栈/测试等),不要预设。
|
|
107
|
+
|
|
108
|
+
评估原则:
|
|
109
|
+
- 如有 AI 编程辅助,标注基准(AI 辅助 vs 纯人工)
|
|
110
|
+
- 复用关系明确标注
|
|
111
|
+
- 优先级以需求文档为准
|
|
112
|
+
|
|
113
|
+
### Step 4: 人员分工
|
|
114
|
+
|
|
115
|
+
按模块边界分工,遵循:
|
|
116
|
+
- 复用链归同一人
|
|
117
|
+
- 散射型变更归同一人
|
|
118
|
+
- 尽量无交集
|
|
119
|
+
|
|
120
|
+
输出分工表和排期建议。
|
|
121
|
+
|
|
122
|
+
### Step 5: 生成产物文件
|
|
123
|
+
|
|
124
|
+
在 `doc/` 目录下生成:
|
|
125
|
+
|
|
126
|
+
```
|
|
127
|
+
doc/
|
|
128
|
+
├── <版本>-需求清单.md # Step 2 的完整输出(含覆盖度校验)
|
|
129
|
+
├── <版本>-开发计划-工时评估.md # Step 3 + Step 4
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## 反模式
|
|
135
|
+
|
|
136
|
+
- ❌ 只从需求总表提取需求(会漏掉嵌入式变更)
|
|
137
|
+
- ❌ 跳过覆盖度确认直接做工时评估
|
|
138
|
+
- ❌ 散射型变更分给不同的人
|
|
139
|
+
- ❌ 假设文档有特定格式或特定的角色分工模式
|
|
140
|
+
- ❌ 当多个来源的优先级冲突时不明确说明以哪个为准
|
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: trellis-push
|
|
3
|
+
description: "Commit + push across configured repos with optional merge-to-target and pre-push PRD-sync reminder."
|
|
4
|
+
---
|
|
5
|
+
# Push — 提交并推送(可选合并到目标分支)
|
|
6
|
+
|
|
7
|
+
一键完成 commit → push → 可选 merge 到目标分支(通常是测试线)→ push 目标分支 → 切回。
|
|
8
|
+
|
|
9
|
+
支持多仓库(frontend / backend),merge 目标分支记录在 `.trellis/config.yaml` 的 `packages.<name>.merge_target` 中。
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## 配置
|
|
14
|
+
|
|
15
|
+
目标分支存储在 `.trellis/config.yaml` 的 packages 配置中:
|
|
16
|
+
|
|
17
|
+
```yaml
|
|
18
|
+
packages:
|
|
19
|
+
frontend:
|
|
20
|
+
path: iqs-front-human
|
|
21
|
+
git: true
|
|
22
|
+
merge_target: test # 首次 push 时询问后自动写入
|
|
23
|
+
backend:
|
|
24
|
+
path: iqs
|
|
25
|
+
git: true
|
|
26
|
+
merge_target: test
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
> 首次运行时如果 `merge_target` 不存在,会在 merge 步骤询问目标分支并回写到 `config.yaml`。
|
|
30
|
+
> 如需修改,直接编辑 `config.yaml` 或通过 `/trellis-push` 传入 `--reconfigure` 语义。
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## 执行步骤
|
|
35
|
+
|
|
36
|
+
### Step 0: 读取配置
|
|
37
|
+
|
|
38
|
+
读取 `.trellis/config.yaml` 中的 `packages` 配置,识别所有 `git: true` 的仓库及其 `merge_target`(如果已配置)。
|
|
39
|
+
|
|
40
|
+
### Step 1: 检测变更
|
|
41
|
+
|
|
42
|
+
读取 `.trellis/config.yaml` 中的 `packages` 配置,对每个 git 仓库检测变更:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
# 对每个 package
|
|
46
|
+
cd <package_path>
|
|
47
|
+
git status --short
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
列出有变更的仓库。如果所有仓库都没有变更,提示用户并终止。
|
|
51
|
+
|
|
52
|
+
如果只有部分仓库有变更,只处理有变更的仓库。
|
|
53
|
+
|
|
54
|
+
**收集所有变更文件列表** —— 用于 Step 1.5 的 PRD 同步判断:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
# 聚合每个仓库的变更文件(相对于仓库根的路径)+ 仓库名前缀
|
|
58
|
+
# 例如:["iqs-front-human/src/pages/inquiry/...", "iqs/src/main/java/..."]
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### Step 1.5: PRD 同步检查(智能判断)`[AI]`
|
|
62
|
+
|
|
63
|
+
在进入 Step 2 逐仓库 commit 前,先判断本次变更是否需要先同步 PRD。
|
|
64
|
+
|
|
65
|
+
#### 判断条件
|
|
66
|
+
|
|
67
|
+
1. **有激活任务**:仓库根下 `.trellis/.current-task` 文件存在,内容是任务目录相对路径
|
|
68
|
+
2. **任务有 PRD**:`<current_task>/prd.md` 存在
|
|
69
|
+
3. **变更命中任务相关文件**(relatedFiles 交集):
|
|
70
|
+
- 读取 `<current_task>/task.json` 的 `relatedFiles` 字段(数组,条目可能是文件或目录)
|
|
71
|
+
- 计算 Step 1 收集的变更文件清单与 `relatedFiles` 的交集(前缀匹配即算命中:变更文件路径以某个 `relatedFiles` 条目开头)
|
|
72
|
+
- `relatedFiles` 未配置或为空 → 跳过交集判断,**只要条件 1+2 成立就提示**
|
|
73
|
+
|
|
74
|
+
#### 处理分支
|
|
75
|
+
|
|
76
|
+
**不满足条件 1 或 2**(无激活任务 / 无 prd.md):静默跳过,直接进入 Step 2。
|
|
77
|
+
|
|
78
|
+
**满足条件 1+2+3**(交集非空 / 无 relatedFiles 配置):展示提示,等待用户选择:
|
|
79
|
+
|
|
80
|
+
```markdown
|
|
81
|
+
⚠️ 检测到当前任务 `<task-slug>` 下存在 prd.md。
|
|
82
|
+
本次变更 <N>/<M> 个文件命中 task.relatedFiles:
|
|
83
|
+
- <命中文件 1>
|
|
84
|
+
- <命中文件 2>
|
|
85
|
+
- ...
|
|
86
|
+
|
|
87
|
+
本次变更可能涉及 PRD 范围,建议先确认 PRD 是否与实际实现一致:
|
|
88
|
+
|
|
89
|
+
1. 先同步 PRD —— 暂停 push,调用 trellis-sync-prd
|
|
90
|
+
2. PRD 已同步 —— 继续 push
|
|
91
|
+
3. 与 PRD 无关(小改动 / hotfix)—— 跳过同步
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
- 用户选 **1** → 立即停止本次 push 流程,调用 trellis-sync-prd skill;完成后提示用户重新运行 `/trellis-push`
|
|
95
|
+
- 用户选 **2 或 3** → 继续进入 Step 2
|
|
96
|
+
|
|
97
|
+
> **[!] 这一步只是提示,不阻塞流程** —— 如果用户确认"与 PRD 无关",立刻继续;不要反复确认。
|
|
98
|
+
|
|
99
|
+
### Step 2: 逐仓库处理
|
|
100
|
+
|
|
101
|
+
对每个有变更的仓库,依次执行以下操作:
|
|
102
|
+
|
|
103
|
+
#### 2.1 展示变更摘要
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
cd <package_path>
|
|
107
|
+
git diff --stat
|
|
108
|
+
git diff --name-only
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
#### 2.2 暂存文件
|
|
112
|
+
|
|
113
|
+
展示要暂存的文件列表,**获得用户确认后**再暂存。
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
git add <具体文件列表>
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
> **[!] 禁止使用 `git add -A` 或 `git add .`**
|
|
120
|
+
> 必须明确列出文件,避免误提交敏感文件(.env、credentials 等)。
|
|
121
|
+
|
|
122
|
+
#### 2.3 生成 commit message 并提交
|
|
123
|
+
|
|
124
|
+
分析变更内容,生成符合项目风格的 commit message:
|
|
125
|
+
- 读取最近 5 条 commit 参考风格
|
|
126
|
+
- 类型前缀:`feat` / `fix` / `chore` / `refactor` 等
|
|
127
|
+
- 简短描述变更内容
|
|
128
|
+
- 使用中文描述
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
git commit -m "<type>(<scope>): <description>"
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
#### 2.4 Push 当前分支
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
git push origin <current_branch>
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
如果远程没有该分支,使用 `-u` 建立跟踪:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
git push -u origin <current_branch>
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
#### 2.5 询问是否 Merge 到目标分支(可选)
|
|
147
|
+
|
|
148
|
+
Push 完成后,检查该 package 是否已配置 `merge_target`:
|
|
149
|
+
|
|
150
|
+
**已配置 `merge_target`**:
|
|
151
|
+
|
|
152
|
+
```markdown
|
|
153
|
+
<package> 已推送到 <current_branch>。是否合并到 <merge_target>?
|
|
154
|
+
|
|
155
|
+
1. 是,合并到 <merge_target>
|
|
156
|
+
2. 否,跳过
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
**未配置 `merge_target`(首次)**:
|
|
160
|
+
|
|
161
|
+
```markdown
|
|
162
|
+
<package> 已推送到 <current_branch>。是否需要合并到其他分支(如测试线)?
|
|
163
|
+
|
|
164
|
+
1. 是,请输入目标分支名
|
|
165
|
+
2. 否,跳过
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
如果用户输入了目标分支名,**将其回写到 `.trellis/config.yaml`** 对应 package 的 `merge_target` 字段,下次自动使用。
|
|
169
|
+
|
|
170
|
+
**如果用户选择合并**:
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
# 切换到目标分支并拉取最新
|
|
174
|
+
git checkout <target_branch>
|
|
175
|
+
git pull origin <target_branch>
|
|
176
|
+
|
|
177
|
+
# 合并当前开发分支
|
|
178
|
+
git merge <current_branch> --no-edit
|
|
179
|
+
|
|
180
|
+
# Push 目标分支
|
|
181
|
+
git push origin <target_branch>
|
|
182
|
+
|
|
183
|
+
# 切回开发分支
|
|
184
|
+
git checkout <current_branch>
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
> **[!] 如果 merge 出现冲突:**
|
|
188
|
+
> 1. 立即停止,展示冲突文件列表
|
|
189
|
+
> 2. 询问用户:手动解决 / 中止 merge
|
|
190
|
+
> 3. **绝对不能** `git merge --abort` 后静默跳过
|
|
191
|
+
|
|
192
|
+
**如果用户选择跳过**:直接进入下一个仓库或输出结果。
|
|
193
|
+
|
|
194
|
+
### Step 3: 输出结果
|
|
195
|
+
|
|
196
|
+
```markdown
|
|
197
|
+
## Push 结果
|
|
198
|
+
|
|
199
|
+
| 仓库 | 分支 | 目标 | commit | 状态 |
|
|
200
|
+
|------|------|------|--------|------|
|
|
201
|
+
| frontend | v1.3 | test | abc1234 feat(...): ... | ✅ 已合并 |
|
|
202
|
+
| backend | v1.3 | test | def5678 fix(...): ... | ⏭️ 跳过合并 |
|
|
203
|
+
|
|
204
|
+
所有变更已推送到目标分支。
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
---
|
|
208
|
+
|
|
209
|
+
## 语义参数(通过自然语 / skill args 传入)
|
|
210
|
+
|
|
211
|
+
| 语义 | 说明 | 用户怎么说 |
|
|
212
|
+
|------|------|-----------|
|
|
213
|
+
| 默认 | 自动检测所有有变更的仓库并处理 | `/trellis-push` |
|
|
214
|
+
| 指定仓库 | 只处理指定仓库 | 「只 push 前端」/「push frontend」 |
|
|
215
|
+
| 重新配置 | 重新询问目标分支 | 「重新配置 push 目标分支」/「reconfigure push」 |
|
|
216
|
+
| 临时目标 | 临时指定目标分支(不修改配置) | 「push 到 hotfix 分支」 |
|
|
217
|
+
| 跳过 PRD 检查 | 明确本次与 PRD 无关 | 「这次 hotfix 不用检查 PRD」 |
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## 安全机制
|
|
222
|
+
|
|
223
|
+
1. **暂存确认** — 每个仓库暂存前展示文件列表,用户确认
|
|
224
|
+
2. **commit message 确认** — 展示生成的 message,用户可修改
|
|
225
|
+
3. **merge 冲突处理** — 冲突时暂停,不静默跳过
|
|
226
|
+
4. **不碰主分支** — 如果目标分支是 `master` / `main`,额外警告确认
|
|
227
|
+
5. **不使用 force push** — 始终使用普通 push
|
|
228
|
+
6. **PRD 同步提示** — Step 1.5 智能检测任务相关变更,提示先同步 PRD
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
## 反模式(避免)
|
|
233
|
+
|
|
234
|
+
- ❌ `git add -A`(可能误提交敏感文件)
|
|
235
|
+
- ❌ merge 冲突后静默 abort(用户需要知道)
|
|
236
|
+
- ❌ 未经确认直接 commit(必须让用户看到 message)
|
|
237
|
+
- ❌ force push 到目标分支
|
|
238
|
+
- ❌ 在目标分支上直接开发(只 merge,不在目标分支上改代码)
|
|
239
|
+
- ❌ 跳过 Step 1.5 PRD 同步检查(即使只是提示,也是给用户一次"想起来"的机会)
|
|
240
|
+
- ❌ Step 1.5 提示后反复追问(用户明确 "跳过" 就继续,不要第二次确认)
|