diff --git a/.agents/skills/trellis-meta/SKILL.md b/.agents/skills/trellis-meta/SKILL.md index 0ffe5939f..91b23b691 100644 --- a/.agents/skills/trellis-meta/SKILL.md +++ b/.agents/skills/trellis-meta/SKILL.md @@ -12,7 +12,7 @@ Trellis v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow / The default operating scope is local files in the user project: - `.trellis/`: workflow, config, tasks, spec, workspace, scripts, bundled runtime agents, and runtime state. -- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills//SKILL.md`; subagent skills carry `runAs: subagent` frontmatter. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer and delivers commands plus agent prompts as `.kimi-code/skills//SKILL.md`. +- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills//SKILL.md`; subagent skills carry `runAs: subagent` frontmatter. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer, delivers commands plus agent prompts as `.kimi-code/skills//SKILL.md`, and installs the same agent prompts as custom sub-agents under `.kimi-code/agents/.md`. - Shared skill layer: `.agents/skills/`. - User-owned channel store outside the project tree: `~/.trellis/channels///events.jsonl`. - Raw platform conversation logs queryable via `trellis mem`: `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` (OpenCode adapter degraded for the v0.6 line). diff --git a/.agents/skills/trellis-meta/references/platform-files/agents.md b/.agents/skills/trellis-meta/references/platform-files/agents.md index 26f472ab4..7e5e47f2c 100644 --- a/.agents/skills/trellis-meta/references/platform-files/agents.md +++ b/.agents/skills/trellis-meta/references/platform-files/agents.md @@ -34,7 +34,7 @@ Agent files should not become generic chat prompts. They should define input sou | Pi Agent | `.pi/agents/trellis-*.md` | | Reasonix | `.reasonix/skills/trellis-*/SKILL.md` (subagent frontmatter) | | ZCode | `.zcode/agents/trellis-*.md` | -| Kimi Code | `.kimi-code/skills/trellis-*/SKILL.md` (agent prompts as skills, dispatched to the built-in `coder`; research needs its file-editing tools to persist findings) | +| Kimi Code | `.kimi-code/agents/trellis-*.md` (custom sub-agents; the same prompts also ship as `.kimi-code/skills/trellis-*/SKILL.md`) | GitHub Copilot agent/prompt support is provided by a combination of directories such as `.github/agents/`, `.github/prompts/`, and `.github/skills/`; inspect the files actually generated in the user project. diff --git a/.agents/skills/trellis-meta/references/platform-files/hooks-and-settings.md b/.agents/skills/trellis-meta/references/platform-files/hooks-and-settings.md index a2ff389ca..85f7f11af 100644 --- a/.agents/skills/trellis-meta/references/platform-files/hooks-and-settings.md +++ b/.agents/skills/trellis-meta/references/platform-files/hooks-and-settings.md @@ -29,7 +29,7 @@ Common files: | Pi Agent | `.pi/settings.json`, `.pi/extensions/trellis/` | | Trae IDE | `.trae/hooks.json` | -Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills with the same prelude. +Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills and `.kimi-code/agents/` sub-agent definitions with the same prelude. Whether these files exist in a project depends on which `trellis init --` flags the user ran. diff --git a/.agents/skills/trellis-meta/references/platform-files/platform-map.md b/.agents/skills/trellis-meta/references/platform-files/platform-map.md index 73b113a66..026773f58 100644 --- a/.agents/skills/trellis-meta/references/platform-files/platform-map.md +++ b/.agents/skills/trellis-meta/references/platform-files/platform-map.md @@ -24,7 +24,7 @@ This page lists common Trellis file locations in a user project by platform. Whe | Reasonix | `--reasonix` | `.reasonix/` | `.reasonix/skills/` | None — sub-agents are skills with `runAs: subagent` frontmatter | None | | ZCode | `--zcode` | `.zcode/` | `.zcode/skills/` | `.zcode/agents/` | `.zcode/hooks/` + `.zcode/config.json` (SessionStart + UserPromptSubmit + PreToolUse Agent/Task); sub-agents use hook-injected context | | Grok Build | `--grok` | `.grok/` | `.grok/skills/` | `.grok/agents/` | pull-based prelude (no hooks; flat `.grok/commands/trellis-*.md`) | -| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | None — agent prompts are skills under `.kimi-code/skills/` and dispatch to the built-in `coder` | None (pull-based prelude; no project hooks/settings) | +| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | `.kimi-code/agents/` (custom sub-agents; same prompts also ship as skills) | None (pull-based prelude; no project hooks/settings) | | Snow CLI | `--snow` | `.snow/` | `.snow/skills/` | `.snow/agents/` (auto-discovered; primary path) | class-1: auto inject + project agents + `beforeSubAgentStart` (`.snow/hooks/` `session`/`user`/`subagent` modes -> `additionalContext` JSON); no legacy sub-agent JSON; commands `.snow/commands/trellis-*.json` | ## Capability Groups @@ -48,7 +48,7 @@ These platforms usually have `trellis-research`, `trellis-implement`, and `trell - Reasonix (delivered as skills with `runAs: subagent` under `.reasonix/skills/`, not as a separate `agents/` directory) - ZCode - Grok Build (`.grok/agents/`; dispatch via `spawn_subagent` with `subagent_type`) -- Kimi Code (delivered as skills under `.kimi-code/skills/`; dispatched to the built-in `coder`, including research because it must persist files) +- Kimi Code (`.kimi-code/agents/`; the same prompts are also delivered as skills under `.kimi-code/skills/`) - Snow CLI (`.snow/agents/`; auto-discovered project agents + class-1 hooks) When changing implementation/check/research behavior, look for the corresponding platform agent files first. diff --git a/.claude/skills/trellis-meta/SKILL.md b/.claude/skills/trellis-meta/SKILL.md index 0ffe5939f..91b23b691 100644 --- a/.claude/skills/trellis-meta/SKILL.md +++ b/.claude/skills/trellis-meta/SKILL.md @@ -12,7 +12,7 @@ Trellis v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow / The default operating scope is local files in the user project: - `.trellis/`: workflow, config, tasks, spec, workspace, scripts, bundled runtime agents, and runtime state. -- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills//SKILL.md`; subagent skills carry `runAs: subagent` frontmatter. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer and delivers commands plus agent prompts as `.kimi-code/skills//SKILL.md`. +- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills//SKILL.md`; subagent skills carry `runAs: subagent` frontmatter. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer, delivers commands plus agent prompts as `.kimi-code/skills//SKILL.md`, and installs the same agent prompts as custom sub-agents under `.kimi-code/agents/.md`. - Shared skill layer: `.agents/skills/`. - User-owned channel store outside the project tree: `~/.trellis/channels///events.jsonl`. - Raw platform conversation logs queryable via `trellis mem`: `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` (OpenCode adapter degraded for the v0.6 line). diff --git a/.claude/skills/trellis-meta/references/platform-files/agents.md b/.claude/skills/trellis-meta/references/platform-files/agents.md index 26f472ab4..7e5e47f2c 100644 --- a/.claude/skills/trellis-meta/references/platform-files/agents.md +++ b/.claude/skills/trellis-meta/references/platform-files/agents.md @@ -34,7 +34,7 @@ Agent files should not become generic chat prompts. They should define input sou | Pi Agent | `.pi/agents/trellis-*.md` | | Reasonix | `.reasonix/skills/trellis-*/SKILL.md` (subagent frontmatter) | | ZCode | `.zcode/agents/trellis-*.md` | -| Kimi Code | `.kimi-code/skills/trellis-*/SKILL.md` (agent prompts as skills, dispatched to the built-in `coder`; research needs its file-editing tools to persist findings) | +| Kimi Code | `.kimi-code/agents/trellis-*.md` (custom sub-agents; the same prompts also ship as `.kimi-code/skills/trellis-*/SKILL.md`) | GitHub Copilot agent/prompt support is provided by a combination of directories such as `.github/agents/`, `.github/prompts/`, and `.github/skills/`; inspect the files actually generated in the user project. diff --git a/.claude/skills/trellis-meta/references/platform-files/hooks-and-settings.md b/.claude/skills/trellis-meta/references/platform-files/hooks-and-settings.md index a2ff389ca..85f7f11af 100644 --- a/.claude/skills/trellis-meta/references/platform-files/hooks-and-settings.md +++ b/.claude/skills/trellis-meta/references/platform-files/hooks-and-settings.md @@ -29,7 +29,7 @@ Common files: | Pi Agent | `.pi/settings.json`, `.pi/extensions/trellis/` | | Trae IDE | `.trae/hooks.json` | -Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills with the same prelude. +Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills and `.kimi-code/agents/` sub-agent definitions with the same prelude. Whether these files exist in a project depends on which `trellis init --` flags the user ran. diff --git a/.claude/skills/trellis-meta/references/platform-files/platform-map.md b/.claude/skills/trellis-meta/references/platform-files/platform-map.md index 73b113a66..026773f58 100644 --- a/.claude/skills/trellis-meta/references/platform-files/platform-map.md +++ b/.claude/skills/trellis-meta/references/platform-files/platform-map.md @@ -24,7 +24,7 @@ This page lists common Trellis file locations in a user project by platform. Whe | Reasonix | `--reasonix` | `.reasonix/` | `.reasonix/skills/` | None — sub-agents are skills with `runAs: subagent` frontmatter | None | | ZCode | `--zcode` | `.zcode/` | `.zcode/skills/` | `.zcode/agents/` | `.zcode/hooks/` + `.zcode/config.json` (SessionStart + UserPromptSubmit + PreToolUse Agent/Task); sub-agents use hook-injected context | | Grok Build | `--grok` | `.grok/` | `.grok/skills/` | `.grok/agents/` | pull-based prelude (no hooks; flat `.grok/commands/trellis-*.md`) | -| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | None — agent prompts are skills under `.kimi-code/skills/` and dispatch to the built-in `coder` | None (pull-based prelude; no project hooks/settings) | +| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | `.kimi-code/agents/` (custom sub-agents; same prompts also ship as skills) | None (pull-based prelude; no project hooks/settings) | | Snow CLI | `--snow` | `.snow/` | `.snow/skills/` | `.snow/agents/` (auto-discovered; primary path) | class-1: auto inject + project agents + `beforeSubAgentStart` (`.snow/hooks/` `session`/`user`/`subagent` modes -> `additionalContext` JSON); no legacy sub-agent JSON; commands `.snow/commands/trellis-*.json` | ## Capability Groups @@ -48,7 +48,7 @@ These platforms usually have `trellis-research`, `trellis-implement`, and `trell - Reasonix (delivered as skills with `runAs: subagent` under `.reasonix/skills/`, not as a separate `agents/` directory) - ZCode - Grok Build (`.grok/agents/`; dispatch via `spawn_subagent` with `subagent_type`) -- Kimi Code (delivered as skills under `.kimi-code/skills/`; dispatched to the built-in `coder`, including research because it must persist files) +- Kimi Code (`.kimi-code/agents/`; the same prompts are also delivered as skills under `.kimi-code/skills/`) - Snow CLI (`.snow/agents/`; auto-discovered project agents + class-1 hooks) When changing implementation/check/research behavior, look for the corresponding platform agent files first. diff --git a/.cursor/skills/trellis-meta/SKILL.md b/.cursor/skills/trellis-meta/SKILL.md index 0ffe5939f..91b23b691 100644 --- a/.cursor/skills/trellis-meta/SKILL.md +++ b/.cursor/skills/trellis-meta/SKILL.md @@ -12,7 +12,7 @@ Trellis v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow / The default operating scope is local files in the user project: - `.trellis/`: workflow, config, tasks, spec, workspace, scripts, bundled runtime agents, and runtime state. -- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills//SKILL.md`; subagent skills carry `runAs: subagent` frontmatter. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer and delivers commands plus agent prompts as `.kimi-code/skills//SKILL.md`. +- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills//SKILL.md`; subagent skills carry `runAs: subagent` frontmatter. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer, delivers commands plus agent prompts as `.kimi-code/skills//SKILL.md`, and installs the same agent prompts as custom sub-agents under `.kimi-code/agents/.md`. - Shared skill layer: `.agents/skills/`. - User-owned channel store outside the project tree: `~/.trellis/channels///events.jsonl`. - Raw platform conversation logs queryable via `trellis mem`: `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` (OpenCode adapter degraded for the v0.6 line). diff --git a/.cursor/skills/trellis-meta/references/platform-files/agents.md b/.cursor/skills/trellis-meta/references/platform-files/agents.md index 26f472ab4..7e5e47f2c 100644 --- a/.cursor/skills/trellis-meta/references/platform-files/agents.md +++ b/.cursor/skills/trellis-meta/references/platform-files/agents.md @@ -34,7 +34,7 @@ Agent files should not become generic chat prompts. They should define input sou | Pi Agent | `.pi/agents/trellis-*.md` | | Reasonix | `.reasonix/skills/trellis-*/SKILL.md` (subagent frontmatter) | | ZCode | `.zcode/agents/trellis-*.md` | -| Kimi Code | `.kimi-code/skills/trellis-*/SKILL.md` (agent prompts as skills, dispatched to the built-in `coder`; research needs its file-editing tools to persist findings) | +| Kimi Code | `.kimi-code/agents/trellis-*.md` (custom sub-agents; the same prompts also ship as `.kimi-code/skills/trellis-*/SKILL.md`) | GitHub Copilot agent/prompt support is provided by a combination of directories such as `.github/agents/`, `.github/prompts/`, and `.github/skills/`; inspect the files actually generated in the user project. diff --git a/.cursor/skills/trellis-meta/references/platform-files/hooks-and-settings.md b/.cursor/skills/trellis-meta/references/platform-files/hooks-and-settings.md index a2ff389ca..85f7f11af 100644 --- a/.cursor/skills/trellis-meta/references/platform-files/hooks-and-settings.md +++ b/.cursor/skills/trellis-meta/references/platform-files/hooks-and-settings.md @@ -29,7 +29,7 @@ Common files: | Pi Agent | `.pi/settings.json`, `.pi/extensions/trellis/` | | Trae IDE | `.trae/hooks.json` | -Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills with the same prelude. +Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills and `.kimi-code/agents/` sub-agent definitions with the same prelude. Whether these files exist in a project depends on which `trellis init --` flags the user ran. diff --git a/.cursor/skills/trellis-meta/references/platform-files/platform-map.md b/.cursor/skills/trellis-meta/references/platform-files/platform-map.md index 73b113a66..026773f58 100644 --- a/.cursor/skills/trellis-meta/references/platform-files/platform-map.md +++ b/.cursor/skills/trellis-meta/references/platform-files/platform-map.md @@ -24,7 +24,7 @@ This page lists common Trellis file locations in a user project by platform. Whe | Reasonix | `--reasonix` | `.reasonix/` | `.reasonix/skills/` | None — sub-agents are skills with `runAs: subagent` frontmatter | None | | ZCode | `--zcode` | `.zcode/` | `.zcode/skills/` | `.zcode/agents/` | `.zcode/hooks/` + `.zcode/config.json` (SessionStart + UserPromptSubmit + PreToolUse Agent/Task); sub-agents use hook-injected context | | Grok Build | `--grok` | `.grok/` | `.grok/skills/` | `.grok/agents/` | pull-based prelude (no hooks; flat `.grok/commands/trellis-*.md`) | -| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | None — agent prompts are skills under `.kimi-code/skills/` and dispatch to the built-in `coder` | None (pull-based prelude; no project hooks/settings) | +| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | `.kimi-code/agents/` (custom sub-agents; same prompts also ship as skills) | None (pull-based prelude; no project hooks/settings) | | Snow CLI | `--snow` | `.snow/` | `.snow/skills/` | `.snow/agents/` (auto-discovered; primary path) | class-1: auto inject + project agents + `beforeSubAgentStart` (`.snow/hooks/` `session`/`user`/`subagent` modes -> `additionalContext` JSON); no legacy sub-agent JSON; commands `.snow/commands/trellis-*.json` | ## Capability Groups @@ -48,7 +48,7 @@ These platforms usually have `trellis-research`, `trellis-implement`, and `trell - Reasonix (delivered as skills with `runAs: subagent` under `.reasonix/skills/`, not as a separate `agents/` directory) - ZCode - Grok Build (`.grok/agents/`; dispatch via `spawn_subagent` with `subagent_type`) -- Kimi Code (delivered as skills under `.kimi-code/skills/`; dispatched to the built-in `coder`, including research because it must persist files) +- Kimi Code (`.kimi-code/agents/`; the same prompts are also delivered as skills under `.kimi-code/skills/`) - Snow CLI (`.snow/agents/`; auto-discovered project agents + class-1 hooks) When changing implementation/check/research behavior, look for the corresponding platform agent files first. diff --git a/.omp/skills/trellis-meta/SKILL.md b/.omp/skills/trellis-meta/SKILL.md index 590bfac3f..91b23b691 100644 --- a/.omp/skills/trellis-meta/SKILL.md +++ b/.omp/skills/trellis-meta/SKILL.md @@ -1,73 +1,85 @@ --- name: trellis-meta -description: "Understand and customize the local Trellis architecture inside a user project. Use when modifying .trellis plus platform hooks, settings, agents, skills, commands, prompts, or workflows generated by trellis init." +description: "Understand and customize the local Trellis architecture inside a user project. Use when modifying .trellis plus platform hooks, settings, agents, skills, commands, prompts, workflows, the channel runtime (trellis channel), bundled runtime agents under .trellis/agents/, selectable workflow templates, registry-backed spec refresh, cross-session memory (trellis mem) generated by trellis init, or AI-facing bundled skills (trellis-channel, trellis-session-insight, trellis-spec-bootstrap) and bundled-skill auto-dispatch flow." --- # Trellis Meta This skill is for local Trellis users who have already run `trellis init` in a project. After reading it, an AI should understand the Trellis architecture, operating model, and customization entry points inside that user project, then modify the generated `.trellis/` and platform directory files according to the user's request. +Trellis v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow / persistence / platform model. First, a multi-agent collaboration runtime: `trellis channel` coordinates multiple AI worker processes through project-scoped JSONL event logs at `~/.trellis/channels///events.jsonl`, with worker OOM guard, forum/thread channels, durable idempotency keys, and bundled `.trellis/agents/{check,implement}.md` runtime definitions. Second, cross-session memory: `trellis mem list | search | context | extract | projects` reads raw Claude Code, Codex, and Pi Agent JSONL already on disk, slices by `--phase brainstorm|implement|all`, and never uploads anything. Third, a dual-package npm release: `@mindfoldhq/trellis` (CLI) and `@mindfoldhq/trellis-core` (SDK with `/channel`, `/task`, `/mem`, `/testing` subpaths) ship in lockstep on one version. Treat these as first-class customization surfaces alongside the per-platform integration files. + The default operating scope is local files in the user project: -- `.trellis/`: workflow, config, tasks, spec, workspace, scripts, and runtime state. -- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.windsurf/`, and similar directories. +- `.trellis/`: workflow, config, tasks, spec, workspace, scripts, bundled runtime agents, and runtime state. +- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills//SKILL.md`; subagent skills carry `runAs: subagent` frontmatter. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer, delivers commands plus agent prompts as `.kimi-code/skills//SKILL.md`, and installs the same agent prompts as custom sub-agents under `.kimi-code/agents/.md`. - Shared skill layer: `.agents/skills/`. +- User-owned channel store outside the project tree: `~/.trellis/channels///events.jsonl`. +- Raw platform conversation logs queryable via `trellis mem`: `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` (OpenCode adapter degraded for the v0.6 line). -Do not assume the user has the Trellis source repository. Do not default to modifying the global npm install directory or `node_modules`. +Do not assume the user has the Trellis source repository. Do not default to modifying the global npm install directory or `node_modules` — both `@mindfoldhq/trellis` and `@mindfoldhq/trellis-core` ship as published packages sharing one version and one git tag per release. ## How To Use 1. Read `references/local-architecture/overview.md` first to establish the local Trellis system model. 2. If the request involves a specific AI tool, read `references/platform-files/platform-map.md` and the relevant platform file notes. -3. If the user wants to change behavior, read `references/customize-local/overview.md`, then open the specific customization topic. -4. Before editing, read the actual files in the user project and treat local content as authoritative. +3. If the request involves multi-agent dispatch or channel workers, read `references/local-architecture/multi-agent-channel.md` and the bundled `.trellis/agents/` files. +4. If the user wants to change behavior, read `references/customize-local/overview.md`, then open the specific customization topic. +5. Before editing, read the actual files in the user project and treat local content as authoritative. ## References ### Local Architecture -- `references/local-architecture/overview.md`: The three-layer local Trellis architecture and customization principles. -- `references/local-architecture/generated-files.md`: Files generated by `trellis init` and their customization boundaries. -- `references/local-architecture/workflow.md`: Phases, routing, and workflow-state blocks in `.trellis/workflow.md`. -- `references/local-architecture/task-system.md`: Task directories, active tasks, JSONL context, and task runtime. -- `references/local-architecture/spec-system.md`: How `.trellis/spec/` is organized and injected. -- `references/local-architecture/workspace-memory.md`: `.trellis/workspace/`, journals, and cross-session memory. -- `references/local-architecture/context-injection.md`: Hooks, sub-agent preludes, and context injection paths. +- `references/local-architecture/overview.md`: The layered local Trellis architecture (workflow / persistence / platform / channel runtime) and customization principles. +- `references/local-architecture/generated-files.md`: Files generated by `trellis init` and their customization boundaries, including `.trellis/agents/`. +- `references/local-architecture/workflow.md`: Phases, routing, workflow-state blocks, and selectable workflow templates (`native`, `tdd`, `channel-driven-subagent-dispatch`, marketplace) in `.trellis/workflow.md`. +- `references/local-architecture/task-system.md`: Task directories, active task, JSONL context, parent/child task trees, and task runtime. +- `references/local-architecture/spec-system.md`: How `.trellis/spec/` is organized, injected, and refreshed from a `registry.spec` source. +- `references/local-architecture/workspace-memory.md`: `.trellis/workspace/` journals plus `trellis mem` cross-session recall and the `@mindfoldhq/trellis-core/mem` SDK. +- `references/local-architecture/context-injection.md`: Hooks, sub-agent preludes, and channel-runtime worker inbox routing. +- `references/local-architecture/multi-agent-channel.md`: `trellis channel` subcommands, project-scoped event store, forum/thread channels, worker OOM guard, durable idempotency, and bundled `.trellis/agents/` runtime agents. +- `references/local-architecture/bundled-skills.md`: Auto-dispatched bundled skills (`trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`) and how `getBundledSkillTemplates()` ships them to every platform skill root. ### Platform Files -- `references/platform-files/overview.md`: How shared `.trellis/` files relate to platform directories. -- `references/platform-files/platform-map.md`: Platform directories and paths for skills, agents, hooks, and extensions. -- `references/platform-files/hooks-and-settings.md`: How settings/config files, hooks, plugins, and extensions connect to Trellis. -- `references/platform-files/agents.md`: Local file responsibilities for `trellis-research`, `trellis-implement`, and `trellis-check`. +- `references/platform-files/overview.md`: How shared `.trellis/` files relate to platform directories and the four platform integration modes (hook-driven, agent prelude, main-session workflow, channel runtime). +- `references/platform-files/platform-map.md`: Platform directories and paths for skills, agents, hooks, and extensions across all supported platforms including Reasonix and Pi's native `trellis_subagent` extension. +- `references/platform-files/hooks-and-settings.md`: How settings/config files, hooks, plugins, and extensions connect to Trellis; covers `channel.worker_guard.*` and `codex.dispatch_mode`. +- `references/platform-files/agents.md`: Per-platform `trellis-research` / `trellis-implement` / `trellis-check` sub-agent files plus bundled `.trellis/agents/{check,implement}.md` for the channel runtime. - `references/platform-files/skills-and-commands.md`: Differences between skills, commands, prompts, and workflows, plus how to change them. ### Local Customization - `references/customize-local/overview.md`: Choose the right local customization entry point for the user's request. -- `references/customize-local/change-workflow.md`: Change phases, routing, next actions, and workflow-state. -- `references/customize-local/change-task-lifecycle.md`: Change task creation, status, archive behavior, and hooks. -- `references/customize-local/change-context-loading.md`: Change how tasks, specs, journals, and hook context are loaded. -- `references/customize-local/change-hooks.md`: Change platform hooks, settings, and shell session bridges. -- `references/customize-local/change-agents.md`: Change research, implement, and check agent behavior. -- `references/customize-local/change-skills-or-commands.md`: Add or modify local skills, commands, prompts, and workflows. -- `references/customize-local/change-spec-structure.md`: Adjust the project spec structure under `.trellis/spec/`. +- `references/customize-local/change-workflow.md`: Change phases, routing, next actions, workflow-state, and the selected workflow template. +- `references/customize-local/change-task-lifecycle.md`: Change task creation, status, archive behavior, parent/child links, archive slug collision handling, and lifecycle hooks. +- `references/customize-local/change-context-loading.md`: Change how tasks, specs, journals, hook context, channel inbox messages, and `trellis mem` recall are loaded. +- `references/customize-local/change-hooks.md`: Change platform hooks, settings, task lifecycle hooks (`hooks.after_*`), and shell session bridges. +- `references/customize-local/change-agents.md`: Change research, implement, and check agent behavior across platform sub-agents, bundled channel runtime agents, and the Codex `dispatch_mode` toggle. +- `references/customize-local/change-skills-or-commands.md`: Add or modify local skills, commands, prompts, and workflows; covers upstream bundled-skill auto-dispatch. +- `references/customize-local/change-spec-structure.md`: Adjust the project spec structure under `.trellis/spec/`, including registry-backed sources. - `references/customize-local/add-project-local-conventions.md`: Put team rules into project-local specs or local skills. ## Current Rules -- `.trellis/workflow.md` is the local workflow source of truth. -- `.trellis/config.yaml` is the project-level Trellis configuration and task hook configuration entry point. -- `.trellis/spec/` stores the user's project-specific coding conventions and design constraints. -- `.trellis/tasks/` stores task PRDs, technical notes, research files, and JSONL context. -- `.trellis/workspace/` stores developer journals and cross-session memory. -- Platform settings/config files decide which hooks, agents, skills, commands, prompts, and workflows actually run. +- `.trellis/workflow.md` is the local workflow source of truth; its initial content was selected from a workflow template (built-in `native`, `tdd`, `channel-driven-subagent-dispatch`, or a marketplace template) at `trellis init` time and can be re-selected via `trellis workflow --template `. Missing `.trellis/agents/.md` files referenced by the active template trigger a non-blocking stderr warning pointing at `trellis update`. +- `.trellis/config.yaml` is the project-level Trellis configuration entry point. It hosts task lifecycle hooks (`hooks.after_create` / `after_start` / `after_finish` / `after_archive`), journal shape (`session_commit_message` / `max_journal_lines` / `session_auto_commit`), channel worker guard (`channel.worker_guard.idle_timeout` / `max_live_workers`), Codex dispatch mode (`codex.dispatch_mode: inline | sub-agent`), and the spec registry block (`registry.spec.source` + `registry.spec.template`). +- `.trellis/spec/` stores the user's project-specific coding conventions and design constraints. When `registry.spec` is set, files are refreshed by `trellis update`; local edits surface as "modified by user" conflicts in `.trellis/.template-hashes.json`. +- `.trellis/tasks/` stores task PRDs, design notes, implement plans, research files, and JSONL context. Tasks form parent/child trees: `task.py create --parent `, `task.py add-subtask `, `task.py remove-subtask `, and `task.py list-context `. `task.py create` rejects a slug already present in `.trellis/tasks/archive/**`. +- `.trellis/workspace/` stores **deliberately written** developer journals. Raw cross-session dialogue is **not** stored here — it lives on disk under `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` and is recovered via `trellis mem search|extract|context`. The bundled `trellis-session-insight` skill teaches when to reach for `mem`. +- `.trellis/agents/{check,implement}.md` are bundled, platform-agnostic channel runtime agent definitions loaded by `trellis channel spawn --agent `. Editable; `trellis update` backfills missing ones. Editing the per-platform `trellis-implement.md` / `trellis-check.md` does **not** change channel-runtime worker behavior. +- `~/.trellis/channels///events.jsonl` is the channel runtime event log per project per channel. User-owned, file-locked sequence numbering, durable `idempotencyKey` support; never under `.trellis/`. +- Bundled multi-file skills (`trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`) are auto-dispatched to every platform skill root by `getBundledSkillTemplates()` in `packages/cli/src/templates/common/index.ts`. Dropping a new directory under `packages/cli/src/templates/common/bundled-skills/` (upstream) ships it to every platform on the next `trellis update`. +- Platform settings/config files decide which hooks, agents, skills, commands, prompts, and workflows actually run. Reasonix has no settings file — behavior is encoded inside skill frontmatter. - `.trellis/.template-hashes.json` and `.trellis/.runtime/` are management/runtime state files. Confirm necessity before editing them. ## Do Not - Do not treat Trellis upstream source code as the default target for local customization. -- Do not modify the global npm install directory or `node_modules/@mindfoldhq/trellis` to implement project needs. -- Do not overwrite user-modified local files with default templates. -- Do not put team-private project rules into the public `trellis-meta`; put project rules in `.trellis/spec/` or a project-local skill. -- Do not describe removed historical mechanisms as current Trellis behavior. +- Do not modify the global npm install directory or `node_modules/@mindfoldhq/trellis` or `node_modules/@mindfoldhq/trellis-core` to implement project needs; both packages ship in lockstep. +- Do not overwrite user-modified local files with default templates; check `.trellis/.template-hashes.json` first and prefer `.new` sidecar files over destructive overwrites. +- Do not put team-private project rules into any public bundled skill (`trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`); put project rules in `.trellis/spec/`, a project-local skill, the current task, or the workspace journal — `trellis update` will overwrite anything inside a bundled skill directory. +- Do not hand-edit `~/.trellis/channels///events.jsonl`; sequence numbers are assigned under a file lock and replay-safe writes go through the `trellis channel` CLI or the `@mindfoldhq/trellis-core/channel` SDK. +- Do not edit `.claude/agents/trellis-implement.md` (or any other per-platform sub-agent file) when the goal is to change channel runtime worker behavior — edit `.trellis/agents/.md` instead. +- Do not describe removed or never-shipped mechanisms as current Trellis behavior; cross-check against the local `.trellis/config.yaml` and the installed CLI's `trellis --help` before claiming a knob exists. diff --git a/.omp/skills/trellis-meta/references/platform-files/agents.md b/.omp/skills/trellis-meta/references/platform-files/agents.md index efbacfa08..7e5e47f2c 100644 --- a/.omp/skills/trellis-meta/references/platform-files/agents.md +++ b/.omp/skills/trellis-meta/references/platform-files/agents.md @@ -13,7 +13,7 @@ File locations and formats differ by platform, but responsibility boundaries sho | Agent | Responsibility | | --- | --- | | `trellis-research` | Investigate the question and write findings into the current task's `research/`. | -| `trellis-implement` | Implement against `prd.md`, `info.md`, `implement.jsonl`, and related spec/research. | +| `trellis-implement` | Implement against `prd.md`, optional `design.md` / `implement.md`, `implement.jsonl`, and related spec/research. | | `trellis-check` | Review changes, fix discovered issues, and run necessary checks. | Agent files should not become generic chat prompts. They should define input sources, write boundaries, whether code may be changed, and how results are reported. @@ -32,10 +32,13 @@ Agent files should not become generic chat prompts. They should define input sou | CodeBuddy | `.codebuddy/agents/trellis-*.md` | | Factory Droid | `.factory/droids/trellis-*.md` | | Pi Agent | `.pi/agents/trellis-*.md` | +| Reasonix | `.reasonix/skills/trellis-*/SKILL.md` (subagent frontmatter) | +| ZCode | `.zcode/agents/trellis-*.md` | +| Kimi Code | `.kimi-code/agents/trellis-*.md` (custom sub-agents; the same prompts also ship as `.kimi-code/skills/trellis-*/SKILL.md`) | GitHub Copilot agent/prompt support is provided by a combination of directories such as `.github/agents/`, `.github/prompts/`, and `.github/skills/`; inspect the files actually generated in the user project. -Main-session workflow platforms such as Kilo, Antigravity, and Windsurf may not have Trellis sub-agent files. They usually rely on workflows/skills to guide the main session. +Main-session workflow platforms such as Kilo, Antigravity, and Devin may not have Trellis sub-agent files. They usually rely on workflows/skills to guide the main session. ## Two Context Loading Modes @@ -50,10 +53,11 @@ Common on platforms that support agent hooks. The agent file instructs the agent to read after startup: - `python3 ./.trellis/scripts/task.py current --source` -- current task `prd.md` -- `info.md` - `implement.jsonl` or `check.jsonl` - spec/research files referenced by JSONL +- current task `prd.md` +- `design.md` if present +- `implement.md` if present This mode fits platforms whose hooks cannot reliably rewrite sub-agent prompts. @@ -70,7 +74,7 @@ This mode fits platforms whose hooks cannot reliably rewrite sub-agent prompts. ## Modification Principles 1. **Keep responsibilities single-purpose**. Do not mix research, implement, and check responsibilities into one agent. -2. **Specify the read order**. Agents must know to start from the active task and then find the PRD and JSONL. +2. **Specify the read order**. Agents must know to start from the active task, read jsonl/spec context, then read `prd.md`, `design.md` if present, and `implement.md` if present. 3. **Specify write boundaries**. Research usually only writes `research/`; implement can write code; check can fix issues. 4. **Keep semantics synchronized in multi-platform projects**. If the user configured Claude, Codex, and Cursor together, decide whether changes to one platform's agent also need to be applied to others. diff --git a/.omp/skills/trellis-meta/references/platform-files/hooks-and-settings.md b/.omp/skills/trellis-meta/references/platform-files/hooks-and-settings.md index 94156a88d..85f7f11af 100644 --- a/.omp/skills/trellis-meta/references/platform-files/hooks-and-settings.md +++ b/.omp/skills/trellis-meta/references/platform-files/hooks-and-settings.md @@ -27,6 +27,9 @@ Common files: | GitHub Copilot | `.github/copilot/hooks.json` | | Factory Droid | `.factory/settings.json` | | Pi Agent | `.pi/settings.json`, `.pi/extensions/trellis/` | +| Trae IDE | `.trae/hooks.json` | + +Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills and `.kimi-code/agents/` sub-agent definitions with the same prelude. Whether these files exist in a project depends on which `trellis init --` flags the user ran. diff --git a/.omp/skills/trellis-meta/references/platform-files/platform-map.md b/.omp/skills/trellis-meta/references/platform-files/platform-map.md index e62512905..026773f58 100644 --- a/.omp/skills/trellis-meta/references/platform-files/platform-map.md +++ b/.omp/skills/trellis-meta/references/platform-files/platform-map.md @@ -14,12 +14,18 @@ This page lists common Trellis file locations in a user project by platform. Whe | Kiro | `--kiro` | `.kiro/` | `.kiro/skills/` | `.kiro/agents/` | `.kiro/hooks/` | | Gemini CLI | `--gemini` | `.gemini/` | `.agents/skills/` | `.gemini/agents/` | `.gemini/settings.json` + `.gemini/hooks/` | | Antigravity | `--antigravity` | `.agent/` | `.agent/skills/` | Usually none | `.agent/workflows/` | -| Windsurf | `--windsurf` | `.windsurf/` | `.windsurf/skills/` | Usually none | `.windsurf/workflows/` | +| Devin | `--devin` | `.devin/` | `.devin/skills/` | Usually none | `.devin/workflows/` | | Qoder | `--qoder` | `.qoder/` | `.qoder/skills/` | `.qoder/agents/` | `.qoder/hooks/` + `.qoder/settings.json` | | 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/` | `.agents/skills/` | `.pi/agents/` | `.pi/extensions/trellis/` (native `trellis_subagent` tool) + `.pi/settings.json` | +| Trae IDE | `--trae` | `.trae/` | `.trae/skills/` | `.trae/agents/` | `.trae/hooks/` + `.trae/hooks.json` | +| Reasonix | `--reasonix` | `.reasonix/` | `.reasonix/skills/` | None — sub-agents are skills with `runAs: subagent` frontmatter | None | +| ZCode | `--zcode` | `.zcode/` | `.zcode/skills/` | `.zcode/agents/` | `.zcode/hooks/` + `.zcode/config.json` (SessionStart + UserPromptSubmit + PreToolUse Agent/Task); sub-agents use hook-injected context | +| Grok Build | `--grok` | `.grok/` | `.grok/skills/` | `.grok/agents/` | pull-based prelude (no hooks; flat `.grok/commands/trellis-*.md`) | +| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | `.kimi-code/agents/` (custom sub-agents; same prompts also ship as skills) | None (pull-based prelude; no project hooks/settings) | +| Snow CLI | `--snow` | `.snow/` | `.snow/skills/` | `.snow/agents/` (auto-discovered; primary path) | class-1: auto inject + project agents + `beforeSubAgentStart` (`.snow/hooks/` `session`/`user`/`subagent` modes -> `additionalContext` JSON); no legacy sub-agent JSON; commands `.snow/commands/trellis-*.json` | ## Capability Groups @@ -38,22 +44,36 @@ These platforms usually have `trellis-research`, `trellis-implement`, and `trell - GitHub Copilot - Factory Droid - Pi Agent +- Trae IDE +- Reasonix (delivered as skills with `runAs: subagent` under `.reasonix/skills/`, not as a separate `agents/` directory) +- ZCode +- Grok Build (`.grok/agents/`; dispatch via `spawn_subagent` with `subagent_type`) +- Kimi Code (`.kimi-code/agents/`; the same prompts are also delivered as skills under `.kimi-code/skills/`) +- Snow CLI (`.snow/agents/`; auto-discovered project agents + class-1 hooks) 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 `./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: - Kilo - Antigravity -- Windsurf +- Devin When changing behavior, inspect workflows and skills first. Do not assume Trellis sub-agents exist. ### Shared `.agents/skills/` -Codex writes the shared `.agents/skills/` layer. Some tools that support agentskills.io can also read this directory. If the user wants multiple compatible tools to share one skill, consider `.agents/skills/` first, but do not assume every platform reads it. +Codex, Gemini CLI, Pi Agent, and Kimi Code write the shared `.agents/skills/` layer. Some tools that support agentskills.io can also read this directory. If the user wants multiple compatible tools to share one skill, consider `.agents/skills/` first, but do not assume every platform reads it. ZCode keeps Trellis-managed skills under `.zcode/skills/`. ## Decision Rules When Modifying Platform Files @@ -77,7 +97,7 @@ Do not delete a custom file just because it is not listed in this path table. Extension-backed platform. OMP native provider auto-discovers all subdirectories. -``` +```text .omp/ ├── commands/ # Slash commands (flat .md) ├── skills/ # Auto-triggered skills (SKILL.md per dir) diff --git a/.opencode/skills/trellis-meta/SKILL.md b/.opencode/skills/trellis-meta/SKILL.md index 0ffe5939f..91b23b691 100644 --- a/.opencode/skills/trellis-meta/SKILL.md +++ b/.opencode/skills/trellis-meta/SKILL.md @@ -12,7 +12,7 @@ Trellis v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow / The default operating scope is local files in the user project: - `.trellis/`: workflow, config, tasks, spec, workspace, scripts, bundled runtime agents, and runtime state. -- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills//SKILL.md`; subagent skills carry `runAs: subagent` frontmatter. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer and delivers commands plus agent prompts as `.kimi-code/skills//SKILL.md`. +- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills//SKILL.md`; subagent skills carry `runAs: subagent` frontmatter. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer, delivers commands plus agent prompts as `.kimi-code/skills//SKILL.md`, and installs the same agent prompts as custom sub-agents under `.kimi-code/agents/.md`. - Shared skill layer: `.agents/skills/`. - User-owned channel store outside the project tree: `~/.trellis/channels///events.jsonl`. - Raw platform conversation logs queryable via `trellis mem`: `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` (OpenCode adapter degraded for the v0.6 line). diff --git a/.opencode/skills/trellis-meta/references/platform-files/agents.md b/.opencode/skills/trellis-meta/references/platform-files/agents.md index 26f472ab4..7e5e47f2c 100644 --- a/.opencode/skills/trellis-meta/references/platform-files/agents.md +++ b/.opencode/skills/trellis-meta/references/platform-files/agents.md @@ -34,7 +34,7 @@ Agent files should not become generic chat prompts. They should define input sou | Pi Agent | `.pi/agents/trellis-*.md` | | Reasonix | `.reasonix/skills/trellis-*/SKILL.md` (subagent frontmatter) | | ZCode | `.zcode/agents/trellis-*.md` | -| Kimi Code | `.kimi-code/skills/trellis-*/SKILL.md` (agent prompts as skills, dispatched to the built-in `coder`; research needs its file-editing tools to persist findings) | +| Kimi Code | `.kimi-code/agents/trellis-*.md` (custom sub-agents; the same prompts also ship as `.kimi-code/skills/trellis-*/SKILL.md`) | GitHub Copilot agent/prompt support is provided by a combination of directories such as `.github/agents/`, `.github/prompts/`, and `.github/skills/`; inspect the files actually generated in the user project. diff --git a/.opencode/skills/trellis-meta/references/platform-files/hooks-and-settings.md b/.opencode/skills/trellis-meta/references/platform-files/hooks-and-settings.md index a2ff389ca..85f7f11af 100644 --- a/.opencode/skills/trellis-meta/references/platform-files/hooks-and-settings.md +++ b/.opencode/skills/trellis-meta/references/platform-files/hooks-and-settings.md @@ -29,7 +29,7 @@ Common files: | Pi Agent | `.pi/settings.json`, `.pi/extensions/trellis/` | | Trae IDE | `.trae/hooks.json` | -Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills with the same prelude. +Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills and `.kimi-code/agents/` sub-agent definitions with the same prelude. Whether these files exist in a project depends on which `trellis init --` flags the user ran. diff --git a/.opencode/skills/trellis-meta/references/platform-files/platform-map.md b/.opencode/skills/trellis-meta/references/platform-files/platform-map.md index 73b113a66..026773f58 100644 --- a/.opencode/skills/trellis-meta/references/platform-files/platform-map.md +++ b/.opencode/skills/trellis-meta/references/platform-files/platform-map.md @@ -24,7 +24,7 @@ This page lists common Trellis file locations in a user project by platform. Whe | Reasonix | `--reasonix` | `.reasonix/` | `.reasonix/skills/` | None — sub-agents are skills with `runAs: subagent` frontmatter | None | | ZCode | `--zcode` | `.zcode/` | `.zcode/skills/` | `.zcode/agents/` | `.zcode/hooks/` + `.zcode/config.json` (SessionStart + UserPromptSubmit + PreToolUse Agent/Task); sub-agents use hook-injected context | | Grok Build | `--grok` | `.grok/` | `.grok/skills/` | `.grok/agents/` | pull-based prelude (no hooks; flat `.grok/commands/trellis-*.md`) | -| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | None — agent prompts are skills under `.kimi-code/skills/` and dispatch to the built-in `coder` | None (pull-based prelude; no project hooks/settings) | +| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | `.kimi-code/agents/` (custom sub-agents; same prompts also ship as skills) | None (pull-based prelude; no project hooks/settings) | | Snow CLI | `--snow` | `.snow/` | `.snow/skills/` | `.snow/agents/` (auto-discovered; primary path) | class-1: auto inject + project agents + `beforeSubAgentStart` (`.snow/hooks/` `session`/`user`/`subagent` modes -> `additionalContext` JSON); no legacy sub-agent JSON; commands `.snow/commands/trellis-*.json` | ## Capability Groups @@ -48,7 +48,7 @@ These platforms usually have `trellis-research`, `trellis-implement`, and `trell - Reasonix (delivered as skills with `runAs: subagent` under `.reasonix/skills/`, not as a separate `agents/` directory) - ZCode - Grok Build (`.grok/agents/`; dispatch via `spawn_subagent` with `subagent_type`) -- Kimi Code (delivered as skills under `.kimi-code/skills/`; dispatched to the built-in `coder`, including research because it must persist files) +- Kimi Code (`.kimi-code/agents/`; the same prompts are also delivered as skills under `.kimi-code/skills/`) - Snow CLI (`.snow/agents/`; auto-discovered project agents + class-1 hooks) When changing implementation/check/research behavior, look for the corresponding platform agent files first. diff --git a/.pi/skills/trellis-meta/SKILL.md b/.pi/skills/trellis-meta/SKILL.md index 0754b53eb..91b23b691 100644 --- a/.pi/skills/trellis-meta/SKILL.md +++ b/.pi/skills/trellis-meta/SKILL.md @@ -12,7 +12,7 @@ Trellis v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow / The default operating scope is local files in the user project: - `.trellis/`: workflow, config, tasks, spec, workspace, scripts, bundled runtime agents, and runtime state. -- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills//SKILL.md`; subagent skills carry `runAs: subagent` frontmatter. +- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills//SKILL.md`; subagent skills carry `runAs: subagent` frontmatter. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer, delivers commands plus agent prompts as `.kimi-code/skills//SKILL.md`, and installs the same agent prompts as custom sub-agents under `.kimi-code/agents/.md`. - Shared skill layer: `.agents/skills/`. - User-owned channel store outside the project tree: `~/.trellis/channels///events.jsonl`. - Raw platform conversation logs queryable via `trellis mem`: `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` (OpenCode adapter degraded for the v0.6 line). @@ -44,7 +44,7 @@ Do not assume the user has the Trellis source repository. Do not default to modi ### Platform Files - `references/platform-files/overview.md`: How shared `.trellis/` files relate to platform directories and the four platform integration modes (hook-driven, agent prelude, main-session workflow, channel runtime). -- `references/platform-files/platform-map.md`: Platform directories and paths for skills, agents, hooks, and extensions across all 15 supported platforms including Reasonix and Pi's native `trellis_subagent` extension. +- `references/platform-files/platform-map.md`: Platform directories and paths for skills, agents, hooks, and extensions across all supported platforms including Reasonix and Pi's native `trellis_subagent` extension. - `references/platform-files/hooks-and-settings.md`: How settings/config files, hooks, plugins, and extensions connect to Trellis; covers `channel.worker_guard.*` and `codex.dispatch_mode`. - `references/platform-files/agents.md`: Per-platform `trellis-research` / `trellis-implement` / `trellis-check` sub-agent files plus bundled `.trellis/agents/{check,implement}.md` for the channel runtime. - `references/platform-files/skills-and-commands.md`: Differences between skills, commands, prompts, and workflows, plus how to change them. diff --git a/.pi/skills/trellis-meta/references/platform-files/agents.md b/.pi/skills/trellis-meta/references/platform-files/agents.md index a07cae789..7e5e47f2c 100644 --- a/.pi/skills/trellis-meta/references/platform-files/agents.md +++ b/.pi/skills/trellis-meta/references/platform-files/agents.md @@ -33,7 +33,8 @@ Agent files should not become generic chat prompts. They should define input sou | Factory Droid | `.factory/droids/trellis-*.md` | | Pi Agent | `.pi/agents/trellis-*.md` | | Reasonix | `.reasonix/skills/trellis-*/SKILL.md` (subagent frontmatter) | -| ZCode | `.zcode/cli/agents/trellis-*.md` | +| ZCode | `.zcode/agents/trellis-*.md` | +| Kimi Code | `.kimi-code/agents/trellis-*.md` (custom sub-agents; the same prompts also ship as `.kimi-code/skills/trellis-*/SKILL.md`) | GitHub Copilot agent/prompt support is provided by a combination of directories such as `.github/agents/`, `.github/prompts/`, and `.github/skills/`; inspect the files actually generated in the user project. diff --git a/.pi/skills/trellis-meta/references/platform-files/hooks-and-settings.md b/.pi/skills/trellis-meta/references/platform-files/hooks-and-settings.md index eb285b60b..85f7f11af 100644 --- a/.pi/skills/trellis-meta/references/platform-files/hooks-and-settings.md +++ b/.pi/skills/trellis-meta/references/platform-files/hooks-and-settings.md @@ -27,8 +27,9 @@ Common files: | GitHub Copilot | `.github/copilot/hooks.json` | | Factory Droid | `.factory/settings.json` | | Pi Agent | `.pi/settings.json`, `.pi/extensions/trellis/` | +| Trae IDE | `.trae/hooks.json` | -Reasonix and ZCode are pull-based platforms that do not use hooks or settings files; their agent files contain prelude instructions to read context after startup. +Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills and `.kimi-code/agents/` sub-agent definitions with the same prelude. Whether these files exist in a project depends on which `trellis init --` flags the user ran. diff --git a/.pi/skills/trellis-meta/references/platform-files/platform-map.md b/.pi/skills/trellis-meta/references/platform-files/platform-map.md index 2561da866..026773f58 100644 --- a/.pi/skills/trellis-meta/references/platform-files/platform-map.md +++ b/.pi/skills/trellis-meta/references/platform-files/platform-map.md @@ -19,9 +19,13 @@ 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/` (native `trellis_subagent` tool) + `.pi/settings.json` | +| Pi Agent | `--pi` | `.pi/` | `.agents/skills/` | `.pi/agents/` | `.pi/extensions/trellis/` (native `trellis_subagent` tool) + `.pi/settings.json` | +| Trae IDE | `--trae` | `.trae/` | `.trae/skills/` | `.trae/agents/` | `.trae/hooks/` + `.trae/hooks.json` | | Reasonix | `--reasonix` | `.reasonix/` | `.reasonix/skills/` | None — sub-agents are skills with `runAs: subagent` frontmatter | None | -| ZCode | `--zcode` | `.zcode/` | `.agents/skills/` | `.zcode/cli/agents/` | pull-based prelude (no hooks) | +| ZCode | `--zcode` | `.zcode/` | `.zcode/skills/` | `.zcode/agents/` | `.zcode/hooks/` + `.zcode/config.json` (SessionStart + UserPromptSubmit + PreToolUse Agent/Task); sub-agents use hook-injected context | +| Grok Build | `--grok` | `.grok/` | `.grok/skills/` | `.grok/agents/` | pull-based prelude (no hooks; flat `.grok/commands/trellis-*.md`) | +| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | `.kimi-code/agents/` (custom sub-agents; same prompts also ship as skills) | None (pull-based prelude; no project hooks/settings) | +| Snow CLI | `--snow` | `.snow/` | `.snow/skills/` | `.snow/agents/` (auto-discovered; primary path) | class-1: auto inject + project agents + `beforeSubAgentStart` (`.snow/hooks/` `session`/`user`/`subagent` modes -> `additionalContext` JSON); no legacy sub-agent JSON; commands `.snow/commands/trellis-*.json` | ## Capability Groups @@ -40,8 +44,12 @@ These platforms usually have `trellis-research`, `trellis-implement`, and `trell - GitHub Copilot - Factory Droid - Pi Agent +- Trae IDE - Reasonix (delivered as skills with `runAs: subagent` under `.reasonix/skills/`, not as a separate `agents/` directory) - ZCode +- Grok Build (`.grok/agents/`; dispatch via `spawn_subagent` with `subagent_type`) +- Kimi Code (`.kimi-code/agents/`; the same prompts are also delivered as skills under `.kimi-code/skills/`) +- Snow CLI (`.snow/agents/`; auto-discovered project agents + class-1 hooks) When changing implementation/check/research behavior, look for the corresponding platform agent files first. @@ -65,7 +73,7 @@ When changing behavior, inspect workflows and skills first. Do not assume Trelli ### Shared `.agents/skills/` -Codex writes the shared `.agents/skills/` layer. Some tools that support agentskills.io can also read this directory. If the user wants multiple compatible tools to share one skill, consider `.agents/skills/` first, but do not assume every platform reads it. +Codex, Gemini CLI, Pi Agent, and Kimi Code write the shared `.agents/skills/` layer. Some tools that support agentskills.io can also read this directory. If the user wants multiple compatible tools to share one skill, consider `.agents/skills/` first, but do not assume every platform reads it. ZCode keeps Trellis-managed skills under `.zcode/skills/`. ## Decision Rules When Modifying Platform Files @@ -84,3 +92,20 @@ Platform ecosystems change, and user projects may already be customized. If this - Judge behavior by the read rules currently written in the agent file. Do not delete a custom file just because it is not listed in this path table. + +### `.omp/` — Oh My Pi (OMP) + +Extension-backed platform. OMP native provider auto-discovers all subdirectories. + +```text +.omp/ +├── commands/ # Slash commands (flat .md) +├── skills/ # Auto-triggered skills (SKILL.md per dir) +├── agents/ # Agent definitions (.md) +└── extensions/ + └── trellis/ + └── index.ts # Trellis extension (context injection) +``` + +No `settings.json` — OMP scans `.omp/` subdirectories automatically. +No Python hooks — hook-equivalent behavior lives in the TypeScript extension. diff --git a/.trellis/spec/cli/backend/platform-integration.md b/.trellis/spec/cli/backend/platform-integration.md index bd5b523b5..8145259cd 100644 --- a/.trellis/spec/cli/backend/platform-integration.md +++ b/.trellis/spec/cli/backend/platform-integration.md @@ -150,7 +150,7 @@ the build if it is really just an extra write. > - Platform detection uses `.codex/` only — `.agents/skills/` alone does NOT trigger codex detection > - `configDir` is `".codex"`, with `supportsAgentSkills: true` to auto-include `.agents/skills` in managed paths > -> **Kimi Code is a hybrid skills platform** — workflow/bundled skills go to the shared `.agents/skills/` root via `resolveSkillsNeutral()` (byte-identical to Codex/Gemini/Pi; Kimi discovers that root natively), while the session-boundary commands (`start` / `continue` / `finish-work`, invoked as `/skill:trellis-`) and the Trellis agent prompts are written as Kimi-private skills under `.kimi-code/skills//SKILL.md`. Kimi has no project-level hooks/settings file (hooks are user-level `~/.kimi-code/config.toml` only) and no custom sub-agent definitions (built-in coder/explore/plan only), so no hooks, settings, extension, or `agents/` directory is written, and the agent prompts ship as skills with the pull-based prelude on implement/check (class-2). +> **Kimi Code is a hybrid skills platform** — workflow/bundled skills go to the shared `.agents/skills/` root via `resolveSkillsNeutral()` (byte-identical to Codex/Gemini/Pi; Kimi discovers that root natively), while the session-boundary commands (`start` / `continue` / `finish-work`, invoked as `/skill:trellis-`) and the Trellis agent prompts are written as Kimi-private skills under `.kimi-code/skills//SKILL.md`. The same agent prompts are also installed as project-level custom sub-agent definitions at `.kimi-code/agents/trellis-{implement,check,research}.md` (Claude Code-compatible frontmatter), so the main session can dispatch `trellis-` sub-agents directly; the skill copies stay as a guidance/fallback path. Kimi has no project-level hooks/settings file (hooks are user-level `~/.kimi-code/config.toml` only), so no hooks, settings, or extension files are written, and the agent prompts keep the pull-based prelude on implement/check (class-2). #### Rule: `.agents/skills/` writes use `resolvePlaceholdersNeutral()` @@ -1205,7 +1205,7 @@ Platform's hook either does not expose a sub-agent-start event or cannot inject | Reasonix | Sub-agent skills run with `runAs: subagent`; no prompt-mutation hook exists, so workflow dispatch must carry the active task and the sub-agent skill reads task artifacts itself. | | Trae IDE | `SessionStart` / `UserPromptSubmit` hooks cover main-session context, but no Trellis-supported sub-agent prompt mutation surface exists; generated `.trae/agents/*.md` files receive the pull-based prelude. | | Grok Build | Hook stdout `additionalContext` is not consumed (verified on 0.2.x), so no Trellis hook is installed; dispatch goes through `spawn_subagent` and generated `.grok/agents/*.md` files receive the pull-based prelude. | -| Kimi Code | Hooks exist only in the user-level `~/.kimi-code/config.toml` (no project-level hook/settings file Trellis may write) and there are no custom sub-agent definitions (built-in coder/explore/plan only), so the Trellis agent prompts ship as `.kimi-code/skills/trellis-*/SKILL.md` with the pull-based prelude. | +| Kimi Code | Hooks exist only in the user-level `~/.kimi-code/config.toml` (no project-level hook/settings file Trellis may write), so the Trellis agent prompts keep the pull-based prelude. They ship both as `.kimi-code/skills/trellis-*/SKILL.md` (guidance/fallback) and as custom sub-agent definitions under `.kimi-code/agents/trellis-*.md` sourced from the same templates. | #### Active task discovery on class-2 platforms (issue #225) diff --git a/packages/cli/src/configurators/kimi.ts b/packages/cli/src/configurators/kimi.ts index 79bf04c0a..b9175a734 100644 --- a/packages/cli/src/configurators/kimi.ts +++ b/packages/cli/src/configurators/kimi.ts @@ -11,11 +11,13 @@ * `/skill:trellis-finish-work`) plus the Trellis agent prompts * (trellis-implement / trellis-check / trellis-research) with the * pull-based prelude on implement/check. + * - `.kimi-code/agents/` — the same Trellis agent prompts as project-level + * custom sub-agent definitions (Claude Code-compatible frontmatter), so + * the main session can dispatch `trellis-` sub-agents directly. * - * Kimi has no project-level hooks/settings file (hooks live in user-level - * `~/.kimi-code/config.toml` only) and no custom sub-agent definitions - * (built-in coder/explore/plan only), so no hooks, settings, or extension - * files are written and the agent prompts ship as skills. + * Trellis does not generate project-local Kimi settings or hooks. + * Project-local Kimi settings go in `.kimi-code/local.toml`; hooks are + * configured in `$KIMI_CODE_HOME/config.toml`. */ import { AI_TOOLS } from "../types/ai-tools.js"; @@ -49,8 +51,8 @@ function resolveKimiCommandSkills(): ReturnType { ); } -/** Trellis agent prompts as Kimi skills, with the pull-based prelude on - * implement/check. */ +/** Trellis agent prompts as Kimi skills (and `.kimi-code/agents/` sub-agent + * definitions), with the pull-based prelude on implement/check. */ function resolveKimiAgentSkills(): AgentContent[] { return applyPullBasedPreludeMarkdown(getAllAgents()); } @@ -73,12 +75,21 @@ export function collectKimiTemplates(): Map { } // 2. Commands-as-skills + Trellis agent prompts → `.kimi-code/skills/`. + const agentPrompts = resolveKimiAgentSkills(); for (const [filePath, content] of collectSkillTemplates(".kimi-code/skills", [ ...resolveKimiCommandSkills(), - ...resolveKimiAgentSkills(), + ...agentPrompts, ])) { files.set(filePath, content); } + // 3. Custom sub-agent definitions → `.kimi-code/agents/`. Kimi Code + // discovers project-level agents there (Claude Code-compatible + // frontmatter); content mirrors the skill copies, pull-based prelude + // included, so dispatching `trellis-` directly behaves the same. + for (const agent of agentPrompts) { + files.set(`.kimi-code/agents/${agent.name}.md`, agent.content); + } + return files; } diff --git a/packages/cli/src/templates/common/bundled-skills/trellis-meta/SKILL.md b/packages/cli/src/templates/common/bundled-skills/trellis-meta/SKILL.md index 0ffe5939f..91b23b691 100644 --- a/packages/cli/src/templates/common/bundled-skills/trellis-meta/SKILL.md +++ b/packages/cli/src/templates/common/bundled-skills/trellis-meta/SKILL.md @@ -12,7 +12,7 @@ Trellis v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow / The default operating scope is local files in the user project: - `.trellis/`: workflow, config, tasks, spec, workspace, scripts, bundled runtime agents, and runtime state. -- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills//SKILL.md`; subagent skills carry `runAs: subagent` frontmatter. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer and delivers commands plus agent prompts as `.kimi-code/skills//SKILL.md`. +- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills//SKILL.md`; subagent skills carry `runAs: subagent` frontmatter. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer, delivers commands plus agent prompts as `.kimi-code/skills//SKILL.md`, and installs the same agent prompts as custom sub-agents under `.kimi-code/agents/.md`. - Shared skill layer: `.agents/skills/`. - User-owned channel store outside the project tree: `~/.trellis/channels///events.jsonl`. - Raw platform conversation logs queryable via `trellis mem`: `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` (OpenCode adapter degraded for the v0.6 line). diff --git a/packages/cli/src/templates/common/bundled-skills/trellis-meta/references/platform-files/agents.md b/packages/cli/src/templates/common/bundled-skills/trellis-meta/references/platform-files/agents.md index 26f472ab4..7e5e47f2c 100644 --- a/packages/cli/src/templates/common/bundled-skills/trellis-meta/references/platform-files/agents.md +++ b/packages/cli/src/templates/common/bundled-skills/trellis-meta/references/platform-files/agents.md @@ -34,7 +34,7 @@ Agent files should not become generic chat prompts. They should define input sou | Pi Agent | `.pi/agents/trellis-*.md` | | Reasonix | `.reasonix/skills/trellis-*/SKILL.md` (subagent frontmatter) | | ZCode | `.zcode/agents/trellis-*.md` | -| Kimi Code | `.kimi-code/skills/trellis-*/SKILL.md` (agent prompts as skills, dispatched to the built-in `coder`; research needs its file-editing tools to persist findings) | +| Kimi Code | `.kimi-code/agents/trellis-*.md` (custom sub-agents; the same prompts also ship as `.kimi-code/skills/trellis-*/SKILL.md`) | GitHub Copilot agent/prompt support is provided by a combination of directories such as `.github/agents/`, `.github/prompts/`, and `.github/skills/`; inspect the files actually generated in the user project. diff --git a/packages/cli/src/templates/common/bundled-skills/trellis-meta/references/platform-files/hooks-and-settings.md b/packages/cli/src/templates/common/bundled-skills/trellis-meta/references/platform-files/hooks-and-settings.md index a2ff389ca..85f7f11af 100644 --- a/packages/cli/src/templates/common/bundled-skills/trellis-meta/references/platform-files/hooks-and-settings.md +++ b/packages/cli/src/templates/common/bundled-skills/trellis-meta/references/platform-files/hooks-and-settings.md @@ -29,7 +29,7 @@ Common files: | Pi Agent | `.pi/settings.json`, `.pi/extensions/trellis/` | | Trae IDE | `.trae/hooks.json` | -Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills with the same prelude. +Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills and `.kimi-code/agents/` sub-agent definitions with the same prelude. Whether these files exist in a project depends on which `trellis init --` flags the user ran. diff --git a/packages/cli/src/templates/common/bundled-skills/trellis-meta/references/platform-files/platform-map.md b/packages/cli/src/templates/common/bundled-skills/trellis-meta/references/platform-files/platform-map.md index 73b113a66..026773f58 100644 --- a/packages/cli/src/templates/common/bundled-skills/trellis-meta/references/platform-files/platform-map.md +++ b/packages/cli/src/templates/common/bundled-skills/trellis-meta/references/platform-files/platform-map.md @@ -24,7 +24,7 @@ This page lists common Trellis file locations in a user project by platform. Whe | Reasonix | `--reasonix` | `.reasonix/` | `.reasonix/skills/` | None — sub-agents are skills with `runAs: subagent` frontmatter | None | | ZCode | `--zcode` | `.zcode/` | `.zcode/skills/` | `.zcode/agents/` | `.zcode/hooks/` + `.zcode/config.json` (SessionStart + UserPromptSubmit + PreToolUse Agent/Task); sub-agents use hook-injected context | | Grok Build | `--grok` | `.grok/` | `.grok/skills/` | `.grok/agents/` | pull-based prelude (no hooks; flat `.grok/commands/trellis-*.md`) | -| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | None — agent prompts are skills under `.kimi-code/skills/` and dispatch to the built-in `coder` | None (pull-based prelude; no project hooks/settings) | +| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | `.kimi-code/agents/` (custom sub-agents; same prompts also ship as skills) | None (pull-based prelude; no project hooks/settings) | | Snow CLI | `--snow` | `.snow/` | `.snow/skills/` | `.snow/agents/` (auto-discovered; primary path) | class-1: auto inject + project agents + `beforeSubAgentStart` (`.snow/hooks/` `session`/`user`/`subagent` modes -> `additionalContext` JSON); no legacy sub-agent JSON; commands `.snow/commands/trellis-*.json` | ## Capability Groups @@ -48,7 +48,7 @@ These platforms usually have `trellis-research`, `trellis-implement`, and `trell - Reasonix (delivered as skills with `runAs: subagent` under `.reasonix/skills/`, not as a separate `agents/` directory) - ZCode - Grok Build (`.grok/agents/`; dispatch via `spawn_subagent` with `subagent_type`) -- Kimi Code (delivered as skills under `.kimi-code/skills/`; dispatched to the built-in `coder`, including research because it must persist files) +- Kimi Code (`.kimi-code/agents/`; the same prompts are also delivered as skills under `.kimi-code/skills/`) - Snow CLI (`.snow/agents/`; auto-discovered project agents + class-1 hooks) When changing implementation/check/research behavior, look for the corresponding platform agent files first. diff --git a/packages/cli/src/templates/kimi/agents/trellis-check.md b/packages/cli/src/templates/kimi/agents/trellis-check.md index 94a18f5d5..b016cb9de 100644 --- a/packages/cli/src/templates/kimi/agents/trellis-check.md +++ b/packages/cli/src/templates/kimi/agents/trellis-check.md @@ -2,9 +2,10 @@ name: trellis-check description: | Code quality check expert for Trellis. Reviews code changes against specs - and self-fixes issues. On Kimi Code the main session dispatches the built-in - coder sub-agent with these instructions; the first prompt line must be - Active task: . + and self-fixes issues. On Kimi Code the main session dispatches this custom + sub-agent (defined in `.kimi-code/agents/trellis-check.md`); the first + prompt line must be Active task: . +tools: Read, Write, Edit, Bash, Glob, Grep --- # Check Agent @@ -20,11 +21,10 @@ You are already the `trellis-check` sub-agent that the main session dispatched. ## Dispatch note (main session) -Kimi Code has no project-level custom sub-agent definitions — only the built-in `coder` / `explore` / `plan` sub-agents. The main session dispatches the built-in `coder` sub-agent via the Agent tool with a prompt that: +Kimi Code supports project-level custom sub-agents under `.kimi-code/agents/`. The main session dispatches the `trellis-check` sub-agent via the Agent tool with a prompt that: 1. Starts with `Active task: ` -2. Includes this skill's instructions (`.kimi-code/skills/trellis-check/SKILL.md`) -3. States that the spawned agent is already `trellis-check` and must review/fix directly without spawning another `trellis-check` / `trellis-implement` +2. States that the spawned agent is already `trellis-check` and must review/fix directly without spawning another `trellis-check` / `trellis-implement` Kimi does not auto-inject SessionStart task context. Always pull context as required below. diff --git a/packages/cli/src/templates/kimi/agents/trellis-implement.md b/packages/cli/src/templates/kimi/agents/trellis-implement.md index 0f10b7f23..e18bf01cf 100644 --- a/packages/cli/src/templates/kimi/agents/trellis-implement.md +++ b/packages/cli/src/templates/kimi/agents/trellis-implement.md @@ -3,8 +3,10 @@ name: trellis-implement description: | Code implementation expert for Trellis. Understands specs and requirements, then implements features. No git commit allowed. On Kimi Code the main - session dispatches the built-in coder sub-agent with these instructions; - the first prompt line must be Active task: . + session dispatches this custom sub-agent (defined in + `.kimi-code/agents/trellis-implement.md`); the first prompt line must be + Active task: . +tools: Read, Write, Edit, Bash, Glob, Grep --- # Implement Agent @@ -20,11 +22,10 @@ You are already the `trellis-implement` sub-agent that the main session dispatch ## Dispatch note (main session) -Kimi Code has no project-level custom sub-agent definitions — only the built-in `coder` / `explore` / `plan` sub-agents. The main session dispatches the built-in `coder` sub-agent via the Agent tool with a prompt that: +Kimi Code supports project-level custom sub-agents under `.kimi-code/agents/`. The main session dispatches the `trellis-implement` sub-agent via the Agent tool with a prompt that: 1. Starts with `Active task: ` -2. Includes this skill's instructions (`.kimi-code/skills/trellis-implement/SKILL.md`) -3. States that the spawned agent is already `trellis-implement` and must implement directly without spawning another `trellis-implement` / `trellis-check` +2. States that the spawned agent is already `trellis-implement` and must implement directly without spawning another `trellis-implement` / `trellis-check` Kimi does not auto-inject SessionStart task context. Always pull context as required below. diff --git a/packages/cli/src/templates/kimi/agents/trellis-research.md b/packages/cli/src/templates/kimi/agents/trellis-research.md index cd94370bb..9f937a573 100644 --- a/packages/cli/src/templates/kimi/agents/trellis-research.md +++ b/packages/cli/src/templates/kimi/agents/trellis-research.md @@ -4,8 +4,9 @@ description: | Code and tech search expert for Trellis. Finds files, patterns, and tech solutions, and PERSISTS every finding to the current task's research/ directory. No code modifications outside that directory. On Kimi Code the - main session dispatches the built-in coder sub-agent with these instructions - because it is the only built-in sub-agent with file-editing tools. + main session dispatches this custom sub-agent (defined in + `.kimi-code/agents/trellis-research.md`). +tools: Read, Write, Glob, Grep, Bash, Skill, mcp__* --- # Research Agent @@ -19,11 +20,10 @@ Conversations get compacted; files don't. Every research output MUST end up as a ## Dispatch note (main session) -Kimi Code has no project-level custom sub-agent definitions — only the built-in `coder` / `explore` / `plan` sub-agents. The built-in `explore` sub-agent is read-only, so it cannot satisfy this agent's persistence contract. The main session dispatches the built-in `coder` sub-agent via the Agent tool with a prompt that: +Kimi Code supports project-level custom sub-agents under `.kimi-code/agents/`. The main session dispatches the `trellis-research` sub-agent via the Agent tool with a prompt that: 1. Starts with `Active task: ` -2. Includes this skill's instructions (`.kimi-code/skills/trellis-research/SKILL.md`) -3. States that the spawned agent is already `trellis-research` and may write only under the active task's `research/` directory +2. States that the spawned agent is already `trellis-research` and may write only under the active task's `research/` directory --- diff --git a/packages/cli/src/templates/kimi/index.ts b/packages/cli/src/templates/kimi/index.ts index f80a72f94..28cfbbe3d 100644 --- a/packages/cli/src/templates/kimi/index.ts +++ b/packages/cli/src/templates/kimi/index.ts @@ -7,11 +7,12 @@ * - User-invocable entry points (`trellis-start` / `trellis-continue` / * `trellis-finish-work`, invoked as `/skill:trellis-`) and the Trellis * agent prompts live under `.kimi-code/skills//SKILL.md`. + * - The same agent prompts are also installed as project-level custom + * sub-agent definitions under `.kimi-code/agents/.md`. * - * Kimi has no project-level hooks/settings file Trellis may write and no - * custom sub-agent definitions (built-in coder/explore/plan only), so the - * Trellis agent prompts ship as skills; trellis-implement / trellis-check get - * the pull-based prelude, trellis-research stays standalone. + * Kimi has no project-level hooks/settings file Trellis may write, so no + * hooks or settings are shipped; trellis-implement / trellis-check get the + * pull-based prelude, trellis-research stays standalone. */ import { createTemplateReader, type AgentTemplate } from "../template-utils.js"; diff --git a/packages/cli/src/types/ai-tools.ts b/packages/cli/src/types/ai-tools.ts index 20cad9755..ee32e26a7 100644 --- a/packages/cli/src/types/ai-tools.ts +++ b/packages/cli/src/types/ai-tools.ts @@ -530,9 +530,11 @@ export const AI_TOOLS: Record = { * `.kimi-code/skills/`. * * Kimi has no project-level hooks/settings file Trellis may write (hooks are - * user-level `~/.kimi-code/config.toml` only) and no project-level custom - * sub-agent definitions (only the built-in coder/explore/plan sub-agents), so - * the Trellis agent prompts ship as skills with the pull-based prelude. + * user-level `~/.kimi-code/config.toml` only), so the Trellis agent prompts + * keep the pull-based prelude. They ship both as skills and as project-level + * custom sub-agent definitions under `.kimi-code/agents/` (Claude + * Code-compatible frontmatter), so the main session can dispatch + * `trellis-` sub-agents directly. */ kimi: { name: "Kimi Code", diff --git a/packages/cli/test/commands/init.integration.test.ts b/packages/cli/test/commands/init.integration.test.ts index 1c915286a..9c39ef02a 100644 --- a/packages/cli/test/commands/init.integration.test.ts +++ b/packages/cli/test/commands/init.integration.test.ts @@ -652,6 +652,17 @@ describe("init() integration", () => { ), ).toBe(true); + // Custom sub-agent definitions → .kimi-code/agents/ + for (const name of [ + "trellis-implement", + "trellis-check", + "trellis-research", + ]) { + expect( + fs.existsSync(path.join(tmpDir, ".kimi-code", "agents", `${name}.md`)), + ).toBe(true); + } + // Kimi has no project-level hooks/settings surface. expect(fs.existsSync(path.join(tmpDir, ".kimi-code", "hooks"))).toBe(false); expect( diff --git a/packages/cli/test/configurators/index.test.ts b/packages/cli/test/configurators/index.test.ts index d67127b5f..4b531df7f 100644 --- a/packages/cli/test/configurators/index.test.ts +++ b/packages/cli/test/configurators/index.test.ts @@ -492,6 +492,10 @@ describe("collectPlatformTemplates", () => { expect( result?.has(".kimi-code/skills/trellis-research/SKILL.md"), ).toBe(true); + // Custom sub-agent definitions + expect(result?.has(".kimi-code/agents/trellis-implement.md")).toBe(true); + expect(result?.has(".kimi-code/agents/trellis-check.md")).toBe(true); + expect(result?.has(".kimi-code/agents/trellis-research.md")).toBe(true); // No project-level hooks/settings for Kimi expect( [...(result?.keys() ?? [])].some((key) => diff --git a/packages/cli/test/templates/kimi.test.ts b/packages/cli/test/templates/kimi.test.ts index 3a65663bd..e935d873d 100644 --- a/packages/cli/test/templates/kimi.test.ts +++ b/packages/cli/test/templates/kimi.test.ts @@ -24,24 +24,34 @@ describe("kimi getAllAgents", () => { expect(content).toMatch(/^---\n/); expect(content).toContain("name: "); expect(content).toContain("description:"); - // Kimi agents document dispatch through the built-in sub-agents - expect(content).toContain("built-in"); + // Kimi agents document dispatch through `.kimi-code/agents/` sub-agents + expect(content).toContain(".kimi-code/agents/"); } }); - it("dispatches research through the writable coder sub-agent", () => { + it("documents dispatch via the Agent tool with an Active task: prompt", () => { + for (const agent of getAllAgents()) { + // Dispatch contract: main session dispatches the custom sub-agent via + // the Agent tool, and the prompt starts with the active task path. + expect(agent.content).toContain( + `dispatches the \`${agent.name}\` sub-agent via the Agent tool`, + ); + expect(agent.content).toContain("Starts with `Active task: { const research = getAllAgents().find( (agent) => agent.name === "trellis-research", ); expect(research).toBeDefined(); if (!research) return; - expect(research.content).toContain("built-in `coder` sub-agent"); - expect(research.content).toContain("`explore` sub-agent is read-only"); - expect(research.content).toContain("may write only under"); - expect(research.content).not.toContain( - "dispatches the built-in `explore` sub-agent", + expect(research.content).toContain( + "dispatches the `trellis-research` sub-agent", ); + expect(research.content).toContain("may write only under"); + expect(research.content).not.toContain("built-in `coder` sub-agent"); }); }); @@ -80,7 +90,7 @@ describe("kimi collectKimiTemplates", () => { true, ); - // Trellis agent prompts (Kimi has no custom sub-agent definitions) + // Trellis agent prompts (also installed as `.kimi-code/agents/*.md`) expect(files.has(".kimi-code/skills/trellis-implement/SKILL.md")).toBe( true, ); @@ -92,6 +102,25 @@ describe("kimi collectKimiTemplates", () => { const research = files.get(".kimi-code/skills/trellis-research/SKILL.md"); expect(research).not.toContain("Load Trellis Context First"); + // Custom sub-agent definitions under .kimi-code/agents/ mirror the skill + // copies (pull-based prelude included). + for (const name of [ + "trellis-implement", + "trellis-check", + "trellis-research", + ]) { + const agent = files.get(`.kimi-code/agents/${name}.md`); + expect(agent, `.kimi-code/agents/${name}.md`).toBeDefined(); + expect(agent).toContain(`name: ${name}`); + expect(agent).toContain("tools: "); + } + expect(files.get(".kimi-code/agents/trellis-implement.md")).toContain( + "Load Trellis Context First", + ); + expect(files.get(".kimi-code/agents/trellis-research.md")).not.toContain( + "Load Trellis Context First", + ); + // No hooks/settings/extension files — Kimi has no project-level hook or // settings surface Trellis may write. for (const key of files.keys()) {