Feature: add structured bug report issue form

[jeffscottward]

Summary

We should add a standardized GitHub bug-report issue form/template for Maestro.

Right now we do not have a structured issue intake flow that consistently asks for the current machine/app state, such as:

• Maestro version
• operating system and version
• install/update method
• reproduction steps
• expected vs actual behavior
• logs, screenshots, or recordings
• whether the issue happens locally, over SSH, in group chat, in Auto Run, etc.

That missing structure makes triage slower and increases back-and-forth with reporters.

Proposal

Add a GitHub issue form under .github/ISSUE_TEMPLATE/ for bug reports that requires the following fields:

Required fields

• Maestro version
• OS / OS version
• Install source
  • release build
  • dev build
  • packaged locally
• Reproduction steps
• Expected behavior
• Actual behavior

Strongly encouraged fields

• Screenshots / screen recording
• Logs or error output
• Agent/provider involved
  • Claude Code
  • Codex
  • OpenCode
  • Factory Droid
  • Terminal
• Whether SSH remote execution was enabled
• Whether it reproduces consistently or intermittently

Optional advanced environment fields

• Node/Electron version if relevant
• Shell used
• Git repo / worktree context
• Remote OS if SSH is involved

Why

Benefits:

• faster triage
• fewer follow-up questions
• more reproducible bug reports
• easier pattern detection across OS/version/install source
• better routing between UI, agent, SSH, and Auto Run issues

Suggested GitHub Forms approach

Instead of a plain markdown template, use GitHub Issue Forms so required fields are enforced.

Possible forms:

• bug_report.yml
• feature_request.yml
• optional config.yml to guide users toward discussions/docs when appropriate

Suggested bug form fields

A good first bug form could ask for:

1. Maestro version
2. Operating system
3. How Maestro was installed
4. What agent/provider was active
5. Whether SSH remote was enabled
6. Steps to reproduce
7. Expected result
8. Actual result
9. Logs / screenshots / additional context

Follow-up idea

Longer term, Maestro could expose a “copy diagnostics” action in-app that generates a safe issue-report block users can paste directly into this form.

[pedramamini]

@jeffscottward perhaps we can extend from the other idea that I think you've got an open PR on, which is the natural language-based issue creation.

[jeffscottward]

@jeffscottward perhaps we can extend from the other idea that I think you've got an open PR on, which is the natural language-based issue creation.

I don't know think that was me but that sounds pretty cool as well. Do you have a link to that? @pedramamini

[pedramamini]

@jeffscottward this one: #491

[jeffscottward]

@pedramamini oh right OK so these are two different things one is a pop-up model in the UI where you can give feedback directly while using maestro and then the other one is a GitHub issue template so they are two different things and one should click into the other

[jeffscottward]

@pedramamini so yes to answer your question. I guess we will need a formal shape for the template and a structured output adherence for the LLM output to fit into that.

[jeffscottward]

@pedramamini so yes to answer your question. I guess we will need a formal shape for the template and a structured output adherence for the LLM output to fit into that.

I forget if the template calls it out but I would imagine a screenshot which could be accompanied too.

And obviously the current state of the logs and I forget who was asking about that today actually about where you store the logs on Mac.

[jeffscottward]

Folding this into PR #491 rather than splitting it out. The branch now adds structured GitHub issue forms under .github/ISSUE_TEMPLATE\ and aligns the in-app feedback-created issue body to the same intake shape (summary, environment, repro/expected/actual or desired outcome, additional context, screenshots).

[jeffscottward]

PR #491 now includes the structured issue-form work for this request. I updated the PR to close #575 on merge so we keep the feedback/intake changes in a single branch.