升级 Trellis 并完成项目审查（07-26-trellis-upgrade-project-audit）
这个提交包含在：
@@ -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.
|
||||
|
||||
|
||||
在新工单中引用
屏蔽一个用户