@baoanaz/cviauto 0.6.5

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 Cviauto 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 `cviauto init` and kept in sync by `cviauto update`. They are part of Cviauto 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. Cviauto 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/cviauto/`, `.cursor/commands/cviauto-*.md`, `.gemini/commands/cviauto/*.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 Cviauto at all |
+
+The Cviauto 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 |
+| --- | --- |
+| `cviauto-meta` | This skill. Explains the local Cviauto architecture and customization entry points to an AI working inside a user project. |
+| `cviauto-session-insight` | Wraps the `cviauto mem` CLI so an AI knows when and how to reach into past Claude Code / Codex / Pi Agent conversation logs. |
+| `cviauto-spec-bootstrap` | Platform-neutral workflow for creating or refreshing `.cviauto/spec/` from the real codebase (with optional GitNexus / ABCoder integration). |
+| `cviauto-channel` | Capability skill teaching an AI when to reach for `cviauto 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 `cviauto 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` |
+| Devin | `.devin/skills/<skill>/` | `configureDevin` |
+| 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 `cviauto init`.
+2. `collectPlatformTemplates(platformId)` (in `configurators/index.ts`) returns a `Map<filePath, content>` that `cviauto update` uses to detect drift and to populate `.cviauto/.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`, `devin.ts`, `kilo.ts`). The `index.ts` `PLATFORM_FUNCTIONS` registry also calls `resolveBundledSkills(ctx)` inside each `collectTemplates` closure so `cviauto 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 `cviauto init` or `cviauto 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 @baoanaz/cviauto 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, `cviauto init` writes `.claude/skills/<skill>/SKILL.md`, `.agents/skills/<skill>/SKILL.md`, etc.
+   - `.cviauto/.template-hashes.json` lists the generated files.
+   - `cviauto 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 `cviauto 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. `.cviauto/skills/`). Bundled skills are platform-rooted, so any override is platform-rooted too.
+
+The supported pattern relies on the existing template-hash diff in `cviauto update`:
+
+1. Edit the local file directly. Example: `.claude/skills/cviauto-meta/SKILL.md`.
+2. The file's hash now diverges from the entry in `.cviauto/.template-hashes.json`.
+3. The next `cviauto update` detects the user modification and leaves the file untouched (Cviauto 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 `cviauto 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 Cviauto and are the cleaner option when the goal is to add behavior, not to mutate the bundled skill.
+- Team-private conventions belong in `.cviauto/spec/` or in a separate marketplace-style local skill, not in modifications to `cviauto-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.** `cviauto 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 Cviauto 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. `cviauto 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 `.cviauto/spec/` or a local skill.

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

@@ -0,0 +1,68 @@
+# Local Context Injection System
+
+Cviauto context injection aims to make AI read the right files at the right time instead of relying on model memory. In a user project, injection is implemented by `.cviauto/` scripts together with platform hooks, agents, and skills.
+
+## Injected Context Types
+
+| Type | Source | Purpose |
+| --- | --- | --- |
+| session context | `.cviauto/scripts/get_context.py` | Current developer, git status, active task, active tasks, journal, packages. |
+| workflow context | `.cviauto/workflow.md` | Current Cviauto flow and next action. |
+| spec context | `.cviauto/spec/` + task JSONL | Specs that must be followed during implementation/checking. |
+| task context | `.cviauto/tasks/<task>/prd.md`, `design.md`, `implement.md`, `research/` | Current task requirements, design, execution plan, and research. |
+| platform context | Platform hooks/settings/agents | Lets different AI tools read the files above through their own mechanisms. |
+
+## session-start
+
+Platforms with session-start support inject a Cviauto overview when a session starts, clears, compacts, or receives a similar event. Injected content usually includes:
+
+- workflow summary.
+- current task status.
+- active tasks.
+- spec index paths.
+- developer identity and git status.
+
+If the user feels the AI does not know the current task in a new session, first check whether the platform's session-start hook or equivalent mechanism is installed and running.
+
+## workflow-state
+
+workflow-state is a lightweight hint injected around each user turn. Based on current task status, it selects a block from `.cviauto/workflow.md`, such as `no_task`, `planning`, `in_progress`, or `completed`.
+
+If the user wants to change "what the AI should do next in a given state," edit the corresponding state block in `.cviauto/workflow.md` first.
+
+## sub-agent context
+
+Implement and check agents need task context. Cviauto has two loading modes:
+
+1. **hook push**: a platform hook injects jsonl-referenced files plus `prd.md`, `design.md` if present, and `implement.md` if present before the agent starts.
+2. **agent pull**: the agent definition instructs the agent to read the active task, jsonl context, and task artifacts after startup.
+
+In both modes, JSONL files in the task directory are the manifest for spec/research context. Task artifacts are read separately in this order: `prd.md` -> `design.md if present` -> `implement.md if present`.
+
+## JSONL Reading Rules
+
+`implement.jsonl` and `check.jsonl` contain one JSON object per line:
+
+```jsonl
+{"file": ".cviauto/spec/backend/index.md", "reason": "Backend rules"}
+```
+
+Readers should skip seed rows without a `file` field. When configuring JSONL, the AI should include only spec/research files, not pre-register code files that will be modified.
+
+## Active Task And Context Key
+
+Active task state lives in `.cviauto/.runtime/sessions/` and is isolated per session. Hooks try to resolve the context key from platform events, environment variables, transcript paths, or `TRELLIS_CONTEXT_ID`.
+
+If shell commands cannot see the same context key, `task.py current --source` may report no active task. In that case, check whether the platform passes session identity into the shell instead of hand-writing a global current-task file.
+
+## Local Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Change session-start injected content | The platform's `session-start` hook or plugin file. |
+| Change per-turn workflow-state rules | `[workflow-state:STATUS]` block in `.cviauto/workflow.md`. The platform workflow-state hook parses these blocks verbatim and embeds no fallback text. |
+| Change how sub-agents read context | Platform agent definitions, the `inject-subagent-context` hook, or agent preludes. |
+| Change JSONL validation/display | `.cviauto/scripts/common/task_context.py`. |
+| Change active task resolution | `.cviauto/scripts/common/active_task.py`. |
+
+When modifying context injection, verify two things: new sessions can see the correct task, and sub-agents can see the correct task artifacts/spec/research.

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

@@ -0,0 +1,80 @@
+# Local Files Generated After Init
+
+`cviauto init` writes the Cviauto runtime into the user project. Later, `cviauto update` tries to update Cviauto-managed template files, but it uses `.cviauto/.template-hashes.json` to determine which files have already been modified by the user.
+
+This page only describes files that are visible and editable inside the user project.
+
+## `.cviauto/`
+
+```text
+.cviauto/
+├── workflow.md
+├── config.yaml
+├── .developer
+├── .version
+├── .template-hashes.json
+├── .runtime/
+├── scripts/
+├── spec/
+├── tasks/
+└── workspace/
+```
+
+| Path | Usually editable? | Notes |
+| --- | --- | --- |
+| `.cviauto/workflow.md` | Yes | Local workflow documentation and AI routing rules. |
+| `.cviauto/config.yaml` | Yes | Project configuration, hooks, packages, journal line limits, and related settings. |
+| `.cviauto/spec/` | Yes | Project specs, intended to be updated regularly by users and AI. |
+| `.cviauto/tasks/` | Yes | Task material and research artifacts, maintained by the task workflow. Local-only by default via `.cviauto/.gitignore`; publish only when the project explicitly wants Cviauto bookkeeping in git. |
+| `.cviauto/workspace/` | Yes | Session records, usually written by `add_session.py`. Local-only by default via `.cviauto/.gitignore`; publish only when the project explicitly wants Cviauto bookkeeping in git. |
+| `.cviauto/scripts/` | Carefully | Local runtime. It can be customized, but only after understanding the call chain. |
+| `.cviauto/.runtime/` | No | Runtime state, usually written automatically by hooks/scripts. |
+| `.cviauto/.developer` | Carefully | Current developer identity. |
+| `.cviauto/.version` | No | Cviauto version record used by update/migration logic. |
+| `.cviauto/.template-hashes.json` | No | Template hash record. Do not hand-write business rules here. |
+
+## Platform Directories
+
+Different platforms generate different directories. Common categories:
+
+| Category | Example paths | Purpose |
+| --- | --- | --- |
+| hooks | `.claude/hooks/`, `.codex/hooks/`, `.cursor/hooks/` | Inject session context, workflow-state, and sub-agent context. |
+| settings | `.claude/settings.json`, `.codex/hooks.json`, `.qoder/settings.json`, `.trae/hooks.json` | Tell the platform when to run hooks or plugins. |
+| agents | `.claude/agents/`, `.codex/agents/`, `.kiro/agents/`, `.zcode/cli/agents/` | Define agents such as `cviauto-research`, `cviauto-implement`, and `cviauto-check`. |
+| skills | `.claude/skills/`, `.agents/skills/`, `.qoder/skills/` | Skills that auto-trigger or can be read by AI. |
+| commands/prompts/workflows | `.cursor/commands/`, `.github/prompts/`, `.devin/workflows/`, `.zcode/commands/` | Explicit user-invoked command or workflow entry points. |
+
+When modifying a platform directory, also confirm whether `.cviauto/workflow.md` still describes the same flow.
+
+## Meaning Of Template Hashes
+
+`.cviauto/.template-hashes.json` records the content hash from the last time Cviauto wrote a template file. `cviauto update` uses it to distinguish three cases:
+
+| Case | Update behavior |
+| --- | --- |
+| File was not modified by the user | It can be updated automatically. |
+| File was modified by the user | Prompt the user to overwrite, keep, or generate `.new`. |
+| File is no longer a current template | It may be deleted, renamed, or preserved according to migration rules. |
+
+When an AI customizes local Cviauto files, it does not need to maintain hashes manually. It is normal for Cviauto update to recognize the result as "modified by the user."
+
+## Local Customization Boundaries
+
+Editable by default:
+
+- `.cviauto/workflow.md`
+- `.cviauto/config.yaml`
+- `.cviauto/spec/**`
+- `.cviauto/scripts/**`
+- Platform hooks, settings, agents, skills, commands, prompts, and workflows
+
+Do not edit by default:
+
+- Global npm install directory
+- `node_modules/@baoanaz/cviauto`
+- Cviauto GitHub repository source code
+- Concrete state files under `.cviauto/.runtime/**`
+- Hash contents inside `.cviauto/.template-hashes.json`
+
+Switch to the Cviauto CLI source-code perspective only when the user explicitly wants to contribute upstream.

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

@@ -0,0 +1,69 @@
+# Local Multi-Agent Channel Runtime
+
+`cviauto channel` is the local multi-agent collaboration runtime shipped with the Cviauto CLI. It lets the main AI session spawn peer workers (Claude Code, Codex, or any agent definition under `.cviauto/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 `cviauto-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 `.cviauto/agents/`: platform-agnostic role cards consumed by `cviauto channel spawn --agent <name>`.
+3. **Project configuration** in `.cviauto/config.yaml`: worker guard thresholds and other channel knobs.
+
+## Core Paths
+
+| Path | Purpose |
+| --- | --- |
+| `~/.cviauto/channels/<project>/<channel>/events.jsonl` | Per-channel append-only event log. Sequence-locked, replay-safe. |
+| `~/.cviauto/channels/<project>/<channel>/<channel>.lock` | Channel-level write lock. |
+| `~/.cviauto/channels/<project>/<channel>/<worker>.spawnlock` | Per-worker spawn lock used by the OOM guard. |
+| `~/.cviauto/channels/<project>/<channel>/.seq` | Sequence sidecar for ordered event assignment. |
+| `~/.cviauto/channels/_global/<channel>/...` | Channels created with `--scope global`. The project bucket is replaced by a shared key. |
+| `.cviauto/agents/check.md` | Default Check Agent role definition consumed by `--agent check`. |
+| `.cviauto/agents/implement.md` | Default Implement Agent role definition consumed by `--agent implement`. |
+| `.cviauto/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 `cviauto mem` instead of a channel.
+
+## Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Change default channel worker idle timeout | `channel.worker_guard.idle_timeout` in `.cviauto/config.yaml`. Accepts `5m`, `30s`, etc. Set `0` to disable idle cleanup. |
+| Change live worker budget | `channel.worker_guard.max_live_workers` in `.cviauto/config.yaml`. Set `0` to disable the spawn-time budget check. |
+| Override worker guard per spawn | Pass `--idle-timeout` / `--max-live-workers` on `cviauto 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 `.cviauto/agents/check.md` or `.cviauto/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 `.cviauto/agents/`. `cviauto 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 > `.cviauto/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 `cviauto channel spawn --agent check` or `--agent implement` instead of a platform sub-agent. If `.cviauto/agents/check.md` or `implement.md` is missing, `cviauto workflow --template <id>` prints a non-blocking warning at install time. Restore them with `cviauto 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 `.cviauto/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 Cviauto CLI binary, not in the project.
+- **Platform sub-agent files vs. channel workers**: editing `.claude/agents/cviauto-implement.md` (and its peers in other platform `.X/agents/` directories) does NOT change channel-runtime worker behavior — channel workers load `.cviauto/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 `cviauto-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 `cviauto-channel` skill (auto-installed under each platform's skills directory after `cviauto init` / `cviauto 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/overview.md

@@ -0,0 +1,51 @@
+# Local Cviauto Architecture Overview
+
+`cviauto-meta` is for user projects that have already run `cviauto init`. The user's machine usually has only the npm-installed `cviauto` command plus the Cviauto files generated inside the project; it may not have the Cviauto CLI source code.
+
+Therefore, when an AI uses this skill, the default customization target is local files inside the user project:
+
+- `.cviauto/`: workflow, tasks, specs, memory, scripts, and runtime state.
+- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.devin/`, `.reasonix/`, `.zcode/`, and similar directories.
+- Shared skill layer: `.agents/skills/`.
+
+Do not default to guiding the user to fork the Cviauto CLI repository. Treat upstream source code as the operating target only when the user explicitly says they want to change Cviauto upstream source, publish an npm package, or contribute a PR.
+
+## Local System Model
+
+Cviauto provides three layers inside a user project:
+
+1. **Workflow layer**: `.cviauto/workflow.md` defines phases, routing, next actions, and prompt blocks.
+2. **Persistence layer**: `.cviauto/tasks/`, `.cviauto/spec/`, and `.cviauto/workspace/` store tasks, specs, and session memory.
+3. **Platform integration layer**: hooks, settings, agents, skills, commands, prompts, and workflows in platform directories connect the Cviauto workflow to different AI tools.
+
+All three layers live inside the user project, so an AI can read and modify them directly.
+
+## Core Paths
+
+| Path | Purpose |
+| --- | --- |
+| `.cviauto/workflow.md` | Workflow phases, skill routing, and workflow-state prompt blocks. |
+| `.cviauto/config.yaml` | Project configuration, task lifecycle hooks, monorepo package configuration, and journal configuration. |
+| `.cviauto/spec/` | The user's project-specific coding conventions and thinking guides. |
+| `.cviauto/tasks/` | Each task's PRD, technical notes, research files, and JSONL context. |
+| `.cviauto/workspace/` | Per-developer journals and cross-session memory. |
+| `.cviauto/scripts/` | Local Python runtime used by commands, hooks, and context injection. |
+| `.cviauto/.runtime/` | Session-level runtime state, such as the current task pointer. |
+| `.cviauto/.template-hashes.json` | Template hashes for Cviauto-managed files, used by update to determine whether local files were modified by the user. |
+
+## AI Customization Principles
+
+1. **Find the local source of truth first**: Do not edit from memory. Read `.cviauto/workflow.md`, `.cviauto/config.yaml`, the relevant platform directory, and related task files first.
+2. **Edit the user project, not the npm package cache**: Modify generated files inside the project, not `node_modules` or the global npm install directory.
+3. **Keep platform files aligned with `.cviauto/`**: If workflow routing changes, also check whether platform skills or commands still describe the same flow.
+4. **Put project-specific rules in `.cviauto/spec/` or a local skill**: Do not put team conventions into `cviauto-meta`.
+5. **Preserve user changes**: If a file was already modified locally, work from the current content instead of overwriting it with a default template.
+
+## How To Use This Directory
+
+- To understand which files exist after init, read `generated-files.md`.
+- To change phases, routing, or next actions, read `workflow.md`.
+- To change the task model, JSONL context, or active task behavior, read `task-system.md`.
+- To change coding convention injection, read `spec-system.md`.
+- To understand journals and cross-session memory, read `workspace-memory.md`.
+- To change hooks or sub-agent context loading, read `context-injection.md`.

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

@@ -0,0 +1,102 @@
+# Local Spec System
+
+`.cviauto/spec/` is the user's project-specific engineering spec library. Cviauto is not about making AI memorize conventions; it injects relevant specs or requires the AI to read them at the right time.
+
+## Directory Model
+
+A common single-repository structure:
+
+```text
+.cviauto/spec/
+├── backend/
+│   ├── index.md
+│   └── ...
+├── frontend/
+│   ├── index.md
+│   └── ...
+└── guides/
+    ├── index.md
+    └── ...
+```
+
+A common monorepo structure:
+
+```text
+.cviauto/spec/
+├── cli/
+│   ├── backend/
+│   │   ├── index.md
+│   │   └── ...
+│   └── unit-test/
+│       ├── index.md
+│       └── ...
+├── docs-site/
+│   └── docs/
+│       ├── index.md
+│       └── ...
+└── guides/
+    ├── index.md
+    └── ...
+```
+
+`index.md` is the entry point for each layer. It should list the Pre-Development Checklist and Quality Check. Specific guidelines live in other Markdown files in the same directory.
+
+## Package Configuration
+
+`.cviauto/config.yaml` can declare packages:
+
+```yaml
+packages:
+  cli:
+    path: packages/cli
+  docs-site:
+    path: docs-site
+    type: submodule
+default_package: cli
+```
+
+The AI can run:
+
+```bash
+python3 ./.cviauto/scripts/get_context.py --mode packages
+```
+
+This command lists packages and spec layers for the current project. Use this output as the reference when configuring context JSONL.
+
+## How Specs Enter Tasks
+
+Before a task enters implementation, planning may write relevant specs into `implement.jsonl` / `check.jsonl` when the task needs spec or research context beyond the task artifacts:
+
+```jsonl
+{"file": ".cviauto/spec/cli/backend/index.md", "reason": "CLI backend conventions"}
+{"file": ".cviauto/spec/cli/unit-test/conventions.md", "reason": "Test expectations"}
+```
+
+Sub-agents or platform preludes read these JSONL files and load the referenced specs. On platforms without sub-agent support, the AI should read the relevant specs directly according to the workflow.
+
+## What Specs Should Contain
+
+Specs should contain executable engineering conventions for the project, not generic best practices:
+
+- Where files should live.
+- How error handling should be expressed.
+- Input/output contracts for APIs, hooks, and commands.
+- Patterns that are forbidden.
+- Cases that require tests.
+- Project-specific pitfalls and how to avoid them.
+
+When the AI learns a new rule during implementation or debugging, it should update `.cviauto/spec/` rather than only summarizing it in chat.
+
+## Local Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Add a new spec layer | `.cviauto/spec/<package>/<layer>/index.md` and corresponding guideline files. |
+| Change monorepo spec mapping | `packages` / `default_package` / `spec_scope` in `.cviauto/config.yaml`. |
+| Change which specs AI reads before implementation | The task's `implement.jsonl`. |
+| Change which specs AI reads during checking | The task's `check.jsonl`. |
+| Change when specs should be updated | Phase 3.3 in `.cviauto/workflow.md` and the `cviauto-update-spec` skill. Default native workflow runs this only when the user explicitly asks to promote knowledge into spec. |
+
+## Boundaries
+
+`.cviauto/spec/` is the user's project specification, not a permanent copy of Cviauto built-in templates. The AI should encourage the user to update it according to the actual project code instead of treating Cviauto default templates as immutable documents.