Linear Ticket Workflow for Project Work

This document defines the default workflow for project tickets so work can resume cleanly when a ticket moves to In Progress.

Core rule

• Git docs are the source of truth.
• Linear is the execution queue.
• A ticket assigned to ynerv-ryo-2@agentmail.to and moved to In Progress means: start work now.
• If a ticket is blocked, explain why in the ticket and move it to Blocked.
• When implementation is complete, move the ticket to Review if the team has that state; otherwise comment Ready for review and move it to Done only after approval.

Recommended Linear states

Use these states for every project team:

• Todo — not started yet
• In Progress — actively being worked on
• Review — finished, waiting for human review
• Blocked — cannot continue right now
• Done — accepted and closed

If a team cannot add Review, use Done plus a review comment instead.

Recommended labels

Use labels only for meaning, not for duplicating state.

Waiting and ownership labels

• waiting:user — waiting for a user decision, approval, or confirmation
• waiting:agent — waiting for the assistant to do the next step
• needs:confirmation — the ticket needs a business or product decision

Optional labels

Use only when needed:

• needs:docs — docs must be updated before work continues
• needs:design — design clarification is required
• needs:deps — blocked by another ticket or external dependency

Ticket lifecycle

1. Todo

Use when the ticket is known but not started.

Typical combinations:

• Todo + waiting:user = waiting for you
• Todo + waiting:agent = waiting for me to pick it up or draft the next step
• Todo + needs:confirmation = waiting for a product/business answer

2. In Progress

Use when active work has started.

Expected behavior:

• read the full ticket
• read the relevant project docs
• continue implementation or analysis
• post a short progress comment in Linear
• keep the project state doc current

3. Review

Use when the task is done and ready for your check.

Expected behavior:

• update the Linear ticket with the result
• summarize what changed
• mention any follow-up tickets if needed
• wait for approval or changes requested

4. Blocked

Use when work cannot continue.

Blocked ticket comment should include:

• the exact blocker
• what is missing
• what would unblock it
• whether this is a hard blocker or a temporary wait

5. Done

Use when the work is accepted.

Expected behavior:

• final result is in the ticket
• docs are aligned
• no further action is required for the current ticket

Trigger rules for the assistant

The assistant should start processing when all of these are true:

• ticket is assigned to ynerv-ryo-2@agentmail.to
• ticket is in In Progress
• the project state doc exists or can be created

The assistant should pause and report when:

• ticket is moved to Blocked
• ticket is moved to Review and awaits human approval
• ticket is reassigned away from the assistant

Required project files

Each project should keep:

• docs/00-project-state.md — current handoff state
• docs/10-linear-backlog.md — issue map and workflow notes
• other project docs for scope, requirements, architecture, and workflows

Progress comment format

Assistant-authored Linear comments should start with the prefix:

• 🤖 Ryo:

Example:

• 🤖 Ryo: I picked this up and am now working on the submission flow.

Default operational loop

1. Detect the ticket state change.
2. Read the full ticket.
3. Read the project docs.
4. Update docs/00-project-state.md.
5. Work the ticket.
6. Post a progress comment in Linear.
7. When complete, move to Review.
8. If blocked, move to Blocked and explain why.