# Yuxuanhui Development Workflow

> Scope: projects where `.trellis/` has already been initialized.
>
> Design baseline: Trellis 0.6.8. This document can be used as a lightweight, single-file override for the project's `.trellis/workflow.md`.
>
> Customization contract reference: [Trellis official “Custom Workflow” documentation](https://docs.trytrellis.app/zh/advanced/custom-workflow).

## 0. Workflow Contract

### Instruction precedence

Higher-level instructions, the project `AGENTS.md`, and the user's current explicit request always take precedence. When a conflict occurs, do not use this workflow or a skill to expand the user's authorization.

### Three operating modes

| Mode           | Owner                                                   | Use when                                                                    | Persistence                                         |
| -------------- | ------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------- |
| Inline         | Main session                                            | Simple, local, root cause known, and completable in one context              | No Trellis task                                     |
| Matt           | The currently matched engineering skill; otherwise the main session | Engineering work that is not simple but can still be completed in one session | Use existing project artifacts; no task is required |
| Trellis + Matt | Trellis owns the lifecycle; the currently matched Matt skill owns the engineering method | Multiple sessions, several durable decisions, multiple deliverables, or explicit persistence | Task, planning artifacts, research, checkpoint, archive |

Trellis is the control plane and does not replace the engineering method. Matt is the method layer and does not own task state. Select exactly one workflow owner for each phase; do not stack multiple complete workflows. Trellis context loading, state writes, and archive actions do not count as a second method owner.

### Lightweight override policy

At project level, this setup overrides `.trellis/workflow.md` and adds `.codex/agents/trellis-matt-implement.toml`; the companion `AGENTS.md` may live globally or in the project. It does not require changes to `.trellis/config.yaml`, Codex hooks, or Trellis bundled skills. To prevent legacy entry points from taking control again, apply these override rules:

- 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`. 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`.
- `trellis-matt-implement` is the Phase 2 execution role explicitly selected by this workflow; dispatch only one by default. Each implementation slice has exactly one method owner: either the `standard` Matt contract or explicit `/tdd`. Enable other sub-agents only when the user explicitly requests them or the currently selected Matt skill explicitly requires parallel work.

### Core principles

1. **Evidence before inference** — Rely on the current machine, repository, task files, diff, and actual command output.
2. **Minimum sufficient work** — Complete the smallest sufficient scope requested by the user. Do not expand scope or overwrite existing user changes.
3. **Persist only when useful** — Keep simple work in the session. Write only cross-session state, durable decisions, and reusable evidence to Trellis.
4. **One lifecycle owner, one method owner** — Trellis manages state; each phase selects exactly one engineering method.
5. **Verification before completion claims** — Without direct verification evidence, do not claim that work is complete, passing, ready to commit, or ready to merge.
6. **No implicit external effects** — Confirm before external writes, sending, publishing, destructive actions, paid actions, permission changes, or material scope expansion.
7. **No implicit promotion or version control** — Spec promotion, commit, push, and PR are never default finishing actions.

## 1. Request Routing

### Step A: Determine the user's authorized intent

| User intent | Default boundary |
| --- | --- |
| Answer, explain, analyze, diagnose, review, or plan | Inspect in read-only mode and report; do not modify product code or external state |
| Modify, implement, build, or fix | Complete in-scope local changes and non-destructive verification; do not ask again for implementation approval |
| External-system write, publish, destructive action, paid action, permission change, or material scope expansion | Confirm before execution |
| Spec promotion | Perform only when the knowledge is durable, reusable, verified, and confirmed by the user |
| Commit, push, or PR | Perform only when explicitly requested; authorization for one does not imply authorization for another |

When a read-only request enters Trellis, the task's own planning, research, and checkpoint artifacts may be written, but “record the analysis” must not be interpreted as “permission to fix the code.” A review-only request reports issues even when it finds them. Modify code only when the user also asks for a fix.

### Step B: Choose the lifecycle mode

#### Inline

Handle the work directly without creating a task when all relevant conditions are satisfied:

- A question, explanation, or code-reading task that can be completed in one turn;
- A local configuration, copy, or single-file change;
- A small fix with a known root cause;
- A narrow impact with no design decision that needs long-term persistence;
- Minimum verification that can be completed in the current context.

#### Matt without Trellis

When the task is not Inline but can still be completed in one healthy context and does not need several decisions to persist:

- Select the narrowest, most precise method from currently available skill `description` values;
- Complete it in the main session unless the selected skill explicitly requires parallel agents;
- Do not create a Trellis task merely to make the work appear formal.

#### Trellis + Matt

Enter the Trellis lifecycle when any of the following applies:

- The user explicitly asks for Trellis, durable records, or cross-session recovery;
- The work is likely to span sessions or require handoff;
- Two or more durable decisions will affect later implementation;
- One request contains multiple independently verifiable deliverables;
- Research, compatibility/migration plans, rollout/rollback plans, or important risks must persist;
- An active task already matches the request.

When the boundary is uncertain, prefer Matt in a single session first. Upgrade to Trellis only when the work actually develops cross-session needs, independent deliverables, or durable decisions. On upgrade, record confirmed facts, decisions, remaining work, and verification evidence in the task, then continue without repeating completed work.

### Method selection details

The Trellis lifecycle has two fixed substitutions:

- 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:

1. Prefer a currently available skill explicitly named by the user.
2. Select `/tdd` when the user requests `/tdd`, test-first, red-green-refactor, or integration tests. A Trellis task must first persist `Implementation Mode: tdd` and confirm its public test seams.
3. Otherwise, scan the `description` of current skills and match the actual intent of the current phase, such as requirements interrogation, spec/issue work, implementation, diagnosis, review, architecture, or research.
4. If several skills match, select the narrowest one whose output best fits the current phase.
5. Mandatory gates of the selected skill remain in force. If it explicitly requires parallel agents, sub-agents are permitted for that phase.
6. If there is no exact match, the main session uses the standard loop: evidence → decision/plan → execution → verification.
7. Do not call an unavailable or mismatched skill merely because it historically belonged to a Matt primary workflow.

`grill-with-docs` is currently an explicit-invocation skill. `trellis-matt-implement` is the Codex custom execution role selected by this workflow and does not call a Matt `/implement` wrapper inside the sub-agent. It follows the mode recorded in planning artifacts and never infers TDD:

- `standard` is the default method: complete a stable implementation increment, then run narrow checks and add tests as needed;
- `tdd` is used only after a user trigger and confirmation of public seams: the sub-agent explicitly loads `/tdd` and works in vertical red → green slices.

When the corresponding capability is unavailable:

- The `grill-with-docs` fallback is `grilling` + `domain-modeling`;
- The `trellis-matt-implement` fallback is the main session following the recorded mode: the Matt contract overridden by this workflow for `standard`, or an explicitly loaded `/tdd` for `tdd`. Neither mode performs implicit Git writes.

## 2. Trellis System

### Task lifecycle

```bash
python3 ./.trellis/scripts/task.py create "<title>" --slug <name>
python3 ./.trellis/scripts/task.py start <task-dir>
python3 ./.trellis/scripts/task.py current --source
python3 ./.trellis/scripts/task.py finish
python3 ./.trellis/scripts/task.py archive <task-dir> --no-commit
python3 ./.trellis/scripts/task.py list [--mine] [--status <status>]
python3 ./.trellis/scripts/task.py list-archive
```

- `create` creates a task with `status=planning`. If a session identifier is available, it sets the session-scoped active task.
- `start` changes the task to `in_progress`. It only indicates entry into the execution phase and does not expand user authorization.
- `finish` only clears the current session pointer. It does not change task status or mean that the task is complete.
- `archive --no-commit` writes `status=completed`, moves the task, and clears related session pointers without touching Git.
- Always pass `--no-commit` explicitly to archive and journal commands, so changing the `session_auto_commit` default is unnecessary.
- Treat `python3 ./.trellis/scripts/task.py --help` as the source of truth for CLI commands. Do not use subcommands absent from the actual help output.

### Planning artifacts

| Artifact | Rule |
| --- | --- |
| `prd.md` | Required for every Trellis task; records goals, facts, scope, constraints, acceptance criteria, open decisions, and implementation mode / TDD seams under `Testing Strategy` |
| `design.md` | Required for cross-module work, contracts, compatibility, migration, security, rollout/rollback, or important technical tradeoffs |
| `implement.md` | Required for multi-step, cross-session, or higher-risk work, or when the verification sequence must be explicit |
| `research/*.md` | Store only research that affects decisions and must persist across sessions; one question per file, with sources and conclusions |
| `implement.jsonl` | Optional context manifest for `trellis-matt-implement`; read real spec/research entries first, while a seed-only manifest allows the agent to discover relevant standards itself |
| `check.jsonl` | This workflow does not use the native Trellis check sub-agent; keep the generated seed as-is without maintaining it |

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
## Testing Strategy

- Implementation Mode: standard | tdd
- Confirmed TDD Seams: Not applicable | <confirmed public seams>
```

`standard` is the default. Write `tdd` only when the user explicitly requests `/tdd`, test-first, red-green-refactor, or integration tests, or when the reviewed spec explicitly requires TDD. TDD execution cannot begin without at least one confirmed seam.

Every cross-session task must maintain a short checkpoint in `implement.md`:

```markdown
## Current Checkpoint

- Last completed:
- Evidence:
- Next:
- Blockers:
```

The checkpoint records only the state needed for recovery, not a recap of the conversation.

### Parent / child tasks

Create a child task only when its deliverable can be planned, implemented, checked, and archived independently. Prefer narrow but complete vertical slices. A split by technical layer alone usually does not justify a child task.

```bash
python3 ./.trellis/scripts/task.py create "<child title>" --slug <child> --parent <parent-dir>
python3 ./.trellis/scripts/task.py add-subtask <parent> <child>
python3 ./.trellis/scripts/task.py remove-subtask <parent> <child>
```

Parent-child relationships are not a dependency graph. Write blocking order explicitly in the child's `prd.md` or `implement.md`. The parent task owns source requirements, the task map, cross-child acceptance, and final integration. Activate next only the child that owns a real deliverable.

## Phase Index

```text
Route:   Inline | Matt | Trellis + Matt
Phase 1: Plan    → persist evidence, decisions, acceptance and execution shape
Phase 2: Execute → perform only the actions authorized by the user's intent
Phase 3: Finish  → verify, evaluate knowledge, optionally use VCS, archive and report
```

### Request triage

- When there is no active task, classify silently first. Do not ask process-only questions such as whether to create a Trellis task.
- Start Inline and single-session Matt work directly.
- When Trellis conditions are met, create the task automatically. An explicit user request to implement or fix already authorizes in-scope local implementation; do not ask again after planning.
- When the user asks only for planning, review, or diagnosis, creating a task does not grant permission to modify product code.
- If a product, scope, compatibility, risk, or acceptance decision still belongs to the user, ask only the single highest-value question and wait for the answer.
- Respect an explicit request not to create a task. If the scope is no longer suitable for one session, narrow the deliverable or explain the risk of unreliable persistence.
- If the project has no `.trellis/`, do not initialize it unless the user explicitly asks for durable records or initialization.

### Skill Routing

| User intent / phase | Route |
| --- | --- |
| 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 | 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/` |

### Phase 1 summary

- 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 or source delta `[required · once]`
- 1.4 Activate or stop at planning boundary `[required · once]`
- 1.5 Planning completion criteria

[workflow-state:no_task]
Route by `AGENTS.md`: Inline for simple work, Matt for single-session engineering, Trellis only for durable work. Do not ask task-consent questions.
[/workflow-state:no_task]

[workflow-state:no_task-inline]
Route by `AGENTS.md`; keep simple work inline. Main session is default. Create a task only for durable work; do not ask task-consent questions.
[/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, 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, 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

- 2.1 Implement with `trellis-matt-implement` `[required · repeatable]`
- 2.2 Quality and acceptance check `[required · repeatable]`
- 2.3 Roll back to the right phase `[on demand]`

[workflow-state:in_progress]
Never dispatch the native `trellis-implement`. Dispatch one `trellis-matt-implement` with `Active task`, the recorded implementation mode, and confirmed TDD seams. After it returns, verify the full diff and update the checkpoint. Commit remains user-requested only.
[/workflow-state:in_progress]

[workflow-state:in_progress-inline]
Main session follows the recorded mode: the adapted Matt contract for `standard`, `/tdd` for `tdd`. Dispatch neither the native `trellis-implement` nor `trellis-matt-implement`. Commit only when explicitly requested.
[/workflow-state:in_progress-inline]

### Phase 3 summary

- 3.2 Debug retrospective `[on demand]`
- 3.3 Knowledge promotion decision `[required · once]`
- 3.4 Version-control actions `[on explicit request]`
- 3.5 Archive, journal and report `[required · once]`

[workflow-state:completed]
Archive and journal with `--no-commit`, then report outcome, verification and remaining risk. Never infer commit, push, PR or spec-promotion permission.
[/workflow-state:completed]

### Phase rules

1. Identify the user's authorization boundary first, then the lifecycle mode and current phase.
2. Run required steps in order within a phase. Do not recreate artifacts that already exist and remain valid.
3. If new evidence invalidates a requirement or design, return to Phase 1. Update the owning artifact before continuing.
4. Each phase has one engineering-method owner. Another skill may run as a substep only when the current owner explicitly delegates to it.
5. When a session approaches the context-quality boundary, update the task checkpoint before switching sessions. Do not continue by relying on a vague summary.
6. When work upgrades from Inline/Matt to Trellis midstream, preserve existing evidence and results. Do not repeat completed steps.

## Phase 1: Plan

Goal: turn durable work into a recoverable, testable task without creating duplicate approval gates.

#### 1.0 Create or resume task `[required · once]`

Check the current task first:

```bash
python3 ./.trellis/scripts/task.py current --source
```

- If the active task matches the request, read it and continue without creating another.
- If the request does not meet Trellis conditions, leave the Trellis path and use Inline or Matt.
- If the request meets Trellis conditions, create the task directly without asking for process consent.

```bash
python3 ./.trellis/scripts/task.py create "<short title>" --slug <name>
```

Run only `create` here. Do not immediately and unconditionally run `start`. First record the user's original intent, evidence, and required planning artifacts clearly.

If one request contains multiple independently verifiable deliverables, first create a parent/child map. Do not split into child tasks merely because the work spans several files or layers; split only when a deliverable can be accepted independently.

#### 1.1 Draft planning artifacts from evidence `[required · repeatable]`

1. Read existing code, tests, configuration, documentation, specs, historical tasks, and Git state.
2. Investigate questions the repository can answer directly instead of asking the user for facts.
3. Distinguish confirmed facts, user intent, scope/risk decisions, technical unknowns, and explicit out-of-scope items.
4. The main session first drafts `prd.md`, plus `design.md` and `implement.md` when their conditions apply.
5. Record the mode under `Testing Strategy` in `prd.md`. Default to `standard`; record `tdd` when the user requests `/tdd`, test-first, red-green-refactor, or integration tests, or when the reviewed spec explicitly requires TDD, and list candidate public seams for confirmation.
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.

Before finishing, perform one convergence pass: remove duplicate facts and resolved questions while preserving every evidence anchor, constraint, decision, and acceptance mapping.

#### 1.2 Research / prototype / design inquiry `[optional · repeatable]`

Research only when the repository cannot directly answer a technical fact. Prototype only when a state model, business rule, or UI must be run or observed to make a decision. Choose the corresponding design method when the interface, seam, domain vocabulary, or architectural shape is itself the question.

Research rules:

- Prefer official documentation, standards, source code, and first-party APIs;
- Use the current-documentation tool required by the project `AGENTS.md`;
- For a Trellis task, write conclusions that affect implementation to `{TASK_DIR}/research/<topic>.md`;
- Record sources, version/date, conclusions, scope of applicability, and unresolved risks;
- Research supplies evidence; it does not make product decisions on behalf of the user.

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 or source delta `[required · once]`

First determine whether the task is bound to an already approved Feishu Spec/Ticket set:

- **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.

During review:

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]`

Apply the authorization matrix:

| Situation | Action |
| --- | --- |
| The user explicitly requested implement/build/fix/change; artifacts are ready; no user decision remains open | Run `task.py start` and enter Phase 2 without asking again |
| The user requested only plan/spec/review/diagnose | Stop at the authorization boundary; deliver the requested artifact or continue read-only execution without modifying product code |
| The selected skill has an explicit human gate | Follow that gate |
| The action involves external writes, destructive actions, payment, permissions, or material scope expansion | Confirm that action first |
| The artifacts materially changed scope and the original authorization no longer covers it | Request direction first |

Start command:

```bash
python3 ./.trellis/scripts/task.py start <task-dir>
```

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.

#### 1.5 Planning completion criteria

| Condition | Required |
| --- | :---: |
| `prd.md` contains observable acceptance criteria | ✅ |
| Repository-answerable facts have evidence | ✅ |
| No blocking user decision remains | ✅ |
| `design.md` exists when its conditions apply | ✅ |
| `implement.md` exists with a checkpoint when its conditions apply | ✅ |
| 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 ✅ |
| 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

Goal: complete the authorized work through one explicit method and leave auditable evidence.

#### 2.1 Implement with `trellis-matt-implement` `[required · repeatable]`

Before execution:

1. Read `prd.md`, conditional `design.md` / `implement.md`, and relevant research.
2. Run package/spec discovery and read the pre-development checklist and concrete standards for the affected area.
3. Check `git status` and distinguish task changes, existing user changes, and unrelated parallel work.
4. If the current project contains `.codegraph/` and the task involves cross-file changes, refactoring, impact analysis, or call-chain investigation, prefer CodeGraph as required by project `AGENTS.md`.
5. Read `Testing Strategy` and accept only `standard` or `tdd`. If `tdd` has no confirmed seam, return to step 1.3; never select or infer TDD in Phase 2.
6. Use `task.py current --source` to obtain the exact task path for the current session and confirm that the task matches the request and has `in_progress` status.
7. Dispatch one `trellis-matt-implement`; never dispatch the native `trellis-implement`. The prompt must include the exact task path, mode, and seams:

```text
Active task: <task-path>
Implementation mode: <standard | tdd>
Confirmed TDD seams:
- <public seam, or Not applicable>
Implement only <delegated slice> from the reviewed task artifacts.
Do not change task state, dispatch another agent, or perform Git writes.
```

Agent contract:

- `trellis-matt-implement` is the execution role and does not call a Matt `/implement` wrapper inside the sub-agent; each slice selects exactly one implementation method;
- Read context in this order: real `implement.jsonl` entries → `prd.md` → conditional `design.md` → conditional `implement.md` → relevant project standards;
- Treat the reviewed Trellis artifacts as the spec/tickets and make only the minimum sufficient implementation for the delegated slice;
- Do not overwrite, revert, or commit the user's existing changes;
- Follow project comment conventions for public functions, classes, and complex logic, explaining design rationale and critical boundaries;
- `standard`: do not use TDD/test-first; complete a stable implementation increment before narrow checks, then add acceptance/regression tests as needed after the behavior exists;
- `tdd`: explicitly load `/tdd` and work only at confirmed public seams in vertical slices of one failing behavioral test → minimum green implementation; if the skill is unavailable or a seam is missing, return `blocked` without silently degrading;
- Do not perform unrelated refactoring inside the TDD red → green loop; return candidates to the main session for review in step 2.2;
- In both modes, run all applicable full-scope verification at the end of the slice;
- Do not change task state, requirements, scope, or acceptance criteria; perform Git writes; or dispatch another agent;
- Self-review the complete delegated slice and return the implementation mode, confirmed seams, changed files, acceptance mapping, actual verification results, and remaining risks.

After the agent returns, the main session must inspect its report and the complete diff, then synchronize completed steps, verification evidence, next action, and blockers to the `implement.md` Current Checkpoint before entering step 2.2. A diagnosis-only or review-only task must not dispatch the implementation agent or modify product code as a convenience.

If the custom agent is unavailable, cannot obtain task context reliably, or the platform does not support custom sub-agents, the main session follows the recorded mode: use the adapted Matt fallback for `standard`, or explicitly load `/tdd` for `tdd`. Dispatch only one implementation agent by default; parallel execution is allowed only for independent child tasks or completely disjoint write scopes. Any commit still requires an explicit user request before entering step 3.4.

#### 2.2 Quality and acceptance check `[required · repeatable]`

The checking behavior depends on user intent:

- Implementation/fix task: fix in-scope issues found by checks, then rerun verification.
- Review-only: report findings without modifying code.
- Diagnosis-only: report the root cause, evidence, and recommendation without implementing a fix.

Every pass checks at least:

1. A mapping from the diff to each `prd.md` acceptance criterion;
2. Applicable `.trellis/spec/` and project standards;
3. Real acceptance commands for the affected area, such as lint, type-check, tests, build, or other checks;
4. Cross-layer data flow, types, error propagation, compatibility, and regression impact when applicable;
5. Checks not run and the reason.

The final pass must cover the entire task diff, not only the last patch. Record commands, exit results, and key output. When a tool was not actually run, record only `not run` or `blocked`, never `passed`.

When implementation mode is `tdd`, refactoring occurs only in this review stage. Rerun affected behavioral tests and all applicable full-scope verification afterward to ensure the green state remains intact.

If the selected review skill explicitly requires several independent review agents, that parallelism is an internal step of the Matt implementation method. If no skill matches or it cannot cover the current uncommitted diff, the main session directly reviews the complete diff. Do not stack `trellis-check` merely for formality.

#### 2.3 Roll back to the right phase `[on demand]`

- New evidence shows a requirement or acceptance criterion is wrong → return to Phase 1 and update `prd.md`.
- The interface, compatibility, migration, or architectural shape is wrong → return to Phase 1 and update `design.md` and `implement.md`.
- A technical fact is missing → return to research in step 1.2 and persist the conclusion.
- The implementation drifted but the requirements remain correct → revert or correct only changes made by this task, then repeat step 2.1.
- Never use destructive Git commands to clean the worktree or revert user changes whose ownership is uncertain.

## Phase 3: Finish

Goal: close the deliverable with evidence while keeping task records, knowledge promotion, and version control as three separate actions.

#### 3.2 Debug retrospective `[on demand]`

Run a retrospective only after repeated failures, multiple fixes for the same issue, an expensive detour, or difficulty establishing a feedback loop. Select the best-matched current diagnosis/learning method and record:

- The root cause;
- Why early approaches failed;
- Why the final evidence is trustworthy;
- Candidate knowledge that could prevent similar issues.

A routine task summary does not trigger a retrospective.

#### 3.3 Knowledge promotion decision `[required · once]`

Always decide whether any knowledge is worth promoting, but do not modify `.trellis/spec/` or a cross-project knowledge base by default.

Candidate knowledge may be promoted only when all of the following are true:

1. Durable: it is not a one-off implementation detail or temporary workaround;
2. Reusable: future tasks would take a different and better action because of it;
3. Verified: supported by code, tests, documentation, or repeated evidence;
4. User-confirmed: the user explicitly agrees to promote it into a spec, skill, hook, test, script, or cross-project pattern.

Without confirmation:

- It may remain in the current task's design, research, or retrospective;
- It may be listed as a promotion candidate in the final response;
- It must not be written automatically to `.trellis/spec/` or a canonical area of the personal knowledge base.

After the user confirms, use the currently available spec/compound-learning method and verify that the new rule matches current repository facts.

#### 3.4 Version-control actions `[on explicit request]`

Skip all Git write operations by default. Perform each action only when the user explicitly requests it:

- Commit: include only known changes from the current task; inspect dirty state and recent history first; group by logical unit; default message is `<type>(scope): <Chinese verb phrase>` with no trailing period; do not amend.
- Push: perform only when the user explicitly requests a push. Commit authorization does not include push.
- PR: create only when explicitly requested. Commit or push authorization does not include a PR.

Trellis never automatically commits a task archive or journal. The commands in section 3.5 always use `--no-commit` explicitly.

#### 3.5 Archive, journal and report `[required · once]`

First determine whether the task is genuinely complete: acceptance criteria are satisfied, required checks have direct evidence, and no blocker remains. Otherwise, update only the checkpoint and risks; do not archive.

Archive after completion:

```bash
python3 ./.trellis/scripts/task.py archive <task-dir> --no-commit
```

Record the session:

```bash
python3 ./.trellis/scripts/add_session.py \
  --title "<title>" \
  --summary "<outcome, verification, remaining risk>" \
  --no-commit
```

Command-level `--no-commit` ensures that both commands only write files and never stage, commit, or push, so `.trellis/config.yaml` does not need to change. Pass `--commit "<hashes>"` only when this task has already created a work commit at the user's explicit request. Otherwise omit the argument; never fabricate a hash.

The final response leads with the conclusion and keeps only:

1. Outcome;
2. Key evidence / changed files;
3. Verification actually run;
4. Remaining risks or blockers;
5. Necessary next step, only when one is genuinely needed.

Without direct verification evidence, do not write “complete,” “passing,” “ready to commit,” or “ready to merge.”

## Active Task Routing

When an active task exists, first read `task.json`, its artifacts, and Current Checkpoint, then resume by state:

| Status / evidence | Resume action |
| --- | --- |
| `planning`, `prd.md` has not converged | 1.1 |
| `planning`, technical unknowns remain | 1.2 |
| `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 |
| `completed` can still be resolved | 3.5 report; the active pointer is normally cleared after a successful archive |

When the user asks an unrelated simple question while a task is active, answer it Inline without modifying the task. When the user explicitly switches to another durable piece of work, save the current checkpoint before activating the new task. Do not mix two requests into one task.

## Runtime and Customization Invariants

1. `.trellis/workflow.md` is the source of truth for workflow semantics and breadcrumb text.
2. When required steps change, update the corresponding `[workflow-state:*]` block.
3. The status in opening and closing workflow-state tags must match exactly. Status values use only `[A-Za-z0-9_-]+`.
4. Do not add custom task statuses unless the status writer, breadcrumb, and this document's `Active Task Routing` are updated together.
5. This workflow retains the existing Trellis phase and step numbers to reduce drift in `get_context.py --mode phase --step <X.Y>` and platform entry files.
6. If a bundled skill or command conflicts with this document, user instructions, `AGENTS.md`, and this document take precedence. Use the low-level Trellis commands given here without modifying bundled files.
7. After `trellis update`, inspect `.new` sidecars or template conflicts. Never overwrite personal customizations directly.
8. Keep breadcrumbs short. Detailed rules belong in the phase body. Keep the Phase Index and detailed phases synchronized.
9. `agents/codex/trellis-matt-implement.toml` is the shared source of truth for the custom implementation agent; install it in a project as `.codex/agents/trellis-matt-implement.toml`.
10. The agent relies on the exact `Active task:` path in its dispatch prompt for pull-based context loading; this setup does not require adding the new name to a Codex hook matcher.
11. Implementation mode is limited to `standard` / `tdd`. `tdd` requires both a user trigger and confirmed public seam; the agent never upgrades modes on its own.

## Adoption Checklist

- [ ] Use this file as the project's `.trellis/workflow.md`.
- [ ] Use the companion guide as the global or project `AGENTS.md`.
- [ ] Copy `agents/codex/trellis-matt-implement.toml` to the project's `.codex/agents/trellis-matt-implement.toml`.
- [ ] Verify the Codex breadcrumb in no-task, planning, and in-progress states.
- [ ] In a `standard` test task, verify that the agent does not use TDD and reads artifacts through `Active task:`.
- [ ] In a `tdd` test task, verify that the agent loads `/tdd` and works only at confirmed seams in vertical red → green slices.
- [ ] In both modes, verify that the agent performs no task-lifecycle or Git write operations.
- [ ] Verify that output from `task.py archive` and `add_session.py` contains evidence that stage/commit was skipped.
- [ ] Use the next user message to verify the breadcrumb; open a new session to verify that the phase body and Skill Routing take effect.