| name | eia-kanban-orchestration |
| description | Use when managing GitHub Kanban boards. Trigger with board state, card move, or completion requests. |
| license | Apache-2.0 |
| compatibility | Requires GitHub CLI authentication, GitHub Projects V2 enabled repository, GraphQL API access, Python 3.8+. Requires AI Maestro installed. |
| metadata | {"author":"Emasoft","version":"1.0.0"} |
| agent | api-coordinator |
| context | fork |
| workflow-instruction | Steps 13, 18 |
| procedure | proc-populate-kanban, proc-update-kanban-status |
| user-invocable | false |
GitHub Kanban Core
THE IRON RULE
GitHub Projects Kanban IS the orchestration state. There is no other source of truth.
- Every module = 1 GitHub Issue on the board
- Every agent assignment = 1 Issue assignee
- Every status change = 1 board column move
- The orchestrator NEVER tracks work in memory, files, or any other system
If it's not on the board, it doesn't exist. If the board says "In Progress", it IS in progress.
Overview
This skill establishes GitHub Projects V2 as the absolute center of EOA orchestration workflow. All planning, tracking, assignment, and completion verification flows through the Kanban board.
Prerequisites
Before using this skill, ensure:
- GitHub CLI is installed and authenticated (
gh auth status)
- GitHub Projects V2 is enabled for the repository
- GraphQL API access is available
- Python 3.8+ for running board management scripts
Instructions
Follow these steps when using GitHub Kanban as the orchestration source of truth:
- Initialize board access - Verify GitHub CLI authentication and Projects V2 access
- Query current state - Use
eia_kanban_get_board_state.py to see all items and their columns
- Create module issues - For new work, create GitHub Issues following the issue-to-module mapping (see references/issue-to-module-mapping.md)
- Assign work - Set issue assignees to designate responsible agents (see references/agent-assignment-via-board.md)
- Track transitions - Move cards between columns as work progresses (see references/status-transitions.md)
- Handle blockers - Mark items as Blocked with reason when cannot proceed (see references/blocking-workflow.md)
- Verify completion - Before exit, use
eia_kanban_check_completion.py to ensure all items are Done
Checklist
Copy this checklist and track your progress:
When to Use This Skill
Read this skill when:
- Starting any orchestration session
- Planning new work (modules, features, tasks)
- Assigning work to agents or humans
- Checking work status or progress
- Verifying completion before exiting
- Handling blocked work items
- Integrating with stop hooks
Quick Reference: Board Columns
| Column | Code | Meaning | Who Can Move Here |
|---|
| Backlog | backlog | Not scheduled | Orchestrator only |
| Todo | todo | Ready to start | Orchestrator only |
| In Progress | in-progress | Active work | Assigned agent |
| AI Review | ai-review | Integrator reviews ALL tasks | Integrator agent |
| Human Review | human-review | User reviews BIG tasks only | User/human reviewer |
| Merge/Release | merge-release | Ready to merge | Orchestrator |
| Done | done | Completed and merged | Auto (PR merge) |
| Blocked | blocked | Cannot proceed | Any (with reason) |
Reference Documentation
All detailed operations are in reference files. Each section shows WHEN to read and the full TOC.
Read this FIRST to understand the philosophical foundation.
Contents:
- 1.1 Why centralized truth matters for AI orchestration
- 1.2 The problems with distributed state tracking
- 1.3 Why GitHub Projects V2 is the ideal choice
- 1.4 The Iron Rules of Kanban-centric orchestration
- 1.5 What happens when you violate these rules
- 1.6 Comparison: Traditional vs Kanban-centric orchestration
Read this when you need to understand what each column means and its requirements.
Contents:
- 2.1 Overview of the 8-column workflow
- 2.2 Backlog column - items not yet scheduled
- 2.3 Todo column - ready for immediate work
- 2.4 In Progress column - active development
- 2.5 AI Review column - Integrator reviews ALL tasks
- 2.5a Human Review column - User reviews BIG tasks only
- 2.5b Merge/Release column - Ready to merge
- 2.6 Done column - completed and verified
- 2.7 Blocked column - cannot proceed
- 2.8 Column metadata and requirements table
- 2.9 Visual board layout example
Read this when creating issues for modules or understanding the 1:1 mapping.
Contents:
- 3.1 The 1:1 principle: every module is exactly one issue
- 3.2 Module issue template structure
- 3.3 Required fields for module issues
- 3.4 Naming conventions for module issues
- 3.5 Linking module issues to parent epics
- 3.6 Creating module issues from plan files
- 3.7 Bulk module issue creation workflow
- 3.8 Module issue lifecycle from creation to closure
Read this when assigning work to agents or checking assignments.
Contents:
- 4.1 Assignment principle: issue assignee = responsible agent
- 4.2 How to assign issues via CLI
- 4.3 How to assign issues via GraphQL
- 4.4 Agent naming conventions for GitHub
- 4.5 Verifying current assignments
- 4.6 Reassigning work between agents
- 4.7 Multi-agent collaboration on single issue
- 4.8 Assignment notifications via AI Maestro
Read this when moving cards between columns or validating transitions.
Contents:
- 5.1 Valid transition matrix (what moves are allowed)
- 5.2 Transition preconditions and postconditions
- 5.3 Who can move cards (orchestrator vs agent vs auto)
- 5.4 Backlog to Todo transition rules
- 5.5 Todo to In Progress transition rules
- 5.6 In Progress to AI Review transition rules
- 5.6a AI Review to Human Review transition rules (big tasks)
- 5.6b AI Review to Merge/Release transition rules (small tasks)
- 5.6c Human Review to Merge/Release transition rules
- 5.7 Merge/Release to Done transition rules
- 5.8 Any status to Blocked transition rules
- 5.9 Blocked to previous status transition rules
- 5.10 Invalid transitions and how to handle them
Read this when an item becomes blocked or when resolving blockers.
Contents:
- 6.1 What constitutes a blocker
- 6.2 How to mark an item as blocked
- 6.3 Required information when blocking
- 6.4 Blocker escalation timeline
- 6.5 Resolving blockers and resuming work
- 6.6 Cross-issue blocking dependencies
- 6.7 External blockers (outside GitHub)
- 6.8 Blocker status reporting
Read this when you need GraphQL queries to inspect board state.
Contents:
- 7.1 Get full board state (all items, all columns)
- 7.2 Get items by status column
- 7.3 Get items assigned to specific agent
- 7.4 Get blocked items with blocker reasons
- 7.5 Get items in review awaiting merge
- 7.6 Count items per column (summary)
- 7.7 Get item history and transitions
- 7.8 Check if all items are Done
Read this to understand how the stop hook uses board state for completion verification.
Contents:
- 8.1 The stop hook's role in orchestration
- 8.2 Board state queries performed by stop hook
- 8.3 Completion criteria: when can orchestrator exit
- 8.4 Handling incomplete work at exit time
- 8.5 Blocked items and exit policy
- 8.6 Stop hook configuration options
- 8.7 Manual override of stop hook
- 8.8 Stop hook error handling
Read this when coordinating between AI agents and human developers.
Contents:
- 9.1 Key differences in AI vs human workflow
- 9.2 Assignment strategies for AI agents
- 9.3 Assignment strategies for human developers
- 9.4 Communication channels: AI Maestro vs GitHub comments
- 9.5 Review workflow differences
- 9.6 Handoff protocols between AI and human
- 9.7 Mixed team coordination patterns
- 9.8 Escalation paths for AI blockers
Read this when creating assignments, integrations, or communicating with agents.
Contents:
- 10.1 Task Assignment Template
- 10.2 GitHub Issue Template for Subtasks
- 10.3 Integration Assignment Template
- 10.4 Conflict Resolution Assignment Template
- 10.5 Merge Authorization Template
- 10.6 Progress Check-In Template
Read this when handling task failures, integration issues, or unresponsive agents.
Contents:
- 11.1 Subtask Reports Failure After Others In Progress
- 11.2 Integration Reports Failures
- 11.3 Agent Becomes Unresponsive
- 11.4 Conflict Resolution Planning
- 11.5 Failure Communication Patterns
Read this when encountering issues with board synchronization or operations.
Contents:
- 12.1 Issue not appearing on board after creation
- 12.2 Status change not reflecting on board
- 12.3 Assignment not showing correctly
- 12.4 GraphQL API errors and rate limiting
- 12.5 Permission denied errors
- 12.6 Board state out of sync with reality
- 12.7 Stop hook blocking exit incorrectly
- 12.8 Recovery procedures for corrupted state
Command Integration: /create-issue-tasks
The /create-issue-tasks command creates Claude Tasks checklists for handling issues. See the full command documentation at:
${CLAUDE_PLUGIN_ROOT}/commands/create-issue-tasks.md
Quick Usage
/create-issue-tasks <CATEGORY> <REPORTER> <MODULE> "<TITLE>" ["<DESCRIPTION>"]
Categories: BUG, BLOCKER, QUESTION, ENHANCEMENT, CONFIG, INVESTIGATION
Example:
/create-issue-tasks BUG implementer-1 auth-core "Login fails with OAuth" "401 error after token expiry"
Python Scripts
Get complete board state with all items grouped by column.
python3 scripts/eia_kanban_get_board_state.py OWNER REPO PROJECT_NUMBER
Output: JSON with items grouped by status column.
Move a card to a different column with validation.
python3 scripts/eia_kanban_move_card.py OWNER REPO PROJECT_NUMBER ISSUE_NUMBER NEW_STATUS [--reason "Reason"]
Validates: Transition is allowed, preconditions met.
Check if all board items are complete (for stop hook).
python3 scripts/eia_kanban_check_completion.py OWNER REPO PROJECT_NUMBER
Exit codes:
- 0: All items Done
- 1: Items still in progress
- 2: Blocked items exist
Read this when understanding how Kanban connects to planning, orchestration, stop hooks, assignments, and PR completion.
Contents:
- IP.1 Planning Phase workflow
- IP.2 Orchestration Phase workflow
- IP.3 Stop Hook Phase workflow
- IP.4 Assignment Flow
- IP.5 PR Completion Flow
Skill Files
github-kanban-core/
├── SKILL.md # This file (map/TOC)
├── README.md # Skill overview
├── scripts/
│ ├── eia_kanban_get_board_state.py # Get full board state
│ ├── eia_kanban_move_card.py # Move card between columns
│ └── eia_kanban_check_completion.py # Check completion for stop hook
└── references/
├── kanban-as-truth.md # Why Kanban is single source of truth
├── board-column-semantics.md # Column meanings and requirements
├── issue-to-module-mapping.md # Module-to-issue 1:1 mapping
├── agent-assignment-via-board.md # Assignment via issue assignees
├── status-transitions.md # Valid state transitions
├── blocking-workflow.md # Handling blocked items
├── board-queries.md # GraphQL queries for board state
├── stop-hook-integration.md # Stop hook completion checks
├── ai-agent-vs-human-workflow.md # Different workflows for AI vs humans
└── troubleshooting.md # Common issues and solutions
Examples
Example 1: Get Current Board State
python3 scripts/eia_kanban_get_board_state.py owner repo 1
Example 2: Move Card and Check Completion
python3 scripts/eia_kanban_move_card.py owner repo 1 42 in-progress --reason "Starting work"
python3 scripts/eia_kanban_check_completion.py owner repo 1
Output
| Output Type | Format | Description | When Generated |
|---|
| Board State JSON | JSON object | All items grouped by status column | Via eia_kanban_get_board_state.py |
| Transition Result | JSON object | Success/failure of card move with validation | Via eia_kanban_move_card.py |
| Completion Status | Exit code + JSON | 0=all done, 1=pending, 2=blocked | Via eia_kanban_check_completion.py |
| Assignment Notification | AI Maestro message | Agent receives work assignment | When issue assigned |
| GraphQL Query Results | JSON object | Raw board data from GitHub API | Via reference queries |
| Blocker Report | JSON object | All blocked items with reasons | When querying blocked items |
Error Handling
| Error | Cause | Resolution |
|---|
| Issue not appearing on board | Issue not added to Projects V2, wrong project number | Verify project link with gh issue view <N>, re-add to project |
| Status change not reflecting | Invalid transition, missing permissions | Check transition matrix in references/status-transitions.md, verify GitHub permissions |
| Assignment not showing | Issue not on board, invalid assignee username | Ensure issue is on project board, use correct GitHub username |
| GraphQL API rate limit | Too many rapid queries | Wait 60 seconds, use query caching, reduce polling frequency |
| Permission denied | Insufficient GitHub permissions | Verify gh auth status, ensure write access to repository and project |
| Board state out of sync | Stale cache, concurrent modifications | Force refresh with fresh GraphQL query, avoid caching board state |
| Stop hook blocking exit | Items not in Done column | Complete pending items, move to Done, or defer with explicit reason |
| Corrupted board state | Manual edits outside workflow | Use recovery procedure in references/troubleshooting.md section 10.8 |
Resources
Read this when setting up or running proactive board monitoring during orchestration sessions.
Contents:
- M.1 Overview of proactive monitoring
- M.2 Polling configuration and frequency
- M.3 What to check on each poll (detection table)
- M.4 Running the polling script
- M.5 Change detection logic (pseudocode)
- M.6 AI Maestro notifications for detected changes
- M.7 Proactive monitoring checklist
Related Skills
- github-projects-sync - Detailed GitHub Projects V2 operations and templates
- remote-agent-coordinator - Agent communication and task routing
- orchestrator-stop-hook - Stop hook behavior and configuration
