升级 Trellis 并完成项目审查（07-26-trellis-upgrade-project-audit）
这个提交包含在：
@@ -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/<project>/<channel>/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/<name>/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/<name>/SKILL.md`.
|
||||
- Shared skill layer: `.agents/skills/`.
|
||||
- User-owned channel store outside the project tree: `~/.trellis/channels/<project>/<channel>/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 <id>`. Missing `.trellis/agents/<name>.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 <slug>`, `task.py add-subtask <parent> <child>`, `task.py remove-subtask <parent> <child>`, and `task.py list-context <task>`. `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 <name>`. 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/<project>/<channel>/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/<project>/<channel>/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/<name>.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.
|
||||
|
||||
@@ -24,6 +24,8 @@ When the user wants to change `trellis-research`, `trellis-implement`, or `trell
|
||||
| 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` |
|
||||
|
||||
Use the actual paths in the user project as authoritative.
|
||||
|
||||
|
||||
@@ -18,6 +18,8 @@ Context loading determines when AI reads workflow, task, spec, research, workspa
|
||||
| --- | --- |
|
||||
| `.trellis/workflow.md` | Workflow and next-action hints. |
|
||||
| `.trellis/tasks/<task>/prd.md` | Current task requirements. |
|
||||
| `.trellis/tasks/<task>/design.md` | Complex task technical design. |
|
||||
| `.trellis/tasks/<task>/implement.md` | Complex task execution plan. |
|
||||
| `.trellis/tasks/<task>/implement.jsonl` | Spec/research to read before implementation. |
|
||||
| `.trellis/tasks/<task>/check.jsonl` | Spec/research to read during checking. |
|
||||
| `.trellis/spec/` | Project specs. |
|
||||
@@ -64,10 +66,11 @@ First determine which mode the platform uses:
|
||||
In both modes, make sure the agent ultimately reads:
|
||||
|
||||
1. active task
|
||||
2. `prd.md`
|
||||
3. `info.md` if present
|
||||
4. the corresponding JSONL
|
||||
5. spec/research referenced by the JSONL
|
||||
2. the corresponding JSONL
|
||||
3. spec/research referenced by the JSONL
|
||||
4. `prd.md`
|
||||
5. `design.md` if present
|
||||
6. `implement.md` if present
|
||||
|
||||
## Troubleshooting Order
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ Hooks are the automation layer that connects a platform to Trellis. When the use
|
||||
|
||||
## Read These Files First
|
||||
|
||||
1. Target platform settings/config, such as `.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json`
|
||||
1. Target platform settings/config, such as `.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json`, `.trae/hooks.json`
|
||||
2. Target platform hooks directory
|
||||
3. `.trellis/scripts/common/active_task.py`
|
||||
4. `.trellis/scripts/common/session_context.py`
|
||||
|
||||
@@ -2,12 +2,20 @@
|
||||
|
||||
When the user wants to change AI entry points, auto-trigger rules, or explicit command behavior, edit skills, commands, prompts, or workflows in local platform directories.
|
||||
|
||||
Before editing, classify the skill you are about to touch:
|
||||
|
||||
- **Bundled upstream skill** — `trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`. Source of truth lives in the Trellis CLI repo under `packages/cli/src/templates/common/bundled-skills/<name>/`; auto-dispatched to every platform's skill root by `getBundledSkillTemplates()` on `trellis init` / `trellis update`. Local edits here are tracked by `.trellis/.template-hashes.json` and will be flagged on the next update.
|
||||
- **Project-local skill** — anything else under `.{platform}/skills/`. Owned by the user; not refreshed by `trellis update`.
|
||||
|
||||
The remainder of this file uses "skill" for the local file; the override and conflict rules differ between the two cases.
|
||||
|
||||
## Read These Files First
|
||||
|
||||
1. `.trellis/workflow.md`
|
||||
2. Target platform skill/command/prompt/workflow directory
|
||||
3. Related agent or hook files
|
||||
4. Whether project rules already exist in `.trellis/spec/`
|
||||
5. `.trellis/.template-hashes.json` — confirms whether the skill you are about to edit is upstream-owned (entry present) or project-local (entry absent)
|
||||
|
||||
## Which Entry Type To Choose
|
||||
|
||||
@@ -15,7 +23,9 @@ When the user wants to change AI entry points, auto-trigger rules, or explicit c
|
||||
| --- | --- |
|
||||
| AI should automatically know a capability | Add or modify a skill. |
|
||||
| User wants to trigger manually with a command | Add or modify a command/prompt/workflow. |
|
||||
| Team project conventions | Prefer `.trellis/spec/` or a project-local skill. |
|
||||
| Team project conventions | Prefer `.trellis/spec/` or a project-local skill — never a bundled skill directory. |
|
||||
| Tweak a bundled skill (`trellis-meta` et al.) for the user's own project | Create a project-local sibling skill (different name) that overrides intent, or edit `.trellis/spec/`. Edits inside the bundled skill directory survive only until the next `trellis update` and will need a "keep" choice each time. |
|
||||
| Contribute the change back upstream | Edit `packages/cli/src/templates/common/bundled-skills/<name>/` in the Trellis CLI repo, not the deployed copy. |
|
||||
| Change Trellis flow semantics | Synchronize `.trellis/workflow.md`. |
|
||||
|
||||
## Modify A Skill
|
||||
@@ -38,6 +48,20 @@ description: "Use when customizing this project's deployment workflow and releas
|
||||
|
||||
Do not write vague descriptions such as "helpful project skill"; they can trigger incorrectly.
|
||||
|
||||
### Bundled vs. Project-Local
|
||||
|
||||
The same directory shape is used by two very different ownership models:
|
||||
|
||||
| Aspect | Bundled (`trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`) | Project-local |
|
||||
| --- | --- | --- |
|
||||
| Source of truth | `packages/cli/src/templates/common/bundled-skills/<name>/` in Trellis CLI repo | Inside the user project itself |
|
||||
| Dispatch | Auto-dispatched to every platform skill root by `getBundledSkillTemplates()` (`packages/cli/src/templates/common/index.ts`) on `trellis init` / `trellis update` | Created by the user (or another skill) and never moved |
|
||||
| Hash tracking | Every file recorded in `.trellis/.template-hashes.json`; conflict prompt on update | Not tracked |
|
||||
| Editing locally | Allowed but will be marked "modified by user" on next update | Free editing |
|
||||
| The right way to customize | Add a *new* project-local skill with a *different* name that supplements (or supersedes) the bundled one | Edit the file directly |
|
||||
|
||||
If the goal is "make my project's AI behave differently when discussing release notes," the answer is almost always a project-local skill, not surgery on `trellis-meta/`.
|
||||
|
||||
## Modify A Command/Prompt/Workflow
|
||||
|
||||
Explicit entry points should state:
|
||||
@@ -57,22 +81,43 @@ If a command only repeats workflow rules, prefer making it reference/read `.trel
|
||||
| Cursor | `.cursor/skills/`, `.cursor/commands/` |
|
||||
| OpenCode | `.opencode/skills/`, `.opencode/commands/` |
|
||||
| Codex | `.agents/skills/`, `.codex/skills/` |
|
||||
| Gemini CLI | `.agents/skills/`, `.gemini/commands/` |
|
||||
| Kiro | `.kiro/skills/` |
|
||||
| Qoder | `.qoder/skills/`, `.qoder/commands/` |
|
||||
| CodeBuddy | `.codebuddy/skills/`, `.codebuddy/commands/` |
|
||||
| GitHub Copilot | `.github/skills/`, `.github/prompts/` |
|
||||
| Kilo / Antigravity / Windsurf | workflows + skills |
|
||||
| Factory Droid | `.factory/skills/`, `.factory/commands/` |
|
||||
| Pi Agent | `.agents/skills/` |
|
||||
| Reasonix | `.reasonix/skills/` (no separate commands dir; slash commands built into the platform) |
|
||||
| ZCode | `.zcode/skills/`, `.zcode/commands/` |
|
||||
| Kilo / Antigravity / Devin | workflows + skills |
|
||||
|
||||
Every directory above is a deploy target for the four bundled skills. Each platform receives a full copy on `trellis init` and refresh on `trellis update`; nothing has to be wired by hand.
|
||||
|
||||
## Add A Project-Local Skill
|
||||
|
||||
If the user wants to document team-private customizations, create a project-local skill, for example:
|
||||
If the user wants to document team-private customizations, create a project-local skill — never put project-private content into a bundled skill directory, since `trellis update` will overwrite it.
|
||||
|
||||
```text
|
||||
.claude/skills/project-trellis-local/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
For multi-platform projects, add equivalent versions in each platform skill directory, or use `.agents/skills/` on platforms that support the shared layer.
|
||||
For multi-platform projects, add equivalent versions in each platform skill directory, or use `.agents/skills/` on platforms that support the shared layer (Codex, Gemini CLI).
|
||||
|
||||
Pick a name that does **not** collide with the bundled set:
|
||||
|
||||
- `trellis-meta`
|
||||
- `trellis-spec-bootstrap`
|
||||
- `trellis-session-insight`
|
||||
- `trellis-channel`
|
||||
|
||||
A reused name causes `getBundledSkillTemplates()` to overwrite the project-local copy on the next update. A common convention is to prefix the project name: `acme-trellis-deploy`, `acme-trellis-onboarding`.
|
||||
|
||||
## Notes
|
||||
|
||||
- Do not mix every platform's syntax into one file.
|
||||
- Do not change only one platform entry point while claiming all platforms are supported.
|
||||
- Do not hide long-term engineering conventions inside a command; write them to `.trellis/spec/`.
|
||||
- Do not hand-edit files inside `trellis-meta/`, `trellis-spec-bootstrap/`, `trellis-session-insight/`, or `trellis-channel/` under any `.{platform}/skills/` directory expecting the change to persist — they are bundled and refreshed by `trellis update`. Either contribute upstream or add a project-local skill that complements them.
|
||||
- After `trellis update` reports a "modified by you" conflict on a bundled skill file, choose **keep** only if you accept maintaining the divergence by hand; otherwise accept the overwrite and re-apply the intent as a project-local skill.
|
||||
|
||||
@@ -6,7 +6,7 @@ When the user wants to change the engineering conventions AI follows, add new sp
|
||||
|
||||
1. `.trellis/config.yaml`
|
||||
2. `.trellis/spec/`
|
||||
3. `.trellis/workflow.md` Phase 1.3 and Phase 3.3
|
||||
3. `.trellis/workflow.md` planning artifact guidance and Phase 3.3
|
||||
4. Current task `implement.jsonl` / `check.jsonl`
|
||||
|
||||
## Common Needs
|
||||
|
||||
@@ -50,11 +50,12 @@ If the user wants only one platform to avoid sub-agents, first confirm whether t
|
||||
| `status` | Artifact state | Resume at |
|
||||
| --- | --- | --- |
|
||||
| `planning` | `prd.md` missing | Phase 1.1 (load `trellis-brainstorm`) |
|
||||
| `planning` | `prd.md` exists, `implement.jsonl` only has the seed `_example` row | Phase 1.3 (curate JSONL context) |
|
||||
| `planning` | `prd.md` exists, `implement.jsonl` curated | Phase 1.4 (run `task.py start`) |
|
||||
| `planning` | lightweight task with `prd.md` complete | ask for start review, then run `task.py start` |
|
||||
| `planning` | complex task missing `design.md` or `implement.md` | complete missing planning artifacts |
|
||||
| `planning` | complex task has `prd.md`, `design.md`, and `implement.md` | ask for start review, then run `task.py start` |
|
||||
| `in_progress` | no implementation in conversation history | Phase 2.1 (`trellis-implement`) |
|
||||
| `in_progress` | implementation done, no `trellis-check` run | Phase 2.2 (`trellis-check`) |
|
||||
| `in_progress` | check passed | Phase 3.1 (verify quality + spec update) |
|
||||
| `in_progress` | check passed | Phase 3.3 (spec update) → 3.4 (commit) |
|
||||
| `completed` | task is still in active tree | Phase 3.5 (run `/trellis:finish-work` to archive) |
|
||||
|
||||
When you add a custom status (e.g. `in-review`), add a `[workflow-state:in-review]` block in `.trellis/workflow.md` for the per-turn breadcrumb AND extend this route table — usually by editing the `/trellis:continue` command file (`.{platform}/commands/trellis/continue.md` or equivalent) to add a row that decides where to resume from. Without the route entry, `/trellis:continue` will fall through to a default branch and the user will not land on the step you intended.
|
||||
|
||||
@@ -17,7 +17,7 @@ This directory is for local AI working in a user project where Trellis was insta
|
||||
|
||||
## General Operation Order
|
||||
|
||||
1. **Confirm platform and directories**: inspect which directories exist, such as `.claude/`, `.codex/`, `.cursor/`.
|
||||
1. **Confirm platform and directories**: inspect which directories exist, such as `.claude/`, `.codex/`, `.cursor/`, `.zcode/`.
|
||||
2. **Confirm the current active task**: run `python3 ./.trellis/scripts/task.py current --source`.
|
||||
3. **Read the local source of truth**: prefer `.trellis/workflow.md`, `.trellis/config.yaml`, and relevant platform files.
|
||||
4. **Modify narrowly**: edit only files related to the user's request.
|
||||
@@ -32,7 +32,7 @@ This directory is for local AI working in a user project where Trellis was insta
|
||||
| Task material | `.trellis/tasks/<task>/` |
|
||||
| Project specs | `.trellis/spec/` |
|
||||
| Runtime scripts | `.trellis/scripts/` |
|
||||
| Platform integration | `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, and similar directories |
|
||||
| Platform integration | `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.zcode/`, and similar directories |
|
||||
| Shared skill | `.agents/skills/` |
|
||||
|
||||
## Things Not To Do By Default
|
||||
|
||||
@@ -0,0 +1,147 @@
|
||||
# Bundled Skills
|
||||
|
||||
"Bundled skills" are multi-file built-in skills shipped inside the Trellis CLI npm package. Unlike marketplace skills (which a user installs separately into their own `.claude/skills/` or other platform skill root), bundled skills are written automatically into every supported platform's skill root by `trellis init` and kept in sync by `trellis update`. They are part of Trellis itself, not third-party content.
|
||||
|
||||
A bundled skill is a directory under `packages/cli/src/templates/common/bundled-skills/<skill>/` that already contains its own `SKILL.md` (with YAML frontmatter) plus optional `references/`, assets, or other supporting files. Trellis copies the whole directory tree as-is into each platform's skill root, so references stay lazy-loadable instead of being flattened into one oversized `SKILL.md`.
|
||||
|
||||
## What Counts As Bundled (vs. Adjacent Concepts)
|
||||
|
||||
| Source path | Type | How it ships |
|
||||
| --- | --- | --- |
|
||||
| `templates/common/bundled-skills/<name>/` | Bundled skill (multi-file) | Whole directory copied to every platform skill root |
|
||||
| `templates/common/skills/<name>.md` | Single-file workflow skill | Wrapped with frontmatter, written as `<root>/<name>/SKILL.md` |
|
||||
| `templates/common/commands/<name>.md` | Slash command / prompt | Written to each platform's command directory (`.claude/commands/trellis/`, `.cursor/commands/trellis-*.md`, `.gemini/commands/trellis/*.toml`, etc.) |
|
||||
| `templates/<platform>/skills/` | Platform-specific skill | Written only into that platform's directory (e.g. `.codex/skills/`) |
|
||||
| User skills under `.claude/skills/<my-skill>/` etc. | Marketplace or user-authored | Not managed by Trellis at all |
|
||||
|
||||
The Trellis CLI never touches anything that is not produced by one of its own template loaders. Anything a user drops into a platform skill root by hand is left alone.
|
||||
|
||||
## Current Bundled Skills (v0.6.0)
|
||||
|
||||
The set is discovered at runtime by listing directories under `templates/common/bundled-skills/`:
|
||||
|
||||
| Skill | Purpose |
|
||||
| --- | --- |
|
||||
| `trellis-meta` | This skill. Explains the local Trellis architecture and customization entry points to an AI working inside a user project. |
|
||||
| `trellis-session-insight` | Wraps the `trellis mem` CLI so an AI knows when and how to reach into past Claude Code / Codex / Pi Agent conversation logs. |
|
||||
| `trellis-spec-bootstrap` | Platform-neutral workflow for creating or refreshing `.trellis/spec/` from the real codebase (with optional GitNexus / ABCoder integration). |
|
||||
| `trellis-channel` | Capability skill teaching an AI when to reach for `trellis channel` for multi-agent collaboration, forum/thread persistent boards, and dispatcher-wait patterns. |
|
||||
|
||||
The list is discovered at runtime, so adding a new directory under `bundled-skills/` is the only step required to register a new skill (see "Adding a New Bundled Skill" below).
|
||||
|
||||
## Where Bundled Skills Land Per Platform
|
||||
|
||||
Each platform configurator calls `writeSkills(<root>, <workflowSkills>, resolveBundledSkills(ctx))` during `trellis init`. `resolveBundledSkills` reads every directory under `templates/common/bundled-skills/`, resolves placeholders, and returns a flat list of `{relativePath, content}` entries. `writeSkills` then mirrors them under the platform's skill root.
|
||||
|
||||
| Platform | Bundled skill root | Notes |
|
||||
| --- | --- | --- |
|
||||
| Claude Code | `.claude/skills/<skill>/` | `configureClaude` |
|
||||
| Cursor | `.cursor/skills/<skill>/` | `configureCursor` |
|
||||
| Codex | `.agents/skills/<skill>/` | `configureCodex` writes the shared `.agents/skills/` root, which Gemini CLI 0.40+ also reads |
|
||||
| Gemini CLI | `.agents/skills/<skill>/` | Same shared root as Codex; the two configurators are required to produce byte-identical output |
|
||||
| Kiro | `.kiro/skills/<skill>/` | `configureKiro` (skills-based platform — no commands) |
|
||||
| Qoder | `.qoder/skills/<skill>/` | `configureQoder` |
|
||||
| Codebuddy | `.codebuddy/skills/<skill>/` | `configureCodebuddy` |
|
||||
| Copilot | `.github/skills/<skill>/` | `configureCopilot` |
|
||||
| Droid | `.factory/skills/<skill>/` | `configureDroid` |
|
||||
| Antigravity | `.agent/skills/<skill>/` | `configureAntigravity` |
|
||||
| Devin | `.devin/skills/<skill>/` | `configureDevin` |
|
||||
| Kilo | `.kilocode/skills/<skill>/` | `configureKilo` |
|
||||
| ZCode | `.zcode/skills/<skill>/` | `configureZcode` |
|
||||
| OpenCode | (handled by `collectOpenCodeTemplates`) | Uses the same `resolveBundledSkills(ctx)` output |
|
||||
| Pi, Reasonix | (their own collectors) | Same `resolveBundledSkills(ctx)` output |
|
||||
|
||||
Two paths exercise the same data:
|
||||
|
||||
1. `configureX(cwd)` writes files during `trellis init`.
|
||||
2. `collectPlatformTemplates(platformId)` (in `configurators/index.ts`) returns a `Map<filePath, content>` that `trellis update` uses to detect drift and to populate `.trellis/.template-hashes.json`. Both must produce byte-identical output, so they both call `resolveBundledSkills(ctx)` and `collectSkillTemplates(root, …, resolveBundledSkills(ctx))`.
|
||||
|
||||
## Dispatch Wiring (Code Path)
|
||||
|
||||
The mechanism that auto-dispatches bundled skills to platform skill roots lives in two files:
|
||||
|
||||
1. `packages/cli/src/templates/common/index.ts`
|
||||
- `listDirectories("bundled-skills")` enumerates the on-disk skills.
|
||||
- `listBundledSkillFiles(skillDir)` walks each skill's directory recursively and returns `{relativePath, content}` for every file.
|
||||
- `getBundledSkillTemplates()` returns the cached `CommonBundledSkill[]`.
|
||||
|
||||
2. `packages/cli/src/configurators/shared.ts`
|
||||
- `resolveBundledSkills(ctx)` flattens that list into `ResolvedSkillFile[]` with `<skill>/<relativePath>` paths and resolved placeholders.
|
||||
- `writeSkills(skillsRoot, workflowSkills, bundledSkills)` writes both workflow skills and bundled skill files under `skillsRoot`.
|
||||
- `collectSkillTemplates(skillsRoot, workflowSkills, bundledSkills)` returns the same shape as a `Map<filePath, content>` for the update / hash pipeline.
|
||||
|
||||
Every platform configurator that supports skills imports both helpers (see `claude.ts`, `cursor.ts`, `codex.ts`, `gemini.ts`, `kiro.ts`, `qoder.ts`, `codebuddy.ts`, `copilot.ts`, `droid.ts`, `antigravity.ts`, `devin.ts`, `kilo.ts`). The `index.ts` `PLATFORM_FUNCTIONS` registry also calls `resolveBundledSkills(ctx)` inside each `collectTemplates` closure so `trellis update` tracking stays consistent.
|
||||
|
||||
## Adding a New Bundled Skill
|
||||
|
||||
The shape and dispatch wiring are already generic, so adding a skill requires only file changes plus distribution verification.
|
||||
|
||||
1. **Create the directory tree.**
|
||||
|
||||
```
|
||||
packages/cli/src/templates/common/bundled-skills/<my-skill>/
|
||||
SKILL.md # YAML frontmatter + body
|
||||
references/ # optional
|
||||
<topic>.md
|
||||
assets/ # optional (anything readable as utf-8)
|
||||
```
|
||||
|
||||
2. **Write a valid `SKILL.md` header.** The frontmatter must include at minimum:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <my-skill>
|
||||
description: "When the AI should reach for this skill. Triggering phrases go here."
|
||||
---
|
||||
```
|
||||
|
||||
The `description` is what each platform's auto-trigger mechanism matches against, so it should describe the user-intent triggers, not the skill's internals.
|
||||
|
||||
3. **Use placeholders where appropriate.** Bundled skill content runs through `resolvePlaceholders(file.content, ctx)`. Any `{{platform_name}}`, `{{python_cmd}}`, etc. token supported by `resolvePlaceholders` will be substituted per platform.
|
||||
|
||||
4. **No dispatch wiring is required.** `listDirectories("bundled-skills")` discovers the new directory automatically, so all platforms receive it on the next `trellis init` or `trellis update`.
|
||||
|
||||
5. **Verify the distribution path** before shipping. Skipping any of these steps has historically caused features to be documented as bundled while the published npm tarball was missing the files:
|
||||
|
||||
- Source files exist on the branch being tagged.
|
||||
- `pnpm --filter @mindfoldhq/trellis build` copies the asset into `dist/templates/common/bundled-skills/<skill>/`.
|
||||
- `npm pack --dry-run --json` includes the expected `dist/**` paths.
|
||||
- In a fresh temp project, `trellis init` writes `.claude/skills/<skill>/SKILL.md`, `.agents/skills/<skill>/SKILL.md`, `.zcode/skills/<skill>/SKILL.md`, etc.
|
||||
- `.trellis/.template-hashes.json` lists the generated files.
|
||||
- `trellis update --dry-run` in that temp project reports "Already up to date!".
|
||||
|
||||
6. **Add a migration manifest entry** if the skill is added in a release that other projects will upgrade into. Without an explicit manifest entry the file will land via the standard "missing file" branch of `trellis update`, but a manifest makes the change visible in the changelog.
|
||||
|
||||
## Overriding a Bundled Skill Locally
|
||||
|
||||
There is no formal "project-local skill" mechanism (e.g. `.trellis/skills/`). Bundled skills are platform-rooted, so any override is platform-rooted too.
|
||||
|
||||
The supported pattern relies on the existing template-hash diff in `trellis update`:
|
||||
|
||||
1. Edit the local file directly. Example: `.claude/skills/trellis-meta/SKILL.md`.
|
||||
2. The file's hash now diverges from the entry in `.trellis/.template-hashes.json`.
|
||||
3. The next `trellis update` detects the user modification and leaves the file untouched (Trellis never overwrites user-modified files without an explicit `--force`).
|
||||
|
||||
Caveats:
|
||||
|
||||
- The override only applies to the one platform whose directory you edited. To override the same skill across, for example, Claude Code and Codex, you must edit both `.claude/skills/<name>/` and `.agents/skills/<name>/`.
|
||||
- A future `trellis update --force` will overwrite local edits. Keep the override under version control so it can be reapplied if needed.
|
||||
- Marketplace skills installed under the same platform skill root with a different folder name (e.g. `.claude/skills/my-custom-meta/`) are untouched by Trellis and are the cleaner option when the goal is to add behavior, not to mutate the bundled skill.
|
||||
- Team-private conventions belong in `.trellis/spec/` or in a separate marketplace-style local skill, not in modifications to `trellis-meta` itself. See `customize-local/add-project-local-conventions.md`.
|
||||
|
||||
## Removing a Bundled Skill From a Project
|
||||
|
||||
There is no per-project opt-out flag for bundled skills. Two options:
|
||||
|
||||
1. **Delete the directory in each platform skill root.** `trellis update` will see the file missing, compare against `.template-hashes.json`, and treat the deletion the same as any other user modification — it will not silently re-create the directory unless `--force` is passed.
|
||||
|
||||
2. **Pin a Trellis version that did not ship the skill.** The bundled-skill set is determined at build time, so installing an older release of the CLI is the only way to permanently exclude a skill that the current release ships.
|
||||
|
||||
A third option — globally disabling all bundled skills — is not supported. The dispatch is unconditional in every configurator. Adding such a flag would require changing `PLATFORM_FUNCTIONS` in `configurators/index.ts` and every `configureX` function.
|
||||
|
||||
## Operating Rules
|
||||
|
||||
- Treat `templates/common/bundled-skills/` as the single source of truth for what bundled skills exist. Do not hand-maintain platform-by-platform skill lists.
|
||||
- Do not add platform-specific logic inside a bundled `SKILL.md`. If a behavior is platform-specific, put it in `templates/<platform>/skills/` instead.
|
||||
- Do not couple bundled skills to a specific CLI binary (e.g. `trellis mem`) without surfacing the dependency in the skill's description and references — users on older releases may not have the command.
|
||||
- Do not store project-private content in a bundled skill. Bundled skills are public, shipped to every user; project rules belong in `.trellis/spec/` or a local skill.
|
||||
@@ -9,7 +9,7 @@ Trellis context injection aims to make AI read the right files at the right time
|
||||
| session context | `.trellis/scripts/get_context.py` | Current developer, git status, active task, active tasks, journal, packages. |
|
||||
| workflow context | `.trellis/workflow.md` | Current Trellis flow and next action. |
|
||||
| spec context | `.trellis/spec/` + task JSONL | Specs that must be followed during implementation/checking. |
|
||||
| task context | `.trellis/tasks/<task>/prd.md`, `info.md`, `research/` | Current task requirements, design, and research. |
|
||||
| task context | `.trellis/tasks/<task>/prd.md`, `design.md`, `implement.md`, `research/` | Current task requirements, design, execution plan, and research. |
|
||||
| platform context | Platform hooks/settings/agents | Lets different AI tools read the files above through their own mechanisms. |
|
||||
|
||||
## session-start
|
||||
@@ -34,10 +34,10 @@ If the user wants to change "what the AI should do next in a given state," edit
|
||||
|
||||
Implement and check agents need task context. Trellis has two loading modes:
|
||||
|
||||
1. **hook push**: a platform hook injects `prd.md` and the files referenced by `implement.jsonl` / `check.jsonl` before the agent starts.
|
||||
2. **agent pull**: the agent definition instructs the agent to read the active task, PRD, and JSONL context after startup.
|
||||
1. **hook push**: a platform hook injects jsonl-referenced files plus `prd.md`, `design.md` if present, and `implement.md` if present before the agent starts.
|
||||
2. **agent pull**: the agent definition instructs the agent to read the active task, jsonl context, and task artifacts after startup.
|
||||
|
||||
In both modes, JSONL files in the task directory are the key interface.
|
||||
In both modes, JSONL files in the task directory are the manifest for spec/research context. Task artifacts are read separately in this order: `prd.md` -> `design.md if present` -> `implement.md if present`.
|
||||
|
||||
## JSONL Reading Rules
|
||||
|
||||
@@ -65,4 +65,4 @@ If shell commands cannot see the same context key, `task.py current --source` ma
|
||||
| Change JSONL validation/display | `.trellis/scripts/common/task_context.py`. |
|
||||
| Change active task resolution | `.trellis/scripts/common/active_task.py`. |
|
||||
|
||||
When modifying context injection, verify two things: new sessions can see the correct task, and sub-agents can see the correct PRD/spec/research.
|
||||
When modifying context injection, verify two things: new sessions can see the correct task, and sub-agents can see the correct task artifacts/spec/research.
|
||||
|
||||
@@ -40,10 +40,10 @@ Different platforms generate different directories. Common categories:
|
||||
| Category | Example paths | Purpose |
|
||||
| --- | --- | --- |
|
||||
| hooks | `.claude/hooks/`, `.codex/hooks/`, `.cursor/hooks/` | Inject session context, workflow-state, and sub-agent context. |
|
||||
| settings | `.claude/settings.json`, `.codex/hooks.json`, `.qoder/settings.json` | Tell the platform when to run hooks or plugins. |
|
||||
| agents | `.claude/agents/`, `.codex/agents/`, `.kiro/agents/` | Define agents such as `trellis-research`, `trellis-implement`, and `trellis-check`. |
|
||||
| skills | `.claude/skills/`, `.agents/skills/`, `.qoder/skills/` | Skills that auto-trigger or can be read by AI. |
|
||||
| commands/prompts/workflows | `.cursor/commands/`, `.github/prompts/`, `.windsurf/workflows/` | Explicit user-invoked command or workflow entry points. |
|
||||
| settings | `.claude/settings.json`, `.codex/hooks.json`, `.qoder/settings.json`, `.trae/hooks.json` | Tell the platform when to run hooks or plugins. |
|
||||
| agents | `.claude/agents/`, `.codex/agents/`, `.kiro/agents/`, `.zcode/agents/` | Define agents such as `trellis-research`, `trellis-implement`, and `trellis-check`. |
|
||||
| skills | `.claude/skills/`, `.agents/skills/`, `.qoder/skills/`, `.zcode/skills/` | Skills that auto-trigger or can be read by AI. |
|
||||
| commands/prompts/workflows | `.cursor/commands/`, `.github/prompts/`, `.devin/workflows/`, `.zcode/commands/` | Explicit user-invoked command or workflow entry points. |
|
||||
|
||||
When modifying a platform directory, also confirm whether `.trellis/workflow.md` still describes the same flow.
|
||||
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
# Local Multi-Agent Channel Runtime
|
||||
|
||||
`trellis channel` is the local multi-agent collaboration runtime shipped with the Trellis CLI. It lets the main AI session spawn peer workers (Claude Code, Codex, or any agent definition under `.trellis/agents/`), exchange durable messages through an event log, and coordinate review or brainstorm loops without hand-stitching shell pipelines.
|
||||
|
||||
This reference covers how channels are wired into the user project so an AI customizing the project knows what to edit. For runtime usage (commands, forum/thread patterns, worker spawn flags), defer to the bundled `trellis-channel` capability skill.
|
||||
|
||||
## Local System Model
|
||||
|
||||
The channel runtime spans three local surfaces:
|
||||
|
||||
1. **Storage layer** in the user's home directory: durable event logs and worker state files.
|
||||
2. **Agent definitions** inside the project at `.trellis/agents/`: platform-agnostic role cards consumed by `trellis channel spawn --agent <name>`.
|
||||
3. **Project configuration** in `.trellis/config.yaml`: worker guard thresholds and other channel knobs.
|
||||
|
||||
## Core Paths
|
||||
|
||||
| Path | Purpose |
|
||||
| --- | --- |
|
||||
| `~/.trellis/channels/<project>/<channel>/events.jsonl` | Per-channel append-only event log. Sequence-locked, replay-safe. |
|
||||
| `~/.trellis/channels/<project>/<channel>/<channel>.lock` | Channel-level write lock. |
|
||||
| `~/.trellis/channels/<project>/<channel>/<worker>.spawnlock` | Per-worker spawn lock used by the OOM guard. |
|
||||
| `~/.trellis/channels/<project>/<channel>/.seq` | Sequence sidecar for ordered event assignment. |
|
||||
| `~/.trellis/channels/_global/<channel>/...` | Channels created with `--scope global`. The project bucket is replaced by a shared key. |
|
||||
| `.trellis/agents/check.md` | Default Check Agent role definition consumed by `--agent check`. |
|
||||
| `.trellis/agents/implement.md` | Default Implement Agent role definition consumed by `--agent implement`. |
|
||||
| `.trellis/config.yaml` (`channel.*` block) | Worker guard thresholds and channel defaults. |
|
||||
|
||||
The project bucket name is derived from the absolute project path (slashes flattened, non-alphanumerics replaced with `-`), matching Claude Code's `~/.claude/projects/<sanitized-cwd>/` convention. Override with `TRELLIS_CHANNEL_ROOT` (root directory) or `TRELLIS_CHANNEL_PROJECT` (bucket name) for testing or sandboxing.
|
||||
|
||||
## When To Reach For The Channel Runtime
|
||||
|
||||
Channels are heavier than a single Bash call or a one-shot sub-agent dispatch. Use them only when at least one of these conditions holds:
|
||||
|
||||
- The work needs **two or more agents to converse** through more than one turn (cross-AI brainstorm, peer review, dispatcher + worker).
|
||||
- A worker should run as a **peer process** that the main session can interrupt, watch progress on, or wait for asynchronously.
|
||||
- The conversation must be **durable and inspectable** later (forum/thread channels, issue boards, decision trails).
|
||||
- Multiple workers must **share an event log** so each can see what the others reported.
|
||||
|
||||
Prefer cheaper primitives when:
|
||||
|
||||
- A single-shot Bash command or single Agent tool call is enough -> do that directly.
|
||||
- The user just needs a static review against a file -> read the file and reply inline.
|
||||
- The need is "remember what we discussed last week" -> use `trellis mem` instead of a channel.
|
||||
|
||||
## Customization Points
|
||||
|
||||
| Need | Edit location |
|
||||
| --- | --- |
|
||||
| Change default channel worker idle timeout | `channel.worker_guard.idle_timeout` in `.trellis/config.yaml`. Accepts `5m`, `30s`, etc. Set `0` to disable idle cleanup. |
|
||||
| Change live worker budget | `channel.worker_guard.max_live_workers` in `.trellis/config.yaml`. Set `0` to disable the spawn-time budget check. |
|
||||
| Override worker guard per spawn | Pass `--idle-timeout` / `--max-live-workers` on `trellis channel spawn`, or set `TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT` / `TRELLIS_CHANNEL_MAX_LIVE_WORKERS` in the environment. |
|
||||
| Change what the default Check or Implement worker does | Edit `.trellis/agents/check.md` or `.trellis/agents/implement.md`. These are platform-agnostic role cards; the channel runtime injects them when `--agent check|implement` is passed. |
|
||||
| Add a new role card | Drop `<name>.md` into `.trellis/agents/`. `trellis channel spawn --agent <name>` will pick it up. |
|
||||
| Relocate channel storage (CI sandbox, ephemeral runs) | Set `TRELLIS_CHANNEL_ROOT=/path/to/dir`. Channel events move with it; existing channels stay at the old root. |
|
||||
| Switch storage scope | Pass `--scope project` (default) or `--scope global` on every channel subcommand. The bucket directory changes; nothing else does. |
|
||||
|
||||
Precedence for the worker guard is: CLI flag > environment variable > `.trellis/config.yaml` > built-in default. Built-in defaults are `idle_timeout: 5m` and `max_live_workers: 6`.
|
||||
|
||||
## Relationship To Other Local Layers
|
||||
|
||||
- **Workflow layer**: workflows that use channel dispatch (such as `channel-driven-subagent-dispatch`) instruct the main agent to call `trellis channel spawn --agent check` or `--agent implement` instead of a platform sub-agent. If `.trellis/agents/check.md` or `implement.md` is missing, `trellis workflow --template <id>` prints a non-blocking warning at install time. Restore them with `trellis update` if they are deleted by accident.
|
||||
- **Task layer**: channel workers do not own task state. The supervising main session passes the active task path through the worker inbox; the worker resolves task artifacts from disk.
|
||||
- **Spec layer**: workers read `.trellis/spec/` the same way the main session does. Channel runtime does not bypass spec context loading.
|
||||
- **Platform integration layer**: channel runtime is platform-neutral. It does not depend on `.claude/`, `.codex/`, or any other platform directory. The adapters that normalize provider output (Claude `stream-json`, Codex `app-server`) live inside the Trellis CLI binary, not in the project.
|
||||
- **Platform sub-agent files vs. channel workers**: editing `.claude/agents/trellis-implement.md` (and its peers in other platform `.X/agents/` directories) does NOT change channel-runtime worker behavior — channel workers load `.trellis/agents/<name>.md`. The platform-specific agent files are for direct sub-agent dispatch from the main AI session, not for channel-spawned workers. See `platform-files/agents.md` for the per-platform agent surface, and the `trellis-meta/SKILL.md` rule that codifies this split.
|
||||
|
||||
## Runtime Usage
|
||||
|
||||
For command syntax, forum/thread patterns, worker handles, progress inspection, and the `--kind done` / `--kind turn_finished` dispatcher wait pattern, load the bundled `trellis-channel` skill (auto-installed under each platform's skills directory after `trellis init` / `trellis update`). This reference only covers the local file layout and customization knobs; it does not duplicate command syntax that may change between releases.
|
||||
@@ -5,7 +5,7 @@
|
||||
Therefore, when an AI uses this skill, the default customization target is local files inside the user project:
|
||||
|
||||
- `.trellis/`: workflow, tasks, specs, memory, scripts, and runtime state.
|
||||
- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.windsurf/`, and similar directories.
|
||||
- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.devin/`, `.reasonix/`, `.zcode/`, and similar directories.
|
||||
- Shared skill layer: `.agents/skills/`.
|
||||
|
||||
Do not default to guiding the user to fork the Trellis CLI repository. Treat upstream source code as the operating target only when the user explicitly says they want to change Trellis upstream source, publish an npm package, or contribute a PR.
|
||||
|
||||
@@ -65,7 +65,7 @@ This command lists packages and spec layers for the current project. Use this ou
|
||||
|
||||
## How Specs Enter Tasks
|
||||
|
||||
Before a task enters implementation, Phase 1.3 should write relevant specs into `implement.jsonl` / `check.jsonl`:
|
||||
Before a task enters implementation, planning may write relevant specs into `implement.jsonl` / `check.jsonl` when the task needs spec or research context beyond the task artifacts:
|
||||
|
||||
```jsonl
|
||||
{"file": ".trellis/spec/cli/backend/index.md", "reason": "CLI backend conventions"}
|
||||
|
||||
@@ -9,7 +9,8 @@ The Trellis task system is stored entirely under `.trellis/tasks/` in the user p
|
||||
├── 04-28-example-task/
|
||||
│ ├── task.json
|
||||
│ ├── prd.md
|
||||
│ ├── info.md
|
||||
│ ├── design.md
|
||||
│ ├── implement.md
|
||||
│ ├── implement.jsonl
|
||||
│ ├── check.jsonl
|
||||
│ └── research/
|
||||
@@ -20,8 +21,9 @@ The Trellis task system is stored entirely under `.trellis/tasks/` in the user p
|
||||
| File | Purpose |
|
||||
| --- | --- |
|
||||
| `task.json` | Task metadata: status, assignee, priority, branch, parent/child tasks, and similar fields. |
|
||||
| `prd.md` | Requirements document; the most important business context during implementation. |
|
||||
| `info.md` | Optional technical design. |
|
||||
| `prd.md` | Requirements, constraints, and acceptance criteria. Lightweight tasks may be PRD-only. |
|
||||
| `design.md` | Technical design for complex tasks: boundaries, contracts, data flow, compatibility, tradeoffs. |
|
||||
| `implement.md` | Execution plan for complex tasks: ordered checklist, validation commands, review gates, rollback points. |
|
||||
| `implement.jsonl` | List of spec/research files the implement agent must read first. |
|
||||
| `check.jsonl` | List of spec/research files the check agent must read first. |
|
||||
| `research/` | Research artifacts. Complex findings should not live only in chat. |
|
||||
@@ -42,7 +44,34 @@ The Trellis task system is stored entirely under `.trellis/tasks/` in the user p
|
||||
| `commit` / `pr_url` | Commit and PR information after completion. |
|
||||
| `meta` | Extension fields. |
|
||||
|
||||
The AI should not treat phase numbers as task status. Task progress is mainly determined by `status`, `prd.md`, whether JSONL context is configured, and the phase descriptions in `workflow.md`.
|
||||
## Parent / Child Task Trees
|
||||
|
||||
Parent/child task relationships are for work structure. A parent task groups related deliverables under one source requirement set; it is not a dependency scheduler and does not replace the child task's own planning artifacts.
|
||||
|
||||
Use a parent task when a request has multiple independently verifiable deliverables. The parent owns:
|
||||
|
||||
- Source requirements and user-facing scope.
|
||||
- The map of child tasks and their responsibility boundaries.
|
||||
- Cross-child acceptance criteria and final integration review.
|
||||
|
||||
Use child tasks for deliverables that can move through planning, implementation, check, and archive independently. If one child depends on another, write that dependency in the child `prd.md` / `implement.md`; do not rely on tree position to imply ordering.
|
||||
|
||||
Create new children with:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py create "<child title>" --slug <child-slug> --parent <parent-dir>
|
||||
```
|
||||
|
||||
Link or unlink existing tasks with:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py add-subtask <parent-dir> <child-dir>
|
||||
python3 ./.trellis/scripts/task.py remove-subtask <parent-dir> <child-dir>
|
||||
```
|
||||
|
||||
`children` on the parent is a historical list. When a child is archived, Trellis keeps that child name in the parent so progress like `[2/3 done]` remains meaningful after completed children move to `archive/`.
|
||||
|
||||
The AI should not treat phase numbers as task status. Task progress is mainly determined by `status`, artifact presence (`prd.md`, optional `design.md` / `implement.md`), whether JSONL context is configured for sub-agent mode, and the phase descriptions in `workflow.md`.
|
||||
|
||||
## Active Task
|
||||
|
||||
@@ -58,7 +87,7 @@ If the platform or shell environment has no stable session identity, `task.py st
|
||||
|
||||
## JSONL Context
|
||||
|
||||
`implement.jsonl` and `check.jsonl` are context manifests for sub-agents to read first.
|
||||
`implement.jsonl` and `check.jsonl` are context manifests for sub-agents to read first. They do not replace `implement.md`; `implement.md` is the human-readable execution plan.
|
||||
|
||||
Format:
|
||||
|
||||
@@ -95,7 +124,7 @@ When modifying the task system, the AI should prefer script commands to maintain
|
||||
| Change the default task template | `.trellis/scripts/common/task_store.py` and task creation instructions. |
|
||||
| Change status semantics | `.trellis/workflow.md`, workflow-state hook logic, and task usage conventions. |
|
||||
| Add task lifecycle actions | `hooks.after_*` in `.trellis/config.yaml`. |
|
||||
| Change context rules | Phase 1.3 in `.trellis/workflow.md` and related platform agent/hook instructions. |
|
||||
| Change context rules | Planning artifact guidance in `.trellis/workflow.md` and related platform agent/hook instructions. |
|
||||
| Change archive policy | `.trellis/scripts/common/task_store.py` / `task_utils.py`. |
|
||||
|
||||
These are local files in the user project. Do not default to editing Trellis CLI source code unless the user wants to contribute upstream.
|
||||
|
||||
@@ -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/skills/trellis-*/SKILL.md` (agent prompts as skills, dispatched to the built-in `coder`; research needs its file-editing tools to persist findings) |
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@@ -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 with the same prelude.
|
||||
|
||||
Whether these files exist in a project depends on which `trellis init --<platform>` flags the user ran.
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ Trellis connects the same local architecture to different AI tools. `.trellis/`
|
||||
When a local AI modifies Trellis, it should distinguish two file categories first:
|
||||
|
||||
- **Shared files**: `.trellis/workflow.md`, `.trellis/tasks/`, `.trellis/spec/`, `.trellis/scripts/`.
|
||||
- **Platform files**: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.windsurf/`, and similar directories.
|
||||
- **Platform files**: `.claude/`, `.snow/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.trae/`, `.kilocode/`, `.agent/`, `.devin/`, `.reasonix/`, `.zcode/`, `.kimi-code/`, and similar directories.
|
||||
|
||||
Platform files do not store business state. They let the corresponding AI tool read Trellis state, call Trellis scripts, and load Trellis skills/agents/hooks.
|
||||
|
||||
@@ -13,11 +13,11 @@ Platform files do not store business state. They let the corresponding AI tool r
|
||||
|
||||
| Category | Common paths | Purpose |
|
||||
| --- | --- | --- |
|
||||
| settings/config | `.claude/settings.json`, `.codex/hooks.json`, `.qoder/settings.json` | Register hooks, plugins, extensions, or platform behavior. |
|
||||
| settings/config | `.claude/settings.json`, `.codex/hooks.json`, `.qoder/settings.json`, `.trae/hooks.json` | Register hooks, plugins, extensions, or platform behavior. |
|
||||
| hooks/plugins/extensions | `.claude/hooks/`, `.opencode/plugins/`, `.pi/extensions/` | Inject context at session start, user input, agent startup, shell execution, and similar events. |
|
||||
| agents | `.claude/agents/`, `.codex/agents/`, `.kiro/agents/` | Define `trellis-research`, `trellis-implement`, and `trellis-check`. |
|
||||
| skills | `.claude/skills/`, `.agents/skills/`, `.qoder/skills/` | Capability descriptions that auto-trigger or can be read on demand. |
|
||||
| commands/prompts/workflows | `.cursor/commands/`, `.github/prompts/`, `.windsurf/workflows/` | Entry points explicitly invoked by the user. |
|
||||
| agents | `.claude/agents/`, `.codex/agents/`, `.kiro/agents/`, `.zcode/agents/` | Define `trellis-research`, `trellis-implement`, and `trellis-check`. |
|
||||
| skills | `.claude/skills/`, `.agents/skills/`, `.qoder/skills/`, `.zcode/skills/` | Capability descriptions that auto-trigger or can be read on demand. |
|
||||
| commands/prompts/workflows | `.cursor/commands/`, `.github/prompts/`, `.devin/workflows/`, `.zcode/commands/` | Entry points explicitly invoked by the user. |
|
||||
|
||||
## Three Platform Integration Modes
|
||||
|
||||
|
||||
@@ -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/` | None — agent prompts are skills under `.kimi-code/skills/` and dispatch to the built-in `coder` | 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 (delivered as skills under `.kimi-code/skills/`; dispatched to the built-in `coder`, including research because it must persist files)
|
||||
- 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 `.<platform>/agents/`, and enforces dispatch modes.
|
||||
|
||||
- Pi Agent — `trellis_subagent` tool, defined in `.pi/extensions/trellis/index.ts`. Supports `single` / `parallel` / `chain` dispatch modes and emits live `trellis-subagent-progress` events.
|
||||
|
||||
When changing sub-agent dispatch behavior on these platforms, edit the extension file, **not** the agent markdown — the agent markdown defines responsibilities, but the host extension owns dispatch, validation, and progress rendering.
|
||||
|
||||
### Main-Session Workflow Platforms
|
||||
|
||||
These platforms rely more on workflows/skills to guide the main session:
|
||||
|
||||
- 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
|
||||
|
||||
@@ -72,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.
|
||||
|
||||
@@ -25,12 +25,15 @@ Trellis workflow skills usually share one semantic set: brainstorm, before-dev,
|
||||
| Kiro | `.kiro/skills/` |
|
||||
| Gemini CLI | `.agents/skills/`, `.gemini/commands/` |
|
||||
| Antigravity | `.agent/skills/`, `.agent/workflows/` |
|
||||
| Windsurf | `.windsurf/skills/`, `.windsurf/workflows/` |
|
||||
| Devin | `.devin/skills/`, `.devin/workflows/` |
|
||||
| Qoder | `.qoder/skills/`, `.qoder/commands/` |
|
||||
| CodeBuddy | `.codebuddy/skills/`, `.codebuddy/commands/` |
|
||||
| GitHub Copilot | `.github/skills/`, `.github/prompts/` |
|
||||
| Factory Droid | `.factory/skills/`, `.factory/commands/` |
|
||||
| Pi Agent | `.pi/skills/` |
|
||||
| Pi Agent | `.agents/skills/` |
|
||||
| Reasonix | `.reasonix/skills/` |
|
||||
| ZCode | `.zcode/skills/`, `.zcode/commands/` |
|
||||
| Kimi Code | `.agents/skills/`, `.kimi-code/skills/` (commands delivered as `/skill:trellis-*` skills) |
|
||||
|
||||
In a user project, use the files actually generated by init as authoritative.
|
||||
|
||||
|
||||
在新工单中引用
屏蔽一个用户