claude custom create github issue command

create-github-issue.md

Create Github Issue

Purpose

This command is used to instruct Claude to generate GitHub issues in the specific house style and structure used by TestifySec. It is optimized for creating clean, actionable, well-structured GitHub issues for engineering planning, with consistent formatting across feat, fix, chore, docs, and epic types.

Command Name

create-github-issue

Invocation Syntax

You can invoke this command and provide additional details after the command, like:

/create-github-issue feat(web): add control family status card

or with more information like:

/create-github-issue we need to fix the bug where clicking on the downnload button doesn't work

Claude must:

1. Immediately enter plan mode when this command is invoked
2. Parse the user input to extract issue type, scope, and description
3. Format the GitHub issue using the exact markdown structure below
4. Use the ExitPlanMode tool to present the formatted issue as the plan
5. Wait for user approval before proceeding
6. After approval, ask for project board selection (default: Engineering #70)
7. Execute the GitHub CLI commands to create the issue

Plan Mode Output Format

In plan mode, Claude must present the issue using this exact structure:

# {type(scope): short description in lowercase}

{Expanded context from user, rewritten as a clear summary. Explain what is being built, changed, or fixed. Be concise but complete. Include motivations and stakeholder context if relevant. Use bullet points where useful.}

## Acceptance Criteria

- [ ] {Itemized criteria, actions, or functional changes that define "done"}
- [ ] {Use checkboxes for each}
- [ ] {Group logically if needed with subheadings}

## Notes (optional)

- {Additional clarifications, decisions, references, or design choices}

Critical: The title format must be {type(scope): description} in all lowercase for GitHub CLI compatibility.

---

Rules & Style Guide

Title Format

• Required pattern: {type(scope): description} in all lowercase
• Supported types: feat, fix, chore, docs, refactor, epic (see .commitlintrc.yaml for complete list)
• Scope format: Parentheses with component name, e.g., (web), (api), (ssp)
• Description: Brief, actionable summary

Content Guidelines

• Use standard markdown heading syntax (#, ##)
• Default to "Acceptance Criteria" for features/fixes, "Requirements" for epics
• Use consistent voice, past tense only for bugs
• Always rewrite user input for clarity, grammar, and consistency
• Include context and motivation, not just what to build

GitHub CLI Requirements

• Title must be passed to --title parameter
• Body content (everything after title) goes to --body parameter
• Project assignment uses --project with board number

---

Examples

Example 1 (feature)

# feat(web): add ssp section to product grid cards

Add a new **System Security Plan (SSP)** section to each product card in the product grid. This section should:

- Display whether an SSP exists for the product
- Include a button labeled "Analyze" to trigger SSP analysis

Also update the glossary to define:
- What "SSP" is
- What "Analyze" means in this context

## Acceptance Criteria

- [ ] Each product card displays SSP status
- [ ] "Analyze" button is present and functional
- [ ] Glossary includes definitions for "SSP" and "Analyze"

Example 2 (chore)

# chore(aws): configure ecr scan policy for sandbox vs prod environments

We hit our ECR scan limits in sandbox, which blocked scan visibility before a release. To avoid this:

- Disable **automatic scanning** in sandbox
- Keep it **enabled** in production to meet AWS Marketplace requirements
- Add a manual scan trigger via CLI or CD pipeline stage in sandbox

## Acceptance Criteria

- [ ] Automatic ECR scanning disabled in sandbox
- [ ] ECR scanning enabled in prod remains untouched
- [ ] CD pipeline optionally supports JIT scan step in sandbox

---

Execution Workflow

Phase 1: Plan Mode

1. Parse Input: Extract type, scope, and description from user input
2. Format Issue: Create GitHub issue using the exact markdown format above
3. Present Plan: Use ExitPlanMode tool with the formatted issue as the plan
4. Wait for Approval: Do not proceed until user explicitly approves

Phase 2: Board Selection

1. Ask for Board: "Which project board should I post this to? (default: Engineering #70)"
2. Handle Response:
   • If user says "default" or "engineering": use board #70
   • If user asks to see options: run gh project list --owner TestifySec
   • If user specifies a board: use that board number

Phase 3: Issue Creation

1. Extract Components:
   • Title: First line of the plan (the # title line)
   • Body: Everything after the title
2. Execute Command: gh issue create --title "<title>" --body "<body>" --project <board-number>
3. Confirm Success: Report the created issue URL to user

GitHub CLI Commands

# List available project boards
gh project list --owner TestifySec

# Create issue on Engineering board (default)
gh issue create --title "feat(web): add new feature" --body "Description..." --project 70

# Create issue on specific board
gh issue create --title "fix(api): resolve bug" --body "Description..." --project <board-number>

Error Handling

• If gh command fails, report the error and ask user to check GitHub CLI authentication
• If project board doesn't exist, list available boards and ask user to select again
• If title format is invalid, reformat according to rules and ask for confirmation

Recap

Use this command whenever you're planning product work, triaging bugs, cleaning up tech debt, or writing internal tooling issues. Claude will clean up your issue in GitHub-ready format, present it for review in plan mode, and then create it on your chosen project board using the GitHub CLI.