@pennixrv/trellis 0.7.0-beta.9 → 0.7.1-beta.1

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

@@ -1,20 +1,20 @@
 ---
 name: trellis-meta
-description: "Understand and customize the local Trellis architecture inside a user project. Use when modifying .trellis plus platform hooks, settings, agents, skills, commands, prompts, workflows, the channel runtime (trellis channel), bundled runtime agents under .trellis/agents/, selectable workflow templates, registry-backed spec refresh, cross-session memory (trellis mem) generated by trellis init, or AI-facing bundled skills and their auto-dispatch flow."
+description: "Understand and customize the local Trellis architecture inside a user project. Use when modifying .trellis plus platform hooks, settings, agents, skills, commands, prompts, workflows, the Teamwork runtime (trellis teamwork), bundled runtime agents under .trellis/agents/, selectable workflow templates, registry-backed spec refresh, cross-session memory (trellis mem) generated by trellis init, or bundled skills and their auto-dispatch flow."
 ---
 
 # Trellis Meta
 
 This skill is for local Trellis users who have already run `trellis init` in a project. After reading it, an AI should understand the Trellis architecture, operating model, and customization entry points inside that user project, then modify the generated `.trellis/` and platform directory files according to the user's request.
 
-Trellis v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow / persistence / platform model. First, a multi-agent collaboration runtime: `trellis channel` coordinates multiple AI worker processes through project-scoped JSONL event logs at `~/.trellis/channels/<project>/<channel>/events.jsonl`, with worker OOM guard, forum/thread channels, durable idempotency keys, and bundled `.trellis/agents/{check,implement,subnode}.md` runtime definitions. Second, cross-session memory: `trellis mem list | search | context | extract | projects` reads raw Claude Code, Codex, and Pi Agent JSONL already on disk, slices by `--phase brainstorm|implement|all`, and never uploads anything. Third, a dual-package npm release: `@pennixrv/trellis` (CLI) and `@pennixrv/trellis-core` (SDK with `/channel`, `/task`, `/mem`, `/testing` subpaths) ship in lockstep on one version. Treat these as first-class customization surfaces alongside the per-platform integration files.
+Trellis v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow / persistence / platform model. First, the Teamwork runtime: `trellis teamwork` coordinates teammate processes through project-scoped JSONL event logs at `~/.trellis/teamwork/<project>/<session>/events.jsonl`, with a process guard, forum threads, durable idempotency keys, and a bundled `.trellis/agents/teammate.md` role card. Second, cross-session memory: `trellis mem list | search | context | extract | projects` reads raw Claude Code, Codex, and Pi Agent JSONL already on disk, slices by `--phase brainstorm|implement|all`, and never uploads anything. Third, a dual-package npm release: `@pennixrv/trellis` (CLI) and `@pennixrv/trellis-core` (SDK with `/teamwork`, `/task`, `/mem`, `/testing` subpaths) ship in lockstep on one version. Treat these as first-class customization surfaces alongside the per-platform integration files.
 
 The default operating scope is local files in the user project:
 
 - `.trellis/`: workflow, config, tasks, spec, workspace, scripts, bundled runtime agents, and runtime state.
 - Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, `.dsh/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills/<name>/SKILL.md`; subagent skills carry `runAs: subagent` frontmatter. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer and delivers commands plus agent prompts as `.kimi-code/skills/<name>/SKILL.md`. DeepSeek Harness keeps shared workflow skills under `.agents/skills/` and DSH-private commands plus `trellis-agent-*` role skills under `.dsh/skills/`; with the optional `dsh-trellis` plugin its continuable subagents use event-driven settlement waits, otherwise required children are dispatched in the foreground from the start.
 - Shared skill layer: `.agents/skills/`.
-- User-owned channel store outside the project tree: `~/.trellis/channels/<project>/<channel>/events.jsonl`.
+- User-owned Teamwork Session store outside the project tree: `~/.trellis/teamwork/<project>/<session>/events.jsonl`.
 - Raw platform conversation logs queryable via `trellis mem`: `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` (OpenCode adapter degraded for the v0.6 line).
 
 Do not assume the user has the Trellis source repository. Do not default to modifying the global npm install directory or `node_modules` — both `@pennixrv/trellis` and `@pennixrv/trellis-core` ship as published packages sharing one version and one git tag per release.
@@ -23,7 +23,7 @@ Do not assume the user has the Trellis source repository. Do not default to modi
 
 1. Read `references/local-architecture/overview.md` first to establish the local Trellis system model.
 2. If the request involves a specific AI tool, read `references/platform-files/platform-map.md` and the relevant platform file notes.
-3. If the request involves multi-agent dispatch or channel workers, read `references/local-architecture/multi-agent-channel.md` and the bundled `.trellis/agents/` files.
+3. If the request involves Teamwork coordination or teammate sessions, read `references/local-architecture/multi-agent-teamwork.md` and the bundled `.trellis/agents/` files.
 4. If the user wants to change behavior, read `references/customize-local/overview.md`, then open the specific customization topic.
 5. Before editing, read the actual files in the user project and treat local content as authoritative.
 
@@ -31,46 +31,46 @@ Do not assume the user has the Trellis source repository. Do not default to modi
 
 ### Local Architecture
 
-- `references/local-architecture/overview.md`: The layered local Trellis architecture (workflow / persistence / platform / channel runtime) and customization principles.
+- `references/local-architecture/overview.md`: The layered local Trellis architecture (workflow / persistence / platform / Teamwork runtime) and customization principles.
 - `references/local-architecture/generated-files.md`: Files generated by `trellis init` and their customization boundaries, including `.trellis/agents/`.
-- `references/local-architecture/workflow.md`: Phases, routing, workflow-state blocks, and selectable workflow templates (`native`, `tdd`, `channel-driven-subagent-dispatch`, marketplace) in `.trellis/workflow.md`.
+- `references/local-architecture/workflow.md`: Phases, routing, workflow-state blocks, the bundled `native` workflow, and explicitly sourced custom workflows in `.trellis/workflow.md`.
 - `references/local-architecture/task-system.md`: Task directories, active task, JSONL context, parent/child task trees, and task runtime.
 - `references/local-architecture/spec-system.md`: How `.trellis/spec/` is organized, injected, and refreshed from a `registry.spec` source.
 - `references/local-architecture/workspace-memory.md`: `.trellis/workspace/` journals plus `trellis mem` cross-session recall and the `@pennixrv/trellis-core/mem` SDK.
-- `references/local-architecture/context-injection.md`: Hooks, sub-agent preludes, and channel-runtime worker inbox routing.
-- `references/local-architecture/multi-agent-channel.md`: `trellis channel` subcommands, project-scoped event store, forum/thread channels, worker OOM guard, durable idempotency, and bundled `.trellis/agents/` runtime agents.
-- `references/local-architecture/bundled-skills.md`: Auto-dispatched bundled skills (`trellis-channel`, `trellis-meta`, `trellis-research-record`, `trellis-session-insight`, `trellis-spec-bootstrap`) and how `getBundledSkillTemplates()` ships them to every platform skill root.
+- `references/local-architecture/context-injection.md`: Hooks, sub-agent preludes, and Teamwork message inbox routing.
+- `references/local-architecture/multi-agent-teamwork.md`: `trellis teamwork`, Teamwork Session storage, teammate process guard, task ownership boundary, and bundled `.trellis/agents/` runtime instructions.
+- `references/local-architecture/bundled-skills.md`: Bundled skills under `packages/cli/src/templates/common/bundled-skills/` and how `getBundledSkillTemplates()` ships them to platform skill roots.
 
 ### Platform Files
 
-- `references/platform-files/overview.md`: How shared `.trellis/` files relate to platform directories and the four platform integration modes (hook-driven, agent prelude, main-session workflow, channel runtime).
+- `references/platform-files/overview.md`: How shared `.trellis/` files relate to platform directories and the three platform integration modes (hook-driven, agent prelude, main-session workflow).
 - `references/platform-files/platform-map.md`: Platform directories and paths for skills, agents, hooks, and extensions across all supported platforms including DeepSeek Harness, Reasonix, and Pi's native `trellis_subagent` extension.
-- `references/platform-files/hooks-and-settings.md`: How settings/config files, hooks, plugins, and extensions connect to Trellis; covers `channel.worker_guard.*`, `channel.subnode.*`, and `codex.dispatch_mode`.
-- `references/platform-files/agents.md`: Per-platform `trellis-research` / `trellis-implement` / `trellis-check` sub-agent files plus bundled `.trellis/agents/{check,implement}.md` for the channel runtime.
+- `references/platform-files/hooks-and-settings.md`: How settings/config files, hooks, plugins, and extensions connect to Trellis; covers `teamwork.teammate_guard.*` and `codex.dispatch_mode`.
+- `references/platform-files/agents.md`: Per-platform `trellis-research` / `trellis-implement` / `trellis-check` sub-agent files plus the bundled `.trellis/agents/teammate.md` role card.
 - `references/platform-files/skills-and-commands.md`: Differences between skills, commands, prompts, and workflows, plus how to change them.
 
 ### Local Customization
 
 - `references/customize-local/overview.md`: Choose the right local customization entry point for the user's request.
 - `references/customize-local/change-workflow.md`: Change phases, routing, next actions, workflow-state, and the selected workflow template.
-- `references/customize-local/change-task-lifecycle.md`: Change task creation, status, archive behavior, parent/child links, archive slug collision handling, and lifecycle hooks.
-- `references/customize-local/change-context-loading.md`: Change how tasks, specs, journals, hook context, channel inbox messages, and `trellis mem` recall are loaded.
+- `references/customize-local/change-task-lifecycle.md`: Change task creation, lifecycle and phase state, parent/child links, and lifecycle hooks.
+- `references/customize-local/change-context-loading.md`: Change how tasks, specs, journals, hook context, Teamwork inbox messages, and `trellis mem` recall are loaded.
 - `references/customize-local/change-hooks.md`: Change platform hooks, settings, task lifecycle hooks (`hooks.after_*`), and shell session bridges.
-- `references/customize-local/change-agents.md`: Change research, implement, and check agent behavior across platform sub-agents, bundled channel runtime agents, and the Codex `dispatch_mode` toggle.
+- `references/customize-local/change-agents.md`: Change research, implement, and check agent behavior across platform sub-agents, the Teamwork teammate role card, and the Codex `dispatch_mode` toggle.
 - `references/customize-local/change-skills-or-commands.md`: Add or modify local skills, commands, prompts, and workflows; covers upstream bundled-skill auto-dispatch.
 - `references/customize-local/change-spec-structure.md`: Adjust the project spec structure under `.trellis/spec/`, including registry-backed sources.
 - `references/customize-local/add-project-local-conventions.md`: Put team rules into project-local specs or local skills.
 
 ## Current Rules
 
-- `.trellis/workflow.md` is the local workflow source of truth; its initial content was selected from a workflow template (built-in `native`, `tdd`, `channel-driven-subagent-dispatch`, or a marketplace template) at `trellis init` time and can be re-selected via `trellis workflow --template <id>`. Missing `.trellis/agents/<name>.md` files referenced by the active template trigger a non-blocking stderr warning pointing at `trellis update`.
-- `.trellis/config.yaml` is the project-level Trellis configuration entry point. It hosts task lifecycle hooks (`hooks.after_create` / `after_start` / `after_finish` / `after_archive`), journal shape (`session_commit_message` / `max_journal_lines` / `session_auto_commit`), generic channel worker guard (`channel.worker_guard.idle_timeout` / `max_live_workers`), bounded subnode defaults (`channel.subnode.max_live_workers` / `idle_timeout` / `timeout` / `warn_before`), Codex dispatch mode (`codex.dispatch_mode: inline | sub-agent`), and the spec registry block (`registry.spec.source` + `registry.spec.template`).
-- `.trellis/spec/` stores the user's project-specific coding conventions and design constraints. When `registry.spec` is set, files are refreshed by `trellis update`; local edits surface as "modified by user" conflicts in `.trellis/.template-hashes.json`.
-- `.trellis/tasks/` stores task PRDs, design notes, implement plans, research files, and JSONL context. Tasks form parent/child trees: `task.py create --parent <slug>`, `task.py add-subtask <parent> <child>`, `task.py remove-subtask <parent> <child>`, and `task.py list-context <task>`. `task.py create` rejects a slug already present in `.trellis/tasks/archive/**`.
+- `.trellis/workflow.md` is the local workflow source of truth. By default, `trellis init` writes the bundled `native` workflow; a custom workflow is available only when its source is explicitly supplied, and can be re-selected via `trellis workflow --template <id> --workflow-source <source>`. Missing `.trellis/agents/<name>.md` files referenced by the active template trigger a non-blocking stderr warning pointing at `trellis update`.
+- `.trellis/config.yaml` is the project-level Trellis configuration entry point. It hosts task lifecycle hooks (`hooks.after_create` / `after_start` / `after_finish`), journal shape (`session_commit_message` / `max_journal_lines` / `session_auto_commit`), Teamwork teammate guard (`teamwork.teammate_guard.idle_timeout` / `max_live_teammates`), Codex dispatch mode (`codex.dispatch_mode: inline | sub-agent`), and the spec registry block (`registry.spec.source` + `registry.spec.template`).
+- `.trellis/spec/` stores the user's project-specific coding conventions and design constraints. When `registry.spec` is set, files are refreshed by `trellis update`; local edits surface as `modified by user` conflicts in `.trellis/.template-hashes.json`.
+- `.trellis/tasks/` stores task records, planning artifacts, research, and JSONL context. Tasks remain in place after completion or cancellation. Tasks form parent/child trees through `task.py create --parent`, `add-subtask`, `remove-subtask`, and `list-context`.
 - `.trellis/workspace/` stores **deliberately written** developer journals. Raw cross-session dialogue is **not** stored here — it lives on disk under `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` and is recovered via `trellis mem search|extract|context`. The bundled `trellis-session-insight` skill teaches when to reach for `mem`.
-- `.trellis/agents/{check,implement,subnode}.md` are bundled, platform-agnostic channel runtime agent definitions loaded by `trellis channel spawn --agent <name>`. Editable; `trellis update` backfills missing ones. Editing the per-platform `trellis-implement.md` / `trellis-check.md` does **not** change channel-runtime worker behavior.
-- `~/.trellis/channels/<project>/<channel>/events.jsonl` is the channel runtime event log per project per channel. User-owned, file-locked sequence numbering, durable `idempotencyKey` support; never under `.trellis/`.
-- Bundled multi-file skills are auto-dispatched to every platform skill root by `getBundledSkillTemplates()` in `packages/cli/src/templates/common/index.ts`. Dropping a new directory under `packages/cli/src/templates/common/bundled-skills/` (upstream) ships it to every platform on the next `trellis update`.
+- `.trellis/agents/teammate.md` is the bundled, platform-agnostic instruction card loaded for a teammate by `trellis teamwork spawn --agent teammate`. Editable; `trellis update` backfills it if missing. Editing the per-platform `trellis-implement.md` / `trellis-check.md` does **not** change Teamwork teammate behavior.
+- `~/.trellis/teamwork/<project>/<session>/events.jsonl` is the Teamwork Session event log. User-owned, file-locked sequence numbering, durable `idempotencyKey` support; never under `.trellis/`.
+- Directories under `packages/cli/src/templates/common/bundled-skills/` are auto-dispatched to platform skill roots by `getBundledSkillTemplates()` in `packages/cli/src/templates/common/index.ts`. Adding a directory there is enough for the shared loader to include it on the next `trellis init` or `trellis update`.
 - Platform settings/config files decide which hooks, agents, skills, commands, prompts, and workflows actually run. Reasonix has no settings file — behavior is encoded inside skill frontmatter.
 - `.trellis/.template-hashes.json` and `.trellis/.runtime/` are management/runtime state files. Confirm necessity before editing them.
 
@@ -79,7 +79,7 @@ Do not assume the user has the Trellis source repository. Do not default to modi
 - Do not treat Trellis upstream source code as the default target for local customization.
 - Do not modify the global npm install directory or `node_modules/@pennixrv/trellis` or `node_modules/@pennixrv/trellis-core` to implement project needs; both packages ship in lockstep.
 - Do not overwrite user-modified local files with default templates; check `.trellis/.template-hashes.json` first and prefer `.new` sidecar files over destructive overwrites.
-- Do not put team-private project rules into any public bundled skill (`trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`); put project rules in `.trellis/spec/`, a project-local skill, the current task, or the workspace journal — `trellis update` will overwrite anything inside a bundled skill directory.
-- Do not hand-edit `~/.trellis/channels/<project>/<channel>/events.jsonl`; sequence numbers are assigned under a file lock and replay-safe writes go through the `trellis channel` CLI or the `@pennixrv/trellis-core/channel` SDK.
-- Do not edit `.claude/agents/trellis-implement.md` (or any other per-platform sub-agent file) when the goal is to change channel runtime worker behavior — edit `.trellis/agents/<name>.md` instead.
+- Do not put team-private project rules into a public bundled skill; put project rules in `.trellis/spec/`, a project-local skill, the current task, or the workspace journal — `trellis update` will overwrite anything inside a bundled skill directory.
+- Do not hand-edit `~/.trellis/teamwork/<project>/<session>/events.jsonl`; sequence numbers are assigned under a file lock and replay-safe writes go through the `trellis teamwork` CLI or the `@pennixrv/trellis-core/teamwork` SDK.
+- Do not edit `.claude/agents/trellis-implement.md` (or any other per-platform sub-agent file) when the goal is to change Teamwork teammate behavior — edit `.trellis/agents/teammate.md` instead.
 - Do not describe removed or never-shipped mechanisms as current Trellis behavior; cross-check against the local `.trellis/config.yaml` and the installed CLI's `trellis --help` before claiming a knob exists.

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/change-agents.md

@@ -5,7 +5,7 @@ When the user wants to change `trellis-research`, `trellis-implement`, or `trell
 ## Read These Files First
 
 1. Target platform agent directory
-2. `.trellis/workflow.md` Phase 2 / research routing
+2. `.trellis/workflow.md` Decision Space Construction and Consolidation Phase / research routing
 3. Current task `prd.md`
 4. Current task `implement.jsonl` / `check.jsonl`
 5. Relevant hook or agent prelude

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/change-skills-or-commands.md

@@ -4,10 +4,11 @@ When the user wants to change AI entry points, auto-trigger rules, or explicit c
 
 Before editing, classify the skill you are about to touch:
 
-- **Bundled upstream skill** — `trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`. Source of truth lives in the Trellis CLI repo under `packages/cli/src/templates/common/bundled-skills/<name>/`; auto-dispatched to every platform's skill root by `getBundledSkillTemplates()` on `trellis init` / `trellis update`. Local edits here are tracked by `.trellis/.template-hashes.json` and will be flagged on the next update.
-- **Project-local skill** — anything else under `.{platform}/skills/`. Owned by the user; not refreshed by `trellis update`.
+- **Bundled skill** — any directory under `packages/cli/src/templates/common/bundled-skills/` in the Trellis CLI repo. The shared loader dispatches these skills to platform skill roots on `trellis init` / `trellis update`; local edits are tracked by `.trellis/.template-hashes.json` and flagged on update.
+- **Other Trellis-generated skill** — a single-file workflow skill under `packages/cli/src/templates/common/skills/` or a platform-specific skill under `packages/cli/src/templates/<platform>/skills/`. Edit its source template; deployed files are managed by Trellis.
+- **Project-local or separately installed skill** — a skill not produced by a Trellis template. Trellis does not refresh it; follow the project owner's or installing tool's update process.
 
-The remainder of this file uses "skill" for the local file; the override and conflict rules differ between the two cases.
+For the source paths and generated layout of each Trellis skill type, see [Bundled Skills](../local-architecture/bundled-skills.md). The remainder of this file uses "skill" for the local file; ownership and update behavior depend on its source.
 
 ## Read These Files First
 
@@ -20,7 +21,7 @@ The remainder of this file uses "skill" for the local file; the override and con
 ## Which Entry Type To Choose
 
 | Goal | Recommendation |
-| --- | --- |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | AI should automatically know a capability | Add or modify a skill. |
 | User wants to trigger manually with a command | Add or modify a command/prompt/workflow. |
 | Team project conventions | Prefer `.trellis/spec/` or a project-local skill — never a bundled skill directory. |
@@ -50,15 +51,15 @@ Do not write vague descriptions such as "helpful project skill"; they can trigge
 
 ### Bundled vs. Project-Local
 
-The same directory shape is used by two very different ownership models:
+Bundled and project-local skills can share a similar on-disk layout but have different owners:
 
-| Aspect | Bundled (`trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`) | Project-local |
-| --- | --- | --- |
+| Aspect                     | Bundled (any directory under `packages/cli/src/templates/common/bundled-skills/`)                                                                                | Project-local                                          |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
 | Source of truth | `packages/cli/src/templates/common/bundled-skills/<name>/` in Trellis CLI repo | Inside the user project itself |
 | Dispatch | Auto-dispatched to every platform skill root by `getBundledSkillTemplates()` (`packages/cli/src/templates/common/index.ts`) on `trellis init` / `trellis update` | Created by the user (or another skill) and never moved |
 | Hash tracking | Every file recorded in `.trellis/.template-hashes.json`; conflict prompt on update | Not tracked |
 | Editing locally | Allowed but will be marked "modified by user" on next update | Free editing |
-| The right way to customize | Add a *new* project-local skill with a *different* name that supplements (or supersedes) the bundled one | Edit the file directly |
+| The right way to customize | Add a _new_ project-local skill with a _different_ name that supplements (or supersedes) the bundled one                                                         | Edit the file directly                                 |
 
 If the goal is "make my project's AI behave differently when discussing release notes," the answer is almost always a project-local skill, not surgery on `trellis-meta/`.
 
@@ -76,7 +77,7 @@ If a command only repeats workflow rules, prefer making it reference/read `.trel
 ## Common Paths
 
 | Platform | Entry directories |
-| --- | --- |
+| -------------------------- | -------------------------------------------------------------------------------------- |
 | Claude Code | `.claude/skills/`, `.claude/commands/` |
 | Cursor | `.cursor/skills/`, `.cursor/commands/` |
 | OpenCode | `.opencode/skills/`, `.opencode/commands/` |
@@ -92,7 +93,7 @@ If a command only repeats workflow rules, prefer making it reference/read `.trel
 | ZCode | `.zcode/skills/`, `.zcode/commands/` |
 | Kilo / Antigravity / Devin | workflows + skills |
 
-Every directory above is a deploy target for the four bundled skills. Each platform receives a full copy on `trellis init` and refresh on `trellis update`; nothing has to be wired by hand.
+Platforms with a skill root receive the bundled skills discovered by the shared loader on `trellis init` and manage them through `trellis update`; no per-skill platform wiring is required.
 
 ## Add A Project-Local Skill
 
@@ -105,19 +106,12 @@ If the user wants to document team-private customizations, create a project-loca
 
 For multi-platform projects, add equivalent versions in each platform skill directory, or use `.agents/skills/` on platforms that support the shared layer (Codex, Gemini CLI).
 
-Pick a name that does **not** collide with the bundled set:
-
-- `trellis-meta`
-- `trellis-spec-bootstrap`
-- `trellis-session-insight`
-- `trellis-channel`
-
-A reused name causes `getBundledSkillTemplates()` to overwrite the project-local copy on the next update. A common convention is to prefix the project name: `acme-trellis-deploy`, `acme-trellis-onboarding`.
+Before choosing a project-local skill name, check `packages/cli/src/templates/common/bundled-skills/`, `packages/cli/src/templates/common/skills/`, and the target platform's `packages/cli/src/templates/<platform>/skills/`; a matching name can target the same path during `trellis init` or `trellis update`. A common convention is to prefix the project name: `acme-trellis-deploy`, `acme-trellis-onboarding`.
 
 ## Notes
 
 - Do not mix every platform's syntax into one file.
 - Do not change only one platform entry point while claiming all platforms are supported.
 - Do not hide long-term engineering conventions inside a command; write them to `.trellis/spec/`.
-- Do not hand-edit files inside `trellis-meta/`, `trellis-spec-bootstrap/`, `trellis-session-insight/`, or `trellis-channel/` under any `.{platform}/skills/` directory expecting the change to persist — they are bundled and refreshed by `trellis update`. Either contribute upstream or add a project-local skill that complements them.
+- Do not hand-edit files inside a bundled skill directory under any `.{platform}/skills/` directory expecting the change to persist — they are refreshed by `trellis update`. Either contribute upstream or add a project-local skill that complements them.
 - After `trellis update` reports a "modified by you" conflict on a bundled skill file, choose **keep** only if you accept maintaining the divergence by hand; otherwise accept the overwrite and re-apply the intent as a project-local skill.

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/change-spec-structure.md

@@ -6,7 +6,7 @@ When the user wants to change the engineering conventions AI follows, add new sp
 
 1. `.trellis/config.yaml`
 2. `.trellis/spec/`
-3. `.trellis/workflow.md` planning artifact guidance and Phase 3.3
+3. `.trellis/workflow.md` planning artifact guidance in Solution Design and Convergence Phase
 4. Current task `implement.jsonl` / `check.jsonl`
 
 ## Common Needs

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/change-task-lifecycle.md

@@ -1,91 +1,43 @@
 # Change Local Task Lifecycle
 
-Task lifecycle includes creation, start, context configuration, finish, archive, parent/child tasks, and lifecycle hooks. The default customization targets are `.trellis/tasks/`, `.trellis/config.yaml`, and `.trellis/scripts/`.
+Read the installed project's workflow and task record before changing task creation or lifecycle behavior. Task records remain in .trellis/tasks/ after completion or cancellation; Trellis does not archive task records.
 
-## Read These Files First
+## Read these files first
 
-1. `.trellis/workflow.md`
-2. `.trellis/config.yaml`
-3. `.trellis/scripts/task.py`
-4. `.trellis/scripts/common/task_store.py`
-5. `.trellis/scripts/common/task_utils.py`
-6. The current task's `.trellis/tasks/<task>/task.json`
+1. .trellis/workflow.md
+2. .trellis/config.yaml
+3. .trellis/scripts/task.py
+4. .trellis/scripts/common/task_store.py
+5. .trellis/scripts/common/task_workflow.py
+6. The current task's task.json
 
-## Common Needs And Edit Points
+## Common edit points
 
 | Need | Edit point |
 | --- | --- |
-| Automatically sync an external system after task creation | `hooks.after_create` in `.trellis/config.yaml`. |
-| Automatically update status after task start | `hooks.after_start` in `.trellis/config.yaml`. |
-| Return an in-progress task to planning | `hooks.after_replan` in `.trellis/config.yaml`. |
-| Run a script after task finish | `hooks.after_finish` in `.trellis/config.yaml`. |
-| Clean external resources after archive | `hooks.after_archive` in `.trellis/config.yaml`. |
-| Change default task fields | `.trellis/scripts/common/task_store.py`. |
-| Change task parsing/search | `.trellis/scripts/common/task_utils.py`. |
-| Change active task behavior | `.trellis/scripts/common/active_task.py`. |
+| Run a script after task creation or start | hooks.after_create or hooks.after_start in .trellis/config.yaml |
+| Run a script after clearing the session task pointer | hooks.after_finish in .trellis/config.yaml |
+| Change default task fields | .trellis/scripts/common/task_store.py |
+| Change task parsing or lookup | .trellis/scripts/common/task_utils.py |
+| Change lifecycle and phase contracts | .trellis/scripts/common/task_workflow.py and Core task model |
+| Change active task behavior | .trellis/scripts/common/active_task.py and host integration |
 
-## lifecycle hooks
+Lifecycle hooks receive TASK_JSON_PATH for the affected task. Hook failures should follow the existing behavior of the native operation and must not silently corrupt task state.
 
-`.trellis/config.yaml` supports:
+Keep project-specific fields under task.json meta unless the standard schema must change. When changing the schema, inspect every reader and writer.
 
-```yaml
-hooks:
-  after_create:
-    - "python3 .trellis/scripts/hooks/my_sync.py create"
-  after_start:
-    - "python3 .trellis/scripts/hooks/my_sync.py start"
-  after_finish:
-    - "python3 .trellis/scripts/hooks/my_sync.py finish"
-  after_archive:
-    - "python3 .trellis/scripts/hooks/my_sync.py archive"
-```
+## Active task behavior
 
-Hook commands receive the `TASK_JSON_PATH` environment variable, pointing to the current task's `task.json`. Hook failures should usually warn, but not block the main task operation.
+The active task pointer is scoped to an AI session under .trellis/.runtime/sessions/. Use task.py current to inspect it, task.py start to attach a task to the current session, and task.py finish to clear that session pointer. Do not introduce a shared global pointer.
 
-## Change Task Fields
+When task.py create runs inside a session with a recognized session identity, it attaches the new task to that session. Outside such a session, the task is still created but no pointer is changed; task.py start can attach it later.
 
-If the user wants to add project-local fields, prefer putting them under `meta` in `task.json` to avoid breaking existing scripts' assumptions about standard fields.
+## Modification steps
 
-Example:
+1. Confirm the active task through task.py current --source.
+2. Inspect its task.json and phase state.
+3. Read the applicable Trellis specs.
+4. Change the native script or configuration that owns the behavior.
+5. Synchronize .trellis/workflow.md and affected host integrations.
 
-```json
-"meta": {
-  "linearIssue": "ENG-123",
-  "risk": "high"
-}
-```
-
-If standard fields really need to change, inspect every local script that reads `task.json`.
-
-## Change Active Task
-
-Active task is session-level state stored in `.trellis/.runtime/sessions/`. Do not fall back to a global `.current-task` model. If the user wants to change active task behavior, edit:
-
-- `.trellis/scripts/common/active_task.py`
-- platform hooks or shell session bridges
-- active task descriptions in `.trellis/workflow.md`
-
-### `task.py create` Sets the Active Pointer
-
-`cmd_create` in `.trellis/scripts/common/task_store.py` calls `set_active_task` best-effort right after writing the new task directory. The behavior:
-
-- When the calling shell carries session identity (`TRELLIS_CONTEXT_ID` env var, or any platform-specific session env that `resolve_context_key` recognizes — see `active_task.py:_ENV_SESSION_KEYS`), the per-session pointer at `.trellis/.runtime/sessions/<context_key>.json` is rewritten to point at the new task. The task's `status=planning` and `[workflow-state:planning]` fires on the very next `UserPromptSubmit`.
-- When session identity is unavailable (raw CLI invocation outside an AI session, or a platform that doesn't propagate identity to shell), the task directory is still created and `status=planning` is still written, but the active pointer is left untouched. The user can attach the task later with `task.py start <dir>` once they're back in an AI session.
-
-This makes `[workflow-state:planning]` the live breadcrumb during the brainstorm and JSONL curation work that follows `task.py create`. The pre-R7 behavior left the breadcrumb stuck on `no_task` until `task.py start`, so the planning block was effectively dead text.
-
-If you fork `task.py` to add a new creation path (e.g. an external import that bypasses `cmd_create`), audit whether your path also calls `set_active_task`. Without that call, your created tasks will not surface as active. The full status writer table is in `.trellis/spec/cli/backend/workflow-state-contract.md`.
-
-## Modification Steps
-
-1. Confirm the current task with `python3 ./.trellis/scripts/task.py current --source`.
-2. Read the current task's `task.json` and confirm status and fields.
-3. For configuration needs, edit `.trellis/config.yaml` first.
-4. For script behavior needs, then edit `.trellis/scripts/`.
-5. If the AI flow changed, synchronize `.trellis/workflow.md`.
-
-## Do Not
-
-- Do not directly edit `.trellis/.runtime/sessions/` to "fix" business state.
-- Do not hard-code project-private fields into scripts; prefer `meta`.
-- Do not default to asking the user to fork Trellis CLI.
+Do not hand-edit runtime pointers or phase state. Do not change task lifecycle outside the Trellis CLI contract.

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/change-workflow.md

@@ -1,65 +1,26 @@
 # Change Local Workflow
 
-When the user wants to change Trellis phases, next-action hints, whether to create tasks, whether to use sub-agents, or when to check/wrap up, edit `.trellis/workflow.md` first.
+Read the installed project's .trellis/workflow.md before changing phase activities, route guidance, or platform entry points.
 
-## Read These Files First
+## Business phases
 
-1. `.trellis/workflow.md`
-2. Entry files for the current platform, such as skills/commands/prompts/workflows
-3. The current task's `task.json` and `prd.md`
+- Goal Exploration and Requirements Confirmation Phase
+- Decision Space Construction and Consolidation Phase
+- Solution Design and Convergence Phase
+- Task Implementation and Test Verification Phase
+- Delivery Review and On-Site Closeout Phase
 
-## Common Needs And Edit Points
+Each phase has its own Skill and workflow diagram. Keep their activities distinct. Trellis CLI owns task lifecycle and phase state; do not encode a second route in a Skill, Hook, or command.
 
-| Need | Edit point |
-| --- | --- |
-| Change phase names or phase order | `Phase Index` and the corresponding Phase sections. |
-| Change whether to create a task when there is no task | `[workflow-state:no_task]` state block. |
-| Change the next step during planning | Phase 1 and `[workflow-state:planning]`. |
-| Change whether an agent is required during in_progress | Phase 2 and `[workflow-state:in_progress]`. |
-| Change wrap-up after completion | Phase 3 and `[workflow-state:completed]`. |
-| Change which skill a user intent triggers | `Skill Routing` table. |
-
-## Modification Steps
-
-1. Find the relevant section in `.trellis/workflow.md`.
-2. When changing rules, keep explicit trigger conditions and next actions.
-3. If adding or renaming a skill/agent, synchronize the corresponding files in platform directories.
-4. Workflow-state changes only need an edit to the `[workflow-state:STATUS]` block in `.trellis/workflow.md`. The hook is parser-only — it reads whatever you put in the block. Keep the opening and closing tags' STATUS strings identical (`[workflow-state:foo]…[/workflow-state:foo]`); mismatched STATUS pairs are silently dropped.
-5. Make the AI reread `.trellis/workflow.md`; do not keep using rules from the old conversation.
-
-## Example: Relax Task Creation Requirements
-
-To change when task creation can be skipped, usually edit `[workflow-state:no_task]`:
-
-```md
-[workflow-state:no_task]
-Task is not required when the answer is a one-reply explanation, no files are changed, and no research is needed.
-[/workflow-state:no_task]
-```
-
-If the formal Phase 1 flow also needs to change, synchronize the Phase 1 section.
+The Goal Exploration and Requirements Confirmation Phase requires explicit user confirmation of the current requirements revision before the route enters Decision Space Construction and Consolidation Phase or Solution Design and Convergence Phase. Acceptance in Solution Design and Convergence Phase does not grant implementation authorization. Task Implementation and Test Verification Phase follows the authorized contract. During Delivery Review and On-Site Closeout Phase, review the current delivery and handle task completion or cancellation. Routes may skip phases when the task record contains sufficient reason and evidence.
 
-## Example: One Platform Does Not Use Sub-Agents
+## Change workflow assets
 
-If the user wants only one platform to avoid sub-agents, first confirm whether that platform has a separate group in the workflow. Then change Phase 2 routing for that platform group instead of deleting all `trellis-implement` / `trellis-check` instructions across platforms.
-
-## `/trellis:continue` Route Table
-
-`/trellis:continue` resumes a task by deciding which phase step to load next. The decision combines `task.json.status` with the presence of artifacts inside the task directory. The mapping is fixed in the command itself; forks that add custom statuses must extend both the workflow.md tag block and this table.
-
-| `status` | Artifact state | Resume at |
-| --- | --- | --- |
-| `planning` | `prd.md` missing | Phase 1.1 (load `trellis-brainstorm`) |
-| `planning` | lightweight task with `prd.md` complete | ask for start review, then run `task.py start` |
-| `planning` | complex task missing `design.md` or `implement.md` | complete missing planning artifacts |
-| `planning` | complex task has `prd.md`, `design.md`, and `implement.md` | ask for start review, then run `task.py start` |
-| `in_progress` | no implementation in conversation history | Phase 2.1 (`trellis-implement`) |
-| `in_progress` | implementation done, no `trellis-check` run | Phase 2.2 (`trellis-check`) |
-| `in_progress` | check passed | Phase 3.3 (spec update) → 3.4 (commit) |
-| `completed` | task is still in active tree | Phase 3.5 (run `/trellis:finish-work` to archive) |
-
-When you add a custom status (e.g. `in-review`), add a `[workflow-state:in-review]` block in `.trellis/workflow.md` for the per-turn breadcrumb AND extend this route table — usually by editing the `/trellis:continue` command file (`.{platform}/commands/trellis/continue.md` or equivalent) to add a row that decides where to resume from. Without the route entry, `/trellis:continue` will fall through to a default branch and the user will not land on the step you intended.
-
-## Notes
+| Goal | Edit point |
+| --- | --- |
+| Change phase activities or transitions | .trellis/workflow.md and the matching phase Skill |
+| Change cross-component routing | .trellis/workflow.md and pennix-workflow-routing |
+| Change phase status or acceptance | Trellis CLI task workflow contract and tests |
+| Change host context injection | Relevant Hook or plugin |
 
-`.trellis/workflow.md` is the local project workflow, not an immutable template. The user can adapt it to team habits. After editing it, platform entry files may still contain old descriptions, so inspect them too.
+Keep workflow-state phase identifiers aligned with Core and the current task record. Hooks surface state; they do not authorize or accept work. After a shared change, inspect host commands and prompts for stale instructions.

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/overview.md

@@ -7,7 +7,7 @@ This directory is for local AI working in a user project where Trellis was insta
 | User wording | Read first |
 | --- | --- |
 | "Change the Trellis flow / phases / next prompt" | `change-workflow.md` |
-| "Change task creation, status, archive, or hooks" | `change-task-lifecycle.md` |
+| "Change task creation, lifecycle, phase state, or hooks" | `change-task-lifecycle.md` |
 | "AI did not read context / change injected content" | `change-context-loading.md` |
 | "A platform hook is not behaving as expected" | `change-hooks.md` |
 | "Change implement/check/research agent behavior" | `change-agents.md` |

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/bundled-skills.md

@@ -1,34 +1,38 @@
 # Bundled Skills
 
-"Bundled skills" are multi-file built-in skills shipped inside the Trellis CLI npm package. Unlike marketplace skills (which a user installs separately into their own `.claude/skills/` or other platform skill root), bundled skills are written automatically into every supported platform's skill root by `trellis init` and kept in sync by `trellis update`. They are part of Trellis itself, not third-party content.
+"Bundled skills" are Trellis CLI-owned skills shipped inside the CLI npm package. Unlike marketplace skills (which a user installs separately into their own `.claude/skills/` or other platform skill root), bundled skills are written automatically into supported platform skill roots by `trellis init` and managed by `trellis update`. They are part of Trellis itself, not third-party content.
 
-A bundled skill is a directory under `packages/cli/src/templates/common/bundled-skills/<skill>/` that already contains its own `SKILL.md` (with YAML frontmatter) plus optional `references/`, assets, or other supporting files. Trellis copies the whole directory tree as-is into each platform's skill root, so references stay lazy-loadable instead of being flattened into one oversized `SKILL.md`.
+A bundled skill is a directory under `packages/cli/src/templates/common/bundled-skills/<skill>/` that contains its own `SKILL.md` (with YAML frontmatter) and may include `references/`, assets, or other supporting files. Trellis copies the complete directory tree into each platform's skill root, resolving supported placeholders per platform so references stay lazy-loadable instead of being flattened into one oversized `SKILL.md`.
 
 ## What Counts As Bundled (vs. Adjacent Concepts)
 
 | Source path | Type | How it ships |
-| --- | --- | --- |
+| --------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `templates/common/bundled-skills/<name>/` | Bundled skill (multi-file) | Whole directory copied to every platform skill root |
 | `templates/common/skills/<name>.md` | Single-file workflow skill | Wrapped with frontmatter, written as `<root>/<name>/SKILL.md` |
 | `templates/common/commands/<name>.md` | Slash command / prompt | Written to each platform's command directory (`.claude/commands/trellis/`, `.cursor/commands/trellis-*.md`, `.gemini/commands/trellis/*.toml`, etc.) |
 | `templates/<platform>/skills/` | Platform-specific skill | Written only into that platform's directory (e.g. `.codex/skills/`) |
 | User skills under `.claude/skills/<my-skill>/` etc. | Marketplace or user-authored | Not managed by Trellis at all |
 
-The Trellis CLI never touches anything that is not produced by one of its own template loaders. Anything a user drops into a platform skill root by hand is left alone.
+Only paths emitted by Trellis template loaders are managed by Trellis. Other files in a platform skill root are outside those write paths.
 
 ## Current Bundled Skills
 
 The set is discovered at runtime by listing directories under `templates/common/bundled-skills/`:
 
 | Skill | Purpose |
-| --- | --- |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `trellis-goal-exploration-and-requirements` | Clarifies a task's goal, scope, success conditions, constraints, evidence, and user confirmation. |
+| `trellis-decision-space-construction-and-merging` | Organizes substantive decisions, options, evidence, dependencies, and decision trees. |
+| `trellis-solution-design-and-convergence` | Resolves user decisions, plan completeness, external precedents, and the implementation contract. |
+| `trellis-task-implementation` | Advances the authorized implementation contract through work packages, verification, integration, and blocker handling. |
+| `trellis-delivery-review-and-closeout` | Reviews the delivery candidate, unresolved items, acceptance conditions, and resource disposition. |
 | `trellis-meta` | This skill. Explains the local Trellis architecture and customization entry points to an AI working inside a user project. |
 | `trellis-session-insight` | Wraps the `trellis mem` CLI so an AI knows when and how to reach into past Claude Code / Codex / Pi Agent conversation logs. |
 | `trellis-spec-bootstrap` | Platform-neutral workflow for creating or refreshing `.trellis/spec/` from the real codebase (with optional GitNexus / ABCoder integration). |
-| `trellis-channel` | Capability skill teaching an AI when to reach for `trellis channel` for multi-agent collaboration, forum/thread persistent boards, and dispatcher-wait patterns. |
-| `trellis-research-record` | Records verified research, audit, or review findings in the active task without creating a second task ledger. |
+| `trellis-teamwork`        | Capability skill teaching an AI when to reach for `trellis teamwork` for multi-agent collaboration, forum/thread persistent boards, and dispatcher-wait patterns. |
 
-The list is discovered at runtime, so adding a new directory under `bundled-skills/` is the only step required to register a new skill (see "Adding a New Bundled Skill" below).
+This inventory reflects the directories currently in the source tree. The CLI discovers them at runtime, so adding a directory under `bundled-skills/` makes it available to the shared loader (see "Adding a New Bundled Skill" below).
 
 ## Where Bundled Skills Land Per Platform
 
@@ -37,7 +41,7 @@ A platform's whole file set — commands, workflow skills, agents, hooks, bundle
 All 21 platforms receive the full bundled-skill set:
 
 | Platform | Bundled skill root |
-| --- | --- |
+| ----------- | ---------------------------- |
 | Claude Code | `.claude/skills/<skill>/` |
 | Cursor | `.cursor/skills/<skill>/` |
 | OpenCode | `.opencode/skills/<skill>/` |
@@ -64,7 +68,7 @@ Codex, Gemini CLI, Pi and Kimi share the `.agents/skills/` root (the upstream Ag
 
 One description, two consumers:
 
-1. `trellis init` → `configurePlatform(platformId, cwd)` → `writeTemplateMap(cwd, collect<Platform>Templates())`. For 18 of the 21 platforms the registry entry in `configurators/index.ts` is literally `fromTemplates(collect<Platform>Templates)`, which *is* that composition. Claude Code, Codex and ZCode spell out a `configure` of their own, each for work a `Map<path, content>` cannot express (an opt-in `--with-statusline` flag, an intentionally empty `.codex/skills/` directory, a one-shot console notice) — none of them restates the file list.
+1. `trellis init` → `configurePlatform(platformId, cwd)` → `writeTemplateMap(cwd, collect<Platform>Templates())`. For 18 of the 21 platforms the registry entry in `configurators/index.ts` is literally `fromTemplates(collect<Platform>Templates)`, which _is_ that composition. Claude Code, Codex and ZCode spell out a `configure` of their own, each for work a `Map<path, content>` cannot express (an opt-in `--with-statusline` flag, an intentionally empty `.codex/skills/` directory, a one-shot console notice) — none of them restates the file list.
 2. `trellis update` → `collectPlatformTemplates(platformId)` (in `configurators/index.ts`) → the same map, used to detect drift and to populate `.trellis/.template-hashes.json`.
 
 Because both consumers read the one description, init and update cannot disagree about which files a bundled skill produces.
@@ -115,7 +119,6 @@ The shape and dispatch wiring are already generic, so adding a skill requires on
 4. **No dispatch wiring is required.** `listDirectories("bundled-skills")` discovers the new directory automatically, so all platforms receive it on the next `trellis init` or `trellis update`.
 
 5. **Verify the distribution path** before shipping. Skipping any of these steps has historically caused features to be documented as bundled while the published npm tarball was missing the files:
-
    - Source files exist on the branch being tagged.
    - `pnpm --filter @pennixrv/trellis build` copies the asset into `dist/templates/common/bundled-skills/<skill>/`.
    - `npm pack --dry-run --json` includes the expected `dist/**` paths.

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/generated-files.md

@@ -10,7 +10,6 @@ This page only describes files that are visible and editable inside the user pro
 .trellis/
 ├── workflow.md
 ├── config.yaml
-├── .gitignore
 ├── .developer
 ├── .version
 ├── .template-hashes.json
@@ -25,7 +24,6 @@ This page only describes files that are visible and editable inside the user pro
 | --- | --- | --- |
 | `.trellis/workflow.md` | Yes | Local workflow documentation and AI routing rules. |
 | `.trellis/config.yaml` | Yes | Project configuration, hooks, packages, journal line limits, and related settings. |
-| `.trellis/.gitignore` | No | Generated ignore rules for local Trellis state. Track it, but do not normally edit it. |
 | `.trellis/spec/` | Yes | Project specs, intended to be updated regularly by users and AI. |
 | `.trellis/tasks/` | Yes | Task material and research artifacts, maintained by the task workflow. |
 | `.trellis/workspace/` | Yes | Session records, usually written by `add_session.py`. |
@@ -35,37 +33,6 @@ This page only describes files that are visible and editable inside the user pro
 | `.trellis/.version` | No | Trellis version record used by update/migration logic. |
 | `.trellis/.template-hashes.json` | No | Template hash record. Do not hand-write business rules here. |
 
-## Git Tracking
-
-`trellis init` and `trellis update` are the single project-asset generation
-path. Do not add a second project initializer for Trellis files or platform
-integration files: use those commands to create or refresh the generated
-assets, then review and commit the resulting project changes normally.
-
-For a Git-tracked project, commit the durable project contract:
-
-- `.trellis/workflow.md`, `config.yaml`, `scripts/`, `spec/`, `tasks/`, and
-  `workspace/`;
-- `.trellis/.version` and `.trellis/.template-hashes.json`. They are generated
-  metadata, not hand-edited configuration; keeping them lets another clone
-  distinguish Trellis-owned templates from local changes safely;
-- the Trellis-managed files in selected platform directories, plus the
-  root-level `AGENTS.md` managed block when Trellis created or merged it.
-
-Do not commit local or ephemeral state. The generated `.trellis/.gitignore`
-already excludes `.developer`, `.current-task`, `.runtime/`, `.ralph-state.json`,
-agent runtime files, atomic-update files, backups, and Python caches. Platform
-session history, caches, logs, and credentials are platform-owned rather than
-Trellis templates; apply the platform's own ignore rules or the repository's
-security policy to them. If workspace journals contain data that the project
-policy forbids in Git, add a project-specific ignore rule rather than changing
-the shared Trellis template for every project.
-
-Generated does not mean disposable: `workflow.md`, specs, tasks, journals, and
-the template-hash receipt are ordinary project artifacts. Conversely, Trellis
-does not infer or broadly ignore all platform directories because doing so
-would hide user-owned files that it must preserve.
-
 ## Platform Directories
 
 Different platforms generate different directories. Common categories: