Make the lifecycle issue the interface: status dashboard, checkbox decisions, Mermaid plans, one run per command

オープン
#2,228 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
12/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
活発
技術スタック
github-actions, typescript

調査の方向性

This is a design proposal, not a single change: it spans the workflow triggers, comment and dashboard rendering, and decision parsing. Start by reading the existing squad command workflows and the code that posts the lifecycle table, then decide the dashboard markers and the decision-card format with the maintainer. Done means the acceptance checklist in the issue body is met, which needs agreement on the design first.

索引モデルが issue の本文から書いたものです。

説明

enhancement post-2.0 type:feature

Problem

Running a proposal through research → triage → plan → activate on octodemo/zava-social-cao-ops-20261014152823#3 showed that the issue is hard to read and to act on:

  • No feedback after a command. The only signal was a 👀 reaction that never changed. Commands were re-sent 2–4 times each, so a 4-phase lifecycle used 10 commands. Two research runs failed with nothing posted.
  • Preconditions aren't checked. /squad triage with no research artifact produced nothing at all, not even a rejection.
  • The lifecycle table isn't trustworthy. It's buried mid-thread and edited silently, the Plan link renders as a placeholder (#aw_eSi0hpoM), Activation never updates, and its JSON is empty ("phases":[]).
  • Decisions were resolved without the human. The plan said "Decisions Needed #1–#4 … are resolved as design choices … no additional decision-gate step is required". D2's acceptance criteria point to "the level of fidelity chosen in Decision #2", which nobody chose.
  • IDs and references break. "Decision #1" auto-links to issue #1. Items are relabelled at every stage (Rn / # / Item N).
  • Dependency graphs are ASCII (1 → 2 → 3) and don't show that decisions gate work items.
  • Too many commands and too much noise. There are long copy-paste commands in the body, five "next step" options (including /squad plan program), a repeated footer, and open "Structured data" JSON.
  • Hidden deadlines. Evidence expiry (expires_at, 24 h) appears only in the JSON.

Constraints (verified against GitHub's documentation and renderer)

  • GitHub strips <button>, <form>, <style> and <script>, so a real click-to-run button isn't possible.
  • Reactions have no Actions trigger. Comment boxes can't be prefilled from a link, and neither can workflow_dispatch inputs.
  • Mermaid (including classDef styling), callout alerts (> [!IMPORTANT] etc.), task-list checkboxes, <details>, tables and images all render in issues.
  • Every checkbox tick fires issues: edited. To conserve runs, Squad must not subscribe to issues: edited. Even a run that immediately skips still counts as a run.

Proposal

1. A status dashboard at the top of the issue body

The bot rewrites only the block between <!-- squad:dashboard:start --> and <!-- squad:dashboard:end -->, and the original proposal stays below it, unchanged. The dashboard shows:

  • the proposal and phase progress
  • one next action in a > [!IMPORTANT] callout
  • evidence expiry in a > [!WARNING] callout
  • the work items table and a Mermaid dependency graph
  • links to artifacts and to the Cast PR, with its merge state
  • collapsed sections for the lifecycle map, run history, provenance/cost/JSON, and other proposals

The bot re-reads the body immediately before writing it.

2. Decisions as checkbox cards; ticking is free and the existing command submits them
  • Each decision gets one checkbox per option, with ⭐ marking Squad's recommendation. Use stable IDs (D1, W1, R1) and never #N.
  • Ticking a box starts no run, because there's no issues: edited trigger.
  • There's no separate submit step. The next phase command (e.g. /squad activate, or /squad plan if decisions come out of triage) reads the current body. It then:
    • checks that the person who sent the command has write access, so the command is their approval
    • echoes the resolved answers back ("D1 = A, D2 = B, …")
    • stops with a clear message if a decision has no box ticked or more than one
  • Decisions are never answered automatically. Optionally, use userContentEdits to flag ticks made by someone without write access.
  • Body text is still untrusted input. Authority comes from the command and the sender's permission check, never from markers or checkboxes alone.
3. Mermaid instead of ASCII
  • Plans render a flowchart with decision nodes, work items coloured by state and owner via classDef, and out-of-scope follow-ups shown dashed.
  • A stateDiagram-v2 lifecycle map goes in a collapsed section.
4. One status comment per command, edited as the run progresses
  • Post it within seconds, then update it in place: 👀 received → ⏳ running (step x of y, run link) → ✅ done (link to the artifact) or ❌ failed (cause, "nothing changed", retry command).
  • A precondition failure gets a one-line ⛔ rejection with the command to run instead.
  • If a duplicate command arrives while a run is in progress, say "merged into this run" instead of starting another.
  • Optionally, move the reaction along 👀 → 🚀 → ✅/😕.
  • Limit concurrent runs to one per issue so duplicates can't race.
5. Less noise
  • Shorten commands to /squad research P1.
  • Make each artifact end with one next step that links to the dashboard.
  • Collapse the footer, the "add this workflow" ad and the structured JSON into <details>.
  • Use one set of size labels everywhere (S/M/L).
  • Pair risk emoji with text so it isn't conveyed by colour alone.
Optional: fewer runs
  • Chain research → triage → plan from a single command and stop at the first point where human input is needed. This saves 2 runs per proposal, at the cost of no chance to redirect between phases.
  • Put the decision cards in triage's output, so /squad plan uses the human's answers instead of guessing them.

Run budget

Today (#3) Proposed
Runs started by commands for one proposal 10 (re-sends) 4 (or 2 if phases are chained)
Runs started by checkbox ticks n/a 0

Acceptance

  • A dashboard section in the issue body is kept current and is the only place that shows "next action"
  • Decisions are checkbox cards with stable IDs; the phase command reads, validates and echoes them; incomplete answers block the phase
  • No workflow trigger on issues: edited
  • Plans and lifecycle use Mermaid instead of ASCII
  • Each command gets one status comment updated in place, covering success, failure and precondition rejection
  • Duplicate commands are merged and acknowledged, never run in parallel
  • Broken references fixed (#aw_… placeholder, #N used for decisions)
主要言語
TypeScript
スター
3.4k
フォーク
516
平均マージ
1日 15時間
マージ済み PR(30日)
116

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

github/squad のほかの issue

github/squad の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。