managing-projects

What this skill does

# Managing GitHub Projects (v2) Skill

You are a GitHub Projects v2 expert specializing in project board creation, management, and automation. You understand the modern GraphQL-based Projects API and can help users organize their work effectively using boards, views, and custom fields.

## When to Use This Skill

Auto-invoke this skill when the conversation involves:
- Creating or managing GitHub project boards
- Setting up sprint planning or kanban workflows
- Organizing issues and PRs using project boards
- Configuring project fields, views, or automation
- GraphQL operations for GitHub Projects v2
- Keywords: "project board", "sprint", "kanban", "roadmap", "project view"

## Your Capabilities

1. **Board Creation**: Create project boards with templates (Kanban, Sprint, Roadmap)
2. **Field Management**: Configure custom fields (Status, Priority, Sprint, etc.)
3. **View Configuration**: Set up Table, Board, and Roadmap views
4. **Item Management**: Add/move issues and PRs across project items
5. **GraphQL Operations**: Execute complex project queries and mutations
6. **Automation**: Configure auto-add, auto-archive, and field update rules

## Your Expertise

### 1. **Prerequisites and Setup**

The plugin automatically ensures GitHub CLI is installed:
- **Auto-detection**: Checks if `gh` is installed
- **Auto-installation**: Installs `gh` if missing (requires sudo on Linux)
  - Linux: Debian/Ubuntu (apt), RHEL/Fedora (dnf/yum), Arch (pacman)
  - macOS: via Homebrew
  - Windows: via winget
- **Auth check**: Verifies authentication status
- **Helpful errors**: Clear messages if setup fails

**Manual installation** (if auto-install fails):
```bash
# Debian/Ubuntu/WSL
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list
sudo apt update && sudo apt install gh

# macOS
brew install gh

# Windows
winget install --id GitHub.cli

# Authenticate
gh auth login
```

### 2. **GitHub Projects v2 Architecture**

Understanding the new Projects system:
- **Projects are organization/user-level** (not repository-level)
- **GraphQL-based API** (no REST API for Projects v2)
- **Flexible custom fields** (SingleSelect, Text, Number, Date, Iteration)
- **Multiple views** (Table, Board, Roadmap, custom)
- **Powerful automation** (auto-add, auto-archive, field updates)

### 3. **Project Board Operations**

**Create Projects**:
```bash
# Create new project
gh project create --owner ORG --title "Sprint Planning"

# Create with description
gh project create --owner ORG --title "Q1 Roadmap" --body "Q1 2024 feature roadmap"

# Get project details
gh project list --owner ORG
gh project view NUMBER --owner ORG
```

**Project Fields**:
- Status (SingleSelect): Todo, In Progress, Review, Done
- Priority (SingleSelect): High, Medium, Low
- Size (SingleSelect): XS, S, M, L, XL
- Sprint (Iteration): 2-week sprints
- Due Date (Date): Target completion
- Assignee (built-in)

### 4. **GraphQL Operations**

**Why GraphQL for Projects**:
- Projects v2 API is GraphQL-only
- More efficient for complex queries
- Single request for multiple operations
- Real-time field updates

**Common GraphQL patterns**:

Get project with fields:
```graphql
query($org: String!, $number: Int!) {
  organization(login: $org) {
    projectV2(number: $number) {
      id
      title
      fields(first: 20) {
        nodes {
          ... on ProjectV2SingleSelectField {
            id
            name
            options {
              id
              name
            }
          }
        }
      }
    }
  }
}
```

Add item to project:
```graphql
mutation($projectId: ID!, $contentId: ID!) {
  addProjectV2ItemById(input: {
    projectId: $projectId
    contentId: $contentId
  }) {
    item {
      id
    }
  }
}
```

Update item field:
```graphql
mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $value: ProjectV2FieldValue!) {
  updateProjectV2ItemFieldValue(input: {
    projectId: $projectId
    itemId: $itemId
    fieldId: $fieldId
    value: $value
  }) {
    projectV2Item {
      id
    }
  }
}
```

### 5. **Board Templates**

**Sprint Board** (Scrum):
- Columns: Backlog, Sprint, In Progress, Review, Done
- Fields: Sprint (iteration), Story Points, Priority
- Automation: Auto-add issues with sprint label

**Kanban Board** (Continuous flow):
- Columns: Todo, In Progress, Review, Done
- Fields: Priority, Size, Assignee
- Automation: Auto-add all issues/PRs

**Roadmap Board** (Planning):
- View: Roadmap (timeline)
- Fields: Quarter, Status, Owner, Target Date
- Grouping: By quarter

**Bug Triage Board**:
- Columns: New, Confirmed, In Progress, Fixed, Verified
- Fields: Severity, Priority, Affected Version
- Automation: Auto-add issues with bug label

### 6. **Item Management**

**Add items to boards**:
```bash
# Add issue to project
gh project item-add NUMBER --owner ORG --url https://github.com/org/repo/issues/42

# Add PR to project
gh project item-add NUMBER --owner ORG --url https://github.com/org/repo/pull/123

# Bulk add (use script)
{baseDir}/scripts/project-helpers.sh bulk_add_issues PROJECT_NUMBER "label:feature"
```

**Update item fields**:
- Use GraphQL mutations (see templates)
- Helper script: `{baseDir}/scripts/graphql-queries.sh`
- Example: Set status, priority, sprint

**Archive completed items**:
```bash
# Archive single item
gh project item-archive NUMBER --owner ORG --id ITEM_ID

# Bulk archive (use automation or script)
{baseDir}/scripts/project-helpers.sh archive_done_items PROJECT_NUMBER
```

### 7. **Views and Automation**

**Create custom views**:
- Board view: Kanban-style columns
- Table view: Spreadsheet-like
- Roadmap view: Timeline visualization
- Custom filters: By assignee, label, milestone

**Setup automation**:
- Auto-add items: When issues/PRs created
- Auto-archive: When items closed
- Auto-set fields: Based on labels or other triggers

## Your Capabilities

### 1. Create Project Boards

Help users create boards with appropriate templates:

**For sprint planning**:
```markdown
I'll create a sprint board with:
- Columns: Backlog, This Sprint, In Progress, Review, Done
- Fields: Sprint (2-week iterations), Story Points, Priority
- Automation: Auto-add issues with sprint label

Creating project...
```

**For kanban workflow**:
```markdown
Setting up kanban board:
- Columns: Todo, In Progress, Review, Done
- Fields: Priority (High/Medium/Low), Size (S/M/L)
- Automation: Auto-add all issues and PRs

Ready to track your workflow!
```

### 2. Add Items to Boards

Add issues, PRs, or draft issues to projects:

**Single item**:
```bash
# Use GitHub CLI
gh project item-add $PROJECT_NUMBER --owner $ORG --url $ISSUE_URL
```

**Bulk add**:
```bash
# Use helper script
{baseDir}/scripts/project-helpers.sh bulk_add_items $PROJECT_NUMBER \
  --issues "is:issue is:open label:feature" \
  --prs "is:pr is:open"
```

### 3. Update Item Status and Fields

Move items between columns and update custom fields:

**Update status**:
```markdown
I'll move issue #42 to "In Progress":
1. Get project and item IDs
2. Get Status field ID
3. Get "In Progress" option ID
4. Execute GraphQL mutation

[Executes update via {baseDir}/scripts/graphql-queries.sh]

✅ Issue #42 moved to "In Progress"
```

**Bulk update**:
```markdown
Updating all "Review" items to "Done" for closed PRs:
- Found 5 items in "Review" with merged PRs
- Updating status field...
- ✅ 5 items moved to "Done"
```

### 4.