@mindfoldhq/trellis 0.6.0-rc.0 → 0.6.0

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

@@ -0,0 +1,233 @@
+# Forum Channels
+
+Forum channels are durable, topic-style channels. They are created with
+`--type forum` at channel-creation time and are immutable after that. They are
+not normal chat streams: the default read path is
+**forum summary -> one thread timeline -> current context**.
+
+## Forum vs Regular Channel
+
+A channel's type is set with `--type` on `channel create` and never changes:
+
+- `chat` (default) — flat message timeline. `channel messages` always renders
+  the event stream. Forum-only flags such as `--thread` and `--action` are
+  rejected here.
+- `forum` — thread-oriented. `channel messages` without filters renders a
+  thread-board summary instead of raw events. The `post`, `forum`, `thread`,
+  and `thread rename` subcommands only apply to forum channels.
+
+Both types share the same scope model (`--scope project` is the default;
+`--scope global` puts the channel in the cross-project bucket).
+
+## Create A Forum Channel
+
+```bash
+trellis channel create design-feedback \
+  --type forum \
+  --scope global \
+  --description "Cross-project design feedback board." \
+  --context-raw "One thread per design topic; close when resolved." \
+  --by main
+```
+
+Use `--scope project` for a board scoped to one repo, `--scope global` for a
+cross-project board.
+
+## Threads: Open, Comment, Status, Summary
+
+Threads live inside a forum channel. Each thread is identified by a stable
+`--thread <key>` (lowercase kebab-case is conventional). The first action on
+a thread is `opened`; everything afterwards uses the same `--thread` key.
+
+```bash
+trellis channel post design-feedback opened \
+  --scope global \
+  --as main \
+  --thread login-empty-state \
+  --title "Empty state on the login screen" \
+  --description "Track design feedback for the new login empty state." \
+  --labels design,login \
+  --context-raw "Spotted during the 0.4 release review." \
+  --text-file /tmp/thread-open.md
+
+trellis channel post design-feedback comment \
+  --scope global \
+  --as reviewer \
+  --thread login-empty-state \
+  --text-file /tmp/review.md
+
+trellis channel post design-feedback status \
+  --scope global \
+  --as main \
+  --thread login-empty-state \
+  --status closed
+
+trellis channel post design-feedback summary \
+  --scope global \
+  --as main \
+  --thread login-empty-state \
+  --summary "Adopted the option-B layout; ticket TRELLIS-123 owns the fix."
+```
+
+Key distinctions:
+
+- `--description` is the **durable** thread description (the answer to "what
+  is this thread about?"). It is set on `opened` and edited by re-running
+  `post` with `--description`.
+- `--text` / `--stdin` / `--text-file` is the **event body** — the comment or
+  payload attached to this specific timeline entry.
+- `--labels` and `--assignees` are CSV and **replace** the current value; they
+  do not append.
+- `--summary` is the rolling thread summary. Setting it on `status closed` is
+  the standard way to mark a thread resolved with context.
+
+`--thread` is required for every action except `opened` (where it is also
+required in practice — there is no anonymous thread).
+
+## Read A Forum
+
+```bash
+trellis channel messages design-feedback --scope global
+trellis channel forum design-feedback --scope global --status open
+trellis channel thread design-feedback login-empty-state --scope global
+trellis channel messages design-feedback --scope global --raw --thread login-empty-state
+```
+
+If a peer says "I commented on the forum", run `channel forum` first to see
+which thread changed, then drill into that thread with `channel thread <name>
+<thread>`. Do not jump straight to ad-hoc `events.jsonl` parsing.
+
+## Context
+
+Context entries are durable background that should always be in scope when
+reading a channel or a thread. They are **not** timeline events; they are
+projected separately and replayed for every reader.
+
+Use the `context` subcommands. The legacy `--linked-context-file` /
+`--linked-context-raw` flags on `create` and `post` are deprecated aliases
+that fold into the canonical `--context-file` / `--context-raw`.
+
+### Add Context
+
+```bash
+# Channel-level context (whole forum)
+trellis channel context add design-feedback \
+  --scope global \
+  --raw "Upstream feedback board; please link tasks before opening threads."
+
+# Thread-level context (one thread)
+trellis channel context add design-feedback \
+  --scope global \
+  --thread login-empty-state \
+  --file "$PWD/.trellis/tasks/05-13-login-redesign/design.md"
+```
+
+- `--thread <key>` switches between channel-level and thread-level context.
+- `--file` paths **must be absolute**; relative paths are rejected.
+- `--raw` is plain text inline content.
+- Both flags are repeatable; at least one is required for `add` / `delete`.
+- `--as <agent>` records authorship; defaults to `main`.
+
+### List Context
+
+```bash
+trellis channel context list design-feedback --scope global
+trellis channel context list design-feedback --scope global --thread login-empty-state --raw
+```
+
+`--raw` on `list` emits one JSON entry per line (useful for piping); without
+it you get a human-readable `file <path>` / `raw <truncated text>` listing.
+An empty store prints `(no context)`.
+
+### Delete Context
+
+```bash
+trellis channel context delete design-feedback \
+  --scope global \
+  --thread login-empty-state \
+  --raw "stale note"
+```
+
+You delete by **value**, not by id: pass the same `--file` or `--raw` value
+that was added. Repeat the flag to delete multiple entries in one call.
+
+### Reading Order
+
+When reading a thread, work top-down:
+
+1. Thread `description` (the durable "what is this about").
+2. Context entries (channel-level + thread-level).
+3. Timeline (`opened`, `comment`, `status`, `summary`).
+
+If a context file is missing or unreadable, state that explicitly and
+continue with the remaining data — do not fabricate the content.
+
+## Title Projection
+
+`title` projects a stable display title onto the channel without renaming the
+storage address. The channel `name` you pass to every command stays the same.
+
+```bash
+trellis channel title set design-feedback \
+  --scope global \
+  --title "Design feedback board"
+
+trellis channel title clear design-feedback --scope global
+```
+
+- `title set` requires `--title`.
+- `--as <agent>` records authorship; defaults to `main`.
+- This is a presentation-layer change. Tooling and scripts keep using the
+  original channel name.
+
+## Thread Rename
+
+`thread rename` is the correction path when a thread was opened with the
+wrong key (typo, wrong slug convention, etc.). Threads do not support hard
+deletion — rename is the supported corrective action.
+
+```bash
+trellis channel thread rename design-feedback old-key new-key \
+  --scope global \
+  --as main
+```
+
+- `--as <agent>` is **required**.
+- `post <name> rename` is rejected — you must use `thread rename`.
+
+## Deletion Discipline
+
+Do not model single-comment deletion or hard thread deletion as normal
+workflow. Forum threads are append-only collaboration history. To correct
+state, use:
+
+- `post ... status` to mark a thread closed / blocked / etc.
+- `post ... summary` to record the resolution.
+- `post ... --labels` to re-label (replaces the set).
+- `thread rename` to correct a bad thread key.
+
+## Internal Changelog Pattern
+
+A common use of a global forum channel is an internal release / runtime
+changelog. One thread per notable change keeps history searchable:
+
+```bash
+trellis channel create release-notes \
+  --type forum \
+  --scope global \
+  --description "Internal release and runtime changelog." \
+  --context-raw "One thread per notable change; close when shipped." \
+  --by main
+
+trellis channel post release-notes opened \
+  --scope global \
+  --as main \
+  --thread release-2026-q1 \
+  --title "Channel threads and forum UX in 0.6" \
+  --description "Forum channel UX shipped in the 0.6 line." \
+  --labels channel,release \
+  --text-file /tmp/release-notes.md
+```
+
+Use stable, descriptive thread keys (e.g. `release-2026-q1`,
+`runtime-event-schema-change`) so later readers can find them by name.

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

@@ -0,0 +1,226 @@
+# Progress And Debugging
+
+Pretty output is for operators. Raw output is the audit log. Subcommands
+(`forum`, `thread`, `messages`, `context`) are the audit *interface* — reach
+for them before grepping `events.jsonl` by hand.
+
+## Pretty vs `--raw`
+
+`trellis channel messages <channel>` renders a compact, human-readable view:
+timestamps, identities, kind, and a short body. It is meant for operators
+scanning a channel, not for diagnostics.
+
+Pretty output can and will truncate:
+
+- long progress deltas (`text_delta`, partial tool args)
+- tool names and command lines
+- multi-line status fields and structured `detail` blobs
+- forum thread titles past the column budget
+
+When something looks "off" — a worker appears stuck, a progress line ends
+mid-word, an action field shows `...` — switch to `--raw`. Raw mode emits
+one JSON event per line exactly as it lives in `events.jsonl`, so nothing
+is dropped.
+
+```bash
+# Pretty (operator view)
+trellis channel messages <channel> --kind done --last 10
+trellis channel messages <channel> --kind error --last 10
+
+# Raw (diagnostic view) — one JSON per line
+trellis channel messages <channel> --raw --kind progress --last 20
+trellis channel messages <channel> --raw --last 50
+```
+
+Rule of thumb: never diagnose a worker from a truncated progress line.
+
+### Rebuild Streaming Text
+
+To reconstruct what a model actually streamed during a turn, concatenate
+`detail.text_delta` from progress events:
+
+```bash
+trellis channel messages <channel> --raw --kind progress --last 80 \
+  | python3 -c 'import json,sys; [print((json.loads(l).get("detail") or {}).get("text_delta",""), end="") for l in sys.stdin if l.strip()]'
+```
+
+## Stalled Worker Diagnosis
+
+Symptom: `trellis channel list` shows the worker as running, but no new
+events appear in `messages` and `wait` keeps timing out.
+
+Triage order:
+
+1. **Locate the channel files.** Use `list --all --all-projects` if you are
+   not sure which bucket the channel lives in.
+
+   ```bash
+   trellis channel list --all --all-projects
+   CHAN=~/.trellis/channels/<bucket>/<channel>
+   ```
+
+2. **Confirm the supervisor and worker PIDs are alive.**
+
+   ```bash
+   cat "$CHAN/<worker>.pid"            # supervisor PID
+   cat "$CHAN/<worker>.worker-pid"     # actual CLI subprocess PID
+   ps -p "$(cat "$CHAN/<worker>.pid")"
+   ps -p "$(cat "$CHAN/<worker>.worker-pid")"
+   ```
+
+   If the supervisor PID is gone but the channel still lists the worker,
+   you have a ghost entry — clean it with
+   `trellis channel kill <name> --as <worker> --force`.
+
+3. **Tail the worker log.** This is the canonical place to see provider /
+   MCP / tool startup output that never makes it onto the channel.
+
+   ```bash
+   tail -f "$CHAN/<worker>.log"
+   ```
+
+4. **Check the last raw events.** A worker that emitted `progress` but no
+   `message`/`done` is usually mid-stream or blocked on a tool call:
+
+   ```bash
+   trellis channel messages <channel> --raw --last 50
+   ```
+
+Common "alive but silent" causes:
+
+- Provider cold start before the first token (long, but eventually moves).
+- A blocking MCP server during startup — visible in the worker log.
+- Worker is waiting for a tool result whose subprocess hung.
+- Prompt is huge / model is rate-limited; check provider-side errors in the
+  worker log.
+
+## Progress Event Interpretation
+
+A `progress` event represents an in-flight piece of work. Its shape varies
+by `action` field, but the load-bearing fields are always under `detail`:
+
+- `detail.text_delta` — incremental model output (concatenate across events
+  to rebuild the streamed reply).
+- `detail.tool_name`, `detail.tool_input` — tool call about to run or
+  currently running.
+- `detail.status` — short string used by long-running actions
+  (`starting`, `running`, `flushing`, `done`).
+- `detail.action` — semantic label (e.g. `status` for thread heartbeats).
+
+Progress events are **noisy** by design. `wait` ignores them unless you
+pass `--include-progress`. When you do want to see them, prefer:
+
+```bash
+trellis channel messages <channel> --raw --kind progress --last 80
+```
+
+A stream that emits progress at a steady cadence but never closes with
+`done`/`error`/`message` is the classic shape of a hung tool call —
+inspect the worker log for the subprocess.
+
+## Wait Semantics (Quick Reference)
+
+`channel wait` watches `events.jsonl` from EOF and wakes on:
+
+- `message`
+- `done`
+- `error`
+- `killed`
+- `progress` only with `--include-progress`
+
+Useful filters:
+
+```bash
+trellis channel wait T --as main --from check --kind done --timeout 15m
+trellis channel wait T --as main --from check,check-cx --kind done --all --timeout 15m
+trellis channel wait T --as worker --tag interrupt --timeout 1h
+trellis channel wait T --as main --thread release-note --action status --timeout 10m
+```
+
+Exit codes: `0` matched, `124` timeout, `1`/`2` errors. On `wait --all`
+timeout, stderr names the workers still missing.
+
+## Auditing `events.jsonl` — Use Subcommands, Not `grep`
+
+Every channel persists its full history at `$CHAN/events.jsonl`. It is
+tempting to `tail` / `grep` / `jq` this file directly during debugging.
+Don't make it a habit, and **never** do it for forum channels.
+
+Why subcommands first:
+
+- `messages` already replays the file with filters (`--kind`, `--from`,
+  `--last`, `--tag`, `--thread`, `--action`) and gives you `--raw` for the
+  exact JSON. Anything you would write a one-liner for, `messages` already
+  does.
+- `wait` consumes the same file with EOF semantics — re-implementing that
+  with `tail -f | jq` will drop events under load and misorder them under
+  rotation.
+- `context` materializes a worker's inbox view, including cursor state.
+  Hand-rolled filters do not respect `<worker>.inbox-cursor`.
+
+### Forum channels: never parse `events.jsonl` directly
+
+Forum channels multiplex many logical threads onto a single `events.jsonl`.
+Each event carries `thread`, `action`, and tag fields that the forum
+subcommands know how to fold together. Parsing the file by hand will:
+
+- Mix threads together and make a thread look incoherent.
+- Miss thread lifecycle events (open / status / close) that change how
+  later events should be interpreted.
+- Ignore worker inbox cursors, so you will "see" events a worker has
+  already consumed and assume they are pending.
+
+Use the forum-aware views instead:
+
+```bash
+# List logical threads inside the forum channel
+trellis channel forum list <channel>
+
+# Inspect one thread end-to-end
+trellis channel thread show <channel> <thread>
+
+# Replay messages for a thread (supports --raw, --kind, --last)
+trellis channel messages <channel> --thread <thread> --raw --last 100
+
+# What a specific worker still has pending
+trellis channel context <channel> --as <worker>
+```
+
+Direct reads of `events.jsonl` are reserved for the case where the CLI
+itself is suspect — e.g. confirming an event was actually persisted, or
+diffing against `<worker>.inbox-cursor` while debugging the supervisor.
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `trellis: command not found` | CLI not installed globally | `npm install -g @mindfoldhq/trellis` |
+| `wait` exits immediately | wrong filter or identity collision | use distinct `--as`, inspect raw messages |
+| zsh errors on message text | shell interpreted punctuation | use `--stdin` or `--text-file` |
+| progress line is cut off | pretty output truncation | use `messages --raw --kind progress` |
+| worker never speaks | provider startup / prompt / MCP delay | inspect `<worker>.log`, `ps`, raw events |
+| channel not found in another cwd | project bucket mismatch | `cd` to project, use `--scope global`, or `list --all-projects` |
+| ghost worker in list | supervisor died without cleanup | `trellis channel kill <name> --as <worker> --force` |
+| forum thread looks scrambled | parsed `events.jsonl` directly | use `forum`, `thread`, `messages --thread` |
+
+## Storage Layout
+
+```text
+~/.trellis/channels/
+└── <bucket>/
+    └── <channel-name>/
+        ├── events.jsonl
+        ├── <channel>.lock
+        ├── <worker>.log
+        ├── <worker>.pid
+        ├── <worker>.worker-pid
+        ├── <worker>.config
+        ├── <worker>.session-id
+        ├── <worker>.thread-id
+        ├── <worker>.inbox-cursor
+        └── <worker>.spawnlock
+```
+
+Agents normally use the CLI, not direct file reads. Direct file reads are
+for debugging when CLI views are insufficient — and even then, never on a
+forum channel's `events.jsonl`.