chore: 升级 Trellis 并精简规则（09-05-trellis-upgrade-rule-cleanup）
这个提交包含在：
@@ -1,40 +1,15 @@
|
||||
---
|
||||
name: trellis-before-dev
|
||||
description: "Discovers and injects project-specific coding guidelines from .trellis/spec/ before implementation begins. Reads spec indexes, pre-development checklists, and shared thinking guides for the target package. Use when starting a new coding task, before writing any code, switching to a different package, or needing to refresh project conventions and standards."
|
||||
description: "Load the task and affected-layer guidelines before implementation or when scope changes. Not for pure consultation or repeated reading of unchanged context."
|
||||
---
|
||||
|
||||
Read the relevant development guidelines before starting your task.
|
||||
# Before Development
|
||||
|
||||
Execute these steps:
|
||||
1. Read the current PRD and applicable design/implementation notes if not already current in context.
|
||||
2. Identify the smallest behavior gap, affected files, exclusions and validation commands. Reuse the approved plan rather than writing another checklist.
|
||||
3. Discover package indexes only when the affected layer is unknown. Read its relevant coding and quality contracts; follow references needed for this change.
|
||||
4. Read cross-layer or reuse guides only when shared contracts, multiple layers, shared constants or new abstractions are involved.
|
||||
5. Once the plan is approved, continue through implementation and relevant validation. Ask again only for material changes to scope, risk or acceptance, or separately protected operations.
|
||||
6. Keep unrelated dirty files and pre-existing failures out of scope. A local refactor requires evidence that behavior stays unchanged.
|
||||
|
||||
1. **Read current task artifacts**:
|
||||
- `prd.md` for requirements and acceptance criteria
|
||||
- `design.md` if present for technical design
|
||||
- `implement.md` if present for execution order and validation plan
|
||||
|
||||
2. **Discover packages and their spec layers**:
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode packages
|
||||
```
|
||||
|
||||
3. **Identify which specs apply** to your task based on:
|
||||
- Which package you're modifying (e.g., `cli/`, `docs-site/`)
|
||||
- What type of work (backend, frontend, unit-test, docs, etc.)
|
||||
- Any spec/research paths referenced by the task artifacts
|
||||
|
||||
4. **Read the spec index** for each relevant module:
|
||||
```bash
|
||||
cat .trellis/spec/<package>/<layer>/index.md
|
||||
```
|
||||
Follow the **"Pre-Development Checklist"** section in the index.
|
||||
|
||||
5. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns.
|
||||
|
||||
6. **Always read shared guides**:
|
||||
```bash
|
||||
cat .trellis/spec/guides/index.md
|
||||
```
|
||||
|
||||
7. Understand the coding standards and patterns you need to follow, then proceed with your development plan.
|
||||
|
||||
This step is **mandatory** before writing any code.
|
||||
Do not force full document reads, repeat unchanged context, require unavailable tools, or turn a rule-only task into full business testing. Preserve privacy, production and independent-review boundaries from AGENTS.md.
|
||||
|
||||
@@ -9,7 +9,7 @@ description: "Guides collaborative requirements discovery before implementation.
|
||||
|
||||
A request to build, implement, fix, refactor, or "go ahead" is not approval to leave planning. Task-creation consent is also not implementation approval.
|
||||
|
||||
For every non-trivial task, the user must respond at least once after the initial request before implementation begins. If no clarification is needed, that response must approve the final planning summary described below.
|
||||
For non-trivial work, present the plan and obtain approval before implementation. Approval of the same plan in prior turns remains valid; clerical backfill, unchanged artifacts or repeated planning breadcrumbs do not restart the approval gate. Once decisions and required artifacts are complete, start and execute the approved scope.
|
||||
|
||||
While any user-owned product, scope, UX, compatibility, risk, or acceptance decision remains unresolved, end the turn with exactly one highest-value question. Do not edit product code, dispatch implementation, or run `task.py start`.
|
||||
|
||||
@@ -34,10 +34,10 @@ Use this skill only after task-creation consent has been given and the user is r
|
||||
If no task exists yet, create one:
|
||||
|
||||
```bash
|
||||
TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<short task title>" --slug <slug>)
|
||||
TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<short task title>" --description "<one-line summary>" --slug <slug>)
|
||||
```
|
||||
|
||||
Use a concise title from the user's request. Use a slug without a date prefix. `task.py create` adds the `MM-DD-` directory prefix automatically.
|
||||
Use a concise title from the user's request. Both the title and `--description` must be non-empty — `create` rejects blanks, and a record with either one empty is refused at archive. Use a slug without a date prefix. `task.py create` adds the `MM-DD-` directory prefix automatically.
|
||||
|
||||
`task.py create` creates the default `prd.md`. Update that file with the current understanding before asking follow-up questions.
|
||||
|
||||
@@ -57,8 +57,8 @@ Use a concise title from the user's request. Use a slug without a date prefix. `
|
||||
5. After each user answer, update `prd.md`, recompute the decision inventory, and repeat from step 2.
|
||||
6. When no user-owned decision remains, create or update `design.md` and `implement.md` for complex tasks.
|
||||
7. Run the requirement convergence gate, then the PRD convergence pass.
|
||||
8. Present the final planning summary and stop. Do not run `task.py start` or edit product code in the same turn.
|
||||
9. Only a subsequent user message that explicitly approves the latest planning summary authorizes `task.py start` and implementation. If the artifacts change materially after approval, repeat the final review.
|
||||
8. If this plan has not yet been approved, present its final summary and wait. If the same scope has already been approved, do not ask again.
|
||||
9. With recorded approval and complete artifacts, run `task.py start` and implement. Repeat review only for a material scope, risk or acceptance change.
|
||||
|
||||
Do not invent a project-specific product/spec hierarchy. If the repository already has product, domain, or spec docs, use them. If it does not, proceed with the evidence that exists.
|
||||
|
||||
@@ -77,9 +77,9 @@ Do not ask process questions such as whether to search, inspect files, or contin
|
||||
|
||||
Recommendations are not default selections. Never choose a recommended product decision on the user's behalf merely because the user asked for implementation.
|
||||
|
||||
Do not manufacture clarification questions when the request and repository evidence already resolve every decision. In that case, proceed directly to the final planning summary, which still requires a subsequent explicit approval.
|
||||
Do not manufacture clarification questions. Present a new plan for approval when needed; if the same plan is already approved and artifacts are complete, start implementation.
|
||||
|
||||
The final review is a required phase-transition gate, not a prohibited process question. Task-creation consent, the initial implementation request, and approval given before the latest final summary do not satisfy this gate.
|
||||
Final review is required for a new or materially changed plan, not for reformatting an already approved plan. Task-creation consent alone is not implementation approval.
|
||||
|
||||
## Thinking Framework: First Principles Analysis
|
||||
|
||||
@@ -167,7 +167,7 @@ The final planning summary must show Goal, In Scope, Out of Scope, Acceptance Cr
|
||||
|
||||
Lightweight tasks may have only `prd.md`. Complex tasks must have `prd.md`, `design.md`, and `implement.md` before `task.py start`.
|
||||
|
||||
`implement.md` is not a replacement for `implement.jsonl`. On sub-agent-dispatch workflows, `implement.jsonl` and `check.jsonl` must each contain at least one real spec/research entry before `task.py start`; the seed `_example` row does not count. Inline workflows skip this JSONL gate because Phase 2 loads context through `trellis-before-dev`.
|
||||
`implement.md` is not a replacement for `implement.jsonl`. On sub-agent-dispatch workflows, `implement.jsonl` and `check.jsonl` must each contain at least one real spec/research entry before `task.py start`; an empty manifest, or one holding only a legacy `_example` placeholder row, does not count. Inline workflows skip this JSONL gate because Phase 2 loads context through `trellis-before-dev`.
|
||||
|
||||
## PRD Convergence Pass
|
||||
|
||||
@@ -195,6 +195,6 @@ Before declaring planning ready:
|
||||
- Complex tasks have `design.md` and `implement.md`.
|
||||
- Sub-agent-dispatch tasks have real curated entries in both `implement.jsonl` and `check.jsonl`; seed-only manifests are not ready.
|
||||
- The latest final planning summary has been presented to the user.
|
||||
- In a subsequent message, the user explicitly approved that summary for implementation.
|
||||
- The user explicitly approved this scope for implementation; unchanged restatements and clerical backfill do not invalidate that approval.
|
||||
|
||||
Do not start implementation merely because the user originally asked for implementation.
|
||||
|
||||
@@ -1,98 +1,15 @@
|
||||
---
|
||||
name: trellis-check
|
||||
description: "Comprehensive quality verification: spec compliance, lint, type-check, tests, cross-layer data flow, code reuse, and consistency checks. Use when code is written and needs quality verification, before committing changes, or to catch context drift during long sessions."
|
||||
description: "Verify the current task diff against its acceptance criteria and affected-layer contracts. Use after implementation or before an authorized commit, not for unrelated repository cleanup."
|
||||
---
|
||||
|
||||
# Code Quality Check
|
||||
# Task-Scoped Quality Check
|
||||
|
||||
Comprehensive quality verification for recently written code. Combines spec compliance, cross-layer safety, and pre-commit checks.
|
||||
1. Identify files changed by this task. Git dirty state is evidence, not permission to include other work.
|
||||
2. Read acceptance criteria and applicable quality contracts not already loaded. Check the complete task diff, not only the last chunk.
|
||||
3. Run the minimum meaningful checks: targeted regressions for behavior changes, relevant syntax/type/build checks for affected layers, and governance/reference checks for rules. Expand for shared contracts and cross-layer risks.
|
||||
4. Verify permissions, state transitions, error handling, data flow and tests when affected. Review abstractions and fallback behavior only where the task changes them.
|
||||
5. Fix task-caused failures and rerun affected checks. Report pre-existing failures separately; do not repair unrelated business code. Reuse passing checks whose inputs remain unchanged.
|
||||
6. Report what passed, failed, was not run and why. Distinguish static checks, runtime tests, independent review and public deployment. Never claim a separate reviewer when only the main session checked.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Identify What Changed
|
||||
|
||||
```bash
|
||||
git diff --name-only HEAD
|
||||
git status
|
||||
```
|
||||
|
||||
## Step 2: Read Task Artifacts and Applicable Specs
|
||||
|
||||
Read the current task artifacts in order:
|
||||
|
||||
- `prd.md`
|
||||
- `design.md` if present
|
||||
- `implement.md` if present
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode packages
|
||||
```
|
||||
|
||||
For each changed package/layer, read the spec index and follow its **Quality Check** section:
|
||||
|
||||
```bash
|
||||
cat .trellis/spec/<package>/<layer>/index.md
|
||||
```
|
||||
|
||||
Read the specific guideline files referenced — the index is a pointer, not the goal.
|
||||
|
||||
## Step 3: Run Project Checks
|
||||
|
||||
Run the project's lint, type-check, and test commands. Fix any failures before proceeding.
|
||||
|
||||
## Step 4: Review Against Checklist
|
||||
|
||||
### Code Quality
|
||||
|
||||
- [ ] Linter passes?
|
||||
- [ ] Type checker passes (if applicable)?
|
||||
- [ ] Tests pass?
|
||||
- [ ] No debug logging left in?
|
||||
- [ ] No suppressed warnings or type-safety bypasses?
|
||||
|
||||
### Test Coverage
|
||||
|
||||
- [ ] New function → unit test added?
|
||||
- [ ] Bug fix → regression test added?
|
||||
- [ ] Changed behavior → existing tests updated?
|
||||
|
||||
### Spec Sync
|
||||
|
||||
- [ ] Does `.trellis/spec/` need updates? (new patterns, conventions, lessons learned)
|
||||
|
||||
> "If I fixed a bug or discovered something non-obvious, should I document it so future me won't hit the same issue?" → If YES, update the relevant spec doc.
|
||||
|
||||
## Step 5: Cross-Layer Dimensions (if applicable)
|
||||
|
||||
Skip this step if your change is confined to a single layer.
|
||||
|
||||
### A. Data Flow (changes touch 3+ layers)
|
||||
|
||||
- [ ] Read flow traces correctly: Storage → Service → API → UI
|
||||
- [ ] Write flow traces correctly: UI → API → Service → Storage
|
||||
- [ ] Types/schemas correctly passed between layers?
|
||||
- [ ] Errors properly propagated to caller?
|
||||
|
||||
### B. Code Reuse (modifying constants, creating utilities)
|
||||
|
||||
- [ ] Searched for existing similar code before creating new?
|
||||
```bash
|
||||
grep -r "pattern" src/
|
||||
```
|
||||
- [ ] If 2+ places define same value → extracted to shared constant?
|
||||
- [ ] After batch modification, all occurrences updated?
|
||||
|
||||
### C. Import/Dependency (creating new files)
|
||||
|
||||
- [ ] Correct import paths (relative vs absolute)?
|
||||
- [ ] No circular dependencies?
|
||||
|
||||
### D. Same-Layer Consistency
|
||||
|
||||
- [ ] Other places using the same concept are consistent?
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Report and Fix
|
||||
|
||||
Report violations found and fix them directly. Re-run project checks after fixes.
|
||||
Run one final task-wide acceptance pass before handoff. Do not repeat full-repository tests each iteration or require deployment for pure rules, documentation or local tooling. Capture reusable contracts in the existing spec only when they add value.
|
||||
|
||||
@@ -31,7 +31,7 @@ Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
|
||||
|
||||
- `status=planning` + no `prd.md` → **1.1** (load `trellis-brainstorm`)
|
||||
- `status=planning` + `prd.md` only → decide whether the task is lightweight or complex. Lightweight can move to **1.4** review; complex returns to **1.1** to add `design.md` + `implement.md`.
|
||||
- `status=planning` + complex artifacts complete + sub-agent jsonl not curated (only the seed `_example` row) → **1.3**
|
||||
- `status=planning` + complex artifacts complete + sub-agent jsonl not curated (empty, or only a legacy `_example` placeholder row) → **1.3**
|
||||
- `status=planning` + required artifacts complete + required jsonl curated or inline mode → **1.4** (ask for start review; only run `task.py start` after user confirms)
|
||||
- `status=in_progress` + implementation not started → **2.1**
|
||||
- `status=in_progress` + implementation done, not yet checked → **2.2**
|
||||
|
||||
@@ -1,71 +1,14 @@
|
||||
---
|
||||
name: trellis-finish-work
|
||||
description: "Wrap up the current session: verify quality gate passed, remind user to commit, archive completed tasks, and record session progress to the developer journal. Use when done coding and ready to end the session."
|
||||
description: "Close out an explicitly requested session or completed task with truthful verification and progress notes. Does not implicitly authorize commits, archival, deployment or other-task cleanup."
|
||||
---
|
||||
|
||||
# Finish Work
|
||||
|
||||
Wrap up the current session: archive the active task (and any other completed-but-unarchived tasks the user wants to clean up) and record the session journal. Code commits are NOT done here — those happen in workflow Phase 3.4 before you invoke this command.
|
||||
1. Compare this task with its acceptance criteria and latest validation evidence. Do not scan unrelated active tasks for cleanup.
|
||||
2. Report implementation, tests, independent review and deployment separately. A completed stage can leave the overall task active; unresolved acceptance must not be checked off.
|
||||
3. Update existing task notes with concise, redacted results and remaining steps. Record a journal only when useful or requested; avoid duplicating stable facts across documents.
|
||||
4. Commit only when explicitly requested, using named task files and a Chinese message containing the task identifier. Never stage unrelated changes or auto-commit journal files; respect session_auto_commit=false.
|
||||
5. Archive only when the task is genuinely complete and archival is explicitly requested. Otherwise leave the task active and report the handoff. Do not infer archive permission from “done” or from reaching the end of a reply.
|
||||
|
||||
## Step 1: Survey current state
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode record
|
||||
```
|
||||
|
||||
This prints:
|
||||
|
||||
- **My active tasks** — review whether any besides the current one are actually done (code merged, AC met) and should be archived this round.
|
||||
- **Git status** — quick visual on what's dirty.
|
||||
- **Recent commits** — you'll need their hashes in Step 4 for `--commit`.
|
||||
|
||||
If `--mode record` surfaces other completed tasks not tied to the current session, surface them to the user with a one-shot confirmation: "These N tasks look done — archive them too in this round? [y/N]". Default is no; the current active task is always archived in Step 3 regardless.
|
||||
|
||||
## Step 2: Sanity check — classify dirty paths
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
git status --porcelain
|
||||
```
|
||||
|
||||
Filter out paths under `.trellis/workspace/` and `.trellis/tasks/` — those are managed by `add_session.py` and `task.py archive` auto-commits and will appear dirty as part of this skill's own work.
|
||||
|
||||
For each remaining dirty path, decide whether it belongs to **the current task** or to **other parallel work** (e.g., another terminal window editing the same repo). Heuristics:
|
||||
|
||||
- Paths referenced in the current task's `prd.md` / `implement.jsonl` / `check.jsonl` → current task
|
||||
- Paths in code areas matching the task's stated scope, or that you remember editing this session → current task
|
||||
- Paths in unrelated areas you have no recollection of touching this session → other parallel work
|
||||
|
||||
Then route:
|
||||
|
||||
- **Any remaining path looks like current-task work** — bail out with:
|
||||
> "Working tree has uncommitted code changes from this task: `<list>`. Return to workflow Phase 3.4 to commit them before running ``finish-work` (Trellis command)`."
|
||||
|
||||
Do NOT run `git commit` here. Do NOT prompt the user to commit. The user goes back to Phase 3.4 and the AI drives the batched commit there.
|
||||
- **All remaining paths look unrelated** (other parallel-window work) — report them once and continue to Step 3:
|
||||
> "FYI, dirty files outside this task's scope — leaving them for the other window: `<list>`."
|
||||
- **Genuinely unsure** — ask the user once: "Are `<list>` this task's work I forgot to commit, or another window's? (commit / ignore)" — then route per their answer.
|
||||
|
||||
## Step 3: Archive task(s)
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py archive <task-name>
|
||||
```
|
||||
|
||||
At minimum: the current active task (if any). Plus any extra tasks the user confirmed in Step 1. Each archive produces a `chore(task): archive ...` commit via the script's auto-commit.
|
||||
|
||||
If there is no active task and the user did not confirm any cleanup archives, skip this step.
|
||||
|
||||
## Step 4: Record session journal
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/add_session.py \
|
||||
--title "Session Title" \
|
||||
--commit "hash1,hash2" \
|
||||
--summary "Brief summary"
|
||||
```
|
||||
|
||||
Use the work-commit hashes produced in Phase 3.4 (visible in Step 1's `Recent commits` list, or via `git log --oneline`) for `--commit`. Do not include the archive commit hashes from Step 3. This produces a `chore: record journal` commit.
|
||||
|
||||
Final git log order: `<work commits from 3.4>` → `chore(task): archive ...` (one or more) → `chore: record journal`.
|
||||
Do not deploy, push, delete files, scan prior conversations, or clean other tasks as a side effect. Tool limitations and pending independent review must be stated rather than hidden or used to repeat an already granted authorization.
|
||||
|
||||
@@ -12,7 +12,7 @@ Trellis v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow /
|
||||
The default operating scope is local files in the user project:
|
||||
|
||||
- `.trellis/`: workflow, config, tasks, spec, workspace, scripts, bundled runtime agents, and runtime state.
|
||||
- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills/<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`.
|
||||
- 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, delivers commands plus agent prompts as `.kimi-code/skills/<name>/SKILL.md`, and installs the same agent prompts as custom sub-agents under `.kimi-code/agents/<name>.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).
|
||||
|
||||
@@ -31,30 +31,42 @@ The list is discovered at runtime, so adding a new directory under `bundled-skil
|
||||
|
||||
## 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.
|
||||
A platform's whole file set — commands, workflow skills, agents, hooks, bundled skills — is described exactly once, by `collect<Platform>Templates()` in `packages/cli/src/configurators/<platform>.ts`. For bundled skills that description is two calls: `resolveBundledSkills(ctx)` reads every directory under `templates/common/bundled-skills/`, resolves placeholders, and returns a flat list of `{relativePath, content}` entries; `collectSkillTemplates(<skillsRoot>, <workflowSkills>, <bundledSkills>)` folds them into the platform's `Map<filePath, content>` under `<skillsRoot>/<skill>/<relativePath>`.
|
||||
|
||||
| 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 |
|
||||
All 21 platforms receive the full bundled-skill set:
|
||||
|
||||
Two paths exercise the same data:
|
||||
| Platform | Bundled skill root |
|
||||
| --- | --- |
|
||||
| Claude Code | `.claude/skills/<skill>/` |
|
||||
| Cursor | `.cursor/skills/<skill>/` |
|
||||
| OpenCode | `.opencode/skills/<skill>/` |
|
||||
| Codex | `.agents/skills/<skill>/` |
|
||||
| Gemini CLI | `.agents/skills/<skill>/` |
|
||||
| Pi | `.agents/skills/<skill>/` |
|
||||
| Kimi | `.agents/skills/<skill>/` |
|
||||
| Kilo | `.kilocode/skills/<skill>/` |
|
||||
| Kiro | `.kiro/skills/<skill>/` |
|
||||
| Antigravity | `.agent/skills/<skill>/` |
|
||||
| Devin | `.devin/skills/<skill>/` |
|
||||
| Qoder | `.qoder/skills/<skill>/` |
|
||||
| Codebuddy | `.codebuddy/skills/<skill>/` |
|
||||
| Copilot | `.github/skills/<skill>/` |
|
||||
| Droid | `.factory/skills/<skill>/` |
|
||||
| Reasonix | `.reasonix/skills/<skill>/` |
|
||||
| ZCode | `.zcode/skills/<skill>/` |
|
||||
| Trae | `.trae/skills/<skill>/` |
|
||||
| OMP | `.omp/skills/<skill>/` |
|
||||
| Grok | `.grok/skills/<skill>/` |
|
||||
| Snow | `.snow/skills/<skill>/` |
|
||||
|
||||
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))`.
|
||||
Codex, Gemini CLI, Pi and Kimi share the `.agents/skills/` root (the upstream Agent Skills workspace alias). Their collectors are required to emit byte-identical content for every file more than one of them writes there.
|
||||
|
||||
One description, two consumers:
|
||||
|
||||
1. `trellis init` → `configurePlatform(platformId, cwd)` → `writeTemplateMap(cwd, collect<Platform>Templates())`. For 18 of the 21 platforms the registry entry in `configurators/index.ts` is literally `fromTemplates(collect<Platform>Templates)`, which *is* that composition. Claude Code, Codex and ZCode spell out a `configure` of their own, each for work a `Map<path, content>` cannot express (an opt-in `--with-statusline` flag, an intentionally empty `.codex/skills/` directory, a one-shot console notice) — none of them restates the file list.
|
||||
2. `trellis update` → `collectPlatformTemplates(platformId)` (in `configurators/index.ts`) → the same map, used to detect drift and to populate `.trellis/.template-hashes.json`.
|
||||
|
||||
Because both consumers read the one description, init and update cannot disagree about which files a bundled skill produces.
|
||||
|
||||
## Dispatch Wiring (Code Path)
|
||||
|
||||
@@ -67,10 +79,10 @@ The mechanism that auto-dispatches bundled skills to platform skill roots lives
|
||||
|
||||
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.
|
||||
- `collectSkillTemplates(skillsRoot, workflowSkills, bundledSkills)` returns workflow skills and bundled skill files together as a `Map<filePath, content>` rooted at `skillsRoot`.
|
||||
- `writeTemplateMap(cwd, files)` is the single writer that puts a collected map on disk.
|
||||
|
||||
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.
|
||||
Every platform that supports skills reaches those two helpers from its own `collect<Platform>Templates()` — either directly (`claude.ts`, `codex.ts`, `copilot.ts`, `gemini.ts`, `grok.ts`, `kimi.ts`, `kiro.ts`, `omp.ts`, `opencode.ts`, `pi.ts`, `reasonix.ts`, `snow.ts`, `zcode.ts`) or through `collectBothTemplates(ctx, cmdPath, skillRoot)` in `shared.ts`, which makes the same two calls on behalf of platforms that have both a commands directory and a skills root (`antigravity.ts`, `codebuddy.ts`, `cursor.ts`, `devin.ts`, `droid.ts`, `kilo.ts`, `qoder.ts`, `trae.ts`).
|
||||
|
||||
## Adding a New Bundled Skill
|
||||
|
||||
@@ -137,7 +149,7 @@ There is no per-project opt-out flag for bundled skills. Two options:
|
||||
|
||||
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.
|
||||
A third option — globally disabling all bundled skills — is not supported. The dispatch is unconditional: `collect<Platform>Templates()` takes no arguments, so there is nowhere for a flag to enter. Adding one would mean changing that signature across all 21 platforms plus `collectPlatformTemplates` in `configurators/index.ts`.
|
||||
|
||||
## Operating Rules
|
||||
|
||||
|
||||
@@ -47,7 +47,7 @@ In both modes, JSONL files in the task directory are the manifest for spec/resea
|
||||
{"file": ".trellis/spec/backend/index.md", "reason": "Backend rules"}
|
||||
```
|
||||
|
||||
Readers should skip seed rows without a `file` field. When configuring JSONL, the AI should include only spec/research files, not pre-register code files that will be modified.
|
||||
Readers should skip rows without a `file` field (e.g. legacy `_example` placeholders). When configuring JSONL, the AI should include only spec/research files, not pre-register code files that will be modified.
|
||||
|
||||
## Active Task And Context Key
|
||||
|
||||
|
||||
@@ -59,7 +59,7 @@ Use child tasks for deliverables that can move through planning, implementation,
|
||||
Create new children with:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py create "<child title>" --slug <child-slug> --parent <parent-dir>
|
||||
python3 ./.trellis/scripts/task.py create "<child title>" --description "<one-line summary>" --slug <child-slug> --parent <parent-dir>
|
||||
```
|
||||
|
||||
Link or unlink existing tasks with:
|
||||
@@ -101,12 +101,12 @@ Rules:
|
||||
- Include spec and research files.
|
||||
- Do not include code files that are about to be modified.
|
||||
- Do not treat temporary conclusions in chat as the only context.
|
||||
- Seed rows have no `file` field; they only prompt the AI to fill in real entries.
|
||||
- Rows without a `file` field are skipped by readers. Legacy `{"_example": ...}` placeholder rows are rejected by `task.py validate` — delete them.
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py create "<title>" --slug <slug>
|
||||
python3 ./.trellis/scripts/task.py create "<title>" --description "<one-line summary>" --slug <slug>
|
||||
python3 ./.trellis/scripts/task.py start <task>
|
||||
python3 ./.trellis/scripts/task.py current --source
|
||||
python3 ./.trellis/scripts/task.py add-context <task> implement <file> <reason>
|
||||
|
||||
@@ -34,7 +34,7 @@ Agent files should not become generic chat prompts. They should define input sou
|
||||
| Pi Agent | `.pi/agents/trellis-*.md` |
|
||||
| Reasonix | `.reasonix/skills/trellis-*/SKILL.md` (subagent frontmatter) |
|
||||
| ZCode | `.zcode/agents/trellis-*.md` |
|
||||
| Kimi Code | `.kimi-code/skills/trellis-*/SKILL.md` (agent prompts as skills, dispatched to the built-in `coder`; research needs its file-editing tools to persist findings) |
|
||||
| Kimi Code | `.kimi-code/agents/trellis-*.md` (custom sub-agents; the same prompts also ship as `.kimi-code/skills/trellis-*/SKILL.md`) |
|
||||
|
||||
GitHub Copilot agent/prompt support is provided by a combination of directories such as `.github/agents/`, `.github/prompts/`, and `.github/skills/`; inspect the files actually generated in the user project.
|
||||
|
||||
|
||||
@@ -29,7 +29,7 @@ Common files:
|
||||
| Pi Agent | `.pi/settings.json`, `.pi/extensions/trellis/` |
|
||||
| Trae IDE | `.trae/hooks.json` |
|
||||
|
||||
Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills with the same prelude.
|
||||
Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills and `.kimi-code/agents/` sub-agent definitions with the same prelude.
|
||||
|
||||
Whether these files exist in a project depends on which `trellis init --<platform>` flags the user ran.
|
||||
|
||||
|
||||
@@ -19,12 +19,13 @@ This page lists common Trellis file locations in a user project by platform. Whe
|
||||
| CodeBuddy | `--codebuddy` | `.codebuddy/` | `.codebuddy/skills/` | `.codebuddy/agents/` | `.codebuddy/hooks/` + `.codebuddy/settings.json` |
|
||||
| GitHub Copilot | `--copilot` | `.github/` | `.github/skills/` | `.github/agents/` | `.github/copilot/hooks/` + prompts |
|
||||
| Factory Droid | `--droid` | `.factory/` | `.factory/skills/` | `.factory/droids/` | `.factory/hooks/` + settings |
|
||||
| DeepSeek Harness (dsh) | `--dsh` | `.dsh/` | `.agents/skills/` (shared) + `.dsh/skills/` (entry skills) | None (workflow skills run implement/check inline) | None (class-2 pull-based; no project hooks/settings) |
|
||||
| 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) |
|
||||
| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | `.kimi-code/agents/` (custom sub-agents; same prompts also ship as skills) | None (pull-based prelude; no project hooks/settings) |
|
||||
| Snow CLI | `--snow` | `.snow/` | `.snow/skills/` | `.snow/agents/` (auto-discovered; primary path) | class-1: auto inject + project agents + `beforeSubAgentStart` (`.snow/hooks/` `session`/`user`/`subagent` modes -> `additionalContext` JSON); no legacy sub-agent JSON; commands `.snow/commands/trellis-*.json` |
|
||||
|
||||
## Capability Groups
|
||||
@@ -48,7 +49,7 @@ These platforms usually have `trellis-research`, `trellis-implement`, and `trell
|
||||
- Reasonix (delivered as skills with `runAs: subagent` under `.reasonix/skills/`, not as a separate `agents/` directory)
|
||||
- ZCode
|
||||
- Grok Build (`.grok/agents/`; dispatch via `spawn_subagent` with `subagent_type`)
|
||||
- Kimi Code (delivered as skills under `.kimi-code/skills/`; dispatched to the built-in `coder`, including research because it must persist files)
|
||||
- Kimi Code (`.kimi-code/agents/`; the same prompts are also delivered as skills under `.kimi-code/skills/`)
|
||||
- Snow CLI (`.snow/agents/`; auto-discovered project agents + class-1 hooks)
|
||||
|
||||
When changing implementation/check/research behavior, look for the corresponding platform agent files first.
|
||||
@@ -73,7 +74,7 @@ When changing behavior, inspect workflows and skills first. Do not assume Trelli
|
||||
|
||||
### Shared `.agents/skills/`
|
||||
|
||||
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/`.
|
||||
Codex, Gemini CLI, Pi Agent, Kimi Code, and DeepSeek Harness (dsh) 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
|
||||
|
||||
|
||||
@@ -1,64 +1,14 @@
|
||||
---
|
||||
name: trellis-start
|
||||
description: "Initializes an AI development session by reading workflow guides, developer identity, git status, active tasks, and project guidelines from .trellis/. Classifies incoming tasks and routes to brainstorm, direct edit, or task workflow. Use when beginning a new coding session, resuming work, starting a new task, or re-establishing project context."
|
||||
description: "Initialize or resume non-trivial work in this Trellis project. Skip pure consultation and small isolated edits unless task tracking is requested."
|
||||
---
|
||||
|
||||
# Start Session
|
||||
|
||||
Initialize a Trellis-managed development session. This platform has no session-start hook, so manually load the equivalent compact context by following these steps.
|
||||
1. Classify the request before loading context. Pure consultation and small isolated edits do not need a task or a task-creation question. Preserve risk boundaries in AGENTS.md.
|
||||
2. For tracked work, obtain current task and status from already supplied context, or run get_context.py when missing or stale. Do not enumerate unrelated journals and historical tasks.
|
||||
3. Read the workflow Phase Index and current step on demand. Read the current PRD, then design and implementation notes if needed. Reuse unchanged material already loaded in this session.
|
||||
4. With no task, obtain task-creation consent for non-trivial work unless already authorized. With a planning task, complete missing decisions; once its plan is approved, start and execute without asking again. An existing PRD alone is not proof of approval.
|
||||
5. For implementation load trellis-before-dev; for verification load trellis-check. Load spec indexes only for affected layers and follow relevant links, not every guideline.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Current state
|
||||
Identity, git status, current task, active tasks, journal location.
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py
|
||||
```
|
||||
|
||||
If this output includes a line beginning `Trellis update available:`, copy the full line verbatim when summarizing session context. Do not shorten operational command hints.
|
||||
|
||||
## Step 2: Workflow overview
|
||||
Compact Phase Index, request triage rules, planning artifact contract, and the step-detail command.
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode phase
|
||||
```
|
||||
|
||||
Full guide in `.trellis/workflow.md` (read on demand).
|
||||
|
||||
## Step 3: Guideline indexes
|
||||
Discover packages + spec layers, then read each relevant index file.
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode packages
|
||||
cat .trellis/spec/guides/index.md
|
||||
cat .trellis/spec/<package>/<layer>/index.md # for each relevant layer
|
||||
```
|
||||
|
||||
Index files list the specific guideline docs to read when you actually start coding.
|
||||
|
||||
## Step 4: Decide next action
|
||||
From Step 1 you know the current task and status. Check the task directory:
|
||||
|
||||
- **Active task status `planning` + no `prd.md`** → Phase 1.1. Load the `trellis-brainstorm` skill.
|
||||
- **Active task status `planning` + `prd.md` exists** → stay in Phase 1. Lightweight tasks can be PRD-only; complex tasks need `design.md` + `implement.md`. Load the relevant Phase 1 step detail before `task.py start`.
|
||||
- **Active task status `in_progress`** → Phase 2 step 2.1. Load the step detail:
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode phase --step 2.1 --platform codex
|
||||
```
|
||||
- **No active task** → classify first. For simple conversation / small task, ask only whether this turn should create a Trellis task. For complex work, ask whether you may create a Trellis task and enter planning. If the user says no, skip Trellis for this session.
|
||||
|
||||
---
|
||||
|
||||
## Skill routing (quick reference)
|
||||
|
||||
| User intent | Skill |
|
||||
|---|---|
|
||||
| New feature / unclear requirements | `trellis-brainstorm` |
|
||||
| About to write code | `trellis-before-dev` |
|
||||
| Done coding / quality check | `trellis-check` |
|
||||
| Stuck / fixed same bug multiple times | `trellis-break-loop` |
|
||||
| Learned something worth capturing | `trellis-update-spec` |
|
||||
|
||||
Full rules + anti-rationalization table in `.trellis/workflow.md`.
|
||||
The project workflow and task status are authoritative over legacy user-level Trellis skills. Missing optional tools require a supported fallback or a precise limitation report, not repeated permission requests.
|
||||
|
||||
在新工单中引用
屏蔽一个用户