@pennixrv/trellis 0.7.0-beta.45 → 0.7.0-beta.47

package/dist/templates/trellis/workflow.md

@@ -1,104 +1,63 @@
-# Development Workflow
+# 开发工作流（Development Workflow）
 
 ---
 
-## Core Principles
+## 核心原则（Core Principles）
 
-1. **Plan before code** — figure out what to do before you start
-2. **Specs injected, not remembered** — guidelines are injected via hook/skill, not recalled from memory
-3. **Persist everything** — research, decisions, and lessons all go to files; conversations get compacted, files don't
-4. **Incremental development** — one task at a time
-5. **Capture learnings** — after each task, review and write new knowledge back to spec
+1. **先规划再编码**——开始前先明确要做什么。
+2. **注入规范而不是凭记忆遵守**——指南通过 Hook/Skill 注入，而不是从记忆中调用。
+3. **全部持久化**——研究、决策和经验都写入文件；对话会压缩，文件不会。
+4. **增量开发**——一次推进一个任务。
+5. **记录经验**——每个任务完成后复盘，并将新知识写回 spec。
 
 ---
 
-### Continuation and Compaction
-
-Reuse the current conversation or sufficient compaction checkpoint when root,
-task, phase, authorization and pending action are known. An ordinary continue
-resumes that action without repeated startup, task/Git/history or handoff
-validation. Query only missing/conflicting facts for a fresh session, changed
-target or explicit inspection. Native protected writes retain owner identity
-and ownership checks. Never repeat or re-answer consumed pre-compaction user
-input; handle genuinely new input normally. No recovery cache or extra waiter.
-
-## Plan Approval And Task Selection
-
-Classify task meta explicitly as `execution_class=direct|planned` and
-`delivery_mode=change_bearing|analysis_only`; an unclassified old planning task
-needs this once before start. Direct small work and eligible analysis-only work
-retain their existing shortest paths. Existing in-progress tasks are not reset.
-
-Except for clearly bounded research, screen consequential user-owned choices
-with `pennix-decision-grill`; one material choice is sufficient. It owns the
-progressive questioning method, not task lifecycle. Use dependency-ready,
-evidence-backed choices first, then impact/priority; ask one to three coherent
-independent decisions and reassess after answers. Do not ask discoverable facts
-or settled implementation details. Save the decision checkpoint before bounded
-local/web evidence or explicitly approved independent subnodes. An empty ready
-frontier may mean missing evidence, not a closed plan.
-
-For planned/change-bearing work, close decisions and required task artifacts,
-run native `task.py plan seal <task>`, present that material plan, and stop before
-implementation. Only a later explicit user approval for THIS task's CURRENT
-sealed revision authorizes `task.py plan approve <task> --revision <n> --basis
-"<short non-sensitive actual approval basis>"`, then `task.py start`. Initial
-delivery requests, parent-task approval, and design answers do not qualify.
-`--allow-empty-context` overrides only context manifests, never approval.
-The native record enforces structure; chat authenticity remains agent-owned.
-
-Material scope, owner, risk, public behavior, or acceptance changes require
-`task.py replan` and a newly sealed, presented, subsequently approved revision.
-Resealing a sealed planning task declares a new material revision. Wording,
-formatting, progress, and execution evidence do not automatically invalidate it.
-Generic create/set-meta cannot prefill the reserved `meta.planning` record.
-
-An explicitly user-requested addition to an `in_progress` task may continue in
-the current phase when it serves the same task, keeps the same actual owner and
-target, is small, reversible, and low risk, and changes none of the sealed
-scope in substance, owner, risk, public behavior, data integrity, credentials,
-deployment/release path, or acceptance. Record the request, classification,
-owner, acceptance, and verification in the unsealed execution record; the
-request authorizes only that exact addition. If any condition is false or
-unclear, preserve the current conclusion, record `decision-needed`, and use
-native `task.py replan` with the normal new-seal and later-approval path.
-
-Use native `task.py select <task>` for context-only selection: no phase/branch
-change, after_start hook, or implementation authority. `create --no-start`
-deliberately keeps the prior pointer. Save the old checkpoint before switching;
-with live Channel work, pause refills and drain all already dispatched units and
-reservations according to `trellis-channel`'s multi-target procedure, preserving
-pending units and the old phase. Do not kill/retry or automatically restart a
-user-stopped task. Ordinary continue/compaction retains the checkpoint fast path.
-
-## Trellis System
-
-### Developer Identity
-
-On first use, initialize your identity:
+### 继续与压缩恢复（Continuation and Compaction）
+
+根目录、任务、阶段、授权和待执行动作已知时，复用当前对话或足够的压缩检查点。普通继续直接恢复该动作，不重复启动、任务/Git/历史或交接核验。新会话、目标变化或用户明确要求检查时，只查询缺失或冲突事实。原生受保护写入保留 owner 身份和所有权检查。不要重复或重答压缩前已经消费的用户输入；真正的新输入按正常流程处理。不增加恢复缓存或额外等待器。
+
+## 方案批准与任务选择（Plan Approval And Task Selection）
+
+显式将任务元数据分类为 `execution_class=direct|planned` 和 `delivery_mode=change_bearing|analysis_only`；未分类的旧 planning 任务需在 start 前补一次分类。直接小任务和符合条件的 analysis-only 任务保留现有最短路径。已有 in_progress 任务不重置。
+
+除边界清晰的研究外，使用 `pennix-decision-grill` 筛选涉及用户实质取舍的选择；一个实质选择即可触发。它负责渐进提问方法，不负责任务生命周期。先处理依赖已满足且有证据支撑的选择，再处理影响和优先级；一次询问一至三个相互独立且连贯的决策，回答后重新评估。不要询问可直接查明的事实或已经确定的实现细节。在执行有界本地/网络证据工作或明确批准独立子节点前保存决策检查点。可执行前沿为空可能表示缺少证据，不表示方案已封口。
+
+对于 planned/change-bearing 工作，先收敛决策和必要任务资产，运行原生 `task.py plan seal <task>`，展示实质方案并停在实施前。只有之后用户明确批准**当前任务当前封口版本**，才可运行 `task.py plan approve <task> --revision <n> --basis "<简短且不含敏感信息的实际批准依据>"`，然后运行 `task.py start`。最初的交付请求、父任务批准和设计答复都不构成实施批准。`--allow-empty-context` 只覆盖上下文清单，不覆盖批准门禁。原生记录负责结构约束，对话真实性仍由 Agent 负责。
+
+实质范围、owner、风险、公开行为或验收变化必须运行 `task.py replan`，重新封口、展示并取得新版本批准。对已封口的 planning 任务重新封口会产生新的实质版本。措辞、格式、进度和执行证据不会自动使封口失效。通用 create/set-meta 不能预填保留的 `meta.planning` 记录。
+
+用户明确要求向 `in_progress` 任务增加内容时，只有该内容服务于同一任务、保持实际 owner 和目标不变、规模小、可逆且风险低，并且实质上不改变已封口的范围、owner、风险、公开行为、数据完整性、凭据、部署/发布路径或验收，才可在当前阶段继续。将请求、分类、owner、验收和验证写入未封口执行记录；该请求只授权这一项明确增加的内容。任何条件不满足或不清楚时，保留当前结论，记录 `decision-needed`，使用原生 `task.py replan`，走重新封口和后续批准路径。
+
+使用原生 `task.py select <task>` 只选择上下文：它不改变阶段或分支，不触发 after_start Hook，也不授予实施权限。`create --no-start` 有意保留之前的指针。切换前保存旧检查点；存在活动 Channel 工作时，按 `trellis-channel` 的多目标流程暂停补充并排空已派发单元和预留，保留待处理单元及旧阶段。不要终止/重试或自动重启用户停止的任务。普通继续/压缩恢复保留检查点快速路径。
+
+## Trellis 系统（Trellis System）
+
+### 开发者身份（Developer Identity）
+
+首次使用时初始化身份：
 
 ```bash
 python3 ./.trellis/scripts/init_developer.py <your-name>
 ```
 
-Creates `.trellis/.developer` (gitignored) + `.trellis/workspace/<your-name>/`.
+创建 `.trellis/.developer`（由 git 忽略）和 `.trellis/workspace/<your-name>/`。
 
-### Spec System
+### Spec 系统（Spec System）
 
-`.trellis/spec/` holds coding guidelines organized by package and layer.
+`.trellis/spec/` 按包和层保存编码指南。
 
-- `.trellis/spec/<package>/<layer>/index.md` — entry point with **Pre-Development Checklist** + **Quality Check**. Actual guidelines live in the `.md` files it points to.
-- `.trellis/spec/guides/index.md` — cross-package thinking guides.
+- `.trellis/spec/<package>/<layer>/index.md`——包含**开发前清单（Pre-Development Checklist）**和**质量检查（Quality Check）**的入口，实际指南位于它链接的 `.md` 文件。
+- `.trellis/spec/guides/index.md`——跨包思考指南。
 
 ```bash
 python3 ./.trellis/scripts/get_context.py --mode packages   # list packages / layers
 ```
 
-**When to update spec**: new pattern/convention found · bug-fix prevention to codify · new technical decision.
+**更新 spec 的时机**：发现新的模式/约定、需要固化错误修复预防措施或形成新的技术决策。
 
-### Task System
+### 任务系统（Task System）
 
-Every task has its own directory under `.trellis/tasks/{MM-DD-name}/` holding `task.json`, `prd.md`, optional `design.md`, optional `implement.md`, optional `research/`, and context manifests (`implement.jsonl`, `check.jsonl`) for sub-agent-capable platforms.
+每个任务在 `.trellis/tasks/{MM-DD-name}/` 下有自己的目录，其中包含 `task.json`、`prd.md`、可选的 `design.md`、可选的 `implement.md`、可选的 `research/`，以及在支持子代理的平台上使用的上下文清单（`implement.jsonl`、`check.jsonl`）。
 
 ```bash
 # Task lifecycle
@@ -137,22 +96,22 @@ python3 ./.trellis/scripts/task.py remove-subtask <parent> <child>
 python3 ./.trellis/scripts/task.py create-pr [name] [--dry-run]
 ```
 
-> Run `python3 ./.trellis/scripts/task.py --help` to see the authoritative, up-to-date list.
+> 运行 `python3 ./.trellis/scripts/task.py --help` 查看权威的最新命令列表。
 
-**Current-task mechanism**: `task.py create` creates the task directory and (when session identity is available) auto-sets the per-session active-task pointer so the planning breadcrumb fires immediately. `task.py start` writes the same pointer (idempotent if already set) and flips `task.json.status` from `planning` to `in_progress`. State is stored under `.trellis/.runtime/sessions/`. If no context key is available from hook input, `TRELLIS_CONTEXT_ID`, or a platform-native session environment variable, `task.py start` fails with a session identity hint because it cannot persist a session pointer; read-only context may still project one unique developer-owned resumable task. `task.py finish` deletes the current session file (status unchanged). `task.py archive <task>` writes `status=completed`, moves the directory to `archive/`, and deletes any runtime session files that still point at the archived task.
+**当前任务机制（Current-task mechanism）**：`task.py create` 创建任务目录；会话身份可用时，自动设置每会话活动任务指针，让规划面包屑立即生效。`task.py start` 写入同一指针（已设置时保持幂等），并将 `task.json.status` 从 `planning` 切换为 `in_progress`。状态存放在 `.trellis/.runtime/sessions/`。如果 Hook 输入、`TRELLIS_CONTEXT_ID` 或平台原生会话环境变量没有提供上下文键，`task.py start` 会给出会话身份提示，因为它无法持久化会话指针；只读上下文仍可投影唯一的开发者所属可恢复任务。`task.py finish` 删除当前会话文件，状态不变。`task.py archive <task>` 写入 `status=completed`，将目录移动到 `archive/`，并删除仍指向该任务的运行时会话文件。
 
-### Workspace System
+### 工作区系统（Workspace System）
 
-Records every AI session for cross-session tracking under `.trellis/workspace/<developer>/`.
+在 `.trellis/workspace/<developer>/` 下记录每个 AI 会话，用于跨会话跟踪。
 
-- `journal-N.md` — session log. **Max 2000 lines per file**; a new `journal-(N+1).md` is auto-created when exceeded.
-- `index.md` — personal index (total sessions, last active).
+- `journal-N.md`——会话日志。每个文件**最多 2000 行**，超过后自动创建 `journal-(N+1).md`。
+- `index.md`——个人索引（会话总数、最近活动）。
 
 ```bash
 python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash" --summary "Summary"
 ```
 
-### Context Script
+### 上下文脚本（Context Script）
 
 ```bash
 python3 ./.trellis/scripts/get_context.py                            # full session runtime
@@ -163,55 +122,48 @@ python3 ./.trellis/scripts/get_context.py --mode phase --step <X.Y>  # detailed
 ---
 
 <!--
-  WORKFLOW-STATE BREADCRUMB CONTRACT (read this before editing the tag blocks below)
-
-  The [workflow-state:STATUS] blocks embedded in the ## Phase Index section
-  below are the SINGLE source of truth for the per-turn `<workflow-state>`
-  breadcrumb that every supported AI platform's UserPromptSubmit hook
-  reads. inject-workflow-state.py (Python platforms) and
-  inject-workflow-state.js (OpenCode plugin) only parse them — there is no
-  fallback dict baked into the scripts after v0.5.0-rc.0.
-
-  STATUS charset: [A-Za-z0-9_-]+. When the hook can't find a tag, it
-  degrades to a generic "Refer to workflow.md for current step." line —
-  intentionally visible so users notice and fix a broken workflow.md.
-
-  INVARIANT (test/regression.test.ts):
-    Every workflow-walkthrough step marked `[required · once]` must have a
-    matching enforcement line in its phase's [workflow-state:*] block. The
-    breadcrumb is the only per-turn channel; if a mandatory step isn't
-    mentioned there, the AI silently skips it (Phase 1 planning gate
-    skip and Phase 3.4 commit skip both manifested via this gap).
-
-  TAG ↔ PHASE scoping:
-    [workflow-state:no_task]      → no active task; before Phase 1
-    [workflow-state:unbound_task] → one developer-owned task exists without a session pointer
-    [workflow-state:unbound_ambiguous] → multiple developer-owned tasks exist without a session pointer
-    [workflow-state:unbound_ambiguous-inline] → Codex inline variant of unbound_ambiguous
-    [workflow-state:task_error]   → active task record is unreadable; repair it before continuing
-    [workflow-state:planning]     → all of Phase 1 (status='planning')
-    [workflow-state:planning-inline] → Codex inline variant of Phase 1
-    [workflow-state:in_progress]  → Phase 2 + Phase 3.2-3.4
-                                    (status stays 'in_progress' from
-                                    task.py start until task.py archive)
-    [workflow-state:in_progress-inline] → Codex inline variant of Phase 2/3
-    [workflow-state:completed]    → currently DEAD: cmd_archive flips
-                                    status and moves the dir in the same
-                                    call, so the resolver loses the
-                                    pointer (block kept for a future
-                                    explicit in_progress→completed
-                                    transition)
-
-  Editing checklist:
-    - When you change a [workflow-state:STATUS] block, also check the
-      matching phase's `[required · once]` walkthrough steps for sync
-    - Run `trellis update` after editing to push the new bodies to
-      downstream user projects (block-level managed replacement)
-    - Full runtime contract:
+  工作流状态面包屑合同（WORKFLOW-STATE BREADCRUMB CONTRACT；编辑以下标记块前阅读）
+
+  下方 ## Phase Index 区域中的 [workflow-state:STATUS] 块是每个支持平台的
+  UserPromptSubmit Hook 读取的每轮 <workflow-state> 面包屑唯一事实来源。
+  inject-workflow-state.py（Python 平台）和 inject-workflow-state.js（OpenCode 插件）
+  只解析这些块；v0.5.0-rc.0 之后，脚本中不再内置回退字典。
+
+  STATUS 字符集为 [A-Za-z0-9_-]+。Hook 找不到标签时，会降级为通用的
+  "Refer to workflow.md for current step."，让用户能发现并修复损坏的 workflow.md。
+
+  不变量（test/regression.test.ts）：
+    每个标记为 `[required · once]` 的工作流步骤，都必须在所属阶段的
+    [workflow-state:*] 块中有对应的约束行。面包屑是每轮唯一的提示通道；
+    如果没有提到必需步骤，AI 会静默跳过它（阶段一规划门禁和阶段 3.4 提交门禁
+    都曾因这一缺口被跳过）。
+
+  标签与阶段范围：
+    [workflow-state:no_task]      → 无活动任务；阶段一之前
+    [workflow-state:unbound_task] → 开发者有一个任务，但没有会话指针
+    [workflow-state:unbound_ambiguous] → 开发者有多个任务，但没有会话指针
+    [workflow-state:unbound_ambiguous-inline] → unbound_ambiguous 的 Codex inline 版本
+    [workflow-state:task_error]   → 活动任务记录不可读；继续前先修复
+    [workflow-state:planning]     → 整个阶段一（status='planning'）
+    [workflow-state:planning-inline] → 阶段一的 Codex inline 版本
+    [workflow-state:in_progress]  → 阶段二与阶段 3.2–3.4
+                                    （从 task.py start 到 task.py archive，
+                                    status 保持 'in_progress'）
+    [workflow-state:in_progress-inline] → 阶段二/三的 Codex inline 版本
+    [workflow-state:completed]    → 当前不可达：cmd_archive 在同一次调用中
+                                    修改状态并移动目录，解析器因此失去指针。
+                                    保留此块以支持未来显式的
+                                    in_progress→completed 转换。
+
+  编辑清单：
+    - 修改 [workflow-state:STATUS] 块时，同时检查对应阶段的 `[required · once]`
+      工作流步骤是否同步
+    - 编辑后运行 `trellis update`，通过按块管理的替换将新正文推送到下游项目
+    - 完整运行时合同：
       .trellis/spec/cli/backend/workflow-state-contract.md
 -->
 
-## Phase Index
+## 阶段索引（Phase Index）
 
 ```
 Phase 1: Plan    → classify, then create planning artifacts for work that needs a task
@@ -219,197 +171,191 @@ Phase 2: Execute → implement only after task status is in_progress
 Phase 3: Finish  → verify, update spec, commit, and wrap up
 ```
 
-### Request Triage
+### 请求分流（Request Triage）
 
-- Direct small work: for a clearly bounded, single-surface operation with an immediate verification path, proceed without creating a Trellis task. Apply normal safety rules. If discovery expands the scope or reveals a design, ownership, release, or durable-record need, stop and create a task before continuing.
-- Complex task: ask whether you may create a Trellis task and enter planning. If the user says no, do not do broad inline implementation; explain, clarify scope, or suggest a smaller split.
-- User approval to create a task is not approval to start implementation. Planning still happens first.
+- 直接小任务：对于边界清晰、只涉及一个表面且可以立即验证的操作，可以不创建 Trellis 任务直接进行，但仍遵守通常安全规则。如果探索扩大了范围，或发现需要设计、owner、发布或持久记录，先停止并创建任务。
+- 复杂任务：询问是否可以创建 Trellis 任务并进入规划。如果用户拒绝，不进行大范围内联实施；解释、澄清范围或建议拆分为更小的任务。
+- 用户批准创建任务不等于批准开始实施，仍须先完成规划。
 
-### Analysis-only tasks
+### analysis-only 任务
 
-An analysis-only task is eligible when `task.json.meta.delivery_mode = "analysis_only"` exactly and its `prd.md` names the evidence deliverable plus a no-change boundary for product source, runtime configuration, deployment, credentials, and external systems. Complexity, cross-owner scope, multiple evidence units, recommendations, or unresolved product choices do not make it ineligible. The user's research request authorizes the requested main-session evidence work.
+当 `task.json.meta.delivery_mode = "analysis_only"` 且 `prd.md` 明确证据交付物以及产品源码、运行时配置、部署、凭据和外部系统均不变的边界时，analysis-only 任务符合条件。复杂度、跨 owner 范围、多个证据单元、建议或未解决的产品选择都不会使它失去资格。用户的研究请求授权主会话完成所请求的证据工作。
 
-Keep the task in `planning`: write and verify its research, audit, or design evidence, commit task artifacts, and archive directly. Do not run `task.py start`, configure implementation context, require a Planning Seal, or wait for a second implementation approval. If independent subnode evidence is requested, freeze the dispatch plan in the task and obtain explicit approval before any spawn/send; that approval authorizes only the listed evidence dispatch. If the evidence recommends a protected-target change, record the recommendation and create a separate change-bearing task before doing it.
+让任务保持 `planning`：写入并验证研究、审查或设计证据，提交任务资产后直接归档。不要运行 `task.py start`，不要配置实施上下文，不要求 Planning Seal，也不等待第二次实施批准。如果需要独立子节点证据，在任务中冻结派发方案，并在任何 spawn/send 前取得明确批准；该批准只授权清单中的证据派发。如果证据建议修改受保护目标，记录建议并另建 change-bearing 任务，之后才能实施。
 
-### Planning Artifacts
+### 规划资产（Planning Artifacts）
 
-- `prd.md` — requirements, constraints, and acceptance criteria. Do not put technical design or execution checklists here.
-- `design.md` — technical design for complex tasks: boundaries, contracts, data flow, tradeoffs, compatibility, rollout / rollback shape.
-- `implement.md` — execution plan for complex tasks: ordered checklist, validation commands, review gates, and rollback points.
-- `implement.jsonl` / `check.jsonl` — spec and research manifests for sub-agent context. They do not replace `implement.md`.
-- Lightweight tasks may be PRD-only. Complex tasks must have `prd.md`, `design.md`, and `implement.md` before `task.py start`.
+- `prd.md`——需求、约束和验收标准。不要在其中放技术设计或执行清单。
+- `design.md`——复杂任务的技术设计：边界、合同、数据流、取舍、兼容性和发布/回滚形态。
+- `implement.md`——复杂任务的执行计划：有序清单、验证命令、审查门禁和回滚点。
+- `implement.jsonl` / `check.jsonl`——子代理上下文使用的 spec 与研究清单，不替代 `implement.md`。
+- 轻量任务可以只有 PRD。复杂任务在 `task.py start` 前必须有 `prd.md`、`design.md` 和 `implement.md`。
 
-For read-heavy research, audit, review, or investigation, split work that cannot persist one useful conclusion in the current bounded session into evidence units. Each unit records one question or scope, minimal evidence, destination, stop condition, conclusion or blocker, unknowns, and recovery point before the next unit begins. Size for one normal context window, without an exact token or time promise; routine navigation needs no record.
+对于阅读量较大的研究、审查或调查，将无法在当前有界会话中持久化一个有用结论的工作拆成证据单元。每个单元在开始下一个单元前记录一个问题或范围、最小证据、落点、停止条件、结论或阻塞、未知项和恢复点。按一个普通上下文窗口控制规模，不承诺精确 token 或时间；例行导航无需记录。
 
-### Parent / Child Task Trees
+### 父子任务树（Parent / Child Task Trees）
 
-Use a parent task when one user request contains several independently verifiable deliverables. The parent task owns the source requirement set, the task map, cross-child acceptance criteria, and final integration review; it normally should not be the implementation target unless it also has direct work.
+当一个用户请求包含多个可独立验证的交付物时使用父任务。父任务负责源需求集合、任务图、跨子任务验收标准和最终集成审查；除非父任务本身也有直接工作，否则通常不作为实施目标。
 
-Use child tasks for deliverables that can be planned, implemented, checked, and archived independently. Parent/child structure is not a dependency system: if one child must wait for another, write that ordering in the child `prd.md` / `implement.md` and keep each child's acceptance criteria testable.
+对可以独立规划、实施、检查和归档的交付物使用子任务。父子结构不是依赖系统：如果一个子任务必须等待另一个子任务，在该子任务的 `prd.md` / `implement.md` 中写明顺序，并保持每个子任务的验收标准可测试。
 
-Create new children with `task.py create "<title>" --slug <name> --parent <parent-dir>`. Link existing tasks with `task.py add-subtask <parent> <child>`, and unlink mistakes with `task.py remove-subtask <parent> <child>`.
+使用 `task.py create "<title>" --slug <name> --parent <parent-dir>` 创建新子任务。使用 `task.py add-subtask <parent> <child>` 关联已有任务，使用 `task.py remove-subtask <parent> <child>` 解除错误关联。
 
-<!-- Per-turn breadcrumb: shown when there is no active task (before Phase 1) -->
+<!-- 每轮面包屑：无活动任务时显示（阶段一之前）。 -->
 
 [workflow-state:no_task]
-No active task. First classify the current turn. Direct small work with a clear single owner and immediate verification may proceed without a Trellis task under normal safety rules.
-If scope expands or requires design, ownership, release, credentials, or a durable record, create a Trellis task before continuing.
-Complex task: ask the user if you can create a Trellis task and enter the planning phase. If the user says no, explain, clarify scope, or suggest a smaller split.
+没有活动任务。先分类当前轮次。owner 清晰、可以立即验证的直接小任务，可以在通常安全规则下不创建 Trellis 任务直接进行。
+如果范围扩大，或需要设计、owner、发布、凭据或持久记录，继续前先创建 Trellis 任务。
+复杂任务：询问用户是否可以创建 Trellis 任务并进入规划。如果用户拒绝，解释、澄清范围或建议拆分为更小任务。
 [/workflow-state:no_task]
 
-<!-- Per-turn breadcrumb: shown when one resumable task exists without a direct session binding. -->
+<!-- 每轮面包屑：存在一个可恢复任务且无直接会话绑定时显示。 -->
 
 [workflow-state:unbound_task]
-An existing developer-owned task has no direct session binding. Inspect native `task.py current --json`: a non-null `session_source` means direct identity is already available; an unbound source still means no task binding. Select the existing task from the user's explicit intent; do not guess or create a duplicate. Resume its planning/status gates first. Run native `task.py start <task>` only when its activation contract permits it, after the Planning Seal and implementation authorization for a planning change-bearing task. An eligible `analysis_only` task stays in planning without start. If identity is absent, report that separately; never invent an identity or edit runtime pointers.
+已有一个由开发者拥有的任务，但没有直接会话绑定。检查原生 `task.py current --json`：非空 `session_source` 表示直接身份已可用；未绑定来源仍表示没有任务绑定。根据用户明确意图选择已有任务，不要猜测或创建重复任务。先恢复其规划/状态门禁。只有激活合同允许时，才在 Planning Seal 和 change-bearing 任务实施授权之后运行原生 `task.py start <task>`。符合条件的 `analysis_only` 任务保持 planning，不运行 start。缺少身份时单独报告；绝不虚构身份或编辑运行时指针。
 [/workflow-state:unbound_task]
 
-<!-- Per-turn breadcrumb shown when multiple resumable tasks exist without a direct session binding. -->
+<!-- 每轮面包屑：存在多个可恢复任务且无直接会话绑定时显示。 -->
 
 [workflow-state:unbound_ambiguous]
-Multiple developer-owned tasks have no direct session binding. Inspect native `task.py current --json`: a non-null `session_source` means direct identity is already available; an unbound source still means no task binding. Select the existing task from the user's explicit intent; do not guess or create a duplicate. Resume its planning/status gates first. Run native `task.py start <task>` only when its activation contract permits it, after the Planning Seal and implementation authorization for a planning change-bearing task. An eligible `analysis_only` task stays in planning without start. If identity is absent, report that separately; never invent an identity or edit runtime pointers.
+多个由开发者拥有的任务没有直接会话绑定。检查原生 `task.py current --json`：非空 `session_source` 表示直接身份已可用；未绑定来源仍表示没有任务绑定。根据用户明确意图选择已有任务，不要猜测或创建重复任务。先恢复其规划/状态门禁。只有激活合同允许时，才在 Planning Seal 和 change-bearing 任务实施授权之后运行原生 `task.py start <task>`。符合条件的 `analysis_only` 任务保持 planning，不运行 start。缺少身份时单独报告；绝不虚构身份或编辑运行时指针。
 [/workflow-state:unbound_ambiguous]
 
 [workflow-state:unbound_ambiguous-inline]
-Multiple developer-owned tasks have no direct session binding. Inspect native `task.py current --json`: a non-null `session_source` means direct identity is already available; an unbound source still means no task binding. Select the existing task from the user's explicit intent; do not guess or create a duplicate. Resume its planning/status gates first. Run native `task.py start <task>` only when its activation contract permits it, after the Planning Seal and implementation authorization for a planning change-bearing task. An eligible `analysis_only` task stays in planning without start. If identity is absent, report that separately; never invent an identity or edit runtime pointers.
+多个由开发者拥有的任务没有直接会话绑定。检查原生 `task.py current --json`：非空 `session_source` 表示直接身份已可用；未绑定来源仍表示没有任务绑定。根据用户明确意图选择已有任务，不要猜测或创建重复任务。先恢复其规划/状态门禁。只有激活合同允许时，才在 Planning Seal 和 change-bearing 任务实施授权之后运行原生 `task.py start <task>`。符合条件的 `analysis_only` 任务保持 planning，不运行 start。缺少身份时单独报告；绝不虚构身份或编辑运行时指针。
 [/workflow-state:unbound_ambiguous-inline]
 
-<!-- Per-turn breadcrumb: shown when the active task record cannot be read. -->
+<!-- 每轮面包屑：活动任务记录不可读时显示。 -->
 
 [workflow-state:task_error]
-The active task record could not be read. Do not create or activate another task.
-Inspect the task directory named above and repair its task.json. It must be a valid JSON object with a non-empty status.
-Preserve existing task fields and artifacts. If the correct status cannot be determined safely, ask the user before reconstructing the record.
+无法读取活动任务记录。不要创建或激活其他任务。
+检查上方命名的任务目录并修复其 task.json。它必须是有效 JSON 对象，且 status 非空。
+保留现有任务字段和资产。如果无法安全确定正确状态，在重建记录前询问用户。
 [/workflow-state:task_error]
 
-### Phase 1: Plan
-- 1.0 Create task `[required · once]` (only after task-creation consent)
-- 1.1 Requirement exploration `[required · repeatable]` (`prd.md`; complex tasks also need `design.md` + `implement.md`)
-- 1.2 Research `[optional · repeatable]`
-- 1.3 Configure context `[required · once]` — Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Grok, Kimi Code (sub-agent-dispatch platforms only; inline and eligible analysis-only tasks skip)
-- 1.4 Activate task `[required · once]` (change-bearing tasks only: review gate, then `task.py start`; status → in_progress)
-- 1.5 Completion criteria
+### 阶段一：规划（Phase 1: Plan）
+- 1.0 创建任务 `[required · once]`（仅在获得创建任务同意后）
+- 1.1 需求探索 `[required · repeatable]`（`prd.md`；复杂任务还需要 `design.md` + `implement.md`）
+- 1.2 研究 `[optional · repeatable]`
+- 1.3 配置上下文 `[required · once]`——Claude Code、Cursor、OpenCode、Codex、Kiro、Gemini、Qoder、CodeBuddy、Copilot、Droid、Pi、Oh My Pi、ZCode、Snow、Reasonix、Grok、Kimi Code（仅派发子代理的平台；inline 和符合条件的 analysis-only 任务跳过）
+- 1.4 激活任务 `[required · once]`（仅 change-bearing 任务：审查门禁后运行 `task.py start`；状态 → in_progress）
+- 1.5 完成标准
 
-<!-- Per-turn breadcrumb: shown throughout Phase 1 (status='planning') -->
+<!-- 每轮面包屑：整个阶段一显示（status='planning'）。 -->
 
 [workflow-state:planning]
-Load `trellis-brainstorm`; stay in planning.
-If `task.json.meta.delivery_mode = "analysis_only"` exactly, complete bounded evidence work regardless of complexity or cross-owner scope; the PRD names the evidence deliverable and protected-target no-change boundary. Do not run a Planning Seal or wait for implementation approval. A protected-target recommendation requires a separate change-bearing task.
-For `analysis_only`, complete the bounded evidence work regardless of complexity or cross-owner scope; its PRD names the evidence deliverable and protected-target no-change boundary. Do not run a Planning Seal or wait for implementation approval. For change-bearing work, lightweight tasks may use `prd.md`; complex tasks need `design.md` and `implement.md` plus the Planning Seal before implementation review. Research recommendations and open product choices may be recorded without sealing them as implementation decisions. Persist answers needed to define the requested work and continue the same planning loop.
-Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position.
-Sub-agent mode: curate `implement.jsonl` and `check.jsonl` as spec/research manifests before start.
-Planned/change-bearing start requires native plan seal and matching later approval of this task's current material revision. Selecting context does not approve it.
+加载 `trellis-brainstorm`；保持 planning。
+如果 `task.json.meta.delivery_mode = "analysis_only"`，无论复杂度或跨 owner 范围如何，都完成有界证据工作；PRD 必须写明证据交付物和受保护目标不变边界。不要运行 Planning Seal 或等待实施批准。涉及受保护目标的建议必须另建 change-bearing 任务。
+对于 `analysis_only`，无论复杂度或跨 owner 范围如何，都完成有界证据工作；PRD 必须写明证据交付物和受保护目标不变边界。不要运行 Planning Seal 或等待实施批准。对于 change-bearing 工作，轻量任务可以使用 `prd.md`；复杂任务在实施审查前需要 `design.md`、`implement.md` 和 Planning Seal。研究建议和开放的产品选择可以记录，但不要将其封口为实施决策。持久化定义请求所需的答复，并继续同一规划循环。
+多交付物范围：考虑父任务和可独立验证的子任务；依赖必须写入子任务资产，不能从树结构位置推断。
+子代理模式：在 start 前维护 `implement.jsonl` 和 `check.jsonl` 作为 spec/研究清单。
+planned/change-bearing start 需要原生 plan seal，以及对当前任务当前实质版本的匹配批准。选择上下文不构成批准。
 [/workflow-state:planning]
 
-<!-- Per-turn breadcrumb: shown throughout Phase 1 when Codex uses its default
-     codex.dispatch_mode=inline. Codex-only alternate to [workflow-state:planning]. The main agent
-     edits code directly in Phase 2, so jsonl curation is skipped —
-     the inline workflow loads `trellis-before-dev` instead of injecting JSONL
-     into a sub-agent. -->
+<!-- Codex 使用默认 codex.dispatch_mode=inline 时，阶段一持续显示的每轮面包屑。
+     这是 [workflow-state:planning] 的 Codex 专用替代块。主 Agent 在阶段二直接编辑代码，
+     因此跳过 JSONL 整理；inline 工作流加载 `trellis-before-dev`，而不是向子代理注入 JSONL。 -->
 
 [workflow-state:planning-inline]
-Load `trellis-brainstorm`; stay in planning.
-If `task.json.meta.delivery_mode = "analysis_only"` exactly, complete bounded evidence work regardless of complexity or cross-owner scope; the PRD names the evidence deliverable and protected-target no-change boundary. Do not run a Planning Seal or wait for implementation approval. A protected-target recommendation requires a separate change-bearing task.
-For `analysis_only`, complete the bounded evidence work regardless of complexity or cross-owner scope; its PRD names the evidence deliverable and protected-target no-change boundary. Do not run a Planning Seal or wait for implementation approval. For change-bearing work, lightweight tasks may use `prd.md`; complex tasks need `design.md` and `implement.md` plus the Planning Seal before implementation review. Research recommendations and open product choices may be recorded without sealing them as implementation decisions. Persist answers needed to define the requested work and continue the same planning loop.
-Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position.
-Inline mode: skip jsonl curation; Phase 2 reads artifacts/specs via `trellis-before-dev`.
-Planned/change-bearing start requires native plan seal and matching later approval of this task's current material revision. Selecting context does not approve it.
+加载 `trellis-brainstorm`；保持 planning。
+如果 `task.json.meta.delivery_mode = "analysis_only"`，无论复杂度或跨 owner 范围如何，都完成有界证据工作；PRD 必须写明证据交付物和受保护目标不变边界。不要运行 Planning Seal 或等待实施批准。涉及受保护目标的建议必须另建 change-bearing 任务。
+对于 `analysis_only`，无论复杂度或跨 owner 范围如何，都完成有界证据工作；PRD 必须写明证据交付物和受保护目标不变边界。不要运行 Planning Seal 或等待实施批准。对于 change-bearing 工作，轻量任务可以使用 `prd.md`；复杂任务在实施审查前需要 `design.md`、`implement.md` 和 Planning Seal。研究建议和开放的产品选择可以记录，但不要将其封口为实施决策。持久化定义请求所需的答复，并继续同一规划循环。
+多交付物范围：考虑父任务和可独立验证的子任务；依赖必须写入子任务资产，不能从树结构位置推断。
+Inline 模式跳过 JSONL 整理；阶段二通过 `trellis-before-dev` 读取任务资产和 spec。
+planned/change-bearing 任务开始前需要原生 plan seal，以及对当前任务当前实质版本的匹配批准。选择上下文不构成批准。
 [/workflow-state:planning-inline]
 
-### Phase 2: Execute
-- 2.1 Implement `[required · repeatable]`
-- 2.2 Quality check `[required · repeatable]`
-- 2.3 Rollback `[on demand]`
+### 阶段二：执行（Phase 2: Execute）
+- 2.1 实施 `[required · repeatable]`
+- 2.2 质量检查 `[required · repeatable]`
+- 2.3 回滚 `[on demand]`
 
-<!-- Per-turn breadcrumb: shown while status='in_progress'.
-     Scope: all of Phase 2 + Phase 3.2-3.4 (status stays 'in_progress' from
-     task.py start until task.py archive; only archive flips it). The body
-     therefore must cover every required step from implementation through
-     commit, including Phase 3.3 spec update and Phase 3.4 commit. -->
+<!-- status='in_progress' 时显示的每轮面包屑。
+     范围覆盖阶段二和阶段 3.2-3.4（从 task.py start 到 task.py archive 期间状态保持
+     'in_progress'，只有 archive 会翻转状态）。因此正文必须覆盖从实施到提交的每个必需步骤，
+     包括阶段 3.3 spec 更新和阶段 3.4 提交。 -->
 
-Sub-agent dispatch protocol applies to all platforms and all sub-agents, including native Codex `SubagentStart` context injection with child-side pull fallback, class-2 Gemini/Qoder/Copilot/Reasonix/Trae/Grok/Kimi Code/DeepSeek Harness, hook-backed ZCode/Snow, and `trellis-research`: every dispatch prompt starts with `Active task: <task path from task.py current>` before role-specific instructions. On Grok Build, use `spawn_subagent` with `subagent_type` set to the Trellis agent name (e.g. `trellis-implement`). On Kimi Code, dispatch the built-in `coder` / `explore` sub-agent with the matching `.kimi-code/skills/trellis-<role>/SKILL.md` instructions. On DeepSeek Harness, tell the child to load the matching `.dsh/skills/trellis-agent-<role>/SKILL.md` exactly once, then choose the synchronization path by capability. If the optional companion plugin exposes `trellis_wait`, dispatch `subagent` in its default continuable background mode, continue independent work, and call `trellis_wait` once per dependent child id when a dependent gate is next; each call returns only after DSH has queued that child's native settlement notice. Without `trellis_wait`, dispatch each child with `run_in_background: false` from the outset so no dependent gate can overtake it. Never simulate waiting with shell sleep, polling loops, `job_output`, repeated `list_agents`, or another long-running command, and never leave a background child without an event-driven wait path.
+子代理派发协议适用于所有平台和所有子代理，包括使用原生 Codex `SubagentStart` 注入上下文并以子代理侧读取为后备的模式、Gemini/Qoder/Copilot/Reasonix/Trae/Grok/Kimi Code/DeepSeek Harness、由 Hook 支持的 ZCode/Snow 以及 `trellis-research`：每个派发提示都必须先写 `Active task: <task path from task.py current>`，再写角色指令。Grok Build 使用 `spawn_subagent`，并将 `subagent_type` 设为 Trellis Agent 名称（例如 `trellis-implement`）。Kimi Code 派发内置 `coder` / `explore` 子代理，并提供对应的 `.kimi-code/skills/trellis-<role>/SKILL.md` 指令。DeepSeek Harness 要求子代理恰好加载一次对应的 `.dsh/skills/trellis-agent-<role>/SKILL.md`，再按能力选择同步路径。如果可选伴随插件提供 `trellis_wait`，使用默认可继续的后台模式派发 `subagent`，继续独立工作；依赖门即将满足时，对每个依赖子代理 ID 调用一次 `trellis_wait`，每次调用都要等到 DSH 排入该子代理的原生结算通知后才返回。没有 `trellis_wait` 时，从一开始就为每个子代理设置 `run_in_background: false`，避免依赖门越过它。不得用 shell sleep、轮询循环、`job_output`、重复 `list_agents` 或其他长命令模拟等待，也不得让后台子代理脱离事件驱动的等待路径。
 
 [workflow-state:in_progress]
-An explicitly user-requested bounded amendment that satisfies the in-progress conditions above stays in the current phase and is recorded in the unsealed execution record. If a material unresolved decision appears, immediately explain its impact and recommendation, stop dependent actions and record `decision-needed`. Run native `task.py replan <task> "<reason>"` to planning, then use the blocking question tool and re-seal/approve the new material revision. Do not defer the decision or change task state by hand.
-Tools: `trellis-implement` / `trellis-research` name sub-agent roles dispatched through your platform's sub-agent mechanism, not skills the main session loads itself (on Claude Code: use the Task/Agent tool, never the Skill tool). `trellis-update-spec` is a skill. `trellis-check` exists as both; prefer the Agent/role form when verifying after code changes.
-On DeepSeek Harness, role instructions ship as collision-free `trellis-agent-implement` / `trellis-agent-check` / `trellis-agent-research` skills under `.dsh/skills/`. The main session must not load them itself: tell the child to load the matching role skill exactly once. If `trellis_wait` is available, use the default background mode, do independent work, then call `trellis_wait` once per dependent child id and consume each native settlement notice before entering the dependent gate. If it is unavailable, dispatch every child with `run_in_background: false` from the outset. Do not poll, sleep, or start a background child without an event-driven wait path.
-Flow: `trellis-implement` -> `trellis-check` -> `trellis-update-spec` -> commit (Phase 3.4) -> `/trellis:finish-work`.
-Use this block only when `codex.dispatch_mode: auto` is explicitly selected. Sub-agent self-exemption: if already running as `trellis-implement`, do NOT spawn another `trellis-implement` or `trellis-check`; if already running as `trellis-check`, do NOT spawn another `trellis-check` or `trellis-implement`. Dispatch is main session only.
-Dispatch prompt starts with `Active task: <task path from task.py current>`. Read context: jsonl entries -> `prd.md` -> `design.md if present` -> `implement.md if present`.
+满足上述 in_progress 条件、且由用户明确要求的有界增补，留在当前阶段，并记录到未封口执行记录。出现实质未决选择时，立即解释影响和建议，停止依赖该选择的动作并记录 `decision-needed`。运行原生 `task.py replan <task> "<reason>"` 回到规划，再使用阻塞式提问工具并重新封口/批准新的实质版本。不要延后该选择，也不要手动修改任务状态。
+`trellis-implement` / `trellis-research` 表示通过平台子代理机制派发的角色，不是主会话自行加载的 Skill（Claude Code 使用 Task/Agent 工具，不使用 Skill 工具）。`trellis-update-spec` 是 Skill。`trellis-check` 同时存在于两种入口；代码变更后验证时优先使用 Agent/角色入口。
+DeepSeek Harness 的角色指令以互不冲突的 `trellis-agent-implement` / `trellis-agent-check` / `trellis-agent-research` Skill 分发到 `.dsh/skills/`。主会话不得自行加载；要求子代理恰好加载一次对应角色 Skill。提供 `trellis_wait` 时，使用默认后台模式，继续独立工作，然后对每个依赖子代理 ID 调用一次 `trellis_wait`，消费原生结算通知后才进入依赖门。未提供时，从一开始就为每个子代理设置 `run_in_background: false`。不得轮询、sleep 或启动没有事件驱动等待路径的后台子代理。
+流程：`trellis-implement` → `trellis-check` → `trellis-update-spec` → 提交（阶段 3.4）→ `/trellis:finish-work`。
+仅在明确选择 `codex.dispatch_mode: auto` 时使用此块。子代理自豁免：如果当前已经是 `trellis-implement`，不得再派发 `trellis-implement` 或 `trellis-check`；如果当前已经是 `trellis-check`，不得再派发 `trellis-check` 或 `trellis-implement`。只有主会话负责派发。
+派发提示必须以 `Active task: <task path from task.py current>` 开始。读取上下文的顺序为：JSONL 条目 → `prd.md` → 存在时的 `design.md` → 存在时的 `implement.md`。
 [/workflow-state:in_progress]
 
-<!-- Per-turn breadcrumb: shown while status='in_progress' when Codex uses its
-     default codex.dispatch_mode=inline. Codex-only alternate to
-     [workflow-state:in_progress]. The main session edits code directly
-     instead of dispatching sub-agents. -->
+<!-- 每轮面包屑：status='in_progress' 且 Codex 使用默认
+     codex.dispatch_mode=inline 时显示。仅供 Codex 替代
+     [workflow-state:in_progress]；主会话直接编辑代码，不派发子代理。 -->
 
 [workflow-state:in_progress-inline]
-Flow: `trellis-before-dev` -> edit -> `trellis-check` -> validation -> `trellis-update-spec` -> commit (Phase 3.4) -> `/trellis:finish-work`.
-An explicitly user-requested bounded amendment that satisfies the in-progress conditions above stays in the current phase and is recorded in the unsealed execution record. If a material unresolved decision appears, immediately explain its impact and recommendation, stop dependent actions and record `decision-needed`. Run native `task.py replan <task> "<reason>"` to planning, then use the blocking question tool and re-seal/approve the new material revision. Do not defer the decision or change task state by hand.
-Do not dispatch implement/check sub-agents in inline mode.
-Explicit Channel independent-evidence subnodes remain available under the selected workflow; required independent evidence cannot be replaced by main-session pass claims.
-Read context: `prd.md` -> `design.md if present` -> `implement.md if present`, plus relevant spec/research loaded by skills.
+流程：`trellis-before-dev` → 编辑 → `trellis-check` → 验证 → `trellis-update-spec` → 提交（阶段 3.4）→ `/trellis:finish-work`。
+满足上述 in_progress 条件、且由用户明确要求的有界增补，留在当前阶段，并记录到未封口执行记录。出现实质未决选择时，立即解释影响和建议，停止依赖该选择的动作并记录 `decision-needed`。运行原生 `task.py replan <task> "<reason>"` 回到规划，再使用阻塞式提问工具并重新封口/批准新的实质版本。不要延后该选择，也不要手动修改任务状态。
+Inline 模式不派发 implement/check 子代理。
+已选工作流仍可使用明确的 Channel 独立证据子节点；不得用主会话自称通过替代必需的独立证据。
+读取上下文的顺序为：`prd.md` → 存在时的 `design.md` → 存在时的 `implement.md`，再读取 Skill 加载的相关 spec/研究。
 [/workflow-state:in_progress-inline]
 
-### Phase 3: Finish
-- 3.2 Debug retrospective `[on demand]`
-- 3.3 Spec update `[required · once]`
-- 3.4 Commit changes `[required · once]`
-- 3.5 Wrap-up reminder
+### 阶段三：完成（Phase 3: Finish）
+- 3.2 调试复盘 `[on demand]`
+- 3.3 更新 Spec `[required · once]`
+- 3.4 提交变更 `[required · once]`
+- 3.5 收尾提醒
 
-> Note: step 3.1 was folded into 2.2 (last-iteration full-scope check) and 3.4 (commit preamble). Numbering kept stable to avoid breaking external references.
+> 注意：步骤 3.1 已并入 2.2（最后一次迭代的全范围检查）和 3.4（提交前置检查）。保留原有编号，避免破坏外部引用。
 
-<!-- Per-turn breadcrumb: shown while status='completed'.
-     Currently DEAD in normal flow: cmd_archive writes status='completed' in
-     the same call that moves the task dir to archive/, so the active-task
-     resolver loses the pointer and the hook never fires on archived tasks.
-     Block preserved for a future status-transition redesign (e.g. an
-     explicit in_progress→completed command). Edit through the same spec
-     channel as the live blocks. -->
+<!-- 每轮面包屑：status='completed' 时显示。
+     当前正常流程不可达：cmd_archive 在同次调用写入 status='completed'
+     并将目录移至 archive/，活动任务解析器失去指针，Hook 不会作用于归档任务。
+     保留此块供未来状态转换重设计使用（如显式 in_progress→completed 命令）。
+     修改时遵循与活动块相同的 spec 入口。 -->
 
 [workflow-state:completed]
-Code committed. Run `/trellis:finish-work`; if dirty, return to Phase 3.4 first.
+代码已提交。运行 `/trellis:finish-work`；如果工作树仍脏，先回到阶段 3.4。
 [/workflow-state:completed]
 
-### Rules
+### 规则（Rules）
 
-1. Identify which Phase you're in, then continue from the next step there
-2. Run steps in order inside each Phase; `[required]` steps can't be skipped
-3. Phases can roll back (e.g., Execute reveals a prd defect → return to Plan to fix, then re-enter Execute)
-4. Steps tagged `[once]` are skipped if the output already exists; don't re-run
-5. Artifact presence informs the next step; missing `design.md` / `implement.md` is valid for lightweight tasks and incomplete planning for complex tasks.
+1. 确认当前阶段，然后从该阶段的下一步继续
+2. 按阶段内顺序执行；不能跳过 `[required]` 步骤
+3. 阶段可以回退（例如执行发现 PRD 缺陷 → 回到规划修复 → 再次进入执行）
+4. 标记为 `[once]` 的步骤已有产物时跳过，不重复运行
+5. 根据资产是否存在判断下一步；轻量任务可以没有 `design.md` / `implement.md`，复杂任务缺少它们则表示规划未完成。
 
-### Active Task Routing
+### 活动任务路由（Active Task Routing）
 
-When a user request matches one of these intents inside an active task, route first, then load the detailed phase step if needed.
+活动任务中的用户请求符合下列意图时，先路由，再按需要加载阶段步骤详情。
 
 [Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
-- Planning or unclear requirements -> `trellis-brainstorm`.
-- Explicit eligible `analysis_only` -> complete evidence in planning, then commit artifacts and archive directly.
-- `in_progress` implementation/check -> dispatch `trellis-implement` / `trellis-check`.
-- Repeated debugging -> `trellis-break-loop`; spec updates -> `trellis-update-spec`.
+- 规划或需求不清 → `trellis-brainstorm`。
+- 明确符合条件的 `analysis_only` → 在规划中完成证据，然后提交资产并直接归档。
+- `in_progress` 实施/检查 → 派发 `trellis-implement` / `trellis-check`。
+- 重复调试 → `trellis-break-loop`；spec 更新 → `trellis-update-spec`。
 
 [/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
 [codex-inline, Kilo, Antigravity, Devin]
 
-- Planning or unclear requirements -> `trellis-brainstorm`.
-- Explicit eligible `analysis_only` -> complete evidence in planning, then commit artifacts and archive directly.
-- Before editing -> `trellis-before-dev`; after editing -> `trellis-check`.
-- Repeated debugging -> `trellis-break-loop`; spec updates -> `trellis-update-spec`.
+- 规划或需求不清 → `trellis-brainstorm`。
+- 明确符合条件的 `analysis_only` → 在规划中完成证据，然后提交资产并直接归档。
+- 编辑前 → `trellis-before-dev`；编辑后 → `trellis-check`。
+- 重复调试 → `trellis-break-loop`；spec 更新 → `trellis-update-spec`。
 
 [/codex-inline, Kilo, Antigravity, Devin]
 
-### Guardrails
+### 防护栏（Guardrails）
 
-- `analysis_only` tasks may complete in `planning` when their PRD names bounded evidence and a protected-target no-change boundary; complexity, cross-owner scope, multiple evidence units, and recommendations do not make them ineligible. Any protected-target change requires a separate change-bearing task.
-- Task creation approval is not implementation approval; change-bearing implementation waits for `task.py start` after artifact review.
-- PRD-only is valid for lightweight tasks; complex tasks need `design.md` + `implement.md`.
-- Planning must be persisted to task artifacts; checks must run before reporting completion.
+- PRD 写明有界证据和受保护目标不变边界时，`analysis_only` 任务可以在 `planning` 中完成；复杂度、跨 owner 范围、多个证据单元和建议都不会使其失去资格。任何受保护目标变更都需要单独的 change-bearing 任务。
+- 创建任务批准不等于实施批准；change-bearing 实施需等待资产审查后的 `task.py start`。
+- 轻量任务可以只有 PRD；复杂任务需要 `design.md` + `implement.md`。
+- 规划必须持久化到任务资产；报告完成前必须运行检查。
 
-### Loading Step Detail
+### 加载步骤详情（Loading Step Detail）
 
-At each step, run this to fetch detailed guidance:
+每一步都可运行以下命令获取详细指引：
 
 ```bash
 python3 ./.trellis/scripts/get_context.py --mode phase --step <step>
@@ -418,333 +364,332 @@ python3 ./.trellis/scripts/get_context.py --mode phase --step <step>
 
 ---
 
-## Phase 1: Plan
+## 阶段一：规划（Phase 1: Plan）
 
-Goal: classify the request, perform only eligible direct small work without a task, and create planning artifacts when a task is needed.
+目标：分类请求；只有符合条件的直接小任务才可不创建任务立即执行；需要任务时创建规划资产。
 
-#### 1.0 Create task `[required · once]`
+#### 1.0 创建任务（Create task）`[required · once]`
 
-Create the task directory only after task-creation consent. The command sets status to `planning`, writes `task.json`, creates a default `prd.md`, and auto-targets the new task when session identity is available:
+只有取得创建任务同意后才创建任务目录。命令会将状态设为 `planning`、写入 `task.json`、创建默认 `prd.md`；会话身份可用时，还会自动将新任务设为当前目标：
 
 ```bash
 python3 ./.trellis/scripts/task.py create "<task title>" --slug <name>
 ```
 
-`--slug` is the human-readable name only. Do **not** include the `MM-DD-` date prefix; `task.py create` adds that prefix automatically.
+`--slug` 仅填写人类可读名称。不要包含 `MM-DD-` 日期前缀；`task.py create` 会自动添加该前缀。
 
-For task trees, create the parent task first and then create each child with `--parent <parent-dir>`. Do not start the parent just because children exist; start the child that owns the next independently verifiable deliverable.
+对于任务树，先创建父任务，再使用 `--parent <parent-dir>` 创建各子任务。不要因为存在子任务就启动父任务；启动拥有下一个可独立验证交付物的子任务。
 
-After this command succeeds, the per-turn breadcrumb auto-switches to `[workflow-state:planning]`, telling the AI to stay in planning.
+命令成功后，每轮面包屑会自动切换为 `[workflow-state:planning]`，要求 AI 留在规划阶段。
 
-Run only `create` here — do not also run `start`. `start` flips status to `in_progress`, which switches the breadcrumb to the implementation phase before planning artifacts are reviewed. Save `start` for step 1.4.
+这里仅运行 `create`，不要同时运行 `start`。`start` 会将状态切换为 `in_progress`，在规划资产审查前就把面包屑切换到实施阶段。将 `start` 留到步骤 1.4。
 
-For an evidence-only task, set `task.json.meta.delivery_mode = "analysis_only"` at creation or with `task.py set-meta`. Its PRD must name the evidence deliverable and exclude protected-target changes before the task proceeds.
+对于只交付证据的任务，在创建时或使用 `task.py set-meta` 设置 `task.json.meta.delivery_mode = "analysis_only"`。任务继续前，其 PRD 必须写明证据交付物并排除受保护目标变更。
 
-Skip when `python3 ./.trellis/scripts/task.py current --source` already points to a task.
+如果 `python3 ./.trellis/scripts/task.py current --source` 已指向任务，则跳过此步骤。
 
-#### 1.1 Requirement exploration `[required · repeatable]`
+#### 1.1 需求探索（Requirement exploration）`[required · repeatable]`
 
-Load the `trellis-brainstorm` skill and explore requirements interactively with the user per the skill's guidance.
+加载 `trellis-brainstorm` Skill，按照其指引与用户交互探索需求。
 
-For an eligible analysis-only task, converge the PRD boundary, then perform the declared research, audit, or design work in this phase. It does not need a start review or `task.py start`; after acceptance evidence is recorded, continue directly to Phase 3.3.
+对于符合条件的 analysis-only 任务，在本阶段收敛 PRD 边界，然后完成声明的研究、审查或设计工作。不需要 start 审查或运行 `task.py start`；记录验收证据后直接进入阶段 3.3。
 
-The brainstorm skill will guide you to:
-- Batch up to three independent material frontier questions; ask one only when dependency ordering requires it
-- Prefer researching over asking the user
-- Prefer offering options over open-ended questions
-- Update `prd.md` immediately after each user answer
-- Split large scopes into a parent task plus child tasks when the deliverables can be verified independently
-- Keep `prd.md` focused on requirements and acceptance criteria
-- For complex tasks, produce `design.md` and `implement.md` before implementation starts
-- For read-heavy work, split long investigation into evidence units and persist each unit's conclusion or recovery point before continuing
-- Before change-bearing implementation review or `task.py start`, run the Planning Seal closure pass across task artifacts and lock targets, branches, dependencies, release, validation, rollback, dynamic-fact handling, and implementation decisions; `analysis_only` does not use this gate
+brainstorm Skill 会引导你：
+- 将最多三个相互独立的实质前沿问题成组处理；只有依赖顺序要求时才一次询问一个
+- 优先研究，减少直接询问用户
+- 优先提供选项，减少开放式提问
+- 每次用户答复后立即更新 `prd.md`
+- 交付物可独立验证时，将大范围拆成父任务和子任务
+- 让 `prd.md` 专注于需求和验收标准
+- 复杂任务在开始实施前生成 `design.md` 和 `implement.md`
+- 对阅读量大的工作拆成证据单元，并在继续前持久化每个单元的结论或恢复点
+- 在 change-bearing 实施审查或 `task.py start` 前，对任务资产运行 Planning Seal 收口检查，并锁定目标、分支、依赖、发布、验证、回滚、动态事实处理和实施决策；`analysis_only` 不使用此门禁
 
-When considering a parent/child split:
-- Use a parent task when one request contains several independently verifiable deliverables.
-- Parent tasks own source requirements, child-task mapping, cross-child acceptance criteria, and final integration review.
-- Child tasks own actual deliverables that can be planned, implemented, checked, and archived independently.
-- Parent/child structure is not a dependency system. If child B depends on child A, write that ordering in child B's `prd.md` / `implement.md`.
-- Start the child task that owns the next deliverable. Do not start the parent unless the parent itself has direct implementation work.
+考虑拆分父子任务时：
+- 一个请求包含多个可独立验证的交付物时使用父任务。
+- 父任务负责原始需求、子任务映射、跨子任务验收标准和最终集成审查。
+- 子任务负责可以独立规划、实施、检查和归档的实际交付物。
+- 父子结构不是依赖系统。如果子任务 B 依赖子任务 A，将顺序写入子任务 B 的 `prd.md` / `implement.md`。
+- 启动拥有下一个交付物的子任务。除非父任务本身有直接实施工作，否则不要启动父任务。
 
-Return to this step whenever requirements change and revise the relevant artifact.
+需求变化时回到此步骤并修改相关资产。
 
-#### 1.2 Research `[optional · repeatable]`
+#### 1.2 研究（Research）`[optional · repeatable]`
 
-Research can happen at any time during requirement exploration. It isn't limited to local code — you can use any available tool (MCP servers, skills, web search, etc.) to look up external information, including third-party library docs, industry practices, API references, etc.
+需求探索期间可以随时研究。研究不限于本地代码；可以使用可用的 MCP 服务、Skill、网页搜索等工具查询第三方库文档、行业实践、API 参考等外部信息。
 
 [Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
-Spawn the research sub-agent:
+派发研究子代理：
 
-- **Agent type**: `trellis-research`
-- **Task description**: Research <specific question>
-- **Key requirement**: Research output MUST be persisted to `{TASK_DIR}/research/`
-- **DeepSeek Harness**: tell the child to load `trellis-agent-research` exactly once. If `trellis_wait` is available, use the default continuable background mode, dispatch independent questions concurrently when useful, continue unrelated work, then call `trellis_wait` once per child id and consume each settlement notice before advancing. Without `trellis_wait`, dispatch each required child with `run_in_background: false`; do not poll or sleep.
+- **Agent 类型**：`trellis-research`
+- **任务描述**：研究 <具体问题>
+- **关键要求**：研究输出必须持久化到 `{TASK_DIR}/research/`
+- **DeepSeek Harness**：告知子代理恰好加载一次 `trellis-agent-research`。如果提供 `trellis_wait`，使用默认可继续的后台模式；有用时并发派发独立问题，继续不相关工作，然后对每个子代理 ID 调用一次 `trellis_wait` 并消费每个结算通知后再推进。没有 `trellis_wait` 时，每个必需子代理都设置 `run_in_background: false`；不得轮询或 sleep。
 
 [/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
 [codex-inline, Kilo, Antigravity, Devin]
 
-Do the research in the main session directly and write findings into `{TASK_DIR}/research/`. `codex-inline` is the explicit mode that keeps work in the main session.
+直接在主会话中研究，并将发现写入 `{TASK_DIR}/research/`。`codex-inline` 是将工作保留在主会话中的明确模式。
 
 [/codex-inline, Kilo, Antigravity, Devin]
 
-**Research artifact conventions**:
-- One file per research topic (e.g. `research/auth-library-comparison.md`)
-- Record third-party library usage examples, API references, version constraints in files
-- Note relevant spec file paths you discovered for later reference
+**研究资产约定**：
+- 每个研究主题一个文件（例如 `research/auth-library-comparison.md`）
+- 在文件中记录第三方库用法示例、API 参考和版本约束
+- 记录发现的相关 spec 文件路径，供后续引用
 
-Brainstorm and research can interleave freely — pause to research a technical question, then return to talk with the user.
+头脑风暴和研究可以交错进行：遇到技术问题先暂停对话进行研究，再回来继续与用户沟通。
 
-**Key principle**: Research output must be written to files, not left only in the chat. Conversations get compacted; files don't.
+**核心原则**：研究输出必须写入文件，不能只留在对话中。对话会被压缩，文件不会。
 
-#### 1.3 Configure context `[required · once]`
+#### 1.3 配置上下文（Configure context）`[required · once]`
 
-Eligible analysis-only tasks skip this step because they never enter Phase 2 or dispatch implementation/check agents.
+符合条件的 analysis-only 任务不会进入阶段二，也不会派发实施/检查 Agent，因此跳过此步骤。
 
 [Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
-Curate `implement.jsonl` and `check.jsonl` so the Phase 2 sub-agents get the right spec/research context. These files were seeded on `task create` with a single self-describing `_example` line; your job here is to fill in real entries.
+整理 `implement.jsonl` 和 `check.jsonl`，让阶段二子代理获得正确的 spec/研究上下文。这些文件在 `task create` 时以一行自描述的 `_example` 种子创建；此处需要填入真实条目。
 
-**Location**: `{TASK_DIR}/implement.jsonl` and `{TASK_DIR}/check.jsonl` (already exist).
+**位置**：`{TASK_DIR}/implement.jsonl` 和 `{TASK_DIR}/check.jsonl`（已存在）。
 
-**Format**: one JSON object per line — `{"file": "<path>", "reason": "<why>"}`. Paths are repo-root relative.
+**格式**：每行一个 JSON 对象——`{"file": "<path>", "reason": "<why>"}`。路径相对于仓库根目录。
 
-**What to put in**:
-- **Spec files** — `.trellis/spec/<package>/<layer>/index.md` and any specific guideline files (`error-handling.md`, `conventions.md`, etc.) relevant to this task
-- **Research files** — `{TASK_DIR}/research/*.md` that the sub-agent will need to consult
+**写入内容**：
+- **Spec 文件**——`.trellis/spec/<package>/<layer>/index.md` 以及与任务相关的具体指南文件（`error-handling.md`、`conventions.md` 等）
+- **研究文件**——子代理需要查阅的 `{TASK_DIR}/research/*.md`
 
-**What NOT to put in**:
-- Code files (`src/**`, `packages/**/*.ts`, etc.) — those are read by the sub-agent during implementation, not pre-registered here
-- Files you're about to modify — same reason
+**不要写入**：
+- 代码文件（`src/**`、`packages/**/*.ts` 等）；子代理会在实施时读取，不在此处预注册
+- 即将修改的文件；原因相同
 
-**Split between the two files**:
-- `implement.jsonl` → specs + research the implement sub-agent needs to write code correctly
-- `check.jsonl` → specs for the check sub-agent (quality guidelines, check conventions, same research if needed)
+**两个文件的分工**：
+- `implement.jsonl` → 实施子代理正确编写代码所需的 spec 和研究
+- `check.jsonl` → 检查子代理所需的 spec（质量指南、检查约定，以及必要时的相同研究）
 
-These manifests do not replace `implement.md`. `implement.md` is the human-readable execution plan for a complex task; jsonl files only list context files to inject or load.
+这些清单不替代 `implement.md`。`implement.md` 是复杂任务的人类可读执行计划；JSONL 文件只列出要注入或加载的上下文文件。
 
-**How to discover relevant specs**:
+**发现相关 spec**：
 
 ```bash
 python3 ./.trellis/scripts/get_context.py --mode packages
 ```
 
-Lists every package + its spec layers with paths. Pick the entries that match this task's domain.
+该命令列出每个包及其 spec 层和路径。选择与本任务领域匹配的条目。
 
-**How to append entries**:
+**追加条目**：
 
-Either edit the jsonl file directly in your editor, or use:
+可以在编辑器中直接编辑 JSONL 文件，也可以使用：
 
 ```bash
 python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
 python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
 ```
 
-Delete the seed `_example` line once real entries exist (optional — it's skipped automatically by consumers).
+存在真实条目后可以删除 `_example` 种子行（可选；消费者会自动跳过它）。
 
-Ready gate: both `implement.jsonl` and `check.jsonl` must contain at least one real `{"file": "...", "reason": "..."}` entry before `task.py start`. The seed `_example` row alone is not ready.
+就绪门禁：运行 `task.py start` 前，`implement.jsonl` 和 `check.jsonl` 都必须至少包含一个真实的 `{"file": "...", "reason": "..."}` 条目。只有 `_example` 种子行不算就绪。
 
-Skip this step only when both files already have real curated entries.
+只有两个文件都已有整理好的真实条目时才跳过此步骤。
 
 [/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
 [codex-inline, Kilo, Antigravity, Devin]
 
-Skip this step. Context is loaded directly by the `trellis-before-dev` skill in Phase 2.
+跳过此步骤。阶段二由 `trellis-before-dev` Skill 直接加载上下文。
 
 [/codex-inline, Kilo, Antigravity, Devin]
 
-#### 1.4 Activate task `[required · once]`
+#### 1.4 激活任务（Activate task）`[required · once]`
 
-This step applies only to change-bearing tasks. An eligible analysis-only task stays in `planning` and, after its evidence work is complete, continues directly to Phase 3.3 without running `task.py start`.
+此步骤仅适用于 change-bearing 任务。符合条件的 analysis-only 任务保持 `planning`，完成证据工作后不运行 `task.py start`，直接进入阶段 3.3。
 
-After the Planning Seal closure pass, artifact review, and applicable native
-plan seal/approve gates described above, flip the task status to `in_progress`:
+完成 Planning Seal 收口检查、资产审查以及上文适用的原生 plan seal/approve 门禁后，将任务状态切换为 `in_progress`：
 
 ```bash
 python3 ./.trellis/scripts/task.py start <task-dir>
 ```
 
-For lightweight tasks, `prd.md` can be enough. For complex tasks, `prd.md`, `design.md`, and `implement.md` must exist and be reviewed before start. On sub-agent-dispatch platforms, `implement.jsonl` and `check.jsonl` must both have real curated entries before start. Runtime consumers tolerate missing or seed-only manifests for compatibility, but that tolerance is not a planning-ready state.
+轻量任务可以只有 `prd.md`。复杂任务在 start 前必须存在并审查 `prd.md`、`design.md` 和 `implement.md`。在派发子代理的平台上，start 前 `implement.jsonl` 和 `check.jsonl` 都必须有真实整理条目。运行时消费者为兼容性可以容忍清单缺失或只有种子内容，但这种容忍不代表规划已就绪。
 
-After this command succeeds, the breadcrumb auto-switches to `[workflow-state:in_progress]`, and the rest of Phase 2 / 3 follows.
+命令成功后，面包屑自动切换为 `[workflow-state:in_progress]`，随后进入阶段二和阶段三。
 
-If `task.py start` errors with a session-identity message (no context key from hook input, `TRELLIS_CONTEXT_ID`, or platform-native session env), follow the hint in the error to set up session identity, then retry.
+如果 `task.py start` 因会话身份错误而失败（Hook 输入、`TRELLIS_CONTEXT_ID` 或平台原生会话环境中没有上下文键），按照错误提示设置会话身份后重试。
 
-#### 1.5 Completion criteria
+#### 1.5 完成标准（Completion criteria）
 
-| Condition | Required |
+| 条件（Condition） | 必需（Required） |
 |------|:---:|
-| `prd.md` exists | ✅ |
-| Change-bearing task: user confirms implementation | ✅ |
-| Change-bearing task: `task.py start` has been run (status = in_progress) | ✅ |
-| Analysis-only task: exact metadata, named evidence deliverable, recorded acceptance evidence, and protected targets unchanged | ✅ |
-| `research/` has artifacts (complex tasks) | recommended |
-| `design.md` exists (complex tasks) | ✅ |
-| `implement.md` exists (complex tasks) | ✅ |
-| Change-bearing task: Planning Seal closure pass recorded; static implementation decisions and paths are locked | ✅ |
+| `prd.md` 存在 | ✅ |
+| Change-bearing 任务：用户确认实施 | ✅ |
+| Change-bearing 任务：已运行 `task.py start`（status = in_progress） | ✅ |
+| Analysis-only 任务：准确的元数据、明确的证据交付物、已记录验收证据，且受保护目标未变 | ✅ |
+| `research/` 有资产（复杂任务） | 推荐 |
+| `design.md` 存在（复杂任务） | ✅ |
+| `implement.md` 存在（复杂任务） | ✅ |
+| Change-bearing 任务：已记录 Planning Seal 收口检查；静态实施决策和路径已锁定 | ✅ |
 
 [Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
-| Change-bearing task: `implement.jsonl` and `check.jsonl` each contain at least one real curated entry (seed row does not count) | ✅ |
+| Change-bearing 任务：`implement.jsonl` 和 `check.jsonl` 都必须至少包含真实整理条目（种子行不算） | ✅ |
 
 [/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
 ---
 
-## Phase 2: Execute
+## 阶段二：执行（Phase 2: Execute）
 
-Goal: turn reviewed planning artifacts into code that passes quality checks.
+目标：将已审查的规划资产转化为通过质量检查的代码。
 
-#### 2.1 Implement `[required · repeatable]`
+#### 2.1 实施（Implement）`[required · repeatable]`
 
 [Claude Code, Cursor, OpenCode, codex-sub-agent, CodeBuddy, Droid, Pi, ZCode, Snow, Oh My Pi]
 
-Spawn the implement sub-agent:
+派发实施子代理：
 
-- **Agent type**: `trellis-implement`
-- **Task description**: Implement the reviewed task artifacts, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
-- **Dispatch prompt guard**: The prompt MUST start with `Active task: <task path>`, then tell the spawned agent it is already the `trellis-implement` sub-agent and must implement directly, not spawn another `trellis-implement` / `trellis-check`.
+- **Agent 类型**：`trellis-implement`
+- **任务描述**：根据已审查的任务资产实施，参考 `{TASK_DIR}/research/` 下的材料；完成后运行项目 lint 和类型检查。
+- **派发提示约束**：提示必须以 `Active task: <task path>` 开始，然后告知派发的 Agent 已经是 `trellis-implement` 子代理，必须直接实施，不得再派发其他 `trellis-implement` / `trellis-check`。
 
-The platform hook/plugin auto-handles:
-- Reads `implement.jsonl` and injects referenced spec/research files into the agent prompt
-- Injects `prd.md`, `design.md` if present, and `implement.md` if present
-- For Codex, `SubagentStart` supplies native context injection; the agent profile keeps child-side loading as the fallback
+平台 Hook/插件会自动处理：
+- 读取 `implement.jsonl`，并将引用的 spec/研究文件注入 Agent 提示
+- 注入存在时的 `prd.md`、`design.md` 和 `implement.md`
+- 对 Codex，`SubagentStart` 提供原生上下文注入；Agent 配置保留子代理侧读取作为后备路径
 
 [/Claude Code, Cursor, OpenCode, codex-sub-agent, CodeBuddy, Droid, Pi, ZCode, Snow, Oh My Pi]
 
 [Gemini, Qoder, Copilot, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
-Spawn the implement sub-agent:
+派发实施子代理：
 
-- **Agent type**: `trellis-implement`
-- **Task description**: Implement the reviewed task artifacts, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
-- **Dispatch prompt guard**: The prompt MUST start with `Active task: <task path>`, then explicitly say the spawned agent is already `trellis-implement` and must implement directly without spawning another `trellis-implement` / `trellis-check`.
-- **DeepSeek Harness**: tell the child to load `trellis-agent-implement` exactly once. If `trellis_wait` is available, use the default background mode, continue independent work, then wait once for that child id and consume its successful native settlement notice before Phase 2.2. Without `trellis_wait`, dispatch that child with `run_in_background: false`. Do not poll or sleep.
+- **Agent 类型**：`trellis-implement`
+- **任务描述**：根据已审查的任务资产实施，参考 `{TASK_DIR}/research/` 下的材料；完成后运行项目 lint 和类型检查。
+- **派发提示约束**：提示必须以 `Active task: <task path>` 开始，然后明确告知派发的 Agent 已经是 `trellis-implement`，必须直接实施，不得再派发 `trellis-implement` / `trellis-check`。
+- **DeepSeek Harness**：告知子代理恰好加载一次 `trellis-agent-implement`。提供 `trellis_wait` 时，使用默认后台模式，继续独立工作，然后对该子代理 ID 等待一次并消费其成功的原生结算通知后才进入阶段 2.2。没有 `trellis_wait` 时，派发设置 `run_in_background: false`。不得轮询或 sleep。
 
-The pull-based sub-agent definition auto-handles the context load requirement:
-- Resolves the active task with `task.py current --source`, then reads `prd.md`, `design.md` if present, and `implement.md` if present
-- Reads `implement.jsonl` and requires the agent to load each referenced spec/research file before coding
+拉取式子代理定义会自动处理上下文加载：
+- 使用 `task.py current --source` 解析活动任务，然后读取 `prd.md`、存在时的 `design.md` 和 `implement.md`
+- 读取 `implement.jsonl`，并要求 Agent 在编码前加载每个引用的 spec/研究文件
 
 [/Gemini, Qoder, Copilot, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
 [Kiro]
 
-Spawn the implement sub-agent:
+派发实施子代理：
 
-- **Agent type**: `trellis-implement`
-- **Task description**: Implement the reviewed task artifacts, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
-- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-implement` sub-agent and must implement directly, not spawn another `trellis-implement` / `trellis-check`.
+- **Agent 类型**：`trellis-implement`
+- **任务描述**：根据已审查的任务资产实施，参考 `{TASK_DIR}/research/` 下的材料；完成后运行项目 lint 和类型检查。
+- **派发提示约束**：告知派发的 Agent 已经是 `trellis-implement` 子代理，必须直接实施，不得再派发 `trellis-implement` / `trellis-check`。
 
-The platform prelude auto-handles the context load requirement:
-- Reads `implement.jsonl` and injects referenced spec/research files into the agent prompt
-- Injects `prd.md`, `design.md` if present, and `implement.md` if present
+平台前置处理会自动加载上下文：
+- 读取 `implement.jsonl`，并将引用的 spec/研究文件注入 Agent 提示
+- 注入存在时的 `prd.md`、`design.md` 和 `implement.md`
 
 [/Kiro]
 
 [codex-inline, Kilo, Antigravity, Devin]
 
-1. Load the `trellis-before-dev` skill to read project guidelines
-2. Read `{TASK_DIR}/prd.md`, then `design.md` if present, then `implement.md` if present
-3. Consult materials under `{TASK_DIR}/research/`
-4. Implement the code per reviewed artifacts
-5. Run project lint and type-check
+1. 加载 `trellis-before-dev` Skill 读取项目指南
+2. 读取 `{TASK_DIR}/prd.md`，再读取存在时的 `design.md` 和 `implement.md`
+3. 查阅 `{TASK_DIR}/research/` 下的材料
+4. 根据已审查资产实施代码
+5. 运行项目 lint 和类型检查
 
 [/codex-inline, Kilo, Antigravity, Devin]
 
-#### 2.2 Quality check `[required · repeatable]`
+#### 2.2 质量检查（Quality check）`[required · repeatable]`
 
 [Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
-Spawn the check sub-agent:
+派发检查子代理：
 
-- **Agent type**: `trellis-check`
-- **Task description**: Review all code changes against specs and task artifacts; fix any findings directly; ensure lint and type-check pass
-- **Dispatch prompt guard**: The prompt MUST start with `Active task: <task path>`, then tell the spawned agent it is already the `trellis-check` sub-agent and must review/fix directly, not spawn another `trellis-check` / `trellis-implement`.
-- **DeepSeek Harness**: tell the child to load `trellis-agent-check` exactly once. If `trellis_wait` is available, use the default background mode, continue independent work, then wait once for that child id and consume its successful native settlement notice before Phase 3. Without `trellis_wait`, dispatch that child with `run_in_background: false`. Do not poll or sleep.
+- **Agent 类型**：`trellis-check`
+- **任务描述**：对照 spec 和任务资产审查全部代码变更；直接修复发现的问题；确保 lint 和类型检查通过。
+- **派发提示约束**：提示必须以 `Active task: <task path>` 开始，然后告知派发的 Agent 已经是 `trellis-check` 子代理，必须直接审查/修复，不得再派发其他 `trellis-check` / `trellis-implement`。
+- **DeepSeek Harness**：告知子代理恰好加载一次 `trellis-agent-check`。提供 `trellis_wait` 时，使用默认后台模式，继续独立工作，然后对该子代理 ID 等待一次并消费其成功的原生结算通知后才进入阶段三。没有 `trellis_wait` 时，派发设置 `run_in_background: false`。不得轮询或 sleep。
 
-The check agent's job:
-- Review code changes against specs
-- Review code changes against `prd.md`, `design.md` if present, and `implement.md` if present
-- Auto-fix issues it finds
-- Run lint and typecheck to verify
-- A required check that cannot run, is skipped, or exits non-zero is blocked/failed, never passed. Do not weaken or rewrite acceptance criteria to advance the workflow.
+检查 Agent 的职责：
+- 对照 spec 审查代码变更
+- 对照 `prd.md`、存在时的 `design.md` 和 `implement.md` 审查代码变更
+- 自动修复发现的问题
+- 运行 lint 和类型检查进行验证
+- 必须检查但无法运行、被跳过或以非零状态退出的检查属于阻塞/失败，绝不能算作通过。不要为了推进工作流而降低或改写验收标准。
 
 [/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
 [codex-inline, Kilo, Antigravity, Devin]
 
-Load the `trellis-check` skill and verify the code per its guidance:
-- Spec compliance
-- lint / type-check / tests
-- Cross-layer consistency (when changes span layers)
+加载 `trellis-check` Skill 并按其指引验证代码：
+- spec 合规性
+- lint / 类型检查 / 测试
+- 跨层一致性（变更跨层时）
 
-If issues are found → fix → re-check, until green.
+如果发现问题 → 修复 → 重新检查，直到通过。
 
 [/codex-inline, Kilo, Antigravity, Devin]
 
-**Final pass (before Phase 3.4 commit)**: the last 2.2 of a task must run full-scope, not just on the latest implement chunk. List all affected packages with `python3 ./.trellis/scripts/get_context.py --mode packages`, then load each package's spec index Quality Check section. This catches cross-layer / multi-package issues a mid-iteration local 2.2 cannot.
+**最终检查（阶段 3.4 提交前）**：任务最后一次 2.2 必须覆盖完整范围，不能只检查最近一次实施的改动。使用 `python3 ./.trellis/scripts/get_context.py --mode packages` 列出所有受影响的包，然后加载每个包 spec 索引中的质量检查部分。这可以发现中途局部 2.2 无法发现的跨层/多包问题。
 
-#### 2.3 Rollback `[on demand]`
+#### 2.3 回滚（Rollback）`[on demand]`
 
-- `check` reveals a prd defect → return to Phase 1, fix `prd.md`, then redo 2.1
-- Implementation went wrong → revert code, redo 2.1
-- Need more research → research (same as Phase 1.2), write findings into `research/`
+- `check` 暴露 PRD 缺陷 → 返回阶段一，修复 `prd.md`，然后重新执行 2.1
+- 实施出错 → 回退代码，重新执行 2.1
+- 需要更多研究 → 进行研究（同阶段一的 1.2），将发现写入 `research/`
 
 ---
 
-## Phase 3: Finish
+## 阶段三：完成（Phase 3: Finish）
 
-Goal: ensure code quality, capture lessons, record the work.
+目标：确保代码质量，记录经验和工作过程。
 
-**Analysis-only completion route**: after the evidence work in Phase 1, verify the PRD acceptance criteria and no-change boundary, then continue with 3.3 and 3.4 for task artifacts only before `/trellis:finish-work`. Do not run Phase 2 or `task.py start`.
+**Analysis-only 完成路径**：阶段一证据工作完成后，验证 PRD 验收标准和不变更边界，然后只针对任务资产进入 3.3 和 3.4，最后运行 `/trellis:finish-work`。不要运行阶段二或 `task.py start`。
 
-#### 3.2 Debug retrospective `[on demand]`
+#### 3.2 调试复盘（Debug retrospective）`[on demand]`
 
-If this task involved repeated debugging (the same issue was fixed multiple times), load the `trellis-break-loop` skill to:
-- Classify the root cause
-- Explain why earlier fixes failed
-- Propose prevention
+如果任务涉及重复调试（同一问题被多次修复），加载 `trellis-break-loop` Skill：
+- 分类根因
+- 解释之前的修复为什么失败
+- 提出预防措施
 
-The goal is to capture debugging lessons so the same class of issue doesn't recur.
+目标是记录调试经验，避免同类问题再次发生。
 
-#### 3.3 Spec update `[required · once]`
+#### 3.3 更新 Spec（Spec update）`[required · once]`
 
-Load the `trellis-update-spec` skill and review whether this task produced new knowledge worth recording:
-- Newly discovered patterns or conventions
-- Pitfalls you hit
-- New technical decisions
+加载 `trellis-update-spec` Skill，审查本任务是否产生了值得记录的新知识：
+- 新发现的模式或约定
+- 遇到的陷阱
+- 新的技术决策
 
-Update the docs under `.trellis/spec/` accordingly. Even if the conclusion is "nothing to update", walk through the judgment.
+相应更新 `.trellis/spec/` 下的文档。即使结论是“不需要更新”，也要完成并记录判断过程。
 
-#### 3.4 Commit changes `[required · once]`
+#### 3.4 提交变更（Commit changes）`[required · once]`
 
-**Spec-sync preamble**: before drafting commits, ask: did this task fix a bug or surface non-obvious knowledge that should land in `.trellis/spec/` so future-you (or future-AI) doesn't repeat the mistake? If yes, return to Phase 3.3 first — spec writes belong in the same task's commit batch, not as a forgotten follow-up.
+**Spec 同步前置检查**：起草提交前询问：本任务是否修复了缺陷，或发现了应写入 `.trellis/spec/` 的非显然知识，以免未来的你或 AI 重复犯错？如果是，先回到阶段 3.3；spec 写入应包含在本任务的提交批次中，不能遗忘到后续。
 
-The AI drives a batched commit of this task's code changes so `/finish-work` can run cleanly afterwards. Goal: produce work commits FIRST, then bookkeeping (archive + journal) commits land after — never interleaved.
+由 AI 批量提交本任务的代码变更，使 `/finish-work` 能在之后干净运行。目标是先生成工作提交，再生成归档和日志等记账提交；两者不得交错。
 
-**Step-by-step**:
+**步骤**：
 
-1. **Inspect dirty state**:
+1. **检查脏状态**：
    ```bash
    git status --porcelain
    ```
-   Snapshot every dirty path. If the working tree is clean, skip to 3.5.
+   记录所有脏路径。如果工作树干净，跳到 3.5。
 
-2. **Learn commit style** from recent history (so drafted messages blend in):
+2. **从近期历史了解提交风格**（使拟定消息保持一致）：
    ```bash
    git log --oneline -5
    ```
-   Note the prefix convention (`feat:` / `fix:` / `chore:` / `docs:` ...), language (中文/English), and length style.
+   记录前缀约定（`feat:` / `fix:` / `chore:` / `docs:` 等）、语言（中文/English）和长度风格。
 
-3. **Classify dirty files into two groups**:
-   - **AI-edited this session** — files you wrote/edited via Edit/Write/Bash tool calls in this session. You know what changed and why.
-   - **Unrecognized** — dirty files you did NOT touch this session (could be the user's manual edits, leftover WIP from a previous session, or unrelated work). Do NOT silently include these.
+3. **将脏文件分为两组**：
+   - **本会话由 AI 编辑**——本会话通过 Edit/Write/Bash 工具调用写入或编辑的文件。你知道它们改了什么以及为什么改。
+   - **未识别**——本会话没有触碰的脏文件（可能是用户手动编辑、之前会话遗留的 WIP 或无关工作）。不要静默纳入。
 
-4. **Draft a commit plan**. Group AI-edited files into logical commits (1 commit per coherent change unit, not 1 commit per file). Each entry: `<commit message>` + file list. List unrecognized files separately at the bottom.
+4. **起草提交计划**。将 AI 编辑的文件按逻辑提交分组（每个连贯变更单元一个提交，而不是每个文件一个提交）。每项包含 `<commit message>` 和文件列表；将未识别文件单独列在末尾。
 
-5. **Present the plan once, ask for one-shot confirmation**. Format:
+5. **展示一次计划并一次性请求确认**。格式：
    ```
    Proposed commits (in order):
      1. <message>
@@ -760,54 +705,54 @@ The AI drives a batched commit of this task's code changes so `/finish-work` can
    Reply 'ok' / '行' to execute. Reply with edits, or '我自己来' / 'manual' to abort.
    ```
 
-6. **On confirmation**: run `git add <files>` + `git commit -m "<msg>"` for each batch in order. Do not amend. Do not push.
+6. **获得确认后**：按顺序对每个批次运行 `git add <files>` + `git commit -m "<msg>"`。不要 amend，不要 push。
 
-7. **On rejection** (user replies "不行" / "我自己来" / "manual" / any pushback on the plan): stop. Do not attempt a second plan. The user will commit by hand; you skip ahead to 3.5 once they confirm.
+7. **遭到拒绝时**（用户回复“不行”/“我自己来”/“manual”或对计划提出任何反对）：停止，不要再尝试第二个计划。用户会手动提交；用户确认后跳到 3.5。
 
-**Rules**:
-- No `git commit --amend` anywhere — three-stage three-commit flow (work commits → archive commit → journal commit).
-- Never push to remote in this step.
-- If the user wants different message wording but accepts the file grouping, edit the message and re-confirm once — but if they reject the grouping, exit to manual mode.
-- The batched plan is one prompt; do not prompt per commit.
+**规则**：
+- 任何位置都不得使用 `git commit --amend`——采用三阶段三提交流程（工作提交 → 归档提交 → 日志提交）。
+- 此步骤绝不 push 到远程。
+- 用户接受文件分组但希望调整消息措辞时，修改消息并重新确认一次；如果拒绝分组，退出到手动模式。
+- 批量计划只使用一个提问，不要逐提交提问。
 
-#### 3.5 Wrap-up reminder
+#### 3.5 收尾提醒（Wrap-up reminder）
 
-After the above, remind the user they can run `/finish-work` to wrap up (archive the task, record the session).
+完成以上步骤后，提醒用户可以运行 `/finish-work` 收尾（归档任务、记录会话）。
 
 ---
 
-## Customizing Trellis (for forks)
+## 自定义 Trellis（适用于 fork）
 
-This section is for developers who want to modify the Trellis workflow itself. All customization is done by editing this file; the scripts are parsers only.
+本节面向需要修改 Trellis 工作流本身的开发者。所有自定义都通过编辑本文件完成；脚本只负责解析。
 
-### Changing what a step means
+### 修改步骤含义
 
-Edit the corresponding step's walkthrough body in the Phase 1 / 2 / 3 sections above. Critical invariants:
-- No active task must triage first; direct small work may proceed only when bounded, single-surface, and immediately verifiable, otherwise create a Trellis task first.
-- Planning must distinguish lightweight PRD-only tasks from complex tasks that require `prd.md`, `design.md`, and `implement.md` before start.
-- Every required execution path must keep the Phase 3.4 commit reminder reachable before `/trellis:finish-work`.
+编辑上方阶段一/二/三中对应步骤的说明正文。关键不变量：
+- 没有活动任务时先分类；只有边界清晰、涉及单一表面且可立即验证的直接小任务可以继续，否则先创建 Trellis 任务。
+- 规划必须区分只有 PRD 的轻量任务，以及 start 前需要 `prd.md`、`design.md` 和 `implement.md` 的复杂任务。
+- 每条必需执行路径都必须在 `/trellis:finish-work` 前保留可达的阶段 3.4 提交提醒。
 
-All tag blocks live in the `## Phase Index` section above, immediately after each phase summary:
+所有标签块位于上方 `## Phase Index` 区域中，紧跟各阶段摘要之后：
 
-| Scope | Corresponding tag |
+| 范围（Scope） | 对应标签（Corresponding tag） |
 |---|---|
-| No active task (before Phase 1) | `[workflow-state:no_task]` (after the Phase Index ASCII art) |
-| One developer-owned task without a session binding | `[workflow-state:unbound_task]` (bind before lifecycle writes) |
-| Multiple developer-owned tasks without a session binding | `[workflow-state:unbound_ambiguous]` / `[workflow-state:unbound_ambiguous-inline]` (choose and bind explicitly) |
-| Active task record unreadable | `[workflow-state:task_error]` (repair the existing task before continuing) |
-| All of Phase 1 (task created → ready for implementation) | `[workflow-state:planning]` (after Phase 1 summary) |
-| Codex inline Phase 1 | `[workflow-state:planning-inline]` |
-| Phase 2 + Phase 3.2–3.4 (implementation + check + wrap-up) | `[workflow-state:in_progress]` (after Phase 2 summary) |
-| Codex inline Phase 2 + Phase 3.2–3.4 | `[workflow-state:in_progress-inline]` |
-| After Phase 3.5 (archived) | `[workflow-state:completed]` (after Phase 3 summary; **currently DEAD**) |
+| 没有活动任务（阶段一之前） | `[workflow-state:no_task]`（阶段索引图之后） |
+| 一个开发者所属任务没有会话绑定 | `[workflow-state:unbound_task]`（生命周期写入前绑定） |
+| 多个开发者所属任务没有会话绑定 | `[workflow-state:unbound_ambiguous]` / `[workflow-state:unbound_ambiguous-inline]`（明确选择并绑定） |
+| 活动任务记录不可读 | `[workflow-state:task_error]`（继续前修复已有任务） |
+| 整个阶段一（创建任务 → 实施就绪） | `[workflow-state:planning]`（阶段一摘要之后） |
+| Codex inline 阶段一 | `[workflow-state:planning-inline]` |
+| 阶段二 + 阶段 3.2–3.4（实施 + 检查 + 收尾） | `[workflow-state:in_progress]`（阶段二摘要之后） |
+| Codex inline 阶段二 + 阶段 3.2–3.4 | `[workflow-state:in_progress-inline]` |
+| 阶段 3.5 之后（已归档） | `[workflow-state:completed]`（阶段三摘要之后；**目前不可达**） |
 
-### Changing the per-turn prompt text
+### 修改每轮提示文本
 
-Directly edit the body of the corresponding `[workflow-state:STATUS]` block. After editing, run `trellis update` (if you're a template maintainer) or restart your AI session (if you're customizing your own project) — no script changes required.
+直接编辑对应 `[workflow-state:STATUS]` 块的正文。编辑后，模板维护者运行 `trellis update`，自定义项目重启 AI 会话；不需要修改脚本。
 
-### Adding a custom status
+### 添加自定义状态
 
-Add a new block:
+添加新块：
 
 ```
 [workflow-state:my-status]
@@ -815,14 +760,14 @@ your per-turn prompt text
 [/workflow-state:my-status]
 ```
 
-Constraints:
-- STATUS charset: `[A-Za-z0-9_-]+` (underscores and hyphens allowed, e.g. `in-review`, `blocked-by-team`)
-- A lifecycle hook must write `task.json.status` to your custom value, otherwise the tag is never read
-- Lifecycle hooks live in `task.json.hooks.after_*` and bind to one of `after_create / after_start / after_finish / after_archive`
+约束：
+- STATUS 字符集：`[A-Za-z0-9_-]+`（允许下划线和连字符，例如 `in-review`、`blocked-by-team`）
+- 生命周期 Hook 必须将 `task.json.status` 写为自定义值，否则标签不会被读取
+- 生命周期 Hook 位于 `task.json.hooks.after_*`，绑定到 `after_create / after_start / after_finish / after_archive` 之一
 
-### Adding a lifecycle hook
+### 添加生命周期 Hook
 
-Add a `hooks` field to your `task.json`:
+在 `task.json` 中添加 `hooks` 字段：
 
 ```json
 {
@@ -834,11 +779,11 @@ Add a `hooks` field to your `task.json`:
 }
 ```
 
-Supported events: `after_create / after_start / after_finish / after_archive`. Note that `after_finish` ≠ a status change (it only clears the active-task pointer); use `after_archive` for "task is done" notifications.
+支持的事件：`after_create / after_start / after_finish / after_archive`。注意 `after_finish` 不等于状态变化（它只清除活动任务指针）；“任务完成”通知应使用 `after_archive`。
 
-### Full contract
+### 完整合同
 
-For the workflow state machine's runtime contract, the locations of all status writers, pseudo-statuses (`no_task` / `stale_<source_type>`), the hook reachability matrix, and other deep details, see:
+关于工作流状态机运行时合同、所有状态写入位置、伪状态（`no_task` / `stale_<source_type>`）、Hook 可达性矩阵及其他详细内容，参阅：
 
-- `.trellis/spec/cli/backend/workflow-state-contract.md` — runtime contract + writer table + test invariants
-- `.trellis/scripts/inject-workflow-state.py` — actual parser (reads workflow.md only, no embedded text)
+- `.trellis/spec/cli/backend/workflow-state-contract.md`——运行时合同、写入表和测试不变量
+- `.trellis/scripts/inject-workflow-state.py`——实际解析器（只读取 workflow.md，没有内嵌正文）