langwatch-kanban

LangWatch Kanban

Manage the LangWatch Kanban GitHub project board (project #5, org: langwatch).

Project Reference

Read the project board reference from memory before doing anything:

• File: /Users/USER/.claude/projects/-Users-hope-workspace-langwatch-workspace-langwatch-saas-langwatch/memory/reference_gh-project.md

This contains all project IDs, field IDs, status option IDs, and GraphQL patterns. Use python3 for all JSON parsing — issue titles with special characters break jq.

Subcommands

Parse $ARGUMENTS to determine which subcommand to run:

sync

Sync the project board so statuses match reality.

1. Page through all project items (100 per page, up to 8 pages) using the GraphQL projectV2.items query
2. Find items where:
   • Issue/PR state is CLOSED or MERGED but project status is NOT Done or Released
3. For each stale item, update the Status field to Done using the updateProjectV2ItemFieldValue mutation
4. Report what was changed:

   Synced N items to Done:
     #123 — Title here (was: In progress)
     #456 — Title here (was: Ready)
   

5. If nothing to sync, say "Board is in sync — no stale items found."

my-board

Show the current user's assigned items grouped by status.

1. Get current user: gh api user --jq .login
2. Page through project items, collecting items where the current user is an assignee
3. Group by status and display:

   ## In progress (3)
   - #123 — Title here [bug]
   - #456 — Title here [feature, scenarios]
   
   ## Ready (2)
   - #789 — Title here [chore]
   
   ## Backlog (5)
   - #101 — Title here
   ...
   

4. Skip Done and Released items
5. Show a count summary at the end

stale

Find items that may be stuck or forgotten.

1. Page through project items
2. Flag items that are:
   • In progress but the issue has had no updates in 14+ days
   • In review but the linked PR has no review activity in 7+ days
   • Blocked with no recent comments explaining why
3. For each flagged item, show:

   #123 — Title [In progress, last updated 21 days ago]
   #456 — Title [Blocked, no comments since 2026-03-01]
   

4. Suggest actions: "Move to Backlog?", "Close as stale?", "Needs attention?"

move <issue-number> <status>

Move an issue to a new status on the board.

1. Parse the issue number and target status from arguments
2. Map status name (case-insensitive) to option ID:
   • backlog → 14fed42e
   • blocked → 131e7d86
   • ready → 12261fbf
   • in-progress / progress → 3264b20e
   • in-review / review → 90b57b27
   • done → 2b388473
   • released → 7717b7ed
   • stale → 9fefdc9d
3. Find the project item ID by paging through items and matching the issue number
4. Update the status field
5. Confirm: Moved #123 to In progress

assign <issue-number>

Assign an issue to the current user and ensure it's on the board.

1. Get current user: gh api user --jq .login
2. Assign the issue: gh issue edit <number> --repo langwatch/langwatch --add-assignee <login>
3. Check if it's on the project board; if not, add it: gh project item-add 5 --owner langwatch --url <issue-url>
4. Confirm: Assigned #123 to <login> and added to LangWatch Kanban

GraphQL Pagination Pattern

Use this python3 pattern for all paginated queries:

import subprocess, json

cursor = None
results = []

for page in range(1, 9):
    after = f', after: "{cursor}"' if cursor else ''
    query = '''{
      organization(login: "langwatch") {
        projectV2(number: 5) {
          items(first: 100''' + after + ''') {
            nodes {
              id
              content {
                ... on Issue { number title state }
                ... on PullRequest { number title state merged }
              }
              fieldValueByName(name: "Status") {
                ... on ProjectV2ItemFieldSingleSelectValue { name }
              }
            }
            pageInfo { hasNextPage endCursor }
          }
        }
      }
    }'''

    result = subprocess.run(
        ['gh', 'api', 'graphql', '-f', f'query={query}'],
        capture_output=True, text=True
    )
    data = json.loads(result.stdout)
    items = data['data']['organization']['projectV2']['items']

    for n in items['nodes']:
        content = n.get('content') or {}
        status = (n.get('fieldValueByName') or {}).get('name', '')
        # ... process each item ...
        results.append({...})

    if not items['pageInfo']['hasNextPage']:
        break
    cursor = items['pageInfo']['endCursor']

Error Handling

• If $ARGUMENTS is empty or unrecognized, show usage:

  Usage: /langwatch-kanban <command> [args]
  
  Commands:
    sync                     Sync closed issues/PRs to Done status
    my-board                 Show your assigned items by status
    stale                    Find stuck or forgotten items
    move <#number> <status>  Move an issue to a new status
    assign <#number>         Assign issue to you and add to board
  
  Statuses: backlog, blocked, ready, in-progress, in-review, done, released, stale
  

• If gh auth status fails, tell the user to run gh auth login
• If a project API call fails, show the error and suggest gh auth refresh -s project

Constants

These are hardcoded from the LangWatch Kanban project:

PROJECT_NUMBER = 5
ORG = "langwatch"
REPO = "langwatch/langwatch"
PROJECT_ID = "PVT_kwDOCL9uOs4BH69J"
STATUS_FIELD_ID = "PVTSSF_lADOCL9uOs4BH69Jzg4iLlU"

STATUS_OPTIONS = {
    "Backlog": "14fed42e",
    "Blocked": "131e7d86",
    "Ready": "12261fbf",
    "In progress": "3264b20e",
    "In review": "90b57b27",
    "Done": "2b388473",
    "Released": "7717b7ed",
    "Stale": "9fefdc9d",
}