From emasoft-orchestrator-agent
GitHub Projects V2 kanban board management. Use when creating boards, adding columns, moving items. Trigger with kanban or column requests.
npx claudepluginhub emasoft/emasoft-plugins --plugin emasoft-orchestrator-agentThis skill uses the workspace's default tool permissions.
This skill teaches the Orchestrator (EOA) how to manage GitHub Projects V2 kanban boards. It covers creating project boards, adding and modifying columns, moving items between columns, and synchronizing task status. This skill also documents critical pitfalls discovered during production use that can cause data loss if not followed.
Manages GitHub Projects V2 kanban boards: creates boards, adds columns, moves items via gh CLI, GraphQL mutations, and Python scripts. Use for kanban or column requests.
Manages GitHub Projects v2 via gh CLI: create/edit/list projects, add issues/PRs as items, manage fields, link repos, automate workflows.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Share bugs, ideas, or general feedback.
This skill teaches the Orchestrator (EOA) how to manage GitHub Projects V2 kanban boards. It covers creating project boards, adding and modifying columns, moving items between columns, and synchronizing task status. This skill also documents critical pitfalls discovered during production use that can cause data loss if not followed.
gh) installed and authenticatedproject and read:project scopes MUST be added to gh auth. See references/gh-auth-scopes.md for detailsBefore ANY kanban operation, verify OAuth scopes:
gh auth status 2>&1 | grep -q "project" || echo "ERROR: Missing project scope. Run: gh auth refresh -h github.com -s project,read:project"
If scopes are missing, the agent CANNOT proceed. See references/gh-auth-scopes.md for how to add scopes.
When to use: When setting up a new project's kanban board for the first time.
Steps:
gh project creategh-project-add-columns.sh.github/project.jsonWhen to use: When adding new status columns to an existing project board.
CRITICAL WARNING: The updateProjectV2Field GraphQL mutation REPLACES all options. If you do not include existing option IDs in the mutation, ALL existing column assignments will be lost. See references/kanban-pitfalls.md Section 3.2 for details.
Steps:
scripts/gh-project-add-columns.shupdateProjectV2Field without preserving existing option IDsScript usage:
# Add new columns safely (preserves existing columns and their assignments)
./scripts/gh-project-add-columns.sh --project <number> --field "Status" --add "AI Review" --add "Human Review"
When to use: When updating a task's kanban status (e.g., moving from "In Progress" to "AI Review").
Steps:
gh project item-edit with the correct IDsWhen to use: When synchronizing label-based status with the GitHub Project board, or vice versa.
Steps:
eoa_sync_kanban.pyThe EOA plugin includes these kanban management scripts in scripts/:
| Script | Purpose | When to Use |
|---|---|---|
eoa_kanban_manager.py | Create tasks, assign agents, update status, check ready tasks | Day-to-day kanban operations |
eoa_sync_kanban.py | Sync label status with GitHub Project board | After manual board changes or to reconcile state |
check-github-projects.sh | Query project board for pending items | Stop-hook checks, status queries |
gh-project-add-columns.sh | Safely add columns preserving existing assignments | When adding new columns to a live board |
The standard 8-column kanban system:
| Column | Status Label | Description |
|---|---|---|
| Backlog | status:backlog | Tasks identified but not yet scheduled |
| Todo | status:todo | Tasks scheduled for current sprint |
| In Progress | status:in-progress | Tasks actively being worked on |
| AI Review | status:ai-review | Code submitted for automated review |
| Human Review | status:human-review | Code awaiting human review |
| Merge/Release | status:merge-release | Approved and ready to merge |
| Done | status:done | Completed tasks |
| Blocked | status:blocked | Tasks blocked by dependencies |
Follow these steps to manage the kanban board:
gh-project-add-columns.sh (PROCEDURE 2)Copy this checklist and track your progress:
Pre-Flight:
which gh)gh auth status)gh auth status 2>&1 | grep project)gh auth refresh -h github.com -s project,read:projectBoard Setup:
gh project create --owner Emasoft --title "<project>"gh-project-add-columns.sh.github/project.jsonTask Management:
assign:*, priority:*, status:*)gh issue closeAfter executing kanban operations, the agent produces:
.github/project.json for future reference.gh project item-list.| Error | Cause | Solution |
|---|---|---|
missing required scopes [project read:project] | gh auth lacks project scopes | See gh-auth-scopes.md Section 1.4 |
InputObject doesn't accept argument 'projectId' | Wrong parameter name | Use fieldId only. See github-projects-v2-graphql.md Section 2.6 |
| Items lost column assignments after adding columns | Used raw updateProjectV2Field | See kanban-pitfalls.md Section 3.2 |
| Issue auto-closed when moved to Done | GitHub Projects V2 built-in automation | See kanban-pitfalls.md Section 3.1 |
gh auth refresh fails in non-interactive session | Requires browser-based OAuth flow | Must be done by human before agent deployment |
# Check if project scopes are available
if ! gh auth status 2>&1 | grep -q "project"; then
echo "ERROR: Missing project scope."
echo "A human must run: gh auth refresh -h github.com -s project,read:project"
echo "This requires interactive browser approval."
exit 1
fi
echo "OK: Project scopes are available."
# 1. Create the issue
ISSUE_URL=$(gh issue create --repo Emasoft/myproject \
--title "Implement feature X" \
--body "Description..." \
--label "assign:epa-impl-01,priority:high,status:todo")
ISSUE_NUMBER=$(echo "$ISSUE_URL" | grep -oE '[0-9]+$')
# 2. Add to project board
gh project item-add <project-number> --owner Emasoft --url "$ISSUE_URL"
# Get the project item ID and Status field ID
ITEM_ID=$(gh project item-list <project-number> --owner Emasoft --format json | \
jq -r ".items[] | select(.content.number == $ISSUE_NUMBER) | .id")
# Move to AI Review column
gh project item-edit \
--project-id <project-id> \
--id "$ITEM_ID" \
--field-id <status-field-id> \
--single-select-option-id <ai-review-option-id>
# Check if issue is already closed (Done column may auto-close it)
STATE=$(gh issue view $ISSUE_NUMBER --repo Emasoft/myproject --json state -q '.state')
if [ "$STATE" = "CLOSED" ]; then
echo "Issue #$ISSUE_NUMBER is already closed (likely auto-closed by Done column)"
else
gh issue close $ISSUE_NUMBER --repo Emasoft/myproject --comment "Task completed."
fi
Version: 1.0.0 Last Updated: 2026-02-15 Target Audience: Orchestrator Agents Difficulty Level: Intermediate