@mindfoldhq/trellis 0.6.0-rc.0 → 0.6.0

package/dist/templates/common/bundled-skills/trellis-channel/references/workers.md

@@ -0,0 +1,276 @@
+# Workers And Agent Cards
+
+Use workers when a peer agent should execute independently and report back
+through the channel event log. A worker is a registered child process (claude
+or codex) attached to a channel; the supervisor forwards inbox messages to it
+and translates its output back into channel events.
+
+## Spawn
+
+```bash
+trellis channel create impl-task --by dispatcher --cwd /path/to/repo
+trellis channel spawn impl-task --provider codex --as codex-impl --timeout 30m
+
+echo "Implement the schema for table X per .trellis/.../prd.md" \
+  | trellis channel send impl-task --as dispatcher --to codex-impl --stdin
+
+trellis channel wait impl-task --as dispatcher --from codex-impl --kind done --timeout 30m
+```
+
+`spawn` forks a `channel __supervisor` worker that emits `spawned`, streams
+`progress`, and should end with `done`, `error`, or `killed`. Workers stay
+inbox-idle until a `send --to <worker>` (or a broadcast when
+`--inbox-policy broadcastAndExplicit` is set) wakes them.
+
+Key `spawn` flags:
+
+- `--agent <name>` — load `.trellis/agents/<name>.md` (provider/model/as/system prompt defaults).
+- `--provider <claude|codex>` — overrides the agent card; validated against the adapter registry.
+- `--as <name>` — channel worker handle; defaults to the agent name.
+- `--cwd <path>` — worker working directory (also the jail root for `--file`/`--jsonl`).
+- `--model <id>` — model override.
+- `--resume <id>` — resume an existing claude session / codex thread.
+- `--timeout <duration>` — auto-kill after `30s` / `2m` / `1h`.
+- `--warn-before <duration>` — supervisor_warning lead time (default `5m`; `0ms` disables).
+- `--file <path>` (repeatable, glob-supported) — inject file content into the system prompt.
+- `--jsonl <path>` (repeatable) — Trellis jsonl manifest (`{file, reason}` per line).
+- `--by <agent>` — author of the `spawned` event (defaults to `$TRELLIS_CHANNEL_AS` or `main`).
+- `--inbox-policy <explicitOnly|broadcastAndExplicit>` — default `explicitOnly`.
+- `--idle-timeout <duration>` — OOM guard idle TTL (default `5m`; `0` disables).
+- `--max-live-workers <n>` — spawn-time live-worker budget (default `6`; `0` disables).
+
+The success event `spawned` records `pid`, `provider`, `agent`, the injected
+`files`, and the resolved `manifests` so later spectators can audit context.
+
+## Agent Cards
+
+`--agent <name>` resolves to `.trellis/agents/<name>.md`. The card name must
+match `[A-Za-z0-9._-]+`. The default Trellis install ships two cards:
+
+- `.trellis/agents/check.md` — code-quality reviewer.
+- `.trellis/agents/implement.md` — coding worker for implementation runs.
+
+```yaml
+---
+name: check
+description: Code quality check expert.
+provider: claude
+---
+```
+
+Frontmatter fields populate `spawn` defaults (provider, model, `as`); the
+markdown body becomes the worker's system-prompt role. Cards do **not**
+auto-attach task files — context must be injected explicitly per spawn (see
+below).
+
+Always inspect project cards before spawning a named agent:
+
+```bash
+ls .trellis/agents
+sed -n '1,100p' .trellis/agents/check.md
+```
+
+## Context Injection
+
+Two flags inject content into the worker's system prompt under a
+`# CONTEXT FILES` block, assembled by `context-loader`:
+
+- `--file <path>` — repeatable, glob-supported (`*`, `**`). Each match is
+  read and concatenated.
+- `--jsonl <path>` — repeatable Trellis manifest where every line is
+  `{"file":"<path>","reason":"<why>"}`. The reason is preserved as a header
+  comment above each file's content.
+
+Limits enforced by the loader:
+
+- 1 MB hard cap per file (oversize → error).
+- 200 KB per-file warning to stderr.
+- 500 KB total assembled-context warning to stderr.
+- Path-traversal jail: all resolved paths must stay under `--cwd`.
+
+Example spawning a check agent against a task directory:
+
+```bash
+TASK=.trellis/tasks/05-13-example
+trellis channel spawn cr-example --agent check --provider codex --as check-cx \
+  --file "$TASK/prd.md" \
+  --file "$TASK/design.md" \
+  --file "$TASK/implement.md" \
+  --jsonl "$TASK/check.jsonl" \
+  --cwd "$PWD" --timeout 30m
+```
+
+The `spawned` event records both the literal `files` array and any `manifests`
+expanded from `--jsonl`, so the audit trail captures whatever the worker was
+actually shown.
+
+## Names And Routing
+
+`--as` has two meanings:
+
+- `send` / `wait` / `interrupt`: speaker identity (author of the resulting event).
+- `spawn`: the worker handle that other agents address with `--to`.
+
+Use explicit names when multiple workers or providers participate in one
+channel:
+
+```bash
+trellis channel spawn cr-feature --agent check --as check-claude
+trellis channel spawn cr-feature --agent check --provider codex --as check-cx
+
+trellis channel wait cr-feature --as main \
+  --from check-claude,check-cx --kind done --all --timeout 15m
+```
+
+`--all` requires `--from` and blocks until every listed worker has produced a
+matching event; timeout exits with code **124** and prints
+`timeout: still waiting on ...` to stderr.
+
+## Soft Interrupt — `interrupt`
+
+`channel interrupt` is the cooperative redirect: it appends an `interrupt`
+event (reason `"user"`) and, where the adapter supports it, issues a
+provider-level turn interrupt with a replacement instruction. Use it when the
+worker should drop its current turn and act on new input immediately, without
+losing its session.
+
+```bash
+echo "Stop refactoring the parser — switch to fixing the failing test in src/foo.ts" \
+  | trellis channel interrupt impl-task --as dispatcher --to codex-impl --stdin
+```
+
+Flags:
+
+- `--as <agent>` **(required)** — caller identity.
+- `--to <agent>` **(required)** — target worker.
+- `--scope <project|global>` — channel scope.
+- `--stdin` / `--text-file <path>` / `[text]` — replacement instruction body.
+
+The appended event has `kind: "interrupt"` — downstream `wait` / `messages`
+filters can subscribe with `--kind interrupt` to react to redirections (e.g.
+to log the rerouting, or to gate other workers behind a coordinator's
+correction).
+
+For low-priority hints that should wait for the worker's next turn, send a
+plain tagged message instead:
+
+```bash
+echo "Check this when you reach the next turn." \
+  | trellis channel send impl-task --as dispatcher --to codex-impl \
+      --stdin --tag question
+```
+
+## Hard Interrupt — `kill` + `--resume`
+
+Use `kill` when the worker must stop **now** (e.g. runaway loop, bad
+instructions already in flight, or `interrupt` is not honored by the
+adapter). The supervisor escalates SIGTERM → 8 s grace → SIGKILL; the CLI
+writes a `killed` event when SIGKILL is needed so the event log stays
+truthful.
+
+```bash
+trellis channel kill impl-task --as codex-impl
+trellis channel spawn impl-task --as codex-impl --provider codex \
+  --resume "$(cat ~/.trellis/channels/<bucket>/impl-task/worker.session-id)"
+
+echo "STOP — new instructions: ..." \
+  | trellis channel send impl-task --as dispatcher --to codex-impl --stdin
+```
+
+`kill` flags:
+
+- `--as <agent>` **(required)** — names the worker (positional `<name>` is the channel).
+- `--scope <project|global>`.
+- `--force` — SIGKILL immediately (also kills the inner worker pid).
+
+Side effects: cleans `pid`, `worker-pid`, `config`, `spawnlock` sidecar
+files; keeps `log`, `session-id`, `thread-id` for forensics and resume.
+
+When `interrupt` will not converge, kill + `--resume` is the guaranteed
+redirection path.
+
+## Worker OOM Guard
+
+The OOM guard prevents orphaned/idle workers from accumulating and exhausting
+host resources. It runs at every `spawn` and enforces two policies per
+project bucket:
+
+- **Idle TTL** — sweep workers whose last activity is older than the
+  configured threshold (default `5m`; `0` disables).
+- **Live-worker budget** — refuse the new spawn if more than N workers are
+  already alive in the same project bucket (default `6`; `0` disables).
+
+Precedence (highest first):
+
+1. CLI flags: `--idle-timeout`, `--max-live-workers` on `spawn`.
+2. Environment variables: `TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT`,
+   `TRELLIS_CHANNEL_MAX_LIVE_WORKERS`.
+3. `.trellis/config.yaml` under `channel.worker_guard`.
+4. Built-in defaults (`5m`, `6`).
+
+Cleanup notices are written to stderr at spawn time so operators can see which
+idle workers were swept and why a new spawn was rejected. The guard does not
+touch ephemeral / `channel run` workers any differently — they are subject to
+the same idle TTL and budget.
+
+To audit current state, list workers via `channel list` (the `WORKERS`
+column) and inspect per-channel `pid` / `worker-pid` sidecar files under
+`~/.trellis/channels/<bucket>/<channel>/`.
+
+## Worker Inbox APIs
+
+The inbox is the channel surface workers wake on. Routing is controlled by
+two knobs:
+
+- **Inbox policy** (`spawn --inbox-policy`):
+  - `explicitOnly` (default) — worker only wakes on `send --to <worker>` or
+    `interrupt --to <worker>`.
+  - `broadcastAndExplicit` — also wakes on broadcasts (`send` with no `--to`).
+- **Delivery mode** (`send --delivery-mode`):
+  - `appendOnly` — append the event regardless of worker state.
+  - `requireKnownWorker` — fail if no worker named in `--to` was ever spawned.
+  - `requireRunningWorker` — fail if the named worker is not currently alive.
+
+Stricter delivery modes prevent silent message loss when callers expect a
+running peer.
+
+Inbox-relevant subcommands:
+
+- `send <channel> [text]` — append a `message` event.
+  - `--as <agent>` **(required)** — author.
+  - `--to <agents>` — CSV; one → string, many → array; broadcast if omitted.
+  - `--stdin` / `--text-file <path>` / `[text]` — body source.
+  - `--delivery-mode <appendOnly|requireKnownWorker|requireRunningWorker>`.
+- `interrupt <channel> [text]` — soft-interrupt redirect (see above).
+- `wait <channel>` — block until matching events arrive.
+  - `--as <agent>` **(required)** — `self` for filter context.
+  - `--from <agents>` — CSV authors.
+  - `--kind <kind[,kind...]>` — CSV (OR semantics); supports `interrupt`,
+    `done`, `progress`, etc.
+  - `--to <target>` — defaults to own agent (broadcast + explicit-to-me).
+  - `--include-progress` — also wake on progress events.
+  - `--all` — require every `--from` agent to match (timeout → exit **124**).
+  - `--timeout <duration>` — `30s` / `2m` / `1h` / `1000ms`.
+- `messages <channel>` — view / filter / follow the event stream.
+  - `--follow` to tail, `--kind` / `--from` / `--to` to filter, `--raw` for
+    JSON-per-line, `--no-progress` to hide progress noise.
+
+A typical dispatcher loop:
+
+```bash
+# 1. Wake the worker.
+echo "Run the failing test and report." \
+  | trellis channel send impl-task --as dispatcher --to codex-impl --stdin \
+      --delivery-mode requireRunningWorker
+
+# 2. Block until it finishes.
+trellis channel wait impl-task --as dispatcher \
+  --from codex-impl --kind done,error --timeout 30m
+
+# 3. Read the final answer.
+trellis channel messages impl-task --from codex-impl --last 1 --raw
+```
+
+All event-emitting subcommands (`send`, `interrupt`, `post`, `context add` /
+`delete`, `title set` / `clear`, `thread rename`) print the appended event as
+a single JSON line on stdout, making the inbox layer easy to script against.

package/dist/templates/common/bundled-skills/trellis-channel/references/workflows.md

@@ -0,0 +1,128 @@
+# Workflows
+
+Use these patterns by intent. Prefer durable channels for multi-round work and
+`channel run` for one-shot questions.
+
+## Pattern A: Multi-round Brainstorm
+
+Use when the user says "和 codex/claude 讨论一下", "brainstorm", or "拉一个 agent
+进来一起看".
+
+```bash
+trellis channel create brainstorm-storage-layer --by main \
+  --task .trellis/tasks/05-XX-storage-adapter
+
+trellis channel spawn brainstorm-storage-layer \
+  --agent architect --provider codex \
+  --file .trellis/tasks/05-XX-storage-adapter/prd.md \
+  --file .trellis/tasks/05-XX-storage-adapter/design.md \
+  --as cx-arch --timeout 30m
+
+trellis channel send brainstorm-storage-layer \
+  --as main --to cx-arch --text-file /tmp/brainstorm-r1.md
+
+trellis channel wait brainstorm-storage-layer \
+  --as main --kind done --from cx-arch --timeout 10m
+```
+
+Do not stop after one answer. Read the answer, identify vague areas, send a
+new probe, and repeat until the result is executable.
+
+Minimum round structure:
+
+1. Direction split: should this live in an existing mechanism or a new one?
+2. MVP boundary: v1, v2, and what would force v2 back into v1.
+3. Data contract: events, schema, metadata, state source of truth, compatibility.
+4. CLI / UX contract: command names, flags, errors, defaults, ambiguity.
+5. Cross-layer risk and tests: shared helpers, drift points, release-blocking tests.
+
+Optional rounds:
+
+- Operations: logs, debugging, stuck workers, kill/restart, recovery.
+- Migration/release: breaking status, manifest, changelog, docs-site.
+- Opposition review: ask the peer agent to argue against the current plan.
+
+Every probe should request concrete file paths, commands, schema, rejected
+alternatives, and release-blocking issues. Reject hedging when a decision is
+needed.
+
+## Pattern B: Implement / Check Agent
+
+Use when the user asks to dispatch implementation or review work.
+
+```bash
+TASK=.trellis/tasks/05-12-foo
+trellis channel create cr-foo --task "$TASK" --by main
+
+trellis channel spawn cr-foo \
+  --agent check \
+  --jsonl "$TASK/check.jsonl" \
+  --file "$TASK/prd.md" \
+  --file "$TASK/design.md" \
+  --file "$TASK/implement.md" \
+  --cwd "$PWD" --timeout 15m
+
+trellis channel send cr-foo --as main --to check --text-file /tmp/cr-brief.md
+trellis channel wait cr-foo --as main --kind done --from check --timeout 15m
+trellis channel messages cr-foo --kind message --from check --tag final_answer
+```
+
+For implement work, use `--agent implement` and send an implementation brief.
+For check work, include the exact diff scope, relevant specs, and validation
+already run.
+
+## Pattern C: Parallel Reviewers
+
+Use one channel and distinct worker names.
+
+```bash
+trellis channel create cr-feature --by main --ephemeral
+
+trellis channel spawn cr-feature --agent check \
+  --jsonl "$TASK/check.jsonl" --file "$TASK/prd.md" --file "$TASK/design.md" \
+  --timeout 15m
+
+trellis channel spawn cr-feature --agent check --provider codex --as check-cx \
+  --jsonl "$TASK/check.jsonl" --file "$TASK/prd.md" --file "$TASK/design.md" \
+  --timeout 15m
+
+trellis channel send cr-feature --as main --to check --text-file /tmp/cr-brief.md
+trellis channel send cr-feature --as main --to check-cx --text-file /tmp/cr-brief.md
+trellis channel wait cr-feature --as main --kind done --from check,check-cx --all --timeout 15m
+```
+
+`--all` means every listed worker must emit a matching event.
+
+## Pattern D: One-shot Worker
+
+```bash
+trellis channel run --provider codex --message "say hi in 3 words" --timeout 1m
+trellis channel run --agent plan --message-file /tmp/plan-question.md --timeout 10m
+```
+
+On success, `run` removes the ephemeral channel. On error/timeout/killed, it
+keeps the channel and prints the path for inspection.
+
+## Pattern E: Forum Channel
+
+Use for issue forums, topic-style feedback, release todos, agent findings, and
+internal changelogs. Read `forum.md` for the full model.
+
+## Pattern F: Take Over Existing Thread
+
+If the user gives a forum/thread name, restore context yourself:
+
+```bash
+trellis channel forum <board> --scope global
+trellis channel thread <board> <thread> --scope global --raw
+trellis channel context list <board> --scope global --thread <thread>
+trellis channel messages <board> --scope global --raw --thread <thread>
+```
+
+Output a constraint summary, not a transcript dump:
+
+- user-level problem
+- context files that affect this repo
+- current-version versus future-version requirements
+- whether current code/design satisfies it
+- next action or comment to append

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

@@ -1,73 +1,85 @@
 ---
 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, or workflows generated by trellis init."
+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 (trellis-channel, trellis-session-insight, trellis-spec-bootstrap) and bundled-skill 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}.md` runtime definitions. Second, cross-session memory: `trellis mem list | search | context | extract | projects` reads raw Claude Code and Codex JSONL already on disk, slices by `--phase brainstorm|implement|all`, and never uploads anything. Third, a dual-package npm release: `@mindfoldhq/trellis` (CLI) and `@mindfoldhq/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.
+
 The default operating scope is local files in the user project:
 
-- `.trellis/`: workflow, config, tasks, spec, workspace, scripts, and runtime state.
-- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.windsurf/`, and similar directories.
+- `.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/`, `.windsurf/`, 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.
 - Shared skill layer: `.agents/skills/`.
+- User-owned channel store outside the project tree: `~/.trellis/channels/<project>/<channel>/events.jsonl`.
+- Raw platform conversation logs queryable via `trellis mem`: `~/.claude/projects/` and `~/.codex/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`.
+Do not assume the user has the Trellis source repository. Do not default to modifying the global npm install directory or `node_modules` — both `@mindfoldhq/trellis` and `@mindfoldhq/trellis-core` ship as published packages sharing one version and one git tag per release.
 
 ## How To Use
 
 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 user wants to change behavior, read `references/customize-local/overview.md`, then open the specific customization topic.
-4. Before editing, read the actual files in the user project and treat local content as authoritative.
+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.
+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.
 
 ## References
 
 ### Local Architecture
 
-- `references/local-architecture/overview.md`: The three-layer local Trellis architecture and customization principles.
-- `references/local-architecture/generated-files.md`: Files generated by `trellis init` and their customization boundaries.
-- `references/local-architecture/workflow.md`: Phases, routing, and workflow-state blocks in `.trellis/workflow.md`.
-- `references/local-architecture/task-system.md`: Task directories, active tasks, JSONL context, and task runtime.
-- `references/local-architecture/spec-system.md`: How `.trellis/spec/` is organized and injected.
-- `references/local-architecture/workspace-memory.md`: `.trellis/workspace/`, journals, and cross-session memory.
-- `references/local-architecture/context-injection.md`: Hooks, sub-agent preludes, and context injection paths.
+- `references/local-architecture/overview.md`: The layered local Trellis architecture (workflow / persistence / platform / channel 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/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 `@mindfoldhq/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-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`) and how `getBundledSkillTemplates()` ships them to every platform skill root.
 
 ### Platform Files
 
-- `references/platform-files/overview.md`: How shared `.trellis/` files relate to platform directories.
-- `references/platform-files/platform-map.md`: Platform directories and paths for skills, agents, hooks, and extensions.
-- `references/platform-files/hooks-and-settings.md`: How settings/config files, hooks, plugins, and extensions connect to Trellis.
-- `references/platform-files/agents.md`: Local file responsibilities for `trellis-research`, `trellis-implement`, and `trellis-check`.
+- `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/platform-map.md`: Platform directories and paths for skills, agents, hooks, and extensions across all 15 supported platforms including 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.*` 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/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, and workflow-state.
-- `references/customize-local/change-task-lifecycle.md`: Change task creation, status, archive behavior, and hooks.
-- `references/customize-local/change-context-loading.md`: Change how tasks, specs, journals, and hook context are loaded.
-- `references/customize-local/change-hooks.md`: Change platform hooks, settings, and shell session bridges.
-- `references/customize-local/change-agents.md`: Change research, implement, and check agent behavior.
-- `references/customize-local/change-skills-or-commands.md`: Add or modify local skills, commands, prompts, and workflows.
-- `references/customize-local/change-spec-structure.md`: Adjust the project spec structure under `.trellis/spec/`.
+- `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-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-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.
-- `.trellis/config.yaml` is the project-level Trellis configuration and task hook configuration entry point.
-- `.trellis/spec/` stores the user's project-specific coding conventions and design constraints.
-- `.trellis/tasks/` stores task PRDs, technical notes, research files, and JSONL context.
-- `.trellis/workspace/` stores developer journals and cross-session memory.
-- Platform settings/config files decide which hooks, agents, skills, commands, prompts, and workflows actually run.
+- `.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`), channel worker guard (`channel.worker_guard.idle_timeout` / `max_live_workers`), 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/workspace/` stores **deliberately written** developer journals. Raw cross-session dialogue is **not** stored here — it lives on disk under `~/.claude/projects/` and `~/.codex/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}.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 (`trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`) 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`.
+- 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.
 
 ## Do Not
 
 - 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/@mindfoldhq/trellis` to implement project needs.
-- Do not overwrite user-modified local files with default templates.
-- Do not put team-private project rules into the public `trellis-meta`; put project rules in `.trellis/spec/` or a project-local skill.
-- Do not describe removed historical mechanisms as current Trellis behavior.
+- Do not modify the global npm install directory or `node_modules/@mindfoldhq/trellis` or `node_modules/@mindfoldhq/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 `@mindfoldhq/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 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-skills-or-commands.md

@@ -2,12 +2,20 @@
 
 When the user wants to change AI entry points, auto-trigger rules, or explicit command behavior, edit skills, commands, prompts, or workflows in local platform directories.
 
+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`.
+
+The remainder of this file uses "skill" for the local file; the override and conflict rules differ between the two cases.
+
 ## Read These Files First
 
 1. `.trellis/workflow.md`
 2. Target platform skill/command/prompt/workflow directory
 3. Related agent or hook files
 4. Whether project rules already exist in `.trellis/spec/`
+5. `.trellis/.template-hashes.json` — confirms whether the skill you are about to edit is upstream-owned (entry present) or project-local (entry absent)
 
 ## Which Entry Type To Choose
 
@@ -15,7 +23,9 @@ When the user wants to change AI entry points, auto-trigger rules, or explicit c
 | --- | --- |
 | 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. |
+| Team project conventions | Prefer `.trellis/spec/` or a project-local skill — never a bundled skill directory. |
+| Tweak a bundled skill (`trellis-meta` et al.) for the user's own project | Create a project-local sibling skill (different name) that overrides intent, or edit `.trellis/spec/`. Edits inside the bundled skill directory survive only until the next `trellis update` and will need a "keep" choice each time. |
+| Contribute the change back upstream | Edit `packages/cli/src/templates/common/bundled-skills/<name>/` in the Trellis CLI repo, not the deployed copy. |
 | Change Trellis flow semantics | Synchronize `.trellis/workflow.md`. |
 
 ## Modify A Skill
@@ -38,6 +48,20 @@ description: "Use when customizing this project's deployment workflow and releas
 
 Do not write vague descriptions such as "helpful project skill"; they can trigger incorrectly.
 
+### Bundled vs. Project-Local
+
+The same directory shape is used by two very different ownership models:
+
+| Aspect | Bundled (`trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`) | 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 |
+
+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/`.
+
 ## Modify A Command/Prompt/Workflow
 
 Explicit entry points should state:
@@ -57,22 +81,42 @@ If a command only repeats workflow rules, prefer making it reference/read `.trel
 | Cursor | `.cursor/skills/`, `.cursor/commands/` |
 | OpenCode | `.opencode/skills/`, `.opencode/commands/` |
 | Codex | `.agents/skills/`, `.codex/skills/` |
+| Gemini CLI | `.agents/skills/`, `.gemini/commands/` |
+| Kiro | `.kiro/skills/` |
+| Qoder | `.qoder/skills/`, `.qoder/commands/` |
+| CodeBuddy | `.codebuddy/skills/`, `.codebuddy/commands/` |
 | GitHub Copilot | `.github/skills/`, `.github/prompts/` |
+| Factory Droid | `.factory/skills/`, `.factory/commands/` |
+| Pi Agent | `.pi/skills/` |
+| Reasonix | `.reasonix/skills/` (no separate commands dir; slash commands built into the platform) |
 | Kilo / Antigravity / Windsurf | 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.
+
 ## Add A Project-Local Skill
 
-If the user wants to document team-private customizations, create a project-local skill, for example:
+If the user wants to document team-private customizations, create a project-local skill — never put project-private content into a bundled skill directory, since `trellis update` will overwrite it.
 
 ```text
 .claude/skills/project-trellis-local/
 └── SKILL.md
 ```
 
-For multi-platform projects, add equivalent versions in each platform skill directory, or use `.agents/skills/` on platforms that support the shared layer.
+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`.
 
 ## 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.
+- 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.