Project Board Enforcement

Overview

The GitHub Project board is THE source of truth for all work state. Not labels. Not comments. Not memory. The project board.

Core principle: If it's not in the project board with correct fields, it doesn't exist.

This skill is called by other skills at gate points. It is not invoked directly.

API Optimization Requirement

CRITICAL: All read operations MUST use cached data from github-api-cache.

The following environment variables MUST be set before using this skill:

• GH_CACHE_ITEMS - Cached project items JSON
• GH_CACHE_FIELDS - Cached project fields JSON
• GH_PROJECT_ID - Project node ID
• GH_STATUS_FIELD_ID - Status field ID
• GH_STATUS_*_ID - Status option IDs

If these are not set, invoke session-start first to initialize the cache.

The Rule

Every issue, epic, and initiative MUST be in the project board BEFORE work begins.

This is not optional. This is not a suggestion. This is a hard gate.

Required Environment

# These MUST be set. Work cannot proceed without them.
echo $GITHUB_PROJECT      # Full URL: https://github.com/users/USER/projects/N
echo $GITHUB_PROJECT_NUM  # Just the number: N
echo $GH_PROJECT_OWNER    # Owner: @me or org name

If any are missing, stop and configure them before proceeding.

Project Field Requirements

Mandatory Fields

Every project MUST have these fields configured:

Field	Type	Required Values
Status	Single select	Backlog, Ready, In Progress, In Review, Done, Blocked
Type	Single select	Feature, Bug, Chore, Research, Spike, Epic, Initiative
Priority	Single select	Critical, High, Medium, Low

Recommended Fields

Field	Type	Purpose
Verification	Single select	Not Verified, Failing, Partial, Passing
Criteria Met	Number	Count of completed acceptance criteria
Criteria Total	Number	Total acceptance criteria
Last Verified	Date	When verification last ran
Epic	Text	Parent epic issue number
Initiative	Text	Parent initiative issue number

Verification Functions

All read operations use cached data (0 API calls). Only writes require API calls.

Verify Issue in Project

GATE FUNCTION - Called before any work begins. 0 API calls (uses cache).

verify_issue_in_project() {
  local issue=$1

  # Get project item ID FROM CACHE (0 API calls)
  ITEM_ID=$(echo "$GH_CACHE_ITEMS" | jq -r ".items[] | select(.content.number == $issue) | .id")

  if [ -z "$ITEM_ID" ] || [ "$ITEM_ID" = "null" ]; then
    echo "BLOCKED: Issue #$issue is not in the project board."
    echo ""
    echo "Add it with:"
    echo "  gh project item-add $GITHUB_PROJECT_NUM --owner $GH_PROJECT_OWNER --url \$(gh issue view $issue --json url -q .url)"
    return 1
  fi

  echo "$ITEM_ID"
  return 0
}

Verify Status Field Set

GATE FUNCTION - Called before work proceeds past issue check. 0 API calls (uses cache).

verify_status_set() {
  local issue=$1
  local item_id=$2

  # Get current status FROM CACHE (0 API calls)
  STATUS=$(echo "$GH_CACHE_ITEMS" | jq -r ".items[] | select(.id == \"$item_id\") | .status.name")

  if [ -z "$STATUS" ] || [ "$STATUS" = "null" ]; then
    echo "BLOCKED: Issue #$issue has no Status set in project board."
    echo ""
    echo "Set status before proceeding."
    return 1
  fi

  echo "$STATUS"
  return 0
}

Add Issue to Project

Called by issue-prerequisite after issue creation. 1 API call + cache refresh.

add_issue_to_project() {
  local issue_url=$1

  # Add to project (1 API call - unavoidable write)
  gh project item-add "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" --url "$issue_url"

  if [ $? -ne 0 ]; then
    echo "ERROR: Failed to add issue to project."
    return 1
  fi

  # Refresh cache after adding (1 API call)
  export GH_CACHE_ITEMS=$(gh project item-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" --format json)

  # Get the item ID from refreshed cache
  local issue_num=$(echo "$issue_url" | grep -oE '[0-9]+$')
  ITEM_ID=$(echo "$GH_CACHE_ITEMS" | jq -r ".items[] | select(.content.number == $issue_num) | .id")

  echo "$ITEM_ID"
  return 0
}

Set Project Status

Called at every status transition. 1 API call (uses cached IDs).

set_project_status() {
  local item_id=$1
  local new_status=$2  # Backlog, Ready, In Progress, In Review, Done, Blocked

  # Use cached IDs (0 API calls for lookups)
  # GH_PROJECT_ID, GH_STATUS_FIELD_ID set by session-start

  # Get option ID from cache
  local option_id
  case "$new_status" in
    "Backlog")     option_id="$GH_STATUS_BACKLOG_ID" ;;
    "Ready")       option_id="$GH_STATUS_READY_ID" ;;
    "In Progress") option_id="$GH_STATUS_IN_PROGRESS_ID" ;;
    "In Review")   option_id="$GH_STATUS_IN_REVIEW_ID" ;;
    "Done")        option_id="$GH_STATUS_DONE_ID" ;;
    "Blocked")     option_id="$GH_STATUS_BLOCKED_ID" ;;
    *)
      # Fallback: look up from cached fields (0 API calls)
      option_id=$(echo "$GH_CACHE_FIELDS" | jq -r ".fields[] | select(.name == \"Status\") | .options[] | select(.name == \"$new_status\") | .id")
      ;;
  esac

  if [ -z "$option_id" ] || [ "$option_id" = "null" ]; then
    echo "ERROR: Status '$new_status' not found in project."
    return 1
  fi

  # Single API call to update status
  gh project item-edit --project-id "$GH_PROJECT_ID" --id "$item_id" \
    --field-id "$GH_STATUS_FIELD_ID" --single-select-option-id "$option_id"

  return $?
}

Set Project Type

Called when creating issues. 1 API call (uses cached IDs).

set_project_type() {
  local item_id=$1
  local type=$2  # Feature, Bug, Chore, Research, Spike, Epic, Initiative

  # Get type field ID and option from cache (0 API calls)
  local type_field_id=$(echo "$GH_CACHE_FIELDS" | jq -r '.fields[] | select(.name == "Type") | .id')
  local option_id=$(echo "$GH_CACHE_FIELDS" | jq -r ".fields[] | select(.name == \"Type\") | .options[] | select(.name == \"$type\") | .id")

  if [ -z "$option_id" ] || [ "$option_id" = "null" ]; then
    echo "ERROR: Type '$type' not found in project."
    return 1
  fi

  # Single API call to update type
  gh project item-edit --project-id "$GH_PROJECT_ID" --id "$item_id" \
    --field-id "$type_field_id" --single-select-option-id "$option_id"
}

State Queries via Project Board

All queries use cached data. 0 API calls.

Get Issues by Status

USE THIS instead of label queries. 0 API calls (uses cache).

get_issues_by_status() {
  local status=$1  # Ready, In Progress, etc.

  # Use cached data (0 API calls)
  echo "$GH_CACHE_ITEMS" | jq -r ".items[] | select(.status.name == \"$status\") | .content.number"
}

# Examples:
# get_issues_by_status "Ready"
# get_issues_by_status "In Progress"
# get_issues_by_status "Blocked"

Get Issues by Type

0 API calls (uses cache).

get_issues_by_type() {
  local type=$1  # Epic, Feature, etc.

  echo "$GH_CACHE_ITEMS" | jq -r ".items[] | select(.type.name == \"$type\") | .content.number"
}

Get Epic Children

0 API calls (uses cache).

get_epic_children() {
  local epic_num=$1

  echo "$GH_CACHE_ITEMS" | jq -r ".items[] | select(.epic == \"#$epic_num\") | .content.number"
}

Count by Status

0 API calls (uses cache).

count_by_status() {
  local status=$1

  echo "$GH_CACHE_ITEMS" | jq "[.items[] | select(.status.name == \"$status\")] | length"
}

Gate Points

These are the points in workflows where project board verification is MANDATORY:

Workflow Point	Gate	Skill
Before any work	Issue in project	issue-driven-development Step 1
After issue creation	Add to project, set fields	issue-prerequisite
Starting work	Status → In Progress	issue-driven-development Step 6
Creating branch	Verify project membership	branch-discipline
PR created	Status → In Review	pr-creation
Work complete	Status → Done	issue-driven-development completion
Blocked	Status → Blocked	error-recovery
Epic created	Add epic to project, set Type=Epic	epic-management
Child issue created	Add to project, link to parent	issue-decomposition

Transition Rules

Valid Status Transitions

Backlog ──► Ready ──► In Progress ──► In Review ──► Done
    │         │            │              │
    │         │            │              │
    └─────────┴────────────┴──────────────┴──► Blocked
                                               │
                                               ▼
                                        (any previous state)

Transition Enforcement

validate_transition() {
  local current=$1
  local target=$2

  case "$current→$target" in
    "Backlog→Ready"|"Ready→In Progress"|"In Progress→In Review"|"In Review→Done")
      return 0 ;;
    *"→Blocked")
      return 0 ;;
    "Blocked→Backlog"|"Blocked→Ready"|"Blocked→In Progress")
      return 0 ;;
    *)
      echo "Invalid transition: $current → $target"
      return 1 ;;
  esac
}

Labels vs Project Board

WRONG - Do Not Use Labels for State

# WRONG - labels are NOT the source of truth
gh issue list --label "status:pending"
gh issue edit 123 --add-label "status:in-progress"

RIGHT - Use Project Board

# RIGHT - project board IS the source of truth
get_issues_by_status "Ready"
set_project_status "$ITEM_ID" "In Progress"

When Labels Are Acceptable

Labels are still used for:

• epic - Identifying epic issues (supplementary)
• epic-[name] - Grouping issues in an epic (supplementary)
• spawned-from:#N - Lineage tracking (supplementary)
• review-finding - Origin tracking (supplementary)

But state (Ready, In Progress, Blocked, etc.) lives in the project board.

Sync Verification

Run periodically to detect drift. 0 API calls (uses cache).

verify_project_sync() {
  echo "## Project Board Sync Check"
  echo ""

  # Check for issues with branches but Status != In Progress (0 API calls)
  echo "### Issues with branches but not 'In Progress':"
  for branch in $(git branch -r | grep -E 'feature/[0-9]+' | sed 's/.*feature\///' | cut -d- -f1); do
    # Use cached data instead of API call
    status=$(echo "$GH_CACHE_ITEMS" | jq -r ".items[] | select(.content.number == $branch) | .status.name")

    if [ "$status" != "In Progress" ] && [ "$status" != "In Review" ]; then
      echo "- #$branch: Status='$status' but has active branch"
    fi
  done

  # Check for In Progress issues with no recent activity (0 API calls)
  echo ""
  echo "### 'In Progress' issues with no recent commits:"
  for issue in $(get_issues_by_status "In Progress"); do
    branch=$(git branch -r | grep -E "feature/$issue-" | head -1)
    if [ -z "$branch" ]; then
      echo "- #$issue: In Progress but no branch exists"
    fi
  done
}

Error Messages

All project board errors should be clear and actionable:

project_error() {
  local code=$1
  local context=$2

  case "$code" in
    "NOT_IN_PROJECT")
      echo "BLOCKED: Issue $context is not in the project board."
      echo "Fix: gh project item-add $GITHUB_PROJECT_NUM --owner $GH_PROJECT_OWNER --url \$(gh issue view $context --json url -q .url)"
      ;;
    "NO_STATUS")
      echo "BLOCKED: Issue $context has no Status field set."
      echo "Fix: Update the issue's Status field in the project board."
      ;;
    "INVALID_TRANSITION")
      echo "BLOCKED: Cannot transition $context - invalid state change."
      ;;
    "PROJECT_NOT_FOUND")
      echo "BLOCKED: Project $GITHUB_PROJECT_NUM not found or not accessible."
      echo "Fix: Verify GITHUB_PROJECT_NUM and GH_PROJECT_OWNER are correct."
      ;;
  esac

  return 1
}

Integration

This skill is called by:

• issue-driven-development - All status transitions
• issue-prerequisite - After issue creation
• epic-management - Epic and child issue setup
• autonomous-orchestration - State queries and updates
• session-start - Sync verification
• work-intake - Project readiness check

This skill requires cache from:

• github-api-cache - Provides GH_CACHE_ITEMS, GH_CACHE_FIELDS, and field IDs

Checklist for Callers

Before proceeding past any gate:

• GitHub API cache initialized (GH_CACHE_ITEMS, GH_CACHE_FIELDS set)
• Issue exists in project (verified from cache, not API call)
• Status field is set
• Type field is set
• Priority field is set (for new issues)
• Epic linkage set (if child of epic)
• Transition is valid (if changing status)

API Cost Summary

Operation	Before Caching	After Caching
verify_issue_in_project	1 call	0 calls
verify_status_set	1 call	0 calls
add_issue_to_project	2 calls	2 calls
set_project_status	4 calls	1 call
set_project_type	3 calls	1 call
get_issues_by_status	1 call	0 calls
count_by_status	1 call	0 calls
verify_project_sync (10 branches)	10 calls	0 calls