droboticflow/docs/agents/issue-tracker.md

2.5 KiB
Raw Blame History

Issue tracker: Local Markdown

Issues and specs live as Markdown files in .scratch/.

Conventions

  • One feature per directory: .scratch/<feature-slug>/.
  • Spec: .scratch/<feature-slug>/spec.md.
  • One file per implementation ticket: .scratch/<feature-slug>/issues/<NN>-<slug>.md, numbered from 01.
  • Record triage state as a Status: line near the top. Use the role strings in triage-labels.md.
  • Append discussion under ## Comments.

Publish and fetch

To publish a spec or ticket to the local tracker (whether invoked by a skill or directly), create the corresponding file under .scratch/<feature-slug>/, creating directories as needed.

To fetch a ticket, read the referenced Markdown file under .scratch/<feature-slug>/.

Wayfinding operations

  • Map: .scratch/<effort>/map.md, with Notes, Decisions-so-far, and Fog.
  • Child ticket: .scratch/<effort>/issues/NN-<slug>.md.
  • Record ticket type with Type: research, prototype, grilling, or task.
  • Record dependencies with Blocked by: NN, NN.
  • A ticket is unblocked when every listed dependency is resolved.
  • Select open, unblocked, unclaimed tickets in numeric order.
  • Claim a ticket by saving Status: claimed before starting work.
  • Resolve it by appending ## Answer, setting Status: resolved, and adding a summary and link to the map's Decisions-so-far section.

The claimed and resolved statuses describe wayfinding execution; they are separate from the five triage roles.

多代理同分支协作(2026-10-14 复盘沉淀)

一次特性中三个修复代理被误判死亡后"复活",同一 worktree 出现三写者;以下协议让下次不再临场发明:

  1. 判死先验尸:send_message 返回 "not found" 只算未知,不等于死亡。宣布同分支代理死亡前,必查其 worktree:git log(有无新提交)、git status(有无在途编辑)、文件 mtime、ps(go test / vite 等门禁进程)。探针失灵而代理存活的案例已发生两次。
  2. 车道分工:同分支多代理必须在票面 Comments 写"车道认领"——每道声明文件域(文件路径清单)、认领注记先落提交。共享文件规则:先落者赢,后到者 rebase 保双意图;跑门禁要干净树时用 stash(挂名 lane-<x>),跑完弹回。
  3. 协调走票面:子代理间 send_message 不可靠;票文件是唯一可靠信道。协调者指令(分工令/追问/背书)一律写进 ## Comments 并提交,代理开工前先读票尾。