obsidian-vault/AI-RD-Workflow/40-workflows/trellis-matt/EN/workflow.md

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.

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. Planning uses grill-with-docs; 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, then uses grill-with-docs to review and tighten the spec.
• 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

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.

Every Trellis implementation task maintains this in prd.md:

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

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

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

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	grill-with-docs; 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 with grill-with-docs [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, review with grill-with-docs, then route 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. [/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:

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.

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.

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 with grill-with-docs [required · once]

Explicitly load grill-with-docs and use it to review prd.md plus conditional design.md and implement.md:

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.

If grill-with-docs cannot be loaded directly on the platform, use the equivalent combination grilling + domain-modeling.

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

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.

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 ✅
grill-with-docs review reached shared understanding	✅
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:

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:

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

Record the session:

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