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