devskill 2.0.7 → 2.0.8

package/skills/github-issues/references/projects.md

@@ -0,0 +1,273 @@
+# Projects V2
+
+GitHub Projects V2 is managed via GraphQL. The MCP server provides three tools that wrap the GraphQL API, so you typically don't need raw GraphQL.
+
+## Using MCP tools (preferred)
+
+**List projects:**
+Call `mcp__github__projects_list` with `method: "list_projects"`, `owner`, and `owner_type` ("user" or "organization").
+
+**List project fields:**
+Call `mcp__github__projects_list` with `method: "list_project_fields"` and `project_number`.
+
+**List project items:**
+Call `mcp__github__projects_list` with `method: "list_project_items"` and `project_number`.
+
+**Add an issue/PR to a project:**
+Call `mcp__github__projects_write` with `method: "add_project_item"`, `project_id` (node ID), and `content_id` (issue/PR node ID).
+
+**Update a project item field value:**
+Call `mcp__github__projects_write` with `method: "update_project_item"`, `project_id`, `item_id`, `field_id`, and `value` (object with one of: `text`, `number`, `date`, `singleSelectOptionId`, `iterationId`).
+
+**Delete a project item:**
+Call `mcp__github__projects_write` with `method: "delete_project_item"`, `project_id`, and `item_id`.
+
+## Workflow for project operations
+
+1. **Find the project** — see [Finding a project by name](#finding-a-project-by-name) below
+2. **Discover fields** - use `projects_list` with `list_project_fields` to get field IDs and option IDs
+3. **Find items** - use `projects_list` with `list_project_items` to get item IDs
+4. **Mutate** - use `projects_write` to add, update, or delete items
+
+## Finding a project by name
+
+> **⚠️ Known issue:** `projectsV2(query: "…")` does keyword search, not exact name match, and returns results sorted by recency. Common words like "issue" or "bug" return hundreds of false positives. The actual project may be buried dozens of pages deep.
+
+Use this priority order:
+
+### 1. Direct lookup (if you know the number)
+```bash
+gh api graphql -f query='{
+  organization(login: "ORG") {
+    projectV2(number: 42) { id title }
+  }
+}' --jq '.data.organization.projectV2'
+```
+
+### 2. Reverse lookup from a known issue (most reliable)
+If the user mentions an issue, epic, or milestone that's in the project, query that issue's `projectItems` to discover the project:
+
+```bash
+gh api graphql -f query='{
+  repository(owner: "OWNER", name: "REPO") {
+    issue(number: 123) {
+      projectItems(first: 10) {
+        nodes {
+          id
+          project { number title id }
+        }
+      }
+    }
+  }
+}' --jq '.data.repository.issue.projectItems.nodes[] | {number: .project.number, title: .project.title, id: .project.id}'
+```
+
+This is the most reliable approach for large orgs where name search fails.
+
+### 3. GraphQL name search with client-side filtering (fallback)
+Query a large page and filter client-side for an exact title match:
+
+```bash
+gh api graphql -f query='{
+  organization(login: "ORG") {
+    projectsV2(first: 100, query: "search term") {
+      nodes { number title id }
+    }
+  }
+}' --jq '.data.organization.projectsV2.nodes[] | select(.title | test("(?i)^exact name$"))'
+```
+
+If this returns nothing, paginate with `after` cursor or broaden the regex. Results are sorted by recency so older projects require pagination.
+
+### 4. MCP tool (small orgs only)
+Call `mcp__github__projects_list` with `method: "list_projects"`. This works well for orgs with <50 projects but has no name filter, so you must scan all results.
+
+## Project discovery for progress reports
+
+When a user asks for a progress update on a project (e.g., "Give me a progress update for Project X"), follow this workflow:
+
+1. **Find the project** — use the [finding a project](#finding-a-project-by-name) strategies above. Ask the user for a known issue number if name search fails.
+
+2. **Discover fields** - call `projects_list` with `list_project_fields` to find the Status field (its options tell you the workflow stages) and any Iteration field (to scope to the current sprint).
+
+3. **Get all items** - call `projects_list` with `list_project_items`. For large projects (100+ items), paginate through all pages. Each item includes its field values (status, iteration, assignees).
+
+4. **Build the report** - group items by Status field value and count them. For iteration-based projects, filter to the current iteration first. Present a breakdown like:
+
+   ```
+   Project: Issue Fields (Iteration 42, Mar 2-8)
+   15 actionable items:
+     🎉 Done:        4 (27%)
+     In Review:      3
+     In Progress:    3
+     Ready:          2
+     Blocked:        2
+   ```
+
+5. **Add context** - if items have sub-issues, include `subIssuesSummary` counts. If items have dependencies, note blocked items and what blocks them.
+
+## OAuth Scope Requirements
+
+| Operation | Required scope |
+|-----------|---------------|
+| Read projects, fields, items | `read:project` |
+| Add/update/delete items, change field values | `project` |
+
+**Common pitfall:** The default `gh auth` token often only has `read:project`. Mutations will fail with `INSUFFICIENT_SCOPES`. To add the write scope:
+
+```bash
+gh auth refresh -h github.com -s project
+```
+
+This triggers a browser-based OAuth flow. You must complete it before mutations will work.
+
+## Finding an Issue's Project Item ID
+
+When you know the issue but need its project item ID (e.g., to update its Status), query from the issue side:
+
+```bash
+gh api graphql -f query='
+{
+  repository(owner: "OWNER", name: "REPO") {
+    issue(number: 123) {
+      projectItems(first: 5) {
+        nodes {
+          id
+          project { title number }
+          fieldValues(first: 10) {
+            nodes {
+              ... on ProjectV2ItemFieldSingleSelectValue {
+                name
+                field { ... on ProjectV2SingleSelectField { name } }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}' --jq '.data.repository.issue.projectItems.nodes'
+```
+
+This returns the item ID, project info, and current field values in one query.
+
+## Using GraphQL via gh api (recommended)
+
+Use `gh api graphql` to run GraphQL queries and mutations. This is more reliable than MCP tools for write operations.
+
+**Find a project and its Status field options:**
+```bash
+gh api graphql -f query='
+{
+  organization(login: "ORG") {
+    projectV2(number: 5) {
+      id
+      title
+      field(name: "Status") {
+        ... on ProjectV2SingleSelectField {
+          id
+          options { id name }
+        }
+      }
+    }
+  }
+}' --jq '.data.organization.projectV2'
+```
+
+**List all fields (including iterations):**
+```bash
+gh api graphql -f query='
+{
+  node(id: "PROJECT_ID") {
+    ... on ProjectV2 {
+      fields(first: 20) {
+        nodes {
+          ... on ProjectV2Field { id name }
+          ... on ProjectV2SingleSelectField { id name options { id name } }
+          ... on ProjectV2IterationField { id name configuration { iterations { id startDate } } }
+        }
+      }
+    }
+  }
+}' --jq '.data.node.fields.nodes'
+```
+
+**Update a field value (e.g., set Status to "In Progress"):**
+```bash
+gh api graphql -f query='
+mutation {
+  updateProjectV2ItemFieldValue(input: {
+    projectId: "PROJECT_ID"
+    itemId: "ITEM_ID"
+    fieldId: "FIELD_ID"
+    value: { singleSelectOptionId: "OPTION_ID" }
+  }) {
+    projectV2Item { id }
+  }
+}'
+```
+
+Value accepts one of: `text`, `number`, `date`, `singleSelectOptionId`, `iterationId`.
+
+**Add an item:**
+```bash
+gh api graphql -f query='
+mutation {
+  addProjectV2ItemById(input: {
+    projectId: "PROJECT_ID"
+    contentId: "ISSUE_OR_PR_NODE_ID"
+  }) {
+    item { id }
+  }
+}'
+```
+
+**Delete an item:**
+```bash
+gh api graphql -f query='
+mutation {
+  deleteProjectV2Item(input: {
+    projectId: "PROJECT_ID"
+    itemId: "ITEM_ID"
+  }) {
+    deletedItemId
+  }
+}'
+```
+
+## End-to-End Example: Set Issue Status to "In Progress"
+
+```bash
+# 1. Get the issue's project item ID, project ID, and current status
+gh api graphql -f query='{
+  repository(owner: "github", name: "planning-tracking") {
+    issue(number: 2574) {
+      projectItems(first: 1) {
+        nodes { id project { id title } }
+      }
+    }
+  }
+}' --jq '.data.repository.issue.projectItems.nodes[0]'
+
+# 2. Get the Status field ID and "In Progress" option ID
+gh api graphql -f query='{
+  node(id: "PROJECT_ID") {
+    ... on ProjectV2 {
+      field(name: "Status") {
+        ... on ProjectV2SingleSelectField { id options { id name } }
+      }
+    }
+  }
+}' --jq '.data.node.field'
+
+# 3. Update the status
+gh api graphql -f query='mutation {
+  updateProjectV2ItemFieldValue(input: {
+    projectId: "PROJECT_ID"
+    itemId: "ITEM_ID"
+    fieldId: "FIELD_ID"
+    value: { singleSelectOptionId: "IN_PROGRESS_OPTION_ID" }
+  }) { projectV2Item { id } }
+}'
+```
+```

package/skills/github-issues/references/search.md

@@ -0,0 +1,231 @@
+# Advanced Issue Search
+
+The `search_issues` MCP tool uses GitHub's issue search query format for cross-repo searches, supporting implicit-AND queries, date ranges, and metadata filters (but not explicit OR/NOT operators).
+
+## When to Use Search vs List vs Advanced Search
+
+There are three ways to find issues, each with different capabilities:
+
+| Capability | `list_issues` (MCP) | `search_issues` (MCP) | Advanced search (`gh api`) |
+|-----------|---------------------|----------------------|---------------------------|
+| **Scope** | Single repo only | Cross-repo, cross-org | Cross-repo, cross-org |
+| **Issue field filters** (`field.priority:P0`) | No | No | **Yes** (dot notation) |
+| **Issue type filter** (`type:Bug`) | No | Yes | Yes |
+| **Boolean logic** (AND/OR/NOT, nesting) | No | Yes (implicit AND only) | **Yes** (explicit AND/OR/NOT) |
+| **Label/state/date filters** | Yes | Yes | Yes |
+| **Assignee/author/mentions** | No | Yes | Yes |
+| **Negation** (`-label:x`, `no:label`) | No | Yes | Yes |
+| **Text search** (title/body/comments) | No | Yes | Yes |
+| **`since` filter** | Yes | No | No |
+| **Result limit** | No cap (paginate all) | 1,000 max | 1,000 max |
+| **How to call** | MCP tool directly | MCP tool directly | `gh api` with `advanced_search=true` |
+
+**Decision guide:**
+- **Single repo, simple filters (state, labels, recent updates):** use `list_issues`
+- **Cross-repo, text search, author/assignee, issue types:** use `search_issues`
+- **Issue field values (Priority, dates, custom fields) or complex boolean logic:** use `gh api` with `advanced_search=true`
+
+## Query Syntax
+
+The `query` parameter is a string of search terms and qualifiers. A space between terms is implicit AND.
+
+### Scoping
+
+```
+repo:owner/repo       # Single repo (auto-added if you pass owner+repo params)
+org:github            # All repos in an org
+user:octocat          # All repos owned by user
+in:title              # Search only in title
+in:body               # Search only in body
+in:comments           # Search only in comments
+```
+
+### State & Close Reason
+
+```
+is:open               # Open issues (auto-added: is:issue)
+is:closed             # Closed issues
+reason:completed      # Closed as completed
+reason:"not planned"  # Closed as not planned
+```
+
+### People
+
+```
+author:username       # Created by
+assignee:username     # Assigned to
+mentions:username     # Mentions user
+commenter:username    # Has comment from
+involves:username     # Author OR assignee OR mentioned OR commenter
+author:@me            # Current authenticated user
+team:org/team         # Team mentioned
+```
+
+### Labels, Milestones, Projects, Types
+
+```
+label:"bug"                 # Has label (quote multi-word labels)
+label:bug label:priority    # Has BOTH labels (AND)
+label:bug,enhancement       # Has EITHER label (OR)
+-label:wontfix              # Does NOT have label
+milestone:"v2.0"            # In milestone
+project:github/57           # In project board
+type:"Bug"                  # Issue type
+```
+
+### Missing Metadata
+
+```
+no:label              # No labels assigned
+no:milestone          # No milestone
+no:assignee           # Unassigned
+no:project            # Not in any project
+```
+
+### Dates
+
+All date qualifiers support `>`, `<`, `>=`, `<=`, and range (`..`) operators with ISO 8601 format:
+
+```
+created:>2026-01-01              # Created after Jan 1
+updated:>=2026-03-01             # Updated since Mar 1
+closed:2026-01-01..2026-02-01   # Closed in January
+created:<2026-01-01              # Created before Jan 1
+```
+
+### Linked Content
+
+```
+linked:pr             # Issue has a linked PR
+-linked:pr            # Issues not yet linked to any PR
+linked:issue          # PR is linked to an issue
+```
+
+### Numeric Filters
+
+```
+comments:>10          # More than 10 comments
+comments:0            # No comments
+interactions:>100     # Reactions + comments > 100
+reactions:>50         # More than 50 reactions
+```
+
+### Boolean Logic & Nesting
+
+Use `AND`, `OR`, and parentheses (up to 5 levels deep, max 5 operators):
+
+```
+label:bug AND assignee:octocat
+assignee:octocat OR assignee:hubot
+(type:"Bug" AND label:P1) OR (type:"Feature" AND label:P1)
+-author:app/dependabot          # Exclude bot issues
+```
+
+A space between terms without an explicit operator is treated as AND.
+
+## Common Query Patterns
+
+**Unassigned bugs:**
+```
+repo:owner/repo type:"Bug" no:assignee is:open
+```
+
+**Issues closed this week:**
+```
+repo:owner/repo is:closed closed:>=2026-03-01
+```
+
+**Stale open issues (no updates in 90 days):**
+```
+repo:owner/repo is:open updated:<2026-01-01
+```
+
+**Open issues without a linked PR (needs work):**
+```
+repo:owner/repo is:open -linked:pr
+```
+
+**Issues I'm involved in across an org:**
+```
+org:github involves:@me is:open
+```
+
+**High-activity issues:**
+```
+repo:owner/repo is:open comments:>20
+```
+
+**Issues by type and priority label:**
+```
+repo:owner/repo type:"Epic" label:P1 is:open
+```
+
+## Issue Field Search
+
+> **Reliability warning:** The `field.name:value` search qualifier syntax is experimental and may return 0 results even when matching issues exist. For reliable filtering by field values, use the GraphQL bulk query approach documented in [issue-fields.md](issue-fields.md#searching-by-field-values).
+
+Issue fields can theoretically be searched via the `field.name:value` qualifier using **advanced search mode**. This works in the web UI but results from the API are inconsistent.
+
+### REST API
+
+Add `advanced_search=true` as a query parameter:
+
+```bash
+gh api "search/issues?q=org:github+field.priority:P0+type:Epic+is:open&advanced_search=true" \
+  --jq '.items[] | "#\(.number): \(.title)"'
+```
+
+### GraphQL
+
+Use `type: ISSUE_ADVANCED` instead of `type: ISSUE`:
+
+```graphql
+{
+  search(query: "org:github field.priority:P0 type:Epic is:open", type: ISSUE_ADVANCED, first: 10) {
+    issueCount
+    nodes {
+      ... on Issue { number title }
+    }
+  }
+}
+```
+
+### Issue Field Qualifiers
+
+The syntax uses **dot notation** with the field's slug name (lowercase, hyphens for spaces):
+
+```
+field.priority:P0                  # Single-select field equals value
+field.priority:P1                  # Different option value
+field.target-date:>=2026-04-01     # Date comparison
+has:field.priority                 # Has any value set
+no:field.priority                  # Has no value set
+```
+
+**MCP limitation:** The `search_issues` MCP tool does not pass `advanced_search=true`. You must use `gh api` directly for issue field searches.
+
+### Common Field Search Patterns
+
+**P0 epics across an org:**
+```
+org:github field.priority:P0 type:Epic is:open
+```
+
+**Issues with a target date this quarter:**
+```
+org:github field.target-date:>=2026-04-01 field.target-date:<=2026-06-30 is:open
+```
+
+**Open bugs missing priority:**
+```
+org:github no:field.priority type:Bug is:open
+```
+
+## Limitations
+
+- Query text: max **256 characters** (excluding operators/qualifiers)
+- Boolean operators: max **5** AND/OR/NOT per query
+- Results: max **1,000** total (use `list_issues` if you need all issues)
+- Repo scan: searches up to **4,000** matching repositories
+- Rate limit: **30 requests/minute** for authenticated search
+- Issue field search requires `advanced_search=true` (REST) or `ISSUE_ADVANCED` (GraphQL); not available through MCP `search_issues`

package/skills/github-issues/references/sub-issues.md

@@ -0,0 +1,137 @@
+# Sub-Issues and Parent Issues
+
+Sub-issues let you break down work into hierarchical tasks. Each parent issue can have up to 100 sub-issues, nested up to 8 levels deep. Sub-issues can span repositories within the same owner.
+
+## Recommended Workflow
+
+The simplest way to create a sub-issue is **two steps**: create the issue, then link it.
+
+```bash
+# Step 1: Create the issue and capture its numeric ID
+ISSUE_ID=$(gh api repos/{owner}/{repo}/issues \
+  -X POST \
+  -f title="Sub-task title" \
+  -f body="Description" \
+  --jq '.id')
+
+# Step 2: Link it as a sub-issue of the parent
+# IMPORTANT: sub_issue_id must be an integer. Use --input (not -f) to send JSON.
+echo "{\"sub_issue_id\": $ISSUE_ID}" | gh api repos/{owner}/{repo}/issues/{parent_number}/sub_issues -X POST --input -
+```
+
+**Why `--input` instead of `-f`?** The `gh api -f` flag sends all values as strings, but the API requires `sub_issue_id` as an integer. Using `-f sub_issue_id=12345` will return a 422 error.
+
+Alternatively, use GraphQL `createIssue` with `parentIssueId` to do it in one step (see GraphQL section below).
+
+## Using MCP tools
+
+**List sub-issues:**
+Call `mcp__github__issue_read` with `method: "get_sub_issues"`, `owner`, `repo`, and `issue_number`.
+
+**Create an issue as a sub-issue:**
+There is no MCP tool for creating sub-issues directly. Use the workflow above or GraphQL.
+
+## Using REST API
+
+**List sub-issues:**
+```bash
+gh api repos/{owner}/{repo}/issues/{issue_number}/sub_issues
+```
+
+**Get parent issue:**
+```bash
+gh api repos/{owner}/{repo}/issues/{issue_number}/parent
+```
+
+**Add an existing issue as a sub-issue:**
+```bash
+# sub_issue_id is the numeric issue ID (not the issue number)
+# Get it from the .id field when creating or fetching an issue
+echo '{"sub_issue_id": 12345}' | gh api repos/{owner}/{repo}/issues/{parent_number}/sub_issues -X POST --input -
+```
+
+To move a sub-issue that already has a parent, add `"replace_parent": true` to the JSON body.
+
+**Remove a sub-issue:**
+```bash
+echo '{"sub_issue_id": 12345}' | gh api repos/{owner}/{repo}/issues/{parent_number}/sub_issue -X DELETE --input -
+```
+
+**Reprioritize a sub-issue:**
+```bash
+echo '{"sub_issue_id": 6, "after_id": 5}' | gh api repos/{owner}/{repo}/issues/{parent_number}/sub_issues/priority -X PATCH --input -
+```
+
+Use `after_id` or `before_id` to position the sub-issue relative to another.
+
+## Using GraphQL
+
+**Read parent and sub-issues:**
+```graphql
+{
+  repository(owner: "OWNER", name: "REPO") {
+    issue(number: 123) {
+      parent { number title }
+      subIssues(first: 50) {
+        nodes { number title state }
+      }
+      subIssuesSummary { total completed percentCompleted }
+    }
+  }
+}
+```
+
+**Add a sub-issue:**
+```graphql
+mutation {
+  addSubIssue(input: {
+    issueId: "PARENT_NODE_ID"
+    subIssueId: "CHILD_NODE_ID"
+  }) {
+    issue { id }
+    subIssue { id number title }
+  }
+}
+```
+
+You can also use `subIssueUrl` instead of `subIssueId` (pass the issue's HTML URL). Add `replaceParent: true` to move a sub-issue from another parent.
+
+**Create an issue directly as a sub-issue:**
+```graphql
+mutation {
+  createIssue(input: {
+    repositoryId: "REPO_NODE_ID"
+    title: "Implement login validation"
+    parentIssueId: "PARENT_NODE_ID"
+  }) {
+    issue { id number }
+  }
+}
+```
+
+**Remove a sub-issue:**
+```graphql
+mutation {
+  removeSubIssue(input: {
+    issueId: "PARENT_NODE_ID"
+    subIssueId: "CHILD_NODE_ID"
+  }) {
+    issue { id }
+  }
+}
+```
+
+**Reprioritize a sub-issue:**
+```graphql
+mutation {
+  reprioritizeSubIssue(input: {
+    issueId: "PARENT_NODE_ID"
+    subIssueId: "CHILD_NODE_ID"
+    afterId: "OTHER_CHILD_NODE_ID"
+  }) {
+    issue { id }
+  }
+}
+```
+
+Use `afterId` or `beforeId` to position relative to another sub-issue.