@pennixrv/trellis 0.7.0-beta.8 → 0.7.1

package/dist/templates/copilot/prompts/brainstorm.prompt.md

@@ -1,156 +1,13 @@
 ---
-description: "Guide requirements discovery for a Trellis task after task-creation consent."
+description: "Route a Trellis task through its current phase."
 ---
 
-# Trellis Brainstorm
+# Requirements and phase routing
 
-## Non-Negotiable Planning Contract
+Use `.trellis/workflow.md` and the current workflow-state breadcrumb as the authority for the task's phase. Task lifecycle status and artifact presence do not identify the business phase.
 
-A request to build, implement, fix, refactor, or "go ahead" is not approval to leave planning. Task-creation consent is also not implementation approval.
+- No active task: if the request needs a Trellis task, obtain task-creation consent, create it, and load `trellis-goal-exploration-and-requirements`. Handle eligible low-risk, authorized work through the taskless route.
+- Task without an initialized phase route: use `trellis-goal-exploration-and-requirements` to align the requirements; initialize the applicable ordered route only after the user confirms the current requirements baseline.
+- Task with an active phase: load the Skill matching that phase. This shortcut must not reset or bypass the current phase.
 
-For every non-trivial task, the user must respond at least once after the initial request before implementation begins. If no clarification is needed, that response must approve the final planning summary described below.
-
-While any user-owned product, scope, UX, compatibility, risk, or acceptance decision remains unresolved, keep the task in planning. First inventory evidence and decision dependencies. If at least two independent material decisions remain and `pennix-decision-gates` is available, delegate one bounded batch of up to three frontier questions; otherwise ask the single highest-value question. Do not edit product code, dispatch implementation, or run `task.py start` until the decision chain is sealed.
-
-## Non-Negotiable Evidence Rule
-
-If a question can be answered by exploring the codebase, explore the codebase instead.
-
-This is mandatory. Before asking the user a question, first check whether the answer is already available in code, tests, configs, docs, existing specs, or task history.
-
-Do not ask the user to confirm facts that the repository can answer. Ask only for product intent, preference, scope, risk tolerance, acceptance behavior, or decisions that remain ambiguous after inspection.
-
-Repository evidence establishes current behavior and technical constraints. The user's intended behavior, feature scope boundaries, and UX preferences are never answerable by repository evidence alone, even when an existing pattern exists; existing patterns are options and recommendation evidence, not decisions.
-
----
-
-Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
-
-## Preconditions
-
-Use this skill only after task-creation consent has been given and the user is ready to enter Trellis planning.
-
-If no task exists yet, create one:
-
-```bash
-TASK_DIR=$({{PYTHON_CMD}} ./.trellis/scripts/task.py create "<short task title>" --description "<one-line summary>" --slug <slug>)
-```
-
-Use a concise title from the user's request. Both the title and `--description` must be non-empty — `create` rejects blanks, and a record with either one empty is refused at archive. Use a slug without a date prefix. `task.py create` adds the `MM-DD-` directory prefix automatically.
-
-`task.py create` creates the default `prd.md`. Update that file with the current understanding before asking follow-up questions.
-
-## Planning Flow
-
-1. Capture the user's request and initial known facts in `prd.md`.
-2. Inspect available evidence before asking questions:
-   - code, tests, fixtures, and configs
-   - README files, docs, existing specs, and domain notes
-   - related Trellis tasks, research files, and session history when present
-3. Separate what you found into:
-   - confirmed facts
-   - product intent still needed from the user
-   - scope or risk decisions still needed from the user
-   - likely out-of-scope items
-4. If user-owned decisions remain, calculate the independent frontier. Use `pennix-decision-gates` for a bounded batch when two or more independent material decisions are ready; otherwise ask the single highest-value question. Include recommendation and trade-off, then stop the turn for native input.
-5. After each answer batch, update `prd.md`, record the selected decisions, recheck evidence and conflicts, and repeat from step 2. Do not create a second Trellis lifecycle for the same decision chain.
-6. When no user-owned decision remains, create or update `design.md` and `implement.md` for complex tasks.
-7. Run the requirement convergence gate, then the PRD convergence pass.
-8. Present the final planning summary and stop. Do not run `task.py start` or edit product code in the same turn.
-9. Only a subsequent user message that explicitly approves the latest planning summary authorizes `task.py start` and implementation. If implementation reveals a material unresolved decision, record `decision-needed`, run `task.py replan <task> "<reason>"`, and return through this planning flow; do not open a popup during implementation.
-
-Do not invent a project-specific product/spec hierarchy. If the repository already has product, domain, or spec docs, use them. If it does not, proceed with the evidence that exists.
-
-## Question Rules
-
-Ask one bounded batch per message: include up to three independent material frontier questions. Ask exactly one question only when it is the sole remaining material decision or later decisions depend on its answer.
-
-Each question must include:
-
-- the decision needed
-- why the answer matters
-- your recommended answer
-- the trade-off if the user chooses differently
-
-Do not ask process questions such as whether to search, inspect files, or continue brainstorming. Do the evidence work directly. Ask the user only when the remaining issue is a product decision, preference, scope boundary, or risk tolerance choice.
-
-Recommendations are not default selections. Never choose a recommended product decision on the user's behalf merely because the user asked for implementation.
-
-Do not manufacture clarification questions when the request and repository evidence already resolve every decision. In that case, proceed directly to the final planning summary, which still requires a subsequent explicit approval.
-
-The final review is a required phase-transition gate, not a prohibited process question. Task-creation consent, the initial implementation request, and approval given before the latest final summary do not satisfy this gate.
-
-## Requirement Convergence Gate
-
-Before final review, verify all of the following:
-
-- the user outcome and product value are explicit
-- in-scope and out-of-scope behavior are explicit
-- acceptance criteria describe observable outcomes
-- user-owned product, scope, UX, compatibility, and risk decisions are resolved
-- blocking open questions are empty
-- technical unknowns are researched or explicitly deferred without changing MVP behavior
-
-Lightweight tasks may omit `design.md` and `implement.md`; they may not skip evidence inspection, requirement convergence, final review, or fresh implementation approval.
-
-The final planning summary must show Goal, In Scope, Out of Scope, Acceptance Criteria, Key Decisions, relevant Risks or Deferred Items, and artifact status.
-
-## Artifact Rules
-
-`prd.md` records requirements and acceptance:
-
-- goal and user value
-- confirmed facts
-- requirements
-- acceptance criteria
-- out of scope
-- open questions that still block planning
-
-`design.md` records technical design for complex tasks:
-
-- architecture and boundaries
-- data flow and contracts
-- compatibility and migration notes
-- important trade-offs
-- operational or rollback considerations
-
-`implement.md` records execution planning for complex tasks:
-
-- ordered implementation checklist
-- validation commands
-- risky files or rollback points
-- follow-up checks before `task.py start`
-
-Lightweight tasks may have only `prd.md`. Complex tasks must have `prd.md`, `design.md`, and `implement.md` before `task.py start`.
-
-`implement.md` is not a replacement for `implement.jsonl`. On sub-agent-dispatch workflows, `implement.jsonl` and `check.jsonl` must each contain at least one real spec/research entry before `task.py start`; an empty manifest, or one holding only a legacy `_example` placeholder row, does not count. Inline workflows skip this JSONL gate because Phase 2 loads context through `trellis-before-dev`.
-
-## PRD Convergence Pass
-
-Before declaring planning ready or running `task.py start`, rewrite `prd.md` once against the final structure described in the artifact rules above. This is not optional cleanup; it is the final planning gate.
-
-The pass must be lossless:
-
-- Collapse repeated facts into one authoritative section.
-- Fold temporary brainstorm sections such as `What I already know`, `Assumptions`, and resolved `Open Questions` into Goal, Background, Requirements, Technical Notes, or Acceptance Criteria.
-- Remove resolved open questions instead of leaving empty or already-answered sections.
-- Merge parallel bug and requirement lists when they describe the same work; keep each defect's severity, evidence, and file:line anchors on the owning requirement.
-- Preserve every file:line anchor, decision, constraint, requirement ID, and acceptance-criteria mapping.
-- Do not proceed to final review while any blocking open question remains.
-
-After the pass, read `prd.md` top to bottom and verify that no fact is repeated across sections unless the repetition adds new information.
-
-## Quality Bar
-
-Before declaring planning ready:
-
-- `prd.md` contains testable acceptance criteria.
-- `prd.md` has passed the PRD convergence pass: no unresolved temporary brainstorm sections, no duplicate facts across sections, and no lost anchors, decisions, or acceptance mappings.
-- Repository-answerable questions have already been answered through inspection.
-- Blocking open questions are empty.
-- Complex tasks have `design.md` and `implement.md`.
-- Sub-agent-dispatch tasks have real curated entries in both `implement.jsonl` and `check.jsonl`; seed-only manifests are not ready.
-- The latest final planning summary has been presented to the user.
-- In a subsequent message, the user explicitly approved that summary for implementation.
-
-Do not start implementation merely because the user originally asked for implementation.
+`task.py start` enters implementation only after the accepted Solution Design and Convergence Phase implementation contract and separate implementation authorization. The phase Skills define their own activities and acceptance conditions; do not impose a fixed number of questions, alternatives, or planning documents.

package/dist/templates/copilot/prompts/finish-work.prompt.md

@@ -1,99 +1,22 @@
 ---
-description: "Trellis Copilot prompt: Finish Work — survey + archive task + record session journal"
+description: "Record progress in the Trellis developer session journal."
 ---
 
 # 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 prompt.
+Record progress in the developer session journal when ending this session. This prompt 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.
 
-**Timing**: After Phase 3.4 (Commit changes) — when the working tree is already clean.
+## Review the current session
 
----
-
-## Step 1: Survey current state
-
-```bash
-python3 ./.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
-
-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 prompt'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 `/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.
+    python3 ./.trellis/scripts/get_context.py --mode record
 
-## Step 3: Archive task(s)
+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
-python3 ./.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.
-
-## Step 4: Record session journal
-
-```bash
-python3 ./.trellis/scripts/add_session.py \
-  --title "Session Title" \
-  --commit "hash1,hash2" \
-  --summary "Brief summary"
-```
-
-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.
-
-Final git log order: `<work commits from 3.4>` → `chore(task): archive ...` (one or more) → `chore: record journal`.
-
----
-
-## Relationship to Other Commands
-
-```
-Development Flow (workflow.md Phase 3):
-  3.2 Debug retrospective (on demand)
-  3.3 Spec update
-  3.4 Commit changes  -> AI drafts batched commits, user confirms
-  3.5 Wrap-up         -> /finish-work (this prompt: survey + archive + journal)
-  (3.1 was folded into 2.2 + 3.4 — see workflow.md "Phase 3: Finish" note)
-
-Debug Flow:
-  Hit bug -> Fix -> /break-loop -> Knowledge capture
-```
-
-- `/finish-work` — survey + archive + record session (this prompt)
-- `/break-loop` — deep analysis after debugging
-
----
+## Record the journal
 
-## Core Principle
+    python3 ./.trellis/scripts/add_session.py \
+      --title "Session title" \
+      --commit "hash1,hash2" \
+      --summary "Progress, remaining work, and blockers"
 
-> **Finish-work is pure bookkeeping.** Code is already committed before this runs. If the working tree is dirty, this prompt refuses to proceed.
+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/copilot/prompts/record-session.prompt.md

@@ -2,28 +2,21 @@
 description: "Trellis Copilot prompt: Method 1: Simple parameters"
 ---
 
-[!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code.
+[!] **Prerequisite**: Record verified progress and the actual commit references for this session. Do not imply that the task is complete merely because work was committed.
 
-**Do NOT run `git commit` directly** — the scripts below handle their own commits for `.trellis/` metadata. You only need to read git history (`git log`, `git status`, `git diff`) and run the Python scripts.
+Task status and phase state are changed only through Trellis CLI. This prompt records the developer session journal; it does not archive, complete, or cancel tasks.
 
 ---
 
 ## Record Work Progress
 
-### Step 1: Get Context & Check Tasks
+### Step 1: Get Context
 
 ```bash
 python3 ./.trellis/scripts/get_context.py --mode record
 ```
 
-[!] Archive tasks whose work is **actually done** — judge by work status, not the `status` field in task.json:
-- Code committed? → Archive it (don't wait for PR)
-- All acceptance criteria met? → Archive it
-- Don't skip archiving just because `status` still says `planning` or `in_progress`
-
-```bash
-python3 ./.trellis/scripts/task.py archive <task-name>
-```
+Review the current phase, changed files, recent commits, remaining work, and blockers. Use the Delivery Review and On-Site Closeout Phase Skill with the Trellis CLI to complete or cancel a task when its acceptance conditions are met.
 
 ### Step 2: One-Click Add Session
 
@@ -62,5 +55,4 @@ EOF
 |---------|---------|
 | `python3 ./.trellis/scripts/get_context.py --mode record` | Get context for record-session |
 | `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended, branch auto-complete)** |
-| `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task (auto-commits) |
 | `python3 ./.trellis/scripts/task.py list` | List active tasks |

package/dist/templates/copilot/prompts/start.prompt.md

@@ -4,7 +4,7 @@ description: "Trellis Copilot prompt: Start Session"
 
 # Start Session
 
-Initialize a Trellis-managed development session. This platform has no session-start hook, so manually load the equivalent context by following these steps (each one mirrors a section the hook would otherwise inject).
+Use this prompt to inspect or refresh Trellis context. Copilot also supplies SessionStart context and a per-turn workflow-state breadcrumb through its hooks.
 
 ---
 
@@ -38,15 +38,13 @@ 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:
+Use the current `<workflow-state>` breadcrumb to identify the business phase; task lifecycle status (`planning` or `in_progress`) and artifact presence do not identify that phase. If the breadcrumb is missing or stale, inspect the task with `task.py phase show <task>` and follow the matching phase Skill in `.trellis/workflow.md`.
 
-- **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.
+- **An active phase is recorded** → continue that phase and load its matching Skill.
+- **The task has no initialized phase route** → load `trellis-goal-exploration-and-requirements`, align and obtain the user's confirmation of the current requirements baseline, then initialize the applicable ordered route with `task.py phase init`.
+- **No active task** → classify first. Handle a clear, low-risk, reversible, authorized, immediately verifiable request directly; otherwise ask for task-creation consent and begin with `trellis-goal-exploration-and-requirements`.
+
+`task.py start` enters implementation only after an accepted implementation contract from Solution Design and Convergence Phase and separate implementation authorization.
 
 ---
 
@@ -54,7 +52,11 @@ From Step 1 you know the current task and status. Check the task directory:
 
 | User intent | Skill |
 |---|---|
-| New feature / unclear requirements | `trellis-brainstorm` |
+| Goal and requirements | `trellis-goal-exploration-and-requirements` |
+| Decision alternatives | `trellis-decision-space-construction-and-merging` |
+| Solution design | `trellis-solution-design-and-convergence` |
+| Implementation | `trellis-task-implementation` |
+| Delivery review | `trellis-delivery-review-and-closeout` |
 | About to write code | `trellis-before-dev` |
 | Done coding / quality check | `trellis-check` |
 | Stuck / fixed same bug multiple times | `trellis-break-loop` |

package/dist/templates/dsh/DSH.md

@@ -27,8 +27,8 @@ In dsh:
 2. The main session dispatches `trellis-agent-research`,
    `trellis-agent-implement`, and `trellis-agent-check` through DSH's native
    `subagent` tool. Each child loads exactly one matching role skill.
-3. Finish through `trellis-finish-work`, which preserves the required order:
-   commit, archive, then journal.
+3. Use Delivery Review and On-Site Closeout Phase to review and close the task. `trellis-finish-work` records
+   session progress separately and does not change task lifecycle state.
 
 ## Companion plugin fallback contract
 

package/dist/templates/kiro/agents/trellis.json

@@ -1,7 +1,7 @@
 {
   "name": "trellis",
-  "description": "Trellis workflow main agent. Drives the Trellis development workflow: reads .trellis/workflow.md, classifies each turn, and routes work through plan / implement / check phases. Use as the default Kiro agent for projects that run Trellis.",
-  "prompt": "# Trellis Workflow Agent\n\nYou are the main session agent for a project that uses the Trellis workflow.\n\n## On Every Turn\n\nA `userPromptSubmit` hook injects a `<workflow-state>` breadcrumb each turn telling you the active task and its current phase. An `agentSpawn` hook injects a `<session-context>` overview when this agent starts. Trust those injections to orient yourself — do not re-derive context from scratch.\n\n## How to Work\n\n1. **Follow the workflow.** `.trellis/workflow.md` is the single source of truth for phases and steps. It is also attached as a resource for this agent. Read it (or the injected Phase Index) and follow the matching phase.\n2. **Resolve the active task** with `python3 ./.trellis/scripts/task.py current --source` when the breadcrumb is missing or stale.\n3. **Classify the turn** before acting: simple conversation, small edit, or a complex task that needs a Trellis task directory + planning. Do not create a task for trivial turns.\n4. **Plan before implementing.** For complex work, write `prd.md` (and `design.md` / `implement.md` when warranted) and get the user's confirmation before entering implementation.\n5. **Load task context in order** for implementation/check: jsonl entries -> `prd.md` -> `design.md` (if present) -> `implement.md` (if present).\n6. **Verify** with the project's lint / type-check / test commands before declaring work done.\n\n## Constraints\n\n- Do NOT run `git commit` / `git push` / `git merge` unless the user explicitly asks.\n- Keep changes surgical and scoped to the request.\n- Discover guidelines on demand: `python3 ./.trellis/scripts/get_context.py --mode packages`.\n",
+  "description": "Trellis workflow main agent. Follows the current task route and matching Skills, or uses the taskless route when eligible.",
+  "prompt": "# Trellis Workflow Agent\n\nYou are the main session agent for a project that uses the Trellis workflow.\n\n## On Every Turn\n\nA `userPromptSubmit` hook injects a `<workflow-state>` breadcrumb each turn with the active task and its current phase. An `agentSpawn` hook injects a `<session-context>` overview when this agent starts. Use these to orient yourself; resolve missing or stale state through Trellis CLI.\n\n## How to Work\n\n1. Follow `.trellis/workflow.md` and the matching phase Skill. The workflow and its task route define the business phase; task lifecycle status and artifact presence do not.\n2. If the breadcrumb is missing or stale, inspect the active task with `python3 ./.trellis/scripts/task.py current --json` and `python3 ./.trellis/scripts/task.py phase show <task>`.\n3. With no active task, use the taskless route only when `.trellis/workflow.md` permits it; otherwise create the task and establish its baseline through Goal Exploration and Requirements Confirmation Phase.\n4. The Goal Exploration and Requirements Confirmation Phase requires the user's confirmation of the current requirements revision. Before Task Implementation and Test Verification Phase, both an accepted `implementation_contract` from Solution Design and Convergence Phase and separate implementation authorization are required. Delivery Review and On-Site Closeout Phase governs delivery acceptance, task completion, and cancellation.\n5. Use task artifacts and context manifests as required by the current route and any dispatched agent; do not require a fixed set of planning documents based only on task complexity.\n6. Verify with project checks appropriate to the changes before reporting completion.\n\n## Constraints\n\n- Do NOT run `git commit` / `git push` / `git merge` unless the user explicitly asks.\n- Keep changes scoped to the request.\n- Discover guidelines on demand: `python3 ./.trellis/scripts/get_context.py --mode packages`.\n",
   "tools": [
     "read",
     "write",

package/dist/templates/markdown/agents.md

@@ -1,9 +1,20 @@
 <!-- TRELLIS:START -->
-# Trellis
+# Trellis Instructions
 
-Follow `.trellis/workflow.md`; read the applicable `.trellis/spec/` guidance before editing code, and keep task facts in `.trellis/tasks/`. Project-scoped helpers live in `.agents/skills/`.
+These instructions are for AI assistants working in this project.
 
-When a live Trellis Channel wait returns a host continuation, resume only that continuation until it resolves, times out, or errors. Do not run another host action meanwhile, including another wait, shell command, or status/message query; use diagnostics only on demand after it returns.
+This project is managed by Trellis. The working knowledge you need lives under `.trellis/`:
+
+- `.trellis/workflow.md` — development phases, when to create tasks, skill routing
+- `.trellis/spec/` — package- and layer-scoped coding guidelines (read before writing code in a given layer)
+- `.trellis/workspace/` — per-developer journals and session traces
+- `.trellis/tasks/` — task records and their planning, implementation, and review artifacts
+
+If a Trellis command is available on your platform (e.g. `/trellis:finish-work`, `/trellis:continue`), prefer it over manual steps. Not every platform exposes every command.
+
+If you're using Codex or another agent-capable tool, additional project-scoped helpers may live in:
+- `.agents/skills/` — reusable Trellis skills
+- `.codex/agents/` — optional custom subagents
 
 Managed by Trellis. Edits outside this block are preserved; edits inside may be overwritten by a future `trellis update`.
 

package/dist/templates/markdown/spec/guides/cross-layer-thinking-guide.md.txt

@@ -216,7 +216,7 @@ When a CLI auto-detects a mode by probing a remote resource (e.g., checking if `
 
 **Real-world example**: Custom registry flow had 8 bugs across 3 review rounds: (1) probe only ran in interactive mode, (2) transient errors fell through to wrong mode, (3) giget URI had `#ref` in wrong position, (4) prefetched templates leaked across source switches, (5) `--template` shortcut bypassed probe but `downloadTemplateById` internally used catch-all `fetchTemplateIndex`, turning timeouts into "Template not found".
 
-**Real-world example**: Agent-session update hints fetched npm `latest` metadata with `response.read(4096)` and then parsed it as complete JSON. The `@pennixrv/trellis` package metadata exceeded 4 KB, so the JSON was truncated, parse failed silently, and the first session injection showed no update hint. Fix: read the complete response before parsing, and add a regression where `version` is followed by an 8 KB metadata tail.
+**Real-world example**: Agent-session update hints fetched npm `latest` metadata with `response.read(4096)` and then parsed it as complete JSON. The `@mindfoldhq/trellis` package metadata exceeded 4 KB, so the JSON was truncated, parse failed silently, and the first session injection showed no update hint. Fix: read the complete response before parsing, and add a regression where `version` is followed by an 8 KB metadata tail.
 
 ---
 
@@ -284,7 +284,7 @@ When a CLI auto-detects a mode by probing a remote resource (e.g., checking if `
 
 **Real-world example**: Custom registry flow had 8 bugs across 3 review rounds: (1) probe only ran in interactive mode, (2) transient errors fell through to wrong mode, (3) giget URI had `#ref` in wrong position, (4) prefetched templates leaked across source switches, (5) `--template` shortcut bypassed probe but `downloadTemplateById` internally used catch-all `fetchTemplateIndex`, turning timeouts into "Template not found".
 
-**Real-world example**: Agent-session update hints fetched npm `latest` metadata with `response.read(4096)` and then parsed it as complete JSON. The `@pennixrv/trellis` package metadata exceeded 4 KB, so the JSON was truncated, parse failed silently, and the first session injection showed no update hint. Fix: read the complete response before parsing, and add a regression where `version` is followed by an 8 KB metadata tail.
+**Real-world example**: Agent-session update hints fetched npm `latest` metadata with `response.read(4096)` and then parsed it as complete JSON. The `@mindfoldhq/trellis` package metadata exceeded 4 KB, so the JSON was truncated, parse failed silently, and the first session injection showed no update hint. Fix: read the complete response before parsing, and add a regression where `version` is followed by an 8 KB metadata tail.
 
 ---
 
@@ -319,9 +319,10 @@ CLI input → event writer → events.jsonl → reader → filter → reducer
 - [ ] Add at least one regression that proves history replay and live filtering
       use the same filter model
 
-**Real-world example**: Thread channels added `kind: "thread"`, `description`,
-`context`, labels, and `lastSeq`. The first implementation replayed thread
-state correctly, but several commands still re-parsed event payload fields with
-local casts. The fix was to make the core event layer own `ThreadChannelEvent`
-and `isThreadEvent`, make `reduceChannelMetadata` the only channel metadata
-projection, and make `reduceThreads` the only thread replay reducer.
+**Real-world example**: Forum Teamwork Sessions added thread events with
+`description`, `context`, labels, and sequence tracking. The first
+implementation replayed thread state correctly, but several commands still
+re-parsed event payload fields with local casts. The fix was to make Core own
+`ThreadTeamworkEvent` and `isThreadEvent`, use
+`reduceTeamworkSessionMetadata` for session metadata, and use `reduceThreads`
+for thread replay.

package/dist/templates/markdown/spec/guides/cross-platform-thinking-guide.md.txt

@@ -600,7 +600,7 @@ When release notes or docs claim an asset is bundled, installed automatically, o
 included with Trellis, verify the whole distribution path:
 
 - [ ] Source file exists in the branch being tagged, not only in another branch,
-  docs submodule, or marketplace tree.
+  docs submodule, or external Marketplace repository.
 - [ ] `pnpm build` copies the asset into `dist/templates/**`.
 - [ ] `npm pack --dry-run --json` includes the expected `dist/**` path.
 - [ ] The built binary installs the asset in a fresh temp repository.

package/dist/templates/markdown/workspace-index.md

@@ -17,7 +17,6 @@ workspace/
     |-- index.md          # Personal index with session history
     |-- tasks/         # Task files
     |   |-- *.json        # Active tasks
-    |   +-- archive/      # Archived tasks by month
     +-- journal-N.md     # Journal files (sequential: 1, 2, 3...)
 ```
 

package/dist/templates/omp/extensions/trellis/index.ts.txt

@@ -59,7 +59,7 @@ function isInsideRoot(root: string, candidate: string): boolean {
 }
 
 // ---------------------------------------------------------------------------
-// Trusted context roots (mirrors packages/cli/src/commands/channel/context-trust.ts;
+// Trusted context roots (mirrors packages/cli/src/commands/teamwork/context-trust.ts;
 // standalone copy since templates don't import from the CLI package).
 // ---------------------------------------------------------------------------
 
@@ -69,7 +69,7 @@ function stripTrustValue(s: string): string {
    return s.trim().replace(/\s*#.*$/, "").trim().replace(/^['"]|['"]$/g, "");
 }
 
-function parseChannelTrustSection(content: string): { trustedDirs: string[]; autoTrustSymlinks?: boolean } {
+function parseTeamworkTrustSection(content: string): { trustedDirs: string[]; autoTrustSymlinks?: boolean } {
    const lines = content.split("\n");
    const trustedDirs: string[] = [];
    let autoTrustSymlinks: boolean | undefined;
@@ -115,7 +115,7 @@ function parseChannelTrustSection(content: string): { trustedDirs: string[]; aut
          const val = stripTrustValue(boolMatch[1]!).toLowerCase();
          if (val === "false") autoTrustSymlinks = false;
          else if (val === "true") autoTrustSymlinks = true;
-         else process.stderr.write(`[channel] channel.auto_trust_trellis_symlinks: invalid value '${val}', ignoring\n`);
+         else process.stderr.write(`[teamwork] teamwork.auto_trust_trellis_symlinks: invalid value '${val}', ignoring\n`);
          continue;
       }
    }
@@ -128,7 +128,7 @@ function resolveTrustedRoots(projectRoot: string): string[] {
    let config: { trustedDirs: string[]; autoTrustSymlinks?: boolean } = { trustedDirs: [] };
    if (existsSync(configPath)) {
       try {
-         config = parseChannelTrustSection(readFileSync(configPath, "utf-8"));
+         config = parseTeamworkTrustSection(readFileSync(configPath, "utf-8"));
       } catch {
          // ignore
       }
@@ -202,9 +202,9 @@ function displayProjectPath(projectRoot: string, filePath: string, taskDir?: str
 function resolveActiveTaskStatus(
    projectRoot: string,
    contextKey: string | null,
-): { status: string; taskDir: string | null; taskTitle: string | null } {
+): { status: string; phaseStatus: string | null; taskDir: string | null; taskTitle: string | null } {
    const sessionsDir = join(projectRoot, ".trellis", ".runtime", "sessions");
-   if (!existsSync(sessionsDir)) return { status: "no_task", taskDir: null, taskTitle: null };
+   if (!existsSync(sessionsDir)) return { status: "no_task", phaseStatus: null, taskDir: null, taskTitle: null };
 
    // --- 通过 context key 解析 session 文件 ---
    let sessionFilePath: string | null = null;
@@ -214,7 +214,7 @@ function resolveActiveTaskStatus(
       if (existsSync(candidate)) {
          sessionFilePath = candidate;
       } else {
-         return { status: "no_task", taskDir: null, taskTitle: null };
+         return { status: "no_task", phaseStatus: null, taskDir: null, taskTitle: null };
       }
    } else {
       // No identity: use single-session fallback only when there is exactly one session file.
@@ -222,12 +222,12 @@ function resolveActiveTaskStatus(
       try {
          sessionFiles = readdirSync(sessionsDir).filter((f) => f.endsWith(".json"));
       } catch {
-         return { status: "no_task", taskDir: null, taskTitle: null };
+         return { status: "no_task", phaseStatus: null, taskDir: null, taskTitle: null };
       }
       if (sessionFiles.length === 1) {
          sessionFilePath = join(sessionsDir, sessionFiles[0]);
       } else {
-         return { status: "no_task", taskDir: null, taskTitle: null };
+         return { status: "no_task", phaseStatus: null, taskDir: null, taskTitle: null };
       }
    }
 
@@ -236,12 +236,12 @@ function resolveActiveTaskStatus(
    try {
       sessionData = JSON.parse(readFileSync(sessionFilePath, "utf-8"));
    } catch {
-      return { status: "no_task", taskDir: null, taskTitle: null };
+      return { status: "no_task", phaseStatus: null, taskDir: null, taskTitle: null };
    }
 
    const currentTask = sessionData.current_task;
    if (typeof currentTask !== "string" || !currentTask)
-      return { status: "no_task", taskDir: null, taskTitle: null };
+      return { status: "no_task", phaseStatus: null, taskDir: null, taskTitle: null };
 
    // Same jail the jsonl-referenced files already go through below. `task.py`
    // now refuses to store a ref that leaves the project, but a session file
@@ -249,19 +249,30 @@ function resolveActiveTaskStatus(
    // rewrite session files — so a poisoned pointer outlives the upgrade that
    // closed the writer.
    const taskDir = resolveProjectFile(projectRoot, currentTask, resolveTrustedRoots(projectRoot));
-   if (!taskDir) return { status: "no_task", taskDir: null, taskTitle: null };
+   if (!taskDir) return { status: "no_task", phaseStatus: null, taskDir: null, taskTitle: null };
    const taskJsonPath = join(taskDir, "task.json");
-   if (!existsSync(taskJsonPath)) return { status: "no_task", taskDir: null, taskTitle: null };
+   if (!existsSync(taskJsonPath)) return { status: "no_task", phaseStatus: null, taskDir: null, taskTitle: null };
 
    let taskData: Record<string, unknown>;
    try {
       taskData = JSON.parse(readFileSync(taskJsonPath, "utf-8"));
    } catch {
-      return { status: "no_task", taskDir: null, taskTitle: null };
+      return { status: "no_task", phaseStatus: null, taskDir: null, taskTitle: null };
    }
 
+   const taskMeta = taskData.meta;
+   const phaseWorkflow = taskMeta && typeof taskMeta === "object" && !Array.isArray(taskMeta)
+      ? (taskMeta as Record<string, unknown>).task_workflow as Record<string, unknown> | undefined
+      : undefined;
+   const route = phaseWorkflow?.phase_ids;
+   const phaseId = phaseWorkflow?.current_phase_id || (Array.isArray(route) ? route[route.length - 1] : undefined);
+   const phaseMap = phaseWorkflow?.phases;
+   const phase = typeof phaseId === "string" && phaseMap && typeof phaseMap === "object" && !Array.isArray(phaseMap)
+      ? (phaseMap as Record<string, Record<string, unknown>>)[phaseId]
+      : null;
    return {
-      status: typeof taskData.status === "string" ? taskData.status : "planning",
+      status: typeof phaseId === "string" && phase ? phaseId : (typeof taskData.status === "string" ? taskData.status : "planning"),
+      phaseStatus: typeof phase?.status === "string" ? phase.status : null,
       taskDir,
       taskTitle: typeof taskData.title === "string" ? taskData.title : null,
    };
@@ -818,7 +829,7 @@ class TurnContextCache {
          return { workflowMsg: this.workflowMsg };
       }
 
-      const { status } = resolveActiveTaskStatus(projectRoot, contextKey);
+      const { status, phaseStatus } = resolveActiveTaskStatus(projectRoot, contextKey);
 
       const workflowPath = join(projectRoot, ".trellis", "workflow.md");
       let workflowMd = "";
@@ -839,7 +850,7 @@ class TurnContextCache {
       // When skip keyword is present, skip workflow state injection this turn
       this.workflowMsg = this.skipThisTurn
          ? ""
-         : `<workflow-state>\n${workflowBody}\n</workflow-state>\n\n<session-overview>\n${SESSION_OVERVIEW_TEXT}\n</session-overview>`;
+         : `<workflow-state>\n${phaseStatus ? `Phase: ${status} (${phaseStatus})\n` : ""}${workflowBody}\n</workflow-state>\n\n<session-overview>\n${SESSION_OVERVIEW_TEXT}\n</session-overview>`;
 
       this.key = cacheKey;
       this.timestamp = now;