Git Issue Plan Workflow

What I do

I implement a standardized GitHub issue creation and planning workflow:

1. Gather Issue Requirements: Prompt user for structured issue description following industry best practices
2. Determine Issue Scope: Ask if issue needs to be broken into sub-issues
3. Create GitHub Issue: Use GitHub CLI to create issue with appropriate labels
4. Create Git Branch: Generate branch from issue number (e.g., GIT-123)
5. Generate PLAN file: Create comprehensive plan with phases and todo list in PLANS/ directory
6. Commit and Push: Commit PLAN file with semantic formatting and push to remote
7. Prompt Execution: Ask user if they want to proceed with plan execution

Framework Skills Used

This workflow delegates to these framework skills for specialized functionality:

When to use me

Use this workflow when:

• Starting a new development task tracked in GitHub Issues
• You want a standardized approach to issue creation and planning
• You need to break down large work into structured phases
• Following the practice of planning before implementation

Prerequisites

• GitHub CLI (gh) installed and authenticated
• Git repository initialized with GitHub remote
• Write access to repository
• gh auth status shows valid authentication

Steps

Step 1: Gather Issue Description

Prompt the user for a structured issue description with these sections:

Required Information:

1. Title: Concise title (max 72 characters)
2. Overview: Brief description of what needs to be done
3. Acceptance Criteria: Definition of done (bullet points)
4. Scope: Files or areas affected
5. Technical Notes: Implementation considerations (optional)

Prompt Template:

Please provide the following for your GitHub issue:

1. **Title** (required): Brief title for the issue
   Example: "Implement user authentication API"

2. **Overview** (required): What does this issue accomplish?
   Example: "Add JWT-based authentication endpoints for user login/registration"

3. **Acceptance Criteria** (required): How do we know it's done?
   Example:
   - Users can register with email/password
   - Users can login and receive JWT token
   - Protected routes validate JWT

4. **Scope** (required): What files/areas will be affected?
   Example: src/api/auth/, src/middleware/, tests/auth/

5. **Technical Notes** (optional): Any implementation details?
   Example: Use bcrypt for password hashing, 24h token expiry

Step 2: Determine Issue Scope

Ask user to choose issue complexity:

Question: "Should this be broken into smaller sub-issues?"

Options:

• Parent with Sub-issues: Creates a parent issue, then prompts for sub-issues
• Single Issue: Creates one issue for contained work

Parent Issue Flow:

If Parent selected:
1. Create parent issue
2. Prompt for sub-issues (repeat until done):
   - Sub-issue title
   - Sub-issue description
3. Create each sub-issue and link to parent
4. Branch name uses parent issue number (e.g., GIT-123)

Single Issue Flow:

If Single selected:
1. Create single issue with appropriate labels
2. Branch name uses issue number (e.g., GIT-124)

Step 3: Determine Labels

Delegate to git-issue-labeler skill for intelligent label assessment:

# Use git-issue-labeler to determine appropriate labels
# The skill analyzes issue content and assigns GitHub default labels
# See: skills/git-issue-labeler/SKILL.md

Available Labels (handled by git-issue-labeler):

• bug - Something isn't working
• enhancement - New feature or request
• documentation - Improvements or additions to documentation
• good first issue - Good for newcomers
• help wanted - Extra attention is needed
• question - Further information is requested
• invalid - This doesn't seem right
• wontfix - This will not be worked on
• duplicate - This issue or pull request already exists
• major, minor, patch - Semantic versioning labels

Integration Pattern:

After user provides issue description:
1. Combine title + overview + technical notes into issue content
2. Invoke git-issue-labeler skill to analyze and assign labels
3. Use returned labels in gh issue create command

Step 4: Create GitHub Issue(s)

For Single Issue:

ISSUE_URL=$(gh issue create \
  --title "$TITLE" \
  --body "$FORMATTED_BODY" \
  --label "$LABELS" \
  --assignee @me)

# Extract issue number
ISSUE_NUMBER=$(echo "$ISSUE_URL" | grep -oE '[0-9]+$')

For Parent with Sub-issues:

# Create parent issue first
PARENT_URL=$(gh issue create \
  --title "$TITLE" \
  --body "$FORMATTED_BODY" \
  --label "$LABELS" \
  --assignee @me)

PARENT_NUMBER=$(echo "$PARENT_URL" | grep -oE '[0-9]+$')

# Create each sub-issue
for subissue in "${SUBISSUES[@]}"; do
  gh issue create \
    --title "$subissue.title" \
    --body "$subissue.body\n\nParent: #$PARENT_NUMBER" \
    --label "$subissue.labels" \
    --assignee @me
done

Formatted Body Template:

## Overview
$OVERVIEW

## Acceptance Criteria
$ACCEPTANCE_CRITERIA

## Scope
$SCOPE

## Technical Notes
$TECHNICAL_NOTES

---
*Created with git-issue-plan-workflow*

Step 5: Create Git Branch

Branch Naming Convention:

• Use issue number: GIT-123 (required format)
• All uppercase, no spaces
• Pattern: GIT-{ISSUE_NUMBER}

# Check for uncommitted changes
if ! git diff-index --quiet HEAD --; then
  echo "Warning: You have uncommitted changes"
  read -p "Continue anyway? (y/n): " CONTINUE
  [ "$CONTINUE" != "y" ] && exit 1
fi

# Create and checkout branch
git checkout -b "GIT-$ISSUE_NUMBER"

echo "✓ Created branch: GIT-$ISSUE_NUMBER"

Step 6: Generate PLAN file

File Location: All PLAN files are stored in the PLANS/ directory at the project root.

• GitHub issues: PLANS/PLAN-GIT-{ISSUE_NUMBER}.md (e.g., PLANS/PLAN-GIT-123.md)

PLANS Folder Check:

# Check if PLANS directory exists, create if not
if [ ! -d "PLANS" ]; then
  mkdir -p PLANS
  echo "✓ Created PLANS directory"
fi

Create comprehensive PLAN file with phases and todos:

Template:

# Plan: $ISSUE_TITLE

## Issue Reference
- **Number**: #$ISSUE_NUMBER
- **URL**: $GITHUB_URL/issues/$ISSUE_NUMBER
- **Labels**: $LABELS

## Overview
$OVERVIEW

## Acceptance Criteria
- [ ] $CRITERION_1
- [ ] $CRITERION_2
- [ ] $CRITERION_3

## Scope
$SCOPE

---

## Implementation Phases

### Phase 1: Setup & Analysis
- [ ] Review existing codebase for affected areas
- [ ] Identify dependencies and potential conflicts
- [ ] Set up development environment if needed
- [ ] Create feature flags (if applicable)

### Phase 2: Core Implementation
- [ ] Implement primary functionality
- [ ] Add error handling and edge cases
- [ ] Update affected modules/components
- [ ] Add logging and monitoring

### Phase 3: Testing
- [ ] Write unit tests for new functionality
- [ ] Write integration tests
- [ ] Perform manual testing
- [ ] Test edge cases and error scenarios

### Phase 4: Documentation & Cleanup
- [ ] Update code documentation/docstrings
- [ ] Update README if applicable
- [ ] Remove debug code and comments
- [ ] Code review preparation

### Phase 5: Final Validation
- [ ] Run all tests (unit, integration, e2e)
- [ ] Verify acceptance criteria met
- [ ] Performance testing (if applicable)
- [ ] Security review (if applicable)

---

## Technical Notes
$TECHNICAL_NOTES

## Dependencies
_List any external dependencies or blocked-by issues_

## Risks & Mitigation
_Identify potential risks and how to mitigate them_

## Success Metrics
_How will we measure success?_

Step 7: Commit and Push PLAN file

Use git-semantic-commits skill for proper commit message formatting:

# Check if PLANS directory exists, create if not
if [ ! -d "PLANS" ]; then
  mkdir -p PLANS
  echo "Created PLANS directory"
fi

# Stage PLAN file
git add "PLANS/PLAN-GIT-${ISSUE_NUMBER}.md"

# Format commit message using git-semantic-commits pattern
# Type: docs (documentation), Scope: plan, Subject: descriptive
# See: skills/git-semantic-commits/SKILL.md
COMMIT_MSG="docs(plan): add PLAN-GIT-${ISSUE_NUMBER}.md for issue #$ISSUE_NUMBER

Plan file created for issue #$ISSUE_NUMBER tracking implementation phases."

git commit -m "$COMMIT_MSG"

# Push to remote
git push -u origin "GIT-$ISSUE_NUMBER"

echo "✓ Committed and pushed PLANS/PLAN-GIT-${ISSUE_NUMBER}.md"

Semantic Commit Format:

• Type: docs (PLAN files are documentation)
• Scope: plan (identifies plan-related commits)
• Subject: Describes the PLAN file added
• Body: Optional additional context

Step 8: Update Issue with Initial Progress

Use git-issue-updater skill to add progress comment to GitHub issue:

# Use git-issue-updater for consistent issue progress updates
# See: skills/git-issue-updater/SKILL.md

# Format progress update following git-issue-updater standards
gh issue comment "$ISSUE_NUMBER" --body "## Planning Complete - $(date '+%Y-%m-%d %H:%M')

**Branch**: \`GIT-$ISSUE_NUMBER\`
**PLAN File**: \`PLANS/PLAN-GIT-${ISSUE_NUMBER}.md\`
**Status**: Ready to begin execution

### Completed
- [x] GitHub issue created
- [x] Branch created and checked out
- [x] PLAN file generated with implementation phases
- [x] Initial commit pushed to remote

### Next Steps
1. Review \`PLANS/PLAN-GIT-${ISSUE_NUMBER}.md\`
2. Begin Phase 1: Setup & Analysis

---
*Tracking progress with git-issue-plan-workflow*"

git-issue-updater Integration: For subsequent commits, use git-issue-updater skill to maintain consistent progress tracking with user, date, time, and file statistics.

Step 9: Prompt for Plan Execution

Ask user if they want to proceed:

✓ GitHub issue created: #$ISSUE_NUMBER
✓ Branch created and checked out: GIT-$ISSUE_NUMBER
✓ PLANS/PLAN-GIT-${ISSUE_NUMBER}.md committed and pushed

Would you like to proceed with executing the plan?
- Yes: Start with Phase 1 tasks
- No: Stop here and execute manually later

[If Yes]: Begin executing todo items from PLANS/PLAN-GIT-${ISSUE_NUMBER}.md
[If No]: Workflow complete. Run tasks manually when ready.

Best Practices

Issue Description

• Be specific: "Add JWT authentication" vs "Add auth"
• Include context: Why is this needed?
• Define done: Clear acceptance criteria
• Limit scope: One feature/fix per issue

Labels

• Use appropriate labels for discoverability
• bug vs enhancement distinction
• help wanted for community contributions
• good first issue for newcomers

Branch Naming

• Use GIT-{number} format for traceability
• Keep it consistent with PLAN file naming

PLAN File Structure

• Start with phases for large work
• Each phase has clear todo items
• Todos are actionable and verifiable
• Include success criteria

Commit Messages

• Use semantic commits: docs(plan):, feat:, fix:
• Reference issue number in message
• Keep first line under 72 chars

Common Issues

GitHub CLI Not Authenticated

Issue: gh command fails with auth error

Solution:

gh auth login
gh auth status

Cannot Create Issue

Issue: Permission denied or repo not found

Solution:

• Verify repository URL: git remote -v
• Check user has write access
• Ensure repository exists on GitHub

Branch Already Exists

Issue: Branch with same name exists

Solution:

# Switch to existing branch
git checkout "GIT-$ISSUE_NUMBER"

# Or force create new
git checkout -B "GIT-$ISSUE_NUMBER"

Push Rejected

Issue: Remote has updates

Solution:

git pull --rebase origin main
git push -u origin "GIT-$ISSUE_NUMBER"

Sub-issue Linking

Issue: Cannot create linked sub-issues

Solution:

• Reference parent manually in body: "Parent: #123"
• Use GitHub's task lists for hierarchical tracking
• Consider using Projects for complex hierarchies

Troubleshooting Checklist

Before starting:

• GitHub CLI authenticated: gh auth status
• Git repository initialized
• Remote repository configured
• Working directory clean

After issue creation:

• Issue number captured
• Issue accessible via URL
• Labels assigned correctly
• Sub-issues created (if parent)

After branch creation:

• Branch name includes issue number
• Branch checked out successfully

After PLAN file:

• File created in PLANS/ directory
• All sections populated
• Phases have actionable todos
• Acceptance criteria listed

After commit/push:

• PLAN file committed with semantic message
• Branch pushed to remote
• GitHub issue updated with progress

Example Usage

User: Create a GitHub issue for adding user authentication

Agent: I'll help you create a GitHub issue. Please provide:

1. **Title**: [Brief title, max 72 chars]
2. **Overview**: [What this issue accomplishes]
3. **Acceptance Criteria**: [Definition of done]
4. **Scope**: [Files/areas affected]
5. **Technical Notes**: [Implementation details, optional]

User: 
1. Implement user authentication API
2. Add JWT-based authentication endpoints
3. Users can register, login, logout. Protected routes work.
4. src/api/auth/, src/middleware/
5. Use bcrypt, 24h token expiry

Agent: Should this be broken into smaller sub-issues?
- Parent with Sub-issues
- Single Issue

User: Single Issue

Agent: Labels detected: enhancement
Creating issue...

✓ Created GitHub issue: #456
✓ Created branch: GIT-456
✓ Created PLANS/PLAN-GIT-456.md with 5 phases
✓ Committed and pushed to remote

Proceed with plan execution? (yes/no)

GitHub vs JIRA Comparison

Converted and distributed by TomeVault — claim your Tome and manage your conversions.