webnovel-writer/.trellis/workflow.md

Development Workflow

---

Core Principles

1. Plan before code — figure out what to do before you start
2. Specs injected, not remembered — guidelines are injected via hook/skill, not recalled from memory
3. Persist everything — research, decisions, and lessons all go to files; conversations get compacted, files don't
4. Incremental development — one task at a time
5. Capture learnings — after each task, review and write new knowledge back to spec

---

Trellis System

Developer Identity

On first use, initialize your identity:

python ./.trellis/scripts/init_developer.py <your-name>

Creates .trellis/.developer (gitignored) + .trellis/workspace/<your-name>/.

Spec System

.trellis/spec/ holds coding guidelines organized by package and layer.

• .trellis/spec/<package>/<layer>/index.md — entry point with Pre-Development Checklist + Quality Check. Actual guidelines live in the .md files it points to.

• .trellis/spec/guides/index.md — cross-package thinking guides.

  python ./.trellis/scripts/get_context.py --mode packages   # list packages / layers
  

When to update spec: new pattern/convention found · bug-fix prevention to codify · new technical decision.

Task System

Every task has its own directory under .trellis/tasks/{MM-DD-name}/ holding task.json, prd.md, optional design.md, optional implement.md, optional research/, and context manifests (implement.jsonl, check.jsonl) for sub-agent-capable platforms.

# Task lifecycle
python ./.trellis/scripts/task.py create "<title>" [--slug <name>] [--parent <dir>]
python ./.trellis/scripts/task.py start <name>          # set active task (session-scoped when available)
python ./.trellis/scripts/task.py current --source      # show active task and source
python ./.trellis/scripts/task.py finish                # clear active task (triggers after_finish hooks)
python ./.trellis/scripts/task.py archive <name>        # move to archive/{year-month}/
python ./.trellis/scripts/task.py list [--mine] [--status <s>]
python ./.trellis/scripts/task.py list-archive

# Code-spec context (injected into implement/check agents via JSONL).
# `implement.jsonl` / `check.jsonl` are seeded on `task create` for sub-agent-capable
# platforms; the AI curates real spec + research entries during planning when needed.
python ./.trellis/scripts/task.py add-context <name> <action> <file> <reason>
python ./.trellis/scripts/task.py list-context <name> [action]
python ./.trellis/scripts/task.py validate <name>

# Task metadata
python ./.trellis/scripts/task.py set-branch <name> <branch>
python ./.trellis/scripts/task.py set-base-branch <name> <branch>    # PR target
python ./.trellis/scripts/task.py set-scope <name> <scope>

# Hierarchy (parent/child)
python ./.trellis/scripts/task.py add-subtask <parent> <child>
python ./.trellis/scripts/task.py remove-subtask <parent> <child>

# PR creation
python ./.trellis/scripts/task.py create-pr [name] [--dry-run]

Run python ./.trellis/scripts/task.py --help to see the authoritative, up-to-date list.

Current-task mechanism: task.py create creates the task directory and (when session identity is available) auto-sets the per-session active-task pointer so the planning breadcrumb fires immediately. task.py start writes the same pointer (idempotent if already set) and flips task.json.status from planning to in_progress. State is stored under .trellis/.runtime/sessions/. If no context key is available from hook input, TRELLIS_CONTEXT_ID, or a platform-native session environment variable, there is no active task and task.py start fails with a session identity hint. task.py finish deletes the current session file (status unchanged). task.py archive <task> writes status=completed, moves the directory to archive/, and deletes any runtime session files that still point at the archived task.

Workspace System

Records every AI session for cross-session tracking under .trellis/workspace/<developer>/.

• journal-N.md — session log. Max 2000 lines per file; a new journal-(N+1).md is auto-created when exceeded.

• index.md — personal index (total sessions, last active).

  python ./.trellis/scripts/add_session.py --title "Title" --commit "hash" --summary "Summary"
  

Context Script

python ./.trellis/scripts/get_context.py                            # full session runtime
python ./.trellis/scripts/get_context.py --mode packages            # available packages + spec layers
python ./.trellis/scripts/get_context.py --mode phase --step <X.Y>  # detailed guide for a workflow step

---

Phase Index

Phase 1: Plan    → classify, get task-creation consent, then write planning artifacts
Phase 2: Execute → implement only after task status is in_progress
Phase 3: Finish  → verify, update spec, commit, and wrap up

Request Triage

• Simple conversation or small task: ask only whether this turn should create a Trellis task. If the user says no, skip Trellis for this session.
• Complex task: ask whether you may create a Trellis task and enter planning. If the user says no, do not do broad inline implementation; explain, clarify scope, or suggest a smaller split.
• User approval to create a task is not approval to start implementation. Planning still happens first.

Planning Artifacts

• prd.md — requirements, constraints, and acceptance criteria. Do not put technical design or execution checklists here.
• design.md — technical design for complex tasks: boundaries, contracts, data flow, tradeoffs, compatibility, rollout / rollback shape.
• implement.md — execution plan for complex tasks: ordered checklist, validation commands, review gates, and rollback points.
• implement.jsonl / check.jsonl — spec and research manifests for sub-agent context. They do not replace implement.md.
• Lightweight tasks may be PRD-only. Complex tasks must have prd.md, design.md, and implement.md before task.py start.

Parent / Child Task Trees

Use a parent task when one user request contains several independently verifiable deliverables. The parent task owns the source requirement set, the task map, cross-child acceptance criteria, and final integration review; it normally should not be the implementation target unless it also has direct work.

Use child tasks for deliverables that can be planned, implemented, checked, and archived independently. Parent/child structure is not a dependency system: if one child must wait for another, write that ordering in the child prd.md / implement.md and keep each child's acceptance criteria testable.

Create new children with task.py create "<title>" --slug <name> --parent <parent-dir>. Link existing tasks with task.py add-subtask <parent> <child>, and unlink mistakes with task.py remove-subtask <parent> <child>.

[workflow-state:no_task] No active task. First classify the current turn and ask for task-creation consent before creating any Trellis task. Simple conversation / small task: ask only whether this turn should create a Trellis task. If the user says no, skip Trellis for this session. Complex task: ask the user if you can create a Trellis task and enter the planning phase. If the user says no, explain, clarify scope, or suggest a smaller split. [/workflow-state:no_task]

Phase 1: Plan

• 1.0 Create task [required · once] (only after task-creation consent)
• 1.1 Requirement exploration [required · repeatable] (prd.md; complex tasks also need design.md + implement.md)
• 1.2 Research [optional · repeatable]
• 1.3 Configure context [required · once] — Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix (sub-agent-dispatch platforms only; inline platforms skip)
• 1.4 Activate task [required · once] (review gate, then task.py start; status → in_progress)
• 1.5 Completion criteria

[workflow-state:planning] Load trellis-brainstorm; stay in planning. Lightweight: prd.md can be enough. Complex: finish prd.md, design.md, and implement.md; ask for review before task.py start. Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position. Sub-agent mode: curate implement.jsonl and check.jsonl as spec/research manifests before start. [/workflow-state:planning]

[workflow-state:planning-inline] Load trellis-brainstorm; stay in planning. Lightweight: prd.md can be enough. Complex: finish prd.md, design.md, and implement.md; ask for review before task.py start. Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position. Inline mode: skip jsonl curation; Phase 2 reads artifacts/specs via trellis-before-dev. [/workflow-state:planning-inline]

Phase 2: Execute

• 2.1 Implement [required · repeatable]
• 2.2 Quality check [required · repeatable]
• 2.3 Rollback [on demand]

Sub-agent dispatch protocol applies to all platforms and all sub-agents, including class-2 Codex/Gemini/Qoder/Copilot/ZCode/Reasonix/Trae and trellis-research: every dispatch prompt starts with Active task: <task path from task.py current> before role-specific instructions.

[workflow-state:in_progress] Tools: trellis-implement / trellis-research are sub-agent types only (Task/Agent tool, NOT Skill; there is no skill by these names). trellis-update-spec is a skill. trellis-check exists as both; prefer the Agent form when verifying after code changes. Flow: trellis-implement -> trellis-check -> trellis-update-spec -> commit (Phase 3.4) -> /trellis:finish-work. Main-session default: dispatch implement/check sub-agents. Sub-agent self-exemption: if already running as trellis-implement, do NOT spawn another trellis-implement or trellis-check; if already running as trellis-check, do NOT spawn another trellis-check or trellis-implement. Dispatch is main session only. Dispatch prompt starts with Active task: <task path from task.py current>. Read context: jsonl entries -> prd.md -> design.md if present -> implement.md if present. [/workflow-state:in_progress]

[workflow-state:in_progress-inline] Flow: trellis-before-dev -> edit -> trellis-check -> validation -> trellis-update-spec -> commit (Phase 3.4) -> /trellis:finish-work. Do not dispatch implement/check sub-agents in inline mode. Read context: prd.md -> design.md if present -> implement.md if present, plus relevant spec/research loaded by skills. [/workflow-state:in_progress-inline]

Phase 3: Finish

• 3.2 Debug retrospective [on demand]
• 3.3 Spec update [required · once]
• 3.4 Commit changes [required · once]
• 3.5 Wrap-up reminder

Note: step 3.1 was folded into 2.2 (last-iteration full-scope check) and 3.4 (commit preamble). Numbering kept stable to avoid breaking external references.

[workflow-state:completed] Code committed. Run /trellis:finish-work; if dirty, return to Phase 3.4 first. [/workflow-state:completed]

Rules

1. Identify which Phase you're in, then continue from the next step there
2. Run steps in order inside each Phase; [required] steps can't be skipped
3. Phases can roll back (e.g., Execute reveals a prd defect → return to Plan to fix, then re-enter Execute)
4. Steps tagged [once] are skipped if the output already exists; don't re-run
5. Artifact presence informs the next step; missing design.md / implement.md is valid for lightweight tasks and incomplete planning for complex tasks.

Active Task Routing

When a user request matches one of these intents inside an active task, route first, then load the detailed phase step if needed.

[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]

• Planning or unclear requirements -> trellis-brainstorm.
• in_progress implementation/check -> dispatch trellis-implement / trellis-check.
• Repeated debugging -> trellis-break-loop; spec updates -> trellis-update-spec.

[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]

[codex-inline, Kilo, Antigravity, Devin]

• Planning or unclear requirements -> trellis-brainstorm.
• Before editing -> trellis-before-dev; after editing -> trellis-check.
• Repeated debugging -> trellis-break-loop; spec updates -> trellis-update-spec.

[/codex-inline, Kilo, Antigravity, Devin]

Guardrails

• Task creation approval is not implementation approval; implementation waits for task.py start after artifact review.
• PRD-only is valid for lightweight tasks; complex tasks need design.md + implement.md.
• Planning must be persisted to task artifacts; checks must run before reporting completion.

Loading Step Detail

At each step, run this to fetch detailed guidance:

python ./.trellis/scripts/get_context.py --mode phase --step <step>
# e.g. python ./.trellis/scripts/get_context.py --mode phase --step 1.1

---

Phase 1: Plan

Goal: classify the request, get task-creation consent when a task is needed, and produce the planning artifacts required before implementation.

1.0 Create task [required · once]

Create the task directory only after task-creation consent. The command sets status to planning, writes task.json, creates a default prd.md, and auto-targets the new task when session identity is available:

python ./.trellis/scripts/task.py create "<task title>" --slug <name>

--slug is the human-readable name only. Do not include the MM-DD- date prefix; task.py create adds that prefix automatically.

For task trees, create the parent task first and then create each child with --parent <parent-dir>. Do not start the parent just because children exist; start the child that owns the next independently verifiable deliverable.

After this command succeeds, the per-turn breadcrumb auto-switches to [workflow-state:planning], telling the AI to stay in planning.

Run only create here — do not also run start. start flips status to in_progress, which switches the breadcrumb to the implementation phase before planning artifacts are reviewed. Save start for step 1.4.

Skip when python ./.trellis/scripts/task.py current --source already points to a task.

1.1 Requirement exploration [required · repeatable]

Load the trellis-brainstorm skill and explore requirements interactively with the user per the skill's guidance.

The brainstorm skill will guide you to:

• Ask one question at a time
• Prefer researching over asking the user
• Prefer offering options over open-ended questions
• Update prd.md immediately after each user answer
• Split large scopes into a parent task plus child tasks when the deliverables can be verified independently
• Keep prd.md focused on requirements and acceptance criteria
• For complex tasks, produce design.md and implement.md before implementation starts

When considering a parent/child split:

• Use a parent task when one request contains several independently verifiable deliverables.
• Parent tasks own source requirements, child-task mapping, cross-child acceptance criteria, and final integration review.
• Child tasks own actual deliverables that can be planned, implemented, checked, and archived independently.
• Parent/child structure is not a dependency system. If child B depends on child A, write that ordering in child B's prd.md / implement.md.
• Start the child task that owns the next deliverable. Do not start the parent unless the parent itself has direct implementation work.

Return to this step whenever requirements change and revise the relevant artifact.

1.2 Research [optional · repeatable]

Research can happen at any time during requirement exploration. It isn't limited to local code — you can use any available tool (MCP servers, skills, web search, etc.) to look up external information, including third-party library docs, industry practices, API references, etc.

[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]

Spawn the research sub-agent:

• Agent type: trellis-research
• Task description: Research
• Key requirement: Research output MUST be persisted to {TASK_DIR}/research/

[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]

[codex-inline, Kilo, Antigravity, Devin]

Do the research in the main session directly and write findings into {TASK_DIR}/research/. (For codex-inline this avoids the fork_turns="none" isolation that prevents trellis-research sub-agents from resolving the active task path.)

[/codex-inline, Kilo, Antigravity, Devin]

Research artifact conventions:

• One file per research topic (e.g. research/auth-library-comparison.md)
• Record third-party library usage examples, API references, version constraints in files
• Note relevant spec file paths you discovered for later reference

Brainstorm and research can interleave freely — pause to research a technical question, then return to talk with the user.

Key principle: Research output must be written to files, not left only in the chat. Conversations get compacted; files don't.

1.3 Configure context [required · once]

[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]

Curate implement.jsonl and check.jsonl so the Phase 2 sub-agents get the right spec/research context. These files were seeded on task create with a single self-describing _example line; your job here is to fill in real entries.

Location: {TASK_DIR}/implement.jsonl and {TASK_DIR}/check.jsonl (already exist).

Format: one JSON object per line — {"file": "<path>", "reason": "<why>"}. Paths are repo-root relative.

What to put in:

• Spec files — .trellis/spec/<package>/<layer>/index.md and any specific guideline files (error-handling.md, conventions.md, etc.) relevant to this task
• Research files — {TASK_DIR}/research/*.md that the sub-agent will need to consult

What NOT to put in:

• Code files (src/**, packages/**/*.ts, etc.) — those are read by the sub-agent during implementation, not pre-registered here
• Files you're about to modify — same reason

Split between the two files:

• implement.jsonl → specs + research the implement sub-agent needs to write code correctly
• check.jsonl → specs for the check sub-agent (quality guidelines, check conventions, same research if needed)

These manifests do not replace implement.md. implement.md is the human-readable execution plan for a complex task; jsonl files only list context files to inject or load.

How to discover relevant specs:

python ./.trellis/scripts/get_context.py --mode packages

Lists every package + its spec layers with paths. Pick the entries that match this task's domain.

How to append entries:

Either edit the jsonl file directly in your editor, or use:

python ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
python ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"

Delete the seed _example line once real entries exist (optional — it's skipped automatically by consumers).

Ready gate: both implement.jsonl and check.jsonl must contain at least one real {"file": "...", "reason": "..."} entry before task.py start. The seed _example row alone is not ready.

Skip this step only when both files already have real curated entries.

[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]

[codex-inline, Kilo, Antigravity, Devin]

Skip this step. Context is loaded directly by the trellis-before-dev skill in Phase 2.

[/codex-inline, Kilo, Antigravity, Devin]

1.4 Activate task [required · once]

After artifact review, flip the task status to in_progress:

python ./.trellis/scripts/task.py start <task-dir>

For lightweight tasks, prd.md can be enough. For complex tasks, prd.md, design.md, and implement.md must exist and be reviewed before start. On sub-agent-dispatch platforms, implement.jsonl and check.jsonl must both have real curated entries before start. Runtime consumers tolerate missing or seed-only manifests for compatibility, but that tolerance is not a planning-ready state.

After this command succeeds, the breadcrumb auto-switches to [workflow-state:in_progress], and the rest of Phase 2 / 3 follows.

If task.py start errors with a session-identity message (no context key from hook input, TRELLIS_CONTEXT_ID, or platform-native session env), follow the hint in the error to set up session identity, then retry.

1.5 Completion criteria

Condition	Required
prd.md exists	✅
User confirms task should enter implementation	✅
task.py start has been run (status = in_progress)	✅
research/ has artifacts (complex tasks)	recommended
design.md exists (complex tasks)	✅
implement.md exists (complex tasks)	✅

[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]

| implement.jsonl and check.jsonl each contain at least one real curated entry (seed row does not count) | ✅ |

[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]

---

Phase 2: Execute

Goal: turn reviewed planning artifacts into code that passes quality checks.

2.1 Implement [required · repeatable]

[Claude Code, Cursor, OpenCode, CodeBuddy, Droid, Pi]

Spawn the implement sub-agent:

• Agent type: trellis-implement
• Task description: Implement the reviewed task artifacts, consulting materials under {TASK_DIR}/research/; finish by running project lint and type-check
• Dispatch prompt guard: Tell the spawned agent it is already the trellis-implement sub-agent and must implement directly, not spawn another trellis-implement / trellis-check.

The platform hook/plugin auto-handles:

• Reads implement.jsonl and injects referenced spec/research files into the agent prompt
• Injects prd.md, design.md if present, and implement.md if present

[/Claude Code, Cursor, OpenCode, CodeBuddy, Droid, Pi]

[codex-sub-agent, Gemini, Qoder, Copilot, ZCode, Reasonix, Trae]

Spawn the implement sub-agent:

• Agent type: trellis-implement
• Task description: Implement the reviewed task artifacts, consulting materials under {TASK_DIR}/research/; finish by running project lint and type-check
• Dispatch prompt guard: The prompt MUST start with Active task: <task path>, then explicitly say the spawned agent is already trellis-implement and must implement directly without spawning another trellis-implement / trellis-check.

The pull-based sub-agent definition auto-handles the context load requirement:

• Resolves the active task with task.py current --source, then reads prd.md, design.md if present, and implement.md if present
• Reads implement.jsonl and requires the agent to load each referenced spec/research file before coding

[/codex-sub-agent, Gemini, Qoder, Copilot, ZCode, Reasonix, Trae]

[Kiro]

Spawn the implement sub-agent:

• Agent type: trellis-implement
• Task description: Implement the reviewed task artifacts, consulting materials under {TASK_DIR}/research/; finish by running project lint and type-check
• Dispatch prompt guard: Tell the spawned agent it is already the trellis-implement sub-agent and must implement directly, not spawn another trellis-implement / trellis-check.

The platform prelude auto-handles the context load requirement:

• Reads implement.jsonl and injects referenced spec/research files into the agent prompt
• Injects prd.md, design.md if present, and implement.md if present

[/Kiro]

[codex-inline, Kilo, Antigravity, Devin]

1. Load the trellis-before-dev skill to read project guidelines
2. Read {TASK_DIR}/prd.md, then design.md if present, then implement.md if present
3. Consult materials under {TASK_DIR}/research/
4. Implement the code per reviewed artifacts
5. Run project lint and type-check

[/codex-inline, Kilo, Antigravity, Devin]

2.2 Quality check [required · repeatable]

[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]

Spawn the check sub-agent:

• Agent type: trellis-check
• Task description: Review all code changes against specs and task artifacts; fix any findings directly; ensure lint and type-check pass
• Dispatch prompt guard: Tell the spawned agent it is already the trellis-check sub-agent and must review/fix directly, not spawn another trellis-check / trellis-implement.

The check agent's job:

• Review code changes against specs
• Review code changes against prd.md, design.md if present, and implement.md if present
• Auto-fix issues it finds
• Run lint and typecheck to verify

[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]

[codex-inline, Kilo, Antigravity, Devin]

Load the trellis-check skill and verify the code per its guidance:

• Spec compliance
• lint / type-check / tests
• Cross-layer consistency (when changes span layers)

If issues are found → fix → re-check, until green.

[/codex-inline, Kilo, Antigravity, Devin]

Final pass (before Phase 3.4 commit): the last 2.2 of a task must run full-scope, not just on the latest implement chunk. List all affected packages with python ./.trellis/scripts/get_context.py --mode packages, then load each package's spec index Quality Check section. This catches cross-layer / multi-package issues a mid-iteration local 2.2 cannot.

2.3 Rollback [on demand]

• check reveals a prd defect → return to Phase 1, fix prd.md, then redo 2.1
• Implementation went wrong → revert code, redo 2.1
• Need more research → research (same as Phase 1.2), write findings into research/

---

Phase 3: Finish

Goal: ensure code quality, capture lessons, record the work.

3.2 Debug retrospective [on demand]

If this task involved repeated debugging (the same issue was fixed multiple times), load the trellis-break-loop skill to:

• Classify the root cause
• Explain why earlier fixes failed
• Propose prevention

The goal is to capture debugging lessons so the same class of issue doesn't recur.

3.3 Spec update [required · once]

Load the trellis-update-spec skill and review whether this task produced new knowledge worth recording:

• Newly discovered patterns or conventions
• Pitfalls you hit
• New technical decisions

Update the docs under .trellis/spec/ accordingly. Even if the conclusion is "nothing to update", walk through the judgment.

3.4 Commit changes [required · once]

Spec-sync preamble: before drafting commits, ask: did this task fix a bug or surface non-obvious knowledge that should land in .trellis/spec/ so future-you (or future-AI) doesn't repeat the mistake? If yes, return to Phase 3.3 first — spec writes belong in the same task's commit batch, not as a forgotten follow-up.

The AI drives a batched commit of this task's code changes so /finish-work can run cleanly afterwards. Goal: produce work commits FIRST, then bookkeeping (archive + journal) commits land after — never interleaved.

Step-by-step:

1. Inspect dirty state:

   git status --porcelain
   

   Snapshot every dirty path. If the working tree is clean, skip to 3.5.

2. Learn commit style from recent history (so drafted messages blend in):

   git log --oneline -5
   

   Note the prefix convention (feat: / fix: / chore: / docs: ...), language (中文/English), and length style.

3. Classify dirty files into two groups:

   • AI-edited this session — files you wrote/edited via Edit/Write/Bash tool calls in this session. You know what changed and why.
   • Unrecognized — dirty files you did NOT touch this session (could be the user's manual edits, leftover WIP from a previous session, or unrelated work). Do NOT silently include these.

4. Draft a commit plan. Group AI-edited files into logical commits (1 commit per coherent change unit, not 1 commit per file). Each entry: <commit message> + file list. List unrecognized files separately at the bottom.

5. Present the plan once, ask for one-shot confirmation. Format:

   Proposed commits (in order):
    1. <message>
       - <file>
       - <file>
    2. <message>
       - <file>
   
   Unrecognized dirty files (NOT in any commit — confirm include/exclude):
    - <file>
    - <file>
   
   Reply 'ok' / '行' to execute. Reply with edits, or '我自己来' / 'manual' to abort.
   

6. On confirmation: run git add <files> + git commit -m "<msg>" for each batch in order. Do not amend. Do not push.

7. On rejection (user replies "不行" / "我自己来" / "manual" / any pushback on the plan): stop. Do not attempt a second plan. The user will commit by hand; you skip ahead to 3.5 once they confirm.

Rules:

• No git commit --amend anywhere — three-stage three-commit flow (work commits → archive commit → journal commit).
• Never push to remote in this step.
• If the user wants different message wording but accepts the file grouping, edit the message and re-confirm once — but if they reject the grouping, exit to manual mode.
• The batched plan is one prompt; do not prompt per commit.

3.5 Wrap-up reminder

After the above, remind the user they can run /finish-work to wrap up (archive the task, record the session).

---

Customizing Trellis (for forks)

This section is for developers who want to modify the Trellis workflow itself. All customization is done by editing this file; the scripts are parsers only.

Changing what a step means

Edit the corresponding step's walkthrough body in the Phase 1 / 2 / 3 sections above. Critical invariants:

• No active task must triage first and ask for task-creation consent before creating a Trellis task.
• Planning must distinguish lightweight PRD-only tasks from complex tasks that require prd.md, design.md, and implement.md before start.
• Every required execution path must keep the Phase 3.4 commit reminder reachable before /trellis:finish-work.

All tag blocks live in the ## Phase Index section above, immediately after each phase summary:

Scope	Corresponding tag
No active task (before Phase 1)	[workflow-state:no_task] (after the Phase Index ASCII art)
All of Phase 1 (task created → ready for implementation)	[workflow-state:planning] (after Phase 1 summary)
Codex inline Phase 1	[workflow-state:planning-inline]
Phase 2 + Phase 3.2–3.4 (implementation + check + wrap-up)	[workflow-state:in_progress] (after Phase 2 summary)
Codex inline Phase 2 + Phase 3.2–3.4	[workflow-state:in_progress-inline]
After Phase 3.5 (archived)	[workflow-state:completed] (after Phase 3 summary; currently DEAD)

Changing the per-turn prompt text

Directly edit the body of the corresponding [workflow-state:STATUS] block. After editing, run trellis update (if you're a template maintainer) or restart your AI session (if you're customizing your own project) — no script changes required.

Adding a custom status

Add a new block:

[workflow-state:my-status]
your per-turn prompt text
[/workflow-state:my-status]

Constraints:

• STATUS charset: [A-Za-z0-9_-]+ (underscores and hyphens allowed, e.g. in-review, blocked-by-team)
• A lifecycle hook must write task.json.status to your custom value, otherwise the tag is never read
• Lifecycle hooks live in task.json.hooks.after_* and bind to one of after_create / after_start / after_finish / after_archive

Adding a lifecycle hook

Add a hooks field to your task.json:

{
  "hooks": {
    "after_finish": [
      "your-script-or-command-here"
    ]
  }
}

Supported events: after_create / after_start / after_finish / after_archive. Note that after_finish ≠ a status change (it only clears the active-task pointer); use after_archive for "task is done" notifications.

Full contract

For the workflow state machine's runtime contract, the locations of all status writers, pseudo-statuses (no_task / stale_<source_type>), the hook reachability matrix, and other deep details, see:

• .trellis/spec/cli/backend/workflow-state-contract.md — runtime contract + writer table + test invariants
• .trellis/scripts/inject-workflow-state.py — actual parser (reads workflow.md only, no embedded text)