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

Open
#2,228 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
12/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
github-actions, typescript

Research direction

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.

Written by the indexing model from the issue text.

Description

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)
Dominant language
TypeScript
Stars
3.4k
Forks
516
Avg merge
1d 15h
Merged PRs (30d)
116

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/squad

All issues in github/squad

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.