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

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

@@ -1,549 +0,0 @@
-# Command Reference
-
-Authoritative current command reference for `trellis channel` subcommands,
-validated against the source in `packages/cli/src/commands/channel/`
-(`index.ts` Commander wiring and each subcommand handler).
-
-Every subcommand accepts `--scope <project|global>` unless noted; `project`
-is the default and resolves against the current cwd's project bucket.
-
-## Top-level
-
-```
-trellis channel <subcommand>
-```
-
-> Multi-agent collaboration runtime — spawn / coordinate / interrupt worker
-> agents through a shared event log.
-
----
-
-## Create / List
-
-### `create <name>`
-
-```bash
-trellis channel create <name>
-  [--scope project|global]                # default: project
-  [--type chat|forum]                     # default: chat
-  [--task <path>]                         # associated Trellis task dir
-  [--project <slug>]
-  [--labels a,b,c]
-  [--description <text>]                  # stable channel description
-  [--context-file <abs-path>] ...         # repeatable
-  [--context-raw  <text>]      ...        # repeatable
-  [--linked-context-file <abs-path>]      # [deprecated alias]
-  [--linked-context-raw  <text>]          # [deprecated alias]
-  [--cwd <path>]                          # recorded in create event
-  [--by <agent>]                          # default: main
-  [--owner-session <id>]                  # opaque main Codex session owner
-  [--force]                               # overwrite existing channel
-  [--ephemeral]                           # hide from default list, prunable
-```
-
-Behavior:
-
-- Appends a `create` event; immutable `type` (cannot mutate forum↔chat after).
-- `--ephemeral` channels are hidden from `channel list` by default and are
-  the sweep target for `channel prune --ephemeral`.
-- `--linked-context-*` are folded into `--context-*`; emit a deprecation
-  notice when used.
-
-### `list`
-
-```bash
-trellis channel list
-  [--scope project|global]
-  [--json]
-  [--project <slug>]                      # substring match on task field
-  [--all]                                 # include ephemeral (suffix '*')
-  [--all-projects]                        # scan every project bucket
-  [--owner-session <id>]                  # exact immutable owner match
-```
-
-Behavior:
-
-- Default scope: current cwd's project. `--all-projects` scans every bucket.
-- Pretty mode prints `NAME WORKERS EVENTS LAST KIND TYPE TASK`, sorted by
-  recency, with a footer noting hidden ephemeral count.
-- `--json` switches to a JSON array.
-
----
-
-## Chat Messages
-
-### `send <name> [text]`
-
-```bash
-trellis channel send <name> [text]
-  --as <agent>                            # REQUIRED — author
-  [--scope project|global]
-  [--to <agents,csv>]                     # default: broadcast
-  [--stdin | --text-file <path>]          # body from stdin or file
-  [--delivery-mode appendOnly|requireKnownWorker|requireRunningWorker]
-```
-
-Behavior:
-
-- Body precedence: positional `[text]` → `--stdin` → `--text-file`.
-- `--to` with one entry stores a string; multiple stores an array; omitted
-  means broadcast.
-- `--delivery-mode` selects targeted-delivery validation:
-  - `appendOnly` (default-ish — just record),
-  - `requireKnownWorker` (the named target must have a `spawned` event),
-  - `requireRunningWorker` (the worker must currently be live).
-- Prints the appended event as one JSON line on stdout.
-
-> **Note:** `send` has **no** `--tag` and **no** `--kind` flag. See
-> [`tag-vs-kind`](#tag-vs-kind--how-event-shape-is-actually-controlled) below.
-
-### `messages <name>`
-
-```bash
-trellis channel messages <name>
-  [--scope project|global]
-  [--raw]                                 # one JSON event per line
-  [--follow]                              # stream new events
-  [--last <N>]                            # last N matching events
-  [--since <seq>]                         # seq > N
-  [--kind <kind>]                         # one of CHANNEL_EVENT_KINDS
-  [--from <csv>]                          # author filter
-  [--to <target>]                         # routing target filter
-  [--thread <key>]                        # forum-only
-  [--action <thread-action>]              # forum-only
-  [--no-progress]                         # hide progress events
-```
-
-Behavior:
-
-- Auto-detects forum channels: with no filters it renders the thread board
-  instead of the event stream. `--thread` / `--action` are forum-only and
-  error against chat channels.
-- `--kind` is validated against `CHANNEL_EVENT_KINDS` (single value, not
-  CSV — that's the `wait` side).
-
-### `barrier <name>`
-
-```bash
-trellis channel barrier <name>
-  [--scope project|global]
-```
-
-Prints the channel's current durable event sequence as one integer. It does not
-append an event. Capture it after `create` and before an operation that can
-emit the event you intend to wait for, then pass it to `wait --after-seq`.
-
-### `wait <name>`
-
-```bash
-trellis channel wait <name>
-  --as <agent>                            # REQUIRED — self for filter ctx
-  [--scope project|global]
-  [--timeout <Ns|Nm|Nh|Nms>]              # parsed by parseDuration
-  [--after-seq <integer>]                 # replay only events after barrier
-  [--from <a,b>]                          # author CSV
-  [--kind <k1,k2>]                        # CSV, OR semantics
-  [--thread <key>]                        # forum filter
-  [--action <thread-action>]              # forum filter
-  [--to <target>]                         # default: own agent (broadcast + me)
-  [--include-progress]                    # also wake on progress events
-  [--all]                                 # require every --from to match
-```
-
-Behavior:
-
-- Streams matching events as JSON, one per line.
-- Default `--to` filter is the caller's own agent (broadcast events still
-  match — broadcast + explicit-to-me).
-- `--all` requires `--from` and blocks until every listed agent has produced
-  a matching event.
-- Without `--after-seq`, the command captures its current event sequence before
-  constructing its watcher and ignores prior events. With `--after-seq`, it
-  replays matching events whose sequence is greater than that supplied barrier.
-- **Timeout exits 124** and prints `timeout: still waiting on ...` to stderr
-  when `--all` was in play.
-
-### `workers <name>`
-
-```bash
-trellis channel workers <name>
-  [--scope project|global]
-  [--project-key <key>]                   # project bucket when names collide
-  [--include-terminal]
-  [--json]
-```
-
-Reads the durable worker projection from Trellis core. Without
-`--include-terminal`, only non-terminal workers are shown. `--json` is the
-machine-readable form for coordinator recovery and disposition checks. This
-command includes the ordered, deduplicated `sessionIds` observed for each
-worker. It does not inspect PID sidecars and does not poll.
-
-### `task progress`
-
-```bash
-trellis task progress
-  [--json]
-```
-
-Counts task records under the direct active-task directories in
-`.trellis/tasks/`; archived tasks are historical and are excluded from the
-current plan. JSON output is
-`{planning, in_progress, completed, partial}` in the fixed lifecycle order.
-Malformed or unknown active task records set `partial: true` without inventing
-a lifecycle count. Human output uses `planning:in_progress:completed` and adds
-`?` when the projection is partial. With `--json`, update notices are written
-to stderr so stdout remains parseable.
-
----
-
-## tag-vs-kind — how event shape is actually controlled
-
-There is **no `--tag` flag** anywhere in the v0.6.0 channel CLI; `--kind` is
-not a legacy alias for any `--tag` flag.
-
-Concrete model in the current source:
-
-- `--kind` is the only event-type filter, and it is constrained to the
-  trellis-emitted whitelist (`CHANNEL_EVENT_KINDS` in
-  `packages/core/src/channel/internal/store/events.ts`):
-  - `create`, `join`, `leave`, `message`, `thread`, `context`, `channel`,
-    `spawned`, `killed`, `respawned`, `progress`, `done`, `error`,
-    `waiting`, `awake`, `undeliverable`, `interrupt_requested`,
-    `turn_started`, `turn_finished`, `interrupted`, `supervisor_warning`
-  - Passing anything else throws
-    `Invalid --kind '<x>'. Must be one of: …`.
-- `--kind` lives on `wait` (CSV, OR semantics) and `messages` (single
-  value). `send` and `run` cannot emit a custom kind — every `send` writes
-  a `message` event.
-- Mid-turn worker abort is **not** a tag. It is the dedicated
-  `channel interrupt` command, which appends an `interrupt_requested` /
-  `interrupted` pair and provider-level interrupts the worker.
-
-Practical rule for dispatchers waiting on workers:
-
-- Use `--kind done,turn_finished` for "worker finished a turn" — these are
-  system events that the supervisor fires automatically. Do not depend on
-  the worker LLM remembering to emit any custom signal.
-- Use `trellis channel interrupt` (the command) only when you actually want
-  mid-turn abort behavior.
-- Do **not** invent user-side tags as completion signals. There is no
-  `--tag` filter; a worker writing a custom string into its final message
-  is just text inside a `message` event and cannot be matched by `wait`.
-
-Long bodies always go through stdin or a file:
-
-```bash
-trellis channel send T --as A --stdin < /tmp/message.md
-trellis channel send T --as A --text-file /tmp/message.md
-```
-
----
-
-## Interrupt
-
-### `interrupt <name> [text]`
-
-```bash
-trellis channel interrupt <name> [text]
-  --as <agent>                            # REQUIRED — caller
-  --to <agent>                            # REQUIRED — target worker
-  [--scope project|global]
-  [--stdin | --text-file <path>]
-```
-
-Behavior:
-
-- Appends an `interrupt` event with `reason: "user"` and a replacement
-  instruction body; supervisor performs provider-level interrupt where
-  supported (Claude `/interrupt`, Codex turn cancel).
-- Prints the appended event JSON on stdout.
-
----
-
-## Workers
-
-### `spawn <name>`
-
-```bash
-trellis channel spawn <name>
-  [--scope project|global]
-  [--agent <agent-name>]                  # loads .trellis/agents/<name>.md
-  [--provider claude|codex]               # overrides agent file
-  [--as <worker-name>]                    # default: agent name
-  [--cwd <path>]
-  [--model <id>]
-  [--resume <id>]                         # session/thread id resume
-  [--timeout <Ns|Nm|Nh>]                  # auto-kill after duration
-  [--warn-before <Ns|Nm|Nh>]              # supervisor_warning lead time
-                                          # default 5m; subnode role reads config
-  [--file <path>] ...                     # glob, repeatable; inject content
-  [--jsonl <path>] ...                    # Trellis manifest, repeatable
-  [--by <agent>]                          # spawn-event author
-                                          # default: TRELLIS_CHANNEL_AS env or 'main'
-  [--inbox-policy explicitOnly|broadcastAndExplicit]
-                                          # default explicitOnly
-  [--idle-timeout <Ns|Nm|Nh>]             # OOM-guard idle TTL
-                                          # default 5m; subnode role reads config
-  [--max-live-workers <n>]                # spawn-time live-worker budget
-                                          # default 6; subnode role reads config
-```
-
-Behavior:
-
-- Provider is validated against the adapter registry
-  (`packages/cli/src/commands/channel/adapters/`); current: `claude`,
-  `codex`.
-- Worker stays inbox-idle until the first `send --to <worker>`.
-- Records a `spawned` event with `pid`, `provider`, `agent`, `files`,
-  `manifests`.
-- OOM-guard precedence: CLI flag → env var
-  (`TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT`,
-  `TRELLIS_CHANNEL_MAX_LIVE_WORKERS`) →
-  `.trellis/config.yaml#channel.worker_guard` → built-in defaults.
-- `--agent subnode` additionally reads `.trellis/config.yaml#channel.subnode`:
-  its `idle_timeout` / `max_live_workers` sit below explicit flags and the
-  guard environment variables but above `worker_guard`; its `timeout` /
-  `warn_before` supply the role's supervisor defaults. Generated projects set
-  `max_live_workers: 8` without changing ordinary workers' default of `6`.
-
-### `run [name]`
-
-```bash
-trellis channel run [name?]
-  [--agent <name>]
-  [--provider claude|codex]
-  [--as <worker-name>]
-  [--cwd <path>]
-  [--model <id>]
-  [--file <path>] ...                     # repeatable, glob
-  [--jsonl <path>] ...                    # repeatable
-  [--message <text> | --message-file <path> | --stdin]
-  [--timeout <Ns|Nm|Nh>]                  # default 5m; subnode role reads config
-```
-
-Behavior:
-
-- One-shot. Auto-generates `run-<hex>` if `name` omitted.
-- Creates an ephemeral channel (`createMode=run`), spawns a single worker,
-  sends the prompt, waits for `done`, prints the final assistant text to
-  stdout, then removes the channel on success. On failure the channel is
-  kept for inspection and exit code is 1.
-
-> `run` has **no** `--tag` flag. Completion is detected via the `done`
-> event the supervisor emits.
-
-### `kill <name>`
-
-```bash
-trellis channel kill <name>
-  --as <agent>                            # REQUIRED — worker agent name
-  [--scope project|global]
-  [--force]                               # SIGKILL immediately
-```
-
-Behavior:
-
-- Default path: SIGTERM → 8 s grace → SIGKILL escalation; the CLI writes a
-  `killed` event when SIGKILL was needed so the log stays truthful.
-- Cleans `pid`, `worker-pid`, `config`, `spawnlock` sidecar files; keeps
-  `log`, `session-id`, `thread-id` for forensics / resume.
-
-### `rm <name>`
-
-```bash
-trellis channel rm <name>
-  [--scope project|global]
-```
-
-Behavior:
-
-- Kills any live workers, then deletes the entire channel directory.
-- Prints `Removed channel '<name>'`.
-
-### `prune`
-
-```bash
-trellis channel prune
-  [--scope project|global]                # omitted: scan every project
-  [--all | --empty | --idle <Ns|Nm|Nh|Nd> | --ephemeral]   # mutually exclusive
-  [--yes]                                 # actually delete (default: dry-run)
-  [--dry-run]                             # default true; redundant with default
-  [--keep <names,csv>]                    # exclusion list
-```
-
-Behavior:
-
-- Filter flags are mutually exclusive — error otherwise.
-- Default is dry-run; `--yes` flips to real delete.
-- Without `--scope`, scans **every** project bucket (intentional, repo-wide
-  cleanup); with `--scope project|global`, limited to that bucket.
-- Live-worker channels are always skipped regardless of filter.
-- Output: per-candidate line `name  last-ts  (reason)` plus a final summary.
-
----
-
-## Forum Channels
-
-### `post <name> <action>`
-
-```bash
-trellis channel post <name> <action>
-  --as <agent>                            # REQUIRED
-  [--scope project|global]
-  [--thread <key>]                        # required except action=opened
-  [--title <text>]
-  [--text <text> | --stdin | --text-file <path>]
-  [--description <text>]                  # stable thread description
-  [--status <status>]
-  [--labels a,b]                          # REPLACES thread labels
-  [--assignees a,b]                       # REPLACES assignees
-  [--summary <text>]
-  [--context-file <abs-path>] ...
-  [--context-raw  <text>]      ...
-  [--linked-context-file <abs-path>]      # [deprecated alias]
-  [--linked-context-raw  <text>]          # [deprecated alias]
-```
-
-Behavior:
-
-- `<action>` is free-form on the CLI surface; conventional values include
-  `opened`, `comment`, `status`, `labels`, `assignees`, `summary`,
-  `processed`.
-- `action=rename` is rejected — use `thread rename` instead.
-- `--labels` / `--assignees` are replace-semantics, not append.
-- Output: appended event JSON on stdout.
-
-### `forum <name>`
-
-```bash
-trellis channel forum <name>
-  [--scope project|global]
-  [--status <status>]
-  [--raw]
-```
-
-Behavior:
-
-- Lists threads (reduced state). `--status` filters by current thread
-  status. `--raw` prints one JSON per thread.
-
-### `thread <name> <thread>` / `thread rename`
-
-```bash
-trellis channel thread <name> <thread-key>
-  [--scope project|global]
-  [--raw]
-
-trellis channel thread rename <name> <old-thread> <new-thread>
-  --as <agent>                            # REQUIRED
-  [--scope project|global]
-```
-
-Behavior:
-
-- `thread <name> <key>` shows one thread's timeline:
-  header `<thread> [<status>] <title>`, then description / labels /
-  assignees / summary / timeline lines. `--raw` switches to raw events.
-- `thread rename` is the only mutation; `post --action rename` is rejected.
-
----
-
-## Context / Title
-
-### `context add` / `context delete` / `context list`
-
-```bash
-trellis channel context add <name>
-  [--as <agent>]                          # default: main
-  [--scope project|global]
-  [--thread <key>]                        # thread-level instead of channel-level
-  [--file <abs-path>] ...                 # repeatable
-  [--raw <text>]      ...                 # repeatable
-                                          # at least one of --file or --raw
-
-trellis channel context delete <name>
-  [--as <agent>]                          # default: main
-  [--scope project|global]
-  [--thread <key>]
-  [--file <abs-path>] ...
-  [--raw <text>]      ...
-
-trellis channel context list <name>
-  [--scope project|global]
-  [--thread <key>]
-  [--raw]                                 # one JSON entry per line
-```
-
-Behavior:
-
-- `add` / `delete` append a `context` event and print the event JSON.
-- `list` projects current context entries; pretty output is
-  `file <path>` / `raw <truncated text>` lines, `(no context)` when empty.
-
-### `title set <name>` / `title clear <name>`
-
-```bash
-trellis channel title set <name>
-  --title <text>                          # REQUIRED
-  [--as <agent>]                          # default: main
-  [--scope project|global]
-
-trellis channel title clear <name>
-  [--as <agent>]                          # default: main
-  [--scope project|global]
-```
-
-Behavior:
-
-- Appends a `title` event projecting a stable display title onto the
-  channel. Output: event JSON.
-
----
-
-## Hidden / Internal
-
-| Command                                            | Purpose                                                                                                                                                                            |
-| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `channel __supervisor <channel> <worker> <config>` | Forked entry point invoked by `spawn`. Do not invoke directly.                                                                                                                     |
-| `channel __parse-trace <adapter> <file>`           | Dev helper — replays a recorded stream-json / wire trace through the matching adapter and prints the resulting channel events. Adapter is validated against the provider registry. |
-
----
-
-## Event Model
-
-`CHANNEL_EVENT_KINDS` (whitelist enforced by `parseChannelKind`):
-
-`create`, `join`, `leave`, `message`, `thread`, `context`, `channel`,
-`spawned`, `killed`, `respawned`, `progress`, `done`, `error`, `waiting`,
-`awake`, `undeliverable`, `interrupt_requested`, `turn_started`,
-`turn_finished`, `interrupted`, `supervisor_warning`.
-
-`MEANINGFUL_EVENT_KINDS` (default-visible subset used by `wait` /
-`messages` when no explicit `--kind` is given):
-
-`create`, `join`, `leave`, `message`, `thread`, `context`, `channel`,
-`spawned`, `killed`, `respawned`, `done`, `error`.
-
-Non-meaningful kinds (e.g. `progress`, `waiting`, `awake`,
-`supervisor_warning`, the `turn_*` / `interrupt*` set) still flow through
-the store; opt in via `--kind` or `--include-progress`.
-
-Forum channels are event-sourced; use the CLI reducers
-(`forum`, `thread`, `context list`) for state projection.
-
----
-
-## Output Conventions
-
-- **Mutations** (`send`, `interrupt`, `post`, `context add/delete`,
-  `title set/clear`, `thread rename`) print the appended event as one JSON
-  line on **stdout**.
-- **Streaming reads** (`wait`, `messages --follow`) print one JSON event
-  per line on stdout.
-- **Pretty reads** (`list`, `messages`, `forum`, `thread`, `context list`)
-  print colored, padded tables / timelines.
-- **`run`** prints only the final assistant text on stdout (so callers can
-  pipe); diagnostic notes go to stderr.
-- **Errors** go through `chalk.red("Error:")` to stderr and `exit 1`.
-- **`wait` timeout** specifically exits **124**.