UX: Add onboarding quickstart and menu integration (#281)

* Document a minimal onboarding flow for first-run usability

This spec captures a one-time quickstart buffer attached to the
main menu so new users can start a session and use the three core
commands without hunting through the full feature surface.

Constraint: Must improve discoverability without adding a second workflow system
Rejected: Multi-step setup wizard | too interruptive for Emacs-native users
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep onboarding focused on first-minute actions; do not let it expand into general help docs
Tested: Spec self-review against brainstorming reviewer checklist
Not-tested: Live Emacs UI behavior and implementation details

* Add onboarding quickstart and menu integration

* add missing files. add design doc

* add screenshot

* Add GitHub CI checks review mode and tests

* turn off approval suggestion

* Request author voice in PR description prompt

* Persist onboarding seen state and restore context

* fix test

* update HISTORY

Author: tninja

.gitignore

@@ -8,3 +8,5 @@ GPATH
 __pycache__/
 *.elc
 .ai-behaviors/
+.omx/
+flycheck_*

HISTORY.org

@@ -2,6 +2,8 @@
 * Release history
 
 ** Main branch change
+- UX: Add onboarding quickstart and menu integration
+  - Also improve the Github PR action feature. It can look into CI checks status and provide analysis
 - Feat: Add diagnostics mcp support with Flycheck and Flymake
 - Fix: Add SPDX header and commentary tests for autoloads
   - Also added unit-test CI workflow

README.org

@@ -72,6 +72,10 @@ First 60 seconds:
 - `C-c a q`: Ask question only (no code change)
 - `C-c a z`: Jump back to AI session buffer
 
+The first time you open `C-c a`, AI Code also shows a small quickstart buffer
+with these core actions. You can reopen it later from `C-c a h`
+(`Help / Quick Start`).
+
 ** Installation
 
 Enable installation of packages from MELPA by adding an entry to package-archives after (require 'package) and before the call to package-initialize in your init.el or .emacs file:
@@ -306,6 +310,10 @@ With the built-in =get_diagnostics= MCP tool, the loop can move further left:
 - treat completion as /no new diagnostics/ on the touched files relative to the baseline, instead of requiring the entire project to be clean
 - use tests as the next sensor in the loop, not the first one
 
+Screenshot:
+
+[[file:./emacs_mcp_tool_diagnosis.png]]
+
 The benefit is practical:
 
 - faster feedback after each AI code change
@@ -315,6 +323,12 @@ The benefit is practical:
 
 This is why features such as `ai-code-auto-test-type` and `ai-code-tdd-cycle` fit the idea of harness engineering: they turn testing and follow-up into part of the system, not an afterthought in each prompt.
 
+Nit: During using auto test feature, I prefer to turn off the approval request from AI, it will make the whole process more smooth. Eg. for Codex CLI, it is
+
+#+begin_src emacs-lisp
+(setq ai-code-codex-cli-program-switches '("-a" "never"))
+#+end_src
+
 - Relevant article: [[https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html][Harness Engineering]]
 
 *** Desktop Notifications (Experimental)

ai-code-autoloads.el

@@ -912,6 +912,21 @@ Navigate using the clickable symbol clicked by mouse EVENT.
 
 (fn EVENT)" t)
 (register-definition-prefixes "ai-code-session-link" '("ai-code-"))
+
+
+;;; Generated autoloads from ai-code-onboarding.el
+
+(defvar ai-code-onboarding-auto-show t "\
+When non-nil, show the quickstart automatically for first-run usage.")
+(custom-autoload 'ai-code-onboarding-auto-show "ai-code-onboarding" t)
+(defvar ai-code-onboarding-seen nil "\
+Whether the user has already seen the onboarding quickstart.")
+(custom-autoload 'ai-code-onboarding-seen "ai-code-onboarding" t)
+(autoload 'ai-code-onboarding-open-quickstart "ai-code-onboarding" "\
+Open the onboarding quickstart buffer." t)
+(autoload 'ai-code-onboarding-disable-auto-show "ai-code-onboarding" "\
+Disable future auto-display of the onboarding quickstart." t)
+(register-definition-prefixes "ai-code-onboarding" '("ai-code-onboarding-"))
 
 ;;; End of scraped data
 

ai-code-backends.el

@@ -11,7 +11,7 @@
 
 (require 'seq)
 
-(require 'ai-code-git) 
+(require 'ai-code-git)
 
 (defvar ai-code-cli)
 (defvar claude-code-terminal-backend)
@@ -20,6 +20,7 @@
 (declare-function claude-code--term-send-string "claude-code" (backend string))
 (declare-function ai-code--validate-git-repository "ai-code-git" ())
 (declare-function ai-code--git-root "ai-code-file" (&optional dir))
+(declare-function ai-code-onboarding-show-backend-switch-hint "ai-code-onboarding" ())
 (declare-function ai-code-read-string "ai-code-input" (prompt &optional initial-input candidate-list))
 
 (defvar ai-code--cli-start-fn #'ai-code--unsupported-start)
@@ -450,13 +451,13 @@ Sets backend dispatch functions and updates `ai-code-cli'."
       ;; inform user to install it.
       (when (and feature (not (featurep feature)))
         (user-error
-         "Backend '%s' is not available. Please install the package providing '%s' and try again"
+         "Backend '%s' is not available.  Please install the package providing '%s' and try again"
          label (symbol-name feature)))
       (let ((missing-fns (seq-filter (lambda (fn) (not (fboundp fn)))
                                      (list start switch send))))
         (when missing-fns
           (user-error
-           "Backend '%s' is not available (missing functions: %s). Please install the package providing '%s'"
+           "Backend '%s' is not available (missing functions: %s).  Please install the package providing '%s'"
            label
            (mapconcat #'symbol-name missing-fns ", ")
            (symbol-name feature))))
@@ -511,7 +512,9 @@ invoke `ai-code-cli-resume'; otherwise call `ai-code-cli-start'."
                                   (mapcar #'car ordered-choices)
                                   nil t nil nil current-label))
          (key (cdr (assoc choice ordered-choices))))
-    (ai-code-set-backend key)))
+    (ai-code-set-backend key)
+    (when (fboundp 'ai-code-onboarding-show-backend-switch-hint)
+      (ai-code-onboarding-show-backend-switch-hint))))
 
 ;;;###autoload
 (defun ai-code-open-backend-config ()

ai-code-git.el

@@ -106,6 +106,7 @@ Issue Investigation Steps:
   "Build PR description prompt for REVIEW-SOURCE with PR-URL."
   (let ((source-instruction
          (ai-code--pull-or-review-source-instruction review-source)))
+    ;; DONE: Update the prompt to make the description sound like it's written by the author/maintainer, and keep it concise.
     (format "Prepare a pull request description for: %s
 
 %s
@@ -114,24 +115,49 @@ PR Description Steps:
 1. Add a summary of the problem and the approach taken in the PR.
 2. Highlight the most important code changes and user-visible impact.
 3. Add a testing section with relevant verification details.
-4. Format the result as a concise PR description ready to share with reviewers."
+4. Format the result as a concise PR description ready to share with reviewers,
+   written in the voice of the author or maintainer."
+            pr-url source-instruction)))
+
+(defun ai-code--build-pr-ci-check-init-prompt (review-source pr-url)
+  "Build CI checks review prompt for REVIEW-SOURCE with PR-URL."
+  (let ((source-instruction
+         (ai-code--pull-or-review-source-instruction review-source 'review-ci-checks)))
+    (format "Review GitHub CI checks for pull request: %s
+
+%s
+
+CI Checks Review Steps:
+1. Review the GitHub CI checks for this pull request.
+2. If there is a failing or error state, inspect the failing checks and relevant details.
+3. Analyze the likely root cause of each failure.
+4. No need to make code change. Provide analysis only."
             pr-url source-instruction)))
 
 (defun ai-code--pull-or-review-source-instruction (review-source &optional review-mode)
   "Return source instruction string for REVIEW-SOURCE and REVIEW-MODE."
-  (if (eq review-mode 'investigate-issue)
-      (pcase review-source
-        ('github-mcp
-         "Use GitHub MCP server to inspect the GitHub issue and relevant repository context.")
-        ('gh-cli
-         "Use gh CLI tool to inspect the GitHub issue and relevant repository context.")
-        (_ "Investigate this GitHub issue using the repository as context."))
-    (pcase review-source
-      ('github-mcp
-       "Use GitHub MCP server to fetch pull request details and review comments.")
-      ('gh-cli
-       "Use gh CLI tool to fetch pull request details and review comments.")
-      (_ "Review this pull request."))))
+  (pcase review-mode
+    ('investigate-issue
+     (pcase review-source
+       ('github-mcp
+        "Use GitHub MCP server to inspect the GitHub issue and relevant repository context.")
+       ('gh-cli
+        "Use gh CLI tool to inspect the GitHub issue and relevant repository context.")
+       (_ "Investigate this GitHub issue using the repository as context.")))
+    ('review-ci-checks
+     (pcase review-source
+       ('github-mcp
+        "Use GitHub MCP server to fetch pull request details and CI checks.")
+       ('gh-cli
+        "Use gh CLI tool to fetch pull request details and CI checks.")
+       (_ "Review the GitHub CI checks for this pull request.")))
+    (_
+     (pcase review-source
+       ('github-mcp
+        "Use GitHub MCP server to fetch pull request details and review comments.")
+       ('gh-cli
+        "Use gh CLI tool to fetch pull request details and review comments.")
+       (_ "Review this pull request.")))))
 
 (defun ai-code--pull-or-review-url-prompt (review-mode)
   "Return the URL prompt string for REVIEW-MODE."
@@ -153,6 +179,7 @@ PR Description Steps:
   (let* ((review-mode-alist '(("Review the PR" . review-pr)
                               ("Check unresolved feedback" . check-feedback)
                               ("Investigate issue" . investigate-issue)
+                              ("Review GitHub CI checks" . review-ci-checks)
                               ("Prepare PR description" . prepare-pr-description)))
          (review-mode (completing-read "Select analysis mode (PR or issue): "
                                        review-mode-alist
@@ -162,15 +189,18 @@ PR Description Steps:
 
 (defun ai-code--build-pr-init-prompt (review-source target-url review-mode)
   "Build initial prompt for REVIEW-SOURCE, TARGET-URL and REVIEW-MODE."
+  ;; DONE: add an option here: review github CI checks. If there is error, look into them and figure out root cause. Only provide analysis, no need to change code.
   (pcase review-mode
-    ('investigate-issue
-     (ai-code--build-issue-investigation-init-prompt review-source target-url))
-    ('check-feedback
-     (ai-code--build-pr-feedback-check-init-prompt review-source target-url))
-    ('prepare-pr-description
-     (ai-code--build-pr-description-init-prompt review-source target-url))
-    (_
-     (ai-code--build-pr-review-init-prompt review-source target-url))))
+   ('investigate-issue
+    (ai-code--build-issue-investigation-init-prompt review-source target-url))
+   ('check-feedback
+    (ai-code--build-pr-feedback-check-init-prompt review-source target-url))
+   ('review-ci-checks
+    (ai-code--build-pr-ci-check-init-prompt review-source target-url))
+   ('prepare-pr-description
+    (ai-code--build-pr-description-init-prompt review-source target-url))
+   (_
+    (ai-code--build-pr-review-init-prompt review-source target-url))))
 
 ;;;###autoload
 (defun ai-code-pull-or-review-diff-file ()
@@ -724,7 +754,9 @@ If not inside a Git repository, do nothing."
                                      "GTAGS"
                                      "GRTAGS"
                                      "GPATH"
-                                     "__pycache__/"))
+                                     "__pycache__/"
+                                     "*.elc"
+                                     "flycheck_*"))
              (gitignore-content (when (file-exists-p gitignore-path)
                                   (with-temp-buffer
                                     (insert-file-contents gitignore-path)