@mindfoldhq/trellis 0.6.0-beta.9 → 0.6.0

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

@@ -0,0 +1,146 @@
+# Bundled Skills
+
+"Bundled skills" are multi-file built-in skills shipped inside the Trellis CLI npm package. Unlike marketplace skills (which a user installs separately into their own `.claude/skills/` or other platform skill root), bundled skills are written automatically into every supported platform's skill root by `trellis init` and kept in sync by `trellis update`. They are part of Trellis itself, not third-party content.
+
+A bundled skill is a directory under `packages/cli/src/templates/common/bundled-skills/<skill>/` that already contains its own `SKILL.md` (with YAML frontmatter) plus optional `references/`, assets, or other supporting files. Trellis copies the whole directory tree as-is into each platform's skill root, so references stay lazy-loadable instead of being flattened into one oversized `SKILL.md`.
+
+## What Counts As Bundled (vs. Adjacent Concepts)
+
+| Source path | Type | How it ships |
+| --- | --- | --- |
+| `templates/common/bundled-skills/<name>/` | Bundled skill (multi-file) | Whole directory copied to every platform skill root |
+| `templates/common/skills/<name>.md` | Single-file workflow skill | Wrapped with frontmatter, written as `<root>/<name>/SKILL.md` |
+| `templates/common/commands/<name>.md` | Slash command / prompt | Written to each platform's command directory (`.claude/commands/trellis/`, `.cursor/commands/trellis-*.md`, `.gemini/commands/trellis/*.toml`, etc.) |
+| `templates/<platform>/skills/` | Platform-specific skill | Written only into that platform's directory (e.g. `.codex/skills/`) |
+| User skills under `.claude/skills/<my-skill>/` etc. | Marketplace or user-authored | Not managed by Trellis at all |
+
+The Trellis CLI never touches anything that is not produced by one of its own template loaders. Anything a user drops into a platform skill root by hand is left alone.
+
+## Current Bundled Skills (v0.6.0)
+
+The set is discovered at runtime by listing directories under `templates/common/bundled-skills/`:
+
+| Skill | Purpose |
+| --- | --- |
+| `trellis-meta` | This skill. Explains the local Trellis architecture and customization entry points to an AI working inside a user project. |
+| `trellis-session-insight` | Wraps the `trellis mem` CLI so an AI knows when and how to reach into past Claude Code / Codex conversation logs. |
+| `trellis-spec-bootstrap` | Platform-neutral workflow for creating or refreshing `.trellis/spec/` from the real codebase (with optional GitNexus / ABCoder integration). |
+| `trellis-channel` | Capability skill teaching an AI when to reach for `trellis channel` for multi-agent collaboration, forum/thread persistent boards, and dispatcher-wait patterns. |
+
+The list is discovered at runtime, so adding a new directory under `bundled-skills/` is the only step required to register a new skill (see "Adding a New Bundled Skill" below).
+
+## Where Bundled Skills Land Per Platform
+
+Each platform configurator calls `writeSkills(<root>, <workflowSkills>, resolveBundledSkills(ctx))` during `trellis init`. `resolveBundledSkills` reads every directory under `templates/common/bundled-skills/`, resolves placeholders, and returns a flat list of `{relativePath, content}` entries. `writeSkills` then mirrors them under the platform's skill root.
+
+| Platform | Bundled skill root | Notes |
+| --- | --- | --- |
+| Claude Code | `.claude/skills/<skill>/` | `configureClaude` |
+| Cursor | `.cursor/skills/<skill>/` | `configureCursor` |
+| Codex | `.agents/skills/<skill>/` | `configureCodex` writes the shared `.agents/skills/` root, which Gemini CLI 0.40+ also reads |
+| Gemini CLI | `.agents/skills/<skill>/` | Same shared root as Codex; the two configurators are required to produce byte-identical output |
+| Kiro | `.kiro/skills/<skill>/` | `configureKiro` (skills-based platform — no commands) |
+| Qoder | `.qoder/skills/<skill>/` | `configureQoder` |
+| Codebuddy | `.codebuddy/skills/<skill>/` | `configureCodebuddy` |
+| Copilot | `.github/skills/<skill>/` | `configureCopilot` |
+| Droid | `.factory/skills/<skill>/` | `configureDroid` |
+| Antigravity | `.agent/skills/<skill>/` | `configureAntigravity` |
+| Windsurf | `.windsurf/skills/<skill>/` | `configureWindsurf` |
+| Kilo | `.kilocode/skills/<skill>/` | `configureKilo` |
+| OpenCode | (handled by `collectOpenCodeTemplates`) | Uses the same `resolveBundledSkills(ctx)` output |
+| Pi, Reasonix | (their own collectors) | Same `resolveBundledSkills(ctx)` output |
+
+Two paths exercise the same data:
+
+1. `configureX(cwd)` writes files during `trellis init`.
+2. `collectPlatformTemplates(platformId)` (in `configurators/index.ts`) returns a `Map<filePath, content>` that `trellis update` uses to detect drift and to populate `.trellis/.template-hashes.json`. Both must produce byte-identical output, so they both call `resolveBundledSkills(ctx)` and `collectSkillTemplates(root, …, resolveBundledSkills(ctx))`.
+
+## Dispatch Wiring (Code Path)
+
+The mechanism that auto-dispatches bundled skills to platform skill roots lives in two files:
+
+1. `packages/cli/src/templates/common/index.ts`
+   - `listDirectories("bundled-skills")` enumerates the on-disk skills.
+   - `listBundledSkillFiles(skillDir)` walks each skill's directory recursively and returns `{relativePath, content}` for every file.
+   - `getBundledSkillTemplates()` returns the cached `CommonBundledSkill[]`.
+
+2. `packages/cli/src/configurators/shared.ts`
+   - `resolveBundledSkills(ctx)` flattens that list into `ResolvedSkillFile[]` with `<skill>/<relativePath>` paths and resolved placeholders.
+   - `writeSkills(skillsRoot, workflowSkills, bundledSkills)` writes both workflow skills and bundled skill files under `skillsRoot`.
+   - `collectSkillTemplates(skillsRoot, workflowSkills, bundledSkills)` returns the same shape as a `Map<filePath, content>` for the update / hash pipeline.
+
+Every platform configurator that supports skills imports both helpers (see `claude.ts`, `cursor.ts`, `codex.ts`, `gemini.ts`, `kiro.ts`, `qoder.ts`, `codebuddy.ts`, `copilot.ts`, `droid.ts`, `antigravity.ts`, `windsurf.ts`, `kilo.ts`). The `index.ts` `PLATFORM_FUNCTIONS` registry also calls `resolveBundledSkills(ctx)` inside each `collectTemplates` closure so `trellis update` tracking stays consistent.
+
+## Adding a New Bundled Skill
+
+The shape and dispatch wiring are already generic, so adding a skill requires only file changes plus distribution verification.
+
+1. **Create the directory tree.**
+
+   ```
+   packages/cli/src/templates/common/bundled-skills/<my-skill>/
+     SKILL.md                     # YAML frontmatter + body
+     references/                  # optional
+       <topic>.md
+     assets/                      # optional (anything readable as utf-8)
+   ```
+
+2. **Write a valid `SKILL.md` header.** The frontmatter must include at minimum:
+
+   ```yaml
+   ---
+   name: <my-skill>
+   description: "When the AI should reach for this skill. Triggering phrases go here."
+   ---
+   ```
+
+   The `description` is what each platform's auto-trigger mechanism matches against, so it should describe the user-intent triggers, not the skill's internals.
+
+3. **Use placeholders where appropriate.** Bundled skill content runs through `resolvePlaceholders(file.content, ctx)`. Any `{{platform_name}}`, `{{python_cmd}}`, etc. token supported by `resolvePlaceholders` will be substituted per platform.
+
+4. **No dispatch wiring is required.** `listDirectories("bundled-skills")` discovers the new directory automatically, so all platforms receive it on the next `trellis init` or `trellis update`.
+
+5. **Verify the distribution path** before shipping. Skipping any of these steps has historically caused features to be documented as bundled while the published npm tarball was missing the files:
+
+   - Source files exist on the branch being tagged.
+   - `pnpm --filter @mindfoldhq/trellis build` copies the asset into `dist/templates/common/bundled-skills/<skill>/`.
+   - `npm pack --dry-run --json` includes the expected `dist/**` paths.
+   - In a fresh temp project, `trellis init` writes `.claude/skills/<skill>/SKILL.md`, `.agents/skills/<skill>/SKILL.md`, etc.
+   - `.trellis/.template-hashes.json` lists the generated files.
+   - `trellis update --dry-run` in that temp project reports "Already up to date!".
+
+6. **Add a migration manifest entry** if the skill is added in a release that other projects will upgrade into. Without an explicit manifest entry the file will land via the standard "missing file" branch of `trellis update`, but a manifest makes the change visible in the changelog.
+
+## Overriding a Bundled Skill Locally
+
+There is no formal "project-local skill" mechanism (e.g. `.trellis/skills/`). Bundled skills are platform-rooted, so any override is platform-rooted too.
+
+The supported pattern relies on the existing template-hash diff in `trellis update`:
+
+1. Edit the local file directly. Example: `.claude/skills/trellis-meta/SKILL.md`.
+2. The file's hash now diverges from the entry in `.trellis/.template-hashes.json`.
+3. The next `trellis update` detects the user modification and leaves the file untouched (Trellis never overwrites user-modified files without an explicit `--force`).
+
+Caveats:
+
+- The override only applies to the one platform whose directory you edited. To override the same skill across, for example, Claude Code and Codex, you must edit both `.claude/skills/<name>/` and `.agents/skills/<name>/`.
+- A future `trellis update --force` will overwrite local edits. Keep the override under version control so it can be reapplied if needed.
+- Marketplace skills installed under the same platform skill root with a different folder name (e.g. `.claude/skills/my-custom-meta/`) are untouched by Trellis and are the cleaner option when the goal is to add behavior, not to mutate the bundled skill.
+- Team-private conventions belong in `.trellis/spec/` or in a separate marketplace-style local skill, not in modifications to `trellis-meta` itself. See `customize-local/add-project-local-conventions.md`.
+
+## Removing a Bundled Skill From a Project
+
+There is no per-project opt-out flag for bundled skills. Two options:
+
+1. **Delete the directory in each platform skill root.** `trellis update` will see the file missing, compare against `.template-hashes.json`, and treat the deletion the same as any other user modification — it will not silently re-create the directory unless `--force` is passed.
+
+2. **Pin a Trellis version that did not ship the skill.** The bundled-skill set is determined at build time, so installing an older release of the CLI is the only way to permanently exclude a skill that the current release ships.
+
+A third option — globally disabling all bundled skills — is not supported. The dispatch is unconditional in every configurator. Adding such a flag would require changing `PLATFORM_FUNCTIONS` in `configurators/index.ts` and every `configureX` function.
+
+## Operating Rules
+
+- Treat `templates/common/bundled-skills/` as the single source of truth for what bundled skills exist. Do not hand-maintain platform-by-platform skill lists.
+- Do not add platform-specific logic inside a bundled `SKILL.md`. If a behavior is platform-specific, put it in `templates/<platform>/skills/` instead.
+- Do not couple bundled skills to a specific CLI binary (e.g. `trellis mem`) without surfacing the dependency in the skill's description and references — users on older releases may not have the command.
+- Do not store project-private content in a bundled skill. Bundled skills are public, shipped to every user; project rules belong in `.trellis/spec/` or a local skill.

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

@@ -0,0 +1,69 @@
+# Local Multi-Agent Channel Runtime
+
+`trellis channel` is the local multi-agent collaboration runtime shipped with the Trellis CLI. It lets the main AI session spawn peer workers (Claude Code, Codex, or any agent definition under `.trellis/agents/`), exchange durable messages through an event log, and coordinate review or brainstorm loops without hand-stitching shell pipelines.
+
+This reference covers how channels are wired into the user project so an AI customizing the project knows what to edit. For runtime usage (commands, forum/thread patterns, worker spawn flags), defer to the bundled `trellis-channel` capability skill.
+
+## Local System Model
+
+The channel runtime spans three local surfaces:
+
+1. **Storage layer** in the user's home directory: durable event logs and worker state files.
+2. **Agent definitions** inside the project at `.trellis/agents/`: platform-agnostic role cards consumed by `trellis channel spawn --agent <name>`.
+3. **Project configuration** in `.trellis/config.yaml`: worker guard thresholds and other channel knobs.
+
+## Core Paths
+
+| Path | Purpose |
+| --- | --- |
+| `~/.trellis/channels/<project>/<channel>/events.jsonl` | Per-channel append-only event log. Sequence-locked, replay-safe. |
+| `~/.trellis/channels/<project>/<channel>/<channel>.lock` | Channel-level write lock. |
+| `~/.trellis/channels/<project>/<channel>/<worker>.spawnlock` | Per-worker spawn lock used by the OOM guard. |
+| `~/.trellis/channels/<project>/<channel>/.seq` | Sequence sidecar for ordered event assignment. |
+| `~/.trellis/channels/_global/<channel>/...` | Channels created with `--scope global`. The project bucket is replaced by a shared key. |
+| `.trellis/agents/check.md` | Default Check Agent role definition consumed by `--agent check`. |
+| `.trellis/agents/implement.md` | Default Implement Agent role definition consumed by `--agent implement`. |
+| `.trellis/config.yaml` (`channel.*` block) | Worker guard thresholds and channel defaults. |
+
+The project bucket name is derived from the absolute project path (slashes flattened, non-alphanumerics replaced with `-`), matching Claude Code's `~/.claude/projects/<sanitized-cwd>/` convention. Override with `TRELLIS_CHANNEL_ROOT` (root directory) or `TRELLIS_CHANNEL_PROJECT` (bucket name) for testing or sandboxing.
+
+## When To Reach For The Channel Runtime
+
+Channels are heavier than a single Bash call or a one-shot sub-agent dispatch. Use them only when at least one of these conditions holds:
+
+- The work needs **two or more agents to converse** through more than one turn (cross-AI brainstorm, peer review, dispatcher + worker).
+- A worker should run as a **peer process** that the main session can interrupt, watch progress on, or wait for asynchronously.
+- The conversation must be **durable and inspectable** later (forum/thread channels, issue boards, decision trails).
+- Multiple workers must **share an event log** so each can see what the others reported.
+
+Prefer cheaper primitives when:
+
+- A single-shot Bash command or single Agent tool call is enough -> do that directly.
+- The user just needs a static review against a file -> read the file and reply inline.
+- The need is "remember what we discussed last week" -> use `trellis mem` instead of a channel.
+
+## Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Change default channel worker idle timeout | `channel.worker_guard.idle_timeout` in `.trellis/config.yaml`. Accepts `5m`, `30s`, etc. Set `0` to disable idle cleanup. |
+| Change live worker budget | `channel.worker_guard.max_live_workers` in `.trellis/config.yaml`. Set `0` to disable the spawn-time budget check. |
+| Override worker guard per spawn | Pass `--idle-timeout` / `--max-live-workers` on `trellis channel spawn`, or set `TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT` / `TRELLIS_CHANNEL_MAX_LIVE_WORKERS` in the environment. |
+| Change what the default Check or Implement worker does | Edit `.trellis/agents/check.md` or `.trellis/agents/implement.md`. These are platform-agnostic role cards; the channel runtime injects them when `--agent check|implement` is passed. |
+| Add a new role card | Drop `<name>.md` into `.trellis/agents/`. `trellis channel spawn --agent <name>` will pick it up. |
+| Relocate channel storage (CI sandbox, ephemeral runs) | Set `TRELLIS_CHANNEL_ROOT=/path/to/dir`. Channel events move with it; existing channels stay at the old root. |
+| Switch storage scope | Pass `--scope project` (default) or `--scope global` on every channel subcommand. The bucket directory changes; nothing else does. |
+
+Precedence for the worker guard is: CLI flag > environment variable > `.trellis/config.yaml` > built-in default. Built-in defaults are `idle_timeout: 5m` and `max_live_workers: 6`.
+
+## Relationship To Other Local Layers
+
+- **Workflow layer**: workflows that use channel dispatch (such as `channel-driven-subagent-dispatch`) instruct the main agent to call `trellis channel spawn --agent check` or `--agent implement` instead of a platform sub-agent. If `.trellis/agents/check.md` or `implement.md` is missing, `trellis workflow --template <id>` prints a non-blocking warning at install time. Restore them with `trellis update` if they are deleted by accident.
+- **Task layer**: channel workers do not own task state. The supervising main session passes the active task path through the worker inbox; the worker resolves task artifacts from disk.
+- **Spec layer**: workers read `.trellis/spec/` the same way the main session does. Channel runtime does not bypass spec context loading.
+- **Platform integration layer**: channel runtime is platform-neutral. It does not depend on `.claude/`, `.codex/`, or any other platform directory. The adapters that normalize provider output (Claude `stream-json`, Codex `app-server`) live inside the Trellis CLI binary, not in the project.
+- **Platform sub-agent files vs. channel workers**: editing `.claude/agents/trellis-implement.md` (and its peers in other platform `.X/agents/` directories) does NOT change channel-runtime worker behavior — channel workers load `.trellis/agents/<name>.md`. The platform-specific agent files are for direct sub-agent dispatch from the main AI session, not for channel-spawned workers. See `platform-files/agents.md` for the per-platform agent surface, and the `trellis-meta/SKILL.md` rule that codifies this split.
+
+## Runtime Usage
+
+For command syntax, forum/thread patterns, worker handles, progress inspection, and the `--kind done` / `--kind turn_finished` dispatcher wait pattern, load the bundled `trellis-channel` skill (auto-installed under each platform's skills directory after `trellis init` / `trellis update`). This reference only covers the local file layout and customization knobs; it does not duplicate command syntax that may change between releases.

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

@@ -44,6 +44,33 @@ The Trellis task system is stored entirely under `.trellis/tasks/` in the user p
 | `commit` / `pr_url` | Commit and PR information after completion. |
 | `meta` | Extension fields. |
 
+## Parent / Child Task Trees
+
+Parent/child task relationships are for work structure. A parent task groups related deliverables under one source requirement set; it is not a dependency scheduler and does not replace the child task's own planning artifacts.
+
+Use a parent task when a request has multiple independently verifiable deliverables. The parent owns:
+
+- Source requirements and user-facing scope.
+- The map of child tasks and their responsibility boundaries.
+- Cross-child acceptance criteria and final integration review.
+
+Use child tasks for deliverables that can move through planning, implementation, check, and archive independently. If one child depends on another, write that dependency in the child `prd.md` / `implement.md`; do not rely on tree position to imply ordering.
+
+Create new children with:
+
+```bash
+python3 ./.trellis/scripts/task.py create "<child title>" --slug <child-slug> --parent <parent-dir>
+```
+
+Link or unlink existing tasks with:
+
+```bash
+python3 ./.trellis/scripts/task.py add-subtask <parent-dir> <child-dir>
+python3 ./.trellis/scripts/task.py remove-subtask <parent-dir> <child-dir>
+```
+
+`children` on the parent is a historical list. When a child is archived, Trellis keeps that child name in the parent so progress like `[2/3 done]` remains meaningful after completed children move to `archive/`.
+
 The AI should not treat phase numbers as task status. Task progress is mainly determined by `status`, artifact presence (`prd.md`, optional `design.md` / `implement.md`), whether JSONL context is configured for sub-agent mode, and the phase descriptions in `workflow.md`.
 
 ## Active Task

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/platform-map.md

@@ -19,7 +19,8 @@ This page lists common Trellis file locations in a user project by platform. Whe
 | CodeBuddy | `--codebuddy` | `.codebuddy/` | `.codebuddy/skills/` | `.codebuddy/agents/` | `.codebuddy/hooks/` + `.codebuddy/settings.json` |
 | GitHub Copilot | `--copilot` | `.github/` | `.github/skills/` | `.github/agents/` | `.github/copilot/hooks/` + prompts |
 | Factory Droid | `--droid` | `.factory/` | `.factory/skills/` | `.factory/droids/` | `.factory/hooks/` + settings |
-| Pi Agent | `--pi` | `.pi/` | `.pi/skills/` | `.pi/agents/` | `.pi/extensions/trellis/` + `.pi/settings.json` |
+| Pi Agent | `--pi` | `.pi/` | `.pi/skills/` | `.pi/agents/` | `.pi/extensions/trellis/` (native `trellis_subagent` tool) + `.pi/settings.json` |
+| Reasonix | `--reasonix` | `.reasonix/` | `.reasonix/skills/` | None — sub-agents are skills with `runAs: subagent` frontmatter | None |
 
 ## Capability Groups
 
@@ -38,9 +39,18 @@ These platforms usually have `trellis-research`, `trellis-implement`, and `trell
 - GitHub Copilot
 - Factory Droid
 - Pi Agent
+- Reasonix (delivered as skills with `runAs: subagent` under `.reasonix/skills/`, not as a separate `agents/` directory)
 
 When changing implementation/check/research behavior, look for the corresponding platform agent files first.
 
+### Native Trellis Sub-Agent Tool
+
+Some platforms expose a first-class tool that the host runtime understands. The model calls it like any other tool and the host renders progress cards, validates the agent name against `.<platform>/agents/`, and enforces dispatch modes.
+
+- Pi Agent — `trellis_subagent` tool, defined in `.pi/extensions/trellis/index.ts`. Supports `single` / `parallel` / `chain` dispatch modes and emits live `trellis-subagent-progress` events.
+
+When changing sub-agent dispatch behavior on these platforms, edit the extension file, **not** the agent markdown — the agent markdown defines responsibilities, but the host extension owns dispatch, validation, and progress rendering.
+
 ### Main-Session Workflow Platforms
 
 These platforms rely more on workflows/skills to guide the main session:

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

@@ -0,0 +1,81 @@
+---
+name: trellis-session-insight
+description: "Reach into past AI conversation history through the `trellis mem` CLI. Use whenever the user asks 'how did we solve X last time', 'have we discussed this before', 'what was the decision on X', 'remind me what we did in this task', '上次怎么解的', '之前讨论过吗', '想起一段对话', or when starting a brainstorm that overlaps prior work, debugging a familiar bug, continuing a task across sessions, or doing a finish-work review. Returns raw past dialogue; decide for the moment whether to update spec, append to task notes, quote inline in the answer, or just internalize."
+---
+
+# Trellis Session Insight
+
+This skill teaches an AI **how to call `trellis mem`** — the project's cross-session memory feedstock — and **when reaching for it is the right move**.
+
+It is intentionally a **capability skill, not a workflow**. There is no fixed output file, no required write-back step, no "always run after finish-work" rule. What to do with what `mem` returns is a judgement call made in the moment of the conversation. The skill exists so the AI knows the capability is there and can decide.
+
+## What `trellis mem` is
+
+A local CLI that indexes the user's past Claude Code and Codex conversation logs (the JSONL files each platform stores under `~/.claude/projects/` and `~/.codex/sessions/`) and lets you list, search, slice by Trellis task boundaries, and dump cleaned dialogue from them. OpenCode logs are not yet indexable (provider adapter pending) — when an OpenCode session is the obvious target, surface that limitation rather than guessing.
+
+Nothing in `mem` is uploaded. All reads are local.
+
+## When to reach for it
+
+The bar is "would a senior teammate ask 'didn't we already talk about this?'" — those are the moments. Some concrete patterns:
+
+- **Brainstorm rerun risk.** Starting a new task that touches an area the user has been in before, and you want to check whether a decision was already made — before re-asking the user.
+- **Familiar-bug debugging.** The current bug pattern feels like one the user reported / fixed before. Pulling the relevant past session can save a full debugging loop.
+- **Cross-session continuation.** The user resumes work after a gap and says "where were we" / "继续上次的" without being specific.
+- **Decision retrieval.** The user references "the decision we made about X" but the decision lives in an old brainstorm, not in any `prd.md` / `spec/`.
+- **Finish-work retrospective.** When the user explicitly asks for a wrap-up of what was decided / what hurt / what surprised them in this task — not as a forced step on every finish-work.
+- **Pattern-spotting across past work.** The user asks "do I keep making the same mistake on X" / "我每次都踩这个坑吗" — search across sessions answers that.
+
+If none of these apply, don't call `mem`. It is a tool, not a ceremony.
+
+## When NOT to reach for it
+
+- The relevant context is already in the current turn, `prd.md`, `design.md`, recent `git log`, or the open files. `mem` is for stuff that has fallen out of immediate reach.
+- The user is asking about a fact in the code, not a fact from a past conversation. `git log -p` / `grep` / reading the file directly is faster and more authoritative.
+- You are in a sub-agent (`trellis-implement` / `trellis-check`) whose dispatch prompt already includes the curated `implement.jsonl` / `check.jsonl` context. Adding `mem` on top usually just clutters.
+- The user has explicitly said "don't dig through history, just answer what I asked".
+
+## What to do with what `mem` returns
+
+Treat the output as **raw material**, not a deliverable. Once you have it, decide based on the live conversation:
+
+- **Quote inline in your reply** if a specific past exchange answers the user's current question — and cite the session-id / phase so the user can verify.
+- **Update `<task>/prd.md` or `<task>/design.md`** if `mem` surfaced a load-bearing decision that should have been written down but wasn't. Surface the proposed edit to the user first.
+- **Append to a task-local notes file** (e.g. `<task>/notes.md` or extending an existing one) if the finding belongs to the current task's record but doesn't fit the PRD.
+- **Update `.trellis/spec/`** if the finding is a project-wide convention or gotcha that would help future tasks. Run the `trellis-update-spec` skill for that — `session-insight` ends at the discovery.
+- **Just absorb it** for the next few turns and answer better, without writing anything. This is often the right move for one-off recall.
+
+Trellis does not prescribe a single destination. Forcing every recall into a fixed file makes the file grow into noise. Let the situation decide.
+
+## How to call it
+
+Full CLI reference is in `references/cli-quick-reference.md`. The 80% case is one of:
+
+```bash
+# Find sessions whose contents mention a keyword (project-scope is default;
+# add --global to search every project on this machine).
+trellis mem search "<keyword>"
+
+# Dump dialogue from one session, optionally filtered by phase or keyword.
+trellis mem extract <session-id> --phase brainstorm
+trellis mem extract <session-id> --grep "<keyword>"
+
+# Drill into a session: top-N hit turns + surrounding context.
+trellis mem context <session-id> --turns 3 --around 2
+
+# When you do not know the session id yet, start with list + filter.
+trellis mem list --task <task-dir>
+trellis mem projects   # → list active project cwds, then narrow
+```
+
+Phase slicing (`--phase brainstorm|implement|all`) cuts the session at `task.py create` and `task.py start` boundaries. For a finish-work review of the current task, `--phase brainstorm` recovers the planning discussion and `--phase implement` recovers the execution loop. Default is `all`.
+
+## Triggering patterns
+
+`references/triggering-patterns.md` lists more verbatim user phrasings (English + Chinese) that should make you think "reach for `mem`" — keep that handy when training instinct.
+
+## Out of scope
+
+- `mem` does not edit code or update files. Any write-back is your decision in the moment.
+- `mem` is read-only on the platform JSONL stores. It does not push or sync to remote.
+- This skill does not replace `trellis-update-spec` (which is the right tool for promoting a finding into project-wide guidance) or the platform-native task / spec workflow.

package/dist/templates/common/bundled-skills/trellis-session-insight/references/cli-quick-reference.md

@@ -0,0 +1,66 @@
+# `trellis mem` CLI Reference
+
+Full flag reference for the five subcommands. Pin this as the authoritative source — `trellis mem help` prints the same content at runtime, so anything here that drifts is a bug.
+
+## Subcommands
+
+| Command | Purpose |
+|---|---|
+| `list` | List sessions. Default subcommand when none is given. |
+| `search <keyword>` | Find sessions whose contents match a keyword. |
+| `context <session-id>` | Drill into one session: top-N hit turns + surrounding context. Pair with `--grep` for keyword anchoring. |
+| `extract <session-id>` | Dump cleaned dialogue. Combine with `--phase` / `--grep` to slice. |
+| `projects` | List active project `cwd` values with session counts. Use this to discover which `--cwd` to pass to other subcommands. |
+
+## Flags (apply where meaningful)
+
+| Flag | Subcommands | Meaning |
+|---|---|---|
+| `--platform claude\|codex\|opencode\|all` | all | Default `all`. OpenCode adapter is currently a stub on `0.6.0-beta.*` — see "Caveats" below. |
+| `--since YYYY-MM-DD` | list / search | Inclusive lower date bound. |
+| `--until YYYY-MM-DD` | list / search | Inclusive upper date bound. |
+| `--global` | list / search | Include sessions from every project on this machine. Default is the current project `cwd`. |
+| `--cwd <path>` | list / search | Force a specific project cwd instead of inferring from where you are. |
+| `--limit N` | list / search | Cap output rows. Default `50`. |
+| `--grep KW` | extract / context | Filter turns by keyword. Multi-token AND when whitespace-separated. |
+| `--phase brainstorm\|implement\|all` | extract | Slice session by Trellis task boundaries. `brainstorm` = `[task.py create, task.py start)`. `implement` = `[task.py start, task.py finish)` window. Default `all`. |
+| `--turns N` | context | Number of hit turns to return. Default `3`. |
+| `--around N` | context | Surrounding turns to include per hit. Default `1`. |
+| `--max-chars N` | context | Total character budget. Default `6000` (~1500 tokens). |
+| `--include-children` | search / context | Merge OpenCode sub-agent sessions into their parent session. |
+| `--json` | all | Emit machine-parseable JSON instead of human-readable output. |
+| `--task <task-dir>` | list | Narrow to sessions whose context-key resolved to a given task directory (uses `.trellis/.runtime/sessions/*.json`). |
+
+## Common one-liners
+
+```bash
+# What past sessions discussed "deadlock" anywhere on this machine?
+trellis mem search "deadlock" --global --limit 20
+
+# Inside a specific session, surface the top 5 turns that mention "lock contention"
+# plus 2 turns of surrounding context.
+trellis mem context 5842592d --grep "lock contention" --turns 5 --around 2
+
+# Recover the brainstorm window for a session — useful when continuing a task
+# the user started a week ago.
+trellis mem extract 5842592d --phase brainstorm
+
+# List every project this machine has Trellis sessions for, with counts.
+trellis mem projects
+```
+
+## Output shapes
+
+- **Default human output** (no `--json`): wrapped to a terminal, with session ids highlighted and turn markers visible. Suitable to read inline but messy to paste into a markdown file.
+- **`--json`**: stable schema, safe to parse and process. When piping `mem` output into a follow-up step (e.g. summarizing for a Lessons section), prefer `--json`.
+
+## Caveats
+
+- **OpenCode adapter is a stub on `0.6.0-beta.*`.** When `--platform` resolves to OpenCode (or `all` and OpenCode would be included), `mem` prints a one-line "reader unavailable" notice and continues with the other platforms. Don't promise OpenCode coverage in your reply until the adapter ships.
+- **`--phase` slicing depends on `task.py create` / `task.py start` invocations appearing in the recorded bash calls of the session.** Sessions where the user ran `task.py` from a different terminal — outside the recorded AI loop — will not have phase boundaries. `--phase all` is the safe fallback.
+- **`mem` indexes platform JSONL files directly.** If the user has cleared their Claude / Codex session storage, `mem` cannot recover what is no longer on disk.
+- **`mem` is read-only.** No remote sync, no edits to platform JSONL. Any write you do based on `mem` findings is your own follow-up call into the editing tools available to you.
+
+## When you need more than this reference
+
+Run `trellis mem help` in the user's shell. The runtime help is authoritative and will be ahead of this reference during fast-moving beta releases.

package/dist/templates/common/bundled-skills/trellis-session-insight/references/triggering-patterns.md

@@ -0,0 +1,93 @@
+# Triggering Patterns
+
+Verbatim user phrasings that should make an AI reach for `trellis mem`. Calibrate instinct against these — if a user message hits one of these patterns and you do not reach for `mem`, you probably missed an obvious recall.
+
+Patterns are grouped by the *intent* behind the phrasing, not the surface words. The same intent shows up in different languages and registers.
+
+## Past-solution recall
+
+The user is asking "how did we (or I) solve this before". Past dialogue holds the answer; the codebase shows the result but not the reasoning.
+
+- "How did we solve this last time?"
+- "What did we end up doing about X?"
+- "We dealt with this once already, didn't we?"
+- "上次怎么解的?"
+- "之前是怎么搞定 X 的?"
+- "我记得以前修过类似的"
+
+Reach: `trellis mem search "<symptom keyword>" --global --limit 10`, then `context` into the hit that looks closest.
+
+## Decision retrieval
+
+The user is referencing a decision that lives in old dialogue, not in any committed file. Look in brainstorm windows.
+
+- "What was the decision on X?"
+- "Did we decide to use Postgres or SQLite?"
+- "The rationale for choosing X over Y was…?"
+- "我们当时为啥选了 X 而不是 Y?"
+- "关于 X 我们之前是怎么定的?"
+- "之前讨论过 X 的方案吗?"
+
+Reach: `trellis mem search "<decision keyword>"` to find the session, then `extract <id> --phase brainstorm` to recover the discussion.
+
+## Cross-session continuation
+
+The user resumed work after a gap and the context is implicit.
+
+- "Where were we?"
+- "Continue from last time."
+- "Pick up where we left off."
+- "继续上次的"
+- "我们上次做到哪了"
+- "接着昨天那个任务"
+
+Reach: `trellis mem list --task <current-task-dir>` to find the most recent sessions tied to the active task, then `extract` the last one.
+
+## Familiar-bug debugging
+
+The current bug feels like one already seen. Past sessions probably hold the resolution path.
+
+- "I feel like I've hit this before."
+- "Doesn't this look like that bug from last month?"
+- "Same kind of timeout I had in X."
+- "这个错好像之前见过"
+- "这个 bug 是不是上次那个?"
+- "怎么又是这个 error?"
+
+Reach: `trellis mem search "<error message fragment>" --global`. Anchor on a short, distinctive token from the actual error string.
+
+## Self-pattern spotting
+
+The user is asking whether they keep repeating the same kind of mistake or decision.
+
+- "Do I always make this mistake?"
+- "How often have I run into X?"
+- "Is this a recurring thing for me?"
+- "我每次都踩这个坑吗?"
+- "我老犯这个错?"
+- "这类问题之前出现过几次?"
+
+Reach: `trellis mem search "<topic>" --global --limit 50` and scan the dates / projects in the listing. Optionally `extract` two or three for comparison.
+
+## Finish-work retrospective (on demand)
+
+The user explicitly wants to look back at this task — not as a forced step, only when they ask.
+
+- "Summarize what we did in this task."
+- "What were the key decisions / surprises?"
+- "Write up the lessons from this round."
+- "总结一下这次的经验"
+- "记一下这次踩的坑"
+- "复盘下这个任务"
+
+Reach: identify the current task's session id (from `.trellis/.runtime/sessions/*.json` or `mem list --task <task-dir>`), then `extract <id> --phase brainstorm` and `--phase implement`. Present a summary — surface concrete file:line citations where possible. Whether to also write the summary somewhere (PRD, spec, notes file) is the user's call; offer, don't auto-write.
+
+## Anti-patterns: do NOT reach for `mem` here
+
+- "What does this function do?" → read the file.
+- "Why is this test failing?" → read the test output and the file.
+- "What's the right pattern for X in our codebase?" → grep / read spec files.
+- "What's the latest npm version of Y?" → call `npm view`.
+- "Fix this bug." → debug. Reach for `mem` only if you suspect prior context exists; otherwise it is noise.
+
+The bar stays: would a senior teammate ask "didn't we already talk about this?" before answering? If yes, reach for `mem`. If no, don't.

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

@@ -0,0 +1,41 @@
+---
+name: trellis-spec-bootstrap
+description: "Bootstrap project-specific Trellis coding specs with a platform-neutral single-agent workflow. Use when creating or refreshing .trellis/spec guidelines, analyzing a codebase with GitNexus, ABCoder, or source inspection, decomposing package/layer spec work, and writing real codebase-backed spec docs without placeholder text."
+---
+
+# Trellis Spec Bootstrap
+
+Use this skill to create or refresh `.trellis/spec/` guidelines from the real codebase. One capable agent owns the full loop: analyze the repository, choose the spec boundaries, write the docs, and verify the result. The workflow does not depend on a specific host, CLI, or agent brand.
+
+## Workflow
+
+1. Confirm Trellis is initialized and inspect the current `.trellis/spec/` tree.
+2. Analyze the repository architecture with the best available tools: GitNexus, ABCoder, language tooling, and direct source reads.
+3. Decompose the spec work by package and layer only when that reflects the actual codebase.
+4. Fill or reshape the spec files with concrete patterns, file paths, examples, and anti-patterns from the project.
+5. Verify that the final specs are internally consistent and contain no template placeholders.
+
+## Reference Routing
+
+| Need | Read |
+|------|------|
+| Repository architecture analysis | [references/repository-analysis.md](references/repository-analysis.md) |
+| Spec work decomposition and task planning | [references/spec-task-planning.md](references/spec-task-planning.md) |
+| Writing high-signal Trellis spec files | [references/spec-writing.md](references/spec-writing.md) |
+| GitNexus and ABCoder MCP setup | [references/mcp-setup.md](references/mcp-setup.md) |
+
+## Operating Rules
+
+- Treat templates as starting points, not contracts. Delete, rename, split, or add spec files when the repository calls for it.
+- Prefer source-backed rules over generic advice. Every important recommendation should point at a real file or repeated local pattern.
+- Keep execution single-owner by default. Optional helper agents are an implementation detail, not a requirement or user-visible dependency.
+- Do not write platform-specific instructions unless the target project already standardizes on that platform.
+- Do not leave placeholder text, empty headings, or copied boilerplate in `.trellis/spec/`.
+
+## Done Criteria
+
+- `.trellis/spec/` describes the project as it exists now.
+- Each relevant package or layer has practical coding guidance with real examples.
+- Non-applicable template sections are removed.
+- `index.md` files match the final spec file set.
+- Any required setup or analysis assumptions are documented in the relevant spec or task notes.