# Amia Github Projects Sync

> 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. Loaded by ai-maestro-integrator-agent-main-agent.

- Skill: `emasoft-ai-maestro-integrator-agent/amia-github-projects-sync` (Agent Skill, multi-file: 43 files)
- Install (CLI): `npx skillmds@latest add emasoft-ai-maestro-integrator-agent/amia-github-projects-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/emasoft-ai-maestro-integrator-agent/amia-github-projects-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: Emasoft (https://skillmd.com/u/emasoft-ai-maestro-integrator-agent)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/emasoft-ai-maestro-integrator-agent/amia-github-projects-sync

---


# GitHub Projects Sync

## Overview

Manages team tasks through GitHub Projects V2 via GraphQL API — READ + STATUS UPDATE ONLY.

## Prerequisites

- GitHub CLI (`gh`) authenticated with `project` scope
- GitHub Projects V2 enabled repository
- Python 3.8+ for automation scripts

## Instructions

1. **Authenticate** — verify with `gh auth status` (needs `project` scope)
2. **Locate project** — find project ID via GraphQL query (see Examples)
3. **Execute** — use `gh api graphql` or run automation scripts
4. **Verify** — check project board or query API to confirm changes
5. **Notify** — send AI Maestro messages to relevant agents if needed

### Checklist

Copy this checklist and track your progress:

- [ ] Verify GitHub CLI auth with `project` scope
- [ ] Locate project using GraphQL queries
- [ ] Execute via GraphQL API or automation scripts
- [ ] Verify result on project board or via API
- [ ] Notify stakeholders via AI Maestro if needed
- [ ] Document change in issue comments or task lists

## Output

| Output Type | Format | Description |
|-------------|--------|-------------|
| Project item IDs | JSON | GraphQL node IDs for created/updated items |
| Status updates | JSON | Confirmation of field value changes |
| Issue metadata | JSON | Issue numbers, titles, states, assignees |
| Project reports | Markdown | Status summaries, progress updates |
| Sync logs | Text/JSON | Automation script execution results |
| Error details | JSON/Text | API errors, validation failures, rate limits |

> **Output discipline:** All scripts support `--output-file <path>`. Use it in automated workflows to minimize token consumption.

## Reference Documents

See `references/` directory for all reference documents.

## Error Handling

Script failures return non-zero exit codes. See [error-handling](references/error-handling.md) for details:
  - When encountering GitHub API errors
  - When hitting rate limits
  - When project or item is not found
  - When item updates fail
  - When authentication fails
  - When webhook delivery fails
  - When implementing retry logic

## Examples

### Example 1: Find Your Project

```bash
gh api graphql -f query='
  query {
    repository(owner: "OWNER", name: "REPO") {
      projectsV2(first: 10) {
        nodes { id title number }
      }
    }
  }
'
```

## Resources

Full reference: [detailed-guide](references/detailed-guide.md):
  - Critical Distinction
  - When to Invoke
  - Iron Rules Compliance
  - Issue Lifecycle Policy
  - AI Maestro Integration
  - Threshold Configuration
  - Error Handling Details
  - Status Columns
  - Reference File Contents Index