@mindfoldhq/trellis 0.6.0-rc.0 → 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindfoldhq/trellis",
-  "version": "0.6.0-rc.0",
+  "version": "0.6.0",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,7 +34,7 @@
     "inquirer": "^9.3.7",
     "undici": "^6.21.0",
     "zod": "^4.4.2",
-    "@mindfoldhq/trellis-core": "0.6.0-rc.0"
+    "@mindfoldhq/trellis-core": "0.6.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",