@pennixrv/trellis 0.7.0-beta.9 → 0.7.1

package/dist/templates/common/bundled-skills/trellis-solution-design-and-convergence/workflow.md

@@ -0,0 +1,36 @@
+# 解决方案设计与收敛阶段流程
+
+核对有效的目标基线、决策空间构造与归并阶段结果或跳过记录及其 revision。按依赖筛选影响目标、范围、成功条件、用户偏好、风险承受或重要取舍的保留决定；使用 `pennix-decision-grill` 同步提问。答复到达后，核对其权限、当前 revision 和影响范围：影响目标或范围时回到目标探索与需求核对阶段，影响候选、标准或依赖时回到决策空间构造与归并阶段，仅改变当前候选中的方案时继续本阶段评估。待决定事项使解决方案设计与收敛阶段保持待决。
+
+比较适用方案，说明选择依据、重要后果、行为边界、责任、必要依赖、验证方式、停止与恢复条件及实质风险。对新颖核心机制、重大重构、跨组件边界变化或关键不确定性缺少可信本地先例的方案，在结果接受前完成有界 `prior-art review`，记录适用性、采纳或排除理由，或说明没有适用先例。外部材料改变候选、标准或依赖时回到决策空间构造与归并阶段。
+
+判断当前结果：分析交付形成 `analysis_conclusion`；不继续形成 `no_go`；延期形成带责任方、触发条件和恢复位置的 `deferred`，留在解决方案设计与收敛阶段；实施路线形成 `implementation_contract`，明确目标、范围和接受条件，并按路线需要补足实施与核验信息。只有交付物具有独立实施或集成边界时才拆分工作包，并说明推进和协作所需的依赖、顺序、责任或集成信息；单一交付不人为拆分工作包。解决方案设计与收敛阶段的结果接受与实施授权分开记录；只有合同及明确批准均有效时，Trellis CLI 才允许进入任务实施与测试验证阶段。
+
+```mermaid
+flowchart TD
+  input["核对需求基线与已接受的 DecisionSpace"] --> decisions{"存在尚待用户决定的实质取舍？"}
+  decisions -->|"是"| grill["pennix-decision-grill 同步询问；留在解决方案设计与收敛阶段"]
+  grill --> impact{"答复影响哪个范围？"}
+  impact -->|"目标或范围"| goal_exploration_and_requirements["回到目标探索与需求核对阶段"]
+  impact -->|"候选、标准或依赖"| decision_space_construction_and_merging["回到决策空间构造与归并阶段"]
+  impact -->|"当前候选中的选择"| compare["比较方案和重要后果"]
+  decisions -->|"否"| compare
+  compare --> prior{"触发 prior-art review？"}
+  prior -->|"是"| review["核验相关开源实现或公开提案并记录适用性"]
+  review --> changed{"外部证据改变候选、标准或依赖？"}
+  changed -->|"是"| decision_space_construction_and_merging
+  changed -->|"否"| assess["核对完整性、风险、验证和恢复条件"]
+  prior -->|"否"| assess
+  assess -->|"有实质缺口"| compare
+  assess -->|"analysis_conclusion 或 no_go"| reviewResult["Trellis CLI 接受解决方案设计与收敛阶段结果"]
+  assess -->|"deferred"| defer["记录恢复条件并留在解决方案设计与收敛阶段"]
+  assess -->|"implementation_contract"| contract["冻结必要实施合同"]
+  contract --> approval{"合同获接受且实施批准有效？"}
+  approval -->|"否"| wait["等待决定或授权；不进入实施"]
+  approval -->|"是"| task_implementation["Trellis CLI 核验并进入任务实施与测试验证阶段"]
+  reviewResult --> delivery_review_and_closeout["交付审查与现场收尾阶段"]
+```
+
+### 方案是否足以收敛
+
+实施者应能从当前方案判断要做什么、由谁负责、依赖什么、如何验证，以及何时停止或恢复；影响选择、接受、安全、权限、成本或不可逆影响的取舍应有依据和处理方式。未知事项可以补证、接受剩余风险、延期或不继续。此判断不要求固定篇幅、备选数量、字段或图表。

package/dist/templates/common/bundled-skills/trellis-task-implementation/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: trellis-task-implementation
+description: 当前任务处于任务实施与测试验证阶段时，按已授权实施合同推进工作包、验证、集成与阻塞处置。
+---
+
+# 任务实施与测试验证阶段
+
+当 `current_phase_id` 为 `task_implementation` 时使用。先阅读本 Skill 同目录的 `workflow.md`，再加载目标仓库适用的 `AGENTS.md`、Trellis spec 和实现合同。
+
+按合同依赖和优先级逐项实施；主工作树主代理负责阶段接受和集成。只在执行路线获准时使用 Paseo 委派写入；Trellis Teamwork teammate 只提供只读证据。默认在当前阶段修复和验证，只有合同、授权、依赖、基线或接受条件实质失效且无法安全恢复时，才回到最早受影响的阶段。

package/dist/templates/common/bundled-skills/trellis-task-implementation/workflow.md

@@ -0,0 +1,29 @@
+# 任务实施与测试验证阶段流程
+
+开始前核验当前 `implementation_contract`、实施授权、路线 revision、必要依赖和执行基线。使用 `trellis-before-dev` 读取目标仓库实际适用的规范；按组件 owner 合同选择主工作树或已批准的独立写入路线。调用项目任务 `start` 只在实施授权有效时将任务置为 `in_progress`。
+
+按合同的依赖和优先级选取当前工作包，实施满足目标的最小变更，并运行与风险和影响相称的局部验证。主工作树主代理核对来源、revision、Git 基线、差异和结果后接受工作包。多包任务按合同集成；单一交付不人为拆分。Trellis Teamwork 仅用于冻结计划下的只读比较或评议，不能改写任务状态或接受实施结果。实际写入委派依父任务规定使用 Trellis 受控入口与 Paseo；各组件源码仍在 owner 仓库内修改。
+
+局部失败、暂时不可用或当前状态已满足接受条件时，先在任务实施与测试验证阶段中处理。依赖或资源暂不可用且现场安全时记录恢复条件；未授权不产生外部副作用；未知现场先停止并核验。合同允许未运行验证且风险可接受时，记录原因、影响和替代证据。替代路线若改变授权、成本、隐私或接受条件，回到解决方案设计与收敛阶段；目标、范围变化按影响回到目标探索与需求核对阶段或决策空间构造与归并阶段。只有合同范围内工作包均已接受、适用必需验证完成或有有效未运行处置、按范围和风险需要的集成验证通过，才将交付候选交由交付审查与现场收尾阶段；仅当路线实际创建或委派资源时，才核验其处置事实。
+
+```mermaid
+flowchart TD
+  contract["核验 implementation_contract、授权、revision 和依赖"] --> ready{"准入与实施授权有效？"}
+  ready -->|"否，待用户决定或依赖"| wait["等待或记录阻断；不启动副作用"]
+  wait -->|"恢复后重新核验"| contract
+  ready -->|"是"| work["按合同依赖和优先级选取当前工作包"]
+  work --> implement["读取适用规范并实施最小变更"]
+  implement --> verify["执行与风险相称的局部验证"]
+  verify --> inspect["主工作树主代理核对 revision、基线、差异和结果"]
+  inspect -->|"局部缺陷或可处理冲突"| implement
+  inspect -->|"合同仍有效，当前 attempt 受阻"| stop["停止受影响范围并记录恢复条件"]
+  stop -->|"可安全恢复"| contract
+  inspect -->|"路线或合同实质失效"| replan["回最早受影响阶段并明确理由"]
+  inspect -->|"当前工作包接受"| more{"还有合同内工作包或必需验证？"}
+  more -->|"是"| work
+  more -->|"否；适用集成已核验，委派资源（如有）已安全处置"| candidate["形成交付候选并进入交付审查与现场收尾阶段"]
+```
+
+### 委派、回退与收敛
+
+回退使用当前 owner 的 Git 和资源合同，不覆盖无关改动，也不删除仍需核验的现场。只有当前合同无法安全覆盖目标、授权、依赖、基线、接受条件或停止条件的变化时，才回退到最早受影响阶段。结束任务实施与测试验证阶段前，记录适用验证结果、未运行处置、合同差异和未结发现；仅当路线实际创建或委派资源时，记录其处置状态。

package/dist/templates/common/bundled-skills/trellis-teamwork/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: trellis-teamwork
+description: Use Trellis Teamwork for live multi-agent collaboration, Teamwork Sessions, teammate assignments, coordination modes, and runtime diagnostics.
+---
+
+# trellis-teamwork
+
+`trellis teamwork` is the local multi-agent collaboration runtime. A
+Teamwork Session is the persistent chat or forum object used by the runtime;
+it is independent from the Trellis task lifecycle and does not own business-phase progress.
+Use Teamwork when agents need a durable event log, a bounded teammate
+assignment, a one-shot consultation, or a forum discussion.
+
+Typical user signals: “和 codex/claude 讨论”, “brainstorm with another agent”, “派一个 teammate 做 review”, “open a Teamwork forum”, “look at this thread”, “Teamwork 卡住了 / 没输出”, “progress was truncated”, “how do I use trellis teamwork”.
+
+This skill is an index. Load only the reference file for the current job — do not preload all of them.
+
+## First Commands
+
+```bash
+trellis --version
+trellis teamwork --help
+trellis teamwork list --all
+trellis teamwork list --scope global --all
+```
+
+If the user names a Teamwork Session or thread, inspect it before asking for
+background:
+
+```bash
+trellis teamwork forum <session> --scope global
+trellis teamwork thread <session> <thread> --scope global
+trellis teamwork context list <session> --scope global --thread <thread>
+```
+
+## Route By User Intent
+
+| User intent | Read |
+|---|---|
+| “和 codex/claude 讨论一下”, “brainstorm with another agent” | `references/teamwork-plan-construction.md`, then `references/coordination-modes.md` |
+| “派一个 implement/check agent”, “让 agent review”, “spawn a worker” | `references/teamwork-plan-construction.md`, then `references/teammate-processes.md` |
+| “开 issue 区 / topic 群 / changelog / board”, “make a forum” | `references/teamwork-plan-construction.md` |
+| “看看这个 thread”, “inspect a thread” | `references/teamwork-plan-construction.md` |
+| “Teamwork 卡住了 / 没输出 / progress 被截断”, “teammate stalled” | `references/teammate-processes.md` |
+| “具体命令怎么写”, “what flags does X take” | `references/teamwork-plan-construction.md` |
+
+## Core Rules
+
+- New forum Teamwork Sessions use `--type forum`. A `thread` is one item inside a forum Teamwork Session.
+- Use `--context-file` / `--context-raw` and `trellis teamwork context add/delete/list`.
+- Use `--stdin` or `--text-file` for long messages. Do not put long mixed Chinese/English text in the positional shell argument.
+- Pretty `messages` output is an operator dashboard and may truncate progress. Use `--raw` for audit.
+- `--as` is the speaker or worker handle, depending on the command. Use explicit, stable names when multiple agents or sessions are involved.
+- `--scope project` (default) operates on the current cwd's project bucket; `--scope global` operates on the shared `__global__` bucket. Pick scope deliberately — a global board is invisible from project listings unless `--scope global` is passed.
+- For brainstorm, do multiple pressure-test rounds. One answer plus one confirmation is review, not brainstorm.
+- **Dispatcher wait pattern**: use `--kind done` / `--kind turn_finished` (Trellis-emitted system events), not a user `--tag` as the completion signal. Tags are labels, not runtime completion events.
+- Teamwork Sessions are event-sourced. Do not parse `events.jsonl` first; use `forum`, `thread`, `messages --thread`, and `context list`.
+- `@pennixrv/trellis-core` owns reusable Teamwork Session/thread state, event append, sequence allocation, context/title projection, reducers, and task helpers. The CLI owns flags, terminal rendering, prompts, teammate lifecycle, and process exits.
+- Teamwork plan construction belongs to the current phase coordinator. Teamwork validates and executes a frozen plan; it does not select the task phase, change task status, or create a second task state machine.
+- The native host-created `subagent` remains separate from a Teamwork teammate.
+
+## Reference Files
+
+- `references/teamwork-plan-construction.md` — plan binding, task integration, Teamwork Session and forum commands, reports, and cleanup.
+- `references/teammate-configuration-matrix.md` — candidate profiles, frozen execution configuration, provider capabilities, and role boundaries.
+- `references/coordination-modes.md` — `general`, `advisor`, and `committee` semantics and selection.
+- `references/teammate-processes.md` — dispatch, context injection, waiting, interruption, retry, reconciliation, and diagnostics.
+
+## Not For
+
+- One static review where a markdown file and prompt are enough.
+- Replacing normal tool calls with self-logging.
+- Long-term memory retrieval. Use durable forum Teamwork Sessions for actionable issues, and `trellis mem` (the `trellis-session-insight` skill) for session/history search.

package/dist/templates/common/bundled-skills/trellis-teamwork/references/coordination-modes.md

@@ -0,0 +1,29 @@
+# Coordination modes
+
+The plan's `coordination_mode` selects the call shape. It is independent from
+the teammate role, execution profile, and Teamwork Session type.
+
+## `general`
+
+Use general coordination for one or more independent assignments. Each
+assignment has its own objective, scope, lens, evidence, and acceptance
+criteria. The coordinator may fill available slots in plan order and settle
+each assignment independently.
+
+## `advisor`
+
+Use advisor coordination for one bounded consultation. The plan contains
+exactly one assignment and its result is advice for the current coordinator.
+The result still carries a source digest and acceptance evidence and does not
+change the task or phase by itself.
+
+## `committee`
+
+Use committee coordination when one question benefits from parallel distinct
+lenses. The plan contains two or three assignments in one evaluation group.
+All members share the assignment contract and use distinct lenses. They return
+independent evidence; the coordinator compares the reports after they finish.
+
+Committee members do not debate with one another, run a consensus loop, or use
+a directional counter relationship. If a question does not need independent
+lenses, use general coordination or advisor coordination instead.

package/dist/templates/common/bundled-skills/trellis-teamwork/references/teammate-configuration-matrix.md

@@ -0,0 +1,31 @@
+# Teammate configuration matrix
+
+The candidate source for teammate execution settings is the teammate
+configuration matrix. It is a selection input, not a new role system. A
+profile may provide a default provider and model plus provider-specific
+options. The frozen plan stores the selected execution values in the
+`Teammate Execution Configuration` snapshot so a running batch is unaffected
+by later matrix changes.
+
+The tuple is:
+
+```text
+role + provider + optional profile + model + reasoning effort + options
+```
+
+The role remains `teammate`. Coordination mode is separate from role and
+profile. Supported provider adapters are Codex app-server, DSH ACP, Copilot
+ACP, and Claude Code CLI when their host contracts are available. A provider
+name alone does not prove that its host is installed or verified.
+
+The host capability proof covers only the boundaries required by the selected
+plan: foreground waiting, protected artifact writes, read-only protected
+targets and Git state, disabled native or recursive delegation, isolated
+context, supported transport, and a positive capacity. The CLI refuses a
+dispatch when the selected host cannot prove those properties. It does not
+invent an execution profile or silently change the frozen values.
+
+The bundled role card is `.trellis/agents/teammate.md`. It is provider-neutral
+and limits a teammate to the frozen context and current attempt artifacts. A
+Teamwork teammate is not the native host-created `subagent`; the two have
+different creation paths and contracts.

package/dist/templates/common/bundled-skills/trellis-teamwork/references/teammate-processes.md

@@ -0,0 +1,37 @@
+# Teammate processes
+
+The coordinator creates a queue fact and an immutable claim for each
+assignment, dispatches the selected provider, waits for a terminal host fact,
+and validates the report against the assignment identity, source digest,
+evidence, path, secret, and symlink rules. The teammate writes only its
+current attempt artifacts. It does not modify product source, Git state, task
+status, or another teammate's artifacts.
+
+After a timeout, the same attempt may receive a continuation. A confirmed
+execution or acceptance failure may consume that assignment's explicit retry
+budget and create a new attempt identity. An uncertain command, changed host
+identity, or unconfirmed cancellation enters reconciliation and is not
+automatically duplicated. Reconciliation is a runtime outcome; the task
+coordinator decides whether a later task phase needs a return.
+
+Use the ordinary Teamwork Session commands for a deliberate one-shot or
+interactive discussion:
+
+```bash
+trellis teamwork run [name]
+trellis teamwork spawn <name> --agent <agent> --provider <provider>
+trellis teamwork send <name> --as <agent> --stdin
+trellis teamwork wait <name> --as <agent> --kind done,turn_finished
+trellis teamwork interrupt <name> --as <agent> --to <teammate> --stdin
+trellis teamwork kill <name> --as <teammate>
+```
+
+These commands operate a Teamwork Session and do not replace a frozen plan or
+create a second scheduler. Do not use them to bypass a rejected batch or to
+steer an active managed assignment manually.
+
+For a stalled process, inspect `teamwork list`, `teamwork messages --raw`, the
+provider log, and the host process state in that order. Use `kill` only when
+the process owner and current state are known. The runtime event log is the
+source of truth for coordination state; sidecar process files are diagnostic
+evidence.

package/dist/templates/common/bundled-skills/trellis-teamwork/references/teamwork-plan-construction.md

@@ -0,0 +1,78 @@
+# Teamwork plan construction
+
+The current phase coordinator constructs one Teamwork plan when a bounded
+teammate call is useful. The plan is a runtime input, not a second task plan.
+It records the task and phase context that produced it:
+
+```text
+task_id
+phase_id
+task_route_revision
+input_revision
+plan_summary
+coordination_mode
+```
+
+The plan also freezes the Teamwork Session, batch, deadline, protected targets,
+and ordered `assignments`. Each assignment has an `assignment_id`, brief path,
+role, provider, optional profile and model, scope, lens, source digest,
+acceptance criteria, and an explicit retry budget. The CLI validates the plan
+and the immutable brief before dispatch.
+
+Use the native task lifecycle for task status and acceptance. Teamwork records
+coordination facts and teammate reports; it does not write `current_phase_id`,
+task status, phase acceptance, or delivery readiness. Accepted reports and
+their evidence become task-owned acceptance inputs. Temporary plan, queue,
+attempt, and verification data may be removed when the batch ends according to
+the task's retention rule. The Teamwork Session itself has its own lifecycle.
+
+## When to construct a plan
+
+Use a plan for independent evidence, review, research, or verification with a
+clear report destination. Keep dependent steps, shared source edits, and work
+that requires peer conversation in the main task flow or a Teamwork Session.
+Use a single bounded teammate call for one self-contained question. Use a
+forum Teamwork Session when a topic needs durable threads and status history.
+
+Before dispatch, read the active task plan, current phase checkpoint, relevant
+specs, and the generic teammate role card. Freeze the input revision and route
+revision after the coordinator has selected the scope. If those values change,
+construct a new plan rather than mixing results from different task inputs.
+
+The public dispatch entry point is:
+
+```bash
+trellis teamwork batch <plan-path>
+```
+
+The command validates the plan, then the coordinator owns dispatch, waiting,
+report acceptance, and the terminal receipt. The coordinating agent does not
+manually refill slots or create a second retry loop.
+
+## Teamwork Session and forum commands
+
+Create and inspect the durable runtime object with the native CLI:
+
+```bash
+trellis teamwork create <name> --type chat|forum
+trellis teamwork list [--scope project|global] [--all]
+trellis teamwork messages <name> [--raw]
+trellis teamwork wait <name> --as <agent> --kind done,turn_finished
+trellis teamwork forum <name>
+trellis teamwork thread <name> <thread-key>
+trellis teamwork context list <name> [--thread <thread-key>]
+```
+
+Use `--context-file` and `--context-raw` for durable context. Use `--stdin` or
+`--text-file` for long message bodies. `--kind` selects runtime event kinds;
+it is not a user-defined tag. Read forum summaries and thread projections
+through the CLI before inspecting raw event storage.
+
+## Result handling
+
+The coordinator returns `ALL_ACCEPTED`, `SETTLED_WITH_FAILURE`, or
+`RECONCILIATION_REQUIRED`. A terminal receipt is a runtime fact. The main task
+then reviews reports against the phase contract, records durable evidence in
+the task-owned artifact, and uses the task's native acceptance gate before
+advancing. A formal session handoff is an independent, lower-priority
+continuity artifact and does not represent a phase transition.

package/dist/templates/common/commands/continue.md

@@ -1,59 +1,19 @@
 # Continue Current Task
 
-Resume work on the current task — pick up at the right phase/step in `.trellis/workflow.md`.
+Resume from the active Trellis task and its current phase. The task record and phase route are authoritative; do not infer the phase from artifact presence or session history.
 
----
+## Load current context
 
-## Step 1: Load Current Context
+    {{PYTHON_CMD}} ./.trellis/scripts/get_context.py
 
-```bash
-{{PYTHON_CMD}} ./.trellis/scripts/get_context.py
-```
+## Read the phase route
 
-Confirms: current task, git state, recent commits.
+    {{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase
 
-## Step 2: Load the Phase Index
+Follow the active phase breadcrumb to the matching bundled phase Skill and its workflow.md. Use the task CLI to inspect or change phase state. A resume does not itself accept an artifact, grant authorization, or move the task.
 
-```bash
-{{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase
-```
+Task lifecycle status and business phase are separate. A planning task may remain in Goal Exploration and Requirements Confirmation Phase, Decision Space Construction and Consolidation Phase, or Solution Design and Convergence Phase. `in_progress` marks authorized Task Implementation and Test Verification Phase; `completed` and `cancelled` are terminal lifecycle states. Delivery Review and On-Site Closeout Phase remains explicit.
 
-Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
+## Phase operations
 
-## Step 3: Decide Where You Are
-
-`get_context.py` shows the active task's `status` field. Route by `status` + artifact presence. This command replaces the user needing to remember the Trellis flow; it does not itself approve implementation.
-
-- `status=planning` + `task.json.meta.delivery_mode = "analysis_only"` → first confirm the task still satisfies the bounded evidence-only eligibility rule; then complete the PRD's evidence work, verify its acceptance criteria and no-change boundary, and archive directly. Do not run `task.py start`; a protected-target change requires a separate change-bearing task.
-- `status=planning` + no `prd.md` → **1.1** (load `trellis-brainstorm`)
-- `status=planning` + a recorded `decision-needed` or unsealed decision chain → return to the planning frontier and load `pennix-decision-gates` when independent material questions can be batched.
-- `status=in_progress` + a material unresolved decision → record the reason and run `task.py replan <task> "<reason>"`; do not ask a native question during implementation.
-- `status=planning` + `prd.md` only → decide whether the task is lightweight or complex. Lightweight can move to **1.4** review; complex returns to **1.1** to add `design.md` + `implement.md`.
-- `status=planning` + complex artifacts complete + sub-agent jsonl not curated (empty, or only a legacy `_example` placeholder row) → **1.3**
-- `status=planning` + required artifacts complete + required jsonl curated or inline mode → run the Planning Seal closure pass, then **1.4** (ask for start review; only run `task.py start` after user confirms)
-- `status=in_progress` + implementation not started → **2.1**
-- `status=in_progress` + implementation done, not yet checked → **2.2**
-- `status=in_progress` + check passed → **3.3** (spec update) → **3.4** (commit)
-- `status=completed` (rare; usually archived immediately) → archive flow
-
-Phase rules (full detail in `.trellis/workflow.md`):
-
-1. Run steps **in order** within a phase — `[required]` steps must not be skipped
-2. `[once]` steps are already done if the required output exists. `prd.md` alone can be enough only for lightweight tasks; complex tasks also need `design.md` and `implement.md`.
-3. You may go back to an earlier phase if discoveries require it
-
-## Step 4: Load the Specific Step
-
-Once you know which step to resume at:
-
-```bash
-{{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase --step <X.X> --platform {{CLI_FLAG}}
-```
-
-Follow the loaded instructions. After each `[required]` step completes, move to the next.
-
----
-
-## Reference
-
-Full workflow and detailed phase steps live in `.trellis/workflow.md`. This command is only an entry point — the canonical guidance is there.
+Use the native task CLI for phase artifact revisions, acceptance, evidence-backed skips, waiting, blocking, resuming, returning to an earlier phase, route changes, implementation authorization, completion, and cancellation. Read task.py help for current arguments. Do not create a second status record or use formal session handoff to resume task work.

package/dist/templates/common/commands/finish-work.md

@@ -1,68 +1,20 @@
 # Finish Work
 
-Wrap up the current session: archive the active task (and any other completed-but-unarchived tasks the user wants to clean up) and record the session journal. Code commits are NOT done here — those happen in workflow Phase 3.4 before you invoke this command.
+Record progress in the developer session journal when ending this session. This command does not change task status, phase state, or implementation authorization. Task completion and cancellation are handled during Delivery Review and On-Site Closeout Phase through Trellis CLI.
 
-For an eligible `task.json.meta.delivery_mode = "analysis_only"` task, reach this command directly from planning only after its PRD-defined evidence, acceptance criteria, and no-change boundary have been verified and its task artifacts have been committed. Do not run `task.py start`; a protected-target change needs a separate change-bearing task.
-
-## Step 1: Survey current state
-
-```bash
-{{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode record
-```
-
-This prints:
-
-- **My active tasks** — review whether any besides the current one are actually done (code merged, AC met) and should be archived this round.
-- **Git status** — quick visual on what's dirty.
-- **Recent commits** — you'll need their hashes in Step 4 for `--commit`.
-
-If `--mode record` surfaces other completed tasks not tied to the current session, surface them to the user with a one-shot confirmation: "These N tasks look done — archive them too in this round? [y/N]". Default is no; the current active task is always archived in Step 3 regardless.
-
-## Step 2: Sanity check — classify dirty paths
+## Review the current session
 
 Run:
 
-```bash
-git status --porcelain
-```
-
-Filter out paths under `.trellis/workspace/` and `.trellis/tasks/` — those are managed by `add_session.py` and `task.py archive` auto-commits and will appear dirty as part of this skill's own work.
-
-For each remaining dirty path, decide whether it belongs to **the current task** or to **other parallel work** (e.g., another terminal window editing the same repo). Heuristics:
-
-- Paths referenced in the current task's `prd.md` / `implement.jsonl` / `check.jsonl` → current task
-- Paths in code areas matching the task's stated scope, or that you remember editing this session → current task
-- Paths in unrelated areas you have no recollection of touching this session → other parallel work
-
-Then route:
-
-- **Any remaining path looks like current-task work** — bail out with:
-  > "Working tree has uncommitted code changes from this task: `<list>`. Return to workflow Phase 3.4 to commit them before running `{{CMD_REF:finish-work}}`."
-
-  Do NOT run `git commit` here. Do NOT prompt the user to commit. The user goes back to Phase 3.4 and the AI drives the batched commit there.
-- **All remaining paths look unrelated** (other parallel-window work) — report them once and continue to Step 3:
-  > "FYI, dirty files outside this task's scope — leaving them for the other window: `<list>`."
-- **Genuinely unsure** — ask the user once: "Are `<list>` this task's work I forgot to commit, or another window's? (commit / ignore)" — then route per their answer.
-
-## Step 3: Archive task(s)
-
-```bash
-{{PYTHON_CMD}} ./.trellis/scripts/task.py archive <task-name>
-```
-
-At minimum: the current active task (if any). Plus any extra tasks the user confirmed in Step 1. Each archive produces a `chore(task): archive ...` commit via the script's auto-commit.
-
-If there is no active task and the user did not confirm any cleanup archives, skip this step.
+    {{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode record
 
-## Step 4: Record session journal
+Review the current task, repository changes, and recent commits. Make the journal summary clear about completed work, remaining work, and blockers. A clean working tree or committed changes do not by themselves mean the task is complete.
 
-```bash
-{{PYTHON_CMD}} ./.trellis/scripts/add_session.py \
-  --title "Session Title" \
-  --commit "hash1,hash2" \
-  --summary "Brief summary"
-```
+## Record the journal
 
-Use the work-commit hashes produced in Phase 3.4 (visible in Step 1's `Recent commits` list, or via `git log --oneline`) for `--commit`. Do not include the archive commit hashes from Step 3. This produces a `chore: record journal` commit.
+    {{PYTHON_CMD}} ./.trellis/scripts/add_session.py \
+      --title "Session title" \
+      --commit "hash1,hash2" \
+      --summary "Progress, remaining work, and blockers"
 
-Final git log order: `<work commits from 3.4>` → `chore(task): archive ...` (one or more) → `chore: record journal`.
+Pass only commit hashes that belong to this session. Omit --commit when no relevant commit exists. Leave task state to Trellis CLI and formal session handoff to its separate, explicitly requested workflow.

package/dist/templates/common/commands/start.md

@@ -1,60 +1,30 @@
 # Start Session
 
-Initialize a Trellis-managed development session. This platform has no session-start hook, so manually load the equivalent compact context by following these steps.
+Load the current Trellis context and continue from the task record's current phase.
 
----
+## Load context
 
-## Step 1: Current state
-Identity, git status, current task, active tasks, journal location.
+    {{PYTHON_CMD}} ./.trellis/scripts/get_context.py
+    {{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase
+    {{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode packages
 
-```bash
-{{PYTHON_CMD}} ./.trellis/scripts/get_context.py
-```
+Read the applicable spec indexes before editing code. The active phase breadcrumb names the phase Skill and its workflow.md.
 
-If this output includes a line beginning `Trellis update available:`, copy the full line verbatim when summarizing session context. Do not shorten operational command hints.
+## Route the current request
 
-## Step 2: Workflow overview
-Compact Phase Index, request triage rules, planning artifact contract, and the step-detail command.
+- No active Trellis task: use the taskless route when the request is clear, low-risk, reversible, authorized, and immediately verifiable. Otherwise create the task with the user's consent and load `trellis-goal-exploration-and-requirements`.
+- Task with no initialized route: inspect its current requirements, choose the applicable ordered phases with evidence for omissions, then initialize the route through task.py phase init.
+- Goal Exploration and Requirements Confirmation Phase: load `trellis-goal-exploration-and-requirements`. Do not leave until the user confirms the current requirements artifact revision.
+- Decision Space Construction and Consolidation Phase: load `trellis-decision-space-construction-and-merging`.
+- Solution Design and Convergence Phase: load `trellis-solution-design-and-convergence`. An accepted implementation contract still requires separate implementation authorization.
+- Task Implementation and Test Verification Phase: load `trellis-task-implementation` and the target repository's applicable specs.
+- Delivery Review and On-Site Closeout Phase: load `trellis-delivery-review-and-closeout`.
 
-```bash
-{{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase
-```
+Task lifecycle status does not replace the business phase route. Use Trellis CLI to inspect or change task and phase state.
 
-Full guide in `.trellis/workflow.md` (read on demand).
+## Spec context
 
-## Step 3: Guideline indexes
-Discover packages + spec layers, then read each relevant index file.
+    {{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode packages
+    cat .trellis/spec/guides/index.md
 
-```bash
-{{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode packages
-cat .trellis/spec/guides/index.md
-cat .trellis/spec/<package>/<layer>/index.md   # for each relevant layer
-```
-
-Index files list the specific guideline docs to read when you actually start coding.
-
-## Step 4: Decide next action
-From Step 1 you know the current task and status. Check the task directory:
-
-- **Active task with `task.json.meta.delivery_mode = "analysis_only"`** → keep `planning`, complete the PRD's bounded evidence work, then verify the no-change boundary, commit task artifacts, and archive directly. Do not run `task.py start`; any protected-target change needs a separate change-bearing task.
-- **Active task status `planning` + no `prd.md`** → Phase 1.1. Load the `trellis-brainstorm` skill.
-- **Active task status `planning` + `prd.md` exists** → stay in Phase 1. Lightweight tasks can be PRD-only; complex tasks need `design.md` + `implement.md`. Load the relevant Phase 1 step detail before `task.py start`.
-- **Active task status `in_progress`** → Phase 2 step 2.1. Load the step detail:
-  ```bash
-  {{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase --step 2.1 --platform {{CLI_FLAG}}
-  ```
-- **No active task** → classify first. For simple conversation / small task, ask only whether this turn should create a Trellis task. For complex work, ask whether you may create a Trellis task and enter planning. If the user says no, skip Trellis for this session.
-
----
-
-## Skill routing (quick reference)
-
-| User intent | Skill |
-|---|---|
-| New feature / unclear requirements | `trellis-brainstorm` |
-| About to write code | `trellis-before-dev` |
-| Done coding / quality check | `trellis-check` |
-| Stuck / fixed same bug multiple times | `trellis-break-loop` |
-| Learned something worth capturing | `trellis-update-spec` |
-
-Full rules + anti-rationalization table in `.trellis/workflow.md`.
+Read the package and layer indexes relevant to the requested changes, then follow their references.