sakibcc/obsidian-vault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add documentation for the three-stage development workflow and CLI management strategy; create a new notes file for additional insights.

Browse Source
This commit is contained in:
yuxuanhui
2026-08-03 16:17:16 +08:00
parent 91861565bb
commit 6e0c5c35fc
14 changed files with 3122 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AI-RD-Workflow/40-workflows/trellis-matt/EN/workflow.md
+27 -21
View File
@@ -28,7 +28,7 @@ At project level, this setup overrides `.trellis/workflow.md` and adds `.codex/a
- Global `AGENTS.md` and this document jointly own task routing. Trellis bundled skills must not override either one.
- Use `trellis-start` only to load context, phase, and spec indexes. Ignore its legacy task-consent and fixed skill routing.
- Do not call `trellis-brainstorm` or the native `trellis-implement`. Planning uses `grill-with-docs`; Trellis Phase 2 uses `trellis-matt-implement` to execute the Matt implementation contract adapted by this workflow.
- Do not call `trellis-brainstorm` or the native `trellis-implement`. Normal planning uses `grill-with-docs`; a Feishu-bound task first checks its approved-source snapshot and uses `grill-with-docs` only for decision-bearing deltas. Trellis Phase 2 uses `trellis-matt-implement` to execute the Matt implementation contract adapted by this workflow.
- Do not depend on the legacy route table in `trellis-continue`. Use this document's `Active Task Routing`.
- Do not call the legacy commit-first flow in `trellis-finish-work`. Run the `--no-commit` commands in section 3.5 directly.
- Even if a Codex hook's `<codex-mode>` banner shows Trellis sub-agent defaults, the explicit planning and implementation method selected here takes precedence. Never dispatch the native `trellis-implement`.
@@ -95,7 +95,7 @@ When the boundary is uncertain, prefer Matt in a single session first. Upgrade t
The Trellis lifecycle has two fixed substitutions:
- Phase 1 does not use `trellis-brainstorm`. The main session first drafts planning artifacts from evidence, then uses `grill-with-docs` to review and tighten the spec.
- Phase 1 does not use `trellis-brainstorm`. The main session first drafts planning artifacts from evidence. It then reviews and tightens a normal task's spec with `grill-with-docs`; an approved Feishu-bound task verifies its source snapshot and reviews only new deltas.
- Phase 2 does not use the native `trellis-implement`. Dispatch `trellis-matt-implement` to execute the adapted Matt implementation contract from the reviewed artifacts.
For other intents, do not copy a Matt skill list into this file where it can become stale. Route in this order:
@@ -152,6 +152,8 @@ python3 ./.trellis/scripts/task.py list-archive
Do not put detailed technical design or an execution checklist in `prd.md`. `design.md` explains the technical shape and tradeoffs. `implement.md` records ordered steps, verification commands, risks, rollback points, and the current checkpoint.
For a Feishu-bound task, the Wiki Spec/Base Tickets remain authoritative for product requirements, acceptance, identity, and relationships. Trellis `prd.md`/`implement.md` hold a recoverable execution snapshot and task-local planning: record stable record IDs, source update times/Wiki revision when available, the Ticket set, and relationships. They must not silently overwrite the Feishu sources or require a second full approval merely because approved content was copied into Trellis.
Every Trellis implementation task maintains this in `prd.md`:
```markdown
@@ -214,7 +216,7 @@ Phase 3: Finish → verify, evaluate knowledge, optionally use VCS, archive and
| Simple, local, root cause known | Inline; no task |
| Not simple but completable in one session | Select a Matt method from current skill `description` values |
| Explicit `/tdd`, test-first, red-green-refactor, or integration tests | `/tdd`; for Trellis, first record the mode and confirm public seams |
| Trellis planning artifact review | `grill-with-docs`; do not use `trellis-brainstorm` |
| Trellis planning artifact review | Normal task: `grill-with-docs`; Feishu-bound task: snapshot check and `grill-with-docs` only for deltas; do not use `trellis-brainstorm` |
| Trellis reviewed-spec implementation | `trellis-matt-implement`; do not use the native `trellis-implement`; use the main-session Matt fallback when unavailable |
| Diagnosis, review, architecture, or research | Select the narrowest match from current skill `description` values |
| Trellis state, recovery, or archive | This document's phases, `Active Task Routing`, and `.trellis/scripts/` |
@@ -224,7 +226,7 @@ Phase 3: Finish → verify, evaluate knowledge, optionally use VCS, archive and
- 1.0 Create or resume task `[required · once]`
- 1.1 Draft planning artifacts from evidence `[required · repeatable]`
- 1.2 Research / prototype / design inquiry `[optional · repeatable]`
- 1.3 Review spec with `grill-with-docs` `[required · once]`
- 1.3 Review spec or source delta `[required · once]`
- 1.4 Activate or stop at planning boundary `[required · once]`
- 1.5 Planning completion criteria
@@ -237,11 +239,11 @@ Route by `AGENTS.md`; keep simple work inline. Main session is default. Create a
[/workflow-state:no_task-inline]
[workflow-state:planning]
Do not use `trellis-brainstorm`. Draft task artifacts, record `standard|tdd`, confirm public TDD seams when required, review with `grill-with-docs`, then route by the user's original intent.
Do not use `trellis-brainstorm`. Draft task artifacts, record `standard|tdd`, confirm public TDD seams when required, then review the full spec or only the approved-source delta as applicable before routing by the user's original intent.
[/workflow-state:planning]
[workflow-state:planning-inline]
Draft task artifacts, record `standard|tdd`, confirm public TDD seams when required, review with `grill-with-docs`, and sync decisions. Trellis artifacts remain task-level truth.
Draft task artifacts, record `standard|tdd`, confirm public TDD seams when required, and review the full spec or only the approved-source delta as applicable. Feishu-bound artifacts remain execution snapshots; unbound Trellis artifacts remain task-level truth.
[/workflow-state:planning-inline]
### Phase 2 summary
@@ -312,6 +314,7 @@ If one request contains multiple independently verifiable deliverables, first cr
6. If the implementation agent must read specific specs or research, add real entries to `implement.jsonl`; do not register product code. When no extra context is needed, the seed may remain and the agent discovers relevant standards itself.
7. After every important conclusion, immediately update the owning artifact so that it does not live only in the conversation.
8. Do not use `trellis-brainstorm`. Leave open decisions and TDD seams for item-by-item review with `grill-with-docs` in step 1.3.
9. For a Feishu-bound task, record the latest Spec/Ticket record IDs, update times, Wiki revision when available, acceptance, and blocker set as the baseline for later snapshot/delta comparison. Do not treat copied source content as a new Spec.
At minimum, `prd.md` contains: Goal, Background/Evidence, In Scope, Out of Scope, Requirements, Acceptance Criteria, Constraints, Open Decisions, and Testing Strategy.
@@ -331,21 +334,24 @@ Research rules:
Prototype rule: treat prototype code as throwaway from the beginning. Keep the answer, but do not merge the prototype into the product implementation without redesigning it.
#### 1.3 Review spec with `grill-with-docs` `[required · once]`
#### 1.3 Review spec or source delta `[required · once]`
Explicitly load `grill-with-docs` and use it to review `prd.md` plus conditional `design.md` and `implement.md`:
First determine whether the task is bound to an already approved Feishu Spec/Ticket set:
1. Answer factual questions from environmental evidence first. Do not ask the user for facts that can be found in the repository.
2. Grill product, scope, UX, compatibility, risk, acceptance, and key design decisions one by one.
3. Ask one question at a time. Each question includes a recommended answer and the tradeoffs of alternative choices.
4. After each answer is confirmed, immediately synchronize it to the owning Trellis artifact.
5. When `Implementation Mode: tdd`, use the `/tdd` contract to confirm the public interface/seam to observe. Do not write tests or enter Phase 2 before confirmation. Do not ask about TDD seams in `standard` mode.
6. `CONTEXT.md` records only durable domain terminology. An ADR records only a decision that is hard to reverse, counterintuitive, and based on a real tradeoff.
7. Trellis artifacts remain the source of truth for the current task spec. Do not duplicate task details in the glossary or ADRs.
- **Normal task**: explicitly load `grill-with-docs` and review `prd.md` plus conditional `design.md` and `implement.md`.
- **Feishu-bound, snapshot-only**: compare stable IDs, Base update times, Wiki revision when available, the complete Ticket set, parent/blocker relationships, acceptance, and task-local text. If they match and add no decision, record `snapshot-only / No decision-bearing delta`; do not repeat full-text grilling.
- **Feishu-bound, delta-reviewed**: give `grill-with-docs` only the decision-bearing compatibility, migration, rollout/rollback, security, seam, or sequencing text that task-local planning added or changed. Record the confirmed delta and source version.
- **source-revision-required**: if task-local planning changes product behavior, scope, acceptance, Ticket identity, parent, or blocker semantics, stop activation. Revise and approve the owning Wiki Spec/Base Tickets first, then refresh the snapshot.
If `grill-with-docs` cannot be loaded directly on the platform, use the equivalent combination `grilling` + `domain-modeling`.
During review:
This step is complete when the user confirms shared understanding. That confirmation completes the spec review; do not add another Trellis implementation-approval layer.
1. Answer factual questions from environment evidence rather than asking the user.
2. Ask one decision-bearing question at a time and provide a recommended answer plus tradeoffs.
3. Sync each confirmed answer into the owning artifact immediately: product/acceptance decisions go back to Feishu; execution decisions go to Trellis.
4. When `Implementation Mode: tdd`, confirm the public interface/seam according to the `/tdd` contract. Do not write tests or enter Phase 2 before confirmation. `standard` does not ask for a TDD seam.
5. `CONTEXT.md` stores only stable domain vocabulary. ADRs store only decisions that are hard to reverse, surprising, and the result of a real tradeoff.
If `grill-with-docs` cannot be loaded directly on the platform, use the equivalent combination `grilling` + `domain-modeling`. A normal task completes this step at shared understanding; a Feishu-bound task completes it when the snapshot/delta disposition is recorded and no unresolved delta remains. Neither path adds another Trellis implementation approval.
#### 1.4 Activate or stop at planning boundary `[required · once]`
@@ -365,7 +371,7 @@ Start command:
python3 ./.trellis/scripts/task.py start <task-dir>
```
The original implementation request plus the shared-understanding confirmation in step 1.3 constitutes implementation authorization. Do not add another Trellis planning approval.
The original implementation request plus step 1.3 review completion—shared understanding for a normal task, or a valid snapshot/delta disposition for a Feishu-bound task—constitutes implementation authorization. Do not add another Trellis planning approval.
For a planning-only task, the planning artifacts are themselves the deliverable. Once completed and verified, the task may go directly to archive in step 3.5 without being moved to `in_progress` merely for formality.
@@ -381,7 +387,7 @@ For a planning-only task, the planning artifacts are themselves the deliverable.
| Research conclusions have been persisted, if any | ✅ |
| `Testing Strategy` records `standard` or `tdd` | ✅ |
| Public test seams have been confirmed by the user in `tdd` mode | Conditional ✅ |
| `grill-with-docs` review reached shared understanding | ✅ |
| Normal task reached shared understanding; Feishu-bound task has a valid recorded snapshot/delta disposition | ✅ |
| The current action remains within user authorization | ✅ |
## Phase 2: Execute
@@ -540,8 +546,8 @@ When an active task exists, first read `task.json`, its artifacts, and Current C
| --- | --- |
| `planning`, `prd.md` has not converged | 1.1 |
| `planning`, technical unknowns remain | 1.2 |
| `planning`, artifacts have not passed `grill-with-docs` review | 1.3 |
| `planning`, shared understanding has been confirmed | 1.4; start or stop at the planning boundary according to the user's original intent |
| `planning`, normal artifacts are unreviewed, or the Feishu snapshot/delta disposition is missing/stale | 1.3 |
| `planning`, step 1.3 review completion is satisfied | 1.4; start or stop at the planning boundary according to the user's original intent |
| `in_progress`, checkpoint points to unfinished implementation/diagnosis/review | 2.1 |
| `in_progress`, execution is complete but full-scope evidence is missing | 2.2 |
| `in_progress`, acceptance has been verified | 3.3 → conditional 3.4 → 3.5 |