Use when managing team tasks through GitHub Projects V2 or synchronizing project state via GraphQL API. Trigger with /sync-projects or when updating project items.
npx claudepluginhub emasoft/emasoft-plugins --plugin emasoft-integrator-agentThis skill uses the workspace's default tool permissions.
The GitHub Projects Sync skill enables the INTEGRATOR-AGENT to manage team tasks through GitHub Projects V2. This is the OFFICIAL task management interface for coordinating work across remote developer agents.
README.mdreferences/automation-scripts.mdreferences/best-practices.mdreferences/ci-notification-setup.mdreferences/core-operations.mdreferences/error-handling.mdreferences/examples-and-inline-troubleshooting.mdreferences/github-sync-procedure.mdreferences/graphql-queries-index.mdreferences/graphql-queries-part1-read-operations.mdreferences/graphql-queries-part2-mutations-section1-item-mutations.mdreferences/graphql-queries-part2-mutations-section2-issue-operations.mdreferences/graphql-queries-part2-mutations-section3-pr-utilities.mdreferences/graphql-queries-part2-mutations.mdreferences/graphql-queries.mdreferences/issue-templates-advanced.mdreferences/issue-templates-core.mdreferences/issue-templates-part1-feature-request.mdreferences/issue-templates-part2-bug-report.mdreferences/issue-templates-part3-epic.mdManages GitHub issues, PRs, milestones, and Projects v2 using gh CLI commands, REST API calls, and GraphQL queries. Useful for automation, bulk operations, and project tracking.
Executes GitHub operations (PRs, issues, milestones, labels, comments, merges) using Python scripts with structured output and error handling. Use for pull requests, issues, review comments, CI checks, milestones instead of raw gh.
Executes GitHub operations on PRs, issues, milestones, labels, comments, and merges using Python scripts with structured output and error handling. Use for pull requests, issues, review comments, CI checks, or milestones instead of raw gh.
Share bugs, ideas, or general feedback.
The GitHub Projects Sync skill enables the INTEGRATOR-AGENT to manage team tasks through GitHub Projects V2. This is the OFFICIAL task management interface for coordinating work across remote developer agents.
Critical Distinction:
gh) installed and authenticated with project scopeFollow these steps when using this skill:
gh auth status and has project scopegh api graphql or run automation scriptsCopy this checklist and track your progress:
project scopeWhen to invoke this skill:
| Output Type | Format | Location | Description |
|---|---|---|---|
| Project item IDs | JSON | API response | GraphQL node IDs for created/updated items |
| Status updates | JSON | API response | Confirmation of field value changes |
| Issue metadata | JSON | API response | Issue numbers, titles, states, assignees |
| Project reports | Markdown | AI Maestro messages | Status summaries, progress updates |
| Sync logs | Text/JSON | Script stdout | Automation script execution results |
| Error details | JSON/Text | stderr | API errors, validation failures, rate limits |
| Notification receipts | JSON | AI Maestro API | Confirmation of sent messages to agents |
This skill is READ + STATUS UPDATE ONLY:
# Verify gh CLI is authenticated
gh auth status
gh api graphql -f query='
query {
repository(owner: "OWNER", name: "REPO") {
projectsV2(first: 10) {
nodes { id title number }
}
}
}
'
All detailed operations, templates, and scripts are organized in reference files below. Each section shows WHEN to read that reference and its contents.
Read this when performing day-to-day GitHub Projects operations.
Contents:
Read this when you need complete GraphQL query/mutation syntax.
Index File Contents:
Sub-Files:
Read this when managing issue/item status transitions.
Contents:
Standard Columns: Backlog -> Todo -> In Progress -> AI Review -> Human Review -> Merge/Release -> Done (+ Blocked)
Read this when classifying or filtering issues by labels.
Contents:
Label Categories: type:, priority:, status:, component:, effort:, agent:, review:*
Read this when creating issues or setting up repository templates.
Contents:
Read this when breaking down large features into smaller tasks.
Contents:
Read this when coordinating GitHub Projects with other EOA skills.
Contents:
Read this when configuring webhooks for CI/project sync.
Contents:
Read this when encountering API errors or failures.
Contents:
Read this before starting work and when unsure about procedures.
Contents:
Read this when using the included Python automation scripts.
Contents:
Read this when synchronizing GitHub Projects state with external systems.
Contents:
Read this when mapping planning phases to GitHub status.
Contents:
See also: references/iteration-cycle-rules.md for sprint/iteration management.
IRON RULE: Issues are NEVER automatically closed due to inactivity.
| Issue Type | Closure Conditions |
|---|---|
| Feature | Implemented + merged, OR explicitly declined with reason |
| Bug | Fixed + verified, OR 3 documented reproduction attempts failed |
| Chore | Completed and verified |
For inactive issues, use labels (needs-attention, awaiting-response, low-priority) instead of closing.
See references/status-management.md for complete policy.
For all inter-agent messaging, refer to the official AI Maestro skill:
~/.claude/skills/agent-messaging/SKILL.md
Use the agent-messaging skill to send notifications. For example, to notify the orchestrator, send a message using the agent-messaging skill with:
orchestrator-master{"type": "TYPE", "message": "MSG"}agent-messaging skill's sent messages feature.The ../shared/thresholds.py module defines automation thresholds:
| Threshold | Value | Purpose |
|---|---|---|
| MAX_CONSECUTIVE_FAILURES | 3 | CI failures before escalation |
| INACTIVE_HOURS | 24 | Hours before flagging inactive items |
| LONG_REVIEW_HOURS | 48 | Hours before review escalation |
| BLOCKED_ESCALATION_HOURS | 72 | Hours before user escalation |
See references/automation-scripts.md for usage.
github-projects-sync/
├── SKILL.md # This file (map/TOC)
├── scripts/
│ ├── sync_tasks.py # Bulk issue creation
│ ├── ci_webhook_handler.py # Webhook receiver
│ └── eia_kanban_sync.py # CI status sync
├── references/
│ ├── core-operations.md # Day-to-day operations
│ ├── graphql-queries-index.md # GraphQL library index
│ ├── graphql-queries-part1-*.md # Read operations
│ ├── graphql-queries-part2-*.md # Mutations
│ ├── status-management.md # Status transitions & lifecycle
│ ├── label-taxonomy.md # Label system
│ ├── issue-templates.md # Issue/PR templates
│ ├── sub-issue-tracking.md # Epic/sub-issue management
│ ├── skill-integrations.md # EOA skill integration
│ ├── ci-notification-setup.md # Webhook configuration
│ ├── error-handling.md # Error handling patterns
│ ├── best-practices.md # Best practices guide
│ ├── automation-scripts.md # Script documentation
│ ├── planning-phase-mapping.md # Planning phase mapping
│ ├── iteration-cycle-rules.md # Sprint/iteration rules
│ ├── review-worktree-workflow.md # Review environment
│ └── plan-file-linking.md # Plan file linking
└── ../shared/
├── thresholds.py # Automation thresholds
└── aimaestro_notify.py # AI Maestro CLI wrapper
For worked examples (finding/querying projects, updating issue status) and inline troubleshooting (project not found, issues not appearing, sync failures, rate limiting), see references/examples-and-inline-troubleshooting.md:
For comprehensive error handling patterns, see also references/error-handling.md.
When GitHub API calls or sync operations fail, consult references/error-handling.md for retry logic, rate-limit handling, and authentication troubleshooting. All errors should be logged and, if unresolvable after retries, escalated via AI Maestro.
For worked examples of finding projects, querying items, and updating issue status, see references/examples-and-inline-troubleshooting.md. That reference also covers inline troubleshooting for common failures such as missing projects, sync conflicts, and rate limiting.