trellis-hgl 0.6.0-beta.29 → 0.6.0-beta.30
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 +2 -2
- package/dist/migrations/manifests/0.6.0-beta.30.json +9 -0
- package/dist/templates/common/commands/start.md +9 -1
- package/dist/templates/common/skills/brainstorm.md +9 -1
- package/dist/templates/common/skills/grill-me.md +9 -0
- package/dist/templates/trellis/workflow.md +18 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -225,7 +225,7 @@
|
|
|
225
225
|
### 安装
|
|
226
226
|
|
|
227
227
|
```bash
|
|
228
|
-
npm install -g trellis-hgl@
|
|
228
|
+
npm install -g trellis-hgl@latest
|
|
229
229
|
```
|
|
230
230
|
|
|
231
231
|
### 卸载
|
|
@@ -241,7 +241,7 @@ npm uninstall -g trellis-hgl
|
|
|
241
241
|
npm uninstall -g @mindfoldhq/trellis
|
|
242
242
|
|
|
243
243
|
# 安装最新版 trellis-hgl
|
|
244
|
-
npm install -g trellis-hgl@
|
|
244
|
+
npm install -g trellis-hgl@latest
|
|
245
245
|
|
|
246
246
|
# 进入你自己的项目目录
|
|
247
247
|
cd /path/to/your/project
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": "0.6.0-beta.30",
|
|
3
|
+
"description": "Beta 补丁：强化 Claude Code planning 的 research-first 提问路径，并用 AskUserQuestion 配置开发策略。",
|
|
4
|
+
"breaking": false,
|
|
5
|
+
"recommendMigrate": false,
|
|
6
|
+
"changelog": "**改进：**\n- feat(workflow): Claude Code planning 在进入 `trellis-brainstorm` 前，会先按 research-first gate 调用 `trellis-research` 调研代码，并把结果写入任务 `research/` 目录。后续问题必须基于调研证据提出，减少盲猜式、兜底式追问。\n- feat(workflow): 开发策略配置优先使用 Claude Code 原生 `AskUserQuestion`，用结构化单选/多选收集执行模式、工作区模式、开发流程、架构指导和 review-gate 选择。\n- docs(upgrade): 升级说明改为推荐 `trellis upgrade` 或 `npm install -g trellis-hgl@latest`，避免依赖当前滞后的 npm `beta` dist-tag。\n\n**说明：**\n- 现有项目执行 `trellis update` 后即可同步新的 workflow、skills 与启动提示。",
|
|
7
|
+
"migrations": [],
|
|
8
|
+
"notes": "安装此版本后请在已有项目中运行 `trellis update`，以同步 Claude Code planning 的 research-first 提问路径和 AskUserQuestion 开发策略配置提示。推荐使用 `trellis upgrade` 或 `npm install -g trellis-hgl@latest` 获取最新版本；不要依赖当前滞后的 `trellis-hgl@beta` dist-tag。"
|
|
9
|
+
}
|
|
@@ -37,7 +37,15 @@ Index files list the specific guideline docs to read when you actually start cod
|
|
|
37
37
|
From Step 1 you know the current task and status. Check the task directory:
|
|
38
38
|
|
|
39
39
|
- **Active task status `planning` + no `prd.md`** → Phase 1.1. Load the `trellis-brainstorm` skill.
|
|
40
|
-
- **Active task status `planning` + `prd.md` exists** → stay in Phase 1. Lightweight tasks can be PRD-only; complex tasks need `design.md` + `implement.md`. For the Claude Code path, keep requirement clarification in `prd.md`, continue repository-first follow-up questioning by entering `trellis-grill-me`, and treat it as a required planning gate. Before `trellis-grill-me` is complete, do not enter development strategy decisions, do not create or complete `design.md` / `implement.md`, and do not run `task.py start`.
|
|
40
|
+
- **Active task status `planning` + `prd.md` exists** → stay in Phase 1. Lightweight tasks can be PRD-only; complex tasks need `design.md` + `implement.md`. For the Claude Code path, keep requirement clarification in `prd.md`, continue repository-first follow-up questioning by entering `trellis-grill-me`, and treat it as a required planning gate. Before `trellis-grill-me` is complete, do not enter development strategy decisions, do not create or complete `design.md` / `implement.md`, and do not run `task.py start`.
|
|
41
|
+
- Before `task.py start`, record the decisions in the task documents: development mode, branch vs worktree, default flow vs TDD, pre-development architecture guidance, plus the task-level review-gate selection.
|
|
42
|
+
- On Claude Code, prefer the native `AskUserQuestion` tool for these development strategy decisions instead of a plain Markdown prompt. Each `AskUserQuestion` question must have 2–4 options. Split the decision into structured questions for development/workspace mode, default flow/TDD and architecture guidance, core review gates, and add-on review gates. Use `multiSelect: true` for review-gate questions.
|
|
43
|
+
- Core review gates are `trellis-spec-review`, `trellis-code-review`, and `trellis-code-architecture-review`; add-on review gates are `trellis-improve-codebase-architecture` and `trellis-merge-review`. Do not offer default review-gate packages; let the user directly select enabled gates, then write explicit enabled/disabled lists.
|
|
44
|
+
- If `AskUserQuestion` is unavailable, rejected, or the user chooses Other, fall back to a text `A.` / `B.` / `C.` option block or targeted free-text follow-up, but ask only for unresolved fields and never repeat answered choices unchanged.
|
|
45
|
+
- New tasks must stamp that block with `Review-gate contract: explicit-selection-v1`. Complex tasks should keep that record in `implement.md` together with the enabled/disabled review gates and the preserved order for any enabled Claude review gates: `trellis-spec-review` → `trellis-code-review` → `trellis-code-architecture-review`.
|
|
46
|
+
- While the choice is still open, `Optional review gates status: pending` is allowed; before `task.py start`, replace it with `Optional review gates status: configured` plus explicit `Enabled optional review gates:` and `Disabled optional review gates:` lists for the selectable review gates (`trellis-spec-review`, `trellis-code-review`, `trellis-code-architecture-review`, `trellis-improve-codebase-architecture`, `trellis-merge-review`). If the user leaves all optional gates off, still record all five in the disabled list while keeping `trellis-check` fixed outside that set.
|
|
47
|
+
- Only tasks that entirely lack `Review-gate contract: explicit-selection-v1` count as legacy tasks and preserve the old behavior; if the marker exists but the configured enabled/disabled lists are missing, planning is incomplete and the task must not start. `trellis-improve-codebase-architecture` deep-review requires `trellis-code-architecture-review`; do not record or accept deep-review without that prerequisite gate.
|
|
48
|
+
- If the strategy is `subagent + worktree`, pin `./.trellis/trellis-worktrees/<task-dir-name>`. On Claude Code, that shared worktree is different from host `Agent(..., isolation: "worktree")`; when both collide, the hook removes the host isolation input before dispatch. If the strategy is TDD, record `trellis-tdd` as the reference flow. If guidance is enabled, record `架构审查：enabled`, dispatch `trellis-improve-codebase-architecture` with `架构审查模式: guidance` before `task.py start`, and append its output to `design.md`, but do NOT implicitly enable `trellis-improve-codebase-architecture` deep-review; that gate still requires explicit selection in the task-level review-gate set.
|
|
41
49
|
- **Active task status `in_progress`** → Phase 2 step 2.1. Load the step detail:
|
|
42
50
|
```bash
|
|
43
51
|
{{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase --step 2.1 --platform {{CLI_FLAG}}
|
|
@@ -14,6 +14,14 @@ This is mandatory. Before asking the user a question, first check whether the an
|
|
|
14
14
|
|
|
15
15
|
Do not ask the user to confirm facts that the repository can answer. Ask only for product intent, preference, scope, risk tolerance, or decisions that remain ambiguous after inspection.
|
|
16
16
|
|
|
17
|
+
## Claude Code Research Gate
|
|
18
|
+
|
|
19
|
+
On the Claude Code path, feature additions, feature changes, and bug fixes that depend on repository facts must run `trellis-research` before the first `trellis-brainstorm` question. When this gate triggers, explicitly tell the user that repository evidence is required, `trellis-research` is running first, and questioning will resume from the findings. Research findings must be persisted to `{TASK_DIR}/research/` and used to frame the first question.
|
|
20
|
+
|
|
21
|
+
Do not trigger the pre-brainstorm research gate for pure conversation, capability or usage explanation, pure user preference choices, copy edits that do not depend on repository facts, explicitly local-only small tasks, or when the user explicitly asks to skip research and answer directly.
|
|
22
|
+
|
|
23
|
+
If a later user answer would materially change the current understanding of repository facts, pause the interview and run `trellis-research` again before asking the next question. If research is inconclusive, report what was checked, which evidence is missing, and which product intent or scope decision the user must provide before asking the question.
|
|
24
|
+
|
|
17
25
|
---
|
|
18
26
|
|
|
19
27
|
Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
|
|
@@ -49,7 +57,7 @@ Use a concise title from the user's request. Use a slug without a date prefix. `
|
|
|
49
57
|
6. After each user answer, update `prd.md` before continuing.
|
|
50
58
|
7. Once repository-answerable questions are exhausted, enter `trellis-grill-me` and tighten the remaining requirement gaps one question at a time, each with a recommendation, while still updating `prd.md` after each answer.
|
|
51
59
|
8. On the Claude Code path, `trellis-grill-me` is a required planning gate. Before it is complete, do not switch into development strategy decisions, do not create or complete `design.md` / `implement.md`, and do not run `task.py start`.
|
|
52
|
-
9. Before implementation starts on the Claude Code path, record the development strategy decisions in the task documents: development mode, branch vs worktree, default flow vs TDD, and the task-level review-gate selection.
|
|
60
|
+
9. Before implementation starts on the Claude Code path, record the development strategy decisions in the task documents: development mode, branch vs worktree, default flow vs TDD, and the task-level review-gate selection. Prefer Claude Code's native `AskUserQuestion` tool for this development strategy decision instead of a plain Markdown prompt. Every `AskUserQuestion` question must have 2–4 options; do not put all five optional review gates in one question. Use structured questions for development/workspace mode, flow/architecture guidance, core review gates with `multiSelect: true`, and add-on review gates with `multiSelect: true`. Core review gates are `trellis-spec-review`, `trellis-code-review`, and `trellis-code-architecture-review`; add-on review gates are `trellis-improve-codebase-architecture` and `trellis-merge-review`. Do not offer default review-gate packages; let the user directly multi-select enabled gates, then write the explicit enabled/disabled lists. If `AskUserQuestion` is unavailable, rejected, or the user chooses Other, fall back to a text `A.` / `B.` / `C.` option block or targeted free-text follow-up, but ask only for unresolved fields and never repeat answered choices unchanged. New tasks must stamp that strategy block with `Review-gate contract: explicit-selection-v1`. Lightweight tasks may keep that record in `prd.md`; complex tasks should keep it in `implement.md` together with the enabled/disabled review gates and the preserved execution order for any enabled Claude review gates: `trellis-spec-review` → `trellis-code-review` → `trellis-code-architecture-review`. The selectable review gates are `trellis-spec-review`, `trellis-code-review`, `trellis-code-architecture-review`, `trellis-improve-codebase-architecture`, and `trellis-merge-review`. While the choice is still open, `Optional review gates status: pending` is allowed; before `task.py start`, replace it with `Optional review gates status: configured` plus explicit `Enabled optional review gates:` and `Disabled optional review gates:` lists. If the user leaves all optional gates off, still record all five in the disabled list; `trellis-check` stays fixed outside this set. Only tasks that entirely lack `Review-gate contract: explicit-selection-v1` count as legacy tasks and preserve the old behavior; if the marker exists but the configured enabled/disabled lists are missing, planning is incomplete and the task must not start. `trellis-improve-codebase-architecture` deep-review requires `trellis-code-architecture-review`, so do not record or accept the deep-review gate without that prerequisite. If the strategy is `subagent + worktree`, pin `./.trellis/trellis-worktrees/<task-dir-name>`. If the strategy is TDD, record `trellis-tdd` as the reference flow. Also record whether to run pre-development architecture guidance in that same strategy block. If guidance is enabled, record `架构审查：enabled`, dispatch `trellis-improve-codebase-architecture` with `架构审查模式: guidance` before `task.py start`, and append its output to `design.md`, but do NOT implicitly enable `trellis-improve-codebase-architecture` deep-review; that gate still requires explicit selection in the task-level review-gate set.
|
|
53
61
|
10. For complex tasks, create or update `design.md` and `implement.md` only after `trellis-grill-me` is complete and implementation is about to start.
|
|
54
62
|
|
|
55
63
|
Do not invent a project-specific product/spec hierarchy. If the repository already has product, domain, or spec docs, use them. If it does not, proceed with the evidence that exists.
|
|
@@ -17,6 +17,14 @@ Use this skill only when:
|
|
|
17
17
|
|
|
18
18
|
Do **not** use this skill for questions the codebase can answer directly.
|
|
19
19
|
|
|
20
|
+
## Claude Code Research Gate
|
|
21
|
+
|
|
22
|
+
On the Claude Code path, this skill may only continue after the active planning thread has already run any required `trellis-research` pass and persisted findings to `{TASK_DIR}/research/` for repository-dependent feature additions, feature changes, or bug fixes.
|
|
23
|
+
|
|
24
|
+
Before each question, check whether the remaining gap is still a repository fact. If it is, stop the interview, explicitly tell the user that repository evidence is required, run `trellis-research`, persist the result, and then continue from the evidence. If research is inconclusive, report what was checked, which evidence is missing, and the exact product intent or scope decision needed from the user.
|
|
25
|
+
|
|
26
|
+
If a user answer would materially change the current understanding of repository facts, run `trellis-research` again before asking the next follow-up question.
|
|
27
|
+
|
|
20
28
|
## Interview Contract
|
|
21
29
|
|
|
22
30
|
- Ask one question at a time.
|
|
@@ -47,3 +55,4 @@ By the time this skill is done:
|
|
|
47
55
|
- `prd.md` has testable acceptance criteria
|
|
48
56
|
- unresolved questions are truly strategic, not factual
|
|
49
57
|
- implementation can move on to development mode / worktree / TDD decisions
|
|
58
|
+
- the next Claude Code development strategy decision should prefer `AskUserQuestion`; each question must have 2–4 options, review gates must be split into core and add-on `multiSelect: true` questions, and text fallback should ask only unresolved fields
|
|
@@ -185,10 +185,12 @@ Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and
|
|
|
185
185
|
Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position.
|
|
186
186
|
Sub-agent mode: curate `implement.jsonl` and `check.jsonl` as spec/research manifests before start.
|
|
187
187
|
|
|
188
|
-
|
|
188
|
+
Claude Code research-first gate: for feature additions, feature changes, and bug fixes that depend on repository facts, run `trellis-research` before the first `trellis-brainstorm` question and persist findings to `{TASK_DIR}/research/`. When this gate triggers, explicitly tell the user that repository evidence is required, `trellis-research` is running first, and questioning will resume from the findings. Do not trigger this pre-brainstorm gate for pure conversation, capability or usage explanation, pure user preference choices, copy edits that do not depend on repository facts, explicitly local-only small tasks, or when the user explicitly asks to skip research and answer directly. If a later user answer would materially change the current understanding of repository facts, pause and run `trellis-research` again before the next question. If research is inconclusive, report what was checked, what evidence is missing, and which product intent or scope decision the user must provide before asking the question.
|
|
189
|
+
Planning order for this Claude Code path: `task.py create` → `trellis-research` when the research-first gate applies → `trellis-brainstorm` → `trellis-grill-me` → development strategy decision.
|
|
189
190
|
`trellis-grill-me` is a required planning gate on this Claude Code path, not an optional suggestion.
|
|
190
191
|
Before `trellis-grill-me` is complete, do not enter development strategy decisions, do not create or complete `design.md` / `implement.md`, and do not run `task.py start`.
|
|
191
192
|
Do not enter development strategy decisions until `prd.md` has been tightened through repository-first clarification and one-question-at-a-time follow-up.
|
|
193
|
+
At the Claude Code development strategy decision point, prefer the native `AskUserQuestion` tool instead of plain Markdown prompts. Every `AskUserQuestion` question must have 2–4 options; do not put all five optional review gates in one question. Use structured questions for development/workspace mode, flow/architecture guidance, core review gates with `multiSelect: true`, and add-on review gates with `multiSelect: true`. Core review gates are `trellis-spec-review`, `trellis-code-review`, and `trellis-code-architecture-review`; add-on review gates are `trellis-improve-codebase-architecture` and `trellis-merge-review`. Do not offer default review-gate packages; let the user directly multi-select enabled gates, then write the explicit enabled/disabled lists. If `AskUserQuestion` is unavailable, rejected, or the user chooses Other, fall back to a text `A.` / `B.` / `C.` block or targeted free-text follow-up, but ask only for unresolved fields and never repeat answered choices unchanged.
|
|
192
194
|
Before `task.py start`, record the development strategy decisions in the task documents. Complex tasks should store them in `implement.md`: development mode (current session / subagent), branch vs worktree, default flow vs TDD, plus a single `A.` / `B.` / `C.` style strategy block that records the task-level selection for `trellis-spec-review`, `trellis-code-review`, `trellis-code-architecture-review`, `trellis-improve-codebase-architecture`, and `trellis-merge-review`. New tasks must stamp that block with `Review-gate contract: explicit-selection-v1`. Use `Optional review gates status: pending` only while the choice is still open; before `task.py start`, replace it with `Optional review gates status: configured` plus explicit `Enabled optional review gates:` and `Disabled optional review gates:` lists. If the user does not select any optional gate, still record all five in the disabled list and keep `trellis-check` fixed outside the optional set. Only tasks that entirely lack `Review-gate contract: explicit-selection-v1` count as legacy tasks and preserve the old behavior; if the marker exists but the configured enabled/disabled lists are missing, planning is incomplete and the task must not start. `trellis-improve-codebase-architecture` deep-review requires `trellis-code-architecture-review`; do not record or accept deep-review without that prerequisite gate. If the strategy is `subagent + worktree`, pin the shared path to `./.trellis/trellis-worktrees/<task-dir-name>` and require every code-development subagent to use it. If the strategy is TDD, record `trellis-tdd` as the reference flow. Record whether to run pre-development architecture guidance in that same strategy block. If guidance is enabled, record `架构审查：enabled` in `implement.md`, dispatch `trellis-improve-codebase-architecture` with `架构审查模式: guidance` before `task.py start`, and append its output to `design.md`, but do NOT implicitly enable `trellis-improve-codebase-architecture` deep-review; that gate still requires explicit selection in the same task-level review-gate set.
|
|
193
195
|
[/workflow-state:planning]
|
|
194
196
|
|
|
@@ -339,6 +341,14 @@ python3 ./.trellis/scripts/task.py create "<任务标题>" --slug <name>
|
|
|
339
341
|
|
|
340
342
|
加载 `trellis-brainstorm` skill，并按该 skill 的指导与用户交互式澄清需求。
|
|
341
343
|
|
|
344
|
+
Claude Code research-first gate:
|
|
345
|
+
- 对新增功能、修改现有功能，以及依赖仓库事实的 bug fix，在第一个 `trellis-brainstorm` 问题前先分派 `trellis-research`，并把研究结果写入 `{TASK_DIR}/research/`。
|
|
346
|
+
- 触发该门槛时，先明确告诉用户当前问题需要仓库证据、正在先执行 `trellis-research`，并会基于调研结果继续提问或收敛需求。
|
|
347
|
+
- 排除：纯对话、能力说明、用法解释、纯用户偏好选择、不依赖仓库事实的文案润色、明确只做局部处理的小任务，以及用户明确要求先别 research / 先直接问的请求。
|
|
348
|
+
- 第一次 research 后，问题必须基于 research 结果提出，而不是脱离仓库事实兜底猜测。
|
|
349
|
+
- 如果用户回答会明显影响“仓库当前事实”，继续追问或收敛需求前必须再次分派 `trellis-research`。
|
|
350
|
+
- 如果 research 无法找到足够证据，继续问用户前必须先报告已查证据、缺失证据和需要用户补充的具体意图或范围。
|
|
351
|
+
|
|
342
352
|
brainstorm skill 会指导你：
|
|
343
353
|
- 一次只问一个问题
|
|
344
354
|
- 能靠调研回答的就先调研，不要先问用户
|
|
@@ -357,6 +367,13 @@ brainstorm skill 会指导你：
|
|
|
357
367
|
- 启动拥有下一个交付物的子任务。Do not start the parent unless the parent itself has direct implementation work.
|
|
358
368
|
|
|
359
369
|
在 Claude Code 路径进入实现前，把开发策略决策写入任务文档。
|
|
370
|
+
- 进入开发策略决策时，优先调用 Claude Code 原生 `AskUserQuestion` 工具，而不是只输出普通 Markdown 选项块。
|
|
371
|
+
- 每个 `AskUserQuestion` question 必须只有 2–4 options；不要把 5 个 optional review gates 放进同一个 question。
|
|
372
|
+
- 推荐拆分为：开发模式 / 工作区模式单选、默认流程 / TDD 与架构指导单选、核心 review gates 多选、附加 review gates 多选。
|
|
373
|
+
- 核心 review gates 问题使用 `multiSelect: true`，只包含 `trellis-spec-review`、`trellis-code-review`、`trellis-code-architecture-review`。
|
|
374
|
+
- 附加 review gates 问题使用 `multiSelect: true`，只包含 `trellis-improve-codebase-architecture` 和 `trellis-merge-review`。
|
|
375
|
+
- 不提供默认 review-gate 套餐；让用户直接多选要启用的 gates，再把未选项写入 disabled 列表。
|
|
376
|
+
- 如果 `AskUserQuestion` 不可用、被拒绝或用户选择 Other，退回文本 `A.` / `B.` / `C.` 选项块或定向自由文本补问，但只补齐未决字段，不要原样重复已回答选择。
|
|
360
377
|
- 轻量任务可以把这些记录写在 `prd.md`。
|
|
361
378
|
- 复杂任务应把这些策略、task-local review-gate 选择，以及任何已启用 Claude review gate 的保序执行顺序写在 `implement.md`。
|
|
362
379
|
- 需要在同一个 `A.` / `B.` / `C.` 风格策略块里记录：当前会话 vs subagent、当前分支 vs worktree、默认流程 vs TDD、是否启用 pre-development architecture guidance，以及 `trellis-spec-review`、`trellis-code-review`、`trellis-code-architecture-review`、`trellis-improve-codebase-architecture`、`trellis-merge-review` 的任务级选择。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "trellis-hgl",
|
|
3
|
-
"version": "0.6.0-beta.
|
|
3
|
+
"version": "0.6.0-beta.30",
|
|
4
4
|
"description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
"inquirer": "^9.3.7",
|
|
35
35
|
"undici": "^6.21.0",
|
|
36
36
|
"zod": "^4.4.2",
|
|
37
|
-
"trellis-hgl-core": "0.6.0-beta.
|
|
37
|
+
"trellis-hgl-core": "0.6.0-beta.30"
|
|
38
38
|
},
|
|
39
39
|
"devDependencies": {
|
|
40
40
|
"@eslint/js": "^9.18.0",
|