Learning

Project Interaction Model

Project Interaction Model: You, Me, Linear, TUI, and Telegram Purpose This document explains who should do what, and where each action should happen, during pro

Source: learning/setup/project-interaction-model.mdUpdated 2026-04-25

Project Interaction Model: You, Me, Linear, TUI, and Telegram

Purpose

This document explains who should do what, and where each action should happen, during project development.

The goal is to keep each tool in its proper role:

  • Git docs = the durable source of truth
  • Linear = execution tracking and approvals for work items
  • TUI = local operator console for editing, checking, and running project operations
  • Telegram/TG = fast human communication and lightweight coordination
  • You = the decision maker and approver
  • Me = the assistant that drafts, organizes, tracks, and keeps the system aligned

---

1. Role Definitions

You

You are the project owner / decision maker.

You should:

  • define goals and priorities
  • approve scope and changes
  • resolve business tradeoffs
  • sign off on milestones and release readiness
  • decide when a project is good enough to move forward

You should do this mainly in:

  • Telegram for fast conversation
  • TUI for direct review when needed
  • Git docs for final approval of the plan

Me

I am the operational assistant.

I should:

  • draft project docs
  • propose plans and issue breakdowns
  • translate docs into Linear tasks
  • keep status summaries current
  • point out missing decisions or open questions
  • prepare review-ready artifacts

I should do this mainly in:

  • Git docs for durable content
  • Linear for task organization and status tracking
  • Telegram for short operational updates
  • TUI when file-level changes or repo checks are needed

Linear

Linear is the work execution layer.

Linear should be used for:

  • project tracking
  • issue tracking
  • task ownership
  • sequencing and prioritization
  • blockers and status updates
  • review-ready task completion

Linear should not be the place where final project intent lives. That belongs in Git docs.

TUI

TUI is the local command-and-control surface.

Use TUI when the work is about:

  • reading or editing repo files
  • checking local state
  • reviewing generated docs
  • running commands or scripts
  • verifying project structure
  • doing bulk updates efficiently

TUI is best for:

  • repo work
  • doc editing
  • local validation
  • structured review before something is posted to Linear or Telegram

Telegram / TG

Telegram is for human communication.

Use TG when the work is about:

  • quick discussion
  • status updates
  • approval requests
  • clarifying questions
  • lightweight coordination
  • daily collaboration

TG should not be the source of truth for project design or task state. It is the conversation layer.

---

2. Tool Boundaries

Git docs

Use Git docs for:

  • vision
  • scope
  • requirements
  • architecture
  • workflows
  • data model
  • MVP plan
  • release notes
  • open questions

Rule:

  • If it matters later, it should exist in Git docs.

Linear

Use Linear for:

  • epics / milestones
  • tasks
  • bugs
  • spikes
  • blockers
  • review status
  • completion tracking

Rule:

  • If it is actionable work, it should exist in Linear.

Telegram

Use Telegram for:

  • asking for approval
  • giving progress summaries
  • discussing options
  • confirming decisions
  • reporting blockers in plain language

Rule:

  • If it is a conversation, use Telegram.
  • If it needs to persist as project structure, move it to docs or Linear.

TUI

Use TUI for:

  • file operations
  • repo inspection
  • plan editing
  • status checks
  • local validation
  • preparing artifacts before sharing

Rule:

  • If it requires detailed file work or local verification, use TUI.

---

3. Who Does What During Development

A. New project creation

What happens:

  • a new idea appears
  • the project is named
  • the initial docs are created
  • the Linear project is created

Who does what:

  • You: confirm the idea is worth pursuing
  • Me: create the initial project structure and draft docs
  • Linear: host the project container
  • TG: used for the initial discussion and confirmation
  • TUI: used to create/edit the files

B. Project planning

What happens:

  • scope is defined
  • requirements are written
  • architecture is drafted
  • MVP is chosen
  • open questions are listed

Who does what:

  • You: approve the plan or ask for changes
  • Me: prepare the plan and highlight gaps
  • Linear: receive the initial milestone breakdown
  • TG: used to discuss tradeoffs and decisions
  • TUI: used to edit the docs and inspect the repo

C. Project execution

What happens:

  • work is broken into tasks
  • tasks are assigned
  • implementation proceeds
  • blockers are tracked

Who does what:

  • You: decide priorities, unblock tradeoffs, approve direction changes
  • Me: turn plan items into tasks and keep the backlog organized
  • Linear: track each issue from ready to done
  • TG: used for quick status updates or blocking questions
  • TUI: used for local implementation support and verification

D. Task review and approval

What happens:

  • a task is completed
  • the result is reviewed
  • feedback is given
  • changes are requested or approved

Who does what:

  • You: approve or reject from a product/business perspective
  • Me: collect the task result, summarize it, and prepare review notes
  • Linear: record the task state and review status
  • TG: used for short review questions or approval requests
  • TUI: used when detailed inspection is needed

E. Final review and release approval

What happens:

  • the MVP is complete
  • the project is reviewed end-to-end
  • release notes are finalized
  • the baseline is approved or rejected

Who does what:

  • You: give final release approval
  • Me: assemble the final review package and checklist
  • Linear: mark the release work complete and close the project tasks
  • TG: used for final sign-off discussion
  • TUI: used to inspect the final docs and release artifacts

---

Project persistence / handoff section

For each project, keep a small handoff block in the project docs so work can resume cleanly after a pause or context reset.

Recommended file location:

  • ~/workspace/projects/<project>/docs/00-project-state.md

Template:

# Project State

## Active ticket
- Linear: YNE-8
- Title: Implement employee leave request submission
- State: In Progress
- Assignee: ynerv-ryo-2@agentmail.to

## Current objective
- What I am doing right now

## Last completed step
- What was finished most recently

## Next step
- What should happen next

## Decisions already made
- Scope choices
- Architecture choices
- Workflow choices

## Blockers / risks
- Anything preventing progress

## Review signal
- What should happen when the work is ready for review

## Relevant docs
- links to the source-of-truth docs

Operational rule:

  • If a ticket is In Progress and assigned to me, I should read the ticket in full, read the linked project docs, continue the work, and then update Linear with the result.
  • If the work is complete, move the ticket to a review state or mark it explicitly as ready for review.
  • If the work is blocked, add the blocker details, then move the ticket to Blocked.

Recommended automation:

  • Keep a watcher that polls Linear for issue updates.
  • Trigger work when a ticket assigned to ynerv-ryo-2@agentmail.to enters In Progress.
  • Trigger a handoff summary when the ticket moves to Review, Blocked, or Done.
  • Store watcher state and pending actions in ~/workspace/run/.

Linear setup recommendation:

  • Use Todo, In Progress, Blocked, and Done at minimum.
  • If you want a visible handoff stage, add a dedicated Review state to the team workflow.
  • Use labels like waiting:agent and waiting:user for visibility.
  • Keep the agent assigned to ynerv-ryo-2@agentmail.to when assignment is supported.

---

Fast path

Use this when the issue is small or obvious:

  1. You ask in Telegram
  2. I answer in Telegram
  3. If needed, I update docs or Linear
  4. You approve in Telegram or in TUI

Structured path

Use this when the issue affects scope, architecture, or release readiness:

  1. You raise the issue in Telegram
  2. I draft the change in docs
  3. I update or propose Linear issues
  4. You review in TUI or Telegram
  5. You approve
  6. I update Linear and docs accordingly

High-risk path

Use this when the decision changes the project significantly:

  1. You raise the concern in Telegram
  2. I produce a doc-level proposal
  3. We review it in TUI
  4. You approve or reject explicitly
  5. Only then do we update Linear for execution

---

5. Example: Leave Management Web Application

Step 1: Idea

You say in Telegram:

  • "We need a leave management web application."

What I do:

  • draft the initial project docs
  • create the project structure
  • suggest the MVP boundaries

What TUI does:

  • lets me create the files and inspect the repo

What Linear does:

  • stores the project container and initial issues

Step 2: Plan review

You review the plan.

You can do that in:

  • Telegram for quick feedback
  • TUI for document review

What I do:

  • summarize scope
  • identify open questions
  • convert the plan into milestone issues

Step 3: Execution

You approve the plan.

What I do:

  • create the task breakdown in Linear
  • keep docs aligned with any changes
  • report progress

What Linear does:

  • tracks each implementation task

What Telegram does:

  • carries short progress updates and blocker questions

What TUI does:

  • supports local implementation and file updates

Step 4: Review

A task like "Manager approval flow" is finished.

What I do:

  • summarize the result
  • note the review checklist
  • flag any follow-up work

Who reviews:

  • You approve the outcome
  • Linear records the state
  • TUI can be used for detailed inspection
  • TG can be used for short review discussion

Step 5: Final approval

The full leave app MVP is done.

What I do:

  • prepare the final review summary
  • list open risks and completed scope
  • propose release approval

What you do:

  • approve release or request fixes

What Linear does:

  • closes the project work

What Telegram does:

  • carries the final yes/no decision and any follow-up notes

---

6. What You Can Change in Linear to Signal Progress

Linear is where you can make execution-level decisions that I should react to.

A. Task approval

You can:

  • move a task to Done
  • mark a task as approved if you use that convention
  • add a comment like "approved" or "good to merge"

What I should do:

  • treat the task as accepted
  • move on to the next dependent task
  • update any linked docs if the task changed the project definition
  • prepare the next issue or milestone if needed

B. Requirement confirmation

You can:

  • comment "confirmed"
  • move a requirement issue from Triage or Backlog to Ready
  • approve a requirement decision
  • create a new issue if the requirement changed

What I should do:

  • treat the requirement as fixed
  • update the docs if the requirement affects the spec
  • break it into implementation tasks if it is still high-level
  • continue with execution planning

C. Scope change

You can:

  • add or remove issues
  • reprioritize milestones
  • close an issue that is no longer needed
  • create a new issue for newly added scope
  • mark an issue blocked because the scope is unclear

What I should do:

  • treat it as a project-level change
  • update 02-scope.md and possibly 07-mvp-plan.md
  • adjust the task plan
  • warn if the change affects timeline or release boundary

D. Priority change

You can:

  • raise or lower priority
  • reorder backlog items
  • mark something urgent

What I should do:

  • reorder the execution sequence
  • keep the docs unchanged unless priority implies a scope change
  • focus the next work on the newly prioritized item

E. Blocker or risk note

You can:

  • comment that something is blocked
  • move an issue to Blocked
  • add the reason in the issue description or comment

What I should do:

  • stop assuming that work can continue
  • identify the dependency or decision needed
  • update docs if the blocker reveals a missing requirement
  • propose the next action to unblock it

F. Design or requirement clarification

You can:

  • answer a question in a comment
  • add a note to the issue
  • approve a proposed design
  • reject a proposed design and ask for revision

What I should do:

  • treat that as the authoritative decision
  • update docs if the clarification affects the spec
  • continue implementation based on the clarified direction

G. Review result

You can:

  • approve the task
  • request changes
  • reject the task
  • add review feedback

What I should do:

  • if approved, move forward to dependent work
  • if changes are requested, create follow-up issues or revise the existing task
  • if rejected, stop and rework the plan

Simple Linear trigger comments

If you want me to react quickly, short comments like these are ideal:

  • "Approved"
  • "Confirmed"
  • "Scope changed: ..."
  • "Blocked by ..."
  • "Ready to proceed"
  • "Please update docs"

Linear waiting-state convention

Use Linear state + labels to make ownership visible.

Recommended convention:

  • Todo + waiting:user = waiting for your decision, confirmation, or approval.
  • Todo + waiting:agent = waiting for the agent to draft, update docs, or prepare the next step.
  • Backlog = planned but not ready for action yet.
  • In Progress = actively being worked on.
  • Done = accepted/completed.
  • Add needs:confirmation when the issue requires a business/product decision.

Linear agent-assignee note:

  • Linear has a reserved coding-agent assignee named Linear, but assigning to it only works when the workspace Coding Agent is enabled in AI settings.
  • In this workspace, the preferred agent assignee is ynerv-ryo-2@agentmail.to (display name ynerv-ryo-2). Use that member for agent-owned issues when assignment is supported.
  • If neither agent assignment path is available, agent-owned work should remain in the existing waiting-state flow (Todo + waiting:agent).

Important note:

  • Do not use Linear Teams to separate "you" and "me". In Linear, Teams usually represent product/engineering groups, not individual responsibility.
  • Use assignee + labels instead.
  • In this workspace, use ynerv-ryo-2@agentmail.to for agent-owned issues when assignment is supported.

How you know a task is waiting for you:

  • It is assigned to you.
  • It is in Todo.
  • It has the waiting:user label.
  • It may also have needs:confirmation.

Automatic Linear change detection

There are two possible automation models:

  1. Webhook-based detection, preferred

    2. - Linear sends an event when an issue is commented, moved, assigned, or updated. - Hermes receives the webhook and runs the relevant project workflow. - This avoids polling and reacts only when something changes.

  1. Polling-based detection, fallback

    2. - A scheduled watcher checks Linear every few minutes. - It compares issue state/comments against the last seen snapshot. - It reacts when it sees a new confirmation, approval, blocker, or review result.

Current environment note:

  • A polling-based cron watcher is now enabled for the Leave Management Linear project.
  • Job name: linear-leave-management-watcher
  • Schedule: every 5 minutes
  • Script: ~/.hermes/scripts/linear_leave_watcher.py
  • State file: ~/workspace/run/linear_leave_watcher_state.json
  • Pending-change queue: ~/workspace/run/linear_leave_watcher_pending.json
  • The watcher keeps pending changes in the queue until the cron agent processes them and clears the queue, so detected Linear changes are not lost if one cron run fails to act.
  • Webhook-based detection is still the preferred future option, but the Hermes webhook platform is not enabled yet.

---

7. Simple Rules of Thumb

  • Use Git docs for durable project truth.
  • Use Linear for actionable work tracking.
  • Use Telegram for conversation and quick approvals.
  • Use TUI for file-level work and local verification.
  • You approve; I organize.
  • If it changes the project, it should end up in docs and/or Linear.
  • If it is only discussion, keep it in Telegram.

---

7. Short Operating Summary

  • You decide.
  • I draft and organize.
  • Linear tracks execution.
  • TUI handles local work and review.
  • Telegram handles human coordination.

That is the cleanest division of labor for project development.