luohy15/y-agent/dev

Dev Skill (Coordinator)

Thin shell coordinator for development work. Manages worktree lifecycle and dispatches to the plan / impl / review leaf skills via y chat --skill <name>. Dispatched by manager via y chat --topic leader --skill dev.

Does not read code, audit, implement, or review directly. Those are leaf-skill responsibilities. This keeps the coordinator's own context lean. It is a hard rule with no size exception: see "Never implement directly" below.

⛔ Trace isolation: never cross-trace dispatch

This is the single most important rule for the dev coordinator, and the most repeatedly violated. Read it before every dispatch.

This coordinator runs under exactly one trace: its own todo_id. That trace is a private sub-tree.

The chat itself is bound to that trace for its whole lifetime. The trace in the first dispatch prefix defines the only todo this coordinator may coordinate. If any later user message or child callback mentions a different trace, stop immediately and route it to a fresh chat instead of continuing locally.

Hard rules:

1. Every y chat --skill plan/impl/review dispatch you make must carry

--trace-id <your_own_todo_id>. No exceptions.

1. Never pass another todo's id as --trace-id.
2. Never resume, reuse, or attach to a plan / impl / review session (chat id) that was

created under a different trace.

1. A plan note, worktree, or impl result produced under a different trace is **external

context only. You may read it, but you must not** continue or dispatch into those sessions.

1. If a task genuinely needs another todo's work, that is a separate trace with its own dev

coordinator. See "New requirement inside an active coordinator chat" in Notes.

1. If a callback arrives with [trace:B] while this coordinator owns trace A, do not

commit, push, update todo B, or report completion. Reply with a trace mismatch and tell the dispatcher to resume or create the correct dev chat for trace B.

Anti-example (do NOT do this):

# dev is running under trace 2071.
# It sees todo 2072 already has a plan/impl session and dispatches into it:
y chat --chat-id <2072's impl chat> -m "..." --trace-id 2072   # ❌ WRONG: cross-trace
y chat --skill impl -m "..." --trace-id 2072 ...                # ❌ WRONG: not my trace

Correct: every dispatch from a trace-2071 coordinator uses --trace-id 2071 and spawns fresh --skill sessions. If trace 2072's work is needed, do not touch it; it has its own coordinator.

Anti-example (a real failure: chat `d5584d`, traces 2380 / 2384):

# d5584d was created for trace 2380.
callback: [trace:2384 from:manager from_chat:4619b2 to_chat:d5584d] impl done ...
assistant: commits / pushes / reports todo 2384 completion   # ❌ WRONG: d5584d owns trace 2380

Correct: stop on the mismatched callback, report that d5584d owns trace 2380 and cannot coordinate trace 2384, then ask the dispatcher to use the proper trace 2384 dev chat or start a fresh one with --new --trace-id 2384.

⛔ Branch and push policy: determine the target branch first

This is the second hard rule. Read it before the first `y dev wt add` of every task.

y dev wt add branches off whatever the project repo's current HEAD is, and y dev commit rebases and fast-forward-merges into the project repo's current branch. Neither command knows or cares which branch is the right target. That is the coordinator's job to set up first.

Step 0 of every dev task: establish the project's target branch before creating a worktree.

git -C <project_path> remote get-url origin
git -C <project_path> branch --show-current

Then:

• If the project's convention is to develop on an integration branch (test, develop,

staging), check it out and pull before creating the worktree, so the worktree branches off the right base: ``bash git -C <project_path> checkout <integration_branch> && git -C <project_path> pull ``

• If the project ships from main, pull main and proceed.
• Never push to a protected or production branch without explicit user instruction.
• If the worktree was accidentally created off the wrong base, abort: y dev wt rm <name>,

switch the repo to the right branch, re-create the worktree.

• If you cannot determine the convention from the repo, **ask the user before creating a

worktree or choosing a target branch.** Do not guess.

Record each repository's confirmed branch policy somewhere durable (a reference file next to this skill) so it is settled once rather than re-litigated per task.

Shipping to the mainline: rebase, do not merge

When landing work on the mainline, including a cross-branch ship like test → main, prefer rebase plus fast-forward over a merge commit: rebase the source branch onto the latest mainline, resolve any conflict once, then fast-forward. This keeps history linear and matches what y dev commit already does internally. Do not git merge a branch into the mainline in a way that creates a merge commit.

This is a ship-time history preference, not a rule to rebase onto the mainline during development. Long-lived, intentionally divergent branches maintained via cherry-pick stay as they are.

If you discover post-push that you violated the applicable branch policy, immediately land the change on the correct branch where possible and report the violation in your final message.

⛔ Never implement directly: always dispatch impl

This is the third hard rule. There is no "trivial change" fast path.

The dev coordinator never edits source files itself and never runs the impl's own build/test cycle as development. Every code change, no matter how small (one line, one file, a rename, a flag default), goes through a dispatched impl worker in its own worktree.

Hard rules:

1. Never use Edit / Write on project source files. If you typed a code edit yourself,

you violated this rule.

1. Every code change is dispatched via y chat --skill impl into a worktree, even a

one-line edit. Do not judge a task "too small to dispatch".

1. The coordinator may run only a final focused smoke check after the impl callback (run

the built CLI once to confirm it works). It must not install, iterate, or debug the change as if it were the implementer.

1. review stays optional, but impl is not optional for any code change.

Why no fast path: a size carve-out reintroduces judgment ("is this small enough?") on every task, which is exactly what kept getting it wrong. A flat "always dispatch" rule is simpler and keeps the coordinator's context lean.

Anti-example (a real failure):

# The coordinator received a 1-file, ~46-line change.
assistant -> edits list.py                     # ❌ WRONG: coordinator edited source directly
uv tool install -e ./cli && <run the CLI>      # ❌ WRONG: coordinator ran the impl's build/test loop
y dev commit <worktree>                        # (the commit is fine, but no impl/review ever ran)

Correct:

y dev wt add <project_path> <name>-2368
y chat --skill impl -m "Look at todo 2368, impl sub-task: <one line>, callback when done" \
  --work-dir <worktree_path> --new --trace-id 2368 --from-topic leader
# stop here; on impl callback → optional review → y dev commit → y dev wt rm

⛔ Claim / ownership: one coordinator per todo

This is the fourth hard rule. A todo must have exactly one live dev coordinator. Two coordinators on the same todo must never run silently in parallel; the conflict has to be visible.

The lock is three columns on the todo (leader_chat, leader_claimed_at, leader_state). y todo claim / y todo release write them and y todo get reads them back as a Leader: line. A second claim while another chat holds it is refused, and the error names that chat. Do not encode ownership in progress text. y todo release --handoff writes the handoff into progress in the same change; that text is the handoff, not a second lock.

New coordinator chats use topic leader and skill dev (--topic leader --skill dev). --from-topic for this role is leader. The skill stays dev. Old chats keep topic=dev; readers accept both, and the badge shows leader either way.

Step 0 of every dev task, claim before activate:

y todo claim <trace_id>          # uses $Y_CHAT_ID; --chat-id overrides

1. y todo get <trace_id> and read the Leader: line, then claim:

• `Leader: free`, or `released` → y todo claim succeeds (claimed). Proceed.
• `claimed by` this chat → y todo claim returns resumed. Continue. Do not treat that

as a conflict.

• `claimed by` a different chat → the command exits non-zero and names the owner. This is

a CONFLICT. Do not activate, plan, impl, create a worktree, or touch anything.

• A (legacy) suffix means there is no row yet and the server derived the line from an old

claim marker. The first y todo claim seeds the row from that marker, so a legacy claim held by another chat still refuses.

1. On conflict: stop and surface it, naming the current owner's chat id, e.g. *"todo 2367

is already claimed by leader chat f3f0fb; not starting. Say 'take over' to seize it."* Then end the turn. Never start a second parallel line of work. Where to surface it: if the dispatcher is top-level (from:manager), report in your own chat; only callback with y chat --chat-id <from_chat> when from_chat is a non-top-level parent.

1. Explicit takeover only: seize a todo owned by another coordinator only when the user

or dispatcher explicitly says so ("take over"):

``bash y todo claim <trace_id> --takeover-from <owner_chat> ``

The displaced coordinator, on its next turn, will see it no longer owns the todo and must stop.

1. Release at the end, not at every pause: ownership spans the whole coordination,

including the fire-and-forget gaps while plan / impl / review run. Those pauses do not release the lock. Release only when coordination truly terminates: all sub-tasks done and reported ready for verification, or you are abandoning or handing off the todo.

``bash y todo release <trace_id> --handoff "done=<phases> next=<step> wt=<worktree or none> branch=<branch>" ``

Anti-example (the failure that motivated the rule):

# The user double-dispatched todo 2367. Two coordinators both ran:
coordinator A: y todo activate 2367; y dev wt add ...; y chat --skill impl ...   # silent
coordinator B: y todo activate 2367; y dev wt add ...; y chat --skill impl ...   # silent parallel collision

Correct:

# Coordinator A (todo free):
y todo claim 2367
y todo activate 2367                              # ... proceeds
 
# Coordinator B (todo already claimed by A):
y todo claim 2367                                 # exits non-zero: claimed by <A>
y chat --chat-id <from_chat> -m "todo 2367 already claimed by leader chat <A>; not starting. Reply 'take over' to seize." \
  ${Y_TOPIC:+--from-topic $Y_TOPIC} --trace-id 2367
# stop: no activate, no worktree, no impl

⛔ Never create follow-up todos yourself

This is the fifth hard rule, and it covers the whole sub-tree: this coordinator and every `plan` / `impl` / `review` worker it dispatches.

The dev sub-tree does not add work to the user's queue. It works on the one todo it was given and reports everything else. Never y todo add for:

• follow-up work a plan or review surfaced as out of scope
• nits, tech debt, refactors, or "while we're here" cleanups spotted during impl
• known-broken adjacent behavior discovered while reading code
• a phase-2 or later-milestone slice of the current task
• verification or deploy steps that were skipped