project-management

name project-management description GitHub issue and project-board management for the dotnet/msbuild repo. Use when asked to file/triage/update issues, post comments, amend issue bodies, move sprints, bulk-update project board fields, or audit items by sprint/status/assignee. argument-hint Manage issues and project board entries for dotnet/msbuild. 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: # 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: gh auth refresh -s project Common single-issue actions # 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: 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. 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. 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 # 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) 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: 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. 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