chore: 升级 Trellis 并精简规则（09-05-trellis-upgrade-rule-cleanup）
这个提交包含在：
+39
-27
@@ -78,8 +78,10 @@ python3 ./.trellis/scripts/task.py list [--mine] [--status <s>]
|
||||
python3 ./.trellis/scripts/task.py list-archive
|
||||
|
||||
# Code-spec context (injected into implement/check agents via JSONL).
|
||||
# `implement.jsonl` / `check.jsonl` are seeded on `task create` for sub-agent-capable
|
||||
# platforms; the AI curates real spec + research entries during planning when needed.
|
||||
# `implement.jsonl` / `check.jsonl` are seeded (empty) on `task create` for sub-agent-capable
|
||||
# platforms; the AI curates real spec + research entries during planning. `validate` fails
|
||||
# and `start` refuses empty manifests in sub-agent mode. Explicit Codex inline mode
|
||||
# permits empty manifests; real entries still validate in either mode.
|
||||
python3 ./.trellis/scripts/task.py add-context <name> <action> <file> <reason>
|
||||
python3 ./.trellis/scripts/task.py list-context <name> [action]
|
||||
python3 ./.trellis/scripts/task.py validate <name>
|
||||
@@ -99,7 +101,7 @@ python3 ./.trellis/scripts/task.py create-pr [name] [--dry-run]
|
||||
|
||||
> Run `python3 ./.trellis/scripts/task.py --help` to see the authoritative, up-to-date list.
|
||||
|
||||
**Current-task mechanism**: `task.py create` creates the task directory and (when session identity is available) auto-sets the per-session active-task pointer so the planning breadcrumb fires immediately. `task.py start` writes the same pointer (idempotent if already set) and flips `task.json.status` from `planning` to `in_progress`. State is stored under `.trellis/.runtime/sessions/`. If no context key is available from hook input, `TRELLIS_CONTEXT_ID`, or a platform-native session environment variable, there is no active task and `task.py start` fails with a session identity hint. `task.py finish` deletes the current session file (status unchanged). `task.py archive <task>` writes `status=completed`, moves the directory to `archive/`, and deletes any runtime session files that still point at the archived task.
|
||||
**Current-task mechanism**: `task.py create` creates the task directory and (when session identity is available) auto-sets the per-session active-task pointer so the planning breadcrumb fires immediately. `task.py start` writes the same pointer (idempotent if already set) and flips `task.json.status` from `planning` to `in_progress`. State is stored under `.trellis/.runtime/sessions/`. If no context key is available from hook input, `TRELLIS_CONTEXT_ID`, or a platform-native session environment variable, `task.py start` reports degraded session tracking but still records the task state; retain the task path in context and do not create a replacement task. `task.py finish` deletes the current session file (status unchanged). `task.py archive <task>` writes `status=completed`, moves the directory to `archive/`, and deletes any runtime session files that still point at the archived task.
|
||||
|
||||
### Workspace System
|
||||
|
||||
@@ -145,6 +147,7 @@ python3 ./.trellis/scripts/get_context.py --mode phase --step <X.Y> # detailed
|
||||
|
||||
TAG ↔ PHASE scoping:
|
||||
[workflow-state:no_task] → no active task; before Phase 1
|
||||
[workflow-state:task_error] → active task record is unreadable; repair it before continuing
|
||||
[workflow-state:planning] → all of Phase 1 (status='planning')
|
||||
[workflow-state:planning-inline] → Codex inline variant of Phase 1
|
||||
[workflow-state:in_progress] → Phase 2 + Phase 3.2-3.4
|
||||
@@ -177,7 +180,7 @@ Phase 3: Finish → verify, update spec, commit, and wrap up
|
||||
|
||||
### Request Triage
|
||||
|
||||
- Simple conversation or small task: ask only whether this turn should create a Trellis task. If the user says no, skip Trellis for this session.
|
||||
- Pure consultation and small, isolated edits need no task unless requested. Non-trivial work needs a task and an approved plan; ask for task creation only when not already authorized.
|
||||
- Complex task: ask whether you may create a Trellis task and enter planning. If the user says no, do not do broad inline implementation; explain, clarify scope, or suggest a smaller split.
|
||||
- User approval to create a task is not approval to start implementation. Planning still happens first.
|
||||
|
||||
@@ -201,10 +204,18 @@ Create new children with `task.py create "<title>" --slug <name> --parent <paren
|
||||
|
||||
[workflow-state:no_task]
|
||||
No active task. First classify the current turn and ask for task-creation consent before creating any Trellis task.
|
||||
Simple conversation / small task: ask only whether this turn should create a Trellis task. If the user says no, skip Trellis for this session.
|
||||
Pure consultation or a small isolated edit: respond or execute within scope without asking to create a task.
|
||||
Complex task: ask the user if you can create a Trellis task and enter the planning phase. If the user says no, explain, clarify scope, or suggest a smaller split.
|
||||
[/workflow-state:no_task]
|
||||
|
||||
<!-- Per-turn breadcrumb: shown when the active task record cannot be read. -->
|
||||
|
||||
[workflow-state:task_error]
|
||||
The active task record could not be read. Do not create or activate another task.
|
||||
Inspect the task directory named above and repair its task.json. It must be a valid JSON object with a non-empty status.
|
||||
Preserve existing task fields and artifacts. If the correct status cannot be determined safely, ask the user before reconstructing the record.
|
||||
[/workflow-state:task_error]
|
||||
|
||||
### Phase 1: Plan
|
||||
- 1.0 Create task `[required · once]` (only after task-creation consent)
|
||||
- 1.1 Requirement exploration `[required · repeatable]` (`prd.md`; complex tasks also need `design.md` + `implement.md`)
|
||||
@@ -216,8 +227,8 @@ Complex task: ask the user if you can create a Trellis task and enter the planni
|
||||
<!-- Per-turn breadcrumb: shown throughout Phase 1 (status='planning') -->
|
||||
|
||||
[workflow-state:planning]
|
||||
Load `trellis-brainstorm`; stay in planning.
|
||||
Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and `implement.md`; ask for review before `task.py start`.
|
||||
If the current plan is complete and the user has approved that version, run `task.py start` and continue execution. Otherwise use `trellis-brainstorm` to complete only the missing decisions and artifacts. Do not repeat approval for unchanged scope or clerical backfill.
|
||||
Lightweight: `prd.md` can be enough. Complex: `prd.md`, `design.md`, and `implement.md` must be reviewed before start; an already recorded approval satisfies this gate.
|
||||
Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position.
|
||||
Sub-agent mode: curate `implement.jsonl` and `check.jsonl` as spec/research manifests before start.
|
||||
[/workflow-state:planning]
|
||||
@@ -229,8 +240,8 @@ Sub-agent mode: curate `implement.jsonl` and `check.jsonl` as spec/research mani
|
||||
into a sub-agent. -->
|
||||
|
||||
[workflow-state:planning-inline]
|
||||
Load `trellis-brainstorm`; stay in planning.
|
||||
Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and `implement.md`; ask for review before `task.py start`.
|
||||
If the current plan is complete and the user has approved that version, run `task.py start` and continue execution. Otherwise use `trellis-brainstorm` to complete only the missing decisions and artifacts. Do not repeat approval for unchanged scope or clerical backfill.
|
||||
Lightweight: `prd.md` can be enough. Complex: `prd.md`, `design.md`, and `implement.md` must be reviewed before start; an already recorded approval satisfies this gate.
|
||||
Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position.
|
||||
Inline mode: skip jsonl curation; Phase 2 reads artifacts/specs via `trellis-before-dev`.
|
||||
[/workflow-state:planning-inline]
|
||||
@@ -306,13 +317,13 @@ When a user request matches one of these intents inside an active task, route fi
|
||||
|
||||
[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
|
||||
|
||||
[codex-inline, Kilo, Antigravity, Devin]
|
||||
[codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
|
||||
|
||||
- Planning or unclear requirements -> `trellis-brainstorm`.
|
||||
- Before editing -> `trellis-before-dev`; after editing -> `trellis-check`.
|
||||
- Repeated debugging -> `trellis-break-loop`; spec updates -> `trellis-update-spec`.
|
||||
|
||||
[/codex-inline, Kilo, Antigravity, Devin]
|
||||
[/codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
|
||||
|
||||
### Guardrails
|
||||
|
||||
@@ -347,7 +358,7 @@ python3 ./.trellis/scripts/task.py create "<task title>" --slug <name>
|
||||
|
||||
For task trees, create the parent task first and then create each child with `--parent <parent-dir>`. Do not start the parent just because children exist; start the child that owns the next independently verifiable deliverable.
|
||||
|
||||
After this command succeeds, the per-turn breadcrumb auto-switches to `[workflow-state:planning]`, telling the AI to stay in planning.
|
||||
After creation, the breadcrumb reflects planning. Complete missing artifacts and approval; if the current plan is already approved, start it without repeating confirmation.
|
||||
|
||||
Run only `create` here — do not also run `start`. `start` flips status to `in_progress`, which switches the breadcrumb to the implementation phase before planning artifacts are reviewed. Save `start` for step 1.4.
|
||||
|
||||
@@ -389,11 +400,11 @@ Spawn the research sub-agent:
|
||||
|
||||
[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
|
||||
|
||||
[codex-inline, Kilo, Antigravity, Devin]
|
||||
[codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
|
||||
|
||||
Do the research in the main session directly and write findings into `{TASK_DIR}/research/`. `codex-inline` is the explicit mode that keeps work in the main session.
|
||||
|
||||
[/codex-inline, Kilo, Antigravity, Devin]
|
||||
[/codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
|
||||
|
||||
**Research artifact conventions**:
|
||||
- One file per research topic (e.g. `research/auth-library-comparison.md`)
|
||||
@@ -453,11 +464,11 @@ Skip this step only when both files already have real curated entries.
|
||||
|
||||
[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
|
||||
|
||||
[codex-inline, Kilo, Antigravity, Devin]
|
||||
[codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
|
||||
|
||||
Skip this step. Context is loaded directly by the `trellis-before-dev` skill in Phase 2.
|
||||
|
||||
[/codex-inline, Kilo, Antigravity, Devin]
|
||||
[/codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
|
||||
|
||||
#### 1.4 Activate task `[required · once]`
|
||||
|
||||
@@ -467,11 +478,11 @@ After artifact review, flip the task status to `in_progress`:
|
||||
python3 ./.trellis/scripts/task.py start <task-dir>
|
||||
```
|
||||
|
||||
For lightweight tasks, `prd.md` can be enough. For complex tasks, `prd.md`, `design.md`, and `implement.md` must exist and be reviewed before start. On sub-agent-dispatch platforms, `implement.jsonl` and `check.jsonl` must both have real curated entries before start. Runtime consumers tolerate missing or seed-only manifests for compatibility, but that tolerance is not a planning-ready state.
|
||||
For lightweight tasks, `prd.md` can be enough. For complex tasks, `prd.md`, `design.md`, and `implement.md` must exist and be reviewed before start. On sub-agent-dispatch platforms, `implement.jsonl` and `check.jsonl` must both have real curated entries before start. In this project, explicit Codex inline mode permits empty and legacy seed-only manifests; real entries still validate. Sub-agent mode requires curated entries. Start and validate both read the configured dispatch mode.
|
||||
|
||||
After this command succeeds, the breadcrumb auto-switches to `[workflow-state:in_progress]`, and the rest of Phase 2 / 3 follows.
|
||||
|
||||
If `task.py start` errors with a session-identity message (no context key from hook input, `TRELLIS_CONTEXT_ID`, or platform-native session env), follow the hint in the error to set up session identity, then retry.
|
||||
If session identity is unavailable, inspect the actual command result: 0.6.16 can start in degraded tracking mode. Preserve the explicit task path and report the missing pointer rather than repeatedly restarting.
|
||||
|
||||
#### 1.5 Completion criteria
|
||||
|
||||
@@ -541,15 +552,15 @@ The platform prelude auto-handles the context load requirement:
|
||||
|
||||
[/Kiro]
|
||||
|
||||
[codex-inline, Kilo, Antigravity, Devin]
|
||||
[codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
|
||||
|
||||
1. Load the `trellis-before-dev` skill to read project guidelines
|
||||
2. Read `{TASK_DIR}/prd.md`, then `design.md` if present, then `implement.md` if present
|
||||
3. Consult materials under `{TASK_DIR}/research/`
|
||||
4. Implement the code per reviewed artifacts
|
||||
5. Run project lint and type-check
|
||||
5. Run the checks selected for the current task and affected layers; do not run unrelated business checks for documentation or rule-only work.
|
||||
|
||||
[/codex-inline, Kilo, Antigravity, Devin]
|
||||
[/codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
|
||||
|
||||
#### 2.2 Quality check `[required · repeatable]`
|
||||
|
||||
@@ -569,18 +580,18 @@ The check agent's job:
|
||||
|
||||
[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
|
||||
|
||||
[codex-inline, Kilo, Antigravity, Devin]
|
||||
[codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
|
||||
|
||||
Load the `trellis-check` skill and verify the code per its guidance:
|
||||
- Spec compliance
|
||||
- lint / type-check / tests
|
||||
- Cross-layer consistency (when changes span layers)
|
||||
|
||||
If issues are found → fix → re-check, until green.
|
||||
Fix task-caused issues and rerun affected checks. Report pre-existing or unrelated failures without widening scope; stop retrying when a genuine external prerequisite prevents progress.
|
||||
|
||||
[/codex-inline, Kilo, Antigravity, Devin]
|
||||
[/codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
|
||||
|
||||
**Final pass (before Phase 3.4 commit)**: the last 2.2 of a task must run full-scope, not just on the latest implement chunk. List all affected packages with `python3 ./.trellis/scripts/get_context.py --mode packages`, then load each package's spec index Quality Check section. This catches cross-layer / multi-package issues a mid-iteration local 2.2 cannot.
|
||||
**Final pass**: verify the complete task diff once against its acceptance criteria and affected layers, not every dirty file in the repository. Reuse passing results if their inputs have not changed. Expand checks only for shared contracts, cross-layer behavior or risk identified by the task.
|
||||
|
||||
#### 2.3 Rollback `[on demand]`
|
||||
|
||||
@@ -616,7 +627,7 @@ Update the docs under `.trellis/spec/` accordingly. Even if the conclusion is "n
|
||||
|
||||
**Spec-sync preamble**: before drafting commits, ask: did this task fix a bug or surface non-obvious knowledge that should land in `.trellis/spec/` so future-you (or future-AI) doesn't repeat the mistake? If yes, return to Phase 3.3 first — spec writes belong in the same task's commit batch, not as a forgotten follow-up.
|
||||
|
||||
The AI drives a batched commit of this task's code changes so `/finish-work` can run cleanly afterwards. Goal: produce work commits FIRST, then bookkeeping (archive + journal) commits land after — never interleaved.
|
||||
Only commit when the user explicitly requests it. Otherwise report the verified changes and continue to 3.5 without treating an uncommitted diff as incomplete implementation. Never auto-commit or archive as a side effect of finishing a session.
|
||||
|
||||
**Step-by-step**:
|
||||
|
||||
@@ -666,7 +677,7 @@ The AI drives a batched commit of this task's code changes so `/finish-work` can
|
||||
|
||||
#### 3.5 Wrap-up reminder
|
||||
|
||||
After the above, remind the user they can run `/finish-work` to wrap up (archive the task, record the session).
|
||||
Report implementation, verification, independent-review and deployment status separately. Archive only a genuinely completed task when explicitly requested; a partial stage remains active. Update existing task notes instead of creating duplicate retrospective documents.
|
||||
|
||||
---
|
||||
|
||||
@@ -686,6 +697,7 @@ All tag blocks live in the `## Phase Index` section above, immediately after eac
|
||||
| Scope | Corresponding tag |
|
||||
|---|---|
|
||||
| No active task (before Phase 1) | `[workflow-state:no_task]` (after the Phase Index ASCII art) |
|
||||
| Active task record unreadable | `[workflow-state:task_error]` (repair the existing task before continuing) |
|
||||
| All of Phase 1 (task created → ready for implementation) | `[workflow-state:planning]` (after Phase 1 summary) |
|
||||
| Codex inline Phase 1 | `[workflow-state:planning-inline]` |
|
||||
| Phase 2 + Phase 3.2–3.4 (implementation + check + wrap-up) | `[workflow-state:in_progress]` (after Phase 2 summary) |
|
||||
|
||||
在新工单中引用
屏蔽一个用户