create-github-issue

Create GitHub Issue

Create issues on GitHub using the gh CLI. Issues must conform to the project's issue templates.

Prerequisites

The gh CLI must be authenticated (gh auth status).

Issue Templates

This project uses YAML form issue templates. When creating issues, match the template structure so the output aligns with what GitHub renders.

Bug Reports

Do not add a type label automatically. The body must include a User Story, Problem Statement, Impact / Why This Matters, and Acceptance Criteria, followed by bug-specific reproduction steps and environment details. Logs are optional and must be concise and redacted. Apply area or topic labels only when they are clearly known.

gh issue create \
  --title "bug: <concise description>" \
  --body "$(cat <<'EOF'
## User Story

As a <persona>, I want <capability or outcome>, so that <benefit or impact>.

## Problem Statement

<Summarize what is broken or missing in OpenShell's current behavior and when the issue occurs>

## Impact / Why This Matters

<Explain the consequences for users, the current workaround, and why that workaround is insufficient>

## Acceptance Criteria

- [ ] <observable outcome that demonstrates the bug is fixed>

## Reproduction Steps

1. <step>
2. <step>

## Environment

- OpenShell: <version>
- OS: <os>
- Runtime, deployment, or integration: <relevant details>

## Logs

<optional minimal, redacted output>

EOF
)"

Feature Requests

Do not add a type label automatically. The body must include a User Story, Problem Statement, Impact / Why This Matters, Proposed Design, Acceptance Criteria, and Alternatives Considered. The proposed design should define the user-facing workflow and externally observable behavior without prescribing internal implementation. Agent investigation is optional. Apply area or topic labels only when they are clearly known.

gh issue create \
  --title "feat: <concise description>" \
  --body "$(cat <<'EOF'
## User Story

As a <persona>, I want <capability or outcome>, so that <benefit or impact>.

## Problem Statement

<Summarize the capability or behavior missing from OpenShell today>

## Impact / Why This Matters

<Explain what users must do today, why it is insufficient, and the operational cost, risk, blocked workflow, or adoption barrier>

## Proposed Design

<The desired user-facing workflow and externally observable behavior, without prescribing internal implementation>

## Acceptance Criteria

- [ ] <specific, observable outcome>

## Alternatives Considered

<Other user-facing workflows or behaviors considered and why this approach best satisfies the user story>

## Agent Investigation

<Optional findings from codebase exploration>
EOF
)"

Tasks

For internal tasks that don't fit bug/feature templates:

gh issue create \
  --title "<type>: <description>" \
  --body "$(cat <<'EOF'
## Description

<Clear description of the work>

## Context

<Any dependencies, related issues, or background>

## Definition of Done

- [ ] <criterion>
EOF
)"

GitHub built-in issue types (Bug, Feature, Task) should come from the matching issue template when possible, or be set manually afterward. Do not try to emulate them through labels.

Creating an issue does not accept it or queue agent work. Agents never apply state:accepted, the roadmap label, add issues to the roadmap project, or apply agent:plan-requested or agent:implementation-requested. Community issues proceed through triage-issue; a human accepts technically validated work with state:accepted or roadmap placement. The request labels queue work for unattended agents. A user may instead direct an agent to a specific issue; the agent warns about missing expected workflow labels and continues with the requested phase without changing them.

Useful Options

After Creating

The command outputs the issue URL and number.

Display the URL using markdown link syntax so it's easily clickable:

Created issue [#123](https://github.com/OWNER/REPO/issues/123)

Use the issue number to:

• Reference in commits: git commit -m "Fix validation error (fixes #123)"
• Create a branch following project convention: <issue-number>-<description>/<username>