---

name: create-issue description: Creates GitHub issue with task checklist based on architecture documents (specs.md, frontend.md, backend.md). Run after reviewing the planning documents. context: fork agent: general-purpose allowed-tools: Task, Read, Bash, Glob user-invocable: true

Create GitHub Issue

This skill creates a comprehensive GitHub issue with task checklists based on the architecture documents generated during feature planning.

When to Use This

Run this skill after completing the /feature workflow and reviewing the generated documentation:

• docs/features/<feature-name>/specs.md
• docs/features/<feature-name>/frontend.md
• docs/features/<feature-name>/backend.md

Workflow Steps

Step 1: Get Feature Name

If the user provides the feature name with the command:

Copy/create-issue payment-processing

If not provided, try to detect it:

1. Check recent feature directories: ls -lt docs/features/ | head -5
2. Ask the user which feature to create an issue for

Step 2: Verify Architecture Documents Exist

Check that all three required documents exist:

Copyls docs/features/<feature-name>/specs.md
ls docs/features/<feature-name>/frontend.md
ls docs/features/<feature-name>/backend.md

If any are missing:

• Report which documents are missing
• Instruct the user to run /feature <feature-name> first
• Do not proceed

Step 3: Invoke GitHub Expert Agent

Use the Task tool to invoke the github-expert agent in "issue mode":

CopyTask tool with:
- subagent_type: general-purpose
- description: "Create GitHub issue for <feature-name>"
- prompt: "You are now acting as the github-expert agent in ISSUE MODE.

Read the agent instructions at .claude/agents/github-expert.md and follow them precisely.

The feature is '<feature-name>'.

Your task:
1. Read the architecture documents:
   - docs/features/<feature-name>/specs.md
   - docs/features/<feature-name>/frontend.md
   - docs/features/<feature-name>/backend.md

2. Extract information:
   - Feature overview (from specs.md)
   - User stories (from specs.md)
   - Acceptance criteria (from specs.md)
   - Critical frontend files (from frontend.md Critical Files section)
   - Critical backend files (from backend.md Critical Files section)

3. Create a GitHub issue using 'gh issue create' with:
   - Title: 'Feature: <Feature Name>'
   - Body including:
     - Overview
     - User stories
     - Links to architecture docs (relative paths)
     - Implementation checklist (Backend, Frontend, Testing sections)
     - Acceptance criteria

4. Use heredoc for proper markdown formatting:
   gh issue create --title \"...\" --body \"\$(cat <<'EOF'
   [Body content]
   EOF
   )\"

5. Report the issue number and URL

Begin by reading the architecture documents."

Wait for the agent to complete.

Step 4: Report Success

After the agent completes, report to the user:

Success message:

CopyGitHub issue created successfully!

Issue: #<number>
URL: <GitHub URL>

The issue includes:
✓ Feature overview
✓ User stories
✓ Architecture documentation links
✓ Implementation checklist (Backend, Frontend, Testing)
✓ Acceptance criteria

Next steps:
1. Review the issue on GitHub
2. Add any additional context or labels
3. Begin implementation following the architecture docs
4. Use /review-frontend and /review-backend after implementation
5. Use /create-pr when ready to submit

Error Handling

Missing Architecture Documents

If any docs are missing:

CopyError: Missing architecture documents for '<feature-name>'.

Missing files:
- docs/features/<feature-name>/specs.md
- docs/features/<feature-name>/frontend.md

Please run: /feature <feature-name>

This will generate all required architecture documents.

gh CLI Not Available

If gh command is not found:

CopyError: GitHub CLI (gh) is not installed or not authenticated.

Please install and authenticate:
1. Install: brew install gh
2. Authenticate: gh auth login

Then run /create-issue again.

Feature Name Not Provided

If user doesn't provide a feature name:

CopyWhich feature would you like to create an issue for?

Recent features:
- payment-processing
- user-notifications
- chat-system

Or provide a feature name: /create-issue <feature-name>

Important Guidelines

Feature Name Detection

Try to be helpful by detecting the feature name:

1. Check if provided as argument: /create-issue payment-processing
2. Look for recent feature directories (sorted by modification time)
3. If only one recent feature, suggest it
4. If multiple, show list and ask user to choose

Document Validation

Before invoking the agent, verify:

• All three architecture docs exist
• Files are not empty (check file size > 0)
• Files are readable

Issue Format

The github-expert agent will create an issue with:

• Clear title: "Feature: "
• Structured body with sections
• Relative links to docs: docs/features/<feature-name>/specs.md
• Actionable checklists extracted from "Critical Files" sections
• All acceptance criteria as checkboxes

gh CLI Usage

The agent uses gh issue create with:

• --title flag for the title
• --body flag with heredoc for multiline content
• Proper markdown formatting

Example Usage

User command:

Copy/create-issue payment-processing

Your workflow:

1. Verify docs exist
2. Invoke github-expert agent
3. Agent reads all three docs
4. Agent creates issue with gh issue create
5. Report success with issue URL

User command:

Copy/create-issue

Your response:

CopyWhich feature would you like to create an issue for?

Recent features:
- payment-processing (modified 5 minutes ago)
- user-notifications (modified 2 hours ago)

Please specify: /create-issue <feature-name>

Success Criteria

The workflow succeeds when:

• Architecture documents verified to exist
• github-expert agent invoked successfully
• GitHub issue created with proper formatting
• Issue includes all required sections
• Issue URL returned to user
• User informed of next steps

Tone & Style

• Be clear and helpful
• Provide specific error messages
• Show what was created
• Guide user to next steps
• Use checkmarks for completed items

Your role is to ensure the user has a well-structured GitHub issue that serves as a clear roadmap for implementing the feature.