ai: add gh-issue command to help diagnose GitHub issues (#8526)

This enables agents (namely Amp) to use `/gh-issue <number/url>` to
begin diagnosing a GitHub issue, explaining the problem, and suggesting
a plan of action. This action explicitly prompts the AI to not write
code.

**You can run this manually too,** for testing or curiosity or for
pasting into another LLM. Execute it like any other script:
`.agents/command/gh-issue <issue>`

I've used this manually for months with good results, so now I'm
formalizing it in the repo for other contributors.

Example diagnosing #8523:

https://ampcode.com/threads/T-3e26e8cc-83d1-4e3c-9b5e-02d9111909a7

**I'm going to be highly selective about integrating repository-level
commands.** I think guiding AI contributors in the right direction is
going to result in less AI slop being sent to us. But I want to only add
commands that maintainers use and also can vouch for. The best way to
vouch is to share something like an Amp thread link that shows it
working on real data.

Ironically, no AI was used to write this PR. I did consult Claude Chat
for help on some Nu syntax, but verified it manually with the Nu manual.

.agents/commands/gh-issue

@@ -0,0 +1,64 @@
+#!/usr/bin/env nu
+
+# A command to generate an agent prompt to diagnose and formulate 
+# a plan for resolving a GitHub issue.
+#
+# IMPORTANT: This command is prompted to NOT write any code and to ONLY
+# produce a plan. You should still be vigilant when running this but that
+# is the expected behavior.
+# 
+# The `<issue>` parameter can be either an issue number or a full GitHub
+# issue URL.
+def main [
+  issue: any, # Ghostty issue number or URL
+  --repo: string = "ghostty-org/ghostty" # GitHub repository in the format "owner/repo"
+] {
+  # TODO: This whole script doesn't handle errors very well. I actually
+  # don't know Nu well enough to know the proper way to handle it all.
+  
+  let issueData = gh issue view $issue --json author,title,number,body,comments | from json
+  let comments = $issueData.comments | each { |comment|
+    $"
+### Comment by ($comment.author.login)
+($comment.body)
+" | str trim
+  } | str join "\n\n"
+
+  $"
+Deep-dive on this GitHub issue. Find the problem and generate a plan. 
+Do not write code. Explain the problem clearly and propose a comprehensive plan 
+to solve it.
+
+# ($issueData.title) \(($issueData.number)\)
+
+## Description
+($issueData.body)
+
+## Comments
+($comments)
+
+## Your Tasks
+
+You are an experienced software developer tasked with diagnosing issues.
+
+1. Review the issue context and details. 
+2. Examine the relevant parts of the codebase. Analyze the code thoroughly
+   until you have a solid understanding of how it works.
+3. Explain the issue in detail, including the problem and its root cause.
+4. Create a comprehensive plan to solve the issue. The plan should include:
+   - Required code changes
+   - Potential impacts on other parts of the system
+   - Necessary tests to be written or updated
+   - Documentation updates
+   - Performance considerations
+   - Security implications
+   - Backwards compatibility \(if applicable\)
+   - Include the reference link to the source issue and any related discussions
+4. Think deeply about all aspects of the task. Consider edge cases, potential
+   challenges, and best practices for addressing the issue. Review the plan 
+   with the oracle and adjust it based on its feedback.
+
+**ONLY CREATE A PLAN. DO NOT WRITE ANY CODE.** Your task is to create
+a thorough, comprehensive strategy for understanding and resolving the issue.
+" | str trim
+}

CONTRIBUTING.md

@@ -45,11 +45,16 @@ work than any human. That isn't the world we live in today, and in most cases
 it's generating slop. I say this despite being a fan of and using them
 successfully myself (with heavy supervision)!
 
+When using AI assistance, we expect contributors to understand the code
+that is produced and be able to answer critical questions about it. It
+isn't a maintainers job to review a PR so broken that it requires
+significant rework to be acceptable.
+
 Please be respectful to maintainers and disclose AI assistance.
 
 ## Quick Guide
 
-### I'd like to contribute!
+### I'd like to contribute
 
 [All issues are actionable](#issues-are-actionable). Pick one and start
 working on it. Thank you. If you need help or guidance, comment on the issue.
@@ -58,7 +63,7 @@ Issues that are extra friendly to new contributors are tagged with
 
 ["contributor friendly"]: https://github.com/ghostty-org/ghostty/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22contributor%20friendly%22
 
-### I'd like to translate Ghostty to my language!
+### I'd like to translate Ghostty to my language
 
 We have written a [Translator's Guide](po/README_TRANSLATORS.md) for
 everyone interested in contributing translations to Ghostty.
@@ -67,7 +72,7 @@ and you can submit pull requests directly, although please make sure that
 our [Style Guide](po/README_TRANSLATORS.md#style-guide) is followed before
 submission.
 
-### I have a bug! / Something isn't working!
+### I have a bug! / Something isn't working
 
 1. Search the issue tracker and discussions for similar issues. Tip: also
    search for [closed issues] and [discussions] — your issue might have already
@@ -82,18 +87,18 @@ submission.
 [discussions]: https://github.com/ghostty-org/ghostty/discussions?discussions_q=is%3Aclosed
 ["Issue Triage" discussion]: https://github.com/ghostty-org/ghostty/discussions/new?category=issue-triage
 
-### I have an idea for a feature!
+### I have an idea for a feature
 
 Open a discussion in the ["Feature Requests, Ideas" category](https://github.com/ghostty-org/ghostty/discussions/new?category=feature-requests-ideas).
 
-### I've implemented a feature!
+### I've implemented a feature
 
 1. If there is an issue for the feature, open a pull request straight away.
 2. If there is no issue, open a discussion and link to your branch.
 3. If you want to live dangerously, open a pull request and
    [hope for the best](#pull-requests-implement-an-issue).
 
-### I have a question!
+### I have a question
 
 Open an [Q&A discussion], or join our [Discord Server] and ask away in the
 `#help` channel.

HACKING.md

@@ -36,7 +36,7 @@ here:
 | `zig build test`                | Runs unit tests (accepts `-Dtest-filter=<filter>` to only run tests whose name matches the filter)                     |
 | `zig build update-translations` | Updates Ghostty's translation strings (see the [Contributor's Guide on Localizing Ghostty](po/README_CONTRIBUTORS.md)) |
 | `zig build dist`                | Builds a source tarball                                                                                                |
-| `zig build distcheck`           | Installs and validates a source tarball                                                                                |
+| `zig build distcheck`           | Builds and validates a source tarball                                                                                  |
 
 ## Extra Dependencies
 
@@ -69,6 +69,32 @@ sudo xcode-select --switch /Applications/Xcode-beta.app
 > You do not need to be running on macOS 26 to build Ghostty, you can
 > still use Xcode 26 beta on macOS 15 stable.
 
+## AI and Agents
+
+If you're using AI assistance with Ghostty, Ghostty provides an
+[AGENTS.md file](https://github.com/ghostty-org/ghostty/blob/main/AGENTS.md)
+read by most of the popular AI agents to help produce higher quality
+results.
+
+We also provide commands in `.agents/commands` that have some vetted
+prompts for common tasks that have been shown to produce good results.
+We provide these to help reduce the amount of time a contributor has to
+spend prompting the AI to get good results, and hopefully to lower the slop
+produced.
+
+- `/gh-issue <number/url>` - Produces a prompt for diagnosing a GitHub
+  issue, explaining the problem, and suggesting a plan for resolving it.
+  Requires `gh` to be installed with read-only access to Ghostty.
+
+> [!WARNING]
+>
+> All AI assistance usage [must be disclosed](https://github.com/ghostty-org/ghostty/blob/main/CONTRIBUTING.md#ai-assistance-notice)
+> and we expect contributors to understand the code that is produced and
+> be able to answer questions about it. If you don't understand the
+> code produced, feel free to disclose that, but if it has problems, we
+> may ask you to fix it and close the issue. It isn't a maintainers job to
+> review a PR so broken that it requires significant rework to be acceptable.
+
 ## Linting
 
 ### Prettier

nix/devShell.nix

@@ -3,6 +3,7 @@
   lib,
   stdenv,
   bashInteractive,
+  nushell,
   appstream,
   flatpak-builder,
   gdb,
@@ -124,6 +125,9 @@ in
         # CI
         uv
 
+        # Scripting
+        nushell
+
         # We need these GTK-related deps on all platform so we can build
         # dist tarballs.
         blueprint-compiler