@baoanaz/cviauto 0.6.5

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
+cviauto channel create impl-task --by dispatcher --cwd /path/to/repo
+cviauto channel spawn impl-task --provider codex --as codex-impl --timeout 30m
+
+echo "Implement the schema for table X per .cviauto/.../prd.md" \
+  | cviauto channel send impl-task --as dispatcher --to codex-impl --stdin
+
+cviauto 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 `.cviauto/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) — Cviauto 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 `.cviauto/agents/<name>.md`. The card name must
+match `[A-Za-z0-9._-]+`. The default Cviauto install ships two cards:
+
+- `.cviauto/agents/check.md` — code-quality reviewer.
+- `.cviauto/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 .cviauto/agents
+sed -n '1,100p' .cviauto/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 Cviauto 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=.cviauto/tasks/05-13-example
+cviauto 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
+cviauto channel spawn cr-feature --agent check --as check-claude
+cviauto channel spawn cr-feature --agent check --provider codex --as check-cx
+
+cviauto 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" \
+  | cviauto 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." \
+  | cviauto 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
+cviauto channel kill impl-task --as codex-impl
+cviauto channel spawn impl-task --as codex-impl --provider codex \
+  --resume "$(cat ~/.cviauto/channels/<bucket>/impl-task/worker.session-id)"
+
+echo "STOP — new instructions: ..." \
+  | cviauto 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. `.cviauto/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
+`~/.cviauto/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." \
+  | cviauto channel send impl-task --as dispatcher --to codex-impl --stdin \
+      --delivery-mode requireRunningWorker
+
+# 2. Block until it finishes.
+cviauto channel wait impl-task --as dispatcher \
+  --from codex-impl --kind done,error --timeout 30m
+
+# 3. Read the final answer.
+cviauto 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
+cviauto channel create brainstorm-storage-layer --by main \
+  --task .cviauto/tasks/05-XX-storage-adapter
+
+cviauto channel spawn brainstorm-storage-layer \
+  --agent architect --provider codex \
+  --file .cviauto/tasks/05-XX-storage-adapter/prd.md \
+  --file .cviauto/tasks/05-XX-storage-adapter/design.md \
+  --as cx-arch --timeout 30m
+
+cviauto channel send brainstorm-storage-layer \
+  --as main --to cx-arch --text-file /tmp/brainstorm-r1.md
+
+cviauto 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=.cviauto/tasks/05-12-foo
+cviauto channel create cr-foo --task "$TASK" --by main
+
+cviauto 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
+
+cviauto channel send cr-foo --as main --to check --text-file /tmp/cr-brief.md
+cviauto channel wait cr-foo --as main --kind done --from check --timeout 15m
+cviauto 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
+cviauto channel create cr-feature --by main --ephemeral
+
+cviauto channel spawn cr-feature --agent check \
+  --jsonl "$TASK/check.jsonl" --file "$TASK/prd.md" --file "$TASK/design.md" \
+  --timeout 15m
+
+cviauto 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
+
+cviauto channel send cr-feature --as main --to check --text-file /tmp/cr-brief.md
+cviauto channel send cr-feature --as main --to check-cx --text-file /tmp/cr-brief.md
+cviauto 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
+cviauto channel run --provider codex --message "say hi in 3 words" --timeout 1m
+cviauto 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
+cviauto channel forum <board> --scope global
+cviauto channel thread <board> <thread> --scope global --raw
+cviauto channel context list <board> --scope global --thread <thread>
+cviauto 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

@@ -0,0 +1,85 @@
+---
+name: cviauto-meta
+description: "Understand and customize the local Cviauto architecture inside a user project. Use when modifying .cviauto plus platform hooks, settings, agents, skills, commands, prompts, workflows, the channel runtime (cviauto channel), bundled runtime agents under .cviauto/agents/, selectable workflow templates, registry-backed spec refresh, cross-session memory (cviauto mem) generated by cviauto init, or AI-facing bundled skills (cviauto-channel, cviauto-session-insight, cviauto-spec-bootstrap) and bundled-skill auto-dispatch flow."
+---
+
+# Cviauto Meta
+
+This skill is for local Cviauto users who have already run `cviauto init` in a project. After reading it, an AI should understand the Cviauto architecture, operating model, and customization entry points inside that user project, then modify the generated `.cviauto/` and platform directory files according to the user's request.
+
+Cviauto v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow / persistence / platform model. First, a multi-agent collaboration runtime: `cviauto channel` coordinates multiple AI worker processes through project-scoped JSONL event logs at `~/.cviauto/channels/<project>/<channel>/events.jsonl`, with worker OOM guard, forum/thread channels, durable idempotency keys, and bundled `.cviauto/agents/{check,implement}.md` runtime definitions. Second, cross-session memory: `cviauto 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: `@baoanaz/cviauto` (CLI) and `@baoanaz/cviauto-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:
+
+- `.cviauto/`: 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/`, 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: `~/.cviauto/channels/<project>/<channel>/events.jsonl`.
+- Raw platform conversation logs queryable via `cviauto mem`: `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` (OpenCode adapter degraded for the v0.6 line).
+
+Do not assume the user has the Cviauto source repository. Do not default to modifying the global npm install directory or `node_modules` — both `@baoanaz/cviauto` and `@baoanaz/cviauto-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 Cviauto 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 `.cviauto/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 layered local Cviauto architecture (workflow / persistence / platform / channel runtime) and customization principles.
+- `references/local-architecture/generated-files.md`: Files generated by `cviauto init` and their customization boundaries, including `.cviauto/agents/`.
+- `references/local-architecture/workflow.md`: Phases, routing, workflow-state blocks, and selectable workflow templates (`native`, `tdd`, `channel-driven-subagent-dispatch`, marketplace) in `.cviauto/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 `.cviauto/spec/` is organized, injected, and refreshed from a `registry.spec` source.
+- `references/local-architecture/workspace-memory.md`: `.cviauto/workspace/` journals plus `cviauto mem` cross-session recall and the `@baoanaz/cviauto-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`: `cviauto channel` subcommands, project-scoped event store, forum/thread channels, worker OOM guard, durable idempotency, and bundled `.cviauto/agents/` runtime agents.
+- `references/local-architecture/bundled-skills.md`: Auto-dispatched bundled skills (`cviauto-meta`, `cviauto-spec-bootstrap`, `cviauto-session-insight`) and how `getBundledSkillTemplates()` ships them to every platform skill root.
+
+### Platform Files
+
+- `references/platform-files/overview.md`: How shared `.cviauto/` 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 Cviauto; covers `channel.worker_guard.*` and `codex.dispatch_mode`.
+- `references/platform-files/agents.md`: Per-platform `cviauto-research` / `cviauto-implement` / `cviauto-check` sub-agent files plus bundled `.cviauto/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, 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 `cviauto 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 `.cviauto/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
+
+- `.cviauto/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 `cviauto init` time and can be re-selected via `cviauto workflow --template <id>`. Missing `.cviauto/agents/<name>.md` files referenced by the active template trigger a non-blocking stderr warning pointing at `cviauto update`.
+- `.cviauto/config.yaml` is the project-level Cviauto 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`).
+- `.cviauto/spec/` stores the user's project-specific coding conventions and design constraints. When `registry.spec` is set, files are refreshed by `cviauto update`; local edits surface as "modified by user" conflicts in `.cviauto/.template-hashes.json`.
+- `.cviauto/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 `.cviauto/tasks/archive/**`.
+- `.cviauto/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 `cviauto mem search|extract|context`. The bundled `cviauto-session-insight` skill teaches when to reach for `mem`.
+- `.cviauto/agents/{check,implement}.md` are bundled, platform-agnostic channel runtime agent definitions loaded by `cviauto channel spawn --agent <name>`. Editable; `cviauto update` backfills missing ones. Editing the per-platform `cviauto-implement.md` / `cviauto-check.md` does **not** change channel-runtime worker behavior.
+- `~/.cviauto/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 `.cviauto/`.
+- Bundled multi-file skills (`cviauto-meta`, `cviauto-spec-bootstrap`, `cviauto-session-insight`, `cviauto-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 `cviauto 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.
+- `.cviauto/.template-hashes.json` and `.cviauto/.runtime/` are management/runtime state files. Confirm necessity before editing them.
+
+## Do Not
+
+- Do not treat Cviauto upstream source code as the default target for local customization.
+- Do not modify the global npm install directory or `node_modules/@baoanaz/cviauto` or `node_modules/@baoanaz/cviauto-core` to implement project needs; both packages ship in lockstep.
+- Do not overwrite user-modified local files with default templates; check `.cviauto/.template-hashes.json` first and prefer `.new` sidecar files over destructive overwrites.
+- Do not put team-private project rules into any public bundled skill (`cviauto-meta`, `cviauto-spec-bootstrap`, `cviauto-session-insight`, `cviauto-channel`); put project rules in `.cviauto/spec/`, a project-local skill, the current task, or the workspace journal — `cviauto update` will overwrite anything inside a bundled skill directory.
+- Do not hand-edit `~/.cviauto/channels/<project>/<channel>/events.jsonl`; sequence numbers are assigned under a file lock and replay-safe writes go through the `cviauto channel` CLI or the `@baoanaz/cviauto-core/channel` SDK.
+- Do not edit `.claude/agents/cviauto-implement.md` (or any other per-platform sub-agent file) when the goal is to change channel runtime worker behavior — edit `.cviauto/agents/<name>.md` instead.
+- Do not describe removed or never-shipped mechanisms as current Cviauto behavior; cross-check against the local `.cviauto/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/add-project-local-conventions.md

@@ -0,0 +1,83 @@
+# Add Project-Local Conventions
+
+Often the user does not need to change Cviauto mechanics; they need local AI to understand their team's conventions. In that case, prefer `.cviauto/spec/` or a project-local skill instead of editing `cviauto-meta`.
+
+## Where To Put Things
+
+| Content type | Location |
+| --- | --- |
+| Rules code must follow | `.cviauto/spec/<layer>/` |
+| Cross-layer thinking methods | `.cviauto/spec/guides/` |
+| AI capability for a project-specific flow | Platform-local skill |
+| One-off task material | `.cviauto/tasks/<task>/` |
+| Session summary | `.cviauto/workspace/<developer>/journal-N.md` |
+
+## Create A Project-Local Skill
+
+If the user wants AI to know "how this project customizes Cviauto," create a local skill:
+
+```text
+.claude/skills/cviauto-local/
+└── SKILL.md
+```
+
+Example:
+
+```md
+---
+name: trellis-local
+description: "Project-local Cviauto customizations for this repository. Use when changing this project's Cviauto workflow, hooks, local agents, or team-specific conventions."
+---
+
+# Cviauto Local
+
+## Local Scope
+
+This skill documents this repository's Cviauto customizations only.
+
+## Custom Workflow Rules
+
+- ...
+
+## Local Hook Changes
+
+- ...
+
+## Local Agent Changes
+
+- ...
+```
+
+For multi-platform projects, place equivalent versions in other platform skill directories, or use `.agents/skills/` for platforms that support the shared layer.
+
+## Write To `.cviauto/spec/`
+
+If the content is a coding convention, write it to spec. Examples:
+
+```text
+.cviauto/spec/backend/error-handling.md
+.cviauto/spec/frontend/components.md
+.cviauto/spec/guides/cross-platform-thinking-guide.md
+```
+
+After writing it, update the corresponding `index.md` so AI can find the new rule from the entry point.
+
+## Make The Current Task Use New Conventions
+
+After writing a spec, add it to the current task context:
+
+```bash
+python3 ./.cviauto/scripts/task.py add-context <task> implement ".cviauto/spec/backend/error-handling.md" "Error handling conventions"
+python3 ./.cviauto/scripts/task.py add-context <task> check ".cviauto/spec/backend/error-handling.md" "Review error handling"
+```
+
+## Do Not Store Project-Private Rules In `cviauto-meta`
+
+`cviauto-meta` is a public skill for understanding Cviauto architecture and local customization entry points. Put project-private content in:
+
+- `.cviauto/spec/`
+- a project-local skill
+- the current task
+- workspace journal
+
+This prevents future updates to Cviauto's built-in `cviauto-meta` from overwriting the team's own conventions.

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

@@ -0,0 +1,56 @@
+# Change Local Agents
+
+When the user wants to change `cviauto-research`, `cviauto-implement`, or `cviauto-check` behavior, edit platform agent files in the user project.
+
+## Read These Files First
+
+1. Target platform agent directory
+2. `.cviauto/workflow.md` Phase 2 / research routing
+3. Current task `prd.md`
+4. Current task `implement.jsonl` / `check.jsonl`
+5. Relevant hook or agent prelude
+
+## Common Paths
+
+| Platform | Path |
+| --- | --- |
+| Claude Code | `.claude/agents/cviauto-*.md` |
+| Cursor | `.cursor/agents/cviauto-*.md` |
+| OpenCode | `.opencode/agents/cviauto-*.md` |
+| Codex | `.codex/agents/cviauto-*.toml` |
+| Kiro | `.kiro/agents/cviauto-*.json` |
+| Gemini CLI | `.gemini/agents/cviauto-*.md` |
+| Qoder | `.qoder/agents/cviauto-*.md` |
+| CodeBuddy | `.codebuddy/agents/cviauto-*.md` |
+| Factory Droid | `.factory/droids/cviauto-*.md` |
+| Pi Agent | `.pi/agents/cviauto-*.md` |
+| Reasonix | `.reasonix/skills/cviauto-*/SKILL.md` (subagent frontmatter) |
+| ZCode | `.zcode/cli/agents/cviauto-*.md` |
+
+Use the actual paths in the user project as authoritative.
+
+## Common Needs
+
+| Need | Which agent to edit |
+| --- | --- |
+| Research must write files, not only reply in chat | `cviauto-research` |
+| Certain local specs must be read before implementation | `cviauto-implement` + `implement.jsonl` configuration rules |
+| Specific commands must run during checking | `cviauto-check` |
+| Agent must not modify certain directories | The corresponding agent's write boundary instructions |
+| Agent output format must be fixed | The corresponding agent's final/reporting instructions |
+
+## Modification Principles
+
+1. **Preserve role boundaries**: research investigates and persists; implement writes implementation; check reviews and fixes.
+2. **Do not hard-code project specs into agents**: long-term specs belong in `.cviauto/spec/`; agents are responsible for reading them.
+3. **Make read order explicit**: active task -> PRD -> info -> JSONL -> spec/research.
+4. **Make write boundaries explicit**: which directories may be written and which may not.
+5. **Synchronize across platforms**: when the user configured multiple platforms, decide whether to change only the current platform or all platform agents.
+
+## Agent Pull Platforms
+
+If an agent file contains a prelude for "read task/context after startup," do not remove those steps when editing. Otherwise the agent will work only from chat context and bypass Cviauto's core mechanism.
+
+## Hook Push Platforms
+
+If context is injected by a hook, the agent file should still retain responsibility boundaries. Do not remove PRD/spec requirements from the agent just because a hook injects context.