Project Management for dotnet/msbuild

This skill covers everything you need to manage issues and the project board for the MSBuild repository: querying, commenting, editing, creating issues, and bulk operations on the project board (sprints, status, assignees, etc.).

Where things live

• Repository: dotnet/msbuild — all issues, PRs, and discussions.
• Project board: dotnet/projects/117 — title "MSBuild". This is the canonical project board for the team. Most issues created in dotnet/msbuild are auto-added or manually added here for sprint planning.
• Sprints are tracked via the Sprint iteration field on project 117. Iteration titles use the format 2026 May I, 2026 May II, 2026 June I, etc. (roughly two-week iterations).

> Note: there are/were other auxiliary project boards for specific initiatives. Use project 117 unless the user explicitly points at another one.

Stable identifiers for project 117

| Identifier | Value | |---|---| | Project node ID | PVT_kwDOAIt-yc4ABM5F | | Sprint field ID (iteration) | PVTIF_lADOAIt-yc4ABM5FzgAtMGI |

These IDs are stable but can be re-derived if the project is ever recreated or migrated:

bash
# Project node ID
gh api graphql -f query='{ organization(login:"dotnet") { projectV2(number:117) { id } } }'

# All field IDs (Sprint, Status, Area, Priority, …)
gh project field-list 117 --owner dotnet --format json | jq '.fields[] | {id,name,type}'

Tooling preference

For GitHub work, prefer gh CLI over MCP tools (per repo convention).

• Use gh issue ... for issue-level operations (create / view / comment / edit / close).
• Use gh project ... for project-board CRUD.
• Use gh api graphql for anything gh doesn't expose directly (sprint values per item, project-level field values, bulk reads).

The default gh token may not include the project scope. If a gh project ... write call fails with a scope error, ask the user to run:

bash
gh auth refresh -s project

Common single-issue actions

bash
# View
gh issue view 13315 --repo dotnet/msbuild --json title,body,state,assignees,labels

# Comment (use --body-file to avoid shell-quoting traps with multi-line markdown)
gh issue comment 13315 --repo dotnet/msbuild --body-file ./comment.md

# Amend body (overwrite — there is no append; use view → edit → write)
gh issue edit 13597 --repo dotnet/msbuild --body-file ./new-body.md

# Create
gh issue create --repo dotnet/msbuild --title "Title" --body-file ./body.md

# Add labels / assignees
gh issue edit 13315 --repo dotnet/msbuild --add-label "Area: Server" --add-assignee someuser

When drafting comments / bodies that summarize internal discussions:

• Use neutral, team-voice language ("the team agreed", "open question").
• Scrub names, "X said Y", room/agent identifiers, and anything resembling internal politics.
• Always write to a file and use --body-file. Don't try to inline multi-line markdown.

Querying issue → project field values (sprint, status, project-level assignees)

gh issue view does not return project-board field values. Use GraphQL via the repository → issue → projectItems path:

bash
gh api graphql -f query='
query {
  r: repository(owner:"dotnet", name:"msbuild") {
    issue(number: 13315) {
      id
      projectItems(first: 5) {
        nodes {
          id
          project { number title }
          sprint:  fieldValueByName(name: "Sprint")  { ... on ProjectV2ItemFieldIterationValue   { title iterationId } }
          status:  fieldValueByName(name: "Status")  { ... on ProjectV2ItemFieldSingleSelectValue { name optionId } }
        }
      }
    }
  }
}'

> fieldValueByName returns null when the field has no value set on that item — handle accordingly.

Bulk / board-wide queries

The gh project item-list CLI command has internal limits and is unreliable for large boards (project 117 is in the thousands of items). Use GraphQL with pagination.

python
import subprocess, json

PROJECT_NUMBER = 117
ORG = "dotnet"

results = []
cursor = None
while True:
    after = f', after: "{cursor}"' if cursor else ''
    query = f'''query {{
      organization(login: "{ORG}") {{
        projectV2(number: {PROJECT_NUMBER}) {{
          items(first: 100{after}) {{
            pageInfo {{ hasNextPage endCursor }}
            nodes {{
              id
              fieldValues(first: 20) {{
                nodes {{
                  ... on ProjectV2ItemFieldIterationValue {{
                    field {{ ... on ProjectV2IterationField  {{ name }} }}
                    title
                  }}
                  ... on ProjectV2ItemFieldUserValue {{
                    field {{ ... on ProjectV2Field           {{ name }} }}
                    users(first: 10) {{ nodes {{ login }} }}
                  }}
                  ... on ProjectV2ItemFieldSingleSelectValue {{
                    field {{ ... on ProjectV2SingleSelectField {{ name }} }}
                    name
                  }}
                }}
              }}
              content {{
                ... on Issue        {{ number title }}
                ... on PullRequest  {{ number title }}
                ... on DraftIssue   {{ title }}
              }}
            }}
          }}
        }}
      }}
    }}'''
    try:
        r = subprocess.run(['gh','api','graphql','-f',f'query={query}'],
                           capture_output=True, text=True, check=True)
    except subprocess.CalledProcessError as e:
        raise RuntimeError(f"GraphQL query failed: {e.stderr}") from e
    page = json.loads(r.stdout)['data']['organization']['projectV2']['items']
    for node in page['nodes']:
        sprint = status = None
        assignees = []
        for fv in node.get('fieldValues', {}).get('nodes', []):
            if not fv:                              # null entries for unset fields
                continue
            fname = (fv.get('field') or {}).get('name', '')
            if fname == 'Sprint':
                sprint = fv.get('title')
            elif fname == 'Status':
                status = fv.get('name')
            elif fname == 'Assignees':
                assignees = [u['login'] for u in (fv.get('users') or {}).get('nodes', [])]
        results.append({'id': node['id'], 'sprint': sprint, 'status': status,
                        'assignees': assignees, 'content': node.get('content')})
    if not page['pageInfo']['hasNextPage']:
        break
    cursor = page['pageInfo']['endCursor']

Updating project-board field values

Set a sprint (iteration) — first look up iteration IDs

Iteration IDs are short hex strings (e.g., 303c2425). They are not the same across projects; always look them up from project 117.

bash
gh api graphql -f query='
query {
  node(id: "PVTIF_lADOAIt-yc4ABM5FzgAtMGI") {
    ... on ProjectV2IterationField {
      configuration {
        iterations           { id title startDate }
        completedIterations  { id title startDate }
      }
    }
  }
}' | jq '.data.node.configuration | (.iterations + .completedIterations)[] | {id,title}'

Single-item field update — gh project item-edit

bash
# Iteration / sprint
gh project item-edit \
  --project-id PVT_kwDOAIt-yc4ABM5F \
  --id <PROJECT_ITEM_ID> \
  --field-id PVTIF_lADOAIt-yc4ABM5FzgAtMGI \
  --iteration-id <ITERATION_ID>

# Single-select (Status, Area, Priority): use --single-select-option-id
# Text: --text  | Number: --number  | Date: --date YYYY-MM-DD

Single-item field update — GraphQL mutation (works the same)

bash
gh api graphql -f query='
mutation {
  updateProjectV2ItemFieldValue(input: {
    projectId: "PVT_kwDOAIt-yc4ABM5F",
    itemId:    "<PROJECT_ITEM_ID>",
    fieldId:   "PVTIF_lADOAIt-yc4ABM5FzgAtMGI",
    value:     { iterationId: "<ITERATION_ID>" }
  }) { projectV2Item { id } }
}'

Adding a freshly created issue to project 117

A newly-created issue is not always auto-added. To add and set its sprint:

bash
ISSUE_NODE_ID=$(gh api graphql -f query='
  query { repository(owner:"dotnet",name:"msbuild") { issue(number:13707) { id } } }' \
  | jq -r '.data.repository.issue.id')

ITEM_ID=$(gh api graphql -f query='
  mutation { addProjectV2ItemById(input:{
      projectId:"PVT_kwDOAIt-yc4ABM5F",
      contentId:"'"$ISSUE_NODE_ID"'"
  }) { item { id } } }' | jq -r '.data.addProjectV2ItemById.item.id')

gh api graphql -f query='
  mutation { updateProjectV2ItemFieldValue(input:{
      projectId:"PVT_kwDOAIt-yc4ABM5F",
      itemId:"'"$ITEM_ID"'",
      fieldId:"PVTIF_lADOAIt-yc4ABM5FzgAtMGI",
      value:{iterationId:"<ITERATION_ID>"}
  }) { projectV2Item { id } } }'

Common errors and gotchas

1. Field 'fieldValueByName' has an argument conflict

gh api graphql --paginate (and several jq-style aliases) re-uses field names. If you call fieldValueByName(name:"Sprint") and fieldValueByName(name:"Status") in the same selection set without aliases, you'll get:

Field 'fieldValueByName' has an argument conflict: {name:"Sprint"} or {name:"Status"}?

Fix: alias each call.

graphql
sprint: fieldValueByName(name: "Sprint")  { ... }
status: fieldValueByName(name: "Status")  { ... }

2. gh api graphql --paginate produces concatenated JSON, not one document

Each page is emitted as a separate JSON object on stdout; piping straight into jq fails with "Invalid numeric literal". Either:

• paginate manually in a loop (preferred for large reads), or
• use jq --slurp to read the stream as an array.

3. "Selections can't be made directly on unions"

field on a project field value is a union; you can't select name directly. Use a typed inline fragment per concrete field type (ProjectV2Field, ProjectV2IterationField, ProjectV2SingleSelectField, …).

4. Issue-level assignees ≠ project-board "Assignees" column

The board's "No Assignees" slice is driven by the project-level Assignees field, not by Issue.assignees. They can diverge. When filtering by board state, always read ProjectV2ItemFieldUserValue from fieldValues.

5. null entries in fieldValues.nodes

GraphQL returns null for items where a particular field is unset. Always guard if not fv: continue before dereferencing.

6. DraftIssue items lack number / repository

content may be a DraftIssue that only exposes title, body, assignees. Code that joins to issue numbers must handle None.

7. gh project item-list is unreliable for large boards

It silently truncates. Always use the GraphQL pagination loop above instead.

8. Missing project scope on gh token

Reads work; writes (gh project item-edit, the addProjectV2ItemById / updateProjectV2ItemFieldValue mutations) fail. Have the user run gh auth refresh -s project.

9. gh issue edit --body overwrites — there is no append

To "append" to a body, fetch with gh issue view --json body, append, write back with --body-file. For status updates, prefer a comment.

Sanitization checklist for comments / body edits

When summarizing meetings or chat threads into GitHub:

• ✅ Use team voice ("the team agreed", "open question", "follow-up needed").
• ✅ Keep objective, decision-relevant content (problem statement, scope, exit criteria, repro steps, numbers).
• ❌ No personal names or "X said / Y replied".
• ❌ No full email addresses of external contributors (use GitHub handles instead).
• ❌ No internal-only identifiers (room names, recording IDs, agent fleet identifiers, partner-team contractor names).
• ❌ No speculation about other teams' motives or anything resembling internal politics.
• ❌ No confidential roadmap dates or unreleased product details unless already public.
• Always show the user the proposed comment / body before posting (unless they've explicitly preapproved).

Common workflows

| Goal | Sketch | |---|---| | Add a status comment to N issues | for n in 13315 13702 …; do gh issue comment $n --repo dotnet/msbuild --body-file ./c-$n.md; done | | Replace a one-line issue body with a full Context / Exit-criteria / Out-of-scope spec | gh issue edit <n> --repo dotnet/msbuild --body-file ./body.md | | Move all unassigned items from sprint X to sprint Y | GraphQL pagination loop above + gh project item-edit --iteration-id per item | | File a new issue and put it in the current sprint | gh issue create → addProjectV2ItemById → updateProjectV2ItemFieldValue | | Audit "what's in the current sprint that has no owner" | GraphQL pagination loop, filter on Sprint == "<current>" and empty Assignees |