shawn-sandy/create-issue

Create Issue

Open a GitHub or GitLab issue from any context. Always confirms before creating — no issue is ever created without your approval.

Overview

Ingests context from four sources (selection, session, bug, feature), detects the git host, drafts a structured issue body, shows a confirmation gate, then calls gh or glab to create the issue.

Workflow

Phase 0 — Exit plan mode

ExitPlanMode is a deferred tool — load its schema before calling it. Use ToolSearch with select:ExitPlanMode, then call ExitPlanMode. Both steps happen silently with no user-visible output.

Error handling: If ExitPlanMode returns the exact error "You are not in plan mode", treat that as success — plan mode was already off, which is the desired state. Do not abort or surface the error to the user; continue immediately to Phase 1.

Phase 1 — Detect host

Run:

git remote get-url origin

• URL contains github.com → host is GitHub, CLI is gh
• URL contains gitlab.com or gitlab. (self-hosted pattern) → host is GitLab, CLI is glab
• URL is absent, unrecognizable, or any other host (Bitbucket, Azure DevOps, Gitea, etc.) → use AskUserQuestion to ask: "Your remote appears to be on an unrecognized host (<url>). Which issue tracker should I use? (GitHub / GitLab / Other — I'll stop if Other)"

Phase 2 — Pre-flight checks

For GitHub:

gh auth status
gh repo view

For GitLab:

glab auth status
glab repo view

If the CLI is missing or unauthenticated, stop with a helpful message:

• "Run ! gh auth login to authenticate with GitHub, then retry /issue-agent:create-issue."
• "Run ! glab auth login to authenticate with GitLab, then retry /issue-agent:create-issue."

Do not proceed past pre-flight if either check fails.

Phase 3 — Resolve source and type

Before any other parsing, strip --no-open from $ARGUMENTS to avoid it appearing in the issue title or description:

ARGS="${ARGUMENTS/--no-open/}"
ARGS="${ARGS//  / }"  # collapse any double spaces left behind
ARGS="${ARGS## }"     # trim leading space
ARGS="${ARGS%% }"     # trim trailing space

Use $ARGS (not $ARGUMENTS) for all subsequent argument parsing in this phase.

Parse $ARGS for:

• An explicit source keyword: bug, feature, selection, session
• A title/description (everything after the keyword)

If both are missing or ambiguous, ask via AskUserQuestion (batch both questions):

1. "What is the source? (bug / feature / selection / session)"
2. "What is the issue title or brief description?"

Per-source behaviour:

bug — also collect:

node --version
npm --version
git log --oneline -5

Read package.json for relevant deps. Gather reproduction steps, expected vs actual, environment, and any related files via Grep and Glob.

feature — user-story shape. Ask for: goal, acceptance criteria. Grep for related existing components.

selection — treat $ARGUMENTS (everything after the keyword) or the pasted/provided text block as the issue seed. Summarize and structure it.

session — synthesize from the current conversation context: the bug surfaced, the feature discussed, or the TODO identified. State clearly what was synthesized.

Phase 4 — Gather repo context

# Check for duplicates first
gh issue list --search "<title keywords>" --limit 10        # GitHub
glab issue list --search "<title keywords>" --per-page 10   # GitLab

Read CLAUDE.md (if present) for project conventions. Use Grep + Glob to identify related source files to reference in the issue body.

Report any near-duplicate issues found and ask the user to confirm they still want to proceed.

Phase 5 — Draft the issue

Select the matching template from references/:

• bug → bug-report.md
• feature → feature-request.md
• selection or session → general-issue.md

Populate the template:

• Title prefix: [BUG] for bugs, [FEATURE] for features, none for general
• Fill in all sections from gathered context
• Suggest labels based on content (see host-specific flags in references/host-commands.md)

Phase 6 — Confirmation gate

Display the full drafted issue (title, labels, body) and ask via AskUserQuestion:

"Ready to create this issue on [GitHub/GitLab]?

• Create — create the issue now
• Edit — I'll revise before creating (describe what to change)
• Cancel — do not create"

NEVER call gh issue create or glab issue create before the user chooses "Create". If the user chooses "Edit", revise and show the gate again. If "Cancel", stop and confirm no issue was created.

Phase 7 — Create the issue

Refer to references/host-commands.md for the exact flags per CLI (note: --body for GitHub, --description for GitLab).

GitHub:

gh issue create \
  --title "<title>" \
  --body "<body>" \
  --label "<label1>,<label2>"

GitLab:

glab issue create \
  --title "<title>" \
  --description "<body>" \
  --label "<label1>,<label2>"

On failure (auth, missing label, etc.), fall back to the web opener:

gh issue create --web    # GitHub
glab issue create --web  # GitLab

When the --web fallback is used, skip the post-creation browser open below — the user is already in the browser.

After successful CLI creation, open the issue in the browser:

1. Parse the issue number/ID from the CLI output. For GitHub, gh issue create returns the issue URL (e.g. https://github.com/owner/repo/issues/42); extract the trailing integer. For GitLab, glab issue create returns a similar URL.

2. Check whether --no-open appears in $ARGUMENTS:

   echo "$ARGUMENTS" | grep -q -- '--no-open'
   

   If --no-open is present, skip the browser open and proceed directly to Phase 8.

3. If --no-open is absent, open the issue in the browser. Wrap the call in error handling — a failure to open the browser is a non-fatal warning; it must not mask the fact that the issue was created:

   # GitHub
   gh issue view <number> --web 2>/dev/null \
     || echo "Warning: could not open browser — open the issue manually at the URL above."
   
   # GitLab
   glab issue view <id> --web 2>/dev/null \
     || echo "Warning: could not open browser — open the issue manually at the URL above."
   

Phase 8 — Report

Print the issue URL and number. Then indicate what happened with the browser:

• Browser opened: "Opened issue #<number> in your browser."
• --no-open was passed: "Browser open suppressed (--no-open). Issue URL: <url>"
• Browser open failed: "Issue created at <url> — browser could not be opened (see warning above)."

Reference Files

• references/bug-report.md — bug issue body skeleton
• references/feature-request.md — feature request body skeleton
• references/general-issue.md — general/selection/session body skeleton
• references/host-commands.md — gh vs glab command and flag equivalence table